Provided by: manpages-es-dev_4.13-4_all 
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 instr);
int fts_set(FTS *ftsp, FTSENT *f, int instr);
int fts_close(FTS *ftsp);
DESCRIPCIÓN
The fts functions are provided for traversing file hierarchies. A simple overview is that
the fts_open() function returns a "handle" (of type FTS *) that refers to a file
hierarchy "stream". This handle is then supplied to the other fts functions. The
function fts_read() returns a pointer to a structure describing one of the files in the
file hierarchy. The function fts_children() returns a pointer to a linked list of
structures, each of which describes one of the files contained in a directory in the
hierarchy.
In general, directories are visited two distinguishable times; in preorder (before any of
their descendants are visited) and in postorder (after all of their descendants have been
visited). Files are visited once. It is possible to walk the hierarchy "logically"
(visiting the files that symbolic links point to) or physically (visiting the symbolic
links themselves), order the walk of the hierarchy or prune and/or revisit portions of the
hierarchy.
Two structures (and associated types) are defined in the include file <fts.h>. The first
type is FTS, the structure that represents the file hierarchy itself. The second type is
FTSENT, the structure that represents a file in the file hierarchy. Normally, an FTSENT
structure is returned for every file in the file hierarchy. In this manual page, "file"
and "FTSENT structure" are generally interchangeable.
The FTSENT structure contains fields describing a file. The structure contains at least
the following fields (there are additional fields that should be considered private to the
implementation):
typedef struct _ftsent {
unsigned short fts_info; /* flags for FTSENT structure */
char *fts_accpath; /* access path */
char *fts_path; /* root path */
short fts_pathlen; /* strlen(fts_path) +
strlen(fts_name) */
char *fts_name; /* filename */
short fts_namelen; /* strlen(fts_name) */
short fts_level; /* depth (-1 to N) */
int fts_errno; /* file errno */
long fts_number; /* local numeric value */
void *fts_pointer; /* local address value */
struct _ftsent *fts_parent; /* parent directory */
struct _ftsent *fts_link; /* next file structure */
struct _ftsent *fts_cycle; /* cycle structure */
struct stat *fts_statp; /* stat(2) information */
} FTSENT;
Estos campos se definen de la siguiente manera:
fts_info
Uno de las siguientes valores 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
The sum of the lengths of the strings referenced by fts_path and fts_name.
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
If fts_children() or fts_read() returns an FTSENT structure whose fts_info field
is set to FTS_DNR, FTS_ERR, or FTS_NS, the fts_errno field contains the error
number (i.e., the errno value) specifying the cause of the error. Otherwise, the
contents of the fts_errno field are undefined.
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 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.
The instr argument is either zero or the following value:
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()
The function fts_set() allows the user application to determine further processing for
the file f of the stream ftsp. The fts_set() function returns 0 on success, and -1 if an
error occurs.
The instr argument is either 0 (meaning "do nothing") or one of the following values:
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()
The fts_close() function closes the file hierarchy stream referred to by ftsp and
restores the current directory to the directory from which fts_open() was called to open
ftsp. The fts_close() function returns 0 on success, and -1 if an error occurs.
ERRORES
The function fts_open() may fail and set errno for any of the errors specified for
open(2) and malloc(3).
The function fts_close() may fail and set errno for any of the errors specified for
chdir(2) and close(2).
The functions fts_read() and fts_children() may fail and set errno for any of the errors
specified for chdir(2), malloc(3), opendir(3), readdir(3), and stat(2).
Además, fts_children(), fts_open() y fts_set() pueden fallar y modificar errno como sigue:
EINVAL options or instr was invalid.
VERSIONES
Estas funciones están disponibles en Linux desde glibc2.
ATRIBUTOS
Para obtener una explicación de los términos usados en esta sección, véase attributes(7).
┌───────────────────────────────────┬────────────────────┬───────────────────┐
│Interfaz │ Atributo │ Valor │
├───────────────────────────────────┼────────────────────┼───────────────────┤
│fts_open(), fts_set(), fts_close() │ Seguridad del hilo │ Multi-hilo seguro │
├───────────────────────────────────┼────────────────────┼───────────────────┤
│fts_read(), fts_children() │ Seguridad del hilo │ MT-Unsafe │
└───────────────────────────────────┴────────────────────┴───────────────────┘
CONFORME A
4.4BSD.
ERRORES
In versions of glibc before 2.23, all of the APIs described in this man page are not safe
when compiling a program using the LFS APIs (e.g., when compiling with
-D_FILE_OFFSET_BITS=64).
VÉASE TAMBIÉN
find(1), chdir(2), stat(2), ftw(3), qsort(3)
COLOFÓN
Esta página es parte de la versión 5.10 del proyecto Linux man-pages. Puede encontrar una
descripción del proyecto, información sobre cómo informar errores y la última versión de
esta página en https://www.kernel.org/doc/man-pages/.
TRADUCCIÓN
La traducción al español de esta página del manual fue creada por Miguel Pérez Ibars
<mpi79470@alu.um.es>
Esta traducción es documentación libre; lea la GNU General Public License Version 3
⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ o posterior con respecto a las condiciones de
copyright. No existe NINGUNA RESPONSABILIDAD.
Si encuentra algún error en la traducción de esta página del manual, envíe un correo
electrónico a debian-l10n-spanish@lists.debian.org ⟨⟩.