This is libc.info, produced by makeinfo version 4.0c from libc.texinfo.

INFO-DIR-SECTION GNU libraries
START-INFO-DIR-ENTRY
* Libc: (libc).                 C library.
END-INFO-DIR-ENTRY

   This file documents the GNU C library.

   This is Edition 0.10, last updated 2001-07-06, of `The GNU C Library
Reference Manual', for Version 2.2.x.

   Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001 Free
Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU Lesser General Public License", the
Front-Cover texts being (a) (see below), and with the Back-Cover Texts
being (b) (see below).  A copy of the license is included in the section
entitled "GNU Free Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.


File: libc.info,  Node: Calling Wordexp,  Next: Flags for Wordexp,  Prev: Expansion Stages,  Up: Word Expansion

Calling `wordexp'
-----------------

   All the functions, constants and data types for word expansion are
declared in the header file `wordexp.h'.

   Word expansion produces a vector of words (strings).  To return this
vector, `wordexp' uses a special data type, `wordexp_t', which is a
structure.  You pass `wordexp' the address of the structure, and it
fills in the structure's fields to tell you about the results.

 - Data Type: wordexp_t
     This data type holds a pointer to a word vector.  More precisely,
     it records both the address of the word vector and its size.

    `we_wordc'
          The number of elements in the vector.

    `we_wordv'
          The address of the vector.  This field has type `char **'.

    `we_offs'
          The offset of the first real element of the vector, from its
          nominal address in the `we_wordv' field.  Unlike the other
          fields, this is always an input to `wordexp', rather than an
          output from it.

          If you use a nonzero offset, then that many elements at the
          beginning of the vector are left empty.  (The `wordexp'
          function fills them with null pointers.)

          The `we_offs' field is meaningful only if you use the
          `WRDE_DOOFFS' flag.  Otherwise, the offset is always zero
          regardless of what is in this field, and the first real
          element comes at the beginning of the vector.

 - Function: int wordexp (const char *WORDS, wordexp_t
          *WORD-VECTOR-PTR, int FLAGS)
     Perform word expansion on the string WORDS, putting the result in
     a newly allocated vector, and store the size and address of this
     vector into `*WORD-VECTOR-PTR'.  The argument FLAGS is a
     combination of bit flags; see *Note Flags for Wordexp::, for
     details of the flags.

     You shouldn't use any of the characters `|&;<>' in the string
     WORDS unless they are quoted; likewise for newline.  If you use
     these characters unquoted, you will get the `WRDE_BADCHAR' error
     code.  Don't use parentheses or braces unless they are quoted or
     part of a word expansion construct.  If you use quotation
     characters `'"`', they should come in pairs that balance.

     The results of word expansion are a sequence of words.  The
     function `wordexp' allocates a string for each resulting word, then
     allocates a vector of type `char **' to store the addresses of
     these strings.  The last element of the vector is a null pointer.
     This vector is called the "word vector".

     To return this vector, `wordexp' stores both its address and its
     length (number of elements, not counting the terminating null
     pointer) into `*WORD-VECTOR-PTR'.

     If `wordexp' succeeds, it returns 0.  Otherwise, it returns one of
     these error codes:

    `WRDE_BADCHAR'
          The input string WORDS contains an unquoted invalid character
          such as `|'.

    `WRDE_BADVAL'
          The input string refers to an undefined shell variable, and
          you used the flag `WRDE_UNDEF' to forbid such references.

    `WRDE_CMDSUB'
          The input string uses command substitution, and you used the
          flag `WRDE_NOCMD' to forbid command substitution.

    `WRDE_NOSPACE'
          It was impossible to allocate memory to hold the result.  In
          this case, `wordexp' can store part of the results--as much
          as it could allocate room for.

    `WRDE_SYNTAX'
          There was a syntax error in the input string.  For example,
          an unmatched quoting character is a syntax error.

 - Function: void wordfree (wordexp_t *WORD-VECTOR-PTR)
     Free the storage used for the word-strings and vector that
     `*WORD-VECTOR-PTR' points to.  This does not free the structure
     `*WORD-VECTOR-PTR' itself--only the other data it points to.


