1.\" $NetBSD: wcsrtombs.3,v 1.13 2010/12/16 17:42:27 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 August 8, 2006 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 wchar.h 41.Ft size_t 42.Fn wcsrtombs "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 nul-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 nul wide character. 58In this case, the nul 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 null pointer, the pointer object pointed to by 80.Fa pwcs 81is a null pointer (if the conversion is stopped due to reaching a 82nul wide character) or the first byte of the character just after 83the last character converted. 84.Pp 85If 86.Fa s 87is not a null pointer and the conversion is stopped due to reaching 88a nul wide character, 89.Fn wcsrtombs 90places the state object pointed to by 91.Fa ps 92to an initial state after the conversion is taken place. 93.Pp 94The behaviour of 95.Fn wcsrtombs 96is affected by the 97.Dv LC_CTYPE 98category of the current locale. 99.Pp 100These are the special cases: 101.Bl -tag -width 012345678901 102.It "s == NULL" 103.Fn wcsrtombs 104returns the number of bytes to store the whole multibyte character string 105corresponding to the wide-character string pointed to by 106.Fa pwcs , 107not including the terminating nul byte. 108In this case, 109.Fa n 110is ignored. 111.It "pwcs == NULL || *pwcs == NULL" 112Undefined (may cause the program to crash). 113.It "ps == NULL" 114.Fn wcsrtombs 115uses its own internal state object to keep the conversion state, 116instead of 117.Fa ps 118mentioned in this manual page. 119.Pp 120Calling any other functions in 121.Lb libc 122never changes the internal 123state of 124.Fn wcsrtombs , 125which is initialized at startup time of the program. 126.El 127.\" ---------------------------------------------------------------------- 128.Sh RETURN VALUES 129.Fn wcsrtombs 130returns: 131.Bl -tag -width 012345678901 132.It 0 or positive 133Number of bytes stored in the array pointed to by 134.Fa s , 135except for a nul byte. 136There are no cases that the value returned is greater than 137.Fa n 138(unless 139.Fa s 140is a null pointer). 141If the return value is equal to 142.Fa n , 143the string pointed to by 144.Fa s 145will not be nul-terminated. 146.It (size_t)-1 147.Fa pwcs 148points to a string containing an invalid wide character. 149The 150.Fn wcsrtombs 151also sets 152.Va errno 153to indicate the error. 154.El 155.\" ---------------------------------------------------------------------- 156.Sh ERRORS 157.Fn wcsrtombs 158may cause an error in the following case: 159.Bl -tag -width Er 160.It Bq Er EILSEQ 161.Fa pwcs 162points to a string containing an invalid wide character. 163.El 164.\" ---------------------------------------------------------------------- 165.Sh SEE ALSO 166.Xr setlocale 3 , 167.Xr wcrtomb 3 , 168.Xr wcstombs 3 169.\" ---------------------------------------------------------------------- 170.Sh STANDARDS 171The 172.Fn wcsrtombs 173function conforms to 174.St -ansiC . 175The restrict qualifier is added at 176.St -isoC-99 . 177