[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1

mbtowc Subroutine


Converts a multibyte character to a wide character.


Standard C Library (libc.a)


#include <stdlib.h>

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


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.


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:

EILSEQ Invalid byte sequence is detected.

Related Information

The mblen Subroutine, mbslen Subroutine, mbstowcs Subroutine, wcstombs subroutine, wctomb subroutine.

Subroutines, Example Programs, and Libraries in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

National Language Support Overview and Multibyte Code and Wide Character Code Conversion Subroutines in AIX 5L Version 5.2 National Language Support Guide and Reference.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]