[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 1

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(WcStringStringNumber)
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

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:

EILSEQ Invalid byte sequence is detected.

Implementation Specifics

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

Related Information

The mblen subroutine, mbslen subroutine, mbtowc subroutine, wcstombs subroutine, wctomb subroutine.

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


[ Previous | Next | Contents | Glossary | Home | Search ]