Content-type: text/html Man page of mbtowc

mbtowc

Section: C Library Functions (3)
Index Return to Main Contents
 

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 standards as follows:

mbtowc(): ISO C, XPG4

mbrtowc(): ISO C

Refer to the standards(5) reference page for more information about industry 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 character 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 operation 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. Currently, the Tru64 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 following 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 contains 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 indicate 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 incomplete (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 undefined.

If *s is a null pointer, both the mbtowc() and mbrtowc() functions return 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 invalid multibyte character or (for mbtowc() only) to a multibyte character with more than n bytes.  

RELATED INFORMATION

Functions: btowc(3), mblen(3), wctomb(3), mbstowcs(3), wcstombs(3), wctob(3)

Files: locale(4) delim off


 

Index

NAME
LIBRARY
SYNOPSIS
STANDARDS
PARAMETERS
DESCRIPTION
RESTRICTIONS
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:41:04 GMT, October 02, 2010