[apple/libc.git] / locale / mbsrtowcs.3

.\" Copyright (c) 2002-2004 Tim J. Robbins
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/lib/libc/locale/mbsrtowcs.3,v 1.5 2004/07/21 10:54:57 tjr Exp $
.Dd July 21, 2004
.Dt MBSRTOWCS 3
.Os
.Sh NAME
.Nm mbsnrtowcs ,
.Nm mbsnrtowcs_l ,
.Nm mbsrtowcs ,
.Nm mbsrtowcs_l
.Nd "convert a character string to a wide-character string (restartable)"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In wchar.h
.Ft size_t
.Fo mbsnrtowcs
.Fa "wchar_t *restrict dst"
.Fa "const char **restrict src"
.Fa "size_t nms"
.Fa "size_t len"
.Fa "mbstate_t *restrict ps"
.Fc
.Ft size_t
.Fo mbsrtowcs
.Fa "wchar_t *restrict dst"
.Fa "const char **restrict src"
.Fa "size_t len"
.Fa "mbstate_t *restrict ps"
.Fc
.In wchar.h
.In xlocale.h
.Ft size_t
.Fo mbsrtowcs_l
.Fa "wchar_t *restrict dst"
.Fa "const char **restrict src"
.Fa "size_t len"
.Fa "mbstate_t *restrict ps"
.Fa "locale_t loc"
.Fc
.Ft size_t
.Fo mbsnrtowcs_l
.Fa "wchar_t *restrict dst"
.Fa "const char **restrict src"
.Fa "size_t nms"
.Fa "size_t len"
.Fa "mbstate_t *restrict ps"
.Fa "locale_t loc"
.Fc
.Sh DESCRIPTION
The
.Fn mbsrtowcs
function converts a sequence of multibyte characters, pointed to indirectly by
.Fa src ,
into a sequence of corresponding wide characters. It stores at most
.Fa len
of them in the
.Vt wchar_t
array pointed to by
.Fa dst ,
until it encounters a terminating null character
.Pq Li '\e0' .
.Pp
If
.Fa dst
is
.Dv NULL ,
no characters are stored.
.Pp
If
.Fa dst
is not
.Dv NULL ,
the pointer pointed to by
.Fa src
is updated to point to the character after the one that conversion stopped at.
If conversion stops because a null character is encountered,
.Fa *src
is set to
.Dv NULL .
.Pp
The
.Vt mbstate_t
argument,
.Fa ps ,
is used to keep track of the shift state.
If it is
.Dv NULL ,
.Fn mbsrtowcs
uses an internal, static
.Vt mbstate_t
object, which is initialized to the initial conversion state
at program startup.
.Pp
The
.Fn mbsnrtowcs
function behaves identically to
.Fn mbsrtowcs ,
except that conversion stops after reading at most
.Fa nms
bytes from the buffer pointed to by 
.Fa src .
.Pp
While the
.Fn mbsrtowcs
and
.Fn mbsnrtowcs
functions use the current locale, the
.Fn mbsrtowcs_l
and
.Fn mbsnrtowcs_l
functions may be passed locales directly. See
.Xr xlocale 3
for more information.
.Sh RETURN VALUES
The
.Fn mbsrtowcs
and
.Fn mbsnrtowcs
functions return the number of wide characters stored in
the array pointed to by
.Fa dst
if successful, otherwise it returns
.Po Vt size_t Pc Ns \-1 .
.Sh ERRORS
The
.Fn mbsrtowcs
and
.Fn mbsnrtowcs
functions will fail if:
.Bl -tag -width Er
.It Bq Er EILSEQ
An invalid multibyte character sequence was encountered.
.It Bq Er EINVAL
The conversion state is invalid.
.El
.Sh SEE ALSO
.Xr mbrtowc 3 ,
.Xr mbstowcs 3 ,
.Xr multibyte 3 ,
.Xr wcsrtombs 3 ,
.Xr xlocale 3
.Sh STANDARDS
The
.Fn mbsrtowcs
function conforms to
.St -isoC-99 .
.Pp
The
.Fn mbsnrtowcs
function is an extension to the standard.
Commit	Line	Data
224c7076 A	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: src/lib/libc/locale/mbsrtowcs.3,v 1.5 2004/07/21 10:54:57 tjr Exp $
	26	.Dd July 21, 2004
	27	.Dt MBSRTOWCS 3
	28	.Os
	29	.Sh NAME
	30	.Nm mbsnrtowcs ,
	31	.Nm mbsnrtowcs_l ,
	32	.Nm mbsrtowcs ,
	33	.Nm mbsrtowcs_l
	34	.Nd "convert a character string to a wide-character string (restartable)"
	35	.Sh LIBRARY
	36	.Lb libc
	37	.Sh SYNOPSIS
	38	.In wchar.h
	39	.Ft size_t
	40	.Fo mbsnrtowcs
	41	.Fa "wchar_t *restrict dst"
	42	.Fa "const char **restrict src"
	43	.Fa "size_t nms"
	44	.Fa "size_t len"
	45	.Fa "mbstate_t *restrict ps"
	46	.Fc
	47	.Ft size_t
	48	.Fo mbsrtowcs
	49	.Fa "wchar_t *restrict dst"
	50	.Fa "const char **restrict src"
	51	.Fa "size_t len"
	52	.Fa "mbstate_t *restrict ps"
	53	.Fc
	54	.In wchar.h
	55	.In xlocale.h
	56	.Ft size_t
	57	.Fo mbsrtowcs_l
	58	.Fa "wchar_t *restrict dst"
	59	.Fa "const char **restrict src"
	60	.Fa "size_t len"
	61	.Fa "mbstate_t *restrict ps"
	62	.Fa "locale_t loc"
	63	.Fc
	64	.Ft size_t
