1.\" $NetBSD: wcsrtombs.3,v 1.4 2002/10/01 17:02:57 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.Fd #include \*[Lt]stdlib.h\*[Gt] 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 by 49.Fa pwcs 50to the corresponding multibyte character string, 51and store it to the array pointed by 52.Fa s . 53The conversion stops due to the following reasons: 54.Bl -bullet 55.It 56The conversion reaches a null wide character. 57In this case, the null wide character is also converted. 58.It 59The 60.Fn wcsrtombs 61has already stored 62.Fa n 63bytes to the array pointed by 64.Fa s . 65.It 66The conversion encounters an invalid character. 67.El 68.Pp 69Each characters will be converted as if 70.Xr wcrtomb 3 71is continuously called, except the internal state of 72.Xr wcrtomb 3 73will not be affected. 74.Pp 75After conversion, 76if 77.Fa s 78is not NULL pointer, 79the pointer object pointed by 80.Fa pwcs 81is NULL pointer (if the conversion is stopped due to reach a null wide character) 82or the first byte of the character just after the last character converted. 83.Pp 84If 85.Fa s 86is not null pointer and the conversion is stopped due to reach 87a null wide character, the 88.Fn wcsrtombs 89places the state object pointed by 90.Fa ps 91to an initial state after the conversion is taken place. 92.Pp 93The behaviour of the 94.Fn wcsrtombs 95is affected by LC_CTYPE category of the current locale. 96.Pp 97There are special cases: 98.Bl -tag -width 012345678901 99.It "s == NULL" 100The 101.Fn wcsrtombs 102returns the number of bytes to store the whole multibyte character string 103corresponding to the wide character string pointed by 104.Fa pwcs , 105not including the terminating null byte. 106In this case, 107.Fa n 108is ignored. 109.It "pwcs == NULL || *pwcs == NULL" 110undefined (may causes the program to crash). 111.It "ps == NULL" 112The 113.Fn wcsrtombs 114uses its own internal state object to keep the conversion state, 115instead of 116.Fa ps 117mentioned in this manual page. 118.Pp 119Calling any other functions in the 120.Lb libc 121never change the internal 122state of the 123.Fn wcsrtombs , 124that is initialized at startup time of the program. 125.El 126.\" ---------------------------------------------------------------------- 127.Sh RETURN VALUES 128The 129.Fn wcsrtombs 130returns: 131.Bl -tag -width 012345678901 132.It 0 or positive 133number of bytes stored to the array pointed by 134.Fa s , 135except for a null byte. 136There is 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 by 144.Fa s 145will not be null-terminated. 146.It (size_t)-1 147.Fa pwcs 148points the string containing invalid wide character. 149The 150.Fn wcsrtombs 151also sets errno to indicate the error. 152.El 153.\" ---------------------------------------------------------------------- 154.Sh ERRORS 155The 156.Fn wcsrtombs 157may causes an error in the following case: 158.Bl -tag -width Er 159.It Bq Er EILSEQ 160.Fa pwcs 161points the string containing invalid wide character. 162.El 163.\" ---------------------------------------------------------------------- 164.Sh SEE ALSO 165.Xr setlocale 3 , 166.Xr wcrtomb 3 , 167.Xr wcstombs 3 168.\" ---------------------------------------------------------------------- 169.Sh STANDARDS 170The 171.Fn wcsrtombs 172function conforms to 173.St -ansiC . 174The restrict qualifier is added at 175.St -isoC99 . 176