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