File: libc.info,  Node: Flags for Wordexp,  Next: Wordexp Example,  Prev: Calling Wordexp,  Up: Word Expansion

Flags for Word Expansion
------------------------

   This section describes the flags that you can specify in the FLAGS
argument to `wordexp'.  Choose the flags you want, and combine them
with the C operator `|'.

`WRDE_APPEND'
     Append the words from this expansion to the vector of words
     produced by previous calls to `wordexp'.  This way you can
     effectively expand several words as if they were concatenated with
     spaces between them.

     In order for appending to work, you must not modify the contents
     of the word vector structure between calls to `wordexp'.  And, if
     you set `WRDE_DOOFFS' in the first call to `wordexp', you must also
     set it when you append to the results.

`WRDE_DOOFFS'
     Leave blank slots at the beginning of the vector of words.  The
     `we_offs' field says how many slots to leave.  The blank slots
     contain null pointers.

`WRDE_NOCMD'
     Don't do command substitution; if the input requests command
     substitution, report an error.

`WRDE_REUSE'
     Reuse a word vector made by a previous call to `wordexp'.  Instead
     of allocating a new vector of words, this call to `wordexp' will
     use the vector that already exists (making it larger if necessary).

     Note that the vector may move, so it is not safe to save an old
     pointer and use it again after calling `wordexp'.  You must fetch
     `we_pathv' anew after each call.

`WRDE_SHOWERR'
     Do show any error messages printed by commands run by command
     substitution.  More precisely, allow these commands to inherit the
     standard error output stream of the current process.  By default,
     `wordexp' gives these commands a standard error stream that
     discards all output.

`WRDE_UNDEF'
     If the input refers to a shell variable that is not defined,
     report an error.


File: libc.info,  Node: Wordexp Example,  Next: Tilde Expansion,  Prev: Flags for Wordexp,  Up: Word Expansion

`wordexp' Example
-----------------

   Here is an example of using `wordexp' to expand several strings and
use the results to run a shell command.  It also shows the use of
`WRDE_APPEND' to concatenate the expansions and of `wordfree' to free
the space allocated by `wordexp'.

     int
     expand_and_execute (const char *program, const char *options)
     {
       wordexp_t result;
       pid_t pid
       int status, i;
     
       /* Expand the string for the program to run.  */
       switch (wordexp (program, &result, 0))
         {
         case 0:			/* Successful.  */
           break;
         case WRDE_NOSPACE:
           /* If the error was `WRDE_NOSPACE',
              then perhaps part of the result was allocated.  */
           wordfree (&result);
         default:                    /* Some other error.  */
           return -1;
         }
     
       /* Expand the strings specified for the arguments.  */
       for (i = 0; args[i]; i++)
         {
           if (wordexp (options, &result, WRDE_APPEND))
             {
               wordfree (&result);
               return -1;
             }
         }
     
       pid = fork ();
       if (pid == 0)
         {
           /* This is the child process.  Execute the command. */
           execv (result.we_wordv[0], result.we_wordv);
           exit (EXIT_FAILURE);
         }
       else if (pid < 0)
         /* The fork failed.  Report failure.  */
         status = -1;
       else
         /* This is the parent process.  Wait for the child to complete.  */
         if (waitpid (pid, &status, 0) != pid)
           status = -1;
     
       wordfree (&result);
       return status;
     }


File: libc.info,  Node: Tilde Expansion,  Next: Variable Substitution,  Prev: Wordexp Example,  Up: Word Expansion

Details of Tilde Expansion
--------------------------

   It's a standard part of shell syntax that you can use `~' at the
beginning of a file name to stand for your own home directory.  You can
use `~USER' to stand for USER's home directory.

   "Tilde expansion" is the process of converting these abbreviations
to the directory names that they stand for.

   Tilde expansion applies to the `~' plus all following characters up
