WCSRTOMBS(3) | Library Functions Manual | WCSRTOMBS(3)

# NAME

`wcsrtombs`, `wcsnrtombs` — converts a wide-character string to a multibyte character string (restartable)

# SYNOPSIS

`#include <wchar.h>`

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

size_t
`wcsnrtombs`(const char * restrict dst, const wchar_t ** restrict src, size_t nwc, size_t len, mbstate_t * restrict ps);

# DESCRIPTION

The `wcsrtombs`() function converts the wide-character string indirectly pointed to by src to the corresponding multibyte character string and stores it to the array pointed to by dst. The conversion stops due to the following reasons:

- The conversion reaches a null wide character. In this case, the null wide character is also converted.
- The conversion has already stored len bytes to the array pointed to by dst.
- The conversion encounters an invalid character.

The `wcsnrtombs`() function is equivalent to `wcsrtombs`() except that it additionally stops the conversion after processing nwc wide characters.

Each character will be converted as if wcrtomb(3) is continuously called, except the internal state of wcrtomb(3) will not be affected.

After conversion, if dst is not a null pointer, the pointer object pointed to by src is a null pointer (if the conversion is stopped due to reaching a null wide character) or the address just past the last wide character processed.

If dst is not a null pointer and the conversion is stopped due to reaching a null wide character, the state object pointed to by ps is set to an initial state after the conversion has taken place.

The behaviour of the `wcsrtombs`() and `wcsnrtombs`() functions is affected by the `LC_CTYPE` category of the current locale.

There are two special cases:

dst == NULL
  The conversion takes place, but the resulting multibyte string is discarded. In this case, the pointer object pointed to by src is not modified and len is ignored.
ps == NULL
  The `wcsrtombs`() and `wcsnrtombs`() functions use their own internal state objects to keep the conversion state, instead of ps as mentioned in this manual page.

  Calling any other functions in libc never change these internal states, which are initialized at startup time of the program.

# RETURN VALUES

The `wcsrtombs`() and `wcsnrtombs`() functions return:

0 or positive
  Number of bytes stored to the array pointed to by dst, except for a null byte. There is no cases that the value returned is greater than len (unless dst is a null pointer). If the return value is equal to len, the string pointed to by dst will not be null-terminated.
(size_t)-1
  src points to the string containing invalid wide character. In this case, errno is set to indicate the error.

# ERRORS

The `wcsrtombs`() and `wcsnrtombs`() functions may return the following errors:

[`EILSEQ`]
  src points to the string containing an invalid wide character.
[`EINVAL`]
  ps points to an invalid or uninitialized mbstate_t object.

# SEE ALSO

setlocale(3), wcrtomb(3), wcstombs(3)

# STANDARDS

The `wcsrtombs`() function conforms to ANSI X3.159-1989 (“ANSI C89”). The restrict qualifier is added at ISO/IEC 9899/AMD1:1995 (“ISO C99”).

The `wcsnrtombs`() function conforms to IEEE Std 1003.1-2008 (“POSIX.1”).

June 5, 2013 | Debian