WCRTOMB(3) | Library Functions Manual | WCRTOMB(3)

# NAME

`wcrtomb`, `c32rtomb` — convert a wide character to a multibyte character

# SYNOPSIS

`#include <wchar.h>`

size_t
`wcrtomb`(const char * restrict s, wchar_t wc, mbstate_t * restrict mbs);

`#include <uchar.h>`

size_t
`c32rtomb`(char * restrict s, char32_t wc, mbstate_t * restrict mbs);

# DESCRIPTION

`wcrtomb`() and `c32rtomb`() convert the wide character wc to the corresponding multibyte character, and store up to `MB_CUR_MAX` bytes in the array pointed to by s if s is not a `NULL` pointer. The interpretation of wc is implementation-defined. On OpenBSD, wchar_t and char32_t are of the same width and both are always interpreted as Unicode codepoints.

The output encoding that `wcrtomb`() and `c32rtomb`() use in s is determined by the `LC_CTYPE` category of the current locale. OpenBSD only supports UTF-8 and ASCII output, and these functions are only useful for UTF-8.

The following arguments cause special processing:

wc == 0
  A NUL byte is stored to *s and the state object pointed to by mbs is reset to the initial state. On operating systems other than OpenBSD that support state-dependent multibyte encodings, a special byte sequence (“shift sequence”) is written before the NUL byte to return to the initial state if that is required by the output encoding and by the current output encoding state.
mbs == `NULL`
  `mbrtowc`() and `c32rtomb`() each use their own internal state object instead of the mbs argument. Both internal state objects are initialized at startup time of the program, and no other libc function ever changes either of them.
s == `NULL`
  The object pointed to by mbs, or the internal object if mbs is a `NULL` pointer, is reset to the initial state, wc is ignored, and 1 is returned.

# RETURN VALUES

`wcrtomb`() and `c32rtomb`() return the number of bytes (including any shift sequences) which are stored in the array pointed to by s, or 1 if s is `NULL`. If wc is not a valid wide character or if it cannot be represented in the multibyte encoding selected with `LC_CTYPE`, both functions return (size_t)-1 and set errno to indicate the error.

# ERRORS

`wcrtomb`() and `c32rtomb`() cause an error in the following cases:

[`EILSEQ`]
  wc is not a valid wide character or cannot be represented using `LC_CTYPE`.
[`EINVAL`]
  mbs points to an invalid or uninitialized mbstate_t object.

# SEE ALSO

mbrtowc(3), setlocale(3), wctomb(3)

# STANDARDS

`wcrtomb`() conforms to ISO/IEC 9899/AMD1:1995 (“ISO C90, Amendment 1”). The restrict qualifier was added at ISO/IEC 9899:1999 (“ISO C99”).

`c32rtomb`() conforms to ISO/IEC 9899:2011 (“ISO C11”).

# HISTORY

`wcrtomb`() has been available since OpenBSD 3.8 and has provided support for UTF-8 since OpenBSD 4.8.

`c32rtomb`() has been available since OpenBSD 7.4.

September 12, 2023 | Debian