1.\" Copyright (c) 2002 Tim J. Robbins 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.Dd August 15, 2002 27.Dt MBRTOWC 3 28.Os 29.Sh NAME 30.Nm mbrtowc 31.Nd "convert a character to a wide-character code (restartable)" 32.Sh LIBRARY 33.Lb libc 34.Sh SYNOPSIS 35.In wchar.h 36.Ft size_t 37.Fn mbrtowc "wchar_t *restrict pwc" "const char *restrict s" "size_t n" "mbstate_t *restrict ps" 38.Sh DESCRIPTION 39The 40.Fn mbrtowc 41function inspects at most 42.Fa n 43bytes pointed to by 44.Fa s 45and interprets them as a multibyte character sequence 46according to the current setting of 47.Ev LC_CTYPE . 48If 49.Fa pwc 50is not 51.Dv NULL , 52the multibyte character which 53.Fa s 54represents is stored in the 55.Ft wchar_t 56it points to. 57.Pp 58If 59.Fa s 60is 61.Dv NULL , 62.Fn mbrtowc 63behaves as if 64.Fa pwc 65was 66.Dv NULL , 67.Fa s 68was an empty string ("") 69and 70.Fa n 71was 1. 72.Pp 73The 74.Ft mbstate_t 75argument, 76.Fa ps , 77is used to keep track of the shift state. 78If it is 79.Dv NULL , 80.Fn mbrtowc 81uses an internal, static 82.Ft mbstate_t 83object. 84.Sh RETURN VALUES 85The 86.Fn mbrtowc 87functions returns: 88.Bl -tag -width indent 89.It 0 90The first 91.Fa n 92or fewer bytes of 93.Fa s 94represent the null wide character (L'\e0'). 95.It >0 96The first 97.Fa n 98or fewer bytes of 99.Fa s 100represent a valid character, 101.Fn mbrtowc 102returns the length (in bytes) of the multibyte sequence. 103.It Xo 104.No ( Ns 105.Ft size_t Ns 106.No ) Ns \&-2 107.Xc 108The first 109.Fa n 110bytes of 111.Fa s 112are an incomplete multibyte sequence. 113.It Xo 114.No ( Ns 115.Ft size_t Ns 116.No ) Ns \&-1 117.Xc 118The byte sequence pointed to by 119.Fa s 120is an invalid multibyte sequence. 121.El 122.Sh ERRORS 123The 124.Fn mbrtowc 125function will fail if: 126.Bl -tag -width Er 127.\".It Bq Er EINVAL 128.\"Invalid argument. 129.It Bq Er EILSEQ 130An invalid multibyte sequence was detected. 131.El 132.Sh SEE ALSO 133.Xr mbtowc 3 , 134.Xr setlocale 3 , 135.Xr wcrtomb 3 136.Sh STANDARDS 137The 138.Fn mbrtowc 139function conforms to 140.St -isoC-99 . 141.Sh BUGS 142The current implementation does not support shift states. 143