Penguin
Blame: wcsnrtombs(3)
EditPageHistoryDiffInfoLikePages
Annotated edit history of wcsnrtombs(3) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 WCSNRTOMBS
2 !!!WCSNRTOMBS
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 RETURN VALUE
7 CONFORMING TO
8 SEE ALSO
9 NOTES
10 ----
11 !!NAME
12
13
14 wcsnrtombs - convert a wide character string to a multibyte string
15 !!SYNOPSIS
16
17
18 __#include
19 __''dest''__, const wchar_t **__''src''__, size_t__ ''nwc''__,
20 size_t__ ''len''__, mbstate_t *__''ps''__);
21 __
22 !!DESCRIPTION
23
24
25 The __wcsnrtombs__ function is like the __wcsrtombs__
26 function, except that the number of wide characters to be
27 converted, starting at ''*src'', is limited to
28 ''nwc''.
29
30
31 If ''dest'' is not a NULL pointer, the __wcsnrtombs__
32 function converts at most ''nwc'' wide characters from
33 the wide-character string ''*src'' to a multibyte string
34 starting at ''dest''. At most ''len'' bytes are
35 written to ''dest''. The shift state ''*ps'' is
36 updated. The conversion is effectively performed by
37 repeatedly calling
38 wcrtomb(''dest'',''*src'',''ps''), as long as this
39 call succeeds, and then incrementing ''dest'' by the
40 number of bytes written and ''*src'' by one. The
41 conversion can stop for three reasons:
42
43
44 1. A wide character has been encountered that can not be
45 represented as a multibyte sequence (according to the
46 current locale). In this case ''*src'' is left pointing
47 to the invalid wide character, (size_t)(-1) is returned, and
48 __errno__ is set to __EILSEQ__.
49
50
51 2. ''nwc'' wide characters have been converted without
52 encountering a L'0', or the length limit forces a stop. In
53 this case ''*src'' is left pointing to the next wide
54 character to be converted, and the number of bytes written
55 to ''dest'' is returned.
56
57
58 3. The wide-character string has been completely converted,
59 including the terminating L'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 bytes written
62 to ''dest'', excluding the terminating '0' byte, is
63 returned.
64
65
66 If ''dest'' is NULL, ''len'' is ignored, and the
67 conversion proceeds as above, except that the converted
68 bytes are not written out to memory, and that no destination
69 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 wcsnrtombs
74 function is used instead.
75
76
77 The programmer must ensure that there is room for at least
78 ''len'' bytes at ''dest''.
79 !!RETURN VALUE
80
81
82 The __wcsnrtombs__ function returns the number of bytes
83 that make up the converted part of multibyte sequence, not
84 including the terminating null byte. If a wide character was
85 encountered which could not be converted, (size_t)(-1) is
86 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 wcsrtombs(3), iconv(3)
96 !!NOTES
97
98
99 The behaviour of __wcsnrtombs__ 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.