library_12.html

Linux程序员的工作手册

<P>
<STRONG>Compatibility Note:</STRONG> Most versions of BSD Unix use a different
error code for this: <CODE>EWOULDBLOCK</CODE>.  In the GNU library,
<CODE>EWOULDBLOCK</CODE> is an alias for <CODE>EAGAIN</CODE>, so it doesn't matter
which name you use.
<P>
On some systems, reading a large amount of data from a character special
file can also fail with <CODE>EAGAIN</CODE> if the kernel cannot find enough
physical memory to lock down the user's pages.  This is limited to
devices that transfer with direct memory access into the user's memory,
which means it does not include terminals, since they always use
separate buffers inside the kernel.
<P>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>EINTR</CODE>
<DD><CODE>read</CODE> was interrupted by a signal while it was waiting for input.
See section <A HREF="library_21.html#SEC362" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<DT><CODE>EIO</CODE>
<DD>For many devices, and for disk files, this error code indicates
a hardware error.
<P>
<CODE>EIO</CODE> also occurs when a background process tries to read from the
controlling terminal, and the normal action of stopping the process by
sending it a <CODE>SIGTTIN</CODE> signal isn't working.  This might happen if
signal is being blocked or ignored, or because the process group is
orphaned.  See section <A HREF="library_24.html#SEC411" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_24.html#SEC411">Job Control</A>, for more information about job control,
and section <A HREF="library_21.html#SEC330" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC330">Signal Handling</A>, for information about signals.
</DL>
<P>
The <CODE>read</CODE> function is the underlying primitive for all of the
functions that read from streams, such as <CODE>fgetc</CODE>.
<P>
<A NAME="IDX642"></A>
<P>
<A NAME="IDX643"></A>
<U>Function:</U> ssize_t <B>write</B> <I>(int <VAR>filedes</VAR>, const void *<VAR>buffer</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>write</CODE> function writes up to <VAR>size</VAR> bytes from
<VAR>buffer</VAR> to the file with descriptor <VAR>filedes</VAR>.  The data in
<VAR>buffer</VAR> is not necessarily a character string and a null character
output like any other character.
<P>
The return value is the number of bytes actually written.  This is
normally the same as <VAR>size</VAR>, but might be less (for example, if the
physical media being written to fills up).
<P>
In the case of an error, <CODE>write</CODE> returns <CODE>-1</CODE>.  The following
<CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EAGAIN</CODE>
<DD>Normally, <CODE>write</CODE> blocks until the write operation is complete.
But if the <CODE>O_NONBLOCK</CODE> flag is set for the file (see section <A HREF="library_12.html#SEC181" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC181">Control Operations on Files</A>), it returns immediately without writing any data, and
reports this error.  An example of a situation that might cause the
process to block on output is writing to a terminal device that supports
flow control, where output has been suspended by receipt of a STOP
character.
<P>
<STRONG>Compatibility Note:</STRONG> Most versions of BSD Unix use a different
error code for this: <CODE>EWOULDBLOCK</CODE>.  In the GNU library,
<CODE>EWOULDBLOCK</CODE> is an alias for <CODE>EAGAIN</CODE>, so it doesn't matter
which name you use.
<P>
On some systems, writing a large amount of data from a character special
file can also fail with <CODE>EAGAIN</CODE> if the kernel cannot find enough
physical memory to lock down the user's pages.  This is limited to
devices that transfer with direct memory access into the user's memory,
which means it does not include terminals, since they always use
separate buffers inside the kernel.
<P>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>EFBIG</CODE>
<DD>The size of the file is larger than the implementation can support.
<P>
<DT><CODE>EINTR</CODE>
<DD>The <CODE>write</CODE> operation was interrupted by a signal while it was
blocked waiting for completion.  See section <A HREF="library_21.html#SEC362" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<DT><CODE>EIO</CODE>
<DD>For many devices, and for disk files, this error code indicates
a hardware error.
<P>
<CODE>EIO</CODE> also occurs when a background process tries to write to the
controlling terminal, and the normal action of stopping the process by
sending it a <CODE>SIGTTOU</CODE> signal isn't working.  This might happen if
the signal is being blocked or ignored.  See section <A HREF="library_24.html#SEC411" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_24.html#SEC411">Job Control</A>, for more
information about job control, and section <A HREF="library_21.html#SEC330" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC330">Signal Handling</A>, for
information about signals.
<P>
<DT><CODE>ENOSPC</CODE>
<DD>The device is full.
<P>
<DT><CODE>EPIPE</CODE>
<DD>This error is returned when you try to write to a pipe or FIFO that
isn't open for reading by any process.  When this happens, a <CODE>SIGPIPE</CODE>
signal is also sent to the process; see section <A HREF="library_21.html#SEC330" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC330">Signal Handling</A>.
</DL>
<P>
Unless you have arranged to prevent <CODE>EINTR</CODE> failures, you should
check <CODE>errno</CODE> after each failing call to <CODE>write</CODE>, and if the
error was <CODE>EINTR</CODE>, you should simply repeat the call.
See section <A HREF="library_21.html#SEC362" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC362">Primitives Interrupted by Signals</A>.  The easy way to do this is with the
macro <CODE>TEMP_FAILURE_RETRY</CODE>, as follows:
<P>
<PRE>
nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
</PRE>
<P>
The <CODE>write</CODE> function is the underlying primitive for all of the
functions that write to streams, such as <CODE>fputc</CODE>.
<P>
<H2><A NAME="SEC174" HREF="library_toc.html#SEC174" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC174">Setting the File Position of a Descriptor</A></H2>
<P>
Just as you can set the file position of a stream with <CODE>fseek</CODE>, you
can set the file position of a descriptor with <CODE>lseek</CODE>.  This
specifies the position in the file for the next <CODE>read</CODE> or
<CODE>write</CODE> operation.  See section <A HREF="library_11.html#SEC158" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html#SEC158">File Positioning</A>, for more information
on the file position and what it means.
<P>
To read the current file position value from a descriptor, use
<CODE>lseek (<VAR>desc</VAR>, 0, SEEK_CUR)</CODE>.
<A NAME="IDX644"></A>
<A NAME="IDX645"></A>
<A NAME="IDX646"></A>
<P>
<A NAME="IDX647"></A>
<U>Function:</U> off_t <B>lseek</B> <I>(int <VAR>filedes</VAR>, off_t <VAR>offset</VAR>, int <VAR>whence</VAR>)</I><P>
The <CODE>lseek</CODE> function is used to change the file position of the
file with descriptor <VAR>filedes</VAR>.
<P>
The <VAR>whence</VAR> argument specifies how the <VAR>offset</VAR> should be
interpreted in the same way as for the <CODE>fseek</CODE> function, and can be
one of the symbolic constants <CODE>SEEK_SET</CODE>, <CODE>SEEK_CUR</CODE>, or
<CODE>SEEK_END</CODE>.
<P>
<DL COMPACT>
<DT><CODE>SEEK_SET</CODE>
<DD>Specifies that <VAR>whence</VAR> is a count of characters from the beginning
of the file.
<P>
<DT><CODE>SEEK_CUR</CODE>
<DD>Specifies that <VAR>whence</VAR> is a count of characters from the current
file position.  This count may be positive or negative.
<P>
<DT><CODE>SEEK_END</CODE>
<DD>Specifies that <VAR>whence</VAR> is a count of characters from the end of
the file.  A negative count specifies a position within the current
extent of the file; a positive count specifies a position past the
current end.  If you set the position past the current end, and 
actually write data, you will extend the file with zeros up to that
position.
</DL>
<P>
The return value from <CODE>lseek</CODE> is normally the resulting file
position, measured in bytes from the beginning of the file.
You can use this feature together with <CODE>SEEK_CUR</CODE> to read the
current file position.
<P>
You can set the file position past the current end of the file.  This
does not by itself make the file longer; <CODE>lseek</CODE> never changes the
file.  But subsequent output at that position will extend the file's
size.
<P>
If the file position cannot be changed, or the operation is in some way
invalid, <CODE>lseek</CODE> returns a value of <CODE>-1</CODE>.  The following
<CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> is not a valid file descriptor.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>whence</VAR> argument value is not valid, or the resulting
file offset is not valid.
<P>
<DT><CODE>ESPIPE</CODE>
<DD>The <VAR>filedes</VAR> corresponds to a pipe or FIFO, which cannot be positioned.
(There may be other kinds of files that cannot be positioned either, but
the behavior is not specified in those cases.)
</DL>
<P>
The <CODE>lseek</CODE> function is the underlying primitive for the
<CODE>fseek</CODE>, <CODE>ftell</CODE> and <CODE>rewind</CODE> functions, which operate on
streams instead of file descriptors.
<P>
You can have multiple descriptors for the same file if you open the file
more than once, or if you duplicate a descriptor with <CODE>dup</CODE>.  
Descriptors that come from separate calls to <CODE>open</CODE> have independent
file positions; using <CODE>lseek</CODE> on one descriptor has no effect on the
other.  For example, 
<P>
<PRE>
{
  int d1, d2;
  char buf[4];
  d1 = open ("foo", O_RDONLY);
  d2 = open ("foo", O_RDONLY);
  lseek (d1, 1024, SEEK_SET);
  read (d2, buf, 4);
}
</PRE>
<P>
will read the first four characters of the file <TT>`foo'</TT>.  (The
error-checking code necessary for a real program has been omitted here
for brevity.)
<P>
By contrast, descriptors made by duplication share a common file
position with the original descriptor that was duplicated.  Anything
which alters the file position of one of the duplicates, including
reading or writing data, affects all of them alike.  Thus, for example,
<P>
<PRE>
{
  int d1, d2, d3;
  char buf1[4], buf2[4];
  d1 = open ("foo", O_RDONLY);
  d2 = dup (d1);
  d3 = dup (d2);
  lseek (d3, 1024, SEEK_SET);
  read (d1, buf1, 4);
  read (d2, buf2, 4);
}
</PRE>
<P>
will read four characters starting with the 1024'th character of
<TT>`foo'</TT>, and then four more characters starting with the 1028'th
character.
<P>
<A NAME="IDX648"></A>
<U>Data Type:</U> <B>off_t</B><P>
This is an arithmetic data type used to represent file sizes.
In the GNU system, this is equivalent to <CODE>fpos_t</CODE> or <CODE>long int</CODE>.
<P>
These three aliases for the <SAMP>`SEEK_...'</SAMP> constants exist for the
sake of compatibility with older BSD systems.  They are defined in two
different header files: <TT>`fcntl.h'</TT> and <TT>`sys/file.h'</TT>.
<P>
<DL COMPACT>
<DT><CODE>L_SET</CODE>
<DD>An alias for <CODE>SEEK_SET</CODE>.
<P>
<DT><CODE>L_INCR</CODE>
<DD>An alias for <CODE>SEEK_CUR</CODE>.
<P>
<DT><CODE>L_XTND</CODE>
<DD>An alias for <CODE>SEEK_END</CODE>.
</DL>
<P>
<A NAME="IDX649"></A>
<A NAME="IDX650"></A>
<A NAME="IDX651"></A>
<H2><A NAME="SEC175" HREF="library_toc.html#SEC175" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC175">Descriptors and Streams</A></H2>
<P>
Given an open file descriptor, you can create a stream for it with the
<CODE>fdopen</CODE> function.  You can get the underlying file descriptor for
an existing stream with the <CODE>fileno</CODE> function.  These functions are
declared in the header file <TT>`stdio.h'</TT>.
<A NAME="IDX652"></A>
<P>
<A NAME="IDX653"></A>
<U>Function:</U> FILE * <B>fdopen</B> <I>(int <VAR>filedes</VAR>, const char *<VAR>opentype</VAR>)</I><P>
The <CODE>fdopen</CODE> function returns a new stream for the file descriptor
<VAR>filedes</VAR>.
<P>
The <VAR>opentype</VAR> argument is interpreted in the same way as for the
<CODE>fopen</CODE> function (see section <A HREF="library_11.html#SEC120" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html#SEC120">Opening Streams</A>), except that
the <SAMP>`b'</SAMP> option is not permitted; this is because GNU makes no
distinction between text and binary files.  Also, <CODE>"w"</CODE> and
<CODE>"w+"</CODE> do not cause truncation of the file; these have affect only
when opening a file, and in this case the file has already been opened.