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)
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.