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

<TITLE>The GNU C Library - Input/Output Overview</TITLE>
<P>Go to the <A HREF="library_9.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_9.html">previous</A>, <A HREF="library_11.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html">next</A> section.<P>
<H1><A NAME="SEC108" HREF="library_toc.html#SEC108" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC108">Input/Output Overview</A></H1>
<P>
Most programs need to do either input (reading data) or output (writing
data), or most frequently both, in order to do anything useful.  The GNU
C library provides such a large selection of input and output functions
that the hardest part is often deciding which function is most
appropriate!
<P>
This chapter introduces concepts and terminology relating to input
and output.  Other chapters relating to the GNU I/O facilities are:
<P>
<UL>
<LI>
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>, which covers the high-level functions
that operate on streams, including formatted input and output.
<P>
<LI>
section <A HREF="library_12.html#SEC171" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC171">Low-Level Input/Output</A>, which covers the basic I/O and control
functions on file descriptors.
<P>
<LI>
section <A HREF="library_13.html#SEC187" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC187">File System Interface</A>, which covers functions for operating on
directories and for manipulating file attributes such as access modes
and ownership.
<P>
<LI>
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>, which includes information on the basic interprocess
communication facilities.
<P>
<LI>
section <A HREF="library_15.html#SEC216" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC216">Sockets</A>, covering a more complicated interprocess communication
facility with support for networking.
<P>
<LI>
section <A HREF="library_16.html#SEC268" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_16.html#SEC268">Low-Level Terminal Interface</A>, which covers functions for changing
how input and output to terminal or other serial devices are processed.
</UL>
<P>
<H2><A NAME="SEC109" HREF="library_toc.html#SEC109" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC109">Input/Output Concepts</A></H2>
<P>
Before you can read or write the contents of a file, you must establish
a connection or communications channel to the file.  This process is
called <DFN>opening</DFN> the file.  You can open a file for reading, writing,
or both.
<A NAME="IDX420"></A>
<P>
The connection to an open file is represented either as a stream or as a
file descriptor.  You pass this as an argument to the functions that do
the actual read or write operations, to tell them which file to operate
on.  Certain functions expect streams, and others are designed to
operate on file descriptors.
<P>
When you have finished reading to or writing from the file, you can
terminate the connection by <DFN>closing</DFN> the file.  Once you have
closed a stream or file descriptor, you cannot do any more input or
output operations on it.
<P>
<H3><A NAME="SEC110" HREF="library_toc.html#SEC110" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC110">Streams and File Descriptors</A></H3>
<P>
When you want to do input or output to a file, you have a choice of two
basic mechanisms for representing the connection between your program
and the file: file descriptors and streams.  File descriptors are
represented as objects of type <CODE>int</CODE>, while streams are represented
as <CODE>FILE *</CODE> objects.
<P>
File descriptors provide a primitive, low-level interface to input and
output operations.  Both file descriptors and streams can represent a
connection to a device (such as a terminal), or a pipe or socket for
communicating with another process, as well as a normal file.  But, if
you want to do control operations that are specific to a particular kind
of device, you must use a file descriptor; there are no facilities to
use streams in this way.  You must also use file descriptors if your
program needs to do input or output in special modes, such as
nonblocking (or polled) input (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>
Streams provide a higher-level interface, layered on top of the
primitive file descriptor facilities.  The stream interface treats all
kinds of files pretty much alike--the sole exception being the three
styles of buffering that you can choose (see section <A HREF="library_11.html#SEC160" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html#SEC160">Stream Buffering</A>).
<P>
The main advantage of using the stream interface is that the set of
functions for performing actual input and output operations (as opposed
to control operations) on streams is much richer and more powerful than
the corresponding facilities for file descriptors.  The file descriptor
interface provides only simple functions for transferring blocks of
characters, but the stream interface also provides powerful formatted
input and output functions (<CODE>printf</CODE> and <CODE>scanf</CODE>) as well as
functions for character- and line-oriented input and output.
<P>
Since streams are implemented in terms of file descriptors, you can
extract the file descriptor from a stream and perform low-level
operations directly on the file descriptor.  You can also initially open
a connection as a file descriptor and then make a stream associated with
that file descriptor.
<P>
In general, you should stick with using streams rather than file
descriptors, unless there is some specific operation you want to do that
can only be done on a file descriptor.  If you are a beginning
programmer and aren't sure what functions to use, we suggest that you
concentrate on the formatted input functions (see section <A HREF="library_11.html#SEC145" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html#SEC145">Formatted Input</A>)
and formatted output functions (see section <A HREF="library_11.html#SEC128" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html#SEC128">Formatted Output</A>).
<P>
If you are concerned about portability of your programs to systems other
than GNU, you should also be aware that file descriptors are not as
portable as streams.  You can expect any system running ANSI C to
support streams, but non-GNU systems may not support file descriptors at
all, or may only implement a subset of the GNU functions that operate on
file descriptors.  Most of the file descriptor functions in the GNU
library are included in the POSIX.1 standard, however.
<P>
<H3><A NAME="SEC111" HREF="library_toc.html#SEC111" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC111">File Position</A></H3>
<P>
One of the attributes of an open file is its <DFN>file position</DFN>
that keeps track of where in the file the next character is to be read
or written.  In the GNU system, the file position is simply an integer
representing the number of bytes from the beginning of the file.
<P>
The file position is normally set to the beginning of the file when it
is opened, and each time a character is read or written, the file
position is incremented.  In other words, access to the file is normally
<DFN>sequential</DFN>.
<A NAME="IDX422"></A>
<A NAME="IDX421"></A>
<P>
Ordinary files permit read or write operations at any position within
the file.  Some other kinds of files may also permit this.  Files which
do permit this are sometimes referred to as <DFN>random-access</DFN> files.
You can change the file position using the <CODE>fseek</CODE> function on a
stream (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>) or the <CODE>lseek</CODE> function on a file
descriptor (see section <A HREF="library_12.html#SEC173" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC173">Input and Output Primitives</A>).  If you try to change the file
position on a file that doesn't support random access, you get an error.
<A NAME="IDX423"></A>
<P>
Streams and descriptors that are opened for <DFN>append access</DFN> are
treated specially for output: output to such files is <EM>always</EM>
appended sequentially to the <EM>end</EM> of the file, regardless of the
file position.  But, the file position is still used to control where in
the file reading is done.
<A NAME="IDX424"></A>
<P>
If you think about it, you'll realize that several programs can read a
given file at the same time.  In order for each program to be able to
read the file at its own pace, each program must have its own file
pointer, which is not affected by anything the other programs do.
<P>
In fact, each opening of a file creates a separate file position.  
Thus, if you open a file twice even in the same program, you get two
streams or descriptors with independent file positions.
<P>
By contrast, if you open a descriptor and then duplicate it to get 
another descriptor, these two descriptors share the same file position:
changing the file position of one descriptor will affect the other.
<P>
<H2><A NAME="SEC112" HREF="library_toc.html#SEC112" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC112">File Names</A></H2>
<P>
In order to open a connection to a file, or to perform other operations
such as deleting a file, you need some way to refer to the file.  Nearly
all files have names that are strings--even files which are actually
devices such as tape drives or terminals.  These strings are called
<DFN>file names</DFN>.  You specify the file name to say which file you want
to open or operate on.
<P>
This section describes the conventions for file names and how the
operating system works with them.
<A NAME="IDX425"></A>
<P>
<H3><A NAME="SEC113" HREF="library_toc.html#SEC113" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC113">Directories</A></H3>
<P>
In order to understand the syntax of file names, you need to understand
how the file system is organized into a hierarchy of directories.
<A NAME="IDX426"></A>