1.\" $NetBSD: wcsrtombs.3,v 1.3 2002/03/25 19:17:02 yamt 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. In this case, 106.Fa n 107is ignored. 108.It "pwcs == NULL || *pwcs == NULL" 109undefined (may causes the program to crash). 110.It "ps == NULL" 111The 112.Fn wcsrtombs 113uses its own internal state object to keep the conversion state, 114instead of 115.Fa ps 116mentioned in this manual page. 117.Pp 118Calling any other functions in the 119.Lb libc 120never change the internal 121state of the 122.Fn wcsrtombs , 123that is initialized at startup time of the program. 124.El 125.\" ---------------------------------------------------------------------- 126.Sh RETURN VALUES 127The 128.Fn wcsrtombs 129returns: 130.Bl -tag -width 012345678901 131.It 0 or positive 132number of bytes stored to the array pointed by 133.Fa s , 134except for a null byte. 135There is no cases that the value returned is greater than 136.Fa n 137(unless 138.Fa s 139is a null pointer). 140If the return value is equal to 141.Fa n , 142the string pointed by 143.Fa s 144will not be null-terminated. 145.It (size_t)-1 146.Fa pwcs 147points the string containing invalid wide character. 148The 149.Fn wcsrtombs 150also sets errno to indicate the error. 151.El 152.\" ---------------------------------------------------------------------- 153.Sh ERRORS 154The 155.Fn wcsrtombs 156may causes an error in the following case: 157.Bl -tag -width Er 158.It Bq Er EILSEQ 159.Fa pwcs 160points the string containing invalid wide character. 161.El 162.\" ---------------------------------------------------------------------- 163.Sh SEE ALSO 164.Xr setlocale 3 , 165.Xr wcrtomb 3 , 166.Xr wcstombs 3 167.\" ---------------------------------------------------------------------- 168.Sh STANDARDS 169The 170.Fn wcsrtombs 171function conforms to 172.St -ansiC . 173The restrict qualifier is added at 174.St -isoC99 . 175