   This file documents the GNU C library.

   This is Edition 0.03, last updated 19 May 1993, of
`The GNU C Library Reference Manual', for Version 1.06 Beta.

   Copyright (C) 1993 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU Library General Public License" is
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the text of the translations of the section
entitled "GNU Library General Public License" must be approved for
accuracy by the Foundation.

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, 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
(see File Positioning.) or the `lseek' function on a file
descriptor (see I/O Primitives.).  If you try to change the file
position on a file that doesn't support random access, you get an 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.
 But, 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 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.

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.

   You can find more detailed information about operations on
directories in File System Interface.

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

   A file name consists of file name components separated by slash
(`/') characters.  On the systems that that GNU 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.  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 (see 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).

   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 Name Errors
----------------

   Functions that accept file name arguments usually detect these
`errno' error conditions relating to file name syntax.  These errors
are referred to throughout this manual as the "usual file name syntax
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 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'.  See 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.

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

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

   The rules for the syntax of file names discussed in 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 ANSI 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.

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

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

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

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

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

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

 -- Macro: 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 File System Interface.)  Most other
operating systems provide similar mechanisms, but the details of how to
use them can vary.

   It is probably not a good idea to close any of the standard streams.
But you can use `freopen' to get te effect of closing one and reopening
it.  See Opening 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 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 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 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
          might be at either the beginning or end 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.  When using such a stream, you must call `fflush' (see
     Stream Buffering.) or a file positioning function such as
     `fseek' (see File Positioning.) when switching from reading to
     writing or vice versa.  Otherwise, internal buffers might not be
     emptied properly.

     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.  This is equivalent to the `O_EXCL' option to the `open'
     function (see File Status Flags.).

     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. See
     Binary Streams.

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

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

   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.  See 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.  See File Locks.

 -- 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.  The value of this constant
     is at least eight, which includes the three standard streams
     `stdin', `stdout', and `stderr'.

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

     The main use of `freopen' is to connect a standard stream such as
     `stdir' 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.

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

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

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

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

Simple Output by Characters or Lines
====================================

   This section describes functions for performing character- and
line-oriented output.  Largely for historical compatibility, there are
several variants of these functions, but as a matter of style (and for
simplicity!) we suggest you stick with using `fputc' and `fputs', and
perhaps `putc' and `putchar'.

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

 -- Function: int fputc (int C, FILE *STREAM)
     The `fputc' function converts the character C to type `unsigned
     char', and writes it to the stream STREAM. `EOF' is returned if a
     write error occurs; otherwise the character C is returned.

 -- Function: int putc (int C, FILE *STREAM)
     This is just like `fputc', except that most systems implement it as
     a macro, making it faster.  One consequence is that it may
     evaluate the STREAM argument more than once.

 -- Function: int putchar (int C)
     The `putchar' function is equivalent to `fputc' with `stdout' as
     the value of the STREAM argument.

 -- Function: int fputs (const char *S, FILE *STREAM)
     The function `fputs' writes the string S to the stream STREAM.
     The terminating null character is not written. This function does
     *not* add a newline character, either. It outputs only the chars
     in the string.

     This function returns `EOF' if a write error occurs, and otherwise
     a non-negative value.

     For example:

          fputs ("Are ", stdout);
          fputs ("you ", stdout);
          fputs ("hungry?\n", stdout);

     outputs the text `Are you hungry?' followed by a newline.

 -- Function: int puts (const char *S)
     The `puts' function writes the string S to the stream `stdout'
     followed by a newline.  The terminating null character of the
     string is not written.

 -- Function: int putw (int W, FILE *STREAM)
     This function writes the word W (that is, an `int') to STREAM.  It
     is provided for compatibility with SVID, but we recommend you use
     `fwrite' instead (see Block Input/Output.).

Character Input
===============

   This section describes functions for performing character- and
line-oriented input.  Again, there are several variants of these
functions, some of which are considered obsolete stylistically.  It's
suggested that you stick with `fgetc', `getline', and maybe `getc',
`getchar' and `fgets'.

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

 -- Function: int fgetc (FILE *STREAM)
     This function reads the next character as an `unsigned char' from
     the stream STREAM and returns its value, converted to an `int'.
     If an end-of-file condition or read error occurs, `EOF' is
     returned instead.

 -- Function: int getc (FILE *STREAM)
     This is just like `fgetc', except that it is permissible (and
     typical) for it to be implemented as a macro that evaluates the
     STREAM argument more than once.

 -- Function: int getchar (void)
     The `getchar' function is equivalent to `fgetc' with `stdin' as
     the value of the STREAM argument.

   Here is an example of a function that does input using `fgetc'.  It
would work just as well using `getc' instead, or using `getchar ()'
instead of `fgetc (stdin)'.

     int
     y_or_n_p (const char *question)
     {
       fputs (question, stdout);
       while (1) {
         int c, answer;
         /* Write a space to separate answer from question. */
         fputc (' ', stdout);
         /* Read the first character of the line.
            This should be the answer character, but might not be. */
         c = tolower (fgetc (stdin));
         answer = c;
         /* Discard rest of input line. */
         while (c != '\n')
           c = fgetc (stdin);
         /* Obey the answer if it was valid. */
         if (answer == 'y')
           return 1;
         if (answer == 'n')
           return 0;
         /* Answer was invalid: ask for valid answer. */
         fputs ("Please answer y or n:", stdout);
       }
     }

 -- Function: int getw (FILE *STREAM)
     This function reads a word (that is, an `int') from STREAM. It's
     provided for compatibility with SVID.  We recommend you use
     `fread' instead (see Block Input/Output.).

Line-Oriented Input
===================

   Since many programs interpret input on the basis of lines, it's
convenient to have functions to read a line of text from a stream.

   Standard C has functions to do this, but they aren't very safe: null
characters and even (for `gets') long lines can confuse them.  So the
GNU library provides the nonstandard `getline' function that makes it
easy to read lines reliably.

   Another GNU extension, `getdelim', generalizes `getline'.  It reads
