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 wcsrtombs ,
	32	.Nm wcsnrtombs
	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
	48	.Sh DESCRIPTION
	49	The
	50	.Fn wcsrtombs
	51	function converts a string of wide characters indirectly pointed to by
	52	.Fa src
	53	to a corresponding multibyte character string stored in the array
	54	pointed to by
	55	.Fa dst .
	56	No more than
	57	.Fa len
	58	bytes are written to
	59	.Fa dst .
	60	.Pp
	61	If
	62	.Fa dst
	63	is
	64	.Dv NULL ,
	65	no characters are stored.
	66	.Pp
	67	If
	68	.Fa dst
	69	is not
	70	.Dv NULL ,
	71	the pointer pointed to by
	72	.Fa src
	73	is updated to point to the character after the one that conversion stopped at.
	74	If conversion stops because a null character is encountered,
	75	.Fa *src
	76	is set to
	77	.Dv NULL .
	78	.Pp
	79	The
	80	.Vt mbstate_t
	81	argument,
	82	.Fa ps ,
	83	is used to keep track of the shift state.
	84	If it is
	85	.Dv NULL ,
	86	.Fn wcsrtombs
	87	uses an internal, static
	88	.Vt mbstate_t
	89	object, which is initialized to the initial conversion state
	90	at program startup.
	91	.Pp
	92	The
	93	.Fn wcsnrtombs
	94	function behaves identically to
	95	.Fn wcsrtombs ,
	96	except that conversion stops after reading at most
	97	.Fa nwc
	98	characters from the buffer pointed to by
	99	.Fa src .
	100	.Sh RETURN VALUES
	101	The
	102	.Fn wcsrtombs
	103	and
	104	.Fn wcsnrtombs
	105	functions return the number of bytes stored in
	106	the 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
	111	The
	112	.Fn wcsrtombs
	113	and
	114	.Fn wcsnrtombs
	115	functions will fail if:
	116	.Bl -tag -width Er
	117	.It Bq Er EILSEQ
	118	An invalid wide character was encountered.
	119	.It Bq Er EINVAL
	120	The 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
	127	The
	128	.Fn wcsrtombs
	129	function conforms to
	130	.St -isoC-99 .
	131	.Pp
	132	The
	133	.Fn wcsnrtombs
	134	function is an extension to the standard.