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