1.\" $OpenBSD: mbsrtowcs.3,v 1.2 2007/05/31 19:19:29 jmc Exp $ 2.\" $NetBSD: mbsrtowcs.3,v 1.6 2003/09/08 17:54:31 wiz 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 $Mdocdate: May 31 2007 $ 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 SYNOPSIS 38.Fd #include <wchar.h> 39.Ft size_t 40.Fn mbsrtowcs "wchar_t * restrict pwcs" "const char ** restrict s" "size_t n" \ 41"mbstate_t * restrict ps" 42.\" ---------------------------------------------------------------------- 43.Sh DESCRIPTION 44The 45.Fn mbsrtowcs 46converts the multibyte character string indirectly pointed to by 47.Fa s 48to the corresponding wide character string, and stores it in the 49array pointed to by 50.Fa pwcs . 51The conversion stops due to the following reasons: 52.Bl -bullet 53.It 54The conversion reaches a null byte. 55In this case, the null byte is also converted. 56.It 57The 58.Fn mbsrtowcs 59has already stored 60.Fa n 61wide characters. 62.It 63The conversion encounters an invalid character. 64.El 65.Pp 66Each character is converted as if 67.Xr mbrtowc 3 68is continuously called. 69.Pp 70After conversion, 71if 72.Fa pwcs 73is not a 74.Dv NULL 75pointer, 76the pointer object pointed to by 77.Fa s 78is a 79.Dv NULL 80pointer (if the conversion is stopped due to reaching a null byte) 81or the first byte of the character just after the last character converted. 82.Pp 83If 84.Fa pwcs 85is not a 86null pointer and the conversion is stopped due to reaching 87a null byte, the 88.Fn mbsrtowcs 89places the state object pointed to by 90.Fa ps 91to an initial state after the conversion has taken place. 92.Pp 93The behaviour of the 94.Fn mbsrtowcs 95is affected by the 96.Dv LC_CTYPE 97category of the current locale. 98.Pp 99These are the special cases: 100.Bl -tag -width 012345678901 101.It "s == NULL || *s == NULL" 102Undefined (may cause the program to crash). 103.It "pwcs == NULL" 104The conversion hass taken place, but the resultant wide character string 105was discarded. 106In this case, the pointer object pointed to by 107.Fa s 108is not modified and 109.Fa n 110is ignored. 111.It "ps == NULL" 112The 113.Fn mbsrtowcs 114uses its own internal state object to keep the conversion state, 115instead of 116.Fa ps 117mentioned in this manual page. 118.Pp 119Calling any other functions in 120.Em libc 121never change the internal 122state of 123.Fn mbsrtowcs , 124which is initialized at startup time of the program. 125.El 126.\" ---------------------------------------------------------------------- 127.Sh RETURN VALUES 128.Fn mbsrtowcs 129returns: 130.Bl -tag -width 012345678901 131.It 0 or positive 132The value returned is the number of elements stored in the array pointed to by 133.Fa pwcs , 134except for a terminating null wide character (if any). 135If 136.Fa pwcs 137is not null and the value returned is equal to 138.Fa n , 139the wide character string pointed to by 140.Fa pwcs 141is not null 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 null 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 cases: 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 . 180ISO/IEC 9899/AMD1:1995 181.Pq Dq ISO C90, Amendment 1 . 182The restrict qualifier is added at 183.\" .St -isoC99 . 184ISO/IEC 9899/1999 185.Dq Pq ISO C99 . 186