1.\" $OpenBSD: mbtowc.3,v 1.6 2016/02/27 14:07:04 schwarze Exp $ 2.\" $NetBSD: mbtowc.3,v 1.5 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: February 27 2016 $ 29.Dt MBTOWC 3 30.Os 31.\" ---------------------------------------------------------------------- 32.Sh NAME 33.Nm mbtowc 34.Nd converts a multibyte character to a wide character 35.\" ---------------------------------------------------------------------- 36.Sh SYNOPSIS 37.In stdlib.h 38.Ft int 39.Fn mbtowc "wchar_t * restrict pwc" "const char * restrict s" "size_t n" 40.Sh DESCRIPTION 41The 42.Fn mbtowc 43function converts the multibyte character pointed to by 44.Fa s 45to a wide character, and stores it in the wchar_t object pointed to by 46.Fa pwc . 47This function may inspect at most 48.Fa n 49bytes of the array pointed to by 50.Fa s . 51.Pp 52Unlike 53.Xr mbrtowc 3 , 54the first 55.Fa n 56bytes pointed to by 57.Fa s 58need to form an entire multibyte character. 59Otherwise, this function returns an error and the internal state will 60be undefined. 61.Pp 62If a call to 63.Fn mbtowc 64resulted in an undefined internal state, 65.Fn mbtowc 66must be called with 67.Ar s 68set to 69.Dv NULL 70to reset the internal state before it can safely be used again. 71.Pp 72The behaviour of 73.Fn mbtowc 74is affected by the 75.Dv LC_CTYPE 76category of the current locale. 77Calling any other functions in 78.Em libc 79never changes the internal 80state of 81.Fn mbtowc , 82except for calling 83.Xr setlocale 3 84with the 85.Dv LC_CTYPE 86category set to a different locale. 87Such 88.Xr setlocale 3 89calls cause the internal state of this function to be undefined. 90.Pp 91In state-dependent encodings such as ISO/IEC 2022-JP, 92.Fa s 93may point to the special sequence of bytes to change the shift-state. 94Because such sequence bytes do not correspond to any individual wide character, 95.Fn mbtowc 96treats them as if they were part of the subsequent multibyte character. 97.Pp 98The following special cases apply to the arguments: 99.Bl -tag -width 012345678901 100.It s == NULL 101.Fn mbtowc 102initializes its own internal state to the initial state, and 103determines whether the current encoding is state-dependent. 104.Fn mbtowc 105returns 0 if the encoding is state-independent, 106otherwise non-zero. 107.Fa pwc 108is ignored. 109.It pwc == NULL 110.Fn mbtowc 111behaves just as if 112.Fa pwc 113was not 114.Dv NULL , 115including modifications to internal state, 116except that the result of the conversion is discarded. 117This can be used to determine the size of the wide character 118representation of a multibyte string. 119Another use case is a check for illegal or incomplete multibyte sequences. 120.It n == 0 121In this case, 122the first 123.Fa n 124bytes of the array pointed to by 125.Fa s 126never form a complete character and 127.Fn mbtowc 128always fails. 129.El 130.\" ---------------------------------------------------------------------- 131.Sh RETURN VALUES 132Normally, 133.Fn mbtowc 134returns: 135.Bl -tag -width 012345678901 136.It 0 137.Fa s 138points to a null byte 139.Pq Sq \e0 . 140.It positive 141Number of bytes for the valid multibyte character pointed to by 142.Fa s . 143There are no cases where the value returned is greater than 144the value of the 145.Dv MB_CUR_MAX 146macro. 147.It -1 148.Fa s 149points to an invalid or an incomplete multibyte character. 150.Va errno 151is set to indicate the error. 152.El 153.Pp 154When 155.Fa s 156is 157.Dv NULL , 158.Fn mbtowc 159returns: 160.Bl -tag -width 0123456789 161.It 0 162The current encoding is state-independent. 163.It non-zero 164The current encoding is state-dependent. 165.El 166.\" ---------------------------------------------------------------------- 167.Sh ERRORS 168.Fn mbtowc 169will set 170.Va errno 171in the following cases: 172.Bl -tag -width Er 173.It Bq Er EILSEQ 174.Fa s 175points to an invalid or incomplete multibyte character. 176.El 177.\" ---------------------------------------------------------------------- 178.Sh SEE ALSO 179.Xr mblen 3 , 180.Xr mbrtowc 3 , 181.Xr setlocale 3 182.\" ---------------------------------------------------------------------- 183.Sh STANDARDS 184The 185.Fn mbtowc 186function conforms to 187.St -ansiC . 188The restrict qualifier is added at 189.St -isoC-99 . 190Setting 191.Va errno 192is an 193.St -p1003.1-2008 194extension. 195.Sh CAVEATS 196On error, callers of 197.Fn mbtowc 198cannot tell whether the multibyte character was invalid or incomplete. 199To treat incomplete data differently from invalid data the 200.Xr mbrtowc 3 201function can be used instead. 202