]>
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/ | |
11 | .\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html | |
12 | .\" | |
13 | .TH WCSNRTOMBS 3 1999-07-25 "GNU" "Linux Programmer's Manual" | |
14 | .SH NAME | |
15 | wcsnrtombs \- convert a wide character string to a multibyte string | |
16 | .SH SYNOPSIS | |
17 | .nf | |
18 | .B #include <wchar.h> | |
19 | .sp | |
20 | .BI "size_t wcsnrtombs(char *" dest ", const wchar_t **" src ", size_t " nwc , | |
21 | .BI " size_t " len ", mbstate_t *" ps ); | |
22 | .fi | |
23 | .SH DESCRIPTION | |
3382bd94 | 24 | The \fBwcsnrtombs\fP() function is like the \fBwcsrtombs\fP() function, except that |
fea681da MK |
25 | the number of wide characters to be converted, starting at \fI*src\fP, is |
26 | limited to \fInwc\fP. | |
27 | .PP | |
e511ffb6 | 28 | If \fIdest\fP is not a NULL pointer, the \fBwcsnrtombs\fP() function converts |
fea681da MK |
29 | at most \fInwc\fP wide characters from |
30 | the wide-character string \fI*src\fP to a multibyte string starting at | |
31 | \fIdest\fP. At most \fIlen\fP bytes are written to \fIdest\fP. The shift state | |
32 | \fI*ps\fP is updated. The conversion is effectively performed by repeatedly | |
33 | calling wcrtomb(\fIdest\fP,\fI*src\fP,\fIps\fP), as long as this call succeeds, | |
34 | and then incrementing \fIdest\fP by the number of bytes written and \fI*src\fP | |
35 | by one. The conversion can stop for three reasons: | |
36 | .PP | |
37 | 1. A wide character has been encountered that can not be represented as a | |
38 | multibyte sequence (according to the current locale). In this case \fI*src\fP | |
2bc2f479 | 39 | is left pointing to the invalid wide character, (size_t)(\-1) is returned, |
dcec8eb5 | 40 | and \fIerrno\fP is set to \fBEILSEQ\fP. |
fea681da MK |
41 | .PP |
42 | 2. \fInwc\fP wide characters have been converted without encountering a L'\\0', | |
43 | or the length limit forces a stop. In this case \fI*src\fP is left pointing | |
44 | to the next wide character to be converted, and the number of bytes written | |
45 | to \fIdest\fP is returned. | |
46 | .PP | |
47 | 3. The wide-character string has been completely converted, including the | |
48 | terminating L'\\0' (which has the side effect of bringing back \fI*ps\fP | |
49 | to the initial state). In this case \fI*src\fP is set to NULL, and the number | |
50 | of bytes written to \fIdest\fP, excluding the terminating '\\0' byte, is | |
51 | returned. | |
52 | .PP | |
53 | If \fIdest\fP is NULL, \fIlen\fP is ignored, and the conversion proceeds as | |
54 | above, except that the converted bytes are not written out to memory, and that | |
55 | no destination length limit exists. | |
56 | .PP | |
57 | In both of the above cases, if \fIps\fP is a NULL pointer, a static anonymous | |
58 | state only known to the wcsnrtombs function is used instead. | |
59 | .PP | |
60 | The programmer must ensure that there is room for at least \fIlen\fP bytes | |
61 | at \fIdest\fP. | |
62 | .SH "RETURN VALUE" | |
e511ffb6 | 63 | The \fBwcsnrtombs\fP() function returns the number of bytes that make up the |
fea681da | 64 | converted part of multibyte sequence, not including the terminating null byte. |
2bc2f479 | 65 | If a wide character was encountered which could not be converted, (size_t)(\-1) |
dcec8eb5 | 66 | is returned, and \fIerrno\fP set to \fBEILSEQ\fP. |
fea681da MK |
67 | .SH "CONFORMING TO" |
68 | This function is a GNU extension. | |
69 | .SH "SEE ALSO" | |
70 | .BR iconv (3), | |
71 | .BR wcsrtombs (3) | |
72 | .SH NOTES | |
e511ffb6 | 73 | The behaviour of \fBwcsnrtombs\fP() depends on the LC_CTYPE category of the |
fea681da MK |
74 | current locale. |
75 | .PP | |
76 | Passing NULL as \fIps\fP is not multi-thread safe. |