# <wchar.h>

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

# `<wchar.h>`

[added with
[Amendment 1](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#Amendment%201)]

* * *

**`NULL· WCHAR_MAX· WCHAR_MIN· WEOF`**

**`btowc· fgetwc· fgetws· fputwc· fputws· fwide· fwprintf· fwscanf· getwc· getwchar· mbrlen· mbrtowc· mbsinit· mbsrtowcs· mbstate_t· putwc· putwchar· size_t· swprintf· swscanf· tm· ungetwc· vfwprintf· vfwscanf· vswprintf· vswscanf· vwprintf· vwscanf· wchar_t· wcrtomb· wcscat· wcschr· wcscmp· wcscoll· wcscpy· wcscspn· wcsftime· wcslen· wcsncat· wcsncmp· wcsncpy· wcspbrk· wcsrchr· wcsrtombs· wcsspn· wcsstr· wcstod· wcstof· wcstok· wcstold· wcstol· wcstoll· wcstoul· wcstoull· wcsxfrm· wctob· wint_t· wmemchr· wmemcmp· wmemcpy· wmemmove· wmemset· wprintf· wscanf`**

* * *

Include the standard header **`<wchar.h>`**
so that you can perform input and output operations on
wide streams or manipulate wide strings.

        /* MACROS */
    #define NULL <either 0, 0L, or (void *)0> [0 in C++]
    #define WCHAR_MAX <#if expression >= 127>
    #define WCHAR_MIN <#if expression <= 0>
    #define WEOF <wint_t constant expression>
    
        /* TYPES */
    typedef o-type mbstate_t;
    typedef ui-type size_t;
    typedef i-type wchar_t; [keyword in C++]
    typedef i_type wint_t;
    struct tm;
    
        /* FUNCTIONS */
    wint_t fgetwc(FILE *stream);
    wchar_t *fgetws(wchar_t *restrict s, int n, FILE *restrict stream);
    wint_t fputwc(wchar_t c, FILE *stream);
    int fputws(const wchar_t *restrict s, FILE *restrict stream);
    int fwide(FILE *stream, int mode);
    wint_t getwc(FILE *stream);
    wint_t getwchar(void);
    wint_t putwc(wchar_t c, FILE *stream);
    wint_t putwchar(wchar_t c);
    wint_t ungetwc(wint_t c, FILE *stream);
    
    int fwscanf(FILE *restrict stream, const wchar_t *restrict format, ...);
    int swscanf(const wchar_t *restrict s,
        const wchar_t *restrict format, ...);
    int wscanf(const wchar_t *restrict format, ...);
    int fwprintf(FILE *restrict stream, const wchar_t *restrict format, ...);
    int swprintf(wchar_t *restrict s, size_t n,
        const wchar_t *restrict format, ...);
    int wprintf(const wchar_t *restrict format, ...);
    int vfwscanf(FILE *restrict stream, const wchar_t *restrict format,
        va_list arg); [added with C99]
    int vswscanf(const wchar_t *restrict s, const wchar_t *restrict format,
        va_list arg); [added with C99]
    int vwscanf(const wchar_t *restrict format,
        va_list arg); [added with C99]
    int vfwprintf(FILE *restrict stream, const wchar_t *restrict format,
        va_list arg);
    int vswprintf(wchar_t *restrict s, size_t n, const wchar_t *restrict format,
        va_list arg);
    int vwprintf(const wchar_t *restrict format,
        va_list arg);
    
    size_t wcsftime(wchar_t *restrict s, size_t maxsize,
        const wchar_t *restrict format, const struct tm *restrict timeptr);
    
    wint_t btowc(int c);
    size_t mbrlen(const char *restrict s, size_t n,
        mbstate_t *restrict ps);
    size_t mbrtowc(wchar_t *restrict pwc, const char *restrict s,
        size_t n, mbstate_t *restrict ps);
    int mbsinit(const mbstate_t *ps);
    size_t mbsrtowcs(wchar_t *restrict dst, const char **restrict src,
        size_t len, mbstate_t *restrict ps);
    size_t wcrtomb(char *restrict s, wchar_t wc,
        mbstate_t *restrict ps);
    size_t wcsrtombs(char *restrict dst, const wchar_t **restrict src,
        size_t len, mbstate_t *restrict ps);
    double wcstod(const wchar_t *restrict nptr,
        wchar_t **restrict endptr);
    float wcstof(const wchar_t *restrict nptr,
        wchar_t **restrict endptr); [added with C99]
    long double wcstold(const wchar_t *restrict nptr,
        wchar_t **restrict endptr); [added with C99]
    long long wcstoll(const wchar_t *restrict nptr, wchar_t **restrict endptr,
        int base); [added with C99]
    unsigned long long wcstoull(const wchar_t *restrict nptr, wchar_t **restrict endptr,
        int base); [added with C99]
    long wcstol(const wchar_t *restrict nptr, wchar_t **restrict endptr,
        int base);
    unsigned long wcstoul(const wchar_t *restrict nptr, wchar_t **restrict endptr,
        int base);
    int wctob(wint_t c);
    
    wchar_t *wcscat(wchar_t *restrict s1, const wchar_t *restrict s2);
    int wcscmp(const wchar_t *s1, const wchar_t *s2);
    int wcscoll(const wchar_t *s1, const wchar_t *s2);
    wchar_t *wcscpy(wchar_t *restrict s1, const wchar_t *restrict s2);
    size_t wcscspn(const wchar_t *s1, const wchar_t *s2);
    size_t wcslen(const wchar_t *s);
    wchar_t *wcsncat(wchar_t *restrict s1, const wchar_t *restrict s2,
        size_t n);
    int wcsncmp(const wchar_t *s1, const wchar_t *s2,
        size_t n);
    wchar_t *wcsncpy(wchar_t *restrict s1, const wchar_t *restrict s2,
        size_t n);
    size_t wcsspn(const wchar_t *s1, const wchar_t *s2);
    wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2);
    wchar_t *wcstok(wchar_t *restrict s1, const wchar_t *restrict s2,
        wchar_t **restrict ptr);
    size_t wcsxfrm(wchar_t *restrict s1, const wchar_t *restrict s2, size_t n);
    int wmemcmp(const wchar_t *s1, const wchar_t *s2,
        size_t n);
    wchar_t *wmemcpy(wchar_t *restrict s1, const wchar_t *restrict s2,
        size_t n);
    wchar_t *wmemmove(wchar_t *s1, const wchar_t *s2,
        size_t n);
    wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);
    
    wchar_t *wcschr(const wchar_t *s, wchar_t c); [not in C++]
    const wchar_t *wcschr(const wchar_t *s, wchar_t c); [C++ only]
    wchar_t *wcschr(wchar_t *s, wchar_t c); [C++ only]
    
    wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2); [not in C++]
    const wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2); [C++ only]
    wchar_t *wcspbrk(wchar_t *s1, const wchar_t *s2); [C++ only]
    
    wchar_t *wcsrchr(const wchar_t *s, wchar_t c); [not in C++]
    const wchar_t *wcsrchr(const wchar_t *s, wchar_t c); [C++ only]
    wchar_t *wcsrchr(wchar_t *s, wchar_t c); [C++ only]
    
    wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2); [not in C++]
    const wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2); [C++ only]
    wchar_t *wcsstr(wchar_t *s1, const wchar_t *s2); [C++ only]
    
    wchar_t *wmemchr(const wchar_t *s, wchar_t c,
        size_t n); [not in C++]
    const wchar_t *wmemchr(const wchar_t *s, wchar_t c,
        size_t n); [C++ only]
    wchar_t *wmemchr(wchar_t *s, wchar_t c,
        size_t n); [C++ only]Copy to clipboard

