(Memory Allocation): Remove invalid character from section title.
[kopensolaris-gnu/glibc.git] / manual / io.texi
index 869a0a5..f839138 100644 (file)
@@ -1,4 +1,5 @@
 @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
@@ -29,12 +30,12 @@ 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
 
 
@@ -119,19 +120,20 @@ 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,  , Streams and File Descriptors, I/O Concepts
-@subsection File Position 
+@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.  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
@@ -146,13 +148,14 @@ 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 an error.
+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.  But, the file position is still used to control where in
+file position.  However, the file position is still used to control where in
 the file reading is done.
 @cindex append-access files
 
@@ -161,11 +164,11 @@ 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.  
+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 
+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.
 
@@ -215,13 +218,16 @@ 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.
+@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}.
@@ -247,10 +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}.
-@c !!! xref here to chroot, if we ever document chroot.
-@c ??? I don't like the idea of encouraging smoking--rms.
+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
@@ -263,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:
 
@@ -278,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.
@@ -288,7 +296,7 @@ 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 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,
@@ -306,21 +314,21 @@ 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 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{Limits for Files}.
 
@@ -330,11 +338,18 @@ component.
 
 @item ENOENT
 This error is reported when a file referenced as a directory component
-in the file name doesn't exist.
+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
 
 
@@ -349,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.
@@ -363,7 +378,7 @@ 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
+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
@@ -378,5 +393,3 @@ 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.
-
-