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