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

Technical Reference: Base Operating System and Extensions, Volume 1


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


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.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

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

National Language Support Overview for Programming, Subroutines Overview, Understanding Multibyte Code, Wide Character Code Conversion Subroutines in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.


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