GLOB(3)

NAZWA
glob, globfree - znalezienie ścieżek odpowiadających wzorcowi, zwolnienie pamięć z glob()

SKŁADNIA
#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);

OPIS
Funkcja glob() przeszukuje wszystkie ścieżki odpowiadające wzorcowi pattern, stosując przy tym reguły takie, jakich użyłaby powłoka (zobacz glob(7)). Nie jest dokonywane rozwinięcie tyldy ani podstawienie parametrów. Jeśli są one potrzebne, to należy użyć wordexp(3).

Funkcja globfree() zwalnia obszar pamięci zaalokowany dynamicznie przez wcześniejsze wywołanie funkcji glob().

W wyniku wywołania glob() tworzona jest struktura, na którą wskazuje pglob, będący typu glob_t zadeklarowanego w <glob.h> i zawierającego następujące elementy zdefiniowane przez POSIX.2 (mogą też występować dodatkowe, ale jako rozszerzenie):

typedef struct
{
    size_t gl_pathc;    /* Liczba odpowiadających dotąd ścieżek  */
    char **gl_pathv;    /* Lista odpowiadających ścieżek.  */
    size_t gl_offs;     /* Sloty do rezerwowania w `gl_pathv'.  */
} glob_t;

Wyniki są zachowywane w dynamicznie przydzielanym obszarze pamięci.

Parametr flags tworzy bitowe OR zera lub więcej następujących symboli stałych modyfikujących zachowanie glob():

GLOB_ERR
    oznacza, że należy powrócić po błędzie odczytu (np. gdy katalog nie ma praw odczytu),

GLOB_MARK
    oznacza dodawanie ukośnika do każdej ścieżki, która odpowiada katalogowi,

GLOB_NOSORT
    oznacza, że zwracane ścieżki nie mają być sortowane (domyślnie są),

GLOB_DOOFFS
    oznacza, że sloty pglob->gl_offs będą rezerwowane na początku listy napisów w pglob->pathv,

GLOB_NOCHECK
    oznacza, że jeśli żaden wzorzec nie odpowiada, zwracany jest wzorzec oryginalny,

GLOB_APPEND
    oznacza, że należy doklejać wyniki do wyników poprzedniego wywołania. Nie należy ustawiać tej flagi przy pierwszym wywołaniu glob().

GLOB_NOESCAPE
    oznacza, że metaznaki nie mogą być cytowane odwrotnymi ukośnikami,

Parametr flags może również zawierać następujące znaczniki, będące rozszerzeniami GNU nie definiowanymi przez POSIX.2:

GLOB_PERIOD
    oznacza, że początkowa kropka może być dopasowana metaznakiem,

GLOB_ALTDIRFUNC oznacza, że przy dostępie do systemy plików zamiast zwykłych funkcji bibliotecznych używane są funkcje alternatywne pglob->gl_closedir, pglob->gl_readdir, pglob->gl_opendir, pglob->gl_lstati pglob->gl_stat,

GLOB_BRACE
    oznacza, że rozwijane są wyrażenia nawiasowe {a,b} w stylu csh(1),

GLOB_NOMAGIC
    oznacza, że wzorzec jest zwracany, gdy nie zawiera metaznaków,

GLOB_TILDE
    oznacza, że przeprowadzane rozwinięcie tyldy, a

GLOB_ONLYDIR
    oznacza, że dopasowywane są wyłącznie katalogi.

Jeśli errfunc nie jest równe NULL, to w wypadku błędu będzie ono wywołane z argumentami epath, czyli wskaźnikiem do ścieżki, na której coś się nie powiodło i z eerrno, przechowującym wartość errno, zwróconą przez wywołanie do opendir(), readdir() lub stat(). Jeśli errfunc zwraca wartość niezerową lub jeśli ustawiony jest znacznik GLOB_ERR, glob() zakończy działanie po wywołaniu funkcji errfunc.

Po pomyślnym zakończeniu, pglob->gl_pathc zawiera liczbę pasujących ścieżek, a pglob->gl_pathv wskaźnik do listy trafionych ścieżek. Pierwszy wskaźnik za ostatnią ścieżką ma wartość NULL.

Możliwe jest wywoływanie glob() wielokrotnie. W takim wypadku, należy w następnych wywołaniach ustawić w flags znacznik GLOB_APPEND.

Jako rozszerzenie GNU, pglob->gl_flags jest ustawiane jako or podanych znaczników i GLOB_MAGCHAR, gdy występują metaznaki.

WARTOŚĆ ZWRACANA
Po pomyślnym zakończeniu glob() zwraca zero. Inne możliwe wartości to:

GLOB_NOSPACE
    przy braku pamięci,

GLOB_ABORTED
    przy błędzie odczytu i

GLOB_NOMATCH
    gdy niczego nie dopasowano.

PRZYKŁADY
Jednym z przykładów użycia jest następujący kod, emulujący wpisanie ls -l *.c ../*.c w powłoce.
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]);

ZGODNE Z
POSIX.2

BŁĘDY
Funkcja glob() może zawieść z powodu błędu wywołanych przez nią funkcji, takich jak malloc() czy opendir(). Wywołania te zapiszą kod błędu w errno.

UWAGI
Elementy gl_pathc i gl_offs struktury są w glibc 2.1 zadeklarowane jako size_t, jak powinno być zgodnie z POSIX.2, ale są zadeklarowane jako int w libc4, libc5 i glibc 2.0.

ZOBACZ TAKŻE
ls(1), sh(1), stat(2), exec(3), malloc(3), opendir(3), readdir(3), wordexp(3), glob(7)