wcstombs() — Convert wide-character string to multibyte character string

Standards

Standards / Extensions	C or C++	Dependencies
ISO C Amendment XPG4 XPG4.2 C99 Single UNIX Specification, Version 3	both

Format

#include <stdlib.h>

size_t wcstombs(char * __restrict__dest, 
                const wchar_t * __restrict__string, size_t count);

General description

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 NULL wide character is encountered.

The behavior of this wide-character function is affected by the LC_CTYPE category of the current locale. If you change the category, undefined results can occur.

If unsuccessful, mbstowcs() returns (size_t) -1 and sets errno to one of the following values:

Error Code: Description
EINVAL: The input argument is a NULL rather than a pointer to a wide character.
EILSEQ: wcstombs() encountered a sequence that is not a valid wide character code.

The mbstowcs() interface checks for an invalid input arg. If the third arg, which should be a pointer to a string of wchar_t elements, is NULL, the interface will set errno to EINVAL as well as returning -1. This clearly differentiates from the situation in which the third arg is a pointer to null, in which case should return 1 and the multibyte target string will contain a null byte.

Returned value

Returns the length in bytes of the multibyte character string, not including a terminating NULL wide character. The value (size_t)-1 is returned if an invalid multibyte character is encountered or if *string is a NULL pointer.

If count is the returned value, the array is not NULL-terminated.

If *dest is a NULL pointer, the number of characters required to convert the wide-character string is returned.

If the area pointed to by *dest is too small (as indicated by the value of count) to contain the wide character codes represented as multibyte characters, the number of bytes containing complete multibyte characters is returned.

Note: wcstombs() does not generate redundant shift characters between the DBCS characters. When the wctomb() function is called for each character, redundant shift characters are generated.

Example

CELEBW24

⁄* CELEBW24

   In this example, a wide-character string is converted to a
   char string twice.  The first call converts the entire string, while
   the second call only converts three characters.  The results are
   printed each time.

 *⁄
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define SIZE 20

int main(void)
{
  char dest[SIZE];
  wchar_t * dptr = L"string";
  size_t count = SIZE;
  size_t length;

  length = wcstombs( dest, dptr, count );
  printf( "%d characters were converted.\n", length );
  printf( "The converted string is \"%s\"\n\n", dest );

  ⁄* Reset the destination buffer *⁄
  memset( dest, '\0', sizeof(dest));

  ⁄* Now convert only 3 characters *⁄
  length = wcstombs( dest, dptr, 3 );
  printf( "%d characters were converted.\n", length );
  printf( "The converted string is \"%s\"\n", dest );
}

Output:

6 characters were converted.
The converted string is "string"

3 characters were converted.
The converted string is "str"