1  .\" Copyright (c) 1998 Softweyr LLC.  All rights reserved.
  2  .\"
  3  .\" strtok_r, from Berkeley strtok
  4  .\" Oct 13, 1998 by Wes Peters <wes@softweyr.com>
  5  .\"
  6  .\" Copyright (c) 1988, 1991, 1993
  7  .\"	The Regents of the University of California.  All rights reserved.
  8  .\"
  9  .\" This code is derived from software contributed to Berkeley by
 10  .\" the American National Standards Committee X3, on Information
 11  .\" Processing Systems.
 12  .\"
 13  .\" Redistribution and use in source and binary forms, with or without
 14  .\" modification, are permitted provided that the following conditions
 15  .\" are met:
 16  .\"
 17  .\" 1. Redistributions of source code must retain the above copyright
 18  .\"    notices, this list of conditions and the following disclaimer.
 19  .\"
 20  .\" 2. Redistributions in binary form must reproduce the above
 21  .\"    copyright notices, this list of conditions and the following
 22  .\"    disclaimer in the documentation and/or other materials provided
 23  .\"    with the distribution.
 24  .\"
 25  .\" 3. All advertising materials mentioning features or use of this
 26  .\"    software must display the following acknowledgement:
 27  .\"
 28  .\"	This product includes software developed by Softweyr LLC, the
 29  .\"      University of California, Berkeley, and its contributors.
 30  .\"
 31  .\" 4. Neither the name of Softweyr LLC, the University nor the names
 32  .\"    of its contributors may be used to endorse or promote products
 33  .\"    derived from this software without specific prior written
 34  .\"    permission.
 35  .\"
 36  .\" THIS SOFTWARE IS PROVIDED BY SOFTWEYR LLC, THE REGENTS AND
 37  .\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
 38  .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 39  .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 40  .\" DISCLAIMED.  IN NO EVENT SHALL SOFTWEYR LLC, THE REGENTS, OR
 41  .\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 42  .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 43  .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 44  .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 45  .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 46  .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 47  .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 48  .\" SUCH DAMAGE.
 49  .\"
 50  .\" $FreeBSD: src/lib/libc/string/wcstok.3,v 1.4 2002/10/15 09:49:54 tjr Exp $
 51  .\"
 52  .Dd October 3, 2002
 53  .Dt WCSTOK 3
 54  .Os
 55  .Sh NAME
 56  .Nm wcstok
 57  .Nd split wide-character string into tokens
 58  .Sh LIBRARY
 59  .Lb libc
 60  .Sh SYNOPSIS
 61  .In wchar.h
 62  .Ft wchar_t *
 63  .Fo wcstok
 64  .Fa "wchar_t *restrict ws1"
 65  .Fa "const wchar_t *restrict ws2"
 66  .Fa "wchar_t **restrict ptr"
 67  .Fc
 68  .Sh DESCRIPTION
 69  The
 70  .Fn wcstok
 71  function
 72  is used to isolate sequential tokens in a null-terminated wide character
 73  string,
 74  .Fa ws1 .
 75  These tokens are separated in the string by at least one of the
 76  characters in
 77  .Fa ws2 .
 78  The first time that
 79  .Fn wcstok
 80  is called,
 81  .Fa ws1
 82  should be specified; subsequent calls, wishing to obtain further tokens
 83  from the same string, should pass a null pointer instead.
 84  The separator string,
 85  .Fa ws2 ,
 86  must be supplied each time, and may change between calls.
 87  The context pointer,
 88  .Fa ptr ,
 89  must be provided on each call.
 90  .Pp
 91  The
 92  .Fn wcstok
 93  function is the wide character counterpart of the
 94  .Fn strtok_r
 95  function.
 96  .Sh RETURN VALUES
 97  The
 98  .Fn wcstok
 99  function
100  returns a pointer to the beginning of each subsequent token in the string,
101  after replacing the token itself with a null wide character (L'\e0').
102  When no more tokens remain, a null pointer is returned.
103  .Sh EXAMPLES
104  The following code fragment splits a wide character string on
105  .Tn ASCII
106  space, tab, and newline characters,
107  writing the resulting tokens to standard output:
108  .Bd -literal -offset indent
109  const wchar_t *seps = L" \et\en";
110  wchar_t *last, *tok, text[] = L" \enone\ettwo\et\etthree  \en";
111  
112  for (tok = wcstok(text, seps, &last); tok != NULL;
113      tok = wcstok(NULL, seps, &last))
114  	wprintf(L"%ls\en", tok);
115  .Ed
116  .Sh COMPATIBILITY
117  Some early implementations of
118  .Fn wcstok
119  omit the
120  context pointer argument,
121  .Fa ptr ,
122  and maintain state across calls in a static variable like
123  .Fn strtok
124  does.
125  .Sh SEE ALSO
126  .Xr strtok 3 ,
127  .Xr wcschr 3 ,
128  .Xr wcscspn 3 ,
129  .Xr wcspbrk 3 ,
130  .Xr wcsrchr 3 ,
131  .Xr wcsspn 3
132  .Sh STANDARDS
133  The
134  .Fn wcstok
135  function
136  conforms to
137  .St -isoC-99 .