1.\" $NetBSD: src/lib/libc/locale/wcsrtombs.3,v 1.8 2004/01/24 16:58:54 wiz Exp $ 2.\" $DragonFly: src/lib/libc/locale/wcsrtombs.3,v 1.1 2005/03/12 00:18:01 joerg 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 February 4, 2002 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 LIBRARY 38.Lb libc 39.\" ---------------------------------------------------------------------- 40.Sh SYNOPSIS 41.In stdlib.h 42.Ft size_t 43.Fn wcsrtombs "const char * restrict s" "const wchar_t ** restrict pwcs" \ 44"size_t n" "mbstate_t * restrict ps" 45.\" ---------------------------------------------------------------------- 46.Sh DESCRIPTION 47The 48.Fn wcsrtombs 49converts the null-terminated wide character string indirectly pointed 50to by 51.Fa pwcs 52to the corresponding multibyte character string, 53and stores it in the array pointed to by 54.Fa s . 55The conversion stops due to the following reasons: 56.Bl -bullet 57.It 58The conversion reaches a null wide character. 59In this case, the null wide character is also converted. 60.It 61The 62.Fn wcsrtombs 63has already stored 64.Fa n 65bytes in the array pointed to by 66.Fa s . 67.It 68The conversion encounters an invalid character. 69.El 70.Pp 71Each character will be converted as if 72.Xr wcrtomb 3 73is continuously called, except the internal state of 74.Xr wcrtomb 3 75will not be affected. 76.Pp 77After conversion, 78if 79.Fa s 80is not a 81.Dv NULL 82pointer, the pointer object pointed to by 83.Fa pwcs 84is a 85.Dv NULL 86pointer (if the conversion is stopped due to reaching a null wide character) 87or the first byte of the character just after the last character converted. 88.Pp 89If 90.Fa s 91is not a 92.Dv NULL 93pointer and the conversion is stopped due to reaching 94a null wide character, 95.Fn wcsrtombs 96places the state object pointed to by 97.Fa ps 98to an initial state after the conversion is taken place. 99.Pp 100The behaviour of 101.Fn wcsrtombs 102is affected by the 103.Dv LC_CTYPE 104category of the current locale. 105.Pp 106These are the special cases: 107.Bl -tag -width 012345678901 108.It "s == NULL" 109.Fn wcsrtombs 110returns the number of bytes to store the whole multibyte character string 111corresponding to the wide character string pointed to by 112.Fa pwcs , 113not including the terminating null byte. 114In this case, 115.Fa n 116is ignored. 117.It "pwcs == NULL || *pwcs == NULL" 118Undefined (may cause the program to crash). 119.It "ps == NULL" 120.Fn wcsrtombs 121uses its own internal state object to keep the conversion state, 122instead of 123.Fa ps 124mentioned in this manual page. 125.Pp 126Calling any other functions in 127.Lb libc 128never changes the internal 129state of 130.Fn wcsrtombs , 131which is initialized at startup time of the program. 132.El 133.\" ---------------------------------------------------------------------- 134.Sh RETURN VALUES 135.Fn wcsrtombs 136returns: 137.Bl -tag -width 012345678901 138.It 0 or positive 139Number of bytes stored in the array pointed to by 140.Fa s , 141except for a null byte. 142There are no cases that the value returned is greater than 143.Fa n 144(unless 145.Fa s 146is a null pointer). 147If the return value is equal to 148.Fa n , 149the string pointed to by 150.Fa s 151will not be null-terminated. 152.It (size_t)-1 153.Fa pwcs 154points to a string containing an invalid wide character. 155The 156.Fn wcsrtombs 157also sets 158.Va errno 159to indicate the error. 160.El 161.\" ---------------------------------------------------------------------- 162.Sh ERRORS 163.Fn wcsrtombs 164may cause an error in the following case: 165.Bl -tag -width Er 166.It Bq Er EILSEQ 167.Fa pwcs 168points to a string containing an invalid wide character. 169.El 170.\" ---------------------------------------------------------------------- 171.Sh SEE ALSO 172.Xr setlocale 3 , 173.Xr wcrtomb 3 , 174.Xr wcstombs 3 175.\" ---------------------------------------------------------------------- 176.Sh STANDARDS 177The 178.Fn wcsrtombs 179function conforms to 180.St -ansiC . 181The restrict qualifier is added at 182.St -isoC-99 . 183