1.\" $NetBSD: mbtowc.3,v 1.8 2006/10/16 09:10:29 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 MBTOWC 3 29.Os 30.\" ---------------------------------------------------------------------- 31.Sh NAME 32.Nm mbtowc 33.Nd converts a multibyte character to a wide character 34.\" ---------------------------------------------------------------------- 35.Sh LIBRARY 36.Lb libc 37.\" ---------------------------------------------------------------------- 38.Sh SYNOPSIS 39.In stdlib.h 40.Ft int 41.Fn mbtowc "wchar_t * restrict pwc" "const char * restrict s" "size_t n" 42.Sh DESCRIPTION 43.Fn mbtowc 44usually converts the multibyte character pointed to by 45.Fa s 46to a wide character, and stores it in the wchar_t object pointed to by 47.Fa pwc 48if 49.Fa pwc 50is 51.Pf non- Dv NULL 52and 53.Fa s 54points to a valid character. 55This function may inspect at most n bytes of the array beginning from 56.Fa s . 57.Pp 58In state-dependent encodings, 59.Fa s 60may point to the special sequence bytes to change the shift-state. 61Although such sequence bytes correspond to no individual 62wide-character code, 63.Fn mbtowc 64changes its own state by the sequence bytes and treats them 65as if they are a part of the subsequence multibyte character. 66.Pp 67Unlike 68.Xr mbrtowc 3 , 69the first 70.Fa n 71bytes pointed to by 72.Fa s 73need to form an entire multibyte character. 74Otherwise, this function causes an error. 75.Pp 76Calling any other functions in 77.Lb libc 78never changes the internal state of 79.Fn mbtowc , 80except for calling 81.Xr setlocale 3 82with changing the 83.Dv LC_CTYPE 84category of the current locale. 85Such 86.Xr setlocale 3 87call causes the internal state of this function to be indeterminate. 88.Pp 89The behaviour of 90.Fn mbtowc 91is affected by the 92.Dv LC_CTYPE 93category of the current locale. 94.Pp 95There are special cases: 96.Bl -tag -width 012345678901 97.It s == NULL 98.Fn mbtowc 99initializes its own internal state to an initial state, and 100determines whether the current encoding is state-dependent. 101This function returns 0 if the encoding is state-independent, 102otherwise non-zero. 103In this case, 104.Fa pwc 105is completely ignored. 106.It pwc == NULL 107.Fn mbtowc 108executes the conversion as if 109.Fa pwc 110is non-NULL, but a result of the conversion is discarded. 111.It n == 0 112In this case, 113the first 114.Fa n 115bytes of the array pointed to by 116.Fa s 117never form a complete character. 118Thus, the 119.Fn mbtowc 120always fails. 121.El 122.\" ---------------------------------------------------------------------- 123.Sh RETURN VALUES 124Normally, the 125.Fn mbtowc 126returns: 127.Bl -tag -width 012345678901 128.It 0 129.Fa s 130points to a nul byte 131.Pq Sq \e0 . 132.It positive 133Number of bytes for the valid multibyte character pointed to by 134.Fa s . 135There are no cases that the value returned is greater than 136the value of the 137.Dv MB_CUR_MAX 138macro. 139.It -1 140.Fa s 141points to an invalid or an incomplete multibyte character. 142The 143.Fn mbtowc 144also sets 145.Va errno 146to indicate the error. 147.El 148.Pp 149When 150.Fa s 151is equal to 152.Dv NULL , 153.Fn mbtowc 154returns: 155.Bl -tag -width 0123456789 156.It 0 157The current encoding is state-independent. 158.It non-zero 159The current encoding is state-dependent. 160.El 161.\" ---------------------------------------------------------------------- 162.Sh ERRORS 163.Fn mbtowc 164may cause an error in the following case: 165.Bl -tag -width Er 166.It Bq Er EILSEQ 167.Fa s 168points to an invalid or incomplete multibyte character. 169.El 170.\" ---------------------------------------------------------------------- 171.Sh SEE ALSO 172.Xr mblen 3 , 173.Xr mbrtowc 3 , 174.Xr setlocale 3 175.\" ---------------------------------------------------------------------- 176.Sh STANDARDS 177The 178.Fn mbtowc 179function conforms to 180.St -ansiC . 181The restrict qualifier is added at 182.St -isoC-99 . 183