glob

GLOB(3)                 PodrÄcznik programisty Linuksa                 GLOB(3)



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.



GNU                               2015-04-19                           GLOB(3)