Penguin
Recent Changes
Annotated edit history of wcstombs(3) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 WCSTOMBS
2 !!!WCSTOMBS
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 RETURN VALUE
7 CONFORMING TO
8 SEE ALSO
9 NOTES
10 ----
11 !!NAME
12
13
14 wcstombs - convert a wide character string to a multibyte string
15 !!SYNOPSIS
16
17
18 __#include
19 __''dest''__, const wchar_t *__''src''__, size_t__ ''n''__);
20 __
21 !!DESCRIPTION
22
23
24 If ''dest'' is not a NULL pointer, the __wcstombs__
25 function converts the wide-character string ''src'' to a
26 multibyte string starting at ''dest''. At most ''n''
27 bytes are written to ''dest''. The conversion starts in
28 the initial state. The conversion can stop for three
29 reasons:
30
31
32 1. A wide character has been encountered that can not be
33 represented as a multibyte sequence (according to the
34 current locale). In this case (size_t)(-1) is
35 returned.
36
37
38 2. The length limit forces a stop. In this case the number
39 of bytes written to ''dest'' is returned, but the shift
40 state at this point is lost.
41
42
43 3. The wide-character string has been completely converted,
44 including the terminating L'0'. In this case the conversion
45 ends in the initial state. The number of bytes written to
46 ''dest'', excluding the terminating '0' byte, is
47 returned.
48
49
50 The programmer must ensure that there is room for at least
51 ''n'' bytes at ''dest''.
52
53
54 If ''dest'' is NULL, ''n'' is ignored, and the
55 conversion proceeds as above, except that the converted
56 bytes are not written out to memory, and that no length
57 limit exists.
58
59
60 In order to avoid the case 2 above, the programmer should
61 make sure ''n'' is greater or equal to
62 ''wcstombs(NULL,src,0)+1''.
63 !!RETURN VALUE
64
65
66 The __wcstombs__ function returns the number of bytes
67 that make up the converted part of multibyte sequence, not
68 including the terminating null byte. If a wide character was
69 encountered which could not be converted, (size_t)(-1) is
70 returned.
71 !!CONFORMING TO
72
73
74 ISO/ANSI C, UNIX98
75 !!SEE ALSO
76
77
78 wcsrtombs(3)
79 !!NOTES
80
81
82 The behaviour of __wcstombs__ depends on the LC_CTYPE
83 category of the current locale.
84
85
86 The function __wcsrtombs__ provides a thread safe
87 interface to the same functionality.
88 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.