1.\" $NetBSD: src/lib/libc/locale/wcstombs.3,v 1.7 2004/01/24 16:58:54 wiz Exp $ 2.\" $DragonFly: src/lib/libc/locale/wcstombs.3,v 1.1 2005/03/12 00:18:01 joerg Exp $ 3.\" 4.\" Copyright (c)2002 Citrus Project, 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd February 4, 2002 29.Dt WCSTOMBS 3 30.Os 31.\" ---------------------------------------------------------------------- 32.Sh NAME 33.Nm wcstombs 34.Nd converts a wide character string to a multibyte character string 35.\" ---------------------------------------------------------------------- 36.Sh LIBRARY 37.Lb libc 38.\" ---------------------------------------------------------------------- 39.Sh SYNOPSIS 40.In stdlib.h 41.Ft size_t 42.Fn wcstombs "const char * restrict s" "wchar_t * restrict pwcs" "size_t n" 43.\" ---------------------------------------------------------------------- 44.Sh DESCRIPTION 45.Fn wcstombs 46converts the null-terminated wide character string pointed to by 47.Fa pwcs 48to the corresponding multibyte character string, 49and stores it in the array pointed to by 50.Fa s . 51This function may modify the first at most 52.Fa n 53bytes of the array pointed to by 54.Fa s . 55Each character will be converted as if 56.Xr wctomb 3 57is continuously called, except the internal state of 58.Xr wctomb 3 59will not be affected. 60.Pp 61For state-dependent encoding, the 62.Fn wcstombs 63implies the result multibyte character string pointed to by 64.Fa s 65always to begin with an initial state. 66.Pp 67The behaviour of 68.Fn wcstombs 69is affected by the 70.Dv LC_CTYPE 71category of the current locale. 72.Pp 73These are the special cases: 74.Bl -tag -width 012345678901 75.It s == NULL 76The 77.Fn wcstombs 78returns the number of bytes to store the whole multibyte character string 79corresponding to the wide character string pointed to by 80.Fa pwcs . 81In this case, 82.Fa n 83is ignored. 84.It pwcs == NULL 85Undefined (may cause the program to crash). 86.El 87.\" ---------------------------------------------------------------------- 88.Sh RETURN VALUES 89.Fn wcstombs 90returns: 91.Bl -tag -width 012345678901 92.It 0 or positive 93Number of bytes stored in the array pointed to by 94.Fa s . 95There are no cases that the value returned is greater than 96.Fa n 97(unless 98.Fa s 99is a null pointer). 100If the return value is equal to 101.Fa n , 102the string pointed to by 103.Fa s 104will not be null-terminated. 105.It (size_t)-1 106.Fa pwcs 107points to a string containing an invalid wide character. 108.Fn wcstombs 109also sets 110.Va errno 111to indicate the error. 112.El 113.\" ---------------------------------------------------------------------- 114.Sh ERRORS 115.Fn wcstombs 116may cause an error in the following case: 117.Bl -tag -width Er 118.It Bq Er EILSEQ 119.Fa pwcs 120points to a string containing an invalid wide character. 121.El 122.\" ---------------------------------------------------------------------- 123.Sh SEE ALSO 124.Xr setlocale 3 , 125.Xr wctomb 3 126.\" ---------------------------------------------------------------------- 127.Sh STANDARDS 128The 129.Fn wcstombs 130function conforms to 131.St -ansiC . 132The restrict qualifier is added at 133.St -isoC-99 . 134