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.

CONFORME A

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

VÉASE TAMBIÉN

       stat(2)

Linux                                             25 junio 1999                                           FTW(3)