Penguin
Recent Changes
Annotated edit history of mbrtowc(3) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 MBRTOWC
2 !!!MBRTOWC
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 RETURN VALUE
7 CONFORMING TO
8 SEE ALSO
9 NOTES
10 ----
11 !!NAME
12
13
14 mbrtowc - convert a multibyte sequence to a wide character
15 !!SYNOPSIS
16
17
18 __#include
19 __''pwc''__, const char *__''s''__, size_t__ ''n''__, mbstate_t *__''ps''__);
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 __mbrtowc__
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 the shift state
30 ''*ps''. If the converted wide character is not L'0', it
31 returns the number of bytes that were consumed from
32 ''s''. If the converted wide character is L'0', it resets
33 the shift state ''*ps'' to the initial state and returns
34 0.
35
36
37 If the ''n'' bytes starting at ''s'' do not contain a
38 complete multibyte character, __mbrtowc__ returns
39 ''(size_t)(-2)''. This can happen even if ''n''
40 ''MB_CUR_MAX'', if the multibyte string contains
41 redundant shift sequences.
42
43
44 If the multibyte string starting at ''s'' contains an
45 invalid multibyte sequence before the next complete
46 character, __mbrtowc__ returns ''(size_t)(-1)'' and
47 sets __errno__ to __EILSEQ__. In this case, the
48 effects on ''*ps'' are undefined.
49
50
51 A different case is when ''s'' is not NULL but ''pwc''
52 is NULL. In this case the __mbrtowc__ function behaves as
53 above, excepts that it does not store the converted wide
54 character in memory.
55
56
57 A third case is when ''s'' is NULL. In this case,
58 ''pwc'' and ''n'' are ignored. The __mbrtowc__
59 function puts ''*ps'' in the initial state and returns
60 0.
61
62
63 In all of the above cases, if ''ps'' is a NULL pointer, a
64 static anonymous state only known to the mbrtowc function is
65 used instead.
66 !!RETURN VALUE
67
68
69 The __mbrtowc__ function returns the number of bytes
70 parsed from the multibyte sequence starting at ''s'', if
71 a non-L'0' wide character was recognized. It returns 0, if a
72 L'0' wide character was recognized. It returns (size_t)(-1)
73 and sets __errno__ to __EILSEQ__, if an invalid
74 multibyte sequence was encountered. It returns (size_t)(-2)
75 if it couldn't parse a complete multibyte character, meaning
76 that ''n'' should be increased.
77 !!CONFORMING TO
78
79
80 ISO/ANSI C, UNIX98
81 !!SEE ALSO
82
83
84 mbsrtowcs(3)
85 !!NOTES
86
87
88 The behaviour of __mbrtowc__ depends on the LC_CTYPE
89 category of the current locale.
90 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.