]>
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 MBTOWC 3 2001-07-04 "GNU" "Linux Programmer's Manual" | |
15 | .SH NAME | |
16 | mbtowc \- convert a multibyte sequence to a wide character | |
17 | .SH SYNOPSIS | |
18 | .nf | |
19 | .B #include <stdlib.h> | |
20 | .sp | |
21 | .BI "int mbtowc(wchar_t *" pwc ", const char *" s ", size_t " n ); | |
22 | .fi | |
23 | .SH DESCRIPTION | |
24 | The main case for this function is when \fIs\fP is not NULL and \fIpwc\fP is | |
c13182ef | 25 | not NULL. |
60a90ecd MK |
26 | In this case, the |
27 | .BR mbtowc () | |
28 | function inspects at most \fIn\fP | |
c13182ef MK |
29 | bytes of the multibyte string starting at \fIs\fP, |
30 | extracts the next complete | |
fea681da | 31 | multibyte character, converts it to a wide character and stores it at |
c13182ef MK |
32 | \fI*pwc\fP. |
33 | It updates an internal shift state only known to the mbtowc | |
34 | function. | |
f81fb444 | 35 | If \fIs\fP does not point to a \(aq\\0\(aq byte, it returns the number |
fea681da MK |
36 | of bytes that were consumed from \fIs\fP, otherwise it returns 0. |
37 | .PP | |
38 | If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte | |
60a90ecd MK |
39 | character, or if they contain an invalid multibyte sequence, |
40 | .BR mbtowc () | |
00e28710 | 41 | returns \-1. |
c13182ef | 42 | This can happen even if \fIn\fP >= \fIMB_CUR_MAX\fP, |
fea681da MK |
43 | if the multibyte string contains redundant shift sequences. |
44 | .PP | |
c13182ef MK |
45 | A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL. |
46 | In this | |
60a90ecd MK |
47 | case the |
48 | .BR mbtowc () | |
5633d88a | 49 | function behaves as above, except that it does not |
fea681da MK |
50 | store the converted wide character in memory. |
51 | .PP | |
c13182ef MK |
52 | A third case is when \fIs\fP is NULL. |
53 | In this case, \fIpwc\fP and \fIn\fP are | |
54 | ignored. | |
60a90ecd MK |
55 | The |
56 | .BR mbtowc () | |
57 | function | |
fea681da MK |
58 | .\" The Dinkumware doc and the Single Unix specification say this, but |
59 | .\" glibc doesn't implement this. | |
c13182ef MK |
60 | resets the shift state, only known to this function, |
61 | to the initial state, and | |
c7094399 | 62 | returns nonzero if the encoding has nontrivial shift state, or zero if the |
fea681da MK |
63 | encoding is stateless. |
64 | .SH "RETURN VALUE" | |
60a90ecd MK |
65 | If \fIs\fP is not NULL, the |
66 | .BR mbtowc () | |
67 | function returns the number of | |
fea681da MK |
68 | consumed bytes starting at \fIs\fP, or 0 if \fIs\fP points to a null byte, |
69 | or \-1 upon failure. | |
70 | .PP | |
60a90ecd MK |
71 | If \fIs\fP is NULL, the |
72 | .BR mbtowc () | |
73 | function | |
c7094399 | 74 | returns nonzero if the encoding |
c382a365 | 75 | has nontrivial shift state, or zero if the encoding is stateless. |
fea681da | 76 | .SH "CONFORMING TO" |
44a2c328 | 77 | C99. |
fea681da | 78 | .SH NOTES |
d9bfdb9c | 79 | The behavior of |
60a90ecd | 80 | .BR mbtowc () |
1274071a MK |
81 | depends on the |
82 | .B LC_CTYPE | |
83 | category of the | |
fea681da MK |
84 | current locale. |
85 | .PP | |
71fea607 | 86 | This function is not multithread safe. |
60a90ecd MK |
87 | The function |
88 | .BR mbrtowc (3) | |
89 | provides | |
fea681da | 90 | a better interface to the same functionality. |
e37e3282 MK |
91 | .SH "SEE ALSO" |
92 | .BR MB_CUR_MAX (3), | |
93 | .BR mbrtowc (3), | |
94 | .BR mbstowcs (3) |