to whitespace or a slash.  It takes place only at the beginning of a
word, and only if none of the characters to be transformed is quoted in
any way.

   Plain `~' uses the value of the environment variable `HOME' as the
proper home directory name.  `~' followed by a user name uses
`getpwname' to look up that user in the user database, and uses
whatever directory is recorded there.  Thus, `~' followed by your own
name can give different results from plain `~', if the value of `HOME'
is not really your home directory.


File: libc.info,  Node: Variable Substitution,  Prev: Tilde Expansion,  Up: Word Expansion

Details of Variable Substitution
--------------------------------

   Part of ordinary shell syntax is the use of `$VARIABLE' to
substitute the value of a shell variable into a command.  This is called
"variable substitution", and it is one part of doing word expansion.

   There are two basic ways you can write a variable reference for
substitution:

`${VARIABLE}'
     If you write braces around the variable name, then it is completely
     unambiguous where the variable name ends.  You can concatenate
     additional letters onto the end of the variable value by writing
     them immediately after the close brace.  For example, `${foo}s'
     expands into `tractors'.

`$VARIABLE'
     If you do not put braces around the variable name, then the
     variable name consists of all the alphanumeric characters and
     underscores that follow the `$'.  The next punctuation character
     ends the variable name.  Thus, `$foo-bar' refers to the variable
     `foo' and expands into `tractor-bar'.

   When you use braces, you can also use various constructs to modify
the value that is substituted, or test it in various ways.

`${VARIABLE:-DEFAULT}'
     Substitute the value of VARIABLE, but if that is empty or
     undefined, use DEFAULT instead.

`${VARIABLE:=DEFAULT}'
     Substitute the value of VARIABLE, but if that is empty or
     undefined, use DEFAULT instead and set the variable to DEFAULT.

`${VARIABLE:?MESSAGE}'
     If VARIABLE is defined and not empty, substitute its value.

     Otherwise, print MESSAGE as an error message on the standard error
     stream, and consider word expansion a failure.

`${VARIABLE:+REPLACEMENT}'
     Substitute REPLACEMENT, but only if VARIABLE is defined and
     nonempty.  Otherwise, substitute nothing for this construct.

