xref: /dragonfly/lib/libc/locale/mbrtowc.3 (revision 19b217af) 
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.
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.\"
25.\" $FreeBSD: head/lib/libc/locale/mbrtowc.3 250883 2013-05-21 19:59:37Z ed $
26.\"
27.Dd May 21, 2013
28.Dt MBRTOWC 3
29.Os
30.Sh NAME
31.Nm mbrtowc ,
32.Nm mbrtoc16 ,
33.Nm mbrtoc32
34.Nd "convert a character to a wide-character code (restartable)"
35.Sh LIBRARY
36.Lb libc
37.Sh SYNOPSIS
38.In wchar.h
39.Ft size_t
40.Fo mbrtowc
41.Fa "wchar_t * restrict pc" "const char * restrict s" "size_t n"
42.Fa "mbstate_t * restrict ps"
43.Fc
44.In uchar.h
45.Ft size_t
46.Fo mbrtoc16
47.Fa "char16_t * restrict pc" "const char * restrict s" "size_t n"
48.Fa "mbstate_t * restrict ps"
49.Fc
50.Ft size_t
51.Fo mbrtoc32
52.Fa "char32_t * restrict pc" "const char * restrict s" "size_t n"
53.Fa "mbstate_t * restrict ps"
54.Fc
55.Sh DESCRIPTION
56The
57.Fn mbrtowc ,
58.Fn mbrtoc16
59and
60.Fn mbrtoc32
61functions inspect at most
62.Fa n
63bytes pointed to by
64.Fa s
65to determine the number of bytes needed to complete the next multibyte
66character.
67If a character can be completed, and
68.Fa pc
69is not
70.Dv NULL ,
71the wide character which is represented by
72.Fa s
73is stored in the
74.Vt wchar_t ,
75.Vt char16_t
76or
77.Vt char32_t
78it points to.
79.Pp
80If
81.Fa s
82is
83.Dv NULL ,
84these functions behave as if
85.Fa pc
86was
87.Dv NULL ,
88.Fa s
89was an empty string
90.Pq Qq
91and
92.Fa n
93was 1.
94.Pp
95The
96.Vt mbstate_t
97argument,
98.Fa ps ,
99is used to keep track of the shift state.
100If it is
101.Dv NULL ,
102these functions use an internal, static
103.Vt mbstate_t
104object, which is initialized to the initial conversion state
105at program startup.
106.Pp
107As a single
108.Vt char16_t
109is not large enough to represent certain multibyte characters, the
110.Fn mbrtoc16
111function may need to be invoked multiple times to convert a single
112multibyte character sequence.
113.Sh RETURN VALUES
114The
115.Fn mbrtowc ,
116.Fn mbrtoc16
117and
118.Fn mbrtoc32
119functions return:
120.Bl -tag -width indent
121.It 0
122The next
123.Fa n
124or fewer bytes
125represent the null wide character
126.Pq Li "L'\e0'" .
127.It >0
128The next
129.Fa n
130or fewer bytes represent a valid character, these functions
131return the number of bytes used to complete the multibyte character.
132.It Po Vt size_t Pc Ns \-1
133An encoding error has occurred.
134The next
135.Fa n
136or fewer bytes do not contribute to a valid multibyte character.
137.It Po Vt size_t Pc Ns \-2
138The next
139.Fa n
140contribute to, but do not complete, a valid multibyte character sequence,
141and all
142.Fa n
143bytes have been processed.
144.El
145.Pp
146The
147.Fn mbrtoc16
148function also returns:
149.Bl -tag -width indent
150.It Po Vt size_t Pc Ns \-3
151The next character resulting from a previous call has been stored.
152No bytes from the input have been consumed.
153.El
154.Sh ERRORS
155The
156.Fn mbrtowc ,
157.Fn mbrtoc16
158and
159.Fn mbrtoc32
160functions will fail if:
161.Bl -tag -width Er
162.It Bq Er EILSEQ
163An invalid multibyte sequence was detected.
164.It Bq Er EINVAL
165The conversion state is invalid.
166.El
167.Sh SEE ALSO
168.Xr mbtowc 3 ,
169.Xr multibyte 3 ,
170.Xr setlocale 3 ,
171.Xr wcrtomb 3
172.Sh STANDARDS
173The
174.Fn mbrtowc ,
175.Fn mbrtoc16
176and
177.Fn mbrtoc32
178functions conform to
179.St -isoC-2011 .
180