xref: /dragonfly/lib/libc/locale/mbsrtowcs.3 (revision 9348a738) 
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/mbsrtowcs.3 140081 2005-01-11 20:50:51Z ru $
26.\"
27.Dd December 26, 2013
28.Dt MBSRTOWCS 3
29.Os
30.Sh NAME
31.Nm mbsrtowcs ,
32.Nm mbsrtowcs_l ,
33.Nm mbsnrtowcs ,
34.Nm mbsnrtowcs_l
35.Nd "convert a character string to a wide-character string (restartable)"
36.Sh LIBRARY
37.Lb libc
38.Sh SYNOPSIS
39.In wchar.h
40.Ft size_t
41.Fo mbsrtowcs
42.Fa "wchar_t * restrict dst" "const char ** restrict src" "size_t len"
43.Fa "mbstate_t * restrict ps"
44.Fc
45.Ft size_t
46.Fo mbsnrtowcs
47.Fa "wchar_t * restrict dst" "const char ** restrict src" "size_t nms"
48.Fa "size_t len" "mbstate_t * restrict ps"
49.Fc
50.In xlocale.h
51.Ft size_t
52.Fo mbsrtowcs_l
53.Fa "wchar_t * restrict dst" "const char ** restrict src" "size_t len"
54.Fa "mbstate_t * restrict ps" "locale_t locale"
55.Fc
56.Ft size_t
57.Fo mbsnrtowcs_l
58.Fa "wchar_t * restrict dst" "const char ** restrict src" "size_t nms"
59.Fa "size_t len" "mbstate_t * restrict ps" "locale_t locale"
60.Fc
61.Sh DESCRIPTION
62The
63.Fn mbsrtowcs
64and
65.Fn mbsrtowcs_l
66functions convert a sequence of multibyte characters pointed to indirectly by
67.Fa src
68into a sequence of corresponding wide characters and store at most
69.Fa len
70of them in the
71.Vt wchar_t
72array pointed to by
73.Fa dst ,
74until they encounter a terminating null character
75.Pq Li '\e0' .
76.Pp
77If
78.Fa dst
79is
80.Dv NULL ,
81no characters are stored.
82.Pp
83If
84.Fa dst
85is not
86.Dv NULL ,
87the pointer pointed to by
88.Fa src
89is updated to point to the character after the one that conversion stopped at.
90If conversion stops because a null character is encountered,
91.Fa *src
92is set to
93.Dv NULL .
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 ,
102.Fn mbsrtowcs
103and
104.Fn mbsrtowcs_l
105use an internal, static
106.Vt mbstate_t
107object, which is initialized to the initial conversion state
108at program startup.
109.Pp
110The
111.Fn mbsnrtowcs
112and
113.Fn mbsnrtowcs_l
114functions behave identically to
115.Fn mbsrtowcs
116and
117.Fn mbsrtowcs_l ,
118except that conversion stops after reading at most
119.Fa nms
120bytes from the buffer pointed to by
121.Fa src .
122.Pp
123The
124.Fn mbsrtowcs_l
125and
126.Fn mbsnrtowcs_l
127functions take an explicit
128.Fa locale
129argument, whereas the
130.Fn mbsrtowcs
131and
132.Fn mbsnrtowcs
133functions use the current global or per-thread locale.
134.Sh RETURN VALUES
135The
136.Fn mbsrtowcs ,
137.Fn mbsrtowcs_l ,
138.Fn mbsnrtowcs ,
139and
140.Fn mbsnrtowcs_l
141functions return the number of wide characters stored in
142the array pointed to by
143.Fa dst
144if successful, otherwise they return
145.Po Vt size_t Pc Ns \-1 .
146.Sh ERRORS
147The
148.Fn mbsrtowcs ,
149.Fn mbsrtowcs_l ,
150.Fn mbsnrtowcs ,
151and
152.Fn mbsnrtowcs_l
153functions will fail if:
154.Bl -tag -width Er
155.It Bq Er EILSEQ
156An invalid multibyte character sequence was encountered.
157.It Bq Er EINVAL
158The conversion state is invalid.
159.El
160.Sh SEE ALSO
161.Xr mbrtowc 3 ,
162.Xr mbstowcs 3 ,
163.Xr multibyte 3 ,
164.Xr wcsrtombs 3 ,
165.Xr xlocale 3
166.Sh STANDARDS
167The
168.Fn mbsrtowcs
169function conforms to
170.St -isoC-99 .
171.Pp
172The
173.Fn mbsrtowcs_l ,
174.Fn mbsnrtowcs ,
175and
176.Fn mbsnrtowcs_l
177functions are an extension to the standard.
178