# <uchar.h>

<head><title>&lt;uchar.h&gt;</title></head>

# `<uchar.h>`

[added with
TR19769]

* * *

**`NULL· __STDC_UTF_16__· __STDC_UTF_32__`**

**`char16_t· char32_t· mbstate_t· size_t`**

**`c16rtomb· c32rtomb· mbrtoc16· mbrtoc32`**

* * *

Include the added header **`<uchar.h>`**
so that you can work with either 16-bit or 32-bit character
encodings regardless of the size of `wchar_t`.

Note that the use of this header does **not** require
the additions to the C language mandated by TR19769, which
include additional literals of the form `u'x'`,
`u"abc"`, `U'x'`, and `U"abc"`.

        /* MACROS */
    #define NULL <either 0, 0L, or (void *)0> [0 in C++]
    #define __STDC_UTF_16__ unspecified
    #define __STDC_UTF_32__ unspecified
    
        /* TYPES */
    typedef i-type char16_t;
    typedef i-type char32_t;
    typedef o-type mbstate_t;
    typedef ui-type size_t;
    
        /* FUNCTIONS */
    size_t c16rtomb(char *s, char16_t wc,
        mbstate_t *ps);
    size_t c32rtomb(char *s, char16_t wc,
        mbstate_t *ps);
    size_t mbrtoc16(char16_t *pwc, const char *s,
        size_t n, mbstate_t *ps);
    size_t mbrtoc32(char16_t *pwc, const char *s,
        size_t n, mbstate_t *ps);Copy to clipboard

## `c16rtomb`

    size_t c16rtomb(char *s, wchar_t wc, mbstate_t *ps);Copy to clipboard

