wcstombs Subroutine
Purpose
Converts a sequence of wide characters into a sequence of multibyte characters.
Library
Standard C Library (libc.a)
Syntax
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. |