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 $
26.\"
27.Dd April 8, 2004
28.Dt WCRTOMB 3
29.Os
30.Sh NAME
31.Nm wcrtomb
32.Nd "convert a wide-character code to a character (restartable)"
33.Sh LIBRARY
34.Lb libc
35.Sh SYNOPSIS
36.In wchar.h
37.Ft size_t
38.Fn wcrtomb "char * restrict s" "wchar_t wc" "mbstate_t * restrict ps"
39.Sh DESCRIPTION
40The
41.Fn wcrtomb
42function stores a multibyte sequence representing the
43wide character
44.Fa wc ,
45including any necessary shift sequences, to the
46character array
47.Fa s ,
48storing a maximum of
49.Dv MB_CUR_MAX
50bytes.
51.Pp
52If
53.Fa s
54is
55.Dv NULL ,
56.Fn wcrtomb
57behaves as if
58.Fa s
59pointed to an internal buffer and
60.Fa wc
61was a null wide character (L'\e0').
62.Pp
63The
64.Ft mbstate_t
65argument,
66.Fa ps ,
67is used to keep track of the shift state.
68If it is
69.Dv NULL ,
70.Fn wcrtomb
71uses an internal, static
72.Vt mbstate_t
73object, which is initialized to the initial conversion state
74at program startup.
75.Sh RETURN VALUES
76The
77.Fn wcrtomb
78functions returns the length (in bytes) of the multibyte sequence
79needed to represent
80.Fa wc ,
81or
82.Po Vt size_t Pc Ns \-1
83if
84.Fa wc
85is not a valid wide character code.
86.Sh ERRORS
87The
88.Fn wcrtomb
89function will fail if:
90.Bl -tag -width Er
91.It Bq Er EILSEQ
92An invalid wide character code was specified.
93.It Bq Er EINVAL
94The conversion state is invalid.
95.El
96.Sh SEE ALSO
97.Xr mbrtowc 3 ,
98.Xr multibyte 3 ,
99.Xr setlocale 3 ,
100.Xr wctomb 3
101.Sh STANDARDS
102The
103.Fn wcrtomb
104function conforms to
105.St -isoC-99 .
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 $
26.\"
27.Dd April 8, 2004
28.Dt WCRTOMB 3
29.Os
30.Sh NAME
31.Nm wcrtomb
32.Nd "convert a wide-character code to a character (restartable)"
33.Sh LIBRARY
34.Lb libc
35.Sh SYNOPSIS
36.In wchar.h
37.Ft size_t
38.Fn wcrtomb "char * restrict s" "wchar_t wc" "mbstate_t * restrict ps"
39.Sh DESCRIPTION
40The
41.Fn wcrtomb
42function stores a multibyte sequence representing the
43wide character
44.Fa wc ,
45including any necessary shift sequences, to the
46character array
47.Fa s ,
48storing a maximum of
49.Dv MB_CUR_MAX
50bytes.
51.Pp
52If
53.Fa s
54is
55.Dv NULL ,
56.Fn wcrtomb
57behaves as if
58.Fa s
59pointed to an internal buffer and
60.Fa wc
61was a null wide character (L'\e0').
62.Pp
63The
64.Ft mbstate_t
65argument,
66.Fa ps ,
67is used to keep track of the shift state.
68If it is
69.Dv NULL ,
70.Fn wcrtomb
71uses an internal, static
72.Vt mbstate_t
73object, which is initialized to the initial conversion state
74at program startup.
75.Sh RETURN VALUES
76The
77.Fn wcrtomb
78functions returns the length (in bytes) of the multibyte sequence
79needed to represent
80.Fa wc ,
81or
82.Po Vt size_t Pc Ns \-1
83if
84.Fa wc
85is not a valid wide character code.
86.Sh ERRORS
87The
88.Fn wcrtomb
89function will fail if:
90.Bl -tag -width Er
91.It Bq Er EILSEQ
92An invalid wide character code was specified.
93.It Bq Er EINVAL
94The conversion state is invalid.
95.El
96.Sh SEE ALSO
97.Xr mbrtowc 3 ,
98.Xr multibyte 3 ,
99.Xr setlocale 3 ,
100.Xr wctomb 3
101.Sh STANDARDS
102The
103.Fn wcrtomb
104function conforms to
105.St -isoC-99 .