OpenBSD manual page server

Manual Page Search Parameters

WCRTOMB(3) Library Functions Manual WCRTOMB(3)

wcrtomb, c32rtombconvert a wide character to a multibyte character

#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);

() and () 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 () and () 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
() and () 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 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.

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.

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

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

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

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”).

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 OpenBSD-current