]>
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 | .\" ISO/IEC 9899:1999 | |
13 | .\" | |
14 | .TH WCRTOMB 3 1999-07-25 "GNU" "Linux Programmer's Manual" | |
15 | .SH NAME | |
16 | wcrtomb \- convert a wide character to a multibyte sequence | |
17 | .SH SYNOPSIS | |
18 | .nf | |
19 | .B #include <wchar.h> | |
20 | .sp | |
21 | .BI "size_t wcrtomb(char *" s ", wchar_t " wc ", mbstate_t *" ps ); | |
22 | .fi | |
23 | .SH DESCRIPTION | |
c13182ef MK |
24 | The main case for this function is when \fIs\fP is |
25 | not NULL and \fIwc\fP is not | |
fea681da | 26 | L'\\0'. |
60a90ecd MK |
27 | In this case, the |
28 | .BR wcrtomb () | |
29 | function | |
c13182ef MK |
30 | converts the wide character \fIwc\fP |
31 | to its multibyte representation and stores it | |
32 | at the beginning of the character | |
33 | array pointed to by \fIs\fP. | |
34 | It updates the shift state \fI*ps\fP, and | |
35 | returns the length of said multibyte representation, | |
36 | i.e. the number of bytes | |
fea681da MK |
37 | written at \fIs\fP. |
38 | .PP | |
c13182ef MK |
39 | A different case is when \fIs\fP is not NULL but \fIwc\fP is L'\\0'. |
40 | In this | |
60a90ecd MK |
41 | case the |
42 | .BR wcrtomb () | |
43 | function stores at | |
c13182ef MK |
44 | the character array pointed to by |
45 | \fIs\fP the shift sequence needed to | |
46 | bring \fI*ps\fP back to the initial state, | |
47 | followed by a '\\0' byte. | |
48 | It updates the shift state \fI*ps\fP (i.e. brings | |
49 | it into the initial state), | |
50 | and returns the length of the shift sequence plus | |
fea681da MK |
51 | one, i.e. the number of bytes written at \fIs\fP. |
52 | .PP | |
c13182ef MK |
53 | A third case is when \fIs\fP is NULL. |
54 | In this case \fIwc\fP is ignored, | |
fea681da MK |
55 | and the function effectively returns wcrtomb(buf,L'\\0',\fIps\fP) where |
56 | buf is an internal anonymous buffer. | |
57 | .PP | |
58 | In all of the above cases, if \fIps\fP is a NULL pointer, a static anonymous | |
60a90ecd MK |
59 | state only known to the |
60 | .BR wcrtomb () | |
61 | function is used instead. | |
fea681da | 62 | .SH "RETURN VALUE" |
60a90ecd MK |
63 | The |
64 | .BR wcrtomb () | |
65 | function returns the number of | |
c13182ef MK |
66 | bytes that have been or would |
67 | have been written to the byte array at \fIs\fP. | |
68 | If \fIwc\fP can not be | |
fea681da | 69 | represented as a multibyte sequence (according to the current locale), |
dcec8eb5 | 70 | (size_t)(\-1) is returned, and \fIerrno\fP set to \fBEILSEQ\fP. |
fea681da | 71 | .SH "CONFORMING TO" |
68e1685c | 72 | C99. |
fea681da | 73 | .SH NOTES |
d9bfdb9c | 74 | The behavior of |
60a90ecd MK |
75 | .BR wcrtomb () |
76 | depends on the LC_CTYPE category of the | |
fea681da MK |
77 | current locale. |
78 | .PP | |
79 | Passing NULL as \fIps\fP is not multi-thread safe. | |
e37e3282 MK |
80 | .SH "SEE ALSO" |
81 | .BR wcsrtombs (3) |