.\" -*- coding: UTF-8 -*- '\" t .\" $NetBSD: fts.3,v 1.13.2.1 1997/11/14 02:09:32 mrg Exp $ .\" .\" Copyright (c) 1989, 1991, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" .\" SPDX-License-Identifier: BSD-4-Clause-UC .\" .\" @(#)fts.3 8.5 (Berkeley) 4/16/94 .\" .\" 2007-12-08, mtk, Converted from mdoc to man macros .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH fts 3 "15 Diciembre 2022" "Páginas de manual de Linux 6.03" .SH NOMBRE fts, fts_open, fts_read, fts_children, fts_set, fts_close \- recorren una jerarquía de ficheros .SH BIBLIOTECA Biblioteca Estándar C (\fIlibc\fP, \fI\-lc\fP) .SH SINOPSIS .nf \fB#include \fP \fB#include \fP \fB#include \fP .PP \fBFTS *fts_open(char * const *\fP\fIpath_argv\fP\fB, int \fP\fIoptions\fP\fB,\fP \fB int (*\fP\fIcompar\fP\fB)(const FTSENT **, const FTSENT **));\fP .PP \fBFTSENT *fts_read(FTS *\fP\fIftsp\fP\fB);\fP .PP \fBFTSENT *fts_children(FTS *\fP\fIftsp\fP\fB, int \fP\fIinstr\fP\fB);\fP .PP \fBint fts_set(FTS *\fP\fIftsp\fP\fB, FTSENT *\fP\fIf\fP\fB, int \fP\fIinstr\fP\fB);\fP .PP \fBint fts_close(FTS *\fP\fIftsp\fP\fB);\fP .fi .SH DESCRIPCIÓN The fts functions are provided for traversing file hierarchies. A simple overview is that the \fBfts_open\fP() function returns a "handle" (of type \fIFTS\ *\fP) that refers to a file hierarchy "stream". This handle is then supplied to the other fts functions. The function \fBfts_read\fP() returns a pointer to a structure describing one of the files in the file hierarchy. The function \fBfts_children\fP() returns a pointer to a linked list of structures, each of which describes one of the files contained in a directory in the hierarchy. .PP 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. .PP Two structures (and associated types) are defined in the include file \fI\fP. The first type is \fIFTS\fP, the structure that represents the file hierarchy itself. The second type is \fIFTSENT\fP, the structure that represents a file in the file hierarchy. Normally, an \fIFTSENT\fP structure is returned for every file in the file hierarchy. In this manual page, "file" and "FTSENT structure" are generally interchangeable. .PP The \fIFTSENT\fP 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): .PP .in +4n .EX .\" Also: .\" ino_t fts_ino; /* inode (only for directories)*/ .\" dev_t fts_dev; /* device (only for directories)*/ .\" nlink_t fts_nlink; /* link count (only for directories)*/ .\" u_short fts_flags; /* private flags for FTSENT structure */ .\" u_short fts_instr; /* fts_set() instructions */ 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; .EE .in .PP .\" .Bl -tag -width "fts_namelen" Estos campos se definen de la siguiente manera: .TP \fIfts_info\fP .\" .Bl -tag -width FTS_DEFAULT Uno de las siguientes valores que describen la estructura \fIFTSENT\fP devuelta y el fichero que representa. Con la excepción de directorios sin errores (\fBFTS_D\fP), todas estas entradas son terminales, es decir, no volverán a ser visitadas, ni tampoco ninguno de sus descendientes. .RS .TP \fBFTS_D\fP Un directorio que está siendo visitado en pre\-orden. .TP \fBFTS_DC\fP Un directorio que provoca un ciclo en el árbol. (El campo \fIfts_cycle\fP de la estructura \fIFTSENT\fP será rellenado también.) .TP \fBFTS_DEFAULT\fP Cualquier estructura \fIFTSENT\fP que represente un tipo de fichero no descrito explícitamente por uno de los otros valores de \fIfts_info\fP. .TP \fBFTS_DNR\fP Un directorio que no puede ser leído. Este valor indica un error y el campo \fIfts_errno\fP será modificado para reflejar la causa del error. .TP \fBFTS_DOT\fP Un fichero llamado "." o ".." que no fue especificado como un nombre de fichero a \fBfts_open\fP() (vea \fBFTS_SEEDOT\fP). .TP \fBFTS_DP\fP Un directorio que está siendo visitado en post\-orden. El contenido de la estructura \fIFTSENT\fP será el mismo que el que se devolvió cuando el directorio se visitó en pre\-orden, es decir, con el valor \fBFTS_D\fP en el campo \fIfts_info\fP. .TP \fBFTS_ERR\fP Este valor indica un error y el campo \fIfts_errno\fP será modificado para reflejar la causa del error. .TP \fBFTS_F\fP Un fichero regular. .TP \fBFTS_NS\fP A file for which no [\fBl\fP]\fBstat\fP(2) information was available. The contents of the \fIfts_statp\fP field are undefined. This is an error return, and the \fIfts_errno\fP field will be set to indicate what caused the error. .TP \fBFTS_NSOK\fP A file for which no [\fBl\fP]\fBstat\fP(2) information was requested. The contents of the \fIfts_statp\fP field are undefined. .TP \fBFTS_SL\fP Un enlace simbólico. .TP \fBFTS_SLNONE\fP .\" .El Un enlace simbólico con un destino inexistente. El contenido del campo \fIfts_statp\fP hace referencia a la información característica del fichero para el enlace simbólico en sí mismo. .RE .TP \fIfts_accpath\fP Un camino para acceder al fichero desde el directorio actual. .TP \fIfts_path\fP El camino del fichero relativo a la raíz del recorrido. Este caminio contiene el camino especificado a \fIfts_open\fP() como prefijo. .TP \fIfts_pathlen\fP The sum of the lengths of the strings referenced by \fIfts_path\fP and \fIfts_name\fP. .TP \fIfts_name\fP El nombre del archivo. .TP \fIfts_namelen\fP La longitud de la cadena referenciada por \fIfts_name\fP. .TP \fIfts_level\fP La profundidad del recorrido, numerada desde \-1 hasta N, donde fue encontrado este fichero. La estructura \fIFTSENT\fP que representa al padre del punto de partida (o raíz) del recorrido se numera con \-1 y la estructura \fIFTSENT\fP para la raíz en sí misma se numera con 0. .TP \fIfts_errno\fP If \fBfts_children\fP() or \fBfts_read\fP() returns an \fIFTSENT\fP structure whose \fIfts_info\fP field is set to \fBFTS_DNR\fP, \fBFTS_ERR\fP, or \fBFTS_NS\fP, the \fIfts_errno\fP field contains the error number (i.e., the \fIerrno\fP value) specifying the cause of the error. Otherwise, the contents of the \fIfts_errno\fP field are undefined. .TP \fIfts_number\fP Este campo se proporciona para su uso por la aplicación y no es modificado por las funciones fts. Se inicializa a 0. .TP \fIfts_pointer\fP Este campo se proporciona para su uso por la aplicación y no es modificado por las funciones fts. Se inicializa a NULL. .TP \fIfts_parent\fP Un puntero a la estructura \fIFTSENT\fP 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 \fIfts_level\fP, \fIfts_number\fP y \fIfts_pointer\fP. .TP \fIfts_link\fP A la vuelta de la función \fBfts_children\fP(), el campo \fIfts_link\fP apunta a la siguiente estructura en la lista enlazada terminada en NULL de miembros de directorio. En otro caso, el contenido del campo \fIfts_link\fP es indefinido. .TP \fIfts_cycle\fP Si un directorio causa un ciclo en la jerarquía (vea \fBFTS_DC\fP), bien debido a un enlace físico entre dos directorios, bien por un enlace simbólico que apunta a un directorio, el campo \fIfts_cycle\fP de la estructura apuntará a la estructura \fIFTSENT\fP en la jerarquía que referencie el mismo fichero que la estructura \fIFTSENT\fP actual. En otro caso, el contenido del campo \fIfts_cycle\fP es indefinido. .TP \fIfts_statp\fP .\" .El Un puntero a información de tipo [\fBl\fP]\fBstat\fP(2) para el fichero. .PP 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 \fIfts_path\fP y \fIfts_accpath\fP terminan en NULL \fIsólo\fP para el fichero más recientemente devuelto por \fIfts_read\fP. Para usar estos campos para referenciar a cualesquier fichero representado por otra estructura \fIFTSENT\fP, será necesario que se modifique el buffer de rutas usando la información contenida en el campo \fIfts_pathlen\fP de esa estructura \fIFTSENT\fP. Cualquiera modificación se deberá deshacer antes de intentar llamar otra vez a \fIfts_read\fP. El campo \fIfts_name\fP siempre termina en NULL. .SS fts_open() La función \fBfts_open\fP() 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. .PP .\" .Bl -tag -width "FTS_PHYSICAL" Hay varias opciones, al menos una de las cuales (bien \fBFTS_LOGICAL\fP o \fBFTS_PHYSICAL\fP) debe ser especificada. Las opciones se seleccionan concatenando con la operación \fIor\fP los siguientes valores: .TP \fBFTS_LOGICAL\fP This option causes the fts routines to return \fIFTSENT\fP structures for the targets of symbolic links instead of the symbolic links themselves. If this option is set, the only symbolic links for which \fIFTSENT\fP structures are returned to the application are those referencing nonexistent files: the \fIfts_statp\fP field is obtained via \fBstat\fP(2) with a fallback to \fBlstat\fP(2). .TP \fBFTS_PHYSICAL\fP This option causes the fts routines to return \fIFTSENT\fP structures for symbolic links themselves instead of the target files they point to. If this option is set, \fIFTSENT\fP structures for all symbolic links in the hierarchy are returned to the application: the \fIfts_statp\fP field is obtained via \fBlstat\fP(2). .TP \fBFTS_COMFOLLOW\fP This option causes any symbolic link specified as a root path to be followed immediately, as if via \fBFTS_LOGICAL\fP, regardless of the primary mode. .TP \fBFTS_NOCHDIR\fP 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 \fBFTS_NOCHDIR\fP is specified and absolute pathnames were provided as arguments to \fBfts_open\fP(). .TP \fBFTS_NOSTAT\fP By default, returned \fIFTSENT\fP structures reference file characteristic information (the \fIfts_statp\fP field) for each file visited. This option relaxes that requirement as a performance optimization, allowing the fts functions to set the \fIfts_info\fP field to \fBFTS_NSOK\fP and leave the contents of the \fIfts_statp\fP field undefined. .TP \fBFTS_SEEDOT\fP Por defecto, a menos que se especifiquen como argumentos de camino a \fBfts_open\fP(), cualquier fichero con nombre "." o ".." encontrado en la jerarquía de ficheros es ignorado. Esta opción hace que las rutinas fts devuelvan estructuras \fIFTSENT\fP para ellos. .TP \fBFTS_XDEV\fP .\" .El 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. .PP El argumento \fBcompar\fP() 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 \fIFTSENT\fP 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 \fIfts_accpath\fP, \fIfts_path\fP y \fIfts_pathlen\fP de las estructuras \fIFTSENT\fP \fInunca\fP deben utilizarse en esta comparación. Si el campo \fIfts_info\fP tiene un valor \fBFTS_NS\fP o \fBFTS_NSOK\fP, el campo .Fa fts_statp tampoco debe usarse. Si el argumento \fBcompar\fP() vale NULL, el orden de recorrido de los directorios es en el orden listado en \fIpath_argv\fP para los caminos raíz, y en el orden de aparición en el directorio para cualquier otro. .SS fts_read() La función \fBfts_read\fP() devuelve un puntero a una estructura \fIFTSENT\fP 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.) .PP If all the members of the hierarchy have been returned, \fBfts_read\fP() returns NULL and sets \fIerrno\fP to 0. If an error unrelated to a file in the hierarchy occurs, \fBfts_read\fP() returns NULL and sets \fIerrno\fP to indicate the error. If an error related to a returned file occurs, a pointer to an \fIFTSENT\fP structure is returned, and \fIerrno\fP may or may not have been set (see \fIfts_info\fP). .PP Las estructuras \fIFTSENT\fP devueltas por \fBfts_read\fP() pueden ser sobrescritas después de una llamada a \fBfts_close\fP() sobre el mismo flujo de jerarquía de ficheros o después de una llamada a \fBfts_read\fP() 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 \fBfts_read\fP(), después de que la estructura \fIFTSENT\fP haya sido devuelta por la función \fBfts_read\fP() en post\-orden. .SS fts_children() La función \fBfts_children\fP() devuelve un puntero a una estructura \fIFTSENT\fP describiendo la primera entrada de una lista enlazada terminada en NULL de los ficheros en el directorio representado por la estructura \fIFTSENT\fP más recientemente devuelta por \fBfts_read\fP(). La lista se enlaza mediante el campo \fIfts_link\fP de la estructura \fIFTSENT\fP y es ordenada por la función de comparación definida por el usuario, si se especifica. Llamadas repetidas a \fIfts_children\fP() volverán a crear esta lista enlazada. .PP As a special case, if \fBfts_read\fP() has not yet been called for a hierarchy, \fBfts_children\fP() will return a pointer to the files in the logical directory specified to \fBfts_open\fP(), that is, the arguments specified to \fBfts_open\fP(). Otherwise, if the \fIFTSENT\fP structure most recently returned by \fBfts_read\fP() is not a directory being visited in preorder, or the directory does not contain any files, \fBfts_children\fP() returns NULL and sets \fIerrno\fP to zero. If an error occurs, \fBfts_children\fP() returns NULL and sets \fIerrno\fP to indicate the error. .PP Las estructuras \fIFTSENT\fP devueltas por \fBfts_children\fP() pueden ser sobrescritas tras una llamada a \fBfts_children\fP(), \fBfts_close\fP() o \fBfts_read\fP() sobre el mismo flujo de jerarquía de ficheros. .PP .\" .Bl -tag -width FTS_NAMEONLY The \fIinstr\fP argument is either zero or the following value: .TP \fBFTS_NAMEONLY\fP .\" .El 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 \fIfts_name\fP y \fIfts_namelen\fP. .SS fts_set() The function \fBfts_set\fP() allows the user application to determine further processing for the file \fIf\fP of the stream \fIftsp\fP. The \fBfts_set\fP() function returns 0 on success, and \-1 if an error occurs. .PP .\" .Bl -tag -width FTS_PHYSICAL The \fIinstr\fP argument is either 0 (meaning "do nothing") or one of the following values: .TP \fBFTS_AGAIN\fP Revisitar el fichero; cualquier tipo de fichero puede ser revisitado. La siguiente llamada a \fBfts_read\fP() devolverá el fichero referenciado. Los campos \fIfts_stat\fP y \fIfts_info\fP 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 \fBfts_read\fP(). 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. .TP \fBFTS_FOLLOW\fP El fichero referenciado debe ser un enlace simbólico. Si el fichero referenciado es aquel más recientemente devuelto por \fBfts_read\fP(), la siguiente llamada a \fBfts_read\fP() devuelve el fichero con los campos \fIfts_info\fP y \fIfts_statp\fP 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 \fBfts_children\fP(), los campos \fIfts_info\fP y \fIfts_statp\fP de la estructura, cuando son devueltos por \fBfts_read\fP(), 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 \fIfts_info\fP valdrá \fBFTS_SLNONE\fP. .IP 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. .TP \fBFTS_SKIP\fP .\" .El No se visita a los descendientes de este fichero. El fichero debe ser uno de aquellos más recientemente devueltos por \fBfts_children\fP() o \fBfts_read\fP(). .SS fts_close() The \fBfts_close\fP() function closes the file hierarchy stream referred to by \fIftsp\fP and restores the current directory to the directory from which \fBfts_open\fP() was called to open \fIftsp\fP. The \fBfts_close\fP() function returns 0 on success, and \-1 if an error occurs. .SH ERRORES The function \fBfts_open\fP() may fail and set \fIerrno\fP for any of the errors specified for \fBopen\fP(2) and \fBmalloc\fP(3). .PP The function \fBfts_close\fP() may fail and set \fIerrno\fP for any of the errors specified for \fBchdir\fP(2) and \fBclose\fP(2). .PP The functions \fBfts_read\fP() and \fBfts_children\fP() may fail and set \fIerrno\fP for any of the errors specified for \fBchdir\fP(2), \fBmalloc\fP(3), \fBopendir\fP(3), \fBreaddir\fP(3), and [\fBl\fP]\fBstat\fP(2). .PP Además, \fBfts_children\fP(), \fBfts_open\fP() y \fBfts_set\fP() pueden fallar y modificar \fIerrno\fP como sigue: .TP \fBEINVAL\fP \fIoptions\fP or \fIinstr\fP was invalid. .SH VERSIONES Estas funciones están disponibles en Linux desde glibc2. .SH ATRIBUTOS Para obtener una explicación de los términos usados en esta sección, véase \fBattributes\fP(7). .ad l .nh .TS allbox; lbx lb lb l l l. Interfaz Atributo Valor T{ \fBfts_open\fP(), \fBfts_set\fP(), \fBfts_close\fP() T} Seguridad del hilo Multi\-hilo seguro T{ \fBfts_read\fP(), \fBfts_children\fP() T} Seguridad del hilo MT\-Unsafe .TE .hy .ad .sp 1 .SH ESTÁNDARES 4.4BSD. .SH ERRORES .\" Fixed by commit 8b7b7f75d91f7bac323dd6a370aeb3e9c5c4a7d5 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=15838 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=11460 .\" .\" The following statement is years old, and seems no closer to .\" being true -- mtk .\" The .\" .I fts .\" utility is expected to be included in a future .\" POSIX.1 .\" revision. 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 \fI\-D_FILE_OFFSET_BITS=64\fP). .SH "VÉASE TAMBIÉN" \fBfind\fP(1), \fBchdir\fP(2), \fBlstat\fP(2), \fBstat\fP(2), \fBftw\fP(3), \fBqsort\fP(3) .PP .SH TRADUCCIÓN La traducción al español de esta página del manual fue creada por Miguel Pérez Ibars . .PP Esta traducción es documentación libre; lea la .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License Version 3 .UE o posterior con respecto a las condiciones de copyright. No existe NINGUNA RESPONSABILIDAD. .PP Si encuentra algún error en la traducción de esta página del manual, envíe un correo electrónico a .MT debian-l10n-spanish@lists.debian.org .ME .