Provided by: manpages-es-dev_4.21.0-2_all 
NOMBRE
fts, fts_open, fts_read, fts_children, fts_set, fts_close - recorren una jerarquía de ficheros
BIBLIOTECA
Biblioteca Estándar C (libc, -lc)
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; /* [l]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 A file for which no [l]stat(2) information was available. The contents of the fts_statp
field are undefined. This is an error return, and the fts_errno field will be set to
indicate what caused the error.
FTS_NSOK
A file for which no [l]stat(2) information was requested. The contents of the fts_statp
field are undefined.
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 archivo.
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 [l]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_LOGICAL
This option causes the fts routines to return FTSENT structures for the targets of symbolic links
instead of the symbolic links themselves. If this option is set, the only symbolic links for
which FTSENT structures are returned to the application are those referencing nonexistent files:
the fts_statp field is obtained via stat(2) with a fallback to lstat(2).
FTS_PHYSICAL
This option causes the fts routines to return FTSENT structures for symbolic links themselves
instead of the target files they point to. If this option is set, FTSENT structures for all
symbolic links in the hierarchy are returned to the application: the fts_statp field is obtained
via lstat(2).
FTS_COMFOLLOW
This option causes any symbolic link specified as a root path to be followed immediately, as if
via FTS_LOGICAL, regardless of the primary mode.
FTS_NOCHDIR
As a performance optimization, the fts functions change directories as they walk the file
hierarchy. This has the side-effect that an application cannot rely on being in any particular
directory during the traversal. This option turns off this optimization, and the fts functions
will not change the current directory. Note that applications should not themselves change their
current directory and try to access files unless FTS_NOCHDIR is specified and absolute pathnames
were provided as arguments to fts_open().
FTS_NOSTAT
By default, returned FTSENT structures reference file characteristic information (the fts_statp
field) for each file visited. This option relaxes that requirement as a performance optimization,
allowing the fts functions to set the fts_info field to FTS_NSOK and leave the contents of the
fts_statp field undefined.
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.)
If all the members of the hierarchy have been returned, fts_read() returns NULL and sets errno to 0. If
an error unrelated to a file in the hierarchy occurs, fts_read() returns NULL and sets errno to indicate
the error. If an error related to a returned file occurs, a pointer to an FTSENT structure is returned,
and errno may or may not have been set (see 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.
As a special case, if fts_read() has not yet been called for a hierarchy, fts_children() will return a
pointer to the files in the logical directory specified to fts_open(), that is, the arguments specified
to fts_open(). Otherwise, if the FTSENT structure most recently returned by fts_read() is not a
directory being visited in preorder, or the directory does not contain any files, fts_children() returns
NULL and sets errno to zero. If an error occurs, fts_children() returns NULL and sets errno to indicate
the error.
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 [l]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 │
└──────────────────────────────────────────────────────────────┴────────────────────┴───────────────────┘
ESTÁNDARES
4.4BSD.
ERRORES
Before glibc 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), lstat(2), stat(2), ftw(3), qsort(3)
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 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.
Páginas de manual de Linux 6.03 15 Diciembre 2022 fts(3)