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)