1.\" Copyright (c) 2002-2004 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.Dd May 21, 2013 26.Dt MBRTOWC 3 27.Os 28.Sh NAME 29.Nm mbrtowc , 30.Nm mbrtoc16 , 31.Nm mbrtoc32 32.Nd "convert a character to a wide-character code (restartable)" 33.Sh LIBRARY 34.Lb libc 35.Sh SYNOPSIS 36.In wchar.h 37.Ft size_t 38.Fo mbrtowc 39.Fa "wchar_t * restrict pc" "const char * restrict s" "size_t n" 40.Fa "mbstate_t * restrict ps" 41.Fc 42.In uchar.h 43.Ft size_t 44.Fo mbrtoc16 45.Fa "char16_t * restrict pc" "const char * restrict s" "size_t n" 46.Fa "mbstate_t * restrict ps" 47.Fc 48.Ft size_t 49.Fo mbrtoc32 50.Fa "char32_t * restrict pc" "const char * restrict s" "size_t n" 51.Fa "mbstate_t * restrict ps" 52.Fc 53.Sh DESCRIPTION 54The 55.Fn mbrtowc , 56.Fn mbrtoc16 57and 58.Fn mbrtoc32 59functions inspect at most 60.Fa n 61bytes pointed to by 62.Fa s 63to determine the number of bytes needed to complete the next multibyte 64character. 65If a character can be completed, and 66.Fa pc 67is not 68.Dv NULL , 69the wide character which is represented by 70.Fa s 71is stored in the 72.Vt wchar_t , 73.Vt char16_t 74or 75.Vt char32_t 76it points to. 77.Pp 78If 79.Fa s 80is 81.Dv NULL , 82these functions behave as if 83.Fa pc 84was 85.Dv NULL , 86.Fa s 87was an empty string 88.Pq Qq 89and 90.Fa n 91was 1. 92.Pp 93The 94.Vt mbstate_t 95argument, 96.Fa ps , 97is used to keep track of the shift state. 98If it is 99.Dv NULL , 100these functions use an internal, static 101.Vt mbstate_t 102object, which is initialized to the initial conversion state 103at program startup. 104.Pp 105As a single 106.Vt char16_t 107is not large enough to represent certain multibyte characters, the 108.Fn mbrtoc16 109function may need to be invoked multiple times to convert a single 110multibyte character sequence. 111.Sh RETURN VALUES 112The 113.Fn mbrtowc , 114.Fn mbrtoc16 115and 116.Fn mbrtoc32 117functions return: 118.Bl -tag -width indent 119.It 0 120The next 121.Fa n 122or fewer bytes 123represent the null wide character 124.Pq Li "L'\e0'" . 125.It >0 126The next 127.Fa n 128or fewer bytes represent a valid character, these functions 129return the number of bytes used to complete the multibyte character. 130.It Po Vt size_t Pc Ns \-1 131An encoding error has occurred. 132The next 133.Fa n 134or fewer bytes do not contribute to a valid multibyte character. 135.It Po Vt size_t Pc Ns \-2 136The next 137.Fa n 138contribute to, but do not complete, a valid multibyte character sequence, 139and all 140.Fa n 141bytes have been processed. 142.El 143.Pp 144The 145.Fn mbrtoc16 146function also returns: 147.Bl -tag -width indent 148.It Po Vt size_t Pc Ns \-3 149The next character resulting from a previous call has been stored. 150No bytes from the input have been consumed. 151.El 152.Sh ERRORS 153The 154.Fn mbrtowc , 155.Fn mbrtoc16 156and 157.Fn mbrtoc32 158functions will fail if: 159.Bl -tag -width Er 160.It Bq Er EILSEQ 161An invalid multibyte sequence was detected. 162.It Bq Er EINVAL 163The conversion state is invalid. 164.El 165.Sh SEE ALSO 166.Xr mbtowc 3 , 167.Xr multibyte 3 , 168.Xr setlocale 3 , 169.Xr wcrtomb 3 170.Sh STANDARDS 171The 172.Fn mbrtowc , 173.Fn mbrtoc16 174and 175.Fn mbrtoc32 176functions conform to 177.St -isoC-2011 . 178