`${#VARIABLE}'
     Substitute a numeral which expresses in base ten the number of
     characters in the value of VARIABLE.  `${#foo}' stands for `7',
     because `tractor' is seven characters.

   These variants of variable substitution let you remove part of the
variable's value before substituting it.  The PREFIX and SUFFIX are not
mere strings; they are wildcard patterns, just like the patterns that
you use to match multiple file names.  But in this context, they match
against parts of the variable value rather than against file names.

`${VARIABLE%%SUFFIX}'
     Substitute the value of VARIABLE, but first discard from that
     variable any portion at the end that matches the pattern SUFFIX.

     If there is more than one alternative for how to match against
     SUFFIX, this construct uses the longest possible match.

     Thus, `${foo%%r*}' substitutes `t', because the largest match for
     `r*' at the end of `tractor' is `ractor'.

`${VARIABLE%SUFFIX}'
     Substitute the value of VARIABLE, but first discard from that
     variable any portion at the end that matches the pattern SUFFIX.

     If there is more than one alternative for how to match against
     SUFFIX, this construct uses the shortest possible alternative.

     Thus, `${foo%%r*}' substitutes `tracto', because the shortest
     match for `r*' at the end of `tractor' is just `r'.

`${VARIABLE##PREFIX}'
     Substitute the value of VARIABLE, but first discard from that
     variable any portion at the beginning that matches the pattern
     PREFIX.

     If there is more than one alternative for how to match against
     PREFIX, this construct uses the longest possible match.

     Thus, `${foo%%r*}' substitutes `t', because the largest match for
     `r*' at the end of `tractor' is `ractor'.

`${VARIABLE#PREFIX}'
     Substitute the value of VARIABLE, but first discard from that
     variable any portion at the beginning that matches the pattern
     PREFIX.

     If there is more than one alternative for how to match against
     PREFIX, this construct uses the shortest possible alternative.

     Thus, `${foo%%r*}' substitutes `tracto', because the shortest
     match for `r*' at the end of `tractor' is just `r'.


File: libc.info,  Node: I/O Overview,  Next: I/O on Streams,  Prev: Pattern Matching,  Up: Top

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 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:

   * *Note I/O on Streams::, which covers the high-level functions that
     operate on streams, including formatted input and output.

   * *Note Low-Level I/O::, which covers the basic I/O and control
     functions on file descriptors.

   * *Note File System Interface::, which covers functions for
     operating on directories and for manipulating file attributes such
     as access modes and ownership.

   * *Note Pipes and FIFOs::, which includes information on the basic
     interprocess communication facilities.

   * *Note Sockets::, which covers a more complicated interprocess
     communication facility with support for networking.

   * *Note Low-Level Terminal Interface::, which covers functions for
     changing how input and output to terminals or other serial devices
     are processed.

* Menu:

* I/O Concepts::       Some basic information and terminology.
* File Names::         How to refer to a file.


File: libc.info,  Node: I/O Concepts,  Next: File Names,  Up: I/O Overview

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 "opening" the file.  You can open a file for reading,
writing, or both.

   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 "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 Library provides two ways
			             to access the contents of files.
* File Position::                   The number of bytes from the
                                     beginning of the file.


File: libc.info,  Node: Streams and File Descriptors,  Next: File Position,  Up: I/O Concepts

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 `int', while streams are represented
as `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 (*note 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 (*note 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 (`printf' and `scanf') as well as functions
for character- and line-oriented input and output.

   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 (*note Formatted Input::)
and formatted output functions (*note 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 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.


File: libc.info,  Node: File Position,  Prev: Streams and File Descriptors,  Up: I/O Concepts

File Position
-------------

   One of the attributes of an open file is its "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
"sequential".

   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 "random-access" files.  You
can change the file position using the `fseek' function on a stream
(*note File Positioning::) or the `lseek' function on a file descriptor
(*note I/O Primitives::).  If you try to change the file position on a
file that doesn't support random access, you get the `ESPIPE' error.

   Streams and descriptors that are opened for "append access" are
treated specially for output: output to such files is _always_ appended
sequentially to the _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.

   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.


File: libc.info,  Node: File Names,  Prev: I/O Concepts,  Up: I/O Overview

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

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


File: libc.info,  Node: Directories,  Next: File Name Resolution,  Up: File Names

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.

   A "directory" is a file that contains information to associate other
files with names; these associations are called "links" or "directory
entries".  Sometimes, people speak of "files in a directory", but in
reality, a directory only contains pointers to files, not the files
themselves.

   The name of a file contained in a directory entry is called a "file
name component".  In general, a file name consists of a sequence of one
or more such components, separated by the slash character (`/').  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
"pathname" for what we call a file name, and either "filename" or
"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 `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 *Note File System Interface::.


File: libc.info,  Node: File Name Resolution,  Next: File Name Errors,  Prev: Directories,  Up: File Names

File Name Resolution
--------------------

   A file name consists of file name components separated by slash
(`/') characters.  On the systems that the GNU C library supports,
multiple successive `/' characters are equivalent to a single `/'
character.

   The process of determining what file a file name refers to is called
"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.

   If a file name begins with a `/', the first component in the file
name is located in the "root directory" of the process (usually all
processes on the system have the same root directory).  Such a file name
is called an "absolute file name".

   Otherwise, the first component in the file name is located in the
current working directory (*note Working Directory::).  This kind of
file name is called a "relative file name".

   The file name components `.' ("dot") and `..' ("dot-dot") have
special meanings.  Every directory has entries for these file name
components.  The file name component `.' refers to the directory
itself, while the file name component `..' refers to its "parent
directory" (the directory that contains the link for the directory in
question).  As a special case, `..' in the root directory refers to the
root directory itself, since it has no parent; thus `/..' is the same
as `/'.

   Here are some examples of file names:

`/a'
     The file named `a', in the root directory.

`/a/b'
     The file named `b', in the directory named `a' in the root
     directory.

`a'
     The file named `a', in the current working directory.

`/a/./b'
     This is the same as `/a/b'.

`./a'
     The file named `a', in the current working directory.

`../a'
     The file named `a', in the parent directory of the current working
     directory.

   A file name that names a directory may optionally end in a `/'.  You
can specify a file name of `/' 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 `.' or `./'.

   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 `.c'--but there is nothing in the file system
itself that enforces this kind of convention.


File: libc.info,  Node: File Name Errors,  Next: File Name Portability,  Prev: File Name Resolution,  Up: File Names

File Name Errors
----------------

   Functions that accept file name arguments usually detect these
`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 "usual file name errors".

`EACCES'
     The process does not have search permission for a directory
     component of the file name.

`ENAMETOOLONG'
     This error is used when either the total length of a file name is
     greater than `PATH_MAX', or when an individual file name component
     has a length greater than `NAME_MAX'.  *Note 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.

`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.  *Note Symbolic
     Links::.

`ENOTDIR'
     A file that is referenced as a directory component in the file name
     exists, but it isn't a directory.

`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.  *Note Symbolic Links::.


File: libc.info,  Node: File Name Portability,  Prev: File Name Errors,  Up: File Names

Portability of File Names
-------------------------

   The rules for the syntax of file names discussed in *Note File
Names::, are the rules normally used by the GNU system 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:

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

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

   The 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, 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.


File: libc.info,  Node: I/O on Streams,  Next: Low-Level I/O,  Prev: I/O Overview,  Up: Top

Input/Output on Streams
***********************

   This chapter describes the functions for creating streams and
performing input and output operations on them.  As discussed in *Note
I/O Overview::, a stream is a fairly abstract, high-level concept
representing a communications channel to a file, device, or process.

* Menu:

* Streams::                     About the data type representing a stream.
* Standard Streams::            Streams to the standard input and output
                                 devices are created for you.
* Opening Streams::             How to create a stream to talk to a file.
* Closing Streams::             Close a stream when you are finished with it.
* Streams and Threads::         Issues with streams in threaded programs.
* Streams and I18N::            Streams in internationalized applications.
* Simple Output::               Unformatted output by characters and lines.
* Character Input::             Unformatted input by characters and words.
* Line Input::                  Reading a line or a record from a stream.
* Unreading::                   Peeking ahead/pushing back input just read.
* Block Input/Output::          Input and output operations on blocks of data.
* Formatted Output::            `printf' and related functions.
* Customizing Printf::          You can define new conversion specifiers for
                                 `printf' and friends.
* Formatted Input::             `scanf' and related functions.
* EOF and Errors::              How you can tell if an I/O error happens.
* Error Recovery::		What you can do about errors.
* Binary Streams::              Some systems distinguish between text files
                                 and binary files.
* File Positioning::            About random-access streams.
* Portable Positioning::        Random access on peculiar ISO C systems.
* Stream Buffering::            How to control buffering of streams.
* Other Kinds of Streams::      Streams that do not necessarily correspond
                                 to an open file.
* Formatted Messages::          Print strictly formatted messages.


File: libc.info,  Node: Streams,  Next: Standard Streams,  Up: I/O on Streams

Streams
=======

   For historical reasons, the type of the C data structure that
represents a stream is called `FILE' rather than "stream".  Since most
of the library functions deal with objects of type `FILE *', sometimes
the term "file pointer" is also used to mean "stream".  This leads to
unfortunate confusion over terminology in many books on C.  This
manual, however, is careful to use the terms "file" and "stream" only
in the technical sense.

   The `FILE' type is declared in the header file `stdio.h'.

 - Data Type: FILE
     This is the data type used to represent stream objects.  A `FILE'
     object holds all of the internal state information about the
     connection to the associated file, including such things as the
     file position indicator and buffering information.  Each stream
     also has error and end-of-file status indicators that can be
     tested with the `ferror' and `feof' functions; see *Note EOF and
     Errors::.

   `FILE' objects are allocated and managed internally by the
input/output library functions.  Don't try to create your own objects of
type `FILE'; let the library do it.  Your programs should deal only
with pointers to these objects (that is, `FILE *' values) rather than
the objects themselves.


File: libc.info,  Node: Standard Streams,  Next: Opening Streams,  Prev: Streams,  Up: I/O on Streams

Standard Streams
================

   When the `main' function of your program is invoked, it already has
three predefined streams open and available for use.  These represent
the "standard" input and output channels that have been established for
the process.

   These streams are declared in the header file `stdio.h'.

 - Variable: FILE * stdin
     The "standard input" stream, which is the normal source of input
     for the program.

 - Variable: FILE * stdout
     The "standard output" stream, which is used for normal output from
     the program.

 - Variable: FILE * stderr
     The "standard error" stream, which is used for error messages and
     diagnostics issued by the program.

   In the GNU system, you can specify what files or processes
correspond to these streams using the pipe and redirection facilities
provided by the shell.  (The primitives shells use to implement these
facilities are described in *Note File System Interface::.)  Most other
operating systems provide similar mechanisms, but the details of how to
use them can vary.

   In the GNU C library, `stdin', `stdout', and `stderr' are normal
variables which you can set just like any others.  For example, to
redirect the standard output to a file, you could do:

     fclose (stdout);
     stdout = fopen ("standard-output-file", "w");

   Note however, that in other systems `stdin', `stdout', and `stderr'
are macros that you cannot assign to in the normal way.  But you can
use `freopen' to get the effect of closing one and reopening it.  *Note
Opening Streams::.

   The three streams `stdin', `stdout', and `stderr' are not unoriented
at program start (*note Streams and I18N::).


File: libc.info,  Node: Opening Streams,  Next: Closing Streams,  Prev: Standard Streams,  Up: I/O on Streams

Opening Streams
===============

   Opening a file with the `fopen' function creates a new stream and
establishes a connection between the stream and a file.  This may
involve creating a new file.

   Everything described in this section is declared in the header file
`stdio.h'.

 - Function: FILE * fopen (const char *FILENAME, const char *OPENTYPE)
     The `fopen' function opens a stream for I/O to the file FILENAME,
     and returns a pointer to the stream.

     The OPENTYPE argument is a string that controls how the file is
     opened and specifies attributes of the resulting stream.  It must
     begin with one of the following sequences of characters:

    `r'
          Open an existing file for reading only.

    `w'
          Open the file for writing only.  If the file already exists,
          it is truncated to zero length.  Otherwise a new file is
          created.

    `a'
          Open a file for append access; that is, writing at the end of
          file only.  If the file already exists, its initial contents
          are unchanged and output to the stream is appended to the end
          of the file.  Otherwise, a new, empty file is created.

    `r+'
          Open an existing file for both reading and writing.  The
          initial contents of the file are unchanged and the initial
          file position is at the beginning of the file.

    `w+'
          Open a file for both reading and writing.  If the file
          already exists, it is truncated to zero length.  Otherwise, a
          new file is created.

    `a+'
          Open or create file for both reading and appending.  If the
          file exists, its initial contents are unchanged.  Otherwise,
          a new file is created.  The initial file position for reading
          is at the beginning of the file, but output is always
          appended to the end of the file.

     As you can see, `+' requests a stream that can do both input and
     output.  The ISO standard says that when using such a stream, you
     must call `fflush' (*note Stream Buffering::) or a file positioning
     function such as `fseek' (*note File Positioning::) when switching
     from reading to writing or vice versa.  Otherwise, internal buffers
     might not be emptied properly.  The GNU C library does not have
     this limitation; you can do arbitrary reading and writing
     operations on a stream in whatever order.

     Additional characters may appear after these to specify flags for
     the call.  Always put the mode (`r', `w+', etc.) first; that is
     the only part you are guaranteed will be understood by all systems.

     The GNU C library defines one additional character for use in
     OPENTYPE: the character `x' insists on creating a new file--if a
     file FILENAME already exists, `fopen' fails rather than opening
     it.  If you use `x' you are guaranteed that you will not clobber
     an existing file.  This is equivalent to the `O_EXCL' option to
     the `open' function (*note Opening and Closing Files::).

     The character `b' in OPENTYPE has a standard meaning; it requests
     a binary stream rather than a text stream.  But this makes no
     difference in POSIX systems (including the GNU system).  If both
     `+' and `b' are specified, they can appear in either order.  *Note
     Binary Streams::.

     If the OPENTYPE string contains the sequence `,ccs=STRING' then
     STRING is taken as the name of a coded character set and `fopen'
     will mark the stream as wide-oriented which appropriate conversion
     functions in place to convert from and to the character set STRING
     is place.  Any other stream is opened initially unoriented and the
     orientation is decided with the first file operation.  If the
     first operation is a wide character operation, the stream is not
     only marked as wide-oriented, also the conversion functions to
     convert to the coded character set used for the current locale are
     loaded.  This will not change anymore from this point on even if
     the locale selected for the `LC_CTYPE' category is changed.

     Any other characters in OPENTYPE are simply ignored.  They may be
     meaningful in other systems.

     If the open fails, `fopen' returns a null pointer.

     When the sources are compiling with `_FILE_OFFSET_BITS == 64' on a
     32 bit machine this function is in fact `fopen64' since the LFS
     interface replaces transparently the old interface.

   You can have multiple streams (or file descriptors) pointing to the
same file open at the same time.  If you do only input, this works
straightforwardly, but you must be careful if any output streams are
included.  *Note Stream/Descriptor Precautions::.  This is equally true
whether the streams are in one program (not usual) or in several
programs (which can easily happen).  It may be advantageous to use the
file locking facilities to avoid simultaneous access.  *Note File
Locks::.

 - Function: FILE * fopen64 (const char *FILENAME, const char *OPENTYPE)
     This function is similar to `fopen' but the stream it returns a
     pointer for is opened using `open64'.  Therefore this stream can be
     used even on files larger then 2^31 bytes on 32 bit machines.

     Please note that the return type is still `FILE *'.  There is no
     special `FILE' type for the LFS interface.

     If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a 32
     bits machine this function is available under the name `fopen' and
     so transparently replaces the old interface.

 - Macro: int FOPEN_MAX
     The value of this macro is an integer constant expression that
     represents the minimum number of streams that the implementation
     guarantees can be open simultaneously.  You might be able to open
     more than this many streams, but that is not guaranteed.  The
     value of this constant is at least eight, which includes the three
     standard streams `stdin', `stdout', and `stderr'.  In POSIX.1
     systems this value is determined by the `OPEN_MAX' parameter;
     *note General Limits::.  In BSD and GNU, it is controlled by the
     `RLIMIT_NOFILE' resource limit; *note Limits on Resources::.

 - Function: FILE * freopen (const char *FILENAME, const char
          *OPENTYPE, FILE *STREAM)
     This function is like a combination of `fclose' and `fopen'.  It
     first closes the stream referred to by STREAM, ignoring any errors
     that are detected in the process.  (Because errors are ignored,
     you should not use `freopen' on an output stream if you have
     actually done any output using the stream.)  Then the file named by
     FILENAME is opened with mode OPENTYPE as for `fopen', and
     associated with the same stream object STREAM.

     If the operation fails, a null pointer is returned; otherwise,
     `freopen' returns STREAM.

     `freopen' has traditionally been used to connect a standard stream
     such as `stdin' with a file of your own choice.  This is useful in
     programs in which use of a standard stream for certain purposes is
     hard-coded.  In the GNU C library, you can simply close the
     standard streams and open new ones with `fopen'.  But other
     systems lack this ability, so using `freopen' is more portable.

     When the sources are compiling with `_FILE_OFFSET_BITS == 64' on a
     32 bit machine this function is in fact `freopen64' since the LFS
     interface replaces transparently the old interface.

 - Function: FILE * freopen64 (const char *FILENAME, const char
          *OPENTYPE, FILE *STREAM)
     This function is similar to `freopen'.  The only difference is that
     on 32 bit machine the stream returned is able to read beyond the
     2^31 bytes limits imposed by the normal interface.  It should be
     noted that the stream pointed to by STREAM need not be opened
     using `fopen64' or `freopen64' since its mode is not important for
     this function.

     If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a 32
     bits machine this function is available under the name `freopen'
     and so transparently replaces the old interface.

   In some situations it is useful to know whether a given stream is
available for reading or writing.  This information is normally not
available and would have to be remembered separately.  Solaris
introduced a few functions to get this information from the stream
descriptor and these functions are also available in the GNU C library.

 - Function: int __freadable (FILE *STREAM)
     The `__freadable' function determines whether the stream STREAM
     was opened to allow reading.  In this case the return value is
     nonzero.  For write-only streams the function returns zero.

     This function is declared in `stdio_ext.h'.

 - Function: int __fwritable (FILE *STREAM)
     The `__fwritable' function determines whether the stream STREAM
     was opened to allow writing.  In this case the return value is
     nonzero.  For read-only streams the function returns zero.

     This function is declared in `stdio_ext.h'.

   For slightly different kind of problems there are two more functions.
They provide even finer-grained information.

 - Function: int __freading (FILE *STREAM)
     The `__freading' function determines whether the stream STREAM was
     last read from or whether it is opened read-only.  In this case
     the return value is nonzero, otherwise it is zero.  Determining
     whether a stream opened for reading and writing was last used for
     writing allows to draw conclusions about the content about the
     buffer, among other things.

     This function is declared in `stdio_ext.h'.

 - Function: int __fwriting (FILE *STREAM)
     The `__fwriting' function determines whether the stream STREAM was
     last written to or whether it is opened write-only.  In this case
     the return value is nonzero, otherwise it is zero.

     This function is declared in `stdio_ext.h'.


File: libc.info,  Node: Closing Streams,  Next: Streams and Threads,  Prev: Opening Streams,  Up: I/O on Streams

Closing Streams
===============

   When a stream is closed with `fclose', the connection between the
stream and the file is canceled.  After you have closed a stream, you
cannot perform any additional operations on it.

 - Function: int fclose (FILE *STREAM)
     This function causes STREAM to be closed and the connection to the
     corresponding file to be broken.  Any buffered output is written
     and any buffered input is discarded.  The `fclose' function returns
     a value of `0' if the file was closed successfully, and `EOF' if
     an error was detected.

     It is important to check for errors when you call `fclose' to close
     an output stream, because real, everyday errors can be detected at
     this time.  For example, when `fclose' writes the remaining
     buffered output, it might get an error because the disk is full.
     Even if you know the buffer is empty, errors can still occur when
     closing a file if you are using NFS.

     The function `fclose' is declared in `stdio.h'.

   To close all streams currently available the GNU C Library provides
another function.

 - Function: int fcloseall (void)
     This function causes all open streams of the process to be closed
     and the connection to corresponding files to be broken.  All
     buffered data is written and any buffered input is discarded.  The
     `fcloseall' function returns a value of `0' if all the files were
     closed successfully, and `EOF' if an error was detected.

     This function should be used only in special situations, e.g.,
     when an error occurred and the program must be aborted.  Normally
     each single stream should be closed separately so that problems
     with individual streams can be identified.  It is also problematic
     since the standard streams (*note Standard Streams::) will also be
     closed.

     The function `fcloseall' is declared in `stdio.h'.

   If the `main' function to your program returns, or if you call the
`exit' function (*note Normal Termination::), all open streams are
automatically closed properly.  If your program terminates in any other
manner, such as by calling the `abort' function (*note Aborting a
Program::) or from a fatal signal (*note Signal Handling::), open
streams might not be closed properly.  Buffered output might not be
flushed and files may be incomplete.  For more information on buffering
of streams, see *Note Stream Buffering::.

