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

Item Description
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:

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