lostecho/oldlinux-files
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add directory study

Browse Source
This commit is contained in:
gohigh
2024-02-19 00:25:23 -05:00
parent b1306b38b1
commit f3774e2f8c
4001 changed files with 2285787 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

274
study/Ref-docs/POSIX/susv3/functions/xsh_chap02_05.html Normal file
View File

@@ -0,0 +1,274 @@
<!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&nbsp;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&nbsp;Std&nbsp;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 &lt;newline&gt; (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&nbsp;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"> &nbsp;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"> &nbsp;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 &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
</font> [ <a href="../mindex.html">Main Index</a>]</center>
<hr size="2" noshade>
</body>
</html>