*** UNIX MANUAL PAGE BROWSER ***

mbtowc(3) Library Functions Manual mbtowc(3) NAME mbtowc, mbrtowc - Converts a multibyte character to a wide character LIBRARY Standard C Library (libc.so, libc.a) SYNOPSIS #include <stdlib.h> int mbtowc( wchar_t *pwc, const char *s, size_t n); #include <wchar.h> size_t mbrtowc( wchar_t *pwc, const char *s, size_t n, mbstate_t *ps); STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: mbtowc(): ISO C, XPG4 mbrtowc(): ISO C Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS Points to the location of a variable containing the wide-character value. Points to a byte array containing the multibyte character to be converted. Specifies the maximum number of bytes to evaluate. Points to the mbstate_t structure that contains the conversion state of the multibyte character in s (for mbrtowc() only). DESCRIPTION The mbtowc() function converts a multibyte character to a wide charac- ter and returns the number of bytes of the multibyte character, which is stored as an output variable. In locales with shift-state character encoding, a call to mbtowc() with a null pointer as the s parameter places the function in the initial shift state. A call to mbtowc() with an s parameter that is not a null pointer may change the shift state for subsequent calls to mbtowc(), depending on the character examined. Changing the LC_CTYPE category of the locale causes the shift state of the function to be indeterminate. The implementation behaves as though no other function calls the mbtowc() function. In the case of nonrestartable functions, such as mbtowc(), conversion of shift-state encoding must first be enabled by calling the function with a null pointer parameter and then calling the function again with the multibyte value to be converted. The status of the conversion op- eration after the call is not available to subsequent calls. The mbrtowc() function is a restartable version of mbtowc(), which means that the shift state for the character in s is maintained in the mbstate_t structure and is therefore available to subsequent calls by mbrtowc() and other restartable conversion functions. RESTRICTIONS The mbrtowc() and other restartable conversion routines are functional only when used with locales that support shift-state encoding. Cur- rently, the DIGITAL UNIX product does not provide locales that use shift-state encoding. Therefore, the run-time behavior of mbrtowc() is equivalent to mbtowc(), and neither function returns values listed for state-dependent conditions. RETURN VALUES If *s is not a null pointer, the mbtowc() function returns the follow- ing values: A positive value indicating the number of bytes in the multibyte character, if the next n or fewer bytes in s constitutes a valid multibyte character other than the null character Zero, if s con- tains a null character -1, if s does not contain a valid multibyte character or contains a character having more than the number of bytes expressed by the n parameter. In this case, mbtowc() sets errno to in- dicate the error. If s is not a null pointer, the mbrtowc() function returns the first value that applies in the following list: Zero, if the next n or fewer bytes are converted to a null wide character, which is then stored in pwc A positive value indicating the number of bytes in the converted multibyte character, if the next n or fewer bytes constitute a valid multibyte character. The counterpart wide-character value is then stored in pwc. (size_t)-2, if the next n bytes contribute to an incom- plete (but potentially valid) multibyte character. In this case, no value is stored in pwc. (size_t)-1, if an encoding error occurs, in which case the next n or fewer bytes do not contribute to a complete and valid multibyte character. In this case, no value is stored in pwc, the function sets errno to EILSEQ, and the conversion state is un- defined. If *s is a null pointer, both the mbtowc() and mbrtowc() functions re- turn one of the following values, depending on whether the character encoding in the current locale is shift-state dependent: A nonzero value, if the character encoding is shift-state dependent Zero, if the character encoding is not shift-state dependent The return values for these functions is never greater than the value specified by the n parameter or the value of MB_CUR_MAX. ERRORS If the following condition occurs, the mbtowc() and mbrtowc() functions set errno to the corresponding value. The s parameter points to an in- valid multibyte character or (for mbtowc() only) to a multibyte charac- ter with more than n bytes. RELATED INFORMATION Functions: btowc(3), mblen(3), wctomb(3), mbstowcs(3), wcstombs(3), wc- tob(3) Files: locale(4) delim off mbtowc(3)