Files
oldlinux-files/Ref-docs/POSIX/susv3/basedefs/wchar.h.html
2024-02-19 00:21:47 -05:00

349 lines
18 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta name="generator" content="HTML Tidy, see www.w3.org">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
<title>&lt;wchar.h&gt;</title>
</head>
<body bgcolor="white">
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
</script>
<basefont size="3"> <a name="&lt;wchar.h&gt;"></a> <a name="tag_13_83"></a><!-- &lt;wchar.h&gt; -->
<!--header start-->
<center><font size="2">The Open Group Base Specifications Issue 6<br>
IEEE Std 1003.1-2001<br>
Copyright &copy; 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
<!--header end-->
<hr size="2" noshade>
<h4><a name="tag_13_83_01"></a>NAME</h4>
<blockquote>wchar.h - wide-character handling</blockquote>
<h4><a name="tag_13_83_02"></a>SYNOPSIS</h4>
<blockquote class="synopsis">
<p><tt>#include &lt;wchar.h&gt;</tt></p>
</blockquote>
<h4><a name="tag_13_83_03"></a>DESCRIPTION</h4>
<blockquote>
<div class="box"><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]"
border="0"> Some of the functionality described on this reference page extends the ISO&nbsp;C standard. Applications shall define
the appropriate feature test macro (see the System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../functions/xsh_chap02_02.html">Section 2.2, The Compilation Environment</a>) to enable the visibility of these symbols in this
header. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></div>
<p>The <i>&lt;wchar.h&gt;</i> header shall define the following types:</p>
<dl compact>
<dt><b>wchar_t</b></dt>
<dd>As described in <a href="stddef.h.html"><i>&lt;stddef.h&gt;</i></a> .</dd>
<dt><b>wint_t</b></dt>
<dd>An integer type capable of storing any valid value of <b>wchar_t</b> or WEOF.</dd>
<dt><b>wctype_t</b></dt>
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
A scalar type of a data object that can hold values which represent locale-specific character classification. <img src=
"../images/opt-end.gif" alt="[Option End]" border="0"></dd>
<dt><b>mbstate_t</b></dt>
<dd>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. <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src=
"../images/opt-start.gif" alt="[Option Start]" border="0"> &nbsp;If a codeset is being used such that an <b>mbstate_t</b> needs to
preserve more than 2 levels of reserved state, the results are unspecified. <img src="../images/opt-end.gif" alt="[Option End]"
border="0"></dd>
<dt><b>FILE</b></dt>
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
As described in <a href="stdio.h.html"><i>&lt;stdio.h&gt;</i></a> . <img src="../images/opt-end.gif" alt="[Option End]" border=
"0"></dd>
<dt><b>size_t</b></dt>
<dd>As described in <a href="stddef.h.html"><i>&lt;stddef.h&gt;</i></a> .</dd>
<dt><b>va_list</b></dt>
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
As described in <a href="stdarg.h.html"><i>&lt;stdarg.h&gt;</i></a> . <img src="../images/opt-end.gif" alt="[Option End]" border=
"0"></dd>
</dl>
<p>The implementation shall support one or more programming environments in which the width of <b>wint_t</b> is no greater than the
width of type <b>long</b>. The names of these programming environments can be obtained using the <a href=
"../functions/confstr.html"><i>confstr</i>()</a> function or the <a href="../utilities/getconf.html"><i>getconf</i></a>
utility.</p>
<p>The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided.</p>
<pre>
<tt>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);
<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
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);
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
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 *);
size_t mbsrtowcs(wchar_t *restrict, const char **restrict, size_t,
mbstate_t *restrict);
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, ...);
<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
wint_t towlower(wint_t);
wint_t towupper(wint_t);
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
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 vwprintf(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 vwscanf(const wchar_t *restrict, va_list);
size_t wcrtomb(char *restrict, wchar_t, mbstate_t *restrict);
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 *);
wchar_t *wcscpy(wchar_t *restrict, const wchar_t *restrict);
size_t wcscspn(const wchar_t *, 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 *);
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);
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);
<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
wchar_t *wcswcs(const wchar_t *, const wchar_t *);
int wcswidth(const wchar_t *, size_t);
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
size_t wcsxfrm(wchar_t *restrict, const wchar_t *restrict, size_t);
int wctob(wint_t);
<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0">
wctype_t wctype(const char *);
int wcwidth(wchar_t);
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
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, ...);
</tt>
</pre>
<p>The <i>&lt;wchar.h&gt;</i> header shall define the following macros:</p>
<dl compact>
<dt>WCHAR_MAX</dt>
<dd>The maximum value representable by an object of type <b>wchar_t</b>.</dd>
<dt>WCHAR_MIN</dt>
<dd>The minimum value representable by an object of type <b>wchar_t</b>.</dd>
<dt>WEOF</dt>
<dd>Constant expression of type <b>wint_t</b> that is returned by several WP functions to indicate end-of-file.</dd>
<dt>NULL</dt>
<dd>As described in <a href="stddef.h.html"><i>&lt;stddef.h&gt;</i></a> .</dd>
</dl>
<p>The tag <b>tm</b> shall be declared as naming an incomplete structure type, the contents of which are described in the header <a
href="time.h.html"><i>&lt;time.h&gt;</i></a> .</p>
<p><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
Inclusion of the <i>&lt;wchar.h&gt;</i> header may make visible all symbols from the headers <a href=
"../basedefs/ctype.h.html"><i>&lt;ctype.h&gt;</i></a>, <a href="../basedefs/string.h.html"><i>&lt;string.h&gt;</i></a>, <a href=
"../basedefs/stdarg.h.html"><i>&lt;stdarg.h&gt;</i></a>, <a href="../basedefs/stddef.h.html"><i>&lt;stddef.h&gt;</i></a>, <a href=
"../basedefs/stdio.h.html"><i>&lt;stdio.h&gt;</i></a>, <a href="../basedefs/stdlib.h.html"><i>&lt;stdlib.h&gt;</i></a>, and <a
href="../basedefs/time.h.html"><i>&lt;time.h&gt;</i></a>. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
</blockquote>
<hr>
<div class="box"><em>The following sections are informative.</em></div>
<h4><a name="tag_13_83_04"></a>APPLICATION USAGE</h4>
<blockquote>
<p>None.</p>
</blockquote>
<h4><a name="tag_13_83_05"></a>RATIONALE</h4>
<blockquote>
<p>In the ISO&nbsp;C standard, the symbols referenced as XSI extensions are in <a href=
"../basedefs/wctype.h.html"><i>&lt;wctype.h&gt;</i></a>. Their presence here is thus an extension.</p>
</blockquote>
<h4><a name="tag_13_83_06"></a>FUTURE DIRECTIONS</h4>
<blockquote>
<p>None.</p>
</blockquote>
<h4><a name="tag_13_83_07"></a>SEE ALSO</h4>
<blockquote>
<p><a href="ctype.h.html"><i>&lt;ctype.h&gt;</i></a> , <a href="stdarg.h.html"><i>&lt;stdarg.h&gt;</i></a> , <a href=
"stddef.h.html"><i>&lt;stddef.h&gt;</i></a> , <a href="stdio.h.html"><i>&lt;stdio.h&gt;</i></a> , <a href=
"stdlib.h.html"><i>&lt;stdlib.h&gt;</i></a> , <a href="string.h.html"><i>&lt;string.h&gt;</i></a> , <a href=
"time.h.html"><i>&lt;time.h&gt;</i></a> , <a href="wctype.h.html"><i>&lt;wctype.h&gt;</i></a> , the System Interfaces volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../functions/btowc.html"><i>btowc</i>()</a>, <a href=
"../functions/confstr.html"><i>confstr</i>()</a>, <a href="../functions/fgetwc.html"><i>fgetwc</i>()</a>, <a href=
"../functions/fgetws.html"><i>fgetws</i>()</a>, <a href="../functions/fputwc.html"><i>fputwc</i>()</a>, <a href=
"../functions/fputws.html"><i>fputws</i>()</a>, <a href="../functions/fwide.html"><i>fwide</i>()</a>, <a href=
"../functions/fwprintf.html"><i>fwprintf</i>()</a>, <a href="../functions/fwscanf.html"><i>fwscanf</i>()</a>, <a href=
"../functions/getwc.html"><i>getwc</i>()</a>, <a href="../functions/getwchar.html"><i>getwchar</i>()</a>, <a href=
"../functions/iswalnum.html"><i>iswalnum</i>()</a>, <a href="../functions/iswalpha.html"><i>iswalpha</i>()</a>, <a href=
"../functions/iswcntrl.html"><i>iswcntrl</i>()</a>, <a href="../functions/iswctype.html"><i>iswctype</i>()</a>, <a href=
"../functions/iswdigit.html"><i>iswdigit</i>()</a>, <a href="../functions/iswgraph.html"><i>iswgraph</i>()</a>, <a href=
"../functions/iswlower.html"><i>iswlower</i>()</a>, <a href="../functions/iswprint.html"><i>iswprint</i>()</a>, <a href=
"../functions/iswpunct.html"><i>iswpunct</i>()</a>, <a href="../functions/iswspace.html"><i>iswspace</i>()</a>, <a href=
"../functions/iswupper.html"><i>iswupper</i>()</a>, <a href="../functions/iswxdigit.html"><i>iswxdigit</i>()</a>, <a href=
"../functions/iswctype.html"><i>iswctype</i>()</a>, <a href="../functions/mbsinit.html"><i>mbsinit</i>()</a>, <a href=
"../functions/mbrlen.html"><i>mbrlen</i>()</a>, <a href="../functions/mbrtowc.html"><i>mbrtowc</i>()</a>, <a href=
"../functions/mbsrtowcs.html"><i>mbsrtowcs</i>()</a>, <a href="../functions/putwc.html"><i>putwc</i>()</a>, <a href=
"../functions/putwchar.html"><i>putwchar</i>()</a>, <a href="../functions/swprintf.html"><i>swprintf</i>()</a>, <a href=
"../functions/swscanf.html"><i>swscanf</i>()</a>, <a href="../functions/towlower.html"><i>towlower</i>()</a>, <a href=
"../functions/towupper.html"><i>towupper</i>()</a>, <a href="../functions/ungetwc.html"><i>ungetwc</i>()</a>, <a href=
"../functions/vfwprintf.html"><i>vfwprintf</i>()</a>, <a href="../functions/vfwscanf.html"><i>vfwscanf</i>()</a>, <a href=
"../functions/vswprintf.html"><i>vswprintf</i>()</a>, <a href="../functions/vswscanf.html"><i>vswscanf</i>()</a>, <a href=
"../functions/vwscanf.html"><i>vwscanf</i>()</a>, <a href="../functions/wcrtomb.html"><i>wcrtomb</i>()</a>, <a href=
"../functions/wcsrtombs.html"><i>wcsrtombs</i>()</a>, <a href="../functions/wcscat.html"><i>wcscat</i>()</a>, <a href=
"../functions/wcschr.html"><i>wcschr</i>()</a>, <a href="../functions/wcscmp.html"><i>wcscmp</i>()</a>, <a href=
"../functions/wcscoll.html"><i>wcscoll</i>()</a>, <a href="../functions/wcscpy.html"><i>wcscpy</i>()</a>, <a href=
"../functions/wcscspn.html"><i>wcscspn</i>()</a>, <a href="../functions/wcsftime.html"><i>wcsftime</i>()</a>, <a href=
"../functions/wcslen.html"><i>wcslen</i>()</a>, <a href="../functions/wcsncat.html"><i>wcsncat</i>()</a>, <a href=
"../functions/wcsncmp.html"><i>wcsncmp</i>()</a>, <a href="../functions/wcsncpy.html"><i>wcsncpy</i>()</a>, <a href=
"../functions/wcspbrk.html"><i>wcspbrk</i>()</a>, <a href="../functions/wcsrchr.html"><i>wcsrchr</i>()</a>, <a href=
"../functions/wcsspn.html"><i>wcsspn</i>()</a>, <a href="../functions/wcsstr.html"><i>wcsstr</i>()</a>, <a href=
"../functions/wcstod.html"><i>wcstod</i>()</a>, <a href="../functions/wcstof.html"><i>wcstof</i>()</a>, <a href=
"../functions/wcstok.html"><i>wcstok</i>()</a>, <a href="../functions/wcstol.html"><i>wcstol</i>()</a>, <a href=
"../functions/wcstold.html"><i>wcstold</i>()</a>, <a href="../functions/wcstoll.html"><i>wcstoll</i>()</a>, <a href=
"../functions/wcstoul.html"><i>wcstoul</i>()</a>, <a href="../functions/wcstoull.html"><i>wcstoull</i>()</a>, <a href=
"../functions/wcswcs.html"><i>wcswcs</i>()</a>, <a href="../functions/wcswidth.html"><i>wcswidth</i>()</a>, <a href=
"../functions/wcsxfrm.html"><i>wcsxfrm</i>()</a>, <a href="../functions/wctob.html"><i>wctob</i>()</a>, <a href=
"../functions/wctype.html"><i>wctype</i>()</a>, <a href="../functions/wcwidth.html"><i>wcwidth</i>()</a>, <a href=
"../functions/wmemchr.html"><i>wmemchr</i>()</a>, <a href="../functions/wmemcmp.html"><i>wmemcmp</i>()</a>, <a href=
"../functions/wmemcpy.html"><i>wmemcpy</i>()</a>, <a href="../functions/wmemmove.html"><i>wmemmove</i>()</a>, <a href=
"../functions/wmemset.html"><i>wmemset</i>()</a>, <a href="../functions/wprintf.html"><i>wprintf</i>()</a>, <a href=
"../functions/wscanf.html"><i>wscanf</i>()</a>, the Shell and Utilities volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../utilities/getconf.html"><i>getconf</i></a></p>
</blockquote>
<h4><a name="tag_13_83_08"></a>CHANGE HISTORY</h4>
<blockquote>
<p>First released in Issue 4.</p>
</blockquote>
<h4><a name="tag_13_83_09"></a>Issue 5</h4>
<blockquote>
<p>Aligned with the ISO/IEC&nbsp;9899:1990/Amendment 1:1995 (E).</p>
</blockquote>
<h4><a name="tag_13_83_10"></a>Issue 6</h4>
<blockquote>
<p>The Open Group Corrigendum U021/10 is applied. The prototypes for <a href="../functions/wcswidth.html"><i>wcswidth</i>()</a> and
<a href="../functions/wcwidth.html"><i>wcwidth</i>()</a> are marked as extensions.</p>
<p>The Open Group Corrigendum U028/5 is applied, correcting the prototype for the <a href=
"../functions/mbsinit.html"><i>mbsinit</i>()</a> function.</p>
<p>The following changes are made for alignment with the ISO/IEC&nbsp;9899:1999 standard:</p>
<ul>
<li>
<p>Various function prototypes are updated to add the <b>restrict</b> keyword.</p>
</li>
<li>
<p>The functions <a href="../functions/vfwscanf.html"><i>vfwscanf</i>()</a>, <a href=
"../functions/vswscanf.html"><i>vswscanf</i>()</a>, <a href="../functions/wcstof.html"><i>wcstof</i>()</a>, <a href=
"../functions/wcstold.html"><i>wcstold</i>()</a>, <a href="../functions/wcstoll.html"><i>wcstoll</i>()</a>, and <a href=
"../functions/wcstoull.html"><i>wcstoull</i>()</a> are added.</p>
</li>
</ul>
<p>The type <b>wctype_t</b>, the <i>isw*</i>(),
<i>to*</i>(), and <a href="../functions/wctype.html"><i>wctype</i>()</a> functions are marked as XSI
extensions.</p>
</blockquote>
<div class="box"><em>End of informative text.</em></div>
<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>
<!--footer end-->
<hr size="2" noshade>
</body>
</html>