NOMBRE¶
fts
,
fts_open
,
fts_read
,
fts_children
,
fts_set
,
fts_close
—
recorren una jerarquía de ficheros
SINOPSIS¶
#include
<sys/types.h>
#include
<sys/stat.h>
#include
<fts.h>
FTS *
fts_open
(
char *
const *path_argv,
int options,
int (*compar)(const FTSENT **, const FTSENT
**))
FTSENT *
fts_read
(
FTS
*ftsp)
FTSENT *
fts_children
(
FTS
*ftsp,
int options)
int
fts_set
(
FTS
*ftsp,
FTSENT *f,
int options)
int
fts_close
(
FTS
*ftsp)
DESCRIPCIÓN¶
Las funciones
fts
se suministran para
recorrer jerarquías de ficheros UNIX. De manera general, la
función
fts_open
() devuelve un
``manejador'' sobre una jerarquía de ficheros, que luego es pasado a
las otras funciones
fts.
La función
fts_read
() devuelve un puntero a una
estructura que describe uno de los ficheros en la jerarquía de
ficheros. La función
fts_children
()
devuelve un puntero a una lista enlazada de estructuras, cada una de las
cuales describe uno de los ficheros contenidos en un directorio de la
jerarquía. En general, los directorios se visitan en dos instantes
distintos: en pre-orden (antes de que se visite cualquiera de sus
descendientes) y en post-orden (despúes de que se hayan visitado todos
sus descencientes). Los ficheros se visitan una sola vez. Es posible recorrer
la jerarquía ``lógicamente'' (ignorando los enlaces
simbólicos) o físicamente (visitando los enlaces
simbólicos), ordenar el recorrido de la jerarquía o recortar y/o
revisitar porciones de la jerarquía.
Se definen dos estructuras en el fichero de cabecera
⟨
fts.h⟩. La primera es
FTS, la estructura que representa la
jerarquía de ficheros en sí misma. La segunda es
FTSENT, la estructura que representa un
fichero en la jerarquía de ficheros. Normalmente, se devuelve una
estructura
FTSENT por cada fichero en la
jerarquía de ficheros. En esta página de manual, ``fichero'' y
estructura “
FTSENT” son
generalmente intercambiables. La estructura
FTSENT contiene al menos los siguientes
campos, que se describen con mayor detalle más abajo:
typedef struct _ftsent {
u_short fts_info; /* banderas para la estructura FTSENT */
char *fts_accpath; /* camino de acceso */
char *fts_path; /* camino raíz */
short fts_pathlen; /* strlen(fts_path) */
char *fts_name; /* nombre de fichero */
short fts_namelen; /* strlen(fts_name) */
short fts_level; /* profundidad (-1 a N) */
int fts_errno; /* código de error */
long fts_number; /* valor numérico local */
void *fts_pointer; /* valor de dirección local */
struct ftsent *fts_parent; /* directorio padre */
struct ftsent *fts_link; /* siguiente estructura de fichero */
struct ftsent *fts_cycle; /* estructura cíclica */
struct stat *fts_statp; /* información stat(2) */
} FTSENT;
Estos campos se definen de la siguiente manera:
- fts_info
- Uno de las siguientes banderas que describen la estructura
FTSENT devuelta y el fichero que
representa. Con la excepción de directorios sin errores
(
FTS_D
), todas estas entradas son
terminales, es decir, no volverán a ser visitadas, ni tampoco
ninguno de sus descendientes.
FTS_D
- Un directorio que está siendo visitado en pre-orden.
FTS_DC
- Un directorio que provoca un ciclo en el árbol. (El campo
fts_cycle de la estructura
FTSENT será rellenado
también.)
FTS_DEFAULT
- Cualquier estructura FTSENT que
represente un tipo de fichero no descrito explícitamente por
uno de los otros valores de
fts_info.
FTS_DNR
- Un directorio que no puede ser leído. Este valor indica un
error y el campo fts_errno
será modificado para reflejar la causa del error.
FTS_DOT
- Un fichero llamado ‘
.
’ o
‘..
’ que no fue especificado
como un nombre de fichero a
fts_open
() (vea
FTS_SEEDOT
).
FTS_DP
- Un directorio que está siendo visitado en post-orden. El
contenido de la estructura FTSENT
será el mismo que el que se devolvió cuando el
directorio se visitó en pre-orden, es decir, con el valor
FTS_D
en el campo
fts_info.
FTS_ERR
- Este valor indica un error y el campo
fts_errno será modificado para
reflejar la causa del error.
FTS_F
- Un fichero regular.
FTS_NS
- Un fichero para el que no hay información de tipo
stat(2) disponible. El contenido del
campo fts_statp es indefinido. Este
valor indica un error y el campo
fts_errno será modificado para
reflejar la causa del error.
FTS_NSOK
- Un fichero para el que no se solicitó información de
tipo stat(2). El contenido del campo
fts_statp es indefinido.
FTS_SL
- Un enlace simbólico.
FTS_SLNONE
- Un enlace simbólico con un destino inexistente. El contenido
del campo fts_statp hace referencia a
la información característica del fichero para el enlace
simbólico en sí mismo.
- fts_accpath
- Un camino para acceder al fichero desde el directorio actual.
- fts_path
- El camino del fichero relativo a la raíz del recorrido. Este
caminio contiene el camino especificado a
fts_open
() como prefijo.
- fts_pathlen
- La longitud de la cadena referenciada por
fts_path.
- fts_name
- El nombre del fichero.
- fts_namelen
- La longitud de la cadena referenciada por
fts_name.
- fts_level
- La profundidad del recorrido, numerada desde -1 hasta N, donde fue
encontrado este fichero. La estructura
FTSENT que representa al padre del punto
de partida (o raíz) del recorrido se numera con -1 y la estructura
FTSENT para la raíz en sí
misma se numera con 0.
- fts_errno
- Cuando las funciones
fts_children
() o
fts_read
() devuelven una estructura
FTSENT cuyo campo
fts_info vale
FTS_DNR
,
FTS_ERR
o
FTS_NS
, el campo
fts_errno contiene el valor de la
variable externa errno especificando la
causa del error. En caso contrario, el contenido del campo
fts_errno es indefinido.
- fts_number
- Este campo se proporciona para su uso por la aplicación y no es
modificado por las funciones
fts.
Se
inicializa a 0.
- fts_pointer
- Este campo se proporciona para su uso por la aplicación y no es
modificado por las funciones
fts.
Se
inicializa a NULL
.
- fts_parent
- Un puntero a la estructura FTSENT que
referencia al fichero en la jerarquía inmediatamente encima del
fichero actual, esto es, el directorio del cual es miembro este fichero.
También se proporciona una estructura padre para el punto de
entrada inicial, aunque sólo se garantiza que se
inicializarán los campos
fts_level,
fts_number y
fts_pointer.
- fts_link
- A la vuelta de la función
fts_children
(), el campo
fts_link apunta a la siguiente estructura
en la lista enlazada terminada en NULL de miembros de directorio. En otro
caso, el contenido del campo fts_link es
indefinido.
- fts_cycle
- Si un directorio causa un ciclo en la jerarquía (vea
FTS_DC
), bien debido a un enlace
físico entre dos directorios, bien por un enlace simbólico
que apunta a un directorio, el campo
fts_cycle de la estructura
apuntará a la estructura FTSENT en
la jerarquía que referencie el mismo fichero que la estructura
FTSENT actual. En otro caso, el contenido
del campo fts_cycle es indefinido.
- fts_statp
- Un puntero a información de tipo
stat(2) para el fichero.
Se utiliza un único buffer para todas las rutas de todos los ficheros en
la jerarquía de ficheros. Por consiguiente, se garantiza que los campos
fts_path y
fts_accpath terminan en
NULL
sólo para el fichero más
recientemente devuelto por
fts_read
(). Para
usar estos campos para referenciar a cualesquier fichero representado por otra
estructura
FTSENT, será necesario que
se modifique el buffer de rutas usando la información contenida en el
campo
fts_pathlen de esa estructura
FTSENT. Cualquiera modificación se
deberá deshacer antes de intentar llamar otra vez a
fts_read
(). El campo
fts_name siempre termina en
NULL
.
FTS_OPEN¶
La función
fts_open
() acepta un
puntero a un array de punteros a carácter designando una o más
rutas o caminos que forman una jerarquía de ficheros lógica a
ser recorrida. El array debe terminarse con un puntero
NULL.
Hay varias opciones, al menos una de las cuales (bien
FTS_LOGICAL
o
FTS_PHYSICAL
) debe ser especificada. Las
opciones se seleccionan concatenando con la operación
or los siguientes valores:
FTS_COMFOLLOW
- Esta opción hace que cualquier enlace simbólico especificado
como un camino raíz sea seguido inmediatamente sin importar que la
opción
FTS_LOGICAL
fuese
especificada.
FTS_LOGICAL
- Esta opción hace que las rutinas
fts
devuelvan estructuras
FTSENT para los destinos de los enlaces
simbólicos en lugar de para los enlaces simbólicos en
sí mismos. Si esta opción está presente, los
únicos enlaces simbólicos para los que se devuelven
estructuras FTSENT a la aplicación
son aquellos que hacen referencia a ficheros no existentes. A la
función fts_open
() se le
debe especificar bien
FTS_LOGICAL
, bien
FTS_PHYSICAL
.
FTS_NOCHDIR
- Para mejorar el rendimiento, las funciones
fts
cambian de directorio según
recorren la jerarquía de ficheros. Esto tiene el efecto secundario
de que una aplicación no puede confiar en estar en ningún
directorio en particular durante el recorrido. La opción
FTS_NOCHDIR
desactiva esta
optimización y las funciones fts
no cambiarán el directorio actual. Observe que las aplicaciones no
deberían por sí mismas cambiar su directorio actual e
intentar acceder a los ficheros a menos que se especifique la
opción FTS_NOCHDIR
y se pasen
caminos de fichero absolutos como argumentos a
fts_open
().
FTS_NOSTAT
- Por defecto, las estructuras FTSENT
devueltas hacen referencia a información característica del
fichero (el campo statp) para cada
fichero visitado. Esta opción relaja ese requisito para mejorar del
rendimiento, permitiendo a las funciones
fts
establecer el campo
fts_info al valor
FTS_NSOK
y dejar el contenido del campo
statp indefinido.
FTS_PHYSICAL
- Esta opción hace que las rutinas
fts
devuelvan estructuras
FTSENT para los enlaces simbólicos
en sí mismos en lugar de para los ficheros destino a los que
apuntan. Si esta opción está presente, se devuelven a la
aplicación estructuras FTSENT para
todos los enlaces simbólicos en la jerarquía. A la
función fts_open
() se le
debe especificar bien
FTS_LOGICAL
, bien
FTS_PHYSICAL
.
FTS_SEEDOT
- Por defecto, a menos que se especifiquen como argumentos de camino a
fts_open
(), cualquier fichero con
nombre ‘.
’ o
‘..
’ encontrado en la
jerarquía de ficheros es ignorado. Esta opción hace que las
rutinas fts
devuelvan estructuras
FTSENT para ellos.
FTS_XDEV
- Esta opción evita que las rutinas
fts
desciendan a directorios que tienen
un número de dispositivo diferente del fichero en el cual comienza
el descenso.
El argumento
compar
() especifica una
función definida por el usuario que puede ser usada para ordenar el
recorrido de la jerarquía. Acepta dos punteros a punteros a estructuras
FTSENT como argumentos y debería
devolver un valor negativo, cero o un valor positivo para indicar que el
fichero referenciado por su primer argumento va antes, en cualquier orden con
respecto a, o después del fichero referenciado por su segundo
argumento. Los campos
fts_accpath,
fts_path y
fts_pathlen de las estructuras
FTSENT nunca
deben utilizarse en esta comparación. Si el campo
fts_info tiene un valor
FTS_NS
o
FTS_NSOK
, el campo
fts_statp tampoco debe usarse. Si el
argumento
compar
() vale
NULL
, el orden de recorrido de los
directorios es en el orden listado en
path_argv para los caminos raíz, y en
el orden de aparición en el directorio para cualquier otro.
FTS_READ¶
La función
fts_read
() devuelve un
puntero a una estructura
FTSENT describiendo
un fichero de la jerarquía. Los directorios (que pueden leerse y no
causan ciclos) son visitados al menos dos veces, una vez en pre-orden y otra
en post-orden. Todos los demás ficheros son visitados al menos una vez.
(Los enlaces físicos entre directorios que no causan ciclos o los
enlaces simbólicos a enlaces simbólicos pueden hacer que haya
ficheros que se visiten más de una vez o directorios que se visiten
más de dos.)
Si todos los miembros de la jerarquía han sido devueltos,
fts_read
() devuelve
NULL
y asigna a la variable externa
errno el valor 0. Si ocurre un error no
relacionado con un fichero en la jerarquía,
fts_read
() devuelve
NULL
y modifica
errno de manera apropiada. Si ocurre un error
relacionado con un fichero devuelto, se devuelve un puntero a una estructura
FTSENT y
errno puede o no tomar algún valor
(vea
fts_info).
Las estructuras
FTSENT devueltas por
fts_read
() pueden ser sobrescritas
después de una llamada a
fts_close
()
sobre el mismo flujo de jerarquía de ficheros o después de una
llamada a
fts_read
() sobre el mismo flujo
de jerarquía de ficheros, a menos que representen un fichero de tipo
directorio en cuyo caso no serán sobrescritas hasta después de
una llamada a
fts_read
(), después de
que la estructura
FTSENT haya sido devuelta
por la función
fts_read
() en
post-orden.
FTS_CHILDREN¶
La función
fts_children
() devuelve un
puntero a una estructura
FTSENT describiendo
la primera entrada de una lista enlazada terminada en NULL de los ficheros en
el directorio representado por la estructura
FTSENT más recientemente devuelta por
fts_read
(). La lista se enlaza mediante el
campo
fts_link de la estructura
FTSENT y es ordenada por la función de
comparación definida por el usuario, si se especifica. Llamadas
repetidas a
fts_children
() volverán
a crear esta lista enlazada.
Como caso especial, si
fts_read
() no ha sido
llamada aún para una jerarquía,
fts_children
() devolverá un puntero
a los ficheros en el directorio lógico especificado a
fts_open
(), es decir, los argumentos
especificados a
fts_open
(). En otro caso,
si la estructura
FTSENT más
recientemente devuelta por
fts_read
() no es
un directorio que se está visitado en pre-orden, o el directorio no
contiene ningún fichero,
fts_children
() devuelve
NULL
y modifica
errno con valor cero. Si ocurre un error,
fts_children
() devuelve
NULL
y modifica
errno con el valor apropiado.
Las estructuras
FTSENT devueltas por
fts_children
() pueden ser sobrescritas tras
una llamada a
fts_children
(),
fts_close
() o
fts_read
() sobre el mismo flujo de
jerarquía de ficheros.
Option puede valer lo siguiente:
FTS_NAMEONLY
- Sólo se necesitan los nombres de los ficheros. El contenido de
todos los campos en la lista enlazada devuelta de estructuras es
indefinido con la excepción de los campos
fts_name y
fts_namelen.
FTS_SET¶
La función
fts_set
() permite a la
aplicación de usuario establecer un procesamiento adicional para el
fichero
f del flujo
ftsp. La función
fts_set
() devuelve 0 en caso de
éxito y -1 si ocurre un error.
Option
puede valer uno de los siguientes valores:
FTS_AGAIN
- Revisitar el fichero; cualquier tipo de fichero puede ser revisitado. La
siguiente llamada a
fts_read
()
devolverá el fichero referenciado. Los campos
fts_stat y
fts_info de la estructura serán
reincializados, pero los demás campos no sufrirán cambios.
Esta opción sólo tiene significado para el fichero
más recientemente devuelto por
fts_read
(). El uso normal de esto es
para las visitas de directorios en post-orden, donde provoca que se
revisiten los directorios (tanto en pre-orden como en post-orden)
así como todos sus descendientes.
FTS_FOLLOW
- El fichero referenciado debe ser un enlace simbólico. Si el fichero
referenciado es aquel más recientemente devuelto por
fts_read
(), la siguiente llamada a
fts_read
() devuelve el fichero con los
campos fts_info y
fts_statp reinicializados para reflejar
el destino del enlace simbólico en lugar del enlace
simbólico en sí mismo. Si el fichero es uno de aquellos
más recientemente devueltos por
fts_children
(), los campos
fts_info y
fts_statp de la estructura, cuando son
devueltos por fts_read
(),
reflejarán el destino del enlace simbólico en lugar del
enlace simbólico en sí mismo. En ambos casos, si el destino
del enlace simbólico no existe, los campos de la estructura
devuelta permanecerán sin cambios y el campo
fts_info valdrá
FTS_SLNONE
.
Si el fichero al que apunta el enlace simbólico es un directorio, se
devuelve el resultado de la visita en pre-orden, seguido de los resultados
de todos sus descendientes, seguidos del resultado de la visita en
post-orden.
FTS_SKIP
- No se visita a los descendientes de este fichero. El fichero debe ser uno
de aquellos más recientemente devueltos por
fts_children
() o
fts_read
().
FTS_CLOSE¶
La función
fts_close
() cierra un flujo
de jerarquía de ficheros
ftsp y
restablece el directorio actual al directorio desde el cual fue llamada
fts_open
() para abrir
ftsp. La función
fts_close
() devuelve 0 en caso de
éxito y -1 si ocurre un error.
ERRORES¶
La función
fts_open
() puede fallar y
modificar
errno para cualquiera de los
errores especificados para las funciones de biblioteca
open(2) y
malloc(3).
La función
fts_close
() puede fallar y
modificar
errno para cualquiera de los
errores especificados para las funciones de biblioteca
chdir(2) y
close(2).
Las funciones
fts_read
() y
fts_children
() pueden fallar y modificar
errno para cualquiera de los errores
especificados para las funciones de biblioteca
chdir(2),
malloc(3),
opendir(3),
readdir(3) y
stat(2).
Además,
fts_children
(),
fts_open
() y
fts_set
() pueden fallar y modificar
errno como sigue:
- [
EINVAL
]
- Las opciones son inválidas.
VÉASE TAMBIÉN¶
find(1),
chdir(2),
stat(2),
qsort(3)
BSD 4.4. Se espera que la utilidad
fts
sea
incluida en una futura revisión
IEEE Std
1003.1-1988 (“POSIX.1”)
DISPONIBILIDAD¶
Estas funciones están disponibles en Linux desde glibc2.