man3/strtok.3

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