Print this page
Garrett's man page edits.
   1 '\" te

   2 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" Portions Copyright (c) 1994 Man-cgi 1.15, Panagiotis Christias (christia@softlab.ntua.gr)
   5 .\" Portions Copyright (c) 1996-2008 Modified for NetBSD by Kimmo Suominen (kimmo@suominen.com)
   6 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
   7 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   8 .\" http://www.opengroup.org/bookstore/.
   9 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
  10 .\"  This notice shall appear on any product containing this material.
  11 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
  12 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  13 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  14 .TH STRING 3C "Jun 19, 2013"
  15 .SH NAME
  16 string, strcasecmp, strcasecmp_l, strncasecmp, strncasecmp_l, strcat, strncat, strlcat, strchr, strrchr,

  17 strcmp, strncmp, strcpy, strncpy, strlcpy, strcspn, strspn, strdup, strlen,
  18 strnlen, strpbrk, strsep, strstr, strtok, strtok_r \- string operations
  19 .SH SYNOPSIS
  20 .LP
  21 .nf
  22 #include <strings.h>
  23 
  24 \fBint\fR \fBstrcasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
  25 .fi
  26 
  27 .LP
  28 .nf
  29 \fBint\fR \fBstrcasecmp_l\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBlocale_t\fR \fIloc\fR);
  30 .fi
  31 
  32 .LP
  33 .nf
  34 \fBint\fR \fBstrncasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR);
  35 .fi
  36 
  37 .LP
  38 .nf
  39 \fBint\fR \fBstrncasecmp_l\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR, \fBlocale_t\fR \fIloc\fR);
  40 .fi
  41 
  42 .LP
  43 .nf
  44 #include <string.h>
  45 
  46 \fBchar *\fR\fBstrcat\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
  47 .fi
  48 
  49 .LP
  50 .nf
  51 \fBchar *\fR\fBstrncat\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR, \fBsize_t\fR \fIn\fR);
  52 .fi
  53 
  54 .LP
  55 .nf
  56 \fBsize_t\fR \fBstrlcat\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR);
  57 .fi
  58 
  59 .LP
  60 .nf
  61 \fBchar *\fR\fBstrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
  62 .fi
  63 
  64 .LP
  65 .nf
  66 \fBchar *\fR\fBstrrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
  67 .fi
  68 
  69 .LP
  70 .nf
  71 \fBint\fR \fBstrcmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
  72 .fi
  73 
  74 .LP
  75 .nf
  76 \fBint\fR \fBstrncmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR);
  77 .fi
  78 
  79 .LP
  80 .nf
  81 \fBchar *\fR\fBstrcpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
  82 .fi
  83 
  84 .LP
  85 .nf
  86 \fBchar *\fR\fBstrncpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR, \fBsize_t\fR \fIn\fR);
  87 .fi
  88 
  89 .LP
  90 .nf
  91 \fBsize_t\fR \fBstrlcpy\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR);
  92 .fi
  93 
  94 .LP
  95 .nf
  96 \fBsize_t\fR \fBstrcspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
  97 .fi
  98 
  99 .LP
 100 .nf
 101 \fBsize_t\fR \fBstrspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 102 .fi
 103 
 104 .LP
 105 .nf
 106 \fBchar *\fR\fBstrdup\fR(\fBconst char *\fR\fIs1\fR);
 107 .fi
 108 
 109 .LP
 110 .nf
 111 \fBsize_t\fR \fBstrlen\fR(\fBconst char *\fR\fIs\fR);
 112 .fi
 113 
 114 .LP
 115 .nf
 116 \fBsize_t\fR \fBstrnlen\fR(\fBconst char *\fR\fIs\fR, \fBsize_t\fR \fIn\fR);
 117 .fi
 118 
 119 .LP
 120 .nf
 121 \fBchar *\fR\fBstrpbrk\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 122 .fi
 123 
 124 .LP
 125 .nf
 126 \fBchar *\fR\fBstrsep\fR(\fBchar **\fR\fIstringp\fR, \fBconst char *\fR\fIdelim\fR);
 127 .fi
 128 
 129 .LP
 130 .nf
 131 \fBchar *\fR\fBstrstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 132 .fi
 133 
 134 .LP
 135 .nf
 136 \fBchar *\fR\fBstrtok\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
 137 .fi
 138 
 139 .LP
 140 .nf
 141 \fBchar *\fR\fBstrtok_r\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR,
 142      \fBchar **restrict\fR \fIlasts\fR);
 143 .fi
 144 
 145 .SS "ISO C++"
 146 .LP
 147 .nf
 148 #include <string.h>
 149 
 150 \fBconst char *\fR\fBstrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
 151 .fi
 152 
 153 .LP
 154 .nf
 155 \fBconst char *\fR\fBstrpbrk\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 156 .fi
 157 
 158 .LP
 159 .nf
 160 \fBconst char *\fR\fBstrrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
 161 .fi
 162 
 163 .LP
 164 .nf
 165 \fBconst char *\fR\fBstrstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 166 .fi
 167 
 168 .LP
 169 .nf
 170 #include <cstring>
 171 
 172 \fBchar *std::\fR\fBstrchr\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIc\fR);
 173 .fi
 174 
 175 .LP
 176 .nf
 177 \fBchar *std::\fR\fBstrpbrk\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 178 .fi
 179 
 180 .LP
 181 .nf
 182 \fBchar *std::\fR\fBstrrchr\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIc\fR);
 183 .fi
 184 
 185 .LP
 186 .nf
 187 \fBchar *std::\fR\fBstrstr\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 188 .fi
 189 
 190 .SH DESCRIPTION
 191 .sp
 192 .LP
 193 The arguments \fIs\fR, \fIs1\fR, and \fIs2\fR point to strings (arrays of
 194 characters terminated by a null character). The \fBstrcat()\fR,
 195 \fBstrncat()\fR, \fBstrlcat()\fR, \fBstrcpy()\fR, \fBstrncpy()\fR,
 196 \fBstrlcpy()\fR, \fBstrsep()\fR, \fBstrtok()\fR, and \fBstrtok_r()\fR functions
 197 all alter their first argument. Additionally, the \fBstrcat()\fR and
 198 \fBstrcpy()\fR functions do not check for overflow of the array.
 199 .SS "\fBstrcasecmp()\fR, \fBstrncasecmp()\fR"
 200 .sp
 201 .LP
 202 The \fBstrcasecmp()\fR and \fBstrncasecmp()\fR functions are case-insensitive
 203 versions of  \fBstrcmp()\fR and \fBstrncmp()\fR respectively, described below.
 204 They assume the \fBASCII\fR character set and ignore differences in case when
 205 comparing lower and upper case characters.













 206 .SS "\fBstrcasecmp_l()\fR, \fBstrncasecmp_l()\fR"
 207 .sp
 208 .LP
 209 The \fBstrcasecmp_l()\fR and \fBstrncasecmp_l()\fR functions behave identically
 210 to \fBstrcasecmp()\fR and \fBstrncasecmp()\fR, except instead of operating in
 211 the current locale, they instead operate in the locale specified by \fIloc\fR.
 212 .SS "\fBstrcat()\fR, \fBstrncat()\fR, \fBstrlcat()\fR"
 213 .sp
 214 .LP
 215 The \fBstrcat()\fR function appends a copy of string \fIs2\fR, including the
 216 terminating null character, to the end of string \fIs1\fR. The \fBstrncat()\fR
 217 function appends at most \fIn\fR characters. Each returns a pointer to the
 218 null-terminated result. The initial character of  \fIs2\fR overrides the null
 219 character at the end of \fIs1\fR. If copying takes place between objects that
 220 overlap, the behavior of \fBstrcat()\fR, \fBstrncat()\fR, and \fBstrlcat()\fR
 221 is undefined.
 222 .sp
 223 .LP
 224 The \fBstrlcat()\fR function appends  at most
 225 (\fIdstsize\fR-\fBstrlen\fR(\fIdst\fR)-1) characters of \fIsrc\fR to \fIdst\fR
 226 (\fIdstsize\fR being the  size of the  string buffer \fIdst\fR). If the string
 227 pointed to by \fIdst\fR contains a null-terminated string that fits into
 228 \fIdstsize\fR bytes when \fBstrlcat()\fR is called, the string pointed to by
 229 \fIdst\fR will be a null-terminated string that fits in \fIdstsize\fR bytes
 230 (including the terminating null character) when it completes, and the initial
 231 character of \fIsrc\fR will override the null character at  the end of
 232 \fIdst\fR. If the string pointed to by \fIdst\fR is longer than \fIdstsize\fR
 233 bytes when \fBstrlcat()\fR is called, the string pointed to by \fIdst\fR will
 234 not be changed. The function returns
 235 \fBmin\fR{\fIdstsize\fR,\fBstrlen\fR(\fIdst\fR)}+\fBstrlen\fR(\fIsrc\fR).
 236 Buffer overflow can be checked as  follows:
 237 .sp
 238 .in +2
 239 .nf
 240 if (strlcat(dst, src, dstsize) >= dstsize)
 241         return \(mi1;
 242 .fi
 243 .in -2
 244 
 245 .SS "\fBstrchr()\fR, \fBstrrchr()\fR"
 246 .sp
 247 .LP
 248 The \fBstrchr()\fR function returns a pointer to the first occurrence of
 249 \fIc\fR (converted to a  \fBchar\fR) in string \fIs\fR, or a null pointer if
 250 \fIc\fR does not occur in the string. The \fBstrrchr()\fR function returns a
 251 pointer to the last occurrence of \fIc\fR. The null character terminating a
 252 string is considered to be part of the string.
 253 .SS "\fBstrcmp()\fR, \fBstrncmp()\fR"
 254 .sp
 255 .LP
 256 The \fBstrcmp()\fR function compares two strings byte-by-byte, according to the
 257 ordering of your machine's character set.  The function returns an integer
 258 greater than, equal to, or less than 0, if  the string pointed to by \fIs1\fR
 259 is greater than, equal to, or less than the string pointed to by \fIs2\fR
 260 respectively. The sign of a non-zero return value is determined  by the sign of
 261 the difference between the values of the first pair of bytes that differ in the
 262 strings being compared. The \fBstrncmp()\fR function makes the same comparison
 263 but looks at a maximum of \fIn\fR bytes. Bytes following a null byte are not
 264 compared.
 265 .SS "\fBstrcpy()\fR, \fBstrncpy()\fR, \fBstrlcpy()\fR"
 266 .sp
 267 .LP
 268 The \fBstrcpy()\fR function copies string \fIs2\fR to \fIs1\fR, including the
 269 terminating null character, stopping after the null character has been copied.
 270 The \fBstrncpy()\fR function copies exactly \fIn\fR bytes, truncating \fIs2\fR
 271 or adding null characters to \fIs1\fR if necessary. The result will not be
 272 null-terminated if the length of \fIs2\fR is \fIn\fR or more. Each function
 273 returns \fIs1\fR.  If copying takes place between objects that overlap, the
 274 behavior of \fBstrcpy()\fR, \fBstrncpy()\fR, and \fBstrlcpy()\fR is undefined.
 275 .sp
 276 .LP
 277 The \fBstrlcpy()\fR function copies  at most \fIdstsize\fR\(mi1 characters
 278 (\fIdstsize\fR being the  size of the  string buffer \fIdst\fR) from \fIsrc\fR
 279 to \fIdst\fR,  truncating \fIsrc\fR if necessary.  The  result is always
 280 null-terminated. The function returns \fBstrlen\fR(\fIsrc\fR). Buffer overflow
 281 can be checked as  follows:
 282 .sp
 283 .in +2
 284 .nf
 285 if (strlcpy(dst, src, dstsize) >= dstsize)
 286         return \(mi1;
 287 .fi
 288 .in -2
 289 
 290 .SS "\fBstrcspn()\fR, \fBstrspn()\fR"
 291 .sp
 292 .LP
 293 The \fBstrcspn()\fR function returns the length of the initial segment of
 294 string \fIs1\fR that consists entirely of characters not from string \fIs2\fR.
 295 The \fBstrspn()\fR function returns the length of the initial segment of string
 296 \fIs1\fR that consists entirely of characters from string \fIs2\fR.
 297 .SS "\fBstrdup()\fR"
 298 .sp
 299 .LP
 300 The \fBstrdup()\fR function returns a pointer to a new string that is a
 301 duplicate of the string pointed to by  \fIs1\fR. The returned pointer can be
 302 passed to \fBfree()\fR. The space for the new string is obtained using
 303 \fBmalloc\fR(3C). If the new string cannot be created, a null pointer is
 304 returned and \fBerrno\fR may be set to \fBENOMEM\fR to indicate that the
 305 storage space available is insufficient.
 306 .SS "\fBstrlen()\fR, \fBstrnlen()\fR"
 307 .sp
 308 .LP
 309 The \fBstrlen()\fR function returns the number of bytes in \fIs\fR, not
 310 including the terminating null character.
 311 .sp
 312 .LP
 313 The \fBstrnlen()\fR function returns the smaller of \fIn\fR or the number of
 314 bytes in \fIs\fR, not including the terminating null character. The
 315 \fBstrnlen()\fR function never examines more than \fIn\fR bytes of the string
 316 pointed to by \fIs\fR.
 317 .SS "\fBstrpbrk()\fR"
 318 .sp
 319 .LP
 320 The \fBstrpbrk()\fR function returns a pointer to the first occurrence in
 321 string \fIs1\fR of any character from string \fIs2\fR, or a null pointer if no
 322 character from \fIs2\fR exists in \fIs1\fR.
 323 .SS "\fBstrsep()\fR"
 324 .sp
 325 .LP
 326 The \fBstrsep()\fR function locates, in the null-terminated string referenced
 327 by *\fIstringp\fR, the first occurrence of any character in the string
 328 \fIdelim\fR (or the terminating `\e0' character) and replaces it with a `\e0'.
 329 The location of the next character after the delimiter character (or
 330 \fINULL\fR, if the end of the string was reached) is stored in *\fIstringp\fR.
 331 The original value of *\fIstringp\fR is returned.
 332 .sp
 333 .LP
 334 An ``empty'' field (one caused by two adjacent delimiter characters) can be
 335 detected by comparing the location referenced by the pointer returned by
 336 \fBstrsep()\fR to `\e0'.
 337 .sp
 338 .LP
 339 If *\fIstringp\fR is initially \fINULL\fR, \fBstrsep()\fR returns \fINULL\fR.
 340 .SS "\fBstrstr()\fR"
 341 .sp
 342 .LP
 343 The \fBstrstr()\fR function locates the first occurrence of the string \fIs2\fR
 344 (excluding the terminating null character) in string \fIs1\fR and returns a
 345 pointer to the located string, or a null pointer if the string is not found. If
 346 \fIs2\fR points to a string with zero length (that is, the string \fB""\fR),
 347 the function returns  \fIs1\fR.
 348 .SS "\fBstrtok()\fR"
 349 .sp
 350 .LP
 351 A sequence of calls to \fBstrtok()\fR breaks the string pointed to by \fIs1\fR
 352 into a sequence of tokens, each of which is delimited by a byte from the string
 353 pointed to by \fIs2\fR. The first call in the sequence has \fIs1\fR as its
 354 first argument, and is followed by calls with a null pointer as their first
 355 argument. The separator string pointed to by \fIs2\fR can be different from
 356 call to call.
 357 .sp
 358 .LP
 359 The first call in the sequence searches the string pointed to by \fIs1\fR for
 360 the first byte that is not contained in the current separator string pointed to
 361 by \fIs2\fR. If no such byte is found, then there are no tokens in the string
 362 pointed to by \fIs1\fR and \fBstrtok()\fR returns a null pointer. If such a
 363 byte is found, it is the start of the first token.
 364 .sp
 365 .LP
 366 The \fBstrtok()\fR function then searches from there for a byte that is
 367 contained in the current separator string. If no such byte is found, the
 368 current token extends to the end of the string pointed to by \fIs1\fR, and
 369 subsequent searches for a token return a null pointer. If such a byte is found,
 370 it is overwritten by a null byte that terminates the current token. The
 371 \fBstrtok()\fR function saves a pointer to the following byte in
 372 thread-specific data, from which the next search for a token starts.
 373 .sp
 374 .LP
 375 Each subsequent call, with a null pointer as the value of the first argument,
 376 starts searching from the saved pointer and behaves as described above.
 377 .sp
 378 .LP
 379 See Example 1, 2, and 3 in the \fBEXAMPLES\fR section for examples of
 380 \fBstrtok()\fR usage and the explanation in \fBNOTES\fR.
 381 .SS "\fBstrtok_r()\fR"
 382 .sp
 383 .LP
 384 The \fBstrtok_r()\fR function considers the null-terminated string \fIs1\fR as
 385 a sequence of zero or more text tokens separated by spans of one or more
 386 characters from the separator string \fIs2\fR. The argument \fIlasts\fR points
 387 to a user-provided pointer which points to stored information necessary for
 388 \fBstrtok_r()\fR to continue scanning the same string.
 389 .sp
 390 .LP
 391 In the first call to \fBstrtok_r()\fR, \fIs1\fR points to a null-terminated
 392 string, \fIs2\fR to a null-terminated string of separator characters, and the
 393 value pointed to by \fIlasts\fR is ignored. The \fBstrtok_r()\fR function
 394 returns a pointer to the first character of the first token, writes a null
 395 character into \fIs1\fR immediately following the returned token, and updates
 396 the pointer to which \fIlasts\fR points.
 397 .sp
 398 .LP
 399 In subsequent calls, \fIs1\fR is a null pointer and \fIlasts\fR is unchanged
 400 from the previous call so that subsequent calls move through the string
 401 \fIs1\fR, returning successive tokens until no tokens remain. The separator
 402 string \fIs2\fR can be different from call to call. When no token remains in
 403 \fIs1\fR, a null pointer is returned.
 404 .sp
 405 .LP
 406 See Example 3 in the \fBEXAMPLES\fR section for an example of \fBstrtok_r()\fR
 407 usage and the explanation in \fBNOTES\fR.
 408 .SH EXAMPLES
 409 .LP
 410 \fBExample 1 \fRSearch for word separators.
 411 .sp
 412 .LP
 413 The following example searches for tokens separated by space characters.
 414 
 415 .sp
 416 .in +2
 417 .nf
 418 #include <string.h>
 419 \&...
 420 char *token;
 421 char line[] = "LINE TO BE SEPARATED";
 422 char *search = " ";
 423 
 424 /* Token will point to "LINE". */
 425 token = strtok(line, search);
 426 
 427 /* Token will point to "TO". */
 428 token = strtok(NULL, search);
 429 .fi
 430 .in -2
 431 
 432 .LP
 433 \fBExample 2 \fRBreak a Line.
 434 .sp
 435 .LP
 436 The following example uses strtok to break a line into two character strings
 437 separated by any combination of SPACEs, TABs, or NEWLINEs.
 438 
 439 .sp
 440 .in +2
 441 .nf
 442 #include <string.h>
 443 \&...
 444 struct element {
 445        char *key;
 446        char *data;
 447 };
 448 \&...
 449 char line[LINE_MAX];
 450 char *key, *data;
 451 \&...
 452 key = strtok(line, " \en");
 453 data = strtok(NULL, " \en");
 454 .fi
 455 .in -2
 456 
 457 .LP
 458 \fBExample 3 \fRSearch for tokens.
 459 .sp
 460 .LP
 461 The following example uses both \fBstrtok()\fR and \fBstrtok_r()\fR to search
 462 for tokens separated by one or more characters from the string pointed to by
 463 the second argument, "/".
 464 
 465 .sp
 466 .in +2
 467 .nf
 468 #define __EXTENSIONS__
 469 #include <stdio.h>
 470 #include <string.h>
 471 
 472 int
 473 main() {
 474         char *buf="5/90/45";
 475         char *token;
 476         char *lasts;
 477 
 478         printf("tokenizing \e"%s\e" with strtok():\en", buf);
 479         if ((token = strtok(buf, "/")) != NULL) {
 480                 printf("token = "%s\e"\en", token);
 481                 while ((token = strtok(NULL, "/")) != NULL) {
 482                         printf("token = \e"%s\e"\en", token);
 483                 }
 484         }
 485 
 486         buf = "//5//90//45//";
 487         printf("\entokenizing \e"%s\e" with strtok_r():\en", buf);
 488         if ((token = strtok_r(buf, "/", &lasts)) != NULL) {
 489                 printf("token = \e"%s\e"\en", token);
 490                 while ((token = strtok_r(NULL, "/", &lasts)) != NULL) {
 491                         printf("token = \e"%s\e"\en", token);
 492                 }
 493         }
 494 }
 495 .fi
 496 .in -2
 497 
 498 .sp
 499 .LP
 500 When compiled and run, this example produces the following output:
 501 
 502 .sp
 503 .in +2
 504 .nf
 505 tokenizing "5/90/45" with \fBstrtok()\fR:
 506 token = "5"
 507 token = "90"
 508 token = "45"
 509 
 510 tokenizing "//5//90//45//" with \fBstrtok_r()\fR:
 511 token = "5"
 512 token = "90"
 513 token = "45"
 514 .fi
 515 .in -2
 516 
 517 .SH ATTRIBUTES
 518 .sp
 519 .LP
 520 See \fBattributes\fR(5) for descriptions of the following attributes:
 521 .sp
 522 
 523 .sp
 524 .TS
 525 box;
 526 c | c
 527 l | l .
 528 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 529 _
 530 Interface Stability     Committed
 531 _
 532 MT-Level        See below.
 533 _
 534 Standard        See below.
 535 .TE
 536 
 537 .sp
 538 .LP




 539 The \fBstrtok()\fR and \fBstrdup()\fR functions are MT-Safe. The remaining
 540 functions are Async-Signal-Safe.
 541 .sp
 542 .LP
 543 For all except \fBstrlcat()\fR, \fBstrlcpy()\fR, and \fBstrsep()\fR, see
 544 \fBstandards\fR(5).
 545 .SH SEE ALSO
 546 .sp
 547 .LP
 548 \fBmalloc\fR(3C), \fBsetlocale\fR(3C), \fBstrxfrm\fR(3C), \fBattributes\fR(5),
 549 \fBstandards\fR(5)

 550 .SH NOTES
 551 .sp
 552 .LP
 553 When compiling multithreaded applications, the \fB_REENTRANT\fR flag must be
 554 defined on the compile line. This flag should only be used in multithreaded
 555 applications.
 556 .sp
 557 .LP
 558 A single-threaded application can gain access to \fBstrtok_r()\fR only by
 559 defining \fB__EXTENSIONS__\fR or by defining \fB_POSIX_C_SOURCE\fR to a value
 560 greater than or equal to 199506L.
 561 .sp
 562 .LP
 563 All of these functions assume the default locale ``C.'' For some locales,

 564 \fBstrxfrm\fR(3C) should be applied to the strings before they are passed to
 565 the functions.
 566 .sp
 567 .LP
 568 The \fBstrtok()\fR function is safe to use in multithreaded applications
 569 because it saves its internal state in a thread-specific data area.  However,
 570 its use is discouraged, even for single-threaded applications. The
 571 \fBstrtok_r()\fR function should be used instead.
 572 .sp
 573 .LP
 574 Do not pass the address of a character string literal as the argument \fIs1\fR
 575 to either \fBstrtok()\fR or \fBstrtok_r()\fR. Similarly, do not pass a pointer
 576 to the address of a character string literal as the argument \fIstringp\fR to
 577 \fBstrsep()\fR. These functions can modify the storage pointed to by \fIs1\fR
 578 in the case of \fBstrtok()\fR and \fBstrtok_r()\fR or *\fIstringp\fR in the
 579 case of \fBstrsep()\fR. The C99 standard specifies that attempting to modify
 580 the storage occupied by a string literal results in undefined behavior. This
 581 allows compilers (including \fBgcc\fR and the Sun Studio compilers when the
 582 \fB-xstrconst\fR flag is used) to place string literals in read-only memory.
 583 Note that in Example 1 above, this problem is avoided because the variable
 584 \fIline\fR is declared as a writable array of type \fBchar\fR that is
 585 initialized by a string literal rather than a pointer to \fBchar\fR that points
 586 to a string literal.
   1 '\" te
   2 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
   3 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
   4 .\" Copyright 1989 AT&T
   5 .\" Portions Copyright (c) 1994 Man-cgi 1.15, Panagiotis Christias (christia@softlab.ntua.gr)
   6 .\" Portions Copyright (c) 1996-2008 Modified for NetBSD by Kimmo Suominen (kimmo@suominen.com)
   7 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
   8 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   9 .\" http://www.opengroup.org/bookstore/.
  10 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
  11 .\"  This notice shall appear on any product containing this material.
  12 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
  13 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  14 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  15 .TH STRING 3C "Jun 21, 2013"
  16 .SH NAME
  17 string, strcasecmp, strcasecmp_l, strncasecmp, strncasecmp_l, strcat, strncat,
  18 strlcat, strchr, strrchr,
  19 strcmp, strncmp, strcpy, strncpy, strlcpy, strcspn, strspn, strdup, strlen,
  20 strnlen, strpbrk, strsep, strstr, strtok, strtok_r \- string operations
  21 .SH SYNOPSIS
  22 .LP
  23 .nf
  24 #include <strings.h>
  25 
  26 \fBint\fR \fBstrcasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
  27 .fi

  28 .LP
  29 .nf
  30 \fBint\fR \fBstrcasecmp_l\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBlocale_t\fR \fIloc\fR);
  31 .fi

  32 .LP
  33 .nf
  34 \fBint\fR \fBstrncasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR);
  35 .fi

  36 .LP
  37 .nf
  38 \fBint\fR \fBstrncasecmp_l\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR, \fBlocale_t\fR \fIloc\fR);
  39 .fi

  40 .LP
  41 .nf
  42 #include <string.h>
  43 
  44 \fBchar *\fR\fBstrcat\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
  45 .fi

  46 .LP
  47 .nf
  48 \fBchar *\fR\fBstrncat\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR, \fBsize_t\fR \fIn\fR);
  49 .fi

  50 .LP
  51 .nf
  52 \fBsize_t\fR \fBstrlcat\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR);
  53 .fi

  54 .LP
  55 .nf
  56 \fBchar *\fR\fBstrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
  57 .fi

  58 .LP
  59 .nf
  60 \fBchar *\fR\fBstrrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
  61 .fi

  62 .LP
  63 .nf
  64 \fBint\fR \fBstrcmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
  65 .fi

  66 .LP
  67 .nf
  68 \fBint\fR \fBstrncmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR);
  69 .fi

  70 .LP
  71 .nf
  72 \fBchar *\fR\fBstrcpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
  73 .fi

  74 .LP
  75 .nf
  76 \fBchar *\fR\fBstrncpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR, \fBsize_t\fR \fIn\fR);
  77 .fi

  78 .LP
  79 .nf
  80 \fBsize_t\fR \fBstrlcpy\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR);
  81 .fi

  82 .LP
  83 .nf
  84 \fBsize_t\fR \fBstrcspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
  85 .fi

  86 .LP
  87 .nf
  88 \fBsize_t\fR \fBstrspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
  89 .fi

  90 .LP
  91 .nf
  92 \fBchar *\fR\fBstrdup\fR(\fBconst char *\fR\fIs1\fR);
  93 .fi

  94 .LP
  95 .nf
  96 \fBsize_t\fR \fBstrlen\fR(\fBconst char *\fR\fIs\fR);
  97 .fi

  98 .LP
  99 .nf
 100 \fBsize_t\fR \fBstrnlen\fR(\fBconst char *\fR\fIs\fR, \fBsize_t\fR \fIn\fR);
 101 .fi

 102 .LP
 103 .nf
 104 \fBchar *\fR\fBstrpbrk\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 105 .fi

 106 .LP
 107 .nf
 108 \fBchar *\fR\fBstrsep\fR(\fBchar **\fR\fIstringp\fR, \fBconst char *\fR\fIdelim\fR);
 109 .fi

 110 .LP
 111 .nf
 112 \fBchar *\fR\fBstrstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 113 .fi

 114 .LP
 115 .nf
 116 \fBchar *\fR\fBstrtok\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
 117 .fi

 118 .LP
 119 .nf
 120 \fBchar *\fR\fBstrtok_r\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR,
 121      \fBchar **restrict\fR \fIlasts\fR);
 122 .fi

 123 .SS "ISO C++"
 124 .LP
 125 .nf
 126 #include <string.h>
 127 
 128 \fBconst char *\fR\fBstrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
 129 .fi

 130 .LP
 131 .nf
 132 \fBconst char *\fR\fBstrpbrk\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 133 .fi

 134 .LP
 135 .nf
 136 \fBconst char *\fR\fBstrrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
 137 .fi

 138 .LP
 139 .nf
 140 \fBconst char *\fR\fBstrstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 141 .fi

 142 .LP
 143 .nf
 144 #include <cstring>
 145 
 146 \fBchar *std::\fR\fBstrchr\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIc\fR);
 147 .fi

 148 .LP
 149 .nf
 150 \fBchar *std::\fR\fBstrpbrk\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 151 .fi

 152 .LP
 153 .nf
 154 \fBchar *std::\fR\fBstrrchr\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIc\fR);
 155 .fi

 156 .LP
 157 .nf
 158 \fBchar *std::\fR\fBstrstr\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 159 .fi

 160 .SH DESCRIPTION

 161 .LP
 162 The arguments \fIs\fR, \fIs1\fR, and \fIs2\fR point to strings (arrays of
 163 characters terminated by a null character). The \fBstrcat()\fR,
 164 \fBstrncat()\fR, \fBstrlcat()\fR, \fBstrcpy()\fR, \fBstrncpy()\fR,
 165 \fBstrlcpy()\fR, \fBstrsep()\fR, \fBstrtok()\fR, and \fBstrtok_r()\fR functions
 166 all alter their first argument. Additionally, the \fBstrcat()\fR and
 167 \fBstrcpy()\fR functions do not check for overflow of the array.
 168 .SS "\fBstrcasecmp()\fR, \fBstrncasecmp()\fR"
 169 .sp
 170 .LP
 171 The \fBstrcasecmp()\fR and \fBstrncasecmp()\fR functions are case-insensitive
 172 versions of  \fBstrcmp()\fR and \fBstrncmp()\fR respectively, described below.
 173 .LP
 174 The \fBstrcasecmp()\fR and \fBstrncasecmp()\fR functions compare two strings
 175 byte-by-byte, after
 176 converting each upper-case character to lower-case (as determined by the
 177 \fBLC_CTYPE\fR category of the current locale).  Note that neither the contents 
 178 pointed to by \fIs1\fR nor \fIs2\fR are modified.
 179 .LP
 180 The functions return an integer
 181 greater than, equal to, or less than 0, if the string pointed to by \fIs1\fR
 182 is greater than, equal to, or less than the string pointed to by \fIs2\fR
 183 respectively. The sign of a non-zero return value is determined  by the sign of
 184 the difference between the values of the first pair of bytes that differ in the
 185 .LP
 186 The \fBstrncasecmp()\fR function examines at most \fIn\fR bytes from each
 187 string.
 188 .SS "\fBstrcasecmp_l()\fR, \fBstrncasecmp_l()\fR"

 189 .LP
 190 The \fBstrcasecmp_l()\fR and \fBstrncasecmp_l()\fR functions behave identically
 191 to \fBstrcasecmp()\fR and \fBstrncasecmp()\fR, except instead of operating in
 192 the current locale, they instead operate in the locale specified by \fIloc\fR.
 193 .SS "\fBstrcat()\fR, \fBstrncat()\fR, \fBstrlcat()\fR"

 194 .LP
 195 The \fBstrcat()\fR function appends a copy of string \fIs2\fR, including the
 196 terminating null character, to the end of string \fIs1\fR. The \fBstrncat()\fR
 197 function appends at most \fIn\fR characters. Each returns a pointer to the
 198 null-terminated result. The initial character of  \fIs2\fR overrides the null
 199 character at the end of \fIs1\fR. If copying takes place between objects that
 200 overlap, the behavior of \fBstrcat()\fR, \fBstrncat()\fR, and \fBstrlcat()\fR
 201 is undefined.

 202 .LP
 203 The \fBstrlcat()\fR function appends  at most
 204 (\fIdstsize\fR-\fBstrlen\fR(\fIdst\fR)-1) characters of \fIsrc\fR to \fIdst\fR
 205 (\fIdstsize\fR being the  size of the  string buffer \fIdst\fR). If the string
 206 pointed to by \fIdst\fR contains a null-terminated string that fits into
 207 \fIdstsize\fR bytes when \fBstrlcat()\fR is called, the string pointed to by
 208 \fIdst\fR will be a null-terminated string that fits in \fIdstsize\fR bytes
 209 (including the terminating null character) when it completes, and the initial
 210 character of \fIsrc\fR will override the null character at  the end of
 211 \fIdst\fR. If the string pointed to by \fIdst\fR is longer than \fIdstsize\fR
 212 bytes when \fBstrlcat()\fR is called, the string pointed to by \fIdst\fR will
 213 not be changed. The function returns
 214 \fBmin\fR{\fIdstsize\fR,\fBstrlen\fR(\fIdst\fR)}+\fBstrlen\fR(\fIsrc\fR).
 215 Buffer overflow can be checked as  follows:
 216 .sp
 217 .in +2
 218 .nf
 219 if (strlcat(dst, src, dstsize) >= dstsize)
 220         return \(mi1;
 221 .fi
 222 .in -2

 223 .SS "\fBstrchr()\fR, \fBstrrchr()\fR"

 224 .LP
 225 The \fBstrchr()\fR function returns a pointer to the first occurrence of
 226 \fIc\fR (converted to a  \fBchar\fR) in string \fIs\fR, or a null pointer if
 227 \fIc\fR does not occur in the string. The \fBstrrchr()\fR function returns a
 228 pointer to the last occurrence of \fIc\fR. The null character terminating a
 229 string is considered to be part of the string.
 230 .SS "\fBstrcmp()\fR, \fBstrncmp()\fR"

 231 .LP
 232 The \fBstrcmp()\fR function compares two strings byte-by-byte, according to the
 233 ordering of your machine's character set.  The function returns an integer
 234 greater than, equal to, or less than 0, if  the string pointed to by \fIs1\fR
 235 is greater than, equal to, or less than the string pointed to by \fIs2\fR
 236 respectively. The sign of a non-zero return value is determined  by the sign of
 237 the difference between the values of the first pair of bytes that differ in the
 238 strings being compared. The \fBstrncmp()\fR function makes the same comparison
 239 but looks at a maximum of \fIn\fR bytes. Bytes following a null byte are not
 240 compared.
 241 .SS "\fBstrcpy()\fR, \fBstrncpy()\fR, \fBstrlcpy()\fR"

 242 .LP
 243 The \fBstrcpy()\fR function copies string \fIs2\fR to \fIs1\fR, including the
 244 terminating null character, stopping after the null character has been copied.
 245 The \fBstrncpy()\fR function copies exactly \fIn\fR bytes, truncating \fIs2\fR
 246 or adding null characters to \fIs1\fR if necessary. The result will not be
 247 null-terminated if the length of \fIs2\fR is \fIn\fR or more. Each function
 248 returns \fIs1\fR.  If copying takes place between objects that overlap, the
 249 behavior of \fBstrcpy()\fR, \fBstrncpy()\fR, and \fBstrlcpy()\fR is undefined.

 250 .LP
 251 The \fBstrlcpy()\fR function copies  at most \fIdstsize\fR\(mi1 characters
 252 (\fIdstsize\fR being the  size of the  string buffer \fIdst\fR) from \fIsrc\fR
 253 to \fIdst\fR,  truncating \fIsrc\fR if necessary.  The  result is always
 254 null-terminated. The function returns \fBstrlen\fR(\fIsrc\fR). Buffer overflow
 255 can be checked as  follows:
 256 .sp
 257 .in +2
 258 .nf
 259 if (strlcpy(dst, src, dstsize) >= dstsize)
 260         return \(mi1;
 261 .fi
 262 .in -2
 263 
 264 .SS "\fBstrcspn()\fR, \fBstrspn()\fR"

 265 .LP
 266 The \fBstrcspn()\fR function returns the length of the initial segment of
 267 string \fIs1\fR that consists entirely of characters not from string \fIs2\fR.
 268 The \fBstrspn()\fR function returns the length of the initial segment of string
 269 \fIs1\fR that consists entirely of characters from string \fIs2\fR.
 270 .SS "\fBstrdup()\fR"

 271 .LP
 272 The \fBstrdup()\fR function returns a pointer to a new string that is a
 273 duplicate of the string pointed to by  \fIs1\fR. The returned pointer can be
 274 passed to \fBfree()\fR. The space for the new string is obtained using
 275 \fBmalloc\fR(3C). If the new string cannot be created, a null pointer is
 276 returned and \fBerrno\fR may be set to \fBENOMEM\fR to indicate that the
 277 storage space available is insufficient.
 278 .SS "\fBstrlen()\fR, \fBstrnlen()\fR"
 279 .sp

 280 The \fBstrlen()\fR function returns the number of bytes in \fIs\fR, not
 281 including the terminating null character.

 282 .LP
 283 The \fBstrnlen()\fR function returns the smaller of \fIn\fR or the number of
 284 bytes in \fIs\fR, not including the terminating null character. The
 285 \fBstrnlen()\fR function never examines more than \fIn\fR bytes of the string
 286 pointed to by \fIs\fR.
 287 .SS "\fBstrpbrk()\fR"

 288 .LP
 289 The \fBstrpbrk()\fR function returns a pointer to the first occurrence in
 290 string \fIs1\fR of any character from string \fIs2\fR, or a null pointer if no
 291 character from \fIs2\fR exists in \fIs1\fR.
 292 .SS "\fBstrsep()\fR"

 293 .LP
 294 The \fBstrsep()\fR function locates, in the null-terminated string referenced
 295 by *\fIstringp\fR, the first occurrence of any character in the string
 296 \fIdelim\fR (or the terminating `\e0' character) and replaces it with a `\e0'.
 297 The location of the next character after the delimiter character (or
 298 \fINULL\fR, if the end of the string was reached) is stored in *\fIstringp\fR.
 299 The original value of *\fIstringp\fR is returned.

 300 .LP
 301 An ``empty'' field (one caused by two adjacent delimiter characters) can be
 302 detected by comparing the location referenced by the pointer returned by
 303 \fBstrsep()\fR to `\e0'.

 304 .LP
 305 If *\fIstringp\fR is initially \fINULL\fR, \fBstrsep()\fR returns \fINULL\fR.
 306 .SS "\fBstrstr()\fR"

 307 .LP
 308 The \fBstrstr()\fR function locates the first occurrence of the string \fIs2\fR
 309 (excluding the terminating null character) in string \fIs1\fR and returns a
 310 pointer to the located string, or a null pointer if the string is not found. If
 311 \fIs2\fR points to a string with zero length (that is, the string \fB""\fR),
 312 the function returns  \fIs1\fR.
 313 .SS "\fBstrtok()\fR"

 314 .LP
 315 A sequence of calls to \fBstrtok()\fR breaks the string pointed to by \fIs1\fR
 316 into a sequence of tokens, each of which is delimited by a byte from the string
 317 pointed to by \fIs2\fR. The first call in the sequence has \fIs1\fR as its
 318 first argument, and is followed by calls with a null pointer as their first
 319 argument. The separator string pointed to by \fIs2\fR can be different from
 320 call to call.

 321 .LP
 322 The first call in the sequence searches the string pointed to by \fIs1\fR for
 323 the first byte that is not contained in the current separator string pointed to
 324 by \fIs2\fR. If no such byte is found, then there are no tokens in the string
 325 pointed to by \fIs1\fR and \fBstrtok()\fR returns a null pointer. If such a
 326 byte is found, it is the start of the first token.

 327 .LP
 328 The \fBstrtok()\fR function then searches from there for a byte that is
 329 contained in the current separator string. If no such byte is found, the
 330 current token extends to the end of the string pointed to by \fIs1\fR, and
 331 subsequent searches for a token return a null pointer. If such a byte is found,
 332 it is overwritten by a null byte that terminates the current token. The
 333 \fBstrtok()\fR function saves a pointer to the following byte in
 334 thread-specific data, from which the next search for a token starts.

 335 .LP
 336 Each subsequent call, with a null pointer as the value of the first argument,
 337 starts searching from the saved pointer and behaves as described above.

 338 .LP
 339 See Example 1, 2, and 3 in the \fBEXAMPLES\fR section for examples of
 340 \fBstrtok()\fR usage and the explanation in \fBNOTES\fR.
 341 .SS "\fBstrtok_r()\fR"

 342 .LP
 343 The \fBstrtok_r()\fR function considers the null-terminated string \fIs1\fR as
 344 a sequence of zero or more text tokens separated by spans of one or more
 345 characters from the separator string \fIs2\fR. The argument \fIlasts\fR points
 346 to a user-provided pointer which points to stored information necessary for
 347 \fBstrtok_r()\fR to continue scanning the same string.

 348 .LP
 349 In the first call to \fBstrtok_r()\fR, \fIs1\fR points to a null-terminated
 350 string, \fIs2\fR to a null-terminated string of separator characters, and the
 351 value pointed to by \fIlasts\fR is ignored. The \fBstrtok_r()\fR function
 352 returns a pointer to the first character of the first token, writes a null
 353 character into \fIs1\fR immediately following the returned token, and updates
 354 the pointer to which \fIlasts\fR points.

 355 .LP
 356 In subsequent calls, \fIs1\fR is a null pointer and \fIlasts\fR is unchanged
 357 from the previous call so that subsequent calls move through the string
 358 \fIs1\fR, returning successive tokens until no tokens remain. The separator
 359 string \fIs2\fR can be different from call to call. When no token remains in
 360 \fIs1\fR, a null pointer is returned.

 361 .LP
 362 See Example 3 in the \fBEXAMPLES\fR section for an example of \fBstrtok_r()\fR
 363 usage and the explanation in \fBNOTES\fR.
 364 .SH EXAMPLES
 365 .LP
 366 \fBExample 1 \fRSearch for word separators.

 367 .LP
 368 The following example searches for tokens separated by space characters.
 369 
 370 .sp
 371 .in +2
 372 .nf
 373 #include <string.h>
 374 \&...
 375 char *token;
 376 char line[] = "LINE TO BE SEPARATED";
 377 char *search = " ";
 378 
 379 /* Token will point to "LINE". */
 380 token = strtok(line, search);
 381 
 382 /* Token will point to "TO". */
 383 token = strtok(NULL, search);
 384 .fi
 385 .in -2
 386 
 387 .LP
 388 \fBExample 2 \fRBreak a Line.

 389 .LP
 390 The following example uses strtok to break a line into two character strings
 391 separated by any combination of SPACEs, TABs, or NEWLINEs.
 392 
 393 .sp
 394 .in +2
 395 .nf
 396 #include <string.h>
 397 \&...
 398 struct element {
 399        char *key;
 400        char *data;
 401 };
 402 \&...
 403 char line[LINE_MAX];
 404 char *key, *data;
 405 \&...
 406 key = strtok(line, " \en");
 407 data = strtok(NULL, " \en");
 408 .fi
 409 .in -2
 410 
 411 .LP
 412 \fBExample 3 \fRSearch for tokens.

 413 .LP
 414 The following example uses both \fBstrtok()\fR and \fBstrtok_r()\fR to search
 415 for tokens separated by one or more characters from the string pointed to by
 416 the second argument, "/".
 417 
 418 .sp
 419 .in +2
 420 .nf
 421 #define __EXTENSIONS__
 422 #include <stdio.h>
 423 #include <string.h>
 424 
 425 int
 426 main() {
 427         char *buf="5/90/45";
 428         char *token;
 429         char *lasts;
 430 
 431         printf("tokenizing \e"%s\e" with strtok():\en", buf);
 432         if ((token = strtok(buf, "/")) != NULL) {
 433                 printf("token = "%s\e"\en", token);
 434                 while ((token = strtok(NULL, "/")) != NULL) {
 435                         printf("token = \e"%s\e"\en", token);
 436                 }
 437         }
 438 
 439         buf = "//5//90//45//";
 440         printf("\entokenizing \e"%s\e" with strtok_r():\en", buf);
 441         if ((token = strtok_r(buf, "/", &lasts)) != NULL) {
 442                 printf("token = \e"%s\e"\en", token);
 443                 while ((token = strtok_r(NULL, "/", &lasts)) != NULL) {
 444                         printf("token = \e"%s\e"\en", token);
 445                 }
 446         }
 447 }
 448 .fi
 449 .in -2
 450 

 451 .LP
 452 When compiled and run, this example produces the following output:
 453 
 454 .sp
 455 .in +2
 456 .nf
 457 tokenizing "5/90/45" with \fBstrtok()\fR:
 458 token = "5"
 459 token = "90"
 460 token = "45"
 461 
 462 tokenizing "//5//90//45//" with \fBstrtok_r()\fR:
 463 token = "5"
 464 token = "90"
 465 token = "45"
 466 .fi
 467 .in -2
 468 
 469 .SH ATTRIBUTES

 470 .LP
 471 See \fBattributes\fR(5) for descriptions of the following attributes:



 472 .TS
 473 box;
 474 c | c
 475 l | l .
 476 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 477 _
 478 Interface Stability     See below.
 479 _
 480 MT-Level        See below.
 481 _
 482 Standard        See below.
 483 .TE
 484 

 485 .LP
 486 The
 487 \fBstrlcat()\fR, \fBstrlcpy()\fR, and \fBstrsep()\fR functions are Committed.
 488 All the rest are Standard.
 489 .LP
 490 The \fBstrtok()\fR and \fBstrdup()\fR functions are MT-Safe. The remaining
 491 functions are Async-Signal-Safe.

 492 .LP
 493 For all except \fBstrlcat()\fR, \fBstrlcpy()\fR, and \fBstrsep()\fR, see
 494 \fBstandards\fR(5).
 495 .SH SEE ALSO

 496 .LP
 497 \fBmalloc\fR(3C),
 498 \fBnewlocale(3C), \fBsetlocale\fR(3C), \fBstrxfrm\fR(3C), \fBuselocale\fR(3C),
 499 \fBattributes\fR(5), \fBstandards\fR(5)
 500 .SH NOTES

 501 .LP
 502 When compiling multithreaded applications, the \fB_REENTRANT\fR flag must be
 503 defined on the compile line. This flag should only be used in multithreaded
 504 applications.

 505 .LP
 506 A single-threaded application can gain access to \fBstrtok_r()\fR only by
 507 defining \fB__EXTENSIONS__\fR or by defining \fB_POSIX_C_SOURCE\fR to a value
 508 greater than or equal to 199506L.

 509 .LP
 510 Except where noted otherwise, all of these functions assume the default
 511 locale ``C.'' For some locales,
 512 \fBstrxfrm\fR(3C) should be applied to the strings before they are passed to
 513 the functions.

 514 .LP
 515 The \fBstrtok()\fR function is safe to use in multithreaded applications
 516 because it saves its internal state in a thread-specific data area.  However,
 517 its use is discouraged, even for single-threaded applications. The
 518 \fBstrtok_r()\fR function should be used instead.

 519 .LP
 520 Do not pass the address of a character string literal as the argument \fIs1\fR
 521 to either \fBstrtok()\fR or \fBstrtok_r()\fR. Similarly, do not pass a pointer
 522 to the address of a character string literal as the argument \fIstringp\fR to
 523 \fBstrsep()\fR. These functions can modify the storage pointed to by \fIs1\fR
 524 in the case of \fBstrtok()\fR and \fBstrtok_r()\fR or *\fIstringp\fR in the
 525 case of \fBstrsep()\fR. The C99 standard specifies that attempting to modify
 526 the storage occupied by a string literal results in undefined behavior. This
 527 allows compilers (including \fBgcc\fR and the Sun Studio compilers when the
 528 \fB-xstrconst\fR flag is used) to place string literals in read-only memory.
 529 Note that in Example 1 above, this problem is avoided because the variable
 530 \fIline\fR is declared as a writable array of type \fBchar\fR that is
 531 initialized by a string literal rather than a pointer to \fBchar\fR that points
 532 to a string literal.