1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
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.
8 .\" References consulted:
9 .\" GNU glibc-2 source code and manual
10 .\" Dinkumware C library reference http://www.dinkumware.com/
11 .\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html
13 .TH MBSNRTOWCS 3 2007-07-26 "GNU" "Linux Programmer's Manual"
15 mbsnrtowcs \- convert a multibyte string to a wide-character string
18 .B #define _GNU_SOURCE
21 .BI "size_t mbsnrtowcs(wchar_t *" dest ", const char **" src ,
22 .BI " size_t " nms ", size_t " len ", mbstate_t *" ps );
30 the number of bytes to be converted, starting at \fI*src\fP, is limited to
33 If \fIdest\fP is not a NULL pointer, the
36 most \fInms\fP bytes from the
37 multibyte string \fI*src\fP to a wide-character string starting at \fIdest\fP.
38 At most \fIlen\fP wide characters are written to \fIdest\fP.
41 The conversion is effectively performed by repeatedly
43 .I "mbrtowc(dest, *src, n, ps)"
45 positive number, as long as this call succeeds, and then incrementing
46 \fIdest\fP by one and \fI*src\fP by the number of bytes consumed.
48 conversion can stop for three reasons:
50 1. An invalid multibyte sequence has been encountered.
51 In this case \fI*src\fP
52 is left pointing to the invalid multibyte sequence,
55 and \fIerrno\fP is set to \fBEILSEQ\fP.
57 2. The \fInms\fP limit forces a stop, or \fIlen\fP non-L'\\0' wide characters
58 have been stored at \fIdest\fP.
59 In this case \fI*src\fP is left pointing to the
60 next multibyte sequence to be converted, and the number of wide characters
61 written to \fIdest\fP is returned.
63 3. The multibyte string has been completely converted, including the
64 terminating '\\0' (which has the side effect of bringing back \fI*ps\fP to the
66 In this case \fI*src\fP is set to NULL, and the number of wide
67 characters written to \fIdest\fP, excluding the terminating L'\\0' character,
70 If \fIdest\fP is NULL, \fIlen\fP is ignored, and the conversion proceeds as
71 above, except that the converted wide characters
72 are not written out to memory,
73 and that no destination length limit exists.
75 In both of the above cases, if \fIps\fP is a NULL pointer, a static anonymous
76 state only known to the mbsnrtowcs function is used instead.
78 The programmer must ensure that there is room for at least \fIlen\fP wide
79 characters at \fIdest\fP.
83 function returns the number of wide characters
84 that make up the converted part of the wide-character string,
85 not including the terminating null wide character.
86 If an invalid multibyte sequence was
89 is returned, and \fIerrno\fP set to \fBEILSEQ\fP.
91 This function is a GNU extension.
100 Passing NULL as \fIps\fP is not multi-thread safe.