git.saurik.com Git - apple/libc.git/blame - locale/FreeBSD/wcsrtombs.3

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