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, strncasecmp, 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 \fBstrncasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR);
  30 .fi
  31 
  32 .LP
  33 .nf
  34 #include <string.h>
  35 
  36 \fBchar *\fR\fBstrcat\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
  37 .fi
  38 
  39 .LP
  40 .nf
  41 \fBchar *\fR\fBstrncat\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR, \fBsize_t\fR \fIn\fR);
  42 .fi
  43 
  44 .LP
  45 .nf
  46 \fBsize_t\fR \fBstrlcat\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR);
  47 .fi
  48 
  49 .LP
  50 .nf
  51 \fBchar *\fR\fBstrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
  52 .fi
  53 
  54 .LP
  55 .nf
  56 \fBchar *\fR\fBstrrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
  57 .fi
  58 
  59 .LP
  60 .nf
  61 \fBint\fR \fBstrcmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
  62 .fi
  63 
  64 .LP
  65 .nf
  66 \fBint\fR \fBstrncmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR);
  67 .fi
  68 
  69 .LP
  70 .nf
  71 \fBchar *\fR\fBstrcpy\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
  72 .fi
  73 
  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 
  79 .LP
  80 .nf
  81 \fBsize_t\fR \fBstrlcpy\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR);
  82 .fi
  83 
  84 .LP
  85 .nf
  86 \fBsize_t\fR \fBstrcspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
  87 .fi
  88 
  89 .LP
  90 .nf
  91 \fBsize_t\fR \fBstrspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
  92 .fi
  93 
  94 .LP
  95 .nf
  96 \fBchar *\fR\fBstrdup\fR(\fBconst char *\fR\fIs1\fR);
  97 .fi
  98 
  99 .LP
 100 .nf
 101 \fBsize_t\fR \fBstrlen\fR(\fBconst char *\fR\fIs\fR);
 102 .fi
 103 
 104 .LP
 105 .nf
 106 \fBsize_t\fR \fBstrnlen\fR(\fBconst char *\fR\fIs\fR, \fBsize_t\fR \fIn\fR);
 107 .fi
 108 
 109 .LP
 110 .nf
 111 \fBchar *\fR\fBstrpbrk\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 112 .fi
 113 
 114 .LP
 115 .nf
 116 \fBchar *\fR\fBstrsep\fR(\fBchar **\fR\fIstringp\fR, \fBconst char *\fR\fIdelim\fR);
 117 .fi
 118 
 119 .LP
 120 .nf
 121 \fBchar *\fR\fBstrstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 122 .fi
 123 
 124 .LP
 125 .nf
 126 \fBchar *\fR\fBstrtok\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR);
 127 .fi
 128 
 129 .LP
 130 .nf
 131 \fBchar *\fR\fBstrtok_r\fR(\fBchar *restrict\fR \fIs1\fR, \fBconst char *restrict\fR \fIs2\fR,
 132      \fBchar **restrict\fR \fIlasts\fR);
 133 .fi
 134 
 135 .SS "ISO C++"
 136 .LP
 137 .nf
 138 #include <string.h>
 139 
 140 \fBconst char *\fR\fBstrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
 141 .fi
 142 
 143 .LP
 144 .nf
 145 \fBconst char *\fR\fBstrpbrk\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 146 .fi
 147 
 148 .LP
 149 .nf
 150 \fBconst char *\fR\fBstrrchr\fR(\fBconst char *\fR\fIs\fR, \fBint\fR \fIc\fR);
 151 .fi
 152 
 153 .LP
 154 .nf
 155 \fBconst char *\fR\fBstrstr\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 156 .fi
 157 
 158 .LP
 159 .nf
 160 #include <cstring>
 161 
 162 \fBchar *std::\fR\fBstrchr\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIc\fR);
 163 .fi
 164 
 165 .LP
 166 .nf
 167 \fBchar *std::\fR\fBstrpbrk\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 168 .fi
 169 
 170 .LP
 171 .nf
 172 \fBchar *std::\fR\fBstrrchr\fR(\fBchar *\fR\fIs\fR, \fBint\fR \fIc\fR);
 173 .fi
 174 
 175 .LP
 176 .nf
 177 \fBchar *std::\fR\fBstrstr\fR(\fBchar *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR);
 178 .fi
 179 
 180 .SH DESCRIPTION
 181 .sp
 182 .LP
 183 The arguments \fIs\fR, \fIs1\fR, and \fIs2\fR point to strings (arrays of
 184 characters terminated by a null character). The \fBstrcat()\fR,
 185 \fBstrncat()\fR, \fBstrlcat()\fR, \fBstrcpy()\fR, \fBstrncpy()\fR,
 186 \fBstrlcpy()\fR, \fBstrsep()\fR, \fBstrtok()\fR, and \fBstrtok_r()\fR functions
 187 all alter their first argument. Additionally, the \fBstrcat()\fR and
 188 \fBstrcpy()\fR functions do not check for overflow of the array.
 189 .SS "\fBstrcasecmp()\fR, \fBstrncasecmp()\fR"
 190 .sp
 191 .LP
 192 The \fBstrcasecmp()\fR and \fBstrncasecmp()\fR functions are case-insensitive
 193 versions of  \fBstrcmp()\fR and \fBstrncmp()\fR respectively, described below.
 194 They assume the \fBASCII\fR character set and ignore differences in case when
 195 comparing lower and upper case characters.
 196 .SS "\fBstrcat()\fR, \fBstrncat()\fR, \fBstrlcat()\fR"
 197 .sp
 198 .LP
 199 The \fBstrcat()\fR function appends a copy of string \fIs2\fR, including the
 200 terminating null character, to the end of string \fIs1\fR. The \fBstrncat()\fR
 201 function appends at most \fIn\fR characters. Each returns a pointer to the
 202 null-terminated result. The initial character of  \fIs2\fR overrides the null
 203 character at the end of \fIs1\fR. If copying takes place between objects that
 204 overlap, the behavior of \fBstrcat()\fR, \fBstrncat()\fR, and \fBstrlcat()\fR
 205 is undefined.
 206 .sp
 207 .LP
 208 The \fBstrlcat()\fR function appends  at most
 209 (\fIdstsize\fR-\fBstrlen\fR(\fIdst\fR)-1) characters of \fIsrc\fR to \fIdst\fR
 210 (\fIdstsize\fR being the  size of the  string buffer \fIdst\fR). If the string
 211 pointed to by \fIdst\fR contains a null-terminated string that fits into
 212 \fIdstsize\fR bytes when \fBstrlcat()\fR is called, the string pointed to by
 213 \fIdst\fR will be a null-terminated string that fits in \fIdstsize\fR bytes
 214 (including the terminating null character) when it completes, and the initial
 215 character of \fIsrc\fR will override the null character at  the end of
 216 \fIdst\fR. If the string pointed to by \fIdst\fR is longer than \fIdstsize\fR
 217 bytes when \fBstrlcat()\fR is called, the string pointed to by \fIdst\fR will
 218 not be changed. The function returns
 219 \fBmin\fR{\fIdstsize\fR,\fBstrlen\fR(\fIdst\fR)}+\fBstrlen\fR(\fIsrc\fR).
 220 Buffer overflow can be checked as  follows:
 221 .sp
 222 .in +2
 223 .nf
 224 if (strlcat(dst, src, dstsize) >= dstsize)
 225         return \(mi1;
 226 .fi
 227 .in -2
 228 
 229 .SS "\fBstrchr()\fR, \fBstrrchr()\fR"
 230 .sp
 231 .LP
 232 The \fBstrchr()\fR function returns a pointer to the first occurrence of
 233 \fIc\fR (converted to a  \fBchar\fR) in string \fIs\fR, or a null pointer if
 234 \fIc\fR does not occur in the string. The \fBstrrchr()\fR function returns a
 235 pointer to the last occurrence of \fIc\fR. The null character terminating a
 236 string is considered to be part of the string.
 237 .SS "\fBstrcmp()\fR, \fBstrncmp()\fR"
 238 .sp
 239 .LP
 240 The \fBstrcmp()\fR function compares two strings byte-by-byte, according to the
 241 ordering of your machine's character set.  The function returns an integer
 242 greater than, equal to, or less than 0, if  the string pointed to by \fIs1\fR
 243 is greater than, equal to, or less than the string pointed to by \fIs2\fR
 244 respectively. The sign of a non-zero return value is determined  by the sign of
 245 the difference between the values of the first pair of bytes that differ in the
 246 strings being compared. The \fBstrncmp()\fR function makes the same comparison
 247 but looks at a maximum of \fIn\fR bytes. Bytes following a null byte are not
 248 compared.
 249 .SS "\fBstrcpy()\fR, \fBstrncpy()\fR, \fBstrlcpy()\fR"
 250 .sp
 251 .LP
 252 The \fBstrcpy()\fR function copies string \fIs2\fR to \fIs1\fR, including the
 253 terminating null character, stopping after the null character has been copied.
 254 The \fBstrncpy()\fR function copies exactly \fIn\fR bytes, truncating \fIs2\fR
 255 or adding null characters to \fIs1\fR if necessary. The result will not be
 256 null-terminated if the length of \fIs2\fR is \fIn\fR or more. Each function
 257 returns \fIs1\fR.  If copying takes place between objects that overlap, the
 258 behavior of \fBstrcpy()\fR, \fBstrncpy()\fR, and \fBstrlcpy()\fR is undefined.
 259 .sp
 260 .LP
 261 The \fBstrlcpy()\fR function copies  at most \fIdstsize\fR\(mi1 characters
 262 (\fIdstsize\fR being the  size of the  string buffer \fIdst\fR) from \fIsrc\fR
 263 to \fIdst\fR,  truncating \fIsrc\fR if necessary.  The  result is always
 264 null-terminated. The function returns \fBstrlen\fR(\fIsrc\fR). Buffer overflow
 265 can be checked as  follows:
 266 .sp
 267 .in +2
 268 .nf
 269 if (strlcpy(dst, src, dstsize) >= dstsize)
 270         return \(mi1;
 271 .fi
 272 .in -2
 273 
 274 .SS "\fBstrcspn()\fR, \fBstrspn()\fR"
 275 .sp
 276 .LP
 277 The \fBstrcspn()\fR function returns the length of the initial segment of
 278 string \fIs1\fR that consists entirely of characters not from string \fIs2\fR.
 279 The \fBstrspn()\fR function returns the length of the initial segment of string
 280 \fIs1\fR that consists entirely of characters from string \fIs2\fR.
 281 .SS "\fBstrdup()\fR"
 282 .sp
 283 .LP
 284 The \fBstrdup()\fR function returns a pointer to a new string that is a
 285 duplicate of the string pointed to by  \fIs1\fR. The returned pointer can be
 286 passed to \fBfree()\fR. The space for the new string is obtained using
 287 \fBmalloc\fR(3C). If the new string cannot be created, a null pointer is
 288 returned and \fBerrno\fR may be set to \fBENOMEM\fR to indicate that the
 289 storage space available is insufficient.
 290 .SS "\fBstrlen()\fR, \fBstrnlen()\fR"
 291 .sp
 292 .LP
 293 The \fBstrlen()\fR function returns the number of bytes in \fIs\fR, not
 294 including the terminating null character.
 295 .sp
 296 .LP
 297 The \fBstrnlen()\fR function returns the smaller of \fIn\fR or the number of
 298 bytes in \fIs\fR, not including the terminating null character. The
 299 \fBstrnlen()\fR function never examines more than \fIn\fR bytes of the string
 300 pointed to by \fIs\fR.
 301 .SS "\fBstrpbrk()\fR"
 302 .sp
 303 .LP
 304 The \fBstrpbrk()\fR function returns a pointer to the first occurrence in
 305 string \fIs1\fR of any character from string \fIs2\fR, or a null pointer if no
 306 character from \fIs2\fR exists in \fIs1\fR.
 307 .SS "\fBstrsep()\fR"
 308 .sp
 309 .LP
 310 The \fBstrsep()\fR function locates, in the null-terminated string referenced
 311 by *\fIstringp\fR, the first occurrence of any character in the string
 312 \fIdelim\fR (or the terminating `\e0' character) and replaces it with a `\e0'.
 313 The location of the next character after the delimiter character (or
 314 \fINULL\fR, if the end of the string was reached) is stored in *\fIstringp\fR.
 315 The original value of *\fIstringp\fR is returned.
 316 .sp
 317 .LP
 318 An ``empty'' field (one caused by two adjacent delimiter characters) can be
 319 detected by comparing the location referenced by the pointer returned by
 320 \fBstrsep()\fR to `\e0'.
 321 .sp
 322 .LP
 323 If *\fIstringp\fR is initially \fINULL\fR, \fBstrsep()\fR returns \fINULL\fR.
 324 .SS "\fBstrstr()\fR"
 325 .sp
 326 .LP
 327 The \fBstrstr()\fR function locates the first occurrence of the string \fIs2\fR
 328 (excluding the terminating null character) in string \fIs1\fR and returns a
 329 pointer to the located string, or a null pointer if the string is not found. If
 330 \fIs2\fR points to a string with zero length (that is, the string \fB""\fR),
 331 the function returns  \fIs1\fR.
 332 .SS "\fBstrtok()\fR"
 333 .sp
 334 .LP
 335 A sequence of calls to \fBstrtok()\fR breaks the string pointed to by \fIs1\fR
 336 into a sequence of tokens, each of which is delimited by a byte from the string
 337 pointed to by \fIs2\fR. The first call in the sequence has \fIs1\fR as its
 338 first argument, and is followed by calls with a null pointer as their first
 339 argument. The separator string pointed to by \fIs2\fR can be different from
 340 call to call.
 341 .sp
 342 .LP
 343 The first call in the sequence searches the string pointed to by \fIs1\fR for
 344 the first byte that is not contained in the current separator string pointed to
 345 by \fIs2\fR. If no such byte is found, then there are no tokens in the string
 346 pointed to by \fIs1\fR and \fBstrtok()\fR returns a null pointer. If such a
 347 byte is found, it is the start of the first token.
 348 .sp
 349 .LP
 350 The \fBstrtok()\fR function then searches from there for a byte that is
 351 contained in the current separator string. If no such byte is found, the
 352 current token extends to the end of the string pointed to by \fIs1\fR, and
 353 subsequent searches for a token return a null pointer. If such a byte is found,
 354 it is overwritten by a null byte that terminates the current token. The
 355 \fBstrtok()\fR function saves a pointer to the following byte in
 356 thread-specific data, from which the next search for a token starts.
 357 .sp
 358 .LP
 359 Each subsequent call, with a null pointer as the value of the first argument,
 360 starts searching from the saved pointer and behaves as described above.
 361 .sp
 362 .LP
 363 See Example 1, 2, and 3 in the \fBEXAMPLES\fR section for examples of
 364 \fBstrtok()\fR usage and the explanation in \fBNOTES\fR.
 365 .SS "\fBstrtok_r()\fR"
 366 .sp
 367 .LP
 368 The \fBstrtok_r()\fR function considers the null-terminated string \fIs1\fR as
 369 a sequence of zero or more text tokens separated by spans of one or more
 370 characters from the separator string \fIs2\fR. The argument \fIlasts\fR points
 371 to a user-provided pointer which points to stored information necessary for
 372 \fBstrtok_r()\fR to continue scanning the same string.
 373 .sp
 374 .LP
 375 In the first call to \fBstrtok_r()\fR, \fIs1\fR points to a null-terminated
 376 string, \fIs2\fR to a null-terminated string of separator characters, and the
 377 value pointed to by \fIlasts\fR is ignored. The \fBstrtok_r()\fR function
 378 returns a pointer to the first character of the first token, writes a null
 379 character into \fIs1\fR immediately following the returned token, and updates
 380 the pointer to which \fIlasts\fR points.
 381 .sp
 382 .LP
 383 In subsequent calls, \fIs1\fR is a null pointer and \fIlasts\fR is unchanged
 384 from the previous call so that subsequent calls move through the string
 385 \fIs1\fR, returning successive tokens until no tokens remain. The separator
 386 string \fIs2\fR can be different from call to call. When no token remains in
 387 \fIs1\fR, a null pointer is returned.
 388 .sp
 389 .LP
 390 See Example 3 in the \fBEXAMPLES\fR section for an example of \fBstrtok_r()\fR
 391 usage and the explanation in \fBNOTES\fR.
 392 .SH EXAMPLES
 393 .LP
 394 \fBExample 1 \fRSearch for word separators.
 395 .sp
 396 .LP
 397 The following example searches for tokens separated by space characters.
 398 
 399 .sp
 400 .in +2
 401 .nf
 402 #include <string.h>
 403 \&...
 404 char *token;
 405 char line[] = "LINE TO BE SEPARATED";
 406 char *search = " ";
 407 
 408 /* Token will point to "LINE". */
 409 token = strtok(line, search);
 410 
 411 /* Token will point to "TO". */
 412 token = strtok(NULL, search);
 413 .fi
 414 .in -2
 415 
 416 .LP
 417 \fBExample 2 \fRBreak a Line.
 418 .sp
 419 .LP
 420 The following example uses strtok to break a line into two character strings
 421 separated by any combination of SPACEs, TABs, or NEWLINEs.
 422 
 423 .sp
 424 .in +2
 425 .nf
 426 #include <string.h>
 427 \&...
 428 struct element {
 429        char *key;
 430        char *data;
 431 };
 432 \&...
 433 char line[LINE_MAX];
 434 char *key, *data;
 435 \&...
 436 key = strtok(line, " \en");
 437 data = strtok(NULL, " \en");
 438 .fi
 439 .in -2
 440 
 441 .LP
 442 \fBExample 3 \fRSearch for tokens.
 443 .sp
 444 .LP
 445 The following example uses both \fBstrtok()\fR and \fBstrtok_r()\fR to search
 446 for tokens separated by one or more characters from the string pointed to by
 447 the second argument, "/".
 448 
 449 .sp
 450 .in +2
 451 .nf
 452 #define __EXTENSIONS__
 453 #include <stdio.h>
 454 #include <string.h>
 455 
 456 int
 457 main() {
 458         char *buf="5/90/45";
 459         char *token;
 460         char *lasts;
 461 
 462         printf("tokenizing \e"%s\e" with strtok():\en", buf);
 463         if ((token = strtok(buf, "/")) != NULL) {
 464                 printf("token = "%s\e"\en", token);
 465                 while ((token = strtok(NULL, "/")) != NULL) {
 466                         printf("token = \e"%s\e"\en", token);
 467                 }
 468         }
 469 
 470         buf = "//5//90//45//";
 471         printf("\entokenizing \e"%s\e" with strtok_r():\en", buf);
 472         if ((token = strtok_r(buf, "/", &lasts)) != NULL) {
 473                 printf("token = \e"%s\e"\en", token);
 474                 while ((token = strtok_r(NULL, "/", &lasts)) != NULL) {
 475                         printf("token = \e"%s\e"\en", token);
 476                 }
 477         }
 478 }
 479 .fi
 480 .in -2
 481 
 482 .sp
 483 .LP
 484 When compiled and run, this example produces the following output:
 485 
 486 .sp
 487 .in +2
 488 .nf
 489 tokenizing "5/90/45" with \fBstrtok()\fR:
 490 token = "5"
 491 token = "90"
 492 token = "45"
 493 
 494 tokenizing "//5//90//45//" with \fBstrtok_r()\fR:
 495 token = "5"
 496 token = "90"
 497 token = "45"
 498 .fi
 499 .in -2
 500 
 501 .SH ATTRIBUTES
 502 .sp
 503 .LP
 504 See \fBattributes\fR(5) for descriptions of the following attributes:
 505 .sp
 506 
 507 .sp
 508 .TS
 509 box;
 510 c | c
 511 l | l .
 512 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 513 _
 514 Interface Stability     Committed
 515 _
 516 MT-Level        See below.
 517 _
 518 Standard        See below.
 519 .TE
 520 
 521 .sp
 522 .LP
 523 The \fBstrtok()\fR and \fBstrdup()\fR functions are MT-Safe. The remaining
 524 functions are Async-Signal-Safe.
 525 .sp
 526 .LP
 527 For all except \fBstrlcat()\fR, \fBstrlcpy()\fR, and \fBstrsep()\fR, see
 528 \fBstandards\fR(5).
 529 .SH SEE ALSO
 530 .sp
 531 .LP
 532 \fBmalloc\fR(3C), \fBsetlocale\fR(3C), \fBstrxfrm\fR(3C), \fBattributes\fR(5),
 533 \fBstandards\fR(5)
 534 .SH NOTES
 535 .sp
 536 .LP
 537 When compiling multithreaded applications, the \fB_REENTRANT\fR flag must be
 538 defined on the compile line. This flag should only be used in multithreaded
 539 applications.
 540 .sp
 541 .LP
 542 A single-threaded application can gain access to \fBstrtok_r()\fR only by
 543 defining \fB__EXTENSIONS__\fR or by defining \fB_POSIX_C_SOURCE\fR to a value
 544 greater than or equal to 199506L.
 545 .sp
 546 .LP
 547 All of these functions assume the default locale ``C.'' For some locales,
 548 \fBstrxfrm\fR(3C) should be applied to the strings before they are passed to
 549 the functions.
 550 .sp
 551 .LP
 552 The \fBstrtok()\fR function is safe to use in multithreaded applications
 553 because it saves its internal state in a thread-specific data area.  However,
 554 its use is discouraged, even for single-threaded applications. The
 555 \fBstrtok_r()\fR function should be used instead.
 556 .sp
 557 .LP
 558 Do not pass the address of a character string literal as the argument \fIs1\fR
 559 to either \fBstrtok()\fR or \fBstrtok_r()\fR. Similarly, do not pass a pointer
 560 to the address of a character string literal as the argument \fIstringp\fR to
 561 \fBstrsep()\fR. These functions can modify the storage pointed to by \fIs1\fR
 562 in the case of \fBstrtok()\fR and \fBstrtok_r()\fR or *\fIstringp\fR in the
 563 case of \fBstrsep()\fR. The C99 standard specifies that attempting to modify
 564 the storage occupied by a string literal results in undefined behavior. This
 565 allows compilers (including \fBgcc\fR and the Sun Studio compilers when the
 566 \fB-xstrconst\fR flag is used) to place string literals in read-only memory.
 567 Note that in Example 1 above, this problem is avoided because the variable
 568 \fIline\fR is declared as a writable array of type \fBchar\fR that is
 569 initialized by a string literal rather than a pointer to \fBchar\fR that points
 570 to a string literal.