1.\" $NetBSD: mbtowc.3,v 1.4 2003/04/16 13:34:41 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 43The 44.Fn mbtowc 45usually converts the multibyte character pointed by 46.Fa s 47to the wide character, and store it to the wchar_t object pointed by 48.Fa pwc 49if 50.Fa pwc 51is non-null and 52.Fa s 53points a valid character. 54This function may inspect at most n bytes of the array beginning from 55.Fa s . 56.Pp 57In state-dependent encodings, 58.Fa s 59may point the special sequence bytes to change the shift-state. 60Although such sequence bytes corresponds to no individual 61wide-character code, 62the 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 by 72.Fa s 73need to form an entire multibyte character. 74Otherwise, this function causes an error. 75.Pp 76Calling any other functions in the 77.Lb libc 78never change the internal 79state of the 80.Fn mbtowc , 81except for calling 82.Xr setlocale 3 83with changing LC_CTYPE category of the current locale. 84Such 85.Xr setlocale 3 86call causes the internal state of this function to be indeterminate. 87.Pp 88The behaviour of the 89.Fn mbtowc 90is affected by LC_CTYPE category of the current locale. 91.Pp 92There are special cases: 93.Bl -tag -width 012345678901 94.It s == NULL 95.Fn mbtowc 96initializes its own internal state to an initial state, and 97determines whether the current encoding is state-dependent. 98This function returns 0 if the encoding is state-independent, 99otherwise non-zero. 100In this case, 101.Fa pwc 102is completely ignored. 103.It pwc == NULL 104.Fn mbtowc 105executes the conversion as if 106.Fa pwc 107is non-null, but a result of the conversion is discarded. 108.It n == 0 109In this case, 110the first 111.Fa n 112bytes of the array pointed by 113.Fa s 114never form a complete character. 115Thus, the 116.Fn mbtowc 117always fails. 118.El 119.\" ---------------------------------------------------------------------- 120.Sh RETURN VALUES 121In the usual cases, the 122.Fn mbtowc 123returns: 124.Bl -tag -width 012345678901 125.It 0 126.Fa s 127points a null byte (\'\\0\'). 128.It positive 129number of bytes for the valid multibyte character pointed by 130.Fa s . 131There is no cases that the value returned is greater than 132the value of MB_CUR_MAX macro. 133.It -1 134.Fa s 135points an invalid or an incomplete multibyte character. 136The 137.Fn mbtowc 138also sets errno to indicate the error. 139.El 140.Pp 141In the case that 142.Fa s 143is equal to NULL, the 144.Fn mbtowc 145returns: 146.Bl -tag -width 0123456789 147.It 0 148The current encoding is state-independent. 149.It non-zero 150The current encoding is state-dependent. 151.El 152.\" ---------------------------------------------------------------------- 153.Sh ERRORS 154The 155.Fn mbtowc 156may causes an error in the following case: 157.Bl -tag -width Er 158.It Bq Er EILSEQ 159.Fa s 160points an invalid or incomplete multibyte character. 161.El 162.\" ---------------------------------------------------------------------- 163.Sh SEE ALSO 164.Xr mblen 3 , 165.Xr mbrtowc 3 , 166.Xr setlocale 3 167.\" ---------------------------------------------------------------------- 168.Sh STANDARDS 169The 170.Fn mbtowc 171function conforms to 172.St -ansiC . 173The restrict qualifier is added at 174.St -isoC99 . 175