glob

Autres langues

Langue: pl

Autres versions - même langue

Version: 1999-09-12 (fedora - 25/11/07)

Autres sections - même nom

Section: 3 (Bibliothèques de fonctions)

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)