Penguin
Recent Changes
Blame: mbsrtowcs(3)
EditPageHistoryDiffInfoLikePages
Annotated edit history of mbsrtowcs(3) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 MBSRTOWCS
2 !!!MBSRTOWCS
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 RETURN VALUE
7 CONFORMING TO
8 SEE ALSO
9 NOTES
10 ----
11 !!NAME
12
13
14 mbsrtowcs - convert a multibyte string to a wide character string
15 !!SYNOPSIS
16
17
18 __#include
19 __''dest''__, const char **__''src''__,
20 size_t__ ''len''__, mbstate_t *__''ps''__);
21 __
22 !!DESCRIPTION
23
24
25 If ''dest'' is not a NULL pointer, the __mbsrtowcs__
26 function converts the multibyte string ''*src'' to a
27 wide-character string starting at ''dest''. At most
28 ''len'' wide characters are written to ''dest''. The
29 shift state ''*ps'' is updated. The conversion is
30 effectively performed by repeatedly calling
31 mbrtowc(''dest'',''*src'',''n'',''ps'') where
32 ''n'' is some positive number, as long as this call
33 succeeds, and then incrementing ''dest'' by one and
34 ''*src'' by the number of bytes consumed. The conversion
35 can stop for three reasons:
36
37
38 1. An invalid multibyte sequence has been encountered. In
39 this case ''*src'' is left pointing to the invalid
40 multibyte sequence, (size_t)(-1) is returned, and
41 __errno__ is set to __EILSEQ__.
42
43
44 2. ''len'' non-L'0' wide characters have been stored at
45 ''dest''. In this case ''*src'' is left pointing to
46 the next multibyte sequence to be converted, and the number
47 of wide characters written to ''dest'' is
48 returned.
49
50
51 3. The multibyte string has been completely converted,
52 including the terminating '0' (which has the side effect of
53 bringing back ''*ps'' to the initial state). In this case
54 ''*src'' is set to NULL, and the number of wide
55 characters written to ''dest'', excluding the terminating
56 L'0' character, is returned.
57
58
59 If ''dest'' is NULL, ''len'' is ignored, and the
60 conversion proceeds as above, except that the converted wide
61 characters are not written out to memory, and that no length
62 limit exists.
63
64
65 In both of the above cases, if ''ps'' is a NULL pointer,
66 a static anonymous state only known to the mbsrtowcs
67 function is used instead.
68
69
70 The programmer must ensure that there is room for at least
71 ''len'' wide characters at ''dest''.
72 !!RETURN VALUE
73
74
75 The __mbsrtowcs__ function returns the number of wide
76 characters that make up the converted part of the wide
77 character string, not including the terminating null wide
78 character. If an invalid multibyte sequence was encountered,
79 (size_t)(-1) is returned, and __errno__ set to
80 __EILSEQ__.
81 !!CONFORMING TO
82
83
84 ISO/ANSI C, UNIX98
85 !!SEE ALSO
86
87
88 mbstowcs(3), mbsnrtowcs(3),
89 iconv(3)
90 !!NOTES
91
92
93 The behaviour of __mbsrtowcs__ depends on the LC_CTYPE
94 category of the current locale.
95
96
97 Passing NULL as ''ps'' is not multi-thread
98 safe.
99 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.