NAME

c8rtomb, c8rtomb_l, c16rtomb, c16rtomb_l, c32rtomb, c32rtomb_l, wcrtomb, wcrtomb_l — convert wide-characters to character sequences

SYNOPSIS

#include <uchar.h>

size_t
c8rtomb(char *restrict str, char8_t c8, mbstate_t *restrict ps);

size_t
c8rtomb_l(char *restrict str, char8_t c8, mbstate_t *restrict ps, locale_t restrict loc);

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

size_t
c16rtomb_l(char *restrict str, char16_t c16, mbstate_t *restrict ps, locale_t restrict loc);

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

size_t
c32rtomb_l(char *restrict str, char32_t c32, mbstate_t *restrict ps, locale_t restrict loc);

#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 c8rtomb(), c8rtomb_l(), c16rtomb(), c16rtomb_l(), c32rtomb(), c32rtomb_l(), wcrtomb(), and wcrtomb_l() functions convert wide-character sequences into a series of multi-byte characters. The functions work in the following formats:

c8rtomb(), c8rtomb_l(): A UTF-8 code sequence, where every code point is represented by one to four char8_t.
c16rtomb(), c16rtomb_l(): 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(), c32rtomb32_l(): 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 may have similar encodings depending on the locale, they should not be assumed to be the same.

The functions all work by looking at the passed in wide-character (c8, 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 c8, 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:

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

The c8rtomb_l(), c16rtomb_l(), and c32rtomb_l() functions operate identically to their counterparts; however, they operate on the passed in locale loc rather than the calling thread's.

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 characters will be converted accordingly as though iconv(3C) were called. If the corresponding iconv module is missing for the locale, then these functions will fail.

RETURN VALUES

Upon successful completion, the c8rtomb(), c8rtomb_l(), c16rtomb(), c16rtomb_l(), c32rtomb(), c32rtomb_l(), 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 c8rtomb(), c8rtomb_l(), c16rtomb(), c16rtomb_l(), c32rtomb(), c32rtomb_l(), 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 c8rtomb(), c8rtomb_l(), c16rtomb(), c16rtomb_l(), c32rtomb(), c32rtomb_l(), 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