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

... / ...

Commit	Line	Data
	1	.\" Copyright (c) 2002 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.3 2002/11/29 17:35:09 ru Exp $
	26	.\"
	27	.Dd August 16, 2002
	28	.Dt WCSRTOMBS 3
	29	.Os
	30	.Sh NAME
	31	.Nm wcsrtombs
	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
	42	.Sh DESCRIPTION
	43	The
	44	.Fn wcsrtombs
	45	function converts a string of wide characters indirectly pointed to by
	46	.Fa src
	47	to a corresponding multibyte character string stored in the array
	48	pointed to by
	49	.Fa dst .
	50	No more than
	51	.Fa len
	52	bytes are written to
	53	.Fa dst .
	54	.Pp
	55	If
	56	.Fa dst
	57	is
	58	.Dv NULL ,
	59	no characters are stored.
	60	.Pp
	61	If
	62	.Fa dst
	63	is not
	64	.Dv NULL ,
	65	the pointer pointed to by
	66	.Fa src
	67	is updated to point to the character after the one that conversion stopped at.
	68	If conversion stops because a null character is encountered,
	69	.Fa *src
	70	is set to
	71	.Dv NULL .
	72	.Pp
	73	The
	74	.Vt mbstate_t
	75	argument,
	76	.Fa ps ,
	77	is used to keep track of the shift state.
	78	If it is
	79	.Dv NULL ,
	80	.Fn wcsrtombs
	81	uses an internal, static
	82	.Vt mbstate_t
	83	object.
	84	.Sh RETURN VALUES
	85	The
	86	.Fn wcsrtombs
	87	function returns the number of bytes stored in
	88	the array pointed to by
	89	.Fa dst
	90	(not including any terminating null), if successful, otherwise it returns
	91	.Po Vt size_t Pc Ns \-1 .
	92	.Sh ERRORS
	93	The
	94	.Fn wcsrtombs
	95	function will fail if:
	96	.Bl -tag -width Er
	97	.It Bq Er EILSEQ
	98	An invalid wide character was encountered.
	99	.El
	100	.Sh SEE ALSO
	101	.Xr mbsrtowcs 3 ,
	102	.Xr wcrtomb 3 ,
	103	.Xr wcstombs 3
	104	.Sh STANDARDS
	105	The
	106	.Fn wcsrtombs
	107	function conforms to
	108	.St -isoC-99 .
	109	.Sh BUGS
	110	The current implementation does not support shift states.