## `btowc`

    wint_t btowc(int c);Copy to clipboard

The function returns
[`WEOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#WEOF) if `c` equals
[`EOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#EOF).
Otherwise, it converts `(unsigned char)c`
as a one-byte multibyte character beginning in the
[initial conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#initial%20conversion%20state),
as if by calling
[`mbrtowc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#mbrtowc).
If the conversion succeeds, the function returns the wide-character
conversion. Otherwise, it returns
[`WEOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#WEOF).

## `fgetwc`

    wint_t fgetwc(FILE *stream);Copy to clipboard

The function reads the next wide character `c` (if present)
from the input stream `stream`,
advances the file-position indicator (if defined), and returns
`(wint_t)c`.
If the function sets either the end-of-file indicator
or the error indicator, it returns
[`WEOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#WEOF).

## `fgetws`

    wchar_t *fgetws(wchar_t *restrict s, int n, FILE *restrict stream);Copy to clipboard

The function reads wide characters
from the input stream `stream`
and stores them in successive elements of the array
beginning at `s` and continuing until it stores
`n - 1` wide characters, stores an `NL`
wide character, or sets the end-of-file or error indicators. If
`fgetws` stores any wide characters, it concludes by storing
a null wide character in the next element of the array. It returns
`s` if it stores any wide characters and it has not set the error
indicator for the stream; otherwise, it returns a null pointer. If
it sets the error indicator, the array contents are indeterminate.

## `fputwc`

    wint_t fputwc(wchar_t c, FILE *stream);Copy to clipboard

The function writes the wide character `c` to the output
stream `stream`, advances the file-position indicator
(if defined), and returns
`(wint_t)c`.
If the function sets the error indicator for the stream, it returns
[`WEOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#WEOF).

## `fputws`

    int fputws(const wchar_t *restrict s, FILE *restrict stream);Copy to clipboard

The function accesses wide characters from the string `s`
and writes them to the output stream `stream`. The function does
not write the terminating null wide character. It returns a nonnegative
value if it has not set the error indicator; otherwise, it returns
[`WEOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#WEOF).

## `fwide`

    int fwide(FILE *stream, int mode);Copy to clipboard

The function determines the orientation of the stream `stream`.
If `mode` is greater than zero,
it first attempts to make the stream
[wide oriented](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#wide%20oriented).
If `mode` is less than zero,
it first attempts to make the stream
[byte oriented](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#byte%20oriented).
In any event, the function returns:

- a value greater than zero if the stream is left
[wide oriented](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#wide%20oriented)
- zero if the stream is left
[unbound](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#unbound%20stream)
- a value less than zero if the stream is left
[byte oriented](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#byte%20oriented)

In no event will the function alter the orientation of a stream
once it has been oriented.

## `fwprintf`

    int fwprintf(FILE *restrict stream, const wchar_t *restrict format, ...);Copy to clipboard

The function
[generates formatted text](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_prin.html#Print%20Functions),
under the control of the format `format`
and any additional arguments, and writes
each generated wide character to the stream `stream`. It returns
the number of wide characters generated, or it returns a negative
value if the function sets the error indicator for the stream.

## `fwscanf`

    int fwscanf(FILE *restrict stream, const wchar_t *restrict format, ...);Copy to clipboard

The function
[scans formatted text](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_scan.html#Scan%20Functions),
under the control of the format `format`
and any additional arguments. It obtains each
scanned character from the stream `stream`. It returns the number
of input items matched and assigned, or it returns
[`EOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#EOF) if the
function does not store values before it sets the end-of-file or error
indicator for the stream.

## `getwc`

    wint_t getwc(FILE *stream);Copy to clipboard

The function has the same effect as
`fgetwc(stream)` except
that a macro version of `getwc` can evaluate
`stream` more than once.

## `getwchar`

    wint_t getwchar(void);Copy to clipboard

The function has the same effect as
`fgetwc(stdin)`.

## `mbrlen`

    size_t mbrlen(const char *restrict s, size_t n, mbstate_t *restrict ps);Copy to clipboard

The function is equivalent to the call:

    mbrtowc(0, s, n, ps != 0 ? ps : &internal)Copy to clipboard

where `internal` is an object of type
[`mbstate_t`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#mbstate_t)
internal to the `mbrlen` function. At
[program startup](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#program%20startup),
`internal` is initialized to the
[initial conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#initial%20conversion%20state).
No other library function
alters the value stored in `internal`.

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state) 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](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state)
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`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_errno.html#EILSEQ) in
[`errno`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_errno.html#errno) and leaves the resulting
[conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state) undefined
- zero, if the next completed character is a null character, in
which case the resulting
[conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state) is the
[initial conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#initial%20conversion%20state)
- `x,` the number of bytes needed to complete the next multibyte
character, in which case the resulting
[conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state) indicates
that `x` bytes have been converted and the next
multibyte character has been produced

Thus, `mbrlen` effectively returns the number of bytes
that would be consumed in successfully converting a multibyte character
to a wide character (without storing the converted wide character),
or an error code if the conversion cannot succeed.

## `mbrtowc`

    size_t mbrtowc(wchar_t *restrict pwc, const char *restrict s,
        size_t n, mbstate_t *restrict ps);Copy to clipboard

The function determines the number of bytes in a multibyte string
that completes the next multibyte character, if possible.

If `ps` is not a null pointer, the
[conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state) for
the multibyte string is assumed to be `*ps`. Otherwise, it is
assumed to be `&internal`,
where `internal` is an object of type
[`mbstate_t`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#mbstate_t)
internal to the `mbrtowc` function. At
[program startup](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#program%20startup),
`internal` is initialized to the
[initial conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#initial%20conversion%20state).
No other library function alters the value stored
in `internal`.

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
`mbrtowc(0, "", 1, ps)`,
ignoring `pwc` and `n`.
(The function thus returns zero only if the
[conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state) indicates
that no incomplete multibyte character is pending from a previous call to
[`mbrlen`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#mbrlen),
`mbrtowc`, or
[`mbsrtowcs`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#mbsrtowcs) for the
same string and
[conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state).)

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](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state) 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](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state)
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`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_errno.html#EILSEQ) in
[`errno`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_errno.html#errno)
and leaves the resulting
[conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state) undefined
- zero, if the next completed character is a null character, in
which case the resulting
[conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state) is the
[initial conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#initial%20conversion%20state)
- `x,` the number of bytes needed to complete the next multibyte
character, in which case the resulting
[conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state) indicates
that `x` bytes have been converted and the next
multibyte character has been produced

## `mbsinit`

    int mbsinit(const mbstate_t *ps);Copy to clipboard

The function returns a nonzero value if `ps` is a null
pointer or if `*ps` designates an
[initial conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#initial%20conversion%20state).
Otherwise, it returns zero.

## `mbsrtowcs`

    size_t mbsrtowcs(wchar_t *restrict dst, const char **restrict src,
        size_t len, mbstate_t *restrict ps);Copy to clipboard

The function converts the multibyte string beginning at `*src`
to a sequence of wide characters as if by repeated calls of the form:

    x = mbrtowc(dst, *src, n, ps != 0 ? ps : &internal)Copy to clipboard

where `n` is some value &gt; 0 and `internal`
is an object of type
[`mbstate_t`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#mbstate_t)
internal to the `mbsrtowcs` function. At
[program startup](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#program%20startup),
`internal` is initialized to the
[initial conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#initial%20conversion%20state).
No other library function alters the value
stored in `internal`.

If `dst` is not a null pointer,
the `mbsrtowcs` function stores at most `len`
wide characters by calls to
[`mbrtowc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#mbrtowc).
The function effectively increments `dst` by one
and `*src` by `x` after each call to
[`mbrtowc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#mbrtowc)
that stores a converted wide character.
After a call that returns zero,
`mbsrtowcs` stores a null wide character
at `dst` and stores
a null pointer at `*src`.

If `dst` is a null pointer,
`len` is effectively assigned a large value.

The function returns:

- `(size_t)-1`, if a call to
[`mbrtowc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#mbrtowc) returns
`(size_t)-1`,
indicating that it has detected an encoding error before completing
the next multibyte character
- the number of multibyte characters successfully converted, not
including the terminating null character

## `mbstate_t`

    typedef o-type mbstate_t;Copy to clipboard

The type is an object type *o-type* that can represent a
[conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state)
for any of the functions
[`mbrlen`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#mbrlen),
[`mbrtowc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#mbrtowc),
[`mbsrtowcs`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#mbsrtowcs),
[`wcrtomb`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#wcrtomb), or
[`wcsrtombs`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#wcsrtombs).
A definition of the form:

    mbstate_t mbst = {0};Copy to clipboard

ensures that `mbst` represents the
[initial conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#initial%20conversion%20state).
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`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#mbsinit).

## `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](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_express.html#address%20constant%20expression).

## `putwc`

    wint_t putwc(wchar_t c, FILE *stream);Copy to clipboard

The function has the same effect as
`fputwc(c, stream)`
except that a macro version of `putwc`
can evaluate `stream` more than once.

## `putwchar`

    wint_t putwchar(wchar_t c);Copy to clipboard

The function has the same effect as
`fputwc(c, stdout)`.

## `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*](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_express.html#sizeof%20operator) operator.

## `swprintf`

    int swprintf(wchar_t *restrict s, size_t n,
        const wchar_t *restrict format, ...);Copy to clipboard

The function
[generates formatted text](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_prin.html#Print%20Functions),
under the control of the format `format`
and any additional arguments, and stores
each generated character in successive locations of the array object whose
first element has the address `s`. The function concludes
by storing a null wide character in the next location of the array.
If it cannot generate and store all characters in an array of size `n`,
the function returns a negative number. Otherwise,
it returns the number of wide characters generated -- not including
the null wide character.

## `swscanf`

    int swscanf(const wchar_t *restrict s,
        const wchar_t *restrict format, ...);Copy to clipboard

The function
[scans formatted text](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_scan.html#Scan%20Functions),
under the control of the format `format`
and any additional arguments. It accesses each scanned
character from successive locations of the array object whose first
element has the address `s`.
It returns the number of items matched and assigned, or it returns
[`EOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#EOF) if the function does not store
values before it accesses a null wide character from the array.

## `tm`

    struct tm;Copy to clipboard

`struct` `tm` contains members that describe various
properties of the calendar time. The declaration in this header leaves
`struct tm` an incomplete type.
Include the header
[`<time.h>`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_time.html#&lt;time.h&gt;)
to complete the type.

## `ungetwc`

    wint_t ungetwc(wint_t c, FILE *stream);Copy to clipboard

If `c` is not equal to
[`WEOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#WEOF), the function stores
`(wchar_t)c`
in the object whose address is `stream` and
clears the end-of-file indicator. If `c` equals
[`WEOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#WEOF) or
the store cannot occur, the function returns
[`WEOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#WEOF); otherwise,
it returns `(wchar_t)c`.
A subsequent library function call that
reads a wide character from the stream `stream` obtains this
stored value, which is then forgotten.

Thus, you can effectively
[push back](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#push%20back) a wide character
to a stream after reading a wide character.

## `vfwprintf`

    int vfwprintf(FILE *restrict stream, const wchar_t *restrict format,
        va_list arg);Copy to clipboard

The function
[generates formatted text](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_prin.html#Print%20Functions),
under the control of the format `format`
and any additional arguments, and writes
each generated wide character to the stream `stream`.
It returns the number of wide characters generated,
or it returns a negative value
if the function sets the error indicator for the stream.

The function accesses additional arguments by using the context
information designated by `ap`.
The program must execute the macro
[`va_start`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdarg.html#va_start)
before it calls the function, and then execute the macro
[`va_end`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdarg.html#va_end)
after the function returns.

## `vfwscanf`

    int vfwscanf(FILE *restrict stream, const wchar_t *restrict format,
        va_list ap); [added with C99]Copy to clipboard

The function
[scans formatted text](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_scan.html#Scan%20Functions),
under the control of the format `format`
and any additional arguments. It obtains each
scanned wide character from the stream `stream`. It returns the number
of input items matched and assigned, or it returns
[`WEOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#WEOF) if the
function does not store values before it sets the end-of-file or error
indicator for the stream.

The function accesses additional arguments by using the context
information designated by `ap`.
The program must execute the macro
[`va_start`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdarg.html#va_start)
before it calls the function, and then execute the macro
[`va_end`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdarg.html#va_end)
after the function returns.

## `vswprintf`

    int vswprintf(wchar_t *restrict s, size_t n, const wchar_t *restrict format,
        va_list arg);Copy to clipboard

The function
[generates formatted text](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_prin.html#Print%20Functions),
under the control of the format `format`
and any additional arguments, and stores
each generated wide character in successive locations of the array object
whose first element has the address `s`.
The function concludes by storing a null wide character
in the next location of the array.
If it cannot generate and store all characters in an array of size `n`,
the function returns a negative number. Otherwise,
it returns the number of wide characters generated -- not including
the null wide character.

The function accesses additional arguments by using the context
information designated by `ap`.
The program must execute the macro
[`va_start`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdarg.html#va_start)
before it calls the function, and then execute the macro
[`va_end`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdarg.html#va_end)
after the function returns.

## `vswscanf`

    int vswscanf(const wchar_t *restrict s, const wchar_t *restrict format,
        va_list ap); [added with C99]Copy to clipboard

The function
[scans formatted text](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_scan.html#Scan%20Functions),
under the control of the format `format`
and any additional arguments. It accesses each scanned wide
character from successive locations of the array object whose first
element has the address `s`.
It returns the number of items matched
and assigned, or it returns
[`WEOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#WEOF)
if the function does not store
values before it accesses a null character from the array.

The function accesses additional arguments by using the context
information designated by `ap`.
The program must execute the macro
[`va_start`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdarg.html#va_start)
before it calls the function, and then execute the macro
[`va_end`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdarg.html#va_end)
after the function returns.

## `vwprintf`

    int vwprintf(const wchar_t *restrict format,
        va_list arg);Copy to clipboard

The function
[generates formatted text](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_prin.html#Print%20Functions),
under the control of the format `format`
and any additional arguments, and writes
each generated wide character to the stream
[`stdout`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#stdout).
It returns the number of characters generated,
or a negative value if the function
sets the error indicator for the stream.

The function accesses additional arguments by using the context
information designated by `ap`.
The program must execute the macro
[`va_start`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdarg.html#va_start)
before it calls the function, and then execute the macro
[`va_end`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdarg.html#va_end)
after the function returns.

## `vwscanf`

    int vwscanf(const wchar_t *restrict format,
        va_list ap); [added with C99]Copy to clipboard

The function
[scans formatted text](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_scan.html#Scan%20Functions),
under the control of the format `format`
and any additional arguments. It obtains each
scanned wide character from the stream
[`stdin`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#stdin). It returns the number
of input items matched and assigned, or it returns
[`WEOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#WEOF) if the
function does not store values before it sets the end-of-file or error
indicators for the stream.

The function accesses additional arguments by using the context
information designated by `ap`.
The program must execute the macro
[`va_start`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdarg.html#va_start)
before it calls the function, and then execute the macro
[`va_end`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdarg.html#va_end)
after the function returns.

## `WCHAR_MAX`

    #define WCHAR_MAX <#if expression >= 127>Copy to clipboard

The macro yields the maximum value for type
[`wchar_t`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#wchar_t).

## `WCHAR_MIN`

    #define WCHAR_MIN <#if expression <= 0>Copy to clipboard

The macro yields the minimum value for type
[`wchar_t`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#wchar_t).

## `wchar_t`

    typedef i-type wchar_t; [keyword in C++]Copy to clipboard

The type is the integer type `i-type` of a
[wide-character constant](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#wide-character%20constant), such as `L'X'`.
You declare an object of type `wchar_t` to hold a
[wide character](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#Wide-Character%20Encoding).

## `wcrtomb`

    size_t wcrtomb(char *restrict s, wchar_t wc, mbstate_t *restrict 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/c_wchar.html#wchar_t)
are necessarily valid wide-character codes.)

If `ps` is not a null pointer, the
[conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state) for
the multibyte string is assumed to be `*ps`. Otherwise, it is
assumed to be `&internal`,
where `internal` is an object of type
[`mbstate_t`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#mbstate_t)
internal to the `wcrtomb` function. At
[program startup](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#program%20startup),
`internal` is initialized to the
[initial conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#initial%20conversion%20state).
No other library function alters the value stored
in `internal`.

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`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdlib.html#MB_CUR_MAX).)
If `wc` is a null wide character,
the function stores any
[shift sequence](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#shift%20sequence)
needed to restore the
[initial shift state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#initial%20shift%20state),
followed by a null byte. The resulting conversion state is the
[initial conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#initial%20conversion%20state).

If `s` is a null pointer, the function effectively returns
`wcrtomb(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](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#initial%20conversion%20state)
and to terminate the multibyte string
pending from a previous call to `wcrtomb` or
[`wcsrtombs`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#wcsrtombs)
for the same string and
[conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state).)

The function returns:

- `(size_t)-1`
if `wc` is an invalid wide-character code,
in which case the function stores the value
[`EILSEQ`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_errno.html#EILSEQ) in
[`errno`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_errno.html#errno)
and leaves the resulting
[conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state) undefined
- `x`, the number of bytes needed
to complete the next muitibyte character, in which case the resulting
[conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#conversion%20state) indicates
that `x` bytes have been generated

## `wcscat`

    wchar_t *wcscat(wchar_t *restrict s1, const wchar_t *restrict s2);Copy to clipboard

The function copies the wide string `s2`, including its
terminating null wide character, to successive elements of the array
that stores the wide string `s1`, beginning
with the element that stores the terminating null wide character of
`s1`. It returns `s1`.

## `wcschr`

    wchar_t *wcschr(const wchar_t *s, wchar_t c); [not in C++]
    const wchar_t *wcschr(const wchar_t *s, wchar_t c); [C++ only]
    wchar_t *wcschr(wchar_t *s, wchar_t c); [C++ only]Copy to clipboard

The function searches for the first element of the wide string
`s` that equals `c`.
It considers the terminating null wide
character as part of the wide string. If successful, the function
returns the address of the matching element; otherwise, it returns
a null pointer.

## `wcscmp`

    int wcscmp(const wchar_t *s1, const wchar_t *s2);Copy to clipboard

The function compares successive elements from two wide strings,
`s1` and `s2`,
until it finds elements that are not equal.

- If all elements are equal, the function returns zero.

- If the differing element from `s1` is greater than the
element from `s2`, the function returns a positive number.
- Otherwise, the function returns a negative number.

## `wcscoll`

    int wcscoll(const wchar_t *s1, const wchar_t *s2);Copy to clipboard

The function compares two wide strings,
`s1` and `s2`,
using a comparison rule that depends on the current
[locale](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_locale.html#locale). If `s1` compares
greater than `s2` by this rule,
the function returns a positive number.
If the two wide strings compare equal, it returns zero. Otherwise, it
returns a negative number.

## `wcscpy`

    wchar_t *wcscpy(wchar_t *restrict s1, const wchar_t *restrict s2);Copy to clipboard

The function copies the wide string `s2`, including its
terminating null wide character, to successive elements of the array
whose first element has the address `s1`. It
returns `s1`.

## `wcscspn`

    size_t wcscspn(const wchar_t *s1, const wchar_t *s2);Copy to clipboard

The function searches for the first element `s1[i]`
in the wide string `s1` that equals *any one* of the elements
of the wide string `s2` and returns `i.`
Each terminating null wide character is considered
part of its wide string.

## `wcsftime`

    size_t wcsftime(wchar_t *restrict s, size_t maxsize,
        const wchar_t *restrict format, const struct tm *restrict timeptr);Copy to clipboard

The function generates formatted text, under the control of
the format `format` and the values stored in the time structure
`*tptr`. It stores each generated wide character in successive
locations of the array object of size `n` whose first element
has the address `s`. The function then stores a null wide character
in the next location of the array. It returns `x`, the number
of wide characters generated, if `x < n`; otherwise,
it returns zero, and the values stored in the array are indeterminate.

For each wide character other than `%` in the format, the
function stores that wide character in the array object. Each occurrence
of `%` followed by another character in the format is a
**conversion specifier.**
For each conversion specifier, the function stores a
replacement wide character sequence. Conversion specifiers are the
same as for the function
[`strftime`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_time.html#strftime). The current
[locale category](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_locale.html#locale%20category)
[`LC_TIME`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_locale.html#LC_TIME) can affect these
replacement character sequences.

## `wcslen`

    size_t wcslen(const wchar_t *s);Copy to clipboard

The function returns the number of wide characters in the wide
string `s`, *not* including
its terminating null wide character.

## `wcsncat`

    wchar_t *wcsncat(wchar_t *restrict s1, const wchar_t *restrict s2,
        size_t n);Copy to clipboard

The function copies the wide string `s2`, *not* including
its terminating null wide character,
to successive elements of the array
that stores the wide string `s1`, beginning
with the element that stores the terminating null wide character of
`s1`. The function copies no more than
`n` wide characters from `s2`.
It then stores a null wide character, in the next
element to be altered in `s1`, and returns `s1`.

## `wcsncmp`

    int wcsncmp(const wchar_t *s1, const wchar_t *s2,
        size_t n);Copy to clipboard

The function compares successive elements from two wide strings,
`s1` and `s2`, until it finds elements
that are not equal or until it has compared the first
`n` elements of the two wide strings.

- If all elements are equal, the function returns zero.
- If the differing element from `s1` is greater than the
element from `s2`, the function returns a positive number.
- Otherwise, it returns a negative number.

## `wcsncpy`

    wchar_t *wcsncpy(wchar_t *restrict s1, const wchar_t *restrict s2,
        size_t n);Copy to clipboard

The function copies the wide string `s2`, *not* including
its terminating null wide character, to successive elements of the array
whose first element has the address `s1`.
It copies no more than `n` wide characters
from `s2`. The function then stores
zero or more null wide characters in the next elements
to be altered in `s1` until it stores a total of `n`
wide characters. It returns `s1`.

## `wcspbrk`

    wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2); [not in C++]
    const wchar_t *wcspbrk(const wchar_t *s1, const wchar_t *s2); [C++ only]
    wchar_t *wcspbrk(wchar_t *s1, const wchar_t *s2); [C++ only]Copy to clipboard

The function searches for the first element `s1[i]`
in the wide string `s1` that equals *any one* of the elements
of the wide string `s2`. It considers each terminating null wide
character as part of its wide string. If `s1[i]` is not
the terminating null wide character, the function returns
`&s1[i]`; otherwise, it returns a null pointer.

## `wcsrchr`

    wchar_t *wcsrchr(const wchar_t *s, wchar_t c); [not in C++]
    const wchar_t *wcsrchr(const wchar_t *s, wchar_t c); [C++ only]
    wchar_t *wcsrchr(wchar_t *s, wchar_t c); [C++ only]Copy to clipboard

The function searches for the last element of the wide string
`s` that equals `c`.
It considers the terminating null wide
character as part of the wide string. If successful, the function
returns the address of the matching element; otherwise, it returns
a null pointer.

## `wcsrtombs`

    size_t wcsrtombs(char *restrict dst, const wchar_t **restrict src,
        size_t len, mbstate_t *restrict ps);Copy to clipboard

The function converts the wide-character string beginning at
`*src` to a sequence of multibyte characters as if by repeated
calls of the form:

    x = wcrtomb(dst ? dst : buf, *src, ps != 0 ? ps : &internal)Copy to clipboard

where `buf` is an array of type *char*
and `internal` is an object of type
[`mbstate_t`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#mbstate_t),
both internal to the `wcsrtombs` function. At
[program startup](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_over.html#program%20startup),
`internal` is initialized to the
[initial conversion state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#initial%20conversion%20state).
No other library function alters the value
stored in `internal`.

If `dst` is not a null pointer,
the `wcsrtombs` function stores at most
`len` bytes by calls to
[`wcrtomb`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#wcrtomb). The function
effectively increments `dst` by `x`
and `*src` by one after each call to
[`wcrtomb`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#wcrtomb)
that stores a *complete* converted
multibyte character in the remaining space available. After a call
that stores a complete null multibyte character at `dst`
(including any
[shift sequence](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#shift%20sequence)
needed to restore the
[initial shift state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#initial%20shift%20state)),
the function stores a null pointer at `*src`.

If `dst` is a null pointer,
`len` is effectively assigned a large value.

The function returns:

- `(size_t)-1`, if a call to
[`wcrtomb`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#wcrtomb)
returns `(size_t)-1`,
indicating that it has detected an invalid wide-character code
- the number of bytes successfully converted, not including the
terminating null byte

## `wcsspn`

    size_t wcsspn(const wchar_t *s1, const wchar_t *s2);Copy to clipboard

The function searches for the first element `s1[i]`
in the wide string `s1` that equals *none* of the elements
of the wide string `s2` and returns `i`. It considers
the terminating null wide character as
part of the wide string `s1` only.

## `wcsstr`

    wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2); [not in C++]
    const wchar_t *wcsstr(const wchar_t *s1, const wchar_t *s2); [C++ only]
    wchar_t *wcsstr(wchar_t *s1, const wchar_t *s2); [C++ only]Copy to clipboard

The function searches for the first sequence of elements in
the wide string `s1` that matches the sequence of elements in
the wide string `s2`, *not* including its terminating null
wide character. If successful, the function returns the address of
the matching first element; otherwise, it returns a null pointer.

## `wcstod`

    double wcstod(const wchar_t *restrict nptr,
        wchar_t **restrict endptr);Copy to clipboard

The function converts the initial wide characters of the wide
string `s` to an equivalent value `x`
of type *double.* If `endptr` is not a null pointer,
the function stores a pointer to the unconverted remainder
of the wide string in `*endptr`.
The function then returns `x`.

The initial wide characters of the wide string `s` must
match the same pattern as recognized by the function
[`strtod`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdlib.html#strtod),
where each wide character `wc` is converted as if by calling
`wctob(wc))`.

If the wide string `s` matches this pattern,
its equivalent value is the value returned by
[`strtod`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdlib.html#strtod)
for the converted sequence.
If the wide string `s` does not match a valid pattern,
the value stored in `*endptr` is `s`,
and `x` is zero. If a
[range error](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_math.html#range%20error) occurs,
`wcstod` behaves exactly as the functions declared in
[`<math.h>`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_math.html#&lt;math.h&gt;).

## `wcstof`

    float wcstof(const wchar_t *restrict nptr,
     wchar_t **restrict endptr);Copy to clipboard

The function converts the initial wide characters of the wide
string `s` to an equivalent value `x`
of type *float.* If `endptr` is not a null pointer,
the function stores a pointer to the unconverted remainder
of the wide string in `*endptr`.
The function then returns `x`.

The initial wide characters of the wide string `s` must
match the same pattern as recognized by the function
[`strtod`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdlib.html#strtod),
where each wide character `wc` is converted as if by calling
`wctob(wc))`.

If the wide string `s` matches this pattern,
its equivalent value is the value returned by
[`strtof`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdlib.html#strtof)
for the converted sequence.
If the wide string `s` does not match a valid pattern,
the value stored in `*endptr` is `s`,
and `x` is zero. If a
[range error](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_math.html#range%20error) occurs,
`wcstod` behaves exactly as the functions declared in
[`<math.h>`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_math.html#&lt;math.h&gt;).

## `wcstok`

    wchar_t *wcstok(wchar_t *restrict s1, const wchar_t *restrict s2,
        wchar_t **restrict ptr);Copy to clipboard

If `s1` is not a null pointer, the function begins a search
of the wide string `s1`. Otherwise, it begins a search of the
wide string whose address was last stored in `*ptr` on an earlier
call to the function, as described below. The search proceeds as follows:

1. The function searches the wide string for `begin,` the
address of the first element that equals *none* of the elements
of the wide string `s2` (a set of token separators). It considers
the terminating null character as part of the search wide string only.
2. If the search does not find an element, the function stores
the address of the terminating null wide character in `*ptr`
(so that a subsequent search beginning with that address will fail)
and returns a null pointer. Otherwise, the function searches from
`begin` for `end,`
the address of the first element that
equals *any one* of the elements of the wide string `s2`.
It again considers the terminating null wide character as part of
the search string only.
3. If the search does not find an element, the function stores
the address of the terminating null wide character in `*ptr`.
Otherwise, it stores a null wide character in the element whose address
is `end.` Then it stores the address of the next element after
`end` in `*ptr`
(so that a subsequent search beginning with
that address will continue with the remaining elements of the string)
and returns `begin`.

## `wcstol`

    long wcstol(const wchar_t *restrict nptr, wchar_t **restrict endptr,
        int base);Copy to clipboard

The function converts the initial wide characters of the wide
string `s` to an equivalent value `x`
of type *long.* If `endptr` is not a null pointer,
the function stores a pointer to the unconverted remainder
of the wide string in `*endptr`.
The function then returns `x`.

The initial wide characters of the wide string `s` must
match the same pattern as recognized by the function
[`strtol`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdlib.html#strtol),
with the same `base` argument,
where each wide character `wc` is converted as if by calling
`wctob(wc))`.

If the wide string `s` matches this pattern,
its equivalent value is the value returned by
[`strtol`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdlib.html#strtol),
with the same `base` argument,
for the converted sequence.
If the wide string `s` does not match a valid pattern,
the value stored in `*endptr` is `s`,
and `x` is zero. If the equivalent value is too large
in magnitude to represent as type *long,*
`wcstol` stores the value of
[`ERANGE`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_errno.html#ERANGE) in
[`errno`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_errno.html#errno) and returns either
[`LONG_MAX`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_limits.html#LONG_MAX)
if `x` is positive or
[`LONG_MIN`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_limits.html#LONG_MIN)
if `x` is negative.

## `wcstold`

    long double wcstof(const wchar_t *restrict nptr,
     wchar_t **restrict endptr);Copy to clipboard

The function converts the initial wide characters of the wide
string `s` to an equivalent value `x`
of type *long double.* If `endptr` is not a null pointer,
the function stores a pointer to the unconverted remainder
of the wide string in `*endptr`.
The function then returns `x`.

The initial wide characters of the wide string `s` must
match the same pattern as recognized by the function
[`strtod`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdlib.html#strtod),
where each wide character `wc` is converted as if by calling
`wctob(wc))`.

If the wide string `s` matches this pattern,
its equivalent value is the value returned by
[`strtold`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdlib.html#strtold)
for the converted sequence.
If the wide string `s` does not match a valid pattern,
the value stored in `*endptr` is `s`,
and `x` is zero. If a
[range error](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_math.html#range%20error) occurs,
`wcstod` behaves exactly as the functions declared in
[`<math.h>`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_math.html#&lt;math.h&gt;).

## `wcstoll`

    long long wcstoll(const wchar_t *restrict nptr, wchar_t **restrict endptr,
        int base);Copy to clipboard

The function converts the initial wide characters of the wide
string `s` to an equivalent value `x`
of type *long long.* If `endptr` is not a null pointer,
the function stores a pointer to the unconverted remainder
of the wide string in `*endptr`.
The function then returns `x`.

The initial wide characters of the wide string `s` must
match the same pattern as recognized by the function
[`strtol`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdlib.html#strtol),
with the same `base` argument,
where each wide character `wc` is converted as if by calling
`wctob(wc))`.

If the wide string `s` matches this pattern,
its equivalent value is the value returned by
[`strtoll`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdlib.html#strtoll),
with the same `base` argument,
for the converted sequence.
If the wide string `s` does not match a valid pattern,
the value stored in `*endptr` is `s`,
and `x` is zero. If the equivalent value is too large
in magnitude to represent as type *long long,*
`wcstoll` stores the value of
[`ERANGE`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_errno.html#ERANGE) in
[`errno`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_errno.html#errno) and returns either
[`LLONG_MAX`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_limits.html#LLONG_MAX)
if `x` is positive or
[`LLONG_MIN`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_limits.html#LLONG_MIN)
if `x` is negative.

## `wcstoul`

    unsigned long wcstoul(const wchar_t *restrict nptr,
         wchar_t **restrict endptr, int base);Copy to clipboard

The function converts the initial wide characters of the wide
string `s` to an equivalent value `x`
of type *unsigned long.* If `endptr` is not a null pointer,
it stores a pointer to the unconverted remainder
of the wide string in `*endptr`.
The function then returns `x`.

`wcstoul` converts strings exactly as does
[`wcstol`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#wcstol),
but checks only if the equivalent value is too large
to represent as type *unsigned long.*
In this case, `wcstoul` stores the value of
[`ERANGE`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_errno.html#ERANGE) in
[`errno`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_errno.html#errno) and returns
[`ULONG_MAX`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_limits.html#ULONG_MAX).

## `wcstoull`

    unsigned long long wcstoull(const wchar_t *restrict nptr,
         wchar_t **restrict endptr, int base);Copy to clipboard

The function converts the initial wide characters of the wide
string `s` to an equivalent value `x`
of type *unsigned long long.* If `endptr` is not a null pointer,
it stores a pointer to the unconverted remainder
of the wide string in `*endptr`.
The function then returns `x`.

`wcstoull` converts strings exactly as does
[`wcstoll`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#wcstoll),
but checks only if the equivalent value is too large
to represent as type *unsigned long long.*
In this case, `wcstoull` stores the value of
[`ERANGE`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_errno.html#ERANGE) in
[`errno`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_errno.html#errno) and returns
[`ULLONG_MAX`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_limits.html#ULLONG_MAX).

## `wcsxfrm`

    size_t wcsxfrm(wchar_t *restrict s1, const wchar_t *restrict s2,
        size_t n);Copy to clipboard

The function stores a wide string in the array
whose first element has the address `s1`. It stores no more than
`n` wide characters, *including* the terminating null wide
character, and returns the number of wide characters needed to represent
the entire wide string, *not* including the terminating null
wide character. If the value returned is `n` or greater, the
values stored in the array are indeterminate. (If `n` is zero,
`s1` can be a null pointer.)

`wcsxfrm` generates the wide string it stores from the
wide string `s2` by using a transformation rule that depends
on the current
[locale](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_locale.html#locale).
For example, if `x` is a transformation
of `s1` and `y` is a transformation
of `s2`, then
`wcscmp(x, y)`
returns the same value as
`wcscoll(s1, s2)`.

## `wctob`

    int wctob(wint_t c);Copy to clipboard

The function determines whether `c` can be represented
as a one-byte multibyte character `x`, beginning in the
[initial shift state](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_charset.html#initial%20shift%20state).
(It effectively calls
[`wcrtomb`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#wcrtomb)
to make the conversion.) If so, the function returns
`x`. Otherwise, it returns
[`EOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#EOF).

## `WEOF`

    #define WEOF <wint_t constant expression>Copy to clipboard

The macro yields the return value, of type
[`wint_t`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#wint_t),
used to signal the end of a
[wide stream](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_file.html#wide%20stream)
or to report an error condition.

## `wint_t`

    typedef i_type wint_t;Copy to clipboard

The type is the integer type `i_type`
that can represent all values of type
[`wchar_t`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#wchar_t)
as well as the value of the macro
[`WEOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_wchar.html#WEOF),
and that doesn't change when
[promoted](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_express.html#Promoting).

## `wmemchr`

    wchar_t *wmemchr(const wchar_t *s, wchar_t c,
        size_t n); [not in C++]
    const wchar_t *wmemchr(const wchar_t *s, wchar_t c,
        size_t n); [C++ only]
    wchar_t *wmemchr(wchar_t *s, wchar_t c,
        size_t n); [C++ only]Copy to clipboard

The function searches for the first element of an array
beginning at the address `s` with size `n`,
that equals `c`. If successful,
it returns the address of the matching element;
otherwise, it returns a null pointer.

## `wmemcmp`

    int wmemcmp(const wchar_t *s1, const wchar_t *s2,
        size_t n);Copy to clipboard

The function compares successive elements from two arrays
beginning at the addresses `s1` and `s2`
(both of size `n`),
until it finds elements that are not equal:

- If all elements are equal, the function returns zero.
- If the differing element from `s1` is greater than the
element from `s2`, the function returns a positive number.
- Otherwise, the function returns a negative number.

## `wmemcpy`

    wchar_t *wmemcpy(wchar_t *restrict s1, const wchar_t *restrict s2,
        size_t n);Copy to clipboard

The function copies the array beginning at
the address `s2` to the array beginning at
the address `s1` (both of size `n`).
It returns `s1`.
The elements of the arrays can be accessed and stored in any order.

## `wmemmove`

    wchar_t *wmemmove(wchar_t *s1, const wchar_t *s2,
        size_t n);Copy to clipboard

The function copies the array beginning at
`s2` to the array beginning at `s1` (both
of size `n`). It returns `s1`.
If the arrays overlap, the
function accesses each of the element values from `s2` before
it stores a new value in that element, so the copy is not corrupted.

## `wmemset`

    wchar_t *wmemset(wchar_t *s, wchar_t c, size_t n);Copy to clipboard

The function stores `c` in each of the elements of the
array beginning at `s`, with size `n`.
It returns `s`.

## `wprintf`

    int wprintf(const wchar_t *restrict format, ...);Copy to clipboard

The function
[generates formatted text](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_prin.html#Print%20Functions),
under the control of the format `format`
and any additional arguments, and writes
each generated wide character to the stream
[`stdout`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#stdout). It returns the
number of wide characters generated, or it returns a negative value
if the function sets the error indicator for the stream.

## `wscanf`

    int wscanf(const wchar_t *restrict format, ...);Copy to clipboard

The function
[scans formatted text](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_lib_scan.html#Scan%20Functions),
under the control of the format `format`
and any additional arguments. It obtains each
scanned wide character from the stream
[`stdin`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#stdin). It returns the
number of input items matched and assigned, or it returns
[`EOF`](https://docs.qualcomm.com/doc/80-N3040-23/topic/c_stdio.html#EOF)
if the function does not store values before it sets the end-of-file
or error indicators for the stream.

* * *

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

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

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

Last Published: Oct 06, 2026

Previous Topic
 
<uchar.h></uchar.h> Next Topic

<wctype.h></wctype.h>