GLOB(3)

NOME
glob, globfree - encontra nomes de arquivo que combinam com um padrão, libera memória de glob()

SINÓPSE
#include <glob.h>

int glob(const char *pattern, int flags,
         int errfunc(const char * epath, int eerrno),
         glob_t *pglob);
void globfree(glob_t *pglob);

DESCRIÇÃO
A função glob() busca por todos os nomes de arquivo combinando com pattern de acordo com as regras usadas pelo shell (veja glob(7)). Nenhuma expansão til ou substituição de parâmetro é feita; se é isso que você procura, use wordexp(3).

A função globfree() libera o espaço de armazenamento alocado dinamicamente por uma chamada feita previamente a glob().

Os resultados de uma chamada a glob() são guardadas na estrutura apontada por pglob, a qual é um glob_t que está declarado em <glob.h> e inclui os seguintes elementos definidos pelo POSIX.2 (mais pode estar presente como uma extensão):

typedef struct
{
    size_t gl_pathc;    /* Contagem dos paths que combinam com o padrão até o momento */
    char **gl_pathv;    /* Lista de nomes de arquivo que combinam */
    size_t gl_offs;     /* Espaços para reservar em `gl_pathv'.  */
} glob_t;

Os resultados são guardados em espaço de armazenamento alocado dinamicamente.

O parâmetro flags é feito de OR bit-a-bit de zero ou mais das seguintes constantes simbólicas, que modificam o comportamento de glob():

GLOB_ERR
    significa retornar quando de um erro de leitura (porque um diretório não possui permissão de leitura, por exemplo),

GLOB_MARK
    significa anexar uma barra a cada caminho que corresponde a um diretório,

GLOB_NOSORT
    significa não ordenar os nomes de arquivo retornados (eles o são por padrão),

GLOB_DOOFFS
    significa que os espaços pglob->gl_offs serão reservados no início da lista de strings em pglob->pathv,

GLOB_NOCHECK
    significa que, se nenhuma padrão casar, retornar o padrão original,

GLOB_APPEND
    signifca anexar aos resultados de uma chamada anterior. Não ligue este flag na primeira invocação de glob().

GLOB_NOESCAPE
    significa que os meta caracteres não podem ser deilmitados por contra-barras.

Os flags podem também incluir alguns dos seguintes, que são extensões GNU e não são definidos pelo POSIX.2:

GLOB_PERIOD
    significa que um ponto no início pode ser casado com metacaracteres,

GLOB_ALTDIRFUNC
    significa que funções alternativas pglob->gl_closedir, pglob->gl_readdir, pglob->gl_opendir, pglob->gl_lstat, e pglob->gl_stat são usadas para acessar o sistema de arquivos em vez das funções normais de biblioteca,

GLOB_BRACE
    significa que expressões chaves {a,b} ao estilo do csh(1) são expandidas,

GLOB_NOMAGIC
    significa que o padrão é retornado se o mesmo não contém metacaracateres,

GLOB_TILDE
    significa que a expansão til é realizada, e

GLOB_ONLYDIR
    significa que apenas os diretórios são combinados.

Se errfunc nao é NULL, ela será chamada no caso de um erro com os argumentos epath, um ponteiro para o caminho que falhou, e eerrno, o valor de errno como retornado de uma de suas chamadas feitas a opendir(), readdir(), ou stat(). Se errfunc retornar não-zero, ou se GLOB_ERR está ligado, glob() vai terminar depois da chamada a errfunc.

No retorno com sucesso, pglob->gl_pathc contém o número de nomes de arquivo casados e pglob->gl_pathv um ponteiro para a lista de nomes de arquivos. O primeiro ponteiro depois do último nome de arquivo é NULL.

É possível chamar glob() várias vezes. Neste caso, o flag GLOB_APPEND deve estar ligado em flags na segunda e demais invocações.

Como uma extensão GNU, pglob->gl_flags é ajustada para os flags especificados, são combinadas com uma operação ou com GLOB_MAGCHAR se quaisquer metacaracteres foram encontrados.

VALORES RETORNADOS
Ao completar com sucesso, glob() retorna zero. Outros possíveis retornos são:

GLOB_NOSPACE
    para falta memória,

GLOB_ABORTED
    para um erro de leitura, e

GLOB_NOMATCH
    para nenhum nome encontrado.

EXEMPLOS
Um exemplo de uso é o seguinte código, o qual simula a digitação de ls -l *.c ../*.c no 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]);

DE ACORDO COM
POSIX.2

PROBLEMAS
A função glob() pode falhar devido a falha de chamadas a funções subjacentes, tais como malloc() ou opendir(). Estas irão gravar seus códigos de erro em errno.

NOTAS
Os elementos da estrutura gl_pathc e gl_offs são declarados como size_t na glibc 2.1, como elas deveriam de acordo com o POSIX.2, mas são declarados como int nas libc4, libc5 e glibc 2.0.

VEJA TAMBÉM
ls(1), sh(1), stat(2), exec(3), malloc(3), opendir(3), readdir(3), wordexp(3), glob(7).

TRADUZIDO POR LDP-BR em 28/05/2001.

  Tradução:
Felipe M Pereira <Felipe.Pereira@ic.unicamp.br>

  Revisão.:
André Luiz Fassone <lonely_wolf@ig.com.br>