mbtowc Subroutine

Purpose

Converts a multibyte character to a wide character.

Library

Standard C Library (libc.a)

Syntax

#include <stdlib.h>

int mbtowc ( WideCharacter String Number)
wchar_t *WideCharacter;
const char *String;
size_t Number;

Description

The mbtowc subroutine converts a multibyte character to a wide character and returns the number of bytes of the multibyte character.

The mbtowc subroutine determines the number of bytes that comprise the multibyte character pointed to by the String parameter. It then converts the multibyte character to a corresponding wide character and, if the WideCharacter parameter is not a null pointer, places it in the location pointed to by the WideCharacter parameter. If the WideCharacter parameter is a null pointer, the mbtowc subroutine returns the number of converted bytes but does not change the WideCharacter parameter value. If the WideCharacter parameter returns a null value, the multibyte character is not converted.

Parameters

Item Description
WideCharacter Specifies the location where a wide character is to be placed.
String Specifies a multibyte character.
Number Specifies the maximum number of bytes of a multibyte character.

Return Values

The mbtowc subroutine returns a value of 0 if the String parameter is a null pointer. The subroutine returns a value of -1 if the bytes pointed to by the String parameter do not form a valid multibyte character before the number of bytes specified by the Number parameter (or fewer) have been processed. It then sets the errno global variable to indicate the error. Otherwise, the number of bytes comprising the multibyte character is returned.

Error Codes

The mbtowc subroutine fails if the following occurs:

Item Description
EILSEQ Invalid byte sequence is detected.