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
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
#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
*/
#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
*/