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