1 files changed, 64 insertions, 20 deletions

diff --git a/src/lib/libc/string/strtok.3 b/src/lib/libc/string/strtok.3
index 644bd10aed..b8dad8eff0 100644
--- a/src/lib/libc/string/strtok.3
+++ b/src/lib/libc/string/strtok.3
@@ -33,29 +33,30 @@
 .\" 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 $
+.\"     $OpenBSD: strtok.3,v 1.15 2001/08/06 10:42:26 mpech Exp $
 .\"
 .Dd June 29, 1991
 .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 null-terminated string,
 .Fa str .
 These tokens are separated in the string by at least one of the
 characters in
@@ -71,17 +72,65 @@ 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
+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.
+.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 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)), i++) {
+        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 ,
@@ -92,21 +141,16 @@ When no more tokens remain, a null pointer is returned.
 .Sh STANDARDS
 The
 .Fn strtok
-function
-conforms to
+function conforms to
 .St -ansiC .
 .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 .