Rechercher une page de manuel
fts
Langue: es
Version: 52402 (openSuse - 09/10/07)
Section: 3 (Bibliothèques de fonctions)
Sommaire
BSD mandoc
NOMBRE
fts fts_open fts_read fts_children fts_set fts_close - recorren una jerarquÃa de ficherosSINOPSIS
Fd #include <sys/types.h> Fd #include <sys/stat.h> Fd #include <fts.h> Ft FTS * Fn fts_open char * const *path_argv int options int (*compar)(const FTSENT **, const FTSENT **) Ft FTSENT * Fn fts_read FTS *ftsp Ft FTSENT * Fn fts_children FTS *ftsp int options Ft int Fn fts_set FTS *ftsp FTSENT *f int options Ft int Fn fts_close FTS *ftspDESCRIPCIÓN
Las funciones fts se suministran para recorrer jerarquÃas de ficheros UNIX. De manera general, la función Fn fts_open devuelve un ``manejador'' sobre una jerarquÃa de ficheros, que luego es pasado a las otras funciones fts. La función Fn fts_read devuelve un puntero a una estructura que describe uno de los ficheros en la jerarquÃa de ficheros. La función Fn 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 Aq Pa fts.h . La primera es Fa FTS , la estructura que representa la jerarquÃa de ficheros en sà misma. La segunda es Fa FTSENT , la estructura que representa un fichero en la jerarquÃa de ficheros. Normalmente, se devuelve una estructura Fa FTSENT por cada fichero en la jerarquÃa de ficheros. En esta página de manual, ``fichero'' y estructura ``Fa FTSENT '' son generalmente intercambiables. La estructura Fa 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:
- Fa fts_info
- Uno de las siguientes banderas que describen la estructura Fa 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 Fa fts_cycle de la estructura Fa FTSENT será rellenado también.)
- FTS_DEFAULT
- Cualquier estructura Fa FTSENT que represente un tipo de fichero no descrito explÃcitamente por uno de los otros valores de Fa fts_info.
- FTS_DNR
- Un directorio que no puede ser leÃdo. Este valor indica un error y el campo Fa 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 Fn fts_open (vea FTS_SEEDOT )
- FTS_DP
- Un directorio que está siendo visitado en post-orden. El contenido de la estructura Fa 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 Fa fts_info .
- FTS_ERR
- Este valor indica un error y el campo Fa 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 Fa fts_statp es indefinido. Este valor indica un error y el campo Fa 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 Fa fts_statp es indefinido.
- FTS_SL
- Un enlace simbólico.
- FTS_SLNONE
- Un enlace simbólico con un destino inexistente. El contenido del campo Fa fts_statp hace referencia a la información caracterÃstica del fichero para el enlace simbólico en sà mismo.
- Fa fts_accpath
- Un camino para acceder al fichero desde el directorio actual.
- Fa fts_path
- El camino del fichero relativo a la raÃz del recorrido. Este caminio contiene el camino especificado a Fn fts_open como prefijo.
- Fa fts_pathlen
- La longitud de la cadena referenciada por Fa fts_path .
- Fa fts_name
- El nombre del fichero.
- Fa fts_namelen
- La longitud de la cadena referenciada por Fa fts_name .
- Fa fts_level
- La profundidad del recorrido, numerada desde -1 hasta N, donde fue encontrado este fichero. La estructura Fa FTSENT que representa al padre del punto de partida (o raÃz) del recorrido se numera con -1 y la estructura Fa FTSENT para la raÃz en sà misma se numera con 0.
- Fa fts_errno
- Cuando las funciones Fn fts_children o Fn fts_read devuelven una estructura Fa FTSENT cuyo campo Fa fts_info vale FTS_DNR FTS_ERR o FTS_NS el campo Fa fts_errno contiene el valor de la variable externa errno especificando la causa del error. En caso contrario, el contenido del campo Fa fts_errno es indefinido.
- Fa 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.
- Fa 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
- Fa fts_parent
- Un puntero a la estructura Fa 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 Fa fts_level , Fa fts_number y Fa fts_pointer .
- Fa fts_link
- A la vuelta de la función Fn fts_children , el campo Fa 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 Fa fts_link es indefinido.
- Fa 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 Fa fts_cycle de la estructura apuntará a la estructura Fa FTSENT en la jerarquÃa que referencie el mismo fichero que la estructura Fa FTSENT actual. En otro caso, el contenido del campo Fa fts_cycle es indefinido.
- Fa 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 Fa fts_path y Fa fts_accpath terminan en NULL sólo para el fichero más recientemente devuelto por Fn fts_read . Para usar estos campos para referenciar a cualesquier fichero representado por otra estructura Fa FTSENT , será necesario que se modifique el buffer de rutas usando la información contenida en el campo Fa fts_pathlen de esa estructura Fa FTSENT . Cualquiera modificación se deberá deshacer antes de intentar llamar otra vez a Fn fts_read . El campo Fa fts_name siempre termina en NULL
FTS_OPEN
La función Fn 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 Fa 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 Fa FTSENT a la aplicación son aquellos que hacen referencia a ficheros no existentes. A la función Fn 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 Fn fts_open .
- FTS_NOSTAT
- Por defecto, las estructuras Fa FTSENT devueltas hacen referencia a información caracterÃstica del fichero (el campo Fa statp ) para cada fichero visitado. Esta opción relaja ese requisito para mejorar del rendimiento, permitiendo a las funciones fts establecer el campo Fa fts_info al valor FTS_NSOK y dejar el contenido del campo Fa statp indefinido.
- FTS_PHYSICAL
- Esta opción hace que las rutinas fts devuelvan estructuras Fa 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 Fa FTSENT para todos los enlaces simbólicos en la jerarquÃa. A la función Fn 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 Fn 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 Fa 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 Fn 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 Fa 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 Fa fts_accpath , Fa fts_path y Fa fts_pathlen de las estructuras Fa FTSENT nunca deben utilizarse en esta comparación. Si el campo Fa fts_info tiene un valor FTS_NS o FTS_NSOK el campo Fa fts_statp tampoco debe usarse. Si el argumento Fn compar vale NULL el orden de recorrido de los directorios es en el orden listado en Fa 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 Fn fts_read devuelve un puntero a una estructura Fa 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, Fn 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, Fn 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 Fa FTSENT y errno puede o no tomar algún valor (vea Fa fts_info ) .
Las estructuras Fa FTSENT devueltas por Fn fts_read pueden ser sobrescritas después de una llamada a Fn fts_close sobre el mismo flujo de jerarquÃa de ficheros o después de una llamada a Fn 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 Fn fts_read , después de que la estructura Fa FTSENT haya sido devuelta por la función Fn fts_read en post-orden.
FTS_CHILDREN
La función Fn fts_children devuelve un puntero a una estructura Fa FTSENT describiendo la primera entrada de una lista enlazada terminada en NULL de los ficheros en el directorio representado por la estructura Fa FTSENT más recientemente devuelta por Fn fts_read . La lista se enlaza mediante el campo Fa fts_link de la estructura Fa FTSENT y es ordenada por la función de comparación definida por el usuario, si se especifica. Llamadas repetidas a Fn fts_children volverán a crear esta lista enlazada.Como caso especial, si Fn fts_read no ha sido llamada aún para una jerarquÃa, Fn fts_children devolverá un puntero a los ficheros en el directorio lógico especificado a Fn fts_open , es decir, los argumentos especificados a Fn fts_open . En otro caso, si la estructura Fa FTSENT más recientemente devuelta por Fn fts_read no es un directorio que se está visitado en pre-orden, o el directorio no contiene ningún fichero, Fn fts_children devuelve NULL y modifica errno con valor cero. Si ocurre un error, Fn fts_children devuelve NULL y modifica errno con el valor apropiado.
Las estructuras Fa FTSENT devueltas por Fn fts_children pueden ser sobrescritas tras una llamada a Fn fts_children , Fn fts_close o Fn 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 Fa fts_name y Fa fts_namelen.
FTS_SET
La función Fn fts_set permite a la aplicación de usuario establecer un procesamiento adicional para el fichero Fa f del flujo Fa ftsp . La función Fn 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 Fn fts_read devolverá el fichero referenciado. Los campos Fa fts_stat y Fa 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 Fn 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 Fn fts_read , la siguiente llamada a Fn fts_read devuelve el fichero con los campos Fa fts_info y Fa 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 Fn fts_children , los campos Fa fts_info y Fa fts_statp de la estructura, cuando son devueltos por Fn 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 Fa 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 Fn fts_children o Fn fts_read .
FTS_CLOSE
La función Fn fts_close cierra un flujo de jerarquÃa de ficheros Fa ftsp y restablece el directorio actual al directorio desde el cual fue llamada Fn fts_open para abrir Fa ftsp . La función Fn fts_close devuelve 0 en caso de éxito y -1 si ocurre un error.ERRORES
La función Fn 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 Fn 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 Fn fts_read y Fn 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, Fn fts_children , Fn fts_open y Fn fts_set pueden fallar y modificar errno como sigue:
- Bq Er EINVAL
- Las opciones son inválidas.
VÉASE TAMBIÉN
find(1), chdir(2), stat(2), qsort(3)CONFORME A
BSD 4.4. Se espera que la utilidad fts sea incluida en una futura revisión St -p1003.1-88DISPONIBILIDAD
Estas funciones están disponibles en Linux desde glibc2.Contenus ©2006-2024 Benjamin Poulain
Design ©2006-2024 Maxime Vantorre