(Memory Allocation): Remove invalid character from section title.
[kopensolaris-gnu/glibc.git] / manual / io.texi
index 51de118..f839138 100644 (file)
@@ -1,9 +1,10 @@
-@node Input/Output Overview
+@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.  The GNU
-C Library provides such a large selection of input and output functions
+C library provides such a large selection of input and output functions
 that the hardest part is often deciding which function is most
 appropriate!
 
@@ -12,11 +13,11 @@ and output.  Other chapters relating to the GNU I/O facilities are:
 
 @itemize @bullet
 @item
-@ref{Input/Output on Streams}, which covers the high-level functions
+@ref{I/O on Streams}, which covers the high-level functions
 that operate on streams, including formatted input and output.
 
 @item
-@ref{Low-Level Input/Output}, which covers the basic i/o and control
+@ref{Low-Level I/O}, which covers the basic I/O and control
 functions on file descriptors.
 
 @item
@@ -29,21 +30,21 @@ and ownership.
 communication facilities.
 
 @item
-@ref{Sockets}, covering a more complicated interprocess communication
+@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 terminal or other serial devices are processed.
+how input and output to terminals or other serial devices are processed.
 @end itemize
 
 
 @menu
-* Input/Output Concepts::              Some basic information and terminology.
-* File Names::                         How to refer to a file.
+* I/O Concepts::       Some basic information and terminology.
+* File Names::         How to refer to a file.
 @end menu
 
-@node Input/Output Concepts
+@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
@@ -52,9 +53,11 @@ 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 as a stream or 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.
+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
@@ -62,12 +65,13 @@ closed a stream or file descriptor, you cannot do any more input or
 output operations on it.
 
 @menu
-* Streams and File Descriptors::       The GNU Library provides two ways
-                                        to access the contents of files.
-* File Position Indicator::
+* Streams and File Descriptors::    The GNU 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
+@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
@@ -80,24 +84,26 @@ 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 one of these
-particular kinds of connections, you must deal with it as a file
-descriptor rather than as a stream.  You must also use file descriptors
-if your program needs to do input or output in special modes, such as
-nonblocking (or polled) input.
+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 connections in the same way.
+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 as well as functions for character-
-and line-oriented input and output.
+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
@@ -109,78 +115,90 @@ 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 and output functions
-(@pxref{Formatted Input} and @pxref{Formatted Output}, respectively).
+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 ANSI C to
+portable as streams.  You can expect any system running @w{ISO 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.
 
-@node File Position Indicator
-@subsection File Position Indicator
+@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 indicator}
-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.
+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.  In the GNU system, 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 indicator
+@cindex file position
 @cindex sequential-access files
 
-Some kinds of files permit read or write operations at any position
-within the file; these files are sometimes referred to as
-@dfn{random-access} files.  You can change the file position indicator
-using the @code{fseek} function on a stream (@pxref{File Positioning})
-or the @code{lseek} function on a file descriptor (@pxref{Input and
-Output Primitives}).
+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
 
-Typically, streams and file descriptors that correspond to real files on
-a disk and not to interactive devices or pipes to another process can be
-positioned, but there's no guarantee that @emph{any} file can be
-positioned.  If you try to perform a file positioning function on a file
-that doesn't support such operations, it reports failure.
-
-Files that are opened for @dfn{append access} are treated a little
-differently.  Output to such files is @emph{always} appended
-sequentially to the @emph{end} of the file, regardless of the file
-position.  But, the file position indicator is still used to control
-where reading occurs in the file.
+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.
 
-@node File Names
+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.  Files
---- even files that are really entire devices instead of components of a
-device such as a disk --- can be referred to by names that are strings.
-These strings are called @dfn{file names}.
+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.
-* Portability of File Names::
+* 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
+@node Directories, File Name Resolution,  , File Names
 @subsection Directories
 
 In order to understand the syntax of file names, you need to understand
-a little bit about what directories are and how the file system is
-organized.
+how the file system is organized into a hierarchy of directories.
 
 @cindex directory
 @cindex link
@@ -193,27 +211,34 @@ 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}.  This is distinct from a file name; a file name
-component names the file relative to a directory it is linked to, while
-a file name also indicates which directory contains the 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 this manual calls a file name, and either
-@dfn{filename} or @dfn{pathname component} for what this manual calls a
-file name component.  The two sets of terminology can be confusing, but
-we always use ``file name'' and ``file name component'' (or sometimes
-just ``component'', where the context is obvious) in this manual.
+@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
+@node File Name Resolution, File Name Errors, Directories, File Names
 @subsection File Name Resolution
 
-A file name string consists of file name components separated by slash
-(@samp{/}) characters.  (Multiple successive @samp{/} characters are
-treated like a single @samp{/} character.)
+A file name consists of file name components separated by slash
+(@samp{/}) characters.  On the systems that the GNU C library 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
@@ -228,8 +253,10 @@ 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.  Such a file
-name is called an @dfn{absolute file name}.
+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
@@ -242,7 +269,9 @@ 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).
+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:
 
@@ -257,7 +286,7 @@ The file named @file{b}, in the directory named @file{a} in the root directory.
 The file named @file{a}, in the current working directory.
 
 @item /a/./b
-This is the same as @file{/a/b}.  
+This is the same as @file{/a/b}.
 
 @item ./a
 The file named @file{a}, in the current working directory.
@@ -267,51 +296,64 @@ The file named @file{a}, in the parent directory of the current working
 directory.
 @end table
 
-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
-you can't have an empty file name.  If you want to refer to the current
-working directory, use a file name of @file{.} or @file{./}.
+@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, the GNU system doesn'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
+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
+@node File Name Errors, File Name Portability, File Name Resolution, File Names
 @subsection File Name Errors
 
-@cindex file name syntax errors
-@cindex usual file name syntax 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 file name syntax.  These
-errors are referred to throughout this manual as the @dfn{usual file
-name syntax errors}.
+@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 
+The process does not have search permission for a directory component
 of the file name.
 
 @item ENAMETOOLONG
-This error is used when either the the total length of a file name is
+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{File System Parameters}.
+has a length greater than @code{NAME_MAX}.  @xref{Limits for Files}.
+
+In the GNU system, 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.  It also is used when an empty file name
-string is supplied.
+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 the file isn't a directory.
+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 Portability of File Names
+@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},
@@ -322,7 +364,7 @@ There are two reasons why it can be important for you to be aware of
 file name portability issues:
 
 @itemize @bullet
-@item 
+@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.
@@ -336,8 +378,8 @@ operating system over a network, or read and write disks in formats used
 by other operating systems.
 @end itemize
 
-The ANSI C standard says very little about file name syntax, only that
-file names are strings.  In addition to the obvious restrictions on the
+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
@@ -347,8 +389,7 @@ 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, in the GNU system, you do not need to
-worry about these restrictions; any character is permitted in a file
-name string, and there are no limits on the length of file name strings.
-
-
+component strings.  However, in the GNU system, you do not need to worry
+about these restrictions; any character except the null character is
+permitted in a file name string, and there are no limits on the length
+of file name strings.