Provided by: manpages-es_1.55-8_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 slo 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.