.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\" 
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\" 
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" License.
.\" Modified Wed Jul 28 11:12:17 1993 by Rik Faith (faith@cs.unc.edu)
.\" Modified Mon May 13 23:08:50 1996 by Martin Schulze (joey@linux.de)
.\" Modified 990912 by aeb
.\" Translated into Spanish Wed Feb 25 21:09:30 CET 1998 by Gerardo
.\" Aburruzaga García <gerardo.aburruzaga@uca.es>
.\" Modified 11 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
.\" Translation revised Tue Aug 18 1998 by Juan Piernas <piernas@ditec.um.es>
.\" Translation revised Tue Apr 18 2000 by Juan Piernas <piernas@ditec.um.es>
.\"
.TH GLOB 3  "12 septiembre 1999" "GNU" "Manual del Programador de Linux"
.SH NOMBRE
glob, globfree \- encuentra nombres de caminos que concuerdan con un
patrón, libera la memoria ocupada por glob()
.SH SINOPSIS
.nf
.B #include <glob.h>
.sp
.BI "int glob(const char *" patron ", int " flags ","
.nl
.BI "         int " funcerr "(const char * " epath ", int " eerrno ),
.nl
.BI "         glob_t " "*pglob" );
.nl
.BI "void globfree(glob_t *" pglob ");"
.fi
.SH DESCRIPCIÓN
La función
.B glob()
busca todos los nombres de camino de los ficheros que concuerden con
.I 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
.BR wordexp (3).
.PP
La función
.B globfree()
libera el almacenamiento alojado dinámicamente en una llamada anterior
a
.BR glob() .
.PP
Los resultados de una llamada a
.B glob()
se guardan en la estructura a la que apunte
.IR pglob ,
que es un
.B glob_t
que se declara en
.B <glob.h>
e incluye los siguientes elementos definidos por POSIX.2 (se pueden
presentar más como extensiones):
.PP
.br
.nf
.in 10
typedef struct
{
.in 14
    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'. */
.in 10
} glob_t;
.fi
.PP
Los resultados se almacenan en memoria obtenida dinámicamente.
.PP
El parámetro
.I flags
se construye mediante un \fBO\fR-lógico
de cero o más de las constantes simbólicas siguientes, que modifican el
comportamiento de
.BR glob() :
.TP
.B GLOB_ERR
que significa regresar en cuanto haya un error de lectura (porque un
directorio no haya concedido permiso de lectura, por ejemplo),
.TP
.B GLOB_MARK
que quiere decir añadir una barra inclinada a cada camino que
corresponda a un directorio,
.TP
.B GLOB_NOSORT
que quiere decir no ordenar los nombres de caminos devueltos (se
ordenan si no se dice nada),
.TP
.B GLOB_DOOFFS
que quiere decir que se reservarán
.I pglob->gl_offs
sitios al principio de la lista de cadenas de caracteres en
.IR pglob->pathv ,
.TP
.B GLOB_NOCHECK
que quiere decir que, si ningún patrón concuerda, hay que devolver el
patrón original.
.TP
.B 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
.BR glob() .
.TP
.B GLOB_NOESCAPE
que quiere decir que los meta-caracteres no pueden ser protegidos por
barras inclinadas invertidas.
.PP
Las opciones también pueden incluir algunas de las siguientes constantes,
que son extensiones GNU no definidar por POSIX.2:
.TP
.B GLOB_PERIOD
que quiere decir que un punto inicial puede concordar con
meta-caracteres,
.TP
.B GLOB_ALTDIRFUNC
que quiere decir que se usen las funciones alternativas
.IR pglob->gl_closedir ,
.IR pglob->gl_readdir ,
.IR pglob->gl_opendir ,
.I pglob->gl_lstat
y
.I pglob->gl_stat
para acceder al sistema de ficheros, en lugar de las funciones normales de
biblioteca,
.TP
.B GLOB_BRACE
que quiere decir que se expandan las expresiones de llaves \fB{a,b}\fR
al estilo
.BR csh (1).
.TP
.B GLOB_NOMAGIC
que quiere decir que se devuelva el patrón si no contiene meta-caracteres,
.TP
.B GLOB_TILDE
que indica que se lleve a cabo la expansión de la tilde (~), y
.TP
.B GLOB_ONLYDIR
que significa que sólo se tengan en cuenta los directorios.
.PP
Si
.I funcerr
no es
.BR NULL ,
se llamará en caso de error con los argumentos
.IR epath ,
un puntero al camino que ha fallado, y
.IR eerrno ,
el valor de
.I errno
según es devuelto por una de las llamadas a
.BR opendir() ", " readdir() ", o " stat() .
Si
.I funcerr
devuelve no cero, o si
.B GLOB_ERR
está activado,
.B glob()
terminará justo tras la llamada a
.IR funcerr .
.PP
Tras un regreso con éxito de la función,
.I pglob->gl_pathc
contiene el número de nombres de caminos que han concordado y
.I 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
.BR NULL .
.PP
Es posible el llamar a
.B glob()
varias veces. En ese caso, la opción
.B GLOB_APPEND
tiene que estar activa en
.I flags
en la segunda llamada y posteriores.
.PP
Como extensión GNU, a
.I pglob->gl_flags
se le asignan las opciones especificadas, operadas mediante un
\fBO\fR-lógico con
.B GLOB_MAGCHAR
si se encontró cualquier meta-carácter.
.SH "VALOR DEVUELTO"
Tras una terminación con éxito,
.B glob()
devuelve cero.
Otras posibles devoluciones son:
.TP
.B GLOB_NOSPACE
si no tenemos bastante memoria,
.TP
.B GLOB_ABORT
para un error de lectura, y
.TP
.B GLOB_NOMATCH
si no se ha encontrado nada.
.SH "EJEMPLOS"
Un ejemplo del modo de empleo es el siguiente código, que simula la
orden 
.nl
.B ls -l *.c ../*.c
.nl
en el shell.
.nf
.in 10

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]);
.fi
.SH "CONFORME A"
POSIX.2
.SH "FALLOS"
La función
.B glob()
puede fallar debido a un error en las funciones subyacentes, como 
.BR malloc() " u " opendir() .
Éstas guardarán su código de error en
.IR errno .
.SH NOTA
Los elementos de estructura
.I gl_pathc
y
.I gl_offs
se declaran como
.B size_t
en glibc 2.1, como deberían de acuerdo a POSIX.2, pero se declaran como
.B int
en libc4, libc5 y glibc 2.0.
.SH "VÉASE TAMBIÉN"
.BR ls (1),
.BR sh (1),
.BR stat (2),
.BR exec (3),
.BR malloc (3),
.BR opendir (3),
.BR readdir (3),
.BR wordexp (3),