1 files changed, 82 insertions, 28 deletions

diff --git a/src/lib/libc/string/strtok.3 b/src/lib/libc/string/strtok.3
index 644bd10aed..fbf0abfc26 100644
--- a/src/lib/libc/string/strtok.3
+++ b/src/lib/libc/string/strtok.3
@@ -1,3 +1,5 @@
+.\"     $OpenBSD: strtok.3,v 1.20 2011/07/25 00:38:53 schwarze Exp $
+.\"
 .\" Copyright (c) 1988, 1991 The Regents of the University of California.
 .\" All rights reserved.
 .\"
@@ -13,11 +15,7 @@
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"     This product includes software developed by the University of
-.\"     California, Berkeley and its contributors.
-.\" 4. Neither the name of the University nor the names of its contributors
+.\" 3. Neither the name of the University nor the names of its contributors
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
 .\"
@@ -33,29 +31,28 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"     from: @(#)strtok.3      5.8 (Berkeley) 6/29/91
-.\"     $Id: strtok.3,v 1.1.1.1 1995/10/18 08:42:23 deraadt Exp $
-.\"
-.Dd June 29, 1991
+.Dd $Mdocdate: July 25 2011 $
 .Dt STRTOK 3
-.Os BSD 3
+.Os
 .Sh NAME
 .Nm strtok ,
-.Nm strsep
+.Nm strtok_r
 .Nd string token operations
 .Sh SYNOPSIS
 .Fd #include <string.h>
 .Ft char *
 .Fn strtok "char *str" "const char *sep"
+.Ft char *
+.Fn strtok_r "char *str" "const char *sep" "char **last"
 .Sh DESCRIPTION
 .Bf -symbolic
-This interface is obsoleted by strsep(3).
+This interface is obsoleted by
+.Xr strsep 3 .
 .Ef
 .Pp
 The
 .Fn strtok
-function
-is used to isolate sequential tokens in a null-terminated string,
+function is used to isolate sequential tokens in a NUL-terminated string,
 .Fa str .
 These tokens are separated in the string by at least one of the
 characters in
@@ -71,42 +68,99 @@ The separator string,
 must be supplied each time, and may change between calls.
 .Pp
 The
+.Fn strtok_r
+function is a version of
 .Fn strtok
-function
-returns a pointer to the beginning of each subsequent token in the string,
-after replacing the separator character itself with a
-.Dv NUL
+that takes an explicit context argument and is reentrant.
+.Pp
+Since
+.Fn strtok
+and
+.Fn strtok_r
+modify the string,
+.Fa str
+should not point to an area in the initialized data segment.
+.Sh RETURN VALUES
+The
+.Fn strtok
+and
+.Fn strtok_r
+functions return a pointer to the beginning of each subsequent token
+in the string, after replacing the separator character itself with an
+.Tn ASCII NUL
 character.
 When no more tokens remain, a null pointer is returned.
+.Sh EXAMPLES
+The following will construct an array of pointers to each individual word in
+the string
+.Va s :
+.Bd -literal -offset indent
+#define MAXTOKENS       128
+
+char s[512], *p, *tokens[MAXTOKENS];
+char *last;
+int i = 0;
+
+snprintf(s, sizeof(s), "cat dog horse cow");
+
+for ((p = strtok_r(s, " ", &last)); p;
+    (p = strtok_r(NULL, " ", &last))) {
+        if (i < MAXTOKENS - 1)
+                tokens[i++] = p;
+}
+tokens[i] = NULL;
+.Ed
+.Pp
+That is,
+.Li tokens[0]
+will point to
+.Qq cat ,
+.Li tokens[1]
+will point to
+.Qq dog ,
+.Li tokens[2]
+will point to
+.Qq horse ,
+and
+.Li tokens[3]
+will point to
+.Qq cow .
 .Sh SEE ALSO
-.Xr index 3 ,
 .Xr memchr 3 ,
-.Xr rindex 3 ,
 .Xr strchr 3 ,
 .Xr strcspn 3 ,
 .Xr strpbrk 3 ,
 .Xr strrchr 3 ,
 .Xr strsep 3 ,
 .Xr strspn 3 ,
-.Xr strstr 3
+.Xr strstr 3 ,
+.Xr wcstok 3
 .Sh STANDARDS
 The
 .Fn strtok
-function
-conforms to
+function conforms to
 .St -ansiC .
+.Sh HISTORY
+The
+.Fn strtok
+function first appeared in
+.At III
+and was reimplemented for
+.Bx 4.3 Tahoe .
+The
+.Fn strtok_r
+function first appeared in
+.Nx 1.3
+and was reimplemented for
+.Ox 2.7 .
 .Sh BUGS
-There is no way to get tokens from multiple strings simultaneously.
-.Pp
 The System V
 .Fn strtok ,
 if handed a string containing only delimiter characters,
 will not alter the next starting point, so that a call to
 .Fn strtok
 with a different (or empty) delimiter string
-may return a
-.Pf non- Dv NULL
-value.
+may return a non-null value.
 Since this implementation always alters the next starting point,
 such a sequence of calls would always return
 .Dv NULL .