glob(3) Library Functions Manual glob(3) NAZWA glob, globfree - znalezienie sciezek odpowiadajacych wzorcowi, zwolnienie pamiec z glob() BIBLIOTEKA Standardowa biblioteka C (libc, -lc) SKLADNIA #include 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 sciezki odpowiadajace wzorcowi pattern, stosujac przy tym reguly takie, jakich uzylaby powloka (zobacz glob(7)). Nie jest dokonywane rozwiniecie tyldy ani podstawienie parametrow. Jesli sa one potrzebne, to nalezy uzyc wordexp(3). Funkcja globfree() zwalnia obszar pamieci zaalokowany dynamicznie przez wczesniejsze wywolanie funkcji glob(). W wyniku wywolania glob() tworzona jest struktura, na ktora wskazuje pglob. Struktura jest typu glob_t (deklarowany w ) i zawiera nastepujace elementy zdefiniowane przez POSIX.2 (moga tez wystepowac dodatkowe jako rozszerzenie): typedef struct { size_t gl_pathc; /* Liczba odpowiadajacych dotad sciezek. */ char **gl_pathv; /* Lista odpowiadajacych sciezek */ size_t gl_offs; /* Sloty do rezerwowania w gl_pathv. */ } glob_t; Wyniki sa zachowywane w dynamicznie przydzielanym obszarze pamieci. Argument flags jest bitowym OR-em zera lub wiecej nastepujacych symboli stalych modyfikujacych zachowanie glob(): GLOB_ERR Powraca po napotkaniu bledu odczytu (na przyklad, jesli nie ma praw do odczytu katalogu). Domyslnie glob() kontynuuje dzialanie mimo bledow, odczytujac wszystkie katalogi, do ktorych ma uprawnienia. GLOB_MARK Dodaje ukosnik do kazdej sciezki, ktora odpowiada katalogowi. GLOB_NOSORT Nie sortuje zwracanych nazw sciezek. Jedynym powodem uzycia tej opcji moze byc zaoszczedzenie czasu przetwarzania. Domyslnie zwracane nazwy sciezek sa sortowane. GLOB_DOOFFS Rezerwuje sloty pglob->gl_offs na poczatku listy napisow w pglob->pathv. Zarezerwowane sloty moga zawierac wskazniki null. GLOB_NOCHECK Jesli zaden wzorzec nie zostanie dopasowany, to zwracany jest oryginalny wzorzec. Domyslnie glob() w razie braku dopasowan zwraca GLOB_NOMATCH. GLOB_APPEND Doklejac wyniki biezacego wywolania do listy wynikow poprzedniego wywolania. Nie nalezy ustawiac tej flagi przy pierwszym wywolaniu 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 moze rowniez zawierac nastepujace znaczniki, bedace rozszerzeniami GNU niedefiniowanymi przez POSIX.2: GLOB_PERIOD Pozwala na to, by poczatkowa kropka byla dopasowywana przez metaznaki. Domyslnie metaznaki nie sa dopasowywane do poczatkowej kropki. GLOB_ALTDIRFUNC Zamiast zwyklych funkcji bibliotecznych uzywa alternatywnych funkcji pglob->gl_closedir, pglob->gl_readdir, pglob->gl_opendir, pglob->gl_lstat oraz pglob->gl_stat do dostepu do systemu plikow. GLOB_BRACE Rozwija wyrazenia nawiasowe stylu csh(1) w formacie {a,b}. Wyrazenia nawiasowe moga byc zagniezdzane. Dlatego na przyklad podanie wzoraca "{foo/{,cat,dog},bar}" zwroci takie same wyniki jak czterokrotne wywolanie glob() z nastepujacymi argumentami: "foo/", "foo/cat", "foo/dog" oraz "bar". GLOB_NOMAGIC Jesli wzorzec nie zawiera metaznakow, to powinien byc zwrocony jako jedyne pasujace slowo nawet wtedy, gdy nie ma plikow 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 sie podobnie do GLOB_TILDE, z ta roznica ze jesli nazwa uzytkownika jest niepoprawna lub jesli nie mozna okreslic katalogu domowego uzytkownika, to glob() zamiast uzywac wzorca jako nazwy zwroci GLOB_NOMATCH, wskazujac, ze wystapil blad. GLOB_ONLYDIR Jest to wskazowka dla funkcji glob(), mowiaca, ze funkcja wywolujaca jest zainteresowana tylko katalogami pasujacymi do wzorca. Jesli implementacja moze w latwy sposob okreslic informacje o typie pliku, to pliki niebedace katalogami nie sa zwracane. Jednakze funkcja wywolujaca musi sprawdzic, ze zwrocone pliki sa katalogami. (Celem tej flagi jest poprawienie wydajnosci w przypadku, gdy funkcja wywolujaca jest zainteresowana tylko katalogami). Jesli errfunc nie jest rowne NULL, to w wypadku bledu bedzie ono wywolane z argumentami epath, czyli wskaznikiem do sciezki, na ktorej cos sie nie powiodlo, i z eerrno, przechowujacym wartosc errno, zwrocona przez wywolanie do opendir(3), readdir(3) lub stat(2). Jesli errfunc zwraca wartosc niezerowa lub jesli ustawiony jest znacznik GLOB_ERR, to glob() zakonczy dzialanie po wywolaniu funkcji errfunc. Po pomyslnym zakonczeniu, pglob->gl_pathc zawiera liczbe pasujacych sciezek, a pglob->gl_pathv wskaznik do listy wskaznikow do dopasowanych sciezek. Lista ta jest zakonczona wskaznikiem null. Mozliwe jest wywolywanie glob() wielokrotnie. W takim wypadku nalezy w nastepnych wywolaniach ustawic w flags znacznik GLOB_APPEND. Jako rozszerzenie GNU, pglob->gl_flags jest ustawiane jako or podanych znacznikow i GLOB_MAGCHAR, gdy wystepuja metaznaki. WARTOSC ZWRACANA Po pomyslnym zakonczeniu glob() zwraca zero. Inne mozliwe wartosci to: GLOB_NOSPACE przy braku pamieci, GLOB_ABORTED przy bledzie odczytu i GLOB_NOMATCH gdy niczego nie dopasowano. ATRYBUTY Informacje o pojeciach uzywanych w tym rozdziale mozna znalezc w podreczniku attributes(7). +-----------+--------------------------+-------------------------------+ |Interfejs | Atrybut | Wartosc | +-----------+--------------------------+-------------------------------+ |glob() | Bezpieczenstwo watkowe | MT-Unsafe race:utent env | | | | sig:ALRM timer locale | +-----------+--------------------------+-------------------------------+ |globfree() | Bezpieczenstwo watkowe | MT-bezpieczne | +-----------+--------------------------+-------------------------------+ W powyzszej tabeli utent w race:utent oznacza, ze jesli ktoras z funkcji setutent(3), getutent(3) lub endutent(3) jest uzywana rownolegle w roznych watkach programu, moze nastapic sytuacja wyscigu danych. Poniewaz glob() wywoluje te funkcje, stad dla przypomnienia uzytkownikom uzywamy race:utent. STANDARDY POSIX.1-2008. HISTORIA POSIX.1-2001, POSIX.2. UWAGI Elementy gl_pathc i gl_offs struktury sa w glibc 2.1 zadeklarowane jako size_t, jak powinno byc zgodnie z POSIX.2, ale sa zadeklarowane jako int w glibc 2.0. USTERKI Funkcja glob() moze zawiesc z powodu bledu wywolanych przez nia funkcji, takich jak malloc(3) czy opendir(3). Wywolania te zapisza kod bledu w errno. PRZYKLADY Jednym z przykladow uzycia jest nastepujacy kod, emulujacy wpisanie ls -l *.c ../*.c w powloce: 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 TAKZE ls(1), sh(1), stat(2), exec(3), fnmatch(3), malloc(3), opendir(3), readdir(3), wordexp(3), glob(7) TLUMACZENIE Autorami polskiego tlumaczenia niniejszej strony podrecznika sa: Przemek Borys , Andrzej Krzysztofowicz , Robert Luberda i Michal Kulach Niniejsze tlumaczenie jest wolna dokumentacja. Blizsze informacje o warunkach licencji mozna uzyskac zapoznajac sie z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje sie ZADNEJ ODPOWIEDZIALNOSCI. Bledy w tlumaczeniu strony podrecznika prosimy zglaszac na adres listy dyskusyjnej . Linux man-pages 6.06 31 pazdziernika 2023 r. glob(3)