1.\" $OpenBSD: mbrtowc.3,v 1.2 2007/05/31 19:19:29 jmc Exp $ 2.\" $NetBSD: mbrtowc.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: May 31 2007 $ 29.Dt MBRTOWC 3 30.Os 31.\" ---------------------------------------------------------------------- 32.Sh NAME 33.Nm mbrtowc 34.Nd converts a multibyte character to a wide character (restartable) 35.\" ---------------------------------------------------------------------- 36.Sh SYNOPSIS 37.Fd #include <wchar.h> 38.Ft size_t 39.Fn mbrtowc "wchar_t * restrict pwc" "const char * restrict s" "size_t n" \ 40"mbstate_t * restrict ps" 41.\" ---------------------------------------------------------------------- 42.Sh DESCRIPTION 43The 44.Fn mbrtowc 45usually converts the multibyte character pointed to by 46.Fa s 47to a wide character, and stores the wide character 48in the wchar_t object pointed to by 49.Fa pwc 50if 51.Fa pwc 52is non-null and 53.Fa s 54points to a valid character. 55The conversion happens in accordance with the conversion state 56described in the mbstate_t object pointed to by 57.Fa ps . 58This function may examine at most 59.Fa n 60bytes of the array beginning from 61.Fa s . 62.Pp 63If 64.Fa s 65points to a valid character and the character corresponds to a null wide 66character, then the 67.Fn mbrtowc 68places the mbstate_t object pointed to by 69.Fa ps 70to an initial conversion state. 71.Pp 72Unlike 73.Xr mbtowc 3 , 74the 75.Fn mbrtowc 76may accept the byte sequence pointed to by 77.Fa s 78not forming a complete multibyte character 79but which may be part of a valid character. 80In this case, this function will accept all such bytes 81and save them into the conversion state object pointed to by 82.Fa ps . 83They will be used at subsequent calls of this function to restart 84the conversion suspended. 85.Pp 86The behaviour of the 87.Fn mbrtowc 88is affected by the 89.Dv LC_CTYPE 90category of the current locale. 91.Pp 92These are the special cases: 93.Bl -tag -width 012345678901 94.It "s == NULL" 95.Fn mbrtowc 96sets the conversion state object pointed to by 97.Fa ps 98to an initial state and always returns 0. 99Unlike 100.Xr mbtowc 3 , 101the value returned does not indicate whether the current encoding of 102the locale is state-dependent. 103.Pp 104In this case, 105.Fn mbrtowc 106ignores 107.Fa pwc 108and 109.Fa n , 110and is equivalent to the following call: 111.Bd -literal -offset indent 112mbrtowc(NULL, "", 1, ps); 113.Ed 114.It "pwc == NULL" 115The conversion from a multibyte character to a wide character has 116taken place and the conversion state may be affected, but the resultant 117wide character is discarded. 118.It "ps == NULL" 119.Fn mbrtowc 120uses its own internal state object to keep the conversion state, 121instead of 122.Fa ps 123mentioned in this manual page. 124.Pp 125Calling any other functions in 126.Em libc 127never change the internal 128state of 129.Fn mbrtowc , 130which is initialized at startup time of the program. 131.El 132.\" ---------------------------------------------------------------------- 133.Sh RETURN VALUES 134In the usual cases, 135.Fn mbrtowc 136returns: 137.Bl -tag -width 012345678901 138.It 0 139The next bytes pointed to by 140.Fa s 141form a null character. 142.It positive 143If 144.Fa s 145points to a valid character, 146.Fn mbrtowc 147returns the number of bytes in the character. 148.It (size_t)-2 149.Fa s 150points to the byte sequence which possibly contains part of a valid 151multibyte character, but which is incomplete. 152When 153.Fa n 154is at least 155.Dv MB_CUR_MAX 156only occurs if the array pointed to by 157.Fa s 158contains a redundant shift sequence. 159.It (size_t)-1 160.Fa s 161points to an illegal byte sequence which does not form a valid multibyte 162character. 163In this case, 164.Fn mbrtowc 165sets 166.Va errno 167to indicate the error. 168.El 169.\" ---------------------------------------------------------------------- 170.Sh ERRORS 171The 172.Fn mbrtowc 173may causes an error in the following case: 174.Bl -tag -width Er 175.It Bq Er EILSEQ 176.Fa s 177points to an invalid or incomplete multibyte character. 178.It Bq Er EINVAL 179.Fa ps 180points to an invalid or uninitialized mbstate_t object. 181.El 182.\" ---------------------------------------------------------------------- 183.Sh SEE ALSO 184.Xr mbrlen 3 , 185.Xr mbtowc 3 , 186.Xr setlocale 3 187.\" ---------------------------------------------------------------------- 188.Sh STANDARDS 189The 190.Fn mbrtowc 191function conforms to 192.\" .St -isoC-amd1 . 193ISO/IEC 9899/AMD1:1995 194.Pq Dq ISO C90, Amendment 1 . 195The restrict qualifier is added at 196.\" .St -isoC99 . 197ISO/IEC 9899:1999 198.Pq Dq ISO C99 . 199