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.

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.

January 1, 2008 posix.fail