illumos: manual page: wcrtomb.3c

C16RTOMB(3C) Standard C Library Functions C16RTOMB(3C)

NAME

c16rtomb, c32rtomb, wcrtomb, wcrtomb_l - convert wide-characters to
character sequences

SYNOPSIS

#include <uchar.h>

size_t
c16rtomb(char *restrict str, char16_t c16, mbstate_t *restrict ps);

size_t
c32rtomb(char *restrict str, char32_t c32, mbstate_t *restrict ps);

#include <stdio.h>

size_t
wcrtomb(char *restrict str, wchar_t wc, mbstate_t *restrict ps);

#include <stdio.h>
#include <xlocale.h>

size_t
wcrtomb_l(char *restrict str, wchar_t wc, mbstate_t *restrict ps,
locale_t loc);

DESCRIPTION

The c16rtomb(), c32rtomb(), wcrtomb(), and wcrtomb_l() functions convert
wide-character sequences into a series of multi-byte characters. The
functions work in the following formats:

c16rtomb()
A UTF-16 code sequence, where every code point is represented by
one or two char16_t. The UTF-16 encoding will encode certain
Unicode code points as a pair of two 16-bit code sequences,
commonly referred to as a surrogate pair.

c32rtomb()
A UTF-32 code sequence, where every code point is represented by
a single char32_t. It is illegal to pass reserved Unicode code
points.

wcrtomb(), wcrtomb_l()
Wide characters, being a 32-bit value where every code point is
represented by a single wchar_t. While the wchar_t and char32_t
are different types, in this implementation, they are similar
encodings.

The functions all work by looking at the passed in wide-character (c16,
c32, wc) and appending it to the current conversion state, ps. Once a
valid code point, based on the current locale, is found, then it will be
converted into a series of characters that are stored in str. Up to
MB_CUR_MAX bytes will be stored in str. It is the caller's responsibility
to ensure that there is sufficient space in str.

The functions are all influenced by the LC_CTYPE category of the current
locale for determining what is considered a valid character. For example,
in the C locale, only ASCII characters are recognized, while in a UTF-8
based locale like en_us.UTF-8, all valid Unicode code points are recognized
and will be converted into the corresponding multi-byte sequence. The
wcrtomb_l() function uses the locale passed in loc rather than the locale
of the current thread.

The ps argument represents a multi-byte conversion state which can be used
across multiple calls to a given function (but not mixed between
functions). These allow for characters to be consumed from subsequent
buffers, e.g. different values of str. The functions may be called from
multiple threads as long as they use unique values for ps. If ps is NULL,
then a function-specific buffer will be used for the conversion state;
however, this is stored between all threads and its use is not recommended.

The functions all have a special behavior when NULL is passed for str.
They instead will treat it as though a the NULL wide-character was passed
in c16, c32, or wc and an internal buffer (buf) will be used to write out
the results of the conversion. In other words, the functions would be
called as:

c16rtomb(buf, L'\0', ps)
c32rtomb(buf, L'\0', ps)
wcrtomb(buf, L'\0', ps)
wcrtomb_l(buf, L'\0', ps, loc)

Locale Details

Not all locales in the system are Unicode based locales. For example, ISO
8859 family locales have code points with values that do not match their
counterparts in Unicode. When using these functions with non-Unicode based
locales, the code points returned will be those determined by the locale.
They will not be converted from the corresponding Unicode code point. For
example, if using the Euro sign in ISO 8859-15, these functions will not
encode the Unicode value 0x20ac into the ISO 8859-15 value 0xa4.

Regardless of the locale, the characters returned will be encoded as though
the code point were the corresponding value in Unicode. This means that
when using UTF-16, if the corresponding code point were in the range for
surrogate pairs, then the c16rtomb() function will expect to receive that
code point in that fashion.

This behavior of the c16rtomb() and c32rtomb() functions should not be
relied upon, is not portable, and subject to change for non-Unicode
locales.

RETURN VALUES

Upon successful completion, the c16rtomb(), c32rtomb(), wcrtomb(), and
wcrtomb_l() functions return the number of bytes stored in str. Otherwise,
(size_t)-1 is returned to indicate an encoding error and errno is set.

EXAMPLES

Example 1 Converting a UTF-32 character into a multi-byte character
sequence.

#include <locale.h>
#include <stdlib.h>
#include <string.h>
#include <err.h>
#include <stdio.h>
#include <uchar.h>

int
main(void)
{
mbstate_t mbs;
size_t ret;
char buf[MB_CUR_MAX];
char32_t val = 0x5149;
const char *uchar_exp = "\xe5\x85\x89";

(void) memset(&mbs, 0, sizeof (mbs));
(void) setlocale(LC_CTYPE, "en_US.UTF-8");
ret = c32rtomb(buf, val, &mbs);
if (ret != strlen(uchar_exp)) {
errx(EXIT_FAILURE, "failed to convert string, got %zd",
ret);
}

if (strncmp(buf, uchar_exp, ret) != 0) {
errx(EXIT_FAILURE, "converted char32_t does not match "
"expected value");
}

return (0);
}

ERRORS

The c16rtomb(), c32rtomb(), wcrtomb(), and wcrtomb_l() functions will fail
if:

EINVAL The conversion state in ps is invalid.

EILSEQ An invalid character sequence has been detected.

MT-LEVEL
The c16rtomb(), c32rtomb(), wcrtomb(), and wcrtomb_l() functions are
MT-Safe as long as different mbstate_t structures are passed in ps. If ps
is NULL or different threads use the same value for ps, then the functions
are Unsafe.

INTERFACE STABILITY

Committed