]> git.saurik.com Git - apple/libc.git/blame - locale/FreeBSD/wcrtomb.3
Libc-1082.50.1.tar.gz
[apple/libc.git] / locale / FreeBSD / wcrtomb.3
CommitLineData
3d9156a7 1.\" Copyright (c) 2002-2004 Tim J. Robbins
5b2abdfb
A
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.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
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.\"
3d9156a7 25.\" $FreeBSD: src/lib/libc/locale/wcrtomb.3,v 1.4 2004/04/08 09:59:02 tjr Exp $
5b2abdfb 26.\"
3d9156a7 27.Dd April 8, 2004
9385eb3d 28.Dt WCRTOMB 3
5b2abdfb
A
29.Os
30.Sh NAME
ad3c9f2a
A
31.Nm wcrtomb ,
32.Nm wcrtomb_l
9385eb3d 33.Nd "convert a wide-character code to a character (restartable)"
5b2abdfb
A
34.Sh LIBRARY
35.Lb libc
36.Sh SYNOPSIS
9385eb3d
A
37.In wchar.h
38.Ft size_t
ad3c9f2a
A
39.Fo wcrtomb
40.Fa "char *restrict s"
41.Fa "wchar_t wc"
42.Fa "mbstate_t *restrict ps"
43.Fc
44.In wchar.h
45.In xlocale.h
46.Ft size_t
47.Fo wcrtomb_l
48.Fa "char *restrict s"
49.Fa "wchar_t wc"
50.Fa "mbstate_t *restrict ps"
51.Fa "locale_t loc"
52.Fc
5b2abdfb 53.Sh DESCRIPTION
9385eb3d
A
54The
55.Fn wcrtomb
56function stores a multibyte sequence representing the
57wide character
58.Fa wc ,
59including any necessary shift sequences, to the
60character array
ad3c9f2a
A
61.Fa s .
62A maximum of
9385eb3d 63.Dv MB_CUR_MAX
ad3c9f2a 64bytes will be stored.
5b2abdfb 65.Pp
9385eb3d
A
66If
67.Fa s
68is
69.Dv NULL ,
70.Fn wcrtomb
71behaves as if
72.Fa s
73pointed to an internal buffer and
74.Fa wc
ad3c9f2a 75were a null wide character (L'\e0').
5b2abdfb 76.Pp
9385eb3d
A
77The
78.Ft mbstate_t
79argument,
80.Fa ps ,
81is used to keep track of the shift state.
82If it is
83.Dv NULL ,
84.Fn wcrtomb
85uses an internal, static
86.Vt mbstate_t
3d9156a7
A
87object, which is initialized to the initial conversion state
88at program startup.
ad3c9f2a
A
89.Pp
90While the
91.Fn wcrtomb
92function uses the current locale, the
93.Fn wcrtomb_l
94function may be passed a locale directly. See
95.Xr xlocale 3
96for more information.
9385eb3d
A
97.Sh RETURN VALUES
98The
99.Fn wcrtomb
100functions returns the length (in bytes) of the multibyte sequence
101needed to represent
102.Fa wc ,
103or
104.Po Vt size_t Pc Ns \-1
105if
106.Fa wc
107is not a valid wide character code.
5b2abdfb 108.Sh ERRORS
9385eb3d
A
109The
110.Fn wcrtomb
111function will fail if:
112.Bl -tag -width Er
9385eb3d
A
113.It Bq Er EILSEQ
114An invalid wide character code was specified.
3d9156a7
A
115.It Bq Er EINVAL
116The conversion state is invalid.
9385eb3d 117.El
5b2abdfb 118.Sh SEE ALSO
9385eb3d 119.Xr mbrtowc 3 ,
3d9156a7 120.Xr multibyte 3 ,
9385eb3d 121.Xr setlocale 3 ,
ad3c9f2a
A
122.Xr wctomb 3 ,
123.Xr xlocale 3
9385eb3d 124.Sh STANDARDS
5b2abdfb 125The
9385eb3d
A
126.Fn wcrtomb
127function conforms to
128.St -isoC-99 .