65	.Fo mbsnrtowcs_l
66	.Fa "wchar_t *restrict dst"
67	.Fa "const char **restrict src"
68	.Fa "size_t nms"
69	.Fa "size_t len"
70	.Fa "mbstate_t *restrict ps"
71	.Fa "locale_t loc"
72	.Fc
73	.Sh DESCRIPTION
74	The
75	.Fn mbsrtowcs
76	function converts a sequence of multibyte characters, pointed to indirectly by
77	.Fa src ,
78	into a sequence of corresponding wide characters. It stores at most
79	.Fa len
80	of them in the
81	.Vt wchar_t
82	array pointed to by
83	.Fa dst ,
84	until it encounters a terminating null character
85	.Pq Li '\e0' .
86	.Pp
87	If
88	.Fa dst
89	is
90	.Dv NULL ,
91	no characters are stored.
92	.Pp
93	If
94	.Fa dst
95	is not
96	.Dv NULL ,
97	the pointer pointed to by
98	.Fa src
99	is updated to point to the character after the one that conversion stopped at.
100	If conversion stops because a null character is encountered,
101	.Fa *src
102	is set to
103	.Dv NULL .
104	.Pp
105	The
106	.Vt mbstate_t
107	argument,
108	.Fa ps ,
109	is used to keep track of the shift state.
110	If it is
111	.Dv NULL ,
112	.Fn mbsrtowcs
113	uses an internal, static
114	.Vt mbstate_t
115	object, which is initialized to the initial conversion state
116	at program startup.
117	.Pp
118	The
119	.Fn mbsnrtowcs
120	function behaves identically to
121	.Fn mbsrtowcs ,
122	except that conversion stops after reading at most
123	.Fa nms
124	bytes from the buffer pointed to by
125	.Fa src .
126	.Pp
127	While the
128	.Fn mbsrtowcs
129	and
130	.Fn mbsnrtowcs
131	functions use the current locale, the
132	.Fn mbsrtowcs_l
133	and
134	.Fn mbsnrtowcs_l
135	functions may be passed locales directly. See
136	.Xr xlocale 3
137	for more information.
138	.Sh RETURN VALUES
139	The
140	.Fn mbsrtowcs
141	and
142	.Fn mbsnrtowcs
143	functions return the number of wide characters stored in
144	the array pointed to by
145	.Fa dst
146	if successful, otherwise it returns
147	.Po Vt size_t Pc Ns \-1 .
148	.Sh ERRORS
149	The
150	.Fn mbsrtowcs
151	and
152	.Fn mbsnrtowcs
153	functions will fail if:
154	.Bl -tag -width Er
155	.It Bq Er EILSEQ
156	An invalid multibyte character sequence was encountered.
157	.It Bq Er EINVAL
158	The 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
167	The
168	.Fn mbsrtowcs
169	function conforms to
170	.St -isoC-99 .
171	.Pp
172	The
173	.Fn mbsnrtowcs
174	function is an extension to the standard.