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.