<!-- This HTML file has been created by texi2html 1.27
     from library.texinfo on 3 March 1994 -->

<TITLE>The GNU C Library - Low-Level Input/Output</TITLE>
<P>Go to the <A HREF="library_11.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html">previous</A>, <A HREF="library_13.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html">next</A> section.<P>
<H1><A NAME="SEC171" HREF="library_toc.html#SEC171" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC171">Low-Level Input/Output</A></H1>
<P>
This chapter describes functions for performing low-level input/output
operations on file descriptors.  These functions include the primitives
for the higher-level I/O functions described in section <A HREF="library_11.html#SEC117" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html#SEC117">Input/Output on Streams</A>, as
well as functions for performing low-level control operations for which
there are no equivalents on streams.
<P>
Stream-level I/O is more flexible and usually more convenient;
therefore, programmers generally use the descriptor-level functions only
when necessary.  These are some of the usual reasons:
<P>
<UL>
<LI>
For reading binary files in large chunks.
<P>
<LI>
For reading an entire file into core before parsing it.
<P>
<LI>
To perform operations other than data transfer, which can only be done
with a descriptor.  (You can use <CODE>fileno</CODE> to get the descriptor
corresponding to a stream.)
<P>
<LI>
To pass descriptors to a child process.  (The child can create its own
stream to use a descriptor that it inherits, but cannot inherit a stream
directly.)
</UL>
<P>
<H2><A NAME="SEC172" HREF="library_toc.html#SEC172" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC172">Opening and Closing Files</A></H2>
<A NAME="IDX618"></A>
<A NAME="IDX619"></A>
<P>
This section describes the primitives for opening and closing files
using file descriptors.  The <CODE>open</CODE> and <CODE>creat</CODE> functions are
declared in the header file <TT>`fcntl.h'</TT>, while <CODE>close</CODE> is
declared in <TT>`unistd.h'</TT>.
<A NAME="IDX621"></A>
<A NAME="IDX620"></A>
<P>
<A NAME="IDX622"></A>
<U>Function:</U> int <B>open</B> <I>(const char *<VAR>filename</VAR>, int <VAR>flags</VAR>[, mode_t <VAR>mode</VAR>])</I><P>
The <CODE>open</CODE> function creates and returns a new file descriptor
for the file named by <VAR>filename</VAR>.  Initially, the file position
indicator for the file is at the beginning of the file.  The argument
<VAR>mode</VAR> is used only when a file is created, but it doesn't hurt
to supply the argument in any case.
<P>
The <VAR>flags</VAR> argument controls how the file is to be opened.  This is
a bit mask; you create the value by the bitwise OR of the appropriate
parameters (using the <SAMP>`|'</SAMP> operator in C).
<P>
The <VAR>flags</VAR> argument must include exactly one of these values to
specify the file access mode:
<P>
<DL COMPACT>
<A NAME="IDX623"></A>
<DT><CODE>O_RDONLY</CODE>
<DD>Open the file for read access.
<P>
<A NAME="IDX624"></A>
<DT><CODE>O_WRONLY</CODE>
<DD>Open the file for write access.
<P>
<A NAME="IDX625"></A>
<DT><CODE>O_RDWR</CODE>
<DD>Open the file for both reading and writing.
</DL>
<P>
The <VAR>flags</VAR> argument can also include any combination of these
flags:
<P>
<DL COMPACT>
<A NAME="IDX626"></A>
<A NAME="IDX627"></A>
<DT><CODE>O_APPEND</CODE>
<DD>If set, then all <CODE>write</CODE> operations write the data at the end of
the file, extending it, regardless of the current file position.
<P>
<A NAME="IDX628"></A>
<DT><CODE>O_CREAT</CODE>
<DD>If set, the file will be created if it doesn't already exist.
<A NAME="IDX629"></A>
<P>
<A NAME="IDX630"></A>
<DT><CODE>O_EXCL</CODE>
<DD>If both <CODE>O_CREAT</CODE> and <CODE>O_EXCL</CODE> are set, then <CODE>open</CODE> fails
if the specified file already exists.
<P>
<A NAME="IDX631"></A>
<DT><CODE>O_NOCTTY</CODE>
<DD>If <VAR>filename</VAR> names a terminal device, don't make it the controlling
terminal for the process.  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 information about what
it means to be the controlling terminal.
<P>
<A NAME="IDX632"></A>
<A NAME="IDX633"></A>
<DT><CODE>O_NONBLOCK</CODE>
<DD>This sets nonblocking mode.  This option is usually only useful for
special files such as FIFOs (see section <A HREF="library_14.html#SEC211" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_14.html#SEC211">Pipes and FIFOs</A>) and devices such
as terminals.  Normally, for these files, <CODE>open</CODE> blocks until
the file is "ready".  If <CODE>O_NONBLOCK</CODE> is set, <CODE>open</CODE>
returns immediately.
<P>
The <CODE>O_NONBLOCK</CODE> bit also affects <CODE>read</CODE> and <CODE>write</CODE>: It
permits them to return immediately with a failure status if there is no
input immediately available (<CODE>read</CODE>), or if the output can't be
written immediately (<CODE>write</CODE>).
<P>
<A NAME="IDX634"></A>
<DT><CODE>O_TRUNC</CODE>
<DD>If the file exists and is opened for write access, truncate it to zero
length.  This option is only useful for regular files, not special
files such as directories or FIFOs.
</DL>
<P>
For more information about these symbolic constants, see section <A HREF="library_12.html#SEC184" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC184">File Status Flags</A>.
<P>
The normal return value from <CODE>open</CODE> is a non-negative integer file
descriptor.  In the case of an error, a value of <CODE>-1</CODE> is returned
instead.  In addition to the usual file name syntax errors (see section <A HREF="library_10.html#SEC115" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_10.html#SEC115">File Name Errors</A>), the following <CODE>errno</CODE> error conditions are defined
for this function:
<P>
<DL COMPACT>
<DT><CODE>EACCES</CODE>
<DD>The file exists but is not readable/writable as requested by the <VAR>flags</VAR>
argument.
<P>
<DT><CODE>EEXIST</CODE>
<DD>Both <CODE>O_CREAT</CODE> and <CODE>O_EXCL</CODE> are set, and the named file already
exists.
<P>
<DT><CODE>EINTR</CODE>
<DD>The <CODE>open</CODE> operation was interrupted by a signal.
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>EISDIR</CODE>
<DD>The <VAR>flags</VAR> argument specified write access, and the file is a directory.
<P>
<DT><CODE>EMFILE</CODE>
<DD>The process has too many files open.
<P>
<DT><CODE>ENFILE</CODE>
<DD>The entire system, or perhaps the file system which contains the
directory, cannot support any additional open files at the moment.
(This problem cannot happen on the GNU system.)
<P>
<DT><CODE>ENOENT</CODE>
<DD>The named file does not exist, but <CODE>O_CREAT</CODE> is not specified.
<P>
<DT><CODE>ENOSPC</CODE>
<DD>The directory or file system that would contain the new file cannot be
extended, because there is no disk space left.
<P>
<DT><CODE>ENXIO</CODE>
<DD><CODE>O_NONBLOCK</CODE> and <CODE>O_WRONLY</CODE> are both set in the <VAR>flags</VAR>
argument, the file named by <VAR>filename</VAR> is a FIFO (see section <A HREF="library_14.html#SEC211" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_14.html#SEC211">Pipes and FIFOs</A>), and no process has the file open for reading.
<P>
<DT><CODE>EROFS</CODE>
<DD>The file resides on a read-only file system and any of <CODE>O_WRONLY</CODE>,
<CODE>O_RDWR</CODE>, <CODE>O_CREAT</CODE>, and <CODE>O_TRUNC</CODE> are set in the
<VAR>flags</VAR> argument.
</DL>
<P>
The <CODE>open</CODE> function is the underlying primitive for the <CODE>fopen</CODE>
and <CODE>freopen</CODE> functions, that create streams.
<P>
<A NAME="IDX635"></A>
<U>Obsolete function:</U> int <B>creat</B> <I>(const char *<VAR>filename</VAR>, mode_t <VAR>mode</VAR>)</I><P>
This function is obsolete.  The call
<P>
<PRE>
creat (<VAR>filename</VAR>, <VAR>mode</VAR>)
</PRE>
<P>
is equivalent to
<P>
<PRE>
open (<VAR>filename</VAR>, O_WRONLY | O_CREAT | O_TRUNC, <VAR>mode</VAR>)
</PRE>
<P>
<A NAME="IDX636"></A>
<U>Function:</U> int <B>close</B> <I>(int <VAR>filedes</VAR>)</I><P>
The function <CODE>close</CODE> closes the file descriptor <VAR>filedes</VAR>.
Closing a file has the following consequences:
<P>
<UL>
<LI>
The file descriptor is deallocated.
<P>
<LI>
Any record locks owned by the process on the file are unlocked.
<P>
<LI>
When all file descriptors associated with a pipe or FIFO have been closed,
any unread data is discarded.
</UL>
<P>
The normal return value from <CODE>close</CODE> is <CODE>0</CODE>; a value of <CODE>-1</CODE>
is returned in case of failure.  The following <CODE>errno</CODE> error
conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>EINTR</CODE>
<DD>The call was interrupted by a signal.  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>.
Here's an example of how to handle <CODE>EINTR</CODE> properly:
<P>
<PRE>
TEMP_FAILURE_RETRY (close (desc));
</PRE>
</DL>
<P>
To close a stream, call <CODE>fclose</CODE> (see section <A HREF="library_11.html#SEC121" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html#SEC121">Closing Streams</A>) instead
of trying to close its underlying file descriptor with <CODE>close</CODE>.
This flushes any buffered output and updates the stream object to
indicate that it is closed.
<P>
<H2><A NAME="SEC173" HREF="library_toc.html#SEC173" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC173">Input and Output Primitives</A></H2>
<P>
This section describes the functions for performing primitive input and
output operations on file descriptors: <CODE>read</CODE>, <CODE>write</CODE>, and
<CODE>lseek</CODE>.  These functions are declared in the header file
<TT>`unistd.h'</TT>.
<A NAME="IDX637"></A>
<P>
<A NAME="IDX638"></A>
<U>Data Type:</U> <B>ssize_t</B><P>
This data type is used to represent the sizes of blocks that can be
read or written in a single operation.  It is similar to <CODE>size_t</CODE>,
but must be a signed type.
<P>
<A NAME="IDX639"></A>
<P>
<A NAME="IDX640"></A>
<U>Function:</U> ssize_t <B>read</B> <I>(int <VAR>filedes</VAR>, void *<VAR>buffer</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>read</CODE> function reads up to <VAR>size</VAR> bytes from the file
with descriptor <VAR>filedes</VAR>, storing the results in the <VAR>buffer</VAR>.
(This is not necessarily a character string and there is no terminating
null character added.)
<A NAME="IDX641"></A>
<P>
The return value is the number of bytes actually read.  This might be
less than <VAR>size</VAR>; for example, if there aren't that many bytes left
in the file or if there aren't that many bytes immediately available.
The exact behavior depends on what kind of file it is.  Note that
reading less than <VAR>size</VAR> bytes is not an error.
<P>
A value of zero indicates end-of-file (except if the value of the
<VAR>size</VAR> argument is also zero).  This is not considered an error.
If you keep calling <CODE>read</CODE> while at end-of-file, it will keep
returning zero and doing nothing else.
<P>
If <CODE>read</CODE> returns at least one character, there is no way you can
tell whether end-of-file was reached.  But if you did reach the end, the
next read will return zero.
<P>
In case of an error, <CODE>read</CODE> returns <CODE>-1</CODE>.  The following
<CODE>errno</CODE> error conditions are defined for this function:
<P>