1.\" $NetBSD: mbrtowc.3,v 1.8 2006/10/16 09:10:29 wiz Exp $ 2.\" 3.\" Copyright (c)2002 Citrus Project, 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd February 4, 2002 28.Dt MBRTOWC 3 29.Os 30.\" ---------------------------------------------------------------------- 31.Sh NAME 32.Nm mbrtowc 33.Nd converts a multibyte character to a wide character (restartable) 34.\" ---------------------------------------------------------------------- 35.Sh LIBRARY 36.Lb libc 37.\" ---------------------------------------------------------------------- 38.Sh SYNOPSIS 39.In wchar.h 40.Ft size_t 41.Fn mbrtowc "wchar_t * restrict pwc" "const char * restrict s" "size_t n" \ 42"mbstate_t * restrict ps" 43.\" ---------------------------------------------------------------------- 44.Sh DESCRIPTION 45The 46.Fn mbrtowc 47usually converts the multibyte character pointed to by 48.Fa s 49to a wide character, and stores the wide character 50to the wchar_t object pointed to by 51.Fa pwc 52if 53.Fa pwc 54is 55.Pf non- Dv NULL 56and 57.Fa s 58points to a valid character. 59The conversion happens in accordance with, and changes the conversion 60state described in the mbstate_t object pointed to by 61.Fa ps . 62This function may examine at most 63.Fa n 64bytes of the array beginning from 65.Fa s . 66.Pp 67If 68.Fa s 69points to a valid character and the character corresponds to a nul wide 70character, then the 71.Fn mbrtowc 72places the mbstate_t object pointed to by 73.Fa ps 74to an initial conversion state. 75.Pp 76Unlike 77.Xr mbtowc 3 , 78the 79.Fn mbrtowc 80may accept the byte sequence pointed to by 81.Fa s 82not forming a complete multibyte character 83but which may be part of a valid character. 84In this case, this function will accept all such bytes 85and save them into the conversion state object pointed to by 86.Fa ps . 87They will be used at subsequent calls of this function to restart 88the conversion suspended. 89.Pp 90The behaviour of 91.Fn mbrtowc 92is affected by the 93.Dv LC_CTYPE 94category of the current locale. 95.Pp 96These are the special cases: 97.Bl -tag -width 012345678901 98.It "s == NULL" 99.Fn mbrtowc 100sets the conversion state object pointed to by 101.Fa ps 102to an initial state and always returns 0. 103Unlike 104.Xr mbtowc 3 , 105the value returned does not indicate whether the current encoding of 106the locale is state-dependent. 107.Pp 108In this case, 109.Fn mbrtowc 110ignores 111.Fa pwc 112and 113.Fa n , 114and is equivalent to the following call: 115.Bd -literal -offset indent 116mbrtowc(NULL, "", 1, ps); 117.Ed 118.It "pwc == NULL" 119The conversion from a multibyte character to a wide character has 120taken place and the conversion state may be affected, but the resulting 121wide character is discarded. 122.It "ps == NULL" 123.Fn mbrtowc 124uses its own internal state object to keep the conversion state, 125instead of 126.Fa ps 127mentioned in this manual page. 128.Pp 129Calling any other functions in 130.Lb libc 131never changes the internal state of 132.Fn mbrtowc , 133which is initialized at startup time of the program. 134.El 135.\" ---------------------------------------------------------------------- 136.Sh RETURN VALUES 137In the usual cases, 138.Fn mbrtowc 139returns: 140.Bl -tag -width 012345678901 141.It 0 142The next bytes pointed to by 143.Fa s 144form a nul character. 145.It positive 146If 147.Fa s 148points to a valid character, 149.Fn mbrtowc 150returns the number of bytes in the character. 151.It (size_t)-2 152.Fa s 153points to a byte sequence which possibly contains part of a valid 154multibyte character, but which is incomplete. 155When 156.Fa n 157is at least 158.Dv MB_CUR_MAX , 159this case can only occur if the array pointed to by 160.Fa s 161contains a redundant shift sequence. 162.It (size_t)-1 163.Fa s 164points to an illegal byte sequence which does not form a valid multibyte 165character. 166In this case, 167.Fn mbrtowc 168sets 169.Va errno 170to indicate the error. 171.El 172.\" ---------------------------------------------------------------------- 173.Sh ERRORS 174.Fn mbrtowc 175may cause an error in the following case: 176.Bl -tag -width Er 177.It Bq Er EILSEQ 178.Fa s 179points to an invalid or incomplete multibyte character. 180.It Bq Er EINVAL 181.Fa ps 182points to an invalid or uninitialized mbstate_t object. 183.El 184.\" ---------------------------------------------------------------------- 185.Sh SEE ALSO 186.Xr mbrlen 3 , 187.Xr mbtowc 3 , 188.Xr setlocale 3 189.\" ---------------------------------------------------------------------- 190.Sh STANDARDS 191The 192.Fn mbrtowc 193function conforms to 194.St -isoC-amd1 . 195The restrict qualifier is added at 196.St -isoC-99 . 197