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