Provided by: manpages-pl-dev_4.18.1-1_all 
NAZWA
glob, globfree - znalezienie ścieżek odpowiadających wzorcowi, zwolnienie pamięć z glob()
BIBLIOTEKA
Standardowa biblioteka C (libc, -lc)
SKŁADNIA
#include <glob.h>
int glob(const char *restrict pattern, int flags,
int (*errfunc)(const char *epath, int eerrno),
glob_t *restrict 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
Don't allow backslash ('\') to be used as an escape character. Normally, a
backslash can be used to quote the following character, providing a mechanism to
turn off the special meaning metacharacters.
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
Carry out tilde expansion. If a tilde ('~') is the only character in the pattern,
or an initial tilde is followed immediately by a slash ('/'), then the home
directory of the caller is substituted for the tilde. If an initial tilde is
followed by a username (e.g., "~andrea/bin"), then the tilde and username are
substituted by the home directory of that user. If the username is invalid, or the
home directory cannot be determined, then no substitution is performed.
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() wywołuje te funkcje, stąd dla
przypomnienia użytkownikom używamy race:utent.
STANDARDY
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Ł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]);
ZOBACZ TAKŻE
ls(1), sh(1), stat(2), exec(3), fnmatch(3), malloc(3), opendir(3), readdir(3), wordexp(3),
glob(7)
TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są: Przemek Borys
<pborys@dione.ids.pl>, Andrzej Krzysztofowicz <ankry@green.mf.pg.gda.pl>, Robert Luberda
<robert@debian.org> i Michał Kułach <michal.kulach@gmail.com>
Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji
można uzyskać zapoznając się z GNU General Public License w wersji 3
⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ lub nowszej. Nie przyjmuje się ŻADNEJ
ODPOWIEDZIALNOŚCI.
Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej
⟨manpages-pl-list@lists.sourceforge.net⟩.