WCHAR.H(7) Miscellaneous Information Manual WCHAR.H(7)

wchar.h — wide-character handling

#include <wchar.h>

[CX] Some of the functionality described on this reference page extends the ISO C standard. Applications shall define the appropriate feature test macro (see XSH V2_chap02(3) ) to enable the visibility of these symbols in this header.

The <wchar.h> header shall define the following types:

[CX] As described in <stdio.h> .
[CX] As described in <locale.h> .
An object type other than an array type that can hold the conversion state information necessary to convert between sequences of (possibly multi-byte) characters and wide characters. [CX] If a codeset is being used such that an mbstate_t needs to preserve more than two levels of reserved state, the results are unspecified.
As described in <stddef.h> .
[CX] As described in <stdarg.h> .
As described in <stddef.h> .
[OB XSI] A scalar type of a data object that can hold values which represent locale-specific character classification.
An integer type capable of storing any valid value of wchar_t or WEOF.

The tag shall be declared as naming an incomplete structure type, the contents of which are described in the <time.h> header.

The implementation shall support one or more programming environments in which the width of wint_t is no greater than the width of type . The names of these programming environments can be obtained using the confstr(3) function or the getconf(1) utility.

The <wchar.h> header shall define the following macros:

As described in <stdint.h> .
As described in <stdint.h> .
Constant expression of type wint_t that is returned by several WP functions to indicate end-of-file.
As described in <stddef.h> .

[CX] Inclusion of the <wchar.h> header may make visible all symbols from the headers <ctype.h>, <string.h>, <stdarg.h>, <stddef.h>, <stdio.h>, <stdlib.h>, and <time.h>.

The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided for use with ISO C standard compilers. Arguments to functions in this list can point to arrays containing wchar_t values that do not correspond to members of the character set of the current locale. Such values shall be processed according to the specified semantics, unless otherwise stated.

wint_t        btowc(int);
wint_t        fgetwc(FILE *);
wchar_t      *fgetws(wchar_t *restrict, int, FILE *restrict);
wint_t        fputwc(wchar_t, FILE *);
int           fputws(const wchar_t *restrict, FILE *restrict);
int           fwide(FILE *, int);
int           fwprintf(FILE *restrict, const wchar_t *restrict, ...);
int           fwscanf(FILE *restrict, const wchar_t *restrict, ...);
wint_t        getwc(FILE *);
wint_t        getwchar(void);
[OB XSI]
int           iswalnum(wint_t);
int           iswalpha(wint_t);
int           iswcntrl(wint_t);
int           iswctype(wint_t, wctype_t);
int           iswdigit(wint_t);
int           iswgraph(wint_t);
int           iswlower(wint_t);
int           iswprint(wint_t);
int           iswpunct(wint_t);
int           iswspace(wint_t);
int           iswupper(wint_t);
int           iswxdigit(wint_t);

size_t        mbrlen(const char *restrict, size_t, mbstate_t *restrict);
size_t        mbrtowc(wchar_t *restrict, const char *restrict, size_t,
                  mbstate_t *restrict);
int           mbsinit(const mbstate_t *);
[CX]
size_t        mbsnrtowcs(wchar_t *restrict, const char **restrict,
                  size_t, size_t, mbstate_t *restrict);

size_t        mbsrtowcs(wchar_t *restrict, const char **restrict, size_t,
                  mbstate_t *restrict);
[CX]
FILE         *open_wmemstream(wchar_t **, size_t *);

wint_t        putwc(wchar_t, FILE *);
wint_t        putwchar(wchar_t);
int           swprintf(wchar_t *restrict, size_t,
                  const wchar_t *restrict, ...);
int           swscanf(const wchar_t *restrict,
                  const wchar_t *restrict, ...);
[OB XSI]
wint_t        towlower(wint_t);
wint_t        towupper(wint_t);

wint_t        ungetwc(wint_t, FILE *);
int           vfwprintf(FILE *restrict, const wchar_t *restrict, va_list);
int           vfwscanf(FILE *restrict, const wchar_t *restrict, va_list);
int           vswprintf(wchar_t *restrict, size_t,
                  const wchar_t *restrict, va_list);
