Ubuntu Manpage: fts, fts_open, fts_read, fts_children, fts_set, fts_close

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.

Debian                                           16 abril, 1994                                           FTS(3)