1.\" $OpenBSD: wcstok.3,v 1.5 2007/05/31 19:19:32 jmc 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: May 31 2007 $ 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.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.Sh HISTORY 129Some early implementations of 130.Fn wcstok 131omit the 132context pointer argument, 133.Fa last , 134and maintain state across calls in a static variable like 135.Fn strtok 136does. 137