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

Technical Reference: Base Operating System and Extensions , Volume 2


wcstombs Subroutine

Purpose

Converts a sequence of wide characters into a sequence of multibyte characters.

Library

Standard C Library (libc.a)

Syntax

#include <stdlib.h>


size_t wcstombs ( String WcString Number)
char *String;
const wchar_t *WcString;
size_t Number;

Description

The wcstombs subroutine converts the sequence of wide characters pointed to by the WcString parameter to a sequence of corresponding multibyte characters and places the results in the area pointed to by the String parameter. The conversion is terminated when the null wide character is encountered or when the number of bytes specified by the Number parameter (or the value of the Number parameter minus 1) has been placed in the area pointed to by the String parameter. If the amount of space available in the area pointed to by the String parameter would cause a partial multibyte character to be stored, the subroutine uses a number of bytes equalling the value of the Number parameter minus 1, because only complete multibyte characters are allowed.

Parameters


String Points to the area where the result of the conversion is stored. If the String parameter is a null pointer, the subroutine returns the number of bytes required to hold the conversion.
WcString Points to a wide-character string.
Number Specifies a number of bytes to be converted.

Return Values

The wcstombs subroutine returns the number of bytes modified. If a wide character is encountered that is not valid, a value of -1 is returned.

Error Codes

The wcstombs subroutine is unsuccessful if the following error occurs:

EILSEQ An invalid character sequence is detected, or a wide-character code does not correspond to a valid character.

Implementation Specifics

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

Related Information

The mbstowcs subroutine, mbtowc subroutine, wcslen (wcslen Subroutine) subroutine, wctomb (wctomb Subroutine) 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 ]