FTW

Section: Manual del Programador de Linux (3)
Updated: 25 junio 1999
Index Return to Main Contents

NOMBRE

ftw, nftw - recorre un árbol de ficheros

SINOPSIS

#include <ftw.h>int ftw (const char *directorio, int (*fn)(constchar *fichero, const struct stat *sb, intflag),intprofun);

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, 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. 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 primera glibc 2.1 suporta FTW_SL y nftw().

CONFORME A

AES, SVID2, SVID3, XPG2, XPG3, XPG4 y XPG4v2.

VÉASE TAMBIÉN

stat

(2)

This document was created by man2html, using the manual pages.
Time: 06:16:24 GMT, January 22, 2005