1.\" $NetBSD: wcsrtombs.3,v 1.8 2004/01/24 16:58:54 wiz Exp $ 2.\" 3.\" Copyright (c)2002 Citrus Project, 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd February 4, 2002 28.Dt WCSRTOMBS 3 29.Os 30.\" ---------------------------------------------------------------------- 31.Sh NAME 32.Nm wcsrtombs 33.Nd converts a wide character string to a multibyte character string \ 34(restartable) 35.\" ---------------------------------------------------------------------- 36.Sh LIBRARY 37.Lb libc 38.\" ---------------------------------------------------------------------- 39.Sh SYNOPSIS 40.In stdlib.h 41.Ft size_t 42.Fn wcsrtombs "const char * restrict s" "const wchar_t ** restrict pwcs" \ 43"size_t n" "mbstate_t * restrict ps" 44.\" ---------------------------------------------------------------------- 45.Sh DESCRIPTION 46The 47.Fn wcsrtombs 48converts the null-terminated wide character string indirectly pointed 49to by 50.Fa pwcs 51to the corresponding multibyte character string, 52and stores it in the array pointed to by 53.Fa s . 54The conversion stops due to the following reasons: 55.Bl -bullet 56.It 57The conversion reaches a null wide character. 58In this case, the null wide character is also converted. 59.It 60The 61.Fn wcsrtombs 62has already stored 63.Fa n 64bytes in the array pointed to by 65.Fa s . 66.It 67The conversion encounters an invalid character. 68.El 69.Pp 70Each character will be converted as if 71.Xr wcrtomb 3 72is continuously called, except the internal state of 73.Xr wcrtomb 3 74will not be affected. 75.Pp 76After conversion, 77if 78.Fa s 79is not a 80.Dv NULL 81pointer, the pointer object pointed to by 82.Fa pwcs 83is a 84.Dv NULL 85pointer (if the conversion is stopped due to reaching a null wide character) 86or the first byte of the character just after the last character converted. 87.Pp 88If 89.Fa s 90is not a 91.Dv NULL 92pointer and the conversion is stopped due to reaching 93a null wide character, 94.Fn wcsrtombs 95places the state object pointed to by 96.Fa ps 97to an initial state after the conversion is taken place. 98.Pp 99The behaviour of 100.Fn wcsrtombs 101is affected by the 102.Dv LC_CTYPE 103category of the current locale. 104.Pp 105These are the special cases: 106.Bl -tag -width 012345678901 107.It "s == NULL" 108.Fn wcsrtombs 109returns the number of bytes to store the whole multibyte character string 110corresponding to the wide character string pointed to by 111.Fa pwcs , 112not including the terminating null byte. 113In this case, 114.Fa n 115is ignored. 116.It "pwcs == NULL || *pwcs == NULL" 117Undefined (may cause the program to crash). 118.It "ps == NULL" 119.Fn wcsrtombs 120uses its own internal state object to keep the conversion state, 121instead of 122.Fa ps 123mentioned in this manual page. 124.Pp 125Calling any other functions in 126.Lb libc 127never changes the internal 128state of 129.Fn wcsrtombs , 130which is initialized at startup time of the program. 131.El 132.\" ---------------------------------------------------------------------- 133.Sh RETURN VALUES 134.Fn wcsrtombs 135returns: 136.Bl -tag -width 012345678901 137.It 0 or positive 138Number of bytes stored in the array pointed to by 139.Fa s , 140except for a null byte. 141There are no cases that the value returned is greater than 142.Fa n 143(unless 144.Fa s 145is a null pointer). 146If the return value is equal to 147.Fa n , 148the string pointed to by 149.Fa s 150will not be null-terminated. 151.It (size_t)-1 152.Fa pwcs 153points to a string containing an invalid wide character. 154The 155.Fn wcsrtombs 156also sets 157.Va errno 158to indicate the error. 159.El 160.\" ---------------------------------------------------------------------- 161.Sh ERRORS 162.Fn wcsrtombs 163may cause an error in the following case: 164.Bl -tag -width Er 165.It Bq Er EILSEQ 166.Fa pwcs 167points to a string containing an invalid wide character. 168.El 169.\" ---------------------------------------------------------------------- 170.Sh SEE ALSO 171.Xr setlocale 3 , 172.Xr wcrtomb 3 , 173.Xr wcstombs 3 174.\" ---------------------------------------------------------------------- 175.Sh STANDARDS 176The 177.Fn wcsrtombs 178function conforms to 179.St -ansiC . 180The restrict qualifier is added at 181.St -isoC-99 . 182