1.\" $OpenBSD: wcstok.3,v 1.7 2011/07/25 00:38:53 schwarze Exp $ 2.\" 3.\" $NetBSD: wcstok.3,v 1.3 2003/09/08 17:54:33 wiz Exp $ 4.\" 5.\" Copyright (c) 1998 Softweyr LLC. All rights reserved. 6.\" 7.\" strtok_r, from Berkeley strtok 8.\" Oct 13, 1998 by Wes Peters <wes@softweyr.com> 9.\" 10.\" Copyright (c) 1988, 1991, 1993 11.\" The Regents of the University of California. All rights reserved. 12.\" 13.\" This code is derived from software contributed to Berkeley by 14.\" the American National Standards Committee X3, on Information 15.\" Processing Systems. 16.\" 17.\" Redistribution and use in source and binary forms, with or without 18.\" modification, are permitted provided that the following conditions 19.\" are met: 20.\" 21.\" 1. Redistributions of source code must retain the above copyright 22.\" notices, this list of conditions and the following disclaimer. 23.\" 24.\" 2. Redistributions in binary form must reproduce the above 25.\" copyright notices, this list of conditions and the following 26.\" disclaimer in the documentation and/or other materials provided 27.\" with the distribution. 28.\" 29.\" 3. All advertising materials mentioning features or use of this 30.\" software must display the following acknowledgement: 31.\" 32.\" This product includes software developed by Softweyr LLC, the 33.\" University of California, Berkeley, and its contributors. 34.\" 35.\" 4. Neither the name of Softweyr LLC, the University nor the names 36.\" of its contributors may be used to endorse or promote products 37.\" derived from this software without specific prior written 38.\" permission. 39.\" 40.\" THIS SOFTWARE IS PROVIDED BY SOFTWEYR LLC, THE REGENTS AND 41.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 42.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 43.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 44.\" DISCLAIMED. IN NO EVENT SHALL SOFTWEYR LLC, THE REGENTS, OR 45.\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 46.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 47.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 48.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 49.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 50.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 51.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 52.\" SUCH DAMAGE. 53.\" 54.\" Original version ID: 55.\" FreeBSD: src/lib/libc/string/wcstok.3,v 1.4 2002/10/15 09:49:54 tjr Exp 56.\" 57.Dd $Mdocdate: July 25 2011 $ 58.Dt WCSTOK 3 59.Os 60.Sh NAME 61.Nm wcstok 62.Nd split wide-character string into tokens 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.Xr strtok_r 3 94function. 95.Pp 96Since 97.Fn wcstok 98modifies the string, 99.Fa str 100should not point to an area in the initialized data segment. 101.Sh RETURN VALUES 102The 103.Fn wcstok 104function 105returns a pointer to the beginning of each subsequent token in the string, 106after replacing the token itself with a NUL wide character (L'\e0'). 107When no more tokens remain, a null pointer is returned. 108.Sh EXAMPLES 109The following code fragment splits a wide-character string on 110.Tn ASCII 111space, tab, and newline characters and writes the tokens to 112standard output: 113.Bd -literal -offset indent 114const wchar_t *seps = L" \et\en"; 115wchar_t *last, *tok, text[] = L" \enone\ettwo\et\etthree \en"; 116 117for (tok = wcstok(text, seps, &last); tok != NULL; 118 tok = wcstok(NULL, seps, &last)) 119 wprintf(L"%ls\en", tok); 120.Ed 121.Sh SEE ALSO 122.Xr strtok 3 , 123.Xr wcschr 3 , 124.Xr wcscspn 3 , 125.Xr wcspbrk 3 , 126.Xr wcsrchr 3 , 127.Xr wcsspn 3 , 128.Xr wcsstr 3 , 129.Xr wmemchr 3 130.Sh STANDARDS 131The 132.Fn wcstok 133function 134conforms to 135.St -isoC-99 . 136.Sh HISTORY 137The 138.Fn wcstok 139function was ported from 140.Nx 141and first appeared in 142.Ox 3.8 . 143.Pp 144Some early implementations of 145.Fn wcstok 146omit the 147context pointer argument, 148.Fa last , 149and maintain state across calls in a static variable like 150.Xr strtok 3 151does. 152