]>
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. | |
35 | If \fIs\fP does not point to a '\\0' 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 () | |
49 | function behaves as above, excepts 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 | |
fea681da MK |
62 | returns non-zero if the encoding has non-trivial shift state, or zero if the |
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 | |
c13182ef | 74 | returns non-zero if the encoding |
fea681da MK |
75 | has non-trivial shift state, or zero if the encoding is stateless. |
76 | .SH "CONFORMING TO" | |
68e1685c | 77 | C99 |
fea681da | 78 | .SH NOTES |
60a90ecd MK |
79 | The behaviour of |
80 | .BR mbtowc () | |
81 | depends on the LC_CTYPE category of the | |
fea681da MK |
82 | current locale. |
83 | .PP | |
c13182ef | 84 | This function is not multi-thread safe. |
60a90ecd MK |
85 | The function |
86 | .BR mbrtowc (3) | |
87 | provides | |
fea681da | 88 | a better interface to the same functionality. |
e37e3282 MK |
89 | .SH "SEE ALSO" |
90 | .BR MB_CUR_MAX (3), | |
91 | .BR mbrtowc (3), | |
92 | .BR mbstowcs (3) |