The function determines the number of bytes needed to represent
the wide character `wc` as a multibyte character, if possible.
(Not all values representable as type
[`wchar_t`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_stddef.html#wchar_t)
are necessarily valid wide-character codes.)
The conversion state for
the multibyte string is assumed to be `*ps`.

If `s` is not a null pointer
and `wc` is a valid wide-character
code, the function determines `x,` the number of bytes needed
to represent `wc` as a multibyte character,
and stores the converted bytes in the array of *char*
beginning at `s`. (`x` cannot be greater than
`MB_CUR_MAX`, defined in `<stdlib.h>`.)
If `wc` is a null wide character,
the function stores any shift sequence needed to restore the initial shift state.
followed by a null byte. The resulting conversion state is the
initial conversion state.

If `s` is a null pointer, the function effectively returns
`c16rtomb(buf, L'\0', ps)`, where `buf` is a
buffer internal to the function. (The function thus returns the number
of bytes needed to restore the initial conversion state
and to terminate the multibyte string
pending from a previous call to `c16rtomb` or
[`wcsrtombs`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_wchar.html#wcsrtombs)
for the same string and conversion state.)

The function returns:

- `(size_t)-1`
if `wc` is an invalid wide-character code,
in which case the function stores the value
`EILSEQ` in `errno` (both macros
defined in `<errno.h>`)
and leaves the resulting conversion state undefined
- `x`, the number of bytes needed
to complete the next muitibyte character, in which case the resulting
conversion state indicates
that `x` bytes have been generated

## `c32rtomb`

    size_t c32rtomb(char *s, wchar_t wc, mbstate_t *ps);Copy to clipboard

The function determines the number of bytes needed to represent
the wide character `wc` as a multibyte character, if possible.
(Not all values representable as type
[`wchar_t`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_stddef.html#wchar_t)
are necessarily valid wide-character codes.)
The conversion state for
the multibyte string is assumed to be `*ps`.

If `s` is not a null pointer
and `wc` is a valid wide-character
code, the function determines `x,` the number of bytes needed
to represent `wc` as a multibyte character,
and stores the converted bytes in the array of *char*
beginning at `s`. (`x` cannot be greater than
`MB_CUR_MAX`, defined in `<stdlib.h>`.)
If `wc` is a null wide character,
the function stores any shift sequence needed to restore the initial shift state
followed by a null byte. The resulting conversion state is the
initial conversion state.

If `s` is a null pointer, the function effectively returns
`c32rtomb(buf, L'\0', ps)`, where `buf` is a
buffer internal to the function. (The function thus returns the number
of bytes needed to restore the initial conversion state
and to terminate the multibyte string
pending from a previous call to `c32rtomb` or
[`wcsrtombs`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_wchar.html#wcsrtombs)
for the same string and conversion state.)

The function returns:

- `(size_t)-1`
if `wc` is an invalid wide-character code,
in which case the function stores the value
`EILSEQ` in `errno` (both macros defined
in `<errno.h>`) and leaves the resulting
conversion state undefined
- `x`, the number of bytes needed
to complete the next muitibyte character, in which case the resulting
conversion state indicates that `x` bytes have been generated

## `char16_t`

    typedef i-type char16_t;Copy to clipboard

The type is the integer type `i-type` of a
16-bit character constant, such as `u'X'`.
You declare an object of type `char16_t` to hold a
16-bit wide character.

## `char32_t`

    typedef i-type char32_t;Copy to clipboard

The type is the integer type `i-type` of a
32-bit character constant, such as `u'X'`.
You declare an object of type `char32_t` to hold a
32-bit wide character.

## `mbrtoc16`

    size_t mbrtoc16(char16_t *pwc, const char *s,
        size_t n, mbstate_t *ps);Copy to clipboard

The function determines the number of bytes in a multibyte string
that completes the next multibyte character, if possible.
The conversion state for
the multibyte string is assumed to be `*ps`.

If `s` is not a null pointer,
the function determines `x,`
the number of bytes in the multibyte string `s` that complete
or contribute to the next multibyte character. (`x` cannot be
greater than `n`.) Otherwise, the function effectively returns
`mbrtoc16(0, "", 1, ps)`,
ignoring `pwc` and `n`.
(The function thus returns zero only if the
conversion state indicates
that no incomplete multibyte character is pending from a previous call to
[`mbrlen`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_wchar.html#mbrlen),
`mbrtoc16`, or
[`mbsrtowcs`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_wchar.html#mbsrtowcs) for the
same string and conversion state.)

If `pwc` is not a null pointer, the function converts a
completed multibyte character to its corresponding wide-character
value and stores that value in `*pwc`.

The function returns:

- `(size_t)-3` if
no additional bytes are needed to complete the next multibyte character,
in which case the resulting conversion state indicates
that no additional bytes have been converted and the next
multibyte character has been produced
- `(size_t)-2` if,
after converting all `n` characters, the resulting
conversion state indicates an incomplete multibyte character
- `(size_t)-1`
if the function detects an encoding error
before completing the next multibyte character, in which case the
function stores the value
`EILSEQ` in `errno` (both macros
defined in `<errno.h>`)
and leaves the resulting conversion state undefined
- zero, if the next completed character is a null character, in
which case the resulting conversion state is the
initial conversion state
- `x,` the number of bytes needed to complete the next multibyte
character, in which case the resulting conversion state indicates
that `x` bytes have been converted and the next
multibyte character has been produced

## `mbrtoc32`

    size_t mbrtoc32(char32_t *pwc, const char *s,
        size_t n, mbstate_t *ps);Copy to clipboard

The function determines the number of bytes in a multibyte string
that completes the next multibyte character, if possible.
The conversion state for
the multibyte string is assumed to be `*ps`.

If `s` is not a null pointer,
the function determines `x,`
the number of bytes in the multibyte string `s` that complete
or contribute to the next multibyte character. (`x` cannot be
greater than `n`.) Otherwise, the function effectively returns
`mbrtoc32(0, "", 1, ps)`,
ignoring `pwc` and `n`.
(The function thus returns zero only if the conversion state indicates
that no incomplete multibyte character is pending from a previous call to
[`mbrlen`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_wchar.html#mbrlen),
`mbrtoc32`, or
[`mbsrtowcs`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_wchar.html#mbsrtowcs) for the
same string and conversion state.)

If `pwc` is not a null pointer, the function converts a
completed multibyte character to its corresponding wide-character
value and stores that value in `*pwc`.

The function returns:

- `(size_t)-3` if
no additional bytes are needed to complete the next multibyte character,
in which case the resulting conversion state indicates
that no additional bytes have been converted and the next
multibyte character has been produced
- `(size_t)-2` if,
after converting all `n` characters, the resulting
conversion state indicates an incomplete multibyte character
- `(size_t)-1`
if the function detects an encoding error
before completing the next multibyte character, in which case the
function stores the value
`EILSEQ` in `errno` (both macros
defined in `<errno.h>`)
and leaves the resulting conversion state undefined
- zero, if the next completed character is a null character, in
which case the resulting conversion state is the
initial conversion state
- `x,` the number of bytes needed to complete the next multibyte
character, in which case the resulting conversion state indicates
that `x` bytes have been converted and the next
multibyte character has been produced

## `mbstate_t`

    typedef o-type mbstate_t;Copy to clipboard

The type is an object type *o-type* that can represent a
conversion state for any of the functions
[`c16rtomb`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_uchar.html#c16rtomb),
[`c32rtomb`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_uchar.html#c32rtomb),
[`mbrtoc16`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_uchar.html#mbrtoc16), or
[`mbrtoc32`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_uchar.html#mbrtoc32).
A definition of the form:

    mbstate_t mbst = {0};Copy to clipboard

ensures that `mbst` represents the
initial conversion state.
Note, however, that other values stored in an object of type
`mbstate_t` can also represent this state.
To test safely for this state, use the function
`mbsinit`, decoared in `<wchar.h>`.

## `NULL`

    #define NULL <either 0, 0L, or (void *)0> [0 in C++]Copy to clipboard

The macro yields a null pointer constant that is usable as an
address constant expression.

## `size_t`

    typedef ui-type size_t;Copy to clipboard

The type is the unsigned integer type `ui-type`
of an object that you declare to store the result of the
*sizeof* operator.

## `__STDC_UTF_16__`

    #define __STDC_UTF_16__ unspecifiedCopy to clipboard

The header defines the macro only if the functions
[`c16rtomb`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_uchar.html#c16rtomb) and
[`mbrtoc16`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_uchar.html#mbrtoc16)
treat elements of type
[`char16_t`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_uchar.html#char16_t)
as characters with the UTF-16 encoding.

## `__STDC_UTF_32__`

    #define __STDC_UTF_32__ unspecifiedCopy to clipboard

The header defines the macro only if the functions
[`c32rtomb`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_uchar.html#c32rtomb) and
[`mbrtoc32`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_uchar.html#mbrtoc32)
treat elements of type
[`char32_t`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_uchar.html#char32_t)
as characters with the UTF-32 encoding.

* * *

See also the
**[Table of Contents](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#Table%20of%20Contents)** and the
**[Index](https://docs.qualcomm.com/doc/80-N3040-23/topic/_cpp_index.html)**.

*[Copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_crit_pjp.html) © 1992-2006by P.J. Plauger. All rights reserved.*

<!--V5.01:1566-->

Last Published: Oct 06, 2026

Previous Topic
 
<typeinfo></typeinfo> Next Topic

<utility></utility>