275 lines
18 KiB
HTML
275 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>System Interfaces Chapter 2</title>
|
|
</head>
|
|
<body>
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3">
|
|
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001</font></center>
|
|
|
|
<hr size="2" noshade>
|
|
<h3><a name="tag_02_05"></a>Standard I/O Streams</h3>
|
|
|
|
<p>A stream is associated with an external file (which may be a physical device) by ``opening'' a file, which may involve
|
|
``creating'' a new file. Creating an existing file causes its former contents to be discarded if necessary. If a file can support
|
|
positioning requests (such as a disk file, as opposed to a terminal), then a ``file position indicator'' associated with the stream
|
|
is positioned at the start (byte number 0) of the file, unless the file is opened with append mode, in which case it is
|
|
implementation-defined whether the file position indicator is initially positioned at the beginning or end of the file. The file
|
|
position indicator is maintained by subsequent reads, writes, and positioning requests, to facilitate an orderly progression
|
|
through the file. All input takes place as if bytes were read by successive calls to <a href=
|
|
"../functions/fgetc.html"><i>fgetc</i>()</a>; all output takes place as if bytes were written by successive calls to <a href=
|
|
"../functions/fputc.html"><i>fputc</i>()</a>.</p>
|
|
|
|
<p>When a stream is ``unbuffered'', bytes are intended to appear from the source or at the destination as soon as possible;
|
|
otherwise, bytes may be accumulated and transmitted as a block. When a stream is ``fully buffered'', bytes are intended to be
|
|
transmitted as a block when a buffer is filled. When a stream is ``line buffered'', bytes are intended to be transmitted as a block
|
|
when a newline byte is encountered. Furthermore, bytes are intended to be transmitted as a block when a buffer is filled, when
|
|
input is requested on an unbuffered stream, or when input is requested on a line-buffered stream that requires the transmission of
|
|
bytes. Support for these characteristics is implementation-defined, and may be affected via <a href=
|
|
"../functions/setbuf.html"><i>setbuf</i>()</a> and <a href="../functions/setvbuf.html"><i>setvbuf</i>()</a>.</p>
|
|
|
|
<p>A file may be disassociated from a controlling stream by ``closing'' the file. Output streams are flushed (any unwritten buffer
|
|
contents are transmitted) before the stream is disassociated from the file. The value of a pointer to a <b>FILE</b> object is
|
|
unspecified after the associated file is closed (including the standard streams).</p>
|
|
|
|
<p>A file may be subsequently reopened, by the same or another program execution, and its contents reclaimed or modified (if it can
|
|
be repositioned at its start). If the <i>main</i>() function returns to its original caller, or if the <a href=
|
|
"../functions/exit.html"><i>exit</i>()</a> function is called, all open files are closed (hence all output streams are flushed)
|
|
before program termination. Other paths to program termination, such as calling <a href=
|
|
"../functions/abort.html"><i>abort</i>()</a>, need not close all files properly.</p>
|
|
|
|
<p>The address of the <b>FILE</b> object used to control a stream may be significant; a copy of a <b>FILE</b> object need not
|
|
necessarily serve in place of the original.</p>
|
|
|
|
<p>At program start-up, three streams are predefined and need not be opened explicitly: <i>standard input</i> (for reading
|
|
conventional input), <i>standard output</i> (for writing conventional output), and <i>standard error</i> (for writing diagnostic
|
|
output). When opened, the standard error stream is not fully buffered; the standard input and standard output streams are fully
|
|
buffered if and only if the stream can be determined not to refer to an interactive device.</p>
|
|
|
|
<h4><a name="tag_02_05_01"></a>Interaction of File Descriptors and Standard I/O Streams</h4>
|
|
|
|
<p><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
This section describes the interaction of file descriptors and standard I/O streams. This functionality is an extension to the
|
|
ISO C standard (and the rest of this section is not further CX shaded). <img src="../images/opt-end.gif" alt="[Option End]"
|
|
border="0"></p>
|
|
|
|
<p>An open file description may be accessed through a file descriptor, which is created using functions such as <a href=
|
|
"../functions/open.html"><i>open</i>()</a> or <a href="../functions/pipe.html"><i>pipe</i>()</a>, or through a stream, which is
|
|
created using functions such as <a href="../functions/fopen.html"><i>fopen</i>()</a> or <a href=
|
|
"../functions/popen.html"><i>popen</i>()</a>. Either a file descriptor or a stream is called a ``handle'' on the open file
|
|
description to which it refers; an open file description may have several handles.</p>
|
|
|
|
<p>Handles can be created or destroyed by explicit user action, without affecting the underlying open file description. Some of the
|
|
ways to create them include <a href="../functions/fcntl.html"><i>fcntl</i>()</a>, <a href="../functions/dup.html"><i>dup</i>()</a>,
|
|
<a href="../functions/fdopen.html"><i>fdopen</i>()</a>, <a href="../functions/fileno.html"><i>fileno</i>()</a>, and <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a>. They can be destroyed by at least <a href=
|
|
"../functions/fclose.html"><i>fclose</i>()</a>, <a href="../functions/close.html"><i>close</i>()</a>, and the <i><a href=
|
|
"../functions/exec.html">exec</a></i> functions.</p>
|
|
|
|
<p>A file descriptor that is never used in an operation that could affect the file offset (for example, <a href=
|
|
"../functions/read.html"><i>read</i>()</a>, <a href="../functions/write.html"><i>write</i>()</a>, or <a href=
|
|
"../functions/lseek.html"><i>lseek</i>()</a>) is not considered a handle for this discussion, but could give rise to one (for
|
|
example, as a consequence of <a href="../functions/fdopen.html"><i>fdopen</i>()</a>, <a href=
|
|
"../functions/dup.html"><i>dup</i>()</a>, or <a href="../functions/fork.html"><i>fork</i>()</a>). This exception does not include
|
|
the file descriptor underlying a stream, whether created with <a href="../functions/fopen.html"><i>fopen</i>()</a> or <a href=
|
|
"../functions/fdopen.html"><i>fdopen</i>()</a>, so long as it is not used directly by the application to affect the file offset.
|
|
The <a href="../functions/read.html"><i>read</i>()</a> and <a href="../functions/write.html"><i>write</i>()</a> functions
|
|
implicitly affect the file offset; <a href="../functions/lseek.html"><i>lseek</i>()</a> explicitly affects it.</p>
|
|
|
|
<p>The result of function calls involving any one handle (the ``active handle'') is defined elsewhere in this volume of
|
|
IEEE Std 1003.1-2001, but if two or more handles are used, and any one of them is a stream, the application shall ensure
|
|
that their actions are coordinated as described below. If this is not done, the result is undefined.</p>
|
|
|
|
<p>A handle which is a stream is considered to be closed when either an <a href="../functions/fclose.html"><i>fclose</i>()</a> or
|
|
<a href="../functions/freopen.html"><i>freopen</i>()</a> is executed on it (the result of <a href=
|
|
"../functions/freopen.html"><i>freopen</i>()</a> is a new stream, which cannot be a handle on the same open file description as its
|
|
previous value), or when the process owning that stream terminates with <a href="../functions/exit.html"><i>exit</i>()</a>, <a
|
|
href="../functions/abort.html"><i>abort</i>()</a>, or due to a signal. A file descriptor is closed by <a href=
|
|
"../functions/close.html"><i>close</i>()</a>, <a href="../functions/_exit.html"><i>_exit</i>()</a>, or the <i><a href=
|
|
"../functions/exec.html">exec</a></i> functions when FD_CLOEXEC is set on that file descriptor.</p>
|
|
|
|
<p>For a handle to become the active handle, the application shall ensure that the actions below are performed between the last use
|
|
of the handle (the current active handle) and the first use of the second handle (the future active handle). The second handle then
|
|
becomes the active handle. All activity by the application affecting the file offset on the first handle shall be suspended until
|
|
it again becomes the active file handle. (If a stream function has as an underlying function one that affects the file offset, the
|
|
stream function shall be considered to affect the file offset.)</p>
|
|
|
|
<p>The handles need not be in the same process for these rules to apply.</p>
|
|
|
|
<p>Note that after a <a href="../functions/fork.html"><i>fork</i>()</a>, two handles exist where one existed before. The
|
|
application shall ensure that, if both handles can ever be accessed, they are both in a state where the other could become the
|
|
active handle first. The application shall prepare for a <a href="../functions/fork.html"><i>fork</i>()</a> exactly as if it were a
|
|
change of active handle. (If the only action performed by one of the processes is one of the <i><a href=
|
|
"../functions/exec.html">exec</a></i> functions or <a href="../functions/_exit.html"><i>_exit</i>()</a> (not <a href=
|
|
"../functions/exit.html"><i>exit</i>()</a>), the handle is never accessed in that process.)</p>
|
|
|
|
<p>For the first handle, the first applicable condition below applies. After the actions required below are taken, if the handle is
|
|
still open, the application can close it.</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>If it is a file descriptor, no action is required.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the only further action to be performed on any handle to this open file descriptor is to close it, no action need be
|
|
taken.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If it is a stream which is unbuffered, no action need be taken.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If it is a stream which is line buffered, and the last byte written to the stream was a <newline> (that is, as if a:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
<tt>putc('\n')
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>was the most recent operation on that stream), no action need be taken.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If it is a stream which is open for writing or appending (but not also open for reading), the application shall either perform
|
|
an <a href="../functions/fflush.html"><i>fflush</i>()</a>, or the stream shall be closed.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the stream is open for reading and it is at the end of the file ( <a href="../functions/feof.html"><i>feof</i>()</a> is
|
|
true), no action need be taken.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the stream is open with a mode that allows reading and the underlying open file description refers to a device that is
|
|
capable of seeking, the application shall either perform an <a href="../functions/fflush.html"><i>fflush</i>()</a>, or the stream
|
|
shall be closed.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Otherwise, the result is undefined.</p>
|
|
|
|
<p>For the second handle:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>If any previous active handle has been used by a function that explicitly changed the file offset, except as required above for
|
|
the first handle, the application shall perform an <a href="../functions/lseek.html"><i>lseek</i>()</a> or <a href=
|
|
"../functions/fseek.html"><i>fseek</i>()</a> (as appropriate to the type of handle) to an appropriate location.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>If the active handle ceases to be accessible before the requirements on the first handle, above, have been met, the state of the
|
|
open file description becomes undefined. This might occur during functions such as a <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a> or <a href="../functions/_exit.html"><i>_exit</i>()</a>.</p>
|
|
|
|
<p>The <i><a href="../functions/exec.html">exec</a></i> functions make inaccessible all streams that are open at the time they are
|
|
called, independent of which streams or file descriptors may be available to the new process image.</p>
|
|
|
|
<p>When these rules are followed, regardless of the sequence of handles used, implementations shall ensure that an application,
|
|
even one consisting of several processes, shall yield correct results: no data shall be lost or duplicated when writing, and all
|
|
data shall be written in order, except as requested by seeks. It is implementation-defined whether, and under what conditions, all
|
|
input is seen exactly once.</p>
|
|
|
|
<p>If the rules above are not followed, the result is unspecified.</p>
|
|
|
|
<p>Each function that operates on a stream is said to have zero or more ``underlying functions''. This means that the stream
|
|
function shares certain traits with the underlying functions, but does not require that there be any relation between the
|
|
implementations of the stream function and its underlying functions.</p>
|
|
|
|
<h4><a name="tag_02_05_02"></a>Stream Orientation and Encoding Rules</h4>
|
|
|
|
<p>For conformance to the ISO/IEC 9899:1999 standard, the definition of a stream includes an ``orientation''. After a stream
|
|
is associated with an external file, but before any operations are performed on it, the stream is without orientation. Once a
|
|
wide-character input/output function has been applied to a stream without orientation, the stream shall become ``wide-oriented''.
|
|
Similarly, once a byte input/output function has been applied to a stream without orientation, the stream shall become
|
|
``byte-oriented''. Only a call to the <a href="../functions/freopen.html"><i>freopen</i>()</a> function or the <a href=
|
|
"../functions/fwide.html"><i>fwide</i>()</a> function can otherwise alter the orientation of a stream.</p>
|
|
|
|
<p>A successful call to <a href="../functions/freopen.html"><i>freopen</i>()</a> shall remove any orientation. The three predefined
|
|
streams <i>standard input</i>, <i>standard output</i>, and <i>standard error</i> shall be unoriented at program start-up.</p>
|
|
|
|
<p>Byte input/output functions cannot be applied to a wide-oriented stream, and wide-character input/output functions cannot be
|
|
applied to a byte-oriented stream. The remaining stream operations shall not affect and shall not be affected by a stream's
|
|
orientation, except for the following additional restriction:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>For wide-oriented streams, after a successful call to a file-positioning function that leaves the file position indicator prior
|
|
to the end-of-file, a wide-character output function can overwrite a partial character; any file contents beyond the byte(s)
|
|
written are henceforth undefined.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Each wide-oriented stream has an associated <b>mbstate_t</b> object that stores the current parse state of the stream. A
|
|
successful call to <a href="../functions/fgetpos.html"><i>fgetpos</i>()</a> shall store a representation of the value of this
|
|
<b>mbstate_t</b> object as part of the value of the <b>fpos_t</b> object. A later successful call to <a href=
|
|
"../functions/fsetpos.html"><i>fsetpos</i>()</a> using the same stored <b>fpos_t</b> value shall restore the value of the
|
|
associated <b>mbstate_t</b> object as well as the position within the controlled stream.</p>
|
|
|
|
<p>Implementations that support multiple encoding rules associate an encoding rule with the stream. The encoding rule shall be
|
|
determined by the setting of the <i>LC_CTYPE</i> category in the current locale at the time when the stream becomes wide-oriented.
|
|
As with the stream's orientation, the encoding rule associated with a stream cannot be changed once it has been set, except by a
|
|
successful call to <a href="../functions/freopen.html"><i>freopen</i>()</a> which clears the encoding rule and resets the
|
|
orientation to unoriented.</p>
|
|
|
|
<p>Although wide-oriented streams are conceptually sequences of wide characters, the external file associated with a wide-oriented
|
|
stream is a sequence of (possibly multi-byte) characters generalized as follows:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Multi-byte encodings within files may contain embedded null bytes (unlike multi-byte encodings valid for use internal to the
|
|
program).</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A file need not begin nor end in the initial shift state.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Moreover, the encodings used for characters may differ among files. Both the nature and choice of such encodings are
|
|
implementation-defined.</p>
|
|
|
|
<p>The wide-character input functions read characters from the stream and convert them to wide characters as if they were read by
|
|
successive calls to the <a href="../functions/fgetwc.html"><i>fgetwc</i>()</a> function. Each conversion shall occur as if by a
|
|
call to the <a href="../functions/mbrtowc.html"><i>mbrtowc</i>()</a> function, with the conversion state described by the stream's
|
|
own <b>mbstate_t</b> object, <sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> except the encoding rule associated with the stream is used instead of the encoding rule implied
|
|
by the <i>LC_CTYPE</i> category of the current locale. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
|
|
<p>The wide-character output functions convert wide characters to (possibly multi-byte) characters and write them to the stream as
|
|
if they were written by successive calls to the <a href="../functions/fputwc.html"><i>fputwc</i>()</a> function. Each conversion
|
|
shall occur as if by a call to the <a href="../functions/wcrtomb.html"><i>wcrtomb</i>()</a> function, with the conversion state
|
|
described by the stream's own <b>mbstate_t</b> object, <sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src=
|
|
"../images/opt-start.gif" alt="[Option Start]" border="0"> except the encoding rule associated with the stream is used
|
|
instead of the encoding rule implied by the <i>LC_CTYPE</i> category of the current locale. <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></p>
|
|
|
|
<p>An ``encoding error'' shall occur if the character sequence presented to the underlying <a href=
|
|
"../functions/mbrtowc.html"><i>mbrtowc</i>()</a> function does not form a valid (generalized) character, or if the code value
|
|
passed to the underlying <a href="../functions/wcrtomb.html"><i>wcrtomb</i>()</a> function does not correspond to a valid
|
|
(generalized) character. The wide-character input/output functions and the byte input/output functions store the value of the macro
|
|
[EILSEQ] in <i>errno</i> if and only if an encoding error occurs.</p>
|
|
|
|
<hr size="2" noshade>
|
|
<center><font size="2">UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
</font> [ <a href="../mindex.html">Main Index</a>]</center>
|
|
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|