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