Provided by: manpages-pl-dev_0.7-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. Struktura jest typu glob_t
(deklarowany w <glob.h>) i zawiera następujące elementy zdefiniowane przez POSIX.2 (mogą też występować
dodatkowe 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.
Argument flags jest bitowym OR-em zera lub więcej następujących symboli stałych modyfikujących zachowanie
glob():
GLOB_ERR
Powraca po napotkaniu błędu odczytu (na przykład, jeśli nie ma praw do odczytu katalogu).
Domyślnie glob() kontynuuje działanie mimo błędów, odczytując wszystkie katalogi, do których ma
uprawnienia.
GLOB_MARK
Dodaje ukośnik do każdej ścieżki, która odpowiada katalogowi.
GLOB_NOSORT
Nie sortuje zwracanych nazw ścieżek. Jedynym powodem użycia tej opcji może być zaoszczędzenie
czasu przetwarzania. Domyślnie zwracane nazwy ścieżek są sortowane.
GLOB_DOOFFS
Rezerwuje sloty pglob->gl_offs na początku listy napisów w pglob->pathv. Zarezerwowane sloty mogą
zawierać wskaźniki null.
GLOB_NOCHECK
Jeśli żaden wzorzec nie zostanie dopasowany, to zwracany jest oryginalny wzorzec. Domyślnie glob()
w razie braku dopasowań zwraca GLOB_NOMATCH.
GLOB_APPEND
Doklejać wyniki bieżącego wywołania do listy wyników poprzedniego wywołania. Nie należy ustawiać
tej flagi przy pierwszym wywołaniu glob().
GLOB_NOESCAPE
Nie pozwala na użycie znaku odwrotnego ukośnika ("\") jako znaku cytowania. Domyślnie odwrotny
ukośnik cytuje następujący po nim znak, dostarczając mechanizmu wyłączania specjalnego znaczenia
metaznaków.
Parametr flags może również zawierać następujące znaczniki, będące rozszerzeniami GNU niedefiniowanymi
przez POSIX.2:
GLOB_PERIOD
Pozwala na to, by początkowa kropka była dopasowywana przez metaznaki. Domyślnie metaznaki nie są
dopasowywane do początkowej kropki.
GLOB_ALTDIRFUNC
Zamiast zwykłych funkcji bibliotecznych używa alternatywnych funkcji pglob->gl_closedir,
pglob->gl_readdir, pglob->gl_opendir, pglob->gl_lstat oraz pglob->gl_stat do dostępu do systemu
plików.
GLOB_BRACE
Rozwija wyrażenia nawiasowe stylu csh(1) w formacie {a,b}. Wyrażenia nawiasowe mogą być
zagnieżdżane. Dlatego na przykład podanie wzoraca "{foo/{,cat,dog},bar}" zwróci takie same wyniki
jak czterokrotne wywołanie glob() z następującymi argumentami: "foo/", "foo/cat", "foo/dog" oraz
"bar".
GLOB_NOMAGIC
Jeśli wzorzec nie zawiera metaznaków, to powinien być zwrócony jako jedyne pasujące słowo nawet
wtedy, gdy nie ma plików o takiej nazwie.
GLOB_TILDE
Przeprowadza ekspansję tyldy. Jeśli tylda ("~") jest jedynym znakiem we wzorcu lub zaraz po
początkowym znaku tyldy występuje ukośnik ("/"), to tylda jest zastępowana przez nazwę katalogu
domowego użytkownika wywołującego glob(). Jeśli po początkowej tyldzie występuje nazwa użytkownika
(np. "~andrea/bin"), to tylda i nazwa użytkownika są zastępowane przez katalog domowy tego
użytkownika. Jeśli nazwa użytkownika jest niepoprawna lub katalog domowy nie może być określony,
to żadne zastępowanie nie jest przeprowadzane.
GLOB_TILDE_CHECK
Zachowuje się podobnie do GLOB_TILDE, z tą różnicą że jeśli nazwa użytkownika jest niepoprawna lub
jeśli nie można określić katalogu domowego użytkownika, to glob() zamiast używać wzorca jako nazwy
zwróci GLOB_NOMATCH, wskazując, że wystąpił błąd.
GLOB_ONLYDIR
Jest to wskazówka dla funkcji glob(), mówiąca, że funkcja wywołująca jest zainteresowana tylko
katalogami pasującymi do wzorca. Jeśli implementacja może w łatwy sposób określić informację o
typie pliku, to pliki niebędące katalogami nie są zwracane. Jednakże funkcja wywołująca musi
sprawdzić, że zwrócone pliki są katalogami. (Celem tej flagi jest poprawienie wydajności w
przypadku, gdy funkcja wywołująca jest zainteresowana tylko katalogami).
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(3), readdir(3) lub stat(2). Jeśli errfunc zwraca wartość niezerową
lub jeśli ustawiony jest znacznik GLOB_ERR, to 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 wskaźników do dopasowanych ścieżek. Lista ta jest zakończona wskaźnikiem 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.
ATRYBUTY
Informacje o pojęciach używanych w tym rozdziale można znaleźć w podręczniku attributes(7).
┌───────────┬────────────────────────┬──────────────────────────┐
│Interfejs │ Atrybut │ Wartość │
├───────────┼────────────────────────┼──────────────────────────┤
│glob() │ Bezpieczeństwo wątkowe │ MT-Unsafe race:utent env │
│ │ │ sig:ALRM timer locale │
├───────────┼────────────────────────┼──────────────────────────┤
│globfree() │ Bezpieczeństwo wątkowe │ MT-Safe │
└───────────┴────────────────────────┴──────────────────────────┘
W powyższej tabeli utent w race:utent oznacza, że jeśli któraś z funkcji setutent(3), getutent(3) lub
endutent(3) jest używana równolegle w różnych wątkach programu, może nastąpić sytuacja wyścigu danych.
Ponieważ glob(3) wywołuje te funkcje, stąd dla przypomnienia użytkownikom używamy race:utent.
ZGODNE Z
POSIX.1-2001, POSIX.1-2008, POSIX.2.
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 glibc 2.0.
BŁĘDY
Funkcja glob() może zawieść z powodu błędu wywołanych przez nią funkcji, takich jak malloc(3) czy
opendir(3). Wywołania te zapiszą kod błędu w errno.
PRZYKŁAD
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]);
ZOBACZ TAKŻE
ls(1), sh(1), stat(2), exec(3), fnmatch(3), malloc(3), opendir(3), readdir(3), wordexp(3), glob(7)
O STRONIE
Angielska wersja tej strony pochodzi z wydania 4.07 projektu Linux man-pages. Opis projektu, informacje
dotyczące zgłaszania błędów oraz najnowszą wersję oryginału można znaleźć pod adresem
https://www.kernel.org/doc/man-pages/.
TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika man są: Przemek Borys (PTM)
<pborys@dione.ids.pl>, Andrzej Krzysztofowicz (PTM) <ankry@mif.pg.gda.pl>, Robert Luberda
<robert@debian.org> i Michał Kułach <michal.kulach@gmail.com>.
Polskie tłumaczenie jest częścią projektu manpages-pl; uwagi, pomoc, zgłaszanie błędów na stronie
http://sourceforge.net/projects/manpages-pl/. Jest zgodne z wersją 4.07 oryginału.