NOMBRE¶
glob, globfree - encuentra nombres de caminos que concuerdan con un patrón,
libera la memoria ocupada por glob()
SINOPSIS¶
#include <glob.h>
int glob(const char *patron, int flags,
int funcerr(const char * epath, int eerrno),
glob_t *pglob);
void globfree(glob_t *pglob);
DESCRIPCIÓN¶
La función
glob() busca todos los nombres de camino de los ficheros
que concuerden con
patron según las reglas usadas por el
interprete de órdenes o shell. No se realiza ni expansión de la
tilde (~) ni sustitución de parámetros; si quiere esto, use
wordexp(3).
La función
globfree() libera el almacenamiento alojado
dinámicamente en una llamada anterior a
glob().
Los resultados de una llamada a
glob() se guardan en la estructura a la
que apunte
pglob, que es un
glob_t que se declara en
<glob.h> e incluye los siguientes elementos definidos por POSIX.2
(se pueden presentar más como extensiones):
typedef struct
{
size_t gl_pathc; /* Nº de caminos concordantes hasta ahora */
char **gl_pathv; /* Lista de los caminos concordantes. */
size_t gl_offs; /* Sitios a reservar en `gl_pathv'. */
} glob_t;
Los resultados se almacenan en memoria obtenida dinámicamente.
El parámetro
flags se construye mediante un
O-lógico de
cero o más de las constantes simbólicas siguientes, que modifican el
comportamiento de
glob():
- GLOB_ERR
- que significa regresar en cuanto haya un error de lectura
(porque un directorio no haya concedido permiso de lectura, por
ejemplo),
- GLOB_MARK
- que quiere decir añadir una barra inclinada a cada
camino que corresponda a un directorio,
- GLOB_NOSORT
- que quiere decir no ordenar los nombres de caminos
devueltos (se ordenan si no se dice nada),
- GLOB_DOOFFS
- que quiere decir que se reservarán
pglob->gl_offs sitios al principio de la lista de cadenas de
caracteres en pglob->pathv,
- GLOB_NOCHECK
- que quiere decir que, si ningún patrón concuerda,
hay que devolver el patrón original.
- GLOB_APPEND
- que quiere decir añadir a los resultados de una
llamada anterior. No active esta opción la primera vez que llame a
glob().
- GLOB_NOESCAPE
- que quiere decir que los meta-caracteres no pueden ser
protegidos por barras inclinadas invertidas.
Las opciones también pueden incluir algunas de las siguientes constantes,
que son extensiones GNU no definidar por POSIX.2:
- GLOB_PERIOD
- que quiere decir que un punto inicial puede concordar con
meta-caracteres,
- GLOB_ALTDIRFUNC
- que quiere decir que se usen las funciones alternativas
pglob->gl_closedir, pglob->gl_readdir,
pglob->gl_opendir, pglob->gl_lstat y
pglob->gl_stat para acceder al sistema de ficheros, en lugar de
las funciones normales de biblioteca,
- GLOB_BRACE
- que quiere decir que se expandan las expresiones de llaves
{a,b} al estilo csh(1).
- GLOB_NOMAGIC
- que quiere decir que se devuelva el patrón si no
contiene meta-caracteres,
- GLOB_TILDE
- que indica que se lleve a cabo la expansión de la
tilde (~), y
- GLOB_ONLYDIR
- que significa que sólo se tengan en cuenta los
directorios.
Si
funcerr no es
NULL, se llamará en caso de error con los
argumentos
epath, un puntero al camino que ha fallado, y
eerrno,
el valor de
errno según es devuelto por una de las llamadas a
opendir(),
readdir(), o
stat(). Si
funcerr
devuelve no cero, o si
GLOB_ERR está activado,
glob()
terminará justo tras la llamada a
funcerr.
Tras un regreso con éxito de la función,
pglob->gl_pathc
contiene el número de nombres de caminos que han concordado y
pglob->gl_pathv un puntero a la lista de nombres de caminos que han
concordado. El primer puntero tras el último nombre de camino es
NULL.
Es posible el llamar a
glob() varias veces. En ese caso, la opción
GLOB_APPEND tiene que estar activa en
flags en la segunda
llamada y posteriores.
Como extensión GNU, a
pglob->gl_flags se le asignan las opciones
especificadas, operadas mediante un
O-lógico con
GLOB_MAGCHAR si se encontró cualquier meta-carácter.
VALOR DEVUELTO¶
Tras una terminación con éxito,
glob() devuelve cero. Otras
posibles devoluciones son:
- GLOB_NOSPACE
- si no tenemos bastante memoria,
- GLOB_ABORT
- para un error de lectura, y
- GLOB_NOMATCH
- si no se ha encontrado nada.
EJEMPLOS¶
Un ejemplo del modo de empleo es el siguiente código, que simula la orden
ls -l *.c ../*.c en el shell.
glob_t globbuf;
globbuf.gl_offs = 2;
glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf);
globbuf.gl_pathv[0] = "ls";
globbuf.gl_pathv[1] = "-l";
execvp("ls", &globbuf.gl_pathv[0]);
POSIX.2
FALLOS¶
La función
glob() puede fallar debido a un error en las funciones
subyacentes, como
malloc() u
opendir(). Éstas
guardarán su código de error en
errno.
NOTA¶
Los elementos de estructura
gl_pathc y
gl_offs se declaran como
size_t en glibc 2.1, como deberían de acuerdo a POSIX.2, pero se
declaran como
int en libc4, libc5 y glibc 2.0.
VÉASE TAMBIÉN¶
ls(1),
sh(1),
stat(2),
exec(3),
malloc(3),
opendir(3),
readdir(3),
wordexp(3),