a delimited record, defined as everything through the next occurrence
of a specified delimeter character.

   All these functions are declared in `stdio.h'.

 -- Function: ssize_t getline (char **LINEPTR, size_t *N, FILE *STREAM)
     This function reads an entire line from STREAM, storing the text
     (including the newline and a terminating null character) in a
     buffer and storing the buffer address in `*LINEPTR'.

     Before calling `getline', you should place in `*LINEPTR' the
     address of a buffer `*N' bytes long.  If this buffer is long
     enough to hold the line, `getline' stores the line in this buffer.
      Otherwise, `getline' makes the buffer bigger using `realloc',
     storing the new buffer address back in `*LINEPTR' and the
     increased size back in `*N'.

     In either case, when `getline' returns,  `*LINEPTR' is a `char *'
     which points to the text of the line.

     When `getline' is successful, it returns the number of characters
     read (including the newline, but not including the terminating
     null). This value enables you to distinguish null characters that
     are part of the line from the null character inserted as a
     terminator.

     This function is a GNU extension, but it is the recommended way to
     read lines from a stream.  The alternative standard functions are
     unreliable.

     If an error occurs or end of file is reached, `getline' returns
     `-1'.

 -- Function: ssize_t getdelim (char **LINEPTR, size_t *N, int
          DELIMITER, FILE *STREAM)
     This function is like `getline' except that the character which
     tells it to stop reading is not necessarily newline.  The argument
     DELIMETER specifies the delimeter character; `getdelim' keeps
     reading until it sees that character (or end of file).

     The text is stored in LINEPTR, including the delimeter character
     and a terminating null.  Like `getline', `getdelim' makes LINEPTR
     bigger if it isn't big enough.

 -- Function: char * fgets (char *S, int COUNT, FILE *STREAM)
     The `fgets' function reads characters from the stream STREAM up to
     and including a newline character and stores them in the string S,
     adding a null character to mark the end of the string.  You must
     supply COUNT characters worth of space in S, but the number of
     characters read is at most COUNT - 1.  The extra character space
     is used to hold the null character at the end of the string.

     If the system is already at end of file when you call `fgets', then
     the contents of the array S are unchanged and a null pointer is
     returned.  A null pointer is also returned if a read error occurs.
     Otherwise, the return value is the pointer S.

     *Warning:*  If the input data has a null character, you can't tell.
     So don't use `fgets' unless you know the data cannot contain a
     null. Don't use it to read files edited by the user because, if
     the user inserts a null character, you should either handle it
     properly or print a clear error message.  We recommend using
     `getline' instead of `fgets'.

 -- Deprecated function: char * gets (char *S)
     The function `gets' reads characters from the stream `stdin' up to
     the next newline character, and stores them in the string S. The
     newline character is discarded (note that this differs from the
     behavior of `fgets', which copies the newline character into the
     string).

     *Warning:*  The `gets' function is *very dangerous* because it
     provides no protection against overflowing the string S. The GNU
     library includes it for compatibility only.  You should *always*
     use `fgets' or `getline' instead.

Unreading
=========

   In parser programs it is often useful to examine the next character
in the input stream without removing it from the stream.  This is called
"peeking ahead" at the input because your program gets a glimpse of the
input it will read next.

   Using stream I/O, you can peek ahead at input by first reading it and
then "unreading" it (also called  "pushing it back" on the stream).
Unreading a character makes it available to be input again from the
stream, by  the next call to `fgetc' or other input function on that
stream.

What Unreading Means
--------------------

   Here is a pictorial explanation of unreading.  Suppose you have a
stream reading a file that contains just six characters, the letters
`foobar'.  Suppose you have read three characters so far.  The
situation looks like this:

     f  o  o  b  a  r
              ^

so the next input character will be `b'.

   If instead of reading `b' you unread the letter `o', you get a
situation like this:

     f  o  o  b  a  r
              |
           o--
           ^

so that the next input characters will be `o' and `b'.

   If you unread `9' instead of `o', you get this situation:

     f  o  o  b  a  r
              |
           9--
           ^

so that the next input characters will be `9' and `b'.

Using `ungetc' To Do Unreading
------------------------------

   The function to unread a character is called `ungetc', because it
reverses the action of `fgetc'.

 -- Function: int ungetc (int C, FILE *STREAM)
     The `ungetc' function pushes back the character C onto the input
     stream STREAM.  So the next input from STREAM will read C before
     anything else.

     The character that you push back doesn't have to be the same as
     the last character that was actually read from the stream.  In
     fact, it isn't necessary to actually read any characters from the
     stream before unreading them with `ungetc'!  But that is a strange
     way to write a program; usually `ungetc' is used only to unread a
     character that was just read from the same stream.

     The GNU C library only supports one character of pushback--in other
     words, it does not work to call `ungetc' twice without doing input
     in between.  Other systems might let you push back multiple
     characters; then reading from the stream retrieves the characters
     in the reverse order that they were pushed.

     Pushing back characters doesn't alter the file; only the internal
     buffering for the stream is affected.  If a file positioning
     function (such as `fseek' or `rewind'; see File Positioning.)
     is called, any pending pushed-back characters are discarded.

     Unreading a character on a stream that is at end of file clears the
     end-of-file indicator for the stream, because it makes the
     character of input available.  Reading that character will set the
     end-of-file indicator again.

   Here is an example showing the use of `getc' and `ungetc' to skip
