NOMBRE¶
ftw, nftw - recorre un árbol de ficheros
SINOPSIS¶
#include <ftw.h> int ftw (const char *directorio,
int (*fn)(const char *fichero, const struct
stat *sb, int flag), int
profun);
int nftw (const char *directorio, int
(*fn)(const char *fichero, const struct
stat *sb, int flag, struct FTW
*s), int profun, int
flags);
DESCRIPCIÓN¶
ftw() recorre un árbol de directorios empezando por el
directorio indicado. Para cada entrada encontrada en el árbol,
llama a
fn() con el nombre de camino completo de la entrada, un puntero
a la estructura
stat(2) para la entrada, y un int
flag, cuyo
valor será uno de los siguientes:
- FTW_F
- El ítem es un fichero normal
- FTW_D
- El ítem es un directorio
- FTW_DNR
- El ítem es un directorio que no se puede leer
- FTW_SL
- El ítem es un enlace simbólico
- FTW_NS
- stat ha fallado en el ítem que no es un enlace
simbólico
Si el ítem es un enlace simbólico y `stat' ha fallado, XPG4v2
establece que el estado queda indefinido si se usa FTW_NS o FTW_SL.
ftw() se llama a sí misma recursivamente para atravesar los
directorios que encuentra, tratando un directorio antes que sus ficheros o
subdirectorios. Para evitar el uso de todos los descriptores de fichero de un
programa, el argumento
profun especifica el número de
directorios abiertos simultáneamente. Cuando la profundidad es
sobrepasada,
ftw() se ralentizará porque los directorios
deberán cerrarse y volverse a abrir.
ftw() usa, como mucho, un
descriptor de fichero para cada nivel de la jerarquía de ficheros.
Para detener el recorrido por el árbol,
fn() devuelve un valor
no-cero. Este valor se convertirá en el devuelto por
ftw(). De
otro modo,
ftw() continuará hasta que haya recorrido el
árbol entero, en cuyo caso devolverá cero, o hasta que ocurra un
error distinto de EACCES (como un fallo de
malloc(3)), en cuyo caso
devolverá -1.
Puesto que
ftw() usa estructuras de datos dinámicas, la
única forma segura de salir de un recorrido por un árbol es
devolver un valor no cero. Para manejar interrupciones, por ejemplo, marque
que ha ocurrido una interrupción y devuelva un valor no-cero (no emplee
longjmp(3) a menos que el programa vaya a terminar).
La función
nftw() hace precisamente lo mismo que
ftw(),
excepto que tiene un argumento
flags adicional (y llama a la
función proporcionada con un argumento más). Este argumento
flags es un
O-lógico de cero o más de las
siguientes opciones:
- FTW_CHDIR
- Llama a chdir() para moverse a un directorio antes de manejar su
contenido.
- FTW_DEPTH
- Realiza una búsqueda primero en profundidad, es decir, llama a la
función para el propio directorio sólo después de
tratar el contenido del directorio y de sus subdirectorios.
- FTW_MOUNT
- Permanece dentro del mismo sistema de ficheros.
- FTW_PHYS
- No sigas enlaces simbólicos (esto es lo que desea). Cuando no
está activa, se siguen los enlaces simbólicos, pero
ningún fichero aparece dos veces.
Si la opción FTW_PHYS no está activa, pero FTW_DEPTH sí,
entonces nunca se llama a la función
fn() para un directorio que
sería descendiente de sí mismo.
La función
fn() se llama con cuatro argumentos: la ruta de la
entrada encontrada, un puntero a una estructura `stat' para esa entrada, un
entero que describe su tipo y un puntero a una estructura FTW. El tipo
será uno de los siguientes: FTW_F, FTW_D, FTW_DNR, FTW_SL, FTW_NS (con
el significado de antes. FTW_SL se da sólo con FTW_PHYS activa) o
- FTW_DP
- El ítem es un directorio y todos sus descendientes ya han sido
tratados. (Esto sólo ocurre cuando FTW_DEPTH está
activa).
- FTW_SLN
- El ítem es un enlace simbólico que apunta a un fichero
inexistente. (Esto ocurre sólo cuando FTW_PHYS no está
activa.)
La estructura FTW apuntada por el cuarto argumento de
fn() tiene al menos
los campos
base, el desplazamiento del nombre de fichero del
ítem en la ruta dada como primer argumento de
fn(), y
level, la profundidad del ítem relativo al punto de comienzo
(que tiene profundidad 0).
NOTA¶
La función
nftw() y el uso de FTW_SL con
ftw() se
introdujeron en XPG4v2.
En algunos sistemas
ftw() no usará nunca FTW_SL, en otros sistemas
FTW_SL se usa sólo para enlaces simbólicos que no apuntan a un
fichero existente, y de nuevo en otros sistemas,
ftw() usará
FTW_SL para cada enlace simbólico. Si quiere un uso determinista, use
nftw().
Bajo Linux, libc4, libc5 y glibc 2.0.6 usarán FTW_F para todos los
objetos (ficheros, enlaces simbólicos, FIFOs, etc) sobre los que se
pueda aplicar la función
stat(2), y que no sean un directorio.
La función
nftw() está disponible desde glibc 2.1.
AES, SVID2, SVID3, XPG2, XPG3, XPG4 y XPG4v2.
VÉASE TAMBIÉN¶
stat(2)