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