Deleted Added
sdiff udiff text old ( 128032 ) new ( 250883 )
full compact
1.\" Copyright (c) 2002-2004 Tim J. Robbins
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.

--- 8 unchanged lines hidden (view full) ---

17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD: head/lib/libc/locale/wcrtomb.3 128032 2004-04-08 09:59:02Z tjr $
25.\" $FreeBSD: head/lib/libc/locale/wcrtomb.3 250883 2013-05-21 19:59:37Z ed $
26.\"
27.Dd April 8, 2004
27.Dd May 21, 2013
28.Dt WCRTOMB 3
29.Os
30.Sh NAME
31.Nm wcrtomb
31.Nm wcrtomb ,
32.Nm c16rtomb ,
33.Nm c32rtomb
34.Nd "convert a wide-character code to a character (restartable)"
35.Sh LIBRARY
36.Lb libc
37.Sh SYNOPSIS
38.In wchar.h
39.Ft size_t
38.Fn wcrtomb "char * restrict s" "wchar_t wc" "mbstate_t * restrict ps"
40.Fn wcrtomb "char * restrict s" "wchar_t c" "mbstate_t * restrict ps"
41.In uchar.h
42.Ft size_t
43.Fn c16rtomb "char * restrict s" "char16_t c" "mbstate_t * restrict ps"
44.Ft size_t
45.Fn c32rtomb "char * restrict s" "char32_t c" "mbstate_t * restrict ps"
46.Sh DESCRIPTION
47The
41.Fn wcrtomb
42function stores a multibyte sequence representing the
48.Fn wcrtomb ,
49.Fn c16rtomb
50and
51.Fn c32rtomb
52functions store a multibyte sequence representing the
53wide character
44.Fa wc ,
54.Fa c ,
55including any necessary shift sequences, to the
56character array
57.Fa s ,
58storing a maximum of
59.Dv MB_CUR_MAX
60bytes.
61.Pp
62If
63.Fa s
64is
65.Dv NULL ,
56.Fn wcrtomb
57behaves as if
66these functions behave as if
67.Fa s
68pointed to an internal buffer and
60.Fa wc
69.Fa c
70was a null wide character (L'\e0').
71.Pp
72The
73.Ft mbstate_t
74argument,
75.Fa ps ,
76is used to keep track of the shift state.
77If it is
78.Dv NULL ,
70.Fn wcrtomb
71uses an internal, static
79these functions use an internal, static
80.Vt mbstate_t
81object, which is initialized to the initial conversion state
82at program startup.
83.Pp
84As certain multibyte characters may only be represented by a series of
8516-bit characters, the
86.Fn c16rtomb
87may need to invoked multiple times before a multibyte sequence is
88returned.
89.Sh RETURN VALUES
76The
77.Fn wcrtomb
78functions returns the length (in bytes) of the multibyte sequence
90These functions return the length (in bytes) of the multibyte sequence
91needed to represent
80.Fa wc ,
92.Fa c ,
93or
94.Po Vt size_t Pc Ns \-1
95if
84.Fa wc
96.Fa c
97is not a valid wide character code.
98.Sh ERRORS
99The
88.Fn wcrtomb
89function will fail if:
100.Fn wcrtomb ,
101.Fn c16rtomb
102and
103.Fn c32rtomb
104functions will fail if:
105.Bl -tag -width Er
106.It Bq Er EILSEQ
107An invalid wide character code was specified.
108.It Bq Er EINVAL
109The conversion state is invalid.
110.El
111.Sh SEE ALSO
112.Xr mbrtowc 3 ,
113.Xr multibyte 3 ,
114.Xr setlocale 3 ,
115.Xr wctomb 3
116.Sh STANDARDS
117The
103.Fn wcrtomb
104function conforms to
105.St -isoC-99 .
118.Fn wcrtomb ,
119.Fn c16rtomb
120and
121.Fn c32rtomb
122functions conform to
123.St -isoC-2011 .