1.\" $MirOS: src/lib/libc/locale/wcsrtombs.3,v 1.5 2014/02/09 22:35:55 tg Exp $
2.\" $OpenBSD: wcsrtombs.3,v 1.1 2005/05/11 18:44:12 espie Exp $
3.\" $NetBSD: wcsrtombs.3,v 1.6 2003/09/08 17:54:32 wiz Exp $
4.\"
5.\" Copyright (c)2002 Citrus Project,
6.\" All rights reserved.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\"
17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27.\" SUCH DAMAGE.
28.\"
29.Dd $Mdocdate: February 9 2014 $
30.Dt WCSRTOMBS 3
31.Os
32.\" ----------------------------------------------------------------------
33.Sh NAME
34.Nm wcsrtombs ,
35.Nm wcsnrtombs
36.Nd convert a wide character string to a multibyte character string \
37(restartable)
38.\" ----------------------------------------------------------------------
39.Sh SYNOPSIS
40.Fd #include <stdlib.h>
41.Ft size_t
42.Fn wcsrtombs "char *s" "const wchar_t **pwcs" "size_t n" "mbstate_t *ps"
43.Ft size_t
44.Fn wcsnrtombs "char *s" "const wchar_t **pwcs" "size_t max" "size_t n" "mbstate_t *ps"
45.\" ----------------------------------------------------------------------
46.Sh DESCRIPTION
47.Fn wcsrtombs
48converts the null-terminated wide character string indirectly pointed to by
49.Fa pwcs
50to the corresponding multibyte character string,
51and store it to the array pointed to by
52.Fa s .
53The
54.Fn wcsnrtombs
55function behaves the same, but reads at most
56.Fa max
57wide characters from the wide character string indirectly pointed to by
58.Fa pwcs .
59The conversion stops due to the following reasons:
60.Bl -bullet
61.It
62The conversion reaches a null wide character.
63In this case, the null wide character is also converted.
64.It
65.Fn wcsrtombs
66or
67.Fn wcsnrtombs
68has already stored
69.Fa n
70bytes to the array pointed to by
71.Fa s .
72.It
73The conversion encounters an invalid character.
74.It
75The
76.Fn wcsnrtombs
77function has already devoured
78.Fa max
79wide characters.
80.El
81.Pp
82Each characters will be converted as if
83.Xr wcrtomb 3
84is continuously called, except the internal state of
85.Xr wcrtomb 3
86will not be affected.
87.Pp
88After conversion,
89if
90.Fa s
91is not a
92.Dv NULL
93pointer,
94the pointer object pointed to by
95.Fa pwcs
96is a
97.Dv NULL
98pointer (if the conversion is stopped due to reaching a null wide character)
99or the first byte of the character just after the last character converted.
100.Pp
101If
102.Fa s
103is not a null pointer and the conversion is stopped due to reaching
104a null wide character,
105.Fn wcsrtombs
106and
107.Fn wcsnrtombs
108place the state object pointed to by
109.Fa ps
110to an initial state after the conversion is taken place.
111.Pp
112The behaviour of the
113.Fn wcsrtombs
114and
115.Fn wcsnrtombs
116is affected by the
117.Dv LC_CTYPE
118category of the current locale.
119.Pp
120These are the special cases:
121.Bl -tag -width 012345678901
122.It "s == NULL"
123.Fn wcsrtombs
124and
125.Fn wcsnrtombs
126return the number of bytes to store the whole multibyte character string
127corresponding to the wide character string pointed to by
128.Fa pwcs ,
129not including the terminating null byte.
130In this case,
131.Fa n
132is ignored.
133.It "pwcs == NULL || *pwcs == NULL"
134Undefined (may causes the program to crash).
135.It "ps == NULL"
136.Fn wcsrtombs
137uses its own internal state object to keep the conversion state,
138instead of
139.Fa ps
140mentioned in this manual page.
141.Fn wcsnrtombs
142has an own internal state which is different from the one of
143.Fn wcsrtombs .
144.Pp
145Calling any other functions in
146.Em libc
147never change the internal
148state of
149.Fn wcsnrtombs
150or
151.Fn wcsrtombs ,
152that is initialised at startup time of the program.
153.El
154.\" ----------------------------------------------------------------------
155.Sh RETURN VALUES
156.Fn wcsrtombs
157and
158.Fn wcsnrtombs
159return:
160.Bl -tag -width 012345678901
161.It 0 or positive
162Number of bytes stored to the array pointed to by
163.Fa s ,
164except for a null byte.
165There is no cases that the value returned is greater than
166.Fa n
167(unless
168.Fa s
169is a null pointer).
170If the return value is equal to
171.Fa n ,
172the string pointed to by
173.Fa s
174will not be null-terminated.
175.It (size_t)-1
176.Fa pwcs
177points to the string containing invalid wide character.
178.Fn wcsrtombs
179and
180.Fn wcsnrtombs
181also set errno to indicate the error.
182.El
183.\" ----------------------------------------------------------------------
184.Sh ERRORS
185.Fn wcsrtombs
186and
187.Fn wcsnrtombs
188may cause an error in the following cases:
189.Bl -tag -width Er
190.It Bq Er EILSEQ
191.Fa pwcs
192points to the string containing an invalid wide character.
193.El
194.\" ----------------------------------------------------------------------
195.Sh SEE ALSO
196.Xr optu16to8 3 ,
197.Xr setlocale 3 ,
198.Xr wcrtomb 3 ,
199.Xr wcstombs 3
200.\" ----------------------------------------------------------------------
201.Sh STANDARDS
202The
203.Fn wcsrtombs
204function conforms to
205.St -ansiC .
206The
207.Fn wcsnrtombs
208function is a GNU extension.
209.Sh HISTORY
210.Fn wcsnrtombs
211first appeared in
212.Mx 10 .
213