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