original/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  2013-05-19 "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 .sp
  39 .BI "char *strtok(char *" str ", const char *" delim );
  40 .sp
  41 .BI "char *strtok_r(char *" str ", const char *" delim ", char **" saveptr );
  42 .fi
  43 .sp
  44 .in -4n
  45 Feature Test Macro Requirements for glibc (see
  46 .BR feature_test_macros (7)):
  47 .in
  48 .sp
  49 .ad l
  50 .BR strtok_r ():
  51 _SVID_SOURCE || _BSD_SOURCE || _POSIX_C_SOURCE\ >=\ 1 ||
  52 _XOPEN_SOURCE || _POSIX_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
  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
  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
  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
 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\\0\(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
 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
 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
 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
 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 .SS Multithreading (see pthreads(7))
 171 The
 172 .BR strtok ()
 173 function is not thread-safe.
 174 .LP
 175 The
 176 .BR strtok_r ()
 177 function is thread-safe.
 178 .SH CONFORMING TO
 179 .TP
 180 .BR strtok ()
 181 SVr4, POSIX.1-2001, 4.3BSD, C89, C99.
 182 .TP
 183 .BR strtok_r ()
 184 POSIX.1-2001.
 185 .SH BUGS
 186 Be cautious when using these functions.
 187 If you do use them, note that:
 188 .IP * 2
 189 These functions modify their first argument.
 190 .IP *
 191 These functions cannot be used on constant strings.
 192 .IP *
 193 The identity of the delimiting byte is lost.
 194 .IP *
 195 The
 196 .BR strtok ()
 197 function uses a static buffer while parsing, so it's not thread safe.
 198 Use
 199 .BR strtok_r ()
 200 if this matters to you.
 201 .SH EXAMPLE
 202 The program below uses nested loops that employ
 203 .BR strtok_r ()
 204 to break a string into a two-level hierarchy of tokens.
 205 The first command-line argument specifies the string to be parsed.
 206 The second argument specifies the delimiter byte(s)
 207 to be used to separate that string into "major" tokens.
 208 The third argument specifies the delimiter byte(s)
 209 to be used to separate the "major" tokens into subtokens.
 210 .PP
 211 An example of the output produced by this program is the following:
 212 .PP
 213 .in +4n
 214 .nf
 215 .RB "$" " ./a.out \(aqa/bbb///cc;xxx:yyy:\(aq \(aq:;\(aq \(aq/\(aq"
 216 1: a/bbb///cc
 217          \-\-> a
 218          \-\-> bbb
 219          \-\-> cc
 220 2: xxx
 221          \-\-> xxx
 222 3: yyy
 223          \-\-> yyy
 224 .fi
 225 .in
 226 .SS Program source
 227 \&
 228 .nf
 229 #include <stdio.h>
 230 #include <stdlib.h>
 231 #include <string.h>
 232
 233 int
 234 main(int argc, char *argv[])
 235 {
 236     char *str1, *str2, *token, *subtoken;
 237     char *saveptr1, *saveptr2;
 238     int j;
 239
 240     if (argc != 4) {
 241         fprintf(stderr, "Usage: %s string delim subdelim\\n",
 242                 argv[0]);
 243         exit(EXIT_FAILURE);
 244     }
 245
 246     for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
 247         token = strtok_r(str1, argv[2], &saveptr1);
 248         if (token == NULL)
 249             break;
 250         printf("%d: %s\\n", j, token);
 251
 252         for (str2 = token; ; str2 = NULL) {
 253             subtoken = strtok_r(str2, argv[3], &saveptr2);
 254             if (subtoken == NULL)
 255                 break;
 256             printf("\t \-\-> %s\\n", subtoken);
 257         }
 258     }
 259
 260     exit(EXIT_SUCCESS);
 261 }
 262 .fi
 263 .PP
 264 Another example program using
 265 .BR strtok ()
 266 can be found in
 267 .BR getaddrinfo_a (3).
 268 .SH SEE ALSO
 269 .BR index (3),
 270 .BR memchr (3),
 271 .BR rindex (3),
 272 .BR strchr (3),
 273 .BR string (3),
 274 .BR strpbrk (3),
 275 .BR strsep (3),
 276 .BR strspn (3),
 277 .BR strstr (3),
 278 .BR wcstok (3)
 279 .SH COLOPHON
 280 This page is part of release 3.79 of the Linux
 281 .I man-pages
 282 project.
 283 A description of the project,
 284 information about reporting bugs,
 285 and the latest version of this page,
 286 can be found at
 287 \%http://www.kernel.org/doc/man\-pages/.