]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) Bruno Haible <haible@clisp.cons.org> |
2 | .\" | |
89e3ffe9 | 3 | .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) |
fea681da MK |
4 | .\" This is free documentation; you can redistribute it and/or |
5 | .\" modify it under the terms of the GNU General Public License as | |
6 | .\" published by the Free Software Foundation; either version 2 of | |
7 | .\" the License, or (at your option) any later version. | |
fe382ebf | 8 | .\" %%%LICENSE_END |
fea681da MK |
9 | .\" |
10 | .\" References consulted: | |
11 | .\" GNU glibc-2 source code and manual | |
12 | .\" Dinkumware C library reference http://www.dinkumware.com/ | |
008f1ecc | 13 | .\" OpenGroup's Single UNIX specification |
fea681da MK |
14 | .\" http://www.UNIX-systems.org/online.html |
15 | .\" ISO/IEC 9899:1999 | |
16 | .\" | |
e9c23bc6 | 17 | .TH MBRTOWC 3 2011-09-28 "GNU" "Linux Programmer's Manual" |
fea681da MK |
18 | .SH NAME |
19 | mbrtowc \- convert a multibyte sequence to a wide character | |
20 | .SH SYNOPSIS | |
21 | .nf | |
22 | .B #include <wchar.h> | |
23 | .sp | |
3d54a910 MK |
24 | .BI "size_t mbrtowc(wchar_t *" pwc ", const char *" s ", size_t " n \ |
25 | ", mbstate_t *" ps ); | |
fea681da MK |
26 | .fi |
27 | .SH DESCRIPTION | |
28 | The main case for this function is when \fIs\fP is not NULL and \fIpwc\fP is | |
c13182ef | 29 | not NULL. |
60a90ecd MK |
30 | In this case, the |
31 | .BR mbrtowc () | |
32 | function inspects at most \fIn\fP | |
fea681da MK |
33 | bytes of the multibyte string starting at \fIs\fP, extracts the next complete |
34 | multibyte character, converts it to a wide character and stores it at | |
c13182ef MK |
35 | \fI*pwc\fP. |
36 | It updates the shift state \fI*ps\fP. | |
37 | If the converted wide | |
e9c23bc6 MK |
38 | character is not L\(aq\\0\(aq (the null wide character), |
39 | it returns the number of bytes that were consumed | |
c13182ef | 40 | from \fIs\fP. |
f81fb444 | 41 | If the converted wide character is L\(aq\\0\(aq, it resets the shift |
fea681da MK |
42 | state \fI*ps\fP to the initial state and returns 0. |
43 | .PP | |
44 | If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte | |
60a90ecd MK |
45 | character, |
46 | .BR mbrtowc () | |
009df872 | 47 | returns \fI(size_t)\ \-2\fP. |
c13182ef | 48 | This can happen even if |
fea681da MK |
49 | \fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift |
50 | sequences. | |
51 | .PP | |
52 | If the multibyte string starting at \fIs\fP contains an invalid multibyte | |
60a90ecd MK |
53 | sequence before the next complete character, |
54 | .BR mbrtowc () | |
55 | returns | |
e17aa487 | 56 | \fI(size_t)\ \-1\fP and sets \fIerrno\fP to \fBEILSEQ\fP. |
c13182ef | 57 | In this case, |
fea681da MK |
58 | the effects on \fI*ps\fP are undefined. |
59 | .PP | |
c13182ef MK |
60 | A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL. |
61 | In this | |
60a90ecd MK |
62 | case the |
63 | .BR mbrtowc () | |
5633d88a | 64 | function behaves as above, except that it does not |
fea681da MK |
65 | store the converted wide character in memory. |
66 | .PP | |
c13182ef MK |
67 | A third case is when \fIs\fP is NULL. |
68 | In this case, \fIpwc\fP and \fIn\fP are | |
69 | ignored. | |
70 | If the conversion state represented by \fI*ps\fP denotes an | |
60a90ecd MK |
71 | incomplete multibyte character conversion, the |
72 | .BR mbrtowc () | |
73 | function | |
e17aa487 | 74 | returns \fI(size_t)\ \-1\fP, sets \fIerrno\fP to \fBEILSEQ\fP, and |
c13182ef | 75 | leaves \fI*ps\fP in an undefined state. |
60a90ecd MK |
76 | Otherwise, the |
77 | .BR mbrtowc () | |
78 | function | |
fea681da MK |
79 | puts \fI*ps\fP in the initial state and returns 0. |
80 | .PP | |
81 | In all of the above cases, if \fIps\fP is a NULL pointer, a static anonymous | |
82 | state only known to the mbrtowc function is used instead. | |
d9a10d9d MK |
83 | Otherwise, \fI*ps\fP must be a valid \fImbstate_t\fP object. |
84 | An \fImbstate_t\fP object \fIa\fP can be initialized to the initial state | |
fea681da MK |
85 | by zeroing it, for example using |
86 | .sp | |
a6e2f128 | 87 | .in +4n |
fea681da | 88 | memset(&a, 0, sizeof(a)); |
a6e2f128 | 89 | .in |
47297adb | 90 | .SH RETURN VALUE |
60a90ecd MK |
91 | The |
92 | .BR mbrtowc () | |
93 | function returns the number of bytes parsed from the | |
f81fb444 | 94 | multibyte sequence starting at \fIs\fP, if a non-L\(aq\\0\(aq wide character |
fea681da | 95 | was recognized. |
f81fb444 | 96 | It returns 0, if a L\(aq\\0\(aq wide character was recognized. |
7d2cb9d5 | 97 | It returns |
009df872 | 98 | .I (size_t)\ \-1 |
dcec8eb5 | 99 | and sets \fIerrno\fP to \fBEILSEQ\fP, if an invalid multibyte sequence was |
c13182ef | 100 | encountered. |
009df872 | 101 | It returns \fI(size_t)\ \-2\fP if it couldn't parse a complete multibyte |
fea681da | 102 | character, meaning that \fIn\fP should be increased. |
47297adb | 103 | .SH CONFORMING TO |
44a2c328 | 104 | C99. |
fea681da | 105 | .SH NOTES |
d9bfdb9c | 106 | The behavior of |
60a90ecd | 107 | .BR mbrtowc () |
1274071a MK |
108 | depends on the |
109 | .B LC_CTYPE | |
110 | category of the | |
fea681da | 111 | current locale. |
47297adb | 112 | .SH SEE ALSO |
e37e3282 | 113 | .BR mbsrtowcs (3) |