📄 mbrtowc.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-2004 IEEE and The Open Group, All Rights Reserved --><title>mbrtowc</title></head><body bgcolor="white"><script type="text/javascript" language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> <a name="mbrtowc"></a> <a name="tag_03_360"></a><!-- mbrtowc --> <!--header start--><center><font size="2">The Open Group Base Specifications Issue 6<br>IEEE Std 1003.1, 2004 Edition<br>Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.</font></center><!--header end--><hr size="2" noshade><h4><a name="tag_03_360_01"></a>NAME</h4><blockquote>mbrtowc - convert a character to a wide-character code (restartable)</blockquote><h4><a name="tag_03_360_02"></a>SYNOPSIS</h4><blockquote class="synopsis"><p><code><tt>#include <<a href="../basedefs/wchar.h.html">wchar.h</a>><br><br> size_t mbrtowc(wchar_t *restrict</tt> <i>pwc</i><tt>, const char *restrict</tt> <i>s</i><tt>,<br> size_t</tt> <i>n</i><tt>, mbstate_t *restrict</tt> <i>ps</i><tt>);<br></tt></code></p></blockquote><h4><a name="tag_03_360_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"> The functionality described on this reference page is aligned with the ISO C standard. Any conflict between therequirements described here and the ISO C standard is unintentional. This volume of IEEE Std 1003.1-2001 defers tothe ISO C standard. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></div><p>If <i>s</i> is a null pointer, the <i>mbrtowc</i>() function shall be equivalent to the call:</p><pre><tt>mbrtowc(NULL, "", 1, ps)</tt></pre><p>In this case, the values of the arguments <i>pwc</i> and <i>n</i> are ignored.</p><p>If <i>s</i> is not a null pointer, the <i>mbrtowc</i>() function shall inspect at most <i>n</i> bytes beginning at the bytepointed to by <i>s</i> to determine the number of bytes needed to complete the next character (including any shift sequences). Ifthe function determines that the next character is completed, it shall determine the value of the corresponding wide character andthen, if <i>pwc</i> is not a null pointer, shall store that value in the object pointed to by <i>pwc</i>. If the corresponding widecharacter is the null wide character, the resulting state described shall be the initial conversion state.</p><p>If <i>ps</i> is a null pointer, the <i>mbrtowc</i>() function shall use its own internal <b>mbstate_t</b> object, which shall beinitialized at program start-up to the initial conversion state. Otherwise, the <b>mbstate_t</b> object pointed to by <i>ps</i>shall be used to completely describe the current conversion state of the associated character sequence. The implementation shallbehave as if no function defined in this volume of IEEE Std 1003.1-2001 calls <i>mbrtowc</i>().</p><p>The behavior of this function is affected by the <i>LC_CTYPE</i> category of the current locale.</p></blockquote><h4><a name="tag_03_360_04"></a>RETURN VALUE</h4><blockquote><p>The <i>mbrtowc</i>() function shall return the first of the following that applies:</p><dl compact><dt>0</dt><dd>If the next <i>n</i> or fewer bytes complete the character that corresponds to the null wide character (which is the valuestored).</dd><dt>between 1 and <i>n</i> inclusive</dt><dd>If the next <i>n</i> or fewer bytes complete a valid character (which is the value stored); the value returned shall be the numberof bytes that complete the character.</dd><dt>(<b>size_t</b>)-2</dt><dd>If the next <i>n</i> bytes contribute to an incomplete but potentially valid character, and all <i>n</i> bytes have beenprocessed (no value is stored). When <i>n</i> has at least the value of the {MB_CUR_MAX} macro, this case can only occur if<i>s</i> points at a sequence of redundant shift sequences (for implementations with state-dependent encodings).</dd><dt>(<b>size_t</b>)-1</dt><dd>If an encoding error occurs, in which case the next <i>n</i> or fewer bytes do not contribute to a complete and valid character(no value is stored). In this case, [EILSEQ] shall be stored in <i>errno</i> and the conversion state is undefined.</dd></dl></blockquote><h4><a name="tag_03_360_05"></a>ERRORS</h4><blockquote><p>The <i>mbrtowc</i>() function may fail if:</p><dl compact><dt>[EINVAL]</dt><dd><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"><i>ps</i> points to an object that contains an invalid conversion state. <img src="../images/opt-end.gif" alt="[Option End]"border="0"></dd><dt>[EILSEQ]</dt><dd>Invalid character sequence is detected.</dd></dl></blockquote><hr><div class="box"><em>The following sections are informative.</em></div><h4><a name="tag_03_360_06"></a>EXAMPLES</h4><blockquote><p>None.</p></blockquote><h4><a name="tag_03_360_07"></a>APPLICATION USAGE</h4><blockquote><p>None.</p></blockquote><h4><a name="tag_03_360_08"></a>RATIONALE</h4><blockquote><p>None.</p></blockquote><h4><a name="tag_03_360_09"></a>FUTURE DIRECTIONS</h4><blockquote><p>None.</p></blockquote><h4><a name="tag_03_360_10"></a>SEE ALSO</h4><blockquote><p><a href="mbsinit.html"><i>mbsinit</i>()</a>, the Base Definitions volume of IEEE Std 1003.1-2001, <a href="../basedefs/wchar.h.html"><i><wchar.h></i></a></p></blockquote><h4><a name="tag_03_360_11"></a>CHANGE HISTORY</h4><blockquote><p>First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 (E).</p></blockquote><h4><a name="tag_03_360_12"></a>Issue 6</h4><blockquote><p>The <i>mbrtowc</i>() prototype is updated for alignment with the ISO/IEC 9899:1999 standard.</p><p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p><ul><li><p>The [EINVAL] error condition is added.</p></li></ul><p>ISO/IEC 9899:1999 standard, Technical Corrigendum 1 is incorporated.</p></blockquote><div class="box"><em>End of informative text.</em></div><hr size="2" noshade><center><font size="2"><!--footer start-->UNIX ® is a registered Trademark of The Open Group.<br>POSIX ® 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>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -