Provided by:
manpages-es_1.55-10_all 
NOMBRE
fts, fts_open, fts_read, fts_children, fts_set, fts_close -- recorren una
jerarquia 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'ON
Las funciones fts se suministran para recorrer jerarquias de ficheros
UNIX. De manera general, la funcion fts_open() devuelve un ``manejador''
sobre una jerarquia de ficheros, que luego es pasado a las otras
funciones fts. La funcion fts_read() devuelve un puntero a una estructura
que describe uno de los ficheros en la jerarquia de ficheros. La funcion
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 jerarquia. 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 (despues de que se hayan visitado
todos sus descencientes). Los ficheros se visitan una sola vez. Es
posible recorrer la jerarquia ``logicamente'' (ignorando los enlaces
simbolicos) o fisicamente (visitando los enlaces simbolicos), ordenar el
recorrido de la jerarquia o recortar y/o revisitar porciones de la
jerarquia.
Se definen dos estructuras en el fichero de cabecera <fts.h>. La primera
es FTS, la estructura que representa la jerarquia de ficheros en si
misma. La segunda es FTSENT, la estructura que representa un fichero en
la jerarquia de ficheros. Normalmente, se devuelve una estructura FTSENT
por cada fichero en la jerarquia de ficheros. En esta pagina de manual,
``fichero'' y estructura ``FTSENT'' son generalmente intercambiables. La
estructura FTSENT contiene al menos los siguientes campos, que se
describen con mayor detalle mas abajo:
typedef struct _ftsent {
u_short fts_info; /* banderas para la estructura FTSENT */
char *fts_accpath; /* camino de acceso */
char *fts_path; /* camino raiz */
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; /* codigo de error */
long fts_number; /* valor numerico local */
void *fts_pointer; /* valor de direccion local */
struct ftsent *fts_parent; /* directorio padre */
struct ftsent *fts_link; /* siguiente estructura de fichero */
struct ftsent *fts_cycle; /* estructura ciclica */
struct stat *fts_statp; /* informacion 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
excepcion de directorios sin errores (FTS_D), todas estas
entradas son terminales, es decir, no volveran a ser
visitadas, ni tampoco ninguno de sus descendientes.
FTS_D Un directorio que esta siendo visitado en pre-
orden.
FTS_DC Un directorio que provoca un ciclo en el arbol.
(El campo fts_cycle de la estructura FTSENT
sera rellenado tambien.)
FTS_DEFAULT Cualquier estructura FTSENT que represente un
tipo de fichero no descrito explicitamente por
uno de los otros valores de fts_info.
FTS_DNR Un directorio que no puede ser leido. Este
valor indica un error y el campo fts_errno sera
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 esta siendo visitado en post-
orden. El contenido de la estructura FTSENT
sera el mismo que el que se devolvio cuando el
directorio se visito 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
sera modificado para reflejar la causa del
error.
FTS_F Un fichero regular.
FTS_NS Un fichero para el que no hay informacion de
tipo stat(2) disponible. El contenido del
campo fts_statp es indefinido. Este valor
indica un error y el campo fts_errno sera
modificado para reflejar la causa del error.
FTS_NSOK Un fichero para el que no se solicito
informacion de tipo stat(2). El contenido del
campo fts_statp es indefinido.
FTS_SL Un enlace simbolico.
FTS_SLNONE Un enlace simbolico con un destino inexistente.
El contenido del campo fts_statp hace
referencia a la informacion caracteristica del
fichero para el enlace simbolico en si mismo.
fts_accpath Un camino para acceder al fichero desde el directorio
actual.
fts_path El camino del fichero relativo a la raiz 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 raiz) del
recorrido se numera con -1 y la estructura FTSENT para la
raiz en si 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 aplicacion y no
es modificado por las funciones fts. Se inicializa a 0.
fts_pointer Este campo se proporciona para su uso por la aplicacion 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 jerarquia inmediatamente encima del fichero actual,
esto es, el directorio del cual es miembro este fichero.
Tambien se proporciona una estructura padre para el punto de
entrada inicial, aunque solo se garantiza que se
inicializaran los campos fts_level, fts_number y
fts_pointer.
fts_link A la vuelta de la funcion 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 jerarquia (vea
FTS_DC), bien debido a un enlace fisico entre dos
directorios, bien por un enlace simbolico que apunta a un
directorio, el campo fts_cycle de la estructura apuntara a
la estructura FTSENT en la jerarquia 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 informacion de tipo stat(2) para el fichero.
Se utiliza un unico buffer para todas las rutas de todos los ficheros en
la jerarquia de ficheros. Por consiguiente, se garantiza que los campos
fts_path y fts_accpath terminan en NULL s'olo para el fichero mas
recientemente devuelto por fts_read(). Para usar estos campos para
referenciar a cualesquier fichero representado por otra estructura
FTSENT, sera necesario que se modifique el buffer de rutas usando la
informacion contenida en el campo fts_pathlen de esa estructura FTSENT.
Cualquiera modificacion se debera deshacer antes de intentar llamar otra
vez a fts_read(). El campo fts_name siempre termina en NULL.
FTS_OPEN
La funcion fts_open() acepta un puntero a un array de punteros a caracter
designando una o mas rutas o caminos que forman una jerarquia de ficheros
logica 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 operacion or los siguientes valores:
FTS_COMFOLLOW
Esta opcion hace que cualquier enlace simbolico
especificado como un camino raiz sea seguido inmediatamente
sin importar que la opcion FTS_LOGICAL fuese especificada.
FTS_LOGICAL Esta opcion hace que las rutinas fts devuelvan estructuras
FTSENT para los destinos de los enlaces simbolicos en lugar
de para los enlaces simbolicos en si mismos. Si esta
opcion esta presente, los unicos enlaces simbolicos para
los que se devuelven estructuras FTSENT a la aplicacion son
aquellos que hacen referencia a ficheros no existentes. A
la funcion fts_open() se le debe especificar bien
FTS_LOGICAL, bien FTS_PHYSICAL.
FTS_NOCHDIR Para mejorar el rendimiento, las funciones fts cambian de
directorio segun recorren la jerarquia de ficheros. Esto
tiene el efecto secundario de que una aplicacion no puede
confiar en estar en ningun directorio en particular durante
el recorrido. La opcion FTS_NOCHDIR desactiva esta
optimizacion y las funciones fts no cambiaran el directorio
actual. Observe que las aplicaciones no deberian por si
mismas cambiar su directorio actual e intentar acceder a
los ficheros a menos que se especifique la opcion
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 informacion caracteristica del fichero (el
campo statp) para cada fichero visitado. Esta opcion
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 opcion hace que las rutinas fts devuelvan estructuras
FTSENT para los enlaces simbolicos en si mismos en lugar de
para los ficheros destino a los que apuntan. Si esta
opcion esta presente, se devuelven a la aplicacion
estructuras FTSENT para todos los enlaces simbolicos en la
jerarquia. A la funcion 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 jerarquia de ficheros es ignorado.
Esta opcion hace que las rutinas fts devuelvan estructuras
FTSENT para ellos.
FTS_XDEV Esta opcion evita que las rutinas fts desciendan a
directorios que tienen un numero de dispositivo diferente
del fichero en el cual comienza el descenso.
El argumento compar() especifica una funcion definida por el usuario que
puede ser usada para ordenar el recorrido de la jerarquia. Acepta dos
punteros a punteros a estructuras FTSENT como argumentos y deberia
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 despues 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 comparacion. 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 raiz, y en el orden de aparicion en el directorio para cualquier
otro.
FTS_READ
La funcion fts_read() devuelve un puntero a una estructura FTSENT
describiendo un fichero de la jerarquia. 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 demas ficheros son visitados
al menos una vez. (Los enlaces fisicos entre directorios que no causan
ciclos o los enlaces simbolicos a enlaces simbolicos pueden hacer que
haya ficheros que se visiten mas de una vez o directorios que se visiten
mas de dos.)
Si todos los miembros de la jerarquia 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 jerarquia, 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 algun valor (vea fts_info).
Las estructuras FTSENT devueltas por fts_read() pueden ser sobrescritas
despues de una llamada a fts_close() sobre el mismo flujo de jerarquia de
ficheros o despues de una llamada a fts_read() sobre el mismo flujo de
jerarquia de ficheros, a menos que representen un fichero de tipo
directorio en cuyo caso no seran sobrescritas hasta despues de una
llamada a fts_read(), despues de que la estructura FTSENT haya sido
devuelta por la funcion fts_read() en post-orden.
FTS_CHILDREN
La funcion 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
mas recientemente devuelta por fts_read(). La lista se enlaza mediante
el campo fts_link de la estructura FTSENT y es ordenada por la funcion de
comparacion definida por el usuario, si se especifica. Llamadas
repetidas a fts_children() volveran a crear esta lista enlazada.
Como caso especial, si fts_read() no ha sido llamada aun para una
jerarquia, fts_children() devolvera un puntero a los ficheros en el
directorio logico especificado a fts_open(), es decir, los argumentos
especificados a fts_open(). En otro caso, si la estructura FTSENT mas
recientemente devuelta por fts_read() no es un directorio que se esta
visitado en pre-orden, o el directorio no contiene ningun 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 jerarquia de ficheros.
Option puede valer lo siguiente:
FTS_NAMEONLY Solo se necesitan los nombres de los ficheros. El
contenido de todos los campos en la lista enlazada devuelta
de estructuras es indefinido con la excepcion de los campos
fts_name y fts_namelen.
FTS_SET
La funcion fts_set() permite a la aplicacion de usuario establecer un
procesamiento adicional para el fichero f del flujo ftsp. La funcion
fts_set() devuelve 0 en caso de exito 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() devolvera el
fichero referenciado. Los campos fts_stat y fts_info de la
estructura seran reincializados, pero los demas campos no
sufriran cambios. Esta opcion solo tiene significado para
el fichero mas 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) asi como todos sus
descendientes.
FTS_FOLLOW El fichero referenciado debe ser un enlace simbolico. Si
el fichero referenciado es aquel mas 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
simbolico en lugar del enlace simbolico en si mismo. Si el
fichero es uno de aquellos mas recientemente devueltos por
fts_children(), los campos fts_info y fts_statp de la
estructura, cuando son devueltos por fts_read(), reflejaran
el destino del enlace simbolico en lugar del enlace
simbolico en si mismo. En ambos casos, si el destino del
enlace simbolico no existe, los campos de la estructura
devuelta permaneceran sin cambios y el campo fts_info
valdra FTS_SLNONE.
Si el fichero al que apunta el enlace simbolico 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 mas recientemente
devueltos por fts_children() o fts_read().
FTS_CLOSE
La funcion fts_close() cierra un flujo de jerarquia de ficheros ftsp y
restablece el directorio actual al directorio desde el cual fue llamada
fts_open() para abrir ftsp. La funcion fts_close() devuelve 0 en caso de
exito y -1 si ocurre un error.
ERRORES
La funcion fts_open() puede fallar y modificar errno para cualquiera de
los errores especificados para las funciones de biblioteca open(2) y
malloc(3).
La funcion 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).
Ademas, fts_children(), fts_open() y fts_set() pueden fallar y modificar
errno como sigue:
[EINVAL] Las opciones son invalidas.
V'EASE TAMBI'EN
find(1), chdir(2), stat(2), qsort(3)
CONFORME A
BSD 4.4. Se espera que la utilidad fts sea incluida en una futura
revision IEEE Std 1003.1-1988 (``POSIX.1'')
DISPONIBILIDAD
Estas funciones estan disponibles en Linux desde glibc2.