6.23.45 wcsrtombs Function

Convert a wide character string to a multibyte character sequence.

Include

<wchar.h>

Prototype

size_t wcsrtombs(char * restrict dst, const wchar_t ** restrict src, size_t len, mbstate_t * restrict ps);

Arguments

dst

a pointer to the object to hold the converted multibyte character sequence

src

the wide character sequence to convert

len

the maximum number of multibyte characters to store

ps

a pointer to a mbstate_t object that holds the current conversion state

Return Value

The function returns the number of bytes in the multibyte character sequence, not including the terminating null character (if any). If src cannot be converted to a mutlibyte character sequence, (size_t)(-1) is returned.

Remarks

The function converts a wide character string indirectly pointed to by src beginning in the conversion state, described by the object pointed to by ps, into a sequence of corresponding multibyte characters, storing the converted characters (including a terminating null character) into the array pointed to by dst, provided dst is not a null pointer. Conversion stops when encountering a wide character that cannot be converted, or when len multibyte characters have been stored. Each conversion takes place as if by a call to the wcrtomb() function. By having the argument to specify the current conversion state, this function is restartable.

An encoding error occurs if src is not a valid multibyte character sequence, when the function stores the value of the macro EILSEQ in errno, and the conversion state is unspecified.

Example

See the notes at the beginning of this chapter or section for information on using printf() or scanf() (and other functions reading and writing the stdin or stdout streams) in the example code.

#include <wchar.h>
#include <locale.h>

int main(void) {
  const wchar_t * ws = L"Volume: 2L±0.5mL";
  char buffer [20];
  size_t length;
  mbstate_t mbs;

  setlocale(LC_CTYPE, "");
  mbrlen (NULL, 0, &mbs);   /* initialize mbs */

  length = wcsrtombs(buffer, &ws, 20, &mbs);
  wprintf(L"multibyte string \"%s\" has length %d\n", buffer, length);
}

Example Output

multibyte string "Volume: 2L±0.5mL" has length 17