1.\" $OpenBSD: wcsrtombs.3,v 1.3 2010/09/10 18:38:19 jmc Exp $ 2.\" $NetBSD: wcsrtombs.3,v 1.6 2003/09/08 17:54:32 wiz 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 $Mdocdate: September 10 2010 $ 29.Dt WCSRTOMBS 3 30.Os 31.\" ---------------------------------------------------------------------- 32.Sh NAME 33.Nm wcsrtombs 34.Nd converts a wide-character string to a multibyte character string \ 35(restartable) 36.\" ---------------------------------------------------------------------- 37.Sh SYNOPSIS 38.Fd #include <stdlib.h> 39.Ft size_t 40.Fn wcsrtombs "const char * restrict s" "const wchar_t ** restrict pwcs" \ 41"size_t n" "mbstate_t * restrict ps" 42.\" ---------------------------------------------------------------------- 43.Sh DESCRIPTION 44The 45.Fn wcsrtombs 46converts the null-terminated wide-character string indirectly pointed to by 47.Fa pwcs 48to the corresponding multibyte character string, 49and store it to the array pointed to by 50.Fa s . 51The conversion stops due to the following reasons: 52.Bl -bullet 53.It 54The conversion reaches a null wide character. 55In this case, the null wide character is also converted. 56.It 57The 58.Fn wcsrtombs 59has already stored 60.Fa n 61bytes to the array pointed to by 62.Fa s . 63.It 64The conversion encounters an invalid character. 65.El 66.Pp 67Each characters will be converted as if 68.Xr wcrtomb 3 69is continuously called, except the internal state of 70.Xr wcrtomb 3 71will not be affected. 72.Pp 73After conversion, 74if 75.Fa s 76is not a 77.Dv NULL 78pointer, 79the pointer object pointed to by 80.Fa pwcs 81is a 82.Dv NULL 83pointer (if the conversion is stopped due to reaching a null wide character) 84or the first byte of the character just after the last character converted. 85.Pp 86If 87.Fa s 88is not a null pointer and the conversion is stopped due to reaching 89a null wide character, the 90.Fn wcsrtombs 91places the state object pointed to by 92.Fa ps 93to an initial state after the conversion is taken place. 94.Pp 95The behaviour of the 96.Fn wcsrtombs 97is affected by the 98.Dv LC_CTYPE 99category of the current locale. 100.Pp 101These are the special cases: 102.Bl -tag -width 012345678901 103.It "s == NULL" 104.Fn wcsrtombs 105returns the number of bytes to store the whole multibyte character string 106corresponding to the wide-character string pointed to by 107.Fa pwcs , 108not including the terminating null byte. 109In this case, 110.Fa n 111is ignored. 112.It "pwcs == NULL || *pwcs == NULL" 113Undefined (may causes the program to crash). 114.It "ps == NULL" 115.Fn wcsrtombs 116uses its own internal state object to keep the conversion state, 117instead of 118.Fa ps 119mentioned in this manual page. 120.Pp 121Calling any other functions in 122.Em libc 123never change the internal 124state of 125.Fn wcsrtombs , 126that is initialized at startup time of the program. 127.El 128.\" ---------------------------------------------------------------------- 129.Sh RETURN VALUES 130.Fn wcsrtombs 131returns: 132.Bl -tag -width 012345678901 133.It 0 or positive 134Number of bytes stored to the array pointed to by 135.Fa s , 136except for a null byte. 137There is no cases that the value returned is greater than 138.Fa n 139(unless 140.Fa s 141is a null pointer). 142If the return value is equal to 143.Fa n , 144the string pointed to by 145.Fa s 146will not be null-terminated. 147.It (size_t)-1 148.Fa pwcs 149points to the string containing invalid wide character. 150The 151.Fn wcsrtombs 152also sets errno to indicate the error. 153.El 154.\" ---------------------------------------------------------------------- 155.Sh ERRORS 156.Fn wcsrtombs 157may cause an error in the following cases: 158.Bl -tag -width Er 159.It Bq Er EILSEQ 160.Fa pwcs 161points to the string containing an 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 . 176ISO/IEC 9899/AMD1:1995 177.Pq Dq ISO C99 . 178