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