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  2021-03-22 "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 *restrict " str ", const char *restrict " delim );
  40 .BI "char *strtok_r(char *restrict " str ", const char *restrict " delim ,
  41 .BI "               char **restrict " saveptr );
  42 .fi
  43 .PP
  44 .RS -4
  45 Feature Test Macro Requirements for glibc (see
  46 .BR feature_test_macros (7)):
  47 .RE
  48 .PP
  49 .BR strtok_r ():
  50 .nf
  51     _POSIX_C_SOURCE
  52         || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  53 .fi
  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 of
 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 (but see NOTES).
 151 In subsequent calls,
 152 .I str
 153 should be NULL, and
 154 .I saveptr
 155 (and the buffer that it points to)
 156 should be unchanged since the previous call.
 157 .PP
 158 Different strings may be parsed concurrently using sequences of calls to
 159 .BR strtok_r ()
 160 that specify different
 161 .I saveptr
 162 arguments.
 163 .SH RETURN VALUE
 164 The
 165 .BR strtok ()
 166 and
 167 .BR strtok_r ()
 168 functions return a pointer to
 169 the next token, or NULL if there are no more tokens.
 170 .SH ATTRIBUTES
 171 For an explanation of the terms used in this section, see
 172 .BR attributes (7).
 173 .ad l
 174 .nh
 175 .TS
 176 allbox;
 177 lbx lb lb
 178 l l l.
 179 Interface       Attribute       Value
 180 T{
 181 .BR strtok ()
 182 T}      Thread safety   MT-Unsafe race:strtok
 183 T{
 184 .BR strtok_r ()
 185 T}      Thread safety   MT-Safe
 186 .TE
 187 .hy
 188 .ad
 189 .sp 1
 190 .SH CONFORMING TO
 191 .TP
 192 .BR strtok ()
 193 POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD.
 194 .TP
 195 .BR strtok_r ()
 196 POSIX.1-2001, POSIX.1-2008.
 197 .SH NOTES
 198 On some implementations,
 199 .\" Tru64, according to its manual page
 200 .I *saveptr
 201 is required to be NULL on the first call to
 202 .BR strtok_r ()
 203 that is being used to parse
 204 .IR str .
 205 .SH BUGS
 206 Be cautious when using these functions.
 207 If you do use them, note that:
 208 .IP * 2
 209 These functions modify their first argument.
 210 .IP *
 211 These functions cannot be used on constant strings.
 212 .IP *
 213 The identity of the delimiting byte is lost.
 214 .IP *
 215 The
 216 .BR strtok ()
 217 function uses a static buffer while parsing, so it's not thread safe.
 218 Use
 219 .BR strtok_r ()
 220 if this matters to you.
 221 .SH EXAMPLES
 222 The program below uses nested loops that employ
 223 .BR strtok_r ()
 224 to break a string into a two-level hierarchy of tokens.
 225 The first command-line argument specifies the string to be parsed.
 226 The second argument specifies the delimiter byte(s)
 227 to be used to separate that string into "major" tokens.
 228 The third argument specifies the delimiter byte(s)
 229 to be used to separate the "major" tokens into subtokens.
 230 .PP
 231 An example of the output produced by this program is the following:
 232 .PP
 233 .in +4n
 234 .EX
 235 .RB "$" " ./a.out \(aqa/bbb///cc;xxx:yyy:\(aq \(aq:;\(aq \(aq/\(aq"
 236 1: a/bbb///cc
 237          \-\-> a
 238          \-\-> bbb
 239          \-\-> cc
 240 2: xxx
 241          \-\-> xxx
 242 3: yyy
 243          \-\-> yyy
 244 .EE
 245 .in
 246 .SS Program source
 247 \&
 248 .EX
 249 #include <stdio.h>
 250 #include <stdlib.h>
 251 #include <string.h>
 252
 253 int
 254 main(int argc, char *argv[])
 255 {
 256     char *str1, *str2, *token, *subtoken;
 257     char *saveptr1, *saveptr2;
 258
 259     if (argc != 4) {
 260         fprintf(stderr, "Usage: %s string delim subdelim\en",
 261                 argv[0]);
 262         exit(EXIT_FAILURE);
 263     }
 264
 265     for (int j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
 266         token = strtok_r(str1, argv[2], &saveptr1);
 267         if (token == NULL)
 268             break;
 269         printf("%d: %s\en", j, token);
 270
 271         for (str2 = token; ; str2 = NULL) {
 272             subtoken = strtok_r(str2, argv[3], &saveptr2);
 273             if (subtoken == NULL)
 274                 break;
 275             printf("\t \-\-> %s\en", subtoken);
 276         }
 277     }
 278
 279     exit(EXIT_SUCCESS);
 280 }
 281 .EE
 282 .PP
 283 Another example program using
 284 .BR strtok ()
 285 can be found in
 286 .BR getaddrinfo_a (3).
 287 .SH SEE ALSO
 288 .BR index (3),
 289 .BR memchr (3),
 290 .BR rindex (3),
 291 .BR strchr (3),
 292 .BR string (3),
 293 .BR strpbrk (3),
 294 .BR strsep (3),
 295 .BR strspn (3),
 296 .BR strstr (3),
 297 .BR wcstok (3)