table of contents
FTS(3) | Library Functions Manual | FTS(3) |
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 afts_open
() (veaFTS_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
() ofts_read
() devuelven una estructura FTSENT cuyo campo fts_info valeFTS_DNR
,FTS_ERR
oFTS_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 aNULL
. - 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ónfts_open
() se le debe especificar bienFTS_LOGICAL
, bienFTS_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ónFTS_NOCHDIR
desactiva esta optimización y las funcionesfts
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ónFTS_NOCHDIR
y se pasen caminos de fichero absolutos como argumentos afts_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 valorFTS_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ónfts_open
() se le debe especificar bienFTS_LOGICAL
, bienFTS_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 rutinasfts
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 porfts_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 afts_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 porfts_children
(), los campos fts_info y fts_statp de la estructura, cuando son devueltos porfts_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
() ofts_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¶
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.
16 abril, 1994 | Linux 5.14.0-427.18.1.el9_4.x86_64 |