]>
Commit | Line | Data |
---|---|---|
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 | |
25 | not NULL. | |
26 | In this case, the | |
27 | .BR mbtowc () | |
28 | function inspects at most \fIn\fP | |
29 | bytes of the multibyte string starting at \fIs\fP, | |
30 | extracts the next complete | |
31 | multibyte character, converts it to a wide character and stores it at | |
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 | |
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 | |
39 | character, or if they contain an invalid multibyte sequence, | |
40 | .BR mbtowc () | |
41 | returns \-1. | |
42 | This can happen even if \fIn\fP >= \fIMB_CUR_MAX\fP, | |
43 | if the multibyte string contains redundant shift sequences. | |
44 | .PP | |
45 | A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL. | |
46 | In this | |
47 | case the | |
48 | .BR mbtowc () | |
49 | function behaves as above, excepts that it does not | |
50 | store the converted wide character in memory. | |
51 | .PP | |
52 | A third case is when \fIs\fP is NULL. | |
53 | In this case, \fIpwc\fP and \fIn\fP are | |
54 | ignored. | |
55 | The | |
56 | .BR mbtowc () | |
57 | function | |
58 | .\" The Dinkumware doc and the Single Unix specification say this, but | |
59 | .\" glibc doesn't implement this. | |
60 | resets the shift state, only known to this function, | |
61 | to the initial state, and | |
62 | returns non-zero if the encoding has non-trivial shift state, or zero if the | |
63 | encoding is stateless. | |
64 | .SH "RETURN VALUE" | |
65 | If \fIs\fP is not NULL, the | |
66 | .BR mbtowc () | |
67 | function returns the number of | |
68 | consumed bytes starting at \fIs\fP, or 0 if \fIs\fP points to a null byte, | |
69 | or \-1 upon failure. | |
70 | .PP | |
71 | If \fIs\fP is NULL, the | |
72 | .BR mbtowc () | |
73 | function | |
74 | returns non-zero if the encoding | |
75 | has non-trivial shift state, or zero if the encoding is stateless. | |
76 | .SH "CONFORMING TO" | |
77 | C99 | |
78 | .SH NOTES | |
79 | The behaviour of | |
80 | .BR mbtowc () | |
81 | depends on the LC_CTYPE category of the | |
82 | current locale. | |
83 | .PP | |
84 | This function is not multi-thread safe. | |
85 | The function | |
86 | .BR mbrtowc (3) | |
87 | provides | |
88 | a better interface to the same functionality. | |
89 | .SH "SEE ALSO" | |
90 | .BR MB_CUR_MAX (3), | |
91 | .BR mbrtowc (3), | |
92 | .BR mbstowcs (3) |