git.saurik.com Git - apple/libc.git/blame_incremental

... / ...

Commit	Line	Data
	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/wcsrtombs.3,v 1.5 2004/07/21 10:54:57 tjr Exp $
	26	.\"
	27	.Dd July 21, 2004
	28	.Dt WCSRTOMBS 3
	29	.Os
	30	.Sh NAME
	31	.Nm wcsnrtombs ,
	32	.Nm wcsnrtombs_l ,
	33	.Nm wcsrtombs ,
	34	.Nm wcsrtombs_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 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
	49	.Fo wcsrtombs
	50	.Fa "char *restrict dst"
	51	.Fa "const wchar_t **restrict src"
	52	.Fa "size_t len"
	53	.Fa "mbstate_t *restrict ps"
	54	.Fc
	55	.In wchar.h
	56	.In xlocale.h
	57	.Ft size_t
	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"
	73	.Fc
	74	.Sh DESCRIPTION
	75	The
	76	.Fn wcsrtombs
	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
	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
	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 .
	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.
	139	.Sh RETURN VALUES
	140	If successful, the
	141	.Fn wcsrtombs
	142	and
	143	.Fn wcsnrtombs
	144	functions return the number of bytes stored in
	145	the array pointed to by
	146	.Fa dst
	147	(not including any terminating null);
	148	otherwise, they return
	149	.Po Vt size_t Pc Ns \-1 .
	150	.Sh ERRORS
	151	The
	152	.Fn wcsrtombs
	153	and
	154	.Fn wcsnrtombs
	155	functions will fail if:
	156	.Bl -tag -width Er
	157	.It Bq Er EILSEQ
	158	An invalid wide character was encountered.
	159	.It Bq Er EINVAL
	160	The conversion state is invalid.
	161	.El
	162	.Sh SEE ALSO
	163	.Xr mbsrtowcs 3 ,
	164	.Xr wcrtomb 3 ,
	165	.Xr wcstombs 3 ,
	166	.Xr xlocale 3
	167	.Sh STANDARDS
	168	The
	169	.Fn wcsrtombs
	170	function conforms to
	171	.St -isoC-99 .
	172	.Pp
	173	The
	174	.Fn wcsnrtombs
	175	function is an extension to the standard.