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