1a64d82da5
when talking about characters/bytes, use "nul" and "nul-terminate" when talking about pointers, use "null pointer" or ".Dv NULL"
136 lines
4.2 KiB
Groff
136 lines
4.2 KiB
Groff
.\" $NetBSD: wcstok.3,v 1.5 2006/10/16 08:48:45 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 1998 Softweyr LLC. All rights reserved.
|
|
.\"
|
|
.\" strtok_r, from Berkeley strtok
|
|
.\" Oct 13, 1998 by Wes Peters <wes@softweyr.com>
|
|
.\"
|
|
.\" Copyright (c) 1988, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to Berkeley by
|
|
.\" the American National Standards Committee X3, on Information
|
|
.\" Processing Systems.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\"
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notices, this list of conditions and the following disclaimer.
|
|
.\"
|
|
.\" 2. Redistributions in binary form must reproduce the above
|
|
.\" copyright notices, this list of conditions and the following
|
|
.\" disclaimer in the documentation and/or other materials provided
|
|
.\" with the distribution.
|
|
.\"
|
|
.\" 3. All advertising materials mentioning features or use of this
|
|
.\" software must display the following acknowledgement:
|
|
.\"
|
|
.\" This product includes software developed by Softweyr LLC, the
|
|
.\" University of California, Berkeley, and its contributors.
|
|
.\"
|
|
.\" 4. Neither the name of Softweyr LLC, the University nor the names
|
|
.\" of its contributors may be used to endorse or promote products
|
|
.\" derived from this software without specific prior written
|
|
.\" permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY SOFTWEYR LLC, THE REGENTS AND
|
|
.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
|
|
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
.\" DISCLAIMED. IN NO EVENT SHALL SOFTWEYR LLC, THE REGENTS, OR
|
|
.\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
|
|
.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
|
|
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" Original version ID:
|
|
.\" FreeBSD: src/lib/libc/string/wcstok.3,v 1.4 2002/10/15 09:49:54 tjr Exp
|
|
.\"
|
|
.Dd October 3, 2002
|
|
.Dt WCSTOK 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm wcstok
|
|
.Nd split wide-character string into tokens
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In wchar.h
|
|
.Ft wchar_t *
|
|
.Fn wcstok "wchar_t * restrict str" "const wchar_t * restrict sep" "wchar_t ** restrict last"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn wcstok
|
|
function
|
|
is used to isolate sequential tokens in a nul-terminated wide character
|
|
string,
|
|
.Fa str .
|
|
These tokens are separated in the string by at least one of the
|
|
characters in
|
|
.Fa sep .
|
|
The first time that
|
|
.Fn wcstok
|
|
is called,
|
|
.Fa str
|
|
should be specified; subsequent calls, wishing to obtain further tokens
|
|
from the same string, should pass a null pointer instead.
|
|
The separator string,
|
|
.Fa sep ,
|
|
must be supplied each time, and may change between calls.
|
|
The context pointer
|
|
.Fa last
|
|
must be provided on each call.
|
|
.Pp
|
|
The
|
|
.Fn wcstok
|
|
function is the wide character counterpart of the
|
|
.Fn strtok_r
|
|
function.
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn wcstok
|
|
function
|
|
returns a pointer to the beginning of each subsequent token in the string,
|
|
after replacing the token itself with a nul wide character (L'\e0').
|
|
When no more tokens remain, a null pointer is returned.
|
|
.Sh EXAMPLES
|
|
The following code fragment splits a wide character string on
|
|
.Tn ASCII
|
|
space, tab and newline characters and writes the tokens to
|
|
standard output:
|
|
.Bd -literal -offset indent
|
|
const wchar_t *seps = L" \et\en";
|
|
wchar_t *last, *tok, text[] = L" \enone\ettwo\et\etthree \en";
|
|
|
|
for (tok = wcstok(text, seps, &last); tok != NULL;
|
|
tok = wcstok(NULL, seps, &last))
|
|
wprintf(L"%ls\en", tok);
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr strtok 3 ,
|
|
.Xr wcschr 3 ,
|
|
.Xr wcscspn 3 ,
|
|
.Xr wcspbrk 3 ,
|
|
.Xr wcsrchr 3 ,
|
|
.Xr wcsspn 3
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn wcstok
|
|
function
|
|
conforms to
|
|
.St -isoC-99 .
|
|
.Pp
|
|
Some early implementations of
|
|
.Fn wcstok
|
|
omit the context pointer argument,
|
|
.Fa last ,
|
|
and maintain state across calls in a static variable like
|
|
.Xr strtok 3
|
|
does.
|