1.\" $NetBSD: wcsrtombs.3,v 1.18 2024/10/13 14:56:30 rillig 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 October 13, 2024 28.Dt WCSRTOMBS 3 29.Os 30.\" ---------------------------------------------------------------------- 31.Sh NAME 32.Nm wcsrtombs , 33.Nm wcsnrtombs 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. 42.In wchar.h 43. 44.Ft size_t 45.Fo wcsrtombs 46.Fa "char * restrict s" 47.Fa "const wchar_t ** restrict pwcs" 48.Fa "size_t n" 49.Fa "mbstate_t * restrict ps" 50.Fc 51. 52.Ft size_t 53.Fo wcsnrtombs 54.Fa "char * restrict s" 55.Fa "const wchar_t ** restrict pwcs" 56.Fa "size_t nwc" 57.Fa "size_t n" 58.Fa "mbstate_t * restrict ps" 59.Fc 60. 61.\" ---------------------------------------------------------------------- 62.Sh DESCRIPTION 63The 64.Fn wcsrtombs 65function converts the NUL-terminated wide-character string indirectly 66pointed to by 67.Fa pwcs 68to the corresponding multibyte character string, 69and stores it in the array pointed to by 70.Fa s . 71The conversion stops due to the following reasons: 72.Bl -bullet 73.It 74The conversion reaches a NUL wide character. 75In this case, the NUL wide character is also converted. 76.It 77The 78.Fn wcsrtombs 79has already stored 80.Fa n 81bytes in the array pointed to by 82.Fa s . 83.It 84The conversion encounters an invalid character. 85.El 86.Pp 87Each character will be converted as if 88.Xr wcrtomb 3 89is continuously called, except the internal state of 90.Xr wcrtomb 3 91will not be affected. 92.Pp 93After conversion, 94if 95.Fa s 96is not a NULL pointer, the pointer object pointed to by 97.Fa pwcs 98is a NULL pointer 99.Pq if the conversion is stopped due to reaching a NUL wide character 100or points to the first byte of the character just after the last 101character converted. 102.Pp 103If 104.Fa s 105is not a NULL pointer and the conversion is stopped due to reaching 106a NUL wide character, 107.Fn wcsrtombs 108places the state object pointed to by 109.Fa ps 110to an initial state after the conversion is taken place. 111.Pp 112The behavior of 113.Fn wcsrtombs 114is affected by the 115.Dv LC_CTYPE 116category of the current locale. 117.Pp 118These are the special cases: 119.Bl -tag -width Li 120.It Li "s == NULL" 121.Fn wcsrtombs 122returns the number of bytes to store the whole multibyte character string 123corresponding to the wide-character string pointed to by 124.Fa pwcs , 125not including the terminating NUL byte. 126In this case, 127.Fa n 128is ignored. 129.It Li "pwcs == NULL || *pwcs == NULL" 130Undefined (may cause the program to crash). 131.It Li "ps == NULL" 132.Fn wcsrtombs 133uses its own internal state object to keep the conversion state, 134instead of 135.Fa ps 136mentioned in this manual page. 137.Pp 138Calling any other functions in 139.Lb libc 140never changes the internal 141state of 142.Fn wcsrtombs , 143which is initialized at startup time of the program. 144.El 145.Pp 146The 147.Fn wcsnrtombs 148function behaves identically to 149.Fn wcsrtombs , 150except that the conversion stops after reading at most 151.Fa nwc 152characters from the buffer pointed to by 153.Fa pwcs . 154.\" ---------------------------------------------------------------------- 155.Sh RETURN VALUES 156The 157.Fn wcsrtombs 158and 159.Fn wcsnrtombs 160functions return: 161.Bl -tag -width Li 162.It Li 0 , No or positive 163Number of bytes stored in the array pointed to by 164.Fa s , 165except for a NUL byte. 166There are no cases that the value returned is greater than 167.Fa n 168.Po 169unless 170.Fa s 171is a NULL pointer 172.Pc . 173If the return value is equal to 174.Fa n , 175the string pointed to by 176.Fa s 177will not be NUL-terminated. 178.It Li "(size_t)-1" 179.Fa pwcs 180points to a string containing an invalid wide character. 181The 182.Fn wcsrtombs 183also sets 184.Va errno 185to indicate the error. 186.El 187.\" ---------------------------------------------------------------------- 188.Sh ERRORS 189The 190.Fn wcsrtombs 191and 192.Fn wcsnrtombs 193functions may fail with the following errors: 194.Bl -tag -width Er 195.It Bq Er EILSEQ 196.Fa pwcs 197points to a string containing an invalid wide character. 198.It Bq Er EINVAL 199.Fa ps 200points to an invalid or uninitialized 201.Vt mbstate_t 202object. 203.El 204.\" ---------------------------------------------------------------------- 205.Sh SEE ALSO 206.Xr setlocale 3 , 207.Xr wcrtomb 3 , 208.Xr wcstombs 3 209.\" ---------------------------------------------------------------------- 210.Sh STANDARDS 211The 212.Fn wcsrtombs 213function conforms to 214.St -ansiC . 215The 216.Li restrict 217qualifier was added by 218.St -isoC-99 . 219.Pp 220The 221.Fn wcsnrtombs 222function conforms to 223.St -p1003.1-2008 . 224