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
15   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
16
17       strtok_r(): _SVID_SOURCE || _BSD_SOURCE || _POSIX_C_SOURCE >= 1 ||
18       _XOPEN_SOURCE || _POSIX_SOURCE
19

DESCRIPTION

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

RETURN VALUE

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

CONFORMING TO

57       strtok()
58              SVr4, POSIX.1-2001, 4.3BSD, C89, C99.
59
60       strtok_r()
61              POSIX.1-2001.
62

BUGS

64       Be cautious when using these functions.  If you do use them, note that:
65
66       * These functions modify their first argument.
67
68       * These functions cannot be used on constant strings.
69
70       * The identity of the delimiting character is lost.
71
72       * The strtok() function uses a static buffer while parsing, so it's not
73         thread safe.  Use strtok_r() if this matters to you.
74

EXAMPLE

76       The  program  below uses nested loops that employ strtok_r() to break a
77       string into a two-level hierarchy of tokens.   The  first  command-line
78       argument specifies the string to be parsed.  The second argument speci‐
79       fies the delimiter character(s) to be used to separate that string into
80       "major"  tokens.   The  third  argument specifies the delimiter charac‐
81       ter(s) to be used to separate the "major" tokens into subtokens.
82
83       An example of the output produced by this program is the following:
84
85           $ ./a.out 'a/bbb///cc;xxx:yyy:' ':;' '/'
86           1: a/bbb///cc
87                    --> a
88                    --> bbb
89                    --> cc
90           2: xxx
91                    --> xxx
92           3: yyy
93                    --> yyy
94
95   Program source
96
97       #include <stdio.h>
98       #include <stdlib.h>
99       #include <string.h>
100
101       int
102       main(int argc, char *argv[])
103       {
104           char *str1, *str2, *token, *subtoken;
105           char *saveptr1, *saveptr2;
106           int j;
107
108           if (argc != 4) {
109               fprintf(stderr, "Usage: %s string delim subdelim\n",
110                       argv[0]);
111               exit(EXIT_FAILURE);
112           }
113
114           for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
115               token = strtok_r(str1, argv[2], &saveptr1);
116               if (token == NULL)
117                   break;
118               printf("%d: %s\n", j, token);
119
120               for (str2 = token; ; str2 = NULL) {
121                   subtoken = strtok_r(str2, argv[3], &saveptr2);
122                   if (subtoken == NULL)
123                       break;
124                   printf(" --> %s\n", subtoken);
125               }
126           }
127
128           exit(EXIT_SUCCESS);
129       } /* main */
130

COLOPHON

136       This  page  is  part of release 3.25 of the Linux man-pages project.  A
137       description of the project, and information about reporting  bugs,  can
138       be found at http://www.kernel.org/doc/man-pages/.
139
140
141
142GNU                               2008-10-29                         STRTOK(3)