wcsrtombs.3 (8b8109275c1a583e96171df08e3136151c02279e) wcsrtombs.3 (1949a3470f29c5edaa5fc2770c2886d653fa68d1)
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.

--- 10 unchanged lines hidden (view full) ---

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$
26.\"
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.

--- 10 unchanged lines hidden (view full) ---

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$
26.\"
27.Dd April 8, 2004
27.Dd July 21, 2004
28.Dt WCSRTOMBS 3
29.Os
30.Sh NAME
28.Dt WCSRTOMBS 3
29.Os
30.Sh NAME
31.Nm wcsrtombs
31.Nm wcsrtombs ,
32.Nm wcsnrtombs
32.Nd "convert a wide-character string to a character string (restartable)"
33.Sh LIBRARY
34.Lb libc
35.Sh SYNOPSIS
36.In wchar.h
37.Ft size_t
38.Fo wcsrtombs
39.Fa "char * restrict dst" "const wchar_t ** restrict src"
40.Fa "size_t len" "mbstate_t * restrict ps"
41.Fc
33.Nd "convert a wide-character string to a character string (restartable)"
34.Sh LIBRARY
35.Lb libc
36.Sh SYNOPSIS
37.In wchar.h
38.Ft size_t
39.Fo wcsrtombs
40.Fa "char * restrict dst" "const wchar_t ** restrict src"
41.Fa "size_t len" "mbstate_t * restrict ps"
42.Fc
43.Ft size_t
44.Fo wcsnrtombs
45.Fa "char * restrict dst" "const wchar_t ** restrict src" "size_t nwc"
46.Fa "size_t len" "mbstate_t * restrict ps"
47.Fc
42.Sh DESCRIPTION
43The
44.Fn wcsrtombs
45function converts a string of wide characters indirectly pointed to by
46.Fa src
47to a corresponding multibyte character string stored in the array
48pointed to by
49.Fa dst .

--- 27 unchanged lines hidden (view full) ---

77is used to keep track of the shift state.
78If it is
79.Dv NULL ,
80.Fn wcsrtombs
81uses an internal, static
82.Vt mbstate_t
83object, which is initialized to the initial conversion state
84at program startup.
48.Sh DESCRIPTION
49The
50.Fn wcsrtombs
51function converts a string of wide characters indirectly pointed to by
52.Fa src
53to a corresponding multibyte character string stored in the array
54pointed to by
55.Fa dst .

--- 27 unchanged lines hidden (view full) ---

83is used to keep track of the shift state.
84If it is
85.Dv NULL ,
86.Fn wcsrtombs
87uses an internal, static
88.Vt mbstate_t
89object, which is initialized to the initial conversion state
90at program startup.
91.Pp
92The
93.Fn wcsnrtombs
94function behaves identically to
95.Fn wcsrtombs ,
96except that conversion stops after reading at most
97.Fa nwc
98characters from the buffer pointed to by
99.Fa src .
85.Sh RETURN VALUES
86The
87.Fn wcsrtombs
100.Sh RETURN VALUES
101The
102.Fn wcsrtombs
88function returns the number of bytes stored in
103and
104.Fn wcsnrtombs
105functions return the number of bytes stored in
89the array pointed to by
90.Fa dst
91(not including any terminating null), if successful, otherwise it returns
92.Po Vt size_t Pc Ns \-1 .
93.Sh ERRORS
94The
95.Fn wcsrtombs
106the array pointed to by
107.Fa dst
108(not including any terminating null), if successful, otherwise it returns
109.Po Vt size_t Pc Ns \-1 .
110.Sh ERRORS
111The
112.Fn wcsrtombs
96function will fail if:
113and
114.Fn wcsnrtombs
115functions will fail if:
97.Bl -tag -width Er
98.It Bq Er EILSEQ
99An invalid wide character was encountered.
100.It Bq Er EINVAL
101The conversion state is invalid.
102.El
103.Sh SEE ALSO
104.Xr mbsrtowcs 3 ,
105.Xr wcrtomb 3 ,
106.Xr wcstombs 3
107.Sh STANDARDS
108The
109.Fn wcsrtombs
110function conforms to
111.St -isoC-99 .
116.Bl -tag -width Er
117.It Bq Er EILSEQ
118An invalid wide character was encountered.
119.It Bq Er EINVAL
120The conversion state is invalid.
121.El
122.Sh SEE ALSO
123.Xr mbsrtowcs 3 ,
124.Xr wcrtomb 3 ,
125.Xr wcstombs 3
126.Sh STANDARDS
127The
128.Fn wcsrtombs
129function conforms to
130.St -isoC-99 .
131.Pp
132The
133.Fn wcsnrtombs
134function is an extension to the standard.