mbstowcs Subroutine

Purpose

Converts a multibyte character string to a wide character string.

Library

Standard C Library (libc.a)

Syntax

#include <stdlib.h>

size_t mbstowcs( WcString,  String,  Number)
wchar_t *WcString;
const char *String;
size_t Number;

Description

The mbstowcs subroutine converts the sequence of multibyte characters pointed to by the String parameter to wide characters and places the results in the buffer pointed to by the WcString parameter. The multibyte characters are converted until a null character is reached or until the number of wide characters specified by the Number parameter have been processed.

Parameters

Item Description
WcString Points to the area where the result of the conversion is stored.
String Points to a multibyte character string.
Number Specifies the maximum number of wide characters to be converted.

Return Values

The mbstowcs subroutine returns the number of wide characters converted, not including a null terminator, if any. If an invalid multibyte character is encountered, a value of -1 is returned. The WcString parameter does not include a null terminator if the value Number is returned.

If WcString is a null wide character pointer, the mbstowcs subroutine returns the number of elements required to store the wide character codes in an array.

Error Codes

The mbstowcs subroutine fails if the following occurs:

Item Description
EILSEQ Invalid byte sequence is detected.