1MBTOWC(3P) POSIX Programmer's Manual MBTOWC(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 mbtowc - convert a character to a wide-character code
13
15 #include <stdlib.h>
16 int mbtowc(wchar_t *restrict pwc, const char *restrict s, size_t n);
18
21 If s is not a null pointer, mbtowc() shall determine the number of
22 bytes that constitute the character pointed to by s. It shall then
23 determine the wide-character code for the value of type wchar_t that
24 corresponds to that character. (The value of the wide-character code
25 corresponding to the null byte is 0.) If the character is valid and pwc
26 is not a null pointer, mbtowc() shall store the wide-character code in
27 the object pointed to by pwc.
28 The behavior of this function is affected by the LC_CTYPE category of
30 the current locale. For a state-dependent encoding, this function is
31 placed into its initial state by a call for which its character pointer
32 argument, s, is a null pointer. Subsequent calls with s as other than
33 a null pointer shall cause the internal state of the function to be
34 altered as necessary. A call with s as a null pointer shall cause this
35 function to return a non-zero value if encodings have state dependency,
36 and 0 otherwise. If the implementation employs special bytes to change
37 the shift state, these bytes shall not produce separate wide-character
38 codes, but shall be grouped with an adjacent character. Changing the
39 LC_CTYPE category causes the shift state of this function to be unspec‐
40 ified. At most n bytes of the array pointed to by s shall be examined.
41 The implementation shall behave as if no function defined in this vol‐
43 ume of IEEE Std 1003.1-2001 calls mbtowc().
44
46 If s is a null pointer, mbtowc() shall return a non-zero or 0 value, if
47 character encodings, respectively, do or do not have state-dependent
48 encodings. If s is not a null pointer, mbtowc() shall either return 0
49 (if s points to the null byte), or return the number of bytes that con‐
50 stitute the converted character (if the next n or fewer bytes form a
51 valid character), or return -1 and may set errno to indicate the error
52 (if they do not form a valid character).
53 In no case shall the value returned be greater than n or the value of
55 the {MB_CUR_MAX} macro.
56
58 The mbtowc() function may fail if:
59 EILSEQ Invalid character sequence is detected.
61 The following sections are informative.
64
66 None.
67
69 None.
70
72 None.
73
75 None.
76
78 mblen(), mbstowcs(), wctomb(), wcstombs(), the Base Definitions volume
79 of IEEE Std 1003.1-2001, <stdlib.h>
80
82 Portions of this text are reprinted and reproduced in electronic form
83 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
84 -- Portable Operating System Interface (POSIX), The Open Group Base
85 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
86 Electrical and Electronics Engineers, Inc and The Open Group. In the
87 event of any discrepancy between this version and the original IEEE and
88 The Open Group Standard, the original IEEE and The Open Group Standard
89 is the referee document. The original Standard can be obtained online
90 at http://www.opengroup.org/unix/online.html .
91IEEE/The Open Group 2003 MBTOWC(3P)