Provided by: manpages-pl-dev_20060617-1_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,  będący  typu  glob_t zadeklarowanego w <glob.h> i zawierającego
       następujące elementy zdefiniowane przez POSIX.2  (mogą  też  występować
       dodatkowe, ale 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.

       Parametr  flags  tworzy bitowe OR zera lub więcej następujących symboli
       stałych modyfikujących zachowanie glob():

       GLOB_ERR
              oznacza, że należy powrócić po błędzie odczytu (np. gdy  katalog
              nie ma praw odczytu),

       GLOB_MARK
              oznacza  dodawanie  ukośnika  do każdej ścieżki, która odpowiada
              katalogowi,

       GLOB_NOSORT
              oznacza, że zwracane ścieżki nie mają być  sortowane  (domyślnie
              są),

       GLOB_DOOFFS
              oznacza,  że  sloty  pglob->gl_offs będą rezerwowane na początku
              listy napisów w pglob->pathv,

       GLOB_NOCHECK
              oznacza, że jeśli żaden wzorzec  nie  odpowiada,  zwracany  jest
              wzorzec oryginalny,

       GLOB_APPEND
              oznacza,  że  należy  doklejać  wyniki  do  wyników poprzedniego
              wywołania.  Nie  należy  ustawiać  tej  flagi   przy   pierwszym
              wywołaniu glob().

       GLOB_NOESCAPE
              oznacza,   że   metaznaki   nie  mogą  być  cytowane  odwrotnymi
              ukośnikami,

       Parametr flags może  również  zawierać  następujące  znaczniki,  będące
       rozszerzeniami GNU nie definiowanymi przez POSIX.2:

       GLOB_PERIOD
              oznacza, że początkowa kropka może być dopasowana metaznakiem,

       GLOB_ALTDIRFUNC  oznacza,  że  przy  dostępie do systemy plików zamiast
       zwykłych  funkcji  bibliotecznych  używane  są   funkcje   alternatywne
       pglob->gl_closedir,        pglob->gl_readdir,        pglob->gl_opendir,
       pglob->gl_lstati pglob->gl_stat,

       GLOB_BRACE
              oznacza, że rozwijane  są  wyrażenia  nawiasowe  {a,b}  w  stylu
              csh(1),

       GLOB_NOMAGIC
              oznacza, że wzorzec jest zwracany, gdy nie zawiera metaznaków,

       GLOB_TILDE
              oznacza, że przeprowadzane rozwinięcie tyldy, a

       GLOB_ONLYDIR
              oznacza, że dopasowywane są wyłącznie katalogi.

       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(),  readdir()  lub  stat().   Jeśli  errfunc
       zwraca  wartość  niezerową  lub jeśli ustawiony jest znacznik GLOB_ERR,
       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  trafionych  ścieżek.
       Pierwszy wskaźnik za ostatnią ścieżką ma wartość 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.

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]);

ZGODNE Z

       POSIX.2

BŁĘDY

       Funkcja glob()  może  zawieść  z  powodu  błędu  wywołanych  przez  nią
       funkcji,  takich  jak malloc() czy opendir().  Wywołania te zapiszą kod
       błędu w errno.

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 libc4, libc5 i glibc 2.0.

ZOBACZ TAKŻE

       ls(1), sh(1),  stat(2),  exec(3),  malloc(3),  opendir(3),  readdir(3),
       wordexp(3), glob(7)