@node I/O Overview, I/O on Streams, Pattern Matching, Top

@c %MENU% Introduction to the I/O facilities

@chapter Input/Output Overview

Most programs need to do either input (reading data) or output (writing

data), or most frequently both, in order to do anything useful.  @Theglibc{}

provides such a large selection of input and output functions

that the hardest part is often deciding which function is most

appropriate!

This chapter introduces concepts and terminology relating to input

and output.  Other chapters relating to the GNU I/O facilities are:

@itemize @bullet

@item

@ref{I/O on Streams}, which covers the high-level functions

that operate on streams, including formatted input and output.

@item

@ref{Low-Level I/O}, which covers the basic I/O and control

functions on file descriptors.

@item

@ref{File System Interface}, which covers functions for operating on

directories and for manipulating file attributes such as access modes

and ownership.

@item

@ref{Pipes and FIFOs}, which includes information on the basic interprocess

communication facilities.

@item

@ref{Sockets}, which covers a more complicated interprocess communication

facility with support for networking.

@item

@ref{Low-Level Terminal Interface}, which covers functions for changing

how input and output to terminals or other serial devices are processed.

@end itemize

@menu

* I/O Concepts::       Some basic information and terminology.

* File Names::         How to refer to a file.

@end menu

@node I/O Concepts, File Names,  , I/O Overview

@section Input/Output Concepts

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} the file.  You can open a file for reading, writing,

or both.

@cindex opening a file

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.

When you have finished reading to or writing from the file, you can

terminate the connection by @dfn{closing} the file.  Once you have

closed a stream or file descriptor, you cannot do any more input or

output operations on it.

@menu

* Streams and File Descriptors::    The GNU C Library provides two ways

			             to access the contents of files.

* File Position::                   The number of bytes from the

                                     beginning of the file.

@end menu

@node Streams and File Descriptors, File Position,  , I/O Concepts

@subsection Streams and File Descriptors

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}, while streams are represented

as @code{FILE *} objects.

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 (@pxref{File Status Flags}).

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 (@pxref{Stream Buffering}).

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} and @code{scanf}) as well as

functions for character- and line-oriented input and output.

@c !!! glibc has dprintf, which lets you do printf on an fd.

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.

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 (@pxref{Formatted Input})

and formatted output functions (@pxref{Formatted Output}).

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 @w{ISO C} to

support streams, but @nongnusystems{} 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 @theglibc{}

are included in the POSIX.1 standard, however.

@node File Position,  , Streams and File Descriptors, I/O Concepts

@subsection File Position

One of the attributes of an open file is its @dfn{file position} that

keeps track of where in the file the next character is to be read or

written.  On @gnusystems{}, and all POSIX.1 systems, the file position

is simply an integer representing the number of bytes from the beginning

of the file.

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}.

@cindex file position

@cindex sequential-access files

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} files.

You can change the file position using the @code{fseek} function on a

stream (@pxref{File Positioning}) or the @code{lseek} function on a file

descriptor (@pxref{I/O Primitives}).  If you try to change the file

position on a file that doesn't support random access, you get the

@code{ESPIPE} error.

@cindex random-access files

Streams and descriptors that are opened for @dfn{append access} are

treated specially for output: output to such files is @emph{always}

appended sequentially to the @emph{end} of the file, regardless of the

file position.  However, the file position is still used to control where in

the file reading is done.

@cindex append-access files

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.

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.

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.

@node File Names,  , I/O Concepts, I/O Overview

@section File Names

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}.  You specify the file name to say which file you want

to open or operate on.

This section describes the conventions for file names and how the

operating system works with them.

@cindex file name

@menu

* Directories::                 Directories contain entries for files.

* File Name Resolution::        A file name specifies how to look up a file.

* File Name Errors::            Error conditions relating to file names.

* File Name Portability::       File name portability and syntax issues.

@end menu

@node Directories, File Name Resolution,  , File Names

@subsection Directories

In order to understand the syntax of file names, you need to understand

how the file system is organized into a hierarchy of directories.

@cindex directory

@cindex link

@cindex directory entry

A @dfn{directory} is a file that contains information to associate other

files with names; these associations are called @dfn{links} or

@dfn{directory entries}.  Sometimes, people speak of ``files in a

directory'', but in reality, a directory only contains pointers to

files, not the files themselves.

@cindex file name component

The name of a file contained in a directory entry is called a @dfn{file

name component}.  In general, a file name consists of a sequence of one

or more such components, separated by the slash character (@samp{/}).  A

file name which is just one component names a file with respect to its

directory.  A file name with multiple components names a directory, and

then a file in that directory, and so on.

Some other documents, such as the POSIX standard, use the term

@dfn{pathname} for what we call a file name, and either @dfn{filename}

or @dfn{pathname component} for what this manual calls a file name

component.  We don't use this terminology because a ``path'' is

something completely different (a list of directories to search), and we

think that ``pathname'' used for something else will confuse users.  We

always use ``file name'' and ``file name component'' (or sometimes just

``component'', where the context is obvious) in GNU documentation.  Some

macros use the POSIX terminology in their names, such as

@code{PATH_MAX}.  These macros are defined by the POSIX standard, so we

cannot change their names.

You can find more detailed information about operations on directories

in @ref{File System Interface}.

@node File Name Resolution, File Name Errors, Directories, File Names

