📄 putchar_unlocked.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-2003 The Open Group, All Rights Reserved --><title>getc_unlocked</title></head><body bgcolor="white"><script type="text/javascript" language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> <a name="getc_unlocked"></a> <a name="tag_03_211"></a><!-- getc_unlocked --> <!--header start--><center><font size="2">The Open Group Base Specifications Issue 6<br>IEEE Std 1003.1, 2003 Edition<br>Copyright © 2001-2003 The IEEE and The Open Group, All Rights reserved.</font></center><!--header end--><hr size="2" noshade><h4><a name="tag_03_211_01"></a>NAME</h4><blockquote>getc_unlocked, getchar_unlocked, putc_unlocked, putchar_unlocked - stdio with explicit client locking</blockquote><h4><a name="tag_03_211_02"></a>SYNOPSIS</h4><blockquote class="synopsis"><div class="box"><code><tt><sup>[<a href="javascript:open_code('TSF')">TSF</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> #include <<a href="../basedefs/stdio.h.html">stdio.h</a>><br><br> int getc_unlocked(FILE *</tt><i>stream</i><tt>);<br> int getchar_unlocked(void);<br> int putc_unlocked(int</tt> <i>c</i><tt>, FILE *</tt><i>stream</i><tt>);<br> int putchar_unlocked(int</tt> <i>c</i><tt>); <img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div><tt><br></tt></blockquote><h4><a name="tag_03_211_03"></a>DESCRIPTION</h4><blockquote><p>Versions of the functions <a href="../functions/getc.html"><i>getc</i>()</a>, <a href="../functions/getchar.html"><i>getchar</i>()</a>, <a href="../functions/putc.html"><i>putc</i>()</a>, and <a href="../functions/putchar.html"><i>putchar</i>()</a> respectively named <i>getc_unlocked</i>(), <i>getchar_unlocked</i>(),<i>putc_unlocked</i>(), and <i>putchar_unlocked</i>() shall be provided which are functionally equivalent to the original versions,with the exception that they are not required to be implemented in a thread-safe manner. They may only safely be used within ascope protected by <a href="../functions/flockfile.html"><i>flockfile</i>()</a> (or <a href="../functions/ftrylockfile.html"><i>ftrylockfile</i>()</a>) and <a href="../functions/funlockfile.html"><i>funlockfile</i>()</a>.These functions may safely be used in a multi-threaded program if and only if they are called while the invoking thread owns the (<b>FILE *</b>) object, as is the case after a successful call to the <a href="../functions/flockfile.html"><i>flockfile</i>()</a>or <a href="../functions/ftrylockfile.html"><i>ftrylockfile</i>()</a> functions.</p></blockquote><h4><a name="tag_03_211_04"></a>RETURN VALUE</h4><blockquote><p>See <a href="getc.html"><i>getc</i>()</a> , <a href="getchar.html"><i>getchar</i>()</a> , <a href="putc.html"><i>putc</i>()</a>, and <a href="putchar.html"><i>putchar</i>()</a> .</p></blockquote><h4><a name="tag_03_211_05"></a>ERRORS</h4><blockquote><p>See <a href="getc.html"><i>getc</i>()</a> , <a href="getchar.html"><i>getchar</i>()</a> , <a href="putc.html"><i>putc</i>()</a>, and <a href="putchar.html"><i>putchar</i>()</a> .</p></blockquote><hr><div class="box"><em>The following sections are informative.</em></div><h4><a name="tag_03_211_06"></a>EXAMPLES</h4><blockquote><p>None.</p></blockquote><h4><a name="tag_03_211_07"></a>APPLICATION USAGE</h4><blockquote><p>Since they may be implemented as macros, <i>getc_unlocked</i>() and <i>putc_unlocked</i>() may treat incorrectly a <i>stream</i>argument with side effects. In particular, <i>getc_unlocked</i>(*f++) and <i>putc_unlocked</i>(*f++) do not necessarily work asexpected. Therefore, use of these functions in such situations should be preceded by the following statement as appropriate:</p><pre><tt>#undef getc_unlocked#undef putc_unlocked</tt></pre></blockquote><h4><a name="tag_03_211_08"></a>RATIONALE</h4><blockquote><p>Some I/O functions are typically implemented as macros for performance reasons (for example, <a href="../functions/putc.html"><i>putc</i>()</a> and <a href="../functions/getc.html"><i>getc</i>()</a>). For safety, they need to besynchronized, but it is often too expensive to synchronize on every character. Nevertheless, it was felt that the safety concernswere more important; consequently, the <a href="../functions/getc.html"><i>getc</i>()</a>, <a href="../functions/getchar.html"><i>getchar</i>()</a>, <a href="../functions/putc.html"><i>putc</i>()</a>, and <a href="../functions/putchar.html"><i>putchar</i>()</a> functions are required to be thread-safe. However, unlocked versions are alsoprovided with names that clearly indicate the unsafe nature of their operation but can be used to exploit their higher performance.These unlocked versions can be safely used only within explicitly locked program regions, using exported locking primitives. Inparticular, a sequence such as:</p><pre><tt>flockfile(fileptr);putc_unlocked('1', fileptr);putc_unlocked('\n', fileptr);fprintf(fileptr, "Line 2\n");funlockfile(fileptr);</tt></pre><p>is permissible, and results in the text sequence:</p><pre><tt>1Line 2</tt></pre><p>being printed without being interspersed with output from other threads.</p><p>It would be wrong to have the standard names such as <a href="../functions/getc.html"><i>getc</i>()</a>, <a href="../functions/putc.html"><i>putc</i>()</a>, and so on, map to the "faster, but unsafe" rather than the "slower, but safe''versions. In either case, you would still want to inspect all uses of <a href="../functions/getc.html"><i>getc</i>()</a>, <a href="../functions/putc.html"><i>putc</i>()</a>, and so on, by hand when converting existing code. Choosing the safe bindings as thedefault, at least, results in correct code and maintains the "atomicity at the function" invariant. To do otherwise wouldintroduce gratuitous synchronization errors into converted code. Other routines that modify the <i>stdio</i> ( <b>FILE *</b>)structures or buffers are also safely synchronized.</p><p>Note that there is no need for functions of the form <i>getc_locked</i>(), <i>putc_locked</i>(), and so on, since this is thefunctionality of <a href="../functions/getc.html"><i>getc</i>()</a>, <a href="../functions/putc.html"><i>putc</i>()</a>, <i>etal</i>. It would be inappropriate to use a feature test macro to switch a macro definition of <a href="../functions/getc.html"><i>getc</i>()</a> between <i>getc_locked</i>() and <i>getc_unlocked</i>(), since the ISO C standardrequires an actual function to exist, a function whose behavior could not be changed by the feature test macro. Also, providingboth the <i>xxx_locked</i>() and <i>xxx_unlocked</i>() forms leads to the confusion of whether the suffix describes the behavior ofthe function or the circumstances under which it should be used.</p><p>Three additional routines, <a href="../functions/flockfile.html"><i>flockfile</i>()</a>, <a href="../functions/ftrylockfile.html"><i>ftrylockfile</i>()</a>, and <a href="../functions/funlockfile.html"><i>funlockfile</i>()</a>(which may be macros), are provided to allow the user to delineate a sequence of I/O statements that are executedsynchronously.</p><p>The <a href="../functions/ungetc.html"><i>ungetc</i>()</a> function is infrequently called relative to the otherfunctions/macros so no unlocked variation is needed.</p></blockquote><h4><a name="tag_03_211_09"></a>FUTURE DIRECTIONS</h4><blockquote><p>None.</p></blockquote><h4><a name="tag_03_211_10"></a>SEE ALSO</h4><blockquote><p><a href="getc.html"><i>getc</i>()</a> , <a href="getchar.html"><i>getchar</i>()</a> , <a href="putc.html"><i>putc</i>()</a> , <ahref="putchar.html"><i>putchar</i>()</a> , the Base Definitions volume of IEEE Std 1003.1-2001, <a href="../basedefs/stdio.h.html"><i><stdio.h></i></a></p></blockquote><h4><a name="tag_03_211_11"></a>CHANGE HISTORY</h4><blockquote><p>First released in Issue 5. Included for alignment with the POSIX Threads Extension.</p></blockquote><h4><a name="tag_03_211_12"></a>Issue 6</h4><blockquote><p>These functions are marked as part of the Thread-Safe Functions option.</p><p>The Open Group Corrigendum U030/2 is applied, adding APPLICATION USAGE describing how applications should be written to avoidthe case when the functions are implemented as macros.</p></blockquote><div class="box"><em>End of informative text.</em></div><hr><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 + -