lib/libc/string/strtok.3

   1 .\" Copyright (c) 1988, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the American National Standards Committee X3, on Information
   6 .\" Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     from: @(#)strtok.3      8.2 (Berkeley) 2/3/94
  33 .\"     $NetBSD: strtok.3,v 1.22 2006/10/16 08:48:45 wiz Exp $
  34 .\"
  35 .Dd August 11, 2002
  36 .Dt STRTOK 3
  37 .Os
  38 .Sh NAME
  39 .Nm strtok, strtok_r
  40 .Nd string tokens
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In string.h
  45 .Ft char *
  46 .Fn strtok "char * restrict str" "const char * restrict sep"
  47 .Ft char *
  48 .Fn strtok_r "char *str" "const char *sep" "char **lasts"
  49 .Sh DESCRIPTION
  50 The
  51 .Fn strtok
  52 function
  53 is used to isolate sequential tokens in a nul-terminated string,
  54 .Fa str .
  55 These tokens are separated in the string by at least one of the
  56 characters in
  57 .Fa sep .
  58 The first time that
  59 .Fn strtok
  60 is called,
  61 .Fa str
  62 should be specified; subsequent calls, wishing to obtain further tokens
  63 from the same string, should pass a null pointer instead.
  64 The separator string,
  65 .Fa sep ,
  66 must be supplied each time, and may change between calls.
  67 .Pp
  68 The
  69 .Fn strtok
  70 function
  71 returns a pointer to the beginning of each subsequent token in the string,
  72 after replacing the separator character itself with a
  73 .Dv NUL
  74 character.
  75 Separator characters at the beginning of the string or at the
  76 continuation point are skipped so that zero length tokens
  77 are not returned.
  78 When no more tokens remain, a null pointer is returned.
  79 .Pp
  80 The
  81 .Fn strtok_r
  82 function implements the functionality of
  83 .Fn strtok
  84 but is passed an additional argument,
  85 .Fa lasts ,
  86 which points to a user-provided pointer which is used by
  87 .Fn strtok_r
  88 to store state which needs to be kept between calls to scan the same string;
  89 unlike
  90 .Fn strtok ,
  91 it is not necessary to limit tokenizing to a single string at a time
  92 when using
  93 .Fn strtok_r .
  94 .Sh EXAMPLES
  95 The following will construct an array of pointers to each individual word in
  96 the string
  97 .Va s :
  98 .Bd -literal -offset indent
  99 #define MAXTOKENS       128
 100
 101 char s[512], *p, *tokens[MAXTOKENS];
 102 char *last;
 103 int i = 0;
 104
 105 snprintf(s, sizeof(s), "cat dog horse cow");
 106
 107 for ((p = strtok_r(s, " ", &last)); p;
 108     (p = strtok_r(NULL, " ", &last)), i++) {
 109         if (i < MAXTOKENS - 1)
 110                 tokens[i] = p;
 111 }
 112 tokens[i] = NULL;
 113 .Ed
 114 .Pp
 115 That is,
 116 .Li tokens[0]
 117 will point to
 118 .Qq cat ,
 119 .Li tokens[1]
 120 will point to
 121 .Qq dog ,
 122 .Li tokens[2]
 123 will point to
 124 .Qq horse ,
 125 and
 126 .Li tokens[3]
 127 will point to
 128 .Qq cow .
 129 .Sh SEE ALSO
 130 .Xr index 3 ,
 131 .Xr memchr 3 ,
 132 .Xr rindex 3 ,
 133 .Xr strchr 3 ,
 134 .Xr strcspn 3 ,
 135 .Xr strpbrk 3 ,
 136 .Xr strrchr 3 ,
 137 .Xr strsep 3 ,
 138 .Xr strspn 3 ,
 139 .Xr strstr 3
 140 .Sh STANDARDS
 141 The
 142 .Fn strtok
 143 function
 144 conforms to
 145 .St -ansiC .
 146 The
 147 .Fn strtok_r
 148 function conforms to
 149 .St -p1003.1c-95 .
 150 .Sh BUGS
 151 The System V
 152 .Fn strtok ,
 153 if handed a string containing only delimiter characters,
 154 will not alter the next starting point, so that a call to
 155 .Fn strtok
 156 with a different (or empty) delimiter string
 157 may return a
 158 .Pf non- Dv NULL
 159 value.
 160 Since this implementation always alters the next starting point,
 161 such a sequence of calls would always return
 162 .Dv NULL .