strtok(3)

1STRTOK(3)                  Linux Programmer's Manual                 STRTOK(3)
2
3
4

NAME

6       strtok, strtok_r - extract tokens from strings
7

SYNOPSIS

9       #include <string.h>
10
11       char *strtok(char *str, const char *delim);
12
13       char *strtok_r(char *str, const char *delim, char **saveptr);
14

DESCRIPTION

16       The  strtok()  function  parses a string into a sequence of tokens.  On
17       the first call to strtok() the string to be parsed should be  specified
18       in str.  In each subsequent call that should parse the same string, str
19       should be NULL.
20
21       The delim argument specifies a  set  of  characters  that  delimit  the
22       tokens  in the parsed string.  The caller may specify different strings
23       in delim in successive calls that parse the same string.
24
25       Each call to strtok() returns a pointer  to  a  null-terminated  string
26       containing the next token.  This string does not include the delimiting
27       character.  If no more tokens are found, strtok() returns NULL.
28
29       A sequence of two or more contiguous delimiter characters in the parsed
30       string is considered to be a single delimiter.  Delimiter characters at
31       the start or end of the string  are  ignored.   Put  another  way:  the
32       tokens returned by strtok() are always non-empty strings.
33
34       The  strtok_r()  function is a reentrant version strtok().  The saveptr
35       argument is a pointer to a char * variable that is used  internally  by
36       strtok_r()  in  order to maintain context between successive calls that
37       parse the same string.
38
39       On the first call to strtok_r(), str should point to the string  to  be
40       parsed,  and the value of saveptr is ignored.  In subsequent calls, str
41       should be NULL, and saveptr should  be  unchanged  since  the  previous
42       call.
43
44       Different  strings  may be parsed concurrently using sequences of calls
45       to strtok_r() that specify different saveptr arguments.
46

EXAMPLE

48       The following program uses nested loops that employ strtok_r() to break
49       a  string into a two-level hierarchy of tokens.  The first command-line
50       argument specifies the string to be parsed.  The second argument speci‐
51       fies the delimiter character(s) to be used to separate that string into
52       "major" tokens.  The third argument  specifies  the  delimiter  charac‐
53       ter(s) to be used to separate the "major" tokens into subtokens.
54
55       #include <stdio.h>
56       #include <stdlib.h>
57       #include <string.h>
58
59       int
60       main(int argc, char *argv[])
61       {
62           char *str1, *str2, *token, *subtoken;
63           char *saveptr1, *saveptr2;
64           int j;
65
66           if (argc != 4) {
67               fprintf(stderr, "Usage: %s string delim subdelim\n",
68                       argv[0]);
69               exit(EXIT_FAILURE);
70           }
71
72           for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
73               token = strtok_r(str1, argv[2], &saveptr1);
74               if (token == NULL)
75                   break;
76               printf("%d: %s\n", j, token);
77
78               for (str2 = token; ; str2 = NULL) {
79                   subtoken = strtok_r(str2, argv[3], &saveptr2);
80                   if (subtoken == NULL)
81                       break;
82                   printf(" --> %s\n", subtoken);
83               }
84           }
85
86           exit(EXIT_SUCCESS);
87       } /* main */
88
89       An example of the output produced by this program is the following:
90
91       $ ./a.out 'a/bbb///cc;xxx:yyy:' ':;' '/'
92       1: a/bbb///cc
93                --> a
94                --> bbb
95                --> cc
96       2: xxx
97                --> xxx
98       3: yyy
99                --> yyy
100

BUGS

102       Avoid using these functions.  If you do use them, note that:
103
104              These functions modify their first argument.
105
106              These functions cannot be used on constant strings.
107
108              The identity of the delimiting character is lost.
109
110              The  strtok()  function  uses  a static buffer while parsing, so
111              it's not thread safe. Use strtok_r() if this matters to you.
112

RETURN VALUE

114       The strtok() and strtok_r() functions return  a  pointer  to  the  next
115       token, or NULL if there are no more tokens.
116

CONFORMING TO

118       strtok()
119              SVr4, POSIX.1-2001, 4.3BSD, C89, C99.
120
121       strtok_r()
122              POSIX.1-2001
123