strtok(3)

НАИМЕНОВАНИЕ
strtok, strtok_r - извлечение элементов (токенов) из строки

БИБЛИОТЕКА
Стандартная библиотека языка C (libc, -lc)

ОБЗОР
#include <string.h>

char *strtok(char *_Nullable restrict str, const char *restrict delim);
char *strtok_r(char *_Nullable restrict str, const char *restrict delim,
               char **restrict saveptr);

    Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

strtok_r():
    _POSIX_C_SOURCE
        || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE

ОПИСАНИЕ
Функция strtok() разделяет строку на последовательность нуля или более непустых токенов. При первом вызове strtok() анализируемую строку нужно указывать в аргументе str. В каждом последующем вызове, в котором анализируется эта же строка, значение str должно быть NULL.

В аргументе delim задаётся набор байт, которые считаются разделителями токенов в анализируемой строке. Вызывающий может указывать разные строки в delim в последующих вызовах при анализе той же строки.

Каждый вызов strtok() возвращает указатель на строку, завершающуюся null, которая содержит следующий токен. Эта строка не включает байт-разделитель. Если больше токенов нет, то strtok() возвращает NULL.

Последовательность вызовов strtok(), оперирующих одной строкой, поддерживает указатель, который определяет точку, с которой начинается поиск следующего токена. Первый вызов strtok() назначает этому указателю ссылку на первый байт строки. Начало следующего токена определяется поиском вперёд в str следующего байта не разделителя. Если байт найден, то он берётся в качестве начала следующего токена. Если такой байт не найден, то токенов больше нет и strtok() возвращает NULL (для пустой строки или состоящей только из разделителей в этом случае NULL вернётся при первом вызове strtok()).

The end of each token is found by scanning forward until either the next delimiter byte is found or until the terminating null byte ('\0') is encountered. If a delimiter byte is found, it is overwritten with a null byte to terminate the current token, and strtok() saves a pointer to the following byte; that pointer will be used as the starting point when searching for the next token. In this case, strtok() returns a pointer to the start of the found token.

From the above description, it follows that a sequence of two or more contiguous delimiter bytes in the parsed string is considered to be a single delimiter, and that delimiter bytes at the start or end of the string are ignored. Put another way: the tokens returned by strtok() are always nonempty strings. Thus, for example, given the string "aaa;;bbb,", successive calls to strtok() that specify the delimiter string ";," would return the strings "aaa" and "bbb", and then a null pointer.

The strtok_r() function is a reentrant version of strtok(). The saveptr argument is a pointer to a char * variable that is used internally by strtok_r() in order to maintain context between successive calls that parse the same string.

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.

Одновременно могут анализироваться разные строки при нескольких запусках strtok_r() с различными аргументами saveptr.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Функции strtok() и strtok_r() возвращают указатель на следующий токен или NULL, если больше токенов нет.

АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).
Интерфейс | Атрибут | Значение
strtok() | Безвредность в нитях | MT-Unsafe race:strtok
strtok_r() | Безвредность в нитях | MT-Safe

ВЕРСИИ
В некоторых реализациях значение *saveptr должно быть равно NULL при первом вызове strtok_r(), который используется для разбора str.

СТАНДАРТЫ

strtok()
    C11, POSIX.1-2008.

strtok_r()
    POSIX.1-2008.

ИСТОРИЯ

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

strtok_r()
    POSIX.1-2001.

ОШИБКИ
Используйте данные функции с осторожностью. Учитывайте, что:

•   Эти функции изменяют свой первый аргумент.

•   Эти функции не могут использоваться со строками-константами.

•   Теряется идентичность байта-разделителя.

•   При анализе функция strtok() использует статический буфер, поэтому не является безопасной для нитей. Используйте strtok_r() в этом случае.

ПРИМЕРЫ
В программе, представленной далее, используются вложенные циклы, которые вызывают strtok_r() для разделения строки на составляющие её токены. В первом параметре командной строки задаётся анализируемая строка. Во втором параметре задаётся байт(ы)- разделитель, который используется для деления строки на «составные» токены. В третьем параметре указывается байт(ы)- разделитель, который используется для разделения «составных» токенов на подтокены.

Пример результата вывода программы:

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

  Исходный код программы
    #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, "Usage: %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("\t --> %s\n", subtoken);
            }
        }

        exit(EXIT_SUCCESS);
    }

Ещё один пример программы, использующей strtok(), можно найти в getaddrinfo_a(3).

СМОТРИТЕ ТАКЖЕ
memchr(3), strchr(3), string(3), strpbrk(3), strsep(3), strspn(3), strstr(3), wcstok(3)

ПЕРЕВОД
Русский перевод этой страницы руководства разработал(и) Alexander Golubev <fatzer2@gmail.com>, Azamat Hackimov <azamat.hackimov@gmail.com>, Hotellook, Nikita <zxcvbnm3230@mail.ru>, Spiros Georgaras <sng@hellug.gr>, Vladislav <ivladislavefimov@gmail.com>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>

Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.

Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских переводчиков (<debian-l10n-russian@lists.debian.org>).