strtok(3) Library Functions Manual strtok(3) NAZWA strtok, strtok_r - wydziela slowa z lancuchow BIBLIOTEKA Standardowa biblioteka C (libc, -lc) SKLADNIA #include char *strtok(char *_Nullable restrict str, const char *restrict delim); char *strtok_r(char *_Nullable restrict str, const char *restrict delim, char **restrict 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 lancuch na sekwencje zera lub wiecej niepustych slow. Przy pierwszym wywolaniu funkcji strtok(), lancuch do przetworzenia powinien byc podany w str. W kazdym kolejnym wywolaniu, ktore powinno przetworzyc ten sam lancuch, str musi byc NULL. Argument delim okresla zbior bajtow sluzacych do oddzielania slow w przetwarzanym lancuchu. Program wywolujacy moze podawac rozne argumenty delim w kolejnych wywolaniach przetwarzajacych ten sam lancuch znakow. Kazde wywolanie funkcji strtok() zwraca wskaznik do zakonczonego znakiem null lancuch zawierajacego nastepne slowo. Lancuch ten nie zawiera znaku separatora. Jesli nie ma wiecej slow, to strtok() zwraca NULL. Sekwencja wywolan strtok() dzialajaca na tym samym lancuchu znakow przechowuje wskaznik okreslajacy punkt, od ktorego nalezy szukac kolejnego slowa. Pierwsze wywolanie strtok() ustawia ten wskaznik na pierwszy bajt lancucha. Poczatek kolejnego slowa jest okreslany przez szukanie kolejnego bajtu niebedacego ogranicznikiem w str. Jesli taki bajt zostanie znaleziony, to jest uwazany za poczatek kolejnego slowa. Jesli nie ma takiego bajtu, to nie ma wiecej slow i strtok() zwraca NULL (Lancuch, ktory jest pusty, lub taki, ktory zawiera tylko znaki ogranicznika, spowoduje, ze pierwsze wywolanie strtok() takze zwroci NULL). Koniec kazdego slowa jest okreslany przez wyszukanie albo nastepnego bajtu ogranicznika albo napotkanie konczacego bajtu null ('\0'). Jesli zostanie znaleziony bajt ogranicznika, to jest nadpisywany znakiem null, tak aby zakonczyc biezace slowo, a strtok() zachowuje wskaznik do kolejnego bajtu; wskaznik ten bedzie uzyty jako punkt startowy wyszukiwania kolejnego slowa. W takim przypadku strtok() zwraca wskaznik do poczatku znalezionego slowa. Z powyzszego opisu wynika, ze sekwencja dwoch lub wiecej nastepujacych po sobie bajtow ogranicznika w przetwarzanym lancuchu jest uwazana za pojedynczy ogranicznik i ze ograniczniki na poczatku i koncu lancucha sa zawsze ignorowane. Innymi slowy: slowa zwracane przez strtok() sa zawsze niepustymi lancuchami znakow. Dlatego na przyklad kolejne wywolanie strtok() dla lancucha "aaa;;bbb," z lancuchem ogranicznikow ";," zwroca slowa "aaa" oraz "bbb", a nastepnie zwroca wskaznik null. Funkcja strtok_r() jest wielowatkowa wersja strtok(). Argument saveptr jest wskaznikiem do zmiennej typu char *, uzywanej wewnetrznie przez strtok_r() do zachowania kontekstu pomiedzy kolejnymi wywolaniami przetwarzajacymi ten sam lancuch znakow. On the first call to strtok_r(), str should point to the string to be parsed, and the value of *saveptr is ignored (but see VERSIONS). In subsequent calls, str should be NULL, and saveptr (and the buffer that it points to) should be unchanged since the previous call. Rozne lancuchy znakow moga byc przetwarzane rownoczesnie przy uzyciu sekwencji wywolan strtok_r(), rozniacych sie argumentami saveptr. WARTOSC ZWRACANA Funkcje strtok() i strtok_r() zwracaja wskaznik do nastepnego slowa lub NULL, jesli nie ma juz wiecej slow. ATRYBUTY Informacje o pojeciach uzywanych w tym rozdziale mozna znalezc w podreczniku attributes(7). +------------+--------------------------+------------------------------+ |Interfejs | Atrybut | Wartosc | +------------+--------------------------+------------------------------+ |strtok() | Bezpieczenstwo watkowe | MT-niebezpieczne race:strtok | +------------+--------------------------+------------------------------+ |strtok_r() | Bezpieczenstwo watkowe | MT-bezpieczne | +------------+--------------------------+------------------------------+ WERSJE W niektorych implementacjach, *saveptr musi wynosic NULL przy pierwszym wywolaniu do strtok_r(), uzywanym do analizy str. STANDARDY strtok() C11, POSIX.1-2008. strtok_r() POSIX.1-2008. HISTORIA strtok() POSIX.1-2001, C89, SVr4, 4.3BSD. strtok_r() POSIX.1-2001. USTERKI Nalezy zachowac ostroznosc przy uzywaniu tych funkcji. Jesli jednak zostana uzyte, to nalezy zauwazyc, ze: o Funkcje te modyfikuja swoj pierwszy argument. o Funkcje te nie moga byc stosowane z ciagami stalymi. o Tozsamosc bajtu separatora jest tracona. o Funkcja strtok() korzysta ze statycznego bufora, wiec nie jest przystosowana do wielowatkowosci. Jesli ma to znaczenie, nalezy uzywac strtok_r(). PRZYKLADY Ponizszy program uzywa zagniezdzonych petli, stosujac strtok_r() do podzielenia lancucha na dwupoziomowa hierarchie slow. Pierwszy argument linii polecen okresla lancuch do przetworzenia. Drugi argument podaje bajty ograniczajace uzywane do dzielenia lancucha na ,,glowne" slowa. Trzeci argument okresla bajty sluzace do dzielenia ,,glownych" slow na podslowa. Przykladowe wyjscie programu jest nastepujace: $ ./a.out 'a/bbb///cc;xxx:yyy:' ':;' '/' 1: a/bbb///cc --> a --> bbb --> cc 2: xxx --> xxx 3: yyy --> yyy Kod zrodlowy programu #include #include #include int main(int argc, char *argv[]) { char *str1, *str2, *token, *subtoken; char *saveptr1, *saveptr2; int j; if (argc != 4) { fprintf(stderr, "Uzycie: %s lancuch separ podsepar\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("\t --> %s\n", subtoken); } } exit(EXIT_SUCCESS); } Inny przykladowy program uzywajacy strtok() mozna znalezc w getaddrinfo_a(3). ZOBACZ TAKZE memchr(3), strchr(3), string(3), strpbrk(3), strsep(3), strspn(3), strstr(3), wcstok(3) TLUMACZENIE Autorami polskiego tlumaczenia niniejszej strony podrecznika sa: Pawel Wilk , 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.12 23 lipca 2024 r. strtok(3)