1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
  45 .\" Portions Copyright (c) 1994 Man-cgi 1.15, Panagiotis Christias (christia@softlab.ntua.gr)
  46 .\" Portions Copyright (c) 1996-2008 Modified for NetBSD by Kimmo Suominen (kimmo@suominen.com)
  47 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
  48 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  49 .\" Copyright (c) 2014, Joyent, Inc.
  50 .\"
  51 .TH STRING 3C "Mar 23, 2016"
  52 .SH NAME
  53 string, strcasecmp, strcasecmp_l, strncasecmp, strncasecmp_l, strcat, strncat,
  54 strlcat, strchr, strchrnul, strrchr, strcmp, strncmp, stpcpy, stpncpy, strcpy,
  55 strncpy, strlcpy, strcspn, strspn, strdup, strndup, strdupa, strndupa, strlen,
  56 strnlen, strpbrk, strsep, strstr, strnstr, strcasestr, strtok, strtok_r \-
  57 string operations
  58 .SH SYNOPSIS
  59 .LP
  60 .nf
  61 #include <strings.h>
  62 
  63 \fBint\fR \fBstrcasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
  64 .fi
  65 .LP
  66 .nf
  67 \fBint\fR \fBstrcasecmp_l\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBlocale_t\fR \fIloc\fR);
  68 .fi
  69 .LP
  70 .nf
  71 \fBint\fR \fBstrncasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR);
  72 .fi
  73 .LP
  74 .nf
  75 \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);
  76 .fi
  77 .LP
  78 .nf
  79 #include <string.h>
  80 
  81 \fBchar *\fR\fBstrcat\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
  82 .fi
  83 .LP
  84 .nf
  85 \fBchar *\fR\fBstrncat\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR, \fBsize_t\fR \fIn\fR);
  86 .fi
  87 .LP
  88 .nf
  89 \fBsize_t\fR \fBstrlcat\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR);
  90 .fi
  91 .LP
  92 .nf
  93 \fBchar *\fR\fBstrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
  94 .fi
  95 .LP
  96 .nf
  97 \fBchar *\fR\fBstrrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
  98 .fi
  99 .LP
 100 .nf
 101 \fBint\fR \fBstrcmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 102 .fi
 103 .LP
 104 .nf
 105 \fBint\fR \fBstrncmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR);
 106 .fi
 107 .LP
 108 .nf
 109 \fBchar *\fR\fBstpcpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
 110 .fi
 111 .LP
 112 .nf
 113 \fBchar *\fR\fBstpncpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR, \fBsize_t\fR \fIn\fR);
 114 .fi
 115 .LP
 116 .nf
 117 \fBchar *\fR\fBstrcpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
 118 .fi
 119 .LP
 120 .nf
 121 \fBchar *\fR\fBstrncpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR, \fBsize_t\fR \fIn\fR);
 122 .fi
 123 .LP
 124 .nf
 125 \fBsize_t\fR \fBstrlcpy\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR);
 126 .fi
 127 .LP
 128 .nf
 129 \fBsize_t\fR \fBstrcspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 130 .fi
 131 .LP
 132 .nf
 133 \fBsize_t\fR \fBstrspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 134 .fi
 135 .LP
 136 .nf
 137 \fBchar *\fR\fBstrdup\fR(\fBconst char *\fR\fIs1\fR);
 138 .fi
 139 .LP
 140 .nf
 141 \fBchar *\fR\fBstrndup\fR(\fBconst char *\fR\fIs1\fR, \fBsize_t\fR \fIn\fR);
 142 .fi
 143 .LP
 144 .nf
 145 \fBchar *\fR\fBstrdupa\fR(\fBconst char *\fR\fIs1\fR);
 146 .fi
 147 .LP
 148 .nf
 149 \fBchar *\fR\fBstrndupa\fR(\fBconst char *\fR\fIs1\fR, \fBsize_t\fR \fIn\fR);
 150 .fi
 151 .LP
 152 .nf
 153 \fBsize_t\fR \fBstrlen\fR(\fBconst char *\fR\fIs\fR);
 154 .fi
 155 .LP
 156 .nf
 157 \fBsize_t\fR \fBstrnlen\fR(\fBconst char *\fR\fIs\fR, \fBsize_t\fR \fIn\fR);
 158 .fi
 159 .LP
 160 .nf
 161 \fBchar *\fR\fBstrpbrk\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 162 .fi
 163 .LP
 164 .nf
 165 \fBchar *\fR\fBstrsep\fR(\fBchar **\fR\fIstringp\fR, \fBconst char *\fR\fIdelim\fR);
 166 .fi
 167 .LP
 168 .nf
 169 \fBchar *\fR\fBstrstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 170 .fi
 171 .LP
 172 .nf
 173 \fBchar *\fR\fBstrnstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR);
 174 .fi
 175 .LP
 176 .nf
 177 \fBchar *\fR\fBstrcasestr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 178 .fi
 179 .LP
 180 .nf
 181 \fBchar *\fR\fBstrcasestr_l\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBlocale_t\fR \fIloc\fR);
 182 .fi
 183 .LP
 184 .nf
 185 \fBchar *\fR\fBstrtok\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
 186 .fi
 187 .LP
 188 .nf
 189 \fBchar *\fR\fBstrtok_r\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR,
 190      \fBchar **restrict\fR \fIlasts\fR);
 191 .fi
 192 .SS "ISO C++"
 193 .LP
 194 .nf
 195 #include <string.h>
 196 
 197 \fBconst char *\fR\fBstrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
 198 .fi
 199 .LP
 200 .nf
 201 \fBconst char *\fR\fBstrchrnul\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
 202 .fi
 203 .LP
 204 .nf
 205 \fBconst char *\fR\fBstrpbrk\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 206 .fi
 207 .LP
 208 .nf
 209 \fBconst char *\fR\fBstrrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
 210 .fi
 211 .LP
 212 .nf
 213 \fBconst char *\fR\fBstrstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 214 .fi
 215 .LP
 216 .nf
 217 #include <cstring>
 218 
 219 \fBchar *std::\fR\fBstrchr\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIc\fR);
 220 .fi
 221 .LP
 222 .nf
 223 \fBchar *std::\fR\fBstrpbrk\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 224 .fi
 225 .LP
 226 .nf
 227 \fBchar *std::\fR\fBstrrchr\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIc\fR);
 228 .fi
 229 .LP
 230 .nf
 231 \fBchar *std::\fR\fBstrstr\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 232 .fi
 233 .SH DESCRIPTION
 234 .LP
 235 The arguments \fIs\fR, \fIs1\fR, and \fIs2\fR point to strings (arrays of
 236 characters terminated by a null character). The \fBstrcat()\fR, \fBstrncat()\fR,
 237 \fBstrlcat()\fR, \fBstrcpy()\fR, \fBstpcpy()\fR, \fBstpncpy()\fR,
 238 \fBstrncpy()\fR, \fBstrlcpy()\fR, \fBstrsep()\fR, \fBstrtok()\fR, and
 239 \fBstrtok_r()\fR functions all alter their first argument. Additionally, the
 240 \fBstrcat()\fR, \fBstpcpy()\fR, and \fBstrcpy()\fR functions do not check for
 241 overflow of the array.
 242 .SS "\fBstrcasecmp()\fR, \fBstrncasecmp()\fR"
 243 .LP
 244 The \fBstrcasecmp()\fR and \fBstrncasecmp()\fR functions are case-insensitive
 245 versions of  \fBstrcmp()\fR and \fBstrncmp()\fR respectively, described below.
 246 .LP
 247 The \fBstrcasecmp()\fR and \fBstrncasecmp()\fR functions compare two strings
 248 byte-by-byte, after
 249 converting each upper-case character to lower-case (as determined by the
 250 \fBLC_CTYPE\fR category of the current locale).  Note that neither the contents
 251 pointed to by \fIs1\fR nor \fIs2\fR are modified.
 252 .LP
 253 The functions return an integer
 254 greater than, equal to, or less than 0, if the string pointed to by \fIs1\fR
 255 is greater than, equal to, or less than the string pointed to by \fIs2\fR
 256 respectively. The sign of a non-zero return value is determined  by the sign of
 257 the difference between the values of the first pair of bytes that differ in the
 258 .LP
 259 The \fBstrncasecmp()\fR function examines at most \fIn\fR bytes from each
 260 string.
 261 .SS "\fBstrcasecmp_l()\fR, \fBstrncasecmp_l()\fR"
 262 .LP
 263 The \fBstrcasecmp_l()\fR and \fBstrncasecmp_l()\fR functions behave identically
 264 to \fBstrcasecmp()\fR and \fBstrncasecmp()\fR, except instead of operating in
 265 the current locale, they instead operate in the locale specified by \fIloc\fR.
 266 .SS "\fBstrcat()\fR, \fBstrncat()\fR, \fBstrlcat()\fR"
 267 .LP
 268 The \fBstrcat()\fR function appends a copy of string \fIs2\fR, including the
 269 terminating null character, to the end of string \fIs1\fR. The \fBstrncat()\fR
 270 function appends at most \fIn\fR characters of \fIs2\fR to \fIs1\fR, not
 271 including any terminating null character, and then appends a null character.
 272 Each returns a pointer to the null-terminated result. The initial character of
 273 \fIs2\fR overrides the null character at the end of \fIs1\fR. If copying takes
 274 place between objects that overlap, the behavior of \fBstrcat()\fR,
 275 \fBstrncat()\fR, and \fBstrlcat()\fR is undefined.
 276 .LP
 277 The \fBstrlcat()\fR function appends  at most
 278 (\fIdstsize\fR-\fBstrlen\fR(\fIdst\fR)-1) characters of \fIsrc\fR to \fIdst\fR
 279 (\fIdstsize\fR being the  size of the  string buffer \fIdst\fR). If the string
 280 pointed to by \fIdst\fR contains a null-terminated string that fits into
 281 \fIdstsize\fR bytes when \fBstrlcat()\fR is called, the string pointed to by
 282 \fIdst\fR will be a null-terminated string that fits in \fIdstsize\fR bytes
 283 (including the terminating null character) when it completes, and the initial
 284 character of \fIsrc\fR will override the null character at  the end of
 285 \fIdst\fR. If the string pointed to by \fIdst\fR is longer than \fIdstsize\fR
 286 bytes when \fBstrlcat()\fR is called, the string pointed to by \fIdst\fR will
 287 not be changed. The function returns
 288 \fBmin\fR{\fIdstsize\fR,\fBstrlen\fR(\fIdst\fR)}+\fBstrlen\fR(\fIsrc\fR).
 289 Buffer overflow can be checked as  follows:
 290 .sp
 291 .in +2
 292 .nf
 293 if (strlcat(dst, src, dstsize) >= dstsize)
 294         return \(mi1;
 295 .fi
 296 .in -2
 297 .SS "\fBstrchr()\fR, \fBstrrchr()\fR, \fBstrchrnul()\fR"
 298 .LP
 299 The \fBstrchr()\fR function returns a pointer to the first occurrence of
 300 \fIc\fR (converted to a  \fBchar\fR) in string \fIs\fR, or a null pointer if
 301 \fIc\fR does not occur in the string. The \fBstrrchr()\fR function returns a
 302 pointer to the last occurrence of \fIc\fR. The null character terminating a
 303 string is considered to be part of the string. The \fBstrchrnul()\fR function
 304 behaves similarly to \fBstrchr()\fR, except when the character \fBc\fR is not
 305 found, it returns a pointer to the null terminator of the string \fBs\fR and not
 306 a null pointer.
 307 .SS "\fBstrcmp()\fR, \fBstrncmp()\fR"
 308 .LP
 309 The \fBstrcmp()\fR function compares two strings byte-by-byte, according to the
 310 ordering of your machine's character set.  The function returns an integer
 311 greater than, equal to, or less than 0, if  the string pointed to by \fIs1\fR
 312 is greater than, equal to, or less than the string pointed to by \fIs2\fR
 313 respectively. The sign of a non-zero return value is determined  by the sign of
 314 the difference between the values of the first pair of bytes that differ in the
 315 strings being compared. The \fBstrncmp()\fR function makes the same comparison
 316 but looks at a maximum of \fIn\fR bytes. Bytes following a null byte are not
 317 compared.
 318 .SS "\fBstrcpy()\fR, \fBstrncpy()\fR, \fBstrlcpy()\fR"
 319 .LP
 320 The \fBstrcpy()\fR function copies string \fIs2\fR to \fIs1\fR, including the
 321 terminating null character, stopping after the null character has been copied.
 322 The \fBstrncpy()\fR function copies exactly \fIn\fR bytes, truncating \fIs2\fR
 323 or adding null characters to \fIs1\fR if necessary. The result will not be
 324 null-terminated if the length of \fIs2\fR is \fIn\fR or more. Both the
 325 \fBstrcpy()\fR and \fBstrncpy()\fR functions return \fIs1\fR. If copying takes
 326 place between objects that overlap, the behavior of \fBstrcpy()\fR,
 327 \fBstrncpy()\fR, and \fBstrlcpy()\fR is undefined.
 328 .LP
 329 The \fBstrlcpy()\fR function copies  at most \fIdstsize\fR\(mi1 characters
 330 (\fIdstsize\fR being the  size of the  string buffer \fIdst\fR) from \fIsrc\fR
 331 to \fIdst\fR,  truncating \fIsrc\fR if necessary.  The  result is always
 332 null-terminated. The function returns \fBstrlen\fR(\fIsrc\fR). Buffer overflow
 333 can be checked as  follows:
 334 .sp
 335 .in +2
 336 .nf
 337 if (strlcpy(dst, src, dstsize) >= dstsize)
 338         return \(mi1;
 339 .fi
 340 .in -2
 341 .SS "\fBstpcpy()\fR, \fBstpncpy()\fR"
 342 .LP
 343 The \fBstpcpy()\fR and \fBstpncpy()\fR functions behave identically to
 344 \fBstrcpy()\fR and \fBstrncpy()\fR respectively; however, instead of returning a
 345 pointer to the beginning of \fIs1\fR, they return a pointer to the terminating
 346 null character.
 347 .SS "\fBstrcspn()\fR, \fBstrspn()\fR"
 348 .LP
 349 The \fBstrcspn()\fR function returns the length of the initial segment of
 350 string \fIs1\fR that consists entirely of characters not from string \fIs2\fR.
 351 The \fBstrspn()\fR function returns the length of the initial segment of string
 352 \fIs1\fR that consists entirely of characters from string \fIs2\fR.
 353 .SS "\fBstrdup()\fR, \fBstrndup()\fR, \fBstrdupa()\fR, \fBstrndupa()\fR"
 354 .LP
 355 The \fBstrdup()\fR function returns a pointer to a new string that is a
 356 duplicate of the string pointed to by  \fIs1\fR. The returned pointer can be
 357 passed to \fBfree()\fR. The space for the new string is obtained using
 358 \fBmalloc\fR(3C). If the new string cannot be created, a null pointer is
 359 returned and \fBerrno\fR may be set to \fBENOMEM\fR to indicate that the
 360 storage space available is insufficient. The \fBstrndup()\fR function is
 361 identical to \fBstrdup()\fR, except it copies at most \fIn\fR bytes from
 362 \fBs1\fR and ensures the copied string is always null terminated.
 363 .LP
 364 The functions \fBstrdupa()\fR and \fBstrndupa()\fR behave identically to
 365 \fBstrdup()\fR and \fBstrndup()\fR respectively; however, instead of allocating
 366 memory using \fBmalloc\fR(3C), they use \fBalloca\fR(3C). These functions are
 367 provided for compatibility only, their use is strongly discouraged due to their
 368 use of \fBalloca\fR(3C).
 369 .SS "\fBstrlen()\fR, \fBstrnlen()\fR"
 370 The \fBstrlen()\fR function returns the number of bytes in \fIs\fR, not
 371 including the terminating null character.
 372 .LP
 373 The \fBstrnlen()\fR function returns the smaller of \fIn\fR or the number of
 374 bytes in \fIs\fR, not including the terminating null character. The
 375 \fBstrnlen()\fR function never examines more than \fIn\fR bytes of the string
 376 pointed to by \fIs\fR.
 377 .SS "\fBstrpbrk()\fR"
 378 .LP
 379 The \fBstrpbrk()\fR function returns a pointer to the first occurrence in
 380 string \fIs1\fR of any character from string \fIs2\fR, or a null pointer if no
 381 character from \fIs2\fR exists in \fIs1\fR.
 382 .SS "\fBstrsep()\fR"
 383 .LP
 384 The \fBstrsep()\fR function locates, in the null-terminated string referenced
 385 by *\fIstringp\fR, the first occurrence of any character in the string
 386 \fIdelim\fR (or the terminating `\e0' character) and replaces it with a `\e0'.
 387 The location of the next character after the delimiter character (or
 388 \fINULL\fR, if the end of the string was reached) is stored in *\fIstringp\fR.
 389 The original value of *\fIstringp\fR is returned.
 390 .LP
 391 An ``empty'' field (one caused by two adjacent delimiter characters) can be
 392 detected by comparing the location referenced by the pointer returned by
 393 \fBstrsep()\fR to `\e0'.
 394 .LP
 395 If *\fIstringp\fR is initially \fINULL\fR, \fBstrsep()\fR returns \fINULL\fR.
 396 .SS "\fBstrstr()\fR, \fBstrnstr()\fR, \fBstrcasestr()\fR, \fBstrcasestr_l()\fR"
 397 .LP
 398 The \fBstrstr()\fR function locates the first occurrence of the string \fIs2\fR
 399 (excluding the terminating null character) in string \fIs1\fR and returns a
 400 pointer to the located string, or a null pointer if the string is not found. If
 401 \fIs2\fR points to a string with zero length (that is, the string \fB""\fR),
 402 the function returns  \fIs1\fR. The \fBstrnstr()\fR function performs the same
 403 search as \fBstrstr()\fR, but only considers up to \fIn\fR bytes of \fIs1\fR.
 404 Bytes following a null byte are not compared.
 405 .sp
 406 .LP
 407 The \fBstrcasestr()\fR and \fBstrcasestr_l()\fR functions are similar to
 408 \fBstrstr()\fR, but both functions ignore the case of both \fBs1\fR and
 409 \fBs2\fR. Where as the \fBstrcasestr()\fR function operates in the current
 410 locale, the \fBstrcasestr_l()\fR function operates in the locale specified by
 411 \fIloc\fR.
 412 .SS "\fBstrtok()\fR"
 413 .LP
 414 A sequence of calls to \fBstrtok()\fR breaks the string pointed to by \fIs1\fR
 415 into a sequence of tokens, each of which is delimited by a byte from the string
 416 pointed to by \fIs2\fR. The first call in the sequence has \fIs1\fR as its
 417 first argument, and is followed by calls with a null pointer as their first
 418 argument. The separator string pointed to by \fIs2\fR can be different from
 419 call to call.
 420 .LP
 421 The first call in the sequence searches the string pointed to by \fIs1\fR for
 422 the first byte that is not contained in the current separator string pointed to
 423 by \fIs2\fR. If no such byte is found, then there are no tokens in the string
 424 pointed to by \fIs1\fR and \fBstrtok()\fR returns a null pointer. If such a
 425 byte is found, it is the start of the first token.
 426 .LP
 427 The \fBstrtok()\fR function then searches from there for a byte that is
 428 contained in the current separator string. If no such byte is found, the
 429 current token extends to the end of the string pointed to by \fIs1\fR, and
 430 subsequent searches for a token return a null pointer. If such a byte is found,
 431 it is overwritten by a null byte that terminates the current token. The
 432 \fBstrtok()\fR function saves a pointer to the following byte in
 433 thread-specific data, from which the next search for a token starts.
 434 .LP
 435 Each subsequent call, with a null pointer as the value of the first argument,
 436 starts searching from the saved pointer and behaves as described above.
 437 .LP
 438 See Example 1, 2, and 3 in the \fBEXAMPLES\fR section for examples of
 439 \fBstrtok()\fR usage and the explanation in \fBNOTES\fR.
 440 .SS "\fBstrtok_r()\fR"
 441 .LP
 442 The \fBstrtok_r()\fR function considers the null-terminated string \fIs1\fR as
 443 a sequence of zero or more text tokens separated by spans of one or more
 444 characters from the separator string \fIs2\fR. The argument \fIlasts\fR points
 445 to a user-provided pointer which points to stored information necessary for
 446 \fBstrtok_r()\fR to continue scanning the same string.
 447 .LP
 448 In the first call to \fBstrtok_r()\fR, \fIs1\fR points to a null-terminated
 449 string, \fIs2\fR to a null-terminated string of separator characters, and the
 450 value pointed to by \fIlasts\fR is ignored. The \fBstrtok_r()\fR function
 451 returns a pointer to the first character of the first token, writes a null
 452 character into \fIs1\fR immediately following the returned token, and updates
 453 the pointer to which \fIlasts\fR points.
 454 .LP
 455 In subsequent calls, \fIs1\fR is a null pointer and \fIlasts\fR is unchanged
 456 from the previous call so that subsequent calls move through the string
 457 \fIs1\fR, returning successive tokens until no tokens remain. The separator
 458 string \fIs2\fR can be different from call to call. When no token remains in
 459 \fIs1\fR, a null pointer is returned.
 460 .LP
 461 See Example 3 in the \fBEXAMPLES\fR section for an example of \fBstrtok_r()\fR
 462 usage and the explanation in \fBNOTES\fR.
 463 .SH EXAMPLES
 464 .LP
 465 \fBExample 1 \fRSearch for word separators.
 466 .LP
 467 The following example searches for tokens separated by space characters.
 468 
 469 .sp
 470 .in +2
 471 .nf
 472 #include <string.h>
 473 \&...
 474 char *token;
 475 char line[] = "LINE TO BE SEPARATED";
 476 char *search = " ";
 477 
 478 /* Token will point to "LINE". */
 479 token = strtok(line, search);
 480 
 481 /* Token will point to "TO". */
 482 token = strtok(NULL, search);
 483 .fi
 484 .in -2
 485 
 486 .LP
 487 \fBExample 2 \fRBreak a Line.
 488 .LP
 489 The following example uses strtok to break a line into two character strings
 490 separated by any combination of SPACEs, TABs, or NEWLINEs.
 491 
 492 .sp
 493 .in +2
 494 .nf
 495 #include <string.h>
 496 \&...
 497 struct element {
 498        char *key;
 499        char *data;
 500 };
 501 \&...
 502 char line[LINE_MAX];
 503 char *key, *data;
 504 \&...
 505 key = strtok(line, " \en");
 506 data = strtok(NULL, " \en");
 507 .fi
 508 .in -2
 509 
 510 .LP
 511 \fBExample 3 \fRSearch for tokens.
 512 .LP
 513 The following example uses both \fBstrtok()\fR and \fBstrtok_r()\fR to search
 514 for tokens separated by one or more characters from the string pointed to by
 515 the second argument, "/".
 516 
 517 .sp
 518 .in +2
 519 .nf
 520 #define __EXTENSIONS__
 521 #include <stdio.h>
 522 #include <string.h>
 523 
 524 int
 525 main() {
 526         char *buf="5/90/45";
 527         char *token;
 528         char *lasts;
 529 
 530         printf("tokenizing \e"%s\e" with strtok():\en", buf);
 531         if ((token = strtok(buf, "/")) != NULL) {
 532                 printf("token = "%s\e"\en", token);
 533                 while ((token = strtok(NULL, "/")) != NULL) {
 534                         printf("token = \e"%s\e"\en", token);
 535                 }
 536         }
 537 
 538         buf = "//5//90//45//";
 539         printf("\entokenizing \e"%s\e" with strtok_r():\en", buf);
 540         if ((token = strtok_r(buf, "/", &lasts)) != NULL) {
 541                 printf("token = \e"%s\e"\en", token);
 542                 while ((token = strtok_r(NULL, "/", &lasts)) != NULL) {
 543                         printf("token = \e"%s\e"\en", token);
 544                 }
 545         }
 546 }
 547 .fi
 548 .in -2
 549 
 550 .LP
 551 When compiled and run, this example produces the following output:
 552 
 553 .sp
 554 .in +2
 555 .nf
 556 tokenizing "5/90/45" with \fBstrtok()\fR:
 557 token = "5"
 558 token = "90"
 559 token = "45"
 560 
 561 tokenizing "//5//90//45//" with \fBstrtok_r()\fR:
 562 token = "5"
 563 token = "90"
 564 token = "45"
 565 .fi
 566 .in -2
 567 
 568 .SH ATTRIBUTES
 569 .LP
 570 See \fBattributes\fR(5) for descriptions of the following attributes:
 571 .TS
 572 box;
 573 c | c
 574 l | l .
 575 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 576 _
 577 Interface Stability     See below.
 578 _
 579 MT-Level        See below.
 580 _
 581 Standard        See below.
 582 .TE
 583 
 584 .LP
 585 The
 586 \fBstrlcat()\fR, \fBstrlcpy()\fR, and \fBstrsep()\fR functions are Committed.
 587 All the rest are Standard.
 588 .LP
 589 The \fBstrtok()\fR, \fBstrdup()\fR, and \fBstrndup()\fR functions are MT-Safe.
 590 The remaining functions are Async-Signal-Safe.
 591 .LP
 592 For all except \fBstrlcat()\fR, \fBstrlcpy()\fR, and \fBstrsep()\fR, see
 593 \fBstandards\fR(5).
 594 .SH SEE ALSO
 595 .LP
 596 \fBmalloc\fR(3C),
 597 \fBnewlocale\fR(3C), \fBsetlocale\fR(3C), \fBstrxfrm\fR(3C),
 598 \fBuselocale\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)
 599 .SH NOTES
 600 .LP
 601 When compiling multithreaded applications, the \fB_REENTRANT\fR flag must be
 602 defined on the compile line. This flag should only be used in multithreaded
 603 applications.
 604 .LP
 605 A single-threaded application can gain access to \fBstrtok_r()\fR only by
 606 defining \fB__EXTENSIONS__\fR or by defining \fB_POSIX_C_SOURCE\fR to a value
 607 greater than or equal to 199506L.
 608 .LP
 609 Except where noted otherwise, all of these functions assume the default
 610 locale ``C.'' For some locales,
 611 \fBstrxfrm\fR(3C) should be applied to the strings before they are passed to
 612 the functions.
 613 .LP
 614 The \fBstrtok()\fR function is safe to use in multithreaded applications
 615 because it saves its internal state in a thread-specific data area.  However,
 616 its use is discouraged, even for single-threaded applications. The
 617 \fBstrtok_r()\fR function should be used instead.
 618 .LP
 619 Do not pass the address of a character string literal as the argument \fIs1\fR
 620 to either \fBstrtok()\fR or \fBstrtok_r()\fR. Similarly, do not pass a pointer
 621 to the address of a character string literal as the argument \fIstringp\fR to
 622 \fBstrsep()\fR. These functions can modify the storage pointed to by \fIs1\fR
 623 in the case of \fBstrtok()\fR and \fBstrtok_r()\fR or *\fIstringp\fR in the
 624 case of \fBstrsep()\fR. The C99 standard specifies that attempting to modify
 625 the storage occupied by a string literal results in undefined behavior. This
 626 allows compilers (including \fBgcc\fR and the Sun Studio compilers when the
 627 \fB-xstrconst\fR flag is used) to place string literals in read-only memory.
 628 Note that in Example 1 above, this problem is avoided because the variable
 629 \fIline\fR is declared as a writable array of type \fBchar\fR that is
 630 initialized by a string literal rather than a pointer to \fBchar\fR that points
 631 to a string literal.