Format
#include <stdlib.h>
size_t wcstombs(char *dest, const wchar_t *string, size_t count);
Language Level: ANSI
Threadsafe: Yes.
Locale Sensitive: The behavior of this function might be affected by the LC_CTYPE category of the current locale. The behavior might also be affected by the LC_UNI_CTYPE category of the current locale if LOCALETYPE(*LOCALEUCS2) or LOCALETYPE(*LOCALEUTF) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.
Wide Character Function: See Wide Characters for more information.
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.
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