Provided by:
manpages-pl-dev_20060617-1_all 
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)