Provided by: manpages-pl-dev_0.6-2_all bug

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.

ZGODNE Z

       POSIX.2, POSIX.1-2001.

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  3.71  projektu Linux man-pages. Opis
       projektu, informacje dotyczące zgłaszania błędów, oraz najnowszą  wersję  oryginału  można
       znaleźć pod adresem http://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> i Robert Luberda
       <robert@debian.org>.

       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ą    3.71
       oryginału.