@subsection File Name Resolution

A file name consists of file name components separated by slash

(@samp{/}) characters.  On the systems that @theglibc{} supports,

multiple successive @samp{/} characters are equivalent to a single

@samp{/} character.

@cindex file name resolution

The process of determining what file a file name refers to is called

@dfn{file name resolution}.  This is performed by examining the

components that make up a file name in left-to-right order, and locating

each successive component in the directory named by the previous

component.  Of course, each of the files that are referenced as

directories must actually exist, be directories instead of regular

files, and have the appropriate permissions to be accessible by the

process; otherwise the file name resolution fails.

@cindex root directory

@cindex absolute file name

If a file name begins with a @samp{/}, the first component in the file

name is located in the @dfn{root directory} of the process (usually all

processes on the system have the same root directory).  Such a file name

is called an @dfn{absolute file name}.

@c !!! xref here to chroot, if we ever document chroot. -rm

@cindex relative file name

Otherwise, the first component in the file name is located in the

current working directory (@pxref{Working Directory}).  This kind of

file name is called a @dfn{relative file name}.

@cindex parent directory

The file name components @file{.} (``dot'') and @file{..} (``dot-dot'')

have special meanings.  Every directory has entries for these file name

components.  The file name component @file{.} refers to the directory

itself, while the file name component @file{..} refers to its

@dfn{parent directory} (the directory that contains the link for the

directory in question).  As a special case, @file{..} in the root

directory refers to the root directory itself, since it has no parent;

thus @file{/..} is the same as @file{/}.

Here are some examples of file names:

@table @file

@item /a

The file named @file{a}, in the root directory.

@item /a/b

The file named @file{b}, in the directory named @file{a} in the root directory.

@item a

The file named @file{a}, in the current working directory.

@item /a/./b

This is the same as @file{/a/b}.

@item ./a

The file named @file{a}, in the current working directory.

@item ../a

The file named @file{a}, in the parent directory of the current working

directory.

@end table

@c An empty string may ``work'', but I think it's confusing to

@c try to describe it.  It's not a useful thing for users to use--rms.

A file name that names a directory may optionally end in a @samp{/}.

You can specify a file name of @file{/} to refer to the root directory,

but the empty string is not a meaningful file name.  If you want to

refer to the current working directory, use a file name of @file{.} or

@file{./}.

Unlike some other operating systems, @gnusystems{} don't have any

built-in support for file types (or extensions) or file versions as part

of its file name syntax.  Many programs and utilities use conventions

for file names---for example, files containing C source code usually

have names suffixed with @samp{.c}---but there is nothing in the file

system itself that enforces this kind of convention.

@node File Name Errors, File Name Portability, File Name Resolution, File Names

@subsection File Name Errors

@cindex file name errors

@cindex usual file name errors

Functions that accept file name arguments usually detect these

@code{errno} error conditions relating to the file name syntax or

trouble finding the named file.  These errors are referred to throughout

this manual as the @dfn{usual file name errors}.

@table @code

@item EACCES

The process does not have search permission for a directory component

of the file name.

@item ENAMETOOLONG

This error is used when either the total length of a file name is

greater than @code{PATH_MAX}, or when an individual file name component

has a length greater than @code{NAME_MAX}.  @xref{Limits for Files}.

On @gnuhurdsystems{}, there is no imposed limit on overall file name

length, but some file systems may place limits on the length of a

component.

@item ENOENT

This error is reported when a file referenced as a directory component

in the file name doesn't exist, or when a component is a symbolic link

whose target file does not exist.  @xref{Symbolic Links}.

@item ENOTDIR

A file that is referenced as a directory component in the file name

exists, but it isn't a directory.

@item ELOOP

Too many symbolic links were resolved while trying to look up the file

name.  The system has an arbitrary limit on the number of symbolic links

that may be resolved in looking up a single file name, as a primitive

way to detect loops.  @xref{Symbolic Links}.

@end table

@node File Name Portability,  , File Name Errors, File Names

@subsection Portability of File Names

The rules for the syntax of file names discussed in @ref{File Names},

are the rules normally used by @gnusystems{} and by other POSIX

systems.  However, other operating systems may use other conventions.

There are two reasons why it can be important for you to be aware of

file name portability issues:

@itemize @bullet

@item

If your program makes assumptions about file name syntax, or contains

embedded literal file name strings, it is more difficult to get it to

run under other operating systems that use different syntax conventions.

@item

Even if you are not concerned about running your program on machines

that run other operating systems, it may still be possible to access

files that use different naming conventions.  For example, you may be

able to access file systems on another computer running a different

operating system over a network, or read and write disks in formats used

by other operating systems.

@end itemize

The @w{ISO C} standard says very little about file name syntax, only that

file names are strings.  In addition to varying restrictions on the

length of file names and what characters can validly appear in a file

name, different operating systems use different conventions and syntax

for concepts such as structured directories and file types or

extensions.  Some concepts such as file versions might be supported in

some operating systems and not by others.

The POSIX.1 standard allows implementations to put additional

restrictions on file name syntax, concerning what characters are

permitted in file names and on the length of file name and file name

component strings.  However, on @gnusystems{}, any character except

the null character is permitted in a file name string, and

on @gnuhurdsystems{} there are no limits on the length of file name

strings.