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