Print this page
2964 need POSIX 2008 locale object support
Reviewed by: Robert Mustacchi <rm@joyent.com>
Reviewed by: Gordon Ross <gordon.ross@nexenta.com>
Approved by: TBD

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