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

Technical Reference: Base Operating System and Extensions, 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( 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


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 (mblen Subroutine) subroutine, mbslen (mbslen Subroutine) subroutine, mbtowc (mbtowc Subroutine) subroutine, wcstombs subroutine, wctomb subroutine.

National Language Support Overview for Programming, Subroutines Overview, Understanding Multibyte Code and 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 ]