]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) Bruno Haible <haible@clisp.cons.org> |
2 | .\" | |
3 | .\" This is free documentation; you can redistribute it and/or | |
4 | .\" modify it under the terms of the GNU General Public License as | |
5 | .\" published by the Free Software Foundation; either version 2 of | |
6 | .\" the License, or (at your option) any later version. | |
7 | .\" | |
8 | .\" References consulted: | |
9 | .\" GNU glibc-2 source code and manual | |
10 | .\" Dinkumware C library reference http://www.dinkumware.com/ | |
008f1ecc | 11 | .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html |
fea681da MK |
12 | .\" ISO/IEC 9899:1999 |
13 | .\" | |
14 | .TH WCSTOK 3 1999-07-25 "GNU" "Linux Programmer's Manual" | |
15 | .SH NAME | |
16 | wcstok \- split wide-character string into tokens | |
17 | .SH SYNOPSIS | |
18 | .nf | |
19 | .B #include <wchar.h> | |
20 | .sp | |
3d54a910 MK |
21 | .BI "wchar_t *wcstok(wchar_t *" wcs ", const wchar_t *" delim \ |
22 | ", wchar_t **" ptr ); | |
fea681da MK |
23 | .fi |
24 | .SH DESCRIPTION | |
60a90ecd MK |
25 | The |
26 | .BR wcstok () | |
27 | function is the wide-character equivalent of the | |
28 | .BR strtok (3) | |
29 | function, | |
c13182ef | 30 | with an added argument to make it multithread-safe. |
35478399 | 31 | It can be used |
fea681da MK |
32 | to split a wide-character string \fIwcs\fP into tokens, where a token is |
33 | defined as a substring not containing any wide-characters from \fIdelim\fP. | |
34 | .PP | |
1c44bd5b MK |
35 | The search starts at \fIwcs\fP, if \fIwcs\fP is not NULL, |
36 | or at \fI*ptr\fP, if \fIwcs\fP is NULL. | |
75b94dc3 | 37 | First, any delimiter wide-characters are skipped, that is, the |
fea681da | 38 | pointer is advanced beyond any wide-characters which occur in \fIdelim\fP. |
1c44bd5b | 39 | If the end of the wide-character string is now |
60a90ecd MK |
40 | reached, |
41 | .BR wcstok () | |
42 | returns NULL, to indicate that no tokens | |
1c44bd5b | 43 | were found, and stores an appropriate value in \fI*ptr\fP, |
60a90ecd MK |
44 | so that subsequent calls to |
45 | .BR wcstok () | |
46 | will continue to return NULL. | |
47 | Otherwise, the | |
48 | .BR wcstok () | |
49 | function recognizes the beginning of a token | |
fea681da MK |
50 | and returns a pointer to it, but before doing that, it zero-terminates the |
51 | token by replacing the next wide-character which occurs in \fIdelim\fP with | |
f81fb444 MK |
52 | a L\(aq\\0\(aq character, |
53 | and it updates \fI*ptr\fP so that subsequent calls will | |
fea681da MK |
54 | continue searching after the end of recognized token. |
55 | .SH "RETURN VALUE" | |
60a90ecd MK |
56 | The |
57 | .BR wcstok () | |
58 | function returns a pointer to the next token, | |
1c44bd5b | 59 | or NULL if no further token was found. |
2b2581ee MK |
60 | .SH "CONFORMING TO" |
61 | C99. | |
fea681da MK |
62 | .SH NOTES |
63 | The original \fIwcs\fP wide-character string is destructively modified during | |
64 | the operation. | |
65 | .SH EXAMPLE | |
66 | The following code loops over the tokens contained in a wide-character string. | |
67 | .sp | |
68 | .nf | |
69 | wchar_t *wcs = ...; | |
70 | wchar_t *token; | |
71 | wchar_t *state; | |
72 | for (token = wcstok(wcs, " \\t\\n", &state); | |
b9f02710 MK |
73 | token != NULL; |
74 | token = wcstok(NULL, " \\t\\n", &state)) { | |
75 | ... | |
fea681da MK |
76 | } |
77 | .fi | |
fea681da MK |
78 | .SH "SEE ALSO" |
79 | .BR strtok (3), | |
80 | .BR wcschr (3) |