1.\" Copyright (c) 2002-2004 Tim J. Robbins. All rights reserved. 2.\" Copyright (c) 1993 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" This code is derived from software contributed to Berkeley by 6.\" Donn Seeley of BSDI. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" From @(#)multibyte.3 8.1 (Berkeley) 6/4/93 33.\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp 34.\" $FreeBSD: head/lib/libc/locale/mbtowc.3 165903 2007-01-09 00:28:16Z imp $ 35.\" 36.Dd December 26, 2013 37.Dt MBTOWC 3 38.Os 39.Sh NAME 40.Nm mbtowc , 41.Nm mbtowc_l 42.Nd convert a character to a wide-character code 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In stdlib.h 47.Ft int 48.Fo mbtowc 49.Fa "wchar_t * restrict wcharp" "const char * restrict mbchar" 50.Fa "size_t nbytes" 51.Fc 52.In xlocale.h 53.Ft int 54.Fo mbtowc_l 55.Fa "wchar_t * restrict wcharp" "const char * restrict mbchar" 56.Fa "size_t nbytes" "locale_t locale" 57.Fc 58.Sh DESCRIPTION 59The 60.Fn mbtowc 61and 62.Fn mbtowc_l 63functions convert a multibyte character 64.Fa mbchar 65into a wide character according to the current conversion state, 66and stores the result 67in the object pointed to by 68.Fa wcharp . 69Up to 70.Fa nbytes 71bytes are examined. 72.Pp 73A call with a null 74.Fa mbchar 75pointer returns nonzero if the current encoding requires shift states, 76zero otherwise; 77if shift states are required, the shift state is reset to the initial state. 78.Pp 79The 80.Fn mbtowc_l 81function takes an explicit 82.Fa locale 83argument, whereas the 84.Fn mbtowc 85function uses the current global or per-thread locale. 86.Sh RETURN VALUES 87If 88.Fa mbchar 89is 90.Dv NULL , 91the 92.Fn mbtowc 93and 94.Fn mbtowc_l 95functions return nonzero if shift states are supported, 96zero otherwise. 97.Pp 98Otherwise, if 99.Fa mbchar 100is not a null pointer, 101.Fn mbtowc 102and 103.Fn mbtowc_l 104either return 0 if 105.Fa mbchar 106represents the null wide character, or return 107the number of bytes processed in 108.Fa mbchar , 109or return \-1 if no multibyte character 110could be recognized or converted. 111In this case, 112.Fn mbtowc Ns 's 113and 114.Fn mbtowc_l Ns 's 115internal conversion states are undefined. 116.Sh ERRORS 117The 118.Fn mbtowc 119and 120.Fn mbtowc_l 121functions will fail if: 122.Bl -tag -width Er 123.It Bq Er EILSEQ 124An invalid multibyte sequence was detected. 125.It Bq Er EINVAL 126The internal conversion state is invalid. 127.El 128.Sh SEE ALSO 129.Xr btowc 3 , 130.Xr mblen 3 , 131.Xr mbrtowc 3 , 132.Xr mbstowcs 3 , 133.Xr multibyte 3 , 134.Xr wctomb 3 , 135.Xr xlocale 3 136.Sh STANDARDS 137The 138.Fn mbtowc 139function conforms to 140.St -isoC-99 . 141