over whitespace characters.  When this function reaches a
non-whitespace character, it unreads that character to be seen again on
the next read operation on the stream.

     #include <stdio.h>

     void
     skip_whitespace (FILE *stream)
     {
       int c;
       do
         /* No need to check for `EOF' because it is not
            `isspace', and `ungetc' ignores `EOF'.  */
         c = getc (stream);
       while (isspace (c));
       ungetc (c, stream);
     }

Formatted Output
================

   The functions described in this section (`printf' and related
functions) provide a convenient way to perform formatted output.  You
call `printf' with a "format string" or "template string" that
specifies how to format the values of the remaining arguments.

   Unless your program is a filter that specifically performs line- or
character-oriented processing, using `printf' or one of the other
related functions described in this section is usually the easiest and
most concise way to perform output.  These functions are especially
useful for printing error messages, tables of data, and the like.

Formatted Output Basics
-----------------------

   The `printf' function can be used to print any number of arguments.
The template string argument you supply in a call provides information
not only about the number of additional arguments, but also about their
types and what style should be used for printing them.

   Ordinary characters in the template string are simply written to the
output stream as-is, while "conversion specifications" introduced by a
`%' character in the template cause subsequent arguments to be
formatted and written to the output stream.  For example,

     int pct = 37;
     char filename[] = "foo.txt";
     printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
             filename, pct);

produces output like

     Processing of `foo.txt' is 37% finished.
     Please be patient.

   This example shows the use of the `%d' conversion to specify that an
`int' argument should be printed in decimal notation, the `%s'
conversion to specify printing of a string argument, and the `%%'
conversion to print a literal `%' character.

   There are also conversions for printing an integer argument as an
unsigned value in octal, decimal, or hexadecimal radix (`%o', `%u', or
`%x', respectively); or as a character value (`%c').

   Floating-point numbers can be printed in normal, fixed-point notation
using the `%f' conversion or in exponential notation using the `%e'
conversion.  The `%g' conversion uses either `%e' or `%f' format,
depending on what is more appropriate for the magnitude of the
particular number.

   You can control formatting more precisely by writing "modifiers"
between the `%' and the character that indicates which conversion to
apply.  These slightly alter the ordinary behavior of the conversion.
For example, most conversion specifications permit you to specify a
minimum field width and a flag indicating whether you want the result
left- or right-justified within the field.

   The specific flags and modifiers that are permitted and their
interpretation vary depending on the particular conversion.  They're all
described in more detail in the following sections.  Don't worry if this
all seems excessively complicated at first; you can almost always get
reasonable free-format output without using any of the modifiers at all.
The modifiers are mostly used to make the output look "prettier" in
tables.

Output Conversion Syntax
------------------------

   This section provides details about the precise syntax of conversion
specifications that can appear in a `printf' template string.

   Characters in the template string that are not part of a conversion
specification are printed as-is to the output stream. Multibyte
character sequences (see Extended Characters.) are permitted in a
template string.

   The conversion specifications in a `printf' template string have the
general form:

     % FLAGS WIDTH [ . PRECISION ] TYPE CONVERSION

   For example, in the conversion specifier `%-10.8ld', the `-' is a
flag, `10' specifies the field width, the precision is `8', the letter
`l' is a type modifier, and `d' specifies the conversion style.  (This
particular type specifier says to print a `long int' argument in
decimal notation, with a minimum of 8 digits left-justified in a field
at least 10 characters wide.)

   In more detail, output conversion specifications consist of an
initial `%' character followed in sequence by:

   * Zero or more "flag characters" that modify the normal behavior of
     the conversion specification.

   * An optional decimal integer specifying the "minimum field width".
     If the normal conversion produces fewer characters than this, the
     field is padded with spaces to the specified width.  This is a
     *minimum* value; if the normal conversion produces more characters
     than this, the field is *not* truncated.  Normally, the output is
     right-justified within the field.

     The GNU library's version of `printf' also allows you to specify a
     field width of `*'.  This means that the next argument in the
     argument list (before the actual value to be printed) is used as
     the field width.  The value must be an `int'.  Other C library
     versions may not recognize this syntax.

   * An optional "precision" to specify the number of digits to be
     written for the numeric conversions.  If the precision is
     specified, it consists of a period (`.') followed optionally by a
     decimal integer (which defaults to zero if omitted).

     The GNU library's version of `printf' also allows you to specify a
     precision of `*'.  This means that the next argument in the
     argument list (before the actual value to be printed) is used as
     the precision.  The value must be an `int'.  If you specify `*'
     for both the field width and precision, the field width argument
     precedes the precision argument.  Other C library versions may not
     recognize this syntax.

   * An optional "type modifier character", which is used to specify the
     data type of the corresponding argument if it differs from the
     default type.  (For example, the integer conversions assume a type
     of `int', but you can specify `h', `l', or `L' for other integer
     types.)

   * A character that specifies the conversion to be applied.

   The exact options that are permitted and how they are interpreted
vary between the different conversion specifiers.  See the descriptions
of the individual conversions for information about the particular
options that they use.

Table of Output Conversions
---------------------------

   Here is a table summarizing what all the different conversions do:

`%d', `%i'
     Print an integer as a signed decimal number.  See Integer Conversions,
     for details.  `%d' and `%i' are synonymous for
     output, but are different when used with `scanf' for input (see
     Table of Input Conversions.).

`%o'
     Print an integer as an unsigned octal number.  See Integer Conversions,
     for details.

`%u'
     Print an integer as an unsigned decimal number.  See Integer Conversions,
     for details.

`%Z'
     Print an integer as an unsigned decimal number, assuming it was
     passed with type `size_t'.  See Integer Conversions, for
     details.

`%x', `%X'
     Print an integer as an unsigned hexadecimal number.  `%x' uses
     lower-case letters and `%X' uses upper-case.  See Integer Conversions,
     for details.

`%f'
     Print a floating-point number in normal (fixed-point) notation.
     See Floating-Point Conversions, for details.

`%e', `%E'
     Print a floating-point number in exponential notation.  `%e' uses
     lower-case letters and `%E' uses upper-case.  See Floating-Point Conversions,
     for details.

`%g', `%G'
     Print a floating-point number in either normal or exponential
     notation, whichever is more appropriate for its magnitude.  `%g'
     uses lower-case letters and `%G' uses upper-case.  See
     Floating-Point Conversions, for details.

`%c'
     Print a single character.  See Other Output Conversions.

`%s'
     Print a string.  See Other Output Conversions.

`%p'
     Print the value of a pointer.  See Other Output Conversions.

`%n'
     Get the number of characters printed so far.  See Other Output Conversions.
     Note that this conversion specification never
     produces any output.

`%m'
     Print the string corresponding to the value of `errno'. See
     Other Output Conversions.

`%%'
     Print a literal `%' character.  See Other Output Conversions.

   If the syntax of a conversion specification is invalid, unpredictable
things will happen, so don't do this.  If there aren't enough function
arguments provided to supply values for all the conversion
specifications in the template string, or if the arguments are not of
the correct types, the results are unpredictable.  If you supply more
arguments than conversion specifications, the extra argument values are
simply ignored; this is sometimes useful.

Integer Conversions
-------------------

   This section describes the options for the `%d', `%i', `%o', `%u',
`%x', `%X', and `%Z' conversion specifications.  These conversions
print integers in various formats.

   The `%d' and `%i' conversion specifications both print an `int'
argument as a signed decimal number; while `%o', `%u', and `%x' print
the argument as an unsigned octal, decimal, or hexadecimal number
(respectively).  The `%X' conversion specification is just like `%x'
except that it uses the characters `ABCDEF' as digits instead of
`abcdef'.  `%Z' is like `%u' but expects an argument of type `size_t'.

   The following flags are meaningful:

`-'
     Left-justify the result in the field (instead of the normal
     right-justification).

`+'
     For the signed `%d' and `%i' conversions, print a plus sign if the
     value is positive.

` '
     For the signed `%d' and `%i' conversions, if the result doesn't
     start with a plus or minus sign, prefix it with a space character
     instead.  Since the `+' flag ensures that the result includes a
     sign, this flag is ignored if you supply both of them.

`#'
     For the `%o' conversion, this forces the leading digit to be `0',
     as if by increasing the precision.  For `%x' or `%X', this
     prefixes a leading `0x' or `0X' (respectively) to the result. This
     doesn't do anything useful for the `%d', `%i', or `%u' conversions.

`0'
     Pad the field with zeros instead of spaces.  The zeros are placed
     after any indication of sign or base.  This flag is ignored if the
     `-' flag is also specified, or if a precision is specified.

   If a precision is supplied, it specifies the minimum number of
digits to appear; leading zeros are produced if necessary.  If you
don't specify a precision, the number is printed with as many digits as
it needs.  If you convert a value of zero with an explicit precision of
zero, then no characters at all are produced.

   Without a type modifier, the corresponding argument is treated as an
`int' (for the signed conversions `%i' and `%d') or `unsigned int' (for
the unsigned conversions `%o', `%u', `%x', and `%X').  Recall that
since `printf' and friends are variadic, any `char' and `short'
arguments are automatically converted to `int' by the default argument
promotions.  For arguments of other integer types, you can use these
modifiers:

`h'
     Specifies that the argument is a `short int' or `unsigned short
     int', as appropriate.  A `short' argument is converted to an `int'
     or `unsigned int' by the default argument promotions anyway, but
     the `h' modifier says to convert it back to a `short' again.

`l'
     Specifies that the argument is a `long int' or `unsigned long
     int', as appropriate.

`L'
     Specifies that the argument is a `long long int'.  (This type is
     an extension supported by the GNU C compiler.  On systems that
     don't support extra-long integers, this is the same as `long int'.)

   The modifiers for argument type are not applicable to `%Z', since
the sole purpose of `%Z' is to specify the data type `size_t'.

   Here is an example.  Using the template string:

     |%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"

to print numbers using the different options for the `%d' conversion
gives results like:

     |    0|0    |   +0|+0   |    0|00000|     |   00|0|
     |    1|1    |   +1|+1   |    1|00001|    1|   01|1|
     |   -1|-1   |   -1|-1   |   -1|-0001|   -1|  -01|-1|
     |100000|100000|+100000| 100000|100000|100000|100000|100000|

   In particular, notice what happens in the last case where the number
is too large to fit in the minimum field width specified.

   Here are some more examples showing how unsigned integers print under
various format options, using the template string:

     "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"

     |    0|    0|    0|    0|    0|  0x0|  0X0|0x00000000|
     |    1|    1|    1|    1|   01|  0x1|  0X1|0x00000001|
     |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|