man3/strtok.3

   1 '\" t
   2 .\" Copyright (C) 2005, 2013 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\" a few fragments from an earlier (1996) version by
   4 .\" Andries Brouwer (aeb@cwi.nl) remain.
   5 .\"
   6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   7 .\"
   8 .\" Rewritten old page, 960210, aeb@cwi.nl
   9 .\" Updated, added strtok_r. 2000-02-13 Nicolás Lichtmaier <nick@debian.org>
  10 .\" 2005-11-17, mtk: Substantial parts rewritten
  11 .\" 2013-05-19, mtk: added much further detail on the operation of strtok()
  12 .\"
  13 .TH strtok 3 (date) "Linux man-pages (unreleased)"
  14 .SH NAME
  15 strtok, strtok_r \- extract tokens from strings
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <string.h>
  22 .PP
  23 .BI "char *strtok(char *restrict " str ", const char *restrict " delim );
  24 .BI "char *strtok_r(char *restrict " str ", const char *restrict " delim ,
  25 .BI "               char **restrict " saveptr );
  26 .fi
  27 .PP
  28 .RS -4
  29 Feature Test Macro Requirements for glibc (see
  30 .BR feature_test_macros (7)):
  31 .RE
  32 .PP
  33 .BR strtok_r ():
  34 .nf
  35     _POSIX_C_SOURCE
  36         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  37 .fi
  38 .SH DESCRIPTION
  39 The
  40 .BR strtok ()
  41 function breaks a string into a sequence of zero or more nonempty tokens.
  42 On the first call to
  43 .BR strtok (),
  44 the string to be parsed should be
  45 specified in
  46 .IR str .
  47 In each subsequent call that should parse the same string,
  48 .I str
  49 must be NULL.
  50 .PP
  51 The
  52 .I delim
  53 argument specifies a set of bytes that
  54 delimit the tokens in the parsed string.
  55 The caller may specify different strings in
  56 .I delim
  57 in successive
  58 calls that parse the same string.
  59 .PP
  60 Each call to
  61 .BR strtok ()
  62 returns a pointer to a
  63 null-terminated string containing the next token.
  64 This string does not include the delimiting byte.
  65 If no more tokens are found,
  66 .BR strtok ()
  67 returns NULL.
  68 .PP
  69 A sequence of calls to
  70 .BR strtok ()
  71 that operate on the same string maintains a pointer
  72 that determines the point from which to start searching for the next token.
  73 The first call to
  74 .BR strtok ()
  75 sets this pointer to point to the first byte of the string.
  76 The start of the next token is determined by scanning forward
  77 for the next nondelimiter byte in
  78 .IR str .
  79 If such a byte is found, it is taken as the start of the next token.
  80 If no such byte is found,
  81 then there are no more tokens, and
  82 .BR strtok ()
  83 returns NULL.
  84 (A string that is empty or that contains only delimiters
  85 will thus cause
  86 .BR strtok ()
  87 to return NULL on the first call.)
  88 .PP
  89 The end of each token is found by scanning forward until either
  90 the next delimiter byte is found or until the
  91 terminating null byte (\[aq]\e0\[aq]) is encountered.
  92 If a delimiter byte is found, it is overwritten with
  93 a null byte to terminate the current token, and
  94 .BR strtok ()
  95 saves a pointer to the following byte;
  96 that pointer will be used as the starting point
  97 when searching for the next token.
  98 In this case,
  99 .BR strtok ()
 100 returns a pointer to the start of the found token.
 101 .PP
 102 From the above description,
 103 it follows that a sequence of two or more contiguous delimiter bytes in
 104 the parsed string is considered to be a single delimiter, and that
 105 delimiter bytes at the start or end of the string are ignored.
 106 Put another way: the tokens returned by
 107 .BR strtok ()
 108 are always nonempty strings.
 109 Thus, for example, given the string "\fIaaa;;bbb,\fP",
 110 successive calls to
 111 .BR strtok ()
 112 that specify the delimiter string "\fI;,\fP"
 113 would return the strings "\fIaaa\fP" and "\fIbbb\fP",
 114 and then a null pointer.
 115 .PP
 116 The
 117 .BR strtok_r ()
 118 function is a reentrant version of
 119 .BR strtok ().
 120 The
 121 .I saveptr
 122 argument is a pointer to a
 123 .I char\~*
 124 variable that is used internally by
 125 .BR strtok_r ()
 126 in order to maintain context between successive calls that parse the
 127 same string.
 128 .PP
 129 On the first call to
 130 .BR strtok_r (),
 131 .I str
 132 should point to the string to be parsed, and the value of
 133 .I *saveptr
 134 is ignored (but see NOTES).
 135 In subsequent calls,
 136 .I str
 137 should be NULL, and
 138 .I saveptr
 139 (and the buffer that it points to)
 140 should be unchanged since the previous call.
 141 .PP
 142 Different strings may be parsed concurrently using sequences of calls to
 143 .BR strtok_r ()
 144 that specify different
 145 .I saveptr
 146 arguments.
 147 .SH RETURN VALUE
 148 The
 149 .BR strtok ()
 150 and
 151 .BR strtok_r ()
 152 functions return a pointer to
 153 the next token, or NULL if there are no more tokens.
 154 .SH ATTRIBUTES
 155 For an explanation of the terms used in this section, see
 156 .BR attributes (7).
 157 .ad l
 158 .nh
 159 .TS
 160 allbox;
 161 lbx lb lb
 162 l l l.
 163 Interface       Attribute       Value
 164 T{
 165 .BR strtok ()
 166 T}      Thread safety   MT-Unsafe race:strtok
 167 T{
 168 .BR strtok_r ()
 169 T}      Thread safety   MT-Safe
 170 .TE
 171 .hy
 172 .ad
 173 .sp 1
 174 .SH STANDARDS
 175 .TP
 176 .BR strtok ()
 177 POSIX.1-2001, POSIX.1-2008, C99, SVr4, 4.3BSD.
 178 .TP
 179 .BR strtok_r ()
 180 POSIX.1-2001, POSIX.1-2008.
 181 .SH NOTES
 182 On some implementations,
 183 .\" Tru64, according to its manual page
 184 .I *saveptr
 185 is required to be NULL on the first call to
 186 .BR strtok_r ()
 187 that is being used to parse
 188 .IR str .
 189 .SH BUGS
 190 Be cautious when using these functions.
 191 If you do use them, note that:
 192 .IP \[bu] 3
 193 These functions modify their first argument.
 194 .IP \[bu]
 195 These functions cannot be used on constant strings.
 196 .IP \[bu]
 197 The identity of the delimiting byte is lost.
 198 .IP \[bu]
 199 The
 200 .BR strtok ()
 201 function uses a static buffer while parsing, so it's not thread safe.
 202 Use
 203 .BR strtok_r ()
 204 if this matters to you.
 205 .SH EXAMPLES
 206 The program below uses nested loops that employ
 207 .BR strtok_r ()
 208 to break a string into a two-level hierarchy of tokens.
 209 The first command-line argument specifies the string to be parsed.
 210 The second argument specifies the delimiter byte(s)
 211 to be used to separate that string into "major" tokens.
 212 The third argument specifies the delimiter byte(s)
 213 to be used to separate the "major" tokens into subtokens.
 214 .PP
 215 An example of the output produced by this program is the following:
 216 .PP
 217 .in +4n
 218 .EX
 219 .RB "$" " ./a.out \[aq]a/bbb///cc;xxx:yyy:\[aq] \[aq]:;\[aq] \[aq]/\[aq]"
 220 1: a/bbb///cc
 221          \-\-> a
 222          \-\-> bbb
 223          \-\-> cc
 224 2: xxx
 225          \-\-> xxx
 226 3: yyy
 227          \-\-> yyy
 228 .EE
 229 .in
 230 .SS Program source
 231 \&
 232 .\" SRC BEGIN (strtok.c)
 233 .EX
 234 #include <stdio.h>
 235 #include <stdlib.h>
 236 #include <string.h>
 237
 238 int
 239 main(int argc, char *argv[])
 240 {
 241     char *str1, *str2, *token, *subtoken;
 242     char *saveptr1, *saveptr2;
 243     int j;
 244
 245     if (argc != 4) {
 246         fprintf(stderr, "Usage: %s string delim subdelim\en",
 247                 argv[0]);
 248         exit(EXIT_FAILURE);
 249     }
 250
 251     for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
 252         token = strtok_r(str1, argv[2], &saveptr1);
 253         if (token == NULL)
 254             break;
 255         printf("%d: %s\en", j, token);
 256
 257         for (str2 = token; ; str2 = NULL) {
 258             subtoken = strtok_r(str2, argv[3], &saveptr2);
 259             if (subtoken == NULL)
 260                 break;
 261             printf("\et \-\-> %s\en", subtoken);
 262         }
 263     }
 264
 265     exit(EXIT_SUCCESS);
 266 }
 267 .EE
 268 .\" SRC END
 269 .PP
 270 Another example program using
 271 .BR strtok ()
 272 can be found in
 273 .BR getaddrinfo_a (3).
 274 .SH SEE ALSO
 275 .BR memchr (3),
 276 .BR strchr (3),
 277 .BR string (3),
 278 .BR strpbrk (3),
 279 .BR strsep (3),
 280 .BR strspn (3),
 281 .BR strstr (3),
 282 .BR wcstok (3)