Penguin
Recent Changes
Annotated edit history of mbtowc(3) version 4 showing authors affecting page license. View with all changes included.
Rev Author # Line
1 perry 1 MBTOWC
2 !!!MBTOWC
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 RETURN VALUE
7 CONFORMING TO
8 SEE ALSO
9 NOTES
10 ----
11 !!NAME
12
13
14 mbtowc - convert a multibyte sequence to a wide character
15 !!SYNOPSIS
16
17
18 __#include
19 __''pwc''__, const char *__''s''__, size_t__ ''n''__);
20 __
21 !!DESCRIPTION
22
23
24 The main case for this function is when ''s'' is not NULL
25 and ''pwc'' is not NULL. In this case, the __mbtowc__
26 function inspects at most ''n'' bytes of the multibyte
27 string starting at ''s'', extracts the next complete
28 multibyte character, converts it to a wide character and
29 stores it at ''*pwc''. It updates an internal shift state
30 only known to the mbtowc function. If ''s'' does not
31 point to a '0' byte, it returns the number of bytes that
32 were consumed from ''s'', otherwise it returns
33 0.
34
35
36 If the ''n'' bytes starting at ''s'' do not contain a
37 complete multibyte character, or if they contain an invalid
38 multibyte sequence, __mbtowc__ returns ''-1''. This
39 can happen even if ''n'' ''MB_CUR_MAX'', if the
40 multibyte string contains redundant shift
41 sequences.
42
43
44 A different case is when ''s'' is not NULL but ''pwc''
45 is NULL. In this case the __mbtowc__ function behaves as
46 above, excepts that it does not store the converted wide
47 character in memory.
48
49
50 A third case is when ''s'' is NULL. In this case,
51 ''pwc'' and ''n'' are ignored. The __mbtowc__
52 function resets the shift state, only known to this
53 function, to the initial state, and returns non-zero if the
54 encoding has non-trivial shift state, or zero if the
55 encoding is stateless.
56 !!RETURN VALUE
57
58
59 If ''s'' is not NULL, the __mbtowc__ function returns
60 the number of consumed bytes starting at ''s'', or 0 if
61 ''s'' points to a null byte, or -1 upon
62 failure.
63
64
65 If ''s'' is NULL, the __mbtowc__ function returns
66 non-zero if the encoding has non-trivial shift state, or
67 zero if the encoding is stateless.
68 !!CONFORMING TO
69
70
71 ISO/ANSI C, UNIX98
72 !!SEE ALSO
73
74
75 mbrtowc(3), mbstowcs(3),
76 MB_CUR_MAX(3)
77 !!NOTES
78
79
80 The behaviour of __mbtowc__ depends on the LC_CTYPE
81 category of the current locale.
82
83
84 This function is not multi-thread safe. The function
85 __mbrtowc__ provides a better interface to the same
86 functionality.
87 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.