1.\" $OpenBSD: mbstowcs.3,v 1.8 2015/10/24 23:07:41 mmcc Exp $ 2.\" $NetBSD: mbstowcs.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: October 24 2015 $ 29.Dt MBSTOWCS 3 30.Os 31.\" ---------------------------------------------------------------------- 32.Sh NAME 33.Nm mbstowcs 34.Nd converts a multibyte character string to a wide-character string 35.\" ---------------------------------------------------------------------- 36.Sh SYNOPSIS 37.In stdlib.h 38.Ft size_t 39.Fn mbstowcs "wchar_t * restrict pwcs" "const char * restrict s" "size_t n" 40.\" ---------------------------------------------------------------------- 41.Sh DESCRIPTION 42.Fn mbstowcs 43converts a null-terminated multibyte character string pointed to by 44.Fa s 45to the corresponding wide-character string and stores up to 46.Fa n 47wide characters in the array pointed to by 48.Fa pwcs . 49Each character will be converted as if 50.Xr mbtowc 3 51is continuously called, except the internal state of 52.Xr mbtowc 3 53will not be affected. 54.Pp 55For state-dependent encoding, 56.Fn mbstowcs 57implies the multibyte character string pointed to by 58.Fa s 59always begin with an initial state. 60.Pp 61These are the special cases: 62.Bl -tag -width 012345678901 63.It pwcs == NULL 64.Fn mbstowcs 65returns the number of elements to store the whole wide-character string 66corresponding to the multibyte character string pointed to by 67.Fa s . 68In this case, 69.Fa n 70is ignored. 71.It s == NULL 72Undefined (may cause the program to crash). 73.El 74.\" ---------------------------------------------------------------------- 75.Sh RETURN VALUES 76.Fn mbstowcs 77returns: 78.Bl -tag -width 012345678901 79.It 0 or positive 80The value returned is the number of elements stored in the array pointed to by 81.Fa pwcs , 82except for a terminating null wide character (if any). 83If 84.Fa pwcs 85is not null and the value returned is equal to 86.Fa n , 87the wide-character string pointed to by 88.Fa pwcs 89is not null terminated. 90If 91.Fa pwcs 92is a null pointer, the value returned is the number of elements to contain 93the whole string converted, except for a terminating null wide character. 94.It (size_t)-1 95The array indirectly pointed to by 96.Fa s 97contains a byte sequence forming invalid character. 98In this case, 99.Fn mbstowcs 100sets 101.Va errno 102to indicate the error. 103.El 104.\" ---------------------------------------------------------------------- 105.Sh ERRORS 106.Fn mbstowcs 107may cause an error in the following cases: 108.Bl -tag -width Er 109.It Bq Er EILSEQ 110.Fa s 111points to the string containing invalid or incomplete multibyte character. 112.El 113.\" ---------------------------------------------------------------------- 114.Sh SEE ALSO 115.Xr mbtowc 3 , 116.Xr setlocale 3 117.\" ---------------------------------------------------------------------- 118.Sh STANDARDS 119The 120.Fn mbstowcs 121function conforms to 122.St -ansiC . 123The restrict qualifier is added at 124.\" .St -isoC99 . 125ISO/IEC 9899/199 126.Pq Dq ISO C99 . 127