.\" $OpenBSD: mbrtowc.3,v 1.3 2010/12/05 14:59:49 stsp Exp $ .\" $NetBSD: mbrtowc.3,v 1.5 2003/09/08 17:54:31 wiz Exp $ .\" .\" Copyright (c)2002 Citrus Project, .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd $Mdocdate: December 5 2010 $ .Dt MBRTOWC 3 .Os .Sh NAME .Nm mbrtowc .Nd converts a multibyte character to a wide character (restartable) .Sh SYNOPSIS .Fd #include <wchar.h> .Ft size_t .Fn mbrtowc "wchar_t * restrict wc" "const char * restrict s" "size_t n" \ "mbstate_t * restrict mbs" .Sh DESCRIPTION The .Fn mbrtowc function examines at most .Fa n bytes of the multibyte character byte string pointed to by .Fa s , converts those bytes to a wide character, and stores the wide character in the wchar_t object pointed to by .Fa wc if .Fa wc is not .Dv NULL and .Fa s points to a valid character. .Pp Conversion happens in accordance with the conversion state described by the mbstate_t object pointed to by .Fa mbs . The mbstate_t object must be initialized to zero before the application's first call to .Fn mbrtowc . If the previous call to .Fn mbrtowc did not return (size_t)-1, the mbstate_t object can safely be reused without reinitialization. .Pp The behaviour of .Fn mbrtowc is affected by the .Dv LC_CTYPE category of the current locale. If the locale is changed without reinitialization of the mbstate_t object pointed to by .Fa mbs , the behaviour of .Fn mbrtowc is undefined. .Pp Unlike .Xr mbtowc 3 , .Fn mbrtowc will accept an incomplete byte sequence pointed to by .Fa s which does not form a complete character but is potentially part of a valid character. In this case, .Fn mbrtowc consumes all such bytes. The conversion state saved in the mbstate_t object pointed to by .Fa mbs will be used to restart the suspended conversion during the next call to .Fn mbrtowc . .Pp In state-dependent encodings, .Fa s may point to a special sequence of bytes called a .Dq shift sequence . Shift sequences switch between character code sets available within an encoding scheme. One encoding scheme using shift sequences is ISO/IEC 2022-JP, which can switch e.g. from ASCII (which uses one byte per character) to JIS X 0208 (which uses two bytes per character). Shift sequence bytes correspond to no individual wide character, so .Fn mbrtowc treats them as if they were part of the subsequent multibyte character. Therefore they do contribute to the number of bytes in the multibyte character. .Pp Special cases in interpretation of arguments are as follows: .Bl -tag -width 012345678901 .It "wc == NULL " The conversion from a multibyte character to a wide character is performed and the conversion state may be affected, but the resulting wide character is discarded. .Pp This can be used to find out how many bytes are contained in the multibyte character pointed to by .Fa s . .It "s == NULL " .Fn mbrtowc ignores .Fa wc and .Fa n , and behaves equivalent to .Bd -literal -offset indent mbrtowc(NULL, "", 1, mbs); .Ed .Pp which attempts to use the mbstate_t object pointed to by .Fa mbs to start or continue conversion using the empty string as input, and discards the conversion result. .Pp If conversion succeeds, this call always returns zero. Unlike .Xr mbtowc 3 , the value returned does not indicate whether the current encoding of the locale is state-dependent, i.e. uses shift sequences. .It "mbs == NULL " .Fn mbrtowc uses its own internal state object to keep the conversion state, instead of an mbstate_t object pointed to by .Fa mbs . This internal conversion state is initialized once at program startup. It is not safe to call .Fn mbrtowc again with a .Dv NULL .Fa mbs argument if .Fn mbrtowc returned (size_t)-1 because at this point the internal conversion state is undefined. .Pp Calling any other functions in .Em libc never changes the internal conversion state object of .Fn mbrtowc . .El .Sh RETURN VALUES .Bl -tag -width 012345678901 .It 0 The bytes pointed to by .Fa s form a terminating NUL character. If .Fa wc is not .Dv NULL , a NUL wide character has been stored in the wchar_t object pointed to by .Fa wc . .It positive .Fa s points to a valid character, and the value returned is the number of bytes completing the character. If .Fa wc is not .Dv NULL , the corresponding wide character has been stored in the wchar_t object pointed to by .Fa wc . .It (size_t)-1 .Fa s points to an illegal byte sequence which does not form a valid multibyte character in the current locale. .Fn mbrtowc sets .Va errno to EILSEQ. The conversion state object pointed to by .Fa mbs is left in an undefined state and must be reinitialized before being used again. .Pp Because applications using .Fn mbrtowc are shielded from the specifics of the multibyte character encoding scheme, it is impossible to repair byte sequences containing encoding errors. Such byte sequences must be treated as invalid and potentially malicious input. Applications must stop processing the byte string pointed to by .Fa s and either discard any wide characters already converted, or cope with truncated input. .It (size_t)-2 .Fa s points to an incomplete byte sequence of length .Fa n which has been consumed and contains part of a valid multibyte character. .Fn mbrtowc sets .Va errno to EILSEQ. The character may be completed by calling .Fn mbrtowc again with .Fa s pointing to one or more subsequent bytes of the multibyte character and .Fa mbs pointing to the conversion state object used during conversion of the incomplete byte sequence. .El .Sh ERRORS The .Fn mbrtowc function may cause an error in the following cases: .Bl -tag -width Er .It Bq Er EILSEQ .Fa s points to an invalid or incomplete multibyte character. .It Bq Er EINVAL .Fa mbs points to an invalid or uninitialized mbstate_t object. .El .Sh SEE ALSO .Xr mbrlen 3 , .Xr mbtowc 3 , .Xr setlocale 3 .Sh STANDARDS The .Fn mbrtowc function conforms to .\" .St -isoC-amd1 . ISO/IEC 9899/AMD1:1995 .Pq Dq ISO C90, Amendment 1 . The restrict qualifier is added at .\" .St -isoC99 . ISO/IEC 9899:1999 .Pq Dq ISO C99 . .Sh CAVEATS .Fn mbrtowc is not suitable for programs that care about internals of the character encoding scheme used by the byte string pointed to by .Fa s . .Pp It is possible that .Fn mbrtowc fails because of locale configuration errors. An .Dq invalid character sequence may simply be encoded in a different encoding than that of the current locale. .Pp The special cases for .Fa s == NULL and .Fa mbs == NULL do not make any sense. Instead of passing .Dv NULL for .Fa mbs , .Xr mbtowc 3 can be used. .Pp Earlier versions of this man page implied that calling .Fn mbrtowc with a .Dv NULL .Fa s argument would always set .Fa mbs to the initial conversion state. But this is true only if the previous call to .Fn mbrtowc using .Fa mbs did not return (size_t)-1 or (size_t)-2. It is recommended to zero the mbstate_t object instead.