Provided by: manpages-es_1.55-10_all bug

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)

CONFORME A

     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.