Provided by: manpages-pl-dev_0.7-1_all bug

NAZWA

       strtok, strtok_r - wydzielanie słów z łańcuchów

SKŁADNIA

       #include <string.h>

       char *strtok(char *str, const char *delim);

       char *strtok_r(char *str, const char *delim, char **saveptr);

   Wymagane ustawienia makr biblioteki glibc (patrz feature_test_macros(7)):

       strtok_r(): _POSIX_C_SOURCE
           || /* Glibc w wersji <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE

OPIS

       Funkcja  strtok()  dzieli  łańcuch  na  sekwencję zera  lub  więcej  niepustych słów. Przy
       pierwszym wywołaniu funkcji strtok(), łańcuch do przetworzenia powinien być podany w  str.
       W każdym kolejnym wywołaniu, które powinno przetworzyć ten sam łańcuch, str musi być NULL.

       Argument  delim  określa  zbiór  bajtów  służących  do  oddzielania  słów  w przetwarzanym
       łańcuchu. Program wywołujący może podawać różne argumenty delim  w  kolejnych  wywołaniach
       przetwarzających ten sam łańcuch znaków.

       Każde  wywołanie  funkcji  strtok()  zwraca  wskaźnik do zakończonego znakiem null łańcuch
       zawierającego następne słowo. Łańcuch ten nie  zawiera  znaku  separatora.  Jeśli  nie  ma
       więcej słów, to strtok() zwraca NULL.

       Sekwencja  wywołań  strtok()  działająca na tym samym łańcuchu znaków przechowuje wskaźnik
       określający punkt, od którego należy szukać kolejnego słowa. Pierwsze  wywołanie  strtok()
       ustawia  ten  wskaźnik  na pierwszy bajt łańcucha. Początek kolejnego słowa jest określany
       przez szukanie kolejnego bajtu niebędącego ogranicznikiem w str. Jeśli taki bajt  zostanie
       znaleziony,  to  jest  uważany za początek kolejnego słowa. Jeśli nie ma takiego bajtu, to
       nie ma więcej słów  i strtok() zwraca NULL (Łańcuch, który jest  pusty,  lub  taki,  który
       zawiera  tylko  znaki ogranicznika, spowoduje, że pierwsze wywołanie strtok() także zwróci
       NULL).

       Koniec każdego słowa jest określany przez wyszukanie albo  następnego  bajtu  ogranicznika
       albo napotkanie kończącego bajtu null ('\0'). Jeśli zostanie znaleziony bajt ogranicznika,
       to jest nadpisywany znakiem null, tak aby zakończyć bieżące słowo,  a  strtok()  zachowuje
       wskaźnik  do  kolejnego  bajtu; wskaźnik ten będzie użyty jako punkt startowy wyszukiwania
       kolejnego słowa. W takim przypadku  strtok()  zwraca  wskaźnik  do  początku  znalezionego
       słowa.

       Z  powyższego  opisu  wynika,  że sekwencja dwóch lub więcej następujących po sobie bajtów
       ogranicznika w  przetwarzanym  łańcuchu  jest  uważana  za  pojedynczy  ogranicznik  i  że
       ograniczniki  na  początku  i  końcu  łańcucha  są  zawsze ignorowane. Innymi słowy: słowa
       zwracane przez strtok() są  zawsze  niepustymi  łańcuchami  znaków.  Dlatego  na  przykład
       kolejne  wywołanie strtok() dla łańcucha "aaa;;bbb," z łańcuchem ograniczników ";," zwrócą
       słowa "aaa" oraz "bbb", a następnie zwrócą wskaźnik null.

       Funkcja strtok_r() jest wielowątkową wersją  strtok(). Argument saveptr  jest  wskaźnikiem
       do  zmiennej  typu  char *,  używanej wewnętrznie przez strtok_r() do zachowania kontekstu
       pomiędzy kolejnymi wywołaniami przetwarzającymi ten sam łańcuch znaków.

       Podczas pierwszego wywołania strtok_r() argument str  powinien  wskazywać  na  łańcuch  do
       przetworzenia, a wartość saveptr jest ignorowana. W kolejnych wywołaniach str powinien być
       równy NULL, a saveptr nie powinien być zmieniony od poprzedniego wywołania.

       Różne łańcuchy znaków mogą być przetwarzane równocześnie  przy  użyciu  sekwencji  wywołań
       strtok_r(), różniących się argumentami saveptr.

WARTOŚĆ ZWRACANA

       Funkcje strtok() i strtok_r() zwracają wskaźnik do następnego słowa lub NULL, jeśli nie ma
       już więcej słów.

ATRYBUTY

       Informacje  o  pojęciach  używanych  w  tym  rozdziale   można   znaleźć   w   podręczniku
       attributes(7).

       ┌───────────┬────────────────────────┬───────────────────────┐
       │InterfejsAtrybutWartość               │
       ├───────────┼────────────────────────┼───────────────────────┤
       │strtok()   │ Bezpieczeństwo wątkowe │ MT-Unsafe race:strtok │
       ├───────────┼────────────────────────┼───────────────────────┤
       │strtok_r() │ Bezpieczeństwo wątkowe │ MT-Safe               │
       └───────────┴────────────────────────┴───────────────────────┘

ZGODNE Z

       strtok()
              POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD.

       strtok_r()
              POSIX.1-2001, POSIX.1-2008.

BŁĘDY IMPLEMENTACJI

       Nigdy nie należy używać tych funkcji. Jeśli jednak zostaną użyte, to należy zauważyć, że:

       * Funkcje te modyfikują swój pierwszy argument.

       * Funkcje ta nie mogą być stosowana z ciągami stałymi.

       * Tożsamość bajtu separatora jest tracona.

       * Funkcja  strtok()   korzysta  ze  statycznego  bufora,  więc  nie  jest przystosowana do
         wielowątkowości. Jeśli ma to znaczenie, należy używać strtok_r().

PRZYKŁAD

       Poniższy program używa zagnieżdżonych pętli, stosując strtok_r() do  podzielenia  łańcucha
       na  dwupoziomową  hierarchię  słów.  Pierwszy  argument  linii  poleceń określa łańcuch do
       przetworzenia. Drugi argument podaje bajty ograniczające używane do dzielenia łańcucha  na
       "główne"  słowa.  Trzeci  argument  określa  bajty służące do dzielenia "głównych" słów na
       podsłowa.

       Przykładowe wyjście programu jest następujące:

           $ ./a.out 'a/bbb///cc;xxx:yyy:' ':;' '/'
           1: a/bbb///cc
                    --> a
                    --> bbb
                    --> cc
           2: xxx
                    --> xxx
           3: yyy
                    --> yyy

   Żródło programu

       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>

       int
       main(int argc, char *argv[])
       {
           char *str1, *str2, *token, *subtoken;
           char *saveptr1, *saveptr2;
           int j;

           if (argc != 4) {
               fprintf(stderr, "Użycie: %s string delim subdelim\n",
                       argv[0]);
               exit(EXIT_FAILURE);
           }

           for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
               token = strtok_r(str1, argv[2], &saveptr1);
               if (token == NULL)
                   break;
               printf("%d: %s\n", j, token);

               for (str2 = token; ; str2 = NULL) {
                   subtoken = strtok_r(str2, argv[3], &saveptr2);
                   if (subtoken == NULL)
                       break;
                   printf(" --> %s\n", subtoken);
               }
           }

           exit(EXIT_SUCCESS);
       }

       Inny przykładowy program używający strtok() można znaleźć w getaddrinfo_a(3).

ZOBACZ TAKŻE

       index(3), memchr(3), rindex(3), strchr(3), string(3),  strpbrk(3),  strsep(3),  strspn(3),
       strstr(3), wcstok(3)

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ą: Paweł Wilk (PTM)
       <siewca@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.