int           vswscanf(const wchar_t *restrict, const wchar_t *restrict,
                  va_list);
int           vwprintf(const wchar_t *restrict, va_list);
int           vwscanf(const wchar_t *restrict, va_list);
[CX]
wchar_t      *wcpcpy(wchar_t *restrict, const wchar_t *restrict);
wchar_t      *wcpncpy(wchar_t *restrict, const wchar_t *restrict, size_t);

size_t        wcrtomb(char *restrict, wchar_t, mbstate_t *restrict);
[CX]
int           wcscasecmp(const wchar_t *, const wchar_t *);
int           wcscasecmp_l(const wchar_t *, const wchar_t *, locale_t);

wchar_t      *wcscat(wchar_t *restrict, const wchar_t *restrict);
wchar_t      *wcschr(const wchar_t *, wchar_t);
int           wcscmp(const wchar_t *, const wchar_t *);
int           wcscoll(const wchar_t *, const wchar_t *);
[CX]
int           wcscoll_l(const wchar_t *, const wchar_t *, locale_t);

wchar_t      *wcscpy(wchar_t *restrict, const wchar_t *restrict);
size_t        wcscspn(const wchar_t *, const wchar_t *);
[CX]
wchar_t      *wcsdup(const wchar_t *);

size_t        wcsftime(wchar_t *restrict, size_t,
                  const wchar_t *restrict, const struct tm *restrict);
size_t        wcslen(const wchar_t *);
[CX]
int           wcsncasecmp(const wchar_t *, const wchar_t *, size_t);
int           wcsncasecmp_l(const wchar_t *, const wchar_t *, size_t,
                  locale_t);

wchar_t      *wcsncat(wchar_t *restrict, const wchar_t *restrict, size_t);
int           wcsncmp(const wchar_t *, const wchar_t *, size_t);
wchar_t      *wcsncpy(wchar_t *restrict, const wchar_t *restrict, size_t);
[CX]
size_t        wcsnlen(const wchar_t *, size_t);
size_t        wcsnrtombs(char *restrict, const wchar_t **restrict, size_t,
                  size_t, mbstate_t *restrict);

wchar_t      *wcspbrk(const wchar_t *, const wchar_t *);
wchar_t      *wcsrchr(const wchar_t *, wchar_t);
size_t        wcsrtombs(char *restrict, const wchar_t **restrict,
                  size_t, mbstate_t *restrict);
size_t        wcsspn(const wchar_t *, const wchar_t *);
wchar_t      *wcsstr(const wchar_t *restrict, const wchar_t *restrict);
double        wcstod(const wchar_t *restrict, wchar_t **restrict);
float         wcstof(const wchar_t *restrict, wchar_t **restrict);
wchar_t      *wcstok(wchar_t *restrict, const wchar_t *restrict,
                  wchar_t **restrict);
long          wcstol(const wchar_t *restrict, wchar_t **restrict, int);
long double   wcstold(const wchar_t *restrict, wchar_t **restrict);
long long     wcstoll(const wchar_t *restrict, wchar_t **restrict, int);
unsigned long wcstoul(const wchar_t *restrict, wchar_t **restrict, int);
unsigned long long
              wcstoull(const wchar_t *restrict, wchar_t **restrict, int);
[XSI]
int           wcswidth(const wchar_t *, size_t);

size_t        wcsxfrm(wchar_t *restrict, const wchar_t *restrict, size_t);
[CX]
size_t        wcsxfrm_l(wchar_t *restrict, const wchar_t *restrict,
                  size_t, locale_t);

int           wctob(wint_t);
[OB XSI]
wctype_t      wctype(const char *);

[XSI]
int           wcwidth(wchar_t);

wchar_t      *wmemchr(const wchar_t *, wchar_t, size_t);
int           wmemcmp(const wchar_t *, const wchar_t *, size_t);
wchar_t      *wmemcpy(wchar_t *restrict, const wchar_t *restrict, size_t);
wchar_t      *wmemmove(wchar_t *, const wchar_t *, size_t);
wchar_t      *wmemset(wchar_t *, wchar_t, size_t);
int           wprintf(const wchar_t *restrict, ...);
int           wscanf(const wchar_t *restrict, ...);

The iswblank(3) function was a late addition to the ISO C standard and was introduced at the same time as the ISO C standard introduced <wctype.h>, which contains all of the isw* () functions. The Open Group Base Specifications had previously aligned with the MSE working draft and had introduced the rest of the isw* () functions into <wchar.h>. For backwards-compatibility, the original set of isw* () functions, without iswblank(3), are permitted (as part of the XSI option) in <wchar.h>. For maximum portability, applications should include <wctype.h> in order to obtain declarations for the isw* () functions. This compatibility has been made obsolescent.

In the ISO C standard, the symbols referenced as XSI extensions are in <wctype.h>. Their presence here is thus an extension.

None.

<ctype.h>, <locale.h> , <stdarg.h>, <stddef.h> , <stdint.h>, <stdio.h>, <stdlib.h>, <string.h>, <time.h>, <wctype.h>

XSH V2_chap02(3), btowc(3), confstr(3), fgetwc(3), fgetws(3), fputwc(3), fputws(3), fwide(3), fwprintf(3), fwscanf(3), getwc(3), getwchar(3), iswalnum(3), iswalpha(3), iswcntrl(3), iswctype(3), iswdigit(3), iswgraph(3), iswlower(3), iswprint(3), iswpunct(3), iswspace(3), iswupper(3), iswxdigit(3), mbrlen(3), mbrtowc(3), mbsinit(3), mbsrtowcs(3), open_memstream(3), putwc(3), putwchar(3), towlower(3), towupper(3), ungetwc(3), vfwprintf(3), vfwscanf(3), wcrtomb(3), wcscasecmp(3), wcscat(3), wcschr(3), wcscmp(3), wcscoll(3), wcscpy(3), wcscspn(3), wcsdup(3), wcsftime(3), wcslen(3), wcsncat(3), wcsncmp(3), wcsncpy(3), wcspbrk(3), wcsrchr(3), wcsrtombs(3), wcsspn(3), wcsstr(3), wcstod(3), wcstok(3), wcstol(3), wcstoul(3), wcswidth(3), wcsxfrm(3), wctob(3), wctype(3), wcwidth(3), wmemchr(3), wmemcmp(3), wmemcpy(3), wmemmove(3), wmemset(3)

XCU getconf(1)

First released in Issue 4.

Aligned with the ISO/IEC 9899/AMD1:1995 (“ISO C90, Amendment 1”) (E).

The Open Group Corrigendum U021/10 is applied. The prototypes for wcswidth(3) and wcwidth(3) are marked as extensions.

The Open Group Corrigendum U028/5 is applied, correcting the prototype for the mbsinit(3) function.

The following changes are made for alignment with the ISO/IEC 9899:1999 (“ISO C99”) standard:

The type wctype_t, the isw* (), (), and wctype(3) functions are marked as XSI extensions.

IEEE Std 1003.1-2001 (“POSIX.1”)/Cor 1-2002, item XBD/TC1/D6/26 is applied, adding the APPLICATION USAGE section.

The mbsnrtowcs(3), open_wmemstream(3), wcpcpy(3), wcpncpy(3), wcscasecmp(3), wcsdup(3), wcsncasecmp(3), wcsnlen(3), and wcsnrtombs(3) functions are added from The Open Group Technical Standard, 2006, Extended API Set Part 1.

The wcscasecmp_l(3), wcsncasecmp_l(3), wcscoll_l(3), and wcsxfrm_l(3) functions are added from The Open Group Technical Standard, 2006, Extended API Set Part 4.

The wctype_t type, and the isw* (), towlower(3), and towupper(3) functions are marked obsolescent in <wchar.h> since the ISO C standard requires the declarations to be in <wctype.h>.

This reference page is clarified with respect to macros and symbolic constants, and a declaration for the locale_t type is added.

POSIX.1-2008, Technical Corrigendum 1, XBD/TC1-2008/0081 [380] is applied.

POSIX.1-2008, Technical Corrigendum 2, XBD/TC2-2008/0088 [73] is applied.

January 31, 2018 posix.fail