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 2.2 The Compilation Environment ) to enable the visibility of these symbols in this header.The <wchar.h> header shall define the following types:
- FILE
- [CX] As described in <stdio.h>.
- locale_t
- [CX] As described in <locale.h>.
- mbstate_t
- A complete 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.
- size_t
- As described in <stddef.h>.
- va_list
- [CX] As described in <stdarg.h>.
- wchar_t
- As described in <stddef.h>.
- wint_t
- An integer type capable of storing any valid value of wchar_t or WEOF.
The tag tm 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 long. The names of these programming environments can be obtained using the confstr() function or the getconf utility.
The <wchar.h> header shall define the following macros:
- WCHAR_MAX
- As described in <stdint.h>.
- WCHAR_MIN
- As described in <stdint.h>.
- WEOF
- Constant expression of type wint_t that is returned by several WP functions to indicate end-of-file.
- NULL
- 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); 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, ...); 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); [CX] size_t wcslcat(wchar_t *restrict, const wchar_t *restrict, size_t); size_t wcslcpy(wchar_t *restrict, const wchar_t *restrict, size_t); 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); [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, ...);
None.
None.
None.
<ctype.h> , <locale.h> , <stdarg.h> , <stddef.h> , <stdint.h> , <stdio.h> , <stdlib.h> , <string.h> , <time.h> , <wctype.h>
XSH 2.2 The Compilation Environment , btowc , confstr , fgetwc , fgetws , fputwc , fputws , fwide , fwprintf , fwscanf , getwc , getwchar , iswalnum , iswalpha , iswcntrl , iswctype , iswdigit , iswgraph , iswlower , iswprint , iswpunct , iswspace , iswupper , iswxdigit , mbrlen , mbrtowc , mbsinit , mbsrtowcs , open_memstream , putwc , putwchar , towlower , towupper , ungetwc , vfwprintf , vfwscanf , wcrtomb , wcscasecmp , wcscat , wcschr , wcscmp , wcscoll , wcscpy , wcscspn , wcsdup , wcsftime , wcslcat , wcslen , wcsncat , wcsncmp , wcsncpy , wcspbrk , wcsrchr , wcsrtombs , wcsspn , wcsstr , wcstod , wcstok , wcstol , wcstoul , wcswidth , wcsxfrm , wctob , wctype , wcwidth , wmemchr , wmemcmp , wmemcpy , wmemmove , wmemset
XCU getconf
First released in Issue 4.
Aligned with the ISO/IEC 9899:1990/Amendment 1:1995 (E).
The Open Group Corrigendum U021/10 is applied. The prototypes for wcswidth() and wcwidth() are marked as extensions.
The Open Group Corrigendum U028/5 is applied, correcting the prototype for the mbsinit() function.
The following changes are made for alignment with the ISO/IEC 9899:1999 standard:
Various function prototypes are updated to add the restrict keyword.
The functions vfwscanf(), vswscanf(), wcstof(), wcstold(), wcstoll(), and wcstoull() are added.
The type wctype_t, the isw*(), to*(), and wctype() functions are marked as XSI extensions.
IEEE Std 1003.1-2001/Cor 1-2002, item XBD/TC1/D6/26 is applied, adding the APPLICATION USAGE section.
The mbsnrtowcs(), open_wmemstream(), wcpcpy(), wcpncpy(), wcscasecmp(), wcsdup(), wcsncasecmp(), wcsnlen(), and wcsnrtombs() functions are added from The Open Group Technical Standard, 2006, Extended API Set Part 1.
The wcscasecmp_l(), wcsncasecmp_l(), wcscoll_l(), and wcsxfrm_l() functions are added from The Open Group Technical Standard, 2006, Extended API Set Part 4.
The wctype_t type, and the isw*(), towlower(), and towupper() 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.
Austin Group Defect 986 is applied, adding wcslcat() and wcslcpy().
Austin Group Defect 1302 is applied, aligning this header with the ISO/IEC 9899:2018 standard.
Austin Group Defect 1330 is applied, removing obsolescent interfaces.
Austin Group Defect 1352 is applied, changing the APPLICATION USAGE and RATIONALE sections.
return to top of page