ILE C/C++ Run-Time Library Functions


wcstombs() -- Convert Wide-Character String to Multibyte String

Format

#include <stdlib.h>
size_t wcstombs(char *dest, const wchar_t *string, size_t count);

Language Level: ANSI

Threadsafe: Yes.

Description

The wcstombs() function converts the wide-character string pointed to by string into the multibyte array pointed to by dest. The converted string begins in the initial shift state. The conversion stops after count bytes in dest are filled up or a wchar_t null character is encountered.

Only complete multibyte characters are stored in dest. If the lack of space in dest would cause a partial multibyte character to be stored, wcstombs() stores fewer than n bytes and discards the invalid character.

When the program is compiled with LOCALETYPE(*LOCALE) and SYSIFCOPT(*IFSIO), the behavior of wcstombs() is affected by the LC_CTYPE category of the current locale. Remember that the CCSID of the locale should match the CCSID of your job. If the CCSID of the locale is a single-byte CCSID, the wide characters are converted to single-byte characters. Any wide character whose value is greater than 256 would be invalid when converting to single-byte CCSID. When the CCSID is multibyte CCSID, the wide characters are converted to multibyte characters.

When the program is compiled with a UNICODE LOCALETYPE and SYSIFCOPT(*IFSIO), the wide characters are assumed to be Unicode characters, and these Unicode characters are converted to the CCSID of the locale that is associated with LC_TYPE.

Note:
This function is not available when LOCALETYPE(*CLD) is specified on the compilation command.

Return Value

The wcstombs() function returns the length in bytes of the multibyte character string, not including a ending null character. The value (size_t)-1 is returned if an invalid multibyte character is encountered.

The value of errno may be set to EILSEQ (conversion stopped due to input character), or ECONVERT (conversion error).

Examples that use wcstombs()

This program is compiled with LOCALETYPE(*LOCALE) and SYSIFCOPT(*IFSIO):

#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
#include <wchar.h>
 
#define  STRLENGTH   10
#define  LOCNAME     "qsys.lib/JA_JP.locale"
#define  LOCNAME_EN  "qsys.lib/EN_US.locale"
 
int main(void)
{
    char      string[STRLENGTH];
    int length, sl = 0;
    wchar_t   wc2[] = L"ABC";
    wchar_t  wc_string[10];
    mbstate_t ps = 0;
    memset(string, '\0', STRLENGTH);
    wc_string[0] = 0x00C1;
    wc_string[1] = 0x4171;
    wc_string[2] = 0x4172;
    wc_string[3] = 0x00C2;
    wc_string[4] = 0x0000;
 
    /* In this first example we will convert a wide character string */
    /* to a single byte character string.  We first set the locale   */
    /* to a single byte locale.  We choose a locale with             */
    /* CCSID 37.                                                     */
 
    if (setlocale(LC_ALL, LOCNAME_EN) == NULL)
        printf("setlocale failed.\n");
 
    length = wcstombs(string, wc2, 10);
 
    /* In this case wide characters ABC are converted to */
    /* single byte characters ABC, length is 3.   */
 
    printf("string = %s, length = %d\n\n", string, length);
 
    /* Now lets try a multibyte example.  We first must set the */
    /* locale to a multibyte locale.  We choose a locale with     */
    /* CCSID 5026  */
 
    if (setlocale(LC_ALL, LOCNAME) == NULL)
        printf("setlocale failed.\n");
 
    length = wcstombs(string, wc_string, 10);
 
 
    /* The hex look at string would now be:                    */
    /* C10E417141720FC2   length will be 8                     */
    /* You would need a device capable of displaying multibyte */
    /* characters to see this string.                          */
 
    printf("length = %d\n\n", length);
 
}
/*  The output should look like this:
 
string = ABC, length = 3
 
length = 8
                                   */
 

This program is compiled with LOCALETYPE(*LOCALEUCS2) and SYSIFCOPT(*IFSIO):

#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
#include <wchar.h>
 
#define  STRLENGTH   10
#define  LOCNAME     "qsys.lib/JA_JP.locale"
#define  LOCNAME_EN  "qsys.lib/EN_US.locale"
 
int main(void)
{
    char      string[STRLENGTH];
    int length, sl = 0;
    wchar_t   wc2[] = L"ABC";
    wchar_t  wc_string[10];
    mbstate_t ps = 0;
    memset(string, '\0', STRLENGTH);
    wc_string[0] = 0x0041;       /* UNICODE A  */
    wc_string[1] = 0xFF41;
    wc_string[2] = 0xFF42;
    wc_string[3] = 0x0042;       /* UNICODE B  */
    wc_string[4] = 0x0000;
    /* In this first example we will convert a wide character string */
    /* to a single byte character string.  We first set the locale   */
    /* to a single byte locale.  We choose a locale with             */
    /* CCSID 37.                                                     */
 
    if (setlocale(LC_ALL, LOCNAME_EN) == NULL)
        printf("setlocale failed.\n");
 
    length = wcstombs(string, wc2, 10);
 
    /* In this case wide characters ABC are converted to */
    /* single byte characters ABC, length is 3.   */
 
    printf("string = %s, length = %d\n\n", string, length);
 
    /* Now lets try a multibyte example.  We first must set the */
    /* locale to a multibyte locale.  We choose a locale with     */
    /* CCSID 5026  */
 
    if (setlocale(LC_ALL, LOCNAME) == NULL)
        printf("setlocale failed.\n");
 
    length = wcstombs(string, wc_string, 10);
 
 
    /* The hex look at string would now be:                    */
    /* C10E428142820FC2   length will be 8                     */
    /* You would need a device capable of displaying multibyte */
    /* characters to see this string.                          */
 
    printf("length = %d\n\n", length);
 
}
/*  The output should look like this:
 
string = ABC, length = 3
 
length = 8
                                   */ 

Related Information


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]