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