oldlinux-files/gnu/glibc/glibc-1.06.html

<!-- This HTML file has been created by texi2html 1.27
     from library.texinfo on 2 March 1994 -->

<TITLE>The GNU C Library</TITLE>
<H1>The GNU C Library</H1>
<P>
@shorttitlepage The GNU C Library Reference Manual
The GNU C Library
<P>
Reference Manual
<P>
Sandra Loosemore
with
Roland McGrath, Andrew Oram, and Richard M. Stallman
<P>
last updated 9 April 1993
<P>
for version 1.06 Beta
Copyright (C) 1993 Free Software Foundation, Inc.
<P>
<H1><A NAME="SEC1" HREF="library_toc.html#SEC1">Introduction</A></H1>
<P>
The C language provides no built-in facilities for performing such
common operations as input/output, memory management, string
manipulation, and the like.  Instead, these facilities are defined
in a standard <DFN>library</DFN>, which you compile and link with your
programs.
<A NAME="IDX1"></A>
<P>
The GNU C library, described in this document, defines all of the
library functions that are specified by the ANSI C standard, as well as
additional features specific to POSIX and other derivatives of the Unix
operating system, and extensions specific to the GNU system.
<P>
The purpose of this manual is to tell you how to use the facilities
of the GNU library.  We have mentioned which features belong to which
standards to help you identify things that are potentially nonportable
to other systems.  But the emphasis on this manual is not on strict
portability.
<P>
<H2><A NAME="SEC2" HREF="library_toc.html#SEC2">Getting Started</A></H2>
<P>
This manual is written with the assumption that you are at least
somewhat familiar with the C programming language and basic programming
concepts.  Specifically, familiarity with ANSI standard C
(see section <A HREF="library.html#SEC4">ANSI C</A>), rather than "traditional" pre-ANSI C dialects, is
assumed.
<P>
The GNU C library includes several <DFN>header files</DFN>, each of which
provides definitions and declarations for a group of related facilities;
this information is used by the C compiler when processing your program.
For example, the header file <TT>`stdio.h'</TT> declares facilities for
performing input and output, and the header file <TT>`string.h'</TT>
declares string processing utilities.  The organization of this manual
generally follows the same division as the header files.
<P>
If you are reading this manual for the first time, you should read all
of the introductory material and skim the remaining chapters.  There are
a <EM>lot</EM> of functions in the GNU C library and it's not realistic to
expect that you will be able to remember exactly <EM>how</EM> to use each
and every one of them.  It's more important to become generally familiar
with the kinds of facilities that the library provides, so that when you
are writing your programs you can recognize <EM>when</EM> to make use of
library functions, and <EM>where</EM> in this manual you can find more
specific information about them.
<P>
<A NAME="IDX2"></A>
<H2><A NAME="SEC3" HREF="library_toc.html#SEC3">Standards and Portability</A></H2>
<P>
This section discusses the various standards and other sources that the
GNU C library is based upon.  These sources include the ANSI C and
POSIX standards, and the System V and Berkeley Unix implementations.
<P>
The primary focus of this manual is to tell you how to make effective
use of the GNU library facilities.  But if you are concerned about
making your programs compatible with these standards, or portable to
operating systems other than GNU, this can affect how you use the
library.  This section gives you an overview of these standards, so that
you will know what they are when they are mentioned in other parts of
the manual.
<P>
See section <A HREF="library.html#SEC492">Summary of Library Facilities</A>, for an alphabetical list of the functions and
other symbols provided by the library.  This list also states which
standards each function or symbol comes from.
<P>
<A NAME="IDX3"></A>
<H3><A NAME="SEC4" HREF="library_toc.html#SEC4">ANSI C</A></H3>
<P>
The GNU C library is compatible with the C standard adopted by the
American National Standards Institute (ANSI):
<CITE>American National Standard X3.159-1989---"ANSI C"</CITE>.
The header files and library facilities that make up the GNU library are
a superset of those specified by the ANSI C standard.<A NAME="IDX4"></A>
<P>
If you are concerned about strict adherence to the ANSI C standard, you
should use the <SAMP>`-ansi'</SAMP> option when you compile your programs with
the GNU C compiler.  This tells the compiler to define <EM>only</EM> ANSI
standard features from the library header files, unless you explicitly
ask for additional features.  See section <A HREF="library.html#SEC12">Feature Test Macros</A>, for
information on how to do this.
<P>
Being able to restrict the library to include only ANSI C features is
important because ANSI C puts limitations on what names can be defined
by the library implementation, and the GNU extensions don't fit these
limitations.  See section <A HREF="library.html#SEC11">Reserved Names</A>, for more information about these
restrictions.
<P>
This manual does not attempt to give you complete details on the
differences between ANSI C and older dialects.  It gives advice on how
to write programs to work portably under multiple C dialects, but does
not aim for completeness.
<P>
<A NAME="IDX5"></A>
<A NAME="IDX6"></A>
<A NAME="IDX7"></A>
<A NAME="IDX8"></A>
<A NAME="IDX9"></A>
<H3><A NAME="SEC5" HREF="library_toc.html#SEC5">POSIX (The Portable Operating System Interface)</A></H3>
<P>
The GNU library is also compatible with the IEEE <DFN>POSIX</DFN> family of
standards, known more formally as the <DFN>Portable Operating System
Interface for Computer Environments</DFN>.  POSIX is derived mostly from
various versions of the Unix operating system.
<P>
The library facilities specified by the POSIX standard are a superset of
those required by ANSI C; POSIX specifies additional features for ANSI C
functions, as well as specifying new additional functions.  In general,
the additional requirements and functionality defined by the POSIX
standard are aimed at providing lower-level support for a particular
kind of operating system environment, rather than general programming
language support which can run in many diverse operating system
environments.<P>
The GNU C library implements all of the functions specified in
<CITE>IEEE Std 1003.1-1988, the POSIX System Application Program
Interface</CITE>, commonly referred to as POSIX.1.  The primary extensions to
the ANSI C facilities specified by this standard include file system
interface primitives (see section <A HREF="library.html#SEC187">File System Interface</A>), device-specific
terminal control functions (see section <A HREF="library.html#SEC268">Low-Level Terminal Interface</A>), and
process control functions (see section <A HREF="library.html#SEC401">Child Processes</A>).
<P>
Some facilities from draft 11 of <CITE>IEEE Std 1003.2, the POSIX Shell
and Utilities standard</CITE> (POSIX.2) are also implemented in the GNU
library.  These include utilities for dealing with regular expressions
and other pattern matching facilities (see section <A HREF="library.html#SEC91">Pattern Matching</A>).
<P>
<A NAME="IDX10"></A>
<A NAME="IDX11"></A>
<A NAME="IDX12"></A>
<A NAME="IDX13"></A>
<A NAME="IDX14"></A>
<H3><A NAME="SEC6" HREF="library_toc.html#SEC6">Berkeley Unix</A></H3>
<P>
The GNU C library defines facilities from some other versions of Unix,
specifically from the 4.2 BSD and 4.3 BSD Unix systems (also known as
<DFN>Berkeley Unix</DFN>) and from <DFN>SunOS</DFN> (a popular 4.2 BSD derivative
that includes some Unix System V functionality).  
<P>
The BSD facilities include symbolic links (see section <A HREF="library.html#SEC196">Symbolic Links</A>), the
<CODE>select</CODE> function (see section <A HREF="library.html#SEC180">Waiting for Input or Output</A>), the BSD signal
functions (see section <A HREF="library.html#SEC380">BSD Signal Handling</A>), and sockets (see section <A HREF="library.html#SEC216">Sockets</A>).
<P>
<A NAME="IDX15"></A>
<A NAME="IDX16"></A>
<A NAME="IDX17"></A>
<H3><A NAME="SEC7" HREF="library_toc.html#SEC7">SVID (The System V Interface Description)</A></H3>
<P>
The <DFN>System V Interface Description</DFN> (SVID) is a document describing
the AT&#38;T Unix System V operating system.  It is to some extent a
superset of the POSIX standard (see section <A HREF="library.html#SEC5">POSIX (The Portable Operating System Interface)</A>).
<P>
The GNU C library defines some of the facilities required by the SVID
that are not also required by the ANSI or POSIX standards, for
compatibility with  System V Unix and other Unix systems (such as
SunOS) which include these facilities.  However, many of the more
obscure and less generally useful facilities required by the SVID are
not included.  (In fact, Unix System V itself does not provide them all.)
<P>
<STRONG>Incomplete:</STRONG>  Are there any particular System V facilities that
ought to be mentioned specifically here?
<P>
<H2><A NAME="SEC8" HREF="library_toc.html#SEC8">Using the Library</A></H2>
<P>
This section describes some of the practical issues involved in using
the GNU C library.
<P>
<A NAME="IDX18"></A>
<H3><A NAME="SEC9" HREF="library_toc.html#SEC9">Header Files</A></H3>
<P>
Libraries for use by C programs really consist of two parts: <DFN>header
files</DFN> that define types and macros and declare variables and
functions; and the actual library or <DFN>archive</DFN> that contains the
definitions of the variables and functions.
<P>
(Recall that in C, a <DFN>declaration</DFN> merely provides information that
a function or variable exists and gives its type.  For a function
declaration, information about the types of its arguments might be
provided as well.  The purpose of declarations is to allow the compiler
to correctly process references to the declared variables and functions.
A <DFN>definition</DFN>, on the other hand, actually allocates storage for a
variable or says what a function does.)
<A NAME="IDX20"></A>
<A NAME="IDX19"></A>
<P>
In order to use the facilities in the GNU C library, you should be sure
that your program source files include the appropriate header files.
This is so that the compiler has declarations of these facilities
available and can correctly process references to them.  Once your
program has been compiled, the linker resolves these references to
the actual definitions provided in the archive file.
<P>
Header files are included into a program source file by the
<SAMP>`#include'</SAMP> preprocessor directive.  The C language supports two
forms of this directive; the first,
<P>
<PRE>
#include "<VAR>header</VAR>"
</PRE>
<P>
is typically used to include a header file <VAR>header</VAR> that you write
yourself; this would contain definitions and declarations describing the
interfaces between the different parts of your particular application.
By contrast,
<P>
<PRE>
#include &#60;file.h&#62;
</PRE>
<P>
is typically used to include a header file <TT>`file.h'</TT> that contains
definitions and declarations for a standard library.  This file would
normally be installed in a standard place by your system administrator.
You should use this second form for the C library header files.
<P>
Typically, <SAMP>`#include'</SAMP> directives are placed at the top of the C
source file, before any other code.  If you begin your source files with
some comments explaining what the code in the file does (a good idea),
put the <SAMP>`#include'</SAMP> directives immediately afterwards, following the
feature test macro definition (see section <A HREF="library.html#SEC12">Feature Test Macros</A>).
<P>
For more information about the use of header files and <SAMP>`#include'</SAMP>
directives, see section 'Header Files' in <CITE>The GNU C Preprocessor Manual</CITE>.<P>
The GNU C library provides several header files, each of which contains
the type and macro definitions and variable and function declarations
for a group of related facilities.  This means that your programs may
need to include several header files, depending on exactly which
facilities you are using.
<P>
Some library header files include other library header files
automatically.  However, as a matter of programming style, you should
not rely on this; it is better to explicitly include all the header
files required for the library facilities you are using.  The GNU C
library header files have been written in such a way that it doesn't
matter if a header file is accidentally included more than once;
including a header file a second time has no effect.  Likewise, if your
program needs to include multiple header files, the order in which they
are included doesn't matter.
<P>
<STRONG>Compatibility Note:</STRONG> Inclusion of standard header files in any
order and any number of times works in any ANSI C implementation.
However, this has traditionally not been the case in many older C
implementations.
<P>
Strictly speaking, you don't <EM>have to</EM> include a header file to use
a function it declares; you could declare the function explicitly
yourself, according to the specifications in this manual.  But it is
usually better to include the header file because it may define types
and macros that are not otherwise available and because it may define
more efficient macro replacements for some functions.  It is also a sure
way to have the correct declaration.
<P>
<A NAME="IDX21"></A>
<A NAME="IDX22"></A>
<A NAME="IDX23"></A>
<H3><A NAME="SEC10" HREF="library_toc.html#SEC10">Macro Definitions of Functions</A></H3>
<P>
If we describe something as a function in this manual, it may have a
macro definition as well.  This normally has no effect on how your
program runs--the macro definition does the same thing as the function
would.  In particular, macro equivalents for library functions evaluate
arguments exactly once, in the same way that a function call would.  The
main reason for these macro definitions is that sometimes they can
produce an inline expansion that is considerably faster than an actual
function call.
<P>
Taking the address of a library function works even if it is also
defined as a macro.  This is because, in this context, the name of the
function isn't followed by the left parenthesis that is syntactically
necessary to recognize the  a macro call.
<P>
You might occasionally want to avoid using the a macro definition of a
function--perhaps to make your program easier to debug.  There are
two ways you can do this:
<P>
<UL>
<LI>
You can avoid a macro definition in a specific use by enclosing the name
of the function in parentheses.  This works because the name of the
function doesn't appear in a syntactic context where it is recognizable
as a macro call.
<P>
<LI>
You can suppress any macro definition for a whole source file by using
the <SAMP>`#undef'</SAMP> preprocessor directive, unless otherwise stated
explicitly in the description of that facility.
</UL>
<P>
For example, suppose the header file <TT>`stdlib.h'</TT> declares a function
named <CODE>abs</CODE> with
<P>
<PRE>
extern int abs (int);
</PRE>
<P>
and also provides a macro definition for <CODE>abs</CODE>.  Then, in:
<P>
<PRE>
#include &#60;stdlib.h&#62;
int f (int *i) { return (abs (++*i)); }
</PRE>
<P>
the reference to <CODE>abs</CODE> might refer to either a macro or a function.
On the other hand, in each of the following examples the reference is
to a function and not a macro.
<P>
<PRE>
#include &#60;stdlib.h&#62;
int g (int *i) { return ((abs)(++*i)); }

#undef abs
int h (int *i) { return (abs (++*i)); }
</PRE>
<P>
Since macro definitions that double for a function behave in
exactly the same way as the actual function version, there is usually no
need for any of these methods.  In fact, removing macro definitions usually
just makes your program slower.
<P>
<A NAME="IDX24"></A>
<A NAME="IDX25"></A>
<H3><A NAME="SEC11" HREF="library_toc.html#SEC11">Reserved Names</A></H3>
<P>
The names of all library types, macros, variables and functions that
come from the ANSI C standard are reserved unconditionally; your program
<STRONG>may not</STRONG> redefine these names.  All other library names are
reserved if your programs explicitly includes the header file that
defines or declares them.  There are several reasons for these
restrictions:
<P>
<UL>
<LI>
Other people reading your code could get very confused if you were using
a function named <CODE>exit</CODE> to do something completely different from
what the standard <CODE>exit</CODE> function does, for example.  Preventing
this situation helps to make your programs easier to understand and
contributes to modularity and maintainability.
<P>
<LI>
It avoids the possibility of a user accidentally redefining a library
function that is called by other library functions.  If redefinition
were allowed, those other functions would not work properly.
<P>
<LI>
It allows the compiler to do whatever special optimizations it pleases
on calls to these functions, without the possibility that they may have
been redefined by the user.  Some library facilities, such as those for
dealing with variadic arguments (see section <A HREF="library.html#SEC472">Variadic Functions</A>)
and non-local exits (see section <A HREF="library.html#SEC326">Non-Local Exits</A>), actually require a
considerable amount of cooperation on the part of the C compiler, and
implementationally it might be easier for the compiler to treat these as
built-in parts of the language.
</UL>
<P>
In addition to the names documented in this manual, reserved names
include all external identifiers (global functions and variables) that
begin with an underscore (<SAMP>`_'</SAMP>) and all identifiers regardless of
use that begin with either two underscores or an underscore followed by
a capital letter are reserved names.  This is so that the library and
header files can define functions, variables, and macros for internal
purposes without risk of conflict with names in user programs.
<P>
Some additional classes of identifier names are reserved for future
extensions to the C language.  While using these names for your own
purposes right now might not cause a problem, they do raise the
possibility of conflict with future versions of the C standard, so you
should avoid these names.
<P>
<UL>
<LI>
Names beginning with a capital <SAMP>`E'</SAMP> followed a digit or uppercase
letter may be used for additional error code names.  See section <A HREF="library.html#SEC14">Error Reporting</A>.
<P>
<LI>
Names that begin with either <SAMP>`is'</SAMP> or <SAMP>`to'</SAMP> followed by a
lowercase letter may be used for additional character testing and
conversion functions.  See section <A HREF="library.html#SEC54">Character Handling</A>.
<P>
<LI>
Names that begin with <SAMP>`LC_'</SAMP> followed by an uppercase letter may be
used for additional macros specifying locale attributes.
See section <A HREF="library.html#SEC76">Locales and Internationalization</A>.
<P>
<LI>
Names of all existing mathematics functions (see section <A HREF="library.html#SEC290">Mathematics</A>)
suffixed with <SAMP>`f'</SAMP> or <SAMP>`l'</SAMP> are reserved for corresponding
functions that operate on <CODE>float</CODE> or <CODE>long double</CODE> arguments,
respectively.
<P>
<LI>
Names that begin with <SAMP>`SIG'</SAMP> followed by an uppercase letter are
reserved for additional signal names.  See section <A HREF="library.html#SEC335">Standard Signals</A>.
<P>
<LI>
Names that begin with <SAMP>`SIG_'</SAMP> followed by an uppercase letter are
reserved for additional signal actions.  See section <A HREF="library.html#SEC345">Basic Signal Handling</A>.
<P>
<LI>
Names beginning with <SAMP>`str'</SAMP>, <SAMP>`mem'</SAMP>, or <SAMP>`wcs'</SAMP> followed by a
lowercase letter are reserved for additional string and array functions.
See section <A HREF="library.html#SEC57">String and Array Utilities</A>.
<P>
<LI>
Names that end with <SAMP>`_t'</SAMP> are reserved for additional type names.
</UL>
<P>
In addition, some individual header files reserve names beyond
those that they actually define.  You only need to worry about these
restrictions if your program includes that particular header file.
<P>
<UL>
<LI>
The header file <TT>`dirent.h'</TT> reserves names prefixed with
<SAMP>`d_'</SAMP>.
<A NAME="IDX26"></A>
<P>
<LI>
The header file <TT>`fcntl.h'</TT> reserves names prefixed with
<SAMP>`l_'</SAMP>, <SAMP>`F_'</SAMP>, <SAMP>`O_'</SAMP>, and <SAMP>`S_'</SAMP>.
<A NAME="IDX27"></A>
<P>
<LI>
The header file <TT>`grp.h'</TT> reserves names prefixed with <SAMP>`gr_'</SAMP>.
<A NAME="IDX28"></A>
<P>
<LI>
The header file <TT>`limits.h'</TT> reserves names suffixed with <SAMP>`_MAX'</SAMP>.
<A NAME="IDX29"></A>
<P>
<LI>
The header file <TT>`pwd.h'</TT> reserves names prefixed with <SAMP>`pw_'</SAMP>.
<A NAME="IDX30"></A>
<P>
<LI>
The header file <TT>`signal.h'</TT> reserves names prefixed with <SAMP>`sa_'</SAMP>
and <SAMP>`SA_'</SAMP>.
<A NAME="IDX31"></A>
<P>
<LI>
The header file <TT>`sys/stat.h'</TT> reserves names prefixed with <SAMP>`st_'</SAMP>
and <SAMP>`S_'</SAMP>.
<A NAME="IDX32"></A>
<P>
<LI>
The header file <TT>`sys/times.h'</TT> reserves names prefixed with <SAMP>`tms_'</SAMP>.
<A NAME="IDX33"></A>
<P>
<LI>
The header file <TT>`termios.h'</TT> reserves names prefixed with <SAMP>`c_'</SAMP>,
<SAMP>`V'</SAMP>, <SAMP>`I'</SAMP>, <SAMP>`O'</SAMP>, and <SAMP>`TC'</SAMP>; and names prefixed with
<SAMP>`B'</SAMP> followed by a digit.
<A NAME="IDX34"></A>
</UL>
<P>
<H3><A NAME="SEC12" HREF="library_toc.html#SEC12">Feature Test Macros</A></H3>
<A NAME="IDX35"></A>
<P>
The exact set of features available when you compile a source file
is controlled by which <DFN>feature test macros</DFN> you define.
<P>
If you compile your programs using <SAMP>`gcc -ansi'</SAMP>, you get only
the ANSI C library features, unless you explicitly request additional
features by defining one or more of the feature macros.
See section 'Options' in <CITE>The GNU CC Manual</CITE>, for more information
about GCC options.<P>
You should define these macros by using <SAMP>`#define'</SAMP> preprocessor
directives at the top of your source code files.  You could also use 
the <SAMP>`-D'</SAMP> option to GCC, but it's better if you make the source
files indicate their own meaning in a self-contained way.
<P>
<A NAME="IDX36"></A>
<U>Macro:</U> <B>_POSIX_SOURCE</B><P>
If you define this macro, then the functionality from the POSIX.1
standard (IEEE Standard 1003.1) is available, as well as all of the
ANSI C facilities.
<P>
<A NAME="IDX37"></A>
<U>Macro:</U> <B>_POSIX_C_SOURCE</B><P>
If you define this macro with a value of <CODE>1</CODE>, then the
functionality from the POSIX.1 standard (IEEE Standard 1003.1) is made
available.  If you define this macro with a value of <CODE>2</CODE>, then both
the functionality from the POSIX.1 standard and the functionality from
the POSIX.2 standard (IEEE Standard 1003.2) are made available.  This is
in addition to the ANSI C facilities.
<P>
<A NAME="IDX38"></A>
<U>Macro:</U> <B>_BSD_SOURCE</B><P>
If you define this macro, functionality derived from 4.3 BSD Unix is
included as well as the ANSI C, POSIX.1, and POSIX.2 material.
<P>
Some of the features derived from 4.3 BSD Unix conflict with the
corresponding features specified by the POSIX.1 standard.  If this
macro is defined, the 4.3 BSD definitions take precedence over the
POSIX definitions.
<P>
<A NAME="IDX39"></A>
<U>Macro:</U> <B>_SVID_SOURCE</B><P>
If you define this macro, functionality derived from SVID is
included as well as the ANSI C, POSIX.1, and POSIX.2 material.
<P>
<A NAME="IDX40"></A>
<U>Macro:</U> <B>_GNU_SOURCE</B><P>
If you define this macro, everything is included: ANSI C, POSIX.1,
POSIX.2, BSD, SVID, and GNU extensions.  In the cases where POSIX.1
conflicts with BSD, the POSIX definitions take precedence.
<P>
If you want to get the full effect of <CODE>_GNU_SOURCE</CODE> but make the
BSD definitions take precedence over the POSIX definitions, use this
sequence of definitions:
<P>
<PRE>
#define _GNU_SOURCE
#define _BSD_SOURCE
#define _SVID_SOURCE
</PRE>
<P>
We recommend you use <CODE>_GNU_SOURCE</CODE> in new programs.
If you don't specify the <SAMP>`-ansi'</SAMP> option to GCC and don't define
any of these macros explicitly, the effect as the same as defining
<CODE>_GNU_SOURCE</CODE>.
<P>
When you define a feature test macro to request a larger class of
features, it is harmless to define in addition a feature test macro for
a subset of those features.  For example, if you define
<CODE>_POSIX_C_SOURCE</CODE>, then defining <CODE>_POSIX_SOURCE</CODE> as well has
no effect.  Likewise, if you define <CODE>_GNU_SOURCE</CODE>, then defining
either <CODE>_POSIX_SOURCE</CODE> or <CODE>_POSIX_C_SOURCE</CODE> or
<CODE>_SVID_SOURCE</CODE> as well has no effect.
<P>
Note, however, that the features of <CODE>_BSD_SOURCE</CODE> are not a subset
of any of the other feature test macros supported.  This is because it
defines BSD features that take precedence over the POSIX features that
are requested by the other macros.  For this reason, defining
<CODE>_BSD_SOURCE</CODE> in addition to the other feature test macros does
have an effect: it causes the BSD features to take priority over the
conflicting POSIX features.
<P>
<H2><A NAME="SEC13" HREF="library_toc.html#SEC13">Roadmap to the Manual</A></H2>
<P>
Here is an overview of the contents of the remaining chapters of
this manual.
<P>
<UL>
<LI>
section <A HREF="library.html#SEC14">Error Reporting</A>, describes how errors detected by the library
are reported.
<P>
<LI>
section <A HREF="library.html#SEC470">C Language Facilities Implemented By the Library</A>, contains information about library support for
standard parts of the C language, including things like the
<CODE>sizeof</CODE> operator and the symbolic constant <CODE>NULL</CODE>, and how to
write functions accepting variable numbers of arguments.
<P>
<LI>
section <A HREF="library.html#SEC18">Memory Allocation</A>, describes the GNU library's facilities for
dynamic allocation of storage.  If you do not know in advance how much
storage your program needs, you can allocate it dynamically instead,
and manipulate it via pointers.
<P>
<LI>
section <A HREF="library.html#SEC54">Character Handling</A>, contains information about character
classification functions (such as <CODE>isspace</CODE>) and functions for
performing case conversion.
<P>
<LI>
section <A HREF="library.html#SEC57">String and Array Utilities</A>, has descriptions of functions for
manipulating strings (null-terminated character arrays) and general
byte arrays, including operations such as copying and comparison.
<P>
<LI>
section <A HREF="library.html#SEC66">Extended Characters</A>, contains information about manipulating
characters and strings using character sets larger than will fit in
the usual <CODE>char</CODE> data type.  
<P>
<LI>
section <A HREF="library.html#SEC76">Locales and Internationalization</A>, describes how selecting a particular country 
or language affects the behavior of the library.  For example, the locale
affects collation sequences for strings and how monetary values are
formatted.
<P>
<LI>
section <A HREF="library.html#SEC86">Searching and Sorting</A>, contains information about functions
for searching and sorting arrays.  You can use these functions on any
kind of array by providing an appropriate comparison function.
<P>
<LI>
section <A HREF="library.html#SEC108">Input/Output Overview</A>, gives an overall look at the input and output
facilities in the library, and contains information about basic concepts
such as file names.
<P>
<LI>
section <A HREF="library.html#SEC117">Input/Output on Streams</A>, describes I/O operations involving streams (or
<CODE>FILE *</CODE> objects).  These are the normal C library functions
from <TT>`stdio.h'</TT>.
<P>
<LI>
section <A HREF="library.html#SEC171">Low-Level Input/Output</A>, contains information about I/O operations
on file descriptors.  File descriptors are a lower-level mechanism
specific to the Unix family of operating systems.
<P>
<LI>
section <A HREF="library.html#SEC187">File System Interface</A>, has descriptions of operations on entire
files, such as functions for deleting and renaming them and for creating
new directories.  This chapter also contains information about how you
can access the attributes of a file, such as its owner and file protection
modes.
<P>
<LI>
section <A HREF="library.html#SEC211">Pipes and FIFOs</A>, contains information about simple interprocess
communication mechanisms.  Pipes allow communication between two related
processes (such as between a parent and child), while FIFOs allow
communication between processes sharing a common file system.
<P>
<LI>
section <A HREF="library.html#SEC216">Sockets</A>, describes a more complicated interprocess communication
mechanism that allows processes running on different machines to
communicate over a network.  This chapter also contains information about
Internet host addressing and how to use the system network databases,
such as <TT>`/etc/hosts'</TT>.
<P>
<LI>
section <A HREF="library.html#SEC268">Low-Level Terminal Interface</A>, describes how you can change the
attributes of a terminal device.  If you want to disable echo of
characters typed by the user, for example, read this chapter.
<P>
<LI>
section <A HREF="library.html#SEC471">Explicitly Checking Internal Consistency</A>, contains information about a simple
debugging mechanism.  You can put assertions in your code, and
diagnostic messages are printed if the test fails.
<P>
<LI>
section <A HREF="library.html#SEC290">Mathematics</A>, contains information about the math library
functions.  These include things like random-number generators and
remainder functions on integers as well as the usual trigonometric and
exponential functions on floating-point numbers.
<P>
<LI>
section <A HREF="library.html#SEC309">Date and Time</A>, describes functions for measuring both calendar time
and CPU time, as well as functions for setting alarms and timers.
<P>
<LI>
section <A HREF="library.html#SEC326">Non-Local Exits</A>, contains descriptions of the <CODE>setjmp</CODE> and
<CODE>longjmp</CODE> functions.
<P>
<LI>
section <A HREF="library.html#SEC330">Signal Handling</A>, tells you all about signals--what they are,
how to establish a handler that is called when a particular kind of
signal is delivered, and how to prevent signals from arriving during
critical sections of your program.
<P>
<LI>
section <A HREF="library.html#SEC401">Child Processes</A>, contains information about how to start new processes
and run programs.
<P>
<LI>
section <A HREF="library.html#SEC385">Process Startup and Termination</A>, tells how your programs can access their
command-line arguments and environment variables.
<P>
<LI>
section <A HREF="library.html#SEC411">Job Control</A>, describes functions for manipulating process groups.
This material is probably only of interest if you are writing a shell.
<P>
<LI>
section <A HREF="library.html#SEC441">User Database</A>, and section <A HREF="library.html#SEC446">Group Database</A>, tell you how to access
the system user and group databases.
<P>
<LI>
section <A HREF="library.html#SEC451">System Information</A>, describes functions for getting information
about the hardware and software configuration your program is executing
under.
<P>
<LI>
section <A HREF="library.html#SEC486">Range of an Integer Type</A>, contains information about
parameters that characterize the sizes of integer and floating-point
types used by the particular C implementation that your program has
been compiled with.  Most of these parameters are provided for 
compatibility with ANSI C.
<P>
<LI>
section <A HREF="library.html#SEC454">System Configuration Parameters</A>, tells you how you can get
information about various operating system limits.  Most of these
parameters are provided for compatibility with POSIX.
</UL>
<P>
If you already know the name of the facility you are interested in, you
can look it up in section <A HREF="library.html#SEC492">Summary of Library Facilities</A>.  This gives you a summary of
its syntax and a pointer to where you can find a more detailed
description.  This appendix is particularly useful if you just want to
verify the order and type of arguments to a function, for example.
<A NAME="IDX41"></A>
<A NAME="IDX42"></A>
<A NAME="IDX43"></A>
<A NAME="IDX44"></A>
<H1><A NAME="SEC14" HREF="library_toc.html#SEC14">Error Reporting</A></H1>
<P>
Many functions in the GNU C library detect and report error conditions,
and sometimes your programs need to check for these error conditions.
For example, when you open an input file, you should verify that the
file was actually opened correctly, and print an error message or take
other appropriate action if the call to the library function failed.
<P>
This chapter describes how the error reporting facility works.  Your
program should include the header file <TT>`errno.h'</TT> to use this
facility.
<A NAME="IDX45"></A>
<P>
<H2><A NAME="SEC15" HREF="library_toc.html#SEC15">Checking for Errors</A></H2>
<P>
Most library functions return a special value to indicate that they have
failed.  The special value is typically <CODE>-1</CODE>, a null pointer, or a
constant such as <CODE>EOF</CODE> that is defined for that purpose.  But this
return value tells you only that an error has occurred.  To find out
what kind of error it was, you need to look at the error code stored in the
variable <CODE>errno</CODE>.  This variable is declared in the header file
<TT>`errno.h'</TT>.
<A NAME="IDX46"></A>
<P>
<A NAME="IDX47"></A>
<U>Variable:</U> volatile int <B>errno</B><P>
The variable <CODE>errno</CODE> contains the system error number.  You can
change the value of <CODE>errno</CODE>.
<P>
Since <CODE>errno</CODE> is declared <CODE>volatile</CODE>, it might be changed
asynchronously by a signal handler; see section <A HREF="library.html#SEC351">Defining Signal Handlers</A>.
However, a properly written signal handler saves and restores the value
of <CODE>errno</CODE>, so you generally do not need to worry about this
possibility except when writing signal handlers.
<P>
The initial value of <CODE>errno</CODE> at program startup is zero.  Many
library functions are guaranteed to set it to certain nonzero values
when they encounter certain kinds of errors.  These error conditions are
listed for each function.  These functions do not change <CODE>errno</CODE>
when they succeed; thus, the value of <CODE>errno</CODE> after a successful
call is not necessarily zero, and you should not use <CODE>errno</CODE> to
determine <EM>whether</EM> a call failed.  The proper way to do that is
documented for each function.  <EM>If</EM> the call the failed, you can
examine <CODE>errno</CODE>.
<P>
Many library functions can set <CODE>errno</CODE> to a nonzero value as a
result of calling other library functions which might fail.  You should
assume that any library function might alter <CODE>errno</CODE>.
<P>
<STRONG>Portability Note:</STRONG> ANSI C specifies <CODE>errno</CODE> as a
"modifiable lvalue" rather than as a variable, permitting it to be
implemented as a macro.  For example, its expansion might involve a
function call, like <CODE>*_errno ()</CODE>.  In fact, that is what it is
on the GNU system itself.  The GNU library, on non-GNU systems, does
whatever is right for the particular system.
<P>
There are a few library functions, like <CODE>sqrt</CODE> and <CODE>atan</CODE>,
that return a perfectly legitimate value in case of an error, but also
set <CODE>errno</CODE>.  For these functions, if you want to check to see
whether an error occurred, the recommended method is to set <CODE>errno</CODE>
to zero before calling the function, and then check its value afterward.
<P>
<A NAME="IDX48"></A>
<P>
All the error codes have symbolic names; they are macros defined in
<TT>`errno.h'</TT>.  The names start with <SAMP>`E'</SAMP> and an upper-case
letter or digit; you should consider names of this form to be
reserved names.  See section <A HREF="library.html#SEC11">Reserved Names</A>.
<P>
The error code values are all positive integers and are all distinct.
(Since the values are distinct, you can use them as labels in a
<CODE>switch</CODE> statement, for example.)  Your program should not make any
other assumptions about the specific values of these symbolic constants.
<P>
The value of <CODE>errno</CODE> doesn't necessarily have to correspond to any
of these macros, since some library functions might return other error
codes of their own for other situations.  The only values that are
guaranteed to be meaningful for a particular library function are the
ones that this manual lists for that function.
<P>
On non-GNU systems, almost any system call can return <CODE>EFAULT</CODE> if
it is given an invalid pointer as an argument.  Since this could only
happen as a result of a bug in your program, and since it will not
happen on the GNU system, we have saved space by not mentioning
<CODE>EFAULT</CODE> in the descriptions of individual functions.
<P>
<H2><A NAME="SEC16" HREF="library_toc.html#SEC16">Error Codes</A></H2>
<A NAME="IDX49"></A>
<P>
The error code macros are defined in the header file <TT>`errno.h'</TT>.
All of them expand into integer constant values.  Some of these error
codes can't occur on the GNU system, but they can occur using the GNU
library on other systems.
<P>
<A NAME="IDX50"></A>
<U>Macro:</U> int <B>EPERM</B><P>
Operation not permitted; only the owner of the file (or other resource)
or processes with special privileges can perform the operation.
<P>
<A NAME="IDX51"></A>
<U>Macro:</U> int <B>ENOENT</B><P>
No such file or directory.  This is a "file doesn't exist" error
for ordinary files that are referenced in contexts where they are
expected to already exist.
<P>
<A NAME="IDX52"></A>
<U>Macro:</U> int <B>ESRCH</B><P>
No process matches the specified process ID.
<P>
<A NAME="IDX53"></A>
<U>Macro:</U> int <B>EINTR</B><P>
Interrupted function call; an asynchronous signal occured and prevented
completion of the call.  When this happens, you should try the call
again.
<P>
You can choose to have functions resume after a signal that is handled,
rather than failing with <CODE>EINTR</CODE>; see section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<A NAME="IDX54"></A>
<U>Macro:</U> int <B>EIO</B><P>
Input/output error; usually used for physical read or write errors.
<P>
<A NAME="IDX55"></A>
<U>Macro:</U> int <B>ENXIO</B><P>
No such device or address.  Typically, this means that a file
representing a device has been installed incorrectly, and the
system can't find the right kind of device driver for it.
<P>
<A NAME="IDX56"></A>
<U>Macro:</U> int <B>E2BIG</B><P>
Argument list too long; used when the arguments passed to a new program
being executed with one of the <CODE>exec</CODE> functions (see section <A HREF="library.html#SEC406">Executing a File</A>) occupy too much memory space.  This condition never arises in the
GNU system.
<P>
<A NAME="IDX57"></A>
<U>Macro:</U> int <B>ENOEXEC</B><P>
Invalid executable file format.  This condition is detected by the
<CODE>exec</CODE> functions; see section <A HREF="library.html#SEC406">Executing a File</A>.
<P>
<A NAME="IDX58"></A>
<U>Macro:</U> int <B>EBADF</B><P>
Bad file descriptor; for example, I/O on a descriptor that has been
closed or reading from a descriptor open only for writing (or vice
versa).
<P>
<A NAME="IDX59"></A>
<U>Macro:</U> int <B>ECHILD</B><P>
There are no child processes.  This error happens on operations that are
supposed to manipulate child processes, when there aren't any processes
to manipulate.
<P>
<A NAME="IDX60"></A>
<U>Macro:</U> int <B>EDEADLK</B><P>
Deadlock avoided; allocating a system resource would have resulted in
a deadlock situation.  For an example, See section <A HREF="library.html#SEC185">File Locks</A>.
<P>
<A NAME="IDX61"></A>
<U>Macro:</U> int <B>ENOMEM</B><P>
No memory available.  The system cannot allocate more virtual memory
because its capacity is full.
<P>
<A NAME="IDX62"></A>
<U>Macro:</U> int <B>EACCES</B><P>
Permission denied; the file permissions do not allow the attempted operation.
<P>
<A NAME="IDX63"></A>
<U>Macro:</U> int <B>EFAULT</B><P>
Bad address; an invalid pointer was detected.
<P>
<A NAME="IDX64"></A>
<U>Macro:</U> int <B>ENOTBLK</B><P>
A file that isn't a block special file was given in a situation that
requires one.  For example, trying to mount an ordinary file as a file
system in Unix gives this error.
<P>
<A NAME="IDX65"></A>
<U>Macro:</U> int <B>EBUSY</B><P>
Resource busy; a system resource that can't be shared is already in use.
For example, if you try to delete a file that is the root of a currently
mounted filesystem, you get this error.
<P>
<A NAME="IDX66"></A>
<U>Macro:</U> int <B>EEXIST</B><P>
File exists; an existing file was specified in a context where it only
makes sense to specify a new file.
<P>
<A NAME="IDX67"></A>
<U>Macro:</U> int <B>EXDEV</B><P>
An attempt to make an improper link across file systems was detected.
<P>
<A NAME="IDX68"></A>
<U>Macro:</U> int <B>ENODEV</B><P>
The wrong type of device was given to a function that expects a
particular sort of device.
<P>
<A NAME="IDX69"></A>
<U>Macro:</U> int <B>ENOTDIR</B><P>
A file that isn't a directory was specified when a directory is required.
<P>
<A NAME="IDX70"></A>
<U>Macro:</U> int <B>EISDIR</B><P>
File is a directory; attempting to open a directory for writing gives
this error.
<P>
<A NAME="IDX71"></A>
<U>Macro:</U> int <B>EINVAL</B><P>
Invalid argument.  This is used to indicate various kinds of problems
with passing the wrong argument to a library function.
<P>
<A NAME="IDX72"></A>
<U>Macro:</U> int <B>ENFILE</B><P>
There are too many distinct file openings in the entire system.  Note
that any number of linked channels count as just one file opening; see
section <A HREF="library.html#SEC177">Linked Channels</A>.
<P>
<A NAME="IDX73"></A>
<U>Macro:</U> int <B>EMFILE</B><P>
The current process has too many files open and can't open any more.
Duplicate descriptors do count toward this limit.
<P>
<A NAME="IDX74"></A>
<U>Macro:</U> int <B>ENOTTY</B><P>
Inappropriate I/O control operation, such as trying to set terminal
modes on an ordinary file.
<P>
<A NAME="IDX75"></A>
<U>Macro:</U> int <B>ETXTBSY</B><P>
An attempt to execute a file that is currently open for writing, or
write to a file that is currently being executed.  (The name stands
for "text file busy".)  This is not an error in the GNU system; the
text is copied as necessary.
<P>
<A NAME="IDX76"></A>
<U>Macro:</U> int <B>EFBIG</B><P>
File too big; the size of a file would be larger than allowed by the system.
<P>
<A NAME="IDX77"></A>
<U>Macro:</U> int <B>ENOSPC</B><P>
No space left on device; write operation on a file failed because the
disk is full.
<P>
<A NAME="IDX78"></A>
<U>Macro:</U> int <B>ESPIPE</B><P>
Invalid seek operation (such as on a pipe).
<P>
<A NAME="IDX79"></A>
<U>Macro:</U> int <B>EROFS</B><P>
An attempt was made to modify a file on a read-only file system.
<P>
<A NAME="IDX80"></A>
<U>Macro:</U> int <B>EMLINK</B><P>
Too many links; the link count of a single file is too large.
<P>
<A NAME="IDX81"></A>
<U>Macro:</U> int <B>EPIPE</B><P>
Broken pipe; there is no process reading from the other end of a pipe.
Every library function that returns this error code also generates a
<CODE>SIGPIPE</CODE> signal; this signal terminates the program if not handled
or blocked.  Thus, your program will never actually see <CODE>EPIPE</CODE>
unless it has handled or blocked <CODE>SIGPIPE</CODE>.
<P>
<A NAME="IDX82"></A>
<U>Macro:</U> int <B>EDOM</B><P>
Domain error; used by mathematical functions when an argument value does
not fall into the domain over which the function is defined.
<P>
<A NAME="IDX83"></A>
<U>Macro:</U> int <B>ERANGE</B><P>
Range error; used by mathematical functions when the result value is
not representable because of overflow or underflow.
<P>
<A NAME="IDX84"></A>
<U>Macro:</U> int <B>EAGAIN</B><P>
Resource temporarily unavailable; the call might work if you try again
later.  Only <CODE>fork</CODE> returns error code <CODE>EAGAIN</CODE> for such a
reason.
<P>
<A NAME="IDX85"></A>
<U>Macro:</U> int <B>EWOULDBLOCK</B><P>
An operation that would block was attempted on an object that has
non-blocking mode selected.
<P>
<STRONG>Portability Note:</STRONG> In 4.4BSD and GNU, <CODE>EWOULDBLOCK</CODE> and
<CODE>EAGAIN</CODE> are the same.  Earlier versions of BSD (see section <A HREF="library.html#SEC6">Berkeley Unix</A>) have two distinct codes, and use <CODE>EWOULDBLOCK</CODE> to indicate
an I/O operation that would block on an object with non-blocking mode
set, and <CODE>EAGAIN</CODE> for other kinds of errors.<P>
<A NAME="IDX86"></A>
<U>Macro:</U> int <B>EINPROGRESS</B><P>
An operation that cannot complete immediately was initiated on an object
that has non-blocking mode selected.
<P>
<A NAME="IDX87"></A>
<U>Macro:</U> int <B>EALREADY</B><P>
An operation is already in progress on an object that has non-blocking
mode selected.
<P>
<A NAME="IDX88"></A>
<U>Macro:</U> int <B>ENOTSOCK</B><P>
A file that isn't a socket was specified when a socket is required.
<P>
<A NAME="IDX89"></A>
<U>Macro:</U> int <B>EDESTADDRREQ</B><P>
No destination address was supplied on a socket operation.
<P>
<A NAME="IDX90"></A>
<U>Macro:</U> int <B>EMSGSIZE</B><P>
The size of a message sent on a socket was larger than the supported
maximum size.  
<P>
<A NAME="IDX91"></A>
<U>Macro:</U> int <B>EPROTOTYPE</B><P>
The socket type does not support the requested communications protocol.
<P>
<A NAME="IDX92"></A>
<U>Macro:</U> int <B>ENOPROTOOPT</B><P>
You specified a socket option that doesn't make sense for the
particular protocol being used by the socket.  See section <A HREF="library.html#SEC264">Socket Options</A>.
<P>
<A NAME="IDX93"></A>
<U>Macro:</U> int <B>EPROTONOSUPPORT</B><P>
The socket domain does not support the requested communications protocol.
See section <A HREF="library.html#SEC241">Creating a Socket</A>.
<P>
<A NAME="IDX94"></A>
<U>Macro:</U> int <B>ESOCKTNOSUPPORT</B><P>
The socket type is not supported.
<P>
<A NAME="IDX95"></A>
<U>Macro:</U> int <B>EOPNOTSUPP</B><P>
The operation you requested is not supported.  Some socket functions
don't make sense for all types of sockets, and others may not be implemented
for all communications protocols.
<P>
<A NAME="IDX96"></A>
<U>Macro:</U> int <B>EPFNOSUPPORT</B><P>
The socket communications protocol family you requested is not supported.
<P>
<A NAME="IDX97"></A>
<U>Macro:</U> int <B>EAFNOSUPPORT</B><P>
The address family specified for a socket is not supported; it is
inconsistent with the protocol being used on the socket.  See section <A HREF="library.html#SEC216">Sockets</A>.
<P>
<A NAME="IDX98"></A>
<U>Macro:</U> int <B>EADDRINUSE</B><P>
The requested socket address is already in use.  See section <A HREF="library.html#SEC219">Socket Addresses</A>.
<P>
<A NAME="IDX99"></A>
<U>Macro:</U> int <B>EADDRNOTAVAIL</B><P>
The requested socket address is not available; for example, you tried
to give a socket a name that doesn't match the local host name.
See section <A HREF="library.html#SEC219">Socket Addresses</A>.
<P>
<A NAME="IDX100"></A>
<U>Macro:</U> int <B>ENETDOWN</B><P>
A socket operation failed because the network was down.
<P>
<A NAME="IDX101"></A>
<U>Macro:</U> int <B>ENETUNREACH</B><P>
A socket operation failed because the subnet containing the remost host
was unreachable.
<P>
<A NAME="IDX102"></A>
<U>Macro:</U> int <B>ENETRESET</B><P>
A network connection was reset because the remote host crashed.
<P>
<A NAME="IDX103"></A>
<U>Macro:</U> int <B>ECONNABORTED</B><P>
A network connection was aborted locally.
<P>
<A NAME="IDX104"></A>
<U>Macro:</U> int <B>ECONNRESET</B><P>
A network connection was closed for reasons outside the control of the
local host, such as by the remote machine rebooting.
<P>
<A NAME="IDX105"></A>
<U>Macro:</U> int <B>ENOBUFS</B><P>
The kernel's buffers for I/O operations are all in use.
<P>
<A NAME="IDX106"></A>
<U>Macro:</U> int <B>EISCONN</B><P>
You tried to connect a socket that is already connected.
See section <A HREF="library.html#SEC245">Making a Connection</A>.
<P>
<A NAME="IDX107"></A>
<U>Macro:</U> int <B>ENOTCONN</B><P>
The socket is not connected to anything.  You get this error when you
try to transmit data over a socket, without first specifying a destination
for the data.
<P>
<A NAME="IDX108"></A>
<U>Macro:</U> int <B>ESHUTDOWN</B><P>
The socket has already been shut down.
<P>
<A NAME="IDX109"></A>
<U>Macro:</U> int <B>ETIMEDOUT</B><P>
A socket operation with a specified timeout received no response during
the timeout period.
<P>
<A NAME="IDX110"></A>
<U>Macro:</U> int <B>ECONNREFUSED</B><P>
A remote host refused to allow the network connection (typically because
it is not running the requested service).
<P>
<A NAME="IDX111"></A>
<U>Macro:</U> int <B>ELOOP</B><P>
Too many levels of symbolic links were encountered in looking up a file name.
This often indicates a cycle of symbolic links.
<P>
<A NAME="IDX112"></A>
<U>Macro:</U> int <B>ENAMETOOLONG</B><P>
Filename too long (longer than <CODE>PATH_MAX</CODE>; see section <A HREF="library.html#SEC463">Limits on File System Capacity</A>) or host name too long (in <CODE>gethostname</CODE> or
<CODE>sethostname</CODE>; see section <A HREF="library.html#SEC452">Host Identification</A>).
<P>
<A NAME="IDX113"></A>
<U>Macro:</U> int <B>EHOSTDOWN</B><P>
The remote host for a requested network connection is down.
<P>
<A NAME="IDX114"></A>
<U>Macro:</U> int <B>EHOSTUNREACH</B><P>
The remote host for a requested network connection is not reachable.
<P>
<A NAME="IDX115"></A>
<U>Macro:</U> int <B>ENOTEMPTY</B><P>
Directory not empty, where an empty directory was expected.  Typically,
this error occurs when you are trying to delete a directory.
<P>
<A NAME="IDX116"></A>
<U>Macro:</U> int <B>EUSERS</B><P>
The file quota system is confused because there are too many users.
<P>
<A NAME="IDX117"></A>
<U>Macro:</U> int <B>EDQUOT</B><P>
The user's disk quota was exceeded.
<P>
<A NAME="IDX118"></A>
<U>Macro:</U> int <B>ESTALE</B><P>
Stale NFS file handle.  This indicates an internal confusion in the NFS
system which is due to file system rearrangements on the server host.
Repairing this condition usually requires unmounting and remounting
the NFS file system on the local host.
<P>
<A NAME="IDX119"></A>
<U>Macro:</U> int <B>EREMOTE</B><P>
An attempt was made to NFS-mount a remote file system with a file name that
already specifies an NFS-mounted file.
(This is an error on some operating systems, but we expect it to work
properly on the GNU system, making this error code impossible.)
<P>
<A NAME="IDX120"></A>
<U>Macro:</U> int <B>ENOLCK</B><P>
No locks available.  This is used by the file locking facilities;
see section <A HREF="library.html#SEC185">File Locks</A>.
<P>
<A NAME="IDX121"></A>
<U>Macro:</U> int <B>ENOSYS</B><P>
Function not implemented.  Some functions have commands or options defined
that might not be supported in all implementations, and this is the kind
of error you get if you request them and they are not supported.
<P>
<A NAME="IDX122"></A>
<U>Macro:</U> int <B>ED</B><P>
The experienced user will know what is wrong.
<P>
<A NAME="IDX123"></A>
<U>Macro:</U> int <B>EGRATUITOUS</B><P>
This error code has no purpose.
<P>
<H2><A NAME="SEC17" HREF="library_toc.html#SEC17">Error Messages</A></H2>
<P>
The library has functions and variables designed to make it easy for
your program to report informative error messages in the customary
format about the failure of a library call.  The functions
<CODE>strerror</CODE> and <CODE>perror</CODE> give you the standard error message
for a given error code; the variable
<CODE>program_invocation_short_name</CODE> gives you convenient access to the
name of the program that encountered the error.
<P>
<A NAME="IDX124"></A>
<U>Function:</U> char * <B>strerror</B> <I>(int <VAR>errnum</VAR>)</I><P>
The <CODE>strerror</CODE> function maps the error code (see section <A HREF="library.html#SEC15">Checking for Errors</A>) specified by the <VAR>errnum</VAR> argument to a descriptive error
message string.  The return value is a pointer to this string.
<P>
The value <VAR>errnum</VAR> normally comes from the variable <CODE>errno</CODE>.
<P>
You should not modify the string returned by <CODE>strerror</CODE>.  Also, if
you make subsequent calls to <CODE>strerror</CODE>, the string might be
overwritten.  (But it's guaranteed that no library function ever calls
<CODE>strerror</CODE> behind your back.)
<P>
The function <CODE>strerror</CODE> is declared in <TT>`string.h'</TT>.
<P>
<A NAME="IDX125"></A>
<U>Function:</U> void <B>perror</B> <I>(const char *<VAR>message</VAR>)</I><P>
This function prints an error message to the stream <CODE>stderr</CODE>;
see section <A HREF="library.html#SEC119">Standard Streams</A>.
<P>
If you call <CODE>perror</CODE> with a <VAR>message</VAR> that is either a null
pointer or an empty string, <CODE>perror</CODE> just prints the error message 
corresponding to <CODE>errno</CODE>, adding a trailing newline.
<P>
If you supply a non-null <VAR>message</VAR> argument, then <CODE>perror</CODE>
prefixes its output with this string.  It adds a colon and a space 
character to separate the <VAR>message</VAR> from the error string corresponding
to <CODE>errno</CODE>.
<P>
The function <CODE>perror</CODE> is declared in <TT>`stdio.h'</TT>.
<P>
<CODE>strerror</CODE> and <CODE>perror</CODE> produce the exact same message for any
given error code; the precise text varies from system to system.  On the
GNU system, the messages are fairly short; there are no multi-line
messages or embedded newlines.  Each error message begins with a capital
letter and does not include any terminating punctuation.
<P>
<STRONG>Compatibility Note:</STRONG>  The <CODE>strerror</CODE> function is a new
feature of ANSI C.  Many older C systems do not support this function
yet.
<A NAME="IDX126"></A>
<A NAME="IDX127"></A>
<P>
Many programs that don't read input from the terminal are designed to
exit if any system call fails.  By convention, the error message from
such a program should start with the program's name, sans directories.
You can find that name in the variable
<CODE>program_invocation_short_name</CODE>; the full file name is stored the
variable <CODE>program_invocation_name</CODE>:
<P>
<A NAME="IDX128"></A>
<U>Variable:</U> char * <B>program_invocation_name</B><P>
This variable's value is the name that was used to invoke the program
running in the current process.  It is the same as <CODE>argv[0]</CODE>.
<P>
<A NAME="IDX129"></A>
<U>Variable:</U> char * <B>program_invocation_short_name</B><P>
This variable's value is the name that was used to invoke the program
running in the current process, with directory names removed.  (That is
to say, it is the same as <CODE>program_invocation_name</CODE> minus
everything up to the last slash, if any.)
<P>
Both <CODE>program_invocation_name</CODE> and
<CODE>program_invocation_short_name</CODE> are set up by the system before
<CODE>main</CODE> is called.
<P>
<STRONG>Portability Note:</STRONG> These two variables are GNU extensions.  If
you want your program to work with non-GNU libraries, you must save the
value of <CODE>argv[0]</CODE> in <CODE>main</CODE>, and then strip off the directory
names yourself.  We added these extensions to make it possible to write
self-contained error-reporting subroutines that require no explicit
cooperation from <CODE>main</CODE>.
<P>
Here is an example showing how to handle failure to open a file
correctly.  The function <CODE>open_sesame</CODE> tries to open the named file
for reading and returns a stream if successful.  The <CODE>fopen</CODE>
library function returns a null pointer if it couldn't open the file for
some reason.  In that situation, <CODE>open_sesame</CODE> constructs an
appropriate error message using the <CODE>strerror</CODE> function, and
terminates the program.  If we were going to make some other library
calls before passing the error code to <CODE>strerror</CODE>, we'd have to
save it in a local variable instead, because those other library
functions might overwrite <CODE>errno</CODE> in the meantime.
<P>
<PRE>
#include &#60;errno.h&#62;
#include &#60;stdio.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;string.h&#62;

FILE *
open_sesame (char *name)
{ 
  FILE *stream;

  errno = 0;                     
  stream = fopen (name, "r");
  if (!stream) {
    fprintf (stderr, "%s: Couldn't open file %s; %s\n",
             program_invocation_short_name, name, strerror (errno));
    exit (EXIT_FAILURE);
  } else
    return stream;
}
</PRE>
<P>
<A NAME="IDX130"></A>
<A NAME="IDX131"></A>
<H1><A NAME="SEC18" HREF="library_toc.html#SEC18">Memory Allocation</A></H1>
<P>
The GNU system provides several methods for allocating memory space
under explicit program control.  They vary in generality and in
efficiency.
<P>
<UL>
<LI>
The <CODE>malloc</CODE> facility allows fully general dynamic allocation.
See section <A HREF="library.html#SEC21">Unconstrained Allocation</A>.
<P>
<LI>
Obstacks are another facility, less general than <CODE>malloc</CODE> but more
efficient and convenient for stacklike allocation.  See section <A HREF="library.html#SEC33">Obstacks</A>.
<P>
<LI>
The function <CODE>alloca</CODE> lets you allocate storage dynamically that
will be freed automatically.  See section <A HREF="library.html#SEC45">Automatic Storage with Variable Size</A>.
</UL>
<P>
<A NAME="IDX132"></A>
<A NAME="IDX133"></A>
<A NAME="IDX134"></A>
<H2><A NAME="SEC19" HREF="library_toc.html#SEC19">Dynamic Memory Allocation Concepts</A></H2>
<P>
<DFN>Dynamic memory allocation</DFN> is a technique in which programs
determine as they are running where to store some information.  You need
dynamic allocation when the number of memory blocks you need, or how
long you continue to need them, depends on the data you are working on.
<P>
For example, you may need a block to store a line read from an input file;
since there is no limit to how long a line can be, you must allocate the
storage dynamically and make it dynamically larger as you read more of the
line.
<P>
Or, you may need a block for each record or each definition in the input
data; since you can't know in advance how many there will be, you must
allocate a new block for each record or definition as you read it.
<P>
When you use dynamic allocation, the allocation of a block of memory is an
action that the program requests explicitly.  You call a function or macro
when you want to allocate space, and specify the size with an argument.  If
you want to free the space, you do so by calling another function or macro.
You can do these things whenever you want, as often as you want.
<P>
<H2><A NAME="SEC20" HREF="library_toc.html#SEC20">Dynamic Allocation and C</A></H2>
<P>
The C language supports two kinds of memory allocation through the variables
in C programs:
<P>
<UL>
<LI>
<DFN>Static allocation</DFN> is what happens when you declare a static
variable.  Each static variable defines one block of space, of a fixed
size.  The space is allocated once, when your program is started, and
is never freed.
<P>
<LI>
<DFN>Automatic allocation</DFN> happens when you declare an automatic
variable, such as a function argument or a local variable.  The space
for an automatic variable is allocated when the compound statement
containing the declaration is entered, and is freed when that
compound statement is exited.
<P>
In GNU C, the length of the automatic storage can be an expression
that varies.  In other C implementations, it must be a constant.
</UL>
<P>
Dynamic allocation is not supported by C variables; there is no storage
class "dynamic", and there can never be a C variable whose value is
stored in dynamically allocated space.  The only way to refer to
dynamically allocated space is through a pointer.  Because it is less
convenient, and because the actual process of dynamic allocation
requires more computation time, programmers use dynamic allocation only
when neither static nor automatic allocation will serve.
<P>
For example, if you want to allocate dynamically some space to hold a
<CODE>struct foobar</CODE>, you cannot declare a variable of type <CODE>struct
foobar</CODE> whose contents are the dynamically allocated space.  But you can
declare a variable of pointer type <CODE>struct foobar *</CODE> and assign it the
address of the space.  Then you can use the operators <SAMP>`*'</SAMP> and
<SAMP>`-&#62;'</SAMP> on this pointer variable to refer to the contents of the space:
<P>
<PRE>
{
  struct foobar *ptr
     = (struct foobar *) malloc (sizeof (struct foobar));
  ptr-&#62;name = x;
  ptr-&#62;next = current_foobar;
  current_foobar = ptr;
}
</PRE>
<P>
<A NAME="IDX135"></A>
<A NAME="IDX136"></A>
<A NAME="IDX137"></A>
<H2><A NAME="SEC21" HREF="library_toc.html#SEC21">Unconstrained Allocation</A></H2>
<P>
The most general dynamic allocation facility is <CODE>malloc</CODE>.  It
allows you to allocate blocks of memory of any size at any time, make
them bigger or smaller at any time, and free the blocks individually at
any time (or never).
<P>
<A NAME="IDX138"></A>
<H3><A NAME="SEC22" HREF="library_toc.html#SEC22">Basic Storage Allocation</A></H3>
<P>
To allocate a block of memory, call <CODE>malloc</CODE>.  The prototype for
this function is in <TT>`stdlib.h'</TT>.
<A NAME="IDX139"></A>
<P>
<A NAME="IDX140"></A>
<U>Function:</U> void * <B>malloc</B> <I>(size_t <VAR>size</VAR>)</I><P>
This function returns a pointer to a newly allocated block <VAR>size</VAR>
bytes long, or a null pointer if the block could not be allocated.
<P>
The contents of the block are undefined; you must initialize it yourself
(or use <CODE>calloc</CODE> instead; see section <A HREF="library.html#SEC26">Allocating Cleared Space</A>).
Normally you would cast the value as a pointer to the kind of object
that you want to store in the block.  Here we show an example of doing
so, and of initializing the space with zeros using the library function
<CODE>memset</CODE> (see section <A HREF="library.html#SEC61">Copying and Concatenation</A>):
<P>
<PRE>
struct foo *ptr;
...
ptr = (struct foo *) malloc (sizeof (struct foo));
if (ptr == 0) abort ();
memset (ptr, 0, sizeof (struct foo));
</PRE>
<P>
You can store the result of <CODE>malloc</CODE> into any pointer variable
without a cast, because ANSI C automatically converts the type
<CODE>void *</CODE> to another type of pointer when necessary.  But the cast
is necessary in contexts other than assignment operators or if you might
want your code to run in traditional C.
<P>
Remember that when allocating space for a string, the argument to
<CODE>malloc</CODE> must be one plus the length of the string.  This is
because a string is terminated with a null character that doesn't count
in the "length" of the string but does need space.  For example:
<P>
<PRE>
char *ptr;
...
ptr = (char *) malloc (length + 1);
</PRE>
<P>
See section <A HREF="library.html#SEC58">Representation of Strings</A>, for more information about this.
<P>
<H3><A NAME="SEC23" HREF="library_toc.html#SEC23">Examples of <CODE>malloc</CODE></A></H3>
<P>
If no more space is available, <CODE>malloc</CODE> returns a null pointer.
You should check the value of <EM>every</EM> call to <CODE>malloc</CODE>.  It is
useful to write a subroutine that calls <CODE>malloc</CODE> and reports an
error if the value is a null pointer, returning only if the value is
nonzero.  This function is conventionally called <CODE>xmalloc</CODE>.  Here
it is:
<P>
<PRE>
void *
xmalloc (size_t size)
{
  register void *value = malloc (size);
  if (value == 0)
    fatal ("virtual memory exhausted");
  return value;
}
</PRE>
<P>
Here is a real example of using <CODE>malloc</CODE> (by way of <CODE>xmalloc</CODE>).
The function <CODE>savestring</CODE> will copy a sequence of characters into
a newly allocated null-terminated string:
<P>
<PRE>
char *
savestring (const char *ptr, size_t len)
{
  register char *value = (char *) xmalloc (len + 1);
  memcpy (value, ptr, len);
  value[len] = 0;
  return value;
}
</PRE>
<P>
The block that <CODE>malloc</CODE> gives you is guaranteed to be aligned so
that it can hold any type of data.  In the GNU system, the address is
always a multiple of eight; if the size of block is 16 or more, then the
address is always a multiple of 16.  Only rarely is any higher boundary
(such as a page boundary) necessary; for those cases, use
<CODE>memalign</CODE> or <CODE>valloc</CODE> (see section <A HREF="library.html#SEC28">Allocating Aligned Memory Blocks</A>).
<P>
Note that the memory located after the end of the block is likely to be
in use for something else; perhaps a block already allocated by another
call to <CODE>malloc</CODE>.  If you attempt to treat the block as longer than
you asked for it to be, you are liable to destroy the data that
<CODE>malloc</CODE> uses to keep track of its blocks, or you may destroy the
contents of another block.  If you have already allocated a block and
discover you want it to be bigger, use <CODE>realloc</CODE> (see section <A HREF="library.html#SEC25">Changing the Size of a Block</A>).
<P>
<A NAME="IDX141"></A>
<A NAME="IDX142"></A>
<H3><A NAME="SEC24" HREF="library_toc.html#SEC24">Freeing Memory Allocated with <CODE>malloc</CODE></A></H3>
<P>
When you no longer need a block that you got with <CODE>malloc</CODE>, use the
function <CODE>free</CODE> to make the block available to be allocated again.
The prototype for this function is in <TT>`stdlib.h'</TT>.
<A NAME="IDX143"></A>
<P>
<A NAME="IDX144"></A>
<U>Function:</U> void <B>free</B> <I>(void *<VAR>ptr</VAR>)</I><P>
The <CODE>free</CODE> function deallocates the block of storage pointed at
by <VAR>ptr</VAR>.
<P>
<A NAME="IDX145"></A>
<U>Function:</U> void <B>cfree</B> <I>(void *<VAR>ptr</VAR>)</I><P>
This function does the same thing as <CODE>free</CODE>.  It's provided for
backward compatibility with SunOS; you should use <CODE>free</CODE> instead.
<P>
Freeing a block alters the contents of the block.  <STRONG>Do not expect to
find any data (such as a pointer to the next block in a chain of blocks) in
the block after freeing it.</STRONG>  Copy whatever you need out of the block before
freeing it!  Here is an example of the proper way to free all the blocks in
a chain, and the strings that they point to:
<P>
<PRE>
struct chain
  {
    struct chain *next;
    char *name;
  }

void
free_chain (struct chain *chain)
{
  while (chain != 0)
    {
      struct chain *next = chain-&#62;next;
      free (chain-&#62;name);
      free (chain);
      chain = next;
    }
}
</PRE>
<P>
Occasionally, <CODE>free</CODE> can actually return memory to the operating
system and make the process smaller.  Usually, all it can do is allow a
later later call to <CODE>malloc</CODE> to reuse the space.  In the mean time,
the space remains in your program as part of a free-list used internally
by <CODE>malloc</CODE>.
<P>
There is no point in freeing blocks at the end of a program, because all
of the program's space is given back to the system when the process
terminates.
<P>
<A NAME="IDX146"></A>
<H3><A NAME="SEC25" HREF="library_toc.html#SEC25">Changing the Size of a Block</A></H3>
<P>
Often you do not know for certain how big a block you will ultimately need
at the time you must begin to use the block.  For example, the block might
be a buffer that you use to hold a line being read from a file; no matter
how long you make the buffer initially, you may encounter a line that is
longer.
<P>
You can make the block longer by calling <CODE>realloc</CODE>.  This function
is declared in <TT>`stdlib.h'</TT>.
<A NAME="IDX147"></A>
<P>
<A NAME="IDX148"></A>
<U>Function:</U> void * <B>realloc</B> <I>(void *<VAR>ptr</VAR>, size_t <VAR>newsize</VAR>)</I><P>
The <CODE>realloc</CODE> function changes the size of the block whose address is
<VAR>ptr</VAR> to be <VAR>newsize</VAR>.
<P>
Since the space after the end of the block may be in use, <CODE>realloc</CODE>
may find it necessary to copy the block to a new address where more free
space is available.  The value of <CODE>realloc</CODE> is the new address of the
block.  If the block needs to be moved, <CODE>realloc</CODE> copies the old
contents.
<P>
Like <CODE>malloc</CODE>, <CODE>realloc</CODE> may return a null pointer if no
memory space is available to make the block bigger.  When this happens,
the original block is untouched; it has not been modified or relocated.
<P>
In most cases it makes no difference what happens to the original block
when <CODE>realloc</CODE> fails, because the application program cannot continue
when it is out of memory, and the only thing to do is to give a fatal error
message.  Often it is convenient to write and use a subroutine,
conventionally called <CODE>xrealloc</CODE>, that takes care of the error message
as <CODE>xmalloc</CODE> does for <CODE>malloc</CODE>:
<P>
<PRE>
void *
xrealloc (void *ptr, size_t size)
{
  register void *value = realloc (ptr, size);
  if (value == 0)
    fatal ("Virtual memory exhausted");
  return value;
}
</PRE>
<P>
You can also use <CODE>realloc</CODE> to make a block smaller.  The reason you
would do this is to avoid tying up a lot of memory space when only a little
is needed.  Making a block smaller sometimes necessitates copying it, so it
can fail if no other space is available.
<P>
If the new size you specify is the same as the old size, <CODE>realloc</CODE>
is guaranteed to change nothing and return the same address that you gave.
<P>
<H3><A NAME="SEC26" HREF="library_toc.html#SEC26">Allocating Cleared Space</A></H3>
<P>
The function <CODE>calloc</CODE> allocates memory and clears it to zero.  It
is declared in <TT>`stdlib.h'</TT>.
<A NAME="IDX149"></A>
<P>
<A NAME="IDX150"></A>
<U>Function:</U> void * <B>calloc</B> <I>(size_t <VAR>count</VAR>, size_t <VAR>eltsize</VAR>)</I><P>
This function allocates a block long enough to contain a vector of
<VAR>count</VAR> elements, each of size <VAR>eltsize</VAR>.  Its contents are
cleared to zero before <CODE>calloc</CODE> returns.
<P>
You could define <CODE>calloc</CODE> as follows:
<P>
<PRE>
void *
calloc (size_t count, size_t eltsize)
{
  size_t size = count * eltsize;
  void *value = malloc (size);
  if (value != 0)
    memset (value, 0, size);
  return value;
}
</PRE>
<P>
We rarely use <CODE>calloc</CODE> today, because it is equivalent to such a
simple combination of other features that are more often used.  It is a
historical holdover that is not quite obsolete.
<P>
<A NAME="IDX151"></A>
<H3><A NAME="SEC27" HREF="library_toc.html#SEC27">Efficiency Considerations for <CODE>malloc</CODE></A></H3>
<P>
To make the best use of <CODE>malloc</CODE>, it helps to know that the GNU
version of <CODE>malloc</CODE> always dispenses small amounts of memory in
blocks whose sizes are powers of two.  It keeps separate pools for each
power of two.  This holds for sizes up to a page size.  Therefore, if
you are free to choose the size of a small block in order to make
<CODE>malloc</CODE> more efficient, make it a power of two.
<P>
Once a page is split up for a particular block size, it can't be reused
for another size unless all the blocks in it are freed.  In many
programs, this is unlikely to happen.  Thus, you can sometimes make a
program use memory more efficiently by using blocks of the same size for
many different purposes.
<P>
When you ask for memory blocks of a page or larger, <CODE>malloc</CODE> uses a
different strategy; it rounds the size up to a multiple of a page, and
it can coalesce and split blocks as needed.
<P>
The reason for the two strategies is that it is important to allocate
and free small blocks as fast as possible, but speed is less important
for a large block since the program normally spends a fair amount of
time using it.  Also, large blocks are normally fewer in number.
Therefore, for large blocks, it makes sense to use a method which takes
more time to minimize the wasted space.
<P>
<H3><A NAME="SEC28" HREF="library_toc.html#SEC28">Allocating Aligned Memory Blocks</A></H3>
<A NAME="IDX152"></A>
<A NAME="IDX153"></A>
<A NAME="IDX154"></A>
<P>
The address of a block returned by <CODE>malloc</CODE> or <CODE>realloc</CODE> in
the GNU system is always a multiple of eight.  If you need a block whose
address is a multiple of a higher power of two than that, use
<CODE>memalign</CODE> or <CODE>valloc</CODE>.  These functions are declared in
<TT>`stdlib.h'</TT>.
<P>
With the GNU library, you can use <CODE>free</CODE> to free the blocks that
<CODE>memalign</CODE> and <CODE>valloc</CODE> return.  That does not work in BSD,
however--BSD does not provide any way to free such blocks.
<P>
<A NAME="IDX155"></A>
<U>Function:</U> void * <B>memalign</B> <I>(size_t <VAR>size</VAR>, int <VAR>boundary</VAR>)</I><P>
The <CODE>memalign</CODE> function allocates a block of <VAR>size</VAR> bytes whose
address is a multiple of <VAR>boundary</VAR>.  The <VAR>boundary</VAR> must be a
power of two!  The function <CODE>memalign</CODE> works by calling
<CODE>malloc</CODE> to allocate a somewhat larger block, and then returning an
address within the block that is on the specified boundary.
<P>
<A NAME="IDX156"></A>
<U>Function:</U> void * <B>valloc</B> <I>(size_t <VAR>size</VAR>)</I><P>
Using <CODE>valloc</CODE> is like using <CODE>memalign</CODE> and passing the page size
as the value of the second argument.
<P>
<H3><A NAME="SEC29" HREF="library_toc.html#SEC29">Heap Consistency Checking</A></H3>
<A NAME="IDX157"></A>
<A NAME="IDX158"></A>
<P>
You can ask <CODE>malloc</CODE> to check the consistency of dynamic storage by
using the <CODE>mcheck</CODE> function.  This function is a GNU extension,
declared in <TT>`malloc.h'</TT>.
<A NAME="IDX159"></A>
<P>
<A NAME="IDX160"></A>
<U>Function:</U> void <B>mcheck</B> <I>(void (*<VAR>abortfn</VAR>) (void))</I><P>
Calling <CODE>mcheck</CODE> tells <CODE>malloc</CODE> to perform occasional
consistency checks.  These will catch things such as writing
past the end of a block that was allocated with <CODE>malloc</CODE>.
<P>
The <VAR>abortfn</VAR> argument is the function to call when an inconsistency
is found.  If you supply a null pointer, the <CODE>abort</CODE> function is
used.
<P>
It is too late to begin allocation checking once you have allocated
anything with <CODE>malloc</CODE>.  So <CODE>mcheck</CODE> does nothing in that
case.  The function returns <CODE>-1</CODE> if you call it too late, and
<CODE>0</CODE> otherwise (when it is successful).
<P>
The easiest way to arrange to call <CODE>mcheck</CODE> early enough is to use
the option <SAMP>`-lmcheck'</SAMP> when you link your program.
<P>
<A NAME="IDX161"></A>
<H3><A NAME="SEC30" HREF="library_toc.html#SEC30">Storage Allocation Hooks</A></H3>
<P>
The GNU C library lets you modify the behavior of <CODE>malloc</CODE>,
<CODE>realloc</CODE>, and <CODE>free</CODE> by specifying appropriate hook
functions.  You can use these hooks to help you debug programs that use
dynamic storage allocation, for example.
<P>
The hook variables are declared in <TT>`malloc.h'</TT>.
<A NAME="IDX162"></A>
<P>
<A NAME="IDX163"></A>
<U>Variable:</U> <B>__malloc_hook</B><P>
The value of this variable is a pointer to function that <CODE>malloc</CODE>
uses whenever it is called.  You should define this function to look
like <CODE>malloc</CODE>; that is, like:
<P>
<PRE>
void *<VAR>function</VAR> (size_t <VAR>size</VAR>)
</PRE>
<P>
<A NAME="IDX164"></A>
<U>Variable:</U> <B>__realloc_hook</B><P>
The value of this variable is a pointer to function that <CODE>realloc</CODE>
uses whenever it is called.  You should define this function to look
like <CODE>realloc</CODE>; that is, like:
<P>
<PRE>
void *<VAR>function</VAR> (void *<VAR>ptr</VAR>, size_t <VAR>size</VAR>)
</PRE>
<P>
<A NAME="IDX165"></A>
<U>Variable:</U> <B>__free_hook</B><P>
The value of this variable is a pointer to function that <CODE>free</CODE>
uses whenever it is called.  You should define this function to look
like <CODE>free</CODE>; that is, like:
<P>
<PRE>
void <VAR>function</VAR> (void *<VAR>ptr</VAR>)
</PRE>
<P>
You must make sure that the function you install as a hook for one of
these functions does not call that function recursively without restoring
the old value of the hook first!  Otherwise, your program will get stuck
in an infinite recursion.
<P>
Here is an example showing how to use <CODE>__malloc_hook</CODE> properly.  It
installs a function that prints out information every time <CODE>malloc</CODE>
is called.
<P>
<PRE>
static void *(*old_malloc_hook) (size_t);
static void *
my_malloc_hook (size_t size)
{
  void *result;
  __malloc_hook = old_malloc_hook;
  result = malloc (size);
  __malloc_hook = my_malloc_hook;
  printf ("malloc (%u) returns %p\n", (unsigned int) size, result);
  return result;
}

main ()
{
  ...
  old_malloc_hook = __malloc_hook;
  __malloc_hook = my_malloc_hook;
  ...
}
</PRE>
<P>
The <CODE>mcheck</CODE> function (see section <A HREF="library.html#SEC29">Heap Consistency Checking</A>) works by
installing such hooks.
<P>
<H3><A NAME="SEC31" HREF="library_toc.html#SEC31">Statistics for Storage Allocation with <CODE>malloc</CODE></A></H3>
<A NAME="IDX166"></A>
<P>
You can get information about dynamic storage allocation by calling the
<CODE>mstats</CODE> function.  This function and its associated data type are
declared in <TT>`malloc.h'</TT>; they are a GNU extension.
<A NAME="IDX167"></A>
<P>
<A NAME="IDX168"></A>
<U>Data Type:</U> <B>struct mstats</B><P>
This structure type is used to return information about the dynamic
storage allocator.  It contains the following members:
<P>
<DL COMPACT>
<DT><CODE>size_t bytes_total</CODE>
<DD>This is the total size of memory managed by malloc, in bytes.
<P>
<DT><CODE>size_t chunks_used</CODE>
<DD>This is the number of chunks in use.  (The storage allocator internally
gets chunks of memory from the operating system, and then carves them up
to satisfy individual <CODE>malloc</CODE> requests; see section <A HREF="library.html#SEC27">Efficiency Considerations for <CODE>malloc</CODE></A>.)
<P>
<DT><CODE>size_t bytes_used</CODE>
<DD>This is the number of bytes in use.
<P>
<DT><CODE>size_t chunks_free</CODE>
<DD>This is the number of chunks which are free -- that is, that have been
allocated by the operating system to your program, but which are not
now being used.
<P>
<DT><CODE>size_t bytes_free</CODE>
<DD>This is the number of bytes which are free.
</DL>
<P>
<A NAME="IDX169"></A>
<U>Function:</U> struct mstats <B>mstats</B> <I>(void)</I><P>
This function returns information about the current dynamic memory usage
in a structure of type <CODE>struct mstats</CODE>.
<P>
<H3><A NAME="SEC32" HREF="library_toc.html#SEC32">Summary of <CODE>malloc</CODE>-Related Functions</A></H3>
<P>
Here is a summary of the functions that work with <CODE>malloc</CODE>:
<P>
<DL COMPACT>
<DT><CODE>void *malloc (size_t <VAR>size</VAR>)</CODE>
<DD>Allocate a block of <VAR>size</VAR> bytes.  See section <A HREF="library.html#SEC22">Basic Storage Allocation</A>.
<P>
<DT><CODE>void free (void *<VAR>addr</VAR>)</CODE>
<DD>Free a block previously allocated by <CODE>malloc</CODE>.  See section <A HREF="library.html#SEC24">Freeing Memory Allocated with <CODE>malloc</CODE></A>.
<P>
<DT><CODE>void *realloc (void *<VAR>addr</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>Make a block previously allocated by <CODE>malloc</CODE> larger or smaller,
possibly by copying it to a new location.  See section <A HREF="library.html#SEC25">Changing the Size of a Block</A>.
<P>
<DT><CODE>void *calloc (size_t <VAR>count</VAR>, size_t <VAR>eltsize</VAR>)</CODE>
<DD>Allocate a block of <VAR>count</VAR> * <VAR>eltsize</VAR> bytes using
<CODE>malloc</CODE>, and set its contents to zero.  See section <A HREF="library.html#SEC26">Allocating Cleared Space</A>.
<P>
<DT><CODE>void *valloc (size_t <VAR>size</VAR>)</CODE>
<DD>Allocate a block <VAR>size</VAR> bytes, starting on a page boundary.
See section <A HREF="library.html#SEC28">Allocating Aligned Memory Blocks</A>.
<P>
<DT><CODE>void *memalign (size_t <VAR>size</VAR>, size_t <VAR>boundary</VAR>)</CODE>
<DD>Allocate a block <VAR>size</VAR> bytes, starting on an address that is a
multiple of <VAR>boundary</VAR>.  See section <A HREF="library.html#SEC28">Allocating Aligned Memory Blocks</A>.
<P>
<DT><CODE>void mcheck (void (*<VAR>abortfn</VAR>) (void))</CODE>
<DD>Tell <CODE>malloc</CODE> to perform occasional consistency checks on
dynamically allocated memory, and to call <VAR>abortfn</VAR> when an
inconsistency is found.  See section <A HREF="library.html#SEC29">Heap Consistency Checking</A>.
<P>
<DT><CODE>void *(*__malloc_hook) (size_t <VAR>size</VAR>)</CODE>
<DD>A pointer to a function that <CODE>malloc</CODE> uses whenever it is called.
<P>
<DT><CODE>void *(*__realloc_hook) (void *<VAR>ptr</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>A pointer to a function that <CODE>realloc</CODE> uses whenever it is called.
<P>
<DT><CODE>void (*__free_hook) (void *<VAR>ptr</VAR>)</CODE>
<DD>A pointer to a function that <CODE>free</CODE> uses whenever it is called.
<P>
<DT><CODE>void struct mstats mstats (void)</CODE>
<DD>Read information about the current dynamic memory usage.
See section <A HREF="library.html#SEC31">Statistics for Storage Allocation with <CODE>malloc</CODE></A>.
</DL>
<P>
<A NAME="IDX170"></A>
<H2><A NAME="SEC33" HREF="library_toc.html#SEC33">Obstacks</A></H2>
<P>
An <DFN>obstack</DFN> is a pool of memory containing a stack of objects.  You
can create any number of separate obstacks, and then allocate objects in
specified obstacks.  Within each obstack, the last object allocated must
always be the first one freed, but distinct obstacks are independent of
each other.
<P>
Aside from this one constraint of order of freeing, obstacks are totally
general: an obstack can contain any number of objects of any size.  They
are implemented with macros, so allocation is usually very fast as long as
the objects are usually small.  And the only space overhead per object is
the padding needed to start each object on a suitable boundary.
<P>
<H3><A NAME="SEC34" HREF="library_toc.html#SEC34">Creating Obstacks</A></H3>
<P>
The utilities for manipulating obstacks are declared in the header
file <TT>`obstack.h'</TT>.
<A NAME="IDX171"></A>
<P>
<A NAME="IDX172"></A>
<U>Data Type:</U> <B>struct obstack</B><P>
An obstack is represented by a data structure of type <CODE>struct
obstack</CODE>.  This structure has a small fixed size; it records the status
of the obstack and how to find the space in which objects are allocated.
It does not contain any of the objects themselves.  You should not try
to access the contents of the structure directly; use only the functions
described in this chapter.
<P>
You can declare variables of type <CODE>struct obstack</CODE> and use them as
obstacks, or you can allocate obstacks dynamically like any other kind
of object.  Dynamic allocation of obstacks allows your program to have a
variable number of different stacks.  (You can even allocate an
obstack structure in another obstack, but this is rarely useful.)
<P>
All the functions that work with obstacks require you to specify which
obstack to use.  You do this with a pointer of type <CODE>struct obstack
*</CODE>.  In the following, we often say "an obstack" when strictly
speaking the object at hand is such a pointer.
<P>
The objects in the obstack are packed into large blocks called
<DFN>chunks</DFN>.  The <CODE>struct obstack</CODE> structure points to a chain of
the chunks currently in use.
<P>
The obstack library obtains a new chunk whenever you allocate an object
that won't fit in the previous chunk.  Since the obstack library manages
chunks automatically, you don't need to pay much attention to them, but
you do need to supply a function which the obstack library should use to
get a chunk.  Usually you supply a function which uses <CODE>malloc</CODE>
directly or indirectly.  You must also supply a function to free a chunk.
These matters are described in the following section.
<P>
<H3><A NAME="SEC35" HREF="library_toc.html#SEC35">Preparing for Using Obstacks</A></H3>
<P>
Each source file in which you plan to use the obstack functions
must include the header file <TT>`obstack.h'</TT>, like this:
<P>
<PRE>
#include &#60;obstack.h&#62;
</PRE>
<A NAME="IDX173"></A>
<A NAME="IDX174"></A>
<P>
Also, if the source file uses the macro <CODE>obstack_init</CODE>, it must
declare or define two functions or macros that will be called by the
obstack library.  One, <CODE>obstack_chunk_alloc</CODE>, is used to allocate the
chunks of memory into which objects are packed.  The other,
<CODE>obstack_chunk_free</CODE>, is used to return chunks when the objects in
them are freed.
<P>
Usually these are defined to use <CODE>malloc</CODE> via the intermediary
<CODE>xmalloc</CODE> (see section <A HREF="library.html#SEC21">Unconstrained Allocation</A>).  This is done with
the following pair of macro definitions:
<P>
<PRE>
#define obstack_chunk_alloc xmalloc
#define obstack_chunk_free free
</PRE>
<P>
Though the storage you get using obstacks really comes from <CODE>malloc</CODE>,
using obstacks is faster because <CODE>malloc</CODE> is called less often, for
larger blocks of memory.  See section <A HREF="library.html#SEC43">Obstack Chunks</A>, for full details.
<P>
At run time, before the program can use a <CODE>struct obstack</CODE> object
as an obstack, it must initialize the obstack by calling
<CODE>obstack_init</CODE>.
<P>
<A NAME="IDX175"></A>
<U>Function:</U> void <B>obstack_init</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>)</I><P>
Initialize obstack <VAR>obstack_ptr</VAR> for allocation of objects.
<P>
Here are two examples of how to allocate the space for an obstack and
initialize it.  First, an obstack that is a static variable:
<P>
<PRE>
struct obstack myobstack;
...
obstack_init (&#38;myobstack);
</PRE>
<P>
Second, an obstack that is itself dynamically allocated:
<P>
<PRE>
struct obstack *myobstack_ptr
  = (struct obstack *) xmalloc (sizeof (struct obstack));

obstack_init (myobstack_ptr);
</PRE>
<P>
<A NAME="IDX176"></A>
<H3><A NAME="SEC36" HREF="library_toc.html#SEC36">Allocation in an Obstack</A></H3>
<P>
The most direct way to allocate an object in an obstack is with
<CODE>obstack_alloc</CODE>, which is invoked almost like <CODE>malloc</CODE>.
<P>
<A NAME="IDX177"></A>
<U>Function:</U> void * <B>obstack_alloc</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>, size_t <VAR>size</VAR>)</I><P>
This allocates an uninitialized block of <VAR>size</VAR> bytes in an obstack
and returns its address.  Here <VAR>obstack_ptr</VAR> specifies which obstack
to allocate the block in; it is the address of the <CODE>struct obstack</CODE>
object which represents the obstack.  Each obstack function or macro
requires you to specify an <VAR>obstack_ptr</VAR> as the first argument.
<P>
For example, here is a function that allocates a copy of a string <VAR>str</VAR>
in a specific obstack, which is the variable <CODE>string_obstack</CODE>:
<P>
<PRE>
struct obstack string_obstack;

char *
copystring (char *string)
{
  char *s = (char *) obstack_alloc (&#38;string_obstack,
                                    strlen (string) + 1);
  memcpy (s, string, strlen (string));
  return s;
}
</PRE>
<P>
To allocate a block with specified contents, use the function
<CODE>obstack_copy</CODE>, declared like this:
<P>
<A NAME="IDX178"></A>
<U>Function:</U> void * <B>obstack_copy</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>address</VAR>, size_t <VAR>size</VAR>)</I><P>
This allocates a block and initializes it by copying <VAR>size</VAR>
bytes of data starting at <VAR>address</VAR>.
<P>
<A NAME="IDX179"></A>
<U>Function:</U> void * <B>obstack_copy0</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>address</VAR>, size_t <VAR>size</VAR>)</I><P>
Like <CODE>obstack_copy</CODE>, but appends an extra byte containing a null
character.  This extra byte is not counted in the argument <VAR>size</VAR>.
<P>
The <CODE>obstack_copy0</CODE> function is convenient for copying a sequence
of characters into an obstack as a null-terminated string.  Here is an
example of its use:
<P>
<PRE>
char *
obstack_savestring (char *addr, size_t size)
{
  return obstack_copy0 (&#38;myobstack, addr, size);
}
</PRE>
<P>
Contrast this with the previous example of <CODE>savestring</CODE> using
<CODE>malloc</CODE> (see section <A HREF="library.html#SEC22">Basic Storage Allocation</A>).
<P>
<A NAME="IDX180"></A>
<H3><A NAME="SEC37" HREF="library_toc.html#SEC37">Freeing Objects in an Obstack</A></H3>
<P>
To free an object allocated in an obstack, use the function
<CODE>obstack_free</CODE>.  Since the obstack is a stack of objects, freeing
one object automatically frees all other objects allocated more recently
in the same obstack.
<P>
<A NAME="IDX181"></A>
<U>Function:</U> void <B>obstack_free</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>object</VAR>)</I><P>
If <VAR>object</VAR> is a null pointer, everything allocated in the obstack
is freed.  Otherwise, <VAR>object</VAR> must be the address of an object
allocated in the obstack.  Then <VAR>object</VAR> is freed, along with
everything allocated in <VAR>obstack</VAR> since <VAR>object</VAR>.
<P>
Note that if <VAR>object</VAR> is a null pointer, the result is an
uninitialized obstack.  To free all storage in an obstack but leave it
valid for further allocation, call <CODE>obstack_free</CODE> with the address
of the first object allocated on the obstack:
<P>
<PRE>
obstack_free (obstack_ptr, first_object_allocated_ptr);
</PRE>
<P>
Recall that the objects in an obstack are grouped into chunks.  When all
the objects in a chunk become free, the obstack library automatically
frees the chunk (see section <A HREF="library.html#SEC35">Preparing for Using Obstacks</A>).  Then other
obstacks, or non-obstack allocation, can reuse the space of the chunk.
<P>
<A NAME="IDX182"></A>
<H3><A NAME="SEC38" HREF="library_toc.html#SEC38">Obstack Functions and Macros</A></H3>
<P>
The interfaces for using obstacks may be defined either as functions or
as macros, depending on the compiler.  The obstack facility works with
all C compilers, including both ANSI C and traditional C, but there are
precautions you must take if you plan to use compilers other than GNU C.
<P>
If you are using an old-fashioned non-ANSI C compiler, all the obstack
"functions" are actually defined only as macros.  You can call these
macros like functions, but you cannot use them in any other way (for
example, you cannot take their address).
<P>
Calling the macros requires a special precaution: namely, the first
operand (the obstack pointer) may not contain any side effects, because
it may be computed more than once.  For example, if you write this:
<P>
<PRE>
obstack_alloc (get_obstack (), 4);
</PRE>
<P>
you will find that <CODE>get_obstack</CODE> may be called several times.
If you use <CODE>*obstack_list_ptr++</CODE> as the obstack pointer argument,
you will get very strange results since the incrementation may occur
several times.
<P>
In ANSI C, each function has both a macro definition and a function
definition.  The function definition is used if you take the address of the
function without calling it.  An ordinary call uses the macro definition by
default, but you can request the function definition instead by writing the
function name in parentheses, as shown here:
<P>
<PRE>
char *x;
void *(*funcp) ();
/* Use the macro.  */
x = (char *) obstack_alloc (obptr, size);
/* Call the function.  */
x = (char *) (obstack_alloc) (obptr, size);
/* Take the address of the function.  */
funcp = obstack_alloc;
</PRE>
<P>
This is the same situation that exists in ANSI C for the standard library
functions.  See section <A HREF="library.html#SEC10">Macro Definitions of Functions</A>.
<P>
<STRONG>Warning:</STRONG> When you do use the macros, you must observe the
precaution of avoiding side effects in the first operand, even in ANSI
C.
<P>
If you use the GNU C compiler, this precaution is not necessary, because
various language extensions in GNU C permit defining the macros so as to
compute each argument only once.
<P>
<A NAME="IDX183"></A>
<A NAME="IDX184"></A>
<H3><A NAME="SEC39" HREF="library_toc.html#SEC39">Growing Objects</A></H3>
<P>
Because storage in obstack chunks is used sequentially, it is possible to
build up an object step by step, adding one or more bytes at a time to the
end of the object.  With this technique, you do not need to know how much
data you will put in the object until you come to the end of it.  We call
this the technique of <DFN>growing objects</DFN>.  The special functions
for adding data to the growing object are described in this section.
<P>
You don't need to do anything special when you start to grow an object.
Using one of the functions to add data to the object automatically
starts it.  However, it is necessary to say explicitly when the object is
finished.  This is done with the function <CODE>obstack_finish</CODE>.
<P>
The actual address of the object thus built up is not known until the
object is finished.  Until then, it always remains possible that you will
add so much data that the object must be copied into a new chunk.
<P>
While the obstack is in use for a growing object, you cannot use it for
ordinary allocation of another object.  If you try to do so, the space
already added to the growing object will become part of the other object.
<P>
<A NAME="IDX185"></A>
<U>Function:</U> void <B>obstack_blank</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>, size_t <VAR>size</VAR>)</I><P>
The most basic function for adding to a growing object is
<CODE>obstack_blank</CODE>, which adds space without initializing it.
<P>
<A NAME="IDX186"></A>
<U>Function:</U> void <B>obstack_grow</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>data</VAR>, size_t <VAR>size</VAR>)</I><P>
To add a block of initialized space, use <CODE>obstack_grow</CODE>, which is
the growing-object analogue of <CODE>obstack_copy</CODE>.  It adds <VAR>size</VAR>
bytes of data to the growing object, copying the contents from
<VAR>data</VAR>.
<P>
<A NAME="IDX187"></A>
<U>Function:</U> void <B>obstack_grow0</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>data</VAR>, size_t <VAR>size</VAR>)</I><P>
This is the growing-object analogue of <CODE>obstack_copy0</CODE>.  It adds
<VAR>size</VAR> bytes copied from <VAR>data</VAR>, followed by an additional null
character.
<P>
<A NAME="IDX188"></A>
<U>Function:</U> void <B>obstack_1grow</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>, char <VAR>c</VAR>)</I><P>
To add one character at a time, use the function <CODE>obstack_1grow</CODE>.
It adds a single byte containing <VAR>c</VAR> to the growing object.
<P>
<A NAME="IDX189"></A>
<U>Function:</U> void * <B>obstack_finish</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>)</I><P>
When you are finished growing the object, use the function
<CODE>obstack_finish</CODE> to close it off and return its final address.
<P>
Once you have finished the object, the obstack is available for ordinary
allocation or for growing another object.
<P>
When you build an object by growing it, you will probably need to know
afterward how long it became.  You need not keep track of this as you grow
the object, because you can find out the length from the obstack just
before finishing the object with the function <CODE>obstack_object_size</CODE>,
declared as follows:
<P>
<A NAME="IDX190"></A>
<U>Function:</U> size_t <B>obstack_object_size</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>)</I><P>
This function returns the current size of the growing object, in bytes.
Remember to call this function <EM>before</EM> finishing the object.
After it is finished, <CODE>obstack_object_size</CODE> will return zero.
<P>
If you have started growing an object and wish to cancel it, you should
finish it and then free it, like this:
<P>
<PRE>
obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
</PRE>
<P>
This has no effect if no object was growing.
<A NAME="IDX191"></A>
<P>
You can use <CODE>obstack_blank</CODE> with a negative size argument to make
the current object smaller.  Just don't try to shrink it beyond zero
length--there's no telling what will happen if you do that.
<P>
<A NAME="IDX192"></A>
<H3><A NAME="SEC40" HREF="library_toc.html#SEC40">Extra Fast Growing Objects</A></H3>
<P>
The usual functions for growing objects incur overhead for checking
whether there is room for the new growth in the current chunk.  If you
are frequently constructing objects in small steps of growth, this
overhead can be significant.
<P>
You can reduce the overhead by using special "fast growth"
functions that grow the object without checking.  In order to have a
robust program, you must do the checking yourself.  If you do this checking
in the simplest way each time you are about to add data to the object, you
have not saved anything, because that is what the ordinary growth
functions do.  But if you can arrange to check less often, or check
more efficiently, then you make the program faster.
<P>
The function <CODE>obstack_room</CODE> returns the amount of room available
in the current chunk.  It is declared as follows:
<P>
<A NAME="IDX193"></A>
<U>Function:</U> size_t <B>obstack_room</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>)</I><P>
This returns the number of bytes that can be added safely to the current
growing object (or to an object about to be started) in obstack
<VAR>obstack</VAR> using the fast growth functions.
<P>
While you know there is room, you can use these fast growth functions
for adding data to a growing object:
<P>
<A NAME="IDX194"></A>
<U>Function:</U> void <B>obstack_1grow_fast</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>, char <VAR>c</VAR>)</I><P>
The function <CODE>obstack_1grow_fast</CODE> adds one byte containing the
character <VAR>c</VAR> to the growing object in obstack <VAR>obstack_ptr</VAR>.
<P>
<A NAME="IDX195"></A>
<U>Function:</U> void <B>obstack_blank_fast</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>, size_t <VAR>size</VAR>)</I><P>
The function <CODE>obstack_blank_fast</CODE> adds <VAR>size</VAR> bytes to the
growing object in obstack <VAR>obstack_ptr</VAR> without initializing them.
<P>
When you check for space using <CODE>obstack_room</CODE> and there is not
enough room for what you want to add, the fast growth functions
are not safe.  In this case, simply use the corresponding ordinary
growth function instead.  Very soon this will copy the object to a
new chunk; then there will be lots of room available again. 
<P>
So, each time you use an ordinary growth function, check afterward for
sufficient space using <CODE>obstack_room</CODE>.  Once the object is copied
to a new chunk, there will be plenty of space again, so the program will
start using the fast growth functions again.
<P>
Here is an example:
<P>
<PRE>
void
add_string (struct obstack *obstack, char *ptr, size_t len)
{
  while (len &#62; 0)
    {
      if (obstack_room (obstack) &#62; len)
        {
          /* We have enough room: add everything fast.  */
          while (len-- &#62; 0)
            obstack_1grow_fast (obstack, *ptr++);
        }
      else
        {
          /* Not enough room. Add one character slowly,
             which may copy to a new chunk and make room.  */
          obstack_1grow (obstack, *ptr++);
          len--;
        }
    }
}
</PRE>
<P>
<A NAME="IDX196"></A>
<A NAME="IDX197"></A>
<H3><A NAME="SEC41" HREF="library_toc.html#SEC41">Status of an Obstack</A></H3>
<P>
Here are functions that provide information on the current status of
allocation in an obstack.  You can use them to learn about an object while
still growing it.
<P>
<A NAME="IDX198"></A>
<U>Function:</U> void * <B>obstack_base</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>)</I><P>
This function returns the tentative address of the beginning of the
currently growing object in <VAR>obstack_ptr</VAR>.  If you finish the object
immediately, it will have that address.  If you make it larger first, it
may outgrow the current chunk--then its address will change!
<P>
If no object is growing, this value says where the next object you
allocate will start (once again assuming it fits in the current
chunk).
<P>
<A NAME="IDX199"></A>
<U>Function:</U> void * <B>obstack_next_free</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>)</I><P>
This function returns the address of the first free byte in the current
chunk of obstack <VAR>obstack_ptr</VAR>.  This is the end of the currently
growing object.  If no object is growing, <CODE>obstack_next_free</CODE>
returns the same value as <CODE>obstack_base</CODE>.
<P>
<A NAME="IDX200"></A>
<U>Function:</U> size_t <B>obstack_object_size</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>)</I><P>
This function returns the size in bytes of the currently growing object.
This is equivalent to
<P>
<PRE>
obstack_next_free (<VAR>obstack_ptr</VAR>) - obstack_base (<VAR>obstack_ptr</VAR>)
</PRE>
<P>
<A NAME="IDX201"></A>
<H3><A NAME="SEC42" HREF="library_toc.html#SEC42">Alignment of Data in Obstacks</A></H3>
<P>
Each obstack has an <DFN>alignment boundary</DFN>; each object allocated in
the obstack automatically starts on an address that is a multiple of the
specified boundary.  By default, this boundary is 4 bytes.
<P>
To access an obstack's alignment boundary, use the macro
<CODE>obstack_alignment_mask</CODE>, whose function prototype looks like
this:
<P>
<A NAME="IDX202"></A>
<U>Macro:</U> int <B>obstack_alignment_mask</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>)</I><P>
The value is a bit mask; a bit that is 1 indicates that the corresponding
bit in the address of an object should be 0.  The mask value should be one
less than a power of 2; the effect is that all object addresses are
multiples of that power of 2.  The default value of the mask is 3, so that
addresses are multiples of 4.  A mask value of 0 means an object can start
on any multiple of 1 (that is, no alignment is required).
<P>
The expansion of the macro <CODE>obstack_alignment_mask</CODE> is an lvalue,
so you can alter the mask by assignment.  For example, this statement:
<P>
<PRE>
obstack_alignment_mask (obstack_ptr) = 0;
</PRE>
<P>
has the effect of turning off alignment processing in the specified obstack.
<P>
Note that a change in alignment mask does not take effect until
<EM>after</EM> the next time an object is allocated or finished in the
obstack.  If you are not growing an object, you can make the new
alignment mask take effect immediately by calling <CODE>obstack_finish</CODE>.
This will finish a zero-length object and then do proper alignment for
the next object.
<P>
<A NAME="IDX203"></A>
<A NAME="IDX204"></A>
<H3><A NAME="SEC43" HREF="library_toc.html#SEC43">Obstack Chunks</A></H3>
<P>
Obstacks work by allocating space for themselves in large chunks, and
then parceling out space in the chunks to satisfy your requests.  Chunks
are normally 4096 bytes long unless you specify a different chunk size.
The chunk size includes 8 bytes of overhead that are not actually used
for storing objects.  Regardless of the specified size, longer chunks
will be allocated when necessary for long objects.
<P>
The obstack library allocates chunks by calling the function
<CODE>obstack_chunk_alloc</CODE>, which you must define.  When a chunk is no
longer needed because you have freed all the objects in it, the obstack
library frees the chunk by calling <CODE>obstack_chunk_free</CODE>, which you
must also define.
<P>
These two must be defined (as macros) or declared (as functions) in each
source file that uses <CODE>obstack_init</CODE> (see section <A HREF="library.html#SEC34">Creating Obstacks</A>).
Most often they are defined as macros like this:
<P>
<PRE>
#define obstack_chunk_alloc xmalloc
#define obstack_chunk_free free
</PRE>
<P>
Note that these are simple macros (no arguments).  Macro definitions with
arguments will not work!  It is necessary that <CODE>obstack_chunk_alloc</CODE>
or <CODE>obstack_chunk_free</CODE>, alone, expand into a function name if it is
not itself a function name.
<P>
The function that actually implements <CODE>obstack_chunk_alloc</CODE> cannot
return "failure" in any fashion, because the obstack library is not
prepared to handle failure.  Therefore, <CODE>malloc</CODE> itself is not
suitable.  If the function cannot obtain space, it should either
terminate the process (see section <A HREF="library.html#SEC395">Program Termination</A>) or do a nonlocal
exit using <CODE>longjmp</CODE> (see section <A HREF="library.html#SEC326">Non-Local Exits</A>).
<P>
If you allocate chunks with <CODE>malloc</CODE>, the chunk size should be a
power of 2.  The default chunk size, 4096, was chosen because it is long
enough to satisfy many typical requests on the obstack yet short enough
not to waste too much memory in the portion of the last chunk not yet used.
<P>
<A NAME="IDX205"></A>
<U>Macro:</U> size_t <B>obstack_chunk_size</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>)</I><P>
This returns the chunk size of the given obstack.
<P>
Since this macro expands to an lvalue, you can specify a new chunk size by
assigning it a new value.  Doing so does not affect the chunks already
allocated, but will change the size of chunks allocated for that particular
obstack in the future.  It is unlikely to be useful to make the chunk size
smaller, but making it larger might improve efficiency if you are
allocating many objects whose size is comparable to the chunk size.  Here
is how to do so cleanly:
<P>
<PRE>
if (obstack_chunk_size (obstack_ptr) &#60; <VAR>new_chunk_size</VAR>)
  obstack_chunk_size (obstack_ptr) = <VAR>new_chunk_size</VAR>;
</PRE>
<P>
<H3><A NAME="SEC44" HREF="library_toc.html#SEC44">Summary of Obstack Functions</A></H3>
<P>
Here is a summary of all the functions associated with obstacks.  Each
takes the address of an obstack (<CODE>struct obstack *</CODE>) as its first
argument.
<P>
<DL COMPACT>
<DT><CODE>void obstack_init (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD>Initialize use of an obstack.  See section <A HREF="library.html#SEC34">Creating Obstacks</A>.
<P>
<DT><CODE>void *obstack_alloc (struct obstack *<VAR>obstack_ptr</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>Allocate an object of <VAR>size</VAR> uninitialized bytes.
See section <A HREF="library.html#SEC36">Allocation in an Obstack</A>.
<P>
<DT><CODE>void *obstack_copy (struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>address</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>Allocate an object of <VAR>size</VAR> bytes, with contents copied from
<VAR>address</VAR>.  See section <A HREF="library.html#SEC36">Allocation in an Obstack</A>.
<P>
<DT><CODE>void *obstack_copy0 (struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>address</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>Allocate an object of <VAR>size</VAR>+1 bytes, with <VAR>size</VAR> of them copied
from <VAR>address</VAR>, followed by a null character at the end.
See section <A HREF="library.html#SEC36">Allocation in an Obstack</A>.
<P>
<DT><CODE>void obstack_free (struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>object</VAR>)</CODE>
<DD>Free <VAR>object</VAR> (and everything allocated in the specified obstack
more recently than <VAR>object</VAR>).  See section <A HREF="library.html#SEC37">Freeing Objects in an Obstack</A>.
<P>
<DT><CODE>void obstack_blank (struct obstack *<VAR>obstack_ptr</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>Add <VAR>size</VAR> uninitialized bytes to a growing object.
See section <A HREF="library.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>void obstack_grow (struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>address</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>Add <VAR>size</VAR> bytes, copied from <VAR>address</VAR>, to a growing object.
See section <A HREF="library.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>void obstack_grow0 (struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>address</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>Add <VAR>size</VAR> bytes, copied from <VAR>address</VAR>, to a growing object,
and then add another byte containing a null character.  See section <A HREF="library.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>void obstack_1grow (struct obstack *<VAR>obstack_ptr</VAR>, char <VAR>data_char</VAR>)</CODE>
<DD>Add one byte containing <VAR>data_char</VAR> to a growing object.
See section <A HREF="library.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>void *obstack_finish (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD>Finalize the object that is growing and return its permanent address.
See section <A HREF="library.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>size_t obstack_object_size (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD>Get the current size of the currently growing object.  See section <A HREF="library.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>void obstack_blank_fast (struct obstack *<VAR>obstack_ptr</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>Add <VAR>size</VAR> uninitialized bytes to a growing object without checking
that there is enough room.  See section <A HREF="library.html#SEC40">Extra Fast Growing Objects</A>.
<P>
<DT><CODE>void obstack_1grow_fast (struct obstack *<VAR>obstack_ptr</VAR>, char <VAR>data_char</VAR>)</CODE>
<DD>Add one byte containing <VAR>data_char</VAR> to a growing object without
checking that there is enough room.  See section <A HREF="library.html#SEC40">Extra Fast Growing Objects</A>.
<P>
<DT><CODE>size_t obstack_room (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD>Get the amount of room now available for growing the current object.
See section <A HREF="library.html#SEC40">Extra Fast Growing Objects</A>.
<P>
<DT><CODE>int obstack_alignment_mask (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD>The mask used for aligning the beginning of an object.  This is an
lvalue.  See section <A HREF="library.html#SEC42">Alignment of Data in Obstacks</A>.
<P>
<DT><CODE>size_t obstack_chunk_size (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD>The size for allocating chunks.  This is an lvalue.  See section <A HREF="library.html#SEC43">Obstack Chunks</A>.
<P>
<DT><CODE>void *obstack_base (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD>Tentative starting address of the currently growing object.
See section <A HREF="library.html#SEC41">Status of an Obstack</A>.
<P>
<DT><CODE>void *obstack_next_free (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD>Address just after the end of the currently growing object.
See section <A HREF="library.html#SEC41">Status of an Obstack</A>.
</DL>
<P>
<A NAME="IDX206"></A>
<A NAME="IDX207"></A>
<A NAME="IDX208"></A>
<H2><A NAME="SEC45" HREF="library_toc.html#SEC45">Automatic Storage with Variable Size</A></H2>
<P>
The function <CODE>alloca</CODE> supports a kind of half-dynamic allocation in
which blocks are allocated dynamically but freed automatically.
<P>
Allocating a block with <CODE>alloca</CODE> is an explicit action; you can
allocate as many blocks as you wish, and compute the size at run time.  But
all the blocks are freed when you exit the function that <CODE>alloca</CODE> was
called from, just as if they were automatic variables declared in that
function.  There is no way to free the space explicitly.
<P>
The prototype for <CODE>alloca</CODE> is in <TT>`stdlib.h'</TT>.  This function is
a BSD extension.
<A NAME="IDX209"></A>
<P>
<A NAME="IDX210"></A>
<U>Function:</U> void * <B>alloca</B> <I>(size_t <VAR>size</VAR>);</I><P>
The return value of <CODE>alloca</CODE> is the address of a block of <VAR>size</VAR>
bytes of storage, allocated in the stack frame of the calling function.
<P>
Do not use <CODE>alloca</CODE> inside the arguments of a function call--you
will get unpredictable results, because the stack space for the
<CODE>alloca</CODE> would appear on the stack in the middle of the space for
the function arguments.  An example of what to avoid is <CODE>foo (x,
alloca (4), y)</CODE>.
<P>
<H3><A NAME="SEC46" HREF="library_toc.html#SEC46"><CODE>alloca</CODE> Example</A></H3>
<P>
As an example of use of <CODE>alloca</CODE>, here is a function that opens a file
name made from concatenating two argument strings, and returns a file
descriptor or minus one signifying failure:
<P>
<PRE>
int
open2 (char *str1, char *str2, int flags, int mode)
{
  char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
  strcpy (name, str1);
  strcat (name, str2);
  return open (name, flags, mode);
}
</PRE>
<P>
Here is how you would get the same results with <CODE>malloc</CODE> and
<CODE>free</CODE>:
<P>
<PRE>
int
open2 (char *str1, char *str2, int flags, int mode)
{
  char *name = (char *) malloc (strlen (str1) + strlen (str2) + 1);
  int desc;
  if (name == 0)
    fatal ("virtual memory exceeded");
  strcpy (name, str1);
  strcat (name, str2);
  desc = open (name, flags, mode);
  free (name);
  return desc;
}
</PRE>
<P>
As you can see, it is simpler with <CODE>alloca</CODE>.  But <CODE>alloca</CODE> has
other, more important advantages, and some disadvantages.
<P>
<H3><A NAME="SEC47" HREF="library_toc.html#SEC47">Advantages of <CODE>alloca</CODE></A></H3>
<P>
Here are the reasons why <CODE>alloca</CODE> may be preferable to <CODE>malloc</CODE>:
<P>
<UL>
<LI>
Using <CODE>alloca</CODE> wastes very little space and is very fast.  (It is
open-coded by the GNU C compiler.)
<P>
<LI>
Since <CODE>alloca</CODE> does not have separate pools for different sizes of
block, space used for any size block can be reused for any other size.
<CODE>alloca</CODE> does not cause storage fragmentation.
<P>
<A NAME="IDX211"></A>
<LI>
Nonlocal exits done with <CODE>longjmp</CODE> (see section <A HREF="library.html#SEC326">Non-Local Exits</A>)
automatically free the space allocated with <CODE>alloca</CODE> when they exit
through the function that called <CODE>alloca</CODE>.  This is the most
important reason to use <CODE>alloca</CODE>.
<P>
To illustrate this, suppose you have a function
<CODE>open_or_report_error</CODE> which returns a descriptor, like
<CODE>open</CODE>, if it succeeds, but does not return to its caller if it
fails.  If the file cannot be opened, it prints an error message and
jumps out to the command level of your program using <CODE>longjmp</CODE>.
Let's change <CODE>open2</CODE> (see section <A HREF="library.html#SEC46"><CODE>alloca</CODE> Example</A>) to use this
subroutine:<P>
<PRE>
int
open2 (char *str1, char *str2, int flags, int mode)
{
  char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
  strcpy (name, str1);
  strcat (name, str2);
  return open_or_report_error (name, flags, mode);
}
</PRE>
<P>
Because of the way <CODE>alloca</CODE> works, the storage it allocates is
freed even when an error occurs, with no special effort required.
<P>
By contrast, the previous definition of <CODE>open2</CODE> (which uses
<CODE>malloc</CODE> and <CODE>free</CODE>) would develop a storage leak if it were
changed in this way.  Even if you are willing to make more changes to
fix it, there is no easy way to do so.
</UL>
<P>
<H3><A NAME="SEC48" HREF="library_toc.html#SEC48">Disadvantages of <CODE>alloca</CODE></A></H3>
<A NAME="IDX212"></A>
<A NAME="IDX213"></A>
<P>
These are the disadvantages of <CODE>alloca</CODE> in comparison with
<CODE>malloc</CODE>:
<P>
<UL>
<LI>
If you try to allocate more storage than the machine can provide, you
don't get a clean error message.  Instead you get a fatal signal like
the one you would get from an infinite recursion; probably a
segmentation violation (see section <A HREF="library.html#SEC336">Program Error Signals</A>).
<P>
<LI>
Some non-GNU systems fail to support <CODE>alloca</CODE>, so it is less
portable.  However, a slower emulation of <CODE>alloca</CODE> written in C
is available for use on systems with this deficiency.
</UL>
<P>
<A NAME="IDX214"></A>
<H3><A NAME="SEC49" HREF="library_toc.html#SEC49">GNU C Variable-Size Arrays</A></H3>
<P>
In GNU C, you can replace most uses of <CODE>alloca</CODE> with an array of
variable size.  Here is how <CODE>open2</CODE> would look then:
<P>
<PRE>
int open2 (char *str1, char *str2, int flags, int mode)
{
  char name[strlen (str1) + strlen (str2) + 1];
  strcpy (name, str1);
  strcat (name, str2);
  return open (name, flags, mode);
}
</PRE>
<P>
But <CODE>alloca</CODE> is not always equivalent to a variable-sized array, for
several reasons:
<P>
<UL>
<LI>
A variable size array's space is freed at the end of the scope of the
name of the array.  The space allocated with <CODE>alloca</CODE> usually
remains until the end of the function.
<P>
<LI>
It is possible to use <CODE>alloca</CODE> within a loop, allocating an
additional block on each iteration.  This is impossible with
variable-sized arrays.  On the other hand, this is also slightly
unclean.
</UL>
<P>
<STRONG>Note:</STRONG> If you mix use of <CODE>alloca</CODE> and variable-sized arrays
within one function, exiting a scope in which a variable-sized array was
declared frees all blocks allocated with <CODE>alloca</CODE> during the
execution of that scope.
<P>
<H2><A NAME="SEC50" HREF="library_toc.html#SEC50">Relocating Allocator</A></H2>
<A NAME="IDX215"></A>
<P>
Any system of dynamic memory allocation has overhead: the amount of
space it uses is more than the amount the program asks for.  The
<DFN>relocating memory allocator</DFN> achieves very low overhead by moving
blocks in memory as necessary, on its own initiative.
<P>
<H3><A NAME="SEC51" HREF="library_toc.html#SEC51">Concepts of Relocating Allocation</A></H3>
<P>
When you allocate a block with <CODE>malloc</CODE>, the address of the block
never changes unless you use <CODE>realloc</CODE> to change its size.  Thus,
you can safely store the address in various places, temporarily or
permanently, as you like.  This is not safe when you use the relocating
memory allocator, because any and all relocatable blocks can move
whenever you allocate memory in any fashion.  Even calling <CODE>malloc</CODE>
or <CODE>realloc</CODE> can move the relocatable blocks.
<A NAME="IDX216"></A>
<P>
For each relocatable block, you must make a <DFN>handle</DFN>---a pointer
object in memory, designated to store the address of that block.  The
relocating allocator knows where each block's handle is, and updates the
address stored there whenever it moves the block, so that the handle
always points to the block.  Each time you access the contents of the
block, you should fetch its address anew from the handle.
<P>
To call any of the relocating allocator functions from a signal handler
is almost certainly incorrect, because the signal could happen at any
time and relocate all the blocks.  The only way to make this safe is to
block the signal around any access to the contents of any relocatable
block--not a convenient mode of operation.  See section <A HREF="library.html#SEC357">Signal Handling and Nonreentrant Functions</A>.
<P>
<H3><A NAME="SEC52" HREF="library_toc.html#SEC52">Allocating and Freeing Relocatable Blocks</A></H3>
<A NAME="IDX217"></A>
<P>
In the descriptions below, <VAR>handleptr</VAR> designates the address of the
handle.  All the functions are declared in <TT>`malloc.h'</TT>; all are GNU
extensions.
<P>
<A NAME="IDX218"></A>
<U>Function:</U> void * <B>r_alloc</B> <I>(void **<VAR>handleptr</VAR>, size_t <VAR>size</VAR>)</I><P>
This function allocates a relocatable block of size <VAR>size</VAR>.  It
stores the block's address in <CODE>*<VAR>handleptr</VAR></CODE> and returns
a non-null pointer to indicate success.
<P>
If <CODE>r_alloc</CODE> can't get the space needed, it stores a null pointer
in <CODE>*<VAR>handleptr</VAR></CODE>, and returns a null pointer.
<P>
<A NAME="IDX219"></A>
<U>Function:</U> void <B>r_alloc_free</B> <I>(void **<VAR>handleptr</VAR>)</I><P>
This function is the way to free a relocatable block.  It frees the
block that <CODE>*<VAR>handleptr</VAR></CODE> points to, and stores a null pointer
in <CODE>*<VAR>handleptr</VAR></CODE> to show it doesn't point to an allocated
block any more.
<P>
<A NAME="IDX220"></A>
<U>Function:</U> void * <B>r_re_alloc</B> <I>(void **<VAR>handleptr</VAR>, size_t <VAR>size</VAR>)</I><P>
The function <CODE>r_re_alloc</CODE> adjusts the size of the block that
<CODE>*<VAR>handleptr</VAR></CODE> points to, making it <VAR>size</VAR> bytes long.  It
stores the address of the resized block in <CODE>*<VAR>handleptr</VAR></CODE> and
returns a non-null pointer to indicate success.
<P>
If enough memory is not available, this function returns a null pointer
and does not modify <CODE>*<VAR>handleptr</VAR></CODE>.
<P>
<A NAME="IDX221"></A>
<A NAME="IDX222"></A>
<H2><A NAME="SEC53" HREF="library_toc.html#SEC53">Memory Usage Warnings</A></H2>
<A NAME="IDX223"></A>
<P>
You can ask for warnings as the program approaches running out of memory
space, by calling <CODE>memory_warnings</CODE>.  This is a GNU extension
declared in <TT>`malloc.h'</TT>.
<P>
<A NAME="IDX224"></A>
<U>Function:</U> void <B>memory_warnings</B> <I>(void *<VAR>start</VAR>, void (*<VAR>warn_func</VAR>) (char *))</I><P>
Call this function to request warnings for nearing exhaustion of virtual
memory.
<P>
The argument <VAR>start</VAR> says where data space begins, in memory.  The
allocator compares this against the last address used and against the
limit of data space, to determine the fraction of available memory in
use.  If you supply zero for <VAR>start</VAR>, then a default value is used
which is right in most circumstances.
<P>
For <VAR>warn_func</VAR>, supply a function that <CODE>malloc</CODE> can call to
warn you.  It is called with a string (a warning message) as argument.
Normally it ought to display the string for the user to read.
<P>
The warnings come when memory becomes 75% full, when it becomes 85%
full, and when it becomes 95% full.  Above 95% you get another warning
each time memory usage increases.
<P>
<H1><A NAME="SEC54" HREF="library_toc.html#SEC54">Character Handling</A></H1>
<P>
Programs that work with characters and strings often need to classify a
character--is it alphabetic, is it a digit, is it whitespace, and so
on--and perform case conversion operations on characters.  The
functions in the header file <TT>`ctype.h'</TT> are provided for this
purpose.
<A NAME="IDX225"></A>
<P>
Since the choice of locale and character set can alter the
classifications of particular character codes, all of these functions
are affected by the current locale.  (More precisely, they are affected
by the locale currently selected for character classification--the
<CODE>LC_CTYPE</CODE> category; see section <A HREF="library.html#SEC79">Categories of Activities that Locales Affect</A>.)
<P>
<A NAME="IDX226"></A>
<A NAME="IDX227"></A>
<A NAME="IDX228"></A>
<A NAME="IDX229"></A>
<H2><A NAME="SEC55" HREF="library_toc.html#SEC55">Classification of Characters</A></H2>
<P>
This section explains the library functions for classifying characters.
For example, <CODE>isalpha</CODE> is the function to test for an alphabetic
character.  It takes one argument, the character to test, and returns a
nonzero integer if the character is alphabetic, and zero otherwise.  You
would use it like this:
<P>
<PRE>
if (isalpha (c))
  printf ("The character `%c' is alphabetic.\n", c);
</PRE>
<P>
Each of the functions in this section tests for membership in a
particular class of characters; each has a name starting with <SAMP>`is'</SAMP>.
Each of them takes one argument, which is a character to test, and
returns an <CODE>int</CODE> which is treated as a boolean value.  The
character argument is passed as an <CODE>int</CODE>, and it may be the
constant value <CODE>EOF</CODE> instead of a real character.  
<P>
The attributes of any given character can vary between locales.
See section <A HREF="library.html#SEC76">Locales and Internationalization</A>, for more information on locales.<P>
These functions are declared in the header file <TT>`ctype.h'</TT>.
<A NAME="IDX230"></A>
<A NAME="IDX231"></A>
<P>
<A NAME="IDX232"></A>
<U>Function:</U> int <B>islower</B> <I>(int <VAR>c</VAR>)</I><P>
Returns true if <VAR>c</VAR> is a lower-case letter.
<P>
<A NAME="IDX233"></A>
<P>
<A NAME="IDX234"></A>
<U>Function:</U> int <B>isupper</B> <I>(int <VAR>c</VAR>)</I><P>
Returns true if <VAR>c</VAR> is an upper-case letter.
<P>
<A NAME="IDX235"></A>
<P>
<A NAME="IDX236"></A>
<U>Function:</U> int <B>isalpha</B> <I>(int <VAR>c</VAR>)</I><P>
Returns true if <VAR>c</VAR> is an alphabetic character (a letter).  If
<CODE>islower</CODE> or <CODE>isupper</CODE> is true of a character, then
<CODE>isalpha</CODE> is also true.
<P>
In some locales, there may be additional characters for which
<CODE>isalpha</CODE> is true--letters which are neither upper case nor lower
case.  But in the standard <CODE>"C"</CODE> locale, there are no such
additional characters.
<P>
<A NAME="IDX237"></A>
<A NAME="IDX238"></A>
<P>
<A NAME="IDX239"></A>
<U>Function:</U> int <B>isdigit</B> <I>(int <VAR>c</VAR>)</I><P>
Returns true if <VAR>c</VAR> is a decimal digit (<SAMP>`0'</SAMP> through <SAMP>`9'</SAMP>).
<P>
<A NAME="IDX240"></A>
<P>
<A NAME="IDX241"></A>
<U>Function:</U> int <B>isalnum</B> <I>(int <VAR>c</VAR>)</I><P>
Returns true if <VAR>c</VAR> is an alphanumeric character (a letter or
number); in other words, if either <CODE>isalpha</CODE> or <CODE>isdigit</CODE> is
true of a character, then <CODE>isalnum</CODE> is also true.
<P>
<A NAME="IDX242"></A>
<P>
<A NAME="IDX243"></A>
<U>Function:</U> int <B>isxdigit</B> <I>(int <VAR>c</VAR>)</I><P>
Returns true if <VAR>c</VAR> is a hexadecimal digit.
Hexadecimal digits include the normal decimal digits <SAMP>`0'</SAMP> through
<SAMP>`9'</SAMP> and the letters <SAMP>`A'</SAMP> through <SAMP>`F'</SAMP> and
<SAMP>`a'</SAMP> through <SAMP>`f'</SAMP>.
<P>
<A NAME="IDX244"></A>
<P>
<A NAME="IDX245"></A>
<U>Function:</U> int <B>ispunct</B> <I>(int <VAR>c</VAR>)</I><P>
Returns true if <VAR>c</VAR> is a punctuation character.
This means any printing character that is not alphanumeric or a space
character.
<P>
<A NAME="IDX246"></A>
<P>
<A NAME="IDX247"></A>
<U>Function:</U> int <B>isspace</B> <I>(int <VAR>c</VAR>)</I><P>
Returns true if <VAR>c</VAR> is a <DFN>whitespace</DFN> character.  In the standard
<CODE>"C"</CODE> locale, <CODE>isspace</CODE> returns true for only the standard
whitespace characters:
<P>
<DL COMPACT>
<DT><CODE>' '</CODE>
<DD>space
<P>
<DT><CODE>'\f'</CODE>
<DD>formfeed
<P>
<DT><CODE>'\n'</CODE>
<DD>newline
<P>
<DT><CODE>'\r'</CODE>
<DD>carriage return
<P>
<DT><CODE>'\t'</CODE>
<DD>horizontal tab
<P>
<DT><CODE>'\v'</CODE>
<DD>vertical tab
</DL>
<P>
<A NAME="IDX248"></A>
<P>
<A NAME="IDX249"></A>
<U>Function:</U> int <B>isblank</B> <I>(int <VAR>c</VAR>)</I><P>
Returns true if <VAR>c</VAR> is a blank character; that is, a space or a tab.
This function is a GNU extension.
<P>
<A NAME="IDX250"></A>
<P>
<A NAME="IDX251"></A>
<U>Function:</U> int <B>isgraph</B> <I>(int <VAR>c</VAR>)</I><P>
Returns true if <VAR>c</VAR> is a graphic character; that is, a character
that has a glyph associated with it.  The whitespace characters are not
considered graphic.
<P>
<A NAME="IDX252"></A>
<P>
<A NAME="IDX253"></A>
<U>Function:</U> int <B>isprint</B> <I>(int <VAR>c</VAR>)</I><P>
Returns true if <VAR>c</VAR> is a printing character.  Printing characters
include all the graphic characters, plus the space (<SAMP>` '</SAMP>) character.
<P>
<A NAME="IDX254"></A>
<P>
<A NAME="IDX255"></A>
<U>Function:</U> int <B>iscntrl</B> <I>(int <VAR>c</VAR>)</I><P>
Returns true if <VAR>c</VAR> is a control character (that is, a character that
is not a printing character).
<P>
<A NAME="IDX256"></A>
<P>
<A NAME="IDX257"></A>
<U>Function:</U> int <B>isascii</B> <I>(int <VAR>c</VAR>)</I><P>
Returns true if <VAR>c</VAR> is a 7-bit <CODE>unsigned char</CODE> value that fits
into the US/UK ASCII character set.  This function is a BSD extension
and is also an SVID extension.
<P>
<A NAME="IDX258"></A>
<A NAME="IDX259"></A>
<A NAME="IDX260"></A>
<H2><A NAME="SEC56" HREF="library_toc.html#SEC56">Case Conversion</A></H2>
<P>
This section explains the library functions for performing conversions
such as case mappings on characters.  For example, <CODE>toupper</CODE>
converts any character to upper case if possible.  If the character
can't be converted, <CODE>toupper</CODE> returns it unchanged.
<P>
These functions take one argument of type <CODE>int</CODE>, which is the
character to convert, and return the converted character as an
<CODE>int</CODE>.  If the conversion is not applicable to the argument given,
the argument is returned unchanged.
<P>
<STRONG>Compatibility Note:</STRONG> In pre-ANSI C dialects, instead of
returning the argument unchanged, these functions may fail when the
argument is not suitable for the conversion.  Thus for portability, you
may need to write <CODE>islower(c) ? toupper(c) : c</CODE> rather than just
<CODE>toupper(c)</CODE>.
<P>
These functions are declared in the header file <TT>`ctype.h'</TT>.
<A NAME="IDX261"></A>
<P>
<A NAME="IDX262"></A>
<U>Function:</U> int <B>tolower</B> <I>(int <VAR>c</VAR>)</I><P>
If <VAR>c</VAR> is an upper-case letter, <CODE>tolower</CODE> returns the corresponding
lower-case letter.  If <VAR>c</VAR> is not an upper-case letter,
<VAR>c</VAR> is returned unchanged.
<P>
<A NAME="IDX263"></A>
<U>Function:</U> int <B>toupper</B> <I>(int <VAR>c</VAR>)</I><P>
If <VAR>c</VAR> is a lower-case letter, <CODE>tolower</CODE> returns the corresponding
upper-case letter.  Otherwise <VAR>c</VAR> is returned unchanged.
<P>
<A NAME="IDX264"></A>
<U>Function:</U> int <B>toascii</B> <I>(int <VAR>c</VAR>)</I><P>
This function converts <VAR>c</VAR> to a 7-bit <CODE>unsigned char</CODE> value
that fits into the US/UK ASCII character set, by clearing the high-order
bits.  This function is a BSD extension and is also an SVID extension.
<P>
<A NAME="IDX265"></A>
<U>Function:</U> int <B>_tolower</B> <I>(int <VAR>c</VAR>)</I><P>
This is identical to <CODE>tolower</CODE>, and is provided for compatibility
with the SVID.  See section <A HREF="library.html#SEC7">SVID (The System V Interface Description)</A>.<P>
<A NAME="IDX266"></A>
<U>Function:</U> int <B>_toupper</B> <I>(int <VAR>c</VAR>)</I><P>
This is identical to <CODE>toupper</CODE>, and is provided for compatibility
with the SVID.
<P>
<H1><A NAME="SEC57" HREF="library_toc.html#SEC57">String and Array Utilities</A></H1>
<P>
Operations on strings (or arrays of characters) are an important part of
many programs.  The GNU C library provides an extensive set of string
utility functions, including functions for copying, concatenating,
comparing, and searching strings.  Many of these functions can also
operate on arbitrary regions of storage; for example, the <CODE>memcpy</CODE>
function can be used to copy the contents of any kind of array.  
<P>
It's fairly common for beginning C programmers to "reinvent the wheel"
by duplicating this functionality in their own code, but it pays to
become familiar with the library functions and to make use of them,
since this offers benefits in maintenance, efficiency, and portability.
<P>
For instance, you could easily compare one string to another in two
lines of C code, but if you use the built-in <CODE>strcmp</CODE> function,
you're less likely to make a mistake.  And, since these library
functions are typically highly optimized, your program may run faster
too.
<P>
<A NAME="IDX267"></A>
<H2><A NAME="SEC58" HREF="library_toc.html#SEC58">Representation of Strings</A></H2>
<P>
This section is a quick summary of string concepts for beginning C
programmers.  It describes how character strings are represented in C
and some common pitfalls.  If you are already familiar with this
material, you can skip this section.
<A NAME="IDX268"></A>
<A NAME="IDX269"></A>
<P>
A <DFN>string</DFN> is an array of <CODE>char</CODE> objects.  But string-valued
variables are usually declared to be pointers of type <CODE>char *</CODE>.
Such variables do not include space for the text of a string; that has
to be stored somewhere else--in an array variable, a string constant,
or dynamically allocated memory (see section <A HREF="library.html#SEC18">Memory Allocation</A>).  It's up to
you to store the address of the chosen memory space into the pointer
variable.  Alternatively you can store a <DFN>null pointer</DFN> in the
pointer variable.  The null pointer does not point anywhere, so
attempting to reference the string it points to gets an error.
<P>
By convention, a <DFN>null character</DFN>, <CODE>'\0'</CODE>, marks the end of a
string.  For example, in testing to see whether the <CODE>char *</CODE>
variable <VAR>p</VAR> points to a null character marking the end of a string,
you can write <CODE>!*<VAR>p</VAR></CODE> or <CODE>*<VAR>p</VAR> == '\0'</CODE>.
<P>
A null character is quite different conceptually from a null pointer,
although both are represented by the integer <CODE>0</CODE>.
<A NAME="IDX270"></A>
<P>
<DFN>String literals</DFN> appear in C program source as strings of
characters between double-quote characters (<SAMP>`"'</SAMP>).  In ANSI C,
string literals can also be formed by <DFN>string concatenation</DFN>:
<CODE>"a" "b"</CODE> is the same as <CODE>"ab"</CODE>.  Modification of string
literals is not allowed by the GNU C compiler, because literals
are placed in read-only storage.
<P>
Character arrays that are declared <CODE>const</CODE> cannot be modified
either.  It's generally good style to declare non-modifiable string
pointers to be of type <CODE>const char *</CODE>, since this often allows the
C compiler to detect accidental modifications as well as providing some
amount of documentation about what your program intends to do with the
string.
<P>
The amount of memory allocated for the character array may extend past
the null character that normally marks the end of the string.  In this
document, the term <DFN>allocation size</DFN> is always used to refer to the
total amount of memory allocated for the string, while the term
<DFN>length</DFN> refers to the number of characters up to (but not
including) the terminating null character.
<A NAME="IDX272"></A>
<A NAME="IDX273"></A>
<A NAME="IDX274"></A>
<A NAME="IDX275"></A>
<A NAME="IDX271"></A>
<P>
A notorious source of program bugs is trying to put more characters in a
string than fit in its allocated size.  When writing code that extends
strings or moves characters into a pre-allocated array, you should be
very careful to keep track of the length of the text and make explicit
checks for overflowing the array.  Many of the library functions
<EM>do not</EM> do this for you!  Remember also that you need to allocate
an extra byte to hold the null character that marks the end of the
string.
<P>
<H2><A NAME="SEC59" HREF="library_toc.html#SEC59">String/Array Conventions</A></H2>
<P>
This chapter describes both functions that work on arbitrary arrays or
blocks of memory, and functions that are specific to null-terminated
arrays of characters.
<P>
Functions that operate on arbitrary blocks of memory have names
beginning with <SAMP>`mem'</SAMP> (such as <CODE>memcpy</CODE>) and invariably take an
argument which specifies the size (in bytes) of the block of memory to
operate on.  The array arguments and return values for these functions
have type <CODE>void *</CODE>, and as a matter of style, the elements of these
arrays are referred to as "bytes".  You can pass any kind of pointer
to these functions, and the <CODE>sizeof</CODE> operator is useful in
computing the value for the size argument.
<P>
In contrast, functions that operate specifically on strings have names
beginning with <SAMP>`str'</SAMP> (such as <CODE>strcpy</CODE>) and look for a null
character to terminate the string instead of requiring an explicit size
argument to be passed.  (Some of these functions accept a specified
maximum length, but they also check for premature termination with a
null character.)  The array arguments and return values for these
functions have type <CODE>char *</CODE>, and the array elements are referred
to as "characters".
<P>
In many cases, there are both <SAMP>`mem'</SAMP> and <SAMP>`str'</SAMP> versions of a
function.  The one that is more appropriate to use depends on the exact
situation.  When your program is manipulating arbitrary arrays or blocks of
storage, then you should always use the <SAMP>`mem'</SAMP> functions.  On the
other hand, when you are manipulating null-terminated strings it is
usually more convenient to use the <SAMP>`str'</SAMP> functions, unless you
already know the length of the string in advance.
<P>
<H2><A NAME="SEC60" HREF="library_toc.html#SEC60">String Length</A></H2>
<P>
You can get the length of a string using the <CODE>strlen</CODE> function.
This function is declared in the header file <TT>`string.h'</TT>.
<A NAME="IDX276"></A>
<P>
<A NAME="IDX277"></A>
<U>Function:</U> size_t <B>strlen</B> <I>(const char *<VAR>s</VAR>)</I><P>
The <CODE>strlen</CODE> function returns the length of the null-terminated
string <VAR>s</VAR>.  (In other words, it returns the offset of the terminating
null character within the array.)
<P>
For example,
<PRE>
strlen ("hello, world")
    => 12
</PRE>
<P>
When applied to a character array, the <CODE>strlen</CODE> function returns
the length of the string stored there, not its allocation size.  You can
get the allocation size of the character array that holds a string using
the <CODE>sizeof</CODE> operator:
<P>
<PRE>
char string[32] = "hello, world"; 
sizeof (string)
    => 32
strlen (string)
    => 12
</PRE>
<P>
<H2><A NAME="SEC61" HREF="library_toc.html#SEC61">Copying and Concatenation</A></H2>
<P>
You can use the functions described in this section to copy the contents
of strings and arrays, or to append the contents of one string to
another.  These functions are declared in the header file
<TT>`string.h'</TT>.
<A NAME="IDX279"></A>
<A NAME="IDX280"></A>
<A NAME="IDX281"></A>
<A NAME="IDX282"></A>
<A NAME="IDX283"></A>
<A NAME="IDX278"></A>
<P>
A helpful way to remember the ordering of the arguments to the functions
in this section is that it corresponds to an assignment expression, with
the destination array specified to the left of the source array.  All
of these functions return the address of the destination array.
<P>
Most of these functions do not work properly if the source and
destination arrays overlap.  For example, if the beginning of the
destination array overlaps the end of the source array, the original
contents of that part of the source array may get overwritten before it
is copied.  Even worse, in the case of the string functions, the null
character marking the end of the string may be lost, and the copy
function might get stuck in a loop trashing all the memory allocated to
your program.
<P>
All functions that have problems copying between overlapping arrays are
explicitly identified in this manual.  In addition to functions in this
section, there are a few others like <CODE>sprintf</CODE> (see section <A HREF="library.html#SEC135">Formatted Output Functions</A>) and <CODE>scanf</CODE> (see section <A HREF="library.html#SEC153">Formatted Input Functions</A>).
<P>
<A NAME="IDX284"></A>
<U>Function:</U> void * <B>memcpy</B> <I>(void *<VAR>to</VAR>, const void *<VAR>from</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>memcpy</CODE> function copies <VAR>size</VAR> bytes from the object
beginning at <VAR>from</VAR> into the object beginning at <VAR>to</VAR>.  The
behavior of this function is undefined if the two arrays <VAR>to</VAR> and
<VAR>from</VAR> overlap; use <CODE>memmove</CODE> instead if overlapping is possible.
<P>
The value returned by <CODE>memcpy</CODE> is the value of <VAR>to</VAR>.
<P>
Here is an example of how you might use <CODE>memcpy</CODE> to copy the
contents of a <CODE>struct</CODE>:
<P>
<PRE>
struct foo *old, *new;
...
memcpy (new, old, sizeof(struct foo));
</PRE>
<P>
<A NAME="IDX285"></A>
<U>Function:</U> void * <B>memmove</B> <I>(void *<VAR>to</VAR>, const void *<VAR>from</VAR>, size_t <VAR>size</VAR>)</I><P>
<CODE>memmove</CODE> copies the <VAR>size</VAR> bytes at <VAR>from</VAR> into the
<VAR>size</VAR> bytes at <VAR>to</VAR>, even if those two blocks of space
overlap.  In the case of overlap, <CODE>memmove</CODE> is careful to copy the
original values of the bytes in the block at <VAR>from</VAR>, including those
bytes which also belong to the block at <VAR>to</VAR>.
<P>
<A NAME="IDX286"></A>
<U>Function:</U> void * <B>memccpy</B> <I>(void *<VAR>to</VAR>, const void *<VAR>from</VAR>, int <VAR>c</VAR>, size_t <VAR>size</VAR>)</I><P>
This function copies no more than <VAR>size</VAR> bytes from <VAR>from</VAR> to
<VAR>to</VAR>, stopping if a byte matching <VAR>c</VAR> is found.  The return
value is a pointer into <VAR>to</VAR> one byte past where <VAR>c</VAR> was copied,
or a null pointer if no byte matching <VAR>c</VAR> appeared in the first
<VAR>size</VAR> bytes of <VAR>from</VAR>.
<P>
<A NAME="IDX287"></A>
<U>Function:</U> void * <B>memset</B> <I>(void *<VAR>block</VAR>, int <VAR>c</VAR>, size_t <VAR>size</VAR>)</I><P>
This function copies the value of <VAR>c</VAR> (converted to an
<CODE>unsigned char</CODE>) into each of the first <VAR>size</VAR> bytes of the
object beginning at <VAR>block</VAR>.  It returns the value of <VAR>block</VAR>.
<P>
<A NAME="IDX288"></A>
<U>Function:</U> char * <B>strcpy</B> <I>(char *<VAR>to</VAR>, const char *<VAR>from</VAR>)</I><P>
This copies characters from the string <VAR>from</VAR> (up to and including
the terminating null character) into the string <VAR>to</VAR>.  Like
<CODE>memcpy</CODE>, this function has undefined results if the strings
overlap.  The return value is the value of <VAR>to</VAR>.
<P>
<A NAME="IDX289"></A>
<U>Function:</U> char * <B>strncpy</B> <I>(char *<VAR>to</VAR>, const char *<VAR>from</VAR>, size_t <VAR>size</VAR>)</I><P>
This function is similar to <CODE>strcpy</CODE> but always copies exactly
<VAR>size</VAR> characters into <VAR>to</VAR>.
<P>
If the length of <VAR>from</VAR> is more than <VAR>size</VAR>, then <CODE>strncpy</CODE>
copies just the first <VAR>size</VAR> characters.
<P>
If the length of <VAR>from</VAR> is less than <VAR>size</VAR>, then <CODE>strncpy</CODE>
copies all of <VAR>from</VAR>, followed by enough null characters to add up
to <VAR>size</VAR> characters in all.  This behavior is rarely useful, but it
is specified by the ANSI C standard.
<P>
The behavior of <CODE>strncpy</CODE> is undefined if the strings overlap.
<P>
Using <CODE>strncpy</CODE> as opposed to <CODE>strcpy</CODE> is a way to avoid bugs
relating to writing past the end of the allocated space for <VAR>to</VAR>.
However, it can also make your program much slower in one common case:
copying a string which is probably small into a potentially large buffer.
In this case, <VAR>size</VAR> may be large, and when it is, <CODE>strncpy</CODE> will
waste a considerable amount of time copying null characters.
<P>
<A NAME="IDX290"></A>
<U>Function:</U> char * <B>strdup</B> <I>(const char *<VAR>s</VAR>)</I><P>
This function copies the null-terminated string <VAR>s</VAR> into a newly
allocated string.  The string is allocated using <CODE>malloc</CODE>; see
section <A HREF="library.html#SEC21">Unconstrained Allocation</A>.  If <CODE>malloc</CODE> cannot allocate space
for the new string, <CODE>strdup</CODE> returns a null pointer.  Otherwise it
returns a pointer to the new string.
<P>
<A NAME="IDX291"></A>
<U>Function:</U> char * <B>stpcpy</B> <I>(char *<VAR>to</VAR>, const char *<VAR>from</VAR>)</I><P>
This function is like <CODE>strcpy</CODE>, except that it returns a pointer to
the end of the string <VAR>to</VAR> (that is, the address of the terminating
null character) rather than the beginning.
<P>
For example, this program uses <CODE>stpcpy</CODE> to concatenate <SAMP>`foo'</SAMP>
and <SAMP>`bar'</SAMP> to produce <SAMP>`foobar'</SAMP>, which it then prints.
<P>
<PRE>
#include &#60;string.h&#62;

int
main (void)
{
  char *to = buffer;
  to = stpcpy (to, "foo");
  to = stpcpy (to, "bar");
  printf ("%s\n", buffer);
}
</PRE>
<P>
This function is not part of the ANSI or POSIX standards, and is not
customary on Unix systems, but we did not invent it either.  Perhaps it
comes from MS-DOG.
<P>
Its behavior is undefined if the strings overlap.
<P>
<A NAME="IDX292"></A>
<U>Function:</U> char * <B>strcat</B> <I>(char *<VAR>to</VAR>, const char *<VAR>from</VAR>)</I><P>
The <CODE>strcat</CODE> function is similar to <CODE>strcpy</CODE>, except that the
characters from <VAR>from</VAR> are concatenated or appended to the end of
<VAR>to</VAR>, instead of overwriting it.  That is, the first character from
<VAR>from</VAR> overwrites the null character marking the end of <VAR>to</VAR>.
<P>
An equivalent definition for <CODE>strcat</CODE> would be:
<P>
<PRE>
char *
strcat (char *to, const char *from)
{
  strcpy (to + strlen (to), from);
  return to;
}
</PRE>
<P>
This function has undefined results if the strings overlap.
<P>
<A NAME="IDX293"></A>
<U>Function:</U> char * <B>strncat</B> <I>(char *<VAR>to</VAR>, const char *<VAR>from</VAR>, size_t <VAR>size</VAR>)</I><P>
This function is like <CODE>strcat</CODE> except that not more than <VAR>size</VAR>
characters from <VAR>from</VAR> are appended to the end of <VAR>to</VAR>.  A
single null character is also always appended to <VAR>to</VAR>, so the total
allocated size of <VAR>to</VAR> must be at least <CODE><VAR>size</VAR> + 1</CODE> bytes
longer than its initial length.
<P>
<PRE>
char *
strncat (char *to, const char *from, size_t size)
{
  strncpy (to + strlen (to), from, size);
  return to;
}
</PRE>
<P>
The behavior of <CODE>strncat</CODE> is undefined if the strings overlap.
<P>
Here is an example showing the use of <CODE>strncpy</CODE> and <CODE>strncat</CODE>.
Notice how, in the call to <CODE>strncat</CODE>, the <VAR>size</VAR> parameter
is computed to avoid overflowing the character array <CODE>buffer</CODE>.
<P>
<PRE>
#include &#60;string.h&#62;
#include &#60;stdio.h&#62;

#define SIZE 10

static char buffer[SIZE];

main ()
{
  strncpy (buffer, "hello", SIZE);
  printf ("%s\n", buffer);
  strncat (buffer, ", world", SIZE - strlen (buffer) - 1);
  printf ("%s\n", buffer);
}
</PRE>
<P>
The output produced by this program looks like:
<P>
<PRE>
hello
hello, wo
</PRE>
<P>
<A NAME="IDX294"></A>
<U>Function:</U> void * <B>bcopy</B> <I>(void *<VAR>from</VAR>, const void *<VAR>to</VAR>, size_t <VAR>size</VAR>)</I><P>
This is a partially obsolete alternative for <CODE>memmove</CODE>, derived from
BSD.  Note that it is not quite equivalent to <CODE>memmove</CODE>, because the
arguments are not in the same order.
<P>
<A NAME="IDX295"></A>
<U>Function:</U> void * <B>bzero</B> <I>(void *<VAR>block</VAR>, size_t <VAR>size</VAR>)</I><P>
This is a partially obsolete alternative for <CODE>memset</CODE>, derived from
BSD.  Note that it is not as general as <CODE>memset</CODE>, because the only
value it can store is zero.
<P>
<A NAME="IDX296"></A>
<A NAME="IDX297"></A>
<A NAME="IDX298"></A>
<A NAME="IDX299"></A>
<A NAME="IDX300"></A>
<H2><A NAME="SEC62" HREF="library_toc.html#SEC62">String/Array Comparison</A></H2>
<P>
You can use the functions in this section to perform comparisons on the
contents of strings and arrays.  As well as checking for equality, these
functions can also be used as the ordering functions for sorting
operations.  See section <A HREF="library.html#SEC86">Searching and Sorting</A>, for an example of this.
<P>
Unlike most comparison operations in C, the string comparison functions
return a nonzero value if the strings are <EM>not</EM> equivalent rather
than if they are.  The sign of the value indicates the relative ordering
of the first characters in the strings that are not equivalent:  a
negative value indicates that the first string is "less" than the
second, while a positive value indicates that the first string is 
"greater".
<P>
If you are using these functions only to check for equality, you might
find it makes for a cleaner program to hide them behind a macro
definition, like this:
<P>
<PRE>
#define str_eq(s1,s2)  (!strcmp ((s1),(s2)))
</PRE>
<P>
All of these functions are declared in the header file <TT>`string.h'</TT>.
<A NAME="IDX301"></A>
<P>
<A NAME="IDX302"></A>
<U>Function:</U> int <B>memcmp</B> <I>(const void *<VAR>a1</VAR>, const void *<VAR>a2</VAR>, size_t <VAR>size</VAR>)</I><P>
The function <CODE>memcmp</CODE> compares the <VAR>size</VAR> bytes of memory
beginning at <VAR>a1</VAR> against the <VAR>size</VAR> bytes of memory beginning
at <VAR>a2</VAR>.  The value returned has the same sign as the difference
between the first differing pair of bytes (interpreted as <CODE>unsigned
char</CODE> objects, then promoted to <CODE>int</CODE>).
<P>
If the contents of the two blocks are equal, <CODE>memcmp</CODE> returns
<CODE>0</CODE>.
<P>
On arbitrary arrays, the <CODE>memcmp</CODE> function is mostly useful for
testing equality.  It usually isn't meaningful to do byte-wise ordering
comparisons on arrays of things other than bytes.  For example, a
byte-wise comparison on the bytes that make up floating-point numbers
isn't likely to tell you anything about the relationship between the
values of the floating-point numbers.
<P>
You should also be careful about using <CODE>memcmp</CODE> to compare objects
that can contain "holes", such as the padding inserted into structure
objects to enforce alignment requirements, extra space at the end of
unions, and extra characters at the ends of strings whose length is less
than their allocated size.  The contents of these "holes" are
indeterminate and may cause strange behavior when performing byte-wise
comparisons.  For more predictable results, perform an explicit
component-wise comparison.
<P>
For example, given a structure type definition like:
<P>
<PRE>
struct foo
  {
    unsigned char tag;
    union
      {
        double f;
        long i;
        char *p;
      } value;
  };
</PRE>
<P>
you are better off writing a specialized comparison function to compare
<CODE>struct foo</CODE> objects instead of comparing them with <CODE>memcmp</CODE>.
<P>
<A NAME="IDX303"></A>
<U>Function:</U> int <B>strcmp</B> <I>(const char *<VAR>s1</VAR>, const char *<VAR>s2</VAR>)</I><P>
The <CODE>strcmp</CODE> function compares the string <VAR>s1</VAR> against
<VAR>s2</VAR>, returning a value that has the same sign as the difference
between the first differing pair of characters (interpreted as
<CODE>unsigned char</CODE> objects, then promoted to <CODE>int</CODE>).
<P>
If the two strings are equal, <CODE>strcmp</CODE> returns <CODE>0</CODE>.
<P>
A consequence of the ordering used by <CODE>strcmp</CODE> is that if <VAR>s1</VAR>
is an initial substring of <VAR>s2</VAR>, then <VAR>s1</VAR> is considered to be
"less than" <VAR>s2</VAR>.
<P>
<A NAME="IDX304"></A>
<U>Function:</U> int <B>strcasecmp</B> <I>(const char *<VAR>s1</VAR>, const char *<VAR>s2</VAR>)</I><P>
This function is like <CODE>strcmp</CODE>, except that differences in case
are ignored.
<P>
<CODE>strcasecmp</CODE> is derived from BSD.
<P>
<A NAME="IDX305"></A>
<U>Function:</U> int <B>strncasecmp</B> <I>(const char *<VAR>s1</VAR>, const char *<VAR>s2</VAR>, size_t <VAR>n</VAR>)</I><P>
This function is like <CODE>strncmp</CODE>, except that differences in case
are ignored.
<P>
<CODE>strncasecmp</CODE> is a GNU extension.
<P>
<A NAME="IDX306"></A>
<U>Function:</U> int <B>strncmp</B> <I>(const char *<VAR>s1</VAR>, const char *<VAR>s2</VAR>, size_t <VAR>size</VAR>)</I><P>
This function is the similar to <CODE>strcmp</CODE>, except that no more than
<VAR>size</VAR> characters are compared.  In other words, if the two strings are
the same in their first <VAR>size</VAR> characters, the return value is zero.
<P>
Here are some examples showing the use of <CODE>strcmp</CODE> and <CODE>strncmp</CODE>.
These examples assume the use of the ASCII character set.  (If some
other character set--say, EBCDIC--is used instead, then the glyphs
are associated with different numeric codes, and the return values
and ordering may differ.)
<P>
<PRE>
strcmp ("hello", "hello")
    => 0    /* These two strings are the same. */
strcmp ("hello", "Hello")
    => 32   /* Comparisons are case-sensitive. */
strcmp ("hello", "world")
    => -15  /* The character <CODE>'h'</CODE> comes before <CODE>'w'</CODE>. */
strcmp ("hello", "hello, world")
    => -44  /* Comparing a null character against a comma. */
strncmp ("hello", "hello, world"", 5)
    => 0    /* The initial 5 characters are the same. */
strncmp ("hello, world", "hello, stupid world!!!", 5)
    => 0    /* The initial 5 characters are the same. */
</PRE>
<P>
<A NAME="IDX307"></A>
<U>Function:</U> int <B>bcmp</B> <I>(const void *<VAR>a1</VAR>, const void *<VAR>a2</VAR>, size_t <VAR>size</VAR>)</I><P>
This is an obsolete alias for <CODE>memcmp</CODE>, derived from BSD.
<P>
<H2><A NAME="SEC63" HREF="library_toc.html#SEC63">Collation Functions</A></H2>
<A NAME="IDX308"></A>
<A NAME="IDX309"></A>
<P>
In some locales, the conventions for lexicographic ordering differ from
the strict numeric ordering of character codes.  For example, in Spanish
most glyphs with diacritical marks such as accents are not considered
distinct letters for the purposes of collation.  On the other hand, the
two-character sequence <SAMP>`ll'</SAMP> is treated as a single letter that is
collated immediately after <SAMP>`l'</SAMP>.
<P>
You can use the functions <CODE>strcoll</CODE> and <CODE>strxfrm</CODE> (declared in
the header file <TT>`string.h'</TT>) to compare strings using a collation
ordering appropriate for the current locale.  The locale used by these
functions in particular can be specified by setting the locale for the
<CODE>LC_COLLATE</CODE> category; see section <A HREF="library.html#SEC76">Locales and Internationalization</A>.
<A NAME="IDX310"></A>
<P>
In the standard C locale, the collation sequence for <CODE>strcoll</CODE> is
the same as that for <CODE>strcmp</CODE>.
<P>
Effectively, the way these functions work is by applying a mapping to
transform the characters in a string to a byte sequence that represents
the string's position in the collating sequence of the current locale.
Comparing two such byte sequences in a simple fashion is equivalent to
comparing the strings with the locale's collating sequence.
<P>
The function <CODE>strcoll</CODE> performs this translation implicitly, in
order to do one comparison.  By contrast, <CODE>strxfrm</CODE> performs the
mapping explicitly.  If you are making multiple comparisons using the
same string or set of strings, it is likely to be more efficient to use
<CODE>strxfrm</CODE> to transform all the strings just once, and subsequently
compare the transformed strings with <CODE>strcmp</CODE>.
<P>
<A NAME="IDX311"></A>
<U>Function:</U> int <B>strcoll</B> <I>(const char *<VAR>s1</VAR>, const char *<VAR>s2</VAR>)</I><P>
The <CODE>strcoll</CODE> function is similar to <CODE>strcmp</CODE> but uses the
collating sequence of the current locale for collation (the
<CODE>LC_COLLATE</CODE> locale).
<P>
Here is an example of sorting an array of strings, using <CODE>strcoll</CODE>
to compare them.  The actual sort algorithm is not written here; it
comes from <CODE>qsort</CODE> (see section <A HREF="library.html#SEC89">Array Sort Function</A>).  The job of the
code shown here is to say how to compare the strings while sorting them.
(Later on in this section, we will show a way to do this more
efficiently using <CODE>strxfrm</CODE>.)
<P>
<PRE>
/* This is the comparison function used with <CODE>qsort</CODE>. */

int
compare_elements (char **p1, char **p2)
{
  return strcoll (*p1, *p2);
}

/* This is the entry point--the function to sort
   strings using the locale's collating sequence. */

void
sort_strings (char **array, int nstrings)
{
  /* Sort <CODE>temp_array</CODE> by comparing the strings. */
  qsort (array, sizeof (char *),
         nstrings, compare_elements);
}
</PRE>
<A NAME="IDX312"></A>
<P>
<A NAME="IDX313"></A>
<U>Function:</U> size_t <B>strxfrm</B> <I>(char *<VAR>to</VAR>, const char *<VAR>from</VAR>, size_t <VAR>size</VAR>)</I><P>
The function <CODE>strxfrm</CODE> transforms <VAR>string</VAR> using the collation
transformation determined by the locale currently selected for
collation, and stores the transformed string in the array <VAR>to</VAR>.  Up
to <VAR>size</VAR> characters (including a terminating null character) are
stored.
<P>
The behavior is undefined if the strings <VAR>to</VAR> and <VAR>from</VAR>
overlap; see section <A HREF="library.html#SEC61">Copying and Concatenation</A>.
<P>
The return value is the length of the entire transformed string.  This
value is not affected by the value of <VAR>size</VAR>, but if it is greater
than <VAR>size</VAR>, it means that the transformed string did not entirely
fit in the array <VAR>to</VAR>.  In this case, only as much of the string as
actually fits was stored.  To get the whole transformed string, call
<CODE>strxfrm</CODE> again with a bigger output array.
<P>
The transformed string may be longer than the original string, and it
may also be shorter.
<P>
If <VAR>size</VAR> is zero, no characters are stored in <VAR>to</VAR>.  In this
case, <CODE>strxfrm</CODE> simply returns the number of characters that would
be the length of the transformed string.  This is useful for determining
what size string to allocate.  It does not matter what <VAR>to</VAR> is if
<VAR>size</VAR> is zero; <VAR>to</VAR> may even be a null pointer.
<P>
Here is an example of how you can use <CODE>strxfrm</CODE> when
you plan to do many comparisons.  It does the same thing as the previous
example, but much faster, because it has to transform each string only
once, no matter how many times it is compared with other strings.  Even
the time needed to allocate and free storage is much less than the time
we save, when there are many strings.
<P>
<PRE>
struct sorter { char *input; char *transformed; };

/* This is the comparison function used with <CODE>qsort</CODE>
   to sort an array of <CODE>struct sorter</CODE>. */

int
compare_elements (struct sorter *p1, struct sorter *p2)
{
  return strcmp (p1-&#62;transformed, p2-&#62;transformed);
}

/* This is the entry point--the function to sort
   strings using the locale's collating sequence. */

void
sort_strings_fast (char **array, int nstrings)
{
  struct sorter temp_array[nstrings];
  int i;

  /* Set up <CODE>temp_array</CODE>.  Each element contains
     one input string and its transformed string. */
  for (i = 0; i &#60; nstrings; i++)
    {
      size_t length = strlen (array[i]) * 2;

      temp_array[i].input = array[i];

      /* Transform <CODE>array[i]</CODE>.
         First try a buffer probably big enough. */
      while (1)
        {
          char *transformed = (char *) xmalloc (length);
          if (strxfrm (transformed, array[i], length) &#60; length)
            {
              temp_array[i].transformed = transformed;
              break;
            }
          /* Try again with a bigger buffer. */
          free (transformed);
          length *= 2;
        }
    }

  /* Sort <CODE>temp_array</CODE> by comparing transformed strings. */
  qsort (temp_array, sizeof (struct sorter),
         nstrings, compare_elements);

  /* Put the elements back in the permanent array
     in their sorted order. */
  for (i = 0; i &#60; nstrings; i++)
    array[i] = temp_array[i].input;

  /* Free the strings we allocated. */
  for (i = 0; i &#60; nstrings; i++)
    free (temp_array[i].transformed);
}
</PRE>
<P>
<STRONG>Compatibility Note:</STRONG>  The string collation functions are a new
feature of ANSI C.  Older C dialects have no equivalent feature.
<P>
<H2><A NAME="SEC64" HREF="library_toc.html#SEC64">Search Functions</A></H2>
<P>
This section describes library functions which perform various kinds
of searching operations on strings and arrays.  These functions are
declared in the header file <TT>`string.h'</TT>.
<A NAME="IDX315"></A>
<A NAME="IDX316"></A>
<A NAME="IDX314"></A>
<P>
<A NAME="IDX317"></A>
<U>Function:</U> void * <B>memchr</B> <I>(const void *<VAR>block</VAR>, int <VAR>c</VAR>, size_t <VAR>size</VAR>)</I><P>
This function finds the first occurrence of the byte <VAR>c</VAR> (converted
to an <CODE>unsigned char</CODE>) in the initial <VAR>size</VAR> bytes of the
object beginning at <VAR>block</VAR>.  The return value is a pointer to the
located byte, or a null pointer if no match was found.
<P>
<A NAME="IDX318"></A>
<U>Function:</U> char * <B>strchr</B> <I>(const char *<VAR>string</VAR>, int <VAR>c</VAR>)</I><P>
The <CODE>strchr</CODE> function finds the first occurrence of the character
<VAR>c</VAR> (converted to a <CODE>char</CODE>) in the null-terminated string
beginning at <VAR>string</VAR>.  The return value is a pointer to the located
character, or a null pointer if no match was found.
<P>
For example,
<PRE>
strchr ("hello, world", 'l')
    => "llo, world"
strchr ("hello, world", '?')
    => NULL
</PRE>
<P>
The terminating null character is considered to be part of the string,
so you can use this function get a pointer to the end of a string by
specifying a null character as the value of the <VAR>c</VAR> argument.
<P>
<A NAME="IDX319"></A>
<U>Function:</U> char * <B>strrchr</B> <I>(const char *<VAR>string</VAR>, int <VAR>c</VAR>)</I><P>
The function <CODE>strrchr</CODE> is like <CODE>strchr</CODE>, except that it searches
backwards from the end of the string <VAR>string</VAR> (instead of forwards
from the front).
<P>
For example,
<PRE>
strrchr ("hello, world", 'l')
    => "ld"
</PRE>
<P>
<A NAME="IDX320"></A>
<U>Function:</U> char * <B>strstr</B> <I>(const char *<VAR>haystack</VAR>, const char *<VAR>needle</VAR>)</I><P>
This is like <CODE>strchr</CODE>, except that it searches <VAR>haystack</VAR> for a
substring <VAR>needle</VAR> rather than just a single character.  It
returns a pointer into the string <VAR>haystack</VAR> that is the first
character of the substring, or a null pointer if no match was found.  If
<VAR>needle</VAR> is an empty string, the function returns <VAR>haystack</VAR>.
<P>
For example,
<PRE>
strstr ("hello, world", "l")
    => "llo, world"
strstr ("hello, world", "wo")
    => "world"
</PRE>
<P>
<A NAME="IDX321"></A>
<U>Function:</U> void * <B>memmem</B> <I>(const void *<VAR>needle</VAR>, size_t <VAR>needle_len</VAR>,<BR>const void *<VAR>haystack</VAR>, size_t <VAR>haystack_len</VAR>)</I><P>
This is like <CODE>strstr</CODE>, but <VAR>needle</VAR> and <VAR>haystack</VAR> are byte
arrays rather than null-terminated strings.  <VAR>needle_len</VAR> is the
length of <VAR>needle</VAR> and <VAR>haystack_len</VAR> is the length of
<VAR>haystack</VAR>.<P>
This function is a GNU extension.
<P>
<A NAME="IDX322"></A>
<U>Function:</U> size_t <B>strspn</B> <I>(const char *<VAR>string</VAR>, const char *<VAR>skipset</VAR>)</I><P>
The <CODE>strspn</CODE> ("string span") function returns the length of the
initial substring of <VAR>string</VAR> that consists entirely of characters that
are members of the set specified by the string <VAR>skipset</VAR>.  The order
of the characters in <VAR>skipset</VAR> is not important.
<P>
For example,
<PRE>
strspn ("hello, world", "abcdefghijklmnopqrstuvwxyz")
    => 5
</PRE>
<P>
<A NAME="IDX323"></A>
<U>Function:</U> size_t <B>strcspn</B> <I>(const char *<VAR>string</VAR>, const char *<VAR>stopset</VAR>)</I><P>
The <CODE>strcspn</CODE> ("string complement span") function returns the length
of the initial substring of <VAR>string</VAR> that consists entirely of characters
that are <EM>not</EM> members of the set specified by the string <VAR>stopset</VAR>.
(In other words, it returns the offset of the first character in <VAR>string</VAR>
that is a member of the set <VAR>stopset</VAR>.)
<P>
For example,
<PRE>
strcspn ("hello, world", " \t\n,.;!?")
    => 5
</PRE>
<P>
<A NAME="IDX324"></A>
<U>Function:</U> char * <B>strpbrk</B> <I>(const char *<VAR>string</VAR>, const char *<VAR>stopset</VAR>)</I><P>
The <CODE>strpbrk</CODE> ("string pointer break") function is related to
<CODE>strcspn</CODE>, except that it returns a pointer to the first character
in <VAR>string</VAR> that is a member of the set <VAR>stopset</VAR> instead of the
length of the initial substring.  It returns a null pointer if no such
character from <VAR>stopset</VAR> is found.
<P>
For example,
<P>
<PRE>
strpbrk ("hello, world", " \t\n,.;!?")
    => ", world"
</PRE>
<P>
<H2><A NAME="SEC65" HREF="library_toc.html#SEC65">Finding Tokens in a String</A></H2>
<P>
<A NAME="IDX325"></A>
<A NAME="IDX326"></A>
<A NAME="IDX327"></A>
<P>
It's fairly common for programs to have a need to do some simple kinds
of lexical analysis and parsing, such as splitting a command string up
into tokens.  You can do this with the <CODE>strtok</CODE> function, declared
in the header file <TT>`string.h'</TT>.
<A NAME="IDX328"></A>
<P>
<A NAME="IDX329"></A>
<U>Function:</U> char * <B>strtok</B> <I>(char *<VAR>newstring</VAR>, const char *<VAR>delimiters</VAR>)</I><P>
A string can be split into tokens by making a series of calls to the
function <CODE>strtok</CODE>.
<P>
The string to be split up is passed as the <VAR>newstring</VAR> argument on
the first call only.  The <CODE>strtok</CODE> function uses this to set up
some internal state information.  Subsequent calls to get additional
tokens from the same string are indicated by passing a null pointer as
the <VAR>newstring</VAR> argument.  Calling <CODE>strtok</CODE> with another
non-null <VAR>newstring</VAR> argument reinitializes the state information.
It is guaranteed that no other library function ever calls <CODE>strtok</CODE>
behind your back (which would mess up this internal state information).
<P>
The <VAR>delimiters</VAR> argument is a string that specifies a set of delimiters
that may surround the token being extracted.  All the initial characters
that are members of this set are discarded.  The first character that is
<EM>not</EM> a member of this set of delimiters marks the beginning of the
next token.  The end of the token is found by looking for the next
character that is a member of the delimiter set.  This character in the
original string <VAR>newstring</VAR> is overwritten by a null character, and the
pointer to the beginning of the token in <VAR>newstring</VAR> is returned.
<P>
On the next call to <CODE>strtok</CODE>, the searching begins at the next
character beyond the one that marked the end of the previous token.
Note that the set of delimiters <VAR>delimiters</VAR> do not have to be the
same on every call in a series of calls to <CODE>strtok</CODE>.
<P>
If the end of the string <VAR>newstring</VAR> is reached, or if the remainder of
string consists only of delimiter characters, <CODE>strtok</CODE> returns
a null pointer.
<P>
<STRONG>Warning:</STRONG> Since <CODE>strtok</CODE> alters the string it is parsing,
you always copy the string to a temporary buffer before parsing it with
<CODE>strtok</CODE>.  If you allow <CODE>strtok</CODE> to modify a string that came
from another part of your program, you are asking for trouble; that
string may be part of a data structure that could be used for other
purposes during the parsing, when alteration by <CODE>strtok</CODE> makes the
data structure temporarily inaccurate.
<P>
The string that you are operating on might even be a constant.  Then
when <CODE>strtok</CODE> tries to modify it, your program will get a fatal
signal for writing in read-only memory.  See section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
This is a special case of a general principle: if a part of a program
does not have as its purpose the modification of a certain data
structure, then it is error-prone to modify the data structure
temporarily.
<P>
The function <CODE>strtok</CODE> is not reentrant.  See section <A HREF="library.html#SEC357">Signal Handling and Nonreentrant Functions</A>, for
a discussion of where and why reentrancy is important.
<P>
Here is a simple example showing the use of <CODE>strtok</CODE>.
<P>
<PRE>
#include &#60;string.h&#62;
#include &#60;stddef.h&#62;

...

char string[] = "words separated by spaces -- and, punctuation!";
const char delimiters[] = " .,;:!-";
char *token;

...

token = strtok (string, delimiters);  /* token =&#62; "words" */
token = strtok (NULL, delimiters);    /* token =&#62; "separated" */
token = strtok (NULL, delimiters);    /* token =&#62; "by" */
token = strtok (NULL, delimiters);    /* token =&#62; "spaces" */
token = strtok (NULL, delimiters);    /* token =&#62; "and" */
token = strtok (NULL, delimiters);    /* token =&#62; "punctuation" */
token = strtok (NULL, delimiters);    /* token =&#62; NULL */
</PRE>
<H1><A NAME="SEC66" HREF="library_toc.html#SEC66">Extended Characters</A></H1>
<P>
A number of languages use character sets that are larger than the range
of values of type <CODE>char</CODE>.  Japanese and Chinese are probably the
most familiar examples.
<P>
The GNU C library includes support for two mechanisms for dealing with
extended character sets: multibyte characters and wide characters.  This
chapter describes how to use these mechanisms, and the functions for
converting between them.
<A NAME="IDX330"></A>
<P>
The behavior of the functions in this chapter is affected by the current
locale for character classification--the <CODE>LC_CTYPE</CODE> category; see
section <A HREF="library.html#SEC79">Categories of Activities that Locales Affect</A>.  This choice of locale selects which multibyte
code is used, and also controls the meanings and characteristics of wide
character codes.
<P>
<H2><A NAME="SEC67" HREF="library_toc.html#SEC67">Introduction to Extended Characters</A></H2>
<P>
You can represent extended characters in either of two ways:
<P>
<UL>
<LI>
As <DFN>Multibyte characters</DFN> which can be embedded in an ordinary
string, an array of <CODE>char</CODE> objects.  Their advantage is that many
programs and operating systems can handle occasional multibyte
characters scattered among ordinary ASCII characters, without any
change.
<P>
<A NAME="IDX331"></A>
<LI>
As <DFN>wide characters</DFN>, which are like ordinary characters except that
they occupy more bits.  The wide character data type, <CODE>wchar_t</CODE>,
has a range large enough to hold extended character codes as well as
old-fashioned ASCII codes.
<P>
An advantage of wide characters is that each character is a single data
object, just like ordinary ASCII characters.  There are a few
disadvantages:
<P>
<UL>
<LI>
Each existing program must be modified and recompiled to make it use
wide characters.
<P>
<LI>
Files of wide characters cannot be read by programs that expect ordinary
characters.
</UL>
</UL>
<P>
Typically, you use the multibyte character representation as part of the
external program interface, such as reading or writing text to files.
However, it's usually easier to perform internal manipulations on
strings containing extended characters on arrays of <CODE>wchar_t</CODE>
objects, since the uniform representation makes most editing operations
easier.  If you do use multibyte characters for files and wide
characters for internal operations, you need to convert between them
when you read and write data.
<P>
If your system supports extended characters, then it supports them both
as multibyte characters and as wide characters.  The library includes
functions you can use to convert between the two representations.
These functions are described in this chapter.
<P>
<H2><A NAME="SEC68" HREF="library_toc.html#SEC68">Locales and Extended Characters</A></H2>
<P>
A computer system can support more than one multibyte character code,
and more than one wide character code.  The user controls the choice of
codes through the current locale for character classification
(see section <A HREF="library.html#SEC76">Locales and Internationalization</A>).  Each locale specifies a particular multibyte
character code and a particular wide character code.  The choice of locale
influences the behavior of the conversion functions in the library.
<P>
Some locales support neither wide characters nor nontrivial multibyte
characters.  In these locales, the library conversion functions still
work, even though what they do is basically trivial.
<P>
If you select a new locale for character classification, the internal
shift state maintained by these functions can become confused, so it's
not a good idea to change the locale while you are in the middle of
processing a string.
<P>
<A NAME="IDX332"></A>
<H2><A NAME="SEC69" HREF="library_toc.html#SEC69">Multibyte Characters</A></H2>
<P>
In the ordinary ASCII code, a sequence of characters is a sequence of
bytes, and each character is one byte.  This is very simple, but
allows for only 256 distinct characters.
<P>
In a <DFN>multibyte character code</DFN>, a sequence of characters is a
sequence of bytes, but each character may occupy one or more consecutive
bytes of the sequence.
<A NAME="IDX333"></A>
<P>
There are many different ways of designing a multibyte character code;
different systems use different codes.  To specify a particular code
means designating the <DFN>basic</DFN> byte sequences--those which represent
a single character--and what characters they stand for.  A code that a
computer can actually use must have a finite number of these basic
sequences, and typically none of them is more than a few characters
long.
<P>
These sequences need not all have the same length.  In fact, many of
them are just one byte long.  Because the basic ASCII characters in the
range from <CODE>0</CODE> to <CODE>0177</CODE> are so important, they stand for
themselves in all multibyte character codes.  That is to say, a byte
whose value is <CODE>0</CODE> through <CODE>0177</CODE> is always a character in
itself.  The characters which are more than one byte must always start
with a byte in the range from <CODE>0200</CODE> through <CODE>0377</CODE>.
<P>
The byte value <CODE>0</CODE> can be used to terminated a string, just as it
is often used in a string of ASCII characters.
<P>
Specifying the basic byte sequences that represent single characters
automatically gives meanings to many longer byte sequences, as more than
one character.  For example, if the two byte sequence <CODE>0205 049</CODE>
stands for the Greek letter alpha, then <CODE>0205 049 065</CODE> must stand
for an alpha followed by an <SAMP>`A'</SAMP> (ASCII code 065), and <CODE>0205 049
0205 049</CODE> must stand for two alphas in a row.
<P>
If any byte sequence can have more than one meaning as a sequence of
characters, then the multibyte code is ambiguous--and no good.  The
codes that systems actually use are all unambiguous.
<P>
In most codes, there are certain sequences of bytes that have no meaning
as a character or characters.  These are called <DFN>invalid</DFN>.
<P>
The simplest possible multibyte code is a trivial one:
<P>
<BLOCKQUOTE>
The basic sequences consist of single bytes.
</BLOCKQUOTE>
<P>
This particular code is equivalent to not using multibyte characters at
all.  It has no invalid sequences.  But it can handle only 256 different
characters.
<P>
Here is another possible code which can handle 9376 different
characters:
<P>
<BLOCKQUOTE>
The basic sequences consist of
<P>
<UL>
<LI>
single bytes with values in the range <CODE>0</CODE> through <CODE>0237</CODE>.
<P>
<LI>
two-byte sequences, in which both of the bytes have values in the range
from <CODE>0240</CODE> through <CODE>0377</CODE>.
</UL>
</BLOCKQUOTE>
<P>
This code or a similar one is used on some systems to represent Japanese
characters.  The invalid sequences are those which consist of an odd
number of consecutive bytes in the range from <CODE>0240</CODE> through
<CODE>0377</CODE>.
<P>
Here is another multibyte code which can handle more distinct extended
characters--in fact, almost thirty million:
<P>
<BLOCKQUOTE>
The basic sequences consist of
<P>
<UL>
<LI>
single bytes with values in the range <CODE>0</CODE> through <CODE>0177</CODE>.
<P>
<LI>
sequences of up to four bytes in which the first byte is in the range
from <CODE>0200</CODE> through <CODE>0237</CODE>, and the remaining bytes are in the
range from <CODE>0240</CODE> through <CODE>0377</CODE>.
</UL>
</BLOCKQUOTE>
<P>
In this code, any sequence that starts with a byte in the range
from <CODE>0240</CODE> through <CODE>0377</CODE> is invalid.
<P>
And here is another variant which has the advantage that removing the
last byte or bytes from a valid character can never produce another
valid character.  (This property is convenient when you want to search
strings for particular characters.)
<P>
<BLOCKQUOTE>
The basic sequences consist of
<P>
<UL>
<LI>
single bytes with values in the range <CODE>0</CODE> through <CODE>0177</CODE>.
<P>
<LI>
two-byte sequences in which the first byte is in the range from
<CODE>0200</CODE> through <CODE>0207</CODE>, and the second byte is in the range
from <CODE>0240</CODE> through <CODE>0377</CODE>.
<P>
<LI>
three-byte sequences in which the first byte is in the range from
<CODE>0210</CODE> through <CODE>0217</CODE>, and the other bytes are in the range
from <CODE>0240</CODE> through <CODE>0377</CODE>.
<P>
<LI>
four-byte sequences in which the first byte is in the range from
<CODE>0220</CODE> through <CODE>0227</CODE>, and the other bytes are in the range
from <CODE>0240</CODE> through <CODE>0377</CODE>.
</UL>
</BLOCKQUOTE>
<P>
The list of invalid sequences for this code is long and not worth
stating in full; examples of invalid sequences include <CODE>0240</CODE> and
<CODE>0220 0300 065</CODE>.
<P>
The number of <EM>possible</EM> multibyte codes is astronomical.  But a
given computer system will support at most a few different codes.  (One
of these codes may allow for thousands of different characters.)
Another computer system may support a completely different code.  The
library facilities described in this chapter are helpful because they
package up the knowledge of the details of a particular computer
system's multibyte code, so your programs need not know them.
<P>
You can use special standard macros to find out the maximum possible
number of bytes in a character in the currently selected multibyte
code with <CODE>MB_CUR_MAX</CODE>, and the maximum for <EM>any</EM> multibyte
code supported on your computer with <CODE>MB_LEN_MAX</CODE>.
<P>
<A NAME="IDX334"></A>
<U>Macro:</U> int <B>MB_LEN_MAX</B><P>
This is the maximum length of a multibyte character for any supported
locale.  It is defined in <TT>`limits.h'</TT>.
<A NAME="IDX335"></A>
<P>
<A NAME="IDX336"></A>
<U>Macro:</U> int <B>MB_CUR_MAX</B><P>
This macro expands into a (possibly non-constant) positive integer
expression that is the maximum number of bytes in a multibyte character
in the current locale.  The value is never greater than <CODE>MB_LEN_MAX</CODE>.
<A NAME="IDX337"></A>
<P>
<CODE>MB_CUR_MAX</CODE> is defined in <TT>`stdlib.h'</TT>.
<P>
Normally, each basic sequence in a particular character code stands for
one character, the same character regardless of context.  Some multibyte
character codes have a concept of <DFN>shift state</DFN>; certain codes,
called <DFN>shift sequences</DFN>, change to a different shift state, and the
meaning of some or all basic sequences varies according to the current
shift state.  In fact, the set of basic sequences might even be
different depending on the current shift state.  See section <A HREF="library.html#SEC75">Multibyte Codes Using Shift Sequences</A>, for
more information on handling this sort of code.
<P>
What happens if you try to pass a string containing multibyte characters
to a function that doesn't know about them?  Normally, such a function
treats a string as a sequence of bytes, and interprets certain byte
values specially; all other byte values are "ordinary".  As long as a
multibyte character doesn't contain any of the special byte values, the
function should pass it through as if it were several ordinary
characters.
<P>
For example, let's figure out what happens if you use multibyte
characters in a file name.  The functions such as <CODE>open</CODE> and
<CODE>unlink</CODE> that operate on file names treat the name as a sequence of
byte values, with <SAMP>`/'</SAMP> as the only special value.  Any other byte
values are copied, or compared, in sequence, and all byte values are
treated alike.  Thus, you may think of the file name as a sequence of
bytes or as a string containing multibyte characters; the same behavior
makes sense equally either way, provided no multibyte character contains
a <SAMP>`/'</SAMP>.
<P>
<H2><A NAME="SEC70" HREF="library_toc.html#SEC70">Wide Character Introduction</A></H2>
<P>
<DFN>Wide characters</DFN> are much simpler than multibyte characters.  They
are simply characters with more than eight bits, so that they have room
for more than 256 distinct codes.  The wide character data type,
<CODE>wchar_t</CODE>, has a range large enough to hold extended character
codes as well as old-fashioned ASCII codes.
<P>
An advantage of wide characters is that each character is a single data
object, just like ordinary ASCII characters.  Wide characters also have
some disadvantages:
<P>
<UL>
<LI>
A program must be modified and recompiled in order to use wide
characters at all.
<P>
<LI>
Files of wide characters cannot be read by programs that expect ordinary
characters.
</UL>
<P>
Wide character values <CODE>0</CODE> through <CODE>0177</CODE> are always identical
in meaning to the ASCII character codes.  The wide character value zero
is often used to terminate a string of wide characters, just as a single
byte with value zero often terminates a string of ordinary characters.
<P>
<A NAME="IDX338"></A>
<U>Data Type:</U> <B>wchar_t</B><P>
This is the "wide character" type, an integer type whose range is
large enough to represent all distinct values in any extended character
set in the supported locales.  See section <A HREF="library.html#SEC76">Locales and Internationalization</A>, for more information
about locales.  This type is defined in the header file <TT>`stddef.h'</TT>.
<A NAME="IDX339"></A>
<P>
If your system supports extended characters, then each extended
character has both a wide character code and a corresponding multibyte
basic sequence.
<A NAME="IDX340"></A>
<A NAME="IDX341"></A>
<P>
In this chapter, the term <DFN>code</DFN> is used to refer to a single
extended character object to emphasize the distinction from the
<CODE>char</CODE> data type.
<P>
<A NAME="IDX342"></A>
<A NAME="IDX343"></A>
<H2><A NAME="SEC71" HREF="library_toc.html#SEC71">Conversion of Extended Strings</A></H2>
<A NAME="IDX344"></A>
<P>
The <CODE>mbstowcs</CODE> function converts a string of multibyte characters
to a wide character array.  The <CODE>wcstombs</CODE> function does the
reverse.  These functions are declared in the header file
<TT>`stdlib.h'</TT>.
<P>
In most programs, these functions are the only ones you need for
conversion between wide strings and multibyte character strings.  But
they have limitations.  If your data is not null-terminated or is not
all in core at once, you probably need to use the low-level conversion
functions to convert one character at a time.  See section <A HREF="library.html#SEC73">Conversion of Extended Characters One by One</A>.
<P>
<A NAME="IDX345"></A>
<U>Function:</U> size_t <B>mbstowcs</B> <I>(wchar_t *<VAR>wstring</VAR>, const char *<VAR>string</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>mbstowcs</CODE> ("multibyte string to wide character string")
function converts the null-terminated string of multibyte characters
<VAR>string</VAR> to an array of wide character codes, storing not more than
<VAR>size</VAR> wide characters into the array beginning at <VAR>wstring</VAR>.
The terminating null character counts towards the size, so if <VAR>size</VAR>
is less than the actual number of wide characters resulting from
<VAR>string</VAR>, no terminating null character is stored.
<P>
The conversion of characters from <VAR>string</VAR> begins in the initial
shift state.
<P>
If an invalid multibyte character sequence is found, this function
returns a value of <CODE>-1</CODE>.  Otherwise, it returns the number of wide
characters stored in the array <VAR>wstring</VAR>.  This number does not
include the terminating null character, which is present if the number
is less than <VAR>size</VAR>.
<P>
Here is an example showing how to convert a string of multibyte
characters, allocating enough space for the result.
<P>
<PRE>
wchar_t *
mbstowcs_alloc (char *string)
{
  int size = strlen (string) + 1;
  wchar_t *buffer = (wchar_t) xmalloc (size * sizeof (wchar_t));

  size = mbstowcs (buffer, string, size);
  if (size &#60; 0)
    return NULL;
  return (wchar_t) xrealloc (buffer, (size + 1) * sizeof (wchar_t));
}
</PRE>
<P>
<A NAME="IDX346"></A>
<U>Function:</U> size_t <B>wcstombs</B> <I>(char *<VAR>string</VAR>, const wchar_t <VAR>wstring</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>wcstombs</CODE> ("wide character string to multibyte string")
function converts the null-terminated wide character array <VAR>wstring</VAR>
into a string containing multibyte characters, storing not more than
<VAR>size</VAR> bytes starting at <VAR>string</VAR>, followed by a terminating
null character if there is room.  The conversion of characters begins in
the initial shift state.
<P>
The terminating null character counts towards the size, so if <VAR>size</VAR>
is less than or equal to the number of bytes needed in <VAR>wstring</VAR>, no
terminating null character is stored.
<P>
If a code that does not correspond to a valid multibyte character is
found, this function returns a value of <CODE>-1</CODE>.  Otherwise, the
return value is the number of bytes stored in the array <VAR>string</VAR>.
This number does not include the terminating null character, which is
present if the number is less than <VAR>size</VAR>.
<P>
<A NAME="IDX347"></A>
<A NAME="IDX348"></A>
<H2><A NAME="SEC72" HREF="library_toc.html#SEC72">Multibyte Character Length</A></H2>
<P>
This section describes how to scan a string containing multibyte
characters, one character at a time.  The difficulty in doing this
is to know how many bytes each character contains.  Your program 
can use <CODE>mblen</CODE> to find this out.
<P>
<A NAME="IDX349"></A>
<U>Function:</U> int <B>mblen</B> <I>(const char *<VAR>string</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>mblen</CODE> function with non-null <VAR>string</VAR> returns the number
of bytes that make up the multibyte character beginning at <VAR>string</VAR>,
never examining more than <VAR>size</VAR> bytes.  (The idea is to supply
for <VAR>size</VAR> the number of bytes of data you have in hand.)
<P>
The return value of <CODE>mblen</CODE> distinguishes three possibilities: the
first <VAR>size</VAR> bytes at <VAR>string</VAR> start with valid multibyte
character, they start with an invalid byte sequence or just part of a
character, or <VAR>string</VAR> points to an empty string (a null character).
<P>
For a valid multibyte character, <CODE>mblen</CODE> returns the number of
bytes in that character (always at least <CODE>1</CODE>, and never more than
<VAR>size</VAR>).  For an invalid byte sequence, <CODE>mblen</CODE> returns
<CODE>-1</CODE>.  For an empty string, it returns <CODE>0</CODE>.
<P>
If the multibyte character code uses shift characters, then <CODE>mblen</CODE>
maintains and updates a shift state as it scans.  If you call
<CODE>mblen</CODE> with a null pointer for <VAR>string</VAR>, that initializes the
shift state to its standard initial value.  It also returns nonzero if
the multibyte character code in use actually has a shift state.
See section <A HREF="library.html#SEC75">Multibyte Codes Using Shift Sequences</A>.
<A NAME="IDX350"></A>
<P>
The function <CODE>mblen</CODE> is declared in <TT>`stdlib.h'</TT>.
<P>
<A NAME="IDX351"></A>
<A NAME="IDX352"></A>
<H2><A NAME="SEC73" HREF="library_toc.html#SEC73">Conversion of Extended Characters One by One</A></H2>
<A NAME="IDX353"></A>
<P>
You can convert multibyte characters one at a time to wide characters
with the <CODE>mbtowc</CODE> function.  The <CODE>wctomb</CODE> function does the
reverse.  These functions are declared in <TT>`stdlib.h'</TT>.
<P>
<A NAME="IDX354"></A>
<U>Function:</U> int <B>mbtowc</B> <I>(wchar_t *<VAR>result</VAR>, const char *<VAR>string</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>mbtowc</CODE> ("multibyte to wide character") function when called
with non-null <VAR>string</VAR> converts the first multibyte character
beginning at <VAR>string</VAR> to its corresponding wide character code.  It
stores the result in <CODE>*<VAR>result</VAR></CODE>.
<P>
<CODE>mbtowc</CODE> never examines more than <VAR>size</VAR> bytes.  (The idea is
to supply for <VAR>size</VAR> the number of bytes of data you have in hand.)
<P>
<CODE>mbtowc</CODE> with non-null <VAR>string</VAR> distinguishes three
possibilities: the first <VAR>size</VAR> bytes at <VAR>string</VAR> start with
valid multibyte character, they start with an invalid byte sequence or
just part of a character, or <VAR>string</VAR> points to an empty string (a
null character).
<P>
For a valid multibyte character, <CODE>mbtowc</CODE> converts it to a wide
character and stores that in <CODE>*<VAR>result</VAR></CODE>, and returns the
number of bytes in that character (always at least <CODE>1</CODE>, and never
more than <VAR>size</VAR>).
<P>
For an invalid byte sequence, <CODE>mbtowc</CODE> returns <CODE>-1</CODE>.  For an
empty string, it returns <CODE>0</CODE>, also storing <CODE>0</CODE> in
<CODE>*<VAR>result</VAR></CODE>.
<P>
If the multibyte character code uses shift characters, then
<CODE>mbtowc</CODE> maintains and updates a shift state as it scans.  If you
call <CODE>mbtowc</CODE> with a null pointer for <VAR>string</VAR>, that
initializes the shift state to its standard initial value.  It also
returns nonzero if the multibyte character code in use actually has a
shift state.  See section <A HREF="library.html#SEC75">Multibyte Codes Using Shift Sequences</A>.
<P>
<A NAME="IDX355"></A>
<U>Function:</U> int <B>wctomb</B> <I>(char *<VAR>string</VAR>, wchar_t <VAR>wchar</VAR>)</I><P>
The <CODE>wctomb</CODE> ("wide character to multibyte") function converts
the wide character code <VAR>wchar</VAR> to its corresponding multibyte
character sequence, and stores the result in bytes starting at
<VAR>string</VAR>.  At most <CODE>MB_CUR_MAX</CODE> characters are stored.
<P>
<CODE>wctomb</CODE> with non-null <VAR>string</VAR> distinguishes three
possibilities for <VAR>wchar</VAR>: a valid wide character code (one that can
be translated to a multibyte character), an invalid code, and <CODE>0</CODE>.
<P>
Given a valid code, <CODE>wctomb</CODE> converts it to a multibyte character,
storing the bytes starting at <VAR>string</VAR>.  Then it returns the number
of bytes in that character (always at least <CODE>1</CODE>, and never more
than <CODE>MB_CUR_MAX</CODE>).
<P>
If <VAR>wchar</VAR> is an invalid wide character code, <CODE>wctomb</CODE> returns
<CODE>-1</CODE>.  If <VAR>wchar</VAR> is <CODE>0</CODE>, it returns <CODE>0</CODE>, also
storing <CODE>0</CODE> in <CODE>*<VAR>string</VAR></CODE>.
<P>
If the multibyte character code uses shift characters, then
<CODE>wctomb</CODE> maintains and updates a shift state as it scans.  If you
call <CODE>wctomb</CODE> with a null pointer for <VAR>string</VAR>, that
initializes the shift state to its standard initial value.  It also
returns nonzero if the multibyte character code in use actually has a
shift state.  See section <A HREF="library.html#SEC75">Multibyte Codes Using Shift Sequences</A>.
<P>
Calling this function with a <VAR>wchar</VAR> argument of zero when
<VAR>string</VAR> is not null has the side-effect of reinitializing the
stored shift state <EM>as well as</EM> storing the multibyte character
<CODE>0</CODE> and returning <CODE>0</CODE>.
<P>
<H2><A NAME="SEC74" HREF="library_toc.html#SEC74">Example of Character-by-Character Conversion</A></H2>
<P>
Here is an example that reads multibyte character text from descriptor
<CODE>input</CODE> and writes the corresponding wide characters to descriptor
<CODE>output</CODE>.  We need to convert characters one by one for this
example because <CODE>mbstowcs</CODE> is unable to continue past a null
character, and cannot cope with an apparently invalid partial character
by reading more input.
<P>
<PRE>
int
file_mbstowcs (int input, int output)
{
  char buffer[BUFSIZ + MB_LEN_MAX];
  int filled = 0;
  int eof = 0;

  while (!eof)
    {
      int nread;
      int nwrite;
      char *inp = buffer;
      wchar_t outbuf[BUFSIZ];
      wchar_t *outp = outbuf;

      /* Fill up the buffer from the input file.  */
      nread = read (input, buffer + filled, BUFSIZ);
      if (nread &#60; 0) {
        perror ("read");
        return 0;
      }
      /* If we reach end of file, make a note to read no more. */
      if (nread == 0)
        eof = 1;

      /* <CODE>filled</CODE> is now the number of bytes in <CODE>buffer</CODE>. */
      filled += nread;

      /* Convert those bytes to wide characters--as many as we can. */
      while (1)
        {
          int thislen = mbtowc (outp, inp, filled);
          /* Stop converting at invalid character;
             this can mean we have read just the first part
             of a valid character.  */
          if (thislen == -1)
            break;
          /* Treat null character like any other,
             but also reset shift state. */
          if (thislen == 0) {
            thislen = 1;
            mbtowc (NULL, NULL, 0);
          }
          /* Advance past this character. */
          inp += thislen;
          filled -= thislen;
          outp++;
        }

      /* Write the wide characters we just made.  */
      nwrite = write (output, outbuf,
                      (outp - outbuf) * sizeof (wchar_t));
      if (nwrite &#60; 0)
        {
          perror ("write");
          return 0;
        }

      /* See if we have a <EM>real</EM> invalid character. */
      if ((eof &#38;&#38; filled &#62; 0) || filled &#62;= MB_CUR_MAX)
        {
          error ("invalid multibyte character");
          return 0;
        }

      /* If any characters must be carried forward,
         put them at the beginning of <CODE>buffer</CODE>. */
      if (filled &#62; 0)
        memcpy (inp, buffer, filled);
      }
    }

  return 1;
}
</PRE>
<P>
<H2><A NAME="SEC75" HREF="library_toc.html#SEC75">Multibyte Codes Using Shift Sequences</A></H2>
<P>
In some multibyte character codes, the <EM>meaning</EM> of any particular
byte sequence is not fixed; it depends on what other sequences have come
earlier in the same string.  Typically there are just a few sequences
that can change the meaning of other sequences; these few are called
<DFN>shift sequences</DFN> and we say that they set the <DFN>shift state</DFN> for
other sequences that follow.
<P>
To illustrate shift state and shift sequences, suppose we decide that
the sequence <CODE>0200</CODE> (just one byte) enters Japanese mode, in which
pairs of bytes in the range from <CODE>0240</CODE> to <CODE>0377</CODE> are single
characters, while <CODE>0201</CODE> enters Latin-1 mode, in which single bytes
in the range from <CODE>0240</CODE> to <CODE>0377</CODE> are characters, and
interpreted according to the ISO Latin-1 character set.  This is a
multibyte code which has two alternative shift states ("Japanese mode"
and "Latin-1 mode"), and two shift sequences that specify particular
shift states.
<P>
When the multibyte character code in use has shift states, then
<CODE>mblen</CODE>, <CODE>mbtowc</CODE> and <CODE>wctomb</CODE> must maintain and update
the current shift state as they scan the string.  To make this work
properly, you must follow these rules:
<P>
<UL>
<LI>
Before starting to scan a string, call the function with a null pointer
for the multibyte character address--for example, <CODE>mblen (NULL,
0)</CODE>.  This initializes the shift state to its standard initial value.
<P>
<LI>
Scan the string one character at a time, in order.  Do not "back up"
and rescan characters already scanned, and do not intersperse the
processing of different strings.
</UL>
<P>
Here is an example of using <CODE>mblen</CODE> following these rules:
<P>
<PRE>
void
scan_string (char *s)
{
  int length = strlen (s);

  /* Initialize shift state. */
  mblen (NULL, 0);

  while (1)
    {
      int thischar = mblen (s, length);
      /* Deal with end of string and invalid characters. */
      if (thischar == 0)
        break;
      if (thischar == -1)
        {
          error ("invalid multibyte character");
          break;
        }
      /* Advance past this character. */
      s += thischar;
      length -= thischar;
    }
}
</PRE>
<P>
The functions <CODE>mblen</CODE>, <CODE>mbtowc</CODE> and <CODE>wctomb</CODE> are not
reentrant when using a multibyte code that uses a shift state.  However,
no other library functions call these functions, so you don't have to
worry that the shift state will be changed mysteriously.
<H1><A NAME="SEC76" HREF="library_toc.html#SEC76">Locales and Internationalization</A></H1>
<P>
Different countries and cultures have varying conventions for how to
communicate.  These conventions range from very simple ones, such as the
format for representing dates and times, to very complex ones, such as
the language spoken.
<A NAME="IDX356"></A>
<A NAME="IDX357"></A>
<P>
<DFN>Internationalization</DFN> of software means programming it to be able
to adapt to the user's favorite conventions.  In ANSI C,
internationalization works by means of <DFN>locales</DFN>.  Each locale
specifies a collection of conventions, one convention for each purpose.
The user chooses a set of conventions by specifying a locale (via
environment variables).
<P>
All programs inherit the chosen locale as part of their environment.
Provided the programs are written to obey the choice of locale, they
will follow the conventions preferred by the user.
<P>
<H2><A NAME="SEC77" HREF="library_toc.html#SEC77">What Effects a Locale Has</A></H2>
<P>
Each locale specifies conventions for several purposes, including the
following:
<P>
<UL>
<LI>
What multibyte character sequences are valid, and how they are
interpreted (see section <A HREF="library.html#SEC66">Extended Characters</A>).
<P>
<LI>
Classification of which characters in the local character set are
considered alphabetic, and upper- and lower-case conversion conventions
(see section <A HREF="library.html#SEC54">Character Handling</A>).
<P>
<LI>
The collating sequence for the local language and character set
(see section <A HREF="library.html#SEC63">Collation Functions</A>).
<P>
<LI>
Formatting of numbers and currency amounts.
<P>
<LI>
Formatting of dates and times (see section <A HREF="library.html#SEC317">Formatting Date and Time</A>).
<P>
<LI>
What language to use for output, including error messages.
(The C library doesn't yet help you implement this.)
<P>
<LI>
What language to use for user answers to yes-or-no questions.
<P>
<LI>
What language to use for more complex user input.
(The C library doesn't yet help you implement this.)
</UL>
<P>
Some aspects of adapting to the specified locale are handled
automatically by the library subroutines.  For example, all your program
needs to do in order to use the collating sequence of the chosen locale
is to use <CODE>strcoll</CODE> or <CODE>strxfrm</CODE> to compare strings.
<P>
Other aspects of locales are beyond the comprehension of the library.
For example, the library can't automatically translate your program's
output messages into other languages.  The only way you can support
output in the user's favorite language is to program this more or less
by hand.  (Eventually, we hope to provide facilities to make this
easier.)
<P>
This chapter discusses the mechanism by which you can modify the current
locale.  The effects of the current locale on specific library functions
are discussed in more detail in the descriptions of those functions.
<P>
<H2><A NAME="SEC78" HREF="library_toc.html#SEC78">Choosing a Locale</A></H2>
<P>
The simplest way for the user to choose a locale is to set the
environment variable <CODE>LANG</CODE>.  This specifies a single locale to use
for all purposes.  For example, a user could specify a hypothetical
locale named <SAMP>`espana-castellano'</SAMP> to use the standard conventions of
most of Spain.
<P>
The set of locales supported depends on the operating system you are
using, and so do their names.  We can't make any promises about what
locales will exist, except for one standard locale called <SAMP>`C'</SAMP> or
<SAMP>`POSIX'</SAMP>.
<A NAME="IDX358"></A>
<P>
A user also has the option of specifying different locales for different
purposes--in effect, choosing a mixture of two locales.
<P>
For example, the user might specify the locale <SAMP>`espana-castellano'</SAMP>
for most purposes, but specify the locale <SAMP>`usa-english'</SAMP> for
currency formatting.  This might make sense if the user is a
Spanish-speaking American, working in Spanish, but representing monetary
amounts in US dollars.
<P>
Note that both locales <SAMP>`espana-castellano'</SAMP> and <SAMP>`usa-english'</SAMP>,
like all locales, would include conventions for all of the purposes to
which locales apply.  However, the user can choose to use each locale
for a particular subset of those purposes.
<P>
<A NAME="IDX359"></A>
<A NAME="IDX360"></A>
<H2><A NAME="SEC79" HREF="library_toc.html#SEC79">Categories of Activities that Locales Affect</A></H2>
<P>
The purposes that locales serve are grouped into <DFN>categories</DFN>, so
that a user or a program can choose the locale for each category
independently.  Here is a table of categories; each name is both an
environment variable that a user can set, and a macro name that you can
use as an argument to <CODE>setlocale</CODE>.
<P>
<DL COMPACT>
<A NAME="IDX361"></A>
<DT><CODE>LC_COLLATE</CODE>
<DD>This category applies to collation of strings (functions <CODE>strcoll</CODE>
and <CODE>strxfrm</CODE>); see section <A HREF="library.html#SEC63">Collation Functions</A>.
<P>
<A NAME="IDX362"></A>
<DT><CODE>LC_CTYPE</CODE>
<DD>This category applies to classification and conversion of characters;
see section <A HREF="library.html#SEC54">Character Handling</A>.
<P>
<A NAME="IDX363"></A>
<DT><CODE>LC_MONETARY</CODE>
<DD>This category applies to formatting monetary values; see section <A HREF="library.html#SEC82">Numeric Formatting</A>.
<P>
<A NAME="IDX364"></A>
<DT><CODE>LC_NUMERIC</CODE>
<DD>This category applies to formatting numeric values that are not
monetary; see section <A HREF="library.html#SEC82">Numeric Formatting</A>.
<P>
<A NAME="IDX365"></A>
<DT><CODE>LC_TIME</CODE>
<DD>This category applies to formatting date and time values; see
section <A HREF="library.html#SEC317">Formatting Date and Time</A>.
<P>
<A NAME="IDX366"></A>
<DT><CODE>LC_ALL</CODE>
<DD>This is not an environment variable; it is only a macro that you can use
with <CODE>setlocale</CODE> to set a single locale for all purposes.
<P>
<A NAME="IDX367"></A>
<DT><CODE>LANG</CODE>
<DD>If this environment variable is defined, its value specifies the locale
to use for all purposes except as overridden by the variables above.
</DL>
<P>
<H2><A NAME="SEC80" HREF="library_toc.html#SEC80">How Programs Set the Locale</A></H2>
<P>
A C program inherits its locale environment variables when it starts up.
This happens automatically.  However, these variables do not
automatically control the locale used by the library functions, because
ANSI C says that all programs start by default in the standard <SAMP>`C'</SAMP>
locale.  To use the locales specified by the environment, you must call
<CODE>setlocale</CODE>.  Call it as follows:
<P>
<PRE>
setlocale (LC_ALL, "");
</PRE>
<P>
to select a locale based on the appropriate environment variables.
<A NAME="IDX368"></A>
<A NAME="IDX369"></A>
<P>
You can also use <CODE>setlocale</CODE> to specify a particular locale, for
general use or for a specific category.
<A NAME="IDX370"></A>
<P>
The symbols in this section are defined in the header file <TT>`locale.h'</TT>.
<P>
<A NAME="IDX371"></A>
<U>Function:</U> char * <B>setlocale</B> <I>(int <VAR>category</VAR>, const char *<VAR>locale</VAR>)</I><P>
The function <CODE>setlocale</CODE> sets the current locale for 
category <VAR>category</VAR> to <VAR>locale</VAR>.
<P>
If <VAR>category</VAR> is <CODE>LC_ALL</CODE>, this specifies the locale for all
purposes.  The other possible values of <VAR>category</VAR> specify an
individual purpose (see section <A HREF="library.html#SEC79">Categories of Activities that Locales Affect</A>).
<P>
You can also use this function to find out the current locale by passing
a null pointer as the <VAR>locale</VAR> argument.  In this case,
<CODE>setlocale</CODE> returns a string that is the name of the locale
currently selected for category <VAR>category</VAR>.
<P>
The string returned by <CODE>setlocale</CODE> can be overwritten by subsequent
calls, so you should make a copy of the string (see section <A HREF="library.html#SEC61">Copying and Concatenation</A>) if you want to save it past any further calls to
<CODE>setlocale</CODE>.  (The standard library is guaranteed never to call
<CODE>setlocale</CODE> itself.)
<P>
You should not modify the string returned by <CODE>setlocale</CODE>.
It might be the same string that was passed as an argument in a 
previous call to <CODE>setlocale</CODE>.
<P>
When you read the current locale for category <CODE>LC_ALL</CODE>, the value
encodes the entire combination of selected locales for all categories.
In this case, the value is not just a single locale name.  In fact, we
don't make any promises about what it looks like.  But if you specify
the same "locale name" with <CODE>LC_ALL</CODE> in a subsequent call to
<CODE>setlocale</CODE>, it restores the same combination of locale selections.
<P>
When the <VAR>locale</VAR> argument is not a null pointer, the string returned
by <CODE>setlocale</CODE> reflects the newly modified locale.
<P>
If you specify an empty string for <VAR>locale</VAR>, this means to read the
appropriate environment variable and use its value to select the locale
for <VAR>category</VAR>.
<P>
If you specify an invalid locale name, <CODE>setlocale</CODE> returns a null
pointer and leaves the current locale unchanged.
<P>
Here is an example showing how you might use <CODE>setlocale</CODE> to
temporarily switch to a new locale.
<P>
<PRE>
#include &#60;stddef.h&#62;
#include &#60;locale.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;string.h&#62;

void
with_other_locale (char *new_locale,
                   void (*subroutine) (int),
                   int argument)
{
  char *old_locale, *saved_locale;

  /* Get the name of the current locale.  */
  old_locale = setlocale (LC_ALL, NULL);
  
  /* Copy the name so it won't be clobbered by <CODE>setlocale</CODE>. */
  saved_locale = strdup (old_locale);
  if (old_locale == NULL)
    fatal ("Out of memory");
  
  /* Now change the locale and do some stuff with it. */
  setlocale (LC_ALL, new_locale);
  (*subroutine) (argument);
  
  /* Restore the original locale. */
  setlocale (LC_ALL, saved_locale);
  free (saved_locale);
}
</PRE>
<P>
<STRONG>Portability Note:</STRONG> Some ANSI C systems may define additional
locale categories.  For portability, assume that any symbol beginning
with <SAMP>`LC_'</SAMP> might be defined in <TT>`locale.h'</TT>.
<P>
<H2><A NAME="SEC81" HREF="library_toc.html#SEC81">Standard Locales</A></H2>
<P>
The only locale names you can count on finding on all operating systems
are these three standard ones:
<P>
<DL COMPACT>
<DT><CODE>"C"</CODE>
<DD>This is the standard C locale.  The attributes and behavior it provides
are specified in the ANSI C standard.  When your program starts up, it
initially uses this locale by default.
<P>
<DT><CODE>"POSIX"</CODE>
<DD>This is the standard POSIX locale.  Currently, it is an alias for the
standard C locale.
<P>
<DT><CODE>""</CODE>
<DD>The empty name stands for a site-specific default locale.  It's supposed
to be a good default for the machine on which the program is running.
</DL>
<P>
Defining and installing named locales is normally a responsibility of
the system administrator at your site (or the person who installed the
GNU C library).  Some systems may allow users to create locales, but
we don't discuss that here.
<P>
If your program needs to use something other than the <SAMP>`C'</SAMP> locale,
it will be more portable if you use the whatever locale the user
specifies with the environment, rather than trying to specify some
non-standard locale explicitly by name.  Remember, different machines
might have different sets of locales installed.
<P>
<H2><A NAME="SEC82" HREF="library_toc.html#SEC82">Numeric Formatting</A></H2>
<P>
When you want to format a number or a currency amount using the
conventions of the current locale, you can use the function
<CODE>localeconv</CODE> to get the data on how to do it.  The function
<CODE>localeconv</CODE> is declared in the header file <TT>`locale.h'</TT>.
<A NAME="IDX373"></A>
<A NAME="IDX374"></A>
<A NAME="IDX372"></A>
<P>
<A NAME="IDX375"></A>
<U>Function:</U> struct lconv * <B>localeconv</B> <I>(void)</I><P>
The <CODE>localeconv</CODE> function returns a pointer to a structure whose
components contain information about how numeric and monetary values
should be formatted in the current locale.
<P>
You shouldn't modify the structure or its contents.  The structure might
be overwritten by subsequent calls to <CODE>localeconv</CODE>, or by calls to
<CODE>setlocale</CODE>, but no other function in the library overwrites this
value.
<P>
<A NAME="IDX376"></A>
<U>Data Type:</U> <B>struct lconv</B><P>
This is the data type of the value returned by <CODE>localeconv</CODE>.
<P>
If a member of the structure <CODE>struct lconv</CODE> has type <CODE>char</CODE>,
and the value is <CODE>CHAR_MAX</CODE>, it means that the current locale has
no value for that parameter.
<P>
<H3><A NAME="SEC83" HREF="library_toc.html#SEC83">Generic Numeric Formatting Parameters</A></H3>
<P>
These are the standard members of <CODE>struct lconv</CODE>; there may be
others.
<P>
<DL COMPACT>
<DT><CODE>char *decimal_point</CODE>
<DD><DT><CODE>char *mon_decimal_point</CODE>
<DD>These are the decimal-point separators used in formatting non-monetary
and monetary quantities, respectively.  In the <SAMP>`C'</SAMP> locale, the
value of <CODE>decimal_point</CODE> is <CODE>"."</CODE>, and the value of
<CODE>mon_decimal_point</CODE> is <CODE>""</CODE>.
<A NAME="IDX377"></A>
<P>
<DT><CODE>char *thousands_sep</CODE>
<DD><DT><CODE>char *mon_thousands_sep</CODE>
<DD>These are the separators used to delimit groups of digits to the left of
the decimal point in formatting non-monetary and monetary quantities,
respectively.  In the <SAMP>`C'</SAMP> locale, both members have a value of
<CODE>""</CODE> (the empty string).
<P>
<DT><CODE>char *grouping</CODE>
<DD><DT><CODE>char *mon_grouping</CODE>
<DD>These are strings that specify how to group the digits to the left of
the decimal point.  <CODE>grouping</CODE> applies to non-monetary quantities
and <CODE>mon_grouping</CODE> applies to monetary quantities.  Use either
<CODE>thousands_sep</CODE> or <CODE>mon_thousands_sep</CODE> to separate the digit
groups.
<A NAME="IDX378"></A>
<P>
Each string is made up of decimal numbers separated by semicolons.
Successive numbers (from left to right) give the sizes of successive
groups (from right to left, starting at the decimal point).  The last
number in the string is used over and over for all the remaining groups.
<P>
If the last integer is <CODE>-1</CODE>, it means that there is no more
grouping--or, put another way, any remaining digits form one large
group without separators.
<P>
For example, if <CODE>grouping</CODE> is <CODE>"4;3;2"</CODE>, the number
<CODE>123456787654321</CODE> should be grouped into <SAMP>`12'</SAMP>, <SAMP>`34'</SAMP>,
<SAMP>`56'</SAMP>, <SAMP>`78'</SAMP>, <SAMP>`765'</SAMP>, <SAMP>`4321'</SAMP>.  This uses a group of 4
digits at the end, preceded by a group of 3 digits, preceded by groups
of 2 digits (as many as needed).  With a separator of <SAMP>`,'</SAMP>, the
number would be printed as <SAMP>`12,34,56,78,765,4321'</SAMP>.
<P>
A value of <CODE>"3"</CODE> indicates repeated groups of three digits, as
normally used in the U.S.
<P>
In the standard <SAMP>`C'</SAMP> locale, both <CODE>grouping</CODE> and
<CODE>mon_grouping</CODE> have a value of <CODE>""</CODE>.  This value specifies no
grouping at all.
<P>
<DT><CODE>char int_frac_digits</CODE>
<DD><DT><CODE>char frac_digits</CODE>
<DD>These are small integers indicating how many fractional digits (to the
right of the decimal point) should be displayed in a monetary value in
international and local formats, respectively.  (Most often, both
members have the same value.)
<P>
In the standard <SAMP>`C'</SAMP> locale, both of these members have the value
<CODE>CHAR_MAX</CODE>, meaning "unspecified".  The ANSI standard doesn't say
what to do when you find this the value; we recommend printing no
fractional digits.  (This locale also specifies the empty string for
<CODE>mon_decimal_point</CODE>, so printing any fractional digits would be
confusing!)
</DL>
<P>
<A NAME="IDX379"></A>
<H3><A NAME="SEC84" HREF="library_toc.html#SEC84">Printing the Currency Symbol</A></H3>
<P>
These members of the <CODE>struct lconv</CODE> structure specify how to print
the symbol to identify a monetary value--the international analog of
<SAMP>`$'</SAMP> for US dollars.
<P>
Each country has two standard currency symbols.  The <DFN>local currency
symbol</DFN> is used commonly within the country, while the
<DFN>international currency symbol</DFN> is used internationally to refer to
that country's currency when it is necessary to indicate the country
unambiguously.
<P>
For example, many countries use the dollar as their monetary unit, and
when dealing with international currencies it's important to specify
that one is dealing with (say) Canadian dollars instead of U.S. dollars
or Australian dollars.  But when the context is known to be Canada,
there is no need to make this explicit--dollar amounts are implicitly
assumed to be in Canadian dollars.
<P>
<DL COMPACT>
<DT><CODE>char *currency_symbol</CODE>
<DD>The local currency symbol for the selected locale.
<P>
In the standard <SAMP>`C'</SAMP> locale, this member has a value of <CODE>""</CODE>
(the empty string), meaning "unspecified".  The ANSI standard doesn't
say what to do when you find this value; we recommend you simply print
the empty string as you would print any other string found in the
appropriate member.
<P>
<DT><CODE>char *int_curr_symbol</CODE>
<DD>The international currency symbol for the selected locale.
<P>
The value of <CODE>int_curr_symbol</CODE> should normally consist of a
three-letter abbreviation determined by the international standard
<CITE>ISO 4217 Codes for the Representation of Currency and Funds</CITE>,
followed by a one-character separator (often a space).
<P>
In the standard <SAMP>`C'</SAMP> locale, this member has a value of <CODE>""</CODE>
(the empty string), meaning "unspecified".  We recommend you simply
print the empty string as you would print any other string found in the
appropriate member.
<P>
<DT><CODE>char p_cs_precedes</CODE>
<DD><DT><CODE>char n_cs_precedes</CODE>
<DD>These members are <CODE>1</CODE> if the <CODE>currency_symbol</CODE> string should
precede the value of a monetary amount, or <CODE>0</CODE> if the string should
follow the value.  The <CODE>p_cs_precedes</CODE> member applies to positive
amounts (or zero), and the <CODE>n_cs_precedes</CODE> member applies to
negative amounts.
<P>
In the standard <SAMP>`C'</SAMP> locale, both of these members have a value of
<CODE>CHAR_MAX</CODE>, meaning "unspecified".  The ANSI standard doesn't say
what to do when you find this value, but we recommend printing the
currency symbol before the amount.  That's right for most countries.
In other words, treat all nonzero values alike in these members.
<P>
The POSIX standard says that these two members apply to the
<CODE>int_curr_symbol</CODE> as well as the <CODE>currency_symbol</CODE>.  The ANSI
C standard seems to imply that they should apply only to the
<CODE>currency_symbol</CODE>---so the <CODE>int_curr_symbol</CODE> should always
preceed the amount.
<P>
We can only guess which of these (if either) matches the usual
conventions for printing international currency symbols.  Our guess is
that they should always preceed the amount.  If we find out a reliable
answer, we will put it here.
<P>
<DT><CODE>char p_sep_by_space</CODE>
<DD><DT><CODE>char n_sep_by_space</CODE>
<DD>These members are <CODE>1</CODE> if a space should appear between the
<CODE>currency_symbol</CODE> string and the amount, or <CODE>0</CODE> if no space
should appear.  The <CODE>p_sep_by_space</CODE> member applies to positive
amounts (or zero), and the <CODE>n_sep_by_space</CODE> member applies to
negative amounts.
<P>
In the standard <SAMP>`C'</SAMP> locale, both of these members have a value of
<CODE>CHAR_MAX</CODE>, meaning "unspecified".  The ANSI standard doesn't say
what you should do when you find this value; we suggest you treat it as
one (print a space).  In other words, treat all nonzero values alike in
these members.
<P>
These members apply only to <CODE>currency_symbol</CODE>.  When you use
<CODE>int_curr_symbol</CODE>, you never print an additional space, because
<CODE>int_curr_symbol</CODE> itself contains the appropriate separator.
<P>
The POSIX standard says that these two members apply to the
<CODE>int_curr_symbol</CODE> as well as the <CODE>currency_symbol</CODE>.  But an
example in the ANSI C standard clearly implies that they should apply
only to the <CODE>currency_symbol</CODE>---that the <CODE>int_curr_symbol</CODE>
contains any appropriate separator, so you should never print an
additional space.
<P>
Based on what we know now, we recommend you ignore these members when
printing international currency symbols, and print no extra space.
</DL>
<P>
<H3><A NAME="SEC85" HREF="library_toc.html#SEC85">Printing the Sign of an Amount of Money</A></H3>
<P>
These members of the <CODE>struct lconv</CODE> structure specify how to print
the sign (if any) in a monetary value.
<P>
<DL COMPACT>
<DT><CODE>char *positive_sign</CODE>
<DD><DT><CODE>char *negative_sign</CODE>
<DD>These are strings used to indicate positive (or zero) and negative
(respectively) monetary quantities.
<P>
In the standard <SAMP>`C'</SAMP> locale, both of these members have a value of
<CODE>""</CODE> (the empty string), meaning "unspecified".
<P>
The ANSI standard doesn't say what to do when you find this value; we
recommend printing <CODE>positive_sign</CODE> as you find it, even if it is
empty.  For a negative value, print <CODE>negative_sign</CODE> as you find it
unless both it and <CODE>positive_sign</CODE> are empty, in which case print
<SAMP>`-'</SAMP> instead.  (Failing to indicate the sign at all seems rather
unreasonable.)
<P>
<DT><CODE>char p_sign_posn</CODE>
<DD><DT><CODE>char n_sign_posn</CODE>
<DD>These members have values that are small integers indicating how to
position the sign for nonnegative and negative monetary quantities,
respectively.  (The string used by the sign is what was specified with
<CODE>positive_sign</CODE> or <CODE>negative_sign</CODE>.)  The possible values are
as follows:
<P>
<DL COMPACT>
<DT><CODE>0</CODE>
<DD>The currency symbol and quantity should be surrounded by parentheses.
<P>
<DT><CODE>1</CODE>
<DD>Print the sign string before the quantity and currency symbol.
<P>
<DT><CODE>2</CODE>
<DD>Print the sign string after the quantity and currency symbol.
<P>
<DT><CODE>3</CODE>
<DD>Print the sign string right before the currency symbol.
<P>
<DT><CODE>4</CODE>
<DD>Print the sign string right after the currency symbol.
<P>
<DT><CODE>CHAR_MAX</CODE>
<DD>"Unspecified".  Both members have this value in the standard
<SAMP>`C'</SAMP> locale.
</DL>
<P>
The ANSI standard doesn't say what you should do when the value is
<CODE>CHAR_MAX</CODE>.  We recommend you print the sign after the currency
symbol.
</DL>
<P>
It is not clear whether you should let these members apply to the
international currency format or not.  POSIX says you should, but
intuition plus the examples in the ANSI C standard suggest you should
not.  We hope that someone who knows well the conventions for formatting
monetary quantities will tell us what we should recommend.
<P>
<H1><A NAME="SEC86" HREF="library_toc.html#SEC86">Searching and Sorting</A></H1>
<P>
This chapter describes functions for searching and sorting arrays of
arbitrary objects.  You pass the appropriate comparison function to be
applied as an argument, along with the size of the objects in the array
and the total number of elements.
<P>
<A NAME="IDX380"></A>
<H2><A NAME="SEC87" HREF="library_toc.html#SEC87">Defining the Comparison Function</A></H2>
<P>
In order to use the sorted array library functions, you have to describe
how to compare the elements of the array.
<P>
To do this, you supply a comparison function to compare two elements of
the array.  The library will call this function, passing as arguments
pointers to two array elements to be compared.  Your comparison function
should return a value the way <CODE>strcmp</CODE> (see section <A HREF="library.html#SEC62">String/Array Comparison</A>) does: negative if the first argument is "less" than the
second, zero if they are "equal", and positive if the first argument
is "greater".
<P>
Here is an example of a comparison function which works with an array of
numbers of type <CODE>double</CODE>:
<P>
<PRE>
int
compare_doubles (const double *a, const double *b)
{
  double temp = *a - *b;
  if (temp &#62; 0)
    return 1;
  else if (temp &#60; 0)
    return -1;
  else
    return 0;
}
</PRE>
<P>
The header file <TT>`stdlib.h'</TT> defines a name for the data type of
comparison functions.  This is a GNU extension and thus defined only if
you request the GNU extensions.
<A NAME="IDX381"></A>
<P>
<PRE>
int comparison_fn_t (const void *, const void *);
</PRE>
<P>
<A NAME="IDX382"></A>
<A NAME="IDX383"></A>
<A NAME="IDX384"></A>
<H2><A NAME="SEC88" HREF="library_toc.html#SEC88">Array Search Function</A></H2>
<P>
To search a sorted array for an element matching the key, use the
<CODE>bsearch</CODE> function.  The prototype for this function is in
the header file <TT>`stdlib.h'</TT>.
<A NAME="IDX385"></A>
<P>
<A NAME="IDX386"></A>
<U>Function:</U> void * <B>bsearch</B> <I>(const void *<VAR>key</VAR>, const void *<VAR>array</VAR>, size_t <VAR>count</VAR>, size_t <VAR>size</VAR>, comparison_fn_t <VAR>compare</VAR>)</I><P>
The <CODE>bsearch</CODE> function searches the sorted array <VAR>array</VAR> for an object
that is equivalent to <VAR>key</VAR>.  The array contains <VAR>count</VAR> elements,
each of which is of size <VAR>size</VAR>.
<P>
The <VAR>compare</VAR> function is used to perform the comparison.  This
function is called with two pointer arguments and should return an
integer less than, equal to, or greater than zero corresponding to
whether its first argument is considered less than, equal to, or greater
than its second argument.  The elements of the <VAR>array</VAR> must already
be sorted in ascending order according to this comparison function.
<P>
The return value is a pointer to the matching array element, or a null
pointer if no match is found.  If the array contains more than one element
that matches, the one that is returned is unspecified.
<P>
This function derives its name from the fact that it is implemented
using the binary search.
<P>
<A NAME="IDX387"></A>
<A NAME="IDX388"></A>
<A NAME="IDX389"></A>
<H2><A NAME="SEC89" HREF="library_toc.html#SEC89">Array Sort Function</A></H2>
<P>
To sort an array using an arbitrary comparison function, use the
<CODE>qsort</CODE> function.  The prototype for this function is in
<TT>`stdlib.h'</TT>.
<A NAME="IDX390"></A>
<P>
<A NAME="IDX391"></A>
<U>Function:</U> void <B>qsort</B> <I>(void *<VAR>array</VAR>, size_t <VAR>count</VAR>, size_t <VAR>size</VAR>, comparison_fn_t <VAR>compare</VAR>)</I><P>
The <VAR>qsort</VAR> function sorts the array <VAR>array</VAR>.  The array contains
<VAR>count</VAR> elements, each of which is of size <VAR>size</VAR>.
<P>
The <VAR>compare</VAR> function is used to perform the comparison on the
array elements.  This function is called with two pointer arguments and
should return an integer less than, equal to, or greater than zero
corresponding to whether its first argument is considered less than,
equal to, or greater than its second argument.
<A NAME="IDX392"></A>
<P>
<STRONG>Warning:</STRONG> If two objects compare as equal, their order after
sorting is unpredictable.  That is to say, the sorting is not stable.
This can make a difference when the comparison considers only part of
the elements.  Two elements with the same sort key may differ in other
respects.
<P>
If you want the effect of a stable sort, you can get this result by
writing the comparison function so that, lacking other reason
distinguish between two elements, it compares them by their addresses.
<P>
Here is a simple example of sorting an array of doubles in numerical
order, using the comparison function defined above (see section <A HREF="library.html#SEC87">Defining the Comparison Function</A>):
<P>
<PRE>
{
  double *array;
  int size;
  ...
  qsort (array, size, sizeof (double), compare_doubles);
}
</PRE>
<P>
The <CODE>qsort</CODE> function derives its name from the fact that it was
originally implemented using the algorithm "quick sort".
<P>
<H2><A NAME="SEC90" HREF="library_toc.html#SEC90">Searching and Sorting Example</A></H2>
<P>
Here is an example showing the use of <CODE>qsort</CODE> and <CODE>bsearch</CODE>
with an array of structures.  The objects in the array are sorted
by comparing their <CODE>name</CODE> fields with the <CODE>strcmp</CODE> function.
Then, we can look up individual objects based on their names.
<P>
<PRE>
#include &#60;stdlib.h&#62;
#include &#60;stdio.h&#62;
#include &#60;string.h&#62;

/* Define an array of critters to sort.  */

struct critter
{
  char *name;
  char *species;
};

struct critter muppets[]=
{
  {"Kermit", "frog"},
  {"Piggy", "pig"},
  {"Gonzo", "whatever"},
  {"Fozzie", "bear"},
  {"Sam", "eagle"},
  {"Robin", "frog"},
  {"Animal", "animal"},
  {"Camilla", "chicken"},
  {"Sweetums", "monster"},
  {"Dr. Strangepork", "pig"},
  {"Link Hogthrob", "pig"},
  {"Zoot", "human"},
  {"Dr. Bunsen Honeydew", "human"},
  {"Beaker", "human"},
  {"Swedish Chef", "human"}};

int count = sizeof (muppets) / sizeof (struct critter);



/* This is the comparison function used for sorting and searching.  */

int 
critter_cmp (const struct critter *c1, const struct critter *c2)
{
  return strcmp (c1-&#62;name, c2-&#62;name);
}


/* Print information about a critter.  */

void 
print_critter (const struct critter *c)
{
  printf ("%s, the %s\n", c-&#62;name, c-&#62;species);
}


/* Do the lookup into the sorted array.  */

void 
find_critter (char *name)
{
  struct critter target, *result;
  target.name = name;
  result = bsearch (&#38;target, muppets, count, sizeof (struct critter),
		    critter_cmp);
  if (result)
    print_critter (result);
  else
    printf ("Couldn't find %s.\n", name);
}

/* Main program.  */

int
main (void)
{
  int i;

  for (i = 0; i &#60; count; i++)
    print_critter (&#38;muppets[i]);
  printf ("\n");

  qsort (muppets, count, sizeof (struct critter), critter_cmp);

  for (i = 0; i &#60; count; i++)
    print_critter (&#38;muppets[i]);
  printf ("\n");

  find_critter ("Kermit");
  find_critter ("Gonzo");
  find_critter ("Janice");

  return 0;
}
</PRE>
<A NAME="IDX393"></A>
<P>
The output from this program looks like:
<P>
<PRE>
Animal, the animal
Beaker, the human
Camilla, the chicken
Dr. Bunsen Honeydew, the human
Dr. Strangepork, the pig
Fozzie, the bear
Gonzo, the whatever
Kermit, the frog
Link Hogthrob, the pig
Piggy, the pig
Robin, the frog
Sam, the eagle
Swedish Chef, the human
Sweetums, the monster
Zoot, the human


Kermit, the frog
Gonzo, the whatever
Couldn't find Janice.
</PRE>
<P>
<H1><A NAME="SEC91" HREF="library_toc.html#SEC91">Pattern Matching</A></H1>
<P>
The GNU C Library provides pattern matching facilities for two kinds
of patterns: regular expressions and file-name wildcards.
<P>
<H2><A NAME="SEC92" HREF="library_toc.html#SEC92">Wildcard Matching</A></H2>
<A NAME="IDX394"></A>
<P>
This section describes how to match a wildcard pattern against a
particular string.  The result is a yes or no answer: does the
string fit the pattern or not.  The symbols described here are all
declared in <TT>`fnmatch.h'</TT>.
<P>
<A NAME="IDX395"></A>
<U>Function:</U> int <B>fnmatch</B> <I>(const char *<VAR>pattern</VAR>, const char *<VAR>string</VAR>, int <VAR>flags</VAR>)</I><P>
This function tests whether the string <VAR>string</VAR> matches the pattern
<VAR>pattern</VAR>.  It returns <CODE>0</CODE> if they do match; otherwise, it
returns the nonzero value <CODE>FNM_NOMATCH</CODE>.  The arguments
<VAR>pattern</VAR> and <VAR>string</VAR> are both strings.
<P>
The argument <VAR>flags</VAR> is a combination of flag bits that alter the
details of matching.  See below for a list of the defined flags.
<P>
In the GNU C Library, <CODE>fnmatch</CODE> cannot experience an "error"---it
always returns an answer for whether the match succeeds.  However, other
implementations of <CODE>fnmatch</CODE> might sometimes report "errors".
They would do so by returning nonzero values that are not equal to
<CODE>FNM_NOMATCH</CODE>.
<P>
These are the available flags for the <VAR>flags</VAR> argument:
<P>
<DL COMPACT>
<DT><CODE>FNM_FILE_NAME</CODE>
<DD>Treat the <SAMP>`/'</SAMP> character specially, for matching file names.  If
this flag is set, wildcard constructs in <VAR>pattern</VAR> cannot match
<SAMP>`/'</SAMP> in <VAR>string</VAR>.  Thus, the only way to match <SAMP>`/'</SAMP> is with
an explicit <SAMP>`/'</SAMP> in <VAR>pattern</VAR>.
<P>
<DT><CODE>FNM_PATHNAME</CODE>
<DD>This is an alias for <CODE>FNM_FILE_NAME</CODE>; it comes from POSIX.2.  We
don't recommend this name because we don't use the term "pathname" for
file names.
<P>
<DT><CODE>FNM_PERIOD</CODE>
<DD>Treat the <SAMP>`.'</SAMP> character specially if it appears at the beginning of
<VAR>string</VAR>.  If this flag is set, wildcard constructs in <VAR>pattern</VAR>
cannot match <SAMP>`.'</SAMP> as the first character of <VAR>string</VAR>.
<P>
If you set both <CODE>FNM_PERIOD</CODE> and <CODE>FNM_FILE_NAME</CODE>, then the
special treatment applies to <SAMP>`.'</SAMP> following <SAMP>`/'</SAMP> as well as
to <SAMP>`.'</SAMP> at the beginning of <VAR>string</VAR>.
<P>
<DT><CODE>FNM_NOESCAPE</CODE>
<DD>Don't treat the <SAMP>`\'</SAMP> character specially in patterns.  Normally,
<SAMP>`\'</SAMP> quotes the following character, turning off its special meaning
(if any) so that it matches only itself.  When quoting is enabled, the
pattern <SAMP>`\?'</SAMP> matches only the string <SAMP>`?'</SAMP>, because the question
mark in the pattern acts like an ordinary character.
<P>
If you use <CODE>FNM_NOESCAPE</CODE>, then <SAMP>`\'</SAMP> is an ordinary character.
<P>
<DT><CODE>FNM_LEADING_DIR</CODE>
<DD>Ignore a trailing sequence of characters starting with a <SAMP>`/'</SAMP> in
<VAR>string</VAR>; that is to say, test whether <VAR>string</VAR> starts with a
directory name that <VAR>pattern</VAR> matches.
<P>
If this flag is set, either <SAMP>`foo*'</SAMP> or <SAMP>`foobar'</SAMP> as a pattern
would match the string <SAMP>`foobar/frobozz'</SAMP>.
<P>
<DT><CODE>FNM_CASEFOLD</CODE>
<DD>Ignore case in comparing <VAR>string</VAR> to <VAR>pattern</VAR>.
</DL>
<P>
<H2><A NAME="SEC93" HREF="library_toc.html#SEC93">Globbing</A></H2>
<A NAME="IDX396"></A>
<P>
The archetypal use of wildcards is for matching against the files in a
directory, and making a list of all the matches.  This is called
<DFN>globbing</DFN>.
<P>
You could do this using <CODE>fnmatch</CODE>, by reading the directory entries
one by one and testing each one with <CODE>fnmatch</CODE>.  But that would be
slow (and complex, since you would have to handle subdirectories by
hand).
<P>
The library provides a function <CODE>glob</CODE> to make this particular use
of wildcards convenient.  <CODE>glob</CODE> and the other symbols in this
section are declared in <TT>`glob.h'</TT>.
<P>
<H3><A NAME="SEC94" HREF="library_toc.html#SEC94">Calling <CODE>glob</CODE></A></H3>
<P>
The result of globbing is a vector of file names (strings).  To return
this vector, <CODE>glob</CODE> uses a special data type, <CODE>glob_t</CODE>, which
is a structure.  You pass <CODE>glob</CODE> the address of the structure, and
it fills in the structure's fields to tell you about the results.
<P>
<A NAME="IDX397"></A>
<U>Data Type:</U> <B>glob_t</B><P>
This data type holds a pointer to a word vector.  More precisely, it
records both the address of the word vector and its size.
<P>
<DL COMPACT>
<DT><CODE>gl_pathc</CODE>
<DD>The number of elements in the vector.
<P>
<DT><CODE>gl_pathv</CODE>
<DD>The address of the vector.  This field has type <CODE>char **</CODE>.
<P>
<DT><CODE>gl_offs</CODE>
<DD>The offset of the first real element of the vector, from its nominal
address in the <CODE>gl_pathv</CODE> field.  Unlike the other fields, this
is always an input to <CODE>glob</CODE>, rather than an output from it.
<P>
If you use a nonzero offset, then that many elements at the beginning of
the vector are left empty.  (The <CODE>glob</CODE> function fills them with
null pointers.)
<P>
The <CODE>gl_offs</CODE> field is meaningful only if you use the
<CODE>GLOB_DOOFFS</CODE> 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.
</DL>
<P>
<A NAME="IDX398"></A>
<U>Function:</U> int <B>glob</B> <I>(const char *<VAR>pattern</VAR>, int <VAR>flags</VAR>, int (*<VAR>errfunc</VAR>) (const char *<VAR>filename</VAR>, int <VAR>error-code</VAR>), glob_t *<VAR>vector_ptr</VAR>)</I><P>
The function <CODE>glob</CODE> does globbing using the pattern <VAR>pattern</VAR>
in the current directory.  It puts the result in a newly allocated
vector, and stores the size and address of this vector into
<CODE>*<VAR>vector-ptr</VAR></CODE>.  The argument <VAR>flags</VAR> is a combination of
bit flags; see section <A HREF="library.html#SEC95">Flags for Globbing</A>, for details of the flags.
<P>
The result of globbing is a sequence of file names.  The function
<CODE>glob</CODE> allocates a string for each resulting word, then
allocates a vector of type <CODE>char **</CODE> to store the addresses of
these strings.  The last element of the vector is a null pointer.
This vector is called the <DFN>word vector</DFN>.
<P>
To return this vector, <CODE>glob</CODE> stores both its address and its
length (number of elements, not counting the terminating null pointer)
into <CODE>*<VAR>vector-ptr</VAR></CODE>.
<P>
Normally, <CODE>glob</CODE> sorts the file names alphabetically before 
returning them.  You can turn this off with the flag <CODE>GLOB_NOSORT</CODE>
if you want to get the information as fast as possible.  Usually it's
a good idea to let <CODE>glob</CODE> sort them--if you process the files in
alphabetical order, the users will have a feel for the rate of progress
that your application is making.
<P>
If <CODE>glob</CODE> succeeds, it returns 0.  Otherwise, it returns one
of these error codes:
<P>
<DL COMPACT>
<DT><CODE>GLOB_ABORTED</CODE>
<DD>There was an error opening a directory, and you used the flag
<CODE>GLOB_ERR</CODE> or your specified <VAR>errfunc</VAR> returned a nonzero
value.
<P>
<DT><CODE>GLOB_NOMATCH</CODE>
<DD>The pattern didn't match any existing files.  If you use the
<CODE>GLOB_NOCHECK</CODE> flag, then you never get this error code, because
that flag tells <CODE>glob</CODE> to <EM>pretend</EM> that the pattern matched
at least one file.
<P>
<DT><CODE>GLOB_NOSPACE</CODE>
<DD>It was impossible to allocate memory to hold the result.
</DL>
<P>
In the event of an error, <CODE>glob</CODE> stores information in
<CODE>*<VAR>vector-ptr</VAR></CODE> about all the matches it has found so far.
<P>
<H3><A NAME="SEC95" HREF="library_toc.html#SEC95">Flags for Globbing</A></H3>
<P>
This section describes the flags that you can specify in the 
<VAR>flags</VAR> argument to <CODE>glob</CODE>.  Choose the flags you want,
and combine them with the C operator <CODE>|</CODE>.
<P>
<DL COMPACT>
<DT><CODE>GLOB_APPEND</CODE>
<DD>Append the words from this expansion to the vector of words produced by
previous calls to <CODE>glob</CODE>.  This way you can effectively expand
several words as if they were concatenated with spaces between them.
<P>
In order for appending to work, you must not modify the contents of the
word vector structure between calls to <CODE>glob</CODE>.  And, if you set
<CODE>GLOB_DOOFFS</CODE> in the first call to <CODE>glob</CODE>, you must also
set it when you append to the results.
<P>
<DT><CODE>GLOB_DOOFFS</CODE>
<DD>Leave blank slots at the beginning of the vector of words.
The <CODE>gl_offs</CODE> field says how many slots to leave.
The blank slots contain null pointers.
<P>
<DT><CODE>GLOB_ERR</CODE>
<DD>Give up right away and report an error if there is any difficulty
reading the directories that must be read in order to expand <VAR>pattern</VAR>
fully.  Such difficulties might include a directory in which you don't
have the requisite access.  Normally, <CODE>glob</CODE> tries its best to keep
on going despite any errors, reading whatever directories it can.
<P>
You can exercise even more control than this by specifying an error-handler
function <VAR>errfunc</VAR> when you call <CODE>glob</CODE>.  If <VAR>errfunc</VAR> is
nonzero, then <CODE>glob</CODE> doesn't give up right away when it can't read
a directory; instead, it calls <VAR>errfunc</VAR> with two arguments, like
this:
<P>
<PRE>
(*<VAR>errfunc</VAR>) (<VAR>filename</VAR>, <VAR>error-code</VAR>)
</PRE>
<P>
The argument <VAR>filename</VAR> is the name of the directory that
<CODE>glob</CODE> couldn't open or couldn't read, and <VAR>error-code</VAR> is the
<CODE>errno</CODE> value that was reported to <CODE>glob</CODE>.
<P>
If the error handler function returns nonzero, then <CODE>glob</CODE> gives up
right away.  Otherwise, it continues.
<P>
<DT><CODE>GLOB_MARK</CODE>
<DD>If the pattern matches the name of a directory, append <SAMP>`/'</SAMP> to the
directory's name when returning it.
<P>
<DT><CODE>GLOB_NOCHECK</CODE>
<DD>If the pattern doesn't match any file names, return the pattern itself
as if it were a file name that had been matched.  (Normally, when the
pattern doesn't match anything, <CODE>glob</CODE> returns that there were no
matches.)
<P>
<DT><CODE>GLOB_NOSORT</CODE>
<DD>Don't sort the file names; return them in no particular order.
(In practice, the order will depend on the order of the entries in
the directory.)  The only reason <EM>not</EM> to sort is to save time.
<P>
<DT><CODE>GLOB_NOESCAPE</CODE>
<DD>Don't treat the <SAMP>`\'</SAMP> character specially in patterns.  Normally,
<SAMP>`\'</SAMP> quotes the following character, turning off its special meaning
(if any) so that it matches only itself.  When quoting is enabled, the
pattern <SAMP>`\?'</SAMP> matches only the string <SAMP>`?'</SAMP>, because the question
mark in the pattern acts like an ordinary character.
<P>
If you use <CODE>GLOB_NOESCAPE</CODE>, then <SAMP>`\'</SAMP> is an ordinary character.
<P>
<CODE>glob</CODE> does its work by calling the function <CODE>fnmatch</CODE>
repeatedly.  It handles the flag <CODE>GLOB_NOESCAPE</CODE> by turning on the
<CODE>FNM_NOESCAPE</CODE> flag in calls to <CODE>fnmatch</CODE>.
</DL>
<P>
<H2><A NAME="SEC96" HREF="library_toc.html#SEC96">Regular Expression Matching</A></H2>
<P>
The GNU C library supports two interfaces for matching regular
expressions.  One is the standard POSIX.2 interface, and the other is
what the GNU system has had for many years.
<P>
Both interfaces are declared in the header file <TT>`regex.h'</TT>.
If you define <CODE>_GNU_SOURCE</CODE>, then the GNU functions, structures
and constants are declared.  Otherwise, only the POSIX names are
declared.
<P>
<H3><A NAME="SEC97" HREF="library_toc.html#SEC97">POSIX Regular Expression Compilation</A></H3>
<P>
Before you can actually match a regular expression, you must
<DFN>compile</DFN> it.  This is not true compilation--it produces a special
data structure, not machine instructions.  But it is like ordinary
compilation in that its purpose is to enable you to "execute" the
pattern fast.  (See section <A HREF="library.html#SEC99">Matching a Compiled POSIX Regular Expression</A>, for how to use the
compiled regular expression for matching.)
<P>
There is a special data type for compiled regular expressions:
<P>
<A NAME="IDX399"></A>
<U>Data Type:</U> <B>regex_t</B><P>
This type of object holds a compiled regular expression.
It is actually a structure.  It has just one field that your programs
should look at:
<P>
<DL COMPACT>
<DT><CODE>re_nsub</CODE>
<DD>This field holds the number of parenthetical subexpressions in the
regular expression that was compiled.
</DL>
<P>
There are several other fields, but we don't describe them here, because
only the functions in the library should use them.
<P>
After you create a <CODE>regex_t</CODE> object, you can compile a regular
expression into it by calling <CODE>regcomp</CODE>.
<P>
<A NAME="IDX400"></A>
<U>Function:</U> int <B>regcomp</B> <I>(regex_t *<VAR>compiled</VAR>, const char *<VAR>pattern</VAR>, int <VAR>cflags</VAR>)</I><P>
The function <CODE>regcomp</CODE> "compiles" a regular expression into a
data structure that you can use with <CODE>regexec</CODE> to match against a
string.  The compiled regular expression format is designed for
efficient matching.  <CODE>regcomp</CODE> stores it into <CODE>*<VAR>compiled</VAR></CODE>.
<P>
It's up to you to allocate an object of type <CODE>regex_t</CODE> and pass its
address to <CODE>regcomp</CODE>.
<P>
The argument <VAR>cflags</VAR> lets you specify various options that control
the syntax and semantics of regular expressions.  See section <A HREF="library.html#SEC98">Flags for POSIX Regular Expressions</A>.
<P>
If you use the flag <CODE>REG_NOSUB</CODE>, then <CODE>regcomp</CODE> omits from
the compiled regular expression the information necessary to record
how subexpressions actually match.  In this case, you might as well
pass <CODE>0</CODE> for the <VAR>matchptr</VAR> and <VAR>nmatch</VAR> arguments when
you call <CODE>regexec</CODE>.
<P>
If you don't use <CODE>REG_NOSUB</CODE>, then the compiled regular expression
does have the capacity to record how subexpressions match.  Also,
<CODE>regcomp</CODE> tells you how many subexpressions <VAR>pattern</VAR> has, by
storing the number in <CODE><VAR>compiled</VAR>-&#62;re_nsub</CODE>.  You can use that
value to decide how long an array to allocate to hold information about
subexpression matches.
<P>
<CODE>regcomp</CODE> returns <CODE>0</CODE> if it succeeds in compiling the regular
expression; otherwise, it returns a nonzero error code (see the table
below).  You can use <CODE>regerror</CODE> to produce an error message string
describing the reason for a nonzero value; see section <A HREF="library.html#SEC102">POSIX Regexp Matching Cleanup</A>.
<P>
Here are the possible nonzero values that <CODE>regcomp</CODE> can return:
<P>
<DL COMPACT>
<DT><CODE>REG_BADBR</CODE>
<DD>There was an invalid <SAMP>`\{...\}'</SAMP> construct in the regular
expression.  A valid <SAMP>`\{...\}'</SAMP> construct must contain either
a single number, or two numbers in increasing order separated by a
comma.
<P>
<DT><CODE>REG_BADPAT</CODE>
<DD>There was a syntax error in the regular expression.
<P>
<DT><CODE>REG_BADRPT</CODE>
<DD>A repetition operator such as <SAMP>`?'</SAMP> or <SAMP>`*'</SAMP> appeared in a bad
position (with no preceding subexpression to act on).
<P>
<DT><CODE>REG_ECOLLATE</CODE>
<DD>The regular expression referred to an invalid collating element (one not
defined in the current locale for string collation).  See section <A HREF="library.html#SEC79">Categories of Activities that Locales Affect</A>.
<P>
<DT><CODE>REG_ECTYPE</CODE>
<DD>The regular expression referred to an invalid character class name.
<P>
<DT><CODE>REG_EESCAPE</CODE>
<DD>The regular expression ended with <SAMP>`\'</SAMP>.
<P>
<DT><CODE>REG_ESUBREG</CODE>
<DD>There was an invalid number in the <SAMP>`\<VAR>digit</VAR>'</SAMP> construct.
<P>
<DT><CODE>REG_EBRACK</CODE>
<DD>There were unbalanced square brackets in the regular expression.
<P>
<DT><CODE>REG_EPAREN</CODE>
<DD>An extended regular expression had unbalanced parentheses,
or a basic regular expression had unbalanced <SAMP>`\('</SAMP> and <SAMP>`\)'</SAMP>.
<P>
<DT><CODE>REG_EBRACE</CODE>
<DD>The regular expression had unbalanced <SAMP>`\{'</SAMP> and <SAMP>`\}'</SAMP>.
<P>
<DT><CODE>REG_ERANGE</CODE>
<DD>One of the endpoints in a range expression was invalid.
<P>
<DT><CODE>REG_ESPACE</CODE>
<DD><CODE>regcomp</CODE> or <CODE>regexec</CODE> ran out of memory.
</DL>
<P>
<H3><A NAME="SEC98" HREF="library_toc.html#SEC98">Flags for POSIX Regular Expressions</A></H3>
<P>
These are the bit flags that you can use in the <VAR>cflags</VAR> operand when
compiling a regular expression with <CODE>regcomp</CODE>.
 
<DL COMPACT>
<DT><CODE>REG_EXTENDED</CODE>
<DD>Treat the pattern as an extended regular expression, rather than as a
basic regular expression.
<P>
<DT><CODE>REG_ICASE</CODE>
<DD>Ignore case when matching letters.
<P>
<DT><CODE>REG_NOSUB</CODE>
<DD>Don't bother storing the contents of the <VAR>matches_ptr</VAR> array.
<P>
<DT><CODE>REG_NEWLINE</CODE>
<DD>Treat a newline in <VAR>string</VAR> as dividing <VAR>string</VAR> into multiple
lines, so that <SAMP>`$'</SAMP> can match before the newline and <SAMP>`^'</SAMP> can
match after.  Also, don't permit <SAMP>`.'</SAMP> to match a newline, and don't
permit <SAMP>`[^...]'</SAMP> to match a newline.
<P>
Otherwise, newline acts like any other ordinary character.
</DL>
<P>
<H3><A NAME="SEC99" HREF="library_toc.html#SEC99">Matching a Compiled POSIX Regular Expression</A></H3>
<P>
Once you have compiled a regular expression, as described in section <A HREF="library.html#SEC97">POSIX Regular Expression Compilation</A>, you can match it against strings using
<CODE>regexec</CODE>.  A match anywhere inside the string counts as success,
unless the regular expression contains anchor characters (<SAMP>`^'</SAMP> or
<SAMP>`$'</SAMP>).
<P>
<A NAME="IDX401"></A>
<U>Function:</U> int <B>regexec</B> <I>(regex_t *<VAR>compiled</VAR>, char *<VAR>string</VAR>, size_t <VAR>nmatch</VAR>, regmatch_t <VAR>matchptr</VAR> <TT>[]</TT>, int <VAR>eflags</VAR>)</I><P>
This function tries to match the compiled regular expression
<CODE>*<VAR>compiled</VAR></CODE> against <VAR>string</VAR>.
<P>
<CODE>regexec</CODE> returns <CODE>0</CODE> if the regular expression matches;
otherwise, it returns a nonzero value.  See the table below for
what nonzero values mean.  You can use <CODE>regerror</CODE> to produce an
error message string describing the reason for a nonzero value; 
see section <A HREF="library.html#SEC102">POSIX Regexp Matching Cleanup</A>.
<P>
The argument <VAR>eflags</VAR> is a word of bit flags that enable various
options.
<P>
If you want to get information about what part of <VAR>string</VAR> actually
matched the regular expression or its subexpressions, use the arguments
<VAR>matchptr</VAR> and <VAR>nmatch</VAR>.  Otherwise, pass <CODE>0</CODE> for 
<VAR>nmatch</VAR>, and <CODE>NULL</CODE> for <VAR>matchptr</VAR>.  See section <A HREF="library.html#SEC100">Subexpressions Match Results</A>.
<P>
You must match the regular expression with the same set of current
locales that were in effect when you compiled the regular expression.
<P>
The function <CODE>regexec</CODE> accepts the following flags in the
<VAR>eflags</VAR> argument:
<P>
<DL COMPACT>
<DT><CODE>REG_NOTBOL</CODE>
<DD>Do not regard the beginning of the specified string as the beginning of
a line; more generally, don't make any assumptions about what text might
precede it.
<P>
<DT><CODE>REG_NOTEOL</CODE>
<DD>Do not regard the end of the specified string as the end of a line; more
generally, don't make any assumptions about what text might follow it.
</DL>
<P>
Here are the possible nonzero values that <CODE>regexec</CODE> can return:
<P>
<DL COMPACT>
<DT><CODE>REG_NOMATCH</CODE>
<DD>The pattern didn't match the string.  This isn't really an error.
<P>
<DT><CODE>REG_ESPACE</CODE>
<DD><CODE>regcomp</CODE> or <CODE>regexec</CODE> ran out of memory.
</DL>
<P>
<H3><A NAME="SEC100" HREF="library_toc.html#SEC100">Subexpressions Match Results</A></H3>
<P>
When <CODE>regexec</CODE> matches parenthetical subexpressions of
<VAR>pattern</VAR>, it records which parts of <VAR>string</VAR> they match.  It
returns that information by storing the offsets into an array whose
elements are structures of type <CODE>regmatch_t</CODE>.  The first element of
the array records the part of the string that matched the entire regular
expression.  Each other element of the array records the beginning and
end of the part that matched a single parenthetical subexpression.
<P>
<A NAME="IDX402"></A>
<U>Data Type:</U> <B>regmatch_t</B><P>
This is the data type of the <VAR>matcharray</VAR> array that you pass to
<CODE>regexec</CODE>.  It containes two structure fields, as follows:
<P>
<DL COMPACT>
<DT><CODE>rm_so</CODE>
<DD>The offset in <VAR>string</VAR> of the beginning of a substring.  Add this
value to <VAR>string</VAR> to get the address of that part.
<P>
<DT><CODE>rm_eo</CODE>
<DD>The offset in <VAR>string</VAR> of the end of the substring.
</DL>
<P>
<A NAME="IDX403"></A>
<U>Data Type:</U> <B>regoff_t</B><P>
<CODE>regoff_t</CODE> is an alias for another signed integer type.
The fields of <CODE>regmatch_t</CODE> have type <CODE>regoff_t</CODE>.
<P>
The <CODE>regmatch_t</CODE> elements correspond to subexpressions
positionally; the first element records where the first subexpression
matched, the second element records the second subexpression, and so on.
The order of the subexpressions is the order in which they begin.
<P>
When you call <CODE>regexec</CODE>, you specify how long the <VAR>matchptr</VAR>
array is, with the <VAR>nmatch</VAR> argument.  This tells <CODE>regexec</CODE> how
many elements to store.  If the actual regular expression has more than
<VAR>nmatch</VAR> subexpressions, then you won't get offset information about
the rest of them.  But this doesn't alter whether the pattern matches a
particular string or not.
<P>
If you don't want <CODE>regexec</CODE> to return any information about where
the subexpressions matched, you can either supply <CODE>0</CODE> for
<VAR>nmatch</VAR>, or use the flag <CODE>REG_NOSUB</CODE> when you compile the
pattern with <CODE>regcomp</CODE>.
<P>
<H3><A NAME="SEC101" HREF="library_toc.html#SEC101">Complications in Subexpression Matching</A></H3>
<P>
Sometimes a subexpression matches a substring of no characters.  This
happens when <SAMP>`f\(o*\)'</SAMP> matches the string <SAMP>`fum'</SAMP>.  (It really
matches just the <SAMP>`f'</SAMP>.)  In this case, both of the offsets identify
the point in the string where the null substring was found.  In this
example, the offsets are both <CODE>1</CODE>.
<P>
Sometimes the entire regular expression can match without using some of
its subexpressions at all--for example, when <SAMP>`ba\(na\)*'</SAMP> matches the
string <SAMP>`ba'</SAMP>, the parenthetical subexpression is not used.  When
this happens, <CODE>regexec</CODE> stores <CODE>-1</CODE> in both fields of the
element for that subexpression.
<P>
Sometimes matching the entire regular expression can match a particular
subexpression more than once--for example, when <SAMP>`ba\(na\)*'</SAMP>
matches the string <SAMP>`bananana'</SAMP>, the parenthetical subexpression
matches three times.  When this happens, <CODE>regexec</CODE> usually stores
the offsets of the last part of the string that matched the
subexpression.  In the case of <SAMP>`bananana'</SAMP>, these offsets are
<CODE>6</CODE> and <CODE>8</CODE>.
<P>
But the last match is not always the one that is chosen.  It's more
accurate to say that the last <EM>opportunity</EM> to match is the one
that takes precedence.  What this means is that when one subexpression
appears within another, then the results reported for the inner
subexpression reflect whatever happened on the last match of the outer
subexpression.  For an example, consider <SAMP>`\(ba\(na\)*s \)'</SAMP> matching
the string <SAMP>`bananas bas '</SAMP>.  The last time the inner expression
actually matches is near the end of the first word.  But it is 
<EM>considered</EM> again in the second word, and fails to match there.
<CODE>regexec</CODE> reports nonuse of the "na" subexpression.
<P>
Another place where this rule applies is when <SAMP>`\(ba\(na\)*s
\|nefer\(ti\)* \)*'</SAMP> matches <SAMP>`bananas nefertiti'</SAMP>.  The "na"
subexpression does match in the first word, but it doesn't match in the
second word because the other alternative is used there.  Once again,
the second repetition of the outer subexpression overrides the first,
and within that second repetition, the "na" subexpression is not used.
So <CODE>regexec</CODE> reports nonuse of the "na" subexpression.
<P>
<H3><A NAME="SEC102" HREF="library_toc.html#SEC102">POSIX Regexp Matching Cleanup</A></H3>
<P>
When you are finished using a compiled regular expression, you can
free the storage it uses by calling <CODE>regfree</CODE>.
<P>
<A NAME="IDX404"></A>
<U>Function:</U> void <B>regfree</B> <I>(regex_t *<VAR>compiled</VAR>)</I><P>
Calling <CODE>regfree</CODE> frees all the storage that <CODE>*<VAR>compiled</VAR></CODE>
points to.  This includes various internal fields of the <CODE>regex_t</CODE>
structure that aren't documented in this manual.
<P>
<CODE>regfree</CODE> does not free the object <CODE>*<VAR>compiled</VAR></CODE> itself.
<P>
You should always free the space in a <CODE>regex_t</CODE> structure with
<CODE>regfree</CODE> before using the structure to compile another regular
expression.
<P>
When <CODE>regcomp</CODE> or <CODE>regexec</CODE> reports an error, you can use
the function <CODE>regerror</CODE> to turn it into an error message string.
<P>
<A NAME="IDX405"></A>
<U>Function:</U> size_t <B>regerror</B> <I>(int <VAR>errcode</VAR>, regex_t *<VAR>compiled</VAR>, char *<VAR>buffer</VAR>, size_t <VAR>length</VAR>)</I><P>
This function produces an error message string for the error code
<VAR>errcode</VAR>, and stores the string in <VAR>length</VAR> bytes of memory
starting at <VAR>buffer</VAR>.  For the <VAR>compiled</VAR> argument, supply the
same compiled regular expression structure that <CODE>regcomp</CODE> or
<CODE>regexec</CODE> was working with when it got the error.  Alternatively,
you can supply <CODE>NULL</CODE> for <VAR>compiled</VAR>; you will still get a
meaningful error message, but it might not be as detailed.
<P>
If the error message can't fit in <VAR>length</VAR> bytes (including a
terminating null character), then <CODE>regerror</CODE> truncates it.
The string that <CODE>regerror</CODE> stores is always null-terminated
even if it has been truncated.
<P>
The return value of <CODE>regerror</CODE> is the minimum length needed to
store the entire error message.  If this is less than <VAR>length</VAR>, then
the error message was not truncated, and you can use it.  Otherwise, you
should call <CODE>regerror</CODE> again with a larger buffer.
<P>
<PRE>
char *get_regerror (int errcode, regex_t *compiled)
{
  size_t length = regerror (errcode, compiled, NULL, 0);
  char *buffer = xmalloc (length);
  (void) regerror (errcode, compiled, buffer, length);
  return buffer;
}
</PRE>
<P>
<A NAME="IDX406"></A>
<A NAME="IDX407"></A>
<H2><A NAME="SEC103" HREF="library_toc.html#SEC103">Shell-Style Word Expansion</A></H2>
<P>
<DFN>Word expansion</DFN> means the process of splitting a string into 
<DFN>words</DFN> and substituting for variables, commands, and wildcards
just as the shell does.
<P>
For example, when you write <SAMP>`ls -l foo.c'</SAMP>, this string is split
into three separate words---<SAMP>`ls'</SAMP>, <SAMP>`-l'</SAMP> and <SAMP>`foo.c'</SAMP>.
This is the most basic function of word expansion.
<P>
When you write <SAMP>`ls *.c'</SAMP>, this can become many words, because
the word <SAMP>`*.c'</SAMP> can be replaced with any number of file names.
This is called <DFN>wildcard expansion</DFN>, and it is also a part of
word expansion.
<P>
When you use <SAMP>`echo $PATH'</SAMP> to print your path, you are taking
advantage of <DFN>variable substitution</DFN>, which is also part of word
expansion.
<P>
Ordinary programs can perform word expansion just like the shell by
calling the library function <CODE>wordexp</CODE>.
<P>
<H3><A NAME="SEC104" HREF="library_toc.html#SEC104">The Stages of Word Expansion</A></H3>
<P>
When word expansion is applied to a sequence of words, it performs the
following transformations in the order shown here:
<P>
<OL>
<A NAME="IDX408"></A>
<LI>
<DFN>Tilde expansion</DFN>: Replacement of <SAMP>`~foo'</SAMP> with the name of
the home directory of <SAMP>`foo'</SAMP>.
<P>
<LI>
Next, three different transformations are applied in the same step,
from left to right:
<P>
<UL>
<A NAME="IDX409"></A>
<A NAME="IDX410"></A>
<LI>
<DFN>Variable substitution</DFN>: The substitution of environment variables
for references such as <SAMP>`$foo'</SAMP>.
<P>
<A NAME="IDX411"></A>
<LI>
<DFN>Command substitution</DFN>: Replacement of constructs such as 
<SAMP>``cat foo`'</SAMP> or <SAMP>`$(cat foo)'</SAMP> with the output from the inner
command.
<P>
<A NAME="IDX412"></A>
<LI>
<DFN>Arithmetic expansion</DFN>: Replacement of constructs such as
<SAMP>`$(($x-1))'</SAMP> with the result of the arithmetic computation.
</UL>
<P>
<A NAME="IDX413"></A>
<LI>
<DFN>Field splitting</DFN>: subdivision of the text into <DFN>words</DFN>.
<P>
<A NAME="IDX414"></A>
<LI>
<DFN>Wildcard expansion</DFN>: The replacement of a construct such as <SAMP>`*.c'</SAMP>
with a list of <SAMP>`.c'</SAMP> file names.  Wildcard expansion applies to an
entire word at a time, and replaces that word with 0 or more file names
that are themselves words.
<P>
<A NAME="IDX415"></A>
<A NAME="IDX416"></A>
<LI>
<DFN>Quote removal</DFN>: The deletion of string-quotes, now that they have
done their job by inhibiting the above transformations when appropriate.
</OL>
<P>
For the details of these transformations, and how to write the constructs
that use them, see <CITE>The BASH Manual</CITE> (to appear).
<P>
<H3><A NAME="SEC105" HREF="library_toc.html#SEC105">Calling <CODE>wordexp</CODE></A></H3>
<P>
All the functions, constants and data types for word expansion are
declared in the header file <TT>`wordexp.h'</TT>.
<P>
Word expansion produces a vector of words (strings).  To return this
vector, <CODE>wordexp</CODE> uses a special data type, <CODE>wordexp_t</CODE>, which
is a structure.  You pass <CODE>wordexp</CODE> the address of the structure,
and it fills in the structure's fields to tell you about the results.
<P>
<A NAME="IDX417"></A>
<U>Data Type:</U> <B>wordexp_t</B><P>
This data type holds a pointer to a word vector.  More precisely, it
records both the address of the word vector and its size.
<P>
<DL COMPACT>
<DT><CODE>we_wordc</CODE>
<DD>The number of elements in the vector.
<P>
<DT><CODE>we_wordv</CODE>
<DD>The address of the vector.  This field has type <CODE>char **</CODE>.
<P>
<DT><CODE>we_offs</CODE>
<DD>The offset of the first real element of the vector, from its nominal
address in the <CODE>we_wordv</CODE> field.  Unlike the other fields, this
is always an input to <CODE>wordexp</CODE>, rather than an output from it.
<P>
If you use a nonzero offset, then that many elements at the beginning of
the vector are left empty.  (The <CODE>wordexp</CODE> function fills them with
null pointers.)
<P>
The <CODE>we_offs</CODE> field is meaningful only if you use the
<CODE>WRDE_DOOFFS</CODE> 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.
</DL>
<P>
<A NAME="IDX418"></A>
<U>Function:</U> int <B>wordexp</B> <I>(const char *<VAR>words</VAR>, wordexp_t *<VAR>word-vector-ptr</VAR>, int <VAR>flags</VAR>)</I><P>
Perform word expansion on the string <VAR>words</VAR>, putting the result in
a newly allocated vector, and store the size and address of this vector
into <CODE>*<VAR>word-vector-ptr</VAR></CODE>.  The argument <VAR>flags</VAR> is a
combination of bit flags; see section <A HREF="library.html#SEC106">Flags for Word Expansion</A>, for details of
the flags.
<P>
You shouldn't use any of the characters <SAMP>`|&#38;;&#60;&#62;'</SAMP> in the string
<VAR>words</VAR> unless they are quoted; likewise for newline.  If you use
these characters unquoted, you will get the <CODE>WRDE_BADCHAR</CODE> error
code.  Don't use parentheses or braces unless they are quoted or part of
a word expansion construct.  If you use quotation characters <SAMP>`'"`'</SAMP>,
they should come in pairs that balance.
<P>
The results of word expansion are a sequence of words.  The function
<CODE>wordexp</CODE> allocates a string for each resulting word, then
allocates a vector of type <CODE>char **</CODE> to store the addresses of
these strings.  The last element of the vector is a null pointer.
This vector is called the <DFN>word vector</DFN>.
<P>
To return this vector, <CODE>wordexp</CODE> stores both its address and its
length (number of elements, not counting the terminating null pointer)
into <CODE>*<VAR>word-vector-ptr</VAR></CODE>.
<P>
If <CODE>wordexp</CODE> succeeds, it returns 0.  Otherwise, it returns one
of these error codes:
<P>
<DL COMPACT>
<DT><CODE>WRDE_BADCHAR</CODE>
<DD>The input string <VAR>words</VAR> contains an unquoted invalid character such
as <SAMP>`|'</SAMP>.
<P>
<DT><CODE>WRDE_BADVAL</CODE>
<DD>The input string refers to an undefined shell variable, and you used the flag
<CODE>WRDE_UNDEF</CODE> to forbid such references.
<P>
<DT><CODE>WRDE_CMDSUB</CODE>
<DD>The input string uses command substitution, and you used the flag
<CODE>WRDE_NOCMD</CODE> to forbid command substitution.
<P>
<DT><CODE>WRDE_NOSPACE</CODE>
<DD>It was impossible to allocate memory to hold the result.  In this case,
<CODE>wordexp</CODE> can store part of the results--as much as it could
allocate room for.
<P>
<DT><CODE>WRDE_SYNTAX</CODE>
<DD>There was a syntax error in the input string.  For example, an unmatched
quoting character is a syntax error.
</DL>
<P>
<A NAME="IDX419"></A>
<U>Function:</U> void <B>wordfree</B> <I>(wordexp_t *<VAR>word-vector-ptr</VAR>)</I><P>
Free the storage used for the word-strings and vector that
<CODE>*<VAR>word-vector-ptr</VAR></CODE> points to.  This does not free the
structure <CODE>*<VAR>word-vector-ptr</VAR></CODE> itself--only the other
data it points to.
<P>
<H3><A NAME="SEC106" HREF="library_toc.html#SEC106">Flags for Word Expansion</A></H3>
<P>
This section describes the flags that you can specify in the 
<VAR>flags</VAR> argument to <CODE>wordexp</CODE>.  Choose the flags you want,
and combine them with the C operator <CODE>|</CODE>.
<P>
<DL COMPACT>
<DT><CODE>WRDE_APPEND</CODE>
<DD>Append the words from this expansion to the vector of words produced by
previous calls to <CODE>wordexp</CODE>.  This way you can effectively expand
several words as if they were concatenated with spaces between them.
<P>
In order for appending to work, you must not modify the contents of the
word vector structure between calls to <CODE>wordexp</CODE>.  And, if you set
<CODE>WRDE_DOOFFS</CODE> in the first call to <CODE>wordexp</CODE>, you must also
set it when you append to the results.
<P>
<DT><CODE>WRDE_DOOFFS</CODE>
<DD>Leave blank slots at the beginning of the vector of words.
The <CODE>we_offs</CODE> field says how many slots to leave.
The blank slots contain null pointers.
<P>
<DT><CODE>WRDE_NOCMD</CODE>
<DD>Don't do command substitution; if the input requests command substitution,
report an error.
<P>
<DT><CODE>WRDE_REUSE</CODE>
<DD>Reuse a word vector made by a previous call to <CODE>wordexp</CODE>.
Instead of allocating a new vector of words, this call to <CODE>wordexp</CODE>
will use the vector that already exists (making it larger if necessary).
<P>
<DT><CODE>WRDE_SHOWERR</CODE>
<DD>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, <CODE>wordexp</CODE> gives these
commands a standard error stream that discards all output.
<P>
<DT><CODE>WRDE_UNDEF</CODE>
<DD>If the input refers to a shell variable that is not defined, report an
error.
</DL>
<P>
<H3><A NAME="SEC107" HREF="library_toc.html#SEC107"><CODE>wordexp</CODE> Example</A></H3>
<P>
Here is an example of using <CODE>wordexp</CODE> to expand several strings
and use the results to run a shell command.  It also shows the use of
<CODE>WRDE_APPEND</CODE> to concatenate the expansions and of <CODE>wordfree</CODE>
to free the space allocated by <CODE>wordexp</CODE>.
<P>
<PRE>
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, &#38;result, 0))
    {
    case 0:			/* Successful.  */
      break;
    case WRDE_NOSPACE:
      /* If the error was <CODE>WRDE_NOSPACE</CODE>,
         then perhaps part of the result was allocated.  */
      wordfree (&#38;result);
    default:                    /* Some other error.  */
      return -1;
    }

  /* Expand the strings specified for the arguments.  */
  for (i = 0; args[i]; i++)
    {
      if (wordexp (options, &#38;result, WRDE_APPEND))
        {
          wordfree (&#38;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 &#60; 0)
    /* The fork failed.  Report failure.  */
    status = -1;
  else
    /* This is the parent process.  Wait for the child to complete.  */
    if (waitpid (pid, &#38;status, 0) != pid)
      status = -1;

  wordfree (&#38;result);
  return status;
}
</PRE>
<P>
In practice, since <CODE>wordexp</CODE> is executed by running a subshell, it
would be faster to do this by concatenating the strings with spaces
between them and running that as a shell command using <SAMP>`sh -c'</SAMP>.
<P>
<H1><A NAME="SEC108" HREF="library_toc.html#SEC108">Input/Output Overview</A></H1>
<P>
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!
<P>
This chapter introduces concepts and terminology relating to input
and output.  Other chapters relating to the GNU I/O facilities are:
<P>
<UL>
<LI>
section <A HREF="library.html#SEC117">Input/Output on Streams</A>, which covers the high-level functions
that operate on streams, including formatted input and output.
<P>
<LI>
section <A HREF="library.html#SEC171">Low-Level Input/Output</A>, which covers the basic I/O and control
functions on file descriptors.
<P>
<LI>
section <A HREF="library.html#SEC187">File System Interface</A>, which covers functions for operating on
directories and for manipulating file attributes such as access modes
and ownership.
<P>
<LI>
section <A HREF="library.html#SEC211">Pipes and FIFOs</A>, which includes information on the basic interprocess
communication facilities.
<P>
<LI>
section <A HREF="library.html#SEC216">Sockets</A>, covering a more complicated interprocess communication
facility with support for networking.
<P>
<LI>
section <A HREF="library.html#SEC268">Low-Level Terminal Interface</A>, which covers functions for changing
how input and output to terminal or other serial devices are processed.
</UL>
<P>
<H2><A NAME="SEC109" HREF="library_toc.html#SEC109">Input/Output Concepts</A></H2>
<P>
Before you can read or write the contents of a file, you must establish
a connection or communications channel to the file.  This process is
called <DFN>opening</DFN> the file.  You can open a file for reading, writing,
or both.
<A NAME="IDX420"></A>
<P>
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.
<P>
When you have finished reading to or writing from the file, you can
terminate the connection by <DFN>closing</DFN> the file.  Once you have
closed a stream or file descriptor, you cannot do any more input or
output operations on it.
<P>
<H3><A NAME="SEC110" HREF="library_toc.html#SEC110">Streams and File Descriptors</A></H3>
<P>
When you want to do input or output to a file, you have a choice of two
basic mechanisms for representing the connection between your program
and the file: file descriptors and streams.  File descriptors are
represented as objects of type <CODE>int</CODE>, while streams are represented
as <CODE>FILE *</CODE> objects.
<P>
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 (see section <A HREF="library.html#SEC184">File Status Flags</A>).
<P>
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 (see section <A HREF="library.html#SEC160">Stream Buffering</A>).
<P>
The main advantage of using the stream interface is that the set of
functions for performing actual input and output operations (as opposed
to control operations) on streams is much richer and more powerful than
the corresponding facilities for file descriptors.  The file descriptor
interface provides only simple functions for transferring blocks of
characters, but the stream interface also provides powerful formatted
input and output functions (<CODE>printf</CODE> and <CODE>scanf</CODE>) as well as
functions for character- and line-oriented input and output.
<P>
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.
<P>
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 (see section <A HREF="library.html#SEC145">Formatted Input</A>)
and formatted output functions (see section <A HREF="library.html#SEC128">Formatted Output</A>).
<P>
If you are concerned about portability of your programs to systems other
than GNU, you should also be aware that file descriptors are not as
portable as streams.  You can expect any system running ANSI C to
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.
<P>
<H3><A NAME="SEC111" HREF="library_toc.html#SEC111">File Position</A></H3>
<P>
One of the attributes of an open file is its <DFN>file position</DFN>
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.
<P>
The file position is normally set to the beginning of the file when it
is opened, and each time a character is read or written, the file
position is incremented.  In other words, access to the file is normally
<DFN>sequential</DFN>.
<A NAME="IDX422"></A>
<A NAME="IDX421"></A>
<P>
Ordinary files permit read or write operations at any position within
the file.  Some other kinds of files may also permit this.  Files which
do permit this are sometimes referred to as <DFN>random-access</DFN> files.
You can change the file position using the <CODE>fseek</CODE> function on a
stream (see section <A HREF="library.html#SEC158">File Positioning</A>) or the <CODE>lseek</CODE> function on a file
descriptor (see section <A HREF="library.html#SEC173">Input and Output Primitives</A>).  If you try to change the file
position on a file that doesn't support random access, you get an error.
<A NAME="IDX423"></A>
<P>
Streams and descriptors that are opened for <DFN>append access</DFN> are
treated specially for output: output to such files is <EM>always</EM>
appended sequentially to the <EM>end</EM> of the file, regardless of the
file position.  But, the file position is still used to control where in
the file reading is done.
<A NAME="IDX424"></A>
<P>
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.
<P>
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.
<P>
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.
<P>
<H2><A NAME="SEC112" HREF="library_toc.html#SEC112">File Names</A></H2>
<P>
In order to open a connection to a file, or to perform other operations
such as deleting a file, you need some way to refer to the file.  Nearly
all files have names that are strings--even files which are actually
devices such as tape drives or terminals.  These strings are called
<DFN>file names</DFN>.  You specify the file name to say which file you want
to open or operate on.
<P>
This section describes the conventions for file names and how the
operating system works with them.
<A NAME="IDX425"></A>
<P>
<H3><A NAME="SEC113" HREF="library_toc.html#SEC113">Directories</A></H3>
<P>
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 NAME="IDX426"></A>
<A NAME="IDX427"></A>
<A NAME="IDX428"></A>
<P>
A <DFN>directory</DFN> is a file that contains information to associate other
files with names; these associations are called <DFN>links</DFN> or
<DFN>directory entries</DFN>.  Sometimes, people speak of "files in a
directory", but in reality, a directory only contains pointers to
files, not the files themselves.
<A NAME="IDX429"></A>
<P>
The name of a file contained in a directory entry is called a <DFN>file
name component</DFN>.  In general, a file name consists of a sequence of one
or more such components, separated by the slash character (<SAMP>`/'</SAMP>).  A
file name which is just one component names a file with respect to its
directory.  A file name with multiple components names a directory, and
then a file in that directory, and so on.
<P>
Some other documents, such as the POSIX standard, use the term
<DFN>pathname</DFN> for what we call a file name, and either
<DFN>filename</DFN> or <DFN>pathname component</DFN> 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.
<P>
You can find more detailed information about operations on directories
in section <A HREF="library.html#SEC187">File System Interface</A>.
<P>
<H3><A NAME="SEC114" HREF="library_toc.html#SEC114">File Name Resolution</A></H3>
<P>
A file name consists of file name components separated by slash
(<SAMP>`/'</SAMP>) characters.  On the systems that that GNU library supports,
multiple successive <SAMP>`/'</SAMP> characters are equivalent to a single
<SAMP>`/'</SAMP> character.
<A NAME="IDX430"></A>
<P>
The process of determining what file a file name refers to is called
<DFN>file name resolution</DFN>.  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.
<A NAME="IDX431"></A>
<A NAME="IDX432"></A>
<P>
If a file name begins with a <SAMP>`/'</SAMP>, the first component in the file
name is located in the <DFN>root directory</DFN> of the process.  Such a file
name is called an <DFN>absolute file name</DFN>.
<A NAME="IDX433"></A>
<P>
Otherwise, the first component in the file name is located in the
current working directory (see section <A HREF="library.html#SEC188">Working Directory</A>).  This kind of
file name is called a <DFN>relative file name</DFN>.
<A NAME="IDX434"></A>
<P>
The file name components <TT>`.'</TT> ("dot") and <TT>`..'</TT> ("dot-dot")
have special meanings.  Every directory has entries for these file name
components.  The file name component <TT>`.'</TT> refers to the directory
itself, while the file name component <TT>`..'</TT> refers to its
<DFN>parent directory</DFN> (the directory that contains the link for the
directory in question).
<P>
Here are some examples of file names:
<P>
<DL COMPACT>
<DT><TT>`/a'</TT>
<DD>The file named <TT>`a'</TT>, in the root directory.
<P>
<DT><TT>`/a/b'</TT>
<DD>The file named <TT>`b'</TT>, in the directory named <TT>`a'</TT> in the root directory.
<P>
<DT><TT>`a'</TT>
<DD>The file named <TT>`a'</TT>, in the current working directory.
<P>
<DT><TT>`/a/./b'</TT>
<DD>This is the same as <TT>`/a/b'</TT>.  
<P>
<DT><TT>`./a'</TT>
<DD>The file named <TT>`a'</TT>, in the current working directory.
<P>
<DT><TT>`../a'</TT>
<DD>The file named <TT>`a'</TT>, in the parent directory of the current working
directory.
</DL>
<P>
A file name that names a directory may optionally end in a <SAMP>`/'</SAMP>.
You can specify a file name of <TT>`/'</TT> 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 <TT>`.'</TT> or
<TT>`./'</TT>.
<P>
Unlike some other operating systems, the GNU system doesn't have any
built-in support for file types (or extensions) or file versions as part
of its file name syntax.  Many programs and utilities use conventions
for file names--for example, files containing C source code usually
have names suffixed with <SAMP>`.c'</SAMP>---but there is nothing in the file
system itself that enforces this kind of convention.
<P>
<H3><A NAME="SEC115" HREF="library_toc.html#SEC115">File Name Errors</A></H3>
<A NAME="IDX435"></A>
<A NAME="IDX436"></A>
<P>
Functions that accept file name arguments usually detect these
<CODE>errno</CODE> error conditions relating to file name syntax.  These
errors are referred to throughout this manual as the <DFN>usual file
name syntax errors</DFN>.
<P>
<DL COMPACT>
<DT><CODE>EACCES</CODE>
<DD>The process does not have search permission for a directory component 
of the file name.
<P>
<DT><CODE>ENAMETOOLONG</CODE>
<DD>This error is used when either the the total length of a file name is
greater than <CODE>PATH_MAX</CODE>, or when an individual file name component
has a length greater than <CODE>NAME_MAX</CODE>.  See section <A HREF="library.html#SEC463">Limits on File System Capacity</A>.
<P>
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.
<P>
<DT><CODE>ENOENT</CODE>
<DD>This error is reported when a file referenced as a directory component
in the file name doesn't exist.
<P>
<DT><CODE>ENOTDIR</CODE>
<DD>A file that is referenced as a directory component in the file name
exists, but it isn't a directory.
</DL>
<P>
<H3><A NAME="SEC116" HREF="library_toc.html#SEC116">Portability of File Names</A></H3>
<P>
The rules for the syntax of file names discussed in section <A HREF="library.html#SEC112">File Names</A>,
are the rules normally used by the GNU system and by other POSIX
systems.  However, other operating systems may use other conventions.
<P>
There are two reasons why it can be important for you to be aware of
file name portability issues:
<P>
<UL>
<LI>
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.
<P>
<LI>
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.
</UL>
<P>
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.
<P>
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.
<P>
<H1><A NAME="SEC117" HREF="library_toc.html#SEC117">Input/Output on Streams</A></H1>
<P>
This chapter describes the functions for creating streams and performing
input and output operations on them.  As discussed in section <A HREF="library.html#SEC108">Input/Output Overview</A>, a stream is a fairly abstract, high-level concept
representing a communications channel to a file, device, or process.
<P>
<H2><A NAME="SEC118" HREF="library_toc.html#SEC118">Streams</A></H2>
<P>
For historical reasons, the type of the C data structure that represents
a stream is called <CODE>FILE</CODE> rather than "stream".  Since most of
the library functions deal with objects of type <CODE>FILE *</CODE>, sometimes
the term <DFN>file pointer</DFN> 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.
<A NAME="IDX437"></A>
<A NAME="IDX438"></A>
<P>
The <CODE>FILE</CODE> type is declared in the header file <TT>`stdio.h'</TT>.
<P>
<A NAME="IDX439"></A>
<U>Data Type:</U> <B>FILE</B><P>
This is the data type is used to represent stream objects.  A
<CODE>FILE</CODE> 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
<CODE>ferror</CODE> and <CODE>feof</CODE> functions; see section <A HREF="library.html#SEC156">End-Of-File and Errors</A>.
<P>
<CODE>FILE</CODE> objects are allocated and managed internally by the
input/output library functions.  Don't try to create your own objects of
type <CODE>FILE</CODE>; let the library do it.  Your programs should
deal only with pointers to these objects (that is, <CODE>FILE *</CODE> values)
rather than the objects themselves.
<P>
<A NAME="IDX440"></A>
<A NAME="IDX441"></A>
<H2><A NAME="SEC119" HREF="library_toc.html#SEC119">Standard Streams</A></H2>
<P>
When the <CODE>main</CODE> 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.
<P>
These streams are declared in the header file <TT>`stdio.h'</TT>.
<A NAME="IDX442"></A>
<P>
<A NAME="IDX443"></A>
<U>Macro:</U> FILE * <B>stdin</B><P>
The <DFN>standard input</DFN> stream, which is the normal source of input for the
program.
<A NAME="IDX444"></A>
<P>
<A NAME="IDX445"></A>
<U>Macro:</U> FILE * <B>stdout</B><P>
The <DFN>standard output</DFN> stream, which is used for normal output from
the program.
<A NAME="IDX446"></A>
<P>
<A NAME="IDX447"></A>
<U>Macro:</U> FILE * <B>stderr</B><P>
The <DFN>standard error</DFN> stream, which is used for error messages and
diagnostics issued by the program.
<A NAME="IDX448"></A>
<P>
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 section <A HREF="library.html#SEC187">File System Interface</A>.)  Most other operating systems
provide similar mechanisms, but the details of how to use them can vary.
<P>
It is probably not a good idea to close any of the standard streams.
But you can use <CODE>freopen</CODE> to get te effect of closing one and
reopening it.  See section <A HREF="library.html#SEC120">Opening Streams</A>.
<P>
<H2><A NAME="SEC120" HREF="library_toc.html#SEC120">Opening Streams</A></H2>
<A NAME="IDX449"></A>
<P>
Opening a file with the <CODE>fopen</CODE> function creates a new stream and
establishes a connection between the stream and a file.  This may
involve creating a new file.  
<A NAME="IDX450"></A>
<P>
Everything described in this section is declared in the header file
<TT>`stdio.h'</TT>.
<P>
<A NAME="IDX451"></A>
<U>Function:</U> FILE * <B>fopen</B> <I>(const char *<VAR>filename</VAR>, const char *<VAR>opentype</VAR>)</I><P>
The <CODE>fopen</CODE> function opens a stream for I/O to the file
<VAR>filename</VAR>, and returns a pointer to the stream.
<P>
The <VAR>opentype</VAR> 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:
<P>
<DL COMPACT>
<DT><SAMP>`r'</SAMP>
<DD>Open an existing file for reading only.
<P>
<DT><SAMP>`w'</SAMP>
<DD>Open the file for writing only.  If the file already exists, it is
truncated to zero length.  Otherwise a new file is created.
<P>
<DT><SAMP>`a'</SAMP>
<DD>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.
<P>
<DT><SAMP>`r+'</SAMP>
<DD>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.
<P>
<DT><SAMP>`w+'</SAMP>
<DD>Open file for both reading and writing.  If the file already exists, it
is truncated to zero length.  Otherwise, a new file is created.
<P>
<DT><SAMP>`a+'</SAMP>
<DD>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.
</DL>
<P>
As you can see, <SAMP>`+'</SAMP> requests a stream that can do both input and
output.  When using such a stream, you must call <CODE>fflush</CODE>
(see section <A HREF="library.html#SEC160">Stream Buffering</A>) or a file positioning function such as
<CODE>fseek</CODE> (see section <A HREF="library.html#SEC158">File Positioning</A>) when switching from reading to
writing or vice versa.  Otherwise, internal buffers might not be emptied
properly.
<P>
The GNU C library defines one additional character for use in
<VAR>opentype</VAR>: the character <SAMP>`x'</SAMP> insists on creating a new
file--if a file <VAR>filename</VAR> already exists, <CODE>fopen</CODE> fails
rather than opening it.  This is equivalent to the <CODE>O_EXCL</CODE> option
to the <CODE>open</CODE> function (see section <A HREF="library.html#SEC184">File Status Flags</A>).
<P>
The character <SAMP>`b'</SAMP> in <VAR>opentype</VAR> 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
<SAMP>`+'</SAMP> and <SAMP>`b'</SAMP> are specified, they can appear in either order.
See section <A HREF="library.html#SEC157">Text and Binary Streams</A>.
<P>
Any other characters in <VAR>opentype</VAR> are simply ignored.  They may be
meaningful in other systems.
<P>
If the open fails, <CODE>fopen</CODE> returns a null pointer.
<P>
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 section <A HREF="library.html#SEC176">Precautions for Mixing Streams and Descriptors</A>.  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 section <A HREF="library.html#SEC185">File Locks</A>.
<P>
<A NAME="IDX452"></A>
<U>Macro:</U> int <B>FOPEN_MAX</B><P>
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 <CODE>stdin</CODE>,
<CODE>stdout</CODE>, and <CODE>stderr</CODE>.
<P>
<A NAME="IDX453"></A>
<U>Function:</U> FILE * <B>freopen</B> <I>(const char *<VAR>filename</VAR>, const char *<VAR>opentype</VAR>, FILE *<VAR>stream</VAR>)</I><P>
This function is like a combination of <CODE>fclose</CODE> and <CODE>fopen</CODE>.
It first closes the stream referred to by <VAR>stream</VAR>, ignoring any
errors that are detected in the process.  (Because errors are ignored,
you should not use <CODE>freopen</CODE> on an output stream if you have
actually done any output using the stream.)  Then the file named by
<VAR>filename</VAR> is opened with mode <VAR>opentype</VAR> as for <CODE>fopen</CODE>,
and associated with the same stream object <VAR>stream</VAR>.
<P>
If the operation fails, a null pointer is returned; otherwise,
<CODE>freopen</CODE> returns <VAR>stream</VAR>.
<P>
The main use of <CODE>freopen</CODE> is to connect a standard stream such as
<CODE>stdir</CODE> 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.
<P>
<H2><A NAME="SEC121" HREF="library_toc.html#SEC121">Closing Streams</A></H2>
<A NAME="IDX454"></A>
<P>
When a stream is closed with <CODE>fclose</CODE>, 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.
<P>
<A NAME="IDX455"></A>
<U>Function:</U> int <B>fclose</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
This function causes <VAR>stream</VAR> 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 <CODE>fclose</CODE> function returns
a value of <CODE>0</CODE> if the file was closed successfully, and <CODE>EOF</CODE>
if an error was detected. 
<P>
It is important to check for errors when you call <CODE>fclose</CODE> to close
an output stream, because real, everyday errors can be detected at this
time.  For example, when <CODE>fclose</CODE> 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.
<P>
The function <CODE>fclose</CODE> is declared in <TT>`stdio.h'</TT>.
<P>
If the <CODE>main</CODE> function to your program returns, or if you call the
<CODE>exit</CODE> function (see section <A HREF="library.html#SEC396">Normal Termination</A>), all open streams are
automatically closed properly.  If your program terminates in any other
manner, such as by calling the <CODE>abort</CODE> function (see section <A HREF="library.html#SEC399">Aborting a Program</A>) or from a fatal signal (see section <A HREF="library.html#SEC330">Signal Handling</A>), 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 section <A HREF="library.html#SEC160">Stream Buffering</A>.
<P>
<H2><A NAME="SEC122" HREF="library_toc.html#SEC122">Simple Output by Characters or Lines</A></H2>
<A NAME="IDX456"></A>
<P>
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 <CODE>fputc</CODE> and
<CODE>fputs</CODE>, and perhaps <CODE>putc</CODE> and <CODE>putchar</CODE>.
<P>
These functions are declared in the header file <TT>`stdio.h'</TT>.
<A NAME="IDX457"></A>
<P>
<A NAME="IDX458"></A>
<U>Function:</U> int <B>fputc</B> <I>(int <VAR>c</VAR>, FILE *<VAR>stream</VAR>)</I><P>
The <CODE>fputc</CODE> function converts the character <VAR>c</VAR> to type
<CODE>unsigned char</CODE>, and writes it to the stream <VAR>stream</VAR>.  
<CODE>EOF</CODE> is returned if a write error occurs; otherwise the
character <VAR>c</VAR> is returned.
<P>
<A NAME="IDX459"></A>
<U>Function:</U> int <B>putc</B> <I>(int <VAR>c</VAR>, FILE *<VAR>stream</VAR>)</I><P>
This is just like <CODE>fputc</CODE>, except that most systems implement it as
a macro, making it faster.  One consequence is that it may evaluate the
<VAR>stream</VAR> argument more than once.
<P>
<A NAME="IDX460"></A>
<U>Function:</U> int <B>putchar</B> <I>(int <VAR>c</VAR>)</I><P>
The <CODE>putchar</CODE> function is equivalent to <CODE>fputc</CODE> with
<CODE>stdout</CODE> as the value of the <VAR>stream</VAR> argument.
<P>
<A NAME="IDX461"></A>
<U>Function:</U> int <B>fputs</B> <I>(const char *<VAR>s</VAR>, FILE *<VAR>stream</VAR>)</I><P>
The function <CODE>fputs</CODE> writes the string <VAR>s</VAR> to the stream
<VAR>stream</VAR>.  The terminating null character is not written.
This function does <EM>not</EM> add a newline character, either.
It outputs only the chars in the string.
<P>
This function returns <CODE>EOF</CODE> if a write error occurs, and otherwise
a non-negative value.
<P>
For example:
<P>
<PRE>
fputs ("Are ", stdout);
fputs ("you ", stdout);
fputs ("hungry?\n", stdout);
</PRE>
<P>
outputs the text <SAMP>`Are you hungry?'</SAMP> followed by a newline.
<P>
<A NAME="IDX462"></A>
<U>Function:</U> int <B>puts</B> <I>(const char *<VAR>s</VAR>)</I><P>
The <CODE>puts</CODE> function writes the string <VAR>s</VAR> to the stream
<CODE>stdout</CODE> followed by a newline.  The terminating null character of
the string is not written.
<P>
<A NAME="IDX463"></A>
<U>Function:</U> int <B>putw</B> <I>(int <VAR>w</VAR>, FILE *<VAR>stream</VAR>)</I><P>
This function writes the word <VAR>w</VAR> (that is, an <CODE>int</CODE>) to
<VAR>stream</VAR>.  It is provided for compatibility with SVID, but we
recommend you use <CODE>fwrite</CODE> instead (see section <A HREF="library.html#SEC155">Block Input/Output</A>).
<P>
<H2><A NAME="SEC123" HREF="library_toc.html#SEC123">Character Input</A></H2>
<A NAME="IDX464"></A>
<P>
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 <CODE>fgetc</CODE>, <CODE>getline</CODE>, and maybe
<CODE>getc</CODE>, <CODE>getchar</CODE> and <CODE>fgets</CODE>.
<P>
These functions are declared in the header file <TT>`stdio.h'</TT>.
<A NAME="IDX465"></A>
<P>
<A NAME="IDX466"></A>
<U>Function:</U> int <B>fgetc</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
This function reads the next character as an <CODE>unsigned char</CODE> from
the stream <VAR>stream</VAR> and returns its value, converted to an
<CODE>int</CODE>.  If an end-of-file condition or read error occurs,
<CODE>EOF</CODE> is returned instead.
<P>
<A NAME="IDX467"></A>
<U>Function:</U> int <B>getc</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
This is just like <CODE>fgetc</CODE>, except that it is permissible (and typical)
for it to be implemented as a macro that evaluates the <VAR>stream</VAR>
argument more than once.
<P>
<A NAME="IDX468"></A>
<U>Function:</U> int <B>getchar</B> <I>(void)</I><P>
The <CODE>getchar</CODE> function is equivalent to <CODE>fgetc</CODE> with <CODE>stdin</CODE>
as the value of the <VAR>stream</VAR> argument.
<P>
Here is an example of a function that does input using <CODE>fgetc</CODE>.  It
would work just as well using <CODE>getc</CODE> instead, or using
<CODE>getchar ()</CODE> instead of <CODE>fgetc (stdin)</CODE>.
<P>
<PRE>
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);
  }
}
</PRE>
<P>
<A NAME="IDX469"></A>
<U>Function:</U> int <B>getw</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
This function reads a word (that is, an <CODE>int</CODE>) from <VAR>stream</VAR>.
It's provided for compatibility with SVID.  We recommend you use
<CODE>fread</CODE> instead (see section <A HREF="library.html#SEC155">Block Input/Output</A>).
<P>
<H2><A NAME="SEC124" HREF="library_toc.html#SEC124">Line-Oriented Input</A></H2>
<P>
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.
<P>
Standard C has functions to do this, but they aren't very safe: null
characters and even (for <CODE>gets</CODE>) long lines can confuse them.  So
the GNU library provides the nonstandard <CODE>getline</CODE> function that
makes it easy to read lines reliably.
<P>
Another GNU extension, <CODE>getdelim</CODE>, generalizes <CODE>getline</CODE>.  It
reads a delimited record, defined as everything through the next
occurrence of a specified delimeter character.
<P>
All these functions are declared in <TT>`stdio.h'</TT>.
<P>
<A NAME="IDX470"></A>
<U>Function:</U> ssize_t <B>getline</B> <I>(char **<VAR>lineptr</VAR>, size_t *<VAR>n</VAR>, FILE *<VAR>stream</VAR>)</I><P>
This function reads an entire line from <VAR>stream</VAR>, storing the text
(including the newline and a terminating null character) in a buffer
and storing the buffer address in <CODE>*<VAR>lineptr</VAR></CODE>.
<P>
Before calling <CODE>getline</CODE>, you should place in <CODE>*<VAR>lineptr</VAR></CODE>
the address of a buffer <CODE>*<VAR>n</VAR></CODE> bytes long.  If this buffer is
long enough to hold the line, <CODE>getline</CODE> stores the line in this
buffer.  Otherwise, <CODE>getline</CODE> makes the buffer bigger using
<CODE>realloc</CODE>, storing the new buffer address back in
<CODE>*<VAR>lineptr</VAR></CODE> and the increased size back in <CODE>*<VAR>n</VAR></CODE>.
<P>
In either case, when <CODE>getline</CODE> returns,  <CODE>*<VAR>lineptr</VAR></CODE> is
a <CODE>char *</CODE> which points to the text of the line.
<P>
When <CODE>getline</CODE> 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.
<P>
This function is a GNU extension, but it is the recommended way to read
lines from a stream.  The alternative standard functions are unreliable.
<P>
If an error occurs or end of file is reached, <CODE>getline</CODE> returns
<CODE>-1</CODE>.
<P>
<A NAME="IDX471"></A>
<U>Function:</U> ssize_t <B>getdelim</B> <I>(char **<VAR>lineptr</VAR>, size_t *<VAR>n</VAR>, int <VAR>delimiter</VAR>, FILE *<VAR>stream</VAR>)</I><P>
This function is like <CODE>getline</CODE> except that the character which
tells it to stop reading is not necessarily newline.  The argument
<VAR>delimeter</VAR> specifies the delimeter character; <CODE>getdelim</CODE> keeps
reading until it sees that character (or end of file).
<P>
The text is stored in <VAR>lineptr</VAR>, including the delimeter character
and a terminating null.  Like <CODE>getline</CODE>, <CODE>getdelim</CODE> makes
<VAR>lineptr</VAR> bigger if it isn't big enough.
<P>
<A NAME="IDX472"></A>
<U>Function:</U> char * <B>fgets</B> <I>(char *<VAR>s</VAR>, int <VAR>count</VAR>, FILE *<VAR>stream</VAR>)</I><P>
The <CODE>fgets</CODE> function reads characters from the stream <VAR>stream</VAR>
up to and including a newline character and stores them in the string
<VAR>s</VAR>, adding a null character to mark the end of the string.  You
must supply <VAR>count</VAR> characters worth of space in <VAR>s</VAR>, but the
number of characters read is at most <VAR>count</VAR> - 1.  The extra
character space is used to hold the null character at the end of the
string.
<P>
If the system is already at end of file when you call <CODE>fgets</CODE>, then
the contents of the array <VAR>s</VAR> 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 <VAR>s</VAR>.
<P>
<STRONG>Warning:</STRONG>  If the input data has a null character, you can't tell.
So don't use <CODE>fgets</CODE> 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 <CODE>getline</CODE> instead of <CODE>fgets</CODE>.
<P>
<A NAME="IDX473"></A>
<U>Deprecated function:</U> char * <B>gets</B> <I>(char *<VAR>s</VAR>)</I><P>
The function <CODE>gets</CODE> reads characters from the stream <CODE>stdin</CODE>
up to the next newline character, and stores them in the string <VAR>s</VAR>.
The newline character is discarded (note that this differs from the
behavior of <CODE>fgets</CODE>, which copies the newline character into the
string).
<P>
<STRONG>Warning:</STRONG>  The <CODE>gets</CODE> function is <STRONG>very dangerous</STRONG> 
because it provides no protection against overflowing the string <VAR>s</VAR>.
The GNU library includes it for compatibility only.  You should 
<STRONG>always</STRONG> use <CODE>fgets</CODE> or <CODE>getline</CODE> instead.
<P>
<A NAME="IDX474"></A>
<A NAME="IDX475"></A>
<A NAME="IDX476"></A>
<H2><A NAME="SEC125" HREF="library_toc.html#SEC125">Unreading</A></H2>
<P>
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.
<P>
Using stream I/O, you can peek ahead at input by first reading it and
then <DFN>unreading</DFN> it (also called  <DFN>pushing it back</DFN> on the stream).  
Unreading a character makes it available to be input again from the stream,
by  the next call to <CODE>fgetc</CODE> or other input function on that stream.
<P>
<H3><A NAME="SEC126" HREF="library_toc.html#SEC126">What Unreading Means</A></H3>
<P>
Here is a pictorial explanation of unreading.  Suppose you have a
stream reading a file that contains just six characters, the letters
<SAMP>`foobar'</SAMP>.  Suppose you have read three characters so far.  The
situation looks like this:
<P>
<PRE>
f  o  o  b  a  r
         ^
</PRE>
<P>
so the next input character will be <SAMP>`b'</SAMP>.
<P>
If instead of reading <SAMP>`b'</SAMP> you unread the letter <SAMP>`o'</SAMP>, you get a
situation like this:
<P>
<PRE>
f  o  o  b  a  r
         |
      o--
      ^
</PRE>
<P>
so that the next input characters will be <SAMP>`o'</SAMP> and <SAMP>`b'</SAMP>.
<P>
If you unread <SAMP>`9'</SAMP> instead of <SAMP>`o'</SAMP>, you get this situation:
<P>
<PRE>
f  o  o  b  a  r
         |
      9--
      ^
</PRE>
<P>
so that the next input characters will be <SAMP>`9'</SAMP> and <SAMP>`b'</SAMP>.
<P>
<H3><A NAME="SEC127" HREF="library_toc.html#SEC127">Using <CODE>ungetc</CODE> To Do Unreading</A></H3>
 
The function to unread a character is called <CODE>ungetc</CODE>, because it
reverses the action of <CODE>fgetc</CODE>.
<P>
<A NAME="IDX477"></A>
<U>Function:</U> int <B>ungetc</B> <I>(int <VAR>c</VAR>, FILE *<VAR>stream</VAR>)</I><P>
The <CODE>ungetc</CODE> function pushes back the character <VAR>c</VAR> onto the
input stream <VAR>stream</VAR>.  So the next input from <VAR>stream</VAR> will
read <VAR>c</VAR> before anything else.
<P>
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 <CODE>ungetc</CODE>!  But that is a strange way to write
a program; usually <CODE>ungetc</CODE> is used only to unread a character
that was just read from the same stream.
<P>
The GNU C library only supports one character of pushback--in other
words, it does not work to call <CODE>ungetc</CODE> 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.
<P>
Pushing back characters doesn't alter the file; only the internal
buffering for the stream is affected.  If a file positioning function
(such as <CODE>fseek</CODE> or <CODE>rewind</CODE>; see section <A HREF="library.html#SEC158">File Positioning</A>) is
called, any pending pushed-back characters are discarded.
<P>
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.
<P>
Here is an example showing the use of <CODE>getc</CODE> and <CODE>ungetc</CODE> 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.
<P>
<PRE>
#include &#60;stdio.h&#62;

void
skip_whitespace (FILE *stream)
{
  int c;
  do
    /* No need to check for <CODE>EOF</CODE> because it is not
       <CODE>isspace</CODE>, and <CODE>ungetc</CODE> ignores <CODE>EOF</CODE>.  */
    c = getc (stream);
  while (isspace (c));
  ungetc (c, stream);
}
</PRE>
<P>
<H2><A NAME="SEC128" HREF="library_toc.html#SEC128">Formatted Output</A></H2>
<A NAME="IDX478"></A>
<A NAME="IDX479"></A>
<A NAME="IDX480"></A>
<A NAME="IDX481"></A>
<P>
The functions described in this section (<CODE>printf</CODE> and related
functions) provide a convenient way to perform formatted output.  You
call <CODE>printf</CODE> with a <DFN>format string</DFN> or <DFN>template string</DFN>
that specifies how to format the values of the remaining arguments.
<P>
Unless your program is a filter that specifically performs line- or
character-oriented processing, using <CODE>printf</CODE> 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.
<P>
<H3><A NAME="SEC129" HREF="library_toc.html#SEC129">Formatted Output Basics</A></H3>
<P>
The <CODE>printf</CODE> 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.
<P>
Ordinary characters in the template string are simply written to the
output stream as-is, while <DFN>conversion specifications</DFN> introduced by
a <SAMP>`%'</SAMP> character in the template cause subsequent arguments to be
formatted and written to the output stream.  For example,
<A NAME="IDX482"></A>
<P>
<PRE>
int pct = 37;
char filename[] = "foo.txt";
printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
        filename, pct);
</PRE>
<P>
produces output like
<P>
<PRE>
Processing of `foo.txt' is 37% finished.
Please be patient.
</PRE>
<P>
This example shows the use of the <SAMP>`%d'</SAMP> conversion to specify that
an <CODE>int</CODE> argument should be printed in decimal notation, the
<SAMP>`%s'</SAMP> conversion to specify printing of a string argument, and
the <SAMP>`%%'</SAMP> conversion to print a literal <SAMP>`%'</SAMP> character.
<P>
There are also conversions for printing an integer argument as an
unsigned value in octal, decimal, or hexadecimal radix (<SAMP>`%o'</SAMP>,
<SAMP>`%u'</SAMP>, or <SAMP>`%x'</SAMP>, respectively); or as a character value
(<SAMP>`%c'</SAMP>).
<P>
Floating-point numbers can be printed in normal, fixed-point notation
using the <SAMP>`%f'</SAMP> conversion or in exponential notation using the
<SAMP>`%e'</SAMP> conversion.  The <SAMP>`%g'</SAMP> conversion uses either <SAMP>`%e'</SAMP>
or <SAMP>`%f'</SAMP> format, depending on what is more appropriate for the
magnitude of the particular number.
<P>
You can control formatting more precisely by writing <DFN>modifiers</DFN>
between the <SAMP>`%'</SAMP> 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.
<P>
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.
<P>
<H3><A NAME="SEC130" HREF="library_toc.html#SEC130">Output Conversion Syntax</A></H3>
<P>
This section provides details about the precise syntax of conversion
specifications that can appear in a <CODE>printf</CODE> template
string.
<P>
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 section <A HREF="library.html#SEC66">Extended Characters</A>) are permitted in
a template string.
<P>
The conversion specifications in a <CODE>printf</CODE> template string have
the general form:
<P>
<PRE>
% <VAR>flags</VAR> <VAR>width</VAR> [ . <VAR>precision</VAR> ] <VAR>type</VAR> <VAR>conversion</VAR>
</PRE>
<P>
For example, in the conversion specifier <SAMP>`%-10.8ld'</SAMP>, the <SAMP>`-'</SAMP>
is a flag, <SAMP>`10'</SAMP> specifies the field width, the precision is
<SAMP>`8'</SAMP>, the letter <SAMP>`l'</SAMP> is a type modifier, and <SAMP>`d'</SAMP> specifies
the conversion style.  (This particular type specifier says to
print a <CODE>long int</CODE> argument in decimal notation, with a minimum of
8 digits left-justified in a field at least 10 characters wide.)
<P>
In more detail, output conversion specifications consist of an
initial <SAMP>`%'</SAMP> character followed in sequence by:
<P>
<UL>
<LI>
Zero or more <DFN>flag characters</DFN> that modify the normal behavior of
the conversion specification.
<A NAME="IDX483"></A>
<P>
<LI>
An optional decimal integer specifying the <DFN>minimum field width</DFN>.
If the normal conversion produces fewer characters than this, the field
is padded with spaces to the specified width.  This is a <EM>minimum</EM>
value; if the normal conversion produces more characters than this, the
field is <EM>not</EM> truncated.  Normally, the output is right-justified
within the field.
<A NAME="IDX484"></A>
<P>
The GNU library's version of <CODE>printf</CODE> also allows you to specify a
field width of <SAMP>`*'</SAMP>.  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 <CODE>int</CODE>.  Other C library versions may
not recognize this syntax.
<P>
<LI>
An optional <DFN>precision</DFN> to specify the number of digits to be
written for the numeric conversions.  If the precision is specified, it
consists of a period (<SAMP>`.'</SAMP>) followed optionally by a decimal integer
(which defaults to zero if omitted).
<A NAME="IDX485"></A>
<P>
The GNU library's version of <CODE>printf</CODE> also allows you to specify a
precision of <SAMP>`*'</SAMP>.  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 <CODE>int</CODE>.  If you specify <SAMP>`*'</SAMP>
for both the field width and precision, the field width argument
precedes the precision argument.  Other C library versions may not
recognize this syntax.
<P>
<LI>
An optional <DFN>type modifier character</DFN>, 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 <CODE>int</CODE>,
but you can specify <SAMP>`h'</SAMP>, <SAMP>`l'</SAMP>, or <SAMP>`L'</SAMP> for other integer
types.)
<A NAME="IDX486"></A>
<P>
<LI>
A character that specifies the conversion to be applied.
</UL>
<P>
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.
<P>
<A NAME="IDX487"></A>
<H3><A NAME="SEC131" HREF="library_toc.html#SEC131">Table of Output Conversions</A></H3>
<P>
Here is a table summarizing what all the different conversions do:
<P>
<DL COMPACT>
<DT><SAMP>`%d'</SAMP>, <SAMP>`%i'</SAMP>
<DD>Print an integer as a signed decimal number.  See section <A HREF="library.html#SEC132">Integer Conversions</A>, for details.  <SAMP>`%d'</SAMP> and <SAMP>`%i'</SAMP> are synonymous for
output, but are different when used with <CODE>scanf</CODE> for input
(see section <A HREF="library.html#SEC148">Table of Input Conversions</A>).
<P>
<DT><SAMP>`%o'</SAMP>
<DD>Print an integer as an unsigned octal number.  See section <A HREF="library.html#SEC132">Integer Conversions</A>, for details.
<P>
<DT><SAMP>`%u'</SAMP>
<DD>Print an integer as an unsigned decimal number.  See section <A HREF="library.html#SEC132">Integer Conversions</A>, for details.
<P>
<DT><SAMP>`%Z'</SAMP>
<DD>Print an integer as an unsigned decimal number, assuming it was passed
with type <CODE>size_t</CODE>.  See section <A HREF="library.html#SEC132">Integer Conversions</A>, for details.
<P>
<DT><SAMP>`%x'</SAMP>, <SAMP>`%X'</SAMP>
<DD>Print an integer as an unsigned hexadecimal number.  <SAMP>`%x'</SAMP> uses
lower-case letters and <SAMP>`%X'</SAMP> uses upper-case.  See section <A HREF="library.html#SEC132">Integer Conversions</A>, for details.
<P>
<DT><SAMP>`%f'</SAMP>
<DD>Print a floating-point number in normal (fixed-point) notation.
See section <A HREF="library.html#SEC133">Floating-Point Conversions</A>, for details.
<P>
<DT><SAMP>`%e'</SAMP>, <SAMP>`%E'</SAMP>
<DD>Print a floating-point number in exponential notation.  <SAMP>`%e'</SAMP> uses
lower-case letters and <SAMP>`%E'</SAMP> uses upper-case.  See section <A HREF="library.html#SEC133">Floating-Point Conversions</A>, for details.
<P>
<DT><SAMP>`%g'</SAMP>, <SAMP>`%G'</SAMP>
<DD>Print a floating-point number in either normal or exponential notation,
whichever is more appropriate for its magnitude.  <SAMP>`%g'</SAMP> uses
lower-case letters and <SAMP>`%G'</SAMP> uses upper-case.  See section <A HREF="library.html#SEC133">Floating-Point Conversions</A>, for details.
<P>
<DT><SAMP>`%c'</SAMP>
<DD>Print a single character.  See section <A HREF="library.html#SEC134">Other Output Conversions</A>.
<P>
<DT><SAMP>`%s'</SAMP>
<DD>Print a string.  See section <A HREF="library.html#SEC134">Other Output Conversions</A>.
<P>
<DT><SAMP>`%p'</SAMP>
<DD>Print the value of a pointer.  See section <A HREF="library.html#SEC134">Other Output Conversions</A>.
<P>
<DT><SAMP>`%n'</SAMP>
<DD>Get the number of characters printed so far.  See section <A HREF="library.html#SEC134">Other Output Conversions</A>.
Note that this conversion specification never produces any output.
<P>
<DT><SAMP>`%m'</SAMP>
<DD>Print the string corresponding to the value of <CODE>errno</CODE>.
See section <A HREF="library.html#SEC134">Other Output Conversions</A>.
<P>
<DT><SAMP>`%%'</SAMP>
<DD>Print a literal <SAMP>`%'</SAMP> character.  See section <A HREF="library.html#SEC134">Other Output Conversions</A>.
</DL>
<P>
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.
<P>
<H3><A NAME="SEC132" HREF="library_toc.html#SEC132">Integer Conversions</A></H3>
<P>
This section describes the options for the <SAMP>`%d'</SAMP>, <SAMP>`%i'</SAMP>,
<SAMP>`%o'</SAMP>, <SAMP>`%u'</SAMP>, <SAMP>`%x'</SAMP>, <SAMP>`%X'</SAMP>, and <SAMP>`%Z'</SAMP> conversion
specifications.  These conversions print integers in various formats.
<P>
The <SAMP>`%d'</SAMP> and <SAMP>`%i'</SAMP> conversion specifications both print an
<CODE>int</CODE> argument as a signed decimal number; while <SAMP>`%o'</SAMP>,
<SAMP>`%u'</SAMP>, and <SAMP>`%x'</SAMP> print the argument as an unsigned octal,
decimal, or hexadecimal number (respectively).  The <SAMP>`%X'</SAMP> conversion
specification is just like <SAMP>`%x'</SAMP> except that it uses the characters
<SAMP>`ABCDEF'</SAMP> as digits instead of <SAMP>`abcdef'</SAMP>.  <SAMP>`%Z'</SAMP> is like
<SAMP>`%u'</SAMP> but expects an argument of type <CODE>size_t</CODE>.
<P>
The following flags are meaningful:
<P>
<DL COMPACT>
<DT><SAMP>`-'</SAMP>
<DD>Left-justify the result in the field (instead of the normal
right-justification).
<P>
<DT><SAMP>`+'</SAMP>
<DD>For the signed <SAMP>`%d'</SAMP> and <SAMP>`%i'</SAMP> conversions, print a
plus sign if the value is positive.
<P>
<DT><SAMP>` '</SAMP>
<DD>For the signed <SAMP>`%d'</SAMP> and <SAMP>`%i'</SAMP> conversions, if the result
doesn't start with a plus or minus sign, prefix it with a space
character instead.  Since the <SAMP>`+'</SAMP> flag ensures that the result
includes a sign, this flag is ignored if you supply both of them.
<P>
<DT><SAMP>`#'</SAMP>
<DD>For the <SAMP>`%o'</SAMP> conversion, this forces the leading digit to be <SAMP>`0'</SAMP>,
as if by increasing the precision.  For <SAMP>`%x'</SAMP> or <SAMP>`%X'</SAMP>, this
prefixes a leading <SAMP>`0x'</SAMP> or <SAMP>`0X'</SAMP> (respectively) to the result.
This doesn't do anything useful for the <SAMP>`%d'</SAMP>, <SAMP>`%i'</SAMP>, or <SAMP>`%u'</SAMP>
conversions.
<P>
<DT><SAMP>`0'</SAMP>
<DD>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 <SAMP>`-'</SAMP>
flag is also specified, or if a precision is specified.
</DL>
<P>
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.
<P>
Without a type modifier, the corresponding argument is treated as an
<CODE>int</CODE> (for the signed conversions <SAMP>`%i'</SAMP> and <SAMP>`%d'</SAMP>) or
<CODE>unsigned int</CODE> (for the unsigned conversions <SAMP>`%o'</SAMP>, <SAMP>`%u'</SAMP>,
<SAMP>`%x'</SAMP>, and <SAMP>`%X'</SAMP>).  Recall that since <CODE>printf</CODE> and friends
are variadic, any <CODE>char</CODE> and <CODE>short</CODE> arguments are
automatically converted to <CODE>int</CODE> by the default argument
promotions.  For arguments of other integer types, you can use these
modifiers:
<P>
<DL COMPACT>
<DT><SAMP>`h'</SAMP>
<DD>Specifies that the argument is a <CODE>short int</CODE> or <CODE>unsigned
short int</CODE>, as appropriate.  A <CODE>short</CODE> argument is converted to an
<CODE>int</CODE> or <CODE>unsigned int</CODE> by the default argument promotions
anyway, but the <SAMP>`h'</SAMP> modifier says to convert it back to a
<CODE>short</CODE> again.
<P>
<DT><SAMP>`l'</SAMP>
<DD>Specifies that the argument is a <CODE>long int</CODE> or <CODE>unsigned long
int</CODE>, as appropriate.  
<P>
<DT><SAMP>`L'</SAMP>
<DD>Specifies that the argument is a <CODE>long long int</CODE>.  (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 <CODE>long int</CODE>.)
</DL>
<P>
The modifiers for argument type are not applicable to <SAMP>`%Z'</SAMP>, since
the sole purpose of <SAMP>`%Z'</SAMP> is to specify the data type
<CODE>size_t</CODE>.
<P>
Here is an example.  Using the template string:
<P>
<PRE>
|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
</PRE>
<P>
to print numbers using the different options for the <SAMP>`%d'</SAMP>
conversion gives results like:
<P>
<PRE>
|    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|
</PRE>
<P>
In particular, notice what happens in the last case where the number
is too large to fit in the minimum field width specified.
<P>
Here are some more examples showing how unsigned integers print under
various format options, using the template string:
<P>
<PRE>
"|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
</PRE>
<P>
<PRE>
|    0|    0|    0|    0|    0|  0x0|  0X0|0x00000000|
|    1|    1|    1|    1|   01|  0x1|  0X1|0x00000001|
|100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
</PRE>
<P>
<H3><A NAME="SEC133" HREF="library_toc.html#SEC133">Floating-Point Conversions</A></H3>
<P>
This section discusses the conversion specifications for floating-point
numbers: the <SAMP>`%f'</SAMP>, <SAMP>`%e'</SAMP>, <SAMP>`%E'</SAMP>, <SAMP>`%g'</SAMP>, and <SAMP>`%G'</SAMP>
conversions.
<P>
The <SAMP>`%f'</SAMP> conversion prints its argument in fixed-point notation,
producing output of the form
[<CODE>-</CODE>]<VAR>ddd</VAR><CODE>.</CODE><VAR>ddd</VAR>,
where the number of digits following the decimal point is controlled
by the precision you specify.
<P>
The <SAMP>`%e'</SAMP> conversion prints its argument in exponential notation,
producing output of the form
[<CODE>-</CODE>]<VAR>d</VAR><CODE>.</CODE><VAR>ddd</VAR><CODE>e</CODE>[<CODE>+</CODE>|<CODE>-</CODE>]<VAR>dd</VAR>.
Again, the number of digits following the decimal point is controlled by
the precision.  The exponent always contains at least two digits.  The
<SAMP>`%E'</SAMP> conversion is similar but the exponent is marked with the letter
<SAMP>`E'</SAMP> instead of <SAMP>`e'</SAMP>.
<P>
The <SAMP>`%g'</SAMP> and <SAMP>`%G'</SAMP> conversions print the argument in the style
of <SAMP>`%e'</SAMP> or <SAMP>`%E'</SAMP> (respectively) if the exponent would be less
than -4 or greater than or equal to the precision; otherwise they use the
<SAMP>`%f'</SAMP> style.  Trailing zeros are removed from the fractional portion
of the result and a decimal-point character appears only if it is
followed by a digit.
<P>
The following flags can be used to modify the behavior:
<P>
<DL COMPACT>
<DT><SAMP>`-'</SAMP>
<DD>Left-justify the result in the field.  Normally the result is
right-justified.
<P>
<DT><SAMP>`+'</SAMP>
<DD>Always include a plus or minus sign in the result.
<P>
<DT><SAMP>` '</SAMP>
<DD>If the result doesn't start with a plus or minus sign, prefix it with a
space instead.  Since the <SAMP>`+'</SAMP> flag ensures that the result includes
a sign, this flag is ignored if you supply both of them.
<P>
<DT><SAMP>`#'</SAMP>
<DD>Specifies that the result should always include a decimal point, even
if no digits follow it.  For the <SAMP>`%g'</SAMP> and <SAMP>`%G'</SAMP> conversions,
this also forces trailing zeros after the decimal point to be left
in place where they would otherwise be removed.
<P>
<DT><SAMP>`0'</SAMP>
<DD>Pad the field with zeros instead of spaces; the zeros are placed
after any sign.  This flag is ignored if the <SAMP>`-'</SAMP> flag is also
specified.
</DL>
<P>
The precision specifies how many digits follow the decimal-point
character for the <SAMP>`%f'</SAMP>, <SAMP>`%e'</SAMP>, and <SAMP>`%E'</SAMP> conversions.  For
these conversions, the default is <CODE>6</CODE>.  If the precision is
explicitly <CODE>0</CODE>, this has the rather strange effect of suppressing
the decimal point character entirely!  For the <SAMP>`%g'</SAMP> and <SAMP>`%G'</SAMP>
conversions, the precision specifies how many significant digits to
print; if <CODE>0</CODE> or not specified, it is treated like a value of
<CODE>1</CODE>.
<P>
Without a type modifier, the floating-point conversions use an argument
of type <CODE>double</CODE>.  (By the default argument promotions, any
<CODE>float</CODE> arguments are automatically converted to <CODE>double</CODE>.)
The following type modifier is supported:
<P>
<DL COMPACT>
<DT><SAMP>`L'</SAMP>
<DD>An uppercase <SAMP>`L'</SAMP> specifies that the argument is a <CODE>long
double</CODE>.
</DL>
<P>
Here are some examples showing how numbers print using the various
floating-point conversions.  All of the numbers were printed using
this template string:
<P>
<PRE>
"|%12.4f|%12.4e|%12.4g|\n"
</PRE>
<P>
Here is the output:
<P>
<PRE>
|      0.0000|  0.0000e+00|           0|
|      1.0000|  1.0000e+00|           1|
|     -1.0000| -1.0000e+00|          -1|
|    100.0000|  1.0000e+02|         100|
|   1000.0000|  1.0000e+03|        1000|
|  10000.0000|  1.0000e+04|       1e+04|
|  12345.0000|  1.2345e+04|   1.234e+04|
| 100000.0000|  1.0000e+05|       1e+05|
| 123456.0000|  1.2346e+05|   1.234e+05|
</PRE>
<P>
Notice how the <SAMP>`%g'</SAMP> conversion drops trailing zeros.
<P>
<H3><A NAME="SEC134" HREF="library_toc.html#SEC134">Other Output Conversions</A></H3>
<P>
This section describes miscellaneous conversions for <CODE>printf</CODE>.
<P>
The <SAMP>`%c'</SAMP> conversion prints a single character.  The <CODE>int</CODE>
argument is first converted to an <CODE>unsigned char</CODE>.  The <SAMP>`-'</SAMP>
flag can be used to specify left-justification in the field, but no
other flags are defined, and no precision or type modifier can be given.
For example:
<P>
<PRE>
printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
</PRE>
<P>
prints <SAMP>`hello'</SAMP>.
<P>
The <SAMP>`%s'</SAMP> conversion prints a string.  The corresponding argument
must be of type <CODE>char *</CODE>.  A precision can be specified to indicate
the maximum number of characters to write; otherwise characters in the
string up to but not including the terminating null character are
written to the output stream.  The <SAMP>`-'</SAMP> flag can be used to specify
left-justification in the field, but no other flags or type modifiers
are defined for this conversion.  For example:
<P>
<PRE>
printf ("%3s%-6s", "no", "where");
</PRE>
<P>
prints <SAMP>` nowhere '</SAMP>.
<P>
If you accidentally pass a null pointer as the argument for a <SAMP>`%s'</SAMP>
conversion, the GNU library prints it as <SAMP>`(null)'</SAMP>.  We think this
is more useful than crashing.  But it's not good practice to pass a null
argument intentionally.
<P>
The <SAMP>`%m'</SAMP> conversion prints the string corresponding to the error
code in <CODE>errno</CODE>.  See section <A HREF="library.html#SEC17">Error Messages</A>.  Thus:
<P>
<PRE>
fprintf (stderr, "can't open `%s': %m\n", filename);
</PRE>
<P>
is equivalent to:
<P>
<PRE>
fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
</PRE>
<P>
The <SAMP>`%m'</SAMP> conversion is a GNU C library extension.
<P>
The <SAMP>`%p'</SAMP> conversion prints a pointer value.  The corresponding
argument must be of type <CODE>void *</CODE>.  In practice, you can use any
type of pointer.
<P>
In the GNU system, non-null pointers are printed as unsigned integers,
as if a <SAMP>`%#x'</SAMP> conversion were used.  Null pointers print as
<SAMP>`(nil)'</SAMP>.  (Pointers might print differently in other systems.)
<P>
For example:
<P>
<PRE>
printf ("%p", "testing");
</PRE>
<P>
prints <SAMP>`0x'</SAMP> followed by a hexadecimal number--the address of the
string constant <CODE>"testing"</CODE>.  It does not print the word
<SAMP>`testing'</SAMP>.
<P>
You can supply the <SAMP>`-'</SAMP> flag with the <SAMP>`%p'</SAMP> conversion to
specify left-justification, but no other flags, precision, or type
modifiers are defined.
<P>
The <SAMP>`%n'</SAMP> conversion is unlike any of the other output conversions.
It uses an argument which must be a pointer to an <CODE>int</CODE>, but
instead of printing anything it stores the number of characters printed
so far by this call at that location.  The <SAMP>`h'</SAMP> and <SAMP>`l'</SAMP> type
modifiers are permitted to specify that the argument is of type
<CODE>short int *</CODE> or <CODE>long int *</CODE> instead of <CODE>int *</CODE>, but no
flags, field width, or precision are permitted.
<P>
For example,
<P>
<PRE>
int nchar;
printf ("%d %s%n\n", 3, "bears", &#38;nchar);
</PRE>
<P>
prints:
<P>
<PRE>
3 bears
</PRE>
<P>
and sets <CODE>nchar</CODE> to <CODE>7</CODE>, because <SAMP>`3 bears'</SAMP> is seven 
characters.
<P>
The <SAMP>`%%'</SAMP> conversion prints a literal <SAMP>`%'</SAMP> character.  This
conversion doesn't use an argument, and no flags, field width,
precision, or type modifiers are permitted.
<P>
<H3><A NAME="SEC135" HREF="library_toc.html#SEC135">Formatted Output Functions</A></H3>
<P>
This section describes how to call <CODE>printf</CODE> and related functions.
Prototypes for these functions are in the header file <TT>`stdio.h'</TT>.
<A NAME="IDX488"></A>
<P>
<A NAME="IDX489"></A>
<U>Function:</U> int <B>printf</B> <I>(const char *<VAR>template</VAR>, ...)</I><P>
The <CODE>printf</CODE> function prints the optional arguments under the
control of the template string <VAR>template</VAR> to the stream
<CODE>stdout</CODE>.  It returns the number of characters printed, or a
negative value if there was an output error.
<P>
<A NAME="IDX490"></A>
<U>Function:</U> int <B>fprintf</B> <I>(FILE *<VAR>stream</VAR>, const char *<VAR>template</VAR>, ...)</I><P>
This function is just like <CODE>printf</CODE>, except that the output is
written to the stream <VAR>stream</VAR> instead of <CODE>stdout</CODE>.
<P>
<A NAME="IDX491"></A>
<U>Function:</U> int <B>sprintf</B> <I>(char *<VAR>s</VAR>, const char *<VAR>template</VAR>, ...)</I><P>
This is like <CODE>printf</CODE>, except that the output is stored in the character
array <VAR>s</VAR> instead of written to a stream.  A null character is written
to mark the end of the string.
<P>
The <CODE>sprintf</CODE> function returns the number of characters stored in
the array <VAR>s</VAR>, not including the terminating null character.
<P>
The behavior of this function is undefined if copying takes place
between objects that overlap--for example, if <VAR>s</VAR> is also given
as an argument to be printed under control of the <SAMP>`%s'</SAMP> conversion.
See section <A HREF="library.html#SEC61">Copying and Concatenation</A>.
<P>
<STRONG>Warning:</STRONG> The <CODE>sprintf</CODE> function can be <STRONG>dangerous</STRONG>
because it can potentially output more characters than can fit in the
allocation size of the string <VAR>s</VAR>.  Remember that the field width
given in a conversion specification is only a <EM>minimum</EM> value.
<P>
To avoid this problem, you can use <CODE>snprintf</CODE> or <CODE>asprintf</CODE>,
described below.
<P>
<A NAME="IDX492"></A>
<U>Function:</U> int <B>snprintf</B> <I>(char *<VAR>s</VAR>, size_t <VAR>size</VAR>, const char *<VAR>template</VAR>, ...)</I><P>
The <CODE>snprintf</CODE> function is similar to <CODE>sprintf</CODE>, except that
the <VAR>size</VAR> argument specifies the maximum number of characters to
produce.  The trailing null character is counted towards this limit, so
you should allocate at least <VAR>size</VAR> characters for the string <VAR>s</VAR>.
<P>
The return value is the number of characters stored, not including the
terminating null.  If this value equals <VAR>size</VAR>, then there was not
enough space in <VAR>s</VAR> for all the output.  You should try again with a
bigger output string.  Here is an example of doing this:
<P>
<PRE>
/* Construct a message describing the value of a variable
   whose name is <VAR>name</VAR> and whose value is <VAR>value</VAR>. */
char *
make_message (char *name, char *value)
{
  /* Guess we need no more than 100 chars of space. */
  int size = 100;
  char *buffer = (char *) xmalloc (size);
  while (1)
    {
      /* Try to print in the allocated space. */
      int nchars = snprintf (buffer, size,
                             "value of %s is %s", name, value);
      /* If that worked, return the string. */
      if (nchars &#60; size)
        return buffer;
      /* Else try again with twice as much space. */
      size *= 2;
      buffer = (char *) xrealloc (size, buffer);
    }
}
</PRE>
<P>
In practice, it is often easier just to use <CODE>asprintf</CODE>, below.
<P>
<H3><A NAME="SEC136" HREF="library_toc.html#SEC136">Dynamically Allocating Formatted Output</A></H3>
<P>
The functions in this section do formatted output and place the results
in dynamically allocated memory.
<P>
<A NAME="IDX493"></A>
<U>Function:</U> int <B>asprintf</B> <I>(char **<VAR>ptr</VAR>, const char *<VAR>template</VAR>, ...)</I><P>
This function is similar to <CODE>sprintf</CODE>, except that it dynamically
allocates a string (as with <CODE>malloc</CODE>; see section <A HREF="library.html#SEC21">Unconstrained Allocation</A>) to hold the output, instead of putting the output in a
buffer you allocate in advance.  The <VAR>ptr</VAR> argument should be the
address of a <CODE>char *</CODE> object, and <CODE>asprintf</CODE> stores a pointer
to the newly allocated string at that location.
<P>
Here is how to use <CODE>asprint</CODE> to get the same result as the
<CODE>snprintf</CODE> example, but more easily:
<P>
<PRE>
/* Construct a message describing the value of a variable
   whose name is <VAR>name</VAR> and whose value is <VAR>value</VAR>. */
char *
make_message (char *name, char *value)
{
  char *result;
  asprintf (&#38;result, "value of %s is %s", name, value);
  return result;
}
</PRE>
<P>
<A NAME="IDX494"></A>
<U>Function:</U> int <B>obstack_printf</B> <I>(struct obstack *<VAR>obstack</VAR>, const char *<VAR>template</VAR>, ...)</I><P>
This function is similar to <CODE>asprintf</CODE>, except that it uses the
obstack <VAR>obstack</VAR> to allocate the space.  See section <A HREF="library.html#SEC33">Obstacks</A>.
<P>
The characters are written onto the end of the current object.
To get at them, you must finish the object with <CODE>obstack_finish</CODE>
(see section <A HREF="library.html#SEC39">Growing Objects</A>).<P>
<H3><A NAME="SEC137" HREF="library_toc.html#SEC137">Variable Arguments Output Functions</A></H3>
<P>
The functions <CODE>vprintf</CODE> and friends are provided so that you can
define your own variadic <CODE>printf</CODE>-like functions that make use of
the same internals as the built-in formatted output functions.
<P>
The most natural way to define such functions would be to use a language
construct to say, "Call <CODE>printf</CODE> and pass this template plus all
of my arguments after the first five."  But there is no way to do this
in C, and it would be hard to provide a way, since at the C language
level there is no way to tell how many arguments your function received.
<P>
Since that method is impossible, we provide alternative functions, the
<CODE>vprintf</CODE> series, which lets you pass a <CODE>va_list</CODE> to describe
"all of my arguments after the first five."
<P>
Before calling <CODE>vprintf</CODE> or the other functions listed in this
section, you <EM>must</EM> call <CODE>va_start</CODE> (see section <A HREF="library.html#SEC472">Variadic Functions</A>) to initialize a pointer to the variable arguments.  Then you
can call <CODE>va_arg</CODE> to fetch the arguments that you want to handle
yourself.  This advances the pointer past those arguments.
<P>
Once your <CODE>va_list</CODE> pointer is pointing at the argument of your
choice, you are ready to call <CODE>vprintf</CODE>.  That argument and all
subsequent arguments that were passed to your function are used by
<CODE>vprintf</CODE> along with the template that you specified separately.
<P>
In some other systems, the <CODE>va_list</CODE> pointer may become invalid
after the call to <CODE>vprintf</CODE>, so you must not use <CODE>va_arg</CODE>
after you call <CODE>vprintf</CODE>.  Instead, you should call <CODE>va_end</CODE>
to retire the pointer from service.  However, you can safely call
<CODE>va_start</CODE> on another pointer variable and begin fetching the
arguments again through that pointer.  Calling <CODE>vfprintf</CODE> does
not destroy the argument list of your function, merely the particular
pointer that you passed to it.
<P>
The GNU library does not have such restrictions.  You can safely continue
to fetch arguments from a <CODE>va_list</CODE> pointer after passing it to
<CODE>vprintf</CODE>, and <CODE>va_end</CODE> is a no-op.
<P>
Prototypes for these functions are declared in <TT>`stdio.h'</TT>.
<A NAME="IDX495"></A>
<P>
<A NAME="IDX496"></A>
<U>Function:</U> int <B>vprintf</B> <I>(const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</I><P>
This function is similar to <CODE>printf</CODE> except that, instead of taking
a variable number of arguments directly, it takes an argument list
pointer <VAR>ap</VAR>.
<P>
<A NAME="IDX497"></A>
<U>Function:</U> int <B>vfprintf</B> <I>(FILE *<VAR>stream</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</I><P>
This is the equivalent of <CODE>fprintf</CODE> with the variable argument list
specified directly as for <CODE>vprintf</CODE>.
<P>
<A NAME="IDX498"></A>
<U>Function:</U> int <B>vsprintf</B> <I>(char *<VAR>s</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</I><P>
This is the equivalent of <CODE>sprintf</CODE> with the variable argument list
specified directly as for <CODE>vprintf</CODE>.
<P>
<A NAME="IDX499"></A>
<U>Function:</U> int <B>vsnprintf</B> <I>(char *<VAR>s</VAR>, size_t <VAR>size</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</I><P>
This is the equivalent of <CODE>snprintf</CODE> with the variable argument list
specified directly as for <CODE>vprintf</CODE>.
<P>
<A NAME="IDX500"></A>
<U>Function:</U> int <B>vasprintf</B> <I>(char **<VAR>ptr</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</I><P>
The <CODE>vasprintf</CODE> function is the equivalent of <CODE>asprintf</CODE> with the
variable argument list specified directly as for <CODE>vprintf</CODE>.
<P>
<A NAME="IDX501"></A>
<U>Function:</U> int <B>obstack_vprintf</B> <I>(struct obstack *<VAR>obstack</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</I><P>
The <CODE>obstack_vprintf</CODE> function is the equivalent of
<CODE>obstack_printf</CODE> with the variable argument list specified directly
as for <CODE>vprintf</CODE>.<P>
Here's an example showing how you might use <CODE>vfprintf</CODE>.  This is a
function that prints error messages to the stream <CODE>stderr</CODE>, along
with a prefix indicating the name of the program
(see section <A HREF="library.html#SEC17">Error Messages</A>, for a description of 
<CODE>program_invocation_short_name</CODE>).
<P>
<PRE>
#include &#60;stdio.h&#62;
#include &#60;stdarg.h&#62;

void
eprintf (char *template, ...)
{
  va_list ap;
  extern char *program_invocation_short_name;

  fprintf (stderr, "%s: ", program_invocation_short_name);
  va_start (ap, count);
  vfprintf (stderr, template, ap);
  va_end (ap);
}
</PRE>
<P>
You could call <CODE>eprintf</CODE> like this:
<P>
<PRE>
eprintf ("file `%s' does not exist\n", filename);
</PRE>
<P>
<A NAME="IDX502"></A>
<H3><A NAME="SEC138" HREF="library_toc.html#SEC138">Parsing a Template String</A></H3>
<P>
You can use the function <CODE>parse_printf_format</CODE> to obtain
information about the number and types of arguments that are expected by
a given template string.  This function permits interpreters that
provide interfaces to <CODE>printf</CODE> to avoid passing along invalid
arguments from the user's program, which could cause a crash.
<P>
All the symbols described in this section are declared in the header
file <TT>`printf.h'</TT>.
<P>
<A NAME="IDX503"></A>
<U>Function:</U> size_t <B>parse_printf_format</B> <I>(const char *<VAR>template</VAR>, size_t <VAR>n</VAR>, int *<VAR>argtypes</VAR>)</I><P>
This function returns information about the number and types of
arguments expected by the <CODE>printf</CODE> template string <VAR>template</VAR>.
The information is stored in the array <VAR>argtypes</VAR>; each element of
this array describes one argument.  This information is encoded using
the various <SAMP>`PA_'</SAMP> macros, listed below.
<P>
The <VAR>n</VAR> argument specifies the number of elements in the array
<VAR>argtypes</VAR>.  This is the most elements that
<CODE>parse_printf_format</CODE> will try to write.
<P>
<CODE>parse_printf_format</CODE> returns the total number of arguments required
by <VAR>template</VAR>.  If this number is greater than <VAR>n</VAR>, then the
information returned describes only the first <VAR>n</VAR> arguments.  If you
want information about more than that many arguments, allocate a bigger
array and call <CODE>parse_printf_format</CODE> again.
<P>
The argument types are encoded as a combination of a basic type and
modifier flag bits.
<P>
<A NAME="IDX504"></A>
<U>Macro:</U> int <B>PA_FLAG_MASK</B><P>
This macro is a bitmask for the type modifier flag bits.  You can write
the expression <CODE>(argtypes[i] &#38; PA_FLAG_MASK)</CODE> to extract just the
flag bits for an argument, or <CODE>(argtypes[i] &#38; ~PA_FLAG_MASK)</CODE> to
extract just the basic type code.
<P>
Here are symbolic constants that represent the basic types; they stand
for integer values.
<P>
<DL COMPACT>
<A NAME="IDX505"></A>
<DT><CODE>PA_INT</CODE>
<DD>This specifies that the base type is <CODE>int</CODE>.
<P>
<A NAME="IDX506"></A>
<DT><CODE>PA_CHAR</CODE>
<DD>This specifies that the base type is <CODE>int</CODE>, cast to <CODE>char</CODE>.
<P>
<A NAME="IDX507"></A>
<DT><CODE>PA_STRING</CODE>
<DD>This specifies that the base type is <CODE>char *</CODE>, a null-terminated string.
<P>
<A NAME="IDX508"></A>
<DT><CODE>PA_POINTER</CODE>
<DD>This specifies that the base type is <CODE>void *</CODE>, an arbitrary pointer.
<P>
<A NAME="IDX509"></A>
<DT><CODE>PA_FLOAT</CODE>
<DD>This specifies that the base type is <CODE>float</CODE>.
<P>
<A NAME="IDX510"></A>
<DT><CODE>PA_DOUBLE</CODE>
<DD>This specifies that the base type is <CODE>double</CODE>.
<P>
<A NAME="IDX511"></A>
<DT><CODE>PA_LAST</CODE>
<DD>You can define additional base types for your own programs as offsets
from <CODE>PA_LAST</CODE>.  For example, if you have data types <SAMP>`foo'</SAMP>
and <SAMP>`bar'</SAMP> with their own specialized <CODE>printf</CODE> conversions,
you could define encodings for these types as:
<P>
<PRE>
#define PA_FOO  PA_LAST
#define PA_BAR  (PA_LAST + 1)
</PRE>
</DL>
<P>
Here are the flag bits that modify a basic type.  They are combined with
the code for the basic type using inclusive-or.
<P>
<DL COMPACT>
<A NAME="IDX512"></A>
<DT><CODE>PA_FLAG_PTR</CODE>
<DD>If this bit is set, it indicates that the encoded type is a pointer to
the base type, rather than an immediate value.
For example, <SAMP>`PA_INT|PA_FLAG_PTR'</SAMP> represents the type <SAMP>`int *'</SAMP>.
<P>
<A NAME="IDX513"></A>
<DT><CODE>PA_FLAG_SHORT</CODE>
<DD>If this bit is set, it indicates that the base type is modified with
<CODE>short</CODE>.  (This corresponds to the <SAMP>`h'</SAMP> type modifier.)
<P>
<A NAME="IDX514"></A>
<DT><CODE>PA_FLAG_LONG</CODE>
<DD>If this bit is set, it indicates that the base type is modified with
<CODE>long</CODE>.  (This corresponds to the <SAMP>`l'</SAMP> type modifier.)
<P>
<A NAME="IDX515"></A>
<DT><CODE>PA_FLAG_LONG_LONG</CODE>
<DD>If this bit is set, it indicates that the base type is modified with
<CODE>long long</CODE>.  (This corresponds to the <SAMP>`L'</SAMP> type modifier.)
<P>
<A NAME="IDX516"></A>
<DT><CODE>PA_FLAG_LONG_DOUBLE</CODE>
<DD>This is a synonym for <CODE>PA_FLAG_LONG_LONG</CODE>, used by convention with
a base type of <CODE>PA_DOUBLE</CODE> to indicate a type of <CODE>long double</CODE>.
</DL>
<P>
<H3><A NAME="SEC139" HREF="library_toc.html#SEC139">Example of Parsing a Template String</A></H3>
<P>
Here is an example of decoding argument types for a format string.  We
assume this is part of an interpreter which contains arguments of type
<CODE>NUMBER</CODE>, <CODE>CHAR</CODE>, <CODE>STRING</CODE> and <CODE>STRUCTURE</CODE> (and
perhaps others which are not valid here).
<P>
<PRE>
/* Test whether the <VAR>nargs</VAR> specified objects
   in the vector <VAR>args</VAR> are valid
   for the format string <VAR>format</VAR>:
   if so, return 1.
   If not, return 0 after printing an error message.  */

int
validate_args (char *format, int nargs, OBJECT *args)
{
  int nelts = 20;
  int *argtypes;
  int nwanted;

  /* Get the information about the arguments.  */
  while (1) {
    argtypes = (int *) alloca (nelts * sizeof (int));
    nwanted = parse_printf_format (string, nelts, argtypes);
    if (nwanted &#60;= nelts)
      break;
    nelts *= 2;
  }

  /* Check the number of arguments.  */
  if (nwanted &#62; nargs) {
    error ("too few arguments (at least %d required)", nwanted);
    return 0;
  }
    
  /* Check the C type wanted for each argument
     and see if the object given is suitable.  */
  for (i = 0; i &#60; nwanted; i++) {
    int wanted;

    if (argtypes[i] &#38; PA_FLAG_PTR)
      wanted = STRUCTURE;
    else
      switch (argtypes[i] &#38; ~PA_FLAG_MASK) {
      case PA_INT:
      case PA_FLOAT:
      case PA_DOUBLE:
        wanted = NUMBER;
        break;
      case PA_CHAR:
        wanted = CHAR;
        break;
      case PA_STRING:
        wanted = STRING;
        break;
      case PA_POINTER:
        wanted = STRUCTURE;
        break;
      }
    if (TYPE (args[i]) != wanted) {
      error ("type mismatch for arg number %d", i);
      return 0;
    }
  }
  return 1;
}
</PRE>
<P>
<A NAME="IDX517"></A>
<A NAME="IDX518"></A>
<A NAME="IDX519"></A>
<H2><A NAME="SEC140" HREF="library_toc.html#SEC140">Customizing <CODE>printf</CODE></A></H2>
<P>
The GNU C library lets you define your own custom conversion specifiers
for <CODE>printf</CODE> template strings, to teach <CODE>printf</CODE> clever ways
to print the important data structures of your program.
<P>
The way you do this is by registering the conversion with
<CODE>register_printf_function</CODE>; see section <A HREF="library.html#SEC141">Registering New Conversions</A>.
One of the arguments you pass to this function is a pointer to a handler
function that produces the actual output; see section <A HREF="library.html#SEC143">Defining the Output Handler</A>, for information on how to write this function.
<P>
You can also install a function that just returns information about the
number and type of arguments expected by the conversion specifier.
See section <A HREF="library.html#SEC138">Parsing a Template String</A>, for information about this.
<P>
The facilities of this section are declared in the header file
<TT>`printf.h'</TT>.
<P>
<STRONG>Portability Note:</STRONG> The ability to extend the syntax of
<CODE>printf</CODE> template strings is a GNU extension.  ANSI standard C has
nothing similar.
<P>
<H3><A NAME="SEC141" HREF="library_toc.html#SEC141">Registering New Conversions</A></H3>
<P>
The function to register a new output conversion is
<CODE>register_printf_function</CODE>, declared in <TT>`printf.h'</TT>.
<A NAME="IDX520"></A>
<P>
<A NAME="IDX521"></A>
<U>Function:</U> int <B>register_printf_function</B> <I>(int <VAR>spec</VAR>, printf_function <VAR>handler_function</VAR>, printf_arginfo_function <VAR>arginfo_function</VAR>)</I><P>
This function defines the conversion specifier character <VAR>spec</VAR>.
Thus, if <VAR>spec</VAR> is <CODE>'q'</CODE>, it defines the conversion <SAMP>`%q'</SAMP>.
<P>
The <VAR>handler_function</VAR> is the function called by <CODE>printf</CODE> and
friends when this conversion appears in a template string.
See section <A HREF="library.html#SEC143">Defining the Output Handler</A>, for information about how to define
a function to pass as this argument.  If you specify a null pointer, any
existing handler function for <VAR>spec</VAR> is removed.
<P>
The <VAR>arginfo_function</VAR> is the function called by
<CODE>parse_printf_format</CODE> when this conversion appears in a
template string.  See section <A HREF="library.html#SEC138">Parsing a Template String</A>, for information
about this.
<P>
Normally, you install both functions for a conversion at the same time,
but if you are never going to call <CODE>parse_printf_format</CODE>, you do
not need to define an arginfo function.
<P>
The return value is <CODE>0</CODE> on success, and <CODE>-1</CODE> on failure
(which occurs if <VAR>spec</VAR> is out of range).
<P>
You can redefine the standard output conversions, but this is probably
not a good idea because of the potential for confusion.  Library routines
written by other people could break if you do this.
<P>
<H3><A NAME="SEC142" HREF="library_toc.html#SEC142">Conversion Specifier Options</A></H3>
<P>
If you define a meaning for <SAMP>`%q'</SAMP>, what if the template contains
<SAMP>`%+Sq'</SAMP> or <SAMP>`%-#q'</SAMP>?  To implement a sensible meaning for these,
the handler when called needs to be able to get the options specified in
the template.
<P>
Both the <VAR>handler_function</VAR> and <VAR>arginfo_function</VAR> arguments
to <CODE>register_printf_function</CODE> accept an argument of type
<CODE>struct print_info</CODE>, which contains information about the options
appearing in an instance of the conversion specifier.  This data type
is declared in the header file <TT>`printf.h'</TT>.
<A NAME="IDX522"></A>
<P>
<A NAME="IDX523"></A>
<U>Type:</U> <B>struct printf_info</B><P>
This structure is used to pass information about the options appearing
in an instance of a conversion specifier in a <CODE>printf</CODE> template
string to the handler and arginfo functions for that specifier.  It
contains the following members:
<P>
<DL COMPACT>
<DT><CODE>int prec</CODE>
<DD>This is the precision specified.  The value is <CODE>-1</CODE> if no precision
was specified.  If the precision was given as <SAMP>`*'</SAMP>, the
<CODE>printf_info</CODE> structure passed to the handler function contains the
actual value retrieved from the argument list.  But the structure passed
to the arginfo function contains a value of <CODE>INT_MIN</CODE>, since the
actual value is not known.
<P>
<DT><CODE>int width</CODE>
<DD>This is the minimum field width specified.  The value is <CODE>0</CODE> if no
width was specified.  If the field width was given as <SAMP>`*'</SAMP>, the
<CODE>printf_info</CODE> structure passed to the handler function contains the
actual value retrieved from the argument list.  But the structure passed
to the arginfo function contains a value of <CODE>INT_MIN</CODE>, since the
actual value is not known.
<P>
<DT><CODE>char spec</CODE>
<DD>This is the conversion specifier character specified.  It's stored in
the structure so that you can register the same handler function for
multiple characters, but still have a way to tell them apart when the
handler function is called.
<P>
<DT><CODE>unsigned int is_long_double</CODE>
<DD>This is a boolean that is true if the <SAMP>`L'</SAMP> type modifier was specified.
<P>
<DT><CODE>unsigned int is_short</CODE>
<DD>This is a boolean that is true if the <SAMP>`h'</SAMP> type modifier was specified.
<P>
<DT><CODE>unsigned int is_long</CODE>
<DD>This is a boolean that is true if the <SAMP>`l'</SAMP> type modifier was specified.
<P>
<DT><CODE>unsigned int alt</CODE>
<DD>This is a boolean that is true if the <SAMP>`#'</SAMP> flag was specified.
<P>
<DT><CODE>unsigned int space</CODE>
<DD>This is a boolean that is true if the <SAMP>` '</SAMP> flag was specified.
<P>
<DT><CODE>unsigned int left</CODE>
<DD>This is a boolean that is true if the <SAMP>`-'</SAMP> flag was specified.
<P>
<DT><CODE>unsigned int showsign</CODE>
<DD>This is a boolean that is true if the <SAMP>`+'</SAMP> flag was specified.
<P>
<DT><CODE>char pad</CODE>
<DD>This is the character to use for padding the output to the minimum field
width.  The value is <CODE>'0'</CODE> if the <SAMP>`0'</SAMP> flag was specified, and
<CODE>' '</CODE> otherwise.
</DL>
<P>
<H3><A NAME="SEC143" HREF="library_toc.html#SEC143">Defining the Output Handler</A></H3>
<P>
Now let's look at how to define the handler and arginfo functions
which are passed as arguments to <CODE>register_printf_function</CODE>.
<P>
You should define your handler functions with a prototype like:
<P>
<PRE>
int <VAR>function</VAR> (FILE *stream, const struct printf_info *info,
                    va_list *ap_pointer)
</PRE>
<P>
The <CODE>stream</CODE> argument passed to the handler function is the stream to
which it should write output.
<P>
The <CODE>info</CODE> argument is a pointer to a structure that contains
information about the various options that were included with the
conversion in the template string.  You should not modify this structure
inside your handler function.  See section <A HREF="library.html#SEC142">Conversion Specifier Options</A>, for
a description of this data structure.
<P>
The <CODE>ap_pointer</CODE> argument is used to pass the tail of the variable
argument list containing the values to be printed to your handler.
Unlike most other functions that can be passed an explicit variable
argument list, this is a <EM>pointer</EM> to a <CODE>va_list</CODE>, rather than
the <CODE>va_list</CODE> itself.  Thus, you should fetch arguments by
means of <CODE>va_arg (<VAR>type</VAR>, *ap_pointer)</CODE>.
<P>
(Passing a pointer here allows the function that calls your handler
function to update its own <CODE>va_list</CODE> variable to account for the
arguments that your handler processes.  See section <A HREF="library.html#SEC472">Variadic Functions</A>.)
<P>
The return value from your handler function should be the number of
argument values that it processes from the variable argument list.  You
can also return a value of <CODE>-1</CODE> to indicate an error.
<P>
<A NAME="IDX524"></A>
<U>Data Type:</U> <B>printf_function</B><P>
This is the data type that a handler function should have.
<P>
If you are going to use <CODE>parse_printf_format</CODE> in your
application, you should also define a function to pass as the
<VAR>arginfo_function</VAR> argument for each new conversion you install with
<CODE>register_printf_function</CODE>. 
<P>
You should define these functions with a prototype like:
<P>
<PRE>
int <VAR>function</VAR> (const struct printf_info *info,
                    size_t n, int *argtypes)
</PRE>
<P>
The return value from the function should be the number of arguments the
conversion expects, up to a maximum of <VAR>n</VAR>.  The function should
also fill in the <VAR>argtypes</VAR> array with information about the types
of each of these arguments.  This information is encoded using the
various <SAMP>`PA_'</SAMP> macros.  (You will notice that this is the same
calling convention <CODE>parse_printf_format</CODE> itself uses.)
<P>
<A NAME="IDX525"></A>
<U>Data Type:</U> <B>printf_arginfo_function</B><P>
This type is used to describe functions that return information about
the number and type of arguments used by a conversion specifier.
<P>
<H3><A NAME="SEC144" HREF="library_toc.html#SEC144"><CODE>printf</CODE> Extension Example</A></H3>
<P>
Here is an example showing how to define a <CODE>printf</CODE> handler function.
This program defines a data structure called a <CODE>Widget</CODE> and 
defines the <SAMP>`%W'</SAMP> conversion to print information about <CODE>Widget *</CODE>
arguments, including the pointer value and the name stored in the data
structure.  The <SAMP>`%W'</SAMP> conversion supports the minimum field width and
left-justification options, but ignores everything else.
<P>
<PRE>
#include &#60;stdio.h&#62;
#include &#60;printf.h&#62;
#include &#60;stdarg.h&#62;

typedef struct
  {
    char *name;
  } Widget;

int 
print_widget (FILE *stream, const struct printf_info *info, va_list *app)
{
  Widget *w;
  char *buffer;
  int len;

  /* Format the output into a string.  */
  w = va_arg (*app, Widget *);
  len = asprintf (&#38;buffer, "&#60;Widget %p: %s&#62;", w, w-&#62;name);
  if (len == -1)
    return -1;

  /* Pad to the minimum field width and print to the stream.  */
  len = fprintf (stream, "%*s",
		 (info-&#62;left ? - info-&#62;width : info-&#62;width),
		 buffer);

  /* Clean up and return.  */
  free (buffer);
  return len;
}


int
main (void)
{
  /* Make a widget to print.  */
  Widget mywidget;
  mywidget.name = "mywidget";

  /* Register the print function for widgets.  */
  register_printf_function ('W', print_widget, NULL); /* No arginfo.   */

  /* Now print the widget.  */
  printf ("|%W|\n", &#38;mywidget);
  printf ("|%35W|\n", &#38;mywidget);
  printf ("|%-35W|\n", &#38;mywidget);

  return 0;
}
</PRE>
<P>
The output produced by this program looks like:
<P>
<PRE>
|&#60;Widget 0xffeffb7c: mywidget&#62;|
|      &#60;Widget 0xffeffb7c: mywidget&#62;|
|&#60;Widget 0xffeffb7c: mywidget&#62;      |
</PRE>
<P>
<H2><A NAME="SEC145" HREF="library_toc.html#SEC145">Formatted Input</A></H2>
<A NAME="IDX526"></A>
<A NAME="IDX527"></A>
<A NAME="IDX528"></A>
<A NAME="IDX529"></A>
<P>
The functions described in this section (<CODE>scanf</CODE> and related
functions) provide facilities for formatted input analogous to the
formatted output facilities.  These functions provide a mechanism for
reading arbitrary values under the control of a <DFN>format string</DFN> or
<DFN>template string</DFN>.
<P>
<H3><A NAME="SEC146" HREF="library_toc.html#SEC146">Formatted Input Basics</A></H3>
<P>
Calls to <CODE>scanf</CODE> are superficially similar to calls to
<CODE>printf</CODE> in that arbitrary arguments are read under the control of
a template string.  While the syntax of the conversion specifications in
the template is very similar to that for <CODE>printf</CODE>, the
interpretation of the template is oriented more towards free-format
input and simple pattern matching, rather than fixed-field formatting.
For example, most <CODE>scanf</CODE> conversions skip over any amount of
"white space" (including spaces, tabs, and newlines) in the input
file, and there is no concept of precision for the numeric input
conversions as there is for the corresponding output conversions.
Ordinarily, non-whitespace characters in the template are expected to
match characters in the input stream exactly, but a matching failure is
distinct from an input error on the stream.
<A NAME="IDX530"></A>
<P>
Another area of difference between <CODE>scanf</CODE> and <CODE>printf</CODE> is
that you must remember to supply pointers rather than immediate values
as the optional arguments to <CODE>scanf</CODE>; the values that are read are
stored in the objects that the pointers point to.  Even experienced
programmers tend to forget this occasionally, so if your program is
getting strange errors that seem to be related to <CODE>scanf</CODE>, you
might want to double-check this.
<P>
When a <DFN>matching failure</DFN> occurs, <CODE>scanf</CODE> returns immediately,
leaving the first non-matching character as the next character to be
read from the stream.  The normal return value from <CODE>scanf</CODE> is the
number of values that were assigned, so you can use this to determine if
a matching error happened before all the expected values were read.
<A NAME="IDX531"></A>
<P>
The <CODE>scanf</CODE> function is typically used for things like reading in
the contents of tables.  For example, here is a function that uses
<CODE>scanf</CODE> to initialize an array of <CODE>double</CODE>:
<P>
<PRE>
void
readarray (double *array, int n)
{
  int i;
  for (i=0; i&#60;n; i++)
    if (scanf (" %lf", &#38;(array[i])) != 1)
      invalid_input_error ();
}
</PRE>
<P>
The formatted input functions are not used as frequently as the
formatted output functions.  Partly, this is because it takes some care
to use them properly.  Another reason is that it is difficult to recover
from a matching error.
<P>
If you are trying to read input that doesn't match a single, fixed
pattern, you may be better off using a tool such as Bison to generate a
parser, rather than using <CODE>scanf</CODE>.  For more information about
this, see section 'Bison' in <CITE>The Bison Reference Manual</CITE>.
<P>
<H3><A NAME="SEC147" HREF="library_toc.html#SEC147">Input Conversion Syntax</A></H3>
<P>
A <CODE>scanf</CODE> template string is a string that contains ordinary
multibyte characters interspersed with conversion specifications that
start with <SAMP>`%'</SAMP>.
<P>
Any whitespace character (as defined by the <CODE>isspace</CODE> function;
see section <A HREF="library.html#SEC55">Classification of Characters</A>) in the template causes any number
of whitespace characters in the input stream to be read and discarded.
The whitespace characters that are matched need not be exactly the same
whitespace characters that appear in the template string.  For example,
write <SAMP>` , '</SAMP> in the template to recognize a comma with optional
whitespace before and after.
<P>
Other characters in the template string that are not part of conversion
specifications must match characters in the input stream exactly; if
this is not the case, a matching failure occurs.
<P>
The conversion specifications in a <CODE>scanf</CODE> template string
have the general form:
<P>
<PRE>
% <VAR>flags</VAR> <VAR>width</VAR> <VAR>type</VAR> <VAR>conversion</VAR>
</PRE>
<P>
In more detail, an input conversion specification consists of an initial
<SAMP>`%'</SAMP> character followed in sequence by:
<P>
<UL>
<LI>
An optional <DFN>flag character</DFN> <SAMP>`*'</SAMP>, which says to ignore the text
read for this specification.  When <CODE>scanf</CODE> finds a conversion
specification that uses this flag, it reads input as directed by the
rest of the conversion specification, but it discards this input, does
not use a pointer argument, and does not increment the count of
successful assignments.
<A NAME="IDX532"></A>
<P>
<LI>
An optional flag character <SAMP>`a'</SAMP> (valid with string conversions only)
which requests allocation of a buffer long enough to store the string in.
See section <A HREF="library.html#SEC151">Dynamically Allocating String Conversions</A>.
<P>
<LI>
An optional decimal integer that specifies the <DFN>maximum field
width</DFN>.  Reading of characters from the input stream stops either when
this maximum is reached or when a non-matching character is found,
whichever happens first.  Most conversions discard initial whitespace
characters (those that don't are explicitly documented), and these
discarded characters don't count towards the maximum field width.
Most input conversions store a null character to mark the end of the
input; the maximum field width does not include this terminator.
<A NAME="IDX533"></A>
<P>
<LI>
An optional <DFN>type modifier character</DFN>.  For example, you can
specify a type modifier of <SAMP>`l'</SAMP> with integer conversions such as
<SAMP>`%d'</SAMP> to specify that the argument is a pointer to a <CODE>long int</CODE>
rather than a pointer to an <CODE>int</CODE>.
<A NAME="IDX534"></A>
<P>
<LI>
A character that specifies the conversion to be applied.
</UL>
<P>
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 allow.
<P>
<A NAME="IDX535"></A>
<H3><A NAME="SEC148" HREF="library_toc.html#SEC148">Table of Input Conversions</A></H3>
<P>
Here is a table that summarizes the various conversion specifications:
<P>
<DL COMPACT>
<DT><SAMP>`%d'</SAMP>
<DD>Matches an optionally signed integer written in decimal.  See section <A HREF="library.html#SEC149">Numeric Input Conversions</A>.
<P>
<DT><SAMP>`%i'</SAMP>
<DD>Matches an optionally signed integer in any of the formats that the C
language defines for specifying an integer constant.  See section <A HREF="library.html#SEC149">Numeric Input Conversions</A>.
<P>
<DT><SAMP>`%o'</SAMP>
<DD>Matches an unsigned integer in octal radix.  See section <A HREF="library.html#SEC149">Numeric Input Conversions</A>.
<P>
<DT><SAMP>`%u'</SAMP>
<DD>Matches an unsigned integer in decimal radix.  See section <A HREF="library.html#SEC149">Numeric Input Conversions</A>.
<P>
<DT><SAMP>`%x'</SAMP>, <SAMP>`%X'</SAMP>
<DD>Matches an unsigned integer in hexadecimal radix.  See section <A HREF="library.html#SEC149">Numeric Input Conversions</A>.
<P>
<DT><SAMP>`%e'</SAMP>, <SAMP>`%f'</SAMP>, <SAMP>`%g'</SAMP>, <SAMP>`%E'</SAMP>, <SAMP>`%G'</SAMP>
<DD>Matches an optionally signed floating-point number.  See section <A HREF="library.html#SEC149">Numeric Input Conversions</A>.
<P>
<DT><SAMP>`%s'</SAMP>
<DD>Matches a string of non-whitespace characters.  See section <A HREF="library.html#SEC150">String Input Conversions</A>.
<P>
<DT><SAMP>`%['</SAMP>
<DD>Matches a string of characters that belong to a specified set.
See section <A HREF="library.html#SEC150">String Input Conversions</A>.
<P>
<DT><SAMP>`%c'</SAMP>
<DD>Matches a string of one or more characters; the number of characters
read is controlled by the maximum field width given for the conversion.
See section <A HREF="library.html#SEC150">String Input Conversions</A>.
<P>
<DT><SAMP>`%p'</SAMP>
<DD>Matches a pointer value in the same implementation-defined format used
by the <SAMP>`%p'</SAMP> output conversion for <CODE>printf</CODE>.  See section <A HREF="library.html#SEC152">Other Input Conversions</A>.
<P>
<DT><SAMP>`%n'</SAMP>
<DD>This conversion doesn't read any characters; it records the number of
characters read so far by this call.  See section <A HREF="library.html#SEC152">Other Input Conversions</A>.
<P>
<DT><SAMP>`%%'</SAMP>
<DD>This matches a literal <SAMP>`%'</SAMP> character in the input stream.  No
corresponding argument is used.  See section <A HREF="library.html#SEC152">Other Input Conversions</A>.
</DL>
<P>
If the syntax of a conversion specification is invalid, the behavior is
undefined.  If there aren't enough function arguments provided to supply
addresses for all the conversion specifications in the template strings
that perform assignments, or if the arguments are not of the correct
types, the behavior is also undefined.  On the other hand, extra
arguments are simply ignored.
<P>
<H3><A NAME="SEC149" HREF="library_toc.html#SEC149">Numeric Input Conversions</A></H3>
<P>
This section describes the <CODE>scanf</CODE> conversions for reading numeric
values.
<P>
The <SAMP>`%d'</SAMP> conversion matches an optionally signed integer in decimal
radix.  The syntax that is recognized is the same as that for the
<CODE>strtol</CODE> function (see section <A HREF="library.html#SEC307">Parsing of Integers</A>) with the value
<CODE>10</CODE> for the <VAR>base</VAR> argument.
<P>
The <SAMP>`%i'</SAMP> conversion matches an optionally signed integer in any of
the formats that the C language defines for specifying an integer
constant.  The syntax that is recognized is the same as that for the
<CODE>strtol</CODE> function (see section <A HREF="library.html#SEC307">Parsing of Integers</A>) with the value
<CODE>0</CODE> for the <VAR>base</VAR> argument.
<P>
For example, any of the strings <SAMP>`10'</SAMP>, <SAMP>`0xa'</SAMP>, or <SAMP>`012'</SAMP>
could be read in as integers under the <SAMP>`%i'</SAMP> conversion.  Each of
these specifies a number with decimal value <CODE>10</CODE>.
<P>
The <SAMP>`%o'</SAMP>, <SAMP>`%u'</SAMP>, and <SAMP>`%x'</SAMP> conversions match unsigned
integers in octal, decimal, and hexadecimal radices, respectively.  The
syntax that is recognized is the same as that for the <CODE>strtoul</CODE>
function (see section <A HREF="library.html#SEC307">Parsing of Integers</A>) with the appropriate value
(<CODE>8</CODE>, <CODE>10</CODE>, or <CODE>16</CODE>) for the <VAR>base</VAR> argument.
<P>
The <SAMP>`%X'</SAMP> conversion is identical to the <SAMP>`%x'</SAMP> conversion.  They
both permit either uppercase or lowercase letters to be used as digits.
<P>
The default type of the corresponding argument for the <CODE>%d</CODE> and
<CODE>%i</CODE> conversions is <CODE>int *</CODE>, and <CODE>unsigned int *</CODE> for the
other integer conversions.  You can use the following type modifiers to
specify other sizes of integer:
<P>
<DL COMPACT>
<DT><SAMP>`h'</SAMP>
<DD>Specifies that the argument is a <CODE>short int *</CODE> or <CODE>unsigned
short int *</CODE>.
<P>
<DT><SAMP>`l'</SAMP>
<DD>Specifies that the argument is a <CODE>long int *</CODE> or <CODE>unsigned
long int *</CODE>.
<P>
<DT><SAMP>`L'</SAMP>
<DD>Specifies that the argument is a <CODE>long long int *</CODE> or <CODE>unsigned long long int *</CODE>.  (The <CODE>long long</CODE> type is an extension supported by the
GNU C compiler.  For systems that don't provide extra-long integers, this
is the same as <CODE>long int</CODE>.)
</DL>
<P>
All of the <SAMP>`%e'</SAMP>, <SAMP>`%f'</SAMP>, <SAMP>`%g'</SAMP>, <SAMP>`%E'</SAMP>, and <SAMP>`%G'</SAMP>
input conversions are interchangeable.  They all match an optionally
signed floating point number, in the same syntax as for the
<CODE>strtod</CODE> function (see section <A HREF="library.html#SEC308">Parsing of Floats</A>).
<P>
For the floating-point input conversions, the default argument type is
<CODE>float *</CODE>.  (This is different from the corresponding output
conversions, where the default type is <CODE>double</CODE>; remember that
<CODE>float</CODE> arguments to <CODE>printf</CODE> are converted to <CODE>double</CODE>
by the default argument promotions, but <CODE>float *</CODE> arguments are
not promoted to <CODE>double *</CODE>.)  You can specify other sizes of float
using these type modifiers:
<P>
<DL COMPACT>
<DT><SAMP>`l'</SAMP>
<DD>Specifies that the argument is of type <CODE>double *</CODE>.
<P>
<DT><SAMP>`L'</SAMP>
<DD>Specifies that the argument is of type <CODE>long double *</CODE>.
</DL>
<P>
<H3><A NAME="SEC150" HREF="library_toc.html#SEC150">String Input Conversions</A></H3>
<P>
This section describes the <CODE>scanf</CODE> input conversions for reading
string and character values: <SAMP>`%s'</SAMP>, <SAMP>`%['</SAMP>, and <SAMP>`%c'</SAMP>.  
<P>
You have two options for how to receive the input from these
conversions:
<P>
<UL>
<LI>
Provide a buffer to store it in.  This is the default.  You
should provide an argument of type <CODE>char *</CODE>.
<P>
<STRONG>Warning:</STRONG> To make a robust program, you must make sure that the
input (plus its terminating null) cannot possibly exceed the size of the
buffer you provide.  In general, the only way to do this is to specify a
maximum field width one less than the buffer size.  <STRONG>If you
provide the buffer, always specify a maximum field width to prevent
overflow.</STRONG>
<P>
<LI>
Ask <CODE>scanf</CODE> to allocate a big enough buffer, by specifying the
<SAMP>`a'</SAMP> flag character.  This is a GNU extension.  You should provide
an argument of type <CODE>char **</CODE> for the buffer address to be stored
in.  See section <A HREF="library.html#SEC151">Dynamically Allocating String Conversions</A>.
</UL>
<P>
The <SAMP>`%c'</SAMP> conversion is the simplest: it matches a fixed number of
characters, always.  The maximum field with says how many characters to
read; if you don't specify the maximum, the default is 1.  This
conversion doesn't append a null character to the end of the text it
reads.  It also does not skip over initial whitespace characters.  It
reads precisely the next <VAR>n</VAR> characters, and fails if it cannot get
that many.  Since there is always a maximum field width with <SAMP>`%c'</SAMP>
(whether specified, or 1 by default), you can always prevent overflow by
making the buffer long enough.
<P>
The <SAMP>`%s'</SAMP> conversion matches a string of non-whitespace characters.
It skips and discards initial whitespace, but stops when it encounters
more whitespace after having read something.  It stores a null character
at the end of the text that it reads.
<P>
For example, reading the input:
<P>
<PRE>
 hello, world
</PRE>
<P>
with the conversion <SAMP>`%10c'</SAMP> produces <CODE>" hello, wo"</CODE>, but
reading the same input with the conversion <SAMP>`%10s'</SAMP> produces
<CODE>"hello,"</CODE>.
<P>
<STRONG>Warning:</STRONG> If you do not specify a field width for <SAMP>`%s'</SAMP>,
then the number of characters read is limited only by where the next
whitespace character appears.  This almost certainly means that invalid
input can make your program crash--which is a bug.
<P>
To read in characters that belong to an arbitrary set of your choice,
use the <SAMP>`%['</SAMP> conversion.  You specify the set between the <SAMP>`['</SAMP>
character and a following <SAMP>`]'</SAMP> character, using the same syntax used
in regular expressions.  As special cases:
<P>
<UL>
<LI>
A literal <SAMP>`]'</SAMP> character can be specified as the first character
of the set.
<P>
<LI>
An embedded <SAMP>`-'</SAMP> character (that is, one that is not the first or
last character of the set) is used to specify a range of characters.
<P>
<LI>
If a caret character <SAMP>`^'</SAMP> immediately follows the initial <SAMP>`['</SAMP>,
then the set of allowed input characters is the everything <EM>except</EM>
the characters listed.
</UL>
<P>
The <SAMP>`%['</SAMP> conversion does not skip over initial whitespace
characters.
<P>
Here are some examples of <SAMP>`%['</SAMP> conversions and what they mean:
<P>
<DL COMPACT>
<DT><SAMP>`%25[1234567890]'</SAMP>
<DD>Matches a string of up to 25 digits.
<P>
<DT><SAMP>`%25[][]'</SAMP>
<DD>Matches a string of up to 25 square brackets.
<P>
<DT><SAMP>`%25[^ \f\n\r\t\v]'</SAMP>
<DD>Matches a string up to 25 characters long that doesn't contain any of
the standard whitespace characters.  This is slightly different from
<SAMP>`%s'</SAMP>, because if the input begins with a whitespace character,
<SAMP>`%['</SAMP> reports a matching failure while <SAMP>`%s'</SAMP> simply discards the
initial whitespace.
<P>
<DT><SAMP>`%25[a-z]'</SAMP>
<DD>Matches up to 25 lowercase characters.
</DL>
<P>
One more reminder: the <SAMP>`%s'</SAMP> and <SAMP>`%['</SAMP> conversions are
<STRONG>dangerous</STRONG> if you don't specify a maximum width or use the
<SAMP>`a'</SAMP> flag, because input too long would overflow whatever buffer you
have provided for it.  No matter how long your buffer is, a user could
supply input that is longer.  A well-written program reports invalid
input with a comprehensible error message, not with a crash.
<P>
<H3><A NAME="SEC151" HREF="library_toc.html#SEC151">Dynamically Allocating String Conversions</A></H3>
<P>
A GNU extension to formatted input lets you safely read a string with no
maximum size.  Using this feature, you don't supply a buffer; instead,
<CODE>scanf</CODE> allocates a buffer big enough to hold the data and gives
you its address.  To use this feature, write <SAMP>`a'</SAMP> as a flag
character, as in <SAMP>`%as'</SAMP> or <SAMP>`%a[0-9a-z]'</SAMP>.
<P>
The pointer argument you supply for where to store the input should have
type <CODE>char **</CODE>.  The <CODE>scanf</CODE> function allocates a buffer and
stores its address in the word that the argument points to.  You should
free the buffer with <CODE>free</CODE> when you no longer need it.
<P>
Here is an example of using the <SAMP>`a'</SAMP> flag with the <SAMP>`%[...]'</SAMP>
conversion specification to read a "variable assignment" of the form
<SAMP>`<VAR>variable</VAR> = <VAR>value</VAR>'</SAMP>.
<P>
<PRE>
{
  char *variable, *value;

  if (2 &#62; scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
                 &#38;variable, &#38;value))
    {
      invalid_input_error ();
      return 0;
    }

  ...
}
</PRE>
<P>
<H3><A NAME="SEC152" HREF="library_toc.html#SEC152">Other Input Conversions</A></H3>
<P>
This section describes the miscellaneous input conversions.
<P>
The <SAMP>`%p'</SAMP> conversion is used to read a pointer value.  It recognizes
the same syntax as is used by the <SAMP>`%p'</SAMP> output conversion for
<CODE>printf</CODE>.  The corresponding argument should be of type <CODE>void **</CODE>;
that is, the address of a place to store a pointer.
<P>
The resulting pointer value is not guaranteed to be valid if it was not
originally written during the same program execution that reads it in.
<P>
The <SAMP>`%n'</SAMP> conversion produces the number of characters read so far
by this call.  The corresponding argument should be of type <CODE>int *</CODE>.
This conversion works in the same way as the <SAMP>`%n'</SAMP> conversion for
<CODE>printf</CODE>; see section <A HREF="library.html#SEC134">Other Output Conversions</A>, for an example.
<P>
The <SAMP>`%n'</SAMP> conversion is the only mechanism for determining the
success of literal matches or conversions with suppressed assignments.
If the <SAMP>`%n'</SAMP> follows the locus of a matching failure, then no value
is stored for it since <CODE>scanf</CODE> returns before processing the
<SAMP>`%n'</SAMP>.  If you store <CODE>-1</CODE> in that argument slot before calling
<CODE>scanf</CODE>, the presence of <CODE>-1</CODE> after <CODE>scanf</CODE> indicates an
error occurred before the <SAMP>`%n'</SAMP> was reached.
<P>
Finally, the <SAMP>`%%'</SAMP> conversion matches a literal <SAMP>`%'</SAMP> character
in the input stream, without using an argument.  This conversion does
not permit any flags, field width, or type modifier to be specified.
<P>
<H3><A NAME="SEC153" HREF="library_toc.html#SEC153">Formatted Input Functions</A></H3>
<P>
Here are the descriptions of the functions for performing formatted
input.
Prototypes for these functions are in the header file <TT>`stdio.h'</TT>.
<A NAME="IDX536"></A>
<P>
<A NAME="IDX537"></A>
<U>Function:</U> int <B>scanf</B> <I>(const char *<VAR>template</VAR>, ...)</I><P>
The <CODE>scanf</CODE> function reads formatted input from the stream
<CODE>stdin</CODE> under the control of the template string <VAR>template</VAR>.
The optional arguments are pointers to the places which receive the
resulting values.
<P>
The return value is normally the number of successful assignments.  If
an end-of-file condition is detected before any matches are performed
(including matches against whitespace and literal characters in the
template), then <CODE>EOF</CODE> is returned.
<P>
<A NAME="IDX538"></A>
<U>Function:</U> int <B>fscanf</B> <I>(FILE *<VAR>stream</VAR>, const char *<VAR>template</VAR>, ...)</I><P>
This function is just like <CODE>scanf</CODE>, except that the input is read
from the stream <VAR>stream</VAR> instead of <CODE>stdin</CODE>.
<P>
<A NAME="IDX539"></A>
<U>Function:</U> int <B>sscanf</B> <I>(const char *<VAR>s</VAR>, const char *<VAR>template</VAR>, ...)</I><P>
This is like <CODE>scanf</CODE>, except that the characters are taken from the
null-terminated string <VAR>s</VAR> instead of from a stream.  Reaching the
end of the string is treated as an end-of-file condition.
<P>
The behavior of this function is undefined if copying takes place
between objects that overlap--for example, if <VAR>s</VAR> is also given
as an argument to receive a string read under control of the <SAMP>`%s'</SAMP>
conversion.
<P>
<H3><A NAME="SEC154" HREF="library_toc.html#SEC154">Variable Arguments Input Functions</A></H3>
<P>
The functions <CODE>vscanf</CODE> and friends are provided so that you can
define your own variadic <CODE>scanf</CODE>-like functions that make use of
the same internals as the built-in formatted output functions.
These functions are analogous to the <CODE>vprintf</CODE> series of output
functions.  See section <A HREF="library.html#SEC137">Variable Arguments Output Functions</A>, for important
information on how to use them.
<P>
<STRONG>Portability Note:</STRONG> The functions listed in this section are GNU
extensions.
<P>
<A NAME="IDX540"></A>
<U>Function:</U> int <B>vscanf</B> <I>(const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</I><P>
This function is similar to <CODE>scanf</CODE> except that, instead of taking
a variable number of arguments directly, it takes an argument list
pointer <VAR>ap</VAR> of type <CODE>va_list</CODE> (see section <A HREF="library.html#SEC472">Variadic Functions</A>).
<P>
<A NAME="IDX541"></A>
<U>Function:</U> int <B>vfscanf</B> <I>(FILE *<VAR>stream</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</I><P>
This is the equivalent of <CODE>fscanf</CODE> with the variable argument list
specified directly as for <CODE>vscanf</CODE>.
<P>
<A NAME="IDX542"></A>
<U>Function:</U> int <B>vsscanf</B> <I>(const char *<VAR>s</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</I><P>
This is the equivalent of <CODE>sscanf</CODE> with the variable argument list
specified directly as for <CODE>vscanf</CODE>.
<P>
<H2><A NAME="SEC155" HREF="library_toc.html#SEC155">Block Input/Output</A></H2>
<P>
This section describes how to do input and output operations on blocks
of data.  You can use these functions to read and write binary data, as
well as to read and write text in fixed-size blocks instead of by
characters or lines.
<A NAME="IDX544"></A>
<A NAME="IDX545"></A>
<A NAME="IDX546"></A>
<A NAME="IDX543"></A>
<P>
Binary files are typically used to read and write blocks of data in the
same format as is used to represent the data in a running program.  In
other words, arbitrary blocks of memory--not just character or string
objects--can be written to a binary file, and meaningfully read in
again by the same program.
<P>
Storing data in binary form is often considerably more efficient than
using the formatted I/O functions.  Also, for floating-point numbers,
the binary form avoids possible loss of precision in the conversion
process.  On the other hand, binary files can't be examined or modified
easily using many standard file utilities (such as text editors), and
are not portable between different implementations of the language, or
different kinds of computers.
<P>
These functions are declared in <TT>`stdio.h'</TT>.
<A NAME="IDX547"></A>
<P>
<A NAME="IDX548"></A>
<U>Function:</U> size_t <B>fread</B> <I>(void *<VAR>data</VAR>, size_t <VAR>size</VAR>, size_t <VAR>count</VAR>, FILE *<VAR>stream</VAR>)</I><P>
This function reads up to <VAR>count</VAR> objects of size <VAR>size</VAR> into
the array <VAR>data</VAR>, from the stream <VAR>stream</VAR>.  It returns the
number of objects actually read, which might be less than <VAR>count</VAR> if
a read error occurs or the end of the file is reached.  This function
returns a value of zero (and doesn't read anything) if either <VAR>size</VAR>
or <VAR>count</VAR> is zero.
<P>
If <CODE>fread</CODE> encounters end of file in the middle of an object, it
returns the number of complete objects read, and discards the partial
object.  Therefore, the stream remains at the actual end of the file.
<P>
<A NAME="IDX549"></A>
<U>Function:</U> size_t <B>fwrite</B> <I>(const void *<VAR>data</VAR>, size_t <VAR>size</VAR>, size_t <VAR>count</VAR>, FILE *<VAR>stream</VAR>)</I><P>
This function writes up to <VAR>count</VAR> objects of size <VAR>size</VAR> from
the array <VAR>data</VAR>, to the stream <VAR>stream</VAR>.  The return value is
normally <VAR>count</VAR>, if the call succeeds.  Any other value indicates
some sort of error, such as running out of space.
<P>
<H2><A NAME="SEC156" HREF="library_toc.html#SEC156">End-Of-File and Errors</A></H2>
<A NAME="IDX550"></A>
<P>
Many of the functions described in this chapter return the value of the
macro <CODE>EOF</CODE> to indicate unsuccessful completion of the operation.
Since <CODE>EOF</CODE> is used to report both end of file and random errors,
it's often better to use the <CODE>feof</CODE> function to check explicitly
for end of file and <CODE>ferror</CODE> to check for errors.  These functions
check indicators that are part of the internal state of the stream
object, indicators set if the appropriate condition was detected by a
previous I/O operation on that stream.
<P>
These symbols are declared in the header file <TT>`stdio.h'</TT>.
<A NAME="IDX551"></A>
<P>
<A NAME="IDX552"></A>
<U>Macro:</U> int <B>EOF</B><P>
This macro is an integer value that is returned
by a number of functions to indicate an end-of-file condition, or some
other error situation.  With the GNU library, <CODE>EOF</CODE> is <CODE>-1</CODE>.
In other libraries, its value may be some other negative number.
<P>
<A NAME="IDX553"></A>
<U>Function:</U> void <B>clearerr</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
This function clears the end-of-file and error indicators for the
stream <VAR>stream</VAR>.
<P>
The file positioning functions (see section <A HREF="library.html#SEC158">File Positioning</A>) also clear the
end-of-file indicator for the stream.
<P>
<A NAME="IDX554"></A>
<U>Function:</U> int <B>feof</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
The <CODE>feof</CODE> function returns nonzero if and only if the end-of-file
indicator for the stream <VAR>stream</VAR> is set.
<P>
<A NAME="IDX555"></A>
<U>Function:</U> int <B>ferror</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
The <CODE>ferror</CODE> function returns nonzero if and only if the error
indicator for the stream <VAR>stream</VAR> is set, indicating that an error
has occurred on a previous operation on the stream.
<P>
In addition to setting the error indicator associated with the stream,
the functions that operate on streams also set <CODE>errno</CODE> in the same
way as the corresponding low-level functions that operate on file
descriptors.  For example, all of the functions that perform output to a
stream--such as <CODE>fputc</CODE>, <CODE>printf</CODE>, and <CODE>fflush</CODE>---are
implemented in terms of <CODE>write</CODE>, and all of the <CODE>errno</CODE> error
conditions defined for <CODE>write</CODE> are meaningful for these functions.
For more information about the descriptor-level I/O functions, see
section <A HREF="library.html#SEC171">Low-Level Input/Output</A>.
<P>
<H2><A NAME="SEC157" HREF="library_toc.html#SEC157">Text and Binary Streams</A></H2>
<P>
The GNU system and other POSIX-compatible operating systems organize all
files as uniform sequences of characters.  However, some other systems
make a distinction between files containing text and files containing
binary data, and the input and output facilities of ANSI C provide for
this distinction.  This section tells you how to write programs portable
to such systems.
<A NAME="IDX556"></A>
<A NAME="IDX557"></A>
<P>
When you open a stream, you can specify either a <DFN>text stream</DFN> or a
<DFN>binary stream</DFN>.  You indicate that you want a binary stream by
specifying the <SAMP>`b'</SAMP> modifier in the <VAR>opentype</VAR> argument to
<CODE>fopen</CODE>; see section <A HREF="library.html#SEC120">Opening Streams</A>.  Without this
option, <CODE>fopen</CODE> opens the file as a text stream.
<P>
Text and binary streams differ in several ways:
<P>
<UL>
<LI>
The data read from a text stream is divided into <DFN>lines</DFN> which are
terminated by newline (<CODE>'\n'</CODE>) characters, while a binary stream is
simply a long series of characters.  A text stream might on some systems
fail to handle lines more than 254 characters long (including the
terminating newline character).
<A NAME="IDX558"></A>
<P>
<LI>
On some systems, text files can contain only printing characters,
horizontal tab characters, and newlines, and so text streams may not
support other characters.  However, binary streams can handle any
character value.
<P>
<LI>
Space characters that are written immediately preceeding a newline
character in a text stream may disappear when the file is read in again.
<P>
<LI>
More generally, there need not be a one-to-one mapping between
characters that are read from or written to a text stream, and the
characters in the actual file.
</UL>
<P>
Since a binary stream is always more capable and more predictable than a
text stream, you might wonder what purpose text streams serve.  Why not
simply always use binary streams?  The answer is that on these operating
systems, text and binary streams use different file formats, and the
only way to read or write "an ordinary file of text" that can work
with other text-oriented programs is through a text stream.
<P>
In the GNU library, and on all POSIX systems, there is no difference
between text streams and binary streams.  When you open a stream, you
get the same kind of stream regardless of whether you ask for binary.
This stream can handle any file content, and has none of the
restrictions that text streams sometimes have.
<P>
<A NAME="IDX559"></A>
<A NAME="IDX560"></A>
<A NAME="IDX561"></A>
<H2><A NAME="SEC158" HREF="library_toc.html#SEC158">File Positioning</A></H2>
<P>
The <DFN>file position</DFN> of a stream describes where in the file the
stream is currently reading or writing.  I/O on the stream advances the
file position through the file.  In the GNU system, the file position is
represented as an integer, which counts the number of bytes from the
beginning of the file.  See section <A HREF="library.html#SEC111">File Position</A>.
<P>
During I/O to an ordinary disk file, you can change the file position
whenever you wish, so as to read or write any portion of the file.  Some
other kinds of files may also permit this.  Files which support changing
the file position are sometimes referred to as <DFN>random-access</DFN>
files.
<P>
You can use the functions in this section to examine or modify the file
position indicator associated with a stream.  The symbols listed below
are declared in the header file <TT>`stdio.h'</TT>.
<A NAME="IDX562"></A>
<P>
<A NAME="IDX563"></A>
<U>Function:</U> long int <B>ftell</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
This function returns the current file position of the stream
<VAR>stream</VAR>.
<P>
This function can fail if the stream doesn't support file positioning,
or if the file position can't be represented in a <CODE>long int</CODE>, and
possibly for other reasons as well.  If a failure occurs, a value of
<CODE>-1</CODE> is returned.
<P>
<A NAME="IDX564"></A>
<U>Function:</U> int <B>fseek</B> <I>(FILE *<VAR>stream</VAR>, long int <VAR>offset</VAR>, int <VAR>whence</VAR>)</I><P>
The <CODE>fseek</CODE> function is used to change the file position of the
stream <VAR>stream</VAR>.  The value of <VAR>whence</VAR> must be one of the
constants <CODE>SEEK_SET</CODE>, <CODE>SEEK_CUR</CODE>, or <CODE>SEEK_END</CODE>, to
indicate whether the <VAR>offset</VAR> is relative to the beginning of the
file, the current file position, or the end of the file, respectively.
<P>
This function returns a value of zero if the operation was successful,
and a nonzero value to indicate failure.  A successful call also clears
the end-of-file indicator of <VAR>stream</VAR> and discards any characters
that were "pushed back" by the use of <CODE>ungetc</CODE>.
<P>
<CODE>fseek</CODE> either flushes any buffered output before setting the file
position or else remembers it so it will be written later in its proper
place in the file.
<P>
<STRONG>Portability Note:</STRONG> In non-POSIX systems, <CODE>ftell</CODE> and
<CODE>fseek</CODE> might work reliably only on binary streams.  See section <A HREF="library.html#SEC157">Text and Binary Streams</A>.
<P>
The following symbolic constants are defined for use as the <VAR>whence</VAR>
argument to <CODE>fseek</CODE>.  They are also used with the <CODE>lseek</CODE>
function (see section <A HREF="library.html#SEC173">Input and Output Primitives</A>) and to specify offsets for file locks
(see section <A HREF="library.html#SEC181">Control Operations on Files</A>).
<P>
<A NAME="IDX565"></A>
<U>Macro:</U> int <B>SEEK_SET</B><P>
This is an integer constant which, when used as the <VAR>whence</VAR>
argument to the <CODE>fseek</CODE> function, specifies that the offset
provided is relative to the beginning of the file.
<P>
<A NAME="IDX566"></A>
<U>Macro:</U> int <B>SEEK_CUR</B><P>
This is an integer constant which, when used as the <VAR>whence</VAR>
argument to the <CODE>fseek</CODE> function, specifies that the offset
provided is relative to the current file position.
<P>
<A NAME="IDX567"></A>
<U>Macro:</U> int <B>SEEK_END</B><P>
This is an integer constant which, when used as the <VAR>whence</VAR>
argument to the <CODE>fseek</CODE> function, specifies that the offset
provided is relative to the end of the file.
<P>
<A NAME="IDX568"></A>
<U>Function:</U> void <B>rewind</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
The <CODE>rewind</CODE> function positions the stream <VAR>stream</VAR> at the
begining of the file.  It is equivalent to calling <CODE>fseek</CODE> on the
<VAR>stream</VAR> with an <VAR>offset</VAR> argument of <CODE>0L</CODE> and a
<VAR>whence</VAR> argument of <CODE>SEEK_SET</CODE>, except that the return
value is discarded and the error indicator for the stream is reset.
<P>
These three aliases for the <SAMP>`SEEK_...'</SAMP> constants exist for the
sake of compatibility with older BSD systems.  They are defined in two
different header files: <TT>`fcntl.h'</TT> and <TT>`sys/file.h'</TT>.
<P>
<DL COMPACT>
<A NAME="IDX569"></A>
<DT><CODE>L_SET</CODE>
<DD>An alias for <CODE>SEEK_SET</CODE>.
<P>
<A NAME="IDX570"></A>
<DT><CODE>L_INCR</CODE>
<DD>An alias for <CODE>SEEK_CUR</CODE>.
<P>
<A NAME="IDX571"></A>
<DT><CODE>L_XTND</CODE>
<DD>An alias for <CODE>SEEK_END</CODE>.
</DL>
<P>
<H2><A NAME="SEC159" HREF="library_toc.html#SEC159">Portable File-Position Functions</A></H2>
<P>
On the GNU system, the file position is truly a character count.  You
can specify any character count value as an argument to <CODE>fseek</CODE> and
get reliable results for any random access file.  However, some ANSI C
systems do not represent file positions in this way.
<P>
On some systems where text streams truly differ from binary streams, it
is impossible to represent the file position of a text stream as a count
of characters from the beginning of the file.  For example, the file
position on some systems must encode both a record offset within the
file, and a character offset within the record.
<P>
As a consequence, if you want your programs to be portable to these
systems, you must observe certain rules:
<P>
<UL>
<LI>
The value returned from <CODE>ftell</CODE> on a text stream has no predictable
relationship to the number of characters you have read so far.  The only
thing you can rely on is that you can use it subsequently as the
<VAR>offset</VAR> argument to <CODE>fseek</CODE> to move back to the same file
position.
<P>
<LI>
In a call to <CODE>fseek</CODE> on a text stream, either the <VAR>offset</VAR> must
either be zero; or <VAR>whence</VAR> must be <CODE>SEEK_SET</CODE> and the
<VAR>offset</VAR> must be the result of an earlier call to <CODE>ftell</CODE> on
the same stream.
<P>
<LI>
The value of the file position indicator of a text stream is undefined
while there are characters that have been pushed back with <CODE>ungetc</CODE>
that haven't been read or discarded.  See section <A HREF="library.html#SEC125">Unreading</A>.
</UL>
<P>
But even if you observe these rules, you may still have trouble for long
files, because <CODE>ftell</CODE> and <CODE>fseek</CODE> use a <CODE>long int</CODE> value
to represent the file position.  This type may not have room to encode
all the file positions in a large file.
<P>
So if you do want to support systems with peculiar encodings for the
file positions, it is better to use the functions <CODE>fgetpos</CODE> and
<CODE>fsetpos</CODE> instead.  These functions represent the file position
using the data type <CODE>fpos_t</CODE>, whose internal representation varies
from system to system.
<P>
These symbols are declared in the header file <TT>`stdio.h'</TT>.
<A NAME="IDX572"></A>
<P>
<A NAME="IDX573"></A>
<U>Data Type:</U> <B>fpos_t</B><P>
This is the type of an object that can encode information about the
file position of a stream, for use by the functions <CODE>fgetpos</CODE> and
<CODE>fsetpos</CODE>.
<P>
In the GNU system, <CODE>fpos_t</CODE> is equivalent to <CODE>off_t</CODE> or
<CODE>long int</CODE>.  In other systems, it might have a different internal
representation.
<P>
<A NAME="IDX574"></A>
<U>Function:</U> int <B>fgetpos</B> <I>(FILE *<VAR>stream</VAR>, fpos_t *<VAR>position</VAR>)</I><P>
This function stores the value of the file position indicator for the
stream <VAR>stream</VAR> in the <CODE>fpos_t</CODE> object pointed to by
<VAR>position</VAR>.  If successful, <CODE>fgetpos</CODE> returns zero; otherwise
it returns a nonzero value and stores an implementation-defined positive
value in <CODE>errno</CODE>.
<P>
<A NAME="IDX575"></A>
<U>Function:</U> int <B>fsetpos</B> <I>(FILE *<VAR>stream</VAR>, const fpos_t <VAR>position</VAR>)</I><P>
This function sets the file position indicator for the stream <VAR>stream</VAR>
to the position <VAR>position</VAR>, which must have been set by a previous
call to <CODE>fgetpos</CODE> on the same stream.  If successful, <CODE>fsetpos</CODE>
clears the end-of-file indicator on the stream, discards any characters
that were "pushed back" by the use of <CODE>ungetc</CODE>, and returns a value
of zero.  Otherwise, <CODE>fsetpos</CODE> returns a nonzero value and stores
an implementation-defined positive value in <CODE>errno</CODE>.
<P>
<H2><A NAME="SEC160" HREF="library_toc.html#SEC160">Stream Buffering</A></H2>
<A NAME="IDX576"></A>
<P>
Characters that are written to a stream are normally accumulated and
transmitted asynchronously to the file in a block, instead of appearing
as soon as they are output by the application program.  Similarly,
streams often retrieve input from the host environment in blocks rather
than on a character-by-character basis.  This is called <DFN>buffering</DFN>.
<P>
If you are writing programs that do interactive input and output using
streams, you need to understand how buffering works when you design the
user interface to your program.  Otherwise, you might find that output
(such as progress or prompt messages) doesn't appear when you intended
it to, or that input typed by the user is made available by lines
instead of by single characters, or other unexpected behavior.  
<P>
This section deals only with controlling when characters are transmitted
between the stream and the file or device, and <EM>not</EM> with how
things like echoing, flow control, and the like are handled on specific
classes of devices.  For information on common control operations on
terminal devices, see section <A HREF="library.html#SEC268">Low-Level Terminal Interface</A>.
<P>
You can bypass the stream buffering facilities altogether by using the
low-level input and output functions that operate on file descriptors
instead.  See section <A HREF="library.html#SEC171">Low-Level Input/Output</A>.
<P>
<H3><A NAME="SEC161" HREF="library_toc.html#SEC161">Buffering Concepts</A></H3>
<P>
There are three different kinds of buffering strategies:
<P>
<UL>
<LI>
Characters written to or read from an <DFN>unbuffered</DFN> stream are
transmitted individually to or from the file as soon as possible.
<A NAME="IDX577"></A>
<P>
<LI>
Characters written to or read from a <DFN>line buffered</DFN> stream are
transmitted to or from the file in blocks when a newline character is
encountered.
<A NAME="IDX578"></A>
<P>
<LI>
Characters written to or read from a <DFN>fully buffered</DFN> stream are
transmitted to or from the file in blocks of arbitrary size.
<A NAME="IDX579"></A>
</UL>
<P>
Newly opened streams are normally fully buffered, with one exception: a
stream connected to an interactive device such as a terminal is
initially line buffered.  See section <A HREF="library.html#SEC163">Controlling Which Kind of Buffering</A>, for information
on how to select a different kind of buffering.
<P>
The use of line buffering for interactive devices implies that output
messages ending in a newline will appear immediately--which is usually
what you want.  Output that doesn't end in a newline might or might not
show up immediately, so if you want them to appear immediately, you
should flush buffered output explicitly with <CODE>fflush</CODE>, as described
in section <A HREF="library.html#SEC162">Flushing Buffers</A>.
<P>
Line buffering is a good default for terminal input as well, because
most interactive programs read commands that are normally single lines.
The program should be able to execute each line right away.  A line
buffered stream permits this, whereas a fully buffered stream would
always read enough text to fill the buffer before allowing the program
to read any of it.  Line buffering also fits in with the usual
input-editing facilities of most operating systems, which work within a
line of input.
<P>
Some programs need an unbuffered terminal input stream.  These include
programs that read single-character commands (like Emacs) and programs
that do their own input editing (such as those that use readline).  In
order to read a character at a time, it is not enough to turn off
buffering in the input stream; you must also turn off input editing in
the operating system.  This requires changing the terminal mode
(see section <A HREF="library.html#SEC272">Terminal Modes</A>).  If you want to change the terminal modes, you
have to do this separately--merely using an unbuffered stream does not
change the modes.
<P>
<H3><A NAME="SEC162" HREF="library_toc.html#SEC162">Flushing Buffers</A></H3>
<A NAME="IDX580"></A>
<P>
<DFN>Flushing</DFN> output on a buffered stream means transmitting all
accumulated characters to the file.  There are many circumstances when
buffered output on a stream is flushed automatically:
<P>
<UL>
<LI>
When you try to do output and the output buffer is full.
<P>
<LI>
When the stream is closed.  See section <A HREF="library.html#SEC121">Closing Streams</A>.
<P>
<LI>
When the program terminates by calling <CODE>exit</CODE>.
See section <A HREF="library.html#SEC396">Normal Termination</A>.
<P>
<LI>
When a newline is written, if the stream is line buffered.
<P>
<LI>
Whenever an input operation on <EM>any</EM> stream actually reads data
from its file.
</UL>
<P>
If you want to flush the buffered output at another time, call
<CODE>fflush</CODE>, which is declared in the header file <TT>`stdio.h'</TT>.
<A NAME="IDX581"></A>
<P>
<A NAME="IDX582"></A>
<U>Function:</U> int <B>fflush</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
This function causes any buffered output on <VAR>stream</VAR> to be delivered
to the file.  If <VAR>stream</VAR> is a null pointer, then
<CODE>fflush</CODE> causes buffered output on <EM>all</EM> open output streams
to be flushed.
<P>
This function returns <CODE>EOF</CODE> if a write error occurs, or zero
otherwise.
<P>
<STRONG>Compatibility Note:</STRONG> Some brain-damaged operating systems have
been known to be so thoroughly fixated on line-oriented input and output
that flushing a line buffered stream causes a newline to be written!
Fortunately, this "feature" seems to be becoming less common.  You do
not need to worry about this in the GNU system.
<P>
<H3><A NAME="SEC163" HREF="library_toc.html#SEC163">Controlling Which Kind of Buffering</A></H3>
<P>
After opening a stream (but before any other operations have been
performed on it), you can explicitly specify what kind of buffering you
want it to have using the <CODE>setvbuf</CODE> function.
<A NAME="IDX583"></A>
<P>
The facilities listed in this section are declared in the header
file <TT>`stdio.h'</TT>.
<A NAME="IDX584"></A>
<P>
<A NAME="IDX585"></A>
<U>Function:</U> int <B>setvbuf</B> <I>(FILE *<VAR>stream</VAR>, char *<VAR>buf</VAR>, int <VAR>mode</VAR>, size_t <VAR>size</VAR>)</I><P>
This function is used to specify that the stream <VAR>stream</VAR> should
have the buffering mode <VAR>mode</VAR>, which can be either <CODE>_IOFBF</CODE>
(for full buffering), <CODE>_IOLBF</CODE> (for line buffering), or
<CODE>_IONBF</CODE> (for unbuffered input/output).
<P>
If you specify a null pointer as the <VAR>buf</VAR> argument, then <CODE>setvbuf</CODE>
allocates a buffer itself using <CODE>malloc</CODE>.  This buffer will be freed
when you close the stream.
<P>
Otherwise, <VAR>buf</VAR> should be a character array that can hold at least
<VAR>size</VAR> characters.  You should not free the space for this array as
long as the stream remains open and this array remains its buffer.  You
should usually either allocate it statically, or <CODE>malloc</CODE>
(see section <A HREF="library.html#SEC21">Unconstrained Allocation</A>) the buffer.  Using an automatic array
is not a good idea unless you close the file before exiting the block
that declares the array.
<P>
While the array remains a stream buffer, the stream I/O functions will
use the buffer for their internal purposes.  You shouldn't try to access
the values in the array directly while the stream is using it for
buffering.
<P>
The <CODE>setvbuf</CODE> function returns zero on success, or a nonzero value
if the value of <VAR>mode</VAR> is not valid or if the request could not
be honored.
<P>
<A NAME="IDX586"></A>
<U>Macro:</U> int <B>_IOFBF</B><P>
The value of this macro is an integer constant expression that can be
used as the <VAR>mode</VAR> argument to the <CODE>setvbuf</CODE> function to
specify that the stream should be fully buffered.
<P>
<A NAME="IDX587"></A>
<U>Macro:</U> int <B>_IOLBF</B><P>
The value of this macro is an integer constant expression that can be
used as the <VAR>mode</VAR> argument to the <CODE>setvbuf</CODE> function to
specify that the stream should be line buffered.
<P>
<A NAME="IDX588"></A>
<U>Macro:</U> int <B>_IONBF</B><P>
The value of this macro is an integer constant expression that can be
used as the <VAR>mode</VAR> argument to the <CODE>setvbuf</CODE> function to
specify that the stream should be unbuffered.
<P>
<A NAME="IDX589"></A>
<U>Macro:</U> int <B>BUFSIZ</B><P>
The value of this macro is an integer constant expression that is good
to use for the <VAR>size</VAR> argument to <CODE>setvbuf</CODE>.  This value is
guaranteed to be at least <CODE>256</CODE>.
<P>
The value of <CODE>BUFSIZ</CODE> is chosen on each system so as to make stream
I/O efficient.  So it is a good idea to use <CODE>BUFSIZ</CODE> as the size 
for the buffer when you call <CODE>setvbuf</CODE>.
<P>
Actually, you can get an even better value to use for the buffer size
by means of the <CODE>fstat</CODE> system call: it is found in the
<CODE>st_blksize</CODE> field of the file attributes.  See section <A HREF="library.html#SEC201">What the File Attribute Values Mean</A>.
<P>
Sometimes people also use <CODE>BUFSIZ</CODE> as the allocation size of
buffers used for related purposes, such as strings used to receive a
line of input with <CODE>fgets</CODE> (see section <A HREF="library.html#SEC123">Character Input</A>).  There is no
particular reason to use <CODE>BUFSIZ</CODE> for this instead of any other
integer, except that it might lead to doing I/O in chunks of an
efficient size.
<P>
<A NAME="IDX590"></A>
<U>Function:</U> void <B>setbuf</B> <I>(FILE *<VAR>stream</VAR>, char *<VAR>buf</VAR>)</I><P>
If <VAR>buf</VAR> is a null pointer, the effect of this function is
equivalent to calling <CODE>setvbuf</CODE> with a <VAR>mode</VAR> argument of
<CODE>_IONBF</CODE>.  Otherwise, it is equivalent to calling <CODE>setvbuf</CODE>
with <VAR>buf</VAR>, and a <VAR>mode</VAR> of <CODE>_IOFBF</CODE> and a <VAR>size</VAR>
argument of <CODE>BUFSIZ</CODE>.
<P>
The <CODE>setbuf</CODE> function is provided for compatibility with old code;
use <CODE>setvbuf</CODE> in all new programs.
<P>
<A NAME="IDX591"></A>
<U>Function:</U> void <B>setbuffer</B> <I>(FILE *<VAR>stream</VAR>, char *<VAR>buf</VAR>, size_t <VAR>size</VAR>)</I><P>
If <VAR>buf</VAR> is a null pointer, this function makes <VAR>stream</VAR> unbuffered.
Otherwise, it makes <VAR>stream</VAR> fully buffered using <VAR>buf</VAR> as the
buffer.  The <VAR>size</VAR> argument specifies the length of <VAR>buf</VAR>.
<P>
This function is provided for compatibility with old BSD code.  Use
<CODE>setvbuf</CODE> instead.
<P>
<A NAME="IDX592"></A>
<U>Function:</U> void <B>setlinebuf</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
This function makes <VAR>stream</VAR> be line buffered, and allocates the
buffer for you.
<P>
This function is provided for compatibility with old BSD code.  Use
<CODE>setvbuf</CODE> instead.
<P>
<H2><A NAME="SEC164" HREF="library_toc.html#SEC164">Temporary Files</A></H2>
<P>
If you need to use a temporary file in your program, you can use the
<CODE>tmpfile</CODE> function to open it.  Or you can use the <CODE>tmpnam</CODE>
function make a name for a temporary file and then open it in the usual
way with <CODE>fopen</CODE>.
<P>
These facilities are declared in the header file <TT>`stdio.h'</TT>.
<A NAME="IDX593"></A>
<P>
<A NAME="IDX594"></A>
<U>Function:</U> FILE * <B>tmpfile</B> <I>(void)</I><P>
This function creates a temporary binary file for update mode, as if by
calling <CODE>fopen</CODE> with mode <CODE>"wb+"</CODE>.  The file is deleted
automatically when it is closed or when the program terminates.  (On
some other ANSI C systems the file may fail to be deleted if the program
terminates abnormally).
<P>
<A NAME="IDX595"></A>
<U>Function:</U> char * <B>tmpnam</B> <I>(char *<VAR>result</VAR>)</I><P>
This function constructs and returns a file name that is a valid file
name and that does not name any existing file.  If the <VAR>result</VAR>
argument is a null pointer, the return value is a pointer to an internal
static string, which might be modified by subsequent calls.  Otherwise,
the <VAR>result</VAR> argument should be a pointer to an array of at least
<CODE>L_tmpnam</CODE> characters, and the result is written into that array.
<P>
It is possible for <CODE>tmpnam</CODE> to fail if you call it too many times.
This is because the fixed length of a temporary file name gives room for
only a finite number of different names.  If <CODE>tmpnam</CODE> fails, it
returns a null pointer.
<P>
<A NAME="IDX596"></A>
<U>Macro:</U> int <B>L_tmpnam</B><P>
The value of this macro is an integer constant expression that represents
the minimum allocation size of a string large enough to hold the
file name generated by the <CODE>tmpnam</CODE> function.
<P>
<A NAME="IDX597"></A>
<U>Macro:</U> int <B>TMP_MAX</B><P>
The macro <CODE>TMP_MAX</CODE> is a lower bound for how many temporary names
you can create with <CODE>tmpnam</CODE>.  You can rely on being able to call
<CODE>tmpnam</CODE> at least this many times before it might fail saying you
have made too many temporary file names.
<P>
With the GNU library, you can create a very large number of temporary
file names--if you actually create the files, you will probably run out
of disk space before you run out of names.  Some other systems have a
fixed, small limit on the number of temporary files.  The limit is never
less than <CODE>25</CODE>.
<P>
<A NAME="IDX598"></A>
<U>Function:</U> char * <B>tempnam</B> <I>(const char *<VAR>dir</VAR>, const char *<VAR>prefix</VAR>)</I><P>
This function generates a unique temporary filename.  If <VAR>prefix</VAR> is
not a null pointer, up to five characters of this string are used as
a prefix for the file name.
<P>
The directory prefix for the temporary file name is determined by testing
each of the following, in sequence.  The directory must exist and be
writable.
<P>
<UL>
<LI>
The environment variable <CODE>TMPDIR</CODE>, if it is defined.
<P>
<LI>
The <VAR>dir</VAR> argument, if it is not a null pointer.
<P>
<LI>
The value of the <CODE>P_tmpdir</CODE> macro.
<P>
<LI>
The directory <TT>`/tmp'</TT>.
</UL>
<P>
This function is defined for SVID compatibility.
<A NAME="IDX599"></A>
<P>
<A NAME="IDX600"></A>
<U>SVID Macro:</U> char * <B>P_tmpdir</B><P>
This macro is the name of the default directory for temporary files.
<P>
<H2><A NAME="SEC165" HREF="library_toc.html#SEC165">Other Kinds of Streams</A></H2>
<P>
The GNU library provides ways for you to define additional kinds of
streams that do not necessarily correspond to an open file.
<P>
One such type of stream takes input from or writes output to a string.
These kinds of streams are used internally to implement the
<CODE>sprintf</CODE> and <CODE>sscanf</CODE> functions.  You can also create such a
stream explicitly, using the functions described in section <A HREF="library.html#SEC166">String Streams</A>.
<P>
More generally, you can define streams that do input/output to arbitrary
objects using functions supplied by your program.  This protocol is
discussed in section <A HREF="library.html#SEC168">Programming Your Own Custom Streams</A>.
<P>
<STRONG>Portability Note:</STRONG> The facilities described in this section are
specific to GNU.  Other systems or C implementations might or might not
provide equivalent functionality.
<P>
<H3><A NAME="SEC166" HREF="library_toc.html#SEC166">String Streams</A></H3>
<A NAME="IDX601"></A>
<A NAME="IDX602"></A>
<P>
The <CODE>fmemopen</CODE> and <CODE>open_memstream</CODE> functions allow you to do
I/O to a string or memory buffer.  These facilities are declared in
<TT>`stdio.h'</TT>.
<A NAME="IDX603"></A>
<P>
<A NAME="IDX604"></A>
<U>Function:</U> FILE * <B>fmemopen</B> <I>(void *<VAR>buf</VAR>, size_t <VAR>size</VAR>, const char *<VAR>opentype</VAR>)</I><P>
This function opens a stream that allows the access specified by the
<VAR>opentype</VAR> argument, that reads from or writes to the buffer specified
by the argument <VAR>buf</VAR>.  This array must be at least <VAR>size</VAR> bytes long.
<P>
If you specify a null pointer as the <VAR>buf</VAR> argument, <CODE>fmemopen</CODE>
dynamically allocates (as with <CODE>malloc</CODE>; see section <A HREF="library.html#SEC21">Unconstrained Allocation</A>) an array <VAR>size</VAR> bytes long.  This is really only useful
if you are going to write things to the buffer and then read them back
in again, because you have no way of actually getting a pointer to the
buffer (for this, try <CODE>open_memstream</CODE>, below).  The buffer is
freed when the stream is open.
<P>
The argument <VAR>opentype</VAR> is the same as in <CODE>fopen</CODE>
(See section <A HREF="library.html#SEC120">Opening Streams</A>).  If the <VAR>opentype</VAR> specifies
append mode, then the initial file position is set to the first null
character in the buffer.  Otherwise the initial file position is at the
beginning of the buffer.
<P>
When a stream open for writing is flushed or closed, a null character
(zero byte) is written at the end of the buffer if it fits.  You
should add an extra byte to the <VAR>size</VAR> argument to account for this.
Attempts to write more than <VAR>size</VAR> bytes to the buffer result
in an error.
<P>
For a stream open for reading, null characters (zero bytes) in the
buffer do not count as "end of file".  Read operations indicate end of
file only when the file position advances past <VAR>size</VAR> bytes.  So, if
you want to read characters from a null-terminated string, you should
supply the length of the string as the <VAR>size</VAR> argument.
<P>
Here is an example of using <CODE>fmemopen</CODE> to create a stream for
reading from a string:
<P>
<PRE>
#include &#60;stdio.h&#62;

static char buffer[] = "foobar";

int
main (void)
{
  int ch;
  FILE *stream;

  stream = fmemopen (buffer, strlen (buffer), "r");
  while ((ch = fgetc (stream)) != EOF)
    printf ("Got %c\n", ch);
  fclose (stream);

  return 0;
}
</PRE>
<P>
This program produces the following output:
<P>
<PRE>
Got f
Got o
Got o
Got b
Got a
Got r
</PRE>
<P>
<A NAME="IDX605"></A>
<U>Function:</U> FILE * <B>open_memstream</B> <I>(char **<VAR>ptr</VAR>, size_t *<VAR>sizeloc</VAR>)</I><P>
This function opens a stream for writing to a buffer.  The buffer is
allocated dynamically (as with <CODE>malloc</CODE>; see section <A HREF="library.html#SEC21">Unconstrained Allocation</A>) and grown as necessary.
<P>
When the stream is closed with <CODE>fclose</CODE> or flushed with
<CODE>fflush</CODE>, the locations <VAR>ptr</VAR> and <VAR>sizeloc</VAR> are updated to
contain the pointer to the buffer and its size.  The values thus stored
remain valid only as long as no further output on the stream takes
place.  If you do more output, you must flush the stream again to store
new values before you use them again.
<P>
A null character is written at the end of the buffer.  This null character
is <EM>not</EM> included in the size value stored at <VAR>sizeloc</VAR>.
<P>
You can move the stream's file position with <CODE>fseek</CODE> (see section <A HREF="library.html#SEC158">File Positioning</A>).  Moving the file position past the end of the data
already written fills the intervening space with zeroes.
<P>
Here is an example of using <CODE>open_memstream</CODE>:
<P>
<PRE>
#include &#60;stdio.h&#62;

int
main (void)
{
  char *bp;
  size_t size;
  FILE *stream;

  stream = open_memstream (&#38;bp, &#38;size);
  fprintf (stream, "hello");
  fflush (stream);
  printf ("buf = %s, size = %d\n", bp, size);
  fprintf (stream, ", world");
  fclose (stream);
  printf ("buf = %s, size = %d\n", bp, size);

  return 0;
}
</PRE>
<P>
This program produces the following output:
<P>
<PRE>
buf = `hello', size = 5
buf = `hello, world', size = 12
</PRE>
<P>
<H3><A NAME="SEC167" HREF="library_toc.html#SEC167">Obstack Streams</A></H3>
<P>
You can open an output stream that puts it data in an obstack.
See section <A HREF="library.html#SEC33">Obstacks</A>.
<P>
<A NAME="IDX606"></A>
<U>Function:</U> FILE * <B>open_obstack_stream</B> <I>(struct obstack *<VAR>obstack</VAR>)</I><P>
This function opens a stream for writing data into the obstack <VAR>obstack</VAR>.
This starts an object in the obstack and makes it grow as data is
written (see section <A HREF="library.html#SEC39">Growing Objects</A>).
<P>
Calling <CODE>fflush</CODE> on this stream updates the current size of the
object to match the amount of data that has been written.  After a call
to <CODE>fflush</CODE>, you can examine the object temporarily.
<P>
You can move the file position of an obstack stream with <CODE>fseek</CODE>
(see section <A HREF="library.html#SEC158">File Positioning</A>).  Moving the file position past the end of
the data written fills the intervening space with zeros.
<P>
To make the object permanent, update the obstack with <CODE>fflush</CODE>, and
then use <CODE>obstack_finish</CODE> to finalize the object and get its address.
The following write to the stream starts a new object in the obstack,
and later writes add to that object until you do another <CODE>fflush</CODE>
and <CODE>obstack_finish</CODE>.
<P>
But how do you find out how long the object is?  You can get the length
in bytes by calling <CODE>obstack_object_size</CODE> (see section <A HREF="library.html#SEC41">Status of an Obstack</A>), or you can null-terminate the object like this:
<P>
<PRE>
obstack_1grow (<VAR>obstack</VAR>, 0);
</PRE>
<P>
Whichever one you do, you must do it <EM>before</EM> calling
<CODE>obstack_finish</CODE>.  (You can do both if you wish.)
<P>
Here is a sample function that uses <CODE>open_obstack_stream</CODE>:
<P>
<PRE>
char *
make_message_string (const char *a, int b)
{
  FILE *stream = open_obstack_stream (&#38;message_obstack);
  output_task (stream);
  fprintf (stream, ": ");
  fprintf (stream, a, b);
  fprintf (stream, "\n");
  fclose (stream);
  obstack_1grow (&#38;message_obstack, 0);
  return obstack_finish (&#38;message_obstack);
}
</PRE>
<P>
<A NAME="IDX607"></A>
<A NAME="IDX608"></A>
<H3><A NAME="SEC168" HREF="library_toc.html#SEC168">Programming Your Own Custom Streams</A></H3>
<P>
This section describes how you can make a stream that gets input from an
arbitrary data source or writes output to an arbitrary data sink
programmed by you.  We call these <DFN>custom streams</DFN>.
<P>
<A NAME="IDX609"></A>
<H4><A NAME="SEC169" HREF="library_toc.html#SEC169">Custom Streams and Cookies</A></H4>
<P>
Inside every custom stream is a special object called the <DFN>cookie</DFN>.
This is an object supplied by you which records where to fetch or store
the data read or written.  It is up to you to define a data type to use
for the cookie.  The stream functions in the library never refer
directly to its contents, and they don't even know what the type is;
they record its address with type <CODE>void *</CODE>.
<P>
To implement a custom stream, you must specify <EM>how</EM> to fetch or
store the data in the specified place.  You do this by defining
<DFN>hook functions</DFN> to read, write, change "file position", and close
the stream.  All four of these functions will be passed the stream's
cookie so they can tell where to fetch or store the data.  The library
functions don't know what's inside the cookie, but your functions will
know.
<P>
When you create a custom stream, you must specify the cookie pointer,
and also the four hook functions stored in a structure of type 
<CODE>struct cookie_io_functions</CODE>.
<P>
These facilities are declared in <TT>`stdio.h'</TT>.
<A NAME="IDX610"></A>
<P>
<A NAME="IDX611"></A>
<U>Data Type:</U> <B>struct cookie_io_functions</B><P>
This is a structure type that holds the functions that define the 
communications protocol between the stream and its cookie.  It has
the following members:
<P>
<DL COMPACT>
<DT><CODE>cookie_read_function *read</CODE>
<DD>This is the function that reads data from the cookie.  If the value is a
null pointer instead of a function, then read operations on ths stream
always return <CODE>EOF</CODE>.
<P>
<DT><CODE>cookie_write_function *write</CODE>
<DD>This is the function that writes data to the cookie.  If the value is a
null pointer instead of a function, then data written to the stream is
discarded.
<P>
<DT><CODE>cookie_seek_function *seek</CODE>
<DD>This is the function that performs the equivalent of file positioning on
the cookie.  If the value is a null pointer instead of a function, calls
to <CODE>fseek</CODE> on this stream return an <CODE>ESPIPE</CODE> error.
<P>
<DT><CODE>cookie_close_function *close</CODE>
<DD>This function performs any appropriate cleanup on the cookie when
closing the stream.  If the value is a null pointer instead of a
function, nothing special is done to close the cookie when the stream is
closed.
</DL>
<P>
<A NAME="IDX612"></A>
<U>Function:</U> FILE * <B>fopencookie</B> <I>(void *<VAR>cookie</VAR>, const char *<VAR>opentype</VAR>, struct cookie_functions <VAR>io_functions</VAR>)</I><P>
This function actually creates the stream for communicating with the
<VAR>cookie</VAR> using the functions in the <VAR>io_functions</VAR> argument.
The <VAR>opentype</VAR> argument is interpreted as for <CODE>fopen</CODE>;
see section <A HREF="library.html#SEC120">Opening Streams</A>.  (But note that the "truncate on
open" option is ignored.)  The new stream is fully buffered.
<P>
The <CODE>fopencookie</CODE> function returns the newly created stream, or a null
pointer in case of an error.
<P>
<A NAME="IDX613"></A>
<H4><A NAME="SEC170" HREF="library_toc.html#SEC170">Custom Stream Hook Functions</A></H4>
<P>
Here are more details on how you should define the four hook functions
that a custom stream needs.
<P>
You should define the function to read data from the cookie as:
<P>
<PRE>
ssize_t <VAR>reader</VAR> (void *<VAR>cookie</VAR>, void *<VAR>buffer</VAR>, size_t <VAR>size</VAR>)
</PRE>
<P>
This is very similar to the <CODE>read</CODE> function; see section <A HREF="library.html#SEC173">Input and Output Primitives</A>.  Your function should transfer up to <VAR>size</VAR> bytes into
the <VAR>buffer</VAR>, and return the number of bytes read, or zero to
indicate end-of-file.  You can return a value of <CODE>-1</CODE> to indicate
an error.
<P>
You should define the function to write data to the cookie as:
<P>
<PRE>
ssize_t <VAR>writer</VAR> (void *<VAR>cookie</VAR>, const void *<VAR>buffer</VAR>, size_t <VAR>size</VAR>)
</PRE>
<P>
This is very similar to the <CODE>write</CODE> function; see section <A HREF="library.html#SEC173">Input and Output Primitives</A>.  Your function should transfer up to <VAR>size</VAR> bytes from
the buffer, and return the number of bytes written.  You can return a
value of <CODE>-1</CODE> to indicate an error.
<P>
You should define the function to perform seek operations on the cookie
as:
<P>
<PRE>
int <VAR>seeker</VAR> (void *<VAR>cookie</VAR>, fpos_t *<VAR>position</VAR>, int <VAR>whence</VAR>)
</PRE>
<P>
For this function, the <VAR>position</VAR> and <VAR>whence</VAR> arguments are
interpreted as for <CODE>fgetpos</CODE>; see section <A HREF="library.html#SEC159">Portable File-Position Functions</A>.  In
the GNU library, <CODE>fpos_t</CODE> is equivalent to <CODE>off_t</CODE> or
<CODE>long int</CODE>, and simply represents the number of bytes from the
beginning of the file.
<P>
After doing the seek operation, your function should store the resulting 
file position relative to the beginning of the file in <VAR>position</VAR>.
Your function should return a value of <CODE>0</CODE> on success and <CODE>-1</CODE>
to indicate an error.
<P>
You should define the function to do cleanup operations on the cookie
appropriate for closing the stream as:
<P>
<PRE>
int <VAR>cleaner</VAR> (void *<VAR>cookie</VAR>)
</PRE>
<P>
Your function should return <CODE>-1</CODE> to indicate an error, and <CODE>0</CODE>
otherwise.
<P>
<A NAME="IDX614"></A>
<U>Data Type:</U> <B>cookie_read_function</B><P>
This is the data type that the read function for a custom stream should have.
If you declare the function as shown above, this is the type it will have.
<P>
<A NAME="IDX615"></A>
<U>Data Type:</U> <B>cookie_write_function</B><P>
The data type of the write function for a custom stream.
<P>
<A NAME="IDX616"></A>
<U>Data Type:</U> <B>cookie_seek_function</B><P>
The data type of the seek function for a custom stream.
<P>
<A NAME="IDX617"></A>
<U>Data Type:</U> <B>cookie_close_function</B><P>
The data type of the close function for a custom stream.
<P>
<H1><A NAME="SEC171" HREF="library_toc.html#SEC171">Low-Level Input/Output</A></H1>
<P>
This chapter describes functions for performing low-level input/output
operations on file descriptors.  These functions include the primitives
for the higher-level I/O functions described in section <A HREF="library.html#SEC117">Input/Output on Streams</A>, as
well as functions for performing low-level control operations for which
there are no equivalents on streams.
<P>
Stream-level I/O is more flexible and usually more convenient;
therefore, programmers generally use the descriptor-level functions only
when necessary.  These are some of the usual reasons:
<P>
<UL>
<LI>
For reading binary files in large chunks.
<P>
<LI>
For reading an entire file into core before parsing it.
<P>
<LI>
To perform operations other than data transfer, which can only be done
with a descriptor.  (You can use <CODE>fileno</CODE> to get the descriptor
corresponding to a stream.)
<P>
<LI>
To pass descriptors to a child process.  (The child can create its own
stream to use a descriptor that it inherits, but cannot inherit a stream
directly.)
</UL>
<P>
<H2><A NAME="SEC172" HREF="library_toc.html#SEC172">Opening and Closing Files</A></H2>
<A NAME="IDX618"></A>
<A NAME="IDX619"></A>
<P>
This section describes the primitives for opening and closing files
using file descriptors.  The <CODE>open</CODE> and <CODE>creat</CODE> functions are
declared in the header file <TT>`fcntl.h'</TT>, while <CODE>close</CODE> is
declared in <TT>`unistd.h'</TT>.
<A NAME="IDX621"></A>
<A NAME="IDX620"></A>
<P>
<A NAME="IDX622"></A>
<U>Function:</U> int <B>open</B> <I>(const char *<VAR>filename</VAR>, int <VAR>flags</VAR>[, mode_t <VAR>mode</VAR>])</I><P>
The <CODE>open</CODE> function creates and returns a new file descriptor
for the file named by <VAR>filename</VAR>.  Initially, the file position
indicator for the file is at the beginning of the file.  The argument
<VAR>mode</VAR> is used only when a file is created, but it doesn't hurt
to supply the argument in any case.
<P>
The <VAR>flags</VAR> argument controls how the file is to be opened.  This is
a bit mask; you create the value by the bitwise OR of the appropriate
parameters (using the <SAMP>`|'</SAMP> operator in C).
<P>
The <VAR>flags</VAR> argument must include exactly one of these values to
specify the file access mode:
<P>
<DL COMPACT>
<A NAME="IDX623"></A>
<DT><CODE>O_RDONLY</CODE>
<DD>Open the file for read access.
<P>
<A NAME="IDX624"></A>
<DT><CODE>O_WRONLY</CODE>
<DD>Open the file for write access.
<P>
<A NAME="IDX625"></A>
<DT><CODE>O_RDWR</CODE>
<DD>Open the file for both reading and writing.
</DL>
<P>
The <VAR>flags</VAR> argument can also include any combination of these
flags:
<P>
<DL COMPACT>
<A NAME="IDX626"></A>
<A NAME="IDX627"></A>
<DT><CODE>O_APPEND</CODE>
<DD>If set, then all <CODE>write</CODE> operations write the data at the end of
the file, extending it, regardless of the current file position.
<P>
<A NAME="IDX628"></A>
<DT><CODE>O_CREAT</CODE>
<DD>If set, the file will be created if it doesn't already exist.
<A NAME="IDX629"></A>
<P>
<A NAME="IDX630"></A>
<DT><CODE>O_EXCL</CODE>
<DD>If both <CODE>O_CREAT</CODE> and <CODE>O_EXCL</CODE> are set, then <CODE>open</CODE> fails
if the specified file already exists.
<P>
<A NAME="IDX631"></A>
<DT><CODE>O_NOCTTY</CODE>
<DD>If <VAR>filename</VAR> names a terminal device, don't make it the controlling
terminal for the process.  See section <A HREF="library.html#SEC411">Job Control</A>, for information about what
it means to be the controlling terminal.
<P>
<A NAME="IDX632"></A>
<A NAME="IDX633"></A>
<DT><CODE>O_NONBLOCK</CODE>
<DD>This sets nonblocking mode.  This option is usually only useful for
special files such as FIFOs (see section <A HREF="library.html#SEC211">Pipes and FIFOs</A>) and devices such
as terminals.  Normally, for these files, <CODE>open</CODE> blocks until
the file is "ready".  If <CODE>O_NONBLOCK</CODE> is set, <CODE>open</CODE>
returns immediately.
<P>
The <CODE>O_NONBLOCK</CODE> bit also affects <CODE>read</CODE> and <CODE>write</CODE>: It
permits them to return immediately with a failure status if there is no
input immediately available (<CODE>read</CODE>), or if the output can't be
written immediately (<CODE>write</CODE>).
<P>
<A NAME="IDX634"></A>
<DT><CODE>O_TRUNC</CODE>
<DD>If the file exists and is opened for write access, truncate it to zero
length.  This option is only useful for regular files, not special
files such as directories or FIFOs.
</DL>
<P>
For more information about these symbolic constants, see section <A HREF="library.html#SEC184">File Status Flags</A>.
<P>
The normal return value from <CODE>open</CODE> is a non-negative integer file
descriptor.  In the case of an error, a value of <CODE>-1</CODE> is returned
instead.  In addition to the usual file name syntax errors (see section <A HREF="library.html#SEC115">File Name Errors</A>), the following <CODE>errno</CODE> error conditions are defined
for this function:
<P>
<DL COMPACT>
<DT><CODE>EACCES</CODE>
<DD>The file exists but is not readable/writable as requested by the <VAR>flags</VAR>
argument.
<P>
<DT><CODE>EEXIST</CODE>
<DD>Both <CODE>O_CREAT</CODE> and <CODE>O_EXCL</CODE> are set, and the named file already
exists.
<P>
<DT><CODE>EINTR</CODE>
<DD>The <CODE>open</CODE> operation was interrupted by a signal.
See section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<DT><CODE>EISDIR</CODE>
<DD>The <VAR>flags</VAR> argument specified write access, and the file is a directory.
<P>
<DT><CODE>EMFILE</CODE>
<DD>The process has too many files open.
<P>
<DT><CODE>ENFILE</CODE>
<DD>The entire system, or perhaps the file system which contains the
directory, cannot support any additional open files at the moment.
(This problem cannot happen on the GNU system.)
<P>
<DT><CODE>ENOENT</CODE>
<DD>The named file does not exist, but <CODE>O_CREAT</CODE> is not specified.
<P>
<DT><CODE>ENOSPC</CODE>
<DD>The directory or file system that would contain the new file cannot be
extended, because there is no disk space left.
<P>
<DT><CODE>ENXIO</CODE>
<DD><CODE>O_NONBLOCK</CODE> and <CODE>O_WRONLY</CODE> are both set in the <VAR>flags</VAR>
argument, the file named by <VAR>filename</VAR> is a FIFO (see section <A HREF="library.html#SEC211">Pipes and FIFOs</A>), and no process has the file open for reading.
<P>
<DT><CODE>EROFS</CODE>
<DD>The file resides on a read-only file system and any of <CODE>O_WRONLY</CODE>,
<CODE>O_RDWR</CODE>, <CODE>O_CREAT</CODE>, and <CODE>O_TRUNC</CODE> are set in the
<VAR>flags</VAR> argument.
</DL>
<P>
The <CODE>open</CODE> function is the underlying primitive for the <CODE>fopen</CODE>
and <CODE>freopen</CODE> functions, that create streams.
<P>
<A NAME="IDX635"></A>
<U>Obsolete function:</U> int <B>creat</B> <I>(const char *<VAR>filename</VAR>, mode_t <VAR>mode</VAR>)</I><P>
This function is obsolete.  The call
<P>
<PRE>
creat (<VAR>filename</VAR>, <VAR>mode</VAR>)
</PRE>
<P>
is equivalent to
<P>
<PRE>
open (<VAR>filename</VAR>, O_WRONLY | O_CREAT | O_TRUNC, <VAR>mode</VAR>)
</PRE>
<P>
<A NAME="IDX636"></A>
<U>Function:</U> int <B>close</B> <I>(int <VAR>filedes</VAR>)</I><P>
The function <CODE>close</CODE> closes the file descriptor <VAR>filedes</VAR>.
Closing a file has the following consequences:
<P>
<UL>
<LI>
The file descriptor is deallocated.
<P>
<LI>
Any record locks owned by the process on the file are unlocked.
<P>
<LI>
When all file descriptors associated with a pipe or FIFO have been closed,
any unread data is discarded.
</UL>
<P>
The normal return value from <CODE>close</CODE> is <CODE>0</CODE>; a value of <CODE>-1</CODE>
is returned in case of failure.  The following <CODE>errno</CODE> error
conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>EINTR</CODE>
<DD>The call was interrupted by a signal.  See section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
Here's an example of how to handle <CODE>EINTR</CODE> properly:
<P>
<PRE>
TEMP_FAILURE_RETRY (close (desc));
</PRE>
</DL>
<P>
To close a stream, call <CODE>fclose</CODE> (see section <A HREF="library.html#SEC121">Closing Streams</A>) instead
of trying to close its underlying file descriptor with <CODE>close</CODE>.
This flushes any buffered output and updates the stream object to
indicate that it is closed.
<P>
<H2><A NAME="SEC173" HREF="library_toc.html#SEC173">Input and Output Primitives</A></H2>
<P>
This section describes the functions for performing primitive input and
output operations on file descriptors: <CODE>read</CODE>, <CODE>write</CODE>, and
<CODE>lseek</CODE>.  These functions are declared in the header file
<TT>`unistd.h'</TT>.
<A NAME="IDX637"></A>
<P>
<A NAME="IDX638"></A>
<U>Data Type:</U> <B>ssize_t</B><P>
This data type is used to represent the sizes of blocks that can be
read or written in a single operation.  It is similar to <CODE>size_t</CODE>,
but must be a signed type.
<P>
<A NAME="IDX639"></A>
<P>
<A NAME="IDX640"></A>
<U>Function:</U> ssize_t <B>read</B> <I>(int <VAR>filedes</VAR>, void *<VAR>buffer</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>read</CODE> function reads up to <VAR>size</VAR> bytes from the file
with descriptor <VAR>filedes</VAR>, storing the results in the <VAR>buffer</VAR>.
(This is not necessarily a character string and there is no terminating
null character added.)
<A NAME="IDX641"></A>
<P>
The return value is the number of bytes actually read.  This might be
less than <VAR>size</VAR>; for example, if there aren't that many bytes left
in the file or if there aren't that many bytes immediately available.
The exact behavior depends on what kind of file it is.  Note that
reading less than <VAR>size</VAR> bytes is not an error.
<P>
A value of zero indicates end-of-file (except if the value of the
<VAR>size</VAR> argument is also zero).  This is not considered an error.
If you keep calling <CODE>read</CODE> while at end-of-file, it will keep
returning zero and doing nothing else.
<P>
If <CODE>read</CODE> returns at least one character, there is no way you can
tell whether end-of-file was reached.  But if you did reach the end, the
next read will return zero.
<P>
In case of an error, <CODE>read</CODE> returns <CODE>-1</CODE>.  The following
<CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EAGAIN</CODE>
<DD>Normally, when no input is immediately available, <CODE>read</CODE> waits for
some input.  But if the <CODE>O_NONBLOCK</CODE> flag is set for the file
(see section <A HREF="library.html#SEC184">File Status Flags</A>), <CODE>read</CODE> returns immediately without
reading any data, and reports this error.
<P>
<STRONG>Compatibility Note:</STRONG> Most versions of BSD Unix use a different
error code for this: <CODE>EWOULDBLOCK</CODE>.  In the GNU library,
<CODE>EWOULDBLOCK</CODE> is an alias for <CODE>EAGAIN</CODE>, so it doesn't matter
which name you use.
<P>
On some systems, reading a large amount of data from a character special
file can also fail with <CODE>EAGAIN</CODE> if the kernel cannot find enough
physical memory to lock down the user's pages.  This is limited to
devices that transfer with direct memory access into the user's memory,
which means it does not include terminals, since they always use
separate buffers inside the kernel.
<P>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>EINTR</CODE>
<DD><CODE>read</CODE> was interrupted by a signal while it was waiting for input.
See section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<DT><CODE>EIO</CODE>
<DD>For many devices, and for disk files, this error code indicates
a hardware error.
<P>
<CODE>EIO</CODE> also occurs when a background process tries to read from the
controlling terminal, and the normal action of stopping the process by
sending it a <CODE>SIGTTIN</CODE> signal isn't working.  This might happen if
signal is being blocked or ignored, or because the process group is
orphaned.  See section <A HREF="library.html#SEC411">Job Control</A>, for more information about job control,
and section <A HREF="library.html#SEC330">Signal Handling</A>, for information about signals.
</DL>
<P>
The <CODE>read</CODE> function is the underlying primitive for all of the
functions that read from streams, such as <CODE>fgetc</CODE>.
<P>
<A NAME="IDX642"></A>
<P>
<A NAME="IDX643"></A>
<U>Function:</U> ssize_t <B>write</B> <I>(int <VAR>filedes</VAR>, const void *<VAR>buffer</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>write</CODE> function writes up to <VAR>size</VAR> bytes from
<VAR>buffer</VAR> to the file with descriptor <VAR>filedes</VAR>.  The data in
<VAR>buffer</VAR> is not necessarily a character string and a null character
output like any other character.
<P>
The return value is the number of bytes actually written.  This is
normally the same as <VAR>size</VAR>, but might be less (for example, if the
physical media being written to fills up).
<P>
In the case of an error, <CODE>write</CODE> returns <CODE>-1</CODE>.  The following
<CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EAGAIN</CODE>
<DD>Normally, <CODE>write</CODE> blocks until the write operation is complete.
But if the <CODE>O_NONBLOCK</CODE> flag is set for the file (see section <A HREF="library.html#SEC181">Control Operations on Files</A>), it returns immediately without writing any data, and
reports this error.  An example of a situation that might cause the
process to block on output is writing to a terminal device that supports
flow control, where output has been suspended by receipt of a STOP
character.
<P>
<STRONG>Compatibility Note:</STRONG> Most versions of BSD Unix use a different
error code for this: <CODE>EWOULDBLOCK</CODE>.  In the GNU library,
<CODE>EWOULDBLOCK</CODE> is an alias for <CODE>EAGAIN</CODE>, so it doesn't matter
which name you use.
<P>
On some systems, writing a large amount of data from a character special
file can also fail with <CODE>EAGAIN</CODE> if the kernel cannot find enough
physical memory to lock down the user's pages.  This is limited to
devices that transfer with direct memory access into the user's memory,
which means it does not include terminals, since they always use
separate buffers inside the kernel.
<P>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>EFBIG</CODE>
<DD>The size of the file is larger than the implementation can support.
<P>
<DT><CODE>EINTR</CODE>
<DD>The <CODE>write</CODE> operation was interrupted by a signal while it was
blocked waiting for completion.  See section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<DT><CODE>EIO</CODE>
<DD>For many devices, and for disk files, this error code indicates
a hardware error.
<P>
<CODE>EIO</CODE> also occurs when a background process tries to write to the
controlling terminal, and the normal action of stopping the process by
sending it a <CODE>SIGTTOU</CODE> signal isn't working.  This might happen if
the signal is being blocked or ignored.  See section <A HREF="library.html#SEC411">Job Control</A>, for more
information about job control, and section <A HREF="library.html#SEC330">Signal Handling</A>, for
information about signals.
<P>
<DT><CODE>ENOSPC</CODE>
<DD>The device is full.
<P>
<DT><CODE>EPIPE</CODE>
<DD>This error is returned when you try to write to a pipe or FIFO that
isn't open for reading by any process.  When this happens, a <CODE>SIGPIPE</CODE>
signal is also sent to the process; see section <A HREF="library.html#SEC330">Signal Handling</A>.
</DL>
<P>
Unless you have arranged to prevent <CODE>EINTR</CODE> failures, you should
check <CODE>errno</CODE> after each failing call to <CODE>write</CODE>, and if the
error was <CODE>EINTR</CODE>, you should simply repeat the call.
See section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.  The easy way to do this is with the
macro <CODE>TEMP_FAILURE_RETRY</CODE>, as follows:
<P>
<PRE>
nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
</PRE>
<P>
The <CODE>write</CODE> function is the underlying primitive for all of the
functions that write to streams, such as <CODE>fputc</CODE>.
<P>
<H2><A NAME="SEC174" HREF="library_toc.html#SEC174">Setting the File Position of a Descriptor</A></H2>
<P>
Just as you can set the file position of a stream with <CODE>fseek</CODE>, you
can set the file position of a descriptor with <CODE>lseek</CODE>.  This
specifies the position in the file for the next <CODE>read</CODE> or
<CODE>write</CODE> operation.  See section <A HREF="library.html#SEC158">File Positioning</A>, for more information
on the file position and what it means.
<P>
To read the current file position value from a descriptor, use
<CODE>lseek (<VAR>desc</VAR>, 0, SEEK_CUR)</CODE>.
<A NAME="IDX644"></A>
<A NAME="IDX645"></A>
<A NAME="IDX646"></A>
<P>
<A NAME="IDX647"></A>
<U>Function:</U> off_t <B>lseek</B> <I>(int <VAR>filedes</VAR>, off_t <VAR>offset</VAR>, int <VAR>whence</VAR>)</I><P>
The <CODE>lseek</CODE> function is used to change the file position of the
file with descriptor <VAR>filedes</VAR>.
<P>
The <VAR>whence</VAR> argument specifies how the <VAR>offset</VAR> should be
interpreted in the same way as for the <CODE>fseek</CODE> function, and can be
one of the symbolic constants <CODE>SEEK_SET</CODE>, <CODE>SEEK_CUR</CODE>, or
<CODE>SEEK_END</CODE>.
<P>
<DL COMPACT>
<DT><CODE>SEEK_SET</CODE>
<DD>Specifies that <VAR>whence</VAR> is a count of characters from the beginning
of the file.
<P>
<DT><CODE>SEEK_CUR</CODE>
<DD>Specifies that <VAR>whence</VAR> is a count of characters from the current
file position.  This count may be positive or negative.
<P>
<DT><CODE>SEEK_END</CODE>
<DD>Specifies that <VAR>whence</VAR> is a count of characters from the end of
the file.  A negative count specifies a position within the current
extent of the file; a positive count specifies a position past the
current end.  If you set the position past the current end, and 
actually write data, you will extend the file with zeros up to that
position.
</DL>
<P>
The return value from <CODE>lseek</CODE> is normally the resulting file
position, measured in bytes from the beginning of the file.
You can use this feature together with <CODE>SEEK_CUR</CODE> to read the
current file position.
<P>
You can set the file position past the current end of the file.  This
does not by itself make the file longer; <CODE>lseek</CODE> never changes the
file.  But subsequent output at that position will extend the file's
size.
<P>
If the file position cannot be changed, or the operation is in some way
invalid, <CODE>lseek</CODE> returns a value of <CODE>-1</CODE>.  The following
<CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> is not a valid file descriptor.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>whence</VAR> argument value is not valid, or the resulting
file offset is not valid.
<P>
<DT><CODE>ESPIPE</CODE>
<DD>The <VAR>filedes</VAR> corresponds to a pipe or FIFO, which cannot be positioned.
(There may be other kinds of files that cannot be positioned either, but
the behavior is not specified in those cases.)
</DL>
<P>
The <CODE>lseek</CODE> function is the underlying primitive for the
<CODE>fseek</CODE>, <CODE>ftell</CODE> and <CODE>rewind</CODE> functions, which operate on
streams instead of file descriptors.
<P>
You can have multiple descriptors for the same file if you open the file
more than once, or if you duplicate a descriptor with <CODE>dup</CODE>.  
Descriptors that come from separate calls to <CODE>open</CODE> have independent
file positions; using <CODE>lseek</CODE> on one descriptor has no effect on the
other.  For example, 
<P>
<PRE>
{
  int d1, d2;
  char buf[4];
  d1 = open ("foo", O_RDONLY);
  d2 = open ("foo", O_RDONLY);
  lseek (d1, 1024, SEEK_SET);
  read (d2, buf, 4);
}
</PRE>
<P>
will read the first four characters of the file <TT>`foo'</TT>.  (The
error-checking code necessary for a real program has been omitted here
for brevity.)
<P>
By contrast, descriptors made by duplication share a common file
position with the original descriptor that was duplicated.  Anything
which alters the file position of one of the duplicates, including
reading or writing data, affects all of them alike.  Thus, for example,
<P>
<PRE>
{
  int d1, d2, d3;
  char buf1[4], buf2[4];
  d1 = open ("foo", O_RDONLY);
  d2 = dup (d1);
  d3 = dup (d2);
  lseek (d3, 1024, SEEK_SET);
  read (d1, buf1, 4);
  read (d2, buf2, 4);
}
</PRE>
<P>
will read four characters starting with the 1024'th character of
<TT>`foo'</TT>, and then four more characters starting with the 1028'th
character.
<P>
<A NAME="IDX648"></A>
<U>Data Type:</U> <B>off_t</B><P>
This is an arithmetic data type used to represent file sizes.
In the GNU system, this is equivalent to <CODE>fpos_t</CODE> or <CODE>long int</CODE>.
<P>
These three aliases for the <SAMP>`SEEK_...'</SAMP> constants exist for the
sake of compatibility with older BSD systems.  They are defined in two
different header files: <TT>`fcntl.h'</TT> and <TT>`sys/file.h'</TT>.
<P>
<DL COMPACT>
<DT><CODE>L_SET</CODE>
<DD>An alias for <CODE>SEEK_SET</CODE>.
<P>
<DT><CODE>L_INCR</CODE>
<DD>An alias for <CODE>SEEK_CUR</CODE>.
<P>
<DT><CODE>L_XTND</CODE>
<DD>An alias for <CODE>SEEK_END</CODE>.
</DL>
<P>
<A NAME="IDX649"></A>
<A NAME="IDX650"></A>
<A NAME="IDX651"></A>
<H2><A NAME="SEC175" HREF="library_toc.html#SEC175">Descriptors and Streams</A></H2>
<P>
Given an open file descriptor, you can create a stream for it with the
<CODE>fdopen</CODE> function.  You can get the underlying file descriptor for
an existing stream with the <CODE>fileno</CODE> function.  These functions are
declared in the header file <TT>`stdio.h'</TT>.
<A NAME="IDX652"></A>
<P>
<A NAME="IDX653"></A>
<U>Function:</U> FILE * <B>fdopen</B> <I>(int <VAR>filedes</VAR>, const char *<VAR>opentype</VAR>)</I><P>
The <CODE>fdopen</CODE> function returns a new stream for the file descriptor
<VAR>filedes</VAR>.
<P>
The <VAR>opentype</VAR> argument is interpreted in the same way as for the
<CODE>fopen</CODE> function (see section <A HREF="library.html#SEC120">Opening Streams</A>), except that
the <SAMP>`b'</SAMP> option is not permitted; this is because GNU makes no
distinction between text and binary files.  Also, <CODE>"w"</CODE> and
<CODE>"w+"</CODE> do not cause truncation of the file; these have affect only
when opening a file, and in this case the file has already been opened.
You must make sure that the <VAR>opentype</VAR> argument matches the actual
mode of the open file descriptor.
<P>
The return value is the new stream.  If the stream cannot be created
(for example, if the modes for the file indicated by the file descriptor
do not permit the access specified by the <VAR>opentype</VAR> argument), a
null pointer is returned instead.
<P>
For an example showing the use of the <CODE>fdopen</CODE> function,
see section <A HREF="library.html#SEC212">Creating a Pipe</A>.
<P>
<A NAME="IDX654"></A>
<U>Function:</U> int <B>fileno</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
This function returns the file descriptor associated with the stream
<VAR>stream</VAR>.  If an error is detected (for example, if the <VAR>stream</VAR>
is not valid) or if <VAR>stream</VAR> does not do I/O to a file,
<CODE>fileno</CODE> returns <CODE>-1</CODE>.
<P>
<A NAME="IDX655"></A>
<A NAME="IDX656"></A>
<P>
There are also symbolic constants defined in <TT>`unistd.h'</TT> for the
file descriptors belonging to the standard streams <CODE>stdin</CODE>,
<CODE>stdout</CODE>, and <CODE>stderr</CODE>; see section <A HREF="library.html#SEC119">Standard Streams</A>.
<A NAME="IDX657"></A>
<P>
<DL COMPACT>
<A NAME="IDX658"></A>
<DT><CODE>STDIN_FILENO</CODE>
<DD>This macro has value <CODE>0</CODE>, which is the file descriptor for
standard input.
<A NAME="IDX659"></A>
<P>
<A NAME="IDX660"></A>
<DT><CODE>STDOUT_FILENO</CODE>
<DD>This macro has value <CODE>1</CODE>, which is the file descriptor for
standard output.
<A NAME="IDX661"></A>
<P>
<A NAME="IDX662"></A>
<DT><CODE>STDERR_FILENO</CODE>
<DD>This macro has value <CODE>2</CODE>, which is the file descriptor for
standard error output.
<A NAME="IDX663"></A>
</DL>
<P>
<A NAME="IDX664"></A>
<A NAME="IDX665"></A>
<A NAME="IDX666"></A>
<A NAME="IDX667"></A>
<H2><A NAME="SEC176" HREF="library_toc.html#SEC176">Precautions for Mixing Streams and Descriptors</A></H2>
<P>
You can have multiple file descriptors and streams (let's call both
streams and descriptors "channels" for short) connected to the same
file, but you must take care to avoid confusion between channels.  There
are two cases to consider: <DFN>linked</DFN> channels that share a single
file position value, and <DFN>independent</DFN> channels that have their own
file positions.
<P>
It's best to use just one channel in your program for actual data
transfer to any given file, except when all the access is for input.
For example, if you open a pipe (something you can only do at the file
descriptor level), either do all I/O with the descriptor, or construct a
stream from the descriptor with <CODE>fdopen</CODE> and then do all I/O with
the stream.
<P>
<A NAME="IDX668"></A>
<H3><A NAME="SEC177" HREF="library_toc.html#SEC177">Linked Channels</A></H3>
<P>
Channels that come from a single opening share the same file position;
we call them <DFN>linked</DFN> channels.  Linked channels result when you
make a stream from a descriptor using <CODE>fdopen</CODE>, when you get a
descriptor from a stream with <CODE>fileno</CODE>, and when you copy a
descriptor with <CODE>dup</CODE> or <CODE>dup2</CODE>.  For files that don't support
random access, such as terminals and pipes, <EM>all</EM> channels are
effectively linked.  On random-access files, all append-type output
streams are effectively linked to each other.
<A NAME="IDX669"></A>
<P>
If you have been using a stream for I/O, and you want to do I/O using
another channel (either a stream or a descriptor) that is linked to it,
you must first <DFN>clean up</DFN> the stream that you have been using.
See section <A HREF="library.html#SEC179">Cleaning Streams</A>.
<P>
Terminating a process, or executing a new program in the process,
destroys all the streams in the process.  If descriptors linked to these
streams persist in other processes, their file positions become
undefined as a result.  To prevent this, you must clean up the streams
before destroying them.
<P>
<A NAME="IDX670"></A>
<H3><A NAME="SEC178" HREF="library_toc.html#SEC178">Independent Channels</A></H3>
<P>
When you open channels (streams or descriptors) separately on a seekable
file, each channel has its own file position.  These are called
<DFN>independent channels</DFN>.
<P>
The system handles each channel independently.  Most of the time, this
is quite predictable and natural (especially for input): each channel
can read or write sequentially at its own place in the file.
The precautions you should take are these:
<P>
<UL>
<LI>
You should clean an output stream after use, before doing anything else
that might read or write from the same part of the file.
<P>
<LI>
You should clean an input stream before reading data that may have been
modified using an independent channel.  Otherwise, you might read
obsolete data that had been in the stream's buffer.
</UL>
<P>
If you do output to one channel at the end of the file, this will
certainly leave the other independent channels positioned somewhere
before the new end.  If you want them to output at the end, you must set
their file positions to end of file, first.  (This is not necessary if
you use an append-type descriptor or stream; they always output at the
current end of the file.)  In order to make the end-of-file position
accurate, you must clean the output channel you were using, if it is a
stream.  (This is necessary even if you plan to use an append-type
channel next.)
<P>
It's impossible for two channels to have separate file pointers for a
file that doesn't support random access.  Thus, channels for reading or
writing such files are always linked, never independent.  Append-type
channels are also always linked.  For these channels, follow the rules
for linked channels; see section <A HREF="library.html#SEC177">Linked Channels</A>.
<P>
<H3><A NAME="SEC179" HREF="library_toc.html#SEC179">Cleaning Streams</A></H3>
<P>
On the GNU system, you can clean up any stream with <CODE>fclean</CODE>:
<P>
<A NAME="IDX671"></A>
<U>Function:</U> int <B>fclean</B> <I>(<VAR>stream</VAR>)</I><P>
Clean up the stream <VAR>stream</VAR> so that its buffer is empty.  If
<VAR>stream</VAR> is doing output, force it out.  If <VAR>stream</VAR> is doing
input, give the data in the buffer back to the system, arranging to
reread it.
<P>
On other systems, you can use <CODE>fflush</CODE> to clean a stream in most
cases.
<P>
You can skip the <CODE>fclean</CODE> or <CODE>fflush</CODE> if you know the stream
is already clean.  A stream is clean whenever its buffer is empty.  For
example, an unbuffered stream is always clean.  An input stream that is
at end-of-file is clean.  A line-buffered stream is clean when the last
character output was a newline.
<P>
There is one case in which cleaning a stream is impossible on most
systems.  This is when the stream is doing input from a file that is not
random-access.  Such streams typically read ahead, and when the file is
not random access, there is no way to give back the excess data already
read.  When an input stream reads from a random-access file,
<CODE>fflush</CODE> does clean the stream, but leaves the file pointer at an
unpredictable place; you must set the file pointer before doing any
further I/O.  On the GNU system, using <CODE>fclean</CODE> avoids both of
these problems.
<P>
Closing an output-only stream also does <CODE>fflush</CODE>, so this is a
valid way of cleaning an output stream.  On the GNU system, closing an
input stream does <CODE>fclean</CODE>.
<P>
You need not clean a stream before using its descriptor for control
operations such as setting terminal modes; these operations don't affect
the file position and are not affected by it.  You can use any
descriptor for these operations, and all channels are affected
simultaneously.  However, text already "output" to a stream but still
buffered by the stream will be subject to the new terminal modes when
subsequently flushed.  To make sure "past" output is covered by the
terminal settings that were in effect at the time, flush the output
streams for that terminal before setting the modes.  See section <A HREF="library.html#SEC272">Terminal Modes</A>.
<P>
<A NAME="IDX672"></A>
<A NAME="IDX673"></A>
<A NAME="IDX674"></A>
<H2><A NAME="SEC180" HREF="library_toc.html#SEC180">Waiting for Input or Output</A></H2>
<P>
Sometimes a program needs to accept input on multiple input channels
whenever input arrives.  For example, some workstations may have devices
such as a digitizing tablet, function button box, or dial box that are
connected via normal asynchronous serial interfaces; good user interface
style requires responding immediately to input on any device.  Another
example is a program that acts as a server to several other processes
via pipes or sockets.
<P>
You cannot normally use <CODE>read</CODE> for this purpose, because this
blocks the program until input is available on one particular file
descriptor; input on other channels won't wake it up.  You could set
nonblocking mode and poll each file descriptor in turn, but this is very
inefficient.
<P>
A better solution is to use the <CODE>select</CODE> function.  This blocks the
program until input or output is ready on a specified set of file
descriptors, or until timer expires, whichever comes first.  This
facility is declared in the header file <TT>`sys/types.h'</TT>.
<A NAME="IDX675"></A>
<A NAME="IDX676"></A>
<P>
The file descriptor sets for the <CODE>select</CODE> function are specified
as <CODE>fd_set</CODE> objects.  Here is the description of the data type
and some macros for manipulating these objects.
<P>
<A NAME="IDX677"></A>
<U>Data Type:</U> <B>fd_set</B><P>
The <CODE>fd_set</CODE> data type represents file descriptor sets for the
<CODE>select</CODE> function.  It is actually a bit array.
<P>
<A NAME="IDX678"></A>
<U>Macro:</U> int <B>FD_SETSIZE</B><P>
The value of this macro is the maximum number of file descriptors that a
<CODE>fd_set</CODE> object can hold information about.  On systems with a
fixed maximum number, <CODE>FD_SETSIZE</CODE> is at least that number.  On
some systems, including GNU, there is no absolute limit on the number of
descriptors open, but this macro still has a constant value which
controls the number of bits in an <CODE>fd_set</CODE>.
<P>
<A NAME="IDX679"></A>
<U>Macro:</U> void <B>FD_ZERO</B> <I>(fd_set *<VAR>set</VAR>)</I><P>
This macro initializes the file descriptor set <VAR>set</VAR> to be the
empty set.
<P>
<A NAME="IDX680"></A>
<U>Macro:</U> void <B>FD_SET</B> <I>(int <VAR>filedes</VAR>, fd_set *<VAR>set</VAR>)</I><P>
This macro adds <VAR>filedes</VAR> to the file descriptor set <VAR>set</VAR>.
<P>
<A NAME="IDX681"></A>
<U>Macro:</U> void <B>FD_CLR</B> <I>(int <VAR>filedes</VAR>, fd_set *<VAR>set</VAR>)</I><P>
This macro removes <VAR>filedes</VAR> from the file descriptor set <VAR>set</VAR>.
<P>
<A NAME="IDX682"></A>
<U>Macro:</U> int <B>FD_ISSET</B> <I>(int <VAR>filedes</VAR>, fd_set *<VAR>set</VAR>)</I><P>
This macro returns a nonzero value (true) if <VAR>filedes</VAR> is a member
of the the file descriptor set <VAR>set</VAR>, and zero (false) otherwise.
<P>
Next, here is the description of the <CODE>select</CODE> function itself.
<P>
<A NAME="IDX683"></A>
<U>Function:</U> int <B>select</B> <I>(int <VAR>nfds</VAR>, fd_set *<VAR>read_fds</VAR>, fd_set *<VAR>write_fds</VAR>, fd_set *<VAR>except_fds</VAR>, struct timeval *<VAR>timeout</VAR>)</I><P>
The <CODE>select</CODE> function blocks the calling process until there is
activity on any of the specified sets of file descriptors, or until the
timeout period has expired.
<P>
The file descriptors specified by the <VAR>read_fds</VAR> argument are
checked to see if they are ready for reading; the <VAR>write_fds</VAR> file
descriptors are checked to see if they are ready for writing; and the
<VAR>except_fds</VAR> file descriptors are checked for exceptional
conditions.  You can pass a null pointer for any of these arguments if
you are not interested in checking for that kind of condition.
<P>
"Exceptional conditions" does not mean errors--errors are reported
immediately when an erroneous system call is executed, and do not
constitute a state of the descriptor.  Rather, they include conditions
such as the presence of an urgent message on a socket.  (See section <A HREF="library.html#SEC216">Sockets</A>,
for information on urgent messages.)
<P>
The <CODE>select</CODE> function checks only the first <VAR>nfds</VAR> file
descriptors.  The usual thing is to pass <CODE>FD_SETSIZE</CODE> as the value
of this argument.
<P>
The <VAR>timeout</VAR> specifies the maximum time to wait.  If you pass a
null pointer for this argument, it means to block indefinitely until one
of the file descriptors is ready.  Otherwise, you should provide the
time in <CODE>struct timeval</CODE> format; see section <A HREF="library.html#SEC315">High-Resolution Calendar</A>.  Specify zero as the time (a <CODE>struct timeval</CODE> containing
all zeros) if you want to find out which descriptors are ready without
waiting if none are ready.
<P>
The normal return value from <CODE>select</CODE> is the total number of ready file
descriptors in all of the sets.  Each of the argument sets is overwritten
with information about the descriptors that are ready for the corresponding
operation.  Thus, to see if a particular descriptor <VAR>desc</VAR> has input,
use <CODE>FD_ISSET (<VAR>desc</VAR>, <VAR>read_fds</VAR>)</CODE> after <CODE>select</CODE> returns.
<P>
If <CODE>select</CODE> returns because the timeout period expires, it returns
a value of zero.
<P>
Any signal will cause <CODE>select</CODE> to return immediately.  So if your
program uses signals, you can't rely on <CODE>select</CODE> to keep waiting
for the full time specified.  If you want to be sure of waiting for a
particular amount of time, you must check for <CODE>EINTR</CODE> and repeat
the <CODE>select</CODE> with a newly calculated timeout based on the current
time.  See the example below.  See also section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
If an error occurs, <CODE>select</CODE> returns <CODE>-1</CODE> and does not modify
the argument file descriptor sets.  The following <CODE>errno</CODE> error 
conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>One of the file descriptor sets specified an invalid file descriptor.
<P>
<DT><CODE>EINTR</CODE>
<DD>The operation was interrupted by a signal.  See section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>timeout</VAR> argument is invalid; one of the components is negative
or too large.
</DL>
<P>
<STRONG>Portability Note:</STRONG>  The <CODE>select</CODE> function is a BSD Unix
feature.
<P>
Here is an example showing how you can use <CODE>select</CODE> to establish a
timeout period for reading from a file descriptor.  The <CODE>input_timeout</CODE>
function blocks the calling process until input is available on the
file descriptor, or until the timeout period expires.
<P>
<PRE>
#include &#60;stdio.h&#62;
#include &#60;unistd.h&#62;
#include &#60;sys/types.h&#62;
#include &#60;sys/time.h&#62;

int 
input_timeout (int filedes, unsigned int seconds)
{
  fd_set set;
  struct timeval timeout;

  /* Initialize the file descriptor set.  */
  FD_ZERO (&#38;set);
  FD_SET (filedes, &#38;set);

  /* Initialize the timeout data structure.  */
  timeout.tv_sec = seconds;
  timeout.tv_usec = 0;

  /* <CODE>select</CODE> returns 0 if timeout, 1 if input available, -1 if error.  */
  return TEMP_FAILURE_RETRY (select (FD_SETSIZE, &#38;set, NULL, NULL, &#38;timeout));
}

int
main (void)
{
  fprintf (stderr, "select returned %d.\n", input_timeout (STDIN_FILENO, 5));
  return 0;
}
</PRE>
<P>
There is another example showing the use of <CODE>select</CODE> to multiplex
input from multiple sockets in section <A HREF="library.html#SEC254">Byte Stream Connection Server Example</A>.
<P>
<H2><A NAME="SEC181" HREF="library_toc.html#SEC181">Control Operations on Files</A></H2>
<A NAME="IDX684"></A>
<A NAME="IDX685"></A>
<P>
This section describes how you can perform various other operations on
file descriptors, such as inquiring about or setting flags describing
the status of the file descriptor, manipulating record locks, and the
like.  All of these operations are performed by the function <CODE>fcntl</CODE>.
<P>
The second argument to the <CODE>fcntl</CODE> function is a command that
specifies which operation to perform.  The function and macros that name
various flags that are used with it are declared in the header file
<TT>`fcntl.h'</TT>.  (Many of these flags are also used by the <CODE>open</CODE>
function; see section <A HREF="library.html#SEC172">Opening and Closing Files</A>.)
<A NAME="IDX686"></A>
<P>
<A NAME="IDX687"></A>
<U>Function:</U> int <B>fcntl</B> <I>(int <VAR>filedes</VAR>, int <VAR>command</VAR>, ...)</I><P>
The <CODE>fcntl</CODE> function performs the operation specified by
<VAR>command</VAR> on the file descriptor <VAR>filedes</VAR>.  Some commands
require additional arguments to be supplied.  These additional arguments
and the return value and error conditions are given in the detailed
descriptions of the individual commands.
<P>
Briefly, here is a list of what the various commands are.
<P>
<DL COMPACT>
<DT><CODE>F_DUPFD</CODE>
<DD>Duplicate the file descriptor (return another file descriptor pointing
to the same open file).  See section <A HREF="library.html#SEC182">Duplicating Descriptors</A>.
<P>
<DT><CODE>F_GETFD</CODE>
<DD>Get flags associated with the file descriptor.  See section <A HREF="library.html#SEC183">File Descriptor Flags</A>.
<P>
<DT><CODE>F_SETFD</CODE>
<DD>Set flags associated with the file descriptor.  See section <A HREF="library.html#SEC183">File Descriptor Flags</A>.
<P>
<DT><CODE>F_GETFL</CODE>
<DD>Get flags associated with the open file.  See section <A HREF="library.html#SEC184">File Status Flags</A>.
<P>
<DT><CODE>F_SETFL</CODE>
<DD>Set flags associated with the open file.  See section <A HREF="library.html#SEC184">File Status Flags</A>.
<P>
<DT><CODE>F_GETLK</CODE>
<DD>Get a file lock.  See section <A HREF="library.html#SEC185">File Locks</A>.
<P>
<DT><CODE>F_SETLK</CODE>
<DD>Set or clear a file lock.  See section <A HREF="library.html#SEC185">File Locks</A>.
<P>
<DT><CODE>F_SETLKW</CODE>
<DD>Like <CODE>F_SETLK</CODE>, but wait for completion.  See section <A HREF="library.html#SEC185">File Locks</A>.
<P>
<DT><CODE>F_GETOWN</CODE>
<DD>Get process or process group ID to receive <CODE>SIGIO</CODE> signals.
See section <A HREF="library.html#SEC186">Interrupt-Driven Input</A>.
<P>
<DT><CODE>F_SETOWN</CODE>
<DD>Set process or process group ID to receive <CODE>SIGIO</CODE> signals.
See section <A HREF="library.html#SEC186">Interrupt-Driven Input</A>.
</DL>
<P>
<H2><A NAME="SEC182" HREF="library_toc.html#SEC182">Duplicating Descriptors</A></H2>
<A NAME="IDX688"></A>
<A NAME="IDX689"></A>
<P>
You can <DFN>duplicate</DFN> a file descriptor, or allocate another file
descriptor that refers to the same open file as the original.  Duplicate
descriptors share one file position and one set of file status flags
(see section <A HREF="library.html#SEC184">File Status Flags</A>), but each has its own set of file descriptor
flags (see section <A HREF="library.html#SEC183">File Descriptor Flags</A>).
<P>
The major use of duplicating a file descriptor is to implement
<DFN>redirection</DFN> of input or output:  that is, to change the
file or pipe that a particular file descriptor corresponds to.
<P>
You can perform this operation using the <CODE>fcntl</CODE> function with the
<CODE>F_DUPFD</CODE> command, but there are also convenient functions
<CODE>dup</CODE> and <CODE>dup2</CODE> for duplicating descriptors.
<A NAME="IDX690"></A>
<A NAME="IDX691"></A>
<P>
The <CODE>fcntl</CODE> function and flags are declared in <TT>`fcntl.h'</TT>,
while prototypes for <CODE>dup</CODE> and <CODE>dup2</CODE> are in the header file
<TT>`unistd.h'</TT>.
<P>
<A NAME="IDX692"></A>
<U>Function:</U> int <B>dup</B> <I>(int <VAR>old</VAR>)</I><P>
This function copies descriptor <VAR>old</VAR> to the first available
descriptor number (the first number not currently open).  It is
equivalent to <CODE>fcntl (<VAR>old</VAR>, F_DUPFD, 0)</CODE>.
<P>
<A NAME="IDX693"></A>
<U>Function:</U> int <B>dup2</B> <I>(int <VAR>old</VAR>, int <VAR>new</VAR>)</I><P>
This function copies the descriptor <VAR>old</VAR> to descriptor number
<VAR>new</VAR>.
<P>
If <VAR>old</VAR> is an invalid descriptor, then <CODE>dup2</CODE> does nothing; it
does not close <VAR>new</VAR>.  Otherwise, the new duplicate of <VAR>old</VAR>
replaces any previous meaning of descriptor <VAR>new</VAR>, as if <VAR>new</VAR>
were closed first.
<P>
If <VAR>old</VAR> and <VAR>new</VAR> are different numbers, and <VAR>old</VAR> is a
valid descriptor number, then <CODE>dup2</CODE> is equivalent to:
<P>
<PRE>
close (<VAR>new</VAR>);
fcntl (<VAR>old</VAR>, F_DUPFD, <VAR>new</VAR>)
</PRE>
<P>
However, <CODE>dup2</CODE> does this atomically; there is no instant in the
middle of calling <CODE>dup2</CODE> at which <VAR>new</VAR> is closed and not yet a
duplicate of <VAR>old</VAR>.
<P>
<A NAME="IDX694"></A>
<U>Macro:</U> int <B>F_DUPFD</B><P>
This macro is used as the <VAR>command</VAR> argument to <CODE>fcntl</CODE>, to
copy the file descriptor given as the first argument.
<P>
The form of the call in this case is:
<P>
<PRE>
fcntl (<VAR>old</VAR>, F_DUPFD, <VAR>next_filedes</VAR>)
</PRE>
<P>
The <VAR>next_filedes</VAR> argument is of type <CODE>int</CODE> and specifies that
the file descriptor returned should be the next available one greater
than or equal to this value.
<P>
The return value from <CODE>fcntl</CODE> with this command is normally the value
of the new file descriptor.  A return value of <CODE>-1</CODE> indicates an
error.  The following <CODE>errno</CODE> error conditions are defined for
this command:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>old</VAR> argument is invalid.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>next_filedes</VAR> argument is invalid.
<P>
<DT><CODE>EMFILE</CODE>
<DD>There are no more file descriptors available--your program is already
using the maximum.
</DL>
<P>
<CODE>ENFILE</CODE> is not a possible error code for <CODE>dup2</CODE> because
<CODE>dup2</CODE> does not create a new opening of a file; duplicate
descriptors do not count toward the limit which <CODE>ENFILE</CODE>
indicates.  <CODE>EMFILE</CODE> is possible because it refers to the limit on
distinct descriptor numbers in use in one process.
<P>
Here is an example showing how to use <CODE>dup2</CODE> to do redirection.
Typically, redirection of the standard streams (like <CODE>stdin</CODE>) is
done by a shell or shell-like program before calling one of the
<CODE>exec</CODE> functions (see section <A HREF="library.html#SEC406">Executing a File</A>) to execute a new
program in a child process.  When the new program is executed, it
creates and initializes the standard streams to point to the
corresponding file descriptors, before its <CODE>main</CODE> function is
invoked.
<P>
So, to redirect standard input to a file, the shell could do something
like:
<P>
<PRE>
pid = fork ();
if (pid == 0)
  {
    char *filename;
    char *program;
    int file;
    ...
    file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
    dup2 (file, STDIN_FILENO);
    TEMP_FAILURE_RETRY (close (file));
    execv (program, NULL);
  }
</PRE>
<P>
There is also a more detailed example showing how to implement redirection
in the context of a pipeline of processes in section <A HREF="library.html#SEC420">Launching Jobs</A>.
<P>
<A NAME="IDX695"></A>
<H2><A NAME="SEC183" HREF="library_toc.html#SEC183">File Descriptor Flags</A></H2>
<P>
<DFN>File descriptor flags</DFN> are miscellaneous attributes of a file
descriptor.  These flags are associated with particular file
descriptors, so that if you have created duplicate file descriptors
from a single opening of a file, each descriptor has its own set of flags.
<P>
Currently there is just one file descriptor flag: <CODE>FD_CLOEXEC</CODE>,
which causes the descriptor to be closed if you use any of the
<CODE>exec...</CODE> functions (see section <A HREF="library.html#SEC406">Executing a File</A>).
<P>
The symbols in this section are defined in the header file
<TT>`fcntl.h'</TT>.
<A NAME="IDX696"></A>
<P>
<A NAME="IDX697"></A>
<U>Macro:</U> int <B>F_GETFD</B><P>
This macro is used as the <VAR>command</VAR> argument to <CODE>fcntl</CODE>, to
specify that it should return the file descriptor flags associated
with the <VAR>filedes</VAR> argument.  
<P>
The normal return value from <CODE>fcntl</CODE> with this command is a
nonnegative number which can be interpreted as the bitwise OR of the
individual flags (except that currently there is only one flag to use).
<P>
In case of an error, <CODE>fcntl</CODE> returns <CODE>-1</CODE>.  The following
<CODE>errno</CODE> error conditions are defined for this command:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is invalid.
</DL>
<P>
<A NAME="IDX698"></A>
<U>Macro:</U> int <B>F_SETFD</B><P>
This macro is used as the <VAR>command</VAR> argument to <CODE>fcntl</CODE>, to
specify that it should set the file descriptor flags associated with the
<VAR>filedes</VAR> argument.  This requires a third <CODE>int</CODE> argument to
specify the new flags, so the form of the call is:
<P>
<PRE>
fcntl (<VAR>filedes</VAR>, F_SETFD, <VAR>new_flags</VAR>)
</PRE>
<P>
The normal return value from <CODE>fcntl</CODE> with this command is an
unspecified value other than <CODE>-1</CODE>, which indicates an error.
The flags and error conditions are the same as for the <CODE>F_GETFD</CODE>
command.
<P>
The following macro is defined for use as a file descriptor flag with
the <CODE>fcntl</CODE> function.  The value is an integer constant usable
as a bit mask value.
<P>
<A NAME="IDX699"></A>
<A NAME="IDX700"></A>
<U>Macro:</U> int <B>FD_CLOEXEC</B><P>
This flag specifies that the file descriptor should be closed when
an <CODE>exec</CODE> function is invoked; see section <A HREF="library.html#SEC406">Executing a File</A>.  When
a file descriptor is allocated (as with <CODE>open</CODE> or <CODE>dup</CODE>),
this bit is initially cleared on the new file descriptor, meaning that
descriptor will survive into the new program after <CODE>exec</CODE>.
<P>
If you want to modify the file descriptor flags, you should get the
current flags with <CODE>F_GETFD</CODE> and modify the value.  Don't assume
that the flag listed here is the only ones that are implemented; your
program may be run years from now and more flags may exist then.
For example, here is a function to set or clear the flag <CODE>FD_CLOEXEC</CODE>
without altering any other flags:
<P>
<PRE>
/* Set the <CODE>FD_CLOEXEC</CODE> flag of <VAR>desc</VAR> if <VAR>value</VAR> is nonzero,
   or clear the flag if <VAR>value</VAR> is 0.
   Return 0 on success, or -1 on error with <CODE>errno</CODE> set. */ 

int
set_cloexec_flag (int desc, int value)
{
  int oldflags = fcntl (desc, F_GETFD, 0);
  /* If reading the flags failed, return error indication now.
  if (oldflags &#60; 0)
    return oldflags;
  /* Set just the flag we want to set. */
  if (value != 0)
    oldflags |= FD_CLOEXEC;
  else
    oldflags &#38;= ~FD_CLOEXEC;
  /* Store modified flag word in the descriptor. */
  return fcntl (desc, F_SETFD, oldflags);
}
</PRE>
<P>
<A NAME="IDX701"></A>
<H2><A NAME="SEC184" HREF="library_toc.html#SEC184">File Status Flags</A></H2>
<P>
<DFN>File status flags</DFN> are used to specify attributes of the opening of
a file.  Unlike the file descriptor flags discussed in section <A HREF="library.html#SEC183">File Descriptor Flags</A>, the file status flags are shared by duplicated file descriptors
resulting from a single opening of the file.
<P>
The file status flags are initialized by the <CODE>open</CODE> function from
the <VAR>flags</VAR> argument of the <CODE>open</CODE> function.  Some of the flags
are meaningful only in <CODE>open</CODE> and are not remembered subsequently;
many of the rest cannot subsequently be changed, though you can read
their values by examining the file status flags.
<P>
A few file status flags can be changed at any time using <CODE>fcntl</CODE>.
These include <CODE>O_APPEND</CODE> and <CODE>O_NONBLOCK</CODE>.
<P>
The symbols in this section are defined in the header file
<TT>`fcntl.h'</TT>.
<A NAME="IDX702"></A>
<P>
<A NAME="IDX703"></A>
<U>Macro:</U> int <B>F_GETFL</B><P>
This macro is used as the <VAR>command</VAR> argument to <CODE>fcntl</CODE>, to
read the file status flags for the open file with descriptor
<VAR>filedes</VAR>.
<P>
The normal return value from <CODE>fcntl</CODE> with this command is a
nonnegative number which can be interpreted as the bitwise OR of the
individual flags.  The flags are encoded like the <VAR>flags</VAR> argument
to <CODE>open</CODE> (see section <A HREF="library.html#SEC172">Opening and Closing Files</A>), but only the file
access modes and the <CODE>O_APPEND</CODE> and <CODE>O_NONBLOCK</CODE> flags are
meaningful here.  Since the file access modes are not single-bit values,
you can mask off other bits in the returned flags with <CODE>O_ACCMODE</CODE>
to compare them.
<P>
In case of an error, <CODE>fcntl</CODE> returns <CODE>-1</CODE>.  The following
<CODE>errno</CODE> error conditions are defined for this command:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is invalid.
</DL>
<P>
<A NAME="IDX704"></A>
<U>Macro:</U> int <B>F_SETFL</B><P>
This macro is used as the <VAR>command</VAR> argument to <CODE>fcntl</CODE>, to set
the file status flags for the open file corresponding to the
<VAR>filedes</VAR> argument.  This command requires a third <CODE>int</CODE>
argument to specify the new flags, so the call looks like this:
<P>
<PRE>
fcntl (<VAR>filedes</VAR>, F_SETFL, <VAR>new_flags</VAR>)
</PRE>
<P>
You can't change the access mode for the file in this way; that is,
whether the file descriptor was opened for reading or writing.  You can
only change the <CODE>O_APPEND</CODE> and <CODE>O_NONBLOCK</CODE> flags.
<P>
The normal return value from <CODE>fcntl</CODE> with this command is an
unspecified value other than <CODE>-1</CODE>, which indicates an error.  The
error conditions are the same as for the <CODE>F_GETFL</CODE> command.
<P>
The following macros are defined for use in analyzing and constructing
file status flag values:
<P>
<DL COMPACT>
<DT><CODE>O_APPEND</CODE>
<DD>The bit that enables append mode for the file.  If set, then all
<CODE>write</CODE> operations write the data at the end of the file, extending
it, regardless of the current file position.
<P>
<DT><CODE>O_NONBLOCK</CODE>
<DD>The bit that enables nonblocking mode for the file.  If this bit is set,
<CODE>read</CODE> requests on the file can return immediately with a failure
status if there is no input immediately available, instead of blocking.
Likewise, <CODE>write</CODE> requests can also return immediately with a
failure status if the output can't be written immediately.
<P>
<DT><CODE>O_NDELAY</CODE>
<DD>This is a synonym for <CODE>O_NONBLOCK</CODE>, provided for compatibility with
BSD.
</DL>
<P>
<A NAME="IDX705"></A>
<U>Macro:</U> int <B>O_ACCMODE</B><P>
This macro stands for a mask that can be bitwise-ANDed with the file
status flag value to produce a value representing the file access mode.
The mode will be <CODE>O_RDONLY</CODE>, <CODE>O_WRONLY</CODE>, or <CODE>O_RDWR</CODE>.
<P>
<DL COMPACT>
<DT><CODE>O_RDONLY</CODE>
<DD>Open the file for read access.
<P>
<DT><CODE>O_WRONLY</CODE>
<DD>Open the file for write access.
<P>
<DT><CODE>O_RDWR</CODE>
<DD>Open the file for both reading and writing.
</DL>
<P>
If you want to modify the file status flags, you should get the current
flags with <CODE>F_GETFL</CODE> and modify the value.  Don't assume that the
flags listed here are the only ones that are implemented; your program
may be run years from now and more flags may exist then.  For example,
here is a function to set or clear the flag <CODE>O_NONBLOCK</CODE> without
altering any other flags:
<P>
<PRE>
/* Set the <CODE>O_NONBLOCK</CODE> flag of <VAR>desc</VAR> if <VAR>value</VAR> is nonzero,
   or clear the flag if <VAR>value</VAR> is 0.
   Return 0 on success, or -1 on error with <CODE>errno</CODE> set. */ 

int
set_nonblock_flag (int desc, int value)
{
  int oldflags = fcntl (desc, F_GETFL, 0);
  /* If reading the flags failed, return error indication now. */
  if (oldflags &#60; 0)
    return oldflags;
  /* Set just the flag we want to set. */
  if (value != 0)
    oldflags |= O_NONBLOCK;
  else
    oldflags &#38;= ~O_NONBLOCK;
  /* Store modified flag word in the descriptor. */
  return fcntl (desc, F_SETFL, oldflags);
}
</PRE>
<P>
<H2><A NAME="SEC185" HREF="library_toc.html#SEC185">File Locks</A></H2>
<A NAME="IDX706"></A>
<A NAME="IDX707"></A>
<P>
The remaining <CODE>fcntl</CODE> commands are used to support <DFN>record
locking</DFN>, which permits multiple cooperating programs to prevent each
other from simultaneously accessing parts of a file in error-prone
ways.
<A NAME="IDX708"></A>
<A NAME="IDX709"></A>
<P>
An <DFN>exclusive</DFN> or <DFN>write</DFN> lock gives a process exclusive access
for writing to the specified part of the file.  While a write lock is in
place, no other process can lock that part of the file.
<A NAME="IDX710"></A>
<A NAME="IDX711"></A>
<P>
A <DFN>shared</DFN> or <DFN>read</DFN> lock prohibits any other process from
requesting a write lock on the specified part of the file.  However,
other processes can request read locks.
<P>
The <CODE>read</CODE> and <CODE>write</CODE> functions do not actually check to see
whether there are any locks in place.  If you want to implement a
locking protocol for a file shared by multiple processes, your application
must do explicit <CODE>fcntl</CODE> calls to request and clear locks at the
appropriate points.
<P>
Locks are associated with processes.  A process can only have one kind
of lock set for each byte of a given file.  When any file descriptor for
that file is closed by the process, all of the locks that process holds
on that file are released, even if the locks were made using other
descriptors that remain open.  Likewise, locks are released when a
process exits, and are not inherited by child processes created using
<CODE>fork</CODE> (see section <A HREF="library.html#SEC405">Creating a Process</A>).
<P>
When making a lock, use a <CODE>struct flock</CODE> to specify what kind of
lock and where.  This data type and the associated macros for the
<CODE>fcntl</CODE> function are declared in the header file <TT>`fcntl.h'</TT>.
<A NAME="IDX712"></A>
<P>
<A NAME="IDX713"></A>
<U>struct Type:</U> <B>flock</B><P>
This structure is used with the <CODE>fcntl</CODE> function to describe a file
lock.  It has these members:
<P>
<DL COMPACT>
<DT><CODE>short int l_type</CODE>
<DD>Specifies the type of the lock; one of <CODE>F_RDLCK</CODE>, <CODE>F_WRLCK</CODE>, or
<CODE>F_UNLCK</CODE>.
<P>
<DT><CODE>short int l_whence</CODE>
<DD>This corresponds to the <VAR>whence</VAR> argument to <CODE>fseek</CODE> or
<CODE>lseek</CODE>, and specifies what the offset is relative to.  Its value
can be one of <CODE>SEEK_SET</CODE>, <CODE>SEEK_CUR</CODE>, or <CODE>SEEK_END</CODE>.
<P>
<DT><CODE>off_t l_start</CODE>
<DD>This specifies the offset of the start of the region to which the lock
applies, and is given in bytes relative to the point specified by
<CODE>l_whence</CODE> member.
<P>
<DT><CODE>off_t l_len</CODE>
<DD>This specifies the length of the region to be locked.  A value of
<CODE>0</CODE> is treated specially; it means the region extends to the end of
the file.
<P>
<DT><CODE>pid_t l_pid</CODE>
<DD>This field is the process ID (see section <A HREF="library.html#SEC403">Process Creation Concepts</A>) of the
process holding the lock.  It is filled in by calling <CODE>fcntl</CODE> with
the <CODE>F_GETLK</CODE> command, but is ignored when making a lock.
</DL>
<P>
<A NAME="IDX714"></A>
<U>Macro:</U> int <B>F_GETLK</B><P>
This macro is used as the <VAR>command</VAR> argument to <CODE>fcntl</CODE>, to
specify that it should get information about a lock.  This command
requires a third argument of type <CODE>struct flock *</CODE> to be passed
to <CODE>fcntl</CODE>, so that the form of the call is:
<P>
<PRE>
fcntl (<VAR>filedes</VAR>, F_GETLK, <VAR>lockp</VAR>)
</PRE>
<P>
If there is a lock already in place that would block the lock described
by the <VAR>lockp</VAR> argument, information about that lock overwrites
<CODE>*<VAR>lockp</VAR></CODE>.  Existing locks are not reported if they are
compatible with making a new lock as specified.  Thus, you should
specify a lock type of <CODE>F_WRLCK</CODE> if you want to find out about both
read and write locks, or <CODE>F_RDLCK</CODE> if you want to find out about
write locks only.
<P>
There might be more than one lock affecting the region specified by the
<VAR>lockp</VAR> argument, but <CODE>fcntl</CODE> only returns information about
one of them.  The <CODE>l_whence</CODE> member of the <VAR>lockp</VAR> structure is
set to <CODE>SEEK_SET</CODE> and the <CODE>l_start</CODE> and <CODE>l_len</CODE> fields
set to identify the locked region.
<P>
If no lock applies, the only change to the <VAR>lockp</VAR> structure is to
update the <CODE>l_type</CODE> to a value of <CODE>F_UNLCK</CODE>.
<P>
The normal return value from <CODE>fcntl</CODE> with this command is an
unspecified value other than <CODE>-1</CODE>, which is reserved to indicate an
error.  The following <CODE>errno</CODE> error conditions are defined for
this command:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is invalid.
<P>
<DT><CODE>EINVAL</CODE>
<DD>Either the <VAR>lockp</VAR> argument doesn't specify valid lock information,
or the file associated with <VAR>filedes</VAR> doesn't support locks.
</DL>
<P>
<A NAME="IDX715"></A>
<U>Macro:</U> int <B>F_SETLK</B><P>
This macro is used as the <VAR>command</VAR> argument to <CODE>fcntl</CODE>, to
specify that it should set or clear a lock.  This command requires a
third argument of type <CODE>struct flock *</CODE> to be passed to
<CODE>fcntl</CODE>, so that the form of the call is:
<P>
<PRE>
fcntl (<VAR>filedes</VAR>, F_SETLK, <VAR>lockp</VAR>)
</PRE>
<P>
If the process already has a lock on any part of the region, the old lock
on that part is replaced with the new lock.  You can remove a lock
by specifying the a lock type of <CODE>F_UNLCK</CODE>.
<P>
If the lock cannot be set, <CODE>fcntl</CODE> returns immediately with a value
of <CODE>-1</CODE>.  This function does not block waiting for other processes
to release locks.  If <CODE>fcntl</CODE> succeeds, it return a value other
than <CODE>-1</CODE>.
<P>
The following <CODE>errno</CODE> error conditions are defined for this
function:
<P>
<DL COMPACT>
<DT><CODE>EACCES</CODE>
<DD><DT><CODE>EAGAIN</CODE>
<DD>The lock cannot be set because it is blocked by an existing lock on the
file.  Some systems use <CODE>EAGAIN</CODE> in this case, and other systems
use <CODE>EACCES</CODE>; your program should treat them alike, after
<CODE>F_SETLK</CODE>.
<P>
<DT><CODE>EBADF</CODE>
<DD>Either: the <VAR>filedes</VAR> argument is invalid; you requested a read lock
but the <VAR>filedes</VAR> is not open for read access; or, you requested a
write lock but the <VAR>filedes</VAR> is not open for write access.
<P>
<DT><CODE>EINVAL</CODE>
<DD>Either the <VAR>lockp</VAR> argument doesn't specify valid lock information,
or the file associated with <VAR>filedes</VAR> doesn't support locks.
<P>
<DT><CODE>ENOLCK</CODE>
<DD>The system has run out of file lock resources; there are already too
many file locks in place.
<P>
Well-designed file systems never report this error, because they have no
limitation on the number of locks.  However, you must still take account
of the possibility of this error, as it could result from network access
to a file system on another machine.
</DL>
<P>
<A NAME="IDX716"></A>
<U>Macro:</U> int <B>F_SETLKW</B><P>
This macro is used as the <VAR>command</VAR> argument to <CODE>fcntl</CODE>, to
specify that it should set or clear a lock.  It is just like the
<CODE>F_SETLK</CODE> command, but causes the process to block (or wait)
until the request can be specified.
<P>
This command requires a third argument of type <CODE>struct flock *</CODE>, as
for the <CODE>F_SETLK</CODE> command.
<P>
The <CODE>fcntl</CODE> return values and errors are the same as for the
<CODE>F_SETLK</CODE> command, but these additional <CODE>errno</CODE> error conditions
are defined for this command:
<P>
<DL COMPACT>
<DT><CODE>EINTR</CODE>
<DD>The function was interrupted by a signal while it was waiting.
See section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<DT><CODE>EDEADLK</CODE>
<DD>A deadlock condition was detected.  This can happen if two processes
each already controlling a locked region request a lock on the same
region locked by the other process.
</DL>
<P>
The following macros are defined for use as values for the <CODE>l_type</CODE>
member of the <CODE>flock</CODE> structure.  The values are integer constants.
<P>
<A NAME="IDX717"></A>
<DL COMPACT>
<DT><CODE>F_RDLCK</CODE>
<DD>This macro is used to specify a read (or shared) lock.
<A NAME="IDX718"></A>
<P>
<DT><CODE>F_WRLCK</CODE>
<DD>This macro is used to specify a write (or exclusive) lock.
<A NAME="IDX719"></A>
<P>
<DT><CODE>F_UNLCK</CODE>
<DD>This macro is used to specify that the region is unlocked.
</DL>
<P>
As an example of a situation where file locking is useful, consider a
program that can be run simultaneously by several different users, that
logs status information to a common file.  One example of such a program
might be a game that uses a file to keep track of high scores.  Another
example might be a program that records usage or accounting information
for billing purposes.
<P>
Having multiple copies of the program simultaneously writing to the
file could cause the contents of the file to become mixed up.  But
you can prevent this kind of problem by setting a write lock on the
file before actually writing to the file.  
<P>
If the program also needs to read the file and wants to make sure that
the contents of the file are in a consistent state, then it can also use
a read lock.  While the read lock is set, no other process can lock
that part of the file for writing.
<P>
Remember that file locks are only a <EM>voluntary</EM> protocol for
controlling access to a file.  There is still potential for access to
the file by programs that don't use the lock protocol.
<P>
<H2><A NAME="SEC186" HREF="library_toc.html#SEC186">Interrupt-Driven Input</A></H2>
<A NAME="IDX720"></A>
<P>
If you set the <CODE>FASYNC</CODE> status flag on a file descriptor
(see section <A HREF="library.html#SEC184">File Status Flags</A>), a <CODE>SIGIO</CODE> signal is sent whenever
input or output becomes possible on that file descriptor.  The process
or process group to receive the signal can be selected by using the
<CODE>F_SETOWN</CODE> command to the <CODE>fcntl</CODE> function.  If the file
descriptor is a socket, this also selects the recipient of <CODE>SIGURG</CODE>
signals that are delivered when out-of-band data arrives on that socket;
see section <A HREF="library.html#SEC255">Out-of-Band Data</A>.
<P>
If the file descriptor corresponds to a terminal device, then <CODE>SIGIO</CODE>
signals are sent to the foreground process group of the terminal.  
See section <A HREF="library.html#SEC411">Job Control</A>.
<A NAME="IDX721"></A>
<P>
The symbols in this section are defined in the header file
<TT>`fcntl.h'</TT>.
<P>
<A NAME="IDX722"></A>
<U>Macro:</U> int <B>F_GETOWN</B><P>
This macro is used as the <VAR>command</VAR> argument to <CODE>fcntl</CODE>, to
specify that it should get information about the process or process
group to which <CODE>SIGIO</CODE> signals are sent.  (For a terminal, this is
actually the foreground process group ID, which you can get using
<CODE>tcgetpgrp</CODE>; see section <A HREF="library.html#SEC428">Functions for Controlling Terminal Access</A>.)
<P>
The return value is interpreted as a process ID; if negative, its
absolute value is the process group ID.
<P>
The following <CODE>errno</CODE> error condition is defined for this command:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is invalid.
</DL>
<P>
<A NAME="IDX723"></A>
<U>Macro:</U> int <B>F_SETOWN</B><P>
This macro is used as the <VAR>command</VAR> argument to <CODE>fcntl</CODE>, to
specify that it should set the process or process group to which
<CODE>SIGIO</CODE> signals are sent.  This command requires a third argument
of type <CODE>pid_t</CODE> to be passed to <CODE>fcntl</CODE>, so that the form of
the call is:
<P>
<PRE>
fcntl (<VAR>filedes</VAR>, F_SETOWN, <VAR>pid</VAR>)
</PRE>
<P>
The <VAR>pid</VAR> argument should be a process ID.  You can also pass a
negative number whose absolute value is a process group ID.
<P>
The return value from <CODE>fcntl</CODE> with this command is <CODE>-1</CODE>
in case of error and some other value if successful.  The following
<CODE>errno</CODE> error conditions are defined for this command:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is invalid.
<P>
<DT><CODE>ESRCH</CODE>
<DD>There is no process or process group corresponding to <VAR>pid</VAR>.
</DL>
<P>
<H1><A NAME="SEC187" HREF="library_toc.html#SEC187">File System Interface</A></H1>
<P>
This chapter describes the GNU C library's functions for manipulating
files.  Unlike the input and output functions described in
section <A HREF="library.html#SEC117">Input/Output on Streams</A> and section <A HREF="library.html#SEC171">Low-Level Input/Output</A>, these
functions are concerned with operating on the files themselves, rather
than on their contents.
<P>
Among the facilities described in this chapter are functions for
examining or modifying directories, functions for renaming and deleting
files, and functions for examining and setting file attributes such as
access permissions and modification times.
<P>
<H2><A NAME="SEC188" HREF="library_toc.html#SEC188">Working Directory</A></H2>
<A NAME="IDX724"></A>
<A NAME="IDX725"></A>
<A NAME="IDX726"></A>
<P>
Each process has associated with it a directory, called its <DFN>current
working directory</DFN> or simply <DFN>working directory</DFN>, that is used in
the resolution of relative file names (see section <A HREF="library.html#SEC114">File Name Resolution</A>).
<P>
When you log in and begin a new session, your working directory is
initially set to the home directory associated with your login account
in the system user database.  You can find any user's home directory
using the <CODE>getpwuid</CODE> or <CODE>getpwnam</CODE> functions; see section <A HREF="library.html#SEC441">User Database</A>.
<P>
Users can change the working directory using shell commands like
<CODE>cd</CODE>.  The functions described in this section are the primitives
used by those commands and by other programs for examining and changing
the working directory.
<A NAME="IDX727"></A>
<P>
Prototypes for these functions are declared in the header file
<TT>`unistd.h'</TT>.
<A NAME="IDX728"></A>
<P>
<A NAME="IDX729"></A>
<U>Function:</U> char * <B>getcwd</B> <I>(char *<VAR>buffer</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>getcwd</CODE> function returns an absolute file name representing
the current working directory, storing it in the character array
<VAR>buffer</VAR> that you provide.  The <VAR>size</VAR> argument is how you tell
the system the allocation size of <VAR>buffer</VAR>.
<P>
The GNU library version of this function also permits you to specify a
null pointer for the <VAR>buffer</VAR> argument.  Then <CODE>getcwd</CODE>
allocates a buffer automatically, as with <CODE>malloc</CODE>
(see section <A HREF="library.html#SEC21">Unconstrained Allocation</A>).  If the <VAR>size</VAR> is greater than
zero, then the buffer is that large; otherwise, the buffer is as large
as necessary to hold the result.
<P>
The return value is <VAR>buffer</VAR> on success and a null pointer on failure.
The following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>size</VAR> argument is zero and <VAR>buffer</VAR> is not a null pointer.
<P>
<DT><CODE>ERANGE</CODE>
<DD>The <VAR>size</VAR> argument is less than the length of the working directory
name.  You need to allocate a bigger array and try again.
<P>
<DT><CODE>EACCES</CODE>
<DD>Permission to read or search a component of the file name was denied.
</DL>
<P>
Here is an example showing how you could implement the behavior of GNU's
<CODE>getcwd (NULL, 0)</CODE> using only the standard behavior of
<CODE>getcwd</CODE>:
<P>
<PRE>
char *
gnu_getcwd ()
{
  int size = 100;
  char *buffer = (char *) xmalloc (size);

  while (1)
    {
      char *value = getcwd (buffer, size);
      if (value != 0)
        return buffer;
      size *= 2;
      free (buffer);
      buffer = (char *) xmalloc (size);
    }
}
</PRE>
<P>
See section <A HREF="library.html#SEC23">Examples of <CODE>malloc</CODE></A>, for information about <CODE>xmalloc</CODE>, which is
not a library function but is a customary name used in most GNU
software.
<P>
<A NAME="IDX730"></A>
<U>Function:</U> char * <B>getwd</B> <I>(char *<VAR>buffer</VAR>)</I><P>
This is similar to <CODE>getcwd</CODE>.  The GNU library provides <CODE>getwd</CODE>
for backwards compatibility with BSD.  The <VAR>buffer</VAR> should be a
pointer to an array at least <CODE>PATH_MAX</CODE> bytes long.
<P>
<A NAME="IDX731"></A>
<U>Function:</U> int <B>chdir</B> <I>(const char *<VAR>filename</VAR>)</I><P>
This function is used to set the process's working directory to
<VAR>filename</VAR>.
<P>
The normal, successful return value from <CODE>chdir</CODE> is <CODE>0</CODE>.  A
value of <CODE>-1</CODE> is returned to indicate an error.  The <CODE>errno</CODE>
error conditions defined for this function are the usual file name
syntax errors (see section <A HREF="library.html#SEC115">File Name Errors</A>), plus <CODE>ENOTDIR</CODE> if the
file <VAR>filename</VAR> is not a directory.
<P>
<A NAME="IDX732"></A>
<A NAME="IDX733"></A>
<A NAME="IDX734"></A>
<H2><A NAME="SEC189" HREF="library_toc.html#SEC189">Accessing Directories</A></H2>
<P>
The facilities described in this section let you read the contents of a
directory file.  This is useful if you want your program to list all the
files in a directory, perhaps as part of a menu.
<A NAME="IDX735"></A>
<P>
The <CODE>opendir</CODE> function opens a <DFN>directory stream</DFN> whose
elements are directory entries.  You use the <CODE>readdir</CODE> function on
the directory stream to retrieve these entries, represented as
<CODE>struct dirent</CODE> objects.  The name of the file for each entry is
stored in the <CODE>d_name</CODE> member of this structure.  There are obvious
parallels here to the stream facilities for ordinary files, described in
section <A HREF="library.html#SEC117">Input/Output on Streams</A>.
<P>
<H3><A NAME="SEC190" HREF="library_toc.html#SEC190">Format of a Directory Entry</A></H3>
<A NAME="IDX736"></A>
<P>
This section describes what you find in a single directory entry, as you
might obtain it from a directory stream.  All the symbols are declared
in the header file <TT>`dirent.h'</TT>.
<P>
<A NAME="IDX737"></A>
<U>Data Type:</U> <B>struct dirent</B><P>
This is a structure type used to return information about directory
entries.  It contains the following fields:
<P>
<DL COMPACT>
<DT><CODE>char *d_name</CODE>
<DD>This is the null-terminated file name component.  This is the only
field you can count on in all POSIX systems.
<P>
<DT><CODE>ino_t d_fileno</CODE>
<DD>This is the file serial number.  For BSD compatibility, you can also
refer to this member as <CODE>d_ino</CODE>.
<P>
<DT><CODE>size_t d_namlen</CODE>
<DD>This is the length of the file name, not including the terminating null
character.
</DL>
<P>
This structure may contain additional members in the future.
<P>
When a file has multiple names, each name has its own directory entry.
The only way you can tell that the directory entries belong to a
single file is that they have the same value for the <CODE>d_fileno</CODE>
field.
<P>
File attributes such as size, modification times, and the like are part
of the file itself, not any particular directory entry.  See section <A HREF="library.html#SEC200">File Attributes</A>.
<P>
<H3><A NAME="SEC191" HREF="library_toc.html#SEC191">Opening a Directory Stream</A></H3>
<A NAME="IDX738"></A>
<P>
This section describes how to open a directory stream.  All the symbols
are declared in the header file <TT>`dirent.h'</TT>.
<P>
<A NAME="IDX739"></A>
<U>Data Type:</U> <B>DIR</B><P>
The <CODE>DIR</CODE> data type represents a directory stream.  
<P>
You shouldn't ever allocate objects of the <CODE>struct dirent</CODE> or
<CODE>DIR</CODE> data types, since the directory access functions do that for
you.  Instead, you refer to these objects using the pointers returned by
the following functions.
<P>
<A NAME="IDX740"></A>
<U>Function:</U> DIR * <B>opendir</B> <I>(const char *<VAR>dirname</VAR>)</I><P>
The <CODE>opendir</CODE> function opens and returns a directory stream for
reading the directory whose file name is <VAR>dirname</VAR>.  The stream has
type <CODE>DIR *</CODE>.
<P>
If unsuccessful, <CODE>opendir</CODE> returns a null pointer.  In addition to
the usual file name syntax errors (see section <A HREF="library.html#SEC115">File Name Errors</A>), the
following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EACCES</CODE>
<DD>Read permission is denied for the directory named by <CODE>dirname</CODE>.
<P>
<DT><CODE>EMFILE</CODE>
<DD>The process has too many files open.
<P>
<DT><CODE>ENFILE</CODE>
<DD>The entire system, or perhaps the file system which contains the
directory, cannot support any additional open files at the moment.
(This problem cannot happen on the GNU system.)
</DL>
<P>
The <CODE>DIR</CODE> type is typically implemented using a file descriptor,
and the <CODE>opendir</CODE> function in terms of the <CODE>open</CODE> function.
See section <A HREF="library.html#SEC171">Low-Level Input/Output</A>.  Directory streams and the underlying
file descriptors are closed on <CODE>exec</CODE> (see section <A HREF="library.html#SEC406">Executing a File</A>).
<P>
<H3><A NAME="SEC192" HREF="library_toc.html#SEC192">Reading and Closing a Directory Stream</A></H3>
<A NAME="IDX741"></A>
<P>
This section describes how to read directory entries from a directory
stream, and how to close the stream when you are done with it.  All the
symbols are declared in the header file <TT>`dirent.h'</TT>.
<P>
<A NAME="IDX742"></A>
<U>Function:</U> struct dirent * <B>readdir</B> <I>(DIR *<VAR>dirstream</VAR>)</I><P>
This function reads the next entry from the directory.  It normally
returns a pointer to a structure containing information about the file.
This structure is statically allocated and can be rewritten by a
subsequent call.
<P>
<STRONG>Portability Note:</STRONG> On some systems, <CODE>readdir</CODE> may not
return entries for <TT>`.'</TT> and <TT>`..'</TT>.  See section <A HREF="library.html#SEC114">File Name Resolution</A>.
<P>
If there are no more entries in the directory or an error is detected,
<CODE>readdir</CODE> returns a null pointer.  The following <CODE>errno</CODE> error
conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>dirstream</VAR> argument is not valid.
</DL>
<P>
<A NAME="IDX743"></A>
<U>Function:</U> int <B>closedir</B> <I>(DIR *<VAR>dirstream</VAR>)</I><P>
This function closes the directory stream <VAR>dirstream</VAR>.  It returns
<CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  
<P>
The following <CODE>errno</CODE> error conditions are defined for this
function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>dirstream</VAR> argument is not valid.
</DL>
<P>
<H3><A NAME="SEC193" HREF="library_toc.html#SEC193">Simple Program to List a Directory</A></H3>
<P>
Here's a simple program that prints the names of the files in
the current working directory:
<P>
<PRE>
#include &#60;stddef.h&#62;
#include &#60;stdio.h&#62;
#include &#60;sys/types.h&#62;
#include &#60;dirent.h&#62;

int
main (void)
{
  DIR *dp;
  struct dirent *ep;

  dp = opendir ("./");
  if (dp != NULL)
    {
      while (ep = readdir (dp))
	puts (ep-&#62;d_name);
      (void) closedir (dp);
    }
  else
    puts ("Couldn't open the directory.");

  return 0;
}
</PRE>
<P>
The order in which files appear in a directory tends to be fairly
random.  A more useful program would sort the entries (perhaps by
alphabetizing them) before printing them; see section <A HREF="library.html#SEC89">Array Sort Function</A>
<P>
<H3><A NAME="SEC194" HREF="library_toc.html#SEC194">Random Access in a Directory Stream</A></H3>
<A NAME="IDX744"></A>
<P>
This section describes how to reread parts of a directory that you have
already read from an open directory stream.  All the symbols are
declared in the header file <TT>`dirent.h'</TT>.
<P>
<A NAME="IDX745"></A>
<U>Function:</U> void <B>rewinddir</B> <I>(DIR *<VAR>dirstream</VAR>)</I><P>
The <CODE>rewinddir</CODE> function is used to reinitialize the directory
stream <VAR>dirstream</VAR>, so that if you call <CODE>readdir</CODE> it
returns information about the first entry in the directory again.  This
function also notices if files have been added or removed to the
directory since it was opened with <CODE>opendir</CODE>.  (Entries for these
files might or might not be returned by <CODE>readdir</CODE> if they were
added or removed since you last called <CODE>opendir</CODE> or
<CODE>rewinddir</CODE>.)
<P>
<A NAME="IDX746"></A>
<U>Function:</U> off_t <B>telldir</B> <I>(DIR *<VAR>dirstream</VAR>)</I><P>
The <CODE>telldir</CODE> function returns the file position of the directory
stream <VAR>dirstream</VAR>.  You can use this value with <CODE>seekdir</CODE> to
restore the directory stream to that position.
<P>
<A NAME="IDX747"></A>
<U>Function:</U> void <B>seekdir</B> <I>(DIR *<VAR>dirstream</VAR>, off_t <VAR>pos</VAR>)</I><P>
The <CODE>seekdir</CODE> function sets the file position of the directory
stream <VAR>dirstream</VAR> to <VAR>pos</VAR>.  The value <VAR>pos</VAR> must be the
result of a previous call to <CODE>telldir</CODE> on this particular stream;
closing and reopening the directory can invalidate values returned by
<CODE>telldir</CODE>.
<P>
<A NAME="IDX748"></A>
<A NAME="IDX749"></A>
<A NAME="IDX750"></A>
<A NAME="IDX751"></A>
<H2><A NAME="SEC195" HREF="library_toc.html#SEC195">Hard Links</A></H2>
<P>
In POSIX systems, one file can have many names at the same time.  All of
the names are equally real, and no one of them is preferred to the
others.
<P>
To add a name to a file, use the <CODE>link</CODE> function.  (The new name is
also called a <DFN>hard link</DFN> to the file.)  Creating a new link to a
file does not copy the contents of the file; it simply makes a new name
by which the file can be known, in addition to the file's existing name
or names.
<P>
One file can have names in several directories, so the the organization
of the file system is not a strict hierarchy or tree.
<P>
Since a particular file exists within a single file system, all its
names must be in directories in that file system.  <CODE>link</CODE> reports
an error if you try to make a hard link to the file from another file
system.
<P>
The prototype for the <CODE>link</CODE> function is declared in the header
file <TT>`unistd.h'</TT>.
<A NAME="IDX752"></A>
<P>
<A NAME="IDX753"></A>
<U>Function:</U> int <B>link</B> <I>(const char *<VAR>oldname</VAR>, const char *<VAR>newname</VAR>)</I><P>
The <CODE>link</CODE> function makes a new link to the existing file named by
<VAR>oldname</VAR>, under the new name <VAR>newname</VAR>.
<P>
This function returns a value of <CODE>0</CODE> if it is successful and
<CODE>-1</CODE> on failure.  In addition to the usual file name syntax errors
(see section <A HREF="library.html#SEC115">File Name Errors</A>) for both <VAR>oldname</VAR> and <VAR>newname</VAR>, the
following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EACCES</CODE>
<DD>The directory in which the new link is to be written is not writable.
<P>
<DT><CODE>EEXIST</CODE>
<DD>There is already a file named <VAR>newname</VAR>.  If you want to replace
this link with a new link, you must remove the old link explicitly first.
<P>
<DT><CODE>EMLINK</CODE>
<DD>There are already too many links to the file named by <VAR>oldname</VAR>.
(The maximum number of links to a file is <CODE>LINK_MAX</CODE>; see
section <A HREF="library.html#SEC463">Limits on File System Capacity</A>.)
<P>
Well-designed file systems never report this error, because they permit
more links than your disk could possibly hold.  However, you must still
take account of the possibility of this error, as it could result from
network access to a file system on another machine.
<P>
<DT><CODE>ENOENT</CODE>
<DD>The file named by <VAR>oldname</VAR> doesn't exist.  You can't make a link to
a file that doesn't exist.
<P>
<DT><CODE>ENOSPC</CODE>
<DD>The directory or file system that would contain the new link is "full"
and cannot be extended.
<P>
<DT><CODE>EPERM</CODE>
<DD>Some implementations only allow privileged users to make links to
directories, and others prohibit this operation entirely.  This error
is used to report the problem.
<P>
<DT><CODE>EROFS</CODE>
<DD>The directory containing the new link can't be modified because it's on
a read-only file system.
<P>
<DT><CODE>EXDEV</CODE>
<DD>The directory specified in <VAR>newname</VAR> is on a different file system
than the existing file.
</DL>
<P>
<A NAME="IDX754"></A>
<A NAME="IDX755"></A>
<A NAME="IDX756"></A>
<A NAME="IDX757"></A>
<H2><A NAME="SEC196" HREF="library_toc.html#SEC196">Symbolic Links</A></H2>
<P>
The GNU system supports <DFN>soft links</DFN> or <DFN>symbolic links</DFN>.  This
is a kind of "file" that is essentially a pointer to another file
name.  Unlike hard links, symbolic links can be made to directories or
across file systems with no restrictions.  You can also make a symbolic
link to a name which is not the name of any file.  (Opening this link
will fail until a file by that name is created.)  Likewise, if the
symbolic link points to an existing file which is later deleted, the
symbolic link continues to point to the same file name even though the
name no longer names any file.
<P>
The reason symbolic links work the way they do is that special things
happen when you try to open the link.  The <CODE>open</CODE> function realizes
you have specified the name of a link, reads the file name contained in
the link, and opens that file name instead.  The <CODE>stat</CODE> function
likewise operates on the file that the symbolic link points to, instead
of on the link itself.  So does <CODE>link</CODE>, the function that makes a
hard link.
<P>
By contrast, other operations such as deleting or renaming the file
operate on the link itself.  The functions <CODE>readlink</CODE> and 
<CODE>lstat</CODE> also refrain from following symbolic links, because
their purpose is to obtain information about the link.
<P>
Prototypes for the functions listed in this section are in
<TT>`unistd.h'</TT>.
<A NAME="IDX758"></A>
<P>
<A NAME="IDX759"></A>
<U>Function:</U> int <B>symlink</B> <I>(const char *<VAR>oldname</VAR>, const char *<VAR>newname</VAR>)</I><P>
The <CODE>symlink</CODE> function makes a symbolic link to <VAR>oldname</VAR> named
<VAR>newname</VAR>.
<P>
The normal return value from <CODE>symlink</CODE> is <CODE>0</CODE>.  A return value
of <CODE>-1</CODE> indicates an error.  In addition to the usual file name
syntax errors (see section <A HREF="library.html#SEC115">File Name Errors</A>), the following <CODE>errno</CODE>
error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EEXIST</CODE>
<DD>There is already an existing file named <VAR>newname</VAR>.
<P>
<DT><CODE>EROFS</CODE>
<DD>The file <VAR>newname</VAR> would exist on a read-only file system.
<P>
<DT><CODE>ENOSPC</CODE>
<DD>The directory or file system cannot be extended to make the new link.
<P>
<DT><CODE>EIO</CODE>
<DD>A hardware error occurred while reading or writing data on the disk.
<P>
</DL>
<P>
<A NAME="IDX760"></A>
<U>Function:</U> int <B>readlink</B> <I>(const char *<VAR>filename</VAR>, char *<VAR>buffer</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>readlink</CODE> function gets the value of the symbolic link
<VAR>filename</VAR>.  The file name that the link points to is copied into
<VAR>buffer</VAR>.  This file name string is <EM>not</EM> null-terminated;
<CODE>readlink</CODE> normally returns the number of characters copied.  The
<VAR>size</VAR> argument specifies the maximum number of characters to copy,
usually the allocation size of <VAR>buffer</VAR>.
<P>
If the return value equals <VAR>size</VAR>, you cannot tell whether or not
there was room to return the entire name.  So make a bigger buffer and
call <CODE>readlink</CODE> again.  Here is an example:
<P>
<PRE>
char *
readlink_malloc (char *filename)
{
  int size = 100;

  while (1)
    {
      char *buffer = (char *) xmalloc (size);
      int nchars = readlink (filename, buffer, size);
      if (nchars &#60; size)
        return buffer;
      free (buffer);
      size *= 2;
    }
}
</PRE>
<P>
A value of <CODE>-1</CODE> is returned in case of error.  In addition to the
usual file name syntax errors (see section <A HREF="library.html#SEC115">File Name Errors</A>), the following
<CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>The named file is not a symbolic link.
<P>
<DT><CODE>EIO</CODE>
<DD>A hardware error occurred while reading or writing data on the disk.
</DL>
<P>
<A NAME="IDX761"></A>
<A NAME="IDX762"></A>
<A NAME="IDX763"></A>
<H2><A NAME="SEC197" HREF="library_toc.html#SEC197">Deleting Files</A></H2>
<P>
You can delete a file with the functions <CODE>unlink</CODE> or <CODE>remove</CODE>.
(These names are synonymous.)
<P>
Deletion actually deletes a file name.  If this is the file's only name,
then the file is deleted as well.  If the file has other names as well
(see section <A HREF="library.html#SEC195">Hard Links</A>), it remains accessible under its other names.
<P>
<A NAME="IDX764"></A>
<U>Function:</U> int <B>unlink</B> <I>(const char *<VAR>filename</VAR>)</I><P>
The <CODE>unlink</CODE> function deletes the file name <VAR>filename</VAR>.  If
this is a file's sole name, the file itself is also deleted.  (Actually,
if any process has the file open when this happens, deletion is
postponed until all processes have closed the file.)
<A NAME="IDX765"></A>
<P>
The function <CODE>unlink</CODE> is declared in the header file <TT>`unistd.h'</TT>.
<P>
This function returns <CODE>0</CODE> on successful completion, and <CODE>-1</CODE>
on error.  In addition to the usual file name syntax errors
(see section <A HREF="library.html#SEC115">File Name Errors</A>), the following <CODE>errno</CODE> error conditions are 
defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EACCESS</CODE>
<DD>Write permission is denied for the directory from which the file is to be
removed.
<P>
<DT><CODE>EBUSY</CODE>
<DD>This error indicates that the file is being used by the system in such a
way that it can't be unlinked.  Examples of situations where you might
see this error are if the file name specifies the root directory or a
mount point for a file system.
<P>
<DT><CODE>ENOENT</CODE>
<DD>The file name to be deleted doesn't exist.
<P>
<DT><CODE>EPERM</CODE>
<DD>On some systems, <CODE>unlink</CODE> cannot be used to delete the name of a
directory, or can only be used this way by a privileged user.
To avoid such problems, use <CODE>rmdir</CODE> to delete directories.
<P>
<DT><CODE>EROFS</CODE>
<DD>The directory in which the file name is to be deleted is on a read-only
file system, and can't be modified.
</DL>
<P>
<A NAME="IDX766"></A>
<U>Function:</U> int <B>remove</B> <I>(const char *<VAR>filename</VAR>)</I><P>
The <CODE>remove</CODE> function is another name for <CODE>unlink</CODE>.
<CODE>remove</CODE> is the ANSI C name, whereas <CODE>unlink</CODE> is the POSIX.1
name.  The name <CODE>remove</CODE> is declared in <TT>`stdio.h'</TT>.
<A NAME="IDX767"></A>
<P>
<A NAME="IDX768"></A>
<A NAME="IDX769"></A>
<A NAME="IDX770"></A>
<U>Function:</U> int <B>rmdir</B> <I>(const char *<VAR>filename</VAR>)</I><P>
The <CODE>rmdir</CODE> function deletes a directory.  The directory must be
empty before it can be removed; in other words, it can only contain
entries for <TT>`.'</TT> and <TT>`..'</TT>.
<P>
In most other respects, <CODE>rmdir</CODE> behaves like <CODE>unlink</CODE>.  There
are two additional <CODE>errno</CODE> error conditions defined for
<CODE>rmdir</CODE>:
<P>
<DL COMPACT>
<DT><CODE>EEXIST</CODE>
<DD><DT><CODE>ENOTEMPTY</CODE>
<DD>The directory to be deleted is not empty.  
</DL>
<P>
These two error codes are synonymous; some systems use one, and some
use the other.
<P>
The prototype for this function is declared in the header file
<TT>`unistd.h'</TT>.
<A NAME="IDX771"></A>
<P>
<H2><A NAME="SEC198" HREF="library_toc.html#SEC198">Renaming Files</A></H2>
<P>
The <CODE>rename</CODE> function is used to change a file's name.
<A NAME="IDX772"></A>
<P>
<A NAME="IDX773"></A>
<U>Function:</U> int <B>rename</B> <I>(const char *<VAR>oldname</VAR>, const char *<VAR>newname</VAR>)</I><P>
The <CODE>rename</CODE> function renames the file name <VAR>oldname</VAR> with
<VAR>newname</VAR>.  The file formerly accessible under the name
<VAR>oldname</VAR> is afterward accessible as <VAR>newname</VAR> instead.  (If the
file had any other names aside from <VAR>oldname</VAR>, it continues to have
those names.)
<P>
The directory containing the name <VAR>newname</VAR> must be on the same
file system as the file (as indicated by the name <VAR>oldname</VAR>).
<P>
One special case for <CODE>rename</CODE> is when <VAR>oldname</VAR> and
<VAR>newname</VAR> are two names for the same file.  The consistent way to
handle this case is to delete <VAR>oldname</VAR>.  However, POSIX says that
in this case <CODE>rename</CODE> does nothing and reports success--which is
inconsistent.  We don't know what your operating system will do.  The
GNU system, when completed, will probably do the right thing (delete
<VAR>oldname</VAR>) unless you explicitly request strict POSIX compatibility
"even when it hurts".
<P>
If the <VAR>oldname</VAR> is not a directory, then any existing file named
<VAR>newname</VAR> is removed during the renaming operation.  However, if
<VAR>newname</VAR> is the name of a directory, <CODE>rename</CODE> fails in this
case.
<P>
If the <VAR>oldname</VAR> is a directory, then either <VAR>newname</VAR> must not
exist or it must name a directory that is empty.  In the latter case,
the existing directory named <VAR>newname</VAR> is deleted first.  The name
<VAR>newname</VAR> must not specify a subdirectory of the directory
<CODE>oldname</CODE> which is being renamed.
<P>
One useful feature of <CODE>rename</CODE> is that the meaning of the name
<VAR>newname</VAR> changes "atomically" from any previously existing file
by that name to its new meaning (the file that was called
<VAR>oldname</VAR>).  There is no instant at which <VAR>newname</VAR> is
nonexistent "in between" the old meaning and the new meaning.
<P>
If <CODE>rename</CODE> fails, it returns <CODE>-1</CODE>.  In addition to the usual
file name syntax errors (see section <A HREF="library.html#SEC115">File Name Errors</A>), the following
<CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EACCES</CODE>
<DD>One of the directories containing <VAR>newname</VAR> or <VAR>oldname</VAR>
refuses write permission; or <VAR>newname</VAR> and <VAR>oldname</VAR> are
directories and write permission is refused for one of them.
<P>
<DT><CODE>EBUSY</CODE>
<DD>A directory named by <VAR>oldname</VAR> or <VAR>newname</VAR> is being used by
the system in a way that prevents the renaming from working.  This includes
directories that are mount points for filesystems, and directories
that are the current working directories of processes.
<P>
<DT><CODE>EEXIST</CODE>
<DD>The directory <VAR>newname</VAR> isn't empty.
<P>
<DT><CODE>ENOTEMPTY</CODE>
<DD>The directory <VAR>newname</VAR> isn't empty.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>oldname</VAR> is a directory that contains <VAR>newname</VAR>.
<P>
<DT><CODE>EISDIR</CODE>
<DD>The <VAR>newname</VAR> names a directory, but the <VAR>oldname</VAR> doesn't.
<P>
<DT><CODE>EMLINK</CODE>
<DD>The parent directory of <VAR>newname</VAR> would have too many links.
<P>
Well-designed file systems never report this error, because they permit
more links than your disk could possibly hold.  However, you must still
take account of the possibility of this error, as it could result from
network access to a file system on another machine.
<P>
<DT><CODE>ENOENT</CODE>
<DD>The file named by <VAR>oldname</VAR> doesn't exist.
<P>
<DT><CODE>ENOSPC</CODE>
<DD>The directory that would contain <VAR>newname</VAR> has no room for another
entry, and there is no space left in the file system to expand it.
<P>
<DT><CODE>EROFS</CODE>
<DD>The operation would involve writing to a directory on a read-only file
system.
<P>
<DT><CODE>EXDEV</CODE>
<DD>The two file names <VAR>newname</VAR> and <VAR>oldnames</VAR> are on different
file systems.
</DL>
<P>
<A NAME="IDX774"></A>
<A NAME="IDX775"></A>
<H2><A NAME="SEC199" HREF="library_toc.html#SEC199">Creating Directories</A></H2>
<A NAME="IDX776"></A>
<P>
Directories are created with the <CODE>mkdir</CODE> function.  (There is also
a shell command <CODE>mkdir</CODE> which does the same thing.)
<P>
<A NAME="IDX777"></A>
<U>Function:</U> int <B>mkdir</B> <I>(const char *<VAR>filename</VAR>, mode_t <VAR>mode</VAR>)</I><P>
The <CODE>mkdir</CODE> function creates a new, empty directory whose name is
<VAR>filename</VAR>.
<P>
The argument <VAR>mode</VAR> specifies the file permissions for the new
directory file.  See section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>, for more information about
this.
<P>
A return value of <CODE>0</CODE> indicates successful completion, and
<CODE>-1</CODE> indicates failure.  In addition to the usual file name syntax
errors (see section <A HREF="library.html#SEC115">File Name Errors</A>), the following <CODE>errno</CODE> error
conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EACCES</CODE>
<DD>Write permission is denied for the parent directory in which the new
directory is to be added.
<P>
<DT><CODE>EEXIST</CODE>
<DD>A file named <VAR>filename</VAR> already exists.
<P>
<DT><CODE>EMLINK</CODE>
<DD>The parent directory has too many links.
<P>
Well-designed file systems never report this error, because they permit
more links than your disk could possibly hold.  However, you must still
take account of the possibility of this error, as it could result from
network access to a file system on another machine.
<P>
<DT><CODE>ENOSPC</CODE>
<DD>The file system doesn't have enough room to create the new directory.
<P>
<DT><CODE>EROFS</CODE>
<DD>The parent directory of the directory being created is on a read-only
file system, and cannot be modified.
</DL>
<P>
To use this function, your program should include the header file
<TT>`sys/stat.h'</TT>.
<A NAME="IDX778"></A>
<P>
<H2><A NAME="SEC200" HREF="library_toc.html#SEC200">File Attributes</A></H2>
<A NAME="IDX779"></A>
<P>
When you issue an <SAMP>`ls -l'</SAMP> shell command on a file, it gives you
information about the size of the file, who owns it, when it was last
modified, and the like.  This kind of information is called the
<DFN>file attributes</DFN>; it is associated with the file itself and not a
particular one of its names.
<P>
This section contains information about how you can inquire about and
modify these attributes of files.
<P>
<A NAME="IDX780"></A>
<A NAME="IDX781"></A>
<A NAME="IDX782"></A>
<H3><A NAME="SEC201" HREF="library_toc.html#SEC201">What the File Attribute Values Mean</A></H3>
<P>
When you read the attributes of a file, they come back in a structure
called <CODE>struct stat</CODE>.  This section describes the names of the
attributes, their data types, and what they mean.  For the functions
to read the attributes of a file, see section <A HREF="library.html#SEC202">Reading the Attributes of a File</A>.
<P>
The header file <TT>`sys/stat.h'</TT> declares all the symbols defined
in this section.
<A NAME="IDX783"></A>
<P>
<A NAME="IDX784"></A>
<U>Data Type:</U> <B>struct stat</B><P>
The <CODE>stat</CODE> structure type is used to return information about the
attributes of a file.  It contains at least the following members:
<P>
<DL COMPACT>
<DT><CODE>mode_t st_mode</CODE>
<DD>Specifies the mode of the file.  This includes file type information
(see section <A HREF="library.html#SEC203">Testing the Type of a File</A>) and the file permission bits
(see section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>).
<P>
<DT><CODE>ino_t st_ino</CODE>
<DD>The file serial number, which distinguishes this file from all other
files on the same device.
<P>
<DT><CODE>dev_t st_dev</CODE>
<DD>Identifies the device containing the file.  The <CODE>st_ino</CODE> and
<CODE>st_dev</CODE>, taken together, uniquely identify the file.
<P>
<DT><CODE>nlink_t st_nlink</CODE>
<DD>The number of hard links to the file.  This count keeps track of how many
directories have entries for this file.  If the count is ever
decremented to zero, then the file itself is discarded.  Symbolic links
are not counted in the total.
<P>
<DT><CODE>uid_t st_uid</CODE>
<DD>The user ID of the file's owner.  See section <A HREF="library.html#SEC204">File Owner</A>.
<P>
<DT><CODE>gid_t st_gid</CODE>
<DD>The group ID of the file.  See section <A HREF="library.html#SEC204">File Owner</A>.
<P>
<DT><CODE>off_t st_size</CODE>
<DD>This specifies the size of a regular file in bytes.  For files that
are really devices and the like, this field isn't usually meaningful.
<P>
<DT><CODE>time_t st_atime</CODE>
<DD>This is the last access time for the file.  See section <A HREF="library.html#SEC209">File Times</A>.
<P>
<DT><CODE>unsigned long int st_atime_usec</CODE>
<DD>This is the fractional part of the last access time for the file.
See section <A HREF="library.html#SEC209">File Times</A>.
<P>
<DT><CODE>time_t st_mtime</CODE>
<DD>This is the time of the last modification to the contents of the file.
See section <A HREF="library.html#SEC209">File Times</A>.
<P>
<DT><CODE>unsigned long int st_mtime_usec</CODE>
<DD>This is the fractional part of the time of last modification to the
contents of the file.  See section <A HREF="library.html#SEC209">File Times</A>.
<P>
<DT><CODE>time_t st_ctime</CODE>
<DD>This is the time of the last modification to the attributes of the file.
See section <A HREF="library.html#SEC209">File Times</A>.
<P>
<DT><CODE>unsigned long int st_ctime_usec</CODE>
<DD>This is the fractional part of the time of last modification to the
attributes of the file.  See section <A HREF="library.html#SEC209">File Times</A>.
<P>
<DT><CODE>unsigned int st_nblocks</CODE>
<DD>This is the amount of disk space that the file occupies, measured in
units of 512-byte blocks.
<P>
The number of disk blocks is not strictly proportional to the size of
the file, for two reasons: the file system may use some blocks for
internal record keeping; and the file may be sparse--it may have
"holes" which contain zeros but do not actually take up space on the
disk.
<P>
You can tell (approximately) whether a file is sparse by comparing this
value with <CODE>st_size</CODE>, like this:
<P>
<PRE>
(st.st_blocks * 512 &#60; st.st_size)
</PRE>
<P>
This test is not perfect because a file that is just slightly sparse
might not be detected as sparse at all.  For practical applications,
this is not a problem.
<P>
<DT><CODE>unsigned int st_blksize</CODE>
<DD>The optimal block size for reading of writing this file.  You might use
this size for allocating the buffer space for reading of writing the
file.
</DL>
<P>
  Some of the file attributes have special data type names which exist
specifically for those attributes.  (They are all aliases for well-known
integer types that you know and love.)  These typedef names are defined
in the header file <TT>`sys/types.h'</TT> as well as in <TT>`sys/stat.h'</TT>.
Here is a list of them.
<P>
<A NAME="IDX785"></A>
<U>Data Type:</U> <B>mode_t</B><P>
This is an integer data type used to represent file modes.  In the
GNU system, this is equivalent to <CODE>unsigned int</CODE>.
<P>
<A NAME="IDX786"></A>
<P>
<A NAME="IDX787"></A>
<U>Data Type:</U> <B>ino_t</B><P>
This is an arithmetic data type used to represent file serial numbers.
(In Unix jargon, these are sometimes called <DFN>inode numbers</DFN>.)
In the GNU system, this type is equivalent to <CODE>unsigned long int</CODE>.
<P>
<A NAME="IDX788"></A>
<U>Data Type:</U> <B>dev_t</B><P>
This is an arithmetic data type used to represent file device numbers.
In the GNU system, this is equivalent to <CODE>int</CODE>.
<P>
<A NAME="IDX789"></A>
<U>Data Type:</U> <B>nlink_t</B><P>
This is an arithmetic data type used to represent file link counts.
In the GNU system, this is equivalent to <CODE>unsigned short int</CODE>.
<P>
<H3><A NAME="SEC202" HREF="library_toc.html#SEC202">Reading the Attributes of a File</A></H3>
<P>
To examine the attributes of files, use the functions <CODE>stat</CODE>,
<CODE>fstat</CODE> and <CODE>lstat</CODE>.  They return the attribute information in
a <CODE>struct stat</CODE> object.  All three functions are declared in the
header file <TT>`sys/stat.h'</TT>.
<P>
<A NAME="IDX790"></A>
<U>Function:</U> int <B>stat</B> <I>(const char *<VAR>filename</VAR>, struct stat *<VAR>buf</VAR>)</I><P>
The <CODE>stat</CODE> function returns information about the attributes of the
file named by <VAR>filename</VAR> in the structure pointed at by <VAR>buf</VAR>.
<P>
If <VAR>filename</VAR> is the name of a symbolic link, the attributes you get
describe the file that the link points to.  If the link points to a
nonexistent file name, then <CODE>stat</CODE> fails, reporting a nonexistent
file.
<P>
The return value is <CODE>0</CODE> if the operation is successful, and <CODE>-1</CODE>
on failure.  In addition to the usual file name syntax errors
(see section <A HREF="library.html#SEC115">File Name Errors</A>, the following <CODE>errno</CODE> error conditions
are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>ENOENT</CODE>
<DD>The file named by <VAR>filename</VAR> doesn't exist.
</DL>
<P>
<A NAME="IDX791"></A>
<U>Function:</U> int <B>fstat</B> <I>(int <VAR>filedes</VAR>, struct stat *<VAR>buf</VAR>)</I><P>
The <CODE>fstat</CODE> function is like <CODE>stat</CODE>, except that it takes an
open file descriptor as an argument instead of a file name.
See section <A HREF="library.html#SEC171">Low-Level Input/Output</A>.
<P>
Like <CODE>stat</CODE>, <CODE>fstat</CODE> returns <CODE>0</CODE> on success and <CODE>-1</CODE>
on failure.  The following <CODE>errno</CODE> error conditions are defined for
<CODE>fstat</CODE>:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
</DL>
<P>
<A NAME="IDX792"></A>
<U>Function:</U> int <B>lstat</B> <I>(const char *<VAR>filename</VAR>, struct stat *<VAR>buf</VAR>)</I><P>
The <CODE>lstat</CODE> function is like <CODE>stat</CODE>, except that it does not
follow symbolic links.  If <VAR>filename</VAR> is the name of a symbolic
link, <CODE>lstat</CODE> returns information about the link itself; otherwise,
<CODE>lstat</CODE> works like <CODE>stat</CODE>.  See section <A HREF="library.html#SEC196">Symbolic Links</A>.
<P>
<H3><A NAME="SEC203" HREF="library_toc.html#SEC203">Testing the Type of a File</A></H3>
<P>
The <DFN>file mode</DFN>, stored in the <CODE>st_mode</CODE> field of the file
attributes, contains two kinds of information: the file type code, and
the access permission bits.  This section discusses only the type code,
which you can use to tell whether the file is a directory, whether it is
a socket, and so on.  For information about the access permission,
section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
There are two predefined ways you can access the file type portion of
the file mode.  First of all, for each type of file, there is a 
<DFN>predicate macro</DFN> which examines a file mode value and returns
true or false--is the file of that type, or not.  Secondly, you can
mask out the rest of the file mode to get just a file type code.
You can compare this against various constants for the supported file
types.
<P>
All of the symbols listed in this section are defined in the header file
<TT>`sys/stat.h'</TT>.
<A NAME="IDX793"></A>
<P>
The following predicate macros test the type of a file, given the value
<VAR>m</VAR> which is the <CODE>st_mode</CODE> field returned by <CODE>stat</CODE> on
that file:
<P>
<A NAME="IDX794"></A>
<U>Macro:</U> int <B>S_ISDIR</B> <I>(mode_t <VAR>m</VAR>)</I><P>
This macro returns nonzero if the file is a directory.
<P>
<A NAME="IDX795"></A>
<U>Macro:</U> int <B>S_ISCHR</B> <I>(mode_t <VAR>m</VAR>)</I><P>
This macro returns nonzero if the file is a character special file (a
device like a terminal).
<P>
<A NAME="IDX796"></A>
<U>Macro:</U> int <B>S_ISBLK</B> <I>(mode_t <VAR>m</VAR>)</I><P>
This macro returns nonzero if the file is a block special file (a device
like a disk).
<P>
<A NAME="IDX797"></A>
<U>Macro:</U> int <B>S_ISREG</B> <I>(mode_t <VAR>m</VAR>)</I><P>
This macro returns nonzero if the file is a regular file.
<P>
<A NAME="IDX798"></A>
<U>Macro:</U> int <B>S_ISFIFO</B> <I>(mode_t <VAR>m</VAR>)</I><P>
This macro returns nonzero if the file is a FIFO special file, or a
pipe.  See section <A HREF="library.html#SEC211">Pipes and FIFOs</A>.
<P>
<A NAME="IDX799"></A>
<U>Macro:</U> int <B>S_ISLNK</B> <I>(mode_t <VAR>m</VAR>)</I><P>
This macro returns nonzero if the file is a symbolic link.
See section <A HREF="library.html#SEC196">Symbolic Links</A>.
<P>
<A NAME="IDX800"></A>
<U>Macro:</U> int <B>S_ISSOCK</B> <I>(mode_t <VAR>m</VAR>)</I><P>
This macro returns nonzero if the file is a socket.  See section <A HREF="library.html#SEC216">Sockets</A>.
<P>
An alterate non-POSIX method of testing the file type is supported for
compatibility with BSD.  The mode can be bitwise ANDed with
<CODE>S_IFMT</CODE> to extract the file type code, and compared to the
appropriate type code constant.  For example,
<P>
<PRE>
S_ISCHR (<VAR>mode</VAR>)
</PRE>
<P>
is equivalent to:
<P>
<PRE>
((<VAR>mode</VAR> &#38; S_IFMT) == S_IFCHR)
</PRE>
<P>
<A NAME="IDX801"></A>
<U>Macro:</U> int <B>S_IFMT</B><P>
This is a bit mask used to extract the file type code portion of a mode
value.
<P>
These are the symbolic names for the different file type codes:
<P>
<DL COMPACT>
<A NAME="IDX802"></A>
<DT><CODE>S_IFDIR</CODE>
<DD>This macro represents the value of the file type code for a directory file.
<P>
<A NAME="IDX803"></A>
<DT><CODE>S_IFCHR</CODE>
<DD>This macro represents the value of the file type code for a
character-oriented device file.
<P>
<A NAME="IDX804"></A>
<DT><CODE>S_IFBLK</CODE>
<DD>This macro represents the value of the file type code for a block-oriented
device file.
<P>
<A NAME="IDX805"></A>
<DT><CODE>S_IFREG</CODE>
<DD>This macro represents the value of the file type code for a regular file.
<P>
<A NAME="IDX806"></A>
<DT><CODE>S_IFLNK</CODE>
<DD>This macro represents the value of the file type code for a symbolic link.
<P>
<A NAME="IDX807"></A>
<DT><CODE>S_IFSOCK</CODE>
<DD>This macro represents the value of the file type code for a socket.
<P>
<A NAME="IDX808"></A>
<DT><CODE>S_IFIFO</CODE>
<DD>This macro represents the value of the file type code for a FIFO or pipe.
</DL>
<P>
<A NAME="IDX809"></A>
<A NAME="IDX810"></A>
<A NAME="IDX811"></A>
<H3><A NAME="SEC204" HREF="library_toc.html#SEC204">File Owner</A></H3>
<P>
Every file has an <DFN>owner</DFN> which is one of the registered user names
defined on the system.  Each file also has a <DFN>group</DFN>, which is one
of the defined groups.  The file owner can often be useful for showing
you who edited the file (especially when you edit with GNU Emacs), but
its main purpose is for access control.
<P>
The file owner and group play a role in determining access because the
file has one set of access permission bits for the user that is the
owner, another set that apply to users who belong to the file's group,
and a third set of bits that apply to everyone else.  See section <A HREF="library.html#SEC206">How Your Access to a File is Decided</A>, for the details of how access is decided based on this
data.
<P>
When a file is created, its owner is set from the effective user ID of
the process that creates it (see section <A HREF="library.html#SEC431">The Persona of a Process</A>).  The file's group
ID may be set from either effective group ID of the process, or the
group ID of the directory that contains the file, depending on the
system where the file is stored.  When you access a remote file system,
it behaves according to its own rule, not according to the system your
program is running on.  Thus, your program must be prepared to encounter
either kind of behavior, no matter what kind of system you run it on.
<A NAME="IDX812"></A>
<A NAME="IDX813"></A>
<P>
You can change the owner and/or group owner of an existing file using
the <CODE>chown</CODE> function.  This is the primitive for the <CODE>chown</CODE>
and <CODE>chgrp</CODE> shell commands.
<A NAME="IDX814"></A>
<P>
The prototype for this function is declared in <TT>`unistd.h'</TT>.
<P>
<A NAME="IDX815"></A>
<U>Function:</U> int <B>chown</B> <I>(const char *<VAR>filename</VAR>, uid_t <VAR>owner</VAR>, gid_t <VAR>group</VAR>)</I><P>
The <CODE>chown</CODE> function changes the owner of the file <VAR>filename</VAR> to
<VAR>owner</VAR>, and its group owner to <VAR>group</VAR>.
<P>
Changing the owner of the file on certain systems clears the set-user-ID
and set-group-ID bits of the file's permissions.  (This is because those
bits may not be appropriate for the new owner.)  The other file
permission bits are not changed.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.
In addition to the usual file name syntax errors (see section <A HREF="library.html#SEC115">File Name Errors</A>), 
the following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EPERM</CODE>
<DD>This process lacks permission to make the requested change.
<P>
Only privileged users or the file's owner can change the file's group.
On most file systems, only privileged users can change the file owner;
some file systems allow you to change the owner if you are currently the
owner.  When you access a remote file system, the behavior you encounter
is determined by the system that actually holds the file, not by the
system your program is running on.
<P>
See section <A HREF="library.html#SEC464">Optional Features in File Support</A>, for information about the
<CODE>_POSIX_CHOWN_RESTRICTED</CODE> macro.
<P>
<DT><CODE>EROFS</CODE>
<DD>The file is on a read-only file system.
</DL>
<P>
<A NAME="IDX816"></A>
<U>Function:</U> int <B>fchown</B> <I>(int <VAR>filedes</VAR>, int <VAR>owner</VAR>, int <VAR>group</VAR>)</I><P>
This is like <CODE>chown</CODE>, except that it changes the owner of the file
with open file descriptor <VAR>filedes</VAR>.
<P>
The return value from <CODE>fchown</CODE> is <CODE>0</CODE> on success and <CODE>-1</CODE>
on failure.  The following <CODE>errno</CODE> error codes are defined for this
function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>filedes</VAR> argument corresponds to a pipe or socket, not an ordinary
file.
<P>
<DT><CODE>EPERM</CODE>
<DD>This process lacks permission to make the requested change.  For
details, see <CODE>chmod</CODE>, above.
<P>
<DT><CODE>EROFS</CODE>
<DD>The file resides on a read-only file system.
</DL>
<P>
<H3><A NAME="SEC205" HREF="library_toc.html#SEC205">The Mode Bits for Access Permission</A></H3>
<P>
The <DFN>file mode</DFN>, stored in the <CODE>st_mode</CODE> field of the file
attributes, contains two kinds of information: the file type code, and
the access permission bits.  This section discusses only the access
permission bits, which control who can read or write the file.
See section <A HREF="library.html#SEC203">Testing the Type of a File</A>, for information about the file type code.
<P>
All of the symbols listed in this section are defined in the header file
<TT>`sys/stat.h'</TT>.
<A NAME="IDX817"></A>
<A NAME="IDX818"></A>
<P>
These symbolic constants are defined for the file mode bits that control
access permission for the file:
<P>
<DL COMPACT>
<A NAME="IDX819"></A>
<DT><CODE>S_IRUSR</CODE>
<DD><A NAME="IDX820"></A>
<DT><CODE>S_IREAD</CODE>
<DD>Read permission bit for the owner of the file.  On many systems, this
bit is 0400.  <CODE>S_IREAD</CODE> is an obsolete synonym provided for BSD
compatibility.
<P>
<A NAME="IDX821"></A>
<DT><CODE>S_IWUSR</CODE>
<DD><A NAME="IDX822"></A>
<DT><CODE>S_IWRITE</CODE>
<DD>Write permission bit for the owner of the file.  Usually 0200.
<CODE>S_IWRITE</CODE> is an obsolete synonym provided for BSD compatibility.
<P>
<A NAME="IDX823"></A>
<DT><CODE>S_IXUSR</CODE>
<DD><A NAME="IDX824"></A>
<DT><CODE>S_IEXEC</CODE>
<DD>Execute (for ordinary files) or search (for directories) permission bit
for the owner of the file.  Usually 0100.  <CODE>S_IEXEC</CODE> is an obsolete
synonym provided for BSD compatibility.
<P>
<A NAME="IDX825"></A>
<DT><CODE>S_IRWXU</CODE>
<DD>This is equivalent to <SAMP>`(S_IRUSR | S_IWUSR | S_IXUSR)'</SAMP>.
<P>
<A NAME="IDX826"></A>
<DT><CODE>S_IRGRP</CODE>
<DD>Read permission bit for the group owner of the file.  Usually 040.
<P>
<A NAME="IDX827"></A>
<DT><CODE>S_IWGRP</CODE>
<DD>Write permission bit for the group owner of the file.  Usually 020.
<P>
<A NAME="IDX828"></A>
<DT><CODE>S_IXGRP</CODE>
<DD>Execute or search permission bit for the group owner of the file.
Usually 010.
<P>
<A NAME="IDX829"></A>
<DT><CODE>S_IRWXG</CODE>
<DD>This is equivalent to <SAMP>`(S_IRGRP | S_IWGRP | S_IXGRP)'</SAMP>.
<P>
<A NAME="IDX830"></A>
<DT><CODE>S_IROTH</CODE>
<DD>Read permission bit for other users.  Usually 04.
<P>
<A NAME="IDX831"></A>
<DT><CODE>S_IWOTH</CODE>
<DD>Write permission bit for other users.  Usually 02.
<P>
<A NAME="IDX832"></A>
<DT><CODE>S_IXOTH</CODE>
<DD>Execute or search permission bit for other users.  Usually 01.
<P>
<A NAME="IDX833"></A>
<DT><CODE>S_IRWXO</CODE>
<DD>This is equivalent to <SAMP>`(S_IROTH | S_IWOTH | S_IXOTH)'</SAMP>.
<P>
<A NAME="IDX834"></A>
<DT><CODE>S_ISUID</CODE>
<DD>This is the set-user-ID on execute bit, usually 04000. 
See section <A HREF="library.html#SEC433">How an Application Can Change Persona</A>.
<P>
<A NAME="IDX835"></A>
<DT><CODE>S_ISGID</CODE>
<DD>This is the set-group-ID on execute bit, usually 02000.
See section <A HREF="library.html#SEC433">How an Application Can Change Persona</A>.
<A NAME="IDX836"></A>
<P>
<A NAME="IDX837"></A>
<DT><CODE>S_ISVTX</CODE>
<DD>This is the <DFN>sticky</DFN> bit, usually 01000.
<P>
On an executable file, it modifies the swapping policies of the system.
Normally, when a program terminates, its pages in core are immediately
freed and reused.  If the sticky bit is set on the executable file, the
system keeps the pages in core for a while as if the program were still
running.  This is advantageous for a program that is likely to be run
many times in succession.
<P>
On a directory, the sticky bit gives permission to delete a file in the
directory if you can write the contents of that file.  Ordinarily, a
user either can delete all the files in the directory or cannot delete
any of them (based on whether the user has write permission for the
directory).  The sticky bit makes it possible to control deletion for
individual files.
</DL>
<P>
The actual bit values of the symbols are listed in the table above
so you can decode file mode values when debugging your programs.
These bit values are correct for most systems, but they are not
guaranteed.
<P>
<STRONG>Warning:</STRONG> Writing explicit numbers for file permissions is bad
practice.  It is not only nonportable, it also requires everyone who
reads your program to remember what the bits mean.  To make your
program clean, use the symbolic names.
<P>
<A NAME="IDX838"></A>
<A NAME="IDX839"></A>
<A NAME="IDX840"></A>
<H3><A NAME="SEC206" HREF="library_toc.html#SEC206">How Your Access to a File is Decided</A></H3>
<P>
Recall that the operating system normally decides access permission for
a file based on the effective user and group IDs of the process, and its
supplementary group IDs, together with the file's owner, group and
permission bits.  These concepts are discussed in detail in
section <A HREF="library.html#SEC431">The Persona of a Process</A>.
<P>
If the effective user ID of the process matches the owner user ID of the
file, then permissions for read, write, and execute/search are
controlled by the corresponding "user" (or "owner") bits.  Likewise,
if any of the effective group ID or supplementary group IDs of the
process matches the group owner ID of the file, then permissions are
controlled by the "group" bits.  Otherwise, permissions are controlled
by the "other" bits.
<P>
Privileged users, like <SAMP>`root'</SAMP>, can access any file, regardless of
its file permission bits.  As a special case, for a file to be
executable even for a privileged user, at least one of its execute bits
must be set.
<P>
<H3><A NAME="SEC207" HREF="library_toc.html#SEC207">Assigning File Permissions</A></H3>
<A NAME="IDX841"></A>
<A NAME="IDX842"></A>
<P>
The primitive functions for creating files (for example, <CODE>open</CODE> or
<CODE>mkdir</CODE>) take a <VAR>mode</VAR> argument, which specifies the file
permissions for the newly created file.  But the specified mode is
modified by the process's <DFN>file creation mask</DFN>, or <DFN>umask</DFN>,
before it is used.
<P>
The bits that are set in the file creation mask identify permissions
that are always to be disabled for newly created files.  For example, if
you set all the "other" access bits in the mask, then newly created
files are not accessible at all to processes in the "other"
category, even if the <VAR>mode</VAR> argument specified to the creation 
function would permit such access.  In other words, the file creation
mask is the complement of the ordinary access permissions you want to
grant.
<P>
Programs that create files typically specify a <VAR>mode</VAR> argument that
includes all the permissions that make sense for the particular file.
For an ordinary file, this is typically read and write permission for
all classes of users.  These permissions are then restricted as
specified by the individual user's own file creation mask.
<A NAME="IDX843"></A>
<P>
To change the permission of an existing file given its name, call
<CODE>chmod</CODE>.  This function ignores the file creation mask; it uses
exactly the specified permission bits.
<A NAME="IDX844"></A>
<P>
In normal use, the file creation mask is initialized in the user's login
shell (using the <CODE>umask</CODE> shell command), and inherited by all
subprocesses.  Application programs normally don't need to worry about
the file creation mask.  It will do automatically what it is supposed to
do.
<P>
When your program should create a file and bypass the umask for its
access permissions, the easiest way to do this is to use <CODE>fchmod</CODE>
after opening the file, rather than changing the umask.
<P>
In fact, changing the umask is usually done only by shells.  They use
the <CODE>umask</CODE> function.
<P>
The functions in this section are declared in <TT>`sys/stat.h'</TT>.
<A NAME="IDX845"></A>
<P>
<A NAME="IDX846"></A>
<U>Function:</U> mode_t <B>umask</B> <I>(mode_t <VAR>mask</VAR>)</I><P>
The <CODE>umask</CODE> function sets the file creation mask of the current
process to <VAR>mask</VAR>, and returns the previous value of the file
creation mask.
<P>
Here is an example showing how to read the mask with <CODE>umask</CODE>
without changing it permanently:
<P>
<PRE>
mode_t
read_umask (void)
{
  mask = umask (0);
  umask (mask);
}
</PRE>
<P>
However, it is better to use <CODE>getumask</CODE> if you just want to read
the mask value, because that is reentrant (at least if you use the GNU
operating system).
<P>
<A NAME="IDX847"></A>
<U>Function:</U> mode_t <B>getumask</B> <I>(void)</I><P>
Return the current value of the file creation mask for the current
process.  This function is a GNU extension.
<P>
<A NAME="IDX848"></A>
<U>Function:</U> int <B>chmod</B> <I>(const char *<VAR>filename</VAR>, mode_t <VAR>mode</VAR>)</I><P>
The <CODE>chmod</CODE> function sets the access permission bits for the file
named by <VAR>filename</VAR> to <VAR>mode</VAR>.
<P>
If the <VAR>filename</VAR> names a symbolic link, <CODE>chmod</CODE> changes the
permission of the file pointed to by the link, not those of the link
itself.  There is actually no way to set the mode of a link, which is
always <CODE>-1</CODE>.
<P>
This function returns <CODE>0</CODE> if successful and <CODE>-1</CODE> if not.  In
addition to the usual file name syntax errors (see section <A HREF="library.html#SEC115">File Name Errors</A>), the following <CODE>errno</CODE> error conditions are defined for
this function:
<P>
<DL COMPACT>
<DT><CODE>ENOENT</CODE>
<DD>The named file doesn't exist.
<P>
<DT><CODE>EPERM</CODE>
<DD>This process does not have permission to change the access permission of
this file.  Only the file's owner (as judged by the effective user ID of
the process) or a privileged user can change them.
<P>
<DT><CODE>EROFS</CODE>
<DD>The file resides on a read-only file system.
</DL>
<P>
<A NAME="IDX849"></A>
<U>Function:</U> int <B>fchmod</B> <I>(int <VAR>filedes</VAR>, int <VAR>mode</VAR>)</I><P>
This is like <CODE>chmod</CODE>, except that it changes the permissions of
the file currently open via descriptor <VAR>filedes</VAR>.
<P>
The return value from <CODE>fchmod</CODE> is <CODE>0</CODE> on success and <CODE>-1</CODE>
on failure.  The following <CODE>errno</CODE> error codes are defined for this
function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>filedes</VAR> argument corresponds to a pipe or socket, or something
else that doesn't really have access permissions.
<P>
<DT><CODE>EPERM</CODE>
<DD>This process does not have permission to change the access permission of
this file.  Only the file's owner (as judged by the effective user ID of
the process) or a privileged user can change them.
<P>
<DT><CODE>EROFS</CODE>
<DD>The file resides on a read-only file system.
</DL>
<P>
<A NAME="IDX850"></A>
<A NAME="IDX851"></A>
<A NAME="IDX852"></A>
<H3><A NAME="SEC208" HREF="library_toc.html#SEC208">Testing Permission to Access a File</A></H3>
<P>
When a program runs as a privileged user, this permits it to access
files off-limits to ordinary users--for example, to modify
<TT>`/etc/passwd'</TT>.  Programs designed to be run by ordinary users but
access such files use the setuid bit feature so that they always run
with <CODE>root</CODE> as the effective user ID.
 
Such a program may also access files specified by the user, files which
conceptually are being accessed explicitly by the user.  Since the
program runs as <CODE>root</CODE>, it has permission to access whatever file
the user specifies--but usually the desired behavior is to permit only
those files which the user could ordinarily access.
<P>
The program therefore must explicitly check whether <EM>the user</EM>
would have the necessary access to a file, before it reads or writes the
file.
<P>
To do this, use the function <CODE>access</CODE>, which checks for access
permission based on the process's <EM>real</EM> user ID rather than the
effective user ID.  (The setuid feature does not alter the real user ID,
so it reflects the user who actually ran the program.)
<P>
There is another way you could check this access, which is easy to
describe, but very hard to use.  This is to examine the file mode bits
and mimic the system's own access computation.  This method is
undesirable because many systems have additional access control
features; your program cannot portably mimic them, and you would not
want to try to keep track of the diverse features that different systems
have.  Using <CODE>access</CODE> is simple and automatically does whatever is
appropriate for the system you are using.
<A NAME="IDX853"></A>
<P>
The symbols in this section are declared in <TT>`unistd.h'</TT>.
<P>
<A NAME="IDX854"></A>
<U>Function:</U> int <B>access</B> <I>(const char *<VAR>filename</VAR>, int <VAR>how</VAR>)</I><P>
The <CODE>access</CODE> function checks to see whether the file named by
<VAR>filename</VAR> can be accessed in the way specified by the <VAR>how</VAR>
argument.  The <VAR>how</VAR> argument either can be the bitwise OR of the
flags <CODE>R_OK</CODE>, <CODE>W_OK</CODE>, <CODE>X_OK</CODE>, or the existence test
<CODE>F_OK</CODE>.
<P>
This function uses the <EM>real</EM> user and group ID's of the calling
process, rather than the <EM>effective</EM> ID's, to check for access
permission.  As a result, if you use the function from a <CODE>setuid</CODE>
or <CODE>setgid</CODE> program (see section <A HREF="library.html#SEC433">How an Application Can Change Persona</A>), it gives
information relative to the user who actually ran the program.
<P>
The return value is <CODE>0</CODE> if the access is permitted, and <CODE>-1</CODE>
otherwise.  (In other words, treated as a predicate function,
<CODE>access</CODE> returns true if the requested access is <EM>denied</EM>.)
<P>
In addition to the usual file name syntax errors (see section <A HREF="library.html#SEC115">File Name Errors</A>), the following <CODE>errno</CODE> error conditions are defined for
this function:
<P>
<DL COMPACT>
<DT><CODE>EACCES</CODE>
<DD>The access specified by <VAR>how</VAR> is denied.
<P>
<DT><CODE>ENOENT</CODE>
<DD>The file doesn't exist.
<P>
<DT><CODE>EROFS</CODE>
<DD>Write permission was requested for a file on a read-only file system.
</DL>
<P>
These macros are defined in the header file <TT>`unistd.h'</TT> for use
as the <VAR>how</VAR> argument to the <CODE>access</CODE> function.  The values
are integer constants.
<A NAME="IDX855"></A>
<P>
<A NAME="IDX856"></A>
<U>Macro:</U> int <B>R_OK</B><P>
Argument that means, test for read permission.
<P>
<A NAME="IDX857"></A>
<U>Macro:</U> int <B>W_OK</B><P>
Argument that means, test for write permission.
<P>
<A NAME="IDX858"></A>
<U>Macro:</U> int <B>X_OK</B><P>
Argument that means, test for execute/search permission.
<P>
<A NAME="IDX859"></A>
<U>Macro:</U> int <B>F_OK</B><P>
Argument that means, test for existence of the file.
<P>
<H3><A NAME="SEC209" HREF="library_toc.html#SEC209">File Times</A></H3>
<A NAME="IDX860"></A>
<A NAME="IDX861"></A>
<A NAME="IDX862"></A>
<P>
Each file has three timestamps associated with it:  its access time,
its modification time, and its attribute modification time.  These
correspond to the <CODE>st_atime</CODE>, <CODE>st_mtime</CODE>, and <CODE>st_ctime</CODE>
members of the <CODE>stat</CODE> structure; see section <A HREF="library.html#SEC200">File Attributes</A>.  
<P>
All of these times are represented in calendar time format, as
<CODE>time_t</CODE> objects.  This data type is defined in <TT>`time.h'</TT>.
For more information about representation and manipulation of time
values, see section <A HREF="library.html#SEC313">Calendar Time</A>.
<A NAME="IDX863"></A>
<P>
When an existing file is opened, its attribute change time and
modification time fields are updated.  Reading from a file updates its
access time attribute, and writing updates its modification time.
<P>
When a file is created, all three timestamps for that file are set to
the current time.  In addition, the attribute change time and
modification time fields of the directory that contains the new entry
are updated.
<P>
Adding a new name for a file with the <CODE>link</CODE> function updates the
attribute change time field of the file being linked, and both the
attribute change time and modification time fields of the directory
containing the new name.  These same fields are affected if a file name
is deleted with <CODE>unlink</CODE>, <CODE>remove</CODE>, or <CODE>rmdir</CODE>.  Renaming
a file with <CODE>rename</CODE> affects only the attribute change time and
modification time fields of the two parent directories involved, and not
the times for the file being renamed.
<P>
Changing attributes of a file (for example, with <CODE>chmod</CODE>) updates
its attribute change time field.
<P>
You can also change some of the timestamps of a file explicitly using
the <CODE>utime</CODE> function--all except the attribute change time.  You
need to include the header file <TT>`utime.h'</TT> to use this facility.
<A NAME="IDX864"></A>
<P>
<A NAME="IDX865"></A>
<U>Data Type:</U> <B>struct utimbuf</B><P>
The <CODE>utimbuf</CODE> structure is used with the <CODE>utime</CODE> function to
specify new access and modification times for a file.  It contains the
following members:
<P>
<DL COMPACT>
<DT><CODE>time_t actime</CODE>
<DD>This is the access time for the file.
<P>
<DT><CODE>time_t modtime</CODE>
<DD>This is the modification time for the file.
</DL>
<P>
<A NAME="IDX866"></A>
<U>Function:</U> int <B>utime</B> <I>(const char *<VAR>filename</VAR>, const struct utimbuf *<VAR>times</VAR>)</I><P>
This function is used to modify the file times associated with the file
named <VAR>filename</VAR>.
<P>
If <VAR>times</VAR> is a null pointer, then the access and modification times
of the file are set to the current time.  Otherwise, they are set to the
values from the <CODE>actime</CODE> and <CODE>modtime</CODE> members (respectively)
of the <CODE>utimbuf</CODE> structure pointed at by <VAR>times</VAR>.  
<P>
The attribute modification time for the file is set to the current time
in either case (since changing the timestamps is itself a modification
of the file attributes).
<P>
The <CODE>utime</CODE> function returns <CODE>0</CODE> if successful and <CODE>-1</CODE>
on failure.  In addition to the usual file name syntax errors
(see section <A HREF="library.html#SEC115">File Name Errors</A>), the following <CODE>errno</CODE> error conditions
are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EACCES</CODE>
<DD>There is a permission problem in the case where a null pointer was
passed as the <VAR>times</VAR> argument.  In order to update the timestamp on
the file, you must either be the owner of the file, have write
permission on the file, or be a privileged user.
<P>
<DT><CODE>ENOENT</CODE>
<DD>The file doesn't exist.
<P>
<DT><CODE>EPERM</CODE>
<DD>If the <VAR>times</VAR> argument is not a null pointer, you must either be
the owner of the file or be a privileged user.  This error is used to
report the problem.
<P>
<DT><CODE>EROFS</CODE>
<DD>The file lives on a read-only file system.
</DL>
<P>
Each of the three time stamps has a corresponding microsecond part,
which extends its resolution.  These fields are called
<CODE>st_atime_usec</CODE>, <CODE>st_mtime_usec</CODE>, and <CODE>st_ctime_usec</CODE>;
each has a value between 0 and 999,999, which indicates the time in
microseconds.  They correspond to the <CODE>tv_usec</CODE> field of a
<CODE>timeval</CODE> structure; see section <A HREF="library.html#SEC315">High-Resolution Calendar</A>.
<P>
The <CODE>utimes</CODE> function is like <CODE>utime</CODE>, but also lets you specify
the fractional part of the file times.  The prototype for this function is
in the header file <TT>`sys/time.h'</TT>.
<A NAME="IDX867"></A>
<P>
<A NAME="IDX868"></A>
<U>Function:</U> int <B>utimes</B> <I>(const char *<VAR>filename</VAR>, struct timeval <VAR>tvp</VAR><TT>[2]</TT>)</I><P>
This function sets the file access and modification times for the file
named by <VAR>filename</VAR>.  The new file access time is specified by
<CODE><VAR>tvp</VAR>[0]</CODE>, and the new modification time by
<CODE><VAR>tvp</VAR>[1]</CODE>.  This function comes from BSD.
<P>
The return values and error conditions are the same as for the <CODE>utime</CODE>
function.
<P>
<A NAME="IDX869"></A>
<A NAME="IDX870"></A>
<H2><A NAME="SEC210" HREF="library_toc.html#SEC210">Making Special Files</A></H2>
<P>
The <CODE>mknod</CODE> function is the primitive for making special files,
such as files that correspond to devices.  The GNU library includes
this function for compatibility with BSD.
<P>
The prototype for <CODE>mknod</CODE> is declared in <TT>`sys/stat.h'</TT>.
<A NAME="IDX871"></A>
<P>
<A NAME="IDX872"></A>
<U>Function:</U> int <B>mknod</B> <I>(const char *<VAR>filename</VAR>, int <VAR>mode</VAR>, int <VAR>dev</VAR>)</I><P>
The <CODE>mknod</CODE> function makes a special file with name <VAR>filename</VAR>.
The <VAR>mode</VAR> specifies the mode of the file, and may include the various
special file bits, such as <CODE>S_IFCHR</CODE> (for a character special file)
or <CODE>S_IFBLK</CODE> (for a block special file).  See section <A HREF="library.html#SEC203">Testing the Type of a File</A>.
<P>
The <VAR>dev</VAR> argument specifies which device the special file refers to.
Its exact interpretation depends on the kind of special file being created.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on error.  In addition
to the usual file name syntax errors (see section <A HREF="library.html#SEC115">File Name Errors</A>), the
following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EPERM</CODE>
<DD>The calling process is not privileged.  Only the superuser can create
special files.
<P>
<DT><CODE>ENOSPC</CODE>
<DD>The directory or file system that would contain the new file is "full"
and cannot be extended.
<P>
<DT><CODE>EROFS</CODE>
<DD>The directory containing the new file can't be modified because it's on
a read-only file system.
<P>
<DT><CODE>EEXIST</CODE>
<DD>There is already a file named <VAR>filename</VAR>.  If you want to replace
this file, you must remove the old file explicitly first.
</DL>
<P>
<H1><A NAME="SEC211" HREF="library_toc.html#SEC211">Pipes and FIFOs</A></H1>
<A NAME="IDX873"></A>
<P>
A <DFN>pipe</DFN> is a mechanism for interprocess communication; data written
to the pipe by one process can be read by another process.  The data is
handled in a first-in, first-out (FIFO) order.  The pipe has no name; it
is created for one use and both ends must be inherited from the single
process which created the pipe.
<A NAME="IDX874"></A>
<P>
A <DFN>FIFO special file</DFN> is similar to a pipe, but instead of being an
anonymous, temporary connection, a FIFO has a name or names like any
other file.  Processes open the FIFO by name in order to communicate
through it.
<P>
A pipe or FIFO has to be open at both ends simultaneously.  If you read
from a pipe or FIFO file that doesn't have any processes writing to it
(perhaps because they have all closed the file, or exited), the read
returns end-of-file.  Writing to a pipe or FIFO that doesn't have a
reading process is treated as an error condition; it generates a
<CODE>SIGPIPE</CODE> signal, and fails with error code <CODE>EPIPE</CODE> if the
signal is handled or blocked.
<P>
Neither pipes nor FIFO special files allow file positioning.  Both
reading and writing operations happen sequentially; reading from the
beginning of the file and writing at the end.
<P>
<A NAME="IDX875"></A>
<A NAME="IDX876"></A>
<A NAME="IDX877"></A>
<H2><A NAME="SEC212" HREF="library_toc.html#SEC212">Creating a Pipe</A></H2>
<P>
The primitive for creating a pipe is the <CODE>pipe</CODE> function.  This
creates both the reading and writing ends of the pipe.  It is not very
useful for a single process to use a pipe to talk to itself.  In typical
use, a process creates a pipe just before it forks one or more child
processes (see section <A HREF="library.html#SEC405">Creating a Process</A>).  The pipe is then used for
communication either between the parent or child processes, or between
two sibling processes.
<P>
The <CODE>pipe</CODE> function is declared in the header file
<TT>`unistd.h'</TT>.
<A NAME="IDX878"></A>
<P>
<A NAME="IDX879"></A>
<U>Function:</U> int <B>pipe</B> <I>(int <VAR>filedes</VAR><TT>[2]</TT>)</I><P>
The <CODE>pipe</CODE> function creates a pipe and puts the file descriptors
for the reading and writing ends of the pipe (respectively) into
<CODE><VAR>filedes</VAR>[0]</CODE> and <CODE><VAR>filedes</VAR>[1]</CODE>.
<P>
An easy way to remember that the input end comes first is that file
descriptor <CODE>0</CODE> is standard input, and file descriptor <CODE>1</CODE> is
standard output.
<P>
If successful, <CODE>pipe</CODE> returns a value of <CODE>0</CODE>.  On failure,
<CODE>-1</CODE> is returned.  The following <CODE>errno</CODE> error conditions are
defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EMFILE</CODE>
<DD>The process has too many files open.
<P>
<DT><CODE>ENFILE</CODE>
<DD>There are too many open files in the entire system.  See section <A HREF="library.html#SEC16">Error Codes</A>,
for more information about <CODE>ENFILE</CODE>.
</DL>
<P>
Here is an example of a simple program that creates a pipe.  This program
uses the <CODE>fork</CODE> function (see section <A HREF="library.html#SEC405">Creating a Process</A>) to create
a child process.  The parent process writes data to the pipe, which is
read by the child process.
<P>
<PRE>
#include &#60;sys/types.h&#62;
#include &#60;unistd.h&#62;
#include &#60;stdio.h&#62;
#include &#60;stdlib.h&#62;

/* Read characters from the pipe and echo them to <CODE>stdout</CODE>.   */

void 
read_from_pipe (int file)
{
  FILE *stream;
  int c;
  stream = fdopen (file, "r");
  while ((c = fgetc (stream)) != EOF)
    putchar (c);
  fclose (stream);
}

/* Write some random text to the pipe.  */

void 
write_to_pipe (int file)
{
  FILE *stream;
  stream = fdopen (file, "w");
  fprintf (stream, "hello, world!\n");
  fprintf (stream, "goodbye, world!\n");
  fclose (stream);
}

int
main (void)
{
  pid_t pid;
  int mypipe[2];

  /* Create the pipe.  */
  if (pipe (mypipe))
    {
      fprintf (stderr, "Pipe failed.\n");
      return EXIT_FAILURE;
    }

  /* Create the child process.  */
  pid = fork ();
  if (pid == (pid_t) 0)
    {
      /* This is the child process.  */
      read_from_pipe (mypipe[0]);
      return EXIT_SUCCESS;
    }
  else if (pid &#60; (pid_t) 0)
    {
      /* The fork failed.  */
      fprintf (stderr, "Fork failed.\n");
      return EXIT_FAILURE;
    }
  else
    {
      /* This is the parent process.  */
      write_to_pipe (mypipe[1]);
      return EXIT_SUCCESS;
    }
}
</PRE>
<P>
<A NAME="IDX880"></A>
<A NAME="IDX881"></A>
<A NAME="IDX882"></A>
<H2><A NAME="SEC213" HREF="library_toc.html#SEC213">Pipe to a Subprocess</A></H2>
<P>
A common use of pipes is to send data to or receive data from a program
being run as subprocess.  One way of doing this is by using a combination of
<CODE>pipe</CODE> (to create the pipe), <CODE>fork</CODE> (to create the subprocess),
<CODE>dup2</CODE> (to force the subprocess to use the pipe as its standard input
or output channel), and <CODE>exec</CODE> (to execute the new program).  Or,
you can use <CODE>popen</CODE> and <CODE>pclose</CODE>.
<P>
The advantage of using <CODE>popen</CODE> and <CODE>pclose</CODE> is that the
interface is much simpler and easier to use.  But it doesn't offer as
much flexibility as using the low-level functions directly.
<P>
<A NAME="IDX883"></A>
<U>Function:</U> FILE * <B>popen</B> <I>(const char *<VAR>command</VAR>, const char *<VAR>mode</VAR>)</I><P>
The <CODE>popen</CODE> function is closely related to the <CODE>system</CODE>
function; see section <A HREF="library.html#SEC402">Running a Command</A>.  It executes the shell command
<VAR>command</VAR> as a subprocess.  However, instead of waiting for the
command to complete, it creates a pipe to the subprocess and returns a
stream that corresponds to that pipe.
<P>
If you specify a <VAR>mode</VAR> argument of <CODE>"r"</CODE>, you can read from the 
stream to retrieve data from the standard output channel of the subprocess.
The subprocess inherits its standard input channel from the parent process.
<P>
Similarly, if you specify a <VAR>mode</VAR> argument of <CODE>"w"</CODE>, you can
write to the stream to send data to the standard input channel of the
subprocess.  The subprocess inherits its standard output channel from
the parent process.
<P>
In the event of an error, <CODE>popen</CODE> returns a null pointer.  This
might happen if the pipe or stream cannot be created, if the subprocess
cannot be forked, or if the program cannot be executed.
<P>
<A NAME="IDX884"></A>
<U>Function:</U> int <B>pclose</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
The <CODE>pclose</CODE> function is used to close a stream created by <CODE>popen</CODE>.
It waits for the child process to terminate and returns its status value,
as for the <CODE>system</CODE> function.
<P>
Here is an example showing how to use <CODE>popen</CODE> and <CODE>pclose</CODE> to
filter output through another program, in this case the paging program
<CODE>more</CODE>.
<P>
<PRE>
#include &#60;stdio.h&#62;
#include &#60;stdlib.h&#62;

void 
write_data (FILE * stream)
{
  int i;
  for (i = 0; i &#60; 100; i++)
    fprintf (stream, "%d\n", i);
  if (ferror (stream))
    {
      fprintf (stderr, "Output to stream failed.\n");
      exit (EXIT_FAILURE);
    }
}

int
main (void)
{
  FILE *output;

  output = popen ("more", "w");
  if (!output)
    {
      fprintf (stderr, "Could not run more.\n");
      return EXIT_FAILURE;
    }
  write_data (output);
  pclose (output);
  return EXIT_SUCCESS;
}
</PRE>
<P>
<A NAME="IDX885"></A>
<A NAME="IDX886"></A>
<H2><A NAME="SEC214" HREF="library_toc.html#SEC214">FIFO Special Files</A></H2>
<P>
A FIFO special file is similar to a pipe, except that it is created in a
different way.  Instead of being an anonymous communications channel, a
FIFO special file is entered into the file system by calling
<CODE>mkfifo</CODE>.
<P>
Once you have created a FIFO special file in this way, any process can
open it for reading or writing, in the same way as an ordinary file.
However, it has to be open at both ends simultaneously before you can
proceed to do any input or output operations on it.  Opening a FIFO for
reading normally blocks until some other process opens the same FIFO for
writing, and vice versa.
<P>
The <CODE>mkfifo</CODE> function is declared in the header file
<TT>`sys/stat.h'</TT>.
<A NAME="IDX887"></A>
<P>
<A NAME="IDX888"></A>
<U>Function:</U> int <B>mkfifo</B> <I>(const char *<VAR>filename</VAR>, mode_t <VAR>mode</VAR>)</I><P>
The <CODE>mkfifo</CODE> function makes a FIFO special file with name
<VAR>filename</VAR>.  The <VAR>mode</VAR> argument is used to set the file's
permissions; see section <A HREF="library.html#SEC207">Assigning File Permissions</A>.
<P>
The normal, successful return value from <CODE>mkfifo</CODE> is <CODE>0</CODE>.  In
the case of an error, <CODE>-1</CODE> is returned.  In addition to the usual
file name syntax errors (see section <A HREF="library.html#SEC115">File Name Errors</A>), the following
<CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EEXIST</CODE>
<DD>The named file already exists.
<P>
<DT><CODE>ENOSPC</CODE>
<DD>The directory or file system cannot be extended.
<P>
<DT><CODE>EROFS</CODE>
<DD>The directory that would contain the file resides on a read-only file
system.
</DL>
<P>
<H2><A NAME="SEC215" HREF="library_toc.html#SEC215">Atomicity of Pipe I/O</A></H2>
<P>
Reading or writing pipe data is <DFN>atomic</DFN> if the size of data written
is less than <CODE>PIPE_BUF</CODE>.  This means that the data transfer seems
to be an instantaneous unit, in that nothing else in the system can
observe a state in which it is partially complete.  Atomic I/O may not
begin right away (it may need to wait for buffer space or for data), but
once it does begin, it finishes immediately.
<P>
Reading or writing a larger amount of data may not be atomic; for
example, output data from other processes sharing the descriptor may be
interspersed.
<P>
See section <A HREF="library.html#SEC463">Limits on File System Capacity</A>, for information about the <CODE>PIPE_BUF</CODE>
parameter.
<H1><A NAME="SEC216" HREF="library_toc.html#SEC216">Sockets</A></H1>
<P>
This chapter describes the GNU facilities for interprocess
communication using sockets.
<A NAME="IDX889"></A>
<A NAME="IDX890"></A>
<P>
A <DFN>socket</DFN> is a generalized interprocess communication channel.
Like a pipe, a socket is represented as a file descriptor.  But,
unlike pipes, sockets support communication between unrelated
processes, and even between processes running on different machines
that communicate over a network.  Sockets are the primary means of
communicating with other machines; <CODE>telnet</CODE>, <CODE>rlogin</CODE>,
<CODE>ftp</CODE>, <CODE>talk</CODE>, and the other familiar network programs use
sockets.
<P>
Not all operating systems support sockets.  In the GNU library, the
header file <TT>`sys/socket.h'</TT> exists regardless of the operating
system, and the socket functions always exist, but if the system does
not really support sockets, these functions always fail.
<P>
<STRONG>Incomplete:</STRONG> We do not currently document the facilities for
broadcast messages or for configuring Internet interfaces.
<P>
<H2><A NAME="SEC217" HREF="library_toc.html#SEC217">Socket Concepts</A></H2>
<A NAME="IDX891"></A>
<A NAME="IDX892"></A>
<P>
When you create a socket, you must specify the style of communication
you want to use and the type of protocol that should implement it.
The <DFN>communication style</DFN> of a socket defines the user-level
semantics of sending and receiving data on the socket.  Choosing a
communication style specifies the answers to questions such as these:
<P>
<UL>
<A NAME="IDX893"></A>
<A NAME="IDX894"></A>
<A NAME="IDX895"></A>
<LI>
<STRONG>What are the units of data transmission?</STRONG>  Some communication
styles regard the data as a sequence of bytes, with no larger
structure; others group the bytes into records (which are known in
this context as <DFN>packets</DFN>).
<P>
<A NAME="IDX896"></A>
<A NAME="IDX897"></A>
<LI>
<STRONG>Can data be lost during normal operation?</STRONG>  Some communication
styles guarantee that all the data sent arrives in the order it was
sent (barring system or network crashes); others styles occasionally
lose data as a normal part of operation, and may sometimes deliver
packets more than once or in the wrong order.
<P>
Designing a program to use unreliable communication styles usually
involves taking precautions to detect lost or misordered packets and
to retransmit data as needed.
<P>
<LI>
<STRONG>Is communication entirely with one partner?</STRONG>  Some
communication styles are like a telephone call--you make a
<DFN>connection</DFN> with one remote socket, and then exchange data
freely.  Other styles are like mailing letters--you specify a
destination address for each message you send.
</UL>
<A NAME="IDX898"></A>
<A NAME="IDX899"></A>
<A NAME="IDX900"></A>
<A NAME="IDX901"></A>
<P>
You must also choose a <DFN>namespace</DFN> for naming the socket.  A socket
name ("address") is meaningful only in the context of a particular
namespace.  In fact, even the data type to use for a socket name may
depend on the namespace.  Namespaces are also called "domains", but we
avoid that word as it can be confused with other usage of the same
term.  Each namespace has a symbolic name that starts with <SAMP>`PF_'</SAMP>.
A corresponding symbolic name starting with <SAMP>`AF_'</SAMP> designates the
address format for that namespace.
<A NAME="IDX902"></A>
<A NAME="IDX903"></A>
<A NAME="IDX904"></A>
<A NAME="IDX905"></A>
<P>
Finally you must next choose the <DFN>protocol</DFN> to carry out the
communication.  The protocol determines what low-level mechanism is used
to transmit and receive data.  Each protocol is valid for a particular
namespace and communication style; a namespace is sometimes called a
<DFN>protocol family</DFN> because of this, which is why the namespace names
start with <SAMP>`PF_'</SAMP>.
<P>
The rules of a protocol apply to the data passing between two programs,
perhaps on different computers; most of these rules are handled by the
operating system, and you need not know about them.  What you do need to
know about protocols is this:
<P>
<UL>
<LI>
In order to have communication between two sockets, they must specify
the <EM>same</EM> protocol.
<P>
<LI>
Each protocol is meaningful with particular style/namespace
combinations and cannot be used with inappropriate combinations.  For
example, the TCP protocol fits only the byte stream style of
communication and the Internet namespace.
<P>
<LI>
For each combination of style and namespace, there is a <DFN>default
protocol</DFN> which you can request by specifying 0 as the protocol
number.  And that's what you should normally do--use the default.
</UL>
<P>
<H2><A NAME="SEC218" HREF="library_toc.html#SEC218">Communication Styles</A></H2>
<P>
The GNU library includes support for several different kinds of sockets,
each with different characteristics.  This section describes the
supported socket types.  The symbolic constants listed here are
defined in <TT>`sys/socket.h'</TT>.
<A NAME="IDX906"></A>
<P>
<A NAME="IDX907"></A>
<U>Macro:</U> int <B>SOCK_STREAM</B><P>
The <CODE>SOCK_STREAM</CODE> style is like a pipe (see section <A HREF="library.html#SEC211">Pipes and FIFOs</A>);
it operates over a connection with a particular remote socket, and
transmits data reliably as a stream of bytes.
<P>
Use of this style is covered in detail in section <A HREF="library.html#SEC244">Using Sockets with Connections</A>.
<P>
<A NAME="IDX908"></A>
<U>Macro:</U> int <B>SOCK_DGRAM</B><P>
The <CODE>SOCK_DGRAM</CODE> style is used for sending
individually-addressed packets, unreliably.  
It is the diametrical opposite of <CODE>SOCK_STREAM</CODE>.
<P>
Each time you write data to a socket of this kind, that data becomes
one packet.  Since <CODE>SOCK_DGRAM</CODE> sockets do not have connections,
you must specify the recipient address with each packet.
<P>
The only guarantee that the system makes about your requests to
transmit data is that it will try its best to deliver each packet you
send.  It may succeed with the sixth packet after failing with the
fourth and fifth packets; the seventh packet may arrive before the
sixth, and may arrive a second time after the sixth.
<P>
The typical use for <CODE>SOCK_DGRAM</CODE> is in situations where it is
acceptible to simply resend a packet if no response is seen in a
reasonable amount of time.
<P>
See section <A HREF="library.html#SEC256">Datagram Socket Operations</A>, for detailed information about how to use datagram
sockets.
<P>
<A NAME="IDX909"></A>
<U>Macro:</U> int <B>SOCK_RAW</B><P>
This style provides access to low-level network protocols and
interfaces.  Ordinary user programs usually have no need to use this
style.
<P>
<H2><A NAME="SEC219" HREF="library_toc.html#SEC219">Socket Addresses</A></H2>
<A NAME="IDX910"></A>
<A NAME="IDX911"></A>
<A NAME="IDX912"></A>
<A NAME="IDX913"></A>
<P>
The name of a socket is normally called an <DFN>address</DFN>.  The
functions and symbols for dealing with socket addresses were named
inconsistently, sometimes using the term "name" and sometimes using
"address".  You can regard these terms as synonymous where sockets
are concerned.
<P>
A socket newly created with the <CODE>socket</CODE> function has no
address.  Other processes can find it for communication only if you
give it an address.  We call this <DFN>binding</DFN> the address to the
socket, and the way to do it is with the <CODE>bind</CODE> function.
<P>
You need be concerned with the address of a socket if other processes
are to find it and start communicating with it.  You can specify an
address for other sockets, but this is usually pointless; the first time
you send data from a socket, or use it to initiate a connection, the
system assigns an address automatically if you have not specified one.
<P>
Occasionally a client needs to specify an address because the server
discriminates based on addresses; for example, the rsh and rlogin
protocols look at the client's socket address and don't bypass password
checking unless it is less than <CODE>IPPORT_RESERVED</CODE> (see section <A HREF="library.html#SEC234">Internet Ports</A>).
<P>
The details of socket addresses vary depending on what namespace you are
using.  See section <A HREF="library.html#SEC223">The File Namespace</A>, or section <A HREF="library.html#SEC227">The Internet Namespace</A>, for specific
information.
<P>
Regardless of the namespace, you use the same functions <CODE>bind</CODE> and
<CODE>getsockname</CODE> to set and examine a socket's address.  These
functions use a phony data type, <CODE>struct sockaddr *</CODE>, to accept the
address.  In practice, the address lives in a structure of some other
data type appropriate to the address format you are using, but you cast
its address to <CODE>struct sockaddr *</CODE> when you pass it to
<CODE>bind</CODE>.
<P>
<H3><A NAME="SEC220" HREF="library_toc.html#SEC220">Address Formats</A></H3>
<P>
The functions <CODE>bind</CODE> and <CODE>getsockname</CODE> use the generic data
type <CODE>struct sockaddr *</CODE> to represent a pointer to a socket
address.  You can't use this data type effectively to interpret an
address or construct one; for that, you must use the proper data type
for the socket's namespace.
<P>
Thus, the usual practice is to construct an address in the proper
namespace-specific type, then cast a pointer to <CODE>struct sockaddr *</CODE>
when you call <CODE>bind</CODE> or <CODE>getsockname</CODE>.
<P>
The one piece of information that you can get from the <CODE>struct
sockaddr</CODE> data type is the <DFN>address format</DFN> designator which tells
you which data type to use to understand the address fully.
<A NAME="IDX914"></A>
<P>
The symbols in this section are defined in the header file
<TT>`sys/socket.h'</TT>.
<P>
<A NAME="IDX915"></A>
<U>Date Type:</U> <B>struct sockaddr</B><P>
The <CODE>struct sockaddr</CODE> type itself has the following members:
<P>
<DL COMPACT>
<DT><CODE>short int sa_family</CODE>
<DD>This is the code for the address format of this address.  It
identifies the format of the data which follows.
<P>
<DT><CODE>char sa_data[14]</CODE>
<DD>This is the actual socket address data, which is format-dependent.  Its
length is also format-dependent, and may well be more than 14.  The
length 14 of <CODE>sa_data</CODE> is essentially arbitrary.
</DL>
<P>
Each address format has a symbolic name which starts with <SAMP>`AF_'</SAMP>.
Each of them corresponds to a <SAMP>`PF_'</SAMP> symbol which designates the
corresponding namespace.  Here is a list of address format names:
<P>
<DL COMPACT>
<A NAME="IDX916"></A>
<DT><CODE>AF_FILE</CODE>
<DD>This designates the address format that goes with the file namespace.
(<CODE>PF_FILE</CODE> is the name of that namespace.)  See section <A HREF="library.html#SEC225">Details of File Namespace</A>, for information about this address format.
<P>
<A NAME="IDX917"></A>
<DT><CODE>AF_UNIX</CODE>
<DD>This is a synonym for <CODE>AF_FILE</CODE>, for compatibility.
(<CODE>PF_UNIX</CODE> is likewise a synonym for <CODE>PF_FILE</CODE>.)
<P>
<A NAME="IDX918"></A>
<DT><CODE>AF_INET</CODE>
<DD>This designates the address format that goes with the Internet
namespace.  (<CODE>PF_INET</CODE> is the name of that namespace.)
See section <A HREF="library.html#SEC228">Internet Socket Address Format</A>.
<P>
<A NAME="IDX919"></A>
<DT><CODE>AF_UNSPEC</CODE>
<DD>This designates no particular address format.  It is used only in rare
cases, such as to clear out the default destination address of a
"connected" datagram socket.  See section <A HREF="library.html#SEC257">Sending Datagrams</A>.
<P>
The corresponding namespace designator symbol <CODE>PF_UNSPEC</CODE> exists
for completeness, but there is no reason to use it in a program.
</DL>
<P>
<TT>`sys/socket.h'</TT> defines symbols starting with <SAMP>`AF_'</SAMP> for many
different kinds of networks, all or most of which are not actually
implemented.  We will document those that really work, as we receive
information about how to use them.
<P>
<H3><A NAME="SEC221" HREF="library_toc.html#SEC221">Setting a Socket's Address</A></H3>
<A NAME="IDX920"></A>
<P>
Use the <CODE>bind</CODE> function to assign an address to a socket.  The
prototype for <CODE>bind</CODE> is in the header file <TT>`sys/socket.h'</TT>.
For examples of use, see section <A HREF="library.html#SEC223">The File Namespace</A>, or see section <A HREF="library.html#SEC238">Internet Socket Example</A>.
<P>
<A NAME="IDX921"></A>
<U>Function:</U> int <B>bind</B> <I>(int <VAR>socket</VAR>, struct sockaddr *<VAR>addr</VAR>, size_t <VAR>length</VAR>)</I><P>
The <CODE>bind</CODE> function assigns an address to the socket
<VAR>socket</VAR>.  The <VAR>addr</VAR> and <VAR>length</VAR> arguments specify the
address; the detailed format of the address depends on the namespace.
The first part of the address is always the format designator, which
specifies a namespace, and says that the address is in the format for
that namespace.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  The
following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>socket</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>ENOTSOCK</CODE>
<DD>The descriptor <VAR>socket</VAR> is not a socket.
<P>
<DT><CODE>EADDRNOTAVAIL</CODE>
<DD>The specified address is not available on this machine.
<P>
<DT><CODE>EADDRINUSE</CODE>
<DD>Some other socket is already using the specified address.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The socket <VAR>socket</VAR> already has an address.
<P>
<DT><CODE>EACCESS</CODE>
<DD>You do not have permission to access the requested address.  (In the
Internet domain, only the super-user is allowed to specify a port number
in the range 0 through <CODE>IPPORT_RESERVED</CODE> minus one; see
section <A HREF="library.html#SEC234">Internet Ports</A>.)
</DL>
<P>
Additional conditions may be possible depending on the particular namespace
of the socket.
<P>
<H3><A NAME="SEC222" HREF="library_toc.html#SEC222">Reading a Socket's Address</A></H3>
<A NAME="IDX922"></A>
<P>
Use the function <CODE>getsockname</CODE> to examine the address of an
Internet socket.  The prototype for this function is in the header file
<TT>`sys/socket.h'</TT>.
<P>
<A NAME="IDX923"></A>
<U>Function:</U> int <B>getsockname</B> <I>(int <VAR>socket</VAR>, struct sockaddr *<VAR>addr</VAR>, size_t *<VAR>length_ptr</VAR>)</I><P>
The <CODE>getsockname</CODE> function returns information about the
address of the socket <VAR>socket</VAR> in the locations specified by the
<VAR>addr</VAR> and <VAR>length_ptr</VAR> arguments.  Note that the
<VAR>length_ptr</VAR> is a pointer; you should initialize it to be the
allocation size of <VAR>addr</VAR>, and on return it contains the actual
size of the address data.
<P>
The format of the address data depends on the socket namespace.  The
length of the information is usually fixed for a given namespace, so
normally you can know exactly how much space is needed and can provide
that much.  The usual practice is to allocate a place for the value
using the proper data type for the socket's namespace, then cast its
address to <CODE>struct sockaddr *</CODE> to pass it to <CODE>getsockname</CODE>.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on error.  The
following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>socket</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>ENOTSOCK</CODE>
<DD>The descriptor <VAR>socket</VAR> is not a socket.
<P>
<DT><CODE>ENOBUFS</CODE>
<DD>There are not enough internal buffers available for the operation.
</DL>
<P>
You can't read the address of a socket in the file namespace.  This is
consistent with the rest of the system; in general, there's no way to
find a file's name from a descriptor for that file.
<P>
<A NAME="IDX924"></A>
<H2><A NAME="SEC223" HREF="library_toc.html#SEC223">The File Namespace</A></H2>
<P>
This section describes the details of the file namespace, whose
symbolic name (required when you create a socket) is <CODE>PF_FILE</CODE>.
<P>
<H3><A NAME="SEC224" HREF="library_toc.html#SEC224">File Namespace Concepts</A></H3>
<P>
In the file namespace, socket addresses are file names.  You can specify
any file name you want as the address of the socket, but you must have
write permission on the directory containing it.  In order to connect to
a socket, you must have read permission for it.  It's common to put
these files in the <TT>`/tmp'</TT> directory.
<P>
One peculiarity of the file namespace is that the name is only used when
opening the connection; once that is over with, the address is not
meaningful and may not exist.
<P>
Another peculiarity is that you cannot connect to such a socket from
another machine--not even if the other machine shares the file system
which contains the name of the socket.  You can see the socket in a
directory listing, but connecting to it never succeeds.  Some programs
take advantage of this, such as by asking the client to send its own
process ID, and using the process IDs to distinguish between clients.
However, we recommend you not use this method in protocols you design,
as we might someday permit connections from other machines that mount
the same file systems.  Instead, send each new client an identifying
number if you want it to have one.
<P>
After you close a socket in the file namespace, you should delete the
file name from the file system.  Use <CODE>unlink</CODE> or <CODE>remove</CODE> to
do this; see section <A HREF="library.html#SEC197">Deleting Files</A>.
<P>
The file namespace supports just one protocol for any communication
style; it is protocol number <CODE>0</CODE>.
<P>
<H3><A NAME="SEC225" HREF="library_toc.html#SEC225">Details of File Namespace</A></H3>
<A NAME="IDX925"></A>
<P>
To create a socket in the file namespace, use the constant
<CODE>PF_FILE</CODE> as the <VAR>namespace</VAR> argument to <CODE>socket</CODE> or
<CODE>socketpair</CODE>.  This constant is defined in <TT>`sys/socket.h'</TT>.
<P>
<A NAME="IDX926"></A>
<U>Macro:</U> int <B>PF_FILE</B><P>
This designates the file namespace, in which socket addresses are file
names, and its associated family of protocols.
<P>
<A NAME="IDX927"></A>
<U>Macro:</U> int <B>PF_UNIX</B><P>
This is a synonym for <CODE>PF_FILE</CODE>, for compatibility's sake.
<P>
The structure for specifying socket names in the file namespace is
defined in the header file <TT>`sys/un.h'</TT>:
<A NAME="IDX928"></A>
<P>
<A NAME="IDX929"></A>
<U>Data Type:</U> <B>struct sockaddr_un</B><P>
This structure is used to specify file namespace socket addresses.  It has
the following members:
<P>
<DL COMPACT>
<DT><CODE>short int sun_family</CODE>
<DD>This identifies the address family or format of the socket address.
You should store the value <CODE>AF_FILE</CODE> to designate the file
namespace.  See section <A HREF="library.html#SEC219">Socket Addresses</A>.
<P>
<DT><CODE>char sun_path[108]</CODE>
<DD>This is the file name to use.
<P>
<STRONG>Incomplete:</STRONG>  Why is 108 a magic number?  RMS suggests making
this a zero-length array and tweaking the example following to use
<CODE>alloca</CODE> to allocate an appropriate amount of storage based on
the length of the filename.
</DL>
<P>
You should compute the <VAR>length</VAR> parameter for a socket address in
the file namespace as the sum of the size of the <CODE>sun_family</CODE>
component and the string length (<EM>not</EM> the allocation size!) of
the file name string.
<P>
<H3><A NAME="SEC226" HREF="library_toc.html#SEC226">Example of File-Namespace Sockets</A></H3>
<P>
Here is an example showing how to create and name a socket in the file
namespace.
<P>
<PRE>
#include &#60;stddef.h&#62;
#include &#60;stdio.h&#62;
#include &#60;errno.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;sys/socket.h&#62;
#include &#60;sys/un.h&#62;

int 
make_named_socket (const char *filename)
{
  struct sockaddr_un name;
  int sock;
  size_t size;

  /* Create the socket.   */
  
  sock = socket (PF_UNIX, SOCK_DGRAM, 0);
  if (sock &#60; 0)
    {
      perror ("socket");
      exit (EXIT_FAILURE);
    }

  /* Bind a name to the socket.   */

  name.sun_family = AF_FILE;
  strcpy (name.sun_path, filename);

  /* The size of the address is
     the offset of the start of the filename,
     plus its length,
     plus one for the terminating null byte.  */
  size = (offsetof (struct sockaddr_un, sun_path)
	  + strlen (name.sun_path) + 1);

  if (bind (sock, (struct sockaddr *) &#38;name, size) &#60; 0)
    {
      perror ("bind");
      exit (EXIT_FAILURE);
    }

  return sock;
}
</PRE>
<P>
<A NAME="IDX930"></A>
<H2><A NAME="SEC227" HREF="library_toc.html#SEC227">The Internet Namespace</A></H2>
<P>
This section describes the details the protocols and socket naming
conventions used in the Internet namespace.
<P>
To create a socket in the Internet namespace, use the symbolic name
<CODE>PF_INET</CODE> of this namespace as the <VAR>namespace</VAR> argument to
<CODE>socket</CODE> or <CODE>socketpair</CODE>.  This macro is defined in
<TT>`sys/socket.h'</TT>.
<A NAME="IDX931"></A>
<P>
<A NAME="IDX932"></A>
<U>Macro:</U> int <B>PF_INET</B><P>
This designates the Internet namespace and associated family of
protocols.
<P>
A socket address for the Internet namespace includes the following components:
<P>
<UL>
<LI>
The address of the machine you want to connect to.  Internet addresses
can be specified in several ways; these are discussed in section <A HREF="library.html#SEC228">Internet Socket Address Format</A>, section <A HREF="library.html#SEC229">Host Addresses</A>, and section <A HREF="library.html#SEC233">Host Names</A>.
<P>
<LI>
A port number for that machine.  See section <A HREF="library.html#SEC234">Internet Ports</A>.
</UL>
<P>
You must ensure that the address and port number are represented in a
canonical format called <DFN>network byte order</DFN>.  See section <A HREF="library.html#SEC236">Byte Order Conversion</A>,
for information about this.
<P>
<H3><A NAME="SEC228" HREF="library_toc.html#SEC228">Internet Socket Address Format</A></H3>
<P>
In the Internet namespace, a socket address consists of a host address
and a port on that host.  In addition, the protocol you choose serves
effectively as a part of the address because local port numbers are
meaningful only within a particular protocol.
<P>
The data type for representing socket addresses in the Internet namespace
is defined in the header file <TT>`netinet/in.h'</TT>.
<A NAME="IDX933"></A>
<P>
<A NAME="IDX934"></A>
<U>Data Type:</U> <B>struct sockaddr_in</B><P>
This is the data type used to represent socket addresses in the
Internet namespace.  It has the following members:
<P>
<DL COMPACT>
<DT><CODE>short int sin_family</CODE>
<DD>This identifies the address family or format of the socket address.
You should store the value of <CODE>AF_INET</CODE> in this member.
See section <A HREF="library.html#SEC219">Socket Addresses</A>.
<P>
<DT><CODE>struct in_addr sin_addr</CODE>
<DD>This is the Internet address of the host machine.  See section <A HREF="library.html#SEC229">Host Addresses</A>, and section <A HREF="library.html#SEC233">Host Names</A>, for how to get a value to store
here.
<P>
<DT><CODE>unsigned short int sin_port</CODE>
<DD>This is the port number.  See section <A HREF="library.html#SEC234">Internet Ports</A>.
</DL>
<P>
When you call <CODE>bind</CODE> or <CODE>getsockname</CODE>, you should specify
<CODE>sizeof (struct sockaddr_in)</CODE> as the <VAR>length</VAR> parameter if
you are using an Internet namespace socket address.
<P>
<H3><A NAME="SEC229" HREF="library_toc.html#SEC229">Host Addresses</A></H3>
<P>
Each computer on the Internet has one or more <DFN>Internet addresses</DFN>,
numbers which identify that computer among all those on the Internet.
Users typically write numeric host addresses as sequences of four
numbers, separated by periods, as in <SAMP>`128.52.46.32'</SAMP>.
<P>
Each computer also has one or more <DFN>host names</DFN>, which are strings
of words separated by periods, as in <SAMP>`churchy.gnu.ai.mit.edu'</SAMP>.
<P>
Programs that let the user specify a host typically accept both numeric
addresses and host names.  But the program needs a numeric address to
open a connection; to use a host name, you must convert it to the
numeric address it stands for.
<P>
<A NAME="IDX935"></A>
<A NAME="IDX936"></A>
<H4><A NAME="SEC230" HREF="library_toc.html#SEC230">Internet Host Addresses</A></H4>
<P>
<A NAME="IDX937"></A>
<A NAME="IDX938"></A>
<P>
An Internet host address is a number containing four bytes of data.
These are divided into two parts, a <DFN>network number</DFN> and a
<DFN>local network address number</DFN> within that network.  The network
number consists of the first one, two or three bytes; the rest of the
bytes are the local address.
<P>
Network numbers are registered with the Network Information Center
(NIC), and are divided into three classes--A, B, and C.  The local
network address numbers of individual machines are registered with the
administrator of the particular network.
<P>
Class A networks have single-byte numbers in the range 0 to 127.  There
are only a small number of Class A networks, but they can each support a
very large number of hosts.  Medium-sized Class B networks have two-byte
network numbers, with the first byte in the range 128 to 191.  Class C
networks are the smallest; they have three-byte network numbers, with
the first byte in the range 192-255.  Thus, the first 1, 2, or 3 bytes
of an Internet address specifies a network.  The remaining bytes of the
Internet address specify the address within that network.
<P>
The Class A network 0 is reserved for broadcast to all networks.  In
addition, the host number 0 within each network is reserved for broadcast 
to all hosts in that network.
<P>
The Class A network 127 is reserved for loopback; you can always use
the Internet address <SAMP>`127.0.0.1'</SAMP> to refer to the host machine.
<P>
Since a single machine can be a member of multiple networks, it can
have multiple Internet host addresses.  However, there is never
supposed to be more than one machine with the same host address.
<P>
<A NAME="IDX939"></A>
<A NAME="IDX940"></A>
<P>
There are four forms of the <DFN>standard numbers-and-dots notation</DFN>
for Internet addresses:
<P>
<DL COMPACT>
<DT><CODE><VAR>a</VAR>.<VAR>b</VAR>.<VAR>c</VAR>.<VAR>d</VAR></CODE>
<DD>This specifies all four bytes of the address individually.
<P>
<DT><CODE><VAR>a</VAR>.<VAR>b</VAR>.<VAR>c</VAR></CODE>
<DD>The last part of the address, <VAR>c</VAR>, is interpreted as a 2-byte quantity.
This is useful for specifying host addresses in a Class B network with
network address number <CODE><VAR>a</VAR>.<VAR>b</VAR></CODE>.
<P>
<DT><CODE><VAR>a</VAR>.<VAR>b</VAR></CODE>
<DD>The last part of the address, <VAR>c</VAR>, is interpreted as a 3-byte quantity.
This is useful for specifying host addresses in a Class A network with
network address number <VAR>a</VAR>.
<P>
<DT><CODE><VAR>a</VAR></CODE>
<DD>If only one part is given, this corresponds directly to the host address
number.
</DL>
<P>
Within each part of the address, the usual C conventions for specifying
the radix apply.  In other words, a leading <SAMP>`0x'</SAMP> or <SAMP>`0X'</SAMP> implies
hexadecimal radix; a leading <SAMP>`0'</SAMP> implies octal; and otherwise decimal
radix is assumed.
<P>
<H4><A NAME="SEC231" HREF="library_toc.html#SEC231">Host Address Data Type</A></H4>
<P>
Internet host addresses are represented in some contexts as integers
(type <CODE>unsigned long int</CODE>).  In other contexts, the integer is
packaged inside a structure of type <CODE>struct in_addr</CODE>.  It would
be better if the usage were made consistent, but it is not hard to extract
the integer from the structure or put the integer into a structure.
<P>
The following basic definitions for Internet addresses appear in the
header file <TT>`netinet/in.h'</TT>:
<A NAME="IDX941"></A>
<P>
<A NAME="IDX942"></A>
<U>Data Type:</U> <B>struct in_addr</B><P>
This data type is used in certain contexts to contain an Internet host
address.  It has just one field, named <CODE>s_addr</CODE>, which records the
host address number as an <CODE>unsigned long int</CODE>.
<P>
<A NAME="IDX943"></A>
<U>Macro:</U> unsigned long int <B>INADDR_ANY</B><P>
You can use this constant to stand for "the address of this machine,"
instead of finding its actual address.  This special constant saves you
the trouble of looking up the address of your own machine.  Also, if
your machine has multiple network addresses on different networks (which
is not unusual), using <CODE>INADDR_ANY</CODE> permits the system to choose
whichever address makes communication most efficient.
<P>
<H4><A NAME="SEC232" HREF="library_toc.html#SEC232">Host Address Functions</A></H4>
<A NAME="IDX944"></A>
<P>
These additional functions for manipulating Internet addresses are
declared in <TT>`arpa/inet.h'</TT>.  They represent Internet addresses in
network byte order; they represent network numbers and
local-address-within-network numbers in host byte order.
See section <A HREF="library.html#SEC236">Byte Order Conversion</A>, for an explanation of network and host byte order.
<P>
<A NAME="IDX945"></A>
<U>Function:</U> unsigned long int <B>inet_addr</B> <I>(const char *<VAR>name</VAR>)</I><P>
This function converts the Internet host address <VAR>name</VAR>
from the standard numbers-and-dots notation into binary data.
If the input is not valid, <CODE>inet_addr</CODE> returns <CODE>-1</CODE>.
<P>
<A NAME="IDX946"></A>
<U>Function:</U> unsigned long int <B>inet_network</B> <I>(const char *<VAR>name</VAR>)</I><P>
This function extracts the network number from the address <VAR>name</VAR>,
given in the standard numbers-and-dots notation.
If the input is not valid, <CODE>inet_network</CODE> returns <CODE>-1</CODE>.
<P>
<A NAME="IDX947"></A>
<U>Function:</U> char * <B>inet_ntoa</B> <I>(struct in_addr <VAR>addr</VAR>)</I><P>
This function converts the Internet host address <VAR>addr</VAR> to a
string in the standard numbers-and-dots notation.  The return value is
a pointer into a statically-allocated buffer.  Subsequent calls will
overwrite the same buffer, so you should copy the string if you need
to save it.
<P>
<A NAME="IDX948"></A>
<U>Function:</U> struct in_addr <B>inet_makeaddr</B> <I>(int <VAR>net</VAR>, int <VAR>local</VAR>)</I><P>
This function makes an Internet host address by combining the network
number <VAR>net</VAR> with the local-address-within-network number
<VAR>local</VAR>.
<P>
<A NAME="IDX949"></A>
<U>Function:</U> int <B>inet_lnaof</B> <I>(struct in_addr <VAR>addr</VAR>)</I><P>
This function returns the local-address-within-network part of the
Internet host address <VAR>addr</VAR>.
<P>
<A NAME="IDX950"></A>
<U>Function:</U> int <B>inet_netof</B> <I>(struct in_addr <VAR>addr</VAR>)</I><P>
This function returns the network number part of the Internet host
address <VAR>addr</VAR>.
<P>
<A NAME="IDX951"></A>
<A NAME="IDX952"></A>
<A NAME="IDX953"></A>
<H4><A NAME="SEC233" HREF="library_toc.html#SEC233">Host Names</A></H4>
<P>
Besides the standard numbers-and-dots notation for Internet addresses,
you can also refer to a host by a symbolic name.  The advantage of a
symbolic name is that it is usually easier to remember.  For example,
the machine with Internet address <SAMP>`128.52.46.32'</SAMP> is also known as
<SAMP>`churchy.gnu.ai.mit.edu'</SAMP>; and other machines in the <SAMP>`gnu.ai.mit.edu'</SAMP>
domain can refer to it simply as <SAMP>`churchy'</SAMP>.
<A NAME="IDX954"></A>
<A NAME="IDX955"></A>
<P>
Internally, the system uses a database to keep track of the mapping
between host names and host numbers.  This database is usually either
the file <TT>`/etc/hosts'</TT> or an equivalent provided by a name server.
The functions and other symbols for accessing this database are declared
in <TT>`netdb.h'</TT>.  They are BSD features, defined unconditionally if
you include <TT>`netdb.h'</TT>.
<P>
<A NAME="IDX956"></A>
<U>Data Type:</U> <B>struct hostent</B><P>
This data type is used to represent an entry in the hosts database.  It
has the following members:
<P>
<DL COMPACT>
<DT><CODE>char *h_name</CODE>
<DD>This is the "official" name of the host.
<P>
<DT><CODE>char **h_aliases</CODE>
<DD>These are alternative names for the host, represented as a null-terminated
vector of strings.
<P>
<DT><CODE>int h_addrtype</CODE>
<DD>This is the host address type; in practice, its value is always
<CODE>AF_INET</CODE>.  In principle other kinds of addresses could be
represented in the data base as well as Internet addresses; if this were
done, you might find a value in this field other than <CODE>AF_INET</CODE>.
See section <A HREF="library.html#SEC219">Socket Addresses</A>.
<P>
<DT><CODE>int h_length</CODE>
<DD>This is the length, in bytes, of each address.
<P>
<DT><CODE>char **h_addr_list</CODE>
<DD>This is the vector of addresses for the host.  (Recall that the host
might be connected to multiple networks and have different addresses on
each one.)  The vector is terminated by a null pointer.
<P>
<DT><CODE>char *h_addr</CODE>
<DD>This is a synonym for <CODE>h_addr_list[0]</CODE>; in other words, it is the
first host address.
</DL>
<P>
As far as the host database is concerned, each address is just a block
of memory <CODE>h_length</CODE> bytes long.  But in other contexts there is an
implicit assumption that you can convert this to a <CODE>struct in_addr</CODE> or
an <CODE>unsigned long int</CODE>.  Host addresses in a <CODE>struct hostent</CODE>
structure are always given in network byte order; see section <A HREF="library.html#SEC236">Byte Order Conversion</A>.
<P>
You can use <CODE>gethostbyname</CODE> or <CODE>gethostbyaddr</CODE> to search the
hosts database for information about a particular host.  The information
is returned in a statically-allocated structure; you must copy the
information if you need to save it across calls.
<P>
<A NAME="IDX957"></A>
<U>Function:</U> struct hostent * <B>gethostbyname</B> <I>(const char *<VAR>name</VAR>)</I><P>
The <CODE>gethostbyname</CODE> function returns information about the host
named <VAR>name</VAR>.  If the lookup fails, it returns a null pointer.
<P>
<A NAME="IDX958"></A>
<U>Function:</U> struct hostent * <B>gethostbyaddr</B> <I>(const char *<VAR>addr</VAR>, int <VAR>length</VAR>, int <VAR>format</VAR>)</I><P>
The <CODE>gethostbyaddr</CODE> function returns information about the host
with Internet address <VAR>addr</VAR>.  The <VAR>length</VAR> argument is the
size (in bytes) of the address at <VAR>addr</VAR>.  <VAR>format</VAR> specifies
the address format; for an Internet address, specify a value of
<CODE>AF_INET</CODE>.
<P>
If the lookup fails, <CODE>gethostbyaddr</CODE> returns a null pointer.
<P>
<A NAME="IDX959"></A>
<P>
If the name lookup by <CODE>gethostbyname</CODE> or <CODE>gethostbyaddr</CODE>
fails, you can find out the reason by looking at the value of the
variable <CODE>h_errno</CODE>.  (It would be cleaner design for these
functions to set <CODE>errno</CODE>, but use of <CODE>h_errno</CODE> is compatible
with other systems.)  Before using <CODE>h_errno</CODE>, you must declare it
like this:
<P>
<PRE>
extern int h_errno;
</PRE>
<P>
Here are the error codes that you may find in <CODE>h_errno</CODE>:
<P>
<DL COMPACT>
<A NAME="IDX960"></A>
<DT><CODE>HOST_NOT_FOUND</CODE>
<DD>No such host is known in the data base.
<P>
<A NAME="IDX961"></A>
<DT><CODE>TRY_AGAIN</CODE>
<DD>This condition happens when the name server could not be contacted.  If
you try again later, you may succeed then.
<P>
<A NAME="IDX962"></A>
<DT><CODE>NO_RECOVERY</CODE>
<DD>A non-recoverable error occurred.
<P>
<A NAME="IDX963"></A>
<DT><CODE>NO_ADDRESS</CODE>
<DD>The host database contains an entry for the name, but it doesn't have an
associated Internet address.
</DL>
<P>
You can also scan the entire hosts database one entry at a time using
<CODE>sethostent</CODE>, <CODE>gethostent</CODE>, and <CODE>endhostent</CODE>.  Be careful
in using these functions, because they are not reentrant.
<P>
<A NAME="IDX964"></A>
<U>Function:</U> void <B>sethostent</B> <I>(int <VAR>stayopen</VAR>)</I><P>
This function opens the hosts database to begin scanning it.  You can
then call <CODE>gethostent</CODE> to read the entries.
<P>
If the <VAR>stayopen</VAR> argument is nonzero, this sets a flag so that
subsequent calls to <CODE>gethostbyname</CODE> or <CODE>gethostbyaddr</CODE> will
not close the database (as they usually would).  This makes for more
efficiency if you call those functions several times, by avoiding
reopening the database for each call.
<P>
<A NAME="IDX965"></A>
<U>Function:</U> struct hostent * <B>gethostent</B> <I>()</I><P>
This function returns the next entry in the hosts database.  It
returns a null pointer if there are no more entries.
<P>
<A NAME="IDX966"></A>
<U>Function:</U> void <B>endhostent</B> <I>()</I><P>
This function closes the hosts database.
<P>
<A NAME="IDX967"></A>
<H3><A NAME="SEC234" HREF="library_toc.html#SEC234">Internet Ports</A></H3>
<P>
A socket address in the Internet namespace consists of a machine's
Internet address plus a <DFN>port number</DFN> which distinguishes the
sockets on a given machine (for a given protocol).  Port numbers range
from 0 to 65,535.
<P>
Port numbers less than <CODE>IPPORT_RESERVED</CODE> are reserved for standard
servers, such as <CODE>finger</CODE> and <CODE>telnet</CODE>.  There is a database
that keeps track of these, and you can use the <CODE>getservbyname</CODE>
function to map a service name onto a port number; see section <A HREF="library.html#SEC235">The Services Database</A>.
<P>
If you write a server that is not one of the standard ones defined in
the database, you must choose a port number for it.  Use a number
greater than <CODE>IPPORT_USERRESERVED</CODE>; such numbers are reserved for
servers and won't ever be generated automatically by the system.
Avoiding conflicts with servers being run by other users is up to you.
<P>
When you use a socket without specifying its address, the system
generates a port number for it.  This number is between
<CODE>IPPORT_RESERVED</CODE> and <CODE>IPPORT_USERRESERVED</CODE>.
<P>
On the Internet, it is actually legitimate to have two different
sockets with the same port number, as long as they never both try to
communicate with the same socket address (host address plus port
number).  You shouldn't duplicate a port number except in special
circumstances where a higher-level protocol requires it.  Normally,
the system won't let you do it; <CODE>bind</CODE> normally insists on
distinct port numbers.  To reuse a port number, you must set the
socket option <CODE>SO_REUSEADDR</CODE>.  See section <A HREF="library.html#SEC266">Socket-Level Options</A>.
<A NAME="IDX968"></A>
<P>
These macros are defined in the header file <TT>`netinet/in.h'</TT>.
<P>
<A NAME="IDX969"></A>
<U>Macro:</U> int <B>IPPORT_RESERVED</B><P>
Port numbers less than <CODE>IPPORT_RESERVED</CODE> are reserved for
superuser use.
<P>
<A NAME="IDX970"></A>
<U>Macro:</U> int <B>IPPORT_USERRESERVED</B><P>
Port numbers greater than or equal to <CODE>IPPORT_USERRESERVED</CODE> are
reserved for explicit use; they will never be allocated automatically.
<P>
<A NAME="IDX971"></A>
<A NAME="IDX972"></A>
<A NAME="IDX973"></A>
<H3><A NAME="SEC235" HREF="library_toc.html#SEC235">The Services Database</A></H3>
<A NAME="IDX974"></A>
<P>
The database that keeps track of "well-known" services is usually
either the file <TT>`/etc/services'</TT> or an equivalent from a name server.
You can use these utilities, declared in <TT>`netdb.h'</TT>, to access
the services database.
<A NAME="IDX975"></A>
<P>
<A NAME="IDX976"></A>
<U>Data Type:</U> <B>struct servent</B><P>
This data type holds information about entries from the services database.
It has the following members:
<P>
<DL COMPACT>
<DT><CODE>char *s_name</CODE>
<DD>This is the "official" name of the service.
<P>
<DT><CODE>char **s_aliases</CODE>
<DD>These are alternate names for the service, represented as an array of
strings.  A null pointer terminates the array.
<P>
<DT><CODE>int s_port</CODE>
<DD>This is the port number for the service.  Port numbers are given in
network byte order; see section <A HREF="library.html#SEC236">Byte Order Conversion</A>.
<P>
<DT><CODE>char *s_proto</CODE>
<DD>This is the name of the protocol to use with this service.
See section <A HREF="library.html#SEC237">Protocols Database</A>.
</DL>
<P>
To get information about a particular service, use the
<CODE>getservbyname</CODE> or <CODE>getservbyport</CODE> functions.  The information
is returned in a statically-allocated structure; you must copy the
information if you need to save it across calls.
<P>
<A NAME="IDX977"></A>
<U>Function:</U> struct servent * <B>getservbyname</B> <I>(const char *<VAR>name</VAR>, const char *<VAR>proto</VAR>)</I><P>
The <CODE>getservbyname</CODE> function returns information about the
service named <VAR>name</VAR> using protocol <VAR>proto</VAR>.  If it can't find
such a service, it returns a null pointer.
<P>
This function is useful for servers as well as for clients; servers
use it to determine which port they should listen on (see section <A HREF="library.html#SEC246">Listening for Connections</A>).
<P>
<A NAME="IDX978"></A>
<U>Function:</U> struct servent * <B>getservbyport</B> <I>(int <VAR>port</VAR>, const char *<VAR>proto</VAR>)</I><P>
The <CODE>getservbyport</CODE> function returns information about the
service at port <VAR>port</VAR> using protocol <VAR>proto</VAR>.  If it can't
find such a service, it returns a null pointer.
<P>
You can also scan the services database using <CODE>setservent</CODE>,
<CODE>getservent</CODE>, and <CODE>endservent</CODE>.  Be careful in using these
functions, because they are not reentrant.
<P>
<A NAME="IDX979"></A>
<U>Function:</U> void <B>setservent</B> <I>(int <VAR>stayopen</VAR>)</I><P>
This function opens the services database to begin scanning it.
<P>
If the <VAR>stayopen</VAR> argument is nonzero, this sets a flag so that
subsequent calls to <CODE>getservbyname</CODE> or <CODE>getservbyport</CODE> will
not close the database (as they usually would).  This makes for more
efficiency if you call those functions several times, by avoiding
reopening the database for each call.
<P>
<A NAME="IDX980"></A>
<U>Function:</U> struct servent * <B>getservent</B> <I>(void)</I><P>
This function returns the next entry in the services database.  If
there are no more entries, it returns a null pointer.
<P>
<A NAME="IDX981"></A>
<U>Function:</U> void <B>endservent</B> <I>(void)</I><P>
This function closes the services database.
<P>
<A NAME="IDX982"></A>
<A NAME="IDX983"></A>
<H3><A NAME="SEC236" HREF="library_toc.html#SEC236">Byte Order Conversion</A></H3>
<A NAME="IDX984"></A>
<A NAME="IDX985"></A>
<P>
Different kinds of computers use different conventions for the
ordering of bytes within a word.  Some computers put the most
significant byte within a word first (this is called "big-endian"
order), and others put it last ("little-endian" order).
<A NAME="IDX986"></A>
<P>
So that machines with different byte order conventions can
communicate, the Internet protocols specify a canonical byte order
convention for data transmitted over the network.  This is known
as the <DFN>network byte order</DFN>.
<P>
When establishing an Internet socket connection, you must make sure that
the data in the <CODE>sin_port</CODE> and <CODE>sin_addr</CODE> members of the
<CODE>sockaddr_in</CODE> structure are represented in the network byte order.
If you are encoding integer data in the messages sent through the
socket, you should convert this to network byte order too.  If you don't
do this, your program may fail when running on or talking to other kinds
of machines.
<P>
If you use <CODE>getservbyname</CODE> and <CODE>gethostbyname</CODE> or
<CODE>inet_addr</CODE> to get the port number and host address, the values are
already in the network byte order, and you can copy them directly into
the <CODE>sockaddr_in</CODE> structure.
<P>
Otherwise, you have to convert the values explicitly.  Use
<CODE>htons</CODE> and <CODE>ntohs</CODE> to convert values for the <CODE>sin_port</CODE>
member.  Use <CODE>htonl</CODE> and <CODE>ntohl</CODE> to convert values for the
<CODE>sin_addr</CODE> member.  (Remember, <CODE>struct in_addr</CODE> is equivalent
to <CODE>unsigned long int</CODE>.)  These functions are declared in
<TT>`netinet/in.h'</TT>.
<A NAME="IDX987"></A>
<P>
<A NAME="IDX988"></A>
<U>Function:</U> unsigned short int <B>htons</B> <I>(unsigned short int <VAR>hostshort</VAR>)</I><P>
This function converts the <CODE>short</CODE> integer <VAR>hostshort</VAR> from
host byte order to network byte order.
<P>
<A NAME="IDX989"></A>
<U>Function:</U> unsigned short int <B>ntohs</B> <I>(unsigned short int <VAR>netshort</VAR>)</I><P>
This function converts the <CODE>short</CODE> integer <VAR>netshort</VAR> from
network byte order to host byte order.
<P>
<A NAME="IDX990"></A>
<U>Function:</U> unsigned long int <B>htonl</B> <I>(unsigned long int <VAR>hostlong</VAR>)</I><P>
This function converts the <CODE>long</CODE> integer <VAR>hostlong</VAR> from
host byte order to network byte order.
<P>
<A NAME="IDX991"></A>
<U>Function:</U> unsigned long int <B>ntohl</B> <I>(unsigned long int <VAR>netlong</VAR>)</I><P>
This function converts the <CODE>long</CODE> integer <VAR>netlong</VAR> from
network byte order to host byte order.
<P>
<A NAME="IDX992"></A>
<H3><A NAME="SEC237" HREF="library_toc.html#SEC237">Protocols Database</A></H3>
<P>
The communications protocol used with a socket controls low-level
details of how data is exchanged.  For example, the protocol implements
things like checksums to detect errors in transmissions, and routing
instructions for messages.  Normal user programs have little reason to
mess with these details directly.
<A NAME="IDX993"></A>
<P>
The default communications protocol for the Internet namespace depends on
the communication style.  For stream communication, the default is TCP
("transmission control protocol").  For datagram communication, the
default is UDP ("user datagram protocol").  For reliable datagram
communication, the default is RDP ("reliable datagram protocol").
You should nearly always use the default.
<A NAME="IDX994"></A>
<P>
Internet protocols are generally specified by a name instead of a
number.  The network protocols that a host knows about are stored in a
database.  This is usually either derived from the file
<TT>`/etc/protocols'</TT>, or it may be an equivalent provided by a name
server.  You look up the protocol number associated with a named
protocol in the database using the <CODE>getprotobyname</CODE> function.
<P>
Here are detailed descriptions of the utilities for accessing the
protocols database.  These are declared in <TT>`netdb.h'</TT>.
<A NAME="IDX995"></A>
<P>
<A NAME="IDX996"></A>
<U>Data Type:</U> <B>struct protoent</B><P>
This data type is used to represent entries in the network protocols
database.  It has the following members:
<P>
<DL COMPACT>
<DT><CODE>char *p_name</CODE>
<DD>This is the official name of the protocol.
<P>
<DT><CODE>char **p_aliases</CODE>
<DD>These are alternate names for the protocol, specified as an array of
strings.  The last element of the array is a null pointer.
<P>
<DT><CODE>int p_proto</CODE>
<DD>This is the protocol number (in host byte order); use this member as the
<VAR>protocol</VAR> argument to <CODE>socket</CODE>.
</DL>
<P>
You can use <CODE>getprotobyname</CODE> and <CODE>getprotobynumber</CODE> to search
the protocols database for a specific protocol.  The information is
returned in a statically-allocated structure; you must copy the
information if you need to save it across calls.
<P>
<A NAME="IDX997"></A>
<U>Function:</U> struct protoent * <B>getprotobyname</B> <I>(const char *<VAR>name</VAR>)</I><P>
The <CODE>getprotobyname</CODE> function returns information about the
network protocol named <VAR>name</VAR>.  If there is no such protocol, it
returns a null pointer.
<P>
<A NAME="IDX998"></A>
<U>Function:</U> struct protoent * <B>getprotobynumber</B> <I>(int <VAR>protocol</VAR>)</I><P>
The <CODE>getprotobynumber</CODE> function returns information about the
network protocol with number <VAR>protocol</VAR>.  If there is no such
protocol, it returns a null pointer.
<P>
You can also scan the whole protocols database one protocol at a time by
using <CODE>setprotoent</CODE>, <CODE>getprotoent</CODE>, and <CODE>endprotoent</CODE>.
Be careful in using these functions, because they are not reentrant.
<P>
<A NAME="IDX999"></A>
<U>Function:</U> void <B>setprotoent</B> <I>(int <VAR>stayopen</VAR>)</I><P>
This function opens the protocols database to begin scanning it.
<P>
If the <VAR>stayopen</VAR> argument is nonzero, this sets a flag so that
subsequent calls to <CODE>getprotobyname</CODE> or <CODE>getprotobynumber</CODE> will
not close the database (as they usually would).  This makes for more
efficiency if you call those functions several times, by avoiding
reopening the database for each call.
<P>
<A NAME="IDX1000"></A>
<U>Function:</U> struct protoent * <B>getprotoent</B> <I>(void)</I><P>
This function returns the next entry in the protocols database.  It
returns a null pointer if there are no more entries.
<P>
<A NAME="IDX1001"></A>
<U>Function:</U> void <B>endprotoent</B> <I>(void)</I><P>
This function closes the protocols database.
<P>
<H3><A NAME="SEC238" HREF="library_toc.html#SEC238">Internet Socket Example</A></H3>
<P>
Here is an example showing how to create and name a socket in the
Internet namespace.  The newly created socket exists on the machine that
the program is running on.  Rather than finding and using the machine's
Internet address, this example specifies <CODE>INADDR_ANY</CODE> as the host
address; the system replaces that with the machine's actual address.
<P>
<PRE>
#include &#60;stdio.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;sys/socket.h&#62;
#include &#60;netinet/in.h&#62;

int 
make_socket (unsigned short int port)
{
  int sock;
  struct sockaddr_in name;

  /* Create the socket.  */
  sock = socket (PF_INET, SOCK_STREAM, 0);
  if (sock &#60; 0)
    {
      perror ("socket");
      exit (EXIT_FAILURE);
    }

  /* Give the socket a name.  */
  name.sin_family = AF_INET;
  name.sin_port = htons (port);
  name.sin_addr.s_addr = htonl (INADDR_ANY);
  if (bind (sock, (struct sockaddr *) &#38;name, sizeof (name)) &#60; 0)
    {
      perror ("bind");
      exit (EXIT_FAILURE);
    }

  return sock;
}
</PRE>
<P>
Here is another example, showing how you can fill in a <CODE>sockaddr_in</CODE>
structure, given a host name string and a port number:
<P>
<PRE>
#include &#60;stdio.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;sys/socket.h&#62;
#include &#60;netinet/in.h&#62;
#include &#60;netdb.h&#62;

void 
init_sockaddr (struct sockaddr_in *name,
	       const char *hostname, unsigned short int port)
{
  struct hostent *hostinfo;

  name-&#62;sin_family = AF_INET;
  name-&#62;sin_port = htons (port);
  hostinfo = gethostbyname (serverhost);
  if (hostinfo == NULL) 
    {
      fprintf (stderr, "Unknown host %s.\n", hostname);
      exit (EXIT_FAILURE);
    }
  name-&#62;sin_addr = *(struct in_addr *) hostinfo-&#62;h_addr;
}
</PRE>
<P>
<H2><A NAME="SEC239" HREF="library_toc.html#SEC239">Other Namespaces</A></H2>
<A NAME="IDX1002"></A>
<A NAME="IDX1003"></A>
<A NAME="IDX1004"></A>
<A NAME="IDX1005"></A>
<A NAME="IDX1006"></A>
<P>
Certain other namespaces and associated protocol families are supported
but not documented yet because they are not often used.  <CODE>PF_NS</CODE>
refers to the Xerox Network Software protocols.  <CODE>PF_ISO</CODE> stands
for Open Systems Interconnect.  <CODE>PF_CCITT</CODE> refers to protocols from
CCITT.  <TT>`socket.h'</TT> defines these symbols and others naming protocols
not actually implemented.
<P>
<CODE>PF_IMPLINK</CODE> is used for communicating between hosts and Internet
Message Processors.  For information on this, and on <CODE>PF_ROUTE</CODE>, an
occasionally-used local area routing protocol, see the GNU Hurd Manual
(to appear in the future).
<P>
<H2><A NAME="SEC240" HREF="library_toc.html#SEC240">Opening and Closing Sockets</A></H2>
<P>
This section describes the actual library functions for opening and
closing sockets.  The same functions work for all namespaces and
connection styles.
<P>
<A NAME="IDX1007"></A>
<A NAME="IDX1008"></A>
<A NAME="IDX1009"></A>
<H3><A NAME="SEC241" HREF="library_toc.html#SEC241">Creating a Socket</A></H3>
<P>
The primitive for creating a socket is the <CODE>socket</CODE> function,
declared in <TT>`sys/socket.h'</TT>.
<A NAME="IDX1010"></A>
<P>
<A NAME="IDX1011"></A>
<U>Function:</U> int <B>socket</B> <I>(int <VAR>namespace</VAR>, int <VAR>style</VAR>, int <VAR>protocol</VAR>)</I><P>
This function creates a socket and specifies communication style
<VAR>style</VAR>, which should be one of the socket styles listed in
section <A HREF="library.html#SEC218">Communication Styles</A>.  The <VAR>namespace</VAR> argument specifies
the namespace; it must be <CODE>PF_FILE</CODE> (see section <A HREF="library.html#SEC223">The File Namespace</A>) or
<CODE>PF_INET</CODE> (see section <A HREF="library.html#SEC227">The Internet Namespace</A>).  <VAR>protocol</VAR>
designates the specific protocol (see section <A HREF="library.html#SEC217">Socket Concepts</A>); zero is
usually right for <VAR>protocol</VAR>.
<P>
The return value from <CODE>socket</CODE> is the file descriptor for the new
socket, or <CODE>-1</CODE> in case of error.  The following <CODE>errno</CODE> error
conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EPROTONOSUPPORT</CODE>
<DD>The <VAR>protocol</VAR> or <VAR>style</VAR> is not supported by the
<VAR>namespace</VAR> specified.
<P>
<DT><CODE>EMFILE</CODE>
<DD>The process already has too many file descriptors open.
<P>
<DT><CODE>ENFILE</CODE>
<DD>The system already has too many file descriptors open.
<P>
<DT><CODE>EACCESS</CODE>
<DD>The process does not have privilege to create a socket of the specified
<VAR>style</VAR> or <VAR>protocol</VAR>.
<P>
<DT><CODE>ENOBUFS</CODE>
<DD>The system ran out of internal buffer space.
</DL>
<P>
The file descriptor returned by the <CODE>socket</CODE> function supports both
read and write operations.  But, like pipes, sockets do not support file
positioning operations.
<P>
For examples of how to call the <CODE>socket</CODE> function, 
see section <A HREF="library.html#SEC223">The File Namespace</A>, or section <A HREF="library.html#SEC238">Internet Socket Example</A>.
<P>
<A NAME="IDX1012"></A>
<A NAME="IDX1013"></A>
<A NAME="IDX1014"></A>
<A NAME="IDX1015"></A>
<H3><A NAME="SEC242" HREF="library_toc.html#SEC242">Closing a Socket</A></H3>
<P>
When you are finished using a socket, you can simply close its
file descriptor with <CODE>close</CODE>; see section <A HREF="library.html#SEC172">Opening and Closing Files</A>.
If there is still data waiting to be transmitted over the connection,
normally <CODE>close</CODE> tries to complete this transmission.  You
can control this behavior using the <CODE>SO_LINGER</CODE> socket option to
specify a timeout period; see section <A HREF="library.html#SEC264">Socket Options</A>.
<A NAME="IDX1016"></A>
<P>
You can also shut down only reception or only transmission on a
connection by calling <CODE>shutdown</CODE>, which is declared in
<TT>`sys/socket.h'</TT>.
<P>
<A NAME="IDX1017"></A>
<U>Function:</U> int <B>shutdown</B> <I>(int <VAR>socket</VAR>, int <VAR>how</VAR>)</I><P>
The <CODE>shutdown</CODE> function shuts down the connection of socket
<VAR>socket</VAR>.  The argument <VAR>how</VAR> specifies what action to
perform:
<P>
<DL COMPACT>
<DT><CODE>0</CODE>
<DD>Stop receiving data for this socket.  If further data arrives,
reject it.
<P>
<DT><CODE>1</CODE>
<DD>Stop trying to transmit data from this socket.  Discard any data
waiting to be sent.  Stop looking for acknowledgement of data already
sent; don't retransmit it if it is lost.
<P>
<DT><CODE>2</CODE>
<DD>Stop both reception and transmission.
</DL>
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  The
following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD><VAR>socket</VAR> is not a valid file descriptor.
<P>
<DT><CODE>ENOTSOCK</CODE>
<DD><VAR>socket</VAR> is not a socket.
<P>
<DT><CODE>ENOTCONN</CODE>
<DD><VAR>socket</VAR> is not connected.
</DL>
<P>
<A NAME="IDX1018"></A>
<A NAME="IDX1019"></A>
<A NAME="IDX1020"></A>
<H3><A NAME="SEC243" HREF="library_toc.html#SEC243">Socket Pairs</A></H3>
<A NAME="IDX1021"></A>
<P>
A <DFN>socket pair</DFN> consists of a pair of connected (but unnamed)
sockets.  It is very similar to a pipe and is used in much the same
way.  Socket pairs are created with the <CODE>socketpair</CODE> function,
declared in <TT>`sys/socket.h'</TT>.  A socket pair is much like a pipe; the
main difference is that the socket pair is bidirectional, whereas the
pipe has one input-only end and one output-only end (see section <A HREF="library.html#SEC211">Pipes and FIFOs</A>).
<P>
<A NAME="IDX1022"></A>
<U>Function:</U> int <B>socketpair</B> <I>(int <VAR>namespace</VAR>, int <VAR>style</VAR>, int <VAR>protocol</VAR>, int <VAR>filedes</VAR><TT>[2]</TT>)</I><P>
This function creates a socket pair, returning the file descriptors in
<CODE><VAR>filedes</VAR>[0]</CODE> and <CODE><VAR>filedes</VAR>[1]</CODE>.  The socket pair
is a full-duplex communications channel, so that both reading and writing
may be performed at either end.
<P>
The <VAR>namespace</VAR>, <VAR>style</VAR>, and <VAR>protocol</VAR> arguments are
interpreted as for the <CODE>socket</CODE> function.  <VAR>style</VAR> should be
one of the communication styles listed in section <A HREF="library.html#SEC218">Communication Styles</A>.
The <VAR>namespace</VAR> argument specifies the namespace, which must be
<CODE>AF_FILE</CODE> (see section <A HREF="library.html#SEC223">The File Namespace</A>); <VAR>protocol</VAR> specifies the
communications protocol, but zero is the only meaningful value.
<P>
If <VAR>style</VAR> specifies a connectionless communication style, then
the two sockets you get are not <EM>connected</EM>, strictly speaking,
but each of them knows the other as the default destination address,
so they can send packets to each other.
<P>
The <CODE>socketpair</CODE> function returns <CODE>0</CODE> on success and <CODE>-1</CODE>
on failure.  The following <CODE>errno</CODE> error conditions are defined
for this function:
<P>
<DL COMPACT>
<DT><CODE>EMFILE</CODE>
<DD>The process has too many file descriptors open.
<P>
<DT><CODE>EAFNOSUPPORT</CODE>
<DD>The specified namespace is not supported.
<P>
<DT><CODE>EPROTONOSUPPORT</CODE>
<DD>The specified protocol is not supported.
<P>
<DT><CODE>EOPNOTSUPP</CODE>
<DD>The specified protocol does not support the creation of socket pairs.
</DL>
<P>
<H2><A NAME="SEC244" HREF="library_toc.html#SEC244">Using Sockets with Connections</A></H2>
<A NAME="IDX1023"></A>
<A NAME="IDX1024"></A>
<A NAME="IDX1025"></A>
<P>
The most common communication styles involve making a connection to a
particular other socket, and then exchanging data with that socket
over and over.  Making a connection is asymmetric; one side (the
<DFN>client</DFN>) acts to request a connection, while the other side (the
<DFN>server</DFN>) makes a socket and waits for the connection request.
<P>
<UL>
<LI>
section <A HREF="library.html#SEC245">Making a Connection</A>, describes what the client program must do to
initiate a connection with a server.
<P>
<LI>
section <A HREF="library.html#SEC246">Listening for Connections</A>, and section <A HREF="library.html#SEC247">Accepting Connections</A>, describe what the
server program must do to wait for and act upon connection requests
from clients.
<P>
<LI>
section <A HREF="library.html#SEC249">Transferring Data</A>, describes how data is transferred through the
connected socket.
</UL>
<P>
<A NAME="IDX1026"></A>
<A NAME="IDX1027"></A>
<A NAME="IDX1028"></A>
<A NAME="IDX1029"></A>
<H3><A NAME="SEC245" HREF="library_toc.html#SEC245">Making a Connection</A></H3>
<P>
In making a connection, the client makes a connection while the server
waits for and accepts the connection.  Here we discuss what the client
program must do, using the <CODE>connect</CODE> function.
<P>
<A NAME="IDX1030"></A>
<U>Function:</U> int <B>connect</B> <I>(int <VAR>socket</VAR>, struct sockaddr *<VAR>addr</VAR>, size_t <VAR>length</VAR>)</I><P>
The <CODE>connect</CODE> function initiates a connection from the socket
with file descriptor <VAR>socket</VAR> to the socket whose address is
specified by the <VAR>addr</VAR> and <VAR>length</VAR> arguments.  (This socket
is typically on another machine, and it must be already set up as a
server.)  See section <A HREF="library.html#SEC219">Socket Addresses</A>, for information about how these
arguments are interpreted.
<P>
Normally, <CODE>connect</CODE> waits until the server responds to the request
before it returns.  You can set nonblocking mode on the socket
<VAR>socket</VAR> to make <CODE>connect</CODE> return immediately without waiting
for the response.  See section <A HREF="library.html#SEC184">File Status Flags</A>, for information about
nonblocking mode.
<P>
The normal return value from <CODE>connect</CODE> is <CODE>0</CODE>.  If an error
occurs, <CODE>connect</CODE> returns <CODE>-1</CODE>.  The following <CODE>errno</CODE>
error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The socket <VAR>socket</VAR> is not a valid file descriptor.
<P>
<DT><CODE>ENOTSOCK</CODE>
<DD>The socket <VAR>socket</VAR> is not a socket.
<P>
<DT><CODE>EADDRNOTAVAIL</CODE>
<DD>The specified address is not available on the remote machine.
<P>
<DT><CODE>EAFNOSUPPORT</CODE>
<DD>The namespace of the <VAR>addr</VAR> is not supported by this socket.
<P>
<DT><CODE>EISCONN</CODE>
<DD>The socket <VAR>socket</VAR> is already connected.
<P>
<DT><CODE>ETIMEDOUT</CODE>
<DD>The attempt to establish the connection timed out.
<P>
<DT><CODE>ECONNREFUSED</CODE>
<DD>The server has actively refused to establish the connection.
<P>
<DT><CODE>ENETUNREACH</CODE>
<DD>The network of the given <VAR>addr</VAR> isn't reachable from this host.
<P>
<DT><CODE>EADDRINUSE</CODE>
<DD>The socket address of the given <VAR>addr</VAR> is already in use.
<P>
<DT><CODE>EINPROGRESS</CODE>
<DD>The socket <VAR>socket</VAR> is non-blocking and the connection could not be
established immediately.
<P>
<DT><CODE>EALREADY</CODE>
<DD>The socket <VAR>socket</VAR> is non-blocking and already has a pending
connection in progress.
</DL>
<P>
<A NAME="IDX1031"></A>
<A NAME="IDX1032"></A>
<A NAME="IDX1033"></A>
<H3><A NAME="SEC246" HREF="library_toc.html#SEC246">Listening for Connections</A></H3>
<P>
Now let us consider what the server process must do to accept
connections on a socket.  This involves the use of the <CODE>listen</CODE>
function to enable connection requests on the socket, and later using
the <CODE>accept</CODE> function (see section <A HREF="library.html#SEC247">Accepting Connections</A>) to act on a
request.  The <CODE>listen</CODE> function is not allowed for sockets using
connectionless communication styles.
<P>
You can write a network server that does not even start running until a
connection to it is requested.  See section <A HREF="library.html#SEC262"><CODE>inetd</CODE> Servers</A>.
<P>
In the Internet namespace, there are no special protection mechanisms
for controlling access to connect to a port; any process on any machine
can make a connection to your server.  If you want to restrict access to
your server, make it examine the addresses associated with connection
requests or implement some other handshaking or identification
protocol.
<P>
In the File namespace, the ordinary file protection bits control who has
access to connect to the socket.
<P>
<A NAME="IDX1034"></A>
<U>Function:</U> int <B>listen</B> <I>(int <VAR>socket</VAR>, unsigned int <VAR>n</VAR>)</I><P>
The <CODE>listen</CODE> function enables the socket <VAR>socket</VAR> to
accept connections, thus making it a server socket.
<P>
The argument <VAR>n</VAR> specifies the length of the queue for pending
connections.
<P>
The <CODE>listen</CODE> function returns <CODE>0</CODE> on success and <CODE>-1</CODE>
on failure.  The following <CODE>errno</CODE> error conditions are defined
for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The argument <VAR>socket</VAR> is not a valid file descriptor.
<P>
<DT><CODE>ENOTSOCK</CODE>
<DD>The argument <VAR>socket</VAR> is not a socket.
<P>
<DT><CODE>EOPNOTSUPP</CODE>
<DD>The socket <VAR>socket</VAR> does not support this operation.
</DL>
<P>
<A NAME="IDX1035"></A>
<A NAME="IDX1036"></A>
<H3><A NAME="SEC247" HREF="library_toc.html#SEC247">Accepting Connections</A></H3>
<P>
When a server receives a connection request, it can complete the
connection by accepting the request.  Use the function <CODE>accept</CODE>
to do this.
<P>
A socket that has been established as a server can accept connection
requests from multiple clients.  The server's original socket
<EM>does not become part</EM> of the connection; instead, <CODE>accept</CODE>
makes a new socket which participates in the connection.
<CODE>accept</CODE> returns the descriptor for this socket.  The server's
original socket remains available for listening for further connection
requests.
<P>
The number of pending connection requests on a server socket is finite.
If connection requests arrive from clients faster than the server can
act upon them, the queue can fill up and additional requests are refused
with a <CODE>ECONNREFUSED</CODE> error.  You can specify the maximum length of
this queue as an argument to the <CODE>listen</CODE> function, although the
system may also impose its own internal limit on the length of this
queue.
<P>
<A NAME="IDX1037"></A>
<U>Function:</U> int <B>accept</B> <I>(int <VAR>socket</VAR>, struct sockaddr *<VAR>addr</VAR>, size_t *<VAR>length_ptr</VAR>)</I><P>
This function is used to accept a connection request on the server
socket <VAR>socket</VAR>.
<P>
The <CODE>accept</CODE> function waits if there are no connections pending,
unless the socket <VAR>socket</VAR> has nonblocking mode set.  (You can use
<CODE>select</CODE> to wait for a pending connection, with a nonblocking
socket.)  See section <A HREF="library.html#SEC184">File Status Flags</A>, for information about nonblocking
mode.
<P>
The <VAR>addr</VAR> and <VAR>length_ptr</VAR> arguments are used to return
information about the name of the client socket that initiated the
connection.  See section <A HREF="library.html#SEC219">Socket Addresses</A>, for information about the format
of the information.
<P>
Accepting a connection does not make <VAR>socket</VAR> part of the
connection.  Instead, it creates a new socket which becomes
connected.  The normal return value of <CODE>accept</CODE> is the file
descriptor for the new socket.
<P>
After <CODE>accept</CODE>, the original socket <VAR>socket</VAR> remains open and
unconnected, and continues listening until you close it.  You can
accept further connections with <VAR>socket</VAR> by calling <CODE>accept</CODE>
again.
<P>
If an error occurs, <CODE>accept</CODE> returns <CODE>-1</CODE>.  The following
<CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>socket</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>ENOTSOCK</CODE>
<DD>The descriptor <VAR>socket</VAR> argument is not a socket.
<P>
<DT><CODE>EOPNOTSUPP</CODE>
<DD>The descriptor <VAR>socket</VAR> does not support this operation.
<P>
<DT><CODE>EWOULDBLOCK</CODE>
<DD><VAR>socket</VAR> has nonblocking mode set, and there are no pending
connections immediately available.
</DL>
<P>
The <CODE>accept</CODE> function is not allowed for sockets using
connectionless communication styles.
<P>
<H3><A NAME="SEC248" HREF="library_toc.html#SEC248">Who is Connected to Me?</A></H3>
<P>
<A NAME="IDX1038"></A>
<U>Function:</U> int <B>getpeername</B> <I>(int <VAR>socket</VAR>, struct sockaddr *<VAR>addr</VAR>, size_t *<VAR>length_ptr</VAR>)</I><P>
The <CODE>getpeername</CODE> function returns the address of the socket that
<VAR>socket</VAR> is connected to; it stores the address in the memory space
specified by <VAR>addr</VAR> and <VAR>length_ptr</VAR>.  It stores the length of
the address in <CODE>*<VAR>length_ptr</VAR></CODE>.
<P>
See section <A HREF="library.html#SEC219">Socket Addresses</A>, for information about the format of the
address.  In some operating systems, <CODE>getpeername</CODE> works only for
sockets in the Internet domain.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on error.  The
following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The argument <VAR>socket</VAR> is not a valid file descriptor.
<P>
<DT><CODE>ENOTSOCK</CODE>
<DD>The descriptor <VAR>socket</VAR> is not a socket.
<P>
<DT><CODE>ENOTCONN</CODE>
<DD>The socket <VAR>socket</VAR> is not connected.
<P>
<DT><CODE>ENOBUFS</CODE>
<DD>There are not enough internal buffers available.
</DL>
<P>
<A NAME="IDX1039"></A>
<A NAME="IDX1040"></A>
<H3><A NAME="SEC249" HREF="library_toc.html#SEC249">Transferring Data</A></H3>
<P>
Once a socket has been connected to a peer, you can use the ordinary
<CODE>read</CODE> and <CODE>write</CODE> operations (see section <A HREF="library.html#SEC173">Input and Output Primitives</A>) to
transfer data.  A socket is a two-way communications channel, so read
and write operations can be performed at either end.
<P>
There are also some I/O modes that are specific to socket operations.
In order to specify these modes, you must use the <CODE>recv</CODE> and
<CODE>send</CODE> functions instead of the more generic <CODE>read</CODE> and
<CODE>write</CODE> functions.  The <CODE>recv</CODE> and <CODE>send</CODE> functions take
an additional argument which you can use to specify various flags to
control the special I/O modes.  For example, you can specify the
<CODE>MSG_OOB</CODE> flag to read or write out-of-band data, the
<CODE>MSG_PEEK</CODE> flag to peek at input, or the <CODE>MSG_DONTROUTE</CODE> flag
to control inclusion of routing information on output.
<P>
<H4><A NAME="SEC250" HREF="library_toc.html#SEC250">Sending Data</A></H4>
<A NAME="IDX1041"></A>
<P>
The <CODE>send</CODE> function is declared in the header file
<TT>`sys/socket.h'</TT>.  If your <VAR>flags</VAR> argument is zero, you can just
as well use <CODE>write</CODE> instead of <CODE>send</CODE>; see section <A HREF="library.html#SEC173">Input and Output Primitives</A>.  If the socket was connected but the connection has broken,
you get a <CODE>SIGPIPE</CODE> signal for any use of <CODE>send</CODE> or
<CODE>write</CODE> (see section <A HREF="library.html#SEC341">Miscellaneous Signals</A>).
<P>
<A NAME="IDX1042"></A>
<U>Function:</U> int <B>send</B> <I>(int <VAR>socket</VAR>, void *<VAR>buffer</VAR>, size_t <VAR>size</VAR>, int <VAR>flags</VAR>)</I><P>
The <CODE>send</CODE> function is like <CODE>write</CODE>, but with the additional
flags <VAR>flags</VAR>.  The possible values of <VAR>flags</VAR> are described
in section <A HREF="library.html#SEC252">Socket Data Options</A>.
<P>
This function returns the number of bytes transmitted, or <CODE>-1</CODE> on
failure.  If the socket is nonblocking, then <CODE>send</CODE> (like
<CODE>write</CODE>) can return after sending just part of the data.
See section <A HREF="library.html#SEC184">File Status Flags</A>, for information about nonblocking mode.
<P>
Note, however, that a successful return value merely indicates that
the message has been sent without error, not necessarily that it has
been received without error.
<P>
The following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>socket</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>EINTR</CODE>
<DD>The operation was interrupted by a signal before any data was sent.
See section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<DT><CODE>ENOTSOCK</CODE>
<DD>The descriptor <VAR>socket</VAR> is not a socket.
<P>
<DT><CODE>EMSGSIZE</CODE>
<DD>The socket type requires that the message be sent atomically, but the
message is too large for this to be possible.
<P>
<DT><CODE>EWOULDBLOCK</CODE>
<DD>Nonblocking mode has been set on the socket, and the write operation
would block.  (Normally <CODE>send</CODE> blocks until the operation can be
completed.)
<P>
<DT><CODE>ENOBUFS</CODE>
<DD>There is not enough internal buffer space available.
<P>
<DT><CODE>ENOTCONN</CODE>
<DD>You never connected this socket.
<P>
<DT><CODE>EPIPE</CODE>
<DD>This socket was connected but the connection is now broken.  In this
case, <CODE>send</CODE> generates a <CODE>SIGPIPE</CODE> signal first; if that
signal is ignored or blocked, or if its handler returns, then
<CODE>send</CODE> fails with <CODE>EPIPE</CODE>.
</DL>
<P>
<H4><A NAME="SEC251" HREF="library_toc.html#SEC251">Receiving Data</A></H4>
<A NAME="IDX1043"></A>
<P>
The <CODE>recv</CODE> function is declared in the header file
<TT>`sys/socket.h'</TT>.  If your <VAR>flags</VAR> argument is zero, you can
just as well use <CODE>read</CODE> instead of <CODE>recv</CODE>; see section <A HREF="library.html#SEC173">Input and Output Primitives</A>.
<P>
<A NAME="IDX1044"></A>
<U>Function:</U> int <B>recv</B> <I>(int <VAR>socket</VAR>, void *<VAR>buffer</VAR>, size_t <VAR>size</VAR>, int <VAR>flags</VAR>)</I><P>
The <CODE>recv</CODE> function is like <CODE>read</CODE>, but with the additional
flags <VAR>flags</VAR>.  The possible values of <VAR>flags</VAR> are described
In section <A HREF="library.html#SEC252">Socket Data Options</A>.
<P>
If nonblocking mode is set for <VAR>socket</VAR>, and no data is available to
be read, <CODE>recv</CODE> fails immediately rather than waiting.  See section <A HREF="library.html#SEC184">File Status Flags</A>, for information about nonblocking mode.
<P>
This function returns the number of bytes received, or <CODE>-1</CODE> on failure.
The following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>socket</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>ENOTSOCK</CODE>
<DD>The descriptor <VAR>socket</VAR> is not a socket.
<P>
<DT><CODE>EWOULDBLOCK</CODE>
<DD>Nonblocking mode has been set on the socket, and the read operation
would block.  (Normally, <CODE>recv</CODE> blocks until there is input
available to be read.)
<P>
<DT><CODE>EINTR</CODE>
<DD>The operation was interrupted by a signal before any data was read.
See section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<DT><CODE>ENOTCONN</CODE>
<DD>You never connected this socket.
</DL>
<P>
<H4><A NAME="SEC252" HREF="library_toc.html#SEC252">Socket Data Options</A></H4>
<A NAME="IDX1045"></A>
<P>
The <VAR>flags</VAR> argument to <CODE>send</CODE> and <CODE>recv</CODE> is a bit
mask.  You can bitwise-OR the values of the following macros together
to obtain a value for this argument.  All are defined in the header
file <TT>`sys/socket.h'</TT>.
<P>
<A NAME="IDX1046"></A>
<U>Macro:</U> int <B>MSG_OOB</B><P>
Send or receive out-of-band data.  See section <A HREF="library.html#SEC255">Out-of-Band Data</A>.
<P>
<A NAME="IDX1047"></A>
<U>Macro:</U> int <B>MSG_PEEK</B><P>
Look at the data but don't remove it from the input queue.  This is
only meaningful with input functions such as <CODE>recv</CODE>, not with
<CODE>send</CODE>.
<P>
<A NAME="IDX1048"></A>
<U>Macro:</U> int <B>MSG_DONTROUTE</B><P>
Don't include routing information in the message.  This is only
meaningful with output operations, and is usually only of interest for
diagnostic or routing programs.  We don't try to explain it here.
<P>
<H3><A NAME="SEC253" HREF="library_toc.html#SEC253">Byte Stream Socket Example</A></H3>
<P>
Here is an example client program that makes a connection for a byte
stream socket in the Internet namespace.  It doesn't do anything
particularly interesting once it has connected to the server; it just
sends a text string to the server and exits.
<P>
<PRE>
#include &#60;stdio.h&#62;
#include &#60;errno.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;unistd.h&#62;
#include &#60;sys/types.h&#62;
#include &#60;sys/socket.h&#62;
#include &#60;netinet/in.h&#62;
#include &#60;netdb.h&#62;

#define PORT		5555
#define MESSAGE		"Yow!!! Are we having fun yet?!?"
#define SERVERHOST 	"churchy.gnu.ai.mit.edu"

void 
write_to_server (int filedes)
{
  int nbytes;

  nbytes = write (filedes, MESSAGE, strlen (MESSAGE) + 1);
  if (nbytes &#60; 0)
    {
      perror ("write");
      exit (EXIT_FAILURE);
    }
}


int
main (void)
{
  extern void init_sockaddr (struct sockaddr_in *name,
			     const char *hostname, unsigned short int port);
  int sock;
  struct sockaddr_in servername;

  /* Create the socket.   */
  sock = socket (PF_INET, SOCK_STREAM, 0);
  if (sock &#60; 0)
    {
      perror ("socket (client)");
      exit (EXIT_FAILURE);
    }

  /* Connect to the server.   */
  init_sockaddr (&#38;servername, SERVERHOST, PORT);
  if (0 &#62; connect (sock,
		   (struct sockaddr *) &#38;servername,
		   sizeof (servername)))
    {
      perror ("connect (client)");
      exit (EXIT_FAILURE);
    }

  /* Send data to the server.   */
  write_to_server (sock);
  close (sock);
  exit (EXIT_SUCCESS);
}
</PRE>
<P>
<H3><A NAME="SEC254" HREF="library_toc.html#SEC254">Byte Stream Connection Server Example</A></H3>
<P>
The server end is much more complicated.  Since we want to allow
multiple clients to be connected to the server at the same time, it
would be incorrect to wait for input from a single client by simply
calling <CODE>read</CODE> or <CODE>recv</CODE>.  Instead, the right thing to do is
to use <CODE>select</CODE> (see section <A HREF="library.html#SEC180">Waiting for Input or Output</A>) to wait for input on
all of the open sockets.  This also allows the server to deal with
additional connection requests.
<P>
This particular server doesn't do anything interesting once it has
gotten a message from a client.  It does close the socket for that
client when it detects an end-of-file condition (resulting from the
client shutting down its end of the connection).
<P>
This program uses <CODE>make_socket</CODE> and <CODE>init_sockaddr</CODE> to set
up the socket address; see section <A HREF="library.html#SEC238">Internet Socket Example</A>.
<P>
<PRE>
#include &#60;stdio.h&#62;
#include &#60;errno.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;unistd.h&#62;
#include &#60;sys/types.h&#62;
#include &#60;sys/socket.h&#62;
#include &#60;netinet/in.h&#62;
#include &#60;netdb.h&#62;

#define PORT	5555
#define MAXMSG	512

int
read_from_client (int filedes)
{
  char buffer[MAXMSG];
  int nbytes;

  nbytes = read (filedes, buffer, MAXMSG);
  if (nbytes &#60; 0)
    {
      /* Read error.  */
      perror ("read");
      exit (EXIT_FAILURE);
    }
  else if (nbytes == 0)
    /* End-of-file.  */
    return -1;
  else
    {
      /* Data read.  */
      fprintf (stderr, "Server: got message: `%s'\n", buffer);
      return 0;
    }
}

int
main (void)
{
  extern int make_socket (unsigned short int port);
  int sock;
  int status;
  fd_set active_fd_set, read_fd_set;
  int i;
  struct sockaddr_in clientname;
  size_t size;

  /* Create the socket and set it up to accept connections.  */
  sock = make_socket (PORT);
  if (listen (sock, 1) &#60; 0)
    {
      perror ("listen");
      exit (EXIT_FAILURE);
    }

  /* Initialize the set of active sockets.  */
  FD_ZERO (&#38;active_fd_set);
  FD_SET (sock, &#38;active_fd_set);

  while (1)
    {
      /* Block until input arrives on one or more active sockets.  */
      read_fd_set = active_fd_set;
      if (select (FD_SETSIZE, &#38;read_fd_set, NULL, NULL, NULL) &#60; 0)
	{
	  perror ("select");
	  exit (EXIT_FAILURE);
	}

      /* Service all the sockets with input pending.  */
      for (i = 0; i &#60; FD_SETSIZE; ++i)
	if (FD_ISSET (i, &#38;read_fd_set))
	  {
	    if (i == sock)
	      {
		/* Connection request on original socket.  */
		size = sizeof (clientname);
		if (accept (sock,
			    (struct sockaddr *) &#38;clientname, &#38;size) &#60; 0)
		  {
		    perror ("accept");
		    exit (EXIT_FAILURE);
		  }
		fprintf (stderr, "Server: connect from host %s, port %hd.\n",
			 inet_ntoa (clientname.sin_addr),
			 ntohs (clientname.sin_port));
		FD_SET (status, &#38;active_fd_set);
	      }
	    else
	      {
		/* Data arriving on an already-connected socket.  */
		if (read_from_client (i) &#60; 0)
		  {
		    close (i);
		    FD_CLR (i, &#38;active_fd_set);
		  }
	      }
	  }
    }
}
</PRE>
<P>
<H3><A NAME="SEC255" HREF="library_toc.html#SEC255">Out-of-Band Data</A></H3>
<A NAME="IDX1049"></A>
<A NAME="IDX1050"></A>
<P>
Streams with connections permit <DFN>out-of-band</DFN> data that is
delivered with higher priority than ordinary data.  Typically the
reason for sending out-of-band data is to send notice of an
exceptional condition.  The way to send out-of-band data is using
<CODE>send</CODE>, specifying the flag <CODE>MSG_OOB</CODE> (see section <A HREF="library.html#SEC250">Sending Data</A>).
<P>
Out-of-band data is received with higher priority because the
receiving process need not read it in sequence; to read the next
available out-of-band data, use <CODE>recv</CODE> with the <CODE>MSG_OOB</CODE>
flag (see section <A HREF="library.html#SEC251">Receiving Data</A>).  Ordinary read operations do not read
out-of-band data; they read only the ordinary data.
<A NAME="IDX1051"></A>
<P>
When a socket finds that out-of-band data is on its way, it sends a
<CODE>SIGURG</CODE> signal to the owner process or process group of the
socket.  You can specify the owner using the <CODE>F_SETOWN</CODE> command
to the <CODE>fcntl</CODE> function; see section <A HREF="library.html#SEC186">Interrupt-Driven Input</A>.  You must
also establish a handler for this signal, as described in section <A HREF="library.html#SEC330">Signal Handling</A>, in order to take appropriate action such as reading the
out-of-band data.
<P>
Alternatively, you can test for pending out-of-band data, or wait
until there is out-of-band data, using the <CODE>select</CODE> function; it
can wait for an exceptional condition on the socket.  See section <A HREF="library.html#SEC180">Waiting for Input or Output</A>, for more information about <CODE>select</CODE>.
<P>
Notification of out-of-band data (whether with <CODE>SIGURG</CODE> or with
<CODE>select</CODE>) indicates that out-of-band data is on the way; the data
may not actually arrive until later.  If you try to read the
out-of-band data before it arrives, <CODE>recv</CODE> fails with an
<CODE>EWOULDBLOCK</CODE> error.
<P>
Sending out-of-band data automatically places a "mark" in the stream
of ordinary data, showing where in the sequence the out-of-band data
"would have been".  This is useful when the meaning of out-of-band
data is "cancel everything sent so far".  Here is how you can test,
in the receiving process, whether any ordinary data was sent before
the mark:
<P>
<PRE>
success = ioctl (socket, SIOCATMARK, &#38;result);
</PRE>
<P>
Here's a function to discard any ordinary data preceding the
out-of-band mark:
<P>
<PRE>
int
discard_until_mark (int socket)
{
  while (1)
    {
      /* This is not an arbitrary limit; any size will do.  */
      char buffer[1024];
      int result, success;

      /* If we have reached the mark, return.  */
      success = ioctl (socket, SIOCATMARK, &#38;result);
      if (success &#60; 0)
        perror ("ioctl");
      if (result)
        return;

      /* Otherwise, read a bunch of ordinary data and discard it.
         This is guaranteed not to read past the mark
         if it starts before the mark.  */
      success = read (socket, buffer, sizeof buffer);
      if (success &#60; 0)
        perror ("read");
    }
}
</PRE>
<P>
If you don't want to discard the ordinary data preceding the mark, you
may need to read some of it anyway, to make room in internal system
buffers for the out-of-band data.  If you try to read out-of-band data
and get an <CODE>EWOULDBLOCK</CODE> error, try reading some ordinary data
(saving it so that you can use it when you want it) and see if that
makes room.  Here is an example:
<P>
<PRE>
struct buffer
{
  char *buffer;
  int size;
  struct buffer *next;
};

/* Read the out-of-band data from SOCKET and return it
   as a `struct buffer', which records the address of the data
   and its size.

   It may be necessary to read some ordinary data
   in order to make room for the out-of-band data.
   If so, the ordinary data is saved as a chain of buffers
   found in the `next' field of the value.  */

struct buffer *
read_oob (int socket)
{
  struct buffer *tail = 0;
  struct buffer *list = 0;

  while (1)
    {
      /* This is an arbitrary limit.
         Does anyone know how to do this without a limit?  */
      char *buffer = (char *) xmalloc (1024);
      struct buffer *link;
      int success;
      int result;

      /* Try again to read the out-of-band data.  */
      success = recv (socket, buffer, sizeof buffer, MSG_OOB);
      if (success &#62;= 0)
        {
          /* We got it, so return it.  */
          struct buffer *link
            = (struct buffer *) xmalloc (sizeof (struct buffer));
          link-&#62;buffer = buffer;
          link-&#62;size = success;
          link-&#62;next = list;
          return link;
        }

      /* If we fail, see if we are at the mark.  */
      success = ioctl (socket, SIOCATMARK, &#38;result);
      if (success &#60; 0)
        perror ("ioctl");
      if (result)
        {
          /* At the mark; skipping past more ordinary data cannot help.
             So just wait a while.  */
          sleep (1);
          continue;
        }

      /* Otherwise, read a bunch of ordinary data and save it.
         This is guaranteed not to read past the mark
         if it starts before the mark.  */
      success = read (socket, buffer, sizeof buffer);
      if (success &#60; 0)
        perror ("read");

      /* Save this data in the buffer list.  */
      {
        struct buffer *link
          = (struct buffer *) xmalloc (sizeof (struct buffer));
        link-&#62;buffer = buffer;
        link-&#62;size = success;

        /* Add the new link to the end of the list.  */
        if (tail)
          tail-&#62;next = link;
        else
          list = link;
        tail = link;
      }
    }
}
</PRE>
<P>
<H2><A NAME="SEC256" HREF="library_toc.html#SEC256">Datagram Socket Operations</A></H2>
<A NAME="IDX1052"></A>
<P>
This section describes how to use communication styles that don't use
connections (styles <CODE>SOCK_DGRAM</CODE> and <CODE>SOCK_RDM</CODE>).  Using
these styles, you group data into packets and each packet is an
independent communication.  You specify the destination for each
packet individually.
<P>
Datagram packets are like letters: you send each one independently,
with its own destination address, and they may arrive in the wrong
order or not at all.
<P>
The <CODE>listen</CODE> and <CODE>accept</CODE> functions are not allowed for
sockets using connectionless communication styles.
<P>
<A NAME="IDX1053"></A>
<A NAME="IDX1054"></A>
<A NAME="IDX1055"></A>
<H3><A NAME="SEC257" HREF="library_toc.html#SEC257">Sending Datagrams</A></H3>
<A NAME="IDX1056"></A>
<P>
The normal way of sending data on a datagram socket is by using the
<CODE>sendto</CODE> function, declared in <TT>`sys/socket.h'</TT>.
<P>
You can call <CODE>connect</CODE> on a datagram socket, but this only
specifies a default destination for further data transmission on the
socket.  When a socket has a default destination, then you can use
<CODE>send</CODE> (see section <A HREF="library.html#SEC250">Sending Data</A>) or even <CODE>write</CODE> (see section <A HREF="library.html#SEC173">Input and Output Primitives</A>) to send a packet there.  You can cancel the default
destination by calling <CODE>connect</CODE> using an address format of
<CODE>AF_UNSPEC</CODE> in the <VAR>addr</VAR> argument.  See section <A HREF="library.html#SEC245">Making a Connection</A>, for
more information about the <CODE>connect</CODE> function.
<P>
<A NAME="IDX1057"></A>
<U>Function:</U> int <B>sendto</B> <I>(int <VAR>socket</VAR>, void *<VAR>buffer</VAR>. size_t <VAR>size</VAR>, int <VAR>flags</VAR>, struct sockaddr *<VAR>addr</VAR>, size_t <VAR>length</VAR>)</I><P>
The <CODE>sendto</CODE> function transmits the data in the <VAR>buffer</VAR>
through the socket <VAR>socket</VAR> to the destination address specified
by the <VAR>addr</VAR> and <VAR>length</VAR> arguments.  The <VAR>size</VAR> argument
specifies the number of bytes to be transmitted.
<P>
The <VAR>flags</VAR> are interpreted the same way as for <CODE>send</CODE>; see
section <A HREF="library.html#SEC252">Socket Data Options</A>.
<P>
The return value and error conditions are also the same as for
<CODE>send</CODE>, but you cannot rely on the system to detect errors and
report them; the most common error is that the packet is lost or there
is no one at the specified address to receive it, and the operating
system on your machine usually does not know this.
<P>
It is also possible for one call to <CODE>sendto</CODE> to report an error
due to a problem related to a previous call.
<P>
<A NAME="IDX1058"></A>
<H3><A NAME="SEC258" HREF="library_toc.html#SEC258">Receiving Datagrams</A></H3>
<P>
The <CODE>recvfrom</CODE> function reads a packet from a datagram socket and
also tells you where it was sent from.  This function is declared in
<TT>`sys/socket.h'</TT>.
<P>
<A NAME="IDX1059"></A>
<U>Function:</U> int <B>recvfrom</B> <I>(int <VAR>socket</VAR>, void *<VAR>buffer</VAR>, size_t <VAR>size</VAR>, int <VAR>flags</VAR>, struct sockaddr *<VAR>addr</VAR>, size_t *<VAR>length_ptr</VAR>)</I><P>
The <CODE>recvfrom</CODE> function reads one packet from the socket
<VAR>socket</VAR> into the buffer <VAR>buffer</VAR>.  The <VAR>size</VAR> argument
specifies the maximum number of bytes to be read.
<P>
If the packet is longer than <VAR>size</VAR> bytes, then you get the first
<VAR>size</VAR> bytes of the packet, and the rest of the packet is lost.
There's no way to read the rest of the packet.  Thus, when you use a
packet protocol, you must always know how long a packet to expect.
<P>
The <VAR>addr</VAR> and <VAR>length_ptr</VAR> arguments are used to return the
address where the packet came from.  See section <A HREF="library.html#SEC219">Socket Addresses</A>.  For a
socket in the file domain, the address information won't be meaningful,
since you can't read the address of such a socket (see section <A HREF="library.html#SEC223">The File Namespace</A>).  You can specify a null pointer as the <VAR>addr</VAR> argument
if you are not interested in this information.
<P>
The <VAR>flags</VAR> are interpreted the same way as for <CODE>recv</CODE>
(see section <A HREF="library.html#SEC252">Socket Data Options</A>).  The return value and error conditions
are also the same as for <CODE>recv</CODE>.
<P>
You can use plain <CODE>recv</CODE> (see section <A HREF="library.html#SEC251">Receiving Data</A>) instead of
<CODE>recvfrom</CODE> if you know don't need to find out who sent the packet
(either because you know where it should come from or because you
treat all possible senders alike).  Even <CODE>read</CODE> can be used if
you don't want to specify <VAR>flags</VAR> (see section <A HREF="library.html#SEC173">Input and Output Primitives</A>).
<P>
<H3><A NAME="SEC259" HREF="library_toc.html#SEC259">Datagram Socket Example</A></H3>
<P>
Here is a set of example programs that send messages over a datagram
stream in the file namespace.  Both the client and server programs use the
<CODE>make_named_socket</CODE> function that was presented in section <A HREF="library.html#SEC223">The File Namespace</A>, to create and name their sockets.
<P>
First, here is the server program.  It sits in a loop waiting for
messages to arrive, bouncing each message back to the sender.
Obviously, this isn't a particularly useful program, but it does show
the general ideas involved.
<P>
<PRE>
#include &#60;stdio.h&#62;
#include &#60;errno.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;sys/socket.h&#62;
#include &#60;sys/un.h&#62;

#define SERVER	"/tmp/serversocket"
#define MAXMSG	512

int
main (void)
{
  int sock;
  char message[MAXMSG];
  struct sockaddr_un name;
  size_t size;
  int nbytes;

  /* Make the socket, then loop endlessly.  */

  sock = make_named_socket (SERVER);
  while (1)
    {
      /* Wait for a datagram.  */
      size = sizeof (name);
      nbytes = recvfrom (sock, message, MAXMSG, 0,
			 (struct sockaddr *) &#38; name, &#38;size);
      if (nbytes &#60; 0)
	{
	  perror ("recfrom (server)");
	  exit (EXIT_FAILURE);
	}

      /* Give a diagnostic message.  */
      fprintf (stderr, "Server: got message: %s\n", message);

      /* Bounce the message back to the sender.  */
      nbytes = sendto (sock, message, nbytes, 0,
		       (struct sockaddr *) &#38; name, size);
      if (nbytes &#60; 0)
	{
	  perror ("sendto (server)");
	  exit (EXIT_FAILURE);
	}
    }
}
</PRE>
<P>
<H3><A NAME="SEC260" HREF="library_toc.html#SEC260">Example of Reading Datagrams</A></H3>
<P>
Here is the client program corresponding to the server above.
<P>
It sends a datagram to the server and then waits for a reply.  Notice
that the socket for the client (as well as for the server) in this
example has to be given a name.  This is so that the server can direct
a message back to the client.  Since the socket has no associated
connection state, the only way the server can do this is by
referencing the name of the client.
<P>
<PRE>
#include &#60;stdio.h&#62;
#include &#60;errno.h&#62;
#include &#60;unistd.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;sys/socket.h&#62;
#include &#60;sys/un.h&#62;

#define SERVER	"/tmp/serversocket"
#define CLIENT	"/tmp/mysocket"
#define MAXMSG	512
#define MESSAGE	"Yow!!! Are we having fun yet?!?"

int
main (void)
{
  extern int make_named_socket (const char *name);
  int sock;
  char message[MAXMSG];
  struct sockaddr_un name;
  size_t size;
  int nbytes;

  /* Make the socket.  */
  sock = make_named_socket (CLIENT);

  /* Initialize the server socket address.  */
  name.sun_family = AF_UNIX;
  strcpy (name.sun_path, SERVER);
  size = strlen (name.sun_path) + sizeof (name.sun_family);

  /* Send the datagram.  */
  nbytes = sendto (sock, MESSAGE, strlen (MESSAGE) + 1, 0,
		   (struct sockaddr *) &#38; name, size);
  if (nbytes &#60; 0)
    {
      perror ("sendto (client)");
      exit (EXIT_FAILURE);
    }

  /* Wait for a reply.  */
  nbytes = recvfrom (sock, message, MAXMSG, 0, NULL, 0);
  if (nbytes &#60; 0)
    {
      perror ("recfrom (client)");
      exit (EXIT_FAILURE);
    }

  /* Print a diagnostic message.  */
  fprintf (stderr, "Client: got message: %s\n", message);

  /* Clean up.  */
  remove (CLIENT);
  close (sock);
}
</PRE>
<P>
Keep in mind that datagram socket communications are unreliable.  In
this example, the client program waits indefinitely if the message
never reaches the server or if the server's response never comes
back.  It's up to the user running the program to kill it and restart
it, if desired.  A more automatic solution could be to use
<CODE>select</CODE> (see section <A HREF="library.html#SEC180">Waiting for Input or Output</A>) to establish a timeout period
for the reply, and in case of timeout either resend the message or
shut down the socket and exit.
<P>
<H2><A NAME="SEC261" HREF="library_toc.html#SEC261">The <CODE>inetd</CODE> Daemon</A></H2>
<P>
We've explained above how to write a server program that does its own
listening.  Such a server must already be running in order for anyone
to connect to it.
<P>
Another way to provide service for an Internet port is to let the daemon
program <CODE>inetd</CODE> do the listening.  <CODE>inetd</CODE> is a program that
runs all the time and waits (using <CODE>select</CODE>) for messages on a
specified set of ports.  When it receives a message, it accepts the
connection (if the socket style calls for connections) and then forks a
child process to run the corresponding server program.  You specify the
ports and their programs in the file <TT>`/etc/inetd.conf'</TT>.
<P>
<H3><A NAME="SEC262" HREF="library_toc.html#SEC262"><CODE>inetd</CODE> Servers</A></H3>
<P>
Writing a server program to be run by <CODE>inetd</CODE> is very simple.  Each time
someone requests a connection to the appropriate port, a new server
process starts.  The connection already exists at this time; the
socket is available as the standard input descriptor and as the
standard output descriptor (descriptors 0 and 1) in the server
process.  So the server program can begin reading and writing data
right away.  Often the program needs only the ordinary I/O facilities;
in fact, a general-purpose filter program that knows nothing about
sockets can work as a byte stream server run by <CODE>inetd</CODE>.
<P>
You can also use <CODE>inetd</CODE> for servers that use connectionless
communication styles.  For these servers, <CODE>inetd</CODE> does not try to accept
a connection, since no connection is possible.  It just starts the
server program, which can read the incoming datagram packet from
descriptor 0.  The server program can handle one request and then
exit, or you can choose to write it to keep reading more requests
until no more arrive, and then exit.  You must specify which of these
two techniques the server uses, when you configure <CODE>inetd</CODE>.
<P>
<H3><A NAME="SEC263" HREF="library_toc.html#SEC263">Configuring <CODE>inetd</CODE></A></H3>
<P>
The file <TT>`/etc/inetd.conf'</TT> tells <CODE>inetd</CODE> which ports to listen to
and what server programs to run for them.  Normally each entry in the
file is one line, but you can split it onto multiple lines provided
all but the first line of the entry start with whitespace.  Lines that
start with <SAMP>`#'</SAMP> are comments.
<P>
Here are two standard entries in <TT>`/etc/inetd.conf'</TT>:
<P>
<PRE>
ftp	stream	tcp	nowait	root	/libexec/ftpd	ftpd
talk	dgram	udp	wait	root	/libexec/talkd	talkd
</PRE>
<P>
An entry has this format:
<P>
<PRE>
<VAR>service</VAR> <VAR>style</VAR> <VAR>protocol</VAR> <VAR>wait</VAR> <VAR>username</VAR> <VAR>program</VAR> <VAR>arguments</VAR>
</PRE>
<P>
The <VAR>service</VAR> field says which service this program provides.  It
should be the name of a service defined in <TT>`/etc/services'</TT>.
<CODE>inetd</CODE> uses <VAR>service</VAR> to decide which port to listen on for
this entry.
<P>
The fields <VAR>style</VAR> and <VAR>protocol</VAR> specify the communication
style and the protocol to use for the listening socket.  The style
should be the name of a communication style, converted to lower case
and with <SAMP>`SOCK_'</SAMP> deleted--for example, <SAMP>`stream'</SAMP> or
<SAMP>`dgram'</SAMP>.  <VAR>protocol</VAR> should be one of the protocols listed in
<TT>`/etc/protocols'</TT>.  The typical protocol names are <SAMP>`tcp'</SAMP> for
byte stream connections and <SAMP>`udp'</SAMP> for unreliable datagrams.
<P>
The <VAR>wait</VAR> field should be either <SAMP>`wait'</SAMP> or <SAMP>`nowait'</SAMP>.
Use <SAMP>`wait'</SAMP> if <VAR>style</VAR> is a connectionless style and the
server, once started, handles multiple requests, as many as come in.
Use <SAMP>`nowait'</SAMP> if <CODE>inetd</CODE> should start a new process for each message
or request that comes in.  If <VAR>style</VAR> uses connections, then
<VAR>wait</VAR> <STRONG>must</STRONG> be <SAMP>`nowait'</SAMP>.
<P>
<VAR>user</VAR> is the user name that the server should run as.  <CODE>inetd</CODE> runs
as root, so it can set the user ID of its children arbitrarily.  It's
best to avoid using <SAMP>`root'</SAMP> for <VAR>user</VAR> if you can; but some
servers, such as Telnet and FTP, read a username and password
themselves.  These servers need to be root initially so they can log
in as commanded by the data coming over the network.
<P>
<VAR>program</VAR> together with <VAR>arguments</VAR> specifies the command to
run to start the server.  <VAR>program</VAR> should be an absolute file
name specifying the executable file to run.  <VAR>arguments</VAR> consists
of any number of whitespace-separated words, which become the
command-line arguments of <VAR>program</VAR>.  The first word in
<VAR>arguments</VAR> is argument zero, which should by convention be the
program name itself (sans directories).
<P>
If you edit <TT>`/etc/inetd.conf'</TT>, you can tell <CODE>inetd</CODE> to reread the
file and obey its new contents by sending the <CODE>inetd</CODE> process the
<CODE>SIGHUP</CODE> signal.  You'll have to use <CODE>ps</CODE> to determine the
process ID of the <CODE>inetd</CODE> process, as it is not fixed.
<P>
<A NAME="IDX1060"></A>
<H2><A NAME="SEC264" HREF="library_toc.html#SEC264">Socket Options</A></H2>
<P>
This section describes how to read or set various options that modify
the behavior of sockets and their underlying communications protocols.
<A NAME="IDX1061"></A>
<A NAME="IDX1062"></A>
<P>
When you are manipulating a socket option, you must specify which
<DFN>level</DFN> the option pertains to.  This describes whether the option
applies to the socket interface, or to a lower-level communications
protocol interface.
<P>
<H3><A NAME="SEC265" HREF="library_toc.html#SEC265">Socket Option Functions</A></H3>
<A NAME="IDX1063"></A>
<P>
Here are the functions for examining and modifying socket options.
They are declared in <TT>`sys/socket.h'</TT>.
<P>
<A NAME="IDX1064"></A>
<U>Function:</U> int <B>getsockopt</B> <I>(int <VAR>socket</VAR>, int <VAR>level</VAR>, int <VAR>optname</VAR>, void *<VAR>optval</VAR>, size_t *<VAR>optlen_ptr</VAR>)</I><P>
The <CODE>getsockopt</CODE> function gets information about the value of
option <VAR>optname</VAR> at level <VAR>level</VAR> for socket <VAR>socket</VAR>.
<P>
The option value is stored in a buffer that <VAR>optval</VAR> points to.
Before the call, you should supply in <CODE>*<VAR>optlen_ptr</VAR></CODE> the
size of this buffer; on return, it contains the number of bytes of
information actually stored in the buffer.
<P>
Most options interpret the <VAR>optval</VAR> buffer as a single <CODE>int</CODE>
value.
<P>
The actual return value of <CODE>getsockopt</CODE> is <CODE>0</CODE> on success
and <CODE>-1</CODE> on failure.  The following <CODE>errno</CODE> error conditions
are defined:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>socket</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>ENOTSOCK</CODE>
<DD>The descriptor <VAR>socket</VAR> is not a socket.
<P>
<DT><CODE>ENOPROTOOPT</CODE>
<DD>The <VAR>optname</VAR> doesn't make sense for the given <VAR>level</VAR>.
</DL>
<P>
<A NAME="IDX1065"></A>
<U>Function:</U> int <B>setsockopt</B> <I>(int <VAR>socket</VAR>, int <VAR>level</VAR>, int <VAR>optname</VAR>, void *<VAR>optval</VAR>, size_t <VAR>optlen</VAR>)</I><P>
This function is used to set the socket option <VAR>optname</VAR> at level
<VAR>level</VAR> for socket <VAR>socket</VAR>.  The value of the option is passed
in the buffer <VAR>optval</VAR>, which has size <VAR>optlen</VAR>.
<P>
The return value and error codes are the same as for <CODE>getsockopt</CODE>.
<P>
<H3><A NAME="SEC266" HREF="library_toc.html#SEC266">Socket-Level Options</A></H3>
<P>
<A NAME="IDX1066"></A>
<U>Constant:</U> int <B>SOL_SOCKET</B><P>
Use this constant as the <VAR>level</VAR> argument to <CODE>getsockopt</CODE> or
<CODE>setsockopt</CODE> to manipulate the socket-level options described in
this section.
<P>
<A NAME="IDX1067"></A>
<P>
Here is a table of socket-level option names; all are defined in the
header file <TT>`sys/socket.h'</TT>.
<P>
<DL COMPACT>
<DT><CODE>SO_DEBUG</CODE>
<DD><P>
This option toggles recording of debugging information in the underlying
protocol modules.  The value has type <CODE>int</CODE>; a nonzero value means
"yes".
<P>
<DT><CODE>SO_REUSEADDR</CODE>
<DD>This option controls whether <CODE>bind</CODE> (see section <A HREF="library.html#SEC221">Setting a Socket's Address</A>)
should permit reuse of local addresses for this socket.  If you enable
this option, you can actually have two sockets with the same Internet
port number; but the system won't allow you to use the two
identically-named sockets in a way that would confuse the Internet.  The
reason for this option is that some higher-level Internet protocols,
including FTP, require you to keep reusing the same socket number.
<P>
The value has type <CODE>int</CODE>; a nonzero value means "yes".
<P>
<DT><CODE>SO_KEEPALIVE</CODE>
<DD>This option controls whether the underlying protocol should
periodically transmit messages on a connected socket.  If the peer
fails to respond to these messages, the connection is considered
broken.  The value has type <CODE>int</CODE>; a nonzero value means
"yes".
<P>
<DT><CODE>SO_DONTROUTE</CODE>
<DD>This option controls whether outgoing messages bypass the normal
message routing facilities.  If set, messages are sent directly to the
network interface instead.  The value has type <CODE>int</CODE>; a nonzero
value means "yes".
<P>
<DT><CODE>SO_LINGER</CODE>
<DD>This option specifies what should happen when the socket of a type
that promises reliable delivery still has untransmitted messages when
it is closed; see section <A HREF="library.html#SEC242">Closing a Socket</A>.  The value has type
<CODE>struct linger</CODE>.
<P>
<A NAME="IDX1068"></A>
<U>Data Type:</U> <B>struct linger</B><P>
This structure type has the following members:
<P>
<DL COMPACT>
<DT><CODE>int l_onoff</CODE>
<DD>This field is interpreted as a boolean.  If nonzero, <CODE>close</CODE>
blocks until the data is transmitted or the timeout period has expired.
<P>
<DT><CODE>int l_linger</CODE>
<DD>This specifies the timeout period, in seconds.
</DL>
<P>
<LI>SO_BROADCAST
This option controls whether datagrams may be broadcast from the socket.
The value has type <CODE>int</CODE>; a nonzero value means "yes".
<P>
<LI>SO_OOBINLINE
If this option is set, out-of-band data received on the socket is
placed in the normal input queue.  This permits it to be read using
<CODE>read</CODE> or <CODE>recv</CODE> without specifying the <CODE>MSG_OOB</CODE>
flag.  See section <A HREF="library.html#SEC255">Out-of-Band Data</A>.  The value has type <CODE>int</CODE>; a
nonzero value means "yes".
<P>
<LI>SO_SNDBUF
This option gets or sets the size of the output buffer.  The value is an
<CODE>size_t</CODE>, which is the size in bytes.
<P>
<LI>SO_RCVBUF
This option gets or sets the size of the input buffer.  The value is an
<CODE>size_t</CODE>, which is the size in bytes.
<P>
<LI>SO_STYLE
<LI>SO_TYPE
This option can be used with <CODE>getsockopt</CODE> only.  It is used to
get the socket's communication style.  <CODE>SO_TYPE</CODE> is the
historical name, and <CODE>SO_STYLE</CODE> is the preferred name in GNU.
The value has type <CODE>int</CODE> and its value designates a communication
style; see section <A HREF="library.html#SEC218">Communication Styles</A>.
<P>
<LI>SO_ERROR
<P>
This option can be used with <CODE>getsockopt</CODE> only.  It is used to reset
the error status of the socket.  The value is an <CODE>int</CODE>, which represents
the previous error status.
</DL>
<P>
<A NAME="IDX1069"></A>
<A NAME="IDX1070"></A>
<A NAME="IDX1071"></A>
<H2><A NAME="SEC267" HREF="library_toc.html#SEC267">Networks Database</A></H2>
<A NAME="IDX1072"></A>
<A NAME="IDX1073"></A>
<P>
Many systems come with a database that records a list of networks known
to the system developer.  This is usually kept either in the file
<TT>`/etc/networks'</TT> or in an equivalent from a name server.  This data
base is useful for routing programs such as <CODE>route</CODE>, but it is not
useful for programs that simply communicate over the network.  We
provide functions to access this data base, which are declared in
<TT>`netdb.h'</TT>.
<P>
<A NAME="IDX1074"></A>
<U>Data Type:</U> <B>struct netent</B><P>
This data type is used to represent information about entries in the
networks database.  It has the following members:
<P>
<DL COMPACT>
<DT><CODE>char *n_name</CODE>
<DD>This is the "official" name of the network.
<P>
<DT><CODE>char **n_aliases</CODE>
<DD>These are alternative names for the network, represented as a vector
of strings.  A null pointer terminates the array.
<P>
<DT><CODE>int n_addrtype</CODE>
<DD>This is the type of the network number; this is always equal to
<CODE>AF_INET</CODE> for Internet networks.
<P>
<DT><CODE>unsigned long int n_net</CODE>
<DD>This is the network number.  Network numbers are returned in host
byte order; see section <A HREF="library.html#SEC236">Byte Order Conversion</A>.
</DL>
<P>
Use the <CODE>getnetbyname</CODE> or <CODE>getnetbyaddr</CODE> functions to search
the networks database for information about a specific network.  The
information is returned in a statically-allocated structure; you must
copy the information if you need to save it.
<P>
<A NAME="IDX1075"></A>
<U>Function:</U> struct netent * <B>getnetbyname</B> <I>(const char *<VAR>name</VAR>)</I><P>
The <CODE>getnetbyname</CODE> function returns information about the network
named <VAR>name</VAR>.  It returns a null pointer if there is no such
network.
<P>
<A NAME="IDX1076"></A>
<U>Function:</U> struct netent * <B>getnetbyaddr</B> <I>(long <VAR>net</VAR>, int <VAR>type</VAR>)</I><P>
The <CODE>getnetbyaddr</CODE> function returns information about the network
of type <VAR>type</VAR> with number <VAR>net</VAR>.  You should specify a value of
<CODE>AF_INET</CODE> for the <VAR>type</VAR> argument for Internet networks.  
<P>
<CODE>getnetbyaddr</CODE> returns a null pointer if there is no such
network.
<P>
You can also scan the networks database using <CODE>setnetent</CODE>,
<CODE>getnetent</CODE>, and <CODE>endnetent</CODE>.  Be careful in using these
functions, because they are not reentrant.
<P>
<A NAME="IDX1077"></A>
<U>Function:</U> void <B>setnetent</B> <I>(int <VAR>stayopen</VAR>)</I><P>
This function opens and rewinds the networks database.
<P>
If the <VAR>stayopen</VAR> argument is nonzero, this sets a flag so that
subsequent calls to <CODE>getnetbyname</CODE> or <CODE>getnetbyaddr</CODE> will
not close the database (as they usually would).  This makes for more
efficiency if you call those functions several times, by avoiding
reopening the database for each call.
<P>
<A NAME="IDX1078"></A>
<U>Function:</U> struct netent * <B>getnetent</B> <I>(void)</I><P>
This function returns the next entry in the networks database.  It
returns a null pointer if there are no more entries.
<P>
<A NAME="IDX1079"></A>
<U>Function:</U> void <B>endnetent</B> <I>(void)</I><P>
This function closes the networks database.
<P>
<H1><A NAME="SEC268" HREF="library_toc.html#SEC268">Low-Level Terminal Interface</A></H1>
<P>
This chapter describes functions that are specific to terminal devices.
You can use these functions to do things like turn off input echoing;
set serial line characteristics such as line speed and flow control; and
change which characters are used for end-of-file, command-line editing,
sending signals, and similar control functions.
<P>
Most of the functions in this chapter operate on file descriptors.
See section <A HREF="library.html#SEC171">Low-Level Input/Output</A>, for more information about what a file
descriptor is and how to open a file descriptor for a terminal device.
<P>
<A NAME="IDX1080"></A>
<A NAME="IDX1081"></A>
<H2><A NAME="SEC269" HREF="library_toc.html#SEC269">Identifying Terminals</A></H2>
<P>
The functions described in this chapter only work on files that
correspond to terminal devices.  You can find out whether a file
descriptor is associated with a terminal by using the <CODE>isatty</CODE>
function.
<A NAME="IDX1082"></A>
<P>
Prototypes for both <CODE>isatty</CODE> and <CODE>ttyname</CODE> are declared in
the header file <TT>`unistd.h'</TT>.
<P>
<A NAME="IDX1083"></A>
<U>Function:</U> int <B>isatty</B> <I>(int <VAR>filedes</VAR>)</I><P>
This function returns <CODE>1</CODE> if <VAR>filedes</VAR> is a file descriptor
associated with an open terminal device, and <CODE>0</CODE> otherwise.
<P>
If a file descriptor is associated with a terminal, you can get its
associated file name using the <CODE>ttyname</CODE> function.  See also the
<CODE>ctermid</CODE> function, described in section <A HREF="library.html#SEC426">Identifying the Controlling Terminal</A>.
<P>
<A NAME="IDX1084"></A>
<U>Function:</U> char * <B>ttyname</B> <I>(int <VAR>filedes</VAR>)</I><P>
If the file descriptor <VAR>filedes</VAR> is associated with a terminal
device, the <CODE>ttyname</CODE> function returns a pointer to a
statically-allocated, null-terminated string containing the file name of
the terminal file.  The value is a null pointer if the file descriptor
isn't associated with a terminal, or the file name cannot be determined.
<P>
<H2><A NAME="SEC270" HREF="library_toc.html#SEC270">I/O Queues</A></H2>
<P>
Many of the remaining functions in this section refer to the input and
output queues of a terminal device.  These queues implement a form of
buffering <EM>within the kernel</EM> independent of the buffering
implemented by I/O streams (see section <A HREF="library.html#SEC117">Input/Output on Streams</A>).
<A NAME="IDX1085"></A>
<A NAME="IDX1086"></A>
<P>
The <DFN>terminal input queue</DFN> is also sometimes referred to as its
<DFN>typeahead buffer</DFN>.  It holds the characters that have been received
from the terminal but not yet read by any process.
<P>
The size of the terminal's input queue is described by the
<CODE>_POSIX_MAX_INPUT</CODE> and <CODE>MAX_INPUT</CODE> parameters; see section <A HREF="library.html#SEC463">Limits on File System Capacity</A>.  If input flow control is enabled by setting the
<CODE>IXOFF</CODE> input mode bit (see section <A HREF="library.html#SEC276">Input Modes</A>), the terminal driver
transmits STOP and START characters to the terminal when necessary to
prevent the queue from overflowing.  Otherwise, input may be lost if it
comes in too fast from the terminal.  (This is unlikely if you are
typing the input by hand!)
<A NAME="IDX1087"></A>
<P>
The <DFN>terminal output queue</DFN> is like the input queue, but for output;
it contains characters that have been written by processes, but not yet
transmitted to the terminal.  If output flow control is enabled by
setting the <CODE>IXON</CODE> input mode bit (see section <A HREF="library.html#SEC276">Input Modes</A>), the
terminal driver obeys STOP and STOP characters sent by the terminal to
stop and restart transmission of output.
<P>
<DFN>Clearing</DFN> the terminal input queue means discarding any characters
that have been received but not yet read.  Similarly, clearing the
terminal output queue means discarding any characters that have been
written but not yet transmitted.
<P>
<H2><A NAME="SEC271" HREF="library_toc.html#SEC271">Two Styles of Input: Canonical or Not</A></H2>
<P>
POSIX systems support two basic modes of input: canonical and
noncanonical.
<A NAME="IDX1088"></A>
<P>
In <DFN>canonical input processing</DFN> mode, terminal input is processed in
lines terminated by newline (<CODE>'\n'</CODE>), EOF, or EOL characters.  No
input can be read until an entire line has been typed by the user, and
the <CODE>read</CODE> function (see section <A HREF="library.html#SEC173">Input and Output Primitives</A>) returns at most a
single line of input, no matter how many bytes are requested.
<P>
In canonical input mode, the operating system provides input editing
facilities: the ERASE and KILL characters are interpreted specially to
perform editing operations within the current line of text.
See section <A HREF="library.html#SEC282">Characters for Input Editing</A>.
<P>
The constants <CODE>_POSIX_MAX_CANON</CODE> and <CODE>MAX_CANON</CODE> parameterize
the maximum number of bytes which may appear in a single line of
canonical input.  See section <A HREF="library.html#SEC463">Limits on File System Capacity</A>.
<A NAME="IDX1089"></A>
<P>
In <DFN>noncanonical input processing</DFN> mode, characters are not grouped
into lines, and ERASE and KILL processing is not performed.  The
granularity with which bytes are read in noncanonical input mode is
controlled by the MIN and TIME settings.  See section <A HREF="library.html#SEC287">Noncanonical Input</A>.
<P>
Most programs use canonical input mode, because this gives the user a
way to edit input line by line.  The usual reason to use noncanonical
mode is when the program accepts single-character commands or provides
its own editing facilities.
<P>
The choice of canonical or noncanonical input is controlled by the
<CODE>ICANON</CODE> flag in the <CODE>c_lflag</CODE> member of <CODE>struct termios</CODE>.
See section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<H2><A NAME="SEC272" HREF="library_toc.html#SEC272">Terminal Modes</A></H2>
<A NAME="IDX1090"></A>
<P>
This section describes the various terminal attributes that control how
input and output are done.  The functions, data structures, and symbolic
constants are all declared in the header file <TT>`termios.h'</TT>.
<P>
<A NAME="IDX1091"></A>
<H3><A NAME="SEC273" HREF="library_toc.html#SEC273">Terminal Mode Data Types</A></H3>
<P>
The entire collection of attributes of a terminal is stored in a
structure of type <CODE>struct termios</CODE>.  This structure is used
with the functions <CODE>tcgetattr</CODE> and <CODE>tcsetattr</CODE> to read
and set the attributes.
<P>
<A NAME="IDX1092"></A>
<U>Data Type:</U> <B>struct termios</B><P>
Structure that records all the I/O attributes of a terminal.  The
structure includes at least the following members:
<P>
<DL COMPACT>
<DT><CODE>tcflag_t c_iflag</CODE>
<DD>A bit mask specifying input modes; see section <A HREF="library.html#SEC276">Input Modes</A>.
<P>
<DT><CODE>tcflag_t c_oflag</CODE>
<DD>A bit mask specifying output modes; see section <A HREF="library.html#SEC277">Output Modes</A>.
<P>
<DT><CODE>tcflag_t c_cflag</CODE>
<DD>A bit mask specifying control modes; see section <A HREF="library.html#SEC278">Control Modes</A>.
<P>
<DT><CODE>tcflag_t c_lflag</CODE>
<DD>A bit mask specifying flags for local modes; see section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>cc_t c_cc[NCCS]</CODE>
<DD>An array specifying which characters are associated with various
control functions; see section <A HREF="library.html#SEC281">Special Characters</A>.
</DL>
<P>
The <CODE>struct termios</CODE> structure also contains members which
encode input and output transmission speeds, but the representation is
not specified.  See section <A HREF="library.html#SEC280">Line Speed</A>, for how to examine and store the
speed values.
<P>
The following sections describe the details of the members of the
<CODE>struct termios</CODE> structure.
<P>
<A NAME="IDX1093"></A>
<U>Data Type:</U> <B>tcflag_t</B><P>
This is an unsigned integer type used to represent the various
bit masks for terminal flags.
<P>
<A NAME="IDX1094"></A>
<U>Data Type:</U> <B>cc_t</B><P>
This is an unsigned integer type used to represent characters associated
with various terminal control functions.
<P>
<A NAME="IDX1095"></A>
<U>Macro:</U> int <B>NCCS</B><P>
The value of this macro is the number of elements in the <CODE>c_cc</CODE>
array.
<P>
<A NAME="IDX1096"></A>
<H3><A NAME="SEC274" HREF="library_toc.html#SEC274">Terminal Mode Functions</A></H3>
<P>
<A NAME="IDX1097"></A>
<U>Function:</U> int <B>tcgetattr</B> <I>(int <VAR>filedes</VAR>, struct termios *<VAR>termios_p</VAR>)</I><P>
This function is used to examine the attributes of the terminal
device with file descriptor <VAR>filedes</VAR>.  The attributes are returned
in the structure that <VAR>termios_p</VAR> points to.
<P>
If successful, <CODE>tcgetattr</CODE> returns <CODE>0</CODE>.  A return value of <CODE>-1</CODE>
indicates an error.  The following <CODE>errno</CODE> error conditions are
defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>ENOTTY</CODE>
<DD>The <VAR>filedes</VAR> is not associated with a terminal.
</DL>
<P>
<A NAME="IDX1098"></A>
<U>Function:</U> int <B>tcsetattr</B> <I>(int <VAR>filedes</VAR>, int <VAR>when</VAR>, const struct termios *<VAR>termios_p</VAR>)</I><P>
This function sets the attributes of the terminal device with file
descriptor <VAR>filedes</VAR>.  The new attributes are taken from the
structure that <VAR>termios_p</VAR> points to.
<P>
The <VAR>when</VAR> argument specifies how to deal with input and output
already queued.  It can be one of the following values:
<P>
<DL COMPACT>
<A NAME="IDX1099"></A>
<DT><CODE>TCSANOW</CODE>
<DD>Make the change immediately.
<P>
<A NAME="IDX1100"></A>
<DT><CODE>TCSADRAIN</CODE>
<DD>Make the change after waiting until all queued output has been written.
You should usually use this option when changing parameters that affect
output.
<P>
<A NAME="IDX1101"></A>
<DT><CODE>TCSAFLUSH</CODE>
<DD>This is like <CODE>TCSADRAIN</CODE>, but also discards any queued input.
<P>
<A NAME="IDX1102"></A>
<DT><CODE>TCSASOFT</CODE>
<DD>This is a flag bit that you can add to any of the above alternatives.
Its meaning is to inhibit alteration of the state of the terminal
hardware.  It is a BSD extension; it has no effect on non-BSD systems.
</DL>
<P>
If this function is called from a background process on its controlling
terminal, normally all processes in the process group are sent a
<CODE>SIGTTOU</CODE> signal, in the same way as if the process were trying to
write to the terminal.  The exception is if the calling process itself
is ignoring or blocking <CODE>SIGTTOU</CODE> signals, in which case the
operation is performed and no signal is sent.  See section <A HREF="library.html#SEC411">Job Control</A>.
<P>
If successful, <CODE>tcsetattr</CODE> returns <CODE>0</CODE>.  A return value of
<CODE>-1</CODE> indicates an error.  The following <CODE>errno</CODE> error
conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>ENOTTY</CODE>
<DD>The <VAR>filedes</VAR> is not associated with a terminal.
<P>
<DT><CODE>EINVAL</CODE>
<DD>Either the value of the <CODE>when</CODE> argument is not valid, or there is
something wrong with the data in the <VAR>termios_p</VAR> argument.
</DL>
<P>
Although <CODE>tcgetattr</CODE> and <CODE>tcsetattr</CODE> specify the terminal
device with a file descriptor, the attributes are those of the terminal
device itself and not of the file descriptor.  This means that the
effects of changing terminal attributes are persistent; if another
process opens the terminal file later on, it will see the changed
attributes even though it doesn't have anything to do with the open file
descriptor you originally specified in changing the attributes.
<P>
Similarly, if a single process has multiple or duplicated file
descriptors for the same terminal device, changing the terminal
attributes affects input and output to all of these file
descriptors.  This means, for example, that you can't open one file
descriptor or stream to read from a terminal in the normal
line-buffered, echoed mode; and simultaneously have another file
descriptor for the same terminal that you use to read from it in
single-character, non-echoed mode.  Instead, you have to explicitly
switch the terminal back and forth between the two modes.
<P>
<H3><A NAME="SEC275" HREF="library_toc.html#SEC275">Setting Terminal Modes Properly</A></H3>
<P>
When you set terminal modes, you should call <CODE>tcgetattr</CODE> first to
get the current modes of the particular terminal device, modify only
those modes that you are really interested in, and store the result with
<CODE>tcsetattr</CODE>.
<P>
It's a bad idea to simply initialize a <CODE>struct termios</CODE> structure
to a chosen set of attributes and pass it directly to <CODE>tcsetattr</CODE>.
Your program may be run years from now, on systems that support members
not documented in this manual.  The way to avoid setting these members
to unreasonable values is to avoid changing them.
<P>
What's more, different terminal devices may require different mode
settings in order to function properly.  So you should avoid blindly
copying attributes from one terminal device to another.
<P>
When a member contains a collection of independent flags, as the
<CODE>c_iflag</CODE>, <CODE>c_oflag</CODE> and <CODE>c_cflag</CODE> members do, even
setting the entire member is a bad idea, because particular operating
systems have their own flags.  Instead, you should start with the
current value of the member and alter only the flags whose values matter
in your program, leaving any other flags unchanged.
<P>
Here is an example of how to set one flag (<CODE>ISTRIP</CODE>) in the
<CODE>struct termios</CODE> structure while properly preserving all the other
data in the structure:
<P>
<PRE>
int
set_istrip (int desc, int value)
{
  struct termios settings;
  int result;

  result = tcgetattr (desc, &#38;settings);
  if (result &#60; 0)
    {
      perror ("error in tcgetattr");
      return 0;
    }
  settings.c_iflag &#38;= ~ISTRIP;
  if (value)
    settings.c_iflag |= ISTRIP;
  result = tcgetattr (desc, &#38;settings);
  if (result &#60; 0)
    {
      perror ("error in tcgetattr");
      return;
   }
  return 1;
}
</PRE>
<P>
<H3><A NAME="SEC276" HREF="library_toc.html#SEC276">Input Modes</A></H3>
<P>
This section describes the terminal attribute flags that control
fairly low-level aspects of input processing: handling of parity errors,
break signals, flow control, and <KBD>RET</KBD> and <KBD>LFD</KBD> characters.
<P>
All of these flags are bits in the <CODE>c_iflag</CODE> member of the
<CODE>struct termios</CODE> structure.  The member is an integer, and you
change flags using the operators <CODE>&#38;</CODE>, <CODE>|</CODE> and <CODE>^</CODE>.  Don't
try to specify the entire value for <CODE>c_iflag</CODE>---instead, change
only specific flags and leave the rest untouched (see section <A HREF="library.html#SEC275">Setting Terminal Modes Properly</A>).
<P>
<A NAME="IDX1103"></A>
<DL COMPACT>
<A NAME="IDX1104"></A>
<DT><CODE>INPCK</CODE>
<DD>If this bit is set, input parity checking is enabled.  If it is not set,
no checking at all is done for parity errors on input; the
characters are simply passed through to the application.
<P>
Parity checking on input processing is independent of whether parity
detection and generation on the underlying terminal hardware is enabled;
see section <A HREF="library.html#SEC278">Control Modes</A>.  For example, you could clear the <CODE>INPCK</CODE>
input mode flag and set the <CODE>PARENB</CODE> control mode flag to ignore
parity errors on input, but still generate parity on output.
<P>
If this bit is set, what happens when a parity error is detected depends
on whether the <CODE>IGNPAR</CODE> or <CODE>PARMRK</CODE> bits are set.  If neither
of these bits are set, a byte with a parity error is passed to the
application as a <CODE>'\0'</CODE> character.
<A NAME="IDX1105"></A>
<P>
<DT><CODE>IGNPAR</CODE>
<DD>If this bit is set, any byte with a framing or parity error is ignored.
This is only useful if <CODE>INPCK</CODE> is also set.
<A NAME="IDX1106"></A>
<P>
<DT><CODE>PARMRK</CODE>
<DD>If this bit is set, input bytes with parity or framing errors are marked
when passed to the program.  This bit is meaningful only when
<CODE>INPCK</CODE> is set and <CODE>IGNPAR</CODE> is not set.
<P>
The way erroneous bytes are marked is with two preceding bytes,
<CODE>377</CODE> and <CODE>0</CODE>.  Thus, the program actually reads three bytes
for one erroneous byte received from the terminal.
<P>
If a valid byte has the value <CODE>0377</CODE>, and <CODE>ISTRIP</CODE> (see below)
is not set, the program might confuse it with the prefix that marks a
parity error.  So a valid byte <CODE>0377</CODE> is passed to the program as
two bytes, <CODE>0377</CODE> <CODE>0377</CODE>, in this case.
<A NAME="IDX1107"></A>
<P>
<DT><CODE>ISTRIP</CODE>
<DD>If this bit is set, valid input bytes are stripped to seven bits;
otherwise, all eight bits are available for programs to read.
<A NAME="IDX1108"></A>
<P>
<DT><CODE>IGNBRK</CODE>
<DD>If this bit is set, break conditions are ignored.
<A NAME="IDX1109"></A>
<P>
A <DFN>break condition</DFN> is defined in the context of asynchronous
serial data transmission as a series of zero-value bits longer than a
single byte.
<A NAME="IDX1110"></A>
<P>
<DT><CODE>BRKINT</CODE>
<DD>If this bit is set and <CODE>IGNBRK</CODE> is not set, a break condition
clears the terminal input and output queues and raises a <CODE>SIGINT</CODE>
signal for the foreground process group associated with the terminal.
<P>
If neither <CODE>BRKINT</CODE> nor <CODE>IGNBRK</CODE> are set, a break condition is
passed to the application as a single <CODE>'\0'</CODE> character if
<CODE>PARMRK</CODE> is not set, or otherwise as a three-character sequence 
<CODE>'\377'</CODE>, <CODE>'\0'</CODE>, <CODE>'\0'</CODE>.
<A NAME="IDX1111"></A>
<P>
<DT><CODE>IGNCR</CODE>
<DD>If this bit is set, carriage return characters (<CODE>'\r'</CODE>) are
discarded on input.  Discarding carriage return may be useful on
terminals that send both carriage return and linefeed when you type the
<KBD>RET</KBD> key.
<A NAME="IDX1112"></A>
<P>
<DT><CODE>ICRNL</CODE>
<DD>If this bit is set and <CODE>IGNCR</CODE> is not set, carriage return characters
(<CODE>'\r'</CODE>) received as input are passed to the application as newline
characters (<CODE>'\n'</CODE>).
<A NAME="IDX1113"></A>
<P>
<DT><CODE>INLCR</CODE>
<DD>If this bit is set, newline characters (<CODE>'\n'</CODE>) received as input
are passed to the application as carriage return characters (<CODE>'\r'</CODE>).
<A NAME="IDX1114"></A>
<P>
<DT><CODE>IXOFF</CODE>
<DD>If this bit is set, start/stop control on input is enabled.  In other
words, the computer sends STOP and START characters as necessary to
prevent input from coming in faster than programs are reading it.  The
idea is that the actual terminal hardware that is generating the input
data responds to a STOP character by suspending transmission, and to a
START character by resuming transmission.  See section <A HREF="library.html#SEC285">Special Characters for Flow Control</A>.
<A NAME="IDX1115"></A>
<P>
<DT><CODE>IXON</CODE>
<DD>If this bit is set, start/stop control on output is enabled.  In other
words, if the computer receives a STOP character, it suspends output
until a START character is received.  In this case, the STOP and START
characters are never passed to the application program.  If this bit is
not set, then START and STOP can be read as ordinary characters.
See section <A HREF="library.html#SEC285">Special Characters for Flow Control</A>.
<P>
<DT><CODE>IXANY</CODE>
<DD>If this bit is set, any input character restarts output when output has
been suspended with the STOP character.  Otherwise, only the START
character restarts output.
<P>
<DT><CODE>IMAXBEL</CODE>
<DD>If this bit is set, then filling up the terminal input buffer sends a
BEL character (code <CODE>007</CODE>) to the terminal to ring the bell.
</DL>
<P>
<H3><A NAME="SEC277" HREF="library_toc.html#SEC277">Output Modes</A></H3>
<P>
This section describes the terminal flags and fields that control how
output characters are translated and padded for display.  All of these
are contained in the <CODE>c_oflag</CODE> member of the <CODE>struct termios</CODE>
structure.
<P>
The <CODE>c_oflag</CODE> member itself is an integer, and you change the flags
and fields using the operators <CODE>&#38;</CODE>, <CODE>|</CODE>, and <CODE>^</CODE>.  Don't
try to specify the entire value for <CODE>c_oflag</CODE>---instead, change
only specific flags and leave the rest untouched (see section <A HREF="library.html#SEC275">Setting Terminal Modes Properly</A>).
<P>
<A NAME="IDX1116"></A>
<U>Macro:</U> int <B>OPOST</B><P>
If this bit is set, output data is processed in some unspecified way so
that it is displayed appropriately on the terminal device.  This
typically includes mapping newline characters (<CODE>'\n'</CODE>) onto
carriage return and linefeed pairs.
<P>
If this bit isn't set, the characters are transmitted as-is.
<P>
The following three bits are BSD features, and they have no effect on
non-BSD systems.  On all systems, they are effective only if
<CODE>OPOST</CODE> is set.
<P>
<A NAME="IDX1117"></A>
<U>Macro:</U> int <B>ONLCR</B><P>
If this bit is set, convert the newline character on output into a pair
of characters, carriage return followed by linefeed.
<P>
<A NAME="IDX1118"></A>
<U>Macro:</U> int <B>OXTABS</B><P>
If this bit is set, convert tab characters on output into the appropriate
number of spaces to emulate a tab stop every eight columns.
<P>
<A NAME="IDX1119"></A>
<U>Macro:</U> int <B>ONOEOT</B><P>
If this bit is set, discard <KBD>C-d</KBD> characters (code <CODE>004</CODE>) on
output.  These characters cause many dial-up terminals to disconnect.
<P>
<H3><A NAME="SEC278" HREF="library_toc.html#SEC278">Control Modes</A></H3>
<P>
This section describes the terminal flags and fields that control
parameters usually associated with asynchronous serial data
transmission.  These flags may not make sense for other kinds of
terminal ports (such as a network connection pseudo-terminal).  All of
these are contained in the <CODE>c_cflag</CODE> member of the <CODE>struct
termios</CODE> structure.
<P>
The <CODE>c_cflag</CODE> member itself is an integer, and you change the flags
and fields using the operators <CODE>&#38;</CODE>, <CODE>|</CODE>, and <CODE>^</CODE>.  Don't
try to specify the entire value for <CODE>c_cflag</CODE>---instead, change
only specific flags and leave the rest untouched (see section <A HREF="library.html#SEC275">Setting Terminal Modes Properly</A>).
<P>
<A NAME="IDX1120"></A>
<DL COMPACT>
<DT><CODE>CLOCAL</CODE>
<DD>If this bit is set, it indicates that the terminal is connected
"locally" and that the modem status lines (such as carrier detect)
should be ignored.
<A NAME="IDX1122"></A>
<A NAME="IDX1121"></A>
<P>
If this bit is not set and you call <CODE>open</CODE> without the
<CODE>O_NONBLOCK</CODE> flag set, <CODE>open</CODE> blocks until a modem
connection is established.
<P>
If this bit is not set and a modem disconnect is detected, a
<CODE>SIGHUP</CODE> signal is sent to the controlling process group for the
terminal (if it has one).  Normally, this causes the process to exit;
see section <A HREF="library.html#SEC330">Signal Handling</A>.  Reading from the terminal after a disconnect
causes an end-of-file condition, and writing causes an <CODE>EIO</CODE> error
to be returned.  The terminal device must be closed and reopened to
clear the condition.
<A NAME="IDX1123"></A>
<A NAME="IDX1124"></A>
<P>
<DT><CODE>HUPCL</CODE>
<DD>If this bit is set, a modem disconnect is generated when all processes
that have the terminal device open have either closed the file or exited.
<A NAME="IDX1125"></A>
<P>
<DT><CODE>CREAD</CODE>
<DD>If this bit is set, input can be read from the terminal.  Otherwise,
input is discarded when it arrives.
<A NAME="IDX1126"></A>
<P>
<DT><CODE>CSTOPB</CODE>
<DD>If this bit is set, two stop bits are used.  Otherwise, only one stop bit
is used.
<A NAME="IDX1127"></A>
<P>
<DT><CODE>PARENB</CODE>
<DD>If this bit is set, generation and detection of a parity bit are enabled.
See section <A HREF="library.html#SEC276">Input Modes</A>, for information on how input parity errors are handled.
<P>
If this bit is not set, no parity bit is added to output characters, and
input characters are not checked for correct parity.
<A NAME="IDX1128"></A>
<P>
<DT><CODE>PARODD</CODE>
<DD>This bit is only useful if <CODE>PARENB</CODE> is set.  If <CODE>PARODD</CODE> is set,
odd parity is used, otherwise even parity is used.
</DL>
<P>
The control mode flags also includes a field for the number of bits per
character.  You can use the <CODE>CSIZE</CODE> macro as a mask to extract the
value, like this: <CODE>settings.c_cflag &#38; CSIZE</CODE>.
<P>
<A NAME="IDX1129"></A>
<DL COMPACT>
<DT><CODE>CSIZE</CODE>
<DD>This is a mask for the number of bits per character.
<A NAME="IDX1130"></A>
<P>
<DT><CODE>CS5</CODE>
<DD>This specifies five bits per byte.
<A NAME="IDX1131"></A>
<P>
<DT><CODE>CS6</CODE>
<DD>This specifies six bits per byte.
<A NAME="IDX1132"></A>
<P>
<DT><CODE>CS7</CODE>
<DD>This specifies seven bits per byte.
<A NAME="IDX1133"></A>
<P>
<DT><CODE>CS8</CODE>
<DD>This specifies eight bits per byte.
<A NAME="IDX1134"></A>
<P>
<DT><CODE>CCTS_OFLOW</CODE>
<DD>If this bit is set, enable flow control of output based on the CTS wire
(RS232 protocol).
<A NAME="IDX1135"></A>
<P>
<DT><CODE>CRTS_IFLOW</CODE>
<DD>If this bit is set, enable flow control of input based on the RTS wire
(RS232 protocol).
<A NAME="IDX1136"></A>
<P>
<DT><CODE>MDMBUF</CODE>
<DD>If this bit is set, enable carrier-based flow control of output.
</DL>
<P>
<H3><A NAME="SEC279" HREF="library_toc.html#SEC279">Local Modes</A></H3>
<P>
This section describes the flags for the <CODE>c_lflag</CODE> member of the
<CODE>struct termios</CODE> structure.  These flags generally control
higher-level aspects of input processing than the input modes flags
described in section <A HREF="library.html#SEC276">Input Modes</A>, such as echoing, signals, and the choice
of canonical or noncanonical input.
<P>
The <CODE>c_lflag</CODE> member itself is an integer, and you change the flags
and fields using the operators <CODE>&#38;</CODE>, <CODE>|</CODE>, and <CODE>^</CODE>.  Don't
try to specify the entire value for <CODE>c_lflag</CODE>---instead, change
only specific flags and leave the rest untouched (see section <A HREF="library.html#SEC275">Setting Terminal Modes Properly</A>).
<P>
<A NAME="IDX1137"></A>
<DL COMPACT>
<DT><CODE>ICANON</CODE>
<DD>This bit, if set, enables canonical input processing mode.  Otherwise,
input is processed in noncanonical mode.  See section <A HREF="library.html#SEC271">Two Styles of Input: Canonical or Not</A>.
<A NAME="IDX1138"></A>
<P>
<DT><CODE>ECHO</CODE>
<DD>If this bit is set, echoing of input characters back to the terminal
is enabled.
<A NAME="IDX1139"></A>
<A NAME="IDX1140"></A>
<P>
<DT><CODE>ECHOE</CODE>
<DD>If this bit is set, echoing indicates erasure of input with the ERASE
character by erasing the last character in the current line from the
screen.  Otherwise, the character erased is re-echoed to show what has
happened (suitable for a printing terminal).
<P>
This bit only controls the display behavior; the <CODE>ICANON</CODE> bit by
itself controls actual recognition of the ERASE character and erasure of
input, without which <CODE>ECHOE</CODE> is simply irrelevant.
<A NAME="IDX1141"></A>
<P>
<DT><CODE>ECHOK</CODE>
<DD>This bit enables special display of the KILL character.  There are two
ways this can be done.  The better way is by erasing on the screen the
entire line that has been killed.  The worse way is by moving to a new
line after echoing the KILL character normally.  Some systems do one,
some systems do the other, and some let you choose either way.
<P>
If this bit is not set, the KILL character echoes just as it would if it
were not the KILL character.  Then it is up to the user to remember that
the KILL character has erased the preceding input; there is no
indication of this on the screen.
<P>
This bit only controls the display behavior; the <CODE>ICANON</CODE> bit by
itself controls actual recognition of the KILL character and erasure of
input, without which <CODE>ECHOK</CODE> is simply irrelevant.
<A NAME="IDX1142"></A>
<P>
<DT><CODE>ECHONL</CODE>
<DD>If this bit is set and the <CODE>ICANON</CODE> bit is also set, then the
newline (<CODE>'\n'</CODE>) character is echoed even if the <CODE>ECHO</CODE> bit
is not set.
<A NAME="IDX1143"></A>
<P>
<DT><CODE>ISIG</CODE>
<DD>This bit controls whether the INTR, QUIT, and SUSP characters are
recognized.  The functions associated with these characters are performed
if and only if this bit is set.  Being in canonical or noncanonical
input mode has no affect on the interpretation of these characters.
<P>
You should use caution when disabling recognition of these characters.
Programs that cannot be interrupted interactively are very
user-unfriendly.  If you clear this bit, your program should provide
some alternate interface that allows the user to interactively send the
signals associated with these characters, or to escape from the program.
<A NAME="IDX1144"></A>
<P>
See section <A HREF="library.html#SEC284">Characters that Cause Signals</A>.
<A NAME="IDX1145"></A>
<P>
<DT><CODE>IEXTEN</CODE>
<DD>This bit is similar to <CODE>ISIG</CODE>, but controls implementation-defined
special characters.  If it is set, it might override the default behavior
for the <CODE>ICANON</CODE> and <CODE>ISIG</CODE> local mode flags, and the <CODE>IXON</CODE>
and <CODE>IXOFF</CODE> input mode flags.
<A NAME="IDX1146"></A>
<P>
<DT><CODE>NOFLSH</CODE>
<DD>Normally, the INTR, QUIT, and SUSP characters cause input and output
queues for the terminal to be cleared.  If this bit is set, the queues
are not cleared.
<A NAME="IDX1147"></A>
<P>
<DT><CODE>TOSTOP</CODE>
<DD>If this bit is set and the system supports job control, then
<CODE>SIGTTOU</CODE> signals are generated by background processes that
attempt to write to the terminal.  See section <A HREF="library.html#SEC415">Access to the Controlling Terminal</A>.
</DL>
<P>
The following bits are BSD extensions; the GNU library defines these
symbols on any system if you ask for them, but the settings of the bits
have no effect except on BSD systems.
<P>
<A NAME="IDX1148"></A>
<DL COMPACT>
<DT><CODE>ECHOKE</CODE>
<DD>On BSD systems, this bit selects between the two alternative ways of
displaying the KILL character, when <CODE>ECHOK</CODE> is set.  If
<CODE>ECHOKE</CODE> is set, then the KILL character erases the whole screen
line; otherwise, the KILL character moves to the next screen line.
The setting of <CODE>ECHOKE</CODE> has no effect when <CODE>ECHOK</CODE> is clear.
<P>
<A NAME="IDX1149"></A>
<DT><CODE>ECHOPRT</CODE>
<DD>This bit enables display of the ERASE character in a way that is geared
to a hardcopy terminal.
<A NAME="IDX1150"></A>
<P>
<DT><CODE>ECHOCTL</CODE>
<DD>If this bit is set, echo control characters with <SAMP>`^'</SAMP> followed by
the corresponding text character.  Thus, control-A echoes as <SAMP>`^A'</SAMP>.
<A NAME="IDX1151"></A>
<P>
<DT><CODE>ALTWERASE</CODE>
<DD>This bit determines how far the WERASE character should erase.  The
WERASE character erases back to the beginning of a word; the question
is, where do words begin?
<P>
If this bit is clear, then the beginning of a word is a nonwhitespace
character following a whitespace character.  If the bit is set, then the
beginning of a word is an alphanumeric character or underscore following
a character which is none of those.
<A NAME="IDX1152"></A>
<P>
<DT><CODE>FLUSHO</CODE>
<DD>This is the bit that toggles when the user types the DISCARD character.
While this bit is set, all output is discarded.  See section <A HREF="library.html#SEC286">Other Special Characters</A>.
<A NAME="IDX1153"></A>
<P>
<DT><CODE>NOKERNINFO</CODE>
<DD>Setting this bit disables handling of the STATUS character.
See section <A HREF="library.html#SEC286">Other Special Characters</A>.
<A NAME="IDX1154"></A>
<P>
<DT><CODE>PENDIN</CODE>
<DD>If this bit is set, it indicates that there is a line of input that
needs to be reprinted.  Typing the REPRINT character sets this bit; the
bit remains set until reprinting is finished.  See section <A HREF="library.html#SEC283">BSD Extensions to Editing Characters</A>.
</DL>
<P>
<A NAME="IDX1155"></A>
<A NAME="IDX1156"></A>
<A NAME="IDX1157"></A>
<A NAME="IDX1158"></A>
<H3><A NAME="SEC280" HREF="library_toc.html#SEC280">Line Speed</A></H3>
<P>
The terminal line speed tells the computer how fast to read and write
data on the terminal.
<P>
If the terminal is connected to a real serial line, the terminal speed
you specify actually controls the line--if it doesn't match the
terminal's own idea of the speed, communication does not work.  Real
serial ports accept only certain standard speeds.  Also, particular
hardware may not support even all the standard speeds.  Specifying a
speed of zero hangs up a dialup connection and turns off modem control
signals.
<P>
If the terminal is not a real serial line (for example, if it is a
network connection), then the line speed won't really affect data
transmission speed, but some programs will use it to determine the
amount of padding needed.  It's best to specify a line speed value that
matches the actual speed of the actual terminal, but you can safely
experiment with different values to vary the amount of padding.
<P>
There are actually two line speeds for each terminal, one for input and
one for output.  You can set them independently, but most often
terminals use the same speed for both directions.
<P>
The speed values are stored in the <CODE>struct termios</CODE> structure, but
don't try to access them in the <CODE>struct termios</CODE> structure
directly.  Instead, you should use the following functions to read and
store them:
<P>
<A NAME="IDX1159"></A>
<U>Function:</U> speed_t <B>cfgetospeed</B> <I>(const struct termios *<VAR>termios_p</VAR>)</I><P>
This function returns the output line speed stored in the structure
<CODE>*<VAR>termios_p</VAR></CODE>.
<P>
<A NAME="IDX1160"></A>
<U>Function:</U> speed_t <B>cfgetispeed</B> <I>(const struct termios *<VAR>termios_p</VAR>)</I><P>
This function returns the input line speed stored in the structure
<CODE>*<VAR>termios_p</VAR></CODE>.
<P>
<A NAME="IDX1161"></A>
<U>Function:</U> int <B>cfsetospeed</B> <I>(struct termios *<VAR>termios_p</VAR>, speed_t <VAR>speed</VAR>)</I><P>
This function stores <VAR>speed</VAR> in <CODE>*<VAR>termios_p</VAR></CODE> as the output
speed.  The normal return value is <CODE>0</CODE>; a value of <CODE>-1</CODE>
indicates an error.  If <VAR>speed</VAR> is not a speed, <CODE>cfsetospeed</CODE>
returns <CODE>-1</CODE>.
<P>
<A NAME="IDX1162"></A>
<U>Function:</U> int <B>cfsetispeed</B> <I>(struct termios *<VAR>termios_p</VAR>, speed_t <VAR>speed</VAR>)</I><P>
This function stores <VAR>speed</VAR> in <CODE>*<VAR>termios_p</VAR></CODE> as the input
speed.  The normal return value is <CODE>0</CODE>; a value of <CODE>-1</CODE>
indicates an error.  If <VAR>speed</VAR> is not a speed, <CODE>cfsetospeed</CODE>
returns <CODE>-1</CODE>.
<P>
<A NAME="IDX1163"></A>
<U>Function:</U> int <B>cfsetspeed</B> <I>(struct termios *<VAR>termios_p</VAR>, speed_t <VAR>speed</VAR>)</I><P>
This function stores <VAR>speed</VAR> in <CODE>*<VAR>termios_p</VAR></CODE> as both the
input and output speeds.  The normal return value is <CODE>0</CODE>; a value
of <CODE>-1</CODE> indicates an error.  If <VAR>speed</VAR> is not a speed,
<CODE>cfsetspeed</CODE> returns <CODE>-1</CODE>.  This function is an extension in
4.4 BSD.
<P>
<A NAME="IDX1164"></A>
<U>Data Type:</U> <B>speed_t</B><P>
The <CODE>speed_t</CODE> type is an unsigned integer data type used to
represent line speeds.
<P>
The functions <CODE>cfsetospeed</CODE> and <CODE>cfsetispeed</CODE> report errors
only for speed values that the system simply cannot handle.  If you
specify a speed value that is basically acceptable, then those functions
will succeed.  But they do not check that a particular hardware device
can actually support the specified speeds--in fact, they don't know
which device you plan to set the speed for.  If you use <CODE>tcsetattr</CODE>
to set the speed of a particular device to a value that it cannot
handle, <CODE>tcsetattr</CODE> returns <CODE>-1</CODE>.
<P>
<STRONG>Portability note:</STRONG> In the GNU library, the functions above
accept speeds measured in bits per second as input, and return speed
values measured in bits per second.  Other libraries require speeds to
be indicated by special codes.  For POSIX.1 portability, you must use
one of the following symbols to represent the speed; their precise
numeric values are system-dependent, but each name has a fixed meaning:
<CODE>B110</CODE> stands for 110 bps, <CODE>B300</CODE> for 300 bps, and so on.
There is no portable way to represent any speed but these, but these are
the only speeds that typical serial lines can support.
<A NAME="IDX1165"></A>
<A NAME="IDX1166"></A>
<A NAME="IDX1167"></A>
<A NAME="IDX1168"></A>
<A NAME="IDX1169"></A>
<A NAME="IDX1170"></A>
<A NAME="IDX1171"></A>
<A NAME="IDX1172"></A>
<A NAME="IDX1173"></A>
<A NAME="IDX1174"></A>
<A NAME="IDX1175"></A>
<A NAME="IDX1176"></A>
<A NAME="IDX1177"></A>
<A NAME="IDX1178"></A>
<A NAME="IDX1179"></A>
<A NAME="IDX1180"></A>
<P>
<PRE>
B0  B50  B75  B110  B134  B150  B200
B300  B600  B1200  B1800  B2400  B4800
B9600  B19200  B38400
</PRE>
<A NAME="IDX1181"></A>
<A NAME="IDX1182"></A>
<P>
BSD defines two additional speed symbols as aliases: <CODE>EXTA</CODE> is an
alias for <CODE>B19200</CODE> and <CODE>EXTB</CODE> is an alias for <CODE>B38400</CODE>.
These aliases are obsolete.
<P>
<A NAME="IDX1183"></A>
<U>Function:</U> int <B>cfmakeraw</B> <I>(struct termios *<VAR>termios_p</VAR>)</I><P>
<PRE>
  t-&#62;c_iflag &#38;= ~(IGNBRK|BRKINT|PARMRK|ISTRIP
                  |INLCR|IGNCR|ICRNL|IXON);
  t-&#62;c_oflag &#38;= ~OPOST;
  t-&#62;c_lflag &#38;= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);
  t-&#62;c_cflag &#38;= ~(CSIZE|PARENB);
  t-&#62;c_cflag |= CS8;
</PRE>
<P>
<H3><A NAME="SEC281" HREF="library_toc.html#SEC281">Special Characters</A></H3>
<P>
In canonical input, the terminal driver recognizes a number of special
characters which perform various control functions.  These include the
ERASE character (usually <KBD>DEL</KBD>) for editing input, and other editing
characters.  The INTR character (normally <KBD>C-c</KBD>) for sending a
<CODE>SIGINT</CODE> signal, and other signal-raising characters, may be
available in either canonical or noncanonical input mode.  All these
characters are described in this section.
<P>
The particular characters used are specified in the <CODE>c_cc</CODE> member
of the <CODE>struct termios</CODE> structure.  This member is an array; each
element specifies the character for a particular role.  Each element has
a symbolic constant that stands for the index of that element--for
example, <CODE>INTR</CODE> is the index of the element that specifies the INTR
character, so storing <CODE>'='</CODE> in <CODE><VAR>termios</VAR>.c_cc[INTR]</CODE>
specifies <SAMP>`='</SAMP> as the INTR character.
<A NAME="IDX1184"></A>
<P>
On some systems, you can disable a particular special character function
by specifying the value <CODE>_POSIX_VDISABLE</CODE> for that role.  This
value is unequal to any possible character code.  See section <A HREF="library.html#SEC464">Optional Features in File Support</A>, for more information about how to tell whether the operating
system you are using supports <CODE>_POSIX_VDISABLE</CODE>.
<P>
<H4><A NAME="SEC282" HREF="library_toc.html#SEC282">Characters for Input Editing</A></H4>
<P>
These special characters are active only in canonical input mode.
See section <A HREF="library.html#SEC271">Two Styles of Input: Canonical or Not</A>.
<P>
<A NAME="IDX1185"></A>
<A NAME="IDX1186"></A>
<U>Macro:</U> int <B>VEOF</B><P>
This is the subscript for the EOF character in the special control
character array.  <CODE><VAR>termios</VAR>.c_cc[VEOF]</CODE> holds the character
itself.
<P>
The EOF character is recognized only in canonical input mode.  It acts
as a line terminator in the same way as a newline character, but if the
EOF character is typed at the beginning of a line it causes <CODE>read</CODE>
to return a byte count of zero, indicating end-of-file.  The EOF
character itself is discarded.
<P>
Usually, the EOF character is <KBD>C-d</KBD>.
<P>
<A NAME="IDX1187"></A>
<A NAME="IDX1188"></A>
<U>Macro:</U> int <B>VEOL</B><P>
This is the subscript for the EOL character in the special control
character array.  <CODE><VAR>termios</VAR>.c_cc[VEOL]</CODE> holds the character
itself.
<P>
The EOL character is recognized only in canonical input mode.  It acts
as a line terminator, just like a newline character.  The EOL character
is not discarded; it is read as the last character in the input line.
<P>
You don't need to use the EOL character to make <KBD>RET</KBD> end a line.
Just set the ICRNL flag.  In fact, this is the default state of
affairs.
<P>
<A NAME="IDX1189"></A>
<A NAME="IDX1190"></A>
<U>Macro:</U> int <B>VERASE</B><P>
This is the subscript for the ERASE character in the special control
character array.  <CODE><VAR>termios</VAR>.c_cc[VERASE]</CODE> holds the
character itself.
<P>
The ERASE character is recognized only in canonical input mode.  When
the user types the erase character, the previous character typed is
discarded.  (If the terminal generates multibyte character sequences,
this may cause more than one byte of input to be discarded.)  This
cannot be used to erase past the beginning of the current line of text.
The ERASE character itself is discarded.
<P>
Usually, the ERASE character is <KBD>DEL</KBD>.
<P>
<A NAME="IDX1191"></A>
<A NAME="IDX1192"></A>
<U>Macro:</U> int <B>VKILL</B><P>
This is the subscript for the KILL character in the special control
character array.  <CODE><VAR>termios</VAR>.c_cc[VKILL]</CODE> holds the character
itself.
<P>
The KILL character is recognized only in canonical input mode.  When the
user types the kill character, the entire contents of the current line
of input are discarded.  The kill character itself is discarded too.
<P>
The KILL character is usually <KBD>C-u</KBD>.
<P>
<H4><A NAME="SEC283" HREF="library_toc.html#SEC283">BSD Extensions to Editing Characters</A></H4>
<P>
These special characters are active only in canonical input mode.
See section <A HREF="library.html#SEC271">Two Styles of Input: Canonical or Not</A>.  They are BSD extensions; the GNU library
defines the symbols on any system if you ask for them, but the
characters you specify don't actually <EM>do</EM> anything except on a BSD
system.
<P>
<A NAME="IDX1193"></A>
<A NAME="IDX1194"></A>
<U>Macro:</U> int <B>VEOL2</B><P>
This is the subscript for the EOL2 character in the special control
character array.  <CODE><VAR>termios</VAR>.c_cc[VEOL2]</CODE> holds the character
itself.
<P>
The EOL2 character works just like the EOL character (see above), but it
can be a different character.  Thus, you can specify two characters to
terminate an input line, but setting EOL to one of them and EOL2 to the
other.
<P>
<A NAME="IDX1195"></A>
<A NAME="IDX1196"></A>
<U>Macro:</U> int <B>VWERASE</B><P>
This is the subscript for the WERASE character in the special control
character array.  <CODE><VAR>termios</VAR>.c_cc[VWERASE]</CODE> holds the character
itself.
<P>
The WERASE character is recognized only in canonical input mode.  It
erases an entire word of prior input.
<P>
<A NAME="IDX1197"></A>
<A NAME="IDX1198"></A>
<U>Macro:</U> int <B>VREPRINT</B><P>
This is the subscript for the REPRINT character in the special control
character array.  <CODE><VAR>termios</VAR>.c_cc[VREPRINT]</CODE> holds the character
itself.
<P>
The REPRINT character is recognized only in canonical input mode.  It
reprints the current input line.
<P>
<A NAME="IDX1199"></A>
<A NAME="IDX1200"></A>
<U>Macro:</U> int <B>VLNEXT</B><P>
This is the subscript for the LNEXT character in the special control
character array.  <CODE><VAR>termios</VAR>.c_cc[VLNEXT]</CODE> holds the character
itself.
<P>
The LNEXT character is recognized only when <CODE>IEXTEN</CODE> is set.  It
disables the editing significance of the next character the user types.
It is the analogue of the <KBD>C-q</KBD> command in Emacs.  "LNEXT" stands
for "literal next."
<P>
The LNEXT character is usually <KBD>C-v</KBD>.
<P>
<H4><A NAME="SEC284" HREF="library_toc.html#SEC284">Characters that Cause Signals</A></H4>
<P>
These special characters may be active in either canonical or noncanonical
input mode, but only when the <CODE>ISIG</CODE> flag is set (see section <A HREF="library.html#SEC279">Local Modes</A>).
<P>
<A NAME="IDX1201"></A>
<A NAME="IDX1202"></A>
<A NAME="IDX1203"></A>
<U>Macro:</U> int <B>VINTR</B><P>
This is the subscript for the INTR character in the special control
character array.  <CODE><VAR>termios</VAR>.c_cc[VINTR]</CODE> holds the character
itself.
<P>
The INTR (interrupt) character raises a <CODE>SIGINT</CODE> signal for all
processes in the foreground job associated with the terminal.  The INTR
character itself is then discarded.  See section <A HREF="library.html#SEC330">Signal Handling</A>, for more
information about signals.
<P>
Typically, the INTR character is <KBD>C-c</KBD>.
<P>
<A NAME="IDX1204"></A>
<A NAME="IDX1205"></A>
<U>Macro:</U> int <B>VQUIT</B><P>
This is the subscript for the QUIT character in the special control
character array.  <CODE><VAR>termios</VAR>.c_cc[VQUIT]</CODE> holds the character
itself.
<P>
The QUIT character raises a <CODE>SIGQUIT</CODE> signal for all processes in
the foreground job associated with the terminal.  The QUIT character
itself is then discarded.  See section <A HREF="library.html#SEC330">Signal Handling</A>, for more information
about signals.
<P>
Typically, the QUIT character is <KBD>C-\</KBD>.
<P>
<A NAME="IDX1206"></A>
<A NAME="IDX1207"></A>
<A NAME="IDX1208"></A>
<U>Macro:</U> int <B>VSUSP</B><P>
This is the subscript for the SUSP character in the special control
character array.  <CODE><VAR>termios</VAR>.c_cc[VSUSP]</CODE> holds the character
itself.
<P>
The SUSP (suspend) character is recognized only if the implementation
supports job control (see section <A HREF="library.html#SEC411">Job Control</A>).  It causes a <CODE>SIGTSTP</CODE>
signal to be sent to all processes in the foreground job associated with
the terminal.  The SUSP character itself is then discarded.
See section <A HREF="library.html#SEC330">Signal Handling</A>, for more information about signals.
<P>
Typically, the SUSP character is <KBD>C-z</KBD>.
<P>
Few applications disable the normal interpretation of the SUSP
character.  If your program does this, it should provide some other
mechanism for the user to stop the job.  When the user invokes this
mechanism, the program should send a <CODE>SIGTSTP</CODE> signal to the
process group of the process, not just to the process itself.
See section <A HREF="library.html#SEC365">Signaling Another Process</A>.
<P>
<A NAME="IDX1209"></A>
<A NAME="IDX1210"></A>
<A NAME="IDX1211"></A>
<U>Macro:</U> int <B>VDSUSP</B><P>
This is the subscript for the DSUSP character in the special control
character array.  <CODE><VAR>termios</VAR>.c_cc[VDSUSP]</CODE> holds the character
itself.
<P>
The DSUSP (suspend) character is recognized only if the implementation
supports job control (see section <A HREF="library.html#SEC411">Job Control</A>).  It sends a <CODE>SIGTSTP</CODE>
signal, like the SUSP character, but not right away--only when the
program tries to read it as input.  Not all systems with job control
support DSUSP; only BSD systems.
<P>
See section <A HREF="library.html#SEC330">Signal Handling</A>, for more information about signals.
<P>
Typically, the DSUSP character is <KBD>C-y</KBD>.
<P>
<H4><A NAME="SEC285" HREF="library_toc.html#SEC285">Special Characters for Flow Control</A></H4>
<P>
These special characters may be active in either canonical or noncanonical
input mode, but their use is controlled by the flags <CODE>IXON</CODE> and
<CODE>IXOFF</CODE> (see section <A HREF="library.html#SEC276">Input Modes</A>).
<P>
<A NAME="IDX1212"></A>
<A NAME="IDX1213"></A>
<U>Macro:</U> int <B>VSTART</B><P>
This is the subscript for the START character in the special control
character array.  <CODE><VAR>termios</VAR>.c_cc[VSTART]</CODE> holds the
character itself.
<P>
The START character is used to support the <CODE>IXON</CODE> and <CODE>IXOFF</CODE>
input modes.  If <CODE>IXON</CODE> is set, receiving a START character resumes
suspended output; the START character itself is discarded.  If
<CODE>IXOFF</CODE> is set, the system may also transmit START characters to
the terminal.
<P>
The usual value for the START character is <KBD>C-q</KBD>.  You may not be
able to change this value--the hardware may insist on using <KBD>C-q</KBD>
regardless of what you specify.
<P>
<A NAME="IDX1214"></A>
<A NAME="IDX1215"></A>
<U>Macro:</U> int <B>VSTOP</B><P>
This is the subscript for the STOP character in the special control
character array.  <CODE><VAR>termios</VAR>.c_cc[VSTOP]</CODE> holds the character
itself.
<P>
The STOP character is used to support the <CODE>IXON</CODE> and <CODE>IXOFF</CODE>
input modes.  If <CODE>IXON</CODE> is set, receiving a STOP character causes
output to be suspended; the STOP character itself is discarded.  If
<CODE>IXOFF</CODE> is set, the system may also transmit STOP characters to the
terminal, to prevent the input queue from overflowing.
<P>
The usual value for the STOP character is <KBD>C-s</KBD>.  You may not be
able to change this value--the hardware may insist on using <KBD>C-s</KBD>
regardless of what you specify.
<P>
<H4><A NAME="SEC286" HREF="library_toc.html#SEC286">Other Special Characters</A></H4>
<P>
Here are two additional special characters that are meaningful on BSD
systems.
<P>
<A NAME="IDX1216"></A>
<A NAME="IDX1217"></A>
<U>Macro:</U> int <B>VDISCARD</B><P>
This is the subscript for the DISCARD character in the special control
character array.  <CODE><VAR>termios</VAR>.c_cc[VDISCARD]</CODE> holds the character
itself.
<P>
The DISCARD character is recognized only when <CODE>IEXTEN</CODE> is set.  Its
effect is to toggle the discard-output flag.  When this flag is set, all
program output is discarded.  Setting the flag also discards all output
currently in the output buffer.
<P>
<A NAME="IDX1218"></A>
<A NAME="IDX1219"></A>
<U>Macro:</U> int <B>VSTATUS</B><P>
This is the subscript for the STATUS character in the special control
character array.  <CODE><VAR>termios</VAR>.c_cc[VSTATUS]</CODE> holds the character
itself.
<P>
The STATUS character's effect is to print out a status message about how
the current process is running.
<P>
The STATUS character is recognized only when canonical mode.  This is a
peculiar design decision, since the STATUS character's meaning has
nothing to do with input, but that's the way it was done.
<P>
<H3><A NAME="SEC287" HREF="library_toc.html#SEC287">Noncanonical Input</A></H3>
<P>
In noncanonical input mode, the special editing characters such as
ERASE and KILL are ignored.  The system facilities for the user to edit
input are disabled in noncanonical mode, so that all input characters
(unless they are special for signal or flow-control purposes) are passed
to the application program exactly as typed.  It is up to the
application program to give the user ways to edit the input, if
appropriate.
<P>
Noncanonical mode offers special parameters called MIN and TIME for
controlling whether and how long to wait for input to be available.  You
can even use them to avoid ever waiting--to return immediately with
whatever input is available, or with no input.
<P>
The MIN and TIME are stored in elements of the <CODE>c_cc</CODE> array, which
is a member of the <CODE>struct termios</CODE> structure.  Each element of
this array has a particular role, and each element has a symbolic
constant that stands for the index of that element.  <CODE>VMIN</CODE> and
<CODE>VMAX</CODE> are the names for the indices in the array of the MIN and
TIME slots.
<P>
<A NAME="IDX1220"></A>
<A NAME="IDX1221"></A>
<U>Macro:</U> int <B>VMIN</B><P>
This is the subscript for the MIN slot in the <CODE>c_cc</CODE> array.  Thus,
<CODE><VAR>termios</VAR>.c_cc[VMIN]</CODE> is the value itself.
<P>
The MIN slot is only meaningful in noncanonical input mode; it
specifies the minimum number of bytes that must be available in the
input queue in order for <CODE>read</CODE> to return.
<P>
<A NAME="IDX1222"></A>
<A NAME="IDX1223"></A>
<U>Macro:</U> int <B>VTIME</B><P>
This is the subscript for the TIME slot in the <CODE>c_cc</CODE> array.  Thus,
<CODE><VAR>termios</VAR>.c_cc[VTIME]</CODE> is the value itself.
<P>
The TIME slot is only meaningful in noncanonical input mode; it
specifies how long to wait for input before returning, in units of 0.1
seconds.
<P>
The MIN and TIME values interact to determine the criterion for when
<CODE>read</CODE> should return; their precise meanings depend on which of
them are nonzero.  There are four possible cases:
<P>
<UL>
<LI>
Both MIN and TIME are zero.
<P>
In this case, <CODE>read</CODE> always returns immediately with as many
characters as are available in the queue, up to the number requested.
If no input is immediately available, <CODE>read</CODE> returns a value of
zero.
<P>
<LI>
MIN is zero but TIME has a nonzero value.
<P>
In this case, <CODE>read</CODE> waits for time TIME for input to become
available; the availability of a single byte is enough to satisfy the
read request and cause <CODE>read</CODE> to return.  When it returns, it
returns as many characters as are available, up to the number requested.
If no input is available before the timer expires, <CODE>read</CODE> returns a
value of zero.
<P>
<LI>
TIME is zero but MIN has a nonzero value.
<P>
In this case, <CODE>read</CODE> waits until at least MIN bytes are available
in the queue.  At that time, <CODE>read</CODE> returns as many characters as
are available, up to the number requested.  <CODE>read</CODE> can return more
than MIN characters if more than MIN happen to be in the queue.
<P>
<LI>
Both TIME and MIN are nonzero.
<P>
In this case, TIME specifies how long to wait after each input character
to see if more input arrives.  <CODE>read</CODE> keeps waiting until either
MIN bytes have arrived, or TIME elapses with no further input.
<P>
<CODE>read</CODE> can return no input if TIME elapses before the first input
character arrives.  <CODE>read</CODE> can return more than MIN characters if
more than MIN happen to be in the queue.
</UL>
<P>
What happens if MIN is 50 and you ask to read just 10 bytes?
Normally, <CODE>read</CODE> waits until there are 50 bytes in the buffer (or,
more generally, the wait condition described above is satisfied), and
then reads 10 of them, leaving the other 40 buffered in the operating
system for a subsequent call to <CODE>read</CODE>.
<P>
<STRONG>Portability note:</STRONG> On some systems, the MIN and TIME slots are
actually the same as the EOF and EOL slots.  This causes no serious
problem because the MIN and TIME slots are used only in noncanonical
input and the EOF and EOL slots are used only in canonical input, but it
isn't very clean.  The GNU library allocates separate slots for these
uses.
<P>
<A NAME="IDX1224"></A>
<H2><A NAME="SEC288" HREF="library_toc.html#SEC288">Line Control Functions</A></H2>
<P>
These functions perform miscellaneous control actions on terminal
devices.  As regards terminal access, they are treated like doing
output: if any of these functions is used by a background process on its
controlling terminal, normally all processes in the process group are
sent a <CODE>SIGTTOU</CODE> signal.  The exception is if the calling process
itself is ignoring or blocking <CODE>SIGTTOU</CODE> signals, in which case the
operation is performed and no signal is sent.  See section <A HREF="library.html#SEC411">Job Control</A>.
<A NAME="IDX1225"></A>
<P>
<A NAME="IDX1226"></A>
<U>Function:</U> int <B>tcsendbreak</B> <I>(int <VAR>filedes</VAR>, int <VAR>duration</VAR>)</I><P>
This function generates a break condition by transmitting a stream of
zero bits on the terminal associated with the file descriptor
<VAR>filedes</VAR>.  The duration of the break is controlled by the
<VAR>duration</VAR> argument.  If zero, the duration is between 0.25 and 0.5
seconds.  The meaning of a nonzero value depends on the operating system.
<P>
This function does nothing if the terminal is not an asynchronous serial
data port.
<P>
The return value is normally zero.  In the event of an error, a value
of <CODE>-1</CODE> is returned.  The following <CODE>errno</CODE> error conditions
are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> is not a valid file descriptor.
<P>
<DT><CODE>ENOTTY</CODE>
<DD>The <VAR>filedes</VAR> is not associated with a terminal device.
</DL>
<P>
<A NAME="IDX1227"></A>
<A NAME="IDX1228"></A>
<P>
<A NAME="IDX1229"></A>
<U>Function:</U> int <B>tcdrain</B> <I>(int <VAR>filedes</VAR>)</I><P>
The <CODE>tcdrain</CODE> function waits until all queued
output to the terminal <VAR>filedes</VAR> has been transmitted.
<P>
The return value is normally zero.  In the event of an error, a value
of <CODE>-1</CODE> is returned.  The following <CODE>errno</CODE> error conditions
are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> is not a valid file descriptor.
<P>
<DT><CODE>ENOTTY</CODE>
<DD>The <VAR>filedes</VAR> is not associated with a terminal device.
<P>
<DT><CODE>EINTR</CODE>
<DD>The operation was interrupted by delivery of a signal.
See section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
</DL>
<P>
<A NAME="IDX1230"></A>
<A NAME="IDX1231"></A>
<P>
<A NAME="IDX1232"></A>
<U>Function:</U> int <B>tcflush</B> <I>(int <VAR>filedes</VAR>, int <VAR>queue</VAR>)</I><P>
The <CODE>tcflush</CODE> function is used to clear the input and/or output
queues associated with the terminal file <VAR>filedes</VAR>.  The <VAR>queue</VAR>
argument specifies which queue(s) to clear, and can be one of the
following values:
<P>
<A NAME="IDX1233"></A>
<DL COMPACT>
<DT><CODE>TCIFLUSH</CODE>
<DD><P>
Clear any input data received, but not yet read.
<A NAME="IDX1234"></A>
<P>
<DT><CODE>TCOFLUSH</CODE>
<DD><P>
Clear any output data written, but not yet transmitted.
<A NAME="IDX1235"></A>
<P>
<DT><CODE>TCIOFLUSH</CODE>
<DD><P>
Clear both queued input and output.
</DL>
<P>
The return value is normally zero.  In the event of an error, a value
of <CODE>-1</CODE> is returned.  The following <CODE>errno</CODE> error conditions
are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> is not a valid file descriptor.
<P>
<DT><CODE>ENOTTY</CODE>
<DD>The <VAR>filedes</VAR> is not associated with a terminal device.
<P>
<DT><CODE>EINVAL</CODE>
<DD>A bad value was supplied as the <VAR>queue</VAR> argument.
</DL>
<P>
It is unfortunate that this function is named <CODE>tcflush</CODE>, because
the term "flush" is normally used for quite another operation--waiting
until all output is transmitted--and using it for discarding input or
output would be confusing.  Unfortunately, the name <CODE>tcflush</CODE> comes
from POSIX and we cannot change it.
<P>
<A NAME="IDX1236"></A>
<A NAME="IDX1237"></A>
<P>
<A NAME="IDX1238"></A>
<U>Function:</U> int <B>tcflow</B> <I>(int <VAR>filedes</VAR>, int <VAR>action</VAR>)</I><P>
The <CODE>tcflow</CODE> function is used to perform operations relating to
XON/XOFF flow control on the terminal file specified by <VAR>filedes</VAR>.
<P>
The <VAR>action</VAR> argument specifies what operation to perform, and can
be one of the following values:
<P>
<A NAME="IDX1239"></A>
<DL COMPACT>
<DT><CODE>TCOOFF</CODE>
<DD>Suspend transmission of output.
<A NAME="IDX1240"></A>
<P>
<DT><CODE>TCOON</CODE>
<DD>Restart transmission of output.
<A NAME="IDX1241"></A>
<P>
<DT><CODE>TCIOFF</CODE>
<DD>Transmit a STOP character.
<A NAME="IDX1242"></A>
<P>
<DT><CODE>TCION</CODE>
<DD>Transmit a START character.
</DL>
<P>
For more information about the STOP and START characters, see section <A HREF="library.html#SEC281">Special Characters</A>.
<P>
The return value is normally zero.  In the event of an error, a value
of <CODE>-1</CODE> is returned.  The following <CODE>errno</CODE> error conditions
are defined for this function:
<P>
<A NAME="IDX1243"></A>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> is not a valid file descriptor.
<A NAME="IDX1244"></A>
<P>
<DT><CODE>ENOTTY</CODE>
<DD>The <VAR>filedes</VAR> is not associated with a terminal device.
<A NAME="IDX1245"></A>
<P>
<DT><CODE>EINVAL</CODE>
<DD>A bad value was supplied as the <VAR>action</VAR> argument.
</DL>
<P>
<H2><A NAME="SEC289" HREF="library_toc.html#SEC289">Noncanonical Mode Example</A></H2>
<P>
Here is an example program that shows how you can set up a terminal
device to read single characters in noncanonical input mode, without
echo.
<P>
<PRE>
#include &#60;unistd.h&#62;
#include &#60;stdio.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;termios.h&#62;

/* Use this variable to remember original terminal attributes.  */

struct termios saved_attributes;

void 
reset_input_mode (void)
{
  tcsetattr (STDIN_FILENO, TCSANOW, &#38;saved_attributes);
}

void 
set_input_mode (void)
{
  struct termios tattr;
  char *name;

  /* Make sure stdin is a terminal.  */
  if (!isatty (STDIN_FILENO))
    {
      fprintf (stderr, "Not a terminal.\n");
      exit (EXIT_FAILURE);
    }

  /* Save the terminal attributes so we can restore them later.  */
  tcgetattr (STDIN_FILENO, &#38;saved_attributes);
  atexit (reset_input_mode);

  /* Set the funny terminal modes.  */
  tcgetattr (STDIN_FILENO, &#38;tattr);
  tattr.c_lflag &#38;= ~(ICANON|ECHO); /* Clear ICANON and ECHO.   */
  tattr.c_cc[VMIN] = 1;
  tattr.c_cc[VTIME] = 0;
  tcsetattr (STDIN_FILENO, TCSAFLUSH, &#38;tattr);
}

int
main (void)
{
  char c;

  set_input_mode ();

  while (1)
    {
      read (STDIN_FILENO, &#38;c, 1);
      if (c == '\004')		/* <KBD>C-d</KBD>  */
	break;
      else
	putchar (c);
    }

  return EXIT_SUCCESS;
}
</PRE>
<P>
This program is careful to restore the original terminal modes before
exiting or terminating with a signal.  It uses the <CODE>atexit</CODE>
function (see section <A HREF="library.html#SEC398">Cleanups on Exit</A>) to make sure this is done
by <CODE>exit</CODE>.
<P>
The signals handled in the example are the ones that typically occur due
to actions of the user.  It might be desirable to handle other signals
such as SIGSEGV that can result from bugs in the program.
<P>
The shell is supposed to take care of resetting the terminal modes when
a process is stopped or continued; see section <A HREF="library.html#SEC411">Job Control</A>.  But some
existing shells do not actually do this, so you may wish to establish
handlers for job control signals that reset terminal modes.  The above
example does so.
<H1><A NAME="SEC290" HREF="library_toc.html#SEC290">Mathematics</A></H1>
<P>
This chapter contains information about functions for performing
mathematical computations, such as trigonometric functions.  Most of
these functions have prototypes declared in the header file
<TT>`math.h'</TT>.
<A NAME="IDX1246"></A>
<P>
All of the functions that operate on floating-point numbers accept
arguments and return results of type <CODE>double</CODE>.  In the future,
there may be additional functions that operate on <CODE>float</CODE> and
<CODE>long double</CODE> values.  For example, <CODE>cosf</CODE> and <CODE>cosl</CODE>
would be versions of the <CODE>cos</CODE> function that operate on
<CODE>float</CODE> and <CODE>long double</CODE> arguments, respectively.  In the
meantime, you should avoid using these names yourself.  See section <A HREF="library.html#SEC11">Reserved Names</A>.
<P>
<H2><A NAME="SEC291" HREF="library_toc.html#SEC291">Domain and Range Errors</A></H2>
<A NAME="IDX1247"></A>
<P>
Many of the functions listed in this chapter are defined mathematically
over a domain that is only a subset of real numbers.  For example, the
<CODE>acos</CODE> function is defined over the domain between <CODE>-1</CODE> and
<CODE>1</CODE>.  If you pass an argument to one of these functions that is
outside the domain over which it is defined, the function sets
<CODE>errno</CODE> to <CODE>EDOM</CODE> to indicate a <DFN>domain error</DFN>.  On
machines that support IEEE floating point, functions reporting error
<CODE>EDOM</CODE> also return a NaN.
<P>
Some of these functions are defined mathematically to result in a
complex value over parts of their domains.  The most familiar example of
this is taking the square root of a negative number.  The functions in
this chapter take only real arguments and return only real values;
therefore, if the value ought to be nonreal, this is treated as a domain
error.
<A NAME="IDX1248"></A>
<P>
A related problem is that the mathematical result of a function may not
be representable as a floating point number.  If magnitude of the
correct result is too large to be represented, the function sets
<CODE>errno</CODE> to <CODE>ERANGE</CODE> to indicate a <DFN>range error</DFN>, and
returns a particular very large value (named by the macro
<CODE>HUGE_VAL</CODE>) or its negation (<CODE>- HUGE_VAL</CODE>).
<P>
If the magnitude of the result is too small, a value of zero is returned
instead.  In this case, <CODE>errno</CODE> might or might not be
set to <CODE>ERANGE</CODE>.
<P>
The only completely reliable way to check for domain and range errors is
to set <CODE>errno</CODE> to <CODE>0</CODE> before you call the mathematical function 
and test <CODE>errno</CODE> afterward.  As a consequence of this use of 
<CODE>errno</CODE>, use of the mathematical functions is not reentrant if you
check for errors.
<P>
None of the mathematical functions ever generates signals as a result of
domain or range errors.  In particular, this means that you won't see
<CODE>SIGFPE</CODE> signals generated within these functions.  (See section <A HREF="library.html#SEC330">Signal Handling</A>, for more information about signals.)
<P>
<A NAME="IDX1249"></A>
<U>Macro:</U> double <B>HUGE_VAL</B><P>
An expression representing a particular very large number.  On machines
that use IEEE floating point format, the value is "infinity".  On
other machines, it's typically the largest positive number that can be
represented.
<P>
The value of this macro is used as the return value from various 
mathematical functions in overflow situations.
<P>
For more information about floating-point representations and limits,
see section <A HREF="library.html#SEC489">Floating Point Parameters</A>.  In particular, the macro
<CODE>DBL_MAX</CODE> might be more appropriate than <CODE>HUGE_VAL</CODE> for many
uses other than testing for an error in a mathematical function.
<P>
<A NAME="IDX1250"></A>
<H2><A NAME="SEC292" HREF="library_toc.html#SEC292">Trigonometric Functions</A></H2>
<P>
These are the familiar <CODE>sin</CODE>, <CODE>cos</CODE>, and <CODE>tan</CODE> functions.
The arguments to all of these functions are in units of radians; recall
that pi radians equals 180 degrees.
<A NAME="IDX1251"></A>
<P>
The math library doesn't define a symbolic constant for pi, but you can
define your own if you need one:
<P>
<PRE>
#define PI 3.14159265358979323846264338327
</PRE>
<P>
You can also compute the value of pi with the expression <CODE>acos
(-1.0)</CODE>.
<P>
<A NAME="IDX1252"></A>
<U>Function:</U> double <B>sin</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns the sine of <VAR>x</VAR>, where <VAR>x</VAR> is given in
radians.  The return value is in the range <CODE>-1</CODE> to <CODE>1</CODE>.
<P>
<A NAME="IDX1253"></A>
<U>Function:</U> double <B>cos</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns the cosine of <VAR>x</VAR>, where <VAR>x</VAR> is given in
radians.  The return value is in the range <CODE>-1</CODE> to <CODE>1</CODE>.
<P>
<A NAME="IDX1254"></A>
<U>Function:</U> double <B>tan</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns the tangent of <VAR>x</VAR>, where <VAR>x</VAR> is given in
radians.
<P>
The following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>ERANGE</CODE>
<DD>Mathematically, the tangent function has singularities at odd multiples
of pi/2.  If the argument <VAR>x</VAR> is too close to one of these
singularities, <CODE>tan</CODE> sets <CODE>errno</CODE> to <CODE>ERANGE</CODE> and returns
either positive or negative <CODE>HUGE_VAL</CODE>.
</DL>
<P>
<A NAME="IDX1255"></A>
<H2><A NAME="SEC293" HREF="library_toc.html#SEC293">Inverse Trigonometric Functions</A></H2>
<P>
These are the usual arc sine, arc cosine and arc tangent functions,
which are the inverses of the sine, cosine and tangent functions,
respectively.
<P>
<A NAME="IDX1256"></A>
<U>Function:</U> double <B>asin</B> <I>(double <VAR>x</VAR>)</I><P>
This function computes the arc sine of <VAR>x</VAR>---that is, the value whose
sine is <VAR>x</VAR>.  The value is in units of radians.  Mathematically,
there are infinitely many such values; the one actually returned is the
one between <CODE>-pi/2</CODE> and <CODE>pi/2</CODE> (inclusive).
<P>
<CODE>asin</CODE> fails, and sets <CODE>errno</CODE> to <CODE>EDOM</CODE>, if <VAR>x</VAR> is
out of range.  The arc sine function is defined mathematically only
over the domain <CODE>-1</CODE> to <CODE>1</CODE>.
<P>
<A NAME="IDX1257"></A>
<U>Function:</U> double <B>acos</B> <I>(double <VAR>x</VAR>)</I><P>
This function computes the arc cosine of <VAR>x</VAR>---that is, the value
whose cosine is <VAR>x</VAR>.  The value is in units of radians.
Mathematically, there are infinitely many such values; the one actually
returned is the one between <CODE>0</CODE> and <CODE>pi</CODE> (inclusive).
<P>
<CODE>acos</CODE> fails, and sets <CODE>errno</CODE> to <CODE>EDOM</CODE>, if <VAR>x</VAR> is
out of range.  The arc cosine function is defined mathematically only
over the domain <CODE>-1</CODE> to <CODE>1</CODE>.
<P>
<A NAME="IDX1258"></A>
<U>Function:</U> double <B>atan</B> <I>(double <VAR>x</VAR>)</I><P>
This function computes the arc tangent of <VAR>x</VAR>---that is, the value
whose tangent is <VAR>x</VAR>.  The value is in units of radians.
Mathematically, there are infinitely many such values; the one actually
returned is the one between <CODE>-pi/2</CODE> and <CODE>pi/2</CODE>
(inclusive).
<P>
<A NAME="IDX1259"></A>
<U>Function:</U> double <B>atan2</B> <I>(double <VAR>y</VAR>, double <VAR>x</VAR>)</I><P>
This is the two argument arc tangent function.  It is similar to computing
the arc tangent of <VAR>y</VAR>/<VAR>x</VAR>, except that the signs of both arguments
are used to determine the quadrant of the result, and <VAR>x</VAR> is
permitted to be zero.  The return value is given in radians and is in
the range <CODE>-pi</CODE> to <CODE>pi</CODE>, inclusive.
<P>
If <VAR>x</VAR> and <VAR>y</VAR> are coordinates of a point in the plane,
<CODE>atan2</CODE> returns the signed angle between the line from the origin
to that point and the x-axis.  Thus, <CODE>atan2</CODE> is useful for
converting Cartesian coordinates to polar coordinates.  (To compute the
radial coordinate, use <CODE>hypot</CODE>; see section <A HREF="library.html#SEC294">Exponentiation and Logarithms</A>.)
<P>
The function <CODE>atan2</CODE> sets <CODE>errno</CODE> to <CODE>EDOM</CODE> if both
<VAR>x</VAR> and <VAR>y</VAR> are zero; the return value is not defined in this
case.
<P>
<A NAME="IDX1260"></A>
<A NAME="IDX1261"></A>
<A NAME="IDX1262"></A>
<H2><A NAME="SEC294" HREF="library_toc.html#SEC294">Exponentiation and Logarithms</A></H2>
<P>
<A NAME="IDX1263"></A>
<U>Function:</U> double <B>exp</B> <I>(double <VAR>x</VAR>)</I><P>
The <CODE>exp</CODE> function returns the value of e (the base of natural
logarithms) raised to power <VAR>x</VAR>.
<P>
The function fails, and sets <CODE>errno</CODE> to <CODE>ERANGE</CODE>, if the
magnitude of the result is too large to be representable.
<P>
<A NAME="IDX1264"></A>
<U>Function:</U> double <B>log</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns the natural logarithm of <VAR>x</VAR>.  <CODE>exp (log
(<VAR>x</VAR>))</CODE> equals <VAR>x</VAR>, exactly in mathematics and approximately in
C.
<P>
The following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EDOM</CODE>
<DD>The argument <VAR>x</VAR> is negative.  The log function is defined
mathematically to return a real result only on positive arguments.
<P>
<DT><CODE>ERANGE</CODE>
<DD>The argument is zero.  The log of zero is not defined.
</DL>
<P>
<A NAME="IDX1265"></A>
<U>Function:</U> double <B>log10</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns the base-10 logarithm of <VAR>x</VAR>.  Except for the
different base, it is similar to the <CODE>log</CODE> function.  In fact,
<CODE>log10 (<VAR>x</VAR>)</CODE> equals <CODE>log (<VAR>x</VAR>) / log (10)</CODE>.
<P>
<A NAME="IDX1266"></A>
<U>Function:</U> double <B>pow</B> <I>(double <VAR>base</VAR>, double <VAR>power</VAR>)</I><P>
This is a general exponentiation function, returning <VAR>base</VAR> raised
to <VAR>power</VAR>.
<P>
The following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EDOM</CODE>
<DD>The argument <VAR>base</VAR> is negative and <VAR>power</VAR> is not an integral
value.  Mathematically, the result would be a complex number in this case.
<P>
<DT><CODE>ERANGE</CODE>
<DD>An underflow or overflow condition was detected in the result.
</DL>
<P>
<A NAME="IDX1267"></A>
<P>
<A NAME="IDX1268"></A>
<U>Function:</U> double <B>sqrt</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns the nonnegative square root of <VAR>x</VAR>.
<P>
The <CODE>sqrt</CODE> function fails, and sets <CODE>errno</CODE> to <CODE>EDOM</CODE>, if
<VAR>x</VAR> is negative.  Mathematically, the square root would be a complex
number.
<P>
<A NAME="IDX1269"></A>
<P>
<A NAME="IDX1270"></A>
<U>Function:</U> double <B>cbrt</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns the cube root of <VAR>x</VAR>.  This function cannot
fail; every representable real value has a represetable real cube root.
<P>
<A NAME="IDX1271"></A>
<U>Function:</U> double <B>hypot</B> <I>(double <VAR>x</VAR>, double <VAR>y</VAR>)</I><P>
The <CODE>hypot</CODE> function returns <CODE>sqrt (<VAR>x</VAR>*<VAR>x</VAR> +
<VAR>y</VAR>*<VAR>y</VAR>)</CODE>.  (This is the length of the hypotenuse of a right
triangle with sides of length <VAR>x</VAR> and <VAR>y</VAR>, or the distance
of the point (<VAR>x</VAR>, <VAR>y</VAR>) from the origin.)  See also the function
<CODE>cabs</CODE> in section <A HREF="library.html#SEC302">Absolute Value</A>.
<P>
<A NAME="IDX1272"></A>
<U>Function:</U> double <B>expm1</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns a value equivalent to <CODE>exp (<VAR>x</VAR>) - 1</CODE>.
It is computed in a way that is accurate even if the value of <VAR>x</VAR> is
near zero--a case where <CODE>exp (<VAR>x</VAR>) - 1</CODE> would be inaccurate due
to subtraction of two numbers that are nearly equal.
<P>
<A NAME="IDX1273"></A>
<U>Function:</U> double <B>log1p</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns a value equivalent to <CODE>log (1 + <VAR>x</VAR>)</CODE>.
It is computed in a way that is accurate even if the value of <VAR>x</VAR> is
near zero.
<P>
<A NAME="IDX1274"></A>
<H2><A NAME="SEC295" HREF="library_toc.html#SEC295">Hyperbolic Functions</A></H2>
<P>
The functions in this section are related to the exponential functions;
see section <A HREF="library.html#SEC294">Exponentiation and Logarithms</A>.
<P>
<A NAME="IDX1275"></A>
<U>Function:</U> double <B>sinh</B> <I>(double <VAR>x</VAR>)</I><P>
The <CODE>sinh</CODE> function returns the hyperbolic sine of <VAR>x</VAR>, defined
mathematically as <CODE>exp (<VAR>x</VAR>) - exp (-<VAR>x</VAR>) / 2</CODE>.  The
function fails, and sets <CODE>errno</CODE> to <CODE>ERANGE</CODE>, if the value of
<VAR>x</VAR> is too large; that is, if overflow occurs.
<P>
<A NAME="IDX1276"></A>
<U>Function:</U> double <B>cosh</B> <I>(double <VAR>x</VAR>)</I><P>
The <CODE>cosh</CODE> function returns the hyperbolic cosine of <VAR>x</VAR>,
defined mathematically as <CODE>exp (<VAR>x</VAR>) + exp (-<VAR>x</VAR>) / 2</CODE>.
The function fails, and sets <CODE>errno</CODE> to <CODE>ERANGE</CODE>, if the value
of <VAR>x</VAR> is too large; that is, if overflow occurs.
<P>
<A NAME="IDX1277"></A>
<U>Function:</U> double <B>tanh</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns the hyperbolic tangent of <VAR>x</VAR>, whose 
mathematical definition is <CODE>sinh (<VAR>x</VAR>) / cosh (<VAR>x</VAR>)</CODE>.
<P>
<A NAME="IDX1278"></A>
<P>
<A NAME="IDX1279"></A>
<U>Function:</U> double <B>asinh</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns the inverse hyperbolic sine of <VAR>x</VAR>---the
value whose hyperbolic sine is <VAR>x</VAR>.
<P>
<A NAME="IDX1280"></A>
<U>Function:</U> double <B>acosh</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns the inverse hyperbolic cosine of <VAR>x</VAR>---the
value whose hyperbolic cosine is <VAR>x</VAR>.  If <VAR>x</VAR> is less than
<CODE>1</CODE>, <CODE>acosh</CODE> returns <CODE>HUGE_VAL</CODE>.
<P>
<A NAME="IDX1281"></A>
<U>Function:</U> double <B>atanh</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns the inverse hyperbolic tangent of <VAR>x</VAR>---the
value whose hyperbolic tangent is <VAR>x</VAR>.  If the absolute value of
<VAR>x</VAR> is greater than or equal to <CODE>1</CODE>, <CODE>atanh</CODE> returns
<CODE>HUGE_VAL</CODE>.
<P>
<A NAME="IDX1282"></A>
<A NAME="IDX1283"></A>
<A NAME="IDX1284"></A>
<H2><A NAME="SEC296" HREF="library_toc.html#SEC296">Pseudo-Random Numbers</A></H2>
<P>
This section describes the GNU facilities for generating a series of
pseudo-random numbers.  The numbers generated are not truly random;
typically, they form a sequence that repeats periodically, with a
period so large that you can ignore it for ordinary purposes.  The
random number generator works by remembering at all times a <DFN>seed</DFN>
value which it uses to compute the next random number and also to
compute a new seed.
<P>
Although the generated numbers look unpredictable within one run of a
program, the sequence of numbers is <EM>exactly the same</EM> from one run
to the next.  This is because the initial seed is always the same.  This
is convenient when you are debugging a program, but it is unhelpful if
you want the program to behave unpredictably.  If you want truly random
numbers, not just pseudo-random, specify a seed based on the current
time.
<P>
You can get repeatable sequences of numbers on a particular machine type
by specifying the same initial seed value for the random number
generator.  There is no standard meaning for a particular seed value;
the same seed, used in different C libraries or on different CPU types,
will give you different random numbers.
<P>
The GNU library supports the standard ANSI C random number functions
plus another set derived from BSD.  We recommend you use the standard
ones, <CODE>rand</CODE> and <CODE>srand</CODE>.
<P>
<H3><A NAME="SEC297" HREF="library_toc.html#SEC297">ANSI C Random Number Functions</A></H3>
<P>
This section describes the random number functions that are part of
the ANSI C standard.
<P>
To use these facilities, you should include the header file
<TT>`stdlib.h'</TT> in your program.
<A NAME="IDX1285"></A>
<P>
<A NAME="IDX1286"></A>
<U>Macro:</U> int <B>RAND_MAX</B><P>
The value of this macro is an integer constant expression that
represents the maximum possible value returned by the <CODE>rand</CODE>
function.  In the GNU library, it is <CODE>037777777</CODE>, which is the
largest signed integer representable in 32 bits.  In other libraries, it
may be as low as <CODE>32767</CODE>.
<P>
<A NAME="IDX1287"></A>
<U>Function:</U> int <B>rand</B> <I>()</I><P>
The <CODE>rand</CODE> function returns the next pseudo-random number in the
series.  The value is in the range from <CODE>0</CODE> to <CODE>RAND_MAX</CODE>.
<P>
<A NAME="IDX1288"></A>
<U>Function:</U> void <B>srand</B> <I>(unsigned int <VAR>seed</VAR>)</I><P>
This function establishes <VAR>seed</VAR> as the seed for a new series of
pseudo-random numbers.  If you call <CODE>rand</CODE> before a seed has been
established with <CODE>srand</CODE>, it uses the value <CODE>1</CODE> as a default
seed.
<P>
To produce truly random numbers (not just pseudo-random), do <CODE>srand
(time (0))</CODE>.
<P>
<H3><A NAME="SEC298" HREF="library_toc.html#SEC298">BSD Random Number Functions</A></H3>
<P>
This section describes a set of random number generation functions that
are derived from BSD.  There is no advantage to using these functions
with the GNU C library; we support them for BSD compatibility only.
<P>
The prototypes for these functions are in <TT>`stdlib.h'</TT>.
<A NAME="IDX1289"></A>
<P>
<A NAME="IDX1290"></A>
<U>Function:</U> long int <B>random</B> <I>()</I><P>
This function returns the next pseudo-random number in the sequence.
The range of values returned is from <CODE>0</CODE> to <CODE>RAND_MAX</CODE>.
<P>
<A NAME="IDX1291"></A>
<U>Function:</U> void <B>srandom</B> <I>(unsigned int <VAR>seed</VAR>)</I><P>
The <CODE>srandom</CODE> function sets the seed for the current random number
state based on the integer <VAR>seed</VAR>.  If you supply a <VAR>seed</VAR> value
of <CODE>1</CODE>, this will cause <CODE>random</CODE> to reproduce the default set
of random numbers.
<P>
To produce truly random numbers (not just pseudo-random), do
<CODE>srandom (time (0))</CODE>.
<P>
<A NAME="IDX1292"></A>
<U>Function:</U> void * <B>initstate</B> <I>(unsigned int <VAR>seed</VAR>, void *<VAR>state</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>initstate</CODE> function is used to initialize the random number
generator state.  The argument <VAR>state</VAR> is an array of <VAR>size</VAR>
bytes, used to hold the state information.  The size must be at least 8
bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The bigger
the <VAR>state</VAR> array, the better.
<P>
The return value is the previous value of the state information array.
You can use this value later as an argument to <CODE>setstate</CODE> to
restore that state.
<P>
<A NAME="IDX1293"></A>
<U>Function:</U> void * <B>setstate</B> <I>(void *<VAR>state</VAR>)</I><P>
The <CODE>setstate</CODE> function restores the random number state
information <VAR>state</VAR>.  The argument must have been the result of
a previous call to <VAR>initstate</VAR> or <VAR>setstate</VAR>.  
<P>
The return value is the previous value of the state information array.
You can use thise value later as an argument to <CODE>setstate</CODE> to
restore that state.
<P>
<H1><A NAME="SEC299" HREF="library_toc.html#SEC299">Low-Level Arithmetic Functions</A></H1>
<P>
This chapter contains information about functions for doing basic
arithmetic operations, such as splitting a float into its integer and
fractional parts.  These functions are declared in the header file
<TT>`math.h'</TT>.
<P>
<A NAME="IDX1294"></A>
<A NAME="IDX1295"></A>
<A NAME="IDX1296"></A>
<H2><A NAME="SEC300" HREF="library_toc.html#SEC300">"Not a Number" Values</A></H2>
<P>
The IEEE floating point format used by most modern computers supports
values that are "not a number".  These values are called <DFN>NaNs</DFN>.
"Not a number" values result from certain operations which have no
meaningful numeric result, such as zero divided by zero or infinity
divided by infinity.
<P>
One noteworthy property of NaNs is that they are not equal to
themselves.  Thus, <CODE>x == x</CODE> can be 0 if the value of <CODE>x</CODE> is a
NaN.  You can use this to test whether a value is a NaN or not: if it is
not equal to itself, then it is a NaN.  But the recommended way to test
for a NaN is with the <CODE>isnan</CODE> function (see section <A HREF="library.html#SEC301">Predicates on Floats</A>).
<P>
Almost any arithmetic operation in which one argument is a NaN returns
a NaN.
<P>
<A NAME="IDX1297"></A>
<U>Macro:</U> double <B>NAN</B><P>
An expression representing a value which is "not a number".  This
macro is a GNU extension, available only on machines that support "not
a number" values--that is to say, on all machines that support IEEE
floating point.
<P>
You can use <SAMP>`#ifdef NAN'</SAMP> to test whether the machine supports
NaNs.  (Of course, you must arrange for GNU extensions to be visible,
such as by defining <CODE>_GNU_SOURCE</CODE>, and then you must include
<TT>`math.h'</TT>.)
<P>
<H2><A NAME="SEC301" HREF="library_toc.html#SEC301">Predicates on Floats</A></H2>
<A NAME="IDX1298"></A>
<P>
This section describes some miscellaneous test functions on doubles.
Prototypes for these functions appear in <TT>`math.h'</TT>.  These are BSD
functions, and thus are available if you define <CODE>_BSD_SOURCE</CODE> or
<CODE>_GNU_SOURCE</CODE>.
<P>
<A NAME="IDX1299"></A>
<U>Function:</U> int <B>isinf</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns <CODE>-1</CODE> if <VAR>x</VAR> represents negative infinity,
<CODE>1</CODE> if <VAR>x</VAR> represents positive infinity, and <CODE>0</CODE> otherwise.
<P>
<A NAME="IDX1300"></A>
<U>Function:</U> int <B>isnan</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns a nonzero value if <VAR>x</VAR> is a "not a number"
value, and zero otherwise.  (You can just as well use <CODE><VAR>x</VAR> !=
<VAR>x</VAR></CODE> to get the same result).
<P>
<A NAME="IDX1301"></A>
<U>Function:</U> int <B>finite</B> <I>(double <VAR>x</VAR>)</I><P>
This function returns a nonzero value if <VAR>x</VAR> is finite or a "not a
number" value, and zero otherwise.
<P>
<A NAME="IDX1302"></A>
<U>Function:</U> double <B>infnan</B> <I>(int <VAR>error</VAR>)</I><P>
This function is provided for compatibility with BSD.  The other
mathematical functions use <CODE>infnan</CODE> to decide what to return on
occasion of an error.  Its argument is an error code, <CODE>EDOM</CODE> or
<CODE>ERANGE</CODE>; <CODE>infnan</CODE> returns a suitable value to indicate this
with.  <CODE>-ERANGE</CODE> is also acceptable as an argument, and corresponds
to <CODE>-HUGE_VAL</CODE> as a value.
<P>
In the BSD library, on certain machines, <CODE>infnan</CODE> raises a fatal
signal in all cases.  The GNU library does not do likewise, because that
does not fit the ANSI C specification.
<P>
<STRONG>Portability Note:</STRONG> The functions listed in this section are BSD
extensions.
<P>
<A NAME="IDX1303"></A>
<H2><A NAME="SEC302" HREF="library_toc.html#SEC302">Absolute Value</A></H2>
<P>
These functions are provided for obtaining the <DFN>absolute value</DFN> (or
<DFN>magnitude</DFN>) of a number.  The absolute value of a real number
<VAR>x</VAR> is <VAR>x</VAR> is <VAR>x</VAR> is positive, -<VAR>x</VAR> if <VAR>x</VAR> is
negative.  For a complex number <VAR>z</VAR>, whose real part is <VAR>x</VAR> and
whose imaginary part is <VAR>y</VAR>, the absolute value is <CODE>sqrt
(<VAR>x</VAR>*<VAR>x</VAR> + <VAR>y</VAR>*<VAR>y</VAR>)</CODE>.
<A NAME="IDX1304"></A>
<A NAME="IDX1305"></A>
<P>
Prototypes for <CODE>abs</CODE> and <CODE>labs</CODE> are in <TT>`stdlib.h'</TT>;
<CODE>fabs</CODE> and <CODE>cabs</CODE> are declared in <TT>`math.h'</TT>.
<P>
<A NAME="IDX1306"></A>
<U>Function:</U> int <B>abs</B> <I>(int <VAR>number</VAR>)</I><P>
This function returns the absolute value of <VAR>number</VAR>.
<P>
Most computers use a two's complement integer representation, in which
the absolute value of <CODE>INT_MIN</CODE> (the smallest possible <CODE>int</CODE>)
cannot be represented; thus, <CODE>abs (INT_MIN)</CODE> is not defined.
<P>
<A NAME="IDX1307"></A>
<U>Function:</U> long int <B>labs</B> <I>(long int <VAR>number</VAR>)</I><P>
This is similar to <CODE>abs</CODE>, except that both the argument and result
are of type <CODE>long int</CODE> rather than <CODE>int</CODE>.
<P>
<A NAME="IDX1308"></A>
<U>Function:</U> double <B>fabs</B> <I>(double <VAR>number</VAR>)</I><P>
This function returns the absolute value of the floating-point number
<VAR>number</VAR>.
<P>
<A NAME="IDX1309"></A>
<U>Function:</U> double <B>cabs</B> <I>(struct { double real, imag; } <VAR>z</VAR>)</I><P>
The <CODE>cabs</CODE> function returns the absolute value of the complex
number <VAR>z</VAR>, whose real part is <CODE><VAR>z</VAR>.real</CODE> and whose
imaginary part is <CODE><VAR>z</VAR>.imag</CODE>.  (See also the function
<CODE>hypot</CODE> in section <A HREF="library.html#SEC294">Exponentiation and Logarithms</A>.)  The value is:
<P>
<PRE>
sqrt (<VAR>z</VAR>.real*<VAR>z</VAR>.real + <VAR>z</VAR>.imag*<VAR>z</VAR>.imag)
</PRE>
<P>
<A NAME="IDX1310"></A>
<H2><A NAME="SEC303" HREF="library_toc.html#SEC303">Normalization Functions</A></H2>
<P>
The functions described in this section are primarily provided as a way
to efficiently perform certain low-level manipulations on floating point
numbers that are represented internally using a binary radix;
see section <A HREF="library.html#SEC488">Floating Point Representation Concepts</A>.  These functions are required to
have equivalent behavior even if the representation does not use a radix
of 2, but of course they are unlikely to be particularly efficient in
those cases.
<A NAME="IDX1311"></A>
<P>
All these functions are declared in <TT>`math.h'</TT>.
<P>
<A NAME="IDX1312"></A>
<U>Function:</U> double <B>frexp</B> <I>(double <VAR>value</VAR>, int *<VAR>exponent</VAR>)</I><P>
The <CODE>frexp</CODE> function is used to split the number <VAR>value</VAR>
into a normalized fraction and an exponent.
<P>
If the argument <VAR>value</VAR> is not zero, the return value is <VAR>value</VAR>
times a power of two, and is always in the range 1/2 (inclusive) to 1
(exclusive).  The corresponding exponent is stored in
<CODE>*<VAR>exponent</VAR></CODE>; the return value multiplied by 2 raised to this
exponent equals the original number <VAR>value</VAR>.
<P>
For example, <CODE>frexp (12.8, &#38;exponent)</CODE> returns <CODE>0.8</CODE> and
stores <CODE>4</CODE> in <CODE>exponent</CODE>.
<P>
If <VAR>value</VAR> is zero, then the return value is zero and
zero is stored in <CODE>*<VAR>exponent</VAR></CODE>.
<P>
<A NAME="IDX1313"></A>
<U>Function:</U> double <B>ldexp</B> <I>(double <VAR>value</VAR>, int <VAR>exponent</VAR>)</I><P>
This function returns the result of multiplying the floating-point
number <VAR>value</VAR> by 2 raised to the power <VAR>exponent</VAR>.  (It can
be used to reassemble floating-point numbers that were taken apart
by <CODE>frexp</CODE>.)
<P>
For example, <CODE>ldexp (0.8, 4)</CODE> returns <CODE>12.8</CODE>.
<P>
The following functions which come from BSD provide facilities
equivalent to those of <CODE>ldexp</CODE> and <CODE>frexp</CODE>:
<P>
<A NAME="IDX1314"></A>
<U>Function:</U> double <B>scalb</B> <I>(double <VAR>value</VAR>, int <VAR>exponent</VAR>)</I><P>
The <CODE>scalb</CODE> function is the BSD name for <CODE>ldexp</CODE>.
<P>
<A NAME="IDX1315"></A>
<U>Function:</U> double <B>logb</B> <I>(double <VAR>x</VAR>)</I><P>
This BSD function returns the integer part of the base-2 logarithm of
<VAR>x</VAR>, an integer value represented in type <CODE>double</CODE>.  This is
the highest integer power of <CODE>2</CODE> contained in <VAR>x</VAR>.  The sign of
<VAR>x</VAR> is ignored.  For example, <CODE>logb (3.5)</CODE> is <CODE>1.0</CODE> and
<CODE>logb (4.0)</CODE> is <CODE>2.0</CODE>.
<P>
When <CODE>2</CODE> raised to this power is divided into <VAR>x</VAR>, it gives a
quotient between <CODE>1</CODE> (inclusive) and <CODE>2</CODE> (exclusive).
<P>
If <VAR>x</VAR> is zero, the value is minus infinity (if the machine supports
such a value), or else a very small number.  If <VAR>x</VAR> is infinity, the
value is infinity.
<P>
The value returned by <CODE>logb</CODE> is one less than the value that
<CODE>frexp</CODE> would store into <CODE>*<VAR>exponent</VAR></CODE>.
<P>
<A NAME="IDX1316"></A>
<U>Function:</U> double <B>copysign</B> <I>(double <VAR>value</VAR>, double <VAR>sign</VAR>)</I><P>
The <CODE>copysign</CODE> function returns a value whose absolute value is the
same as that of <VAR>value</VAR>, and whose sign matches that of <VAR>sign</VAR>.
This is a BSD function.
<P>
<A NAME="IDX1317"></A>
<A NAME="IDX1318"></A>
<A NAME="IDX1319"></A>
<H2><A NAME="SEC304" HREF="library_toc.html#SEC304">Rounding and Remainder Functions</A></H2>
<A NAME="IDX1320"></A>
<P>
The functions listed here perform operations such as rounding,
truncation, and remainder in division of floating point numbers.  Some
of these functions convert floating point numbers to integer values.
They are all declared in <TT>`math.h'</TT>.
<P>
You can also convert floating-point numbers to integers simply by
casting them to <CODE>int</CODE>.  This discards the fractional part,
effectively rounding towards zero.  However, this only works if the
result can actually be represented as an <CODE>int</CODE>---for very large
numbers, this is impossible.  The functions listed here return the
result as a <CODE>double</CODE> instead to get around this problem.
<P>
<A NAME="IDX1321"></A>
<U>Function:</U> double <B>ceil</B> <I>(double <VAR>x</VAR>)</I><P>
The <CODE>ceil</CODE> function rounds <VAR>x</VAR> upwards to the nearest integer,
returning that value as a <CODE>double</CODE>.  Thus, <CODE>ceil (1.5)</CODE>
is <CODE>2.0</CODE>.
<P>
<A NAME="IDX1322"></A>
<U>Function:</U> double <B>floor</B> <I>(double <VAR>x</VAR>)</I><P>
The <CODE>ceil</CODE> function rounds <VAR>x</VAR> downwards to the nearest
integer, returning that value as a <CODE>double</CODE>.  Thus, <CODE>floor
(1.5)</CODE> is <CODE>1.0</CODE> and <CODE>floor (-1.5)</CODE> is <CODE>-2.0</CODE>.
<P>
<A NAME="IDX1323"></A>
<U>Function:</U> double <B>rint</B> <I>(double <VAR>x</VAR>)</I><P>
This function rounds <VAR>x</VAR> to an integer value according to the
current rounding mode.  See section <A HREF="library.html#SEC489">Floating Point Parameters</A>, for
information about the various rounding modes.  The default
rounding mode is to round to the nearest integer; some machines
support other modes, but round-to-nearest is always used unless
you explicit select another.
<P>
<A NAME="IDX1324"></A>
<U>Function:</U> double <B>modf</B> <I>(double <VAR>value</VAR>, double *<VAR>integer_part</VAR>)</I><P>
This function breaks the argument <VAR>value</VAR> into an integer part and a
fractional part (between <CODE>-1</CODE> and <CODE>1</CODE>, exclusive).  Their sum
equals <VAR>value</VAR>.  Each of the parts has the same sign as <VAR>value</VAR>,
so the rounding of the integer part is towards zero.
<P>
<CODE>modf</CODE> stores the integer part in <CODE>*<VAR>integer_part</VAR></CODE>, and
returns the fractional part.  For example, <CODE>modf (2.5, &#38;intpart)</CODE>
returns <CODE>0.5</CODE> and stores <CODE>2.0</CODE> into <CODE>intpart</CODE>.
<P>
<A NAME="IDX1325"></A>
<U>Function:</U> double <B>fmod</B> <I>(double <VAR>numerator</VAR>, double <VAR>denominator</VAR>)</I><P>
This function computes the remainder of dividing <VAR>numerator</VAR> by
<VAR>denominator</VAR>.  Specifically, the return value is
<CODE><VAR>numerator</VAR> - <VAR>n</VAR> * <VAR>denominator</VAR></CODE>, where <VAR>n</VAR>
is the quotient of <VAR>numerator</VAR> divided by <VAR>denominator</VAR>, rounded
towards zero to an integer.  Thus, <CODE>fmod (6.5, 2.3)</CODE> returns
<CODE>1.9</CODE>, which is <CODE>6.5</CODE> minus <CODE>4.6</CODE>.
<P>
The result has the same sign as the <VAR>numerator</VAR> and has magnitude
less than the magnitude of the <VAR>denominator</VAR>.
<P>
If <VAR>denominator</VAR> is zero, <CODE>fmod</CODE> fails and sets <CODE>errno</CODE> to
<CODE>EDOM</CODE>.
<P>
<A NAME="IDX1326"></A>
<U>Function:</U> double <B>drem</B> <I>(double <VAR>numerator</VAR>, double <VAR>denominator</VAR>)</I><P>
The function <CODE>drem</CODE> is like <CODE>fmod</CODE> except that it rounds the
internal quotient <VAR>n</VAR> to the nearest integer instead of towards zero
to an integer.  For example, <CODE>drem (6.5, 2.3)</CODE> returns <CODE>-0.4</CODE>,
which is <CODE>6.5</CODE> minus <CODE>6.9</CODE>.
<P>
The absolute value of the result is less than or equal to half the
absolute value of the <VAR>denominator</VAR>.  The difference between
<CODE>fmod (<VAR>numerator</VAR>, <VAR>denominator</VAR>)</CODE> and <CODE>drem
(<VAR>numerator</VAR>, <VAR>denominator</VAR>)</CODE> is always either
<VAR>denominator</VAR>, minus <VAR>denominator</VAR>, or zero.
<P>
If <VAR>denominator</VAR> is zero, <CODE>drem</CODE> fails and sets <CODE>errno</CODE> to
<CODE>EDOM</CODE>.
<P>
<A NAME="IDX1327"></A>
<H2><A NAME="SEC305" HREF="library_toc.html#SEC305">Integer Division</A></H2>
<P>
This section describes functions for performing integer division.  These
functions are redundant in the GNU C library, since in GNU C the <SAMP>`/'</SAMP>
operator always rounds towards zero.  But in other C implementations,
<SAMP>`/'</SAMP> may round differently with negative arguments.  <CODE>div</CODE> and
<CODE>ldiv</CODE> are useful because they specify how to round the quotient:
towards zero.  The remainder has the same sign as the numerator.
<P>
These functions are specified to return a result <VAR>r</VAR> such that
<CODE><VAR>r</VAR>.quot*<VAR>denominator</VAR> + <VAR>r</VAR>.rem</CODE> equals
<VAR>numerator</VAR>.
<A NAME="IDX1328"></A>
<P>
To use these facilities, you should include the header file
<TT>`stdlib.h'</TT> in your program.
<P>
<A NAME="IDX1329"></A>
<U>Data Type:</U> <B>div_t</B><P>
This is a structure type used to hold the result returned by the <CODE>div</CODE>
function.  It has the following members:
<P>
<DL COMPACT>
<DT><CODE>int quot</CODE>
<DD>The quotient from the division.
<P>
<DT><CODE>int rem</CODE>
<DD>The remainder from the division.
</DL>
<P>
<A NAME="IDX1330"></A>
<U>Function:</U> div_t <B>div</B> <I>(int <VAR>numerator</VAR>, int <VAR>denominator</VAR>)</I><P>
This function <CODE>div</CODE> computes the quotient and remainder from
the division of <VAR>numerator</VAR> by <VAR>denominator</VAR>, returning the
result in a structure of type <CODE>div_t</CODE>.
<P>
If the result cannot be represented (as in a division by zero), the
behavior is undefined.
<P>
Here is an example, albeit not a very useful one.
<P>
<PRE>
div_t result;
result = div (20, -6);
</PRE>
<P>
Now <CODE>result.quot</CODE> is <CODE>-3</CODE> and <CODE>result.rem</CODE> is <CODE>2</CODE>.
<P>
<A NAME="IDX1331"></A>
<U>Data Type:</U> <B>ldiv_t</B><P>
This is a structure type used to hold the result returned by the <CODE>ldiv</CODE>
function.  It has the following members:
<P>
<DL COMPACT>
<DT><CODE>long int quot</CODE>
<DD>The quotient from the division.
<P>
<DT><CODE>long int rem</CODE>
<DD>The remainder from the division.
</DL>
<P>
(This is identical to <CODE>div_t</CODE> except that the components are of
type <CODE>long int</CODE> rather than <CODE>int</CODE>.)
<P>
<A NAME="IDX1332"></A>
<U>Function:</U> ldiv_t <B>ldiv</B> <I>(long int <VAR>numerator</VAR>, long int <VAR>denominator</VAR>)</I><P>
The <CODE>ldiv</CODE> function is similar to <CODE>div</CODE>, except that the
arguments are of type <CODE>long int</CODE> and the result is returned as a
structure of type <CODE>ldiv</CODE>.
<P>
<A NAME="IDX1333"></A>
<A NAME="IDX1334"></A>
<A NAME="IDX1335"></A>
<A NAME="IDX1336"></A>
<H2><A NAME="SEC306" HREF="library_toc.html#SEC306">Parsing of Numbers</A></H2>
<P>
This section describes functions for "reading" integer and
floating-point numbers from a string.  It may be more convenient in some
cases to use <CODE>sscanf</CODE> or one of the related functions; see
section <A HREF="library.html#SEC145">Formatted Input</A>.  But often you can make a program more robust by
finding the tokens in the string by hand, then converting the numbers
one by one.
<P>
<H3><A NAME="SEC307" HREF="library_toc.html#SEC307">Parsing of Integers</A></H3>
<A NAME="IDX1337"></A>
<P>
These functions are declared in <TT>`stdlib.h'</TT>.
<P>
<A NAME="IDX1338"></A>
<U>Function:</U> long int <B>strtol</B> <I>(const char *<VAR>string</VAR>, char **<VAR>tailptr</VAR>, int <VAR>base</VAR>)</I><P>
The <CODE>strtol</CODE> ("string-to-long") function converts the initial
part of <VAR>string</VAR> to a signed integer, which is returned as a value
of type <CODE>long int</CODE>.  
<P>
This function attempts to decompose <VAR>string</VAR> as follows:
<P>
<UL>
<LI>
A (possibly empty) sequence of whitespace characters.  Which characters
are whitespace is determined by the <CODE>isspace</CODE> function
(see section <A HREF="library.html#SEC55">Classification of Characters</A>).  These are discarded.
<P>
<LI>
An optional plus or minus sign (<SAMP>`+'</SAMP> or <SAMP>`-'</SAMP>).
<P>
<LI>
A nonempty sequence of digits in the radix specified by <VAR>base</VAR>.
<P>
If <VAR>base</VAR> is zero, decimal radix is assumed unless the series of
digits begins with <SAMP>`0'</SAMP> (specifying octal radix), or <SAMP>`0x'</SAMP> or
<SAMP>`0X'</SAMP> (specifying hexadecimal radix); in other words, the same
syntax used for integer constants in C.
<P>
Otherwise <VAR>base</VAR> must have a value between <CODE>2</CODE> and <CODE>35</CODE>.
If <VAR>base</VAR> is <CODE>16</CODE>, the digits may optionally be preceeded by
<SAMP>`0x'</SAMP> or <SAMP>`0X'</SAMP>.
<P>
<LI>
Any remaining characters in the string.  If <VAR>tailptr</VAR> is not a null
pointer, <CODE>strtol</CODE> stores a pointer to this tail in
<CODE>*<VAR>tailptr</VAR></CODE>.
</UL>
<P>
If the string is empty, contains only whitespace, or does not contain an
initial substring that has the expected syntax for an integer in the
specified <VAR>base</VAR>, no conversion is performed.  In this case,
<CODE>strtol</CODE> returns a value of zero and the value stored in
<CODE>*<VAR>tailptr</VAR></CODE> is the value of <VAR>string</VAR>.
<P>
In a locale other than the standard <CODE>"C"</CODE> locale, this function
may recognize additional implementation-dependent syntax.
<P>
If the string has valid syntax for an integer but the value is not
representable because of overflow, <CODE>strtol</CODE> returns either
<CODE>LONG_MAX</CODE> or <CODE>LONG_MIN</CODE> (see section <A HREF="library.html#SEC486">Range of an Integer Type</A>), as
appropriate for the sign of the value.  It also sets <CODE>errno</CODE>
to <CODE>ERANGE</CODE> to indicate there was overflow.
<P>
There is an example at the end of this section.
<P>
<A NAME="IDX1339"></A>
<U>Function:</U> unsigned long int <B>strtoul</B> <I>(const char *<VAR>string</VAR>, char **<VAR>tailptr</VAR>, int <VAR>base</VAR>)</I><P>
The <CODE>strtoul</CODE> ("string-to-unsigned-long") function is like
<CODE>strtol</CODE> except that it returns its value with type <CODE>unsigned
long int</CODE>.  The value returned in case of overflow is <CODE>ULONG_MAX</CODE>
(see section <A HREF="library.html#SEC486">Range of an Integer Type</A>).
<P>
<A NAME="IDX1340"></A>
<U>Function:</U> long int <B>atol</B> <I>(const char *<VAR>string</VAR>)</I><P>
This function is similar to the <CODE>strtol</CODE> function with a <VAR>base</VAR>
argument of <CODE>10</CODE>, except that it need not detect overflow errors.
The <CODE>atol</CODE> function is provided mostly for compatibility with
existing code; using <CODE>strtol</CODE> is more robust.
<P>
<A NAME="IDX1341"></A>
<U>Function:</U> int <B>atoi</B> <I>(const char *<VAR>string</VAR>)</I><P>
This function is like <CODE>atol</CODE>, except that it returns an <CODE>int</CODE>
value rather than <CODE>long int</CODE>.  The <CODE>atoi</CODE> function is also
considered obsolete; use <CODE>strtol</CODE> instead.
<P>
Here is a function which parses a string as a sequence of integers and
returns the sum of them:
<P>
<PRE>
sum_ints_from_string (char *string)
{
  int sum = 0;

  while (1) {
    char *tail;
    int next;

    /* Skip whitespace by hand, to detect the end.  */
    while (isspace (*string)) string++;
    if (*string == 0)
      break;

    /* There is more nonwhitespace,  */
    /* so it ought to be another number.  */
    errno = 0;
    /* Parse it.  */
    next = strtol (string, &#38;tail, 0);
    /* Add it in, if not overflow.  */
    if (errno)
      printf ("Overflow\n");
    else
      sum += next;
    /* Advance past it.  */
    string = tail;
  }

  return sum;
}
</PRE>
<P>
<H3><A NAME="SEC308" HREF="library_toc.html#SEC308">Parsing of Floats</A></H3>
<A NAME="IDX1342"></A>
<P>
These functions are declared in <TT>`stdlib.h'</TT>.
<P>
<A NAME="IDX1343"></A>
<U>Function:</U> double <B>strtod</B> <I>(const char *<VAR>string</VAR>, char **<VAR>tailptr</VAR>)</I><P>
The <CODE>strtod</CODE> ("string-to-double") function converts the initial
part of <VAR>string</VAR> to a floating-point number, which is returned as a
value of type <CODE>double</CODE>.  
<P>
This function attempts to decompose <VAR>string</VAR> as follows:
<P>
<UL>
<LI>
A (possibly empty) sequence of whitespace characters.  Which characters
are whitespace is determined by the <CODE>isspace</CODE> function
(see section <A HREF="library.html#SEC55">Classification of Characters</A>).  These are discarded.
<P>
<LI>
An optional plus or minus sign (<SAMP>`+'</SAMP> or <SAMP>`-'</SAMP>).
<P>
<LI>
A nonempty sequence of digits optionally containing a decimal-point
character--normally <SAMP>`.'</SAMP>, but it depends on the locale
(see section <A HREF="library.html#SEC82">Numeric Formatting</A>).
<P>
<LI>
An optional exponent part, consisting of a character <SAMP>`e'</SAMP> or
<SAMP>`E'</SAMP>, an optional sign, and a sequence of digits.
<P>
<LI>
Any remaining characters in the string.  If <VAR>tailptr</VAR> is not a null
pointer, a pointer to this tail of the string is stored in
<CODE>*<VAR>tailptr</VAR></CODE>.
</UL>
<P>
If the string is empty, contains only whitespace, or does not contain an
initial substring that has the expected syntax for a floating-point
number, no conversion is performed.  In this case, <CODE>strtod</CODE> returns
a value of zero and the value returned in <CODE>*<VAR>tailptr</VAR></CODE> is the
value of <VAR>string</VAR>.
<P>
In a locale other than the standard <CODE>"C"</CODE> locale, this function may
recognize additional locale-dependent syntax.
<P>
If the string has valid syntax for a floating-point number but the value
is not representable because of overflow, <CODE>strtod</CODE> returns either
positive or negative <CODE>HUGE_VAL</CODE> (see section <A HREF="library.html#SEC290">Mathematics</A>), depending on
the sign of the value.  Similarly, if the value is not representable
because of underflow, <CODE>strtod</CODE> returns zero.  It also sets <CODE>errno</CODE>
to <CODE>ERANGE</CODE> if there was overflow or underflow.
<P>
<A NAME="IDX1344"></A>
<U>Function:</U> double <B>atof</B> <I>(const char *<VAR>string</VAR>)</I><P>
This function is similar to the <CODE>strtod</CODE> function, except that it
need not detect overflow and underflow errors.  The <CODE>atof</CODE> function
is provided mostly for compatibility with existing code; using
<CODE>strtod</CODE> is more robust.
<P>
<H1><A NAME="SEC309" HREF="library_toc.html#SEC309">Date and Time</A></H1>
<P>
This chapter describes functions for manipulating dates and times,
including functions for determining what the current time is and
conversion between different time representations.
<P>
The time functions fall into three main categories:
<P>
<UL>
<LI>
Functions for measuring elapsed CPU time are discussed in section <A HREF="library.html#SEC310">Processor Time</A>.
<P>
<LI>
Functions for measuring absolute clock or calendar time are discussed in
section <A HREF="library.html#SEC313">Calendar Time</A>.
<P>
<LI>
Functions for setting alarms and timers are discussed in section <A HREF="library.html#SEC321">Setting an Alarm</A>.
</UL>
<P>
<H2><A NAME="SEC310" HREF="library_toc.html#SEC310">Processor Time</A></H2>
<P>
If you're trying to optimize your program or measure its efficiency, it's
very useful to be able to know how much <DFN>processor time</DFN> or <DFN>CPU
time</DFN> it has used at any given point.  Processor time is different from
actual wall clock time because it doesn't include any time spent waiting
for I/O or when some other process is running.  Processor time is
represented by the data type <CODE>clock_t</CODE>, and is given as a number of
<DFN>clock ticks</DFN> relative to an arbitrary base time marking the beginning
of a single program invocation.
<A NAME="IDX1346"></A>
<A NAME="IDX1347"></A>
<A NAME="IDX1348"></A>
<A NAME="IDX1349"></A>
<A NAME="IDX1345"></A>
<P>
<H3><A NAME="SEC311" HREF="library_toc.html#SEC311">Basic CPU Time Inquiry</A></H3>
<P>
To get the elapsed CPU time used by a process, you can use the
<CODE>clock</CODE> function.  This facility is declared in the header file
<TT>`time.h'</TT>.
<A NAME="IDX1350"></A>
<P>
In typical usage, you call the <CODE>clock</CODE> function at the beginning and
end of the interval you want to time, subtract the values, and then divide
by <CODE>CLOCKS_PER_SEC</CODE> (the number of clock ticks per second), like this:
<P>
<PRE>
#include &#60;time.h&#62;

clock_t start, end;
double elapsed;

start = clock();
... /* Do the work. */
end = clock();
elapsed = ((double) (end - start)) / CLOCKS_PER_SEC;
</PRE>
<P>
Different computers and operating systems vary wildly in how they keep
track of processor time.  It's common for the internal processor clock
to have a resolution somewhere between hundredths and millionths of a
second.
<P>
In the GNU system, <CODE>clock_t</CODE> is equivalent to <CODE>long int</CODE> and
<CODE>CLOCKS_PER_SEC</CODE> is an integer value.  But in other systems, both
<CODE>clock_t</CODE> and the type of the macro <CODE>CLOCKS_PER_SEC</CODE> can be
either integer or floating-point types.  Casting processor time values
to <CODE>double</CODE>, as in the example above, makes sure that operations
such as arithmetic and printing work properly and consistently no matter
what the underlying representation is.
<P>
<A NAME="IDX1351"></A>
<U>Macro:</U> int <B>CLOCKS_PER_SEC</B><P>
The value of this macro is the number of clock ticks per second measured
by the <CODE>clock</CODE> function.
<P>
<A NAME="IDX1352"></A>
<U>Macro:</U> int <B>CLK_TCK</B><P>
This is an obsolete name for <CODE>CLOCKS_PER_SEC</CODE>.  
<P>
<A NAME="IDX1353"></A>
<U>Data Type:</U> <B>clock_t</B><P>
This is the type of the value returned by the <CODE>clock</CODE> function.
Values of type <CODE>clock_t</CODE> are in units of clock ticks.
<P>
<A NAME="IDX1354"></A>
<U>Function:</U> clock_t <B>clock</B> <I>(void)</I><P>
This function returns the elapsed processor time.  The base time is
arbitrary but doesn't change within a single process.  If the processor
time is not available or cannot be represented, <CODE>clock</CODE> returns the
value <CODE>(clock_t)(-1)</CODE>.
<P>
<H3><A NAME="SEC312" HREF="library_toc.html#SEC312">Detailed Elapsed CPU Time Inquiry</A></H3>
<P>
The <CODE>times</CODE> function returns more detailed information about
elapsed processor time in a <CODE>struct tms</CODE> object.  You should
include the header file <TT>`sys/times.h'</TT> to use this facility.
<A NAME="IDX1355"></A>
<P>
<A NAME="IDX1356"></A>
<U>Data Type:</U> <B>struct tms</B><P>
The <CODE>tms</CODE> structure is used to return information about process
times.  It contains at least the following members:
<P>
<DL COMPACT>
<DT><CODE>clock_t tms_utime</CODE>
<DD>This is the CPU time used in executing the instructions of the calling
process.
<P>
<DT><CODE>clock_t tms_stime</CODE>
<DD>This is the CPU time used by the system on behalf of the calling process.
<P>
<DT><CODE>clock_t tms_cutime</CODE>
<DD>This is the sum of the <CODE>tms_utime</CODE> values and the <CODE>tms_cutime</CODE>
values of all terminated child processes of the calling process, whose
status has been reported to the parent process by <CODE>wait</CODE> or
<CODE>waitpid</CODE>; see section <A HREF="library.html#SEC407">Process Completion</A>.  In other words, it represents
the total CPU time used in executing the instructions of all the terminated
child processes of the calling process.
<P>
<DT><CODE>clock_t tms_cstime</CODE>
<DD>This is similar to <CODE>tms_cutime</CODE>, but represents the total CPU time
used by the system on behalf of all the terminated child processes of the
calling process.
</DL>
<P>
All of the times are given in clock ticks.  These are absolute values; in a
newly created process, they are all zero.  See section <A HREF="library.html#SEC405">Creating a Process</A>.
<P>
<A NAME="IDX1357"></A>
<U>Function:</U> clock_t <B>times</B> <I>(struct tms *<VAR>buffer</VAR>)</I><P>
The <CODE>times</CODE> function stores the processor time information for
the calling process in <VAR>buffer</VAR>.
<P>
The return value is the same as the value of <CODE>clock()</CODE>: the elapsed
real time relative to an arbitrary base.  The base is a constant within a
particular process, and typically represents the time since system
start-up.  A value of <CODE>(clock_t)(-1)</CODE> is returned to indicate failure.
<P>
<STRONG>Portability Note:</STRONG> The <CODE>clock</CODE> function described in
section <A HREF="library.html#SEC311">Basic CPU Time Inquiry</A>, is specified by the ANSI C standard.  The
<CODE>times</CODE> function is a feature of POSIX.1.  In the GNU system, the
value returned by the <CODE>clock</CODE> function is equivalent to the sum of
the <CODE>tms_utime</CODE> and <CODE>tms_stime</CODE> fields returned by
<CODE>times</CODE>.
<P>
<H2><A NAME="SEC313" HREF="library_toc.html#SEC313">Calendar Time</A></H2>
<P>
This section describes facilities for keeping track of dates and times
according to the Gregorian calendar.
<A NAME="IDX1359"></A>
<A NAME="IDX1360"></A>
<A NAME="IDX1358"></A>
<P>
There are three representations for date and time information:
<P>
<UL>
<LI>
<DFN>Calendar time</DFN> (the <CODE>time_t</CODE> data type) is a compact 
representation, typically giving the number of seconds elapsed since
some implementation-specific base time.
<A NAME="IDX1361"></A>
<P>
<LI>
There is also a <DFN>high-resolution time</DFN> representation (the <CODE>struct
timeval</CODE> data type) that includes fractions of a second.  Use this time
representation instead of ordinary calendar time when you need greater
precision.
<A NAME="IDX1362"></A>
<P>
<LI>
<DFN>Local time</DFN> or <DFN>broken-down time</DFN> (the <CODE>struct
tm</CODE> data type) represents the date and time as a set of components
specifying the year, month, and so on, for a specific time zone.
This time representation is usually used in conjunction with formatting
date and time values.
<A NAME="IDX1364"></A>
<A NAME="IDX1363"></A>
</UL>
<P>
<H3><A NAME="SEC314" HREF="library_toc.html#SEC314">Simple Calendar Time</A></H3>
<P>
This section describes the <CODE>time_t</CODE> data type for representing
calendar time, and the functions which operate on calendar time objects.
These facilities are declared in the header file <TT>`time.h'</TT>.
<A NAME="IDX1365"></A>
<A NAME="IDX1366"></A>
<P>
<A NAME="IDX1367"></A>
<U>Data Type:</U> <B>time_t</B><P>
This is the data type used to represent calendar time.  In the GNU C
library and other POSIX-compliant implementations, <CODE>time_t</CODE> is
equivalent to <CODE>long int</CODE>.  When interpreted as an absolute time
value, it represents the number of seconds elapsed since 00:00:00 on
January 1, 1970, Coordinated Universal Time.  (This date is sometimes
referred to as the <DFN>epoch</DFN>.)
<P>
In other systems, <CODE>time_t</CODE> might be either an integer or
floating-point type.
<P>
<A NAME="IDX1368"></A>
<U>Function:</U> double <B>difftime</B> <I>(time_t <VAR>time1</VAR>, time_t <VAR>time0</VAR>)</I><P>
The <CODE>difftime</CODE> function returns the number of seconds elapsed
between time <VAR>time1</VAR> and time <VAR>time0</VAR>, as a value of type
<CODE>double</CODE>.  
<P>
In the GNU system, you can simply subtract <CODE>time_t</CODE> values.  But on
other systems, the <CODE>time_t</CODE> data type might use some other encoding
where subtraction doesn't work directly.
<P>
<A NAME="IDX1369"></A>
<U>Function:</U> time_t <B>time</B> <I>(time_t *<VAR>result</VAR>)</I><P>
The <CODE>time</CODE> function returns the current time as a value of type
<CODE>time_t</CODE>.  If the argument <VAR>result</VAR> is not a null pointer, the
time value is also stored in <CODE>*<VAR>result</VAR></CODE>.  If the calendar 
time is not available, the value <CODE>(time_t)(-1)</CODE> is returned.
<P>
<H3><A NAME="SEC315" HREF="library_toc.html#SEC315">High-Resolution Calendar</A></H3>
<P>
The <CODE>time_t</CODE> data type used to represent calendar times has a 
resolution of only one second.  Some applications need more precision.
<P>
So, the GNU C library also contains functions which are capable of
representing calendar times to a higher resolution than one second.  The
functions and the associated data types described in this section are
declared in <TT>`sys/time.h'</TT>.
<A NAME="IDX1370"></A>
<P>
<A NAME="IDX1371"></A>
<U>Data Type:</U> <B>struct timeval</B><P>
The <CODE>struct timeval</CODE> structure represents a calendar time.  It
has the following members:
<P>
<DL COMPACT>
<DT><CODE>long int tv_sec</CODE>
<DD>This represents the number of seconds since the epoch.  It is equivalent
to a normal <CODE>time_t</CODE> value.
<P>
<DT><CODE>long int tv_usec</CODE>
<DD>This is the fractional second value, represented as the number of
microseconds.
<P>
Some times struct timeval values are user for time intervals.  Then the
<CODE>tv_sec</CODE> member is the number of seconds in the interval, and
<CODE>tv_usec</CODE> is the number of addictional microseconds.
</DL>
<P>
<A NAME="IDX1372"></A>
<U>Data Type:</U> <B>struct timezone</B><P>
The <CODE>struct timezone</CODE> structure is used to hold minimal information
about the local time zone.  It has the following members:
<P>
<DL COMPACT>
<DT><CODE>int tz_minuteswest</CODE>
<DD>This is the number of minutes west of GMT.
<P>
<DT><CODE>int tz_dsttime</CODE>
<DD>If nonzero, daylight savings time applies during some part of the year.
</DL>
<P>
It is often necessary to subtract two values of type <CODE>struct
timeval</CODE>.  Here is the best way to do this.  It works even on some
peculiar operating systems where the <CODE>tv_sec</CODE> member has an
unsigned type.
<P>
<PRE>
/* Subtract the `struct timeval' values X and Y,
   storing the result in RESULT.
   Return 1 if the difference is negative, otherwise 0.  */

int
timeval_subtract (result, x, y)
     struct timeval *result, *x, *y;
{
  /* Perform the carry for the later subtraction by updating y. */
  if (x-&#62;tv_usec &#60; y-&#62;tv_usec) {
    int nsec = (y-&#62;tv_usec - x-&#62;tv_usec) / 1000000 + 1;
    y-&#62;tv_usec -= 1000000 * nsec;
    y-&#62;tv_sec += nsec;
  }
  if (x-&#62;tv_usec - y-&#62;tv_usec &#62; 1000000) {
    int nsec = (y-&#62;tv_usec - x-&#62;tv_usec) / 1000000;
    y-&#62;tv_usec += 1000000 * nsec;
    y-&#62;tv_sec -= nsec;
  }

  /* Compute the time remaining to wait.
     <CODE>tv_usec</CODE> is certainly positive. */
  result-&#62;tv_sec = x-&#62;tv_sec - y-&#62;tv_sec;
  result-&#62;tv_usec = x-&#62;tv_usec - y-&#62;tv_usec;

  /* Return 1 if result is negative. */
  return x-&#62;tv_sec &#60; y-&#62;tv_sec;
}
</PRE>
<P>
<A NAME="IDX1373"></A>
<U>Function:</U> int <B>gettimeofday</B> <I>(struct timeval *<VAR>tp</VAR>, struct timezone *<VAR>tzp</VAR>)</I><P>
The <CODE>gettimeofday</CODE> function returns the current date and time in the
<CODE>struct timeval</CODE> structure indicated by <VAR>tp</VAR>.  Information about the
time zone is returned in the structure pointed at <VAR>tzp</VAR>.  If the <VAR>tzp</VAR>
argument is a null pointer, time zone information is ignored.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  The
following <CODE>errno</CODE> error condition is defined for this function:
<P>
<DL COMPACT>
<DT><CODE>ENOSYS</CODE>
<DD>The operating system does not support getting time zone information, and
<VAR>tzp</VAR> is not a null pointer.  The GNU operating system does not
support using <CODE>struct timezone</CODE> to represent time zone
information.  Use <CODE>tzname</CODE> et al instead.  <STRONG>Say something
more helpful here.</STRONG>
</DL>
<P>
<A NAME="IDX1374"></A>
<U>Function:</U> int <B>settimeofday</B> <I>(const struct timeval *<VAR>tp</VAR>, const struct timezone *<VAR>tzp</VAR>)</I><P>
The <CODE>settimeofday</CODE> function sets the current date and time
according to the arguments.  As for <CODE>gettimeofday</CODE>, time zone
information is ignored if <VAR>tzp</VAR> is a null pointer.
<P>
You must be a privileged user in order to use <CODE>settimeofday</CODE>.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  The
following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EPERM</CODE>
<DD>This process cannot set the time because it is not privileged.
<P>
<DT><CODE>ENOSYS</CODE>
<DD>The operating system does not support setting time zone information, and
<VAR>tzp</VAR> is not a null pointer.
</DL>
<P>
<A NAME="IDX1375"></A>
<U>Function:</U> int <B>adjtime</B> <I>(const struct timeval *<VAR>delta</VAR>, struct timeval *<VAR>olddelta</VAR>)</I><P>
This function speeds up or slows down the system clock in order to make
gradual adjustments in the current time.  This ensures that the time
reported by the system clock is always monotonically increasing, which
might not happen if you simply set the current time.
<P>
The <VAR>delta</VAR> argument specifies a relative adjustment to be made to
the current time.  If negative, the system clock is slowed down for a
while until it has lost this much time.  If positive, the system clock
is speeded up for a while.
<P>
If the <VAR>olddelta</VAR> argument is not a null pointer, the <CODE>adjtime</CODE>
function returns information about any previous time adjustment that
has not yet completed.
<P>
This function is typically used to synchronize the clocks of computers
in a local network.  You must be a privileged user to use it.
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  The
following <CODE>errno</CODE> error condition is defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EPERM</CODE>
<DD>You do not have privilege to set the time.
</DL>
<P>
<STRONG>Portability Note:</STRONG>  The <CODE>gettimeofday</CODE>, <CODE>settimeofday</CODE>,
and <CODE>adjtime</CODE> functions are derived from BSD.  
<P>
<A NAME="IDX1376"></A>
<A NAME="IDX1377"></A>
<H3><A NAME="SEC316" HREF="library_toc.html#SEC316">Broken-down Time</A></H3>
<P>
Calender time is represented as a number of seconds.  This is convenient
for calculation, but has no resemblance to the way people normally
represent dates and times.  By contrast, <DFN>broken-down time</DFN> is a binary
representation separated into year, month, day, and so on.  Broken down
time values are not useful for calculations, but they are useful for
printing human readable time.
<P>
A broken-down time value is always relative to a choice of local time
zone, and it also indicates which time zone was used.
<P>
The symbols in this section are declared in the header file <TT>`time.h'</TT>.
<P>
<A NAME="IDX1378"></A>
<U>Data Type:</U> <B>struct tm</B><P>
This is the data type used to represent a broken-down time.  The structure
contains at least the following members, which can appear in any order:
<P>
<DL COMPACT>
<DT><CODE>int tm_sec</CODE>
<DD>This is the number of seconds after the minute, normally in the range
<CODE>0</CODE> to <CODE>59</CODE>.  (The actual upper limit is <CODE>61</CODE>, to allow
for "leap seconds".)
<A NAME="IDX1379"></A>
<P>
<DT><CODE>int tm_min</CODE>
<DD>This is the number of minutes after the hour, in the range <CODE>0</CODE> to
<CODE>59</CODE>.
<P>
<DT><CODE>int tm_hour</CODE>
<DD>This is the number of hours past midnight, in the range <CODE>0</CODE> to
<CODE>23</CODE>.
<P>
<DT><CODE>int tm_mday</CODE>
<DD>This is the day of the month, in the range <CODE>1</CODE> to <CODE>31</CODE>.
<P>
<DT><CODE>int tm_mon</CODE>
<DD>This is the number of months since January, in the range <CODE>0</CODE> to
<CODE>11</CODE>.
<P>
<DT><CODE>int tm_year</CODE>
<DD>This is the number of years since <CODE>1900</CODE>.
<P>
<DT><CODE>int tm_wday</CODE>
<DD>This is the number of days since Sunday, in the range <CODE>0</CODE> to <CODE>6</CODE>.
<P>
<DT><CODE>int tm_yday</CODE>
<DD>This is the number of days since January 1, in the range <CODE>0</CODE> to
<CODE>365</CODE>.
<P>
<A NAME="IDX1380"></A>
<A NAME="IDX1381"></A>
<DT><CODE>int tm_isdst</CODE>
<DD>This is a flag that indicates whether Daylight Saving Time is (or was, or
will be) in effect at the time described.  The value is positive if
Daylight Saving Time is in effect, zero if it is not, and negative if the
information is not available.
<P>
<DT><CODE>long int tm_gmtoff</CODE>
<DD>This field describes the time zone that was used to compute this
broken-down time value; it is the amount you must add to the local time
in that zone to get GMT, in units of seconds.  The value is like that of
the variable <CODE>timezone</CODE> (see section <A HREF="library.html#SEC319">Functions and Variables for Time Zones</A>).  You can
also think of this as the "number of seconds west" of GMT.  The
<CODE>tm_gmtoff</CODE> field is a GNU library extension.
<P>
<DT><CODE>const char *tm_zone</CODE>
<DD>This field is the three-letter name for the time zone that was used to
compute this broken-down time value.  It is a GNU library extension.
</DL>
<P>
<A NAME="IDX1382"></A>
<U>Function:</U> struct tm * <B>localtime</B> <I>(const time_t *<VAR>time</VAR>)</I><P>
The <CODE>localtime</CODE> function converts the calendar time pointed to by
<VAR>time</VAR> to broken-down time representation, expressed relative to the
user's specified time zone.
<P>
The return value is a pointer to a static broken-down time structure, which
might be overwritten by subsequent calls to any of the date and time
functions.  (But no other library function overwrites the contents of this
object.)
<P>
Calling <CODE>localtime</CODE> has one other effect: it sets the variable
<CODE>tzname</CODE> with information about the current time zone.  See section <A HREF="library.html#SEC319">Functions and Variables for Time Zones</A>.
<P>
<A NAME="IDX1383"></A>
<U>Function:</U> struct tm * <B>gmtime</B> <I>(const time_t *<VAR>time</VAR>)</I><P>
This function is similar to <CODE>localtime</CODE>, except that the broken-down
time is expressed as Coordinated Universal Time (UTC)---that is, as
Greenwich Mean Time (GMT) rather than relative to the local time zone.
<P>
Recall that calendar times are <EM>always</EM> expressed in coordinated
universal time.
<P>
<A NAME="IDX1384"></A>
<U>Function:</U> time_t <B>mktime</B> <I>(struct tm *<VAR>brokentime</VAR>)</I><P>
The <CODE>mktime</CODE> function is used to convert a broken-down time structure
to a calendar time representation.  It also "normalizes" the contents of
the broken-down time structure, by filling in the day of week and day of
year based on the other date and time components.
<P>
The <CODE>mktime</CODE> function ignores the specified contents of the
<CODE>tm_wday</CODE> and <CODE>tm_yday</CODE> members of the broken-down time
structure.  It uses the values of the other components to compute the
calendar time; it's permissible for these components to have
unnormalized values outside of their normal ranges.  The last thing that
<CODE>mktime</CODE> does is adjust the components of the <VAR>brokentime</VAR>
structure (including the <CODE>tm_wday</CODE> and <CODE>tm_yday</CODE>).
<P>
If the specified broken-down time cannot be represented as a calendar time,
<CODE>mktime</CODE> returns a value of <CODE>(time_t)(-1)</CODE> and does not modify
the contents of <VAR>brokentime</VAR>.
<P>
Calling <CODE>mktime</CODE> also sets the variable <CODE>tzname</CODE> with
information about the current time zone.  See section <A HREF="library.html#SEC319">Functions and Variables for Time Zones</A>.
<P>
<H3><A NAME="SEC317" HREF="library_toc.html#SEC317">Formatting Date and Time</A></H3>
<P>
The functions described in this section format time values as strings.
These functions are declared in the header file <TT>`time.h'</TT>.
<A NAME="IDX1385"></A>
<P>
<A NAME="IDX1386"></A>
<U>Function:</U> char * <B>asctime</B> <I>(const struct tm *<VAR>brokentime</VAR>)</I><P>
The <CODE>asctime</CODE> function writes the broken-down time value pointed at by
<VAR>brokentime</VAR> into a string in a standard format:
<P>
<PRE>
"Tue May 21 13:46:22 1991\n"
</PRE>
<P>
The abbreviations for the days of week are: <SAMP>`Sun'</SAMP>, <SAMP>`Mon'</SAMP>,
<SAMP>`Tue'</SAMP>, <SAMP>`Wed'</SAMP>, <SAMP>`Thu'</SAMP>, <SAMP>`Fri'</SAMP>, and <SAMP>`Sat'</SAMP>.
<P>
The abbreviations for the months are: <SAMP>`Jan'</SAMP>, <SAMP>`Feb'</SAMP>,
<SAMP>`Mar'</SAMP>, <SAMP>`Apr'</SAMP>, <SAMP>`May'</SAMP>, <SAMP>`Jun'</SAMP>, <SAMP>`Jul'</SAMP>, <SAMP>`Aug'</SAMP>,
<SAMP>`Sep'</SAMP>, <SAMP>`Oct'</SAMP>, <SAMP>`Nov'</SAMP>, and <SAMP>`Dec'</SAMP>.
<P>
The return value points to a statically allocated string, which might be
overwritten by subsequent calls to any of the date and time functions.
(But no other library function overwrites the contents of this
string.)
<P>
<A NAME="IDX1387"></A>
<U>Function:</U> char * <B>ctime</B> <I>(const time_t *<VAR>time</VAR>)</I><P>
The <CODE>ctime</CODE> function is similar to <CODE>asctime</CODE>, except that
the time value is specified in calendar time (rather than local time)
format.  It is equivalent to
<P>
<PRE>
asctime (localtime (<VAR>time</VAR>))
</PRE>
<P>
<CODE>ctime</CODE> sets the variable <CODE>tzname</CODE>, because <CODE>localtime</CODE>
does so.  See section <A HREF="library.html#SEC319">Functions and Variables for Time Zones</A>.
<P>
<A NAME="IDX1388"></A>
<U>Function:</U> size_t <B>strftime</B> <I>(char *<VAR>s</VAR>, size_t <VAR>size</VAR>, const char *<VAR>template</VAR>, const struct tm *<VAR>brokentime</VAR>)</I><P>
This function is similar to the <CODE>sprintf</CODE> function (see section <A HREF="library.html#SEC145">Formatted Input</A>), but the conversion specifications that can appear in the format
template <VAR>template</VAR> are specialized for printing components of the date
and time <VAR>brokentime</VAR> according to the locale currently specified for
time conversion (see section <A HREF="library.html#SEC76">Locales and Internationalization</A>).
<P>
Ordinary characters appearing in the <VAR>template</VAR> are copied to the
output string <VAR>s</VAR>; this can include multibyte character sequences.
Conversion specifiers are introduced by a <SAMP>`%'</SAMP> character, and are
replaced in the output string as follows:
<P>
<DL COMPACT>
<DT><CODE>%a</CODE>
<DD>The abbreviated weekday name according to the current locale.
<P>
<DT><CODE>%A</CODE>
<DD>The full weekday name according to the current locale.
<P>
<DT><CODE>%b</CODE>
<DD>The abbreviated month name according to the current locale.
<P>
<DT><CODE>%B</CODE>
<DD>The full month name according to the current locale.
<P>
<DT><CODE>%c</CODE>
<DD>The preferred date and time representation for the current locale.
<P>
<DT><CODE>%d</CODE>
<DD>The day of the month as a decimal number (range <CODE>01</CODE> to <CODE>31</CODE>).
<P>
<DT><CODE>%H</CODE>
<DD>The hour as a decimal number, using a 24-hour clock (range <CODE>00</CODE> to
<CODE>23</CODE>).
<P>
<DT><CODE>%I</CODE>
<DD>The hour as a decimal number, using a 12-hour clock (range <CODE>01</CODE> to
<CODE>12</CODE>).
<P>
<DT><CODE>%j</CODE>
<DD>The day of the year as a decimal number (range <CODE>001</CODE> to <CODE>366</CODE>).
<P>
<DT><CODE>%m</CODE>
<DD>The month as a decimal number (range <CODE>01</CODE> to <CODE>12</CODE>).
<P>
<DT><CODE>%M</CODE>
<DD>The minute as a decimal number.
<P>
<DT><CODE>%p</CODE>
<DD>Either <SAMP>`am'</SAMP> or <SAMP>`pm'</SAMP>, according to the given time value; or the
corresponding strings for the current locale.
<P>
<DT><CODE>%S</CODE>
<DD>The second as a decimal number.
<P>
<DT><CODE>%U</CODE>
<DD>The week number of the current year as a decimal number, starting with
the first Sunday as the first day of the first week.
<P>
<DT><CODE>%W</CODE>
<DD>The week number of the current year as a decimal number, starting with
the first Monday as the first day of the first week.
<P>
<DT><CODE>%w</CODE>
<DD>The day of the week as a decimal number, Sunday being <CODE>0</CODE>.
<P>
<DT><CODE>%x</CODE>
<DD>The preferred date representation for the current locale, but without the
time.
<P>
<DT><CODE>%X</CODE>
<DD>The preferred time representation for the current locale, but with no date.
<P>
<DT><CODE>%y</CODE>
<DD>The year as a decimal number, but without a century (range <CODE>00</CODE> to
<CODE>99</CODE>).
<P>
<DT><CODE>%Y</CODE>
<DD>The year as a decimal number, including the century.
<P>
<DT><CODE>%Z</CODE>
<DD>The time zone or name or abbreviation (empty if the time zone can't be
determined).
<P>
<DT><CODE>%%</CODE>
<DD>A literal <SAMP>`%'</SAMP> character.
</DL>
<P>
The <VAR>size</VAR> parameter can be used to specify the maximum number of
characters to be stored in the array <VAR>s</VAR>, including the terminating
null character.  If the formatted time requires more than <VAR>size</VAR>
characters, the excess characters are discarded.  The return value from
<CODE>strftime</CODE> is the number of characters placed in the array <VAR>s</VAR>,
not including the terminating null character.  If the value equals
<VAR>size</VAR>, it means that the array <VAR>s</VAR> was too small; you should
repeat the call, providing a bigger array.
<P>
For an example of <CODE>strftime</CODE>, see section <A HREF="library.html#SEC320">Time Functions Example</A>.
<P>
<H3><A NAME="SEC318" HREF="library_toc.html#SEC318">Specifying the Time Zone with <CODE>TZ</CODE></A></H3>
<P>
In the GNU system, a user can specify the time zone by means of the
<CODE>TZ</CODE> environment variable.  For information about how to set
environment variables, see section <A HREF="library.html#SEC392">Environment Variables</A>.  The functions for
accessing the time zone are declared in <TT>`time.h'</TT>.
<A NAME="IDX1390"></A>
<A NAME="IDX1389"></A>
<P>
The value of the <CODE>TZ</CODE> variable can be of one of three formats.  The
first format is used when there is no Daylight Saving Time (or summer
time) in the local time zone:
<P>
<PRE>
<VAR>std</VAR> <VAR>offset</VAR>
</PRE>
<P>
The <VAR>std</VAR> string specifies the name of the time zone.  It must be
three or more characters long and must not contain a leading colon or
embedded digits, commas, or plus or minus signs.  There is no space
character separating the time zone name from the <VAR>offset</VAR>, so these
restrictions are necessary to parse the specification correctly.
<P>
The <VAR>offset</VAR> specifies the time value one must add to the local time
to get a Coordinated Universal Time value.  It has syntax like
[<CODE>+</CODE>|<CODE>-</CODE>]<VAR>hh</VAR>[<CODE>:</CODE><VAR>mm</VAR>[<CODE>:</CODE><VAR>ss</VAR>]].  This
is positive if the local time zone is west of the Prime Meridian and
negative if it is east.  The hour must be between <CODE>0</CODE> and
<CODE>24</CODE>, and the minute and seconds between <CODE>0</CODE> and <CODE>59</CODE>.
<P>
For example, here is how we would specify Eastern Standard Time, but
without any daylight savings time alternative:
<P>
<PRE>
EST+5
</PRE>
<P>
The second format is used when there is Daylight Saving Time:
<P>
<PRE>
<VAR>std</VAR> <VAR>offset</VAR> <VAR>dst</VAR> [<VAR>offset</VAR>]<CODE>,</CODE><VAR>start</VAR>[<CODE>/</CODE><VAR>time</VAR>]<CODE>,</CODE><VAR>end</VAR>[<CODE>/</CODE><VAR>time</VAR>]
</PRE>
<P>
The initial <VAR>std</VAR> and <VAR>offset</VAR> specify the standard time zone, as
described above.  The <VAR>dst</VAR> string and <VAR>offset</VAR> specify the name
and offset for the corresponding daylight savings time time zone; if the
<VAR>offset</VAR> is omitted, it defaults to one hour ahead of standard time.
<P>
The remainder of the specification describes when daylight savings time is
in effect.  The <VAR>start</VAR> field is when daylight savings time goes into
effect and the <VAR>end</VAR> field is when the change is made back to standard
time.  The following formats are recognized for these fields:
<P>
<DL COMPACT>
<DT><CODE>J<VAR>n</VAR></CODE>
<DD>This specifies the Julian day, with <VAR>n</VAR> between <CODE>1</CODE> and <CODE>365</CODE>.
February 29 is never counted, even in leap years.
<P>
<DT><CODE><VAR>n</VAR></CODE>
<DD>This specifies the Julian day, with <VAR>n</VAR> between <CODE>0</CODE> and <CODE>365</CODE>.
February 29 is counted in leap years.
<P>
<DT><CODE>M<VAR>m</VAR>.<VAR>w</VAR>.<VAR>d</VAR></CODE>
<DD>This specifies day <VAR>d</VAR> of week <VAR>w</VAR> of month <VAR>m</VAR>.  The day
<VAR>d</VAR> must be between <CODE>0</CODE> (Sunday) and <CODE>6</CODE>.  The week
<VAR>w</VAR> must be between <CODE>1</CODE> and <CODE>5</CODE>; week <CODE>1</CODE> is the
first week in which day <VAR>d</VAR> occurs, and week <CODE>5</CODE> specifies the
<EM>last</EM> <VAR>d</VAR> day in the month.  The month <VAR>m</VAR> should be
between <CODE>1</CODE> and <CODE>12</CODE>.
</DL>
<P>
The <VAR>time</VAR> fields specify when, in the local time currently in
effect, the change to the other time occurs.  If omitted, the default is
<CODE>02:00:00</CODE>.
<P>
For example, here is how one would specify the Eastern time zone in the
United States, including the appropriate daylight saving time and its dates
of applicability.  The normal offset from GMT is 5 hours; since this is
west of the prime meridian, the sign is positive.  Summer time begins on
the first Sunday in April at 2:00am, and ends on the last Sunday in October
at 2:00am.
<P>
<PRE>
EST+5EDT,M4.1.0/M10.5.0
</PRE>
<P>
The schedule of daylight savings time in any particular jurisdiction has
changed over the years.  To be strictly correct, the conversion of dates
and times in the past should be based on the schedule that was in effect
then.  However, the system has no facilities to let you specify how the
schedule has changed from year to year.  The most you can do is specify
one particular schedule--usually the present day schedule--and this is
used to convert any date, no matter when.
<P>
The third format looks like this:
<P>
<PRE>
:<VAR>characters</VAR>
</PRE>
<P>
Each operating system interprets this format differently; in the GNU C
library, <VAR>characters</VAR> is the name of a file which describes the time
zone.
<P>
If the <CODE>TZ</CODE> environment variable does not have a value, the
operation chooses a time zone by default.  Each operating system has its
own rules for choosing the default time zone, so there is little we can
say about them.
<P>
<H3><A NAME="SEC319" HREF="library_toc.html#SEC319">Functions and Variables for Time Zones</A></H3>
<P>
<A NAME="IDX1391"></A>
<U>Variable:</U> char <B>*tzname[2]</B><P>
The array <CODE>tzname</CODE> contains two strings, which are the standard
three-letter names of the pair of time zones (standard and daylight
savings) that the user has selected.  <CODE>tzname[0]</CODE> is the name of
the standard time zone (for example, <CODE>"EST"</CODE>), and <CODE>tzname[1]</CODE>
is the name for the time zone when daylight savings time is in use (for
example, <CODE>"EDT"</CODE>).  These correspond to the <VAR>std</VAR> and <VAR>dst</VAR>
strings (respectively) from the <CODE>TZ</CODE> environment variable.
<P>
The <CODE>tzname</CODE> array is initialized from the <CODE>TZ</CODE> environment
variable whenever <CODE>tzset</CODE>, <CODE>ctime</CODE>, <CODE>strftime</CODE>,
<CODE>mktime</CODE>, or <CODE>localtime</CODE> is called.
<P>
<A NAME="IDX1392"></A>
<U>Function:</U> void <B>tzset</B> <I>(void)</I><P>
The <CODE>tzset</CODE> function initializes the <CODE>tzname</CODE> variable from
the value of the <CODE>TZ</CODE> environment variable.  It is not usually
necessary for your program to call this function, because it is called
automatically when you use the other time conversion functions that
depend on the time zone.
<P>
The following variables are defined for compatibility with System V
Unix.  These variables are set by calling <CODE>localtime</CODE>.
<P>
<A NAME="IDX1393"></A>
<U>Variable:</U> long int <B>timezone</B><P>
This contains the difference between GMT and local standard time, in
seconds.  For example, in the U.S. Eastern time zone, the value is
<CODE>5*60*60</CODE>.
<P>
<A NAME="IDX1394"></A>
<U>Variable:</U> int <B>daylight</B><P>
This variable has a nonzero value if the standard U.S. daylight savings
time rules apply.
<P>
<H3><A NAME="SEC320" HREF="library_toc.html#SEC320">Time Functions Example</A></H3>
<P>
Here is an example program showing the use of some of the local time and
calendar time functions.
<P>
<PRE>
#include &#60;time.h&#62;
#include &#60;stdio.h&#62;

#define SIZE 256

int
main (void)
{
  char buffer[SIZE];
  time_t curtime;
  struct tm *loctime;

  /* Get the current time.  */
  curtime = time (NULL);

  /* Convert it to local time representation.  */
  loctime = localtime (&#38;curtime);

  /* Print out the date and time in the standard format.  */
  fputs (asctime (loctime), stdout);

  /* Print it out in a nice format.  */
  strftime (buffer, SIZE, "Today is %A, %B %d.\n", loctime);
  fputs (buffer, stdout);
  strftime (buffer, SIZE, "The time is %I:%M %p.\n", loctime);
  fputs (buffer, stdout);

  return 0;
}
</PRE>
<P>
It produces output like this:
<P>
<PRE>
Wed Jul 31 13:02:36 1991
Today is Wednesday, July 31.
The time is 01:02 PM.
</PRE>
<P>
<H2><A NAME="SEC321" HREF="library_toc.html#SEC321">Setting an Alarm</A></H2>
<P>
The <CODE>alarm</CODE> and <CODE>setitimer</CODE> functions provide a mechanism for a
process to interrupt itself at some future time.  They do this by setting a
timer; when the timer expires, the process recieves a signal.
<A NAME="IDX1395"></A>
<A NAME="IDX1396"></A>
<A NAME="IDX1397"></A>
<A NAME="IDX1398"></A>
<P>
Each process has three independent interval timers available:
<P>
<UL>
<LI>
A real-time timer that counts clock time.  This timer sends a
<CODE>SIGALRM</CODE> signal to the process when it expires.
<A NAME="IDX1399"></A>
<P>
<LI>
A virtual timer that counts CPU time used by the process.  This timer
sends a <CODE>SIGVTALRM</CODE> signal to the process when it expires.
<A NAME="IDX1400"></A>
<P>
<LI>
A profiling timer that counts both CPU time used by the process, and CPU
time spent in system calls on behalf of the process.  This timer sends a
<CODE>SIGPROF</CODE> signal to the process when it expires.
<A NAME="IDX1401"></A>
</UL>
<P>
You can only have one timer of each kind set at any given time.  If you
set a timer that has not yet expired, that timer is simply reset to the
new value.
<P>
You should establish a handler for the appropriate alarm signal using
<CODE>signal</CODE> or <CODE>sigaction</CODE> before issuing a call to <CODE>setitimer</CODE>
or <CODE>alarm</CODE>.  Otherwise, an unusual chain of events could cause the
timer to expire before your program establishes the handler, and in that
case it would be terminated, since that is the default action for the alarm
signals.  See section <A HREF="library.html#SEC330">Signal Handling</A>.
<P>
The <CODE>setitimer</CODE> function is the primary means for setting an alarm.
This facility is declared in the header file <TT>`sys/time.h'</TT>.  The
<CODE>alarm</CODE> function, declared in <TT>`unistd.h'</TT>, provides a somewhat
simpler interface for setting the real-time timer.
<A NAME="IDX1403"></A>
<A NAME="IDX1402"></A>
<P>
<A NAME="IDX1404"></A>
<U>Data Type:</U> <B>struct itimerval</B><P>
This structure is used to specify when a timer should expire.  It contains
the following members:
<DL COMPACT>
<DT><CODE>struct timeval it_interval</CODE>
<DD>This is the interval between successive timer interrupts.  If zero, the
alarm will only be sent once.
<P>
<DT><CODE>struct timeval it_value</CODE>
<DD>This is the interval to the first timer interrupt.  If zero, the alarm is
disabled.
</DL>
<P>
The <CODE>struct timeval</CODE> data type is described in section <A HREF="library.html#SEC315">High-Resolution Calendar</A>.
<P>
<A NAME="IDX1405"></A>
<U>Function:</U> int <B>setitimer</B> <I>(int <VAR>which</VAR>, struct itimerval *<VAR>old</VAR>, struct itimerval *<VAR>new</VAR>)</I><P>
The <CODE>setitimer</CODE> function sets the timer specified by <VAR>which</VAR> 
according to <VAR>new</VAR>.  The <VAR>which</VAR> argument can have a value of
<CODE>ITIMER_REAL</CODE>, <CODE>ITIMER_VIRTUAL</CODE>, or <CODE>ITIMER_PROF</CODE>.
<P>
If <VAR>old</VAR> is not a null pointer, <CODE>setitimer</CODE> returns information
about any previous unexpired timer of the same kind in the structure it
points to.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  The
following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>The timer interval was too large.
</DL>
<P>
<A NAME="IDX1406"></A>
<U>Function:</U> int <B>getitimer</B> <I>(int <VAR>which</VAR>, struct itimerval *<VAR>old</VAR>)</I><P>
The <CODE>getitimer</CODE> function stores information about the timer specified
by <VAR>which</VAR> in the structure pointed at by <VAR>old</VAR>.
<P>
The return value and error conditions are the same as for <CODE>setitimer</CODE>.
<P>
<DL COMPACT>
<A NAME="IDX1407"></A>
<DT><CODE>ITIMER_REAL</CODE>
<DD>This constant can be used as the <VAR>which</VAR> argument to the
<CODE>setitimer</CODE> and <CODE>getitimer</CODE> functions to specify the real-time
timer.
<P>
<A NAME="IDX1408"></A>
<DT><CODE>ITIMER_VIRTUAL</CODE>
<DD>This constant can be used as the <VAR>which</VAR> argument to the
<CODE>setitimer</CODE> and <CODE>getitimer</CODE> functions to specify the virtual
timer.
<P>
<A NAME="IDX1409"></A>
<DT><CODE>ITIMER_PROF</CODE>
<DD>This constant can be used as the <VAR>which</VAR> argument to the
<CODE>setitimer</CODE> and <CODE>getitimer</CODE> functions to specify the profiling
timer.
</DL>
<P>
<A NAME="IDX1410"></A>
<U>Function:</U> unsigned int <B>alarm</B> <I>(unsigned int <VAR>seconds</VAR>)</I><P>
The <CODE>alarm</CODE> function sets the real-time timer to expire in
<VAR>seconds</VAR> seconds.  If you want to cancel any existing alarm, you
can do this by calling <CODE>alarm</CODE> with a <VAR>seconds</VAR> argument of
zero.
<P>
The return value indicates how many seconds remain before the previous
alarm would have been sent.  If there is no previous alarm, <CODE>alarm</CODE>
returns zero.
<P>
The <CODE>alarm</CODE> function could be defined in terms of <CODE>setitimer</CODE>
like this:
<P>
<PRE>
unsigned int
alarm (unsigned int seconds)
{
  struct itimerval old, new;
  new.it_interval.tv_usec = 0;
  new.it_interval.tv_sec = 0;
  new.it_value.tv_usec = 0;
  new.it_value.tv_sec = (long int) seconds;
  if (setitimer (ITIMER_REAL, &#38;new, &#38;old) &#60; 0)
    return 0;
  else
    return old.it_value.tv_sec;
}
</PRE>
<P>
There is an example showing the use of the <CODE>alarm</CODE> function in
section <A HREF="library.html#SEC352">Signal Handlers That Return</A>.
<P>
If you simply want your process to wait for a given number of seconds,
you should use the <CODE>sleep</CODE> function.  See section <A HREF="library.html#SEC322">Sleeping</A>.
<P>
You shouldn't count on the signal arriving precisely when the timer
expires.  In a multiprocessing environment there is typically some
amount of delay involved.
<P>
<STRONG>Portability Note:</STRONG> The <CODE>setitimer</CODE> and <CODE>getitimer</CODE>
functions are derived from BSD Unix, while the <CODE>alarm</CODE> function is
specified by the POSIX.1 standard.  <CODE>setitimer</CODE> is more powerful than
<CODE>alarm</CODE>, but <CODE>alarm</CODE> is more widely used.
<P>
<H2><A NAME="SEC322" HREF="library_toc.html#SEC322">Sleeping</A></H2>
<P>
The function <CODE>sleep</CODE> gives a simple way to make the program wait
for short periods of time.  If your program doesn't use signals (except
to terminate), then you can expect <CODE>sleep</CODE> to wait reliably for
the specified amount of time.  Otherwise, <CODE>sleep</CODE> can return sooner
if a signal arrives; if you want to wait for a given period regardless
of signals, use <CODE>select</CODE> (see section <A HREF="library.html#SEC180">Waiting for Input or Output</A>) and don't
specify any descriptors to wait for.
<P>
<A NAME="IDX1411"></A>
<U>Function:</U> unsigned int <B>sleep</B> <I>(unsigned int <VAR>seconds</VAR>)</I><P>
The <CODE>sleep</CODE> function waits for <VAR>seconds</VAR> or until a signal
is delivered, whichever happens first.  
<P>
If <CODE>sleep</CODE> function returns because the requested time has
elapsed, it returns a value of zero.  If it returns because of delivery
of a signal, its return value is the remaining time in the sleep period.
<P>
The <CODE>sleep</CODE> function is declared in <TT>`unistd.h'</TT>.
<P>
Resist the temptation to implement a sleep for a fixed amount of time by
using the return value of <CODE>sleep</CODE>, when nonzero, to call
<CODE>sleep</CODE> again.  This will work with a certain amount of accuracy as
long as signals arrive infrequently.  But each signal can cause the
eventual wakeup time to be off by an additional second or so.  Suppose a
few signals happen to arrive in rapid succession by bad luck--there is
no limit on how much this could shorten or lengthen the wait.
<P>
Instead, compute the time at which the program should stop waiting, and
keep trying to wait until that time.  This won't be off by more than a
second.  With just a little more work, you can use <CODE>select</CODE> and
make the waiting period quite accurate.  (Of course, heavy system load
can cause unavoidable additional delays--unless the machine is 
dedicated to one application, there is no way you can avoid this.)
<P>
On some systems, <CODE>sleep</CODE> can do strange things if your program uses
<CODE>SIGALRM</CODE> explicitly.  Even if <CODE>SIGALRM</CODE> signals are being
ignored or blocked when <CODE>sleep</CODE> is called, <CODE>sleep</CODE> might
return prematurely on delivery of a <CODE>SIGALRM</CODE> signal.  If you have
established a handler for <CODE>SIGALRM</CODE> signals and a <CODE>SIGALRM</CODE>
signal is delivered while the process is sleeping, the action taken
might be just to cause <CODE>sleep</CODE> to return instead of invoking your
handler.  And, if <CODE>sleep</CODE> is interrupted by delivery of a signal
whose handler requests an alarm or alters the handling of <CODE>SIGALRM</CODE>,
this handler and <CODE>sleep</CODE> will interfere.
<P>
On the GNU system, it is safe to use <CODE>sleep</CODE> and <CODE>SIGALRM</CODE> in
the same program, because <CODE>sleep</CODE> does not work by means of
<CODE>SIGALRM</CODE>.
<P>
<H2><A NAME="SEC323" HREF="library_toc.html#SEC323">Resource Usage</A></H2>
<A NAME="IDX1412"></A>
<P>
The function <CODE>getrusage</CODE> and the data type <CODE>struct rusage</CODE>
are used for examining the usage figures of a process.  They are declared
in <TT>`sys/resource.h'</TT>.
<P>
<A NAME="IDX1413"></A>
<U>Function:</U> int <B>getrusage</B> <I>(int <VAR>processes</VAR>, struct rusage *<VAR>rusage</VAR>)</I><P>
This function reports the usage totals for processes specified by
<VAR>processes</VAR>, storing the information in <CODE>*<VAR>rusage</VAR></CODE>.
<P>
In most systems, <VAR>processes</VAR> has only two valid values:
<P>
<DL COMPACT>
<DT><CODE>RUSAGE_SELF</CODE>
<DD>Just the current process.
<P>
<DT><CODE>RUSAGE_CHILDREN</CODE>
<DD>All child processes (direct and indirect) that have terminated already.
</DL>
<P>
In the GNU system, you can also inquire about a particular child process
by specifying its process ID.
<P>
The return value of <CODE>getrusage</CODE> is zero for success, and <CODE>-1</CODE>
for failure.
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>The argument <VAR>processes</VAR> is not valid.
</DL>
<P>
One way of getting usage figures for a particular child process is with
the function <CODE>wait4</CODE>, which returns totals for a child when it
terminates.  See section <A HREF="library.html#SEC409">BSD Process Wait Functions</A>.
<P>
<A NAME="IDX1414"></A>
<U>Data Type:</U> <B>struct rusage</B><P>
This data type records a collection usage amounts for various sorts of
resources.  It has the following members, and possibly others:
<P>
<DL COMPACT>
<DT><CODE>struct timeval ru_utime</CODE>
<DD>User time used.
<P>
<DT><CODE>struct timeval ru_stime</CODE>
<DD>System time used.
<P>
<DT><CODE>long ru_majflt</CODE>
<DD>Number of page faults.
<P>
<DT><CODE>long ru_inblock</CODE>
<DD>Number of block input operations.
<P>
<DT><CODE>long ru_oublock</CODE>
<DD>Number of block output operations.
<P>
<DT><CODE>long ru_msgsnd</CODE>
<DD>Number of messages sent.
<P>
<DT><CODE>long ru_msgrcv</CODE>
<DD>Number of messages received.
<P>
<DT><CODE>long ru_nsignals</CODE>
<DD>Number of signals received.
</DL>
<P>
An additional historical function for examining usage figures,
<CODE>vtimes</CODE>, is supported but not documented here.  It is declared in
<TT>`sys/vtimes.h'</TT>.
<P>
<A NAME="IDX1415"></A>
<A NAME="IDX1416"></A>
<A NAME="IDX1417"></A>
<H2><A NAME="SEC324" HREF="library_toc.html#SEC324">Limiting Resource Usage</A></H2>
<P>
You can specify limits for the resource usage of a process.  When the
process tries to exceed a limit, it may get a signal, or the system call
by which it tried to do so may fail, depending on the limit.  Each
process initially inherits its limit values from its parent, but it can
subsequently change them.
<A NAME="IDX1418"></A>
<P>
The symbols in this section are defined in <TT>`sys/resource.h'</TT>.
<P>
<A NAME="IDX1419"></A>
<U>Function:</U> int <B>getrlimit</B> <I>(int <VAR>resource</VAR>, struct rlimit *<VAR>rlp</VAR>)</I><P>
Read the current value and the maximum value of resource <VAR>resource</VAR>
and store them in <CODE>*<VAR>rlp</VAR></CODE>.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  The
only possible <CODE>errno</CODE> error condition is <CODE>EFAULT</CODE>.
<P>
<A NAME="IDX1420"></A>
<U>Function:</U> int <B>setrlimit</B> <I>(int <VAR>resource</VAR>, struct rlimit *<VAR>rlp</VAR>)</I><P>
Store the current value and the maximum value of resource <VAR>resource</VAR>
in <CODE>*<VAR>rlp</VAR></CODE>.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  The
following <CODE>errno</CODE> error condition is possible:
<P>
<DL COMPACT>
<DT><CODE>EPERM</CODE>
<DD>You tried to change the maximum permissible limit value,
but you don't have privileges to do so.
</DL>
<P>
<A NAME="IDX1421"></A>
<U>Data Type:</U> <B>struct rlimit</B><P>
This structure is used with <CODE>getrlimit</CODE> to receive limit values,
and with <CODE>setrlimit</CODE> to specify limit values.  It has two fields:
<P>
<DL COMPACT>
<DT><CODE>rlim_cur</CODE>
<DD>The current value of the limit in question.
<P>
<DT><CODE>rlim_max</CODE>
<DD>The maximum permissible value of the limit in question.  You cannot set
the current value of the limit to a larger number than this maximum.
Only the super user can change the maximum permissible value.
</DL>
<P>
In <CODE>getrlimit</CODE>, the structure is an output; it receives the current
values.  In <CODE>setrlimit</CODE>, it specifies the new values.
<P>
Here is a list of resources that you can specify a limit for.
Those that are sizes are measured in bytes.
<P>
<DL COMPACT>
<A NAME="IDX1422"></A>
<DT><CODE>RLIMIT_CPU</CODE>
<DD>The maximum amount of cpu time the process can use.  If it runs for
longer than this, it gets a signal: <CODE>SIGXCPU</CODE>.  The value is
measured in seconds.  See section <A HREF="library.html#SEC342">Nonstandard Signals</A>.
<P>
<A NAME="IDX1423"></A>
<DT><CODE>RLIMIT_FSIZE</CODE>
<DD>The maximum size of file the process can create.  Trying to write a
larger file causes a signal: <CODE>SIGXFSZ</CODE>.  See section <A HREF="library.html#SEC342">Nonstandard Signals</A>.
<P>
<A NAME="IDX1424"></A>
<DT><CODE>RLIMIT_DATA</CODE>
<DD>The maximum size of data memory for the process.  If the process tries
to allocate data memory beyond this amount, the allocation function
fails.
<P>
<A NAME="IDX1425"></A>
<DT><CODE>RLIMIT_STACK</CODE>
<DD>The maximum stack size for the process.  If the process tries to extend
its stack past this size, it gets a <CODE>SIGSEGV</CODE> signal.
See section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<A NAME="IDX1426"></A>
<DT><CODE>RLIMIT_CORE</CODE>
<DD>The maximum size core file that this process can create.  If the process
terminates and a core file is made, and this maximum size is not enough,
the core file is truncated.
<P>
<A NAME="IDX1427"></A>
<DT><CODE>RLIMIT_RSS</CODE>
<DD>The maximum amount of physical memory that this process should get.
This parameter is a guide for the system's scheduler and memory
allocator; the system may give the process more memory when there is a
surplus.
<P>
<A NAME="IDX1428"></A>
<DT><CODE>RLIMIT_OPEN_FILES</CODE>
<DD>The maximum number of files that the process can open.
If it tries to open more files than this, it gets error code
<CODE>EMFILE</CODE>.  See section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<A NAME="IDX1429"></A>
<DT><CODE>RLIM_NLIMITS</CODE>
<DD>The number of different resource limits.  Any valid <VAR>resource</VAR>
operand must be less than <CODE>RLIM_NLIMITS</CODE>.
</DL>
<P>
<A NAME="IDX1430"></A>
<U>Constant:</U> <B>int</B> <I>RLIM_INFINITY</I><P>
This constant stands for a value of "infinity" when supplied as
the limit value in <CODE>setrlimit</CODE>.
<P>
Two historical functions for setting resource limits, <CODE>ulimit</CODE> and
<CODE>vlimit</CODE>, are not documented here.  The latter is declared in
<TT>`sys/vlimit.h'</TT> and comes from BSD.
<P>
<A NAME="IDX1431"></A>
<A NAME="IDX1432"></A>
<H2><A NAME="SEC325" HREF="library_toc.html#SEC325">Process Priority</A></H2>
<A NAME="IDX1433"></A>
<P>
When several processes try to run, their respective priorities determine
what share of the CPU each process gets.  This section describes how you
can read and set the priority of a process.  All these functions and
macros are declared in <TT>`sys/resource.h'</TT>.
<P>
The range of valid priority values depends on the operating system, but
typically it runs from <CODE>-20</CODE> to <CODE>20</CODE>.  A lower priority value
means the process runs more often.  These constants describe the range of
priority values:
<P>
<DL COMPACT>
<A NAME="IDX1434"></A>
<DT><CODE>PRIO_MIN</CODE>
<DD>The smallest valid priority value.
<P>
<A NAME="IDX1435"></A>
<DT><CODE>PRIO_MAX</CODE>
<DD>The smallest valid priority value.
</DL>
<P>
<A NAME="IDX1436"></A>
<U>Function:</U> int <B>getpriority</B> <I>(int <VAR>class</VAR>, int <VAR>id</VAR>)</I><P>
Read the priority of a class of processes; <VAR>class</VAR> and <VAR>id</VAR>
specify which ones (see below).
<P>
The return value is the priority value on success, and <CODE>-1</CODE> on
failure.  The following <CODE>errno</CODE> error condition are possible for
this function:
<P>
<DL COMPACT>
<DT><CODE>ESRCH</CODE>
<DD>The combination of <VAR>class</VAR> and <VAR>id</VAR> does not match any existing
process.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The value of <VAR>class</VAR> is not valid.
</DL>
<P>
When the return value is <CODE>-1</CODE>, it could indicate failure, or it
could be the priority value.  The only way to make certain is to set
<CODE>errno = 0</CODE> before calling <CODE>getpriority</CODE>, then use <CODE>errno
!= 0</CODE> afterward as the criterion for failure.
<P>
<A NAME="IDX1437"></A>
<U>Function:</U> int <B>setpriority</B> <I>(int <VAR>class</VAR>, int <VAR>id</VAR>, int <VAR>priority</VAR>)</I><P>
Read the priority of a class of processes; <VAR>class</VAR> and <VAR>id</VAR>
specify which ones (see below).
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  The
following <CODE>errno</CODE> error condition are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>ESRCH</CODE>
<DD>The combination of <VAR>class</VAR> and <VAR>id</VAR> does not match any existing
process.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The value of <VAR>class</VAR> is not valid.
<P>
<DT><CODE>EPERM</CODE>
<DD>You tried to set the priority of some other user's process, and you
don't have privileges for that.
<P>
<DT><CODE>EACCES</CODE>
<DD>You tried to lower the priority of a process, and you don't have
privileges for that.
</DL>
<P>
The arguments <VAR>class</VAR> and <VAR>id</VAR> together specify a set of
processes you are interested in.  These are the possible values for
<VAR>class</VAR>:
<P>
<DL COMPACT>
<A NAME="IDX1438"></A>
<DT><CODE>PRIO_PROCESS</CODE>
<DD>Read or set the priority of one process.  The argument <VAR>id</VAR> is a
process ID.
<P>
<A NAME="IDX1439"></A>
<DT><CODE>PRIO_PGRP</CODE>
<DD>Read or set the priority of one process group.  The argument <VAR>id</VAR> is
a process group ID.
<P>
<A NAME="IDX1440"></A>
<DT><CODE>PRIO_USER</CODE>
<DD>Read or set the priority of one user's processes.  The argument <VAR>id</VAR>
is a user ID.
</DL>
<P>
If the argument <VAR>id</VAR> is 0, it stands for the current process,
current process group, or the current user, according to <VAR>class</VAR>.
<P>
<A NAME="IDX1441"></A>
<U>Function:</U> int <B>nice</B> <I>(int <VAR>increment</VAR>)</I><P>
Increment the priority of the current process by <VAR>increment</VAR>.
The return value is not meaningful.
<P>
Here is an equivalent definition for <CODE>nice</CODE>:
<P>
<PRE>
int
nice (int increment)
{
  int old = getpriority (PRIO_PROCESS, 0);
  setpriority (PRIO_PROCESS, 0, old + increment);
}
</PRE>
<P>
<A NAME="IDX1442"></A>
<A NAME="IDX1443"></A>
<H1><A NAME="SEC326" HREF="library_toc.html#SEC326">Non-Local Exits</A></H1>
<P>
Sometimes when your program detects an unusual situation inside a deeply
nested set of function calls, you would like to be able to immediately
return to an outer level of control.  This section describes how you can
do such <DFN>non-local exits</DFN> using the <CODE>setjmp</CODE> and <CODE>longjmp</CODE>
functions.
<P>
<H2><A NAME="SEC327" HREF="library_toc.html#SEC327">Introduction to Non-Local Exits</A></H2>
<P>
As an example of a situation where a non-local exit can be useful,
suppose you have an interactive program that has a "main loop" that
prompts for and executes commands.  Suppose the "read" command reads
input from a file, doing some lexical analysis and parsing of the input
while processing it.  If a low-level input error is detected, it would
be useful to be able to return immediately to the "main loop" instead
of having to make each of the lexical analysis, parsing, and processing
phases all have to explicitly deal with error situations initially
detected by nested calls.
<P>
(On the other hand, if each of these phases has to do a substantial
amount of cleanup when it exits--such as closing files, deallocating
buffers or other data structures, and the like--then it can be more
appropriate to do a normal return and have each phase do its own
cleanup, because a non-local exit would bypass the intervening phases and
their associated cleanup code entirely.  Alternatively, you could use a
non-local exit but do the cleanup explicitly either before or after
returning to the "main loop".)
<P>
In some ways, a non-local exit is similar to using the <SAMP>`return'</SAMP>
statement to return from a function.  But while <SAMP>`return'</SAMP> abandons
only a single function call, transferring control back to the point at
which it was called, a non-local exit can potentially abandon many
levels of nested function calls.
<P>
You identify return points for non-local exits calling the function
<CODE>setjmp</CODE>.  This function saves information about the execution
environment in which the call to <CODE>setjmp</CODE> appears in an object of
type <CODE>jmp_buf</CODE>.  Execution of the program continues normally after
the call to <CODE>setjmp</CODE>, but if a exit is later made to this return
point by calling <CODE>longjmp</CODE> with the corresponding <CODE>jmp_buf</CODE>
object, control is transferred back to the point where <CODE>setjmp</CODE> was
called.  The return value from <CODE>setjmp</CODE> is used to distinguish
between an ordinary return and a return made by a call to
<CODE>longjmp</CODE>, so calls to <CODE>setjmp</CODE> usually appear in an <SAMP>`if'</SAMP>
statement.
<P>
Here is how the example program described above might be set up:  
<P>
<PRE>
#include &#60;setjmp.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;stdio.h&#62;

jmp_buf main_loop;

void 
abort_to_main_loop (int status)
{
  longjmp (main_loop, status);
}

int
main (void)
{
  while (1)
    if (setjmp (main_loop))
      puts ("Back at main loop....");
    else
      do_command ();
}


void 
do_command (void)
{
  char buffer[128];
  if (fgets (buffer, 128, stdin) == NULL)
    abort_to_main_loop (-1);
  else
    exit (EXIT_SUCCESS);
}
</PRE>
<P>
The function <CODE>abort_to_main_loop</CODE> causes an immediate transfer of
control back to the main loop of the program, no matter where it is
called from.
<P>
The flow of control inside the <CODE>main</CODE> function may appear a little
mysterious at first, but it is actually a common idiom with
<CODE>setjmp</CODE>.  A normal call to <CODE>setjmp</CODE> returns zero, so the
"else" clause of the conditional is executed.  If
<CODE>abort_to_main_loop</CODE> is called somewhere within the execution of
<CODE>do_command</CODE>, then it actually appears as if the <EM>same</EM> call
to <CODE>setjmp</CODE> in <CODE>main</CODE> were returning a second time with a value
of <CODE>-1</CODE>.
<P>
So, the general pattern for using <CODE>setjmp</CODE> looks something like:
<P>
<PRE>
if (setjmp (<VAR>buffer</VAR>))
  /* Code to clean up after premature return. */
  ...
else
  /* Code to be executed normally after setting up the return point. */
  ...
</PRE>
<P>
<H2><A NAME="SEC328" HREF="library_toc.html#SEC328">Details of Non-Local Exits</A></H2>
<P>
Here are the details on the functions and data structures used for
performing non-local exits.  These facilities are declared in
<TT>`setjmp.h'</TT>.
<A NAME="IDX1444"></A>
<P>
<A NAME="IDX1445"></A>
<U>Data Type:</U> <B>jmp_buf</B><P>
Objects of type <CODE>jmp_buf</CODE> hold the state information to
be restored by a non-local exit.  The contents of a <CODE>jmp_buf</CODE>
identify a specific place to return to.
<P>
<A NAME="IDX1446"></A>
<U>Macro:</U> int <B>setjmp</B> <I>(jmp_buf <VAR>state</VAR>)</I><P>
When called normally, <CODE>setjmp</CODE> stores information about the
execution state of the program in <VAR>state</VAR> and returns zero.  If
<CODE>longjmp</CODE> is later used to perform a non-local exit to this
<VAR>state</VAR>, <CODE>setjmp</CODE> returns a nonzero value.
<P>
<A NAME="IDX1447"></A>
<U>Function:</U> void <B>longjmp</B> <I>(jmp_buf <VAR>state</VAR>, int <VAR>value</VAR>)</I><P>
This function restores current execution to the state saved in
<VAR>state</VAR>, and continues execution from the call to <CODE>setjmp</CODE> that
established that return point.  Returning from <CODE>setjmp</CODE> by means of
<CODE>longjmp</CODE> returns the <VAR>value</VAR> argument that was passed to
<CODE>longjmp</CODE>, rather than <CODE>0</CODE>.  (But if <VAR>value</VAR> is given as
<CODE>0</CODE>, <CODE>setjmp</CODE> returns <CODE>1</CODE>).<P>
There are a lot of obscure but important restrictions on the use of
<CODE>setjmp</CODE> and <CODE>longjmp</CODE>.  Most of these restrictions are
present because non-local exits require a fair amount of magic on the
part of the C compiler and can interact with other parts of the language
in strange ways.
<P>
The <CODE>setjmp</CODE> function is actually a macro without an actual
function definition, so you shouldn't try to <SAMP>`#undef'</SAMP> it or take
its address.  In addition, calls to <CODE>setjmp</CODE> are safe in only the
following contexts:
<P>
<UL>
<LI>
As the test expression of a selection or iteration
statement (such as <SAMP>`if'</SAMP> or <SAMP>`while'</SAMP>).
<P>
<LI>
As one operand of a equality or comparison operator that appears as the
test expression of a selection or iteration statement.  The other
operand must be an integer constant expression.
<P>
<LI>
As the operand of a unary <SAMP>`!'</SAMP> operator, that appears as the
test expression of a selection or iteration statement.
<P>
<LI>
By itself as an expression statement.
</UL>
<P>
Return points are valid only during the dynamic extent of the function
that called <CODE>setjmp</CODE> to establish them.  If you <CODE>longjmp</CODE> to
a return point that was established in a function that has already
returned, unpredictable and disastrous things are likely to happen.
<P>
You should use a nonzero <VAR>value</VAR> argument to <CODE>longjmp</CODE>.  While
<CODE>longjmp</CODE> refuses to pass back a zero argument as the return value
from <CODE>setjmp</CODE>, this is intended as a safety net against accidental
misuse and is not really good programming style.
<P>
When you perform a non-local exit, accessible objects generally retain
whatever values they had at the time <CODE>longjmp</CODE> was called.  The
exception is that the values of automatic variables local to the
function containing the <CODE>setjmp</CODE> call that have been changed since
the call to <CODE>setjmp</CODE> are indeterminate, unless you have declared
them <CODE>volatile</CODE>.
<P>
<H2><A NAME="SEC329" HREF="library_toc.html#SEC329">Non-Local Exits and Signals</A></H2>
<P>
In BSD Unix systems, <CODE>setjmp</CODE> and <CODE>longjmp</CODE> also save and
restore the set of blocked signals; see section <A HREF="library.html#SEC368">Blocking Signals</A>.  However,
the POSIX.1 standard requires <CODE>setjmp</CODE> and <CODE>longjmp</CODE> not to
change the set of blocked signals, and provides an additional pair of
functions (<CODE>sigsetjmp</CODE> and <CODE>sigsetjmp</CODE>) to get the BSD
behavior.
<P>
The behavior of <CODE>setjmp</CODE> and <CODE>longjmp</CODE> in the GNU library is
controlled by feature test macros; see section <A HREF="library.html#SEC12">Feature Test Macros</A>.  The
default in the GNU system is the POSIX.1 behavior rather than the BSD
behavior.
<P>
The facilities in this section are declared in the header file
<TT>`setjmp.h'</TT>.
<A NAME="IDX1448"></A>
<P>
<A NAME="IDX1449"></A>
<U>Data Type:</U> <B>sigjmp_buf</B><P>
This is similar to <CODE>jmp_buf</CODE>, except that it can also store state
information about the set of blocked signals.
<P>
<A NAME="IDX1450"></A>
<U>Function:</U> int <B>sigsetjmp</B> <I>(sigjmp_buf <VAR>state</VAR>, int <VAR>savesigs</VAR>)</I><P>
This is similar to <CODE>setjmp</CODE>.  If <VAR>savesigs</VAR> is nonzero, the set
of blocked signals is saved in <VAR>state</VAR> and will be restored if a
<CODE>siglongjmp</CODE> is later performed with this <VAR>state</VAR>.
<P>
<A NAME="IDX1451"></A>
<U>Function:</U> void <B>siglongjmp</B> <I>(sigjmp_buf <VAR>state</VAR>, int <VAR>value</VAR>)</I><P>
This is similar to <CODE>longjmp</CODE> except for the type of its <VAR>state</VAR>
argument.  If the <CODE>sigsetjmp</CODE> call that set this <VAR>state</VAR> used a
nonzero <VAR>savesigs</VAR> flag, <CODE>siglongjmp</CODE> also restores the set of
blocked signals.
<P>
<H1><A NAME="SEC330" HREF="library_toc.html#SEC330">Signal Handling</A></H1>
<A NAME="IDX1452"></A>
<P>
A <DFN>signal</DFN> is a software interrupt delivered to a process.  The
operating system uses signals to report exceptional situations to an
executing program.  Some signals report errors such as references to
invalid memory addresses; others report asynchronous events, such as
disconnection of a phone line.
<P>
The GNU C library defines a variety of signal types, each for a
particular kind of event.  Some kinds of events make it inadvisable or
impossible for the program to proceed as usual, and the corresponding
signals normally abort the program.  Other kinds of signals that report
harmless events are ignored by default.
<P>
If you anticipate an event that causes signals, you can define a handler
function and tell the operating system to run it when that particular
type of signal arrives.
<P>
Finally, one process can send a signal to another process; this allows a
parent process to abort a child, or two related processes to communicate
and synchronize.
<P>
<H2><A NAME="SEC331" HREF="library_toc.html#SEC331">Basic Concepts of Signals</A></H2>
<P>
This section explains basic concepts of how signals are generated, what
happens after a signal is delivered, and how programs can handle
signals.
<P>
<H3><A NAME="SEC332" HREF="library_toc.html#SEC332">Some Kinds of Signals</A></H3>
<P>
A signal reports the occurrence of an exceptional event.  These are some
of the events that can cause (or <DFN>generate</DFN>, or <DFN>raise</DFN>) a
signal:
<P>
<UL>
<LI>
A program error such as dividing by zero or issuing an address outside
the valid range.
<P>
<LI>
A user request to interrupt or terminate the program.  Most environments
are set up to let a user suspend the program by typing <KBD>C-z</KBD>, or
terminate it with <KBD>C-c</KBD>.  Whatever key sequence is used, the
operating system sends the proper signal to interrupt the process.
<P>
<LI>
The termination of a child process.
<P>
<LI>
Expiration of a timer or alarm.
<P>
<LI>
A call to <CODE>kill</CODE> or <CODE>raise</CODE> by the same process.
<P>
<LI>
A call to <CODE>kill</CODE> from another process.  Signals are a limited but
useful form of interprocess communication.
</UL>
<P>
Each of these kinds of events (excepting explicit calls to <CODE>kill</CODE>
and <CODE>raise</CODE>) generates its own particular kind of signal.  The
various kinds of signals are listed and described in detail in
section <A HREF="library.html#SEC335">Standard Signals</A>.
<P>
<A NAME="IDX1453"></A>
<H3><A NAME="SEC333" HREF="library_toc.html#SEC333">Concepts of Signal Generation</A></H3>
<P>
In general, the events that generate signals fall into three major
categories: errors, external events, and explicit requests.
<P>
An error means that a program has done something invalid and cannot
continue execution.  But not all kinds of errors generate signals--in
fact, most do not.  For example, opening a nonexistant file is an error,
but it does not raise a signal; instead, <CODE>open</CODE> returns <CODE>-1</CODE>.
In general, errors that are necessarily associated with certain library
functions are reported by returning a value that indicates an error.
The errors which raise signals are those which can happen anywhere in
the program, not just in library calls.  These include division by zero
and invalid memory addresses.
<P>
An external event generally has to do with I/O or other processes.
These include the arrival of input, the expiration of a timer, and the
termination of a child process.
<P>
An explicit request means the use of a library function such as
<CODE>kill</CODE> whose purpose is specifically to generate a signal.
<P>
Signals may be generated <DFN>synchronously</DFN> or <DFN>asynchronously</DFN>.  A
synchronous signal pertains to a specific action in the program, and is
delivered (unless blocked) during that action.  Errors generate signals
synchronously, and so do explicit requests by a process to generate a
signal for that same process.
<P>
Asynchronous signals are generated by events outside the control of the
process that receives them.  These signals arrive at unpredictable times
during execution.  External events generate signals asynchronously, and
so do explicit requests that apply to some other process.
<P>
A given type of signal is either typically synchrous or typically
asynchronous.  For example, signals for errors are typically synchronous
because errors generate signals synchronously.  But any type of signal
can be generated synchronously or asynchronously with an explicit
request.
<P>
<A NAME="IDX1454"></A>
<A NAME="IDX1455"></A>
<A NAME="IDX1456"></A>
<H3><A NAME="SEC334" HREF="library_toc.html#SEC334">How Signals Are Delivered</A></H3>
<P>
When a signal is generated, it becomes <DFN>pending</DFN>.  Normally it
remains pending for just a short period of time and then is
<DFN>delivered</DFN> to the process that was signaled.  However, if that kind
of signal is currently <DFN>blocked</DFN>, it may remain pending
indefinitely--until signals of that kind are <DFN>unblocked</DFN>.  Once
unblocked, it will be delivered immediately.  See section <A HREF="library.html#SEC368">Blocking Signals</A>.
<A NAME="IDX1457"></A>
<A NAME="IDX1458"></A>
<A NAME="IDX1459"></A>
<A NAME="IDX1460"></A>
<P>
When the signal is delivered, whether right away or after a long delay,
the <DFN>specified action</DFN> for that signal is taken.  For certain
signals, such as <CODE>SIGKILL</CODE> and <CODE>SIGSTOP</CODE>, the action is fixed,
but for most signals, the program has a choice: ignore the signal,
specify a <DFN>handler function</DFN>, or accept the <DFN>default action</DFN> for
that kind of signal.  The program specifies its choice using functions
such as <CODE>signal</CODE> or <CODE>sigaction</CODE> (see section <A HREF="library.html#SEC344">Specifying Signal Actions</A>).  We
sometimes say that a handler <DFN>catches</DFN> the signal.  While the
handler is running, that particular signal is normally blocked.
<P>
If the specified action for a kind of signal is to ignore it, then any
such signal which is generated is discarded immediately.  This happens
even if the signal is also blocked at the time.  A signal discarded in
this way will never be delivered, not even if the program subsequently
specifies a different action for that kind of signal and then unblocks
it.
<P>
If a signal arrives which the program has neither handled nor ignored,
its <DFN>default action</DFN> takes place.  Each kind of signal has its own
default action, documented below (see section <A HREF="library.html#SEC335">Standard Signals</A>).  For most kinds
of signals, the default action is to terminate the process.  For certain
kinds of signals that represent "harmless" events, the default action
is to do nothing.
<P>
When a signal terminates a process, its parent process can determine the
cause of termination by examining the termination status code reported
by the <CODE>wait</CODE> or <CODE>waitpid</CODE> functions.  (This is discussed in
more detail in section <A HREF="library.html#SEC407">Process Completion</A>.)  The information it can get
includes the fact that termination was due to a signal, and the kind of
signal involved.  If a program you run from a shell is terminated by a
signal, the shell typically prints some kind of error message.
<P>
The signals that normally represent program errors have a special
property: when one of these signals terminates the process, it also
writes a <DFN>core dump file</DFN> which records the state of the process at
the time of termination.  You can examine the core dump with a debugger
to investigate what caused the error.
<P>
If you raise a "program error" signal by explicit request, and this
terminates the process, it makes a core dump file just as if the signal
had been due directly to an error.
<P>
<A NAME="IDX1461"></A>
<A NAME="IDX1462"></A>
<H2><A NAME="SEC335" HREF="library_toc.html#SEC335">Standard Signals</A></H2>
<A NAME="IDX1463"></A>
<A NAME="IDX1464"></A>
<P>
This section lists the names for various standard kinds of signals and
describes what kind of event they mean.  Each signal name is a macro
which stands for a positive integer--the <DFN>signal number</DFN> for that
kind of signal.  Your programs should never make assumptions about the
numeric code for a particular kind of signal, but rather refer to them
always by the names defined here.  This is because the number for a
given kind of signal can vary from system to system, but the meanings of
the names are standardized and fairly uniform.
<P>
The signal names are defined in the header file <TT>`signal.h'</TT>.
<P>
<A NAME="IDX1465"></A>
<U>Macro:</U> int <B>NSIG</B><P>
The value of this symbolic constant is the total number of signals
defined.  Since the signal numbers are allocated consecutively,
<CODE>NSIG</CODE> is also one greater than the largest defined signal number.
<P>
<A NAME="IDX1466"></A>
<H3><A NAME="SEC336" HREF="library_toc.html#SEC336">Program Error Signals</A></H3>
<P>
The following signals are generated when a serious program error is
detected by the operating system or the computer itself.  In general,
all of these signals are indications that your program is seriously
broken in some way, and there's usually no way to continue the
computation which encountered the error.
<P>
Some programs handle program error signals in order to tidy up before
terminating; for example, programs that turn off echoing of terminal
input should handle program error signals in order to turn echoing back
on.  The handler should end by specifying the default action for the
signal that happened and then reraising it; this will cause the program
to terminate with that signal, as if it had not had a handler.
(See section <A HREF="library.html#SEC353">Handlers That Terminate the Process</A>.)
<P>
Termination is the sensible ultimate outcome from a program error in
most programs.  However, programming systems such as Lisp that can load
compiled user programs might need to keep executing even if a user
program incurs an error.  These programs have handlers which use
<CODE>longjmp</CODE> to return control to the command level.
<P>
The default action for all of these signals is to cause the process to
terminate.  If you block or ignore these signals or establish handlers
for them that return normally, your program will probably break horribly
when such signals happen, unless they are generated by <CODE>raise</CODE> or
<CODE>kill</CODE> instead of a real error.
<A NAME="IDX1467"></A>
<P>
When one of these program error signals terminates a process, it also
writes a <DFN>core dump file</DFN> which records the state of the process at
the time of termination.  The core dump file is named <TT>`core'</TT> and is
written in whichever directory is current in the process at the time.
(On the GNU system, you can specify the file name for core dumps with
the environment variable <CODE>COREFILE</CODE>.)  The purpose of core dump
files is so that you can examine them with a debugger to investigate
what caused the error.
<P>
<A NAME="IDX1468"></A>
<U>Macro:</U> int <B>SIGFPE</B><P>
The <CODE>SIGFPE</CODE> signal reports a fatal arithmetic error.  Although the
name is derived from "floating-point exception", this signal actually
covers all arithmetic errors, including division by zero and overflow.
If a program stores integer data in a location which is then used in a
floating-point operation, this often causes an "invalid operation"
exception, because the processor cannot recognize the data as a
floating-point number.
<A NAME="IDX1470"></A>
<A NAME="IDX1469"></A>
<P>
Actual floating-point exceptions are a complicated subject because there
are many types of exceptions with subtly different meanings, and the
<CODE>SIGFPE</CODE> signal doesn't distinguish between them.  The <CITE>IEEE
Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985)</CITE>
defines various floating-point exceptions and requires conforming
computer systems to report their occurrences.  However, this standard
does not specify how the exceptions are reported, or what kinds of
handling and control the operating system can offer to the programmer.
<P>
BSD systems provide the <CODE>SIGFPE</CODE> handler with an extra argument
that distinguishes various causes of the exception.  In order to access
this argument, you must define the handler to accept two arguments,
which means you must cast it to a one-argument function type in order to
establish the handler.  The GNU library does provide this extra
argument, but the value is meaningful only on operating systems that
provide the information (BSD systems and GNU systems).
<P>
<DL COMPACT>
<A NAME="IDX1471"></A>
<DT><CODE>FPE_INTOVF_TRAP</CODE>
<DD>Integer overflow (impossible in a C program unless you enable overflow
trapping in a hardware-specific fashion).
<A NAME="IDX1472"></A>
<DT><CODE>FPE_INTDIV_TRAP</CODE>
<DD>Integer division by zero.
<A NAME="IDX1473"></A>
<DT><CODE>FPE_SUBRNG_TRAP</CODE>
<DD>Subscript-range (something that C programs never check for).
<A NAME="IDX1474"></A>
<DT><CODE>FPE_FLTOVF_TRAP</CODE>
<DD>Floating overflow trap.
<A NAME="IDX1475"></A>
<DT><CODE>FPE_FLTDIV_TRAP</CODE>
<DD>Floating/decimal division by zero.
<A NAME="IDX1476"></A>
<DT><CODE>FPE_FLTUND_TRAP</CODE>
<DD>Floating underflow trap.  (Trapping on floating underflow is not
normally enabled.)
<A NAME="IDX1477"></A>
<DT><CODE>FPE_DECOVF_TRAP</CODE>
<DD>Decimal overflow trap.  (Only a few machines have decimal arithmetic and
C never uses it.)
</DL>
<P>
<A NAME="IDX1478"></A>
<U>Macro:</U> int <B>SIGILL</B><P>
The name of this signal is derived from "illegal instruction"; it
means your program is trying to execute garbage or a privileged
instruction.  Since the C compiler generates only valid instructions,
<CODE>SIGILL</CODE> typically indicates that the executable file is corrupted,
or that you are trying to execute data.  Some common ways of getting
into the latter situation are by passing an invalid object where a
pointer to a function was expected, or by writing past the end of an
automatic array (or similar problems with pointers to automatic
variables) and corrupting other data on the stack such as the return
address of a stack frame.
<A NAME="IDX1479"></A>
<P>
<A NAME="IDX1480"></A>
<A NAME="IDX1481"></A>
<U>Macro:</U> int <B>SIGSEGV</B><P>
This signal is generated when a program tries to read or write outside
the memory that is allocated for it.  (Actually, the signals only occur
when the program goes far enough outside to be detected by the system's
memory protection mechanism.)  The name is an abbreviation for
"segmentation violation".
<P>
The most common way of getting a <CODE>SIGSEGV</CODE> condition is by
dereferencing a null or uninitialized pointer.  A null pointer refers to
the address 0, and most operating systems make sure this address is
always invalid precisely so that dereferencing a null pointer will cause
<CODE>SIGSEGV</CODE>.  (Some operating systems place valid memory at address
0, and dereferencing a null pointer does not cause a signal on these
systems.)  As for uninitialized pointer variables, they contain random
addresses which may or may not be valid.
<P>
Another common way of getting into a <CODE>SIGSEGV</CODE> situation is when
you use a pointer to step through an array, but fail to check for the
end of the array.
<P>
<A NAME="IDX1482"></A>
<U>Macro:</U> int <B>SIGBUS</B><P>
This signal is generated when an invalid pointer is dereferenced.  Like
<CODE>SIGSEGV</CODE>, this signal is typically the result of dereferencing an
uninitialized pointer.  The difference between the two is that
<CODE>SIGSEGV</CODE> indicates an invalid access to valid memory, while
<CODE>SIGBUS</CODE> indicates an access to an invalid address.  In particular,
<CODE>SIGBUS</CODE> signals often result from dereferencing a misaligned
pointer, such as referring to a four-word integer at an address not
divisible by four.  (Each kind of computer has its own requirements for
address alignment.)
<P>
The name of this signal is an abbreviation for "bus error".
<A NAME="IDX1483"></A>
<P>
<A NAME="IDX1484"></A>
<A NAME="IDX1485"></A>
<U>Macro:</U> int <B>SIGABRT</B><P>
This signal indicates an error detected by the program itself and
reported by calling <CODE>abort</CODE>.  See section <A HREF="library.html#SEC399">Aborting a Program</A>.
<P>
<A NAME="IDX1486"></A>
<H3><A NAME="SEC337" HREF="library_toc.html#SEC337">Termination Signals</A></H3>
<P>
These signals are all used to tell a process to terminate, in one way
or another.  They have different names because they're used for slightly
different purposes, and programs might want to handle them differently.
<P>
The reason for handling these signals is usually so your program can
tidy up as appropriate before actually terminating.  For example, you
might want to save state information, delete temporary files, or restore
the previous terminal modes.  Such a handler should end by specifying
the default action for the signal that happened and then reraising it;
this will cause the program to terminate with that signal, as if it had
not had a handler.  (See section <A HREF="library.html#SEC353">Handlers That Terminate the Process</A>.)
<P>
The (obvious) default action for all of these signals is to cause the
process to terminate.
<P>
<A NAME="IDX1487"></A>
<A NAME="IDX1488"></A>
<U>Macro:</U> int <B>SIGHUP</B><P>
The <CODE>SIGHUP</CODE> ("hang-up") signal is used to report that the user's
terminal is disconnected, perhaps because a network or telephone
connection was broken.  For more information about this, see section <A HREF="library.html#SEC278">Control Modes</A>.
<P>
This signal is also used to report the termination of the controlling
process on a terminal to jobs associated with that session; this
termination effectively disconnects all processes in the session from
the controlling terminal.  For more information, see section <A HREF="library.html#SEC400">Termination Internals</A>.
<P>
<A NAME="IDX1489"></A>
<A NAME="IDX1490"></A>
<U>Macro:</U> int <B>SIGINT</B><P>
The <CODE>SIGINT</CODE> ("program interrupt") signal is sent when the user
types the INTR character (normally <KBD>C-c</KBD>).  See section <A HREF="library.html#SEC281">Special Characters</A>, for information about terminal driver support for
<KBD>C-c</KBD>.
<P>
<A NAME="IDX1491"></A>
<A NAME="IDX1492"></A>
<A NAME="IDX1493"></A>
<U>Macro:</U> int <B>SIGQUIT</B><P>
The <CODE>SIGQUIT</CODE> signal is similar to <CODE>SIGINT</CODE>, except that it's
controlled by a different key--the QUIT character, usually
<KBD>C-\</KBD>---and produces a core dump when it terminates the process,
just like a program error signal.  You can think of this as a
program error condition "detected" by the user.
<P>
See section <A HREF="library.html#SEC336">Program Error Signals</A>, for information about core dumps.
See section <A HREF="library.html#SEC281">Special Characters</A>, for information about terminal driver
support.
<P>
Certain kinds of cleanups are best omitted in handling <CODE>SIGQUIT</CODE>.
For example, if the program creates temporary files, it should handle
the other termination requests by deleting the temporary files.  But it
is better for <CODE>SIGQUIT</CODE> not to delete them, so that the user can
examine them in conjunction with the core dump.
<P>
<A NAME="IDX1494"></A>
<A NAME="IDX1495"></A>
<U>Macro:</U> int <B>SIGTERM</B><P>
The <CODE>SIGTERM</CODE> signal is a generic signal used to cause program
termination.  Unlike <CODE>SIGKILL</CODE>, this signal can be blocked,
handled, and ignored.
<P>
The shell command <CODE>kill</CODE> generates <CODE>SIGTERM</CODE> by default.
<A NAME="IDX1496"></A>
<P>
<A NAME="IDX1497"></A>
<U>Macro:</U> int <B>SIGKILL</B><P>
The <CODE>SIGKILL</CODE> signal is used to cause immediate program termination.
It cannot be handled or ignored, and is therefore always fatal.  It is
also not possible to block this signal.
<P>
This signal is generated only by explicit request.  Since it cannot be
handled, you should generate it only as a last resort, after first
trying a less drastic method such as <KBD>C-c</KBD> or <CODE>SIGTERM</CODE>.  If a
process does not respond to any other termination signals, sending it a
<CODE>SIGKILL</CODE> signal will almost always cause it to go away.
<P>
In fact, if <CODE>SIGKILL</CODE> fails to terminate a process, that by itself
constitutes an operating system bug which you should report.
<A NAME="IDX1498"></A>
<P>
<H3><A NAME="SEC338" HREF="library_toc.html#SEC338">Alarm Signals</A></H3>
<P>
These signals are used to indicate the expiration of timers.
See section <A HREF="library.html#SEC321">Setting an Alarm</A>, for information about functions that cause
these signals to be sent.
<P>
The default behavior for these signals is to cause program termination.
This default is rarely useful, but no other default would be useful;
most of the ways of using these signals would require handler functions
in any case.
<P>
<A NAME="IDX1499"></A>
<U>Macro:</U> int <B>SIGALRM</B><P>
This signal typically indicates expiration of a timer that measures real
or clock time.  It is used by the <CODE>alarm</CODE> function, for example.
<A NAME="IDX1500"></A>
<P>
<A NAME="IDX1501"></A>
<U>Macro:</U> int <B>SIGVTALRM</B><P>
This signal typically indicates expiration of a timer that measures CPU
time used by the current process.  The name is an abbreviation for
"virtual time alarm".
<A NAME="IDX1502"></A>
<P>
<A NAME="IDX1503"></A>
<U>Macro:</U> int <B>SIGPROF</B><P>
This signal is typically indicates expiration of a timer that measures
both CPU time used by the current process, and CPU time expended on 
behalf of the process by the system.  Such a timer is used to implement
code profiling facilities, hence the name of this signal.
<A NAME="IDX1504"></A>
<P>
<H3><A NAME="SEC339" HREF="library_toc.html#SEC339">Asynchronous I/O Signals</A></H3>
<P>
The signals listed in this section are used in conjunction with
asynchronous I/O facilities.  You have to take explicit action by
calling <CODE>fcntl</CODE> to enable a particular file descriptior to generate
these signals (see section <A HREF="library.html#SEC186">Interrupt-Driven Input</A>).  The default action for these
signals is to ignore them.
<P>
<A NAME="IDX1505"></A>
<A NAME="IDX1506"></A>
<A NAME="IDX1507"></A>
<U>Macro:</U> int <B>SIGIO</B><P>
This signal is sent when a file descriptor is ready to perform input
or output.
<P>
On most operating systems, terminals and sockets are the only kinds of
files that can generate <CODE>SIGIO</CODE>; other kinds, including ordinary
files, never generate <CODE>SIGIO</CODE> even if you ask them to.
<P>
<A NAME="IDX1508"></A>
<A NAME="IDX1509"></A>
<U>Macro:</U> int <B>SIGURG</B><P>
This signal is sent when "urgent" or out-of-band data arrives on a
socket.  See section <A HREF="library.html#SEC255">Out-of-Band Data</A>.
<P>
<A NAME="IDX1510"></A>
<H3><A NAME="SEC340" HREF="library_toc.html#SEC340">Job Control Signals</A></H3>
<P>
These signals are used to support job control.  If your system
doesn't support job control, then these macros are defined but the
signals themselves can't be raised or handled.
<P>
You should generally leave these signals alone unless you really
understand how job control works.  See section <A HREF="library.html#SEC411">Job Control</A>.
<P>
<A NAME="IDX1511"></A>
<A NAME="IDX1512"></A>
<U>Macro:</U> int <B>SIGCHLD</B><P>
This signal is sent to a parent process whenever one of its child
processes terminates or stops.
<P>
The default action for this signal is to ignore it.  If you establish a
handler for this signal while there are child processes that have
terminated but not reported their status via <CODE>wait</CODE> or
<CODE>waitpid</CODE> (see section <A HREF="library.html#SEC407">Process Completion</A>), whether your new handler
applies to those processes or not depends on the particular operating
system.
<P>
<A NAME="IDX1513"></A>
<A NAME="IDX1514"></A>
<U>Macro:</U> int <B>SIGCONT</B><P>
You can send a <CODE>SIGCONT</CODE> signal to a process to make it continue.
The default behavior for this signal is to make the process continue if
it is stopped, and to ignore it otherwise.
<P>
Most programs have no reason to handle <CODE>SIGCONT</CODE>; they simply
resume execution without realizing they were ever stopped.  You can use
a handler for <CODE>SIGCONT</CODE> to make a program do something special when
it is stopped and continued--for example, to reprint a prompt when it
is suspended while waiting for input.
<P>
<A NAME="IDX1515"></A>
<U>Macro:</U> int <B>SIGSTOP</B><P>
The <CODE>SIGSTOP</CODE> signal stops the process.  It cannot be handled,
ignored, or blocked.
<A NAME="IDX1516"></A>
<P>
<A NAME="IDX1517"></A>
<U>Macro:</U> int <B>SIGTSTP</B><P>
The <CODE>SIGTSTP</CODE> signal is an interactive stop signal.  Unlike
<CODE>SIGSTOP</CODE>, this signal can be handled and ignored.  
<P>
Your program should handle this signal if you have a special need to
leave files or system tables in a secure state when a process is
stopped.  For example, programs that turn off echoing should handle
<CODE>SIGTSTP</CODE> so they can turn echoing back on before stopping.
<P>
This signal is generated when the user types the SUSP character
(normally <KBD>C-z</KBD>).  For more information about terminal driver
support, see section <A HREF="library.html#SEC281">Special Characters</A>.
<A NAME="IDX1518"></A>
<P>
<A NAME="IDX1519"></A>
<U>Macro:</U> int <B>SIGTTIN</B><P>
A process cannot read from the the user's terminal while it is running 
as a background job.  When any process in a background job tries to
read from the terminal, all of the processes in the job are sent a
<CODE>SIGTTIN</CODE> signal.  The default action for this signal is to
stop the process.  For more information about how this interacts with
the terminal driver, see section <A HREF="library.html#SEC415">Access to the Controlling Terminal</A>.
<A NAME="IDX1520"></A>
<P>
<A NAME="IDX1521"></A>
<U>Macro:</U> int <B>SIGTTOU</B><P>
This is similar to <CODE>SIGTTIN</CODE>, but is generated when a process in a
background job attempts to write to the terminal or set its modes.
Again, the default action is to stop the process.
<A NAME="IDX1522"></A>
<P>
While a process is stopped, no more signals can be delivered to it until
it is continued, except <CODE>SIGKILL</CODE> signals and (obviously)
<CODE>SIGCONT</CODE> signals.  The <CODE>SIGKILL</CODE> signal always causes
termination of the process and can't be blocked or ignored.  You can
block or ignore <CODE>SIGCONT</CODE>, but it always causes the process to
be continued anyway if it is stopped.  Sending a <CODE>SIGCONT</CODE> signal
to a process causes any pending stop signals for that process to be
discarded.  Likewise, any pending <CODE>SIGCONT</CODE> signals for a process
are discarded when it receives a stop signal.
<P>
When a process in an orphaned process group (see section <A HREF="library.html#SEC416">Orphaned Process Groups</A>) receives a <CODE>SIGTSTP</CODE>, <CODE>SIGTTIN</CODE>, or <CODE>SIGTTOU</CODE>
signal and does not handle it, the process does not stop.  Stopping the
process would be unreasonable since there would be no way to continue
it.  What happens instead depends on the operating system you are
using.  Some systems may do nothing; others may deliver another signal
instead, such as <CODE>SIGKILL</CODE> or <CODE>SIGHUP</CODE>.
<P>
<H3><A NAME="SEC341" HREF="library_toc.html#SEC341">Miscellaneous Signals</A></H3>
<P>
These signals are used to report various other conditions.  The default
action for all of them is to cause the process to terminate.
<P>
<A NAME="IDX1523"></A>
<A NAME="IDX1524"></A>
<A NAME="IDX1525"></A>
<U>Macro:</U> int <B>SIGPIPE</B><P>
If you use pipes or FIFOs, you have to design your application so that
one process opens the pipe for reading before another starts writing.
If the reading process never starts, or terminates unexpectedly, writing
to the pipe or FIFO raises a <CODE>SIGPIPE</CODE> signal.  If <CODE>SIGPIPE</CODE>
is blocked, handled or ignored, the offending call fails with
<CODE>EPIPE</CODE> instead.
<P>
Pipes and FIFO special files are discussed in more detail in section <A HREF="library.html#SEC211">Pipes and FIFOs</A>.
<P>
Another cause of <CODE>SIGPIPE</CODE> is when you try to output to a socket
that isn't connected.  See section <A HREF="library.html#SEC250">Sending Data</A>.
<P>
<A NAME="IDX1526"></A>
<U>Macro:</U> int <B>SIGUSR1</B><P>
<P>
<A NAME="IDX1527"></A>
<U>Macro:</U> int <B>SIGUSR2</B><P>
The <CODE>SIGUSR1</CODE> and <CODE>SIGUSR2</CODE> signals are set aside for you to
use any way you want.  They're useful for interprocess communication.
Since these signals are normally fatal, you should write a signal handler
for them in the program that receives the signal.
<P>
There is an example showing the use of <CODE>SIGUSR1</CODE> and <CODE>SIGUSR2</CODE>
in section <A HREF="library.html#SEC365">Signaling Another Process</A>.
<A NAME="IDX1528"></A>
<P>
<H3><A NAME="SEC342" HREF="library_toc.html#SEC342">Nonstandard Signals</A></H3>
<P>
Particular operating systems support additional signals not listed
above.  The ANSI C standard reserves all identifiers beginning with
<SAMP>`SIG'</SAMP> followed by an uppercase letter for the names of signals.
You should consult the documentation or header files for your particular
operating system and processor type to find out about the specific
signals it supports.
<P>
For example, some systems support extra signals which correspond to
hardware traps.  Some other kinds of signals commonly supported are used
to implement limits on CPU time or file system usage, asynchronous
changes to terminal configuration, and the like.  Systems may also
define signal names that are aliases for standard signal names.
<P>
You can generally assume that the default action (or the action set up
by the shell) for implementation-defined signals is reasonable, and not
worry about them yourself.  In fact, it's usually a bad idea to ignore
or block signals you don't know anything about, or try to establish a
handler for signals whose meanings you don't know.
<P>
Here are some of the other signals found on commonly used operating
systems:
<P>
<DL COMPACT>
<DT><CODE>SIGCLD</CODE>
<DD>Obsolete name for <CODE>SIGCHLD</CODE>.
<P>
<DT><CODE>SIGTRAP</CODE>
<DD>Generated by the machine's breakpoint instruction.  Used by debuggers.
Default action is to dump core.
<P>
<DT><CODE>SIGIOT</CODE>
<DD>Generated by the PDP-11 "iot" instruction; equivalent to <CODE>SIGABRT</CODE>.
Default action is to dump core.
<P>
<DT><CODE>SIGEMT</CODE>
<DD>Emulator trap; this results from certain unimplemented instructions.
It is a program error signal.
<P>
<DT><CODE>SIGSYS</CODE>
<DD>Bad system call; that is to say, the instruction to trap to the
operating system was executed, but the code number for the system call
to perform was invalid.  This is a program error signal.
<P>
<DT><CODE>SIGPOLL</CODE>
<DD>This is a System V signal name, more or less similar to <CODE>SIGIO</CODE>.
<P>
<DT><CODE>SIGXCPU</CODE>
<DD>CPU time limit exceeded.  This is used for batch processing.
Default action is program termination.
<P>
<DT><CODE>SIGXFSZ</CODE>
<DD>File size limit exceeded.  This is used for batch processing.
Default action is program termination.
<P>
<DT><CODE>SIGWINCH</CODE>
<DD>Window size change.  This is generated on certain systems when the size
of the current window on the screen is changed.  Default action is to
ignore it.
</DL>
<P>
<A NAME="IDX1529"></A>
<H3><A NAME="SEC343" HREF="library_toc.html#SEC343">Signal Messages</A></H3>
<P>
We mentioned above that the shell prints a message describing the signal
that terminated a child process.  The clean way to print a message
describing a signal is to use the functions <CODE>strsignal</CODE> and
<CODE>psignal</CODE>.  These functions use a signal number to specify which
kind of signal to describe.  The signal number may come from the
termination status of a child process (see section <A HREF="library.html#SEC407">Process Completion</A>) or it
may come from a signal handler in the same process.
<P>
<A NAME="IDX1530"></A>
<U>Function:</U> char * <B>strsignal</B> <I>(int <VAR>signum</VAR>)</I><P>
This function returns a pointer to a statically-allocated string
containing a message describing the signal <VAR>signum</VAR>.  You
should not modify the contents of this string; and, since it can be
rewritten on subsequent calls, you should save a copy of it if you need
to reference it later.
<A NAME="IDX1531"></A>
<P>
This function is a GNU extension, declared in the header file
<TT>`string.h'</TT>.
<P>
<A NAME="IDX1532"></A>
<U>Function:</U> void <B>psignal</B> <I>(int <VAR>signum</VAR>, const char *<VAR>message</VAR>)</I><P>
This function prints a message describing the signal <VAR>signum</VAR> to the
standard error output stream <CODE>stderr</CODE>; see section <A HREF="library.html#SEC119">Standard Streams</A>.
<P>
If you call <CODE>psignal</CODE> with a <VAR>message</VAR> that is either a null
pointer or an empty string, <CODE>psignal</CODE> just prints the message 
corresponding to <VAR>signum</VAR>, adding a trailing newline.
<P>
If you supply a non-null <VAR>message</VAR> argument, then <CODE>psignal</CODE>
prefixes its output with this string.  It adds a colon and a space 
character to separate the <VAR>message</VAR> from the string corresponding
to <VAR>signum</VAR>.
<A NAME="IDX1533"></A>
<P>
This function is a BSD feature, declared in the header file <TT>`stdio.h'</TT>.
<P>
<A NAME="IDX1534"></A>
<P>
There is also an array <CODE>sys_siglist</CODE> which contains the messages
for the various signal codes.  This array exists on BSD systems, unlike
<CODE>strsignal</CODE>.
<P>
<A NAME="IDX1535"></A>
<A NAME="IDX1536"></A>
<H2><A NAME="SEC344" HREF="library_toc.html#SEC344">Specifying Signal Actions</A></H2>
<P>
The simplest way to change the action for a signal is to use the
<CODE>signal</CODE> function.  You can specify a built-in action (such as to
ignore the signal), or you can <DFN>establish a handler</DFN>.
<P>
The GNU library also implements the more versatile <CODE>sigaction</CODE>
facility.  This section describes both facilities and gives suggestions
on which to use when.
<P>
<A NAME="IDX1537"></A>
<H3><A NAME="SEC345" HREF="library_toc.html#SEC345">Basic Signal Handling</A></H3>
<P>
The <CODE>signal</CODE> function provides a simple interface for establishing
an action for a particular signal.  The function and associated macros
are declared in the header file <TT>`signal.h'</TT>.
<A NAME="IDX1538"></A>
<P>
<A NAME="IDX1539"></A>
<U>Data Type:</U> <B>sighandler_t</B><P>
This is the type of signal handler functions.  Signal handlers take one
integer argument specifying the signal number, and have return type
<CODE>void</CODE>.  So, you should define handler functions like this:
<P>
<PRE>
void <VAR>handler</VAR> (int <CODE>signum</CODE>) { ... }
</PRE>
<P>
The name <CODE>sighandler_t</CODE> for this data type is a GNU extension.
<P>
<A NAME="IDX1540"></A>
<U>Function:</U> sighandler_t <B>signal</B> <I>(int <VAR>signum</VAR>, sighandler_t <VAR>action</VAR>)</I><P>
The <CODE>signal</CODE> function establishes <VAR>action</VAR> as the action for
the signal <VAR>signum</VAR>.
<P>
The first argument, <VAR>signum</VAR>, identifies the signal whose behavior
you want to control, and should be a signal number.  The proper way to
specify a signal number is with one of the symbolic signal names
described in section <A HREF="library.html#SEC335">Standard Signals</A>---don't use an explicit number, because
the numerical code for a given kind of signal may vary from operating
system to operating system.
<P>
The second argument, <VAR>action</VAR>, specifies the action to use for the
signal <VAR>signum</VAR>.  This can be one of the following:
<P>
<DL COMPACT>
<A NAME="IDX1541"></A>
<A NAME="IDX1542"></A>
<DT><CODE>SIG_DFL</CODE>
<DD><CODE>SIG_DFL</CODE> specifies the default action for the particular signal.
The default actions for various kinds of signals are stated in
section <A HREF="library.html#SEC335">Standard Signals</A>.
<P>
<A NAME="IDX1543"></A>
<A NAME="IDX1544"></A>
<DT><CODE>SIG_IGN</CODE>
<DD><CODE>SIG_IGN</CODE> specifies that the signal should be ignored.
<P>
Your program generally should not ignore signals that represent serious
events or that are normally used to request termination.  You cannot
ignore the <CODE>SIGKILL</CODE> or <CODE>SIGSTOP</CODE> signals at all.  You can
ignore program error signals like <CODE>SIGSEGV</CODE>, but ignoring the error
won't enable the program to continue executing meaningfully.  Ignoring
user requests such as <CODE>SIGINT</CODE>, <CODE>SIGQUIT</CODE>, and <CODE>SIGTSTP</CODE>
is unfriendly.
<P>
When you do not wish signals to be delivered during a certain part of
the program, the thing to do is to block them, not ignore them.
See section <A HREF="library.html#SEC368">Blocking Signals</A>.
<P>
<DT><CODE><VAR>handler</VAR></CODE>
<DD>Supply the address of a handler function in your program, to specify
running this handler as the way to deliver the signal.
<P>
For more information about defining signal handler functions,
see section <A HREF="library.html#SEC351">Defining Signal Handlers</A>.
</DL>
<P>
If you set the action for a signal to <CODE>SIG_IGN</CODE>, or if you set it
to <CODE>SIG_DFL</CODE> and the default action is to ignore that signal, then
any pending signals of that type are discarded (even if they are
blocked).  Discarding the pending signals means that they will never be
delivered, not even if you subsequently specify another action and
unblock this kind of signal.
<P>
The <CODE>signal</CODE> function returns the action that was previously in
effect for the specified <VAR>signum</VAR>.  You can save this value and
restore it later by calling <CODE>signal</CODE> again.
<P>
If <CODE>signal</CODE> can't honor the request, it returns <CODE>SIG_ERR</CODE>
instead.  The following <CODE>errno</CODE> error conditions are defined for
this function:
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>You specified an invalid <VAR>signum</VAR>; or you tried to ignore or provide
a handler for <CODE>SIGKILL</CODE> or <CODE>SIGSTOP</CODE>.
</DL>
<P>
Here is a simple example of setting up a handler to delete temporary
files when certain fatal signals happen:
<P>
<PRE>
#include &#60;signal.h&#62;

void
termination_handler (int signum)
{
  struct temp_file *p;

  for (p = temp_file_list; p; p = p-&#62;next)
    unlink (p-&#62;name);
}

int
main (void)
{
  ...
  if (signal (SIGINT, termination_handler) == SIG_IGN)
    signal (SIGINT, SIG_IGN);
  if (signal (SIGHUP, termination_handler) == SIG_IGN)
    signal (SIGHUP, SIG_IGN);
  if (signal (SIGTERM, termination_handler) == SIG_IGN)
    signal (SIGTERM, SIG_IGN);
  ...
}
</PRE>
<P>
Note how if a given signal was previously set to be ignored, this code
avoids altering that setting.  This is because non-job-control shells
often ignore certain signals when starting children, and it is important
for the children to respect this.
<P>
We do not handle <CODE>SIGQUIT</CODE> or the program error signals in this
example because these are designed to provide information for debugging
(a core dump), and the temporary files may give useful information.
<P>
<A NAME="IDX1545"></A>
<U>Function:</U> sighandler_t <B>ssignal</B> <I>(int <VAR>signum</VAR>, sighandler_t <VAR>action</VAR>)</I><P>
The <CODE>ssignal</CODE> function does the same thing as <CODE>signal</CODE>; it is
provided only for compatibility with SVID.
<P>
<A NAME="IDX1546"></A>
<U>Macro:</U> sighandler_t <B>SIG_ERR</B><P>
The value of this macro is used as the return value from <CODE>signal</CODE>
to indicate an error.
<P>
<A NAME="IDX1547"></A>
<H3><A NAME="SEC346" HREF="library_toc.html#SEC346">Advanced Signal Handling</A></H3>
<P>
The <CODE>sigaction</CODE> function has the same basic effect as
<CODE>signal</CODE>: to specify how a signal should be handled by the process.
However, <CODE>sigaction</CODE> offers more control, at the expense of more
complexity.  In particular, <CODE>sigaction</CODE> allows you to specify
additional flags to control when the signal is generated and how the
handler is invoked.
<P>
The <CODE>sigaction</CODE> function is declared in <TT>`signal.h'</TT>.
<A NAME="IDX1548"></A>
<P>
<A NAME="IDX1549"></A>
<U>Data Type:</U> <B>struct sigaction</B><P>
Structures of type <CODE>struct sigaction</CODE> are used in the
<CODE>sigaction</CODE> function to specify all the information about how to
handle a particular signal.  This structure contains at least the
following members:
<P>
<DL COMPACT>
<DT><CODE>sighandler_t sa_handler</CODE>
<DD>This is used in the same way as the <VAR>action</VAR> argument to the
<CODE>signal</CODE> function.  The value can be <CODE>SIG_DFL</CODE>,
<CODE>SIG_IGN</CODE>, or a function pointer.  See section <A HREF="library.html#SEC345">Basic Signal Handling</A>.
<P>
<DT><CODE>sigset_t sa_mask</CODE>
<DD>This specifies a set of signals to be blocked while the handler runs.
Blocking is explained in section <A HREF="library.html#SEC373">Blocking Signals for a Handler</A>.  Note that the
signal that was delivered is automatically blocked by default before its
handler is started; this is true regardless of the value in
<CODE>sa_mask</CODE>.  If you want that signal not to be blocked within its
handler, you must write code in the handler to unblock it.
<P>
<DT><CODE>int sa_flags</CODE>
<DD>This specifies various flags which can affect the behavior of 
the signal.  These are described in more detail in section <A HREF="library.html#SEC349">Flags for <CODE>sigaction</CODE></A>.
</DL>
<P>
<A NAME="IDX1550"></A>
<U>Function:</U> int <B>sigaction</B> <I>(int <VAR>signum</VAR>, const struct sigaction *<VAR>action</VAR>, struct sigaction *<VAR>old_action</VAR>)</I><P>
The <VAR>action</VAR> argument is used to set up a new action for the signal
<VAR>signum</VAR>, while the <VAR>old_action</VAR> argument is used to return
information about the action previously associated with this symbol.
(In other words, <VAR>old_action</VAR> has the same purpose as the
<CODE>signal</CODE> function's return value--you can check to see what the
old action in effect for the signal was, and restore it later if you
want.)
<P>
Either <VAR>action</VAR> or <VAR>old_action</VAR> can be a null pointer.  If
<VAR>old_action</VAR> is a null pointer, this simply suppresses the return
of information about the old action.  If <VAR>action</VAR> is a null pointer,
the action associated with the signal <VAR>signum</VAR> is unchanged; this
allows you to inquire about how a signal is being handled without changing
that handling.
<P>
The return value from <CODE>sigaction</CODE> is zero if it succeeds, and
<CODE>-1</CODE> on failure.  The following <CODE>errno</CODE> error conditions are
defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>signum</VAR> argument is not valid, or you are trying to
trap or ignore <CODE>SIGKILL</CODE> or <CODE>SIGSTOP</CODE>.
</DL>
<P>
<H3><A NAME="SEC347" HREF="library_toc.html#SEC347">Interaction of <CODE>signal</CODE> and <CODE>sigaction</CODE></A></H3>
<P>
It's possible to use both the <CODE>signal</CODE> and <CODE>sigaction</CODE>
functions within a single program, but you have to be careful because
they can interact in slightly strange ways.
<P>
The <CODE>sigaction</CODE> function specifies more information than the
<CODE>signal</CODE> function, so the return value from <CODE>signal</CODE> cannot
express the full range of <CODE>sigaction</CODE> possibilities.  Therefore, if
you use <CODE>signal</CODE> to save and later reestablish an action, it may
not be able to reestablish properly a handler that was established with
<CODE>sigaction</CODE>.
<P>
To avoid having problems as a result, always use <CODE>sigaction</CODE> to
save and restore a handler if your program uses <CODE>sigaction</CODE> at all.
Since <CODE>sigaction</CODE> is more general, it can properly save and
reestablish any action, regardless of whether it was established
originally with <CODE>signal</CODE> or <CODE>sigaction</CODE>.
<P>
If you establish an action with <CODE>signal</CODE> and then examine it with
<CODE>sigaction</CODE>, the handler address that you get may not be the same
as what you specified with <CODE>signal</CODE>.  It may not even be suitable
for use as an action argument with <CODE>signal</CODE>.  But you can rely on
using it as an argument to <CODE>sigaction</CODE>.
<P>
So, you're better off using one or the other of the mechanisms
consistently within a single program.  
<P>
<STRONG>Portability Note:</STRONG> The basic <CODE>signal</CODE> function is a feature
of ANSI C, while <CODE>sigaction</CODE> is part of the POSIX.1 standard.  If
you are concerned about portability to non-POSIX systems, then you
should use the <CODE>signal</CODE> function instead.
<P>
<H3><A NAME="SEC348" HREF="library_toc.html#SEC348"><CODE>sigaction</CODE> Function Example</A></H3>
<P>
In section <A HREF="library.html#SEC345">Basic Signal Handling</A>, we gave an example of establishing a
simple handler for termination signals using <CODE>signal</CODE>.  Here is an
equivalent example using <CODE>sigaction</CODE>:
<P>
<PRE>
#include &#60;signal.h&#62;

void
termination_handler (int signum)
{
  struct temp_file *p;

  for (p = temp_file_list; p; p = p-&#62;next)
    unlink (p-&#62;name);
}

int
main (void)
{
  ...
  struct sigaction new_action, old_action;

  /* Set up the structure to specify the new action. */
  new_action.sa_handler = termination_handler;
  sigemptyset (&#38;new_action.sa_mask);
  new_action.sa_flags = 0;

  sigaction (SIGINT, NULL, &#38;old_action);
  if (old_action.sa_handler != SIG_IGN)
    sigaction (SIGINT, &#38;new_action, NULL);
  sigaction (SIGHUP, NULL, &#38;old_action);
  if (old_action.sa_handler != SIG_IGN)
    sigaction (SIGHUP, &#38;new_action, NULL);
  sigaction (SIGTERM, NULL, &#38;old_action);
  if (old_action.sa_handler != SIG_IGN)
    sigaction (SIGTERM, &#38;new_action, NULL);
  ...
}
</PRE>
<P>
The program just loads the <CODE>new_action</CODE> structure with the desired
parameters and passes it in the <CODE>sigaction</CODE> call.  The usage of
<CODE>sigemptyset</CODE> is described later; see section <A HREF="library.html#SEC368">Blocking Signals</A>.
<P>
As in the example using <CODE>signal</CODE>, we avoid handling signals
previously set to be ignored.  Here we can avoid altering the signal
handler even momentarily, by using the feature of <CODE>sigaction</CODE> that
lets us examine the current action without specifying a new one.
<P>
Here is another example.  It retrieves information about the current
action for <CODE>SIGINT</CODE> without changing that action.
<P>
<PRE>
struct sigaction query_action;

if (sigaction (SIGINT, NULL, &#38;query_action) &#60; 0)
  /* <CODE>sigaction</CODE> returns -1 in case of error. */ 
else if (query_action.sa_handler == SIG_DFL)
  /* <CODE>SIGINT</CODE> is handled in the default, fatal manner. */
else if (query_action.sa_handler == SIG_IGN)
  /* <CODE>SIGINT</CODE> is ignored. */
else
  /* A programmer-defined signal handler is in effect. */
</PRE>
<P>
<A NAME="IDX1551"></A>
<A NAME="IDX1552"></A>
<A NAME="IDX1553"></A>
<H3><A NAME="SEC349" HREF="library_toc.html#SEC349">Flags for <CODE>sigaction</CODE></A></H3>
<P>
The <CODE>sa_flags</CODE> member of the <CODE>sigaction</CODE> structure is a
catch-all for special features.  Most of the time, <CODE>SA_RESTART</CODE> is
a good value to use for this field.
<P>
The value of <CODE>sa_flags</CODE> is interpreted as a bit mask.  Thus, you
should choose the flags you want to set, OR those flags together,
and store the result in the <CODE>sa_flags</CODE> member of your
<CODE>sigaction</CODE> structure.
<P>
Each signal number has its own set of flags.  Each call to
<CODE>sigaction</CODE> affects one particular signal number, and the flags
that you specify apply only to that particular signal.
<P>
In the GNU C library, establishing a handler with <CODE>signal</CODE> sets all
the flags to zero except for <CODE>SA_RESTART</CODE>, whose value depends on
the settings you have made with <CODE>siginterrupt</CODE>.  See section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>, to see what this is about.
<A NAME="IDX1554"></A>
<P>
These macros are defined in the header file <TT>`signal.h'</TT>.
<P>
<A NAME="IDX1555"></A>
<U>Macro:</U> int <B>SA_NOCLDSTOP</B><P>
This flag is meaningful only for the <CODE>SIGCHLD</CODE> signal.  When the
flag is set, the system delivers the signal for a terminated child
process but not for one that is stopped.  By default, <CODE>SIGCHLD</CODE> is
delivered for both terminated children and stopped children.
<P>
Setting this flag for a signal other than <CODE>SIGCHLD</CODE> has no effect.
<P>
<A NAME="IDX1556"></A>
<U>Macro:</U> int <B>SA_ONSTACK</B><P>
If this flag is set for a particular signal number, the system uses the
signal stack when delivering that kind of signal.  See section <A HREF="library.html#SEC380">BSD Signal Handling</A>.
<P>
<A NAME="IDX1557"></A>
<U>Macro:</U> int <B>SA_RESTART</B><P>
This flag controls what happens when a signal is delivered during
certain primitives (such as <CODE>open</CODE>, <CODE>read</CODE> or <CODE>write</CODE>),
and the signal handler returns normally.  There are two alternatives:
the library function can resume, or it can return failure with error
code <CODE>EINTR</CODE>.
<P>
The choice is controlled by the <CODE>SA_RESTART</CODE> flag for the
particular kind of signal that was delivered.  If the flag is set,
returning from a handler resumes the library function.  If the flag is
clear, returning from a handler makes the function fail.
See section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<A NAME="IDX1558"></A>
<H3><A NAME="SEC350" HREF="library_toc.html#SEC350">Initial Signal Actions</A></H3>
<P>
When a new process is created (see section <A HREF="library.html#SEC405">Creating a Process</A>), it inherits
handling of signals from its parent process.  However, when you load a
new process image using the <CODE>exec</CODE> function (see section <A HREF="library.html#SEC406">Executing a File</A>), any signals that you've defined your own handlers for revert to
their <CODE>SIG_DFL</CODE> handling.  (If you think about it a little, this
makes sense; the handler functions from the old program are specific to
that program, and aren't even present in the address space of the new
program image.)  Of course, the new program can establish its own
handlers.
<P>
When a program is run by a shell, the shell normally sets the initial
actions for the child process to <CODE>SIG_DFL</CODE> or <CODE>SIG_IGN</CODE>, as
appropriate.  It's a good idea to check to make sure that the shell has
not set up an initial action of <CODE>SIG_IGN</CODE> before you establish your
own signal handlers.
<P>
Here is an example of how to establish a handler for <CODE>SIGHUP</CODE>, but
not if <CODE>SIGHUP</CODE> is currently ignored:
<P>
<PRE>
...
struct sigaction temp;

sigaction (SIGHUP, NULL, &#38;temp);

if (temp.sa_handler != SIG_IGN)
  {
    temp.sa_handler = handle_sighup;
    sigemptyset (&#38;temp.sa_mask);
    sigaction (SIGHUP, &#38;temp, NULL);
  }
</PRE>
<P>
<A NAME="IDX1559"></A>
<H2><A NAME="SEC351" HREF="library_toc.html#SEC351">Defining Signal Handlers</A></H2>
<P>
This section describes how to write a signal handler function that can
be established with the <CODE>signal</CODE> or <CODE>sigaction</CODE> functions.
<P>
A signal handler is just a function that you compile together with the
rest of the program.  Instead of directly invoking the function, you use
<CODE>signal</CODE> or <CODE>sigaction</CODE> to tell the operating system to call
it when a signal arrives.  This is known as <DFN>establishing</DFN> the
handler.  See section <A HREF="library.html#SEC344">Specifying Signal Actions</A>.
<P>
There are two basic strategies you can use in signal handler functions:
<P>
<UL>
<LI>
You can have the handler function note that the signal arrived by
tweaking some global data structures, and then return normally.
<P>
<LI>
You can have the handler function terminate the program or transfer
control to a point where it can recover from the situation that caused
the signal.
</UL>
<P>
You need to take special care in writing handler functions because they
can be called asynchronously.  That is, a handler might be called at any
point in the program, unpredictably.  If two signals arrive during a
very short interval, one handler can run within another.  This section
describes what your handler should do, and what you should avoid.
<P>
<H3><A NAME="SEC352" HREF="library_toc.html#SEC352">Signal Handlers That Return</A></H3>
<P>
Handlers which return normally are usually used for signals such as
<CODE>SIGALRM</CODE> and the I/O and interprocess communication signals.  But
a handler for <CODE>SIGINT</CODE> might also return normally after setting a
flag that tells the program to exit at a convenient time.
<P>
It is not safe to return normally from the handler for a program error
signal, because the behavior of the program when the handler function
returns is not defined after a program error.  See section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
Handlers that return normally must modify some global variable in order
to have any effect.  Typically, the variable is one that is examined
periodically by the program during normal operation.  Its data type
should be <CODE>sig_atomic_t</CODE> for reasons described in section <A HREF="library.html#SEC358">Atomic Data Access and Signal Handling</A>.
<P>
Here is a simple example of such a program.  It executes the body of
the loop until it has noticed that a <CODE>SIGALRM</CODE> signal has arrived.
This technique is useful because it allows the iteration in progress
when the signal arrives to complete before the loop exits.
<P>
<PRE>
#include &#60;signal.h&#62;
#include &#60;stdio.h&#62;
#include &#60;stdlib.h&#62;

/* This flag controls termination of the main loop.  */
volatile sig_atomic_t keep_going = 1;

/* The signal handler just clears the flag and re-enables itself.  */
void 
catch_alarm (int sig)
{
  keep_going = 0;
  signal (sig, catch_alarm);
}

void 
do_stuff (void)
{
  puts ("Doing stuff while waiting for alarm....");
}

int
main (void)
{
  /* Establish a handler for SIGALRM signals.  */
  signal (SIGALRM, catch_alarm);

  /* Set an alarm to go off in a little while.  */
  alarm (2);

  /* Check the flag once in a while to see when to quit.  */
  while (keep_going)
    do_stuff ();

  return EXIT_SUCCESS;
}
</PRE>
<P>
<H3><A NAME="SEC353" HREF="library_toc.html#SEC353">Handlers That Terminate the Process</A></H3>
<P>
Handler functions that terminate the program are typically used to cause
orderly cleanup or recovery from program error signals and interactive
interrupts.
<P>
The cleanest way for a handler to terminate the process is to raise the
same signal that ran the handler in the first place.  Here is how to do
this:
<P>
<PRE>
volatile sig_atomic_t fatal_error_in_progress = 0;

void
fatal_error_signal (int sig)
{
  /* Since this handler is established for more than one kind of signal, 
     it might still get invoked recursively by delivery of some other kind
     of signal.  Use a static variable to keep track of that. */
  if (fatal_error_in_progress)
    raise (sig);
  fatal_error_in_progress = 1;

  /* Now do the clean up actions:
     - reset terminal modes
     - kill child processes
     - remove lock files */
  ...

  /* Now reraise the signal.  Since the signal is blocked,
     it will receive its default handling, which is
     to terminate the process.  We could just call
     <CODE>exit</CODE> or <CODE>abort</CODE>, but reraising the signal
     sets the return status from the process correctly. */
  raise (sig);
}
</PRE>
<P>
<A NAME="IDX1560"></A>
<H3><A NAME="SEC354" HREF="library_toc.html#SEC354">Nonlocal Control Transfer in Handlers</A></H3>
<P>
You can do a nonlocal transfer of control out of a signal handler using
the <CODE>setjmp</CODE> and <CODE>longjmp</CODE> facilities (see section <A HREF="library.html#SEC326">Non-Local Exits</A>).
<P>
When the handler does a nonlocal control transfer, the part of the
program that was running will not continue.  If this part of the program
was in the middle of updating an important data structure, the data
structure will remain inconsistent.  Since the program does not
terminate, the inconsistency is likely to be noticed later on.
<P>
There are two ways to avoid this problem.  One is to block the signal
for the parts of the program that update important data structures.
Blocking the signal delays its delivery until it is unblocked, once the
critical updating is finished.  See section <A HREF="library.html#SEC368">Blocking Signals</A>.
<P>
The other way to re-initialize the crucial data structures in the signal
handler, or make their values consistent.
<P>
Here is a rather schematic example showing the reinitialization of one
global variable.
<P>
<PRE>
#include &#60;signal.h&#62;
#include &#60;setjmp.h&#62;

jmp_buf return_to_top_level;

volatile sig_atomic_t waiting_for_input;

void
handle_sigint (int signum)
{
  /* We may have been waiting for input when the signal arrived,
     but we are no longer waiting once we transfer control. */
  waiting_for_input = 0;
  longjmp (return_to_top_level, 1);
}

int
main (void)
{
  ...
  signal (SIGINT, sigint_handler);
  ...
  while (1) {
    prepare_for_command ();
    if (setjmp (return_to_top_level) == 0)
      read_and_execute_command ();
  }
}

/* Imagine this is a subroutine used by various commands. */
char *
read_data ()
{
  if (input_from_terminal) {
    waiting_for_input = 1;
    ...
    waiting_for_input = 0;
  } else { 
    ...
  }
}
</PRE>
<P>
<A NAME="IDX1561"></A>
<H3><A NAME="SEC355" HREF="library_toc.html#SEC355">Signals Arriving While a Handler Runs</A></H3>
<P>
What happens if another signal arrives when your signal handler function
is running?
<P>
When the handler for a particular signal is invoked, that signal is
normally blocked until the handler returns.  That means that if two
signals of the same kind arrive close together, the second one will be
held until the first has been handled.  (The handler can explicitly
unblock the signal using <CODE>sigprocmask</CODE>, if you want to allow more
signals of this type to arrive; see section <A HREF="library.html#SEC371">Process Signal Mask</A>.)
<P>
However, your handler can still be interrupted by delivery of another
kind of signal.  To avoid this, you can use the <CODE>sa_mask</CODE> member of
the action structure passed to <CODE>sigaction</CODE> to explicitly specify
which signals should be blocked while the signal handler runs.  These
signals are in addition to the signal for which the handler was invoked,
and any other signals that are normally blocked by the process.
See section <A HREF="library.html#SEC373">Blocking Signals for a Handler</A>.
<P>
<STRONG>Portability Note:</STRONG> Always use <CODE>sigaction</CODE> to establish a
handler for a signal that you expect to receive asynchronously, if you
want your program to work properly on System V Unix.  On this system,
the handling of a signal whose handler was established with
<CODE>signal</CODE> automatically sets the signal's action back to
<CODE>SIG_DFL</CODE>, and the handler must re-establish itself each time it
runs.  This practice, while inconvenient, does work when signals cannot
arrive in succession.  However, if another signal can arrive right away,
it may arrive before the handler can re-establish itself.  Then the
second signal would receive the default handling, which could terminate
the process.
<P>
<A NAME="IDX1562"></A>
<A NAME="IDX1563"></A>
<A NAME="IDX1564"></A>
<H3><A NAME="SEC356" HREF="library_toc.html#SEC356">Signals Close Together Merge into One</A></H3>
<P>
If multiple signals of the same type are delivered to your process
before your signal handler has a chance to be invoked at all, the
handler may only be invoked once, as if only a single signal had
arrived.  In effect, the signals merge into one.  This situation can
arise when the signal is blocked, or in a multiprocessing environment
where the system is busy running some other processes while the signals
are delivered.  This means, for example, that you cannot reliably use a
signal handler to count signals.  The only distinction you can reliably
make is whether at least one signal has arrived since a given time in
the past.
<P>
Here is an example of a handler for <CODE>SIGCHLD</CODE> that compensates for
the fact that the number of signals recieved may not equal the number of
child processes generate them.  It assumes that the program keeps track
of all the child processes with a chain of structures as follows:
<P>
<PRE>
struct process
{
  struct process *next;
  /* The process ID of this child.  */
  int pid;
  /* The descriptor of the pipe or pseudo terminal
     on which output comes from this child.  */
  int input_descriptor;
  /* Nonzero if this process has stopped or terminated.  */
  sig_atomic_t have_status;
  /* The status of this child; 0 if running,
     otherwise a status value from <CODE>waitpid</CODE>.  */
  int status;
};

struct process *process_list;
</PRE>
<P>
This example also uses a flag to indicate whether signals have arrived
since some time in the past--whenever the program last cleared it to
zero.
<P>
<PRE>
/* Nonzero means some child's status has changed
   so look at <CODE>process_list</CODE> for the details.  */
int process_status_change;
</PRE>
<P>
Here is the handler itself:
<P>
<PRE>
void
sigchld_handler (int signo)
{
  int old_errno = errno;

  while (1) {
    register int pid;
    int w;
    struct process *p;

    /* Keep asking for a status until we get a definitive result.  */
    do 
      {
        errno = 0;
        pid = waitpid (WAIT_ANY, &#38;w, WNOHANG | WUNTRACED);
      }
    while (pid &#60;= 0 &#38;&#38; errno == EINTR);

    if (pid &#60;= 0) {
      /* A real failure means there are no more
         stopped or terminated child processes, so return.  */
      errno = old_errno;
      return;
    }

    /* Find the process that signaled us, and record its status.  */

    for (p = process_list; p; p = p-&#62;next)
      if (p-&#62;pid == pid) {
        p-&#62;status = w;
        /* Indicate that the <CODE>status</CODE> field
           has data to look at.  We do this only after storing it.  */
        p-&#62;have_status = 1;

        /* If process has terminated, stop waiting for its output.  */
        if (WIFSIGNALED (w) || WIFEXITED (w))
          if (p-&#62;input_descriptor)
            FD_CLR (p-&#62;input_descriptor, &#38;input_wait_mask);

        /* The program should check this flag from time to time
           to see if there is any news in <CODE>process_list</CODE>.  */
        ++process_status_change;
      }

    /* Loop around to handle all the processes
       that have something to tell us.  */
  }
}
</PRE>
<P>
Here is the proper way to check the flag <CODE>process_status_change</CODE>:
<P>
<PRE>
if (process_status_change) {
  struct process *p;
  process_status_change = 0;
  for (p = process_list; p; p = p-&#62;next)
    if (p-&#62;have_status) {
      ... Examine <CODE>p-&#62;status</CODE> ...
    }
}
</PRE>
<P>
It is vital to clear the flag before examining the list; otherwise, if a
signal were delivered just before the clearing of the flag, and after
the appropriate element of the process list had been checked, the status
change would go unnoticed until the next signal arrived to set the flag
again.  You could, of course, avoid this problem by blocking the signal
while scanning the list, but it is much more elegant to guarantee
correctness by doing things in the right order.
<P>
The loop which checks process status avoids examining <CODE>p-&#62;status</CODE>
until it sees that status has been validly stored.  This is to make sure
that the status cannot change in the middle of accessing it.  Once
<CODE>p-&#62;have_status</CODE> is set, it means that the child process is stopped
or terminated, and in either case, it cannot stop or terminate again
until the program has taken notice.  See section <A HREF="library.html#SEC361">Atomic Usage Patterns</A>, for more
information about coping with interruptions during accessings of a
variable.
<P>
Here is another way you can test whether the handler has run since the
last time you checked.  This technique uses a counter which is never
changed outside the handler.  Instead of clearing the count, the program
remembers the previous value and sees whether it has changed since the
previous check.  The advantage of this method is that different parts of
the program can check independently, each part checking whether there
has been a signal since that part last checked.
<P>
<PRE>
sig_atomic_t process_status_change;

sig_atomic_t last_process_status_change;

...
{
  sig_atomic_t prev = last_process_status_change;
  last_process_status_change = process_status_change;
  if (last_process_status_change != prev) {
    struct process *p;
    for (p = process_list; p; p = p-&#62;next)
      if (p-&#62;have_status) {
        ... Examine <CODE>p-&#62;status</CODE> ...
      }
  }
}
</PRE>
<P>
<A NAME="IDX1565"></A>
<H3><A NAME="SEC357" HREF="library_toc.html#SEC357">Signal Handling and Nonreentrant Functions</A></H3>
<P>
Handler functions usually don't do very much.  The best practice is to
write a handler that does nothing but set an external variable that the
program checks regularly, and leave all serious work to the program.
This is best because the handler can be called at asynchronously, at
unpredictable times--perhaps in the middle of a system call, or even
between the beginning and the end of a C operator that requires multiple
instructions.  The data structures being manipulated might therefore be
in an inconsistent state when the handler function is invoked.  Even
copying one <CODE>int</CODE> variable into another can take two instructions
on most machines.
<P>
This means you have to be very careful about what you do in a signal
handler.
<P>
<UL>
<A NAME="IDX1566"></A>
<LI>
If your handler needs to access any global variables from your program,
declare those variables <CODE>volatile</CODE>.  This tells the compiler that
the value of the variable might change asynchronously, and inhibits
certain optimizations that would be invalidated by such modifications.
<P>
<A NAME="IDX1567"></A>
<LI>
If you call a function in the handler, make sure it is <DFN>reentrant</DFN>
with respect to signals, or else make sure that the signal cannot
interrupt a call to a related function.
</UL>
<P>
A function can be non-reentrant if it uses memory that is not on the
stack.
<P>
<UL>
<LI>
If a function uses a static variable or a global variable, or a
dynamically-allocated object that it finds for itself, then it is
non-reentrant and any two calls to the function can interfere.
<P>
For example, suppose that the signal handler uses <CODE>gethostbyname</CODE>.
This function returns its value in a static object, reusing the same
object each time.  If the signal happens to arrive during a call to
<CODE>gethostbyname</CODE>, or even after one (while the program is still
using the value), it will clobber the value that the program asked for.
<P>
However, if the program does not use <CODE>gethostbyname</CODE> or any other
function that returns information in the same object, or if it always
blocks signals around each use, then you are safe.
<P>
There are a large number of library functions that return values in a
fixed object, always reusing the same object in this fashion, and all of
them cause the same problem.  The description of a function in this
manual always mentions this behavior.
<P>
<LI>
If a function uses and modifies an object that you supply, then it is
potentially non-reentrant; two calls can interfere if they use the same
object.
<P>
This case arises when you do I/O using streams.  Suppose that the
signal handler prints a message with <CODE>fprintf</CODE>.  Suppose that the
program was in the middle of an <CODE>fprintf</CODE> call using the same
stream when the signal was delivered.  Both the signal handler's message
and the program's data could be corrupted, because both calls operate on
the same data structure--the stream itself.
<P>
However, if you know that the stream that the handler uses cannot
possibly be used by the program at a time when signals can arrive, then
you are safe.  It is no problem if the program uses some other stream.
<P>
<LI>
On most systems, <CODE>malloc</CODE> and <CODE>free</CODE> are not reentrant,
because they use a static data structure which records what memory
blocks are free.  As a result, no library functions that allocate or
free memory are reentrant.  This includes functions that allocate space
to store a result.
<P>
The best way to avoid the need to allocate memory in a handler is to
allocate in advance space for signal handlers to use.
<P>
The best way to avoid freeing memory in a handler is to flag or record
the objects to be freed, and have the program check from time to time
whether anything is waiting to be freed.  But this must be done with
care, because placing an object on a chain is not atomic, and if it is
interrupted by another signal handler that does the same thing, you
could "lose" one of the objects.
<P>
On the GNU system, <CODE>malloc</CODE> and <CODE>free</CODE> are safe to use in
signal handlers because it blocks signals.  As a result, the library
functions that allocate space for a result are also safe in signal
handlers.  The obstack allocation functions are safe as long as you
don't use the same obstack both inside and outside of a signal handler.
<P>
The relocating allocation functions (see section <A HREF="library.html#SEC50">Relocating Allocator</A>)
are certainly not safe to use in a signal handler.
<P>
<LI>
Any function that modifies <CODE>errno</CODE> is non-reentrant, but you can
correct for this: in the handler, save the original value of
<CODE>errno</CODE> and restore it before returning normally.  This prevents
errors that occur within the signal handler from being confused with
errors from system calls at the point the program is interrupted to run
the handler.
<P>
This technique is generally applicable; if you want to call in a handler
a function that modifies a particular object in memory, you can make
this safe by saving and restoring that object.
<P>
<LI>
Merely reading from a memory object is safe provided that you can deal
with any of the values that might appear in the object at a time when
the signal can be delivered.  Keep in mind that assignment to some data
types requires more than one instruction, which means that the handler
could run "in the middle of" an assignment to the variable if its type
is not atomic.  See section <A HREF="library.html#SEC358">Atomic Data Access and Signal Handling</A>.
<P>
<LI>
Merely writing into a memory object is safe as long as a sudden change
in the value, at any time when the handler might run, will not disturb
anything.
</UL>
<P>
<H3><A NAME="SEC358" HREF="library_toc.html#SEC358">Atomic Data Access and Signal Handling</A></H3>
<P>
Whether the data in your application concerns atoms, or mere text, you
have to be careful about the fact that access to a single datum is not
necessarily <DFN>atomic</DFN>.  This means that it can take more than one
instruction to read or write a single object.  In such cases, a signal
handler can run in the middle of reading or writing the object.
<P>
There are three ways you can cope with this problem.  You can use data
types that are always accessed atomically; you can carefully arrange
that nothing untoward happens if an access is interrupted, or you can
block all signals around any access that had better not be interrupted
(see section <A HREF="library.html#SEC368">Blocking Signals</A>).
<P>
<H4><A NAME="SEC359" HREF="library_toc.html#SEC359">Example of Problems with Non-Atomic Access</A></H4>
<P>
Here is an example which shows what can happen if a signal handler runs
in the middle of modifying a variable.  (Interrupting the reading of a
variable can also lead to paradoxical results, but here we only show
writing.)
<P>
<PRE>
#include &#60;signal.h&#62;
#include &#60;stdio.h&#62;

struct two_words { int a, b; } memory;

void
handler(int signum)
{
   printf ("%d,%d\n", memory.a, memory.b);
   alarm (1);
}

int
main (void)
{
   static struct two_words zeros = { 0, 0 }, ones = { 1, 1 };
   signal (SIGALRM, handler);
   memory = zeros;
   alarm (1);
   while (1)
     {
       memory = zeros;
       memory = ones;
     }
}
</PRE>
<P>
This program fills <CODE>memory</CODE> with zeros, ones, zeros, ones,
alternating forever; meanwhile, once per second, the alarm signal handler
prints the current contents.  (Calling <CODE>printf</CODE> in the handler is
safe in this program because it is certainly not being called outside
the handler when the signal happens.)
<P>
Clearly, this program can print a pair of zeros or a pair of ones.  But
that's not all it can do!  On most machines, it takes several
instructions to store a new value in <CODE>memory</CODE>, and the value is
stored one word at a time.  If the signal is delivered in between these
instructions, the handler might find that <CODE>memory.a</CODE> is zero and
<CODE>memory.b</CODE> is one (or vice versa).
<P>
On some machines it may be possible to store a new value in
<CODE>memory</CODE> with just one instruction that cannot be interrupted.  On
these machines, the handler will always print two zeros or two ones.
<P>
<H4><A NAME="SEC360" HREF="library_toc.html#SEC360">Atomic Types</A></H4>
<P>
To avoid uncertainty about interrupting access to a variable, you can
use a particular data type for which access is always atomic:
<CODE>sig_atomic_t</CODE>.  Reading and writing this data type is guaranteed
to happen in a single instruction, so there's no way for a handler to
run "in the middle" of an access.
<P>
The type <CODE>sig_atomic_t</CODE> is always an integer data type, but which
one it is, and how many bits it contains, may vary from machine to
machine.
<P>
<A NAME="IDX1568"></A>
<U>Data Type:</U> <B>sig_atomic_t</B><P>
This is an integer data type.  Objects of this type are always accessed
atomically.
<P>
In practice, you can assume that <CODE>int</CODE> and other integer types no
longer than <CODE>int</CODE> are atomic.  You can also assume that pointer
types are atomic; that is very convenient.  Both of these are true on
all of the machines that the GNU C library supports, and on all POSIX
systems we know of.
<P>
<H4><A NAME="SEC361" HREF="library_toc.html#SEC361">Atomic Usage Patterns</A></H4>
<P>
Certain patterns of access avoid any problem even if an access is
interrupted.  For example, a flag which is set by the handler, and
tested and cleared by the main program from time to time, is always safe
even if access actually requires two instructions.  To show that this is
so, we must consider each access that could be interrupted, and show
that there is no problem if it is interrupted.
<P>
An interrupt in the middle of testing the flag is safe because either it's
recognized to be nonzero, in which case the precise value doesn't
matter, or it will be seen to be nonzero the next time it's tested.
<P>
An interrupt in the middle of clearing the flag is no problem because
either the value ends up zero, which is what happens if a signal comes
in just before the flag is cleared, or the value ends up nonzero, and
subsequent events occur as if the signal had come in just after the flag
was cleared.  As long as the code handles both of these cases properly,
it can also handle a signal in the middle of clearing the flag.  (This
is an example of the sort of reasoning you need to do to figure out
whether non-atomic usage is safe.)
<P>
Sometimes you can insure uninterrupted access to one object by
protecting its use with another object, perhaps one whose type
guarantees atomicity.  See section <A HREF="library.html#SEC356">Signals Close Together Merge into One</A>, for an example.
<P>
<H2><A NAME="SEC362" HREF="library_toc.html#SEC362">Primitives Interrupted by Signals</A></H2>
<P>
A signal can arrive and be handled while an I/O primitive such as
<CODE>open</CODE> or <CODE>read</CODE> is waiting for an I/O device.  If the signal
handler returns, the system faces the question: what should happen next?
<P>
POSIX specifies one approach: make the primitive fail right away.  The
error code for this kind of failure is <CODE>EINTR</CODE>.  This is flexible,
but usually inconvenient.  Typically, POSIX applications that use signal
handlers must check for <CODE>EINTR</CODE> after each library function that
can return it, in order to try the call again.  Often programmers forget
to check, which is a common source of error.
<P>
The GNU library provides a convenient way to retry a call after a
temporary failure, with the macro <CODE>TEMP_FAILURE_RETRY</CODE>:
<P>
<A NAME="IDX1569"></A>
<U>Macro:</U> <B>TEMP_FAILURE_RETRY</B> <I>(<VAR>expression</VAR>)</I><P>
This macro evaluates <VAR>expression</VAR> once.  If it fails and reports
error code <CODE>EINTR</CODE>, <CODE>TEMP_FAILURE_RETRY</CODE> evaluates it again,
and over and over until the result is not a temporary failure.
<P>
The value returned by <CODE>TEMP_FAILURE_RETRY</CODE> is whatever value
<VAR>expression</VAR> produced.
<P>
BSD avoids <CODE>EINTR</CODE> entirely and provides a more convenient
approach: to restart the interrupted primitive, instead of making it
fail.  If you choose this approach, you need not be concerned with
<CODE>EINTR</CODE>.
<P>
You can choose either approach with the GNU library.  If you use
<CODE>sigaction</CODE> to establish a signal handler, you can specify how that
handler should behave.  If you specify the <CODE>SA_RESTART</CODE> flag,
return from that handler will resume a primitive; otherwise, return from
that handler will cause <CODE>EINTR</CODE>.  See section <A HREF="library.html#SEC349">Flags for <CODE>sigaction</CODE></A>.
<P>
Another way to specify the choice is with the <CODE>siginterrupt</CODE>
function.  See section <A HREF="library.html#SEC381">POSIX and BSD Signal Facilities</A>.
<P>
When you don't specify with <CODE>sigaction</CODE> or <CODE>siginterrupt</CODE> what
a particular handler should do, it uses a default choice.  The default
choice in the GNU library depends on the feature test macros you have
defined.  If you define <CODE>_BSD_SOURCE</CODE> or <CODE>_GNU_SOURCE</CODE> before
calling <CODE>signal</CODE>, the default is to resume primitives; otherwise,
the default is to make them fail with <CODE>EINTR</CODE>.  (The library
contains alternate versions of the <CODE>signal</CODE> function, and the
feature test macros determine which one you really call.)  See section <A HREF="library.html#SEC12">Feature Test Macros</A>.
<P>
The primitives affected by this issue are <CODE>close</CODE>, <CODE>fcntl</CODE>
(operation <CODE>F_SETLK</CODE>), <CODE>open</CODE>, <CODE>read</CODE>, <CODE>recv</CODE>,
<CODE>recvfrom</CODE>, <CODE>select</CODE>, <CODE>send</CODE>, <CODE>sendto</CODE>,
<CODE>tcdrain</CODE>, <CODE>waitpid</CODE>, <CODE>wait</CODE>, and <CODE>write</CODE>.
<P>
There is one situation where resumption never happens no matter which
choice you make: when a data-transfer function such as <CODE>read</CODE> or
<CODE>write</CODE> is interrupted by a signal after transferring part of the
data.  In this case, the function returns the number of bytes already
transferred, indicating partial success.
<P>
This might at first appear to cause unreliable behavior on
record-oriented devices (including datagram sockets; see section <A HREF="library.html#SEC256">Datagram Socket Operations</A>),
where splitting one <CODE>read</CODE> or <CODE>write</CODE> into two would read or
write two records.  Actually, there is no problem, because interruption
after a partial transfer cannot happen on such devices; they always
transfer an entire record in one burst, with no waiting once data
transfer has started.
<P>
<A NAME="IDX1570"></A>
<A NAME="IDX1571"></A>
<A NAME="IDX1572"></A>
<H2><A NAME="SEC363" HREF="library_toc.html#SEC363">Generating Signals</A></H2>
<P>
Besides signals that are generated as a result of a hardware trap or
interrupt, your program can explicitly send signals to itself or to
another process.
<P>
<H3><A NAME="SEC364" HREF="library_toc.html#SEC364">Signaling Yourself</A></H3>
<P>
A process can send itself a signal with the <CODE>raise</CODE> function.  This
function is declared in <TT>`signal.h'</TT>.
<A NAME="IDX1573"></A>
<P>
<A NAME="IDX1574"></A>
<U>Function:</U> int <B>raise</B> <I>(int <VAR>signum</VAR>)</I><P>
The <CODE>raise</CODE> function sends the signal <VAR>signum</VAR> to the calling
process.  It returns zero if successful and a nonzero value if it fails.
About the only reason for failure would be if the value of <VAR>signum</VAR>
is invalid.
<P>
<A NAME="IDX1575"></A>
<U>Function:</U> int <B>gsignal</B> <I>(int <VAR>signum</VAR>)</I><P>
The <CODE>gsignal</CODE> function does the same thing as <CODE>raise</CODE>; it is
provided only for compatibility with SVID.
<P>
One convenient use for <CODE>raise</CODE> is to reproduce the default behavior
of a signal that you have trapped.  For instance, suppose a user of your
program types the SUSP character (usually <KBD>C-z</KBD>; see section <A HREF="library.html#SEC281">Special Characters</A>) to send it an interactive stop stop signal
(<CODE>SIGTSTP</CODE>), and you want to clean up some internal data buffers
before stopping.  You might set this up like this:
<P>
<PRE>
#include &#60;signal.h&#62;

/* When a stop signal arrives, set the action back to the default
   and then resend the signal after doing cleanup actions. */

void
tstp_handler (int sig)
{
  signal (SIGTSTP, SIG_DFL);
  /* Do cleanup actions here. */
  ...
  raise (SIGTSTP);
}

/* When the process is continued again, restore the signal handler. */

void
cont_handler (int sig)
{
  signal (SIGCONT, cont_handler);
  signal (SIGTSTP, tstp_handler);
}

/* Enable both handlers during program initialization. */

int
main (void)
{
  signal (SIGCONT, cont_handler);
  signal (SIGTSTP, tstp_handler);
  ...
}
</PRE>
<P>
<STRONG>Portability note:</STRONG> <CODE>raise</CODE> was invented by the ANSI C
committee.  Older systems may not support it, so using <CODE>kill</CODE> may
be more portable.  See section <A HREF="library.html#SEC365">Signaling Another Process</A>.
<P>
<H3><A NAME="SEC365" HREF="library_toc.html#SEC365">Signaling Another Process</A></H3>
<A NAME="IDX1576"></A>
<P>
The <CODE>kill</CODE> function can be used to send a signal to another process.
In spite of its name, it can be used for a lot of things other than
causing a process to terminate.  Some examples of situations where you
might want to send signals between processes are:
<P>
<UL>
<LI>
A parent process starts a child to perform a task--perhaps having the
child running an infinite loop--and then terminates the child when the
task is no longer needed.
<P>
<LI>
A process executes as part of a group, and needs to terminate or notify
the other processes in the group when an error or other event occurs.
<P>
<LI>
Two processes need to synchronize while working together.
</UL>
<P>
This section assumes that you know a little bit about how processes
work.  For more information on this subject, see section <A HREF="library.html#SEC401">Child Processes</A>.
<P>
The <CODE>kill</CODE> function is declared in <TT>`signal.h'</TT>.
<A NAME="IDX1577"></A>
<P>
<A NAME="IDX1578"></A>
<U>Function:</U> int <B>kill</B> <I>(pid_t <VAR>pid</VAR>, int <VAR>signum</VAR>)</I><P>
The <CODE>kill</CODE> function sends the signal <VAR>signum</VAR> to the process
or process group specified by <VAR>pid</VAR>.  Besides the signals listed in
section <A HREF="library.html#SEC335">Standard Signals</A>, <VAR>signum</VAR> can also have a value of zero to
check the validity of the <VAR>pid</VAR>.
<P>
The <VAR>pid</VAR> specifies the process or process group to receive the
signal:
<P>
<DL COMPACT>
<DT><CODE><VAR>pid</VAR> &#62; 0</CODE>
<DD>The process whose identifier is <VAR>pid</VAR>.
<P>
<DT><CODE><VAR>pid</VAR> == 0</CODE>
<DD>All processes in the same process group as the sender.  The sender
itself does not receive the signal.
<P>
<DT><CODE><VAR>pid</VAR> &#60; -1</CODE>
<DD>The process group whose identifier is -<VAR>pid</VAR>.
<P>
<DT><CODE><VAR>pid</VAR> == -1</CODE>
<DD>If the process is privileged, send the signal to all processes except
for some special system processes.  Otherwise, send the signal to all
processes with the same effective user ID.
</DL>
<P>
A process can send a signal to itself with <CODE>kill (getpid(),
<VAR>signum</VAR>);</CODE>.  If <CODE>kill</CODE> is used by a process to send a signal to
itself, and the signal is not blocked, then <CODE>kill</CODE> delivers at
least one signal (which might be some other pending unblocked signal
instead of the signal <VAR>signum</VAR>) to that process before it returns.
<P>
The return value from <CODE>kill</CODE> is zero if the signal can be sent
successfully.  Otherwise, no signal is sent, and a value of <CODE>-1</CODE> is
returned.  If <VAR>pid</VAR> specifies sending a signal to several processes,
<CODE>kill</CODE> succeeds if it can send the signal to at least one of them.
There's no way you can tell which of the processes got the signal
or whether all of them did.
<P>
The following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>signum</VAR> argument is an invalid or unsupported number.
<P>
<DT><CODE>EPERM</CODE>
<DD>You do not have the privilege to send a signal to the process or any of
the processes in the process group named by <VAR>pid</VAR>.
<P>
<DT><CODE>ESCRH</CODE>
<DD>The <VAR>pid</VAR> argument does not refer to an existing process or group.
</DL>
<P>
<A NAME="IDX1579"></A>
<U>Function:</U> int <B>killpg</B> <I>(int <VAR>pgid</VAR>, int <VAR>signum</VAR>)</I><P>
This is similar to <CODE>kill</CODE>, but sends signal <VAR>signum</VAR> to the
process group <VAR>pgid</VAR>.  This function is provided for compatibility
with BSD; using <CODE>kill</CODE> to do this is more portable.
<P>
As a simple example of <CODE>kill</CODE>, the call <CODE>kill (getpid (),
<VAR>sig</VAR>)</CODE> has the same effect as <CODE>raise (<VAR>sig</VAR>)</CODE>.
<P>
<H3><A NAME="SEC366" HREF="library_toc.html#SEC366">Permission for using <CODE>kill</CODE></A></H3>
<P>
There are restrictions that prevent you from using <CODE>kill</CODE> to send
signals to any random process.  These are intended to prevent antisocial
behavior such as arbitrarily killing off processes belonging to another
user.  In typical use, <CODE>kill</CODE> is used to pass signals between
parent, child, and sibling processes, and in these situations you
normally do have permission to send signals.  The only common execption
is when you run a setuid program in a child process; if the program
changes its real UID as well as its effective UID, you may not have
permission to send a signal.  The <CODE>su</CODE> program does this.
<P>
Whether a process has permission to send a signal to another process
is determined by the user IDs of the two processes.  This concept is
discussed in detail in section <A HREF="library.html#SEC431">The Persona of a Process</A>.
<P>
Generally, for a process to be able to send a signal to another process,
either the sending process must belong to a privileged user (like
<SAMP>`root'</SAMP>), or the real or effective user ID of the sending process
must match the real or effective user ID of the receiving process.  If
the receiving process has changed its effective user ID from the
set-user-ID mode bit on its process image file, then the owner of the
process image file is used in place of its current effective user ID.
In some implementations, a parent process might be able to send signals
to a child process even if the user ID's don't match, and other
implementations might enforce other restrictions.
<P>
The <CODE>SIGCONT</CODE> signal is a special case.  It can be sent if the
sender is part of the same session as the receiver, regardless of
user IDs.
<P>
<A NAME="IDX1580"></A>
<H3><A NAME="SEC367" HREF="library_toc.html#SEC367">Using <CODE>kill</CODE> for Communication</A></H3>
Here is a longer example showing how signals can be used for
interprocess communication.  This is what the <CODE>SIGUSR1</CODE> and
<CODE>SIGUSR2</CODE> signals are provided for.  Since these signals are fatal
by default, the process that is supposed to receive them must trap them
through <CODE>signal</CODE> or <CODE>sigaction</CODE>.
<P>
In this example, a parent process forks a child process and then waits
for the child to complete its initialization.  The child process tells
the parent when it is ready by sending it a <CODE>SIGUSR1</CODE> signal, using
the <CODE>kill</CODE> function.
<P>
<PRE>
#include &#60;signal.h&#62;
#include &#60;stdio.h&#62;
#include &#60;sys/types.h&#62;
#include &#60;unistd.h&#62;

/* When a <CODE>SIGUSR1</CODE> signal arrives, set this variable.   */
volatile sig_atomic_t usr_interrupt = 0;

void 
synch_signal (int sig)
{
  usr_interrupt = 1;
}

/* The child process executes this function.  */
void 
child_function (void)
{
  /* Perform initialization.  */
  printf ("I'm here!!!  My pid is %d.\n", (int) getpid ());

  /* Let parent know you're done.  */
  kill (getppid (), SIGUSR1);

  /* Continue with execution.  */
  puts ("Bye, now....");
  exit (0);
}

int
main (void)
{
  struct sigaction usr_action;
  sigset_t block_mask;
  pid_t child_id;

  /* Establish the signal handler.  */
  sigfillset (&#38;block_mask);
  usr_action.sa_handler = synch_signal;
  usr_action.sa_mask = block_mask;
  usr_action.sa_flags = 0;
  sigaction (SIGUSR1, &#38;usr_action, NULL);

  /* Create the child process.  */
  child_id = fork ();
  if (child_id == 0)
    child_function ();		/* Does not return.   */

  /* Busy wait for the child to send a signal.  */
  while (!usr_interrupt)
    ;

  /* Now continue execution.  */
  puts ("That's all, folks!");

  return 0;
}
</PRE>
<P>
This example uses a busy wait, which is bad, because it wastes CPU
cycles that other programs could otherwise use.  It is better to ask the
system to wait until the signal arrives.  See the example in
section <A HREF="library.html#SEC376">Waiting for a Signal</A>.
<P>
<A NAME="IDX1581"></A>
<H2><A NAME="SEC368" HREF="library_toc.html#SEC368">Blocking Signals</A></H2>
<P>
Blocking a signal means telling the operating system to hold it and
deliver it later.  Generally, a program does not block signals
indefinitely--it might as well ignore them by setting their actions to
<CODE>SIG_IGN</CODE>.  But it is useful to block signals briefly, to prevent
them from interrupting sensitive operations.  For instance:
<P>
<UL>
<LI>
You can use the <CODE>sigprocmask</CODE> function to block signals while you
modify global variables that are also modified by the handlers for these 
signals.
<P>
<LI>
You can set <CODE>sa_mask</CODE> in your <CODE>sigaction</CODE> call to block
certain signals while a particular signal handler runs.  This way, the
signal handler can run without being interrupted itself by signals.
</UL>
<P>
<H3><A NAME="SEC369" HREF="library_toc.html#SEC369">Why Blocking Signals is Useful</A></H3>
<P>
Temporary blocking of signals with <CODE>sigprocmask</CODE> gives you a way to
prevent interrupts during critical parts of your code.  If signals
arrive in that part of the program, they are delivered later, after you
unblock them.
<P>
One example where this is useful is for sharing data between a signal
handler and the rest of the program.  If the type of the data is not
<CODE>sig_atomic_t</CODE> (see section <A HREF="library.html#SEC358">Atomic Data Access and Signal Handling</A>), then the signal
handler could run when the rest of the program has only half finished
reading or writing the data.  This would lead to confusing consequences.
<P>
To make the program reliable, you can prevent the signal handler from
running while the rest of the program is examining or modifying that
data--by blocking the appropriate signal around the parts of the
program that touch the data.
<P>
Blocking signals is also necessary when you want to perform a certain
action only if a signal has not arrived.  Suppose that the handler for
the signal sets a flag of type <CODE>sig_atomic_t</CODE>; you would like to
test the flag and perform the action if the flag is not set.  This is
unreliable.  Suppose the signal is delivered immediately after you test
the flag, but before the consequent action: then the program will
perform the action even though the signal has arrived.
<P>
The only way to test reliably for whether a signal has yet arrived is to
test while the signal is blocked.
<P>
<H3><A NAME="SEC370" HREF="library_toc.html#SEC370">Signal Sets</A></H3>
<P>
All of the signal blocking functions use a data structure called a
<DFN>signal set</DFN> to specify what signals are affected.  Thus, every
activity involves two stages: creating the signal set, and then passing
it as an argument to a library function.
<A NAME="IDX1582"></A>
<P>
These facilities are declared in the header file <TT>`signal.h'</TT>.
<A NAME="IDX1583"></A>
<P>
<A NAME="IDX1584"></A>
<U>Data Type:</U> <B>sigset_t</B><P>
The <CODE>sigset_t</CODE> data type is used to represent a signal set.
Internally, it may be implemented as either an integer or structure
type.
<P>
For portability, use only the functions described in this section to
initialize, change, and retrieve information from <CODE>sigset_t</CODE>
objects--don't try to manipulate them directly.
<P>
There are two ways to initialize a signal set.  You can initially
specify it to be empty with <CODE>sigemptyset</CODE> and then add specified
signals individually.  Or you can specify it to be full with
<CODE>sigfillset</CODE> and then delete specified signals individually.
<P>
You must always initialize the signal set with one of these two
functions before using it in any other way.  Don't try to set all the
signals explicitly because the <CODE>sigset_t</CODE> object might include some
other information (like a version field) that needs to be initialized as
well.  (In addition, it's not wise to put into your program an
assumption that the system has no signals aside from the ones you know
about.)
<P>
<A NAME="IDX1585"></A>
<U>Function:</U> int <B>sigemptyset</B> <I>(sigset_t *<VAR>set</VAR>)</I><P>
This function initializes the signal set <VAR>set</VAR> to exclude all of the
defined signals.  It always returns <CODE>0</CODE>.
<P>
<A NAME="IDX1586"></A>
<U>Function:</U> int <B>sigfillset</B> <I>(sigset_t *<VAR>set</VAR>)</I><P>
This function initializes the signal set <VAR>set</VAR> to include
all of the defined signals.  Again, the return value is <CODE>0</CODE>.
<P>
<A NAME="IDX1587"></A>
<U>Function:</U> int <B>sigaddset</B> <I>(sigset_t *<VAR>set</VAR>, int <VAR>signum</VAR>)</I><P>
This function adds the signal <VAR>signum</VAR> to the signal set <VAR>set</VAR>.
All <CODE>sigaddset</CODE> does is modify <VAR>set</VAR>; it does not block or
unblock any signals.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.
The following <CODE>errno</CODE> error condition is defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>signum</VAR> argument doesn't specify a valid signal.
</DL>
<P>
<A NAME="IDX1588"></A>
<U>Function:</U> int <B>sigdelset</B> <I>(sigset_t *<VAR>set</VAR>, int <VAR>signum</VAR>)</I><P>
This function removes the signal <VAR>signum</VAR> from the signal set
<VAR>set</VAR>.  All <CODE>sigdelset</CODE> does is modify <VAR>set</VAR>; it does not
block or unblock any signals.  The return value and error conditions are
the same as for <CODE>sigaddset</CODE>.
<P>
Finally, there is a function to test what signals are in a signal set:
<P>
<A NAME="IDX1589"></A>
<U>Function:</U> int <B>sigismember</B> <I>(const sigset_t *<VAR>set</VAR>, int <VAR>signum</VAR>)</I><P>
The <CODE>sigismember</CODE> function tests whether the signal <VAR>signum</VAR> is
a member of the signal set <VAR>set</VAR>.  It returns <CODE>1</CODE> if the signal
is in the set, <CODE>0</CODE> if not, and <CODE>-1</CODE> if there is an error.
<P>
The following <CODE>errno</CODE> error condition is defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>signum</VAR> argument doesn't specify a valid signal.
</DL>
<P>
<A NAME="IDX1590"></A>
<A NAME="IDX1591"></A>
<H3><A NAME="SEC371" HREF="library_toc.html#SEC371">Process Signal Mask</A></H3>
<P>
The collection of signals that are currently blocked is called the
<DFN>signal mask</DFN>.  Each process has its own signal mask.  When you
create a new process (see section <A HREF="library.html#SEC405">Creating a Process</A>), it inherits its
parent's mask.  You can block or unblock signals with total flexibility
by modifying the signal mask.
<P>
The prototype for the <CODE>sigprocmask</CODE> function is in <TT>`signal.h'</TT>.
<A NAME="IDX1592"></A>
<P>
<A NAME="IDX1593"></A>
<U>Function:</U> int <B>sigprocmask</B> <I>(int <VAR>how</VAR>, const sigset_t *<VAR>set</VAR>, sigset_t *<VAR>oldset</VAR>)</I><P>
The <CODE>sigprocmask</CODE> function is used to examine or change the calling
process's signal mask.  The <VAR>how</VAR> argument determines how the signal
mask is changed, and must be one of the following values:
<P>
<A NAME="IDX1594"></A>
<DL COMPACT>
<DT><CODE>SIG_BLOCK</CODE>
<DD>Block the signals in <CODE>set</CODE>---add them to the existing mask.  In
other words, the new mask is the union of the existing mask and
<VAR>set</VAR>.
<A NAME="IDX1595"></A>
<P>
<DT><CODE>SIG_UNBLOCK</CODE>
<DD>Unblock the signals in <VAR>set</VAR>---remove them from the existing mask.
<A NAME="IDX1596"></A>
<P>
<DT><CODE>SIG_SETMASK</CODE>
<DD>Use <VAR>set</VAR> for the mask; ignore the previous value of the mask.
</DL>
<P>
The last argument, <VAR>oldset</VAR>, is used to return information about the
old process signal mask.  If you just want to change the mask without
looking at it, pass a null pointer as the <VAR>oldset</VAR> argument.
Similarly, if you want to know what's in the mask without changing it,
pass a null pointer for <VAR>set</VAR> (in this case the <VAR>how</VAR> argument
is not significant).  The <VAR>oldset</VAR> argument is often used to
remember the previous signal mask in order to restore it later.  (Since
the signal mask is inherited over <CODE>fork</CODE> and <CODE>exec</CODE> calls, you
can't predict what its contents are when your program starts running.)
<P>
If invoking <CODE>sigprocmask</CODE> causes any pending signals to be
unblocked, at least one of those signals is delivered to the process
before <CODE>sigprocmask</CODE> returns.  The order in which pending signals
are delivered is not specified, but you can control the order explicitly
by making multiple <CODE>sigprockmask</CODE> calls to unblock various signals
one at a time.
<P>
The <CODE>sigprocmask</CODE> function returns <CODE>0</CODE> if successful, and <CODE>-1</CODE>
to indicate an error.  The following <CODE>errno</CODE> error conditions are
defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>how</VAR> argument is invalid.
</DL>
<P>
You can't block the <CODE>SIGKILL</CODE> and <CODE>SIGSTOP</CODE> signals, but
if the signal set includes these, <CODE>sigprocmask</CODE> just ignores
them instead of returning an error status.
<P>
Remember, too, that blocking program error signals such as <CODE>SIGFPE</CODE>
leads to undesirable results for signals generated by an actual program
error (as opposed to signals sent with <CODE>raise</CODE> or <CODE>kill</CODE>).
This is because your program may be too broken to be able to continue
executing to a point where the signal is unblocked again.
See section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<H3><A NAME="SEC372" HREF="library_toc.html#SEC372">Blocking to Test for Delivery of a Signal</A></H3>
<P>
Now for a simple example.  Suppose you establish a handler for
<CODE>SIGALRM</CODE> signals that sets a flag whenever a signal arrives, and
your main program checks this flag from time to time and then resets it.
You can prevent additional <CODE>SIGALRM</CODE> signals from arriving in the
meantime by wrapping the critical part of the code with calls to
<CODE>sigprocmask</CODE>, like this:
<P>
<PRE>
/* This variable is set by the SIGALRM signal handler. */
volatile sig_atomic_t flag = 0;

int
main (void)
{
  sigset_t block_alarm;

  ...

  /* Initialize the signal mask. */
  sigemptyset (&#38;block_alarm);
  sigaddset (&#38;block_alarm, SIGALRM);

  while (1)
    {
      /* Check if a signal has arrived; if so, reset the flag. */
      sigprocmask (SIG_BLOCK, &#38;block_alarm, NULL);
      if (flag)
        {
          <VAR>actions-if-not-arrived</VAR>
          flag = 0;
        }
      sigprocmask (SIG_UNBLOCK, &#38;block_alarm, NULL);

      ...
    }
}
</PRE>
<P>
<A NAME="IDX1597"></A>
<H3><A NAME="SEC373" HREF="library_toc.html#SEC373">Blocking Signals for a Handler</A></H3>
<P>
When a signal handler is invoked, you usually want it to be able to
finish without being interrupted by another signal.  From the moment the
handler starts until the moment it finishes, you must block signals that
might confuse it or corrupt its data.
<P>
When a handler function is invoked on a signal, that signal is
automatically blocked (in addition to any other signals that are already
in the process's signal mask) during the time the handler is running.
If you set up a handler for <CODE>SIGTSTP</CODE>, for instance, then the
arrival of that signal forces further <CODE>SIGTSTP</CODE> signals to wait
during the execution of the handler.
<P>
However, by default, other kinds of signals are not blocked; they can
arrive during handler execution.
<P>
The reliable way to block other kinds of signals during the execution of
the handler is to use the <CODE>sa_mask</CODE> member of the <CODE>sigaction</CODE>
structure.
<P>
Here is an example:
<P>
<PRE>
#include &#60;signal.h&#62;
#include &#60;stddef.h&#62;

void catch_stop ();

void
install_handler (void)
{
  struct sigaction setup_action;
  sigset_t block_mask;

  sigemptyset (&#38;block_mask);
  /* Block other terminal-generated signals while handler runs. */
  sigaddset (&#38;block_mask, SIGINT);
  sigaddset (&#38;block_mask, SIGQUIT);
  setup_action.sa_handler = catch_stop;
  setup_action.sa_mask = block_mask;
  setup_action.sa_flags = 0;
  sigaction (SIGTSTP, &#38;setup_action, NULL);
}
</PRE>
<P>
This is more reliable than blocking the other signals explicitly in the
code for the handler.  If you block signals explicity in the handler,
you can't avoid at least a short interval at the beginning of the
handler where they are not yet blocked.
<P>
You cannot remove signals from the process's current mask using this
mechanism.  However, you can make calls to <CODE>sigprocmask</CODE> within
your handler to block or unblock signals as you wish.
<P>
In any case, when the handler returns, the system restores the mask that
was in place before the handler was entered.
<P>
<A NAME="IDX1598"></A>
<A NAME="IDX1599"></A>
<A NAME="IDX1600"></A>
<H3><A NAME="SEC374" HREF="library_toc.html#SEC374">Checking for Pending Signals</A></H3>
<P>
You can find out which signals are pending at any time by calling
<CODE>sigpending</CODE>.  This function is declared in <TT>`signal.h'</TT>.
<A NAME="IDX1601"></A>
<P>
<A NAME="IDX1602"></A>
<U>Function:</U> int <B>sigpending</B> <I>(sigset_t *<VAR>set</VAR>)</I><P>
The <CODE>sigpending</CODE> function stores information about pending signals
in <VAR>set</VAR>.  If there is a pending signal that is blocked from
delivery, then that signal is a member of the returned set.  (You can
test whether a particular signal is a member of this set using
<CODE>sigismember</CODE>; see section <A HREF="library.html#SEC370">Signal Sets</A>.)
<P>
The return value is <CODE>0</CODE> if successful, and <CODE>-1</CODE> on failure.
<P>
Testing whether a signal is pending is not often useful.  Testing when
that signal is not blocked is almost certainly bad design.
<P>
Here is an example.
<P>
<PRE>
#include &#60;signal.h&#62;
#include &#60;stddef.h&#62;

sigset_t base_mask, waiting_mask;

sigemptyset (&#38;base_mask);
sigaddset (&#38;base_mask, SIGINT);
sigaddset (&#38;base_mask, SIGTSTP);

/* Block user interrupts while doing other processing. */
sigprocmask (SIG_SETMASK, &#38;base_mask, NULL); 
...

/* After a while, check to see whether any signals are pending. */
sigpending (&#38;waiting_mask);
if (sigismember (&#38;waiting_mask, SIGINT)) {
  /* User has tried to kill the process. */
}
else if (sigismember (&#38;waiting_mask, SIGTSTP)) {
  /* User has tried to stop the process. */
}
</PRE>
<P>
Remember that if there is a particular signal pending for your process,
additional signals of that same type that arrive in the meantime might
be discarded.  For example, if a <CODE>SIGINT</CODE> signal is pending when
another <CODE>SIGINT</CODE> signal arrives, your program will probably only
see one of them when you unblock this signal.
<P>
<STRONG>Portability Note:</STRONG> The <CODE>sigpending</CODE> function is new in
POSIX.1.  Older systems have no equivalent facility.
<P>
<H3><A NAME="SEC375" HREF="library_toc.html#SEC375">Remembering a Signal to Act On Later</A></H3>
<P>
Instead of blocking a signal using the library facilities, you can get
almost the same results by making the handler set a flag to be tested
later, when you "unblock".  Here is an example:
<P>
<PRE>
/* If this flag is nonzero, don't handle the signal right away. */
volatile sig_atomic_t signal_pending;

/* This is nonzero if a signal arrived and was not handled. */
volatile sig_atomic_t defer_signal;

void
handler (int signum)
{
  if (defer_signal)
    signal_pending = signum;
  else
    ... /* "Really" handle the signal. */
}

...

void
update_mumble (int frob)
{
  /* Prevent signals from having immediate effect. */
  defer_signal++;
  /* Now update <CODE>mumble</CODE>, without worrying about interruption. */
  mumble.a = 1;
  mumble.b = hack ();
  mumble.c = frob;
  /* We have updated <CODE>mumble</CODE>.  Handle any signal that came in. */
  defer_signal--;
  if (defer_signal == 0 &#38;&#38; signal_pending != 0)
    raise (signal_pending);
}
</PRE>
<P>
Note how the particular signal that arrives is stored in
<CODE>signal_pending</CODE>.  That way, we can handle several types of
inconvenient signals with the same mechanism.
<P>
We increment and decrement <CODE>defer_signal</CODE> so that nested critical
sections will work properly; thus, if <CODE>update_mumble</CODE> were called
with <CODE>signal_pending</CODE> already nonzero, signals would be deferred
not only within <CODE>update_mumble</CODE>, but also within the caller.  This
is also why we do not check <CODE>signal_pending</CODE> if <CODE>defer_signal</CODE>
is still nonzero.
<P>
The incrementing and decrementing of <CODE>defer_signal</CODE> require more
than one instruction; it is possible for a signal to happen in the
middle.  But that does not cause any problem.  If the signal happens
early enough to see the value from before the increment or decrement,
that is equivalent to a signal which came before the beginning of the
increment or decrement, which is a case that works properly.
<P>
It is absolutely vital to decrement <CODE>defer_signal</CODE> before testing
<CODE>signal_pending</CODE>, because this avoids a subtle bug.  If we did
these things in the other order, like this,
<P>
<PRE>
  if (defer_signal == 1 &#38;&#38; signal_pending != 0)
    raise (signal_pending);
  defer_signal--;
</PRE>
<P>
then a signal arriving in between the <CODE>if</CODE> statement and the decrement
would be effetively "lost" for an indefinite amount of time.  The
handler would merely set <CODE>defer_signal</CODE>, but the program having
already tested this variable, it would not test the variable again.
<A NAME="IDX1603"></A>
<P>
Bugs like these are called <DFN>timing errors</DFN>.  They are especially bad
because they happen only rarely and are nearly impossible to reproduce.
You can't expect to find them with a debugger as you would find a
reproducible bug.  So it is worth being especially careful to avoid
them.
<P>
(You would not be tempted to write the code in this order, given the use
of <CODE>defer_signal</CODE> as a counter which must be tested along with
<CODE>signal_pending</CODE>.  After all, testing for zero is cleaner than
testing for one.  But if you did not use <CODE>defer_signal</CODE> as a
counter, and gave it values of zero and one only, then either order
might seem equally simple.  This is a further advantage of using a
counter for <CODE>defer_signal</CODE>: it will reduce the chance you will
write the code in the wrong order and create a subtle bug.)
<P>
<A NAME="IDX1604"></A>
<A NAME="IDX1605"></A>
<H2><A NAME="SEC376" HREF="library_toc.html#SEC376">Waiting for a Signal</A></H2>
<P>
If your program is driven by external events, or uses signals for
synchronization, then when it has nothing to do it should probably wait
until a signal arrives.
<P>
<H3><A NAME="SEC377" HREF="library_toc.html#SEC377">Using <CODE>pause</CODE></A></H3>
<P>
The simple way to wait until a signal arrives is to call <CODE>pause</CODE>.
Please read about its disadvantages, in the following section, before
you use it.
<P>
<A NAME="IDX1606"></A>
<U>Function:</U> int <B>pause</B> <I>()</I><P>
The <CODE>pause</CODE> function suspends program execution until a signal
arrives whose action is either to execute a handler function, or to
terminate the process.
<P>
If the signal causes a handler function to be executed, then
<CODE>pause</CODE> returns.  This is considered an unsuccessful return (since
"successful" behavior would be to suspend the program forever), so the
return value is <CODE>-1</CODE>.  Even if you specify that other primitives
should resume when a system handler returns (see section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>), this has no effect on <CODE>pause</CODE>; it always fails when a
signal is handled.
<P>
The following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EINTR</CODE>
<DD>The function was interrupted by delivery of a signal.
</DL>
<P>
If the signal causes program termination, <CODE>pause</CODE> doesn't return
(obviously).
<P>
The <CODE>pause</CODE> function is declared in  <TT>`unistd.h'</TT>.
<P>
<H3><A NAME="SEC378" HREF="library_toc.html#SEC378">Problems with <CODE>pause</CODE></A></H3>
<P>
The simplicity of <CODE>pause</CODE> can conceal serious timing errors that
can make a program hang mysteriously.
<P>
It is safe to use <CODE>pause</CODE> if the real work of your program is done
by the signal handlers themselves, and the "main program" does nothing
but call <CODE>pause</CODE>.  Each time a signal is delivered, the handler
will do the next batch of work that is to be done, and then return, so
that the main loop of the program can call <CODE>pause</CODE> again.
<P>
You can't safely use <CODE>pause</CODE> to wait until one more signal arrives,
and then resume real work.  Even if you arrange for the signal handler
to cooperate by setting a flag, you still can't use <CODE>pause</CODE>
reliably.  Here is an example of this problem:
<P>
<PRE>
/* <CODE>usr_interrupt</CODE> is set by the signal handler.  */
if (!usr_interrupt)
  pause ();

/* Do work once the signal arrives.  */
...
</PRE>
<P>
This has a bug: the signal could arrive after the variable
<CODE>usr_interrupt</CODE> is checked, but before the call to <CODE>pause</CODE>.
If no further signals arrive, the process would never wake up again.
<P>
You can put an upper limit on the excess waiting by using <CODE>sleep</CODE>
in a loop, instead of using <CODE>pause</CODE>.  (See section <A HREF="library.html#SEC322">Sleeping</A>, for more
about <CODE>sleep</CODE>.)  Here is what this looks like:
<P>
<PRE>
/* <CODE>usr_interrupt</CODE> is set by the signal handler.
while (!usr_interrupt)
  sleep (1);

/* Do work once the signal arrives.  */
...
</PRE>
<P>
For some purposes, that is good enough.  But with a little more
complexity, you can wait reliably until a particular signal handler is
run, using <CODE>sigsuspend</CODE>.
<P>
<H3><A NAME="SEC379" HREF="library_toc.html#SEC379">Using <CODE>sigsuspend</CODE></A></H3>
<P>
The clean and reliable way to wait for a signal to arrive is to block it
and then use <CODE>sigsuspend</CODE>.  By using <CODE>sigsuspend</CODE> in a loop,
you can wait for certain kinds of signals, while letting other kinds of
signals be handled by their handlers.
<P>
<A NAME="IDX1607"></A>
<U>Function:</U> int <B>sigsuspend</B> <I>(const sigset_t *<VAR>set</VAR>)</I><P>
This function replaces the process's signal mask with <VAR>set</VAR> and then
suspends the process until a signal is delivered whose action is either
to terminate the process or invoke a signal handling function.  In other
words, the program is effectively suspended until one of the signals that
is not a member of <VAR>set</VAR> arrives.
<P>
If the process is woken up by deliver of a signal that invokes a handler
function, and the handler function returns, then <CODE>sigsuspend</CODE> also
returns.
<P>
The mask remains <VAR>set</VAR> only as long as <CODE>sigsuspend</CODE> is waiting.
The function <CODE>sigsuspend</CODE> always restores the previous signal mask
when it returns.  
<P>
The return value and error conditions are the same as for <CODE>pause</CODE>.
<P>
With <CODE>sigsuspend</CODE>, you can replace the <CODE>pause</CODE> or <CODE>sleep</CODE>
loop in the previous section with something completely reliable:
<P>
<PRE>
sigset_t mask, oldmask;

...

/* Set up the mask of signals to temporarily block. */ 
sigemptyset (&#38;mask); 
sigaddset (&#38;mask, SIGUSR1);

...

/* Wait for a signal to arrive. */
sigprocmask (SIG_BLOCK, &#38;mask, &#38;oldmask);
while (!usr_interrupt)
  sigsuspend (&#38;oldmask);
sigprocmask (SIG_UNBLOCK, &#38;mask, NULL);
</PRE>
<P>
This last piece of code is a little tricky.  The key point to remember
here is that when <CODE>sigsuspend</CODE> returns, it resets the process's
signal mask to the original value, the value from before the call to
<CODE>sigsuspend</CODE>---in this case, the <CODE>SIGUSR1</CODE> signal is once
again blocked.  The second call to <CODE>sigprocmask</CODE> is
necessary to explicitly unblock this signal.
<P>
One other point: you may be wondering why the <CODE>while</CODE> loop is
necessary at all, since the program is apparently only waiting for one
<CODE>SIGUSR1</CODE> signal.  The answer is that the mask passed to
<CODE>sigsuspend</CODE> permits the process to be woken up by the delivery of
other kinds of signals, as well--for example, job control signals.  If
the process is woken up by a signal that doesn't set
<CODE>usr_interrupt</CODE>, it just suspends itself again until the "right"
kind of signal eventually arrives.
<P>
This technique takes a few more lines of preparation, but that is needed
just once for each kind of wait criterion you want to use.  The code
that actually waits is just four lines.
<P>
<H2><A NAME="SEC380" HREF="library_toc.html#SEC380">BSD Signal Handling</A></H2>
<P>
This section describes alternative signal handling functions derived
from BSD Unix.  These facilities were an advance, in their time; today,
they are mostly obsolete, and supported mainly for compatibility with
BSD Unix.
<P>
They do provide one feature that is not available through the POSIX
functions: You can specify a separate stack for use in certain signal
handlers.  Using a signal stack is the only way you can handle a signal
caused by stack overflow.
<P>
<H3><A NAME="SEC381" HREF="library_toc.html#SEC381">POSIX and BSD Signal Facilities</A></H3>
<P>
There are many similarities between the BSD and POSIX signal handling
facilities, because the POSIX facilities were inspired by the BSD
facilities.  Besides having different names for all the functions to
avoid conflicts, the main differences between the two are:
<P>
<UL>
<LI>
BSD Unix represents signal masks as an <CODE>int</CODE> bit mask, rather than
as a <CODE>sigset_t</CODE> object.
<P>
<LI>
The BSD facilities use a different default for whether an interrupted
primitive should fail or resume.  The POSIX facilities make system
calls fail unless you specify that they should resume.  With the BSD
facility, the default is to make system calls resume unless you say they
should fail.  See section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<LI>
BSD Unix has a concept of a <DFN>signal stack</DFN>.  This is an alternate
stack that is used during the execution of signal handler functions,
instead of its normal execution stack.
<A NAME="IDX1608"></A>
</UL>
<P>
The BSD facilities are declared in <TT>`signal.h'</TT>.
<A NAME="IDX1609"></A>
<P>
<H2><A NAME="SEC382" HREF="library_toc.html#SEC382">BSD Function to Establish a Handler</A></H2>
<P>
<A NAME="IDX1610"></A>
<U>Data Type:</U> <B>struct sigvec</B><P>
This data type is the BSD equivalent of <CODE>struct sigaction</CODE>
(see section <A HREF="library.html#SEC346">Advanced Signal Handling</A>); it is used to specify signal actions
to the <CODE>sigvec</CODE> function.  It contains the following members:
<P>
<DL COMPACT>
<DT><CODE>sighandler_t sv_handler</CODE>
<DD>This is the handler function.
<P>
<DT><CODE>int sv_mask</CODE>
<DD>This is the mask of additional signals to be blocked while the handler
function is being called.
<P>
<DT><CODE>int sv_flags</CODE>
<DD>This is a bit mask used to specify various flags which affect the
behavior of the signal.  You can also refer to this field as
<CODE>sv_onstack</CODE>.
</DL>
<P>
These symbolic constants can be used to provide values for the
<CODE>sv_flags</CODE> field of a <CODE>sigvec</CODE> structure.  This field is a bit
mask value, so you bitwise-OR the flags of interest to you together.
<P>
<A NAME="IDX1611"></A>
<U>Macro:</U> int <B>SV_ONSTACK</B><P>
If this bit is set in the <CODE>sv_flags</CODE> field of a <CODE>sigvec</CODE>
structure, it means to use the signal stack when delivering the signal.
<P>
<A NAME="IDX1612"></A>
<U>Macro:</U> int <B>SV_INTERRUPT</B><P>
If this bit is set in the <CODE>sv_flags</CODE> field of a <CODE>sigvec</CODE>
structure, it means that system calls interrupted by this kind of signal
should not be restarted if the handler returns; instead, the system
calls should return with a <CODE>EINTR</CODE> error status.  See section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<A NAME="IDX1613"></A>
<U>Macro:</U> int <B>SV_RESETHAND</B><P>
If this bit is set in the <CODE>sv_flags</CODE> field of a <CODE>sigvec</CODE>
structure, it means to reset the action for the signal back to
<CODE>SIG_DFL</CODE> when the signal is received.
<P>
<A NAME="IDX1614"></A>
<U>Function:</U> int <B>sigvec</B> <I>(int <VAR>signum</VAR>, const struct sigvec *<VAR>action</VAR>,struct sigvec *<VAR>old_action</VAR>)</I><P>
This function is the equivalent of <CODE>sigaction</CODE> (see section <A HREF="library.html#SEC346">Advanced Signal Handling</A>); it installs the action <VAR>action</VAR> for the signal <VAR>signum</VAR>,
returning information about the previous action in effect for that signal
in <VAR>old_action</VAR>.
<P>
<A NAME="IDX1615"></A>
<U>Function:</U> int <B>siginterrupt</B> <I>(int <VAR>signum</VAR>, int <VAR>failflag</VAR>)</I><P>
This function specifies which approach to use when certain primitives
are interrupted by handling signal <VAR>signum</VAR>.  If <VAR>failflag</VAR> is
false, signal <VAR>signum</VAR> restarts primitives.  If <VAR>failflag</VAR> is
true, handling <VAR>signum</VAR> causes these primitives to fail with error
code <CODE>EINTR</CODE>.  See section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<H3><A NAME="SEC383" HREF="library_toc.html#SEC383">BSD Functions for Blocking Signals</A></H3>
<P>
<A NAME="IDX1616"></A>
<U>Macro:</U> int <B>sigmask</B> <I>(int <VAR>signum</VAR>)</I><P>
This macro returns a signal mask that has the bit for signal <VAR>signum</VAR>
set.  You can bitwise-OR the results of several calls to <CODE>sigmask</CODE>
together to specify more than one signal.  For example,
<P>
<PRE>
(sigmask (SIGTSTP) | sigmask (SIGSTOP)
 | sigmask (SIGTTIN) | sigmask (SIGTTOU))
</PRE>
<P>
specifies a mask that includes all the job-control stop signals.
<P>
<A NAME="IDX1617"></A>
<U>Function:</U> int <B>sigblock</B> <I>(int <VAR>mask</VAR>)</I><P>
This function is the equivalent of <CODE>sigprocmask</CODE> (see section <A HREF="library.html#SEC371">Process Signal Mask</A>) with a <VAR>how</VAR> argument of <CODE>SIG_BLOCK</CODE>: it adds the
signals specified by <VAR>mask</VAR> to the calling process's signal mask.
The return value is the previous set of blocked signals.
<P>
<A NAME="IDX1618"></A>
<U>Function:</U> int <B>sigsetmask</B> <I>(int <VAR>mask</VAR>)</I><P>
This function is the equivalent of <CODE>sigprocmask</CODE> (see section <A HREF="library.html#SEC371">Process Signal Mask</A>) with a <VAR>how</VAR> argument of <CODE>SIG_SETMASK</CODE>: it sets
the calling process's signal mask to <VAR>mask</VAR>.  The return value is
the previous set of blocked signals.
<P>
<A NAME="IDX1619"></A>
<U>Function:</U> int <B>sigpause</B> <I>(int <VAR>mask</VAR>)</I><P>
This function is the equivalent of <CODE>sigsuspend</CODE> (see section <A HREF="library.html#SEC376">Waiting for a Signal</A>):  it sets the calling process's signal mask to <VAR>mask</VAR>,
and waits for a signal to arrive.  On return the previous set of blocked
signals is restored.
<P>
<H3><A NAME="SEC384" HREF="library_toc.html#SEC384">Using a Separate Signal Stack</A></H3>
<P>
A signal stack is a special area of memory to be used as the execution
stack during signal handlers.  It should be fairly large, to avoid any
danger that it will overflow in turn--we recommend at least 16,000
bytes.  You can use <CODE>malloc</CODE> to allocate the space for the stack.
Then call <CODE>sigstack</CODE> to tell the system to use that space for the
signal stack.
<P>
You don't need to write signal handlers differently in order to use a
signal stack.  Switching from one stack to the other happens
automatically.  However, some debuggers on some machines may get
confused if you examine a stack trace while a handler that uses the
signal stack is running.
<P>
<A NAME="IDX1620"></A>
<U>Data Type:</U> <B>struct sigstack</B><P>
This structure describes a signal stack.  It contains the following members:
<P>
<DL COMPACT>
<DT><CODE>void *ss_sp</CODE>
<DD>This is the stack pointer.
<P>
<DT><CODE>int ss_onstack</CODE>
<DD>This field is true if the process is currently using this stack.
</DL>
<P>
<A NAME="IDX1621"></A>
<U>Function:</U> int <B>sigstack</B> <I>(const struct sigstack *<VAR>stack</VAR>, struct sigstack *<VAR>oldstack</VAR>)</I><P>
The <CODE>sigstack</CODE> function specifies an alternate stack for use during
signal handling.  When a signal is received by the process and its
action indicates that the signal stack is used, the system arranges a
switch to the currently installed signal stack while the handler for
that signal is executed.
<P>
If <VAR>oldstack</VAR> is not a null pointer, information about the currently
installed signal stack is returned in the location it points to.  If
<VAR>stack</VAR> is not a null pointer, then this is installed as the new
stack for use by signal handlers.
<P>
The return value is <CODE>0</CODE> on success and <CODE>1</CODE> on failure.
<P>
<H1><A NAME="SEC385" HREF="library_toc.html#SEC385">Process Startup and Termination</A></H1>
<A NAME="IDX1622"></A>
<P>
<DFN>Processes</DFN> are the primitive units for allocation of system
resources.  Each process has its own address space and (usually) one
thread of control.  A process executes a program; you can have multiple
processes executing the same program, but each process has its own copy
of the program within its own address space and executes it
independently of the other copies.
<P>
This chapter explains what your program should do to handle the startup
of a process, to terminate its process, and to receive information
(arguments and the environment) from the parent process.
<P>
<A NAME="IDX1623"></A>
<A NAME="IDX1624"></A>
<H2><A NAME="SEC386" HREF="library_toc.html#SEC386">Program Arguments</A></H2>
<A NAME="IDX1625"></A>
<P>
The system starts a C program by calling the function <CODE>main</CODE>.  It
is up to you to write a function named <CODE>main</CODE>---otherwise, you
won't even be able to link your program without errors.
<P>
You can define <CODE>main</CODE> either to take no arguments, or to take two
arguments that represent the command line arguments to the program, like
this:
<P>
<PRE>
int main (int <VAR>argc</VAR>, char *<VAR>argv</VAR>[])
</PRE>
<A NAME="IDX1626"></A>
<A NAME="IDX1627"></A>
<P>
The command line arguments are the whitespace-separated tokens given in
the shell command used to invoke the program; thus, in <SAMP>`cat foo
bar'</SAMP>, the arguments are <SAMP>`foo'</SAMP> and <SAMP>`bar'</SAMP>.  The only way a
program can look at its command line arguments is via the arguments of
<CODE>main</CODE>.  If <CODE>main</CODE> doesn't take arguments, then you cannot get
at the command line.
<P>
The value of the <VAR>argc</VAR> argument is the number of command line
arguments.  The <VAR>argv</VAR> argument is a vector of C strings; its
elements are the individual command line argument strings.  The file
name of the program being run is also included in the vector as the
first element; the value of <VAR>argc</VAR> counts this element.  A null
pointer always follows the last element: <CODE><VAR>argv</VAR>[<VAR>argc</VAR>]</CODE>
is this null pointer.
<P>
For the command <SAMP>`cat foo bar'</SAMP>, <VAR>argc</VAR> is 3 and <VAR>argv</VAR> has
three elements, <CODE>"cat"</CODE>, <CODE>"foo"</CODE> and <CODE>"bar"</CODE>.
<P>
If the syntax for the command line arguments to your program is simple
enough, you can simply pick the arguments off from <VAR>argv</VAR> by hand.
But unless your program takes a fixed number of arguments, or all of the
arguments are interpreted in the same way (as file names, for example),
you are usually better off using <CODE>getopt</CODE> to do the parsing.
<P>
<A NAME="IDX1628"></A>
<A NAME="IDX1629"></A>
<A NAME="IDX1630"></A>
<H3><A NAME="SEC387" HREF="library_toc.html#SEC387">Program Argument Syntax Conventions</A></H3>
<P>
POSIX recommends these conventions for command line arguments.
<CODE>getopt</CODE> (see section <A HREF="library.html#SEC388">Parsing Program Options</A>) makes it easy to implement them.
<P>
<UL>
<LI>
Arguments are options if they begin with a hyphen delimiter (<SAMP>`-'</SAMP>).
<P>
<LI>
Multiple options may follow a hyphen delimiter in a single token if
the options do not take arguments.  Thus, <SAMP>`-abc'</SAMP> is equivalent to
<SAMP>`-a -b -c'</SAMP>.
<P>
<LI>
Option names are single alphanumeric characters (as for <CODE>isalnum</CODE>;
see section <A HREF="library.html#SEC55">Classification of Characters</A>).
<P>
<LI>
Certain options require an argument.  For example, the <SAMP>`-o'</SAMP> command
of the <CODE>ld</CODE> command requires an argument--an output file name.
<P>
<LI>
An option and its argument may or may not appear as separate tokens.  (In
other words, the whitespace separating them is optional.)  Thus,
<SAMP>`-o foo'</SAMP> and <SAMP>`-ofoo'</SAMP> are equivalent.
<P>
<LI>
Options typically precede other non-option arguments.
<P>
The implementation of <CODE>getopt</CODE> in the GNU C library normally makes
it appear as if all the option arguments were specified before all the
non-option arguments for the purposes of parsing, even if the user of
your program intermixed option and non-option arguments.  It does this
by reordering the elements of the <VAR>argv</VAR> array.  This behavior is
nonstandard; if you want to suppress it, define the
<CODE>_POSIX_OPTION_ORDER</CODE> environment variable.  See section <A HREF="library.html#SEC394">Standard Environment Variables</A>.
<P>
<LI>
The argument <SAMP>`--'</SAMP> terminates all options; any following arguments
are treated as non-option arguments, even if they begin with a hyphen.
<P>
<LI>
A token consisting of a single hyphen character is interpreted as an
ordinary non-option argument.  By convention, it is used to specify
input from or output to the standard input and output streams.
<P>
<LI>
Options may be supplied in any order, or appear multiple times.  The
interpretation is left up to the particular application program.
</UL>
<A NAME="IDX1631"></A>
<P>
GNU adds <DFN>long options</DFN> to these conventions.  Long options consist
of <SAMP>`--'</SAMP> followed by a name made of alphanumeric characters and
dashes.  Option names are typically one to three words long, with
hyphens to separate words.  Users can abbreviate the option names as
long as the abbreviations are unique.
<P>
To specify an argument for a long option, write
<SAMP>`--<VAR>name</VAR>=<VAR>value</VAR>'</SAMP>.  This syntax enables a long option to
accept an argument that is itself optional.
<P>
Eventually, the GNU system will provide completion for long option names
in the shell.
<P>
<A NAME="IDX1632"></A>
<A NAME="IDX1633"></A>
<A NAME="IDX1634"></A>
<H3><A NAME="SEC388" HREF="library_toc.html#SEC388">Parsing Program Options</A></H3>
<P>
Here are the details about how to call the <CODE>getopt</CODE> function.  To
use this facility, your program must include the header file
<TT>`unistd.h'</TT>.
<A NAME="IDX1635"></A>
<P>
<A NAME="IDX1636"></A>
<U>Variable:</U> int <B>opterr</B><P>
If the value of this variable is nonzero, then <CODE>getopt</CODE> prints an
error message to the standard error stream if it encounters an unknown
option character or an option with a missing required argument.  This is
the default behavior.  If you set this variable to zero, <CODE>getopt</CODE>
does not print any messages, but it still returns the character <CODE>?</CODE>
to indicate an error.
<P>
<A NAME="IDX1637"></A>
<U>Variable:</U> int <B>optopt</B><P>
When <CODE>getopt</CODE> encounters an unknown option character or an option
with a missing required argument, it stores that option character in
this variable.  You can use this for providing your own diagnostic
messages.
<P>
<A NAME="IDX1638"></A>
<U>Variable:</U> int <B>optind</B><P>
This variable is set by <CODE>getopt</CODE> to the index of the next element
of the <VAR>argv</VAR> array to be processed.  Once <CODE>getopt</CODE> has found
all of the option arguments, you can use this variable to determine
where the remaining non-option arguments begin.  The initial value of
this variable is <CODE>1</CODE>.
<P>
<A NAME="IDX1639"></A>
<U>Variable:</U> char * <B>optarg</B><P>
This variable is set by <CODE>getopt</CODE> to point at the value of the
option argument, for those options that accept arguments.
<P>
<A NAME="IDX1640"></A>
<U>Function:</U> int <B>getopt</B> <I>(int <VAR>argc</VAR>, char **<VAR>argv</VAR>, const char *<VAR>options</VAR>)</I><P>
The <CODE>getopt</CODE> function gets the next option argument from the
argument list specified by the <VAR>argv</VAR> and <VAR>argc</VAR> arguments.
Normally these values come directly from the arguments received by
<CODE>main</CODE>.
<P>
The <VAR>options</VAR> argument is a string that specifies the option
characters that are valid for this program.  An option character in this
string can be followed by a colon (<SAMP>`:'</SAMP>) to indicate that it takes a
required argument.
<P>
If the <VAR>options</VAR> argument string begins with a hyphen (<SAMP>`-'</SAMP>), this
is treated specially.  It permits arguments that are not options to be
returned as if they were associated with option character <SAMP>`\0'</SAMP>.
<P>
The <CODE>getopt</CODE> function returns the option character for the next
command line option.  When no more option arguments are available, it
returns <CODE>-1</CODE>.  There may still be more non-option arguments; you
must compare the external variable <CODE>optind</CODE> against the <VAR>argc</VAR>
parameter to check this.
<P>
If the option has an argument, <CODE>getopt</CODE> returns the argument by
storing it in the varables <VAR>optarg</VAR>.  You don't ordinarily need to
copy the <CODE>optarg</CODE> string, since it is a pointer into the original
<VAR>argv</VAR> array, not into a static area that might be overwritten.
<P>
If <CODE>getopt</CODE> finds an option character in <VAR>argv</VAR> that was not
included in <VAR>options</VAR>, or a missing option argument, it returns
<SAMP>`?'</SAMP> and sets the external variable <CODE>optopt</CODE> to the actual
option character.  If the first character of <VAR>options</VAR> is a colon
(<SAMP>`:'</SAMP>), then <CODE>getopt</CODE> returns <SAMP>`:'</SAMP> instead of <SAMP>`?'</SAMP> to
indicate a missing option argument.  In addition, if the external
variable <CODE>opterr</CODE> is nonzero (which is the default), <CODE>getopt</CODE>
prints an error message.
<P>
<H3><A NAME="SEC389" HREF="library_toc.html#SEC389">Example of Parsing Arguments with <CODE>getopt</CODE></A></H3>
<P>
Here is an example showing how <CODE>getopt</CODE> is typically used.  The
key points to notice are:
<P>
<UL>
<LI>
Normally, <CODE>getopt</CODE> is called in a loop.  When <CODE>getopt</CODE> returns
<CODE>-1</CODE>, indicating no more options are present, the loop terminates.
<P>
<LI>
A <CODE>switch</CODE> statement is used to dispatch on the return value from
<CODE>getopt</CODE>.  In typical use, each case just sets a variable that
is used later in the program.
<P>
<LI>
A second loop is used to process the remaining non-option arguments.
</UL>
<P>
<PRE>
#include &#60;unistd.h&#62;
#include &#60;stdio.h&#62;

int 
main (int argc, char **argv)
{
  int aflag = 0;
  int bflag = 0;
  char *cvalue = NULL;
  int index;
  int c;

  opterr = 0;

  while ((c = getopt (argc, argv, "abc:")) != -1)
    switch (c)
      {
      case 'a':
        aflag = 1;
        break;
      case 'b':
        bflag = 1;
        break;
      case 'c':
        cvalue = optarg;
        break;
      case '?':
        if (isprint (optopt))
          fprintf (stderr, "Unknown option `-%c'.\n", optopt);
        else
          fprintf (stderr,
                   "Unknown option character `\\x%x'.\n",
                   optopt);
        return 1;
      default:
        abort ();
      }

  printf ("aflag = %d, bflag = %d, cvalue = %s\n", aflag, bflag, cvalue);

  for (index = optind; index &#60; argc; index++)
    printf ("Non-option argument %s\n", argv[index]);
  return 0;
}
</PRE>
<P>
Here are some examples showing what this program prints with different
combinations of arguments:
<P>
<PRE>
% testopt
aflag = 0, bflag = 0, cvalue = (null)

% testopt -a -b
aflag = 1, bflag = 1, cvalue = (null)

% testopt -ab
aflag = 1, bflag = 1, cvalue = (null)

% testopt -c foo
aflag = 0, bflag = 0, cvalue = foo

% testopt -cfoo
aflag = 0, bflag = 0, cvalue = foo

% testopt arg1
aflag = 0, bflag = 0, cvalue = (null)
Non-option argument arg1

% testopt -a arg1
aflag = 1, bflag = 0, cvalue = (null)
Non-option argument arg1

% testopt -c foo arg1
aflag = 0, bflag = 0, cvalue = foo
Non-option argument arg1

% testopt -a -- -b
aflag = 1, bflag = 0, cvalue = (null)
Non-option argument -b

% testopt -a -
aflag = 1, bflag = 0, cvalue = (null)
Non-option argument -
</PRE>
<P>
<H3><A NAME="SEC390" HREF="library_toc.html#SEC390">Parsing Long Options</A></H3>
<P>
To accept GNU-style long options as well as single-character options,
use <CODE>getopt_long</CODE> instead of <CODE>getopt</CODE>.  You should make every
program accept long options if it uses any options, for this takes
little extra work and helps beginners remember how to use the program.
<P>
<A NAME="IDX1641"></A>
<U>Data Type:</U> <B>struct option</B><P>
This structure describes a single long option name for the sake of
<CODE>getopt_long</CODE>.  The argument <VAR>longopts</VAR> must be an array of
these structures, one for each long option.  Terminate the array with an
element containing all zeros.
<P>
The <CODE>struct option</CODE> structure has these fields:
<P>
<DL COMPACT>
<DT><CODE>const char *name</CODE>
<DD>This field is the name of the option.  It is a string.
<P>
<DT><CODE>int has_arg</CODE>
<DD>This field says whether the option takes an argument.  It is an integer,
and there are three legitimate values: <CODE>no_argument</CODE>,
<CODE>required_argument</CODE> and <CODE>optional_argument</CODE>.
<P>
<DT><CODE>int *flag</CODE>
<DD><DT><CODE>int val</CODE>
<DD>These fields control how to report or act on the option when it occurs.
<P>
If <CODE>flag</CODE> is a null pointer, then the <CODE>val</CODE> is a value which
identifies this option.  Often these values are chosen to uniquely
identify particular long options.
<P>
If <CODE>flag</CODE> is not a null pointer, it should be the address of an
<CODE>int</CODE> variable which is the flag for this option.  The value in
<CODE>val</CODE> is the value to store in the flag to indicate that the option
was seen.
</DL>
<P>
<A NAME="IDX1642"></A>
<U>Function:</U> int <B>getopt_long</B> <I>(int <VAR>argc</VAR>, char **<VAR>argv</VAR>, const char *<VAR>shortopts</VAR>, struct option *<VAR>longopts</VAR>, int *<VAR>indexptr</VAR>)</I><P>
Decode options from the vector <VAR>argv</VAR> (whose length is <VAR>argc</VAR>).
The argument <VAR>shortopts</VAR> describes the short options to accept, just as
it does in <CODE>getopt</CODE>.  The argument <VAR>longopts</VAR> describes the long
options to accept (see above).
<P>
When <CODE>getopt_long</CODE> encounters a short option, it does the same
thing that <CODE>getopt</CODE> would do: it returns the character code for the
option, and stores the options argument (if it has one) in <CODE>optarg</CODE>.
<P>
When <CODE>getopt_long</CODE> encounters a long option, it takes actions based
on the <CODE>flag</CODE> and <CODE>val</CODE> fields of the definition of that
option.
<P>
If <CODE>flag</CODE> is a null pointer, then <CODE>getopt_long</CODE> returns the
contents of <CODE>val</CODE> to indicate which option it found.  You should
arrange distinct values in the <CODE>val</CODE> field for options with
different meanings, so you can decode these values after
<CODE>getopt_long</CODE> returns.  If the long option is equivalent to a short
option, you can use the short option's character code in <CODE>val</CODE>.
<P>
If <CODE>flag</CODE> is not a null pointer, that means this option should just
set a flag in the program.  The flag is a variable of type <CODE>int</CODE>
that you define.  Put the address of the flag in the <CODE>flag</CODE> field.
Put in the <CODE>val</CODE> field the value you would like this option to
store in the flag.  In this case, <CODE>getopt_long</CODE> returns <CODE>0</CODE>.
<P>
For any long option, <CODE>getopt_long</CODE> tells you the index in the array
<VAR>longopts</VAR> of the options definition, by storing it into
<CODE>*<VAR>indexptr</VAR></CODE>.  You can get the name of the option with
<CODE><VAR>longopts</VAR>[*<VAR>indexptr</VAR>].name</CODE>.  So you can distinguish among
long options either by the values in their <CODE>val</CODE> fields or by their
indices.  You can also distinguish in this way among long options that
set flags.
<P>
When a long option has an argument, <CODE>getopt_long</CODE> puts the argument
value in the variable <CODE>optarg</CODE> before returning.  When the option
has no argument, the value in <CODE>optarg</CODE> is a null pointer.  This is
how you can tell whether an optional argument was supplied.
<P>
When <CODE>getopt_long</CODE> has no more options to handle, it returns
<CODE>-1</CODE>, and leaves in the variable <CODE>optind</CODE> the index in
<VAR>argv</VAR> of the next remaining argument.
<P>
<H3><A NAME="SEC391" HREF="library_toc.html#SEC391">Example of Parsing Long Options</A></H3>
<P>
<PRE>
#include &#60;stdio.h&#62;

/* Flag set by <SAMP>`--verbose'</SAMP>.   */
static int verbose_flag;

int
main (argc, argv)
     int argc;
     char **argv;
{
  int c;

  while (1)
    {
      static struct option long_options[] =
	{
	  /* These options set a flag.   */
	  {"verbose", 0, &#38;verbose_flag, 1},
	  {"brief", 0, &#38;verbose_flag, 0},
	  /* These options don't set a flag.
	     We distinguish them by their indices.  */
	  {"add", 1, 0, 0},
	  {"append", 0, 0, 0},
	  {"delete", 1, 0, 0},
	  {"create", 0, 0, 0},
	  {"file", 1, 0, 0},
	  {0, 0, 0, 0}
	};
      /* <CODE>getopt_long</CODE> stores the option index here.   */
      int option_index = 0;

      c = getopt_long (argc, argv, "abc:d:",
		       long_options, &#38;option_index);

      /* Detect the end of the options.   */
      if (c == -1)
	break;

      switch (c)
	{
	case 0:
	  /* If this option set a flag, do nothing else now.   */
	  if (long_options[option_index].flag != 0)
	    break;
	  printf ("option %s", long_options[option_index].name);
	  if (optarg)
	    printf (" with arg %s", optarg);
	  printf ("\n");
	  break;

	case 'a':
	  puts ("option -a\n");
	  break;

	case 'b':
	  puts ("option -b\n");
	  break;

	case 'c':
	  printf ("option -c with value `%s'\n", optarg);
	  break;

	case 'd':
	  printf ("option -d with value `%s'\n", optarg);
	  break;

	case '?':
	  /* <CODE>getopt_long</CODE> already printed an error message.   */
	  break;

	default:
	  abort ();
	}
    }

  /* Instead of reporting <SAMP>`--verbose'</SAMP>
     and <SAMP>`--brief'</SAMP> as they are encountered,
     we report the final status resulting from them.  */
  if (verbose_flag)
    puts ("verbose flag is set");

  /* Print any remaining command line arguments (not options).   */
  if (optind &#60; argc)
    {
      printf ("non-option ARGV-elements: ");
      while (optind &#60; argc)
	printf ("%s ", argv[optind++]);
      putchar ('\n');
    }

  exit (0);
}
</PRE>
<P>
<H2><A NAME="SEC392" HREF="library_toc.html#SEC392">Environment Variables</A></H2>
<A NAME="IDX1643"></A>
<P>
When a program is executed, it receives information about the context in
which it was invoked in two ways.  The first mechanism uses the
<VAR>argv</VAR> and <VAR>argc</VAR> arguments to its <CODE>main</CODE> function, and is
discussed in section <A HREF="library.html#SEC386">Program Arguments</A>.  The second mechanism uses
<DFN>environment variables</DFN> and is discussed in this section.
<P>
The <VAR>argv</VAR> mechanism is typically used to pass command-line
arguments specific to the particular program being invoked.  The
environment, on the other hand, keeps track of information that is
shared by many programs, changes infrequently, and that is less
frequently accessed.
<P>
The environment variables discussed in this section are the same
environment variables that you set using assignments and the
<CODE>export</CODE> command in the shell.  Programs executed from the shell
inherit all of the environment variables from the shell.
<A NAME="IDX1644"></A>
<P>
Standard environment variables are used for information about the user's
home directory, terminal type, current locale, and so on; you can define
additional variables for other purposes.  The set of all environment
variables that have values is collectively known as the
<DFN>environment</DFN>.
<P>
Names of environment variables are case-sensitive and must not contain
the character <SAMP>`='</SAMP>.  System-defined environment variables are
invariably uppercase.
<P>
The values of environment variables can be anything that can be
represented as a string.  A value must not contain an embedded null
character, since this is assumed to terminate the string.
<P>
<A NAME="IDX1645"></A>
<A NAME="IDX1646"></A>
<H3><A NAME="SEC393" HREF="library_toc.html#SEC393">Environment Access</A></H3>
<P>
The value of an environment variable can be accessed with the
<CODE>getenv</CODE> function.  This is declared in the header file
<TT>`stdlib.h'</TT>.
<A NAME="IDX1647"></A>
<P>
<A NAME="IDX1648"></A>
<U>Function:</U> char * <B>getenv</B> <I>(const char *<VAR>name</VAR>)</I><P>
This function returns a string that is the value of the environment
variable <VAR>name</VAR>.  You must not modify this string.  In some systems
not using the GNU library, it might be overwritten by subsequent calls
to <CODE>getenv</CODE> (but not by any other library function).
If the environment variable <VAR>name</VAR> is not defined, the value is a
null pointer.
<P>
<A NAME="IDX1649"></A>
<U>Function:</U> int <B>putenv</B> <I>(const char *<VAR>string</VAR>)</I><P>
The <CODE>putenv</CODE> function adds or removes definitions from the environment.
If the <VAR>string</VAR> is of the form <SAMP>`<VAR>name</VAR>=<VAR>value</VAR>'</SAMP>, the
definition is added to the environment.  Otherwise, the <VAR>string</VAR> is
interpreted as the name of an environment variable, and any definition
for this variable in the environment is removed.
<P>
The GNU library provides this function for compatibility with SVID; it
may not be available in other systems.
<P>
You can deal directly with the underlying representation of environment
objects to add more variables to the environment (for example, to
communicate with another program you are about to execute; see
section <A HREF="library.html#SEC406">Executing a File</A>).  
<P>
<A NAME="IDX1650"></A>
<U>Variable:</U> char ** <B>environ</B><P>
The environment is represented as an array of strings.  Each string is
of the format <SAMP>`<VAR>name</VAR>=<VAR>value</VAR>'</SAMP>.  The order in which
strings appear in the environment is not significant, but the same
<VAR>name</VAR> must not appear more than once.  The last element of the
array is a null pointer.
<P>
This variable is declared in the header file <TT>`unistd.h'</TT>.
<P>
If you just want to get the value of an environment variable, use
<CODE>getenv</CODE>.
<P>
<A NAME="IDX1651"></A>
<H3><A NAME="SEC394" HREF="library_toc.html#SEC394">Standard Environment Variables</A></H3>
<P>
These environment variables have standard meanings.  This doesn't mean
that they are always present in the environment; but if these variables
<EM>are</EM> present, they have these meanings, and that you shouldn't try
to use these environment variable names for some other purpose.
<P>
<DL COMPACT>
<A NAME="IDX1652"></A>
<A NAME="IDX1653"></A>
<DT><CODE>HOME</CODE>
<DD><P>
This is a string representing the user's <DFN>home directory</DFN>, or
initial default working directory.
<P>
The user can set <CODE>HOME</CODE> to any value.
If you need to make sure to obtain the proper home directory
for a particular user, you should not use <CODE>HOME</CODE>; instead,
look up the user's name in the user database (see section <A HREF="library.html#SEC441">User Database</A>).
<P>
For most purposes, it is better to use <CODE>HOME</CODE>, precisely because
this lets the user specify the value.
<P>
<A NAME="IDX1654"></A>
<DT><CODE>LOGNAME</CODE>
<DD><P>
This is the name that the user used to log in.  Since the value in the
environment can be tweaked arbitrarily, this is not a reliable way to
identify the user who is running a process; a function like
<CODE>getlogin</CODE> (see section <A HREF="library.html#SEC440">Identifying Who Logged In</A>) is better for that purpose.
<P>
For most purposes, it is better to use <CODE>LOGNAME</CODE>, precisely because
this lets the user specify the value.
<P>
<A NAME="IDX1655"></A>
<DT><CODE>PATH</CODE>
<DD><P>
A <DFN>path</DFN> is a sequence of directory names which is used for
searching for a file.  The variable <CODE>PATH</CODE> holds a path used
for searching for programs to be run.
<P>
The <CODE>execlp</CODE> and <CODE>execvp</CODE> functions (see section <A HREF="library.html#SEC406">Executing a File</A>)
use this environment variable, as do many shells and other utilities
which are implemented in terms of those functions.
<P>
The syntax of a path is a sequence of directory names separated by
colons.  An empty string instead of a directory name stands for the 
current directory (see section <A HREF="library.html#SEC188">Working Directory</A>).
<P>
A typical value for this environment variable might be a string like:
<P>
<PRE>
:/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local:/usr/local/bin
</PRE>
<P>
This means that if the user tries to execute a program named <CODE>foo</CODE>,
the system will look for files named <TT>`foo'</TT>, <TT>`/bin/foo'</TT>,
<TT>`/etc/foo'</TT>, and so on.  The first of these files that exists is
the one that is executed.
<P>
<A NAME="IDX1656"></A>
<DT><CODE>TERM</CODE>
<DD><P>
This specifies the kind of terminal that is receiving program output.
Some programs can make use of this information to take advantage of
special escape sequences or terminal modes supported by particular kinds
of terminals.  Many programs which use the termcap library
(see section 'Finding a Terminal Description' in <CITE>The Termcap Library Manual</CITE>) use the <CODE>TERM</CODE> environment variable, for example.
<P>
<A NAME="IDX1657"></A>
<DT><CODE>TZ</CODE>
<DD><P>
This specifies the time zone.  See section <A HREF="library.html#SEC318">Specifying the Time Zone with <CODE>TZ</CODE></A>, for information about
the format of this string and how it is used.
<P>
<A NAME="IDX1658"></A>
<DT><CODE>LANG</CODE>
<DD><P>
This specifies the default locale to use for attribute categories where
neither <CODE>LC_ALL</CODE> nor the specific environment variable for that
category is set.  See section <A HREF="library.html#SEC76">Locales and Internationalization</A>, for more information about
locales.
<P>
<A NAME="IDX1659"></A>
<DT><CODE>LC_COLLATE</CODE>
<DD><P>
This specifies what locale to use for string sorting.
<P>
<A NAME="IDX1660"></A>
<DT><CODE>LC_CTYPE</CODE>
<DD><P>
This specifies what locale to use for character sets and character
classification.
<P>
<A NAME="IDX1661"></A>
<DT><CODE>LC_MONETARY</CODE>
<DD><P>
This specifies what locale to use for formatting monetary values.
<P>
<A NAME="IDX1662"></A>
<DT><CODE>LC_NUMERIC</CODE>
<DD><P>
This specifies what locale to use for formatting numbers.
<P>
<A NAME="IDX1663"></A>
<DT><CODE>LC_TIME</CODE>
<DD><P>
This specifies what locale to use for formatting date/time values.
<P>
<A NAME="IDX1664"></A>
<DT><CODE>_POSIX_OPTION_ORDER</CODE>
<DD><P>
If this environment variable is defined, it suppresses the usual
reordering of command line arguments by <CODE>getopt</CODE>.  See section <A HREF="library.html#SEC387">Program Argument Syntax Conventions</A>.
<P>
</DL>
<P>
<A NAME="IDX1665"></A>
<A NAME="IDX1666"></A>
<H2><A NAME="SEC395" HREF="library_toc.html#SEC395">Program Termination</A></H2>
<A NAME="IDX1667"></A>
<P>
The usual way for a program to terminate is simply for its <CODE>main</CODE>
function to return.  The <DFN>exit status value</DFN> returned from the
<CODE>main</CODE> function is used to report information back to the process's
parent process or shell.
<P>
A program can also terminate normally by calling the <CODE>exit</CODE>
function.
<P>
In addition, programs can be terminated by signals; this is discussed in
more detail in section <A HREF="library.html#SEC330">Signal Handling</A>.  The <CODE>abort</CODE> function causes
a signal that kills the program.
<P>
<H3><A NAME="SEC396" HREF="library_toc.html#SEC396">Normal Termination</A></H3>
<P>
A process terminates normally when the program calls <CODE>exit</CODE>.
Returning from <CODE>main</CODE> is equivalent to calling <CODE>exit</CODE>, and
the value that <CODE>main</CODE> returns is used as the argument to <CODE>exit</CODE>.
<P>
<A NAME="IDX1668"></A>
<U>Function:</U> void <B>exit</B> <I>(int <VAR>status</VAR>)</I><P>
The <CODE>exit</CODE> function terminates the process with status
<VAR>status</VAR>.  This function does not return.
<P>
Normal termination causes the following actions:
<P>
<OL>
<LI>
Functions that were registered with the <CODE>atexit</CODE> or <CODE>on_exit</CODE>
functions are called in the reverse order of their registration.  This
mechanism allows your application to specify its own "cleanup" actions
to be performed at program termination.  Typically, this is used to do
things like saving program state information in a file, or unlocking
locks in shared data bases.
<P>
<LI>
All open streams are closed, writing out any buffered output data.  See
section <A HREF="library.html#SEC121">Closing Streams</A>.  In addition, temporary files opened
with the <CODE>tmpfile</CODE> function are removed; see section <A HREF="library.html#SEC164">Temporary Files</A>.
<P>
<LI>
<CODE>_exit</CODE> is called, terminating the program.  See section <A HREF="library.html#SEC400">Termination Internals</A>.
</OL>
<P>
<A NAME="IDX1669"></A>
<H3><A NAME="SEC397" HREF="library_toc.html#SEC397">Exit Status</A></H3>
<P>
When a program exits, it can return to the parent process a small
amount of information about the cause of termination, using the
<DFN>exit status</DFN>.  This is a value between 0 and 255 that the exiting
process passes as an argument to <CODE>exit</CODE>.
<P>
Normally you should use the exit status to report very broad information
about success or failure.  You can't provide a lot of detail about the
reasons for the failure, and most parent processes would not want much
detail anyway.
<P>
There are conventions for what sorts of status values certain programs
should return.  The most common convention is simply 0 for success and 1
for failure.  Programs that perform comparison use a different
convention: they use status 1 to indicate a mismatch, and status 2 to
indicate an inability to compare.  Your program should follow an
existing convention if an existing convention makes sense for it.
<P>
A general convention reserves status values 128 and up for special
purposes.  In particular, the value 128 is used to indicate failure to
execute another program in a subprocess.  This convention is not
universally obeyed, but it is a good idea to follow it in your programs.
<P>
<STRONG>Warning:</STRONG> Don't try to use the number of errors as the exit
status.  This is actually not very useful; a parent process would
generally not care how many errors occurred.  Worse than that, it does
not work, because the status value is truncated to eight bits.
Thus, if the program tried to report 256 errors, the parent would
receive a report of 0 errors--that is, success.
<P>
For the same reason, it does not work to use the value of <CODE>errno</CODE>
as the exit status--these can exceed 255.
<P>
<STRONG>Portability note:</STRONG> Some non-POSIX systems use different
conventions for exit status values.  For greater portability, you can
use the macros <CODE>EXIT_SUCCESS</CODE> and <CODE>EXIT_FAILURE</CODE> for the
conventional status value for success and failure, respectively.  They
are declared in the file <TT>`stdlib.h'</TT>.
<A NAME="IDX1670"></A>
<P>
<A NAME="IDX1671"></A>
<U>Macro:</U> int <B>EXIT_SUCCESS</B><P>
This macro can be used with the <CODE>exit</CODE> function to indicate
successful program completion.
<P>
On POSIX systems, the value of this macro is <CODE>0</CODE>.  On other
systems, the value might be some other (possibly non-constant) integer
expression.
<P>
<A NAME="IDX1672"></A>
<U>Macro:</U> int <B>EXIT_FAILURE</B><P>
This macro can be used with the <CODE>exit</CODE> function to indicate
unsuccessful program completion in a general sense.
<P>
On POSIX systems, the value of this macro is <CODE>1</CODE>.  On other
systems, the value might be some other (possibly non-constant) integer
expression.  Other nonzero status values also indicate future.  Certain
programs use different nonzero status values to indicate particular
kinds of "non-success".  For example, <CODE>diff</CODE> uses status value
<CODE>1</CODE> to mean that the files are different, and <CODE>2</CODE> or more to
mean that there was difficulty in opening the files.
<P>
<H3><A NAME="SEC398" HREF="library_toc.html#SEC398">Cleanups on Exit</A></H3>
<P>
Your program can arrange to run its own cleanup functions if normal
termination happens.  If you are writing a library for use in various
application programs, then it is unreliable to insist that all
applications call the library's cleanup functions explicitly before
exiting.  It is much more robust to make the cleanup invisible to the
application, by setting up a cleanup function in the library itself
using <CODE>atexit</CODE> or <CODE>on_exit</CODE>.
<P>
<A NAME="IDX1673"></A>
<U>Function:</U> int <B>atexit</B> <I>(void (*<VAR>function</VAR>) (void))</I><P>
The <CODE>atexit</CODE> function registers the function <VAR>function</VAR> to be
called at normal program termination.  The <VAR>function</VAR> is called with
no arguments.
<P>
The return value from <CODE>atexit</CODE> is zero on success and nonzero if
the function cannot be registered. 
<P>
<A NAME="IDX1674"></A>
<U>Function:</U> int <B>on_exit</B> <I>(void (*<VAR>function</VAR>)(int <VAR>status</VAR>, void *<VAR>arg</VAR>), void *<VAR>arg</VAR>)</I><P>
This function is a somewhat more powerful variant of <CODE>atexit</CODE>.  It
accepts two arguments, a function <VAR>function</VAR> and an arbitrary
pointer <VAR>arg</VAR>.  At normal program termination, the <VAR>function</VAR> is
called with two arguments:  the <VAR>status</VAR> value passed to <CODE>exit</CODE>,
and the <VAR>arg</VAR>.
<P>
This function is included in the GNU C library only for compatibility
for SunOS, and may not be supported by other implementations.
<P>
Here's a trivial program that illustrates the use of <CODE>exit</CODE> and
<CODE>atexit</CODE>:
<P>
<PRE>
#include &#60;stdio.h&#62;
#include &#60;stdlib.h&#62;

void 
bye (void)
{
  puts ("Goodbye, cruel world....");
}

int
main (void)
{
  atexit (bye);
  exit (EXIT_SUCCESS);
}
</PRE>
<P>
When this program is executed, it just prints the message and exits.
<P>
<A NAME="IDX1675"></A>
<H3><A NAME="SEC399" HREF="library_toc.html#SEC399">Aborting a Program</A></H3>
<P>
You can abort your program using the <CODE>abort</CODE> function.  The prototype
for this function is in <TT>`stdlib.h'</TT>.
<A NAME="IDX1676"></A>
<P>
<A NAME="IDX1677"></A>
<U>Function:</U> void <B>abort</B> <I>(void)</I><P>
The <CODE>abort</CODE> function causes abnormal program termination.  This
does not execute cleanup functions registered with <CODE>atexit</CODE> or
<CODE>on_exit</CODE>.
<P>
This function actually terminates the process by raising a
<CODE>SIGABRT</CODE> signal, and your program can include a handler to
intercept this signal; see section <A HREF="library.html#SEC330">Signal Handling</A>.
<P>
<STRONG>Future Change Warning:</STRONG> Proposed Federal censorship regulations
may prohibit us from giving you information about the possibility of
calling this function.  We would be required to say that this is not an
acceptable way of terminating a program.
<P>
<H3><A NAME="SEC400" HREF="library_toc.html#SEC400">Termination Internals</A></H3>
<P>
The <CODE>_exit</CODE> function is the primitive used for process termination
by <CODE>exit</CODE>.  It is declared in the header file <TT>`unistd.h'</TT>.
<A NAME="IDX1678"></A>
<P>
<A NAME="IDX1679"></A>
<U>Function:</U> void <B>_exit</B> <I>(int <VAR>status</VAR>)</I><P>
The <CODE>_exit</CODE> function is the primitive for causing a process to
terminate with status <VAR>status</VAR>.  Calling this function does not
execute cleanup functions registered with <CODE>atexit</CODE> or
<CODE>on_exit</CODE>.
<P>
When a process terminates for any reason--either by an explicit
termination call, or termination as a result of a signal--the
following things happen:
<P>
<UL>
<LI>
All open file descriptors in the process are closed.  See section <A HREF="library.html#SEC171">Low-Level Input/Output</A>.
<P>
<LI>
The low-order 8 bits of the return status code are saved to be reported
back to the parent process via <CODE>wait</CODE> or <CODE>waitpid</CODE>; see
section <A HREF="library.html#SEC407">Process Completion</A>.
<P>
<LI>
Any child processes of the process being terminated are assigned a new
parent process.  (This is the <CODE>init</CODE> process, with process ID 1.)
<P>
<LI>
A <CODE>SIGCHLD</CODE> signal is sent to the parent process.
<P>
<LI>
If the process is a session leader that has a controlling terminal, then
a <CODE>SIGHUP</CODE> signal is sent to each process in the foreground job,
and the controlling terminal is disassociated from that session.
See section <A HREF="library.html#SEC411">Job Control</A>.
<P>
<LI>
If termination of a process causes a process group to become orphaned,
and any member of that process group is stopped, then a <CODE>SIGHUP</CODE>
signal and a <CODE>SIGCONT</CODE> signal are sent to each process in the
group.  See section <A HREF="library.html#SEC411">Job Control</A>.
</UL>
<H1><A NAME="SEC401" HREF="library_toc.html#SEC401">Child Processes</A></H1>
<A NAME="IDX1680"></A>
<P>
<DFN>Processes</DFN> are the primitive units for allocation of system
resources.  Each process has its own address space and (usually) one
thread of control.  A process executes a program; you can have multiple
processes executing the same program, but each process has its own copy
of the program within its own address space and executes it
independently of the other copies.
<A NAME="IDX1681"></A>
<A NAME="IDX1682"></A>
<P>
Processes are organized hierarchically.  Each process has a <DFN>parent
process</DFN> which explicitly arranged to create it.  The processes created
by a given parent are called its <DFN>child processes</DFN>.  A child
inherits many of its attributes from the parent process.
<P>
This chapter describes how a program can create, terminate, and control
child processes.  Actually, there are three distinct operations
involved: creating a new child process, causing the new process to
execute a program, and coordinating the completion of the child process
with the original program.
<P>
The <CODE>system</CODE> function provides a simple, portable mechanism for
running another program; it does all three steps automatically.  If you
need more control over the details of how this is done, you can use the
primitive functions to do each step individually instead.
<P>
<A NAME="IDX1683"></A>
<H2><A NAME="SEC402" HREF="library_toc.html#SEC402">Running a Command</A></H2>
<P>
The easy way to run another program is to use the <CODE>system</CODE>
function.  This function does all the work of running a subprogram, but
it doesn't give you much control over the details: you have to wait
until the subprogram terminates before you can do anything else.
<P>
<A NAME="IDX1684"></A>
<A NAME="IDX1685"></A>
<U>Function:</U> int <B>system</B> <I>(const char *<VAR>command</VAR>)</I><P>
This function executes <VAR>command</VAR> as a shell command.  In the GNU C
library, it always uses the default shell <CODE>sh</CODE> to run the command.
In particular, it searches the directories in <CODE>PATH</CODE> to find
programs to execute.  The return value is <CODE>-1</CODE> if it wasn't
possible to create the shell process, and otherwise is the status of the
shell process.  See section <A HREF="library.html#SEC407">Process Completion</A>, for details on how this
status code can be interpreted.
<A NAME="IDX1686"></A>
<P>
The <CODE>system</CODE> function is declared in the header file
<TT>`stdlib.h'</TT>.
<P>
<STRONG>Portability Note:</STRONG> Some C implementations may not have any
notion of a command processor that can execute other programs.  You can
determine whether a command processor exists by executing
<CODE>system (NULL)</CODE>; if the return value is nonzero, a command
processor is available.
<P>
The <CODE>popen</CODE> and <CODE>pclose</CODE> functions (see section <A HREF="library.html#SEC213">Pipe to a Subprocess</A>) are closely related to the <CODE>system</CODE> function.  They
allow the parent process to communicate with the standard input and
output channels of the command being executed.
<P>
<H2><A NAME="SEC403" HREF="library_toc.html#SEC403">Process Creation Concepts</A></H2>
<P>
This section gives an overview of processes and of the steps involved in
creating a process and making it run another program.
<A NAME="IDX1687"></A>
<A NAME="IDX1688"></A>
<P>
Each process is named by a <DFN>process ID</DFN> number.  A unique process ID
is allocated to each process when it is created.  The <DFN>lifetime</DFN> of
a process ends when its termination is reported to its parent process;
at that time, all of the process resources, including its process ID,
are freed.
<A NAME="IDX1689"></A>
<A NAME="IDX1690"></A>
<A NAME="IDX1691"></A>
<A NAME="IDX1692"></A>
<P>
Processes are created with the <CODE>fork</CODE> system call (so the operation
of creating a new process is sometimes called <DFN>forking</DFN> a process).
The <DFN>child process</DFN> created by <CODE>fork</CODE> is an exact clone of the
original <DFN>parent process</DFN>, except that it has its own process ID.
<P>
After forking a child process, both the parent and child processes
continue to execute normally.  If you want your program to wait for a
child process to finish executing before continuing, you must do this
explicitly after the fork operation, by calling <CODE>wait</CODE> or
<CODE>waitpid</CODE> (see section <A HREF="library.html#SEC407">Process Completion</A>).  These functions give you
limited information about why the child terminated--for example, its
exit status code.
<P>
A newly forked child process continues to execute the same program as
its parent process, at the point where the <CODE>fork</CODE> call returns.
You can use the return value from <CODE>fork</CODE> to tell whether the program
is running in the parent process or the child.
<A NAME="IDX1693"></A>
<P>
Having several processes run the same program is only occasionally
useful.  But the child can execute another program using one of the
<CODE>exec</CODE> functions; see section <A HREF="library.html#SEC406">Executing a File</A>.  The program that the
process is executing is called its <DFN>process image</DFN>.  Starting
execution of a new program causes the process to forget all about its
previous process image; when the new program exits, the process exits
too, instead of returning to the previous process image.
<P>
<H2><A NAME="SEC404" HREF="library_toc.html#SEC404">Process Identification</A></H2>
<P>
The <CODE>pid_t</CODE> data type represents process IDs.  You can get the
process ID of a process by calling <CODE>getpid</CODE>.  The function
<CODE>getppid</CODE> returns the process ID of the parent of the current
process (this is also known as the <DFN>parent process ID</DFN>).  Your
program should include the header files <TT>`unistd.h'</TT> and
<TT>`sys/types.h'</TT> to use these functions.
<A NAME="IDX1695"></A>
<A NAME="IDX1694"></A>
<P>
<A NAME="IDX1696"></A>
<U>Data Type:</U> <B>pid_t</B><P>
The <CODE>pid_t</CODE> data type is a signed integer type which is capable
of representing a process ID.  In the GNU library, this is an <CODE>int</CODE>.
<P>
<A NAME="IDX1697"></A>
<U>Function:</U> pid_t <B>getpid</B> <I>(void)</I><P>
The <CODE>getpid</CODE> function returns the process ID of the current process.
<P>
<A NAME="IDX1698"></A>
<U>Function:</U> pid_t <B>getppid</B> <I>(void)</I><P>
The <CODE>getppid</CODE> function returns the process ID of the parent of the
current process.
<P>
<H2><A NAME="SEC405" HREF="library_toc.html#SEC405">Creating a Process</A></H2>
<P>
The <CODE>fork</CODE> function is the primitive for creating a process.
It is declared in the header file <TT>`unistd.h'</TT>.
<A NAME="IDX1699"></A>
<P>
<A NAME="IDX1700"></A>
<U>Function:</U> pid_t <B>fork</B> <I>(void)</I><P>
The <CODE>fork</CODE> function creates a new process.
<P>
If the operation is successful, there are then both parent and child
processes and both see <CODE>fork</CODE> return, but with different values: it
returns a value of <CODE>0</CODE> in the child process and returns the child's
process ID in the parent process.
<P>
If process creation failed, <CODE>fork</CODE> returns a value of <CODE>-1</CODE> in
the parent process.  The following <CODE>errno</CODE> error conditions are
defined for <CODE>fork</CODE>:
<P>
<DL COMPACT>
<DT><CODE>EAGAIN</CODE>
<DD>There aren't enough system resources to create another process, or the
user already has too many processes running.
<P>
<DT><CODE>ENOMEM</CODE>
<DD>The process requires more space than the system can supply.
</DL>
<P>
The specific attributes of the child process that differ from the
parent process are:
<P>
<UL>
<LI>
The child process has its own unique process ID.
<P>
<LI>
The parent process ID of the child process is the process ID of its
parent process.
<P>
<LI>
The child process gets its own copies of the parent process's open file
descriptors.  Subsequently changing attributes of the file descriptors
in the parent process won't affect the file descriptors in the child,
and vice versa.  See section <A HREF="library.html#SEC181">Control Operations on Files</A>.
<P>
<LI>
The elapsed processor times for the child process are set to zero;
see section <A HREF="library.html#SEC310">Processor Time</A>.
<P>
<LI>
The child doesn't inherit file locks set by the parent process.
See section <A HREF="library.html#SEC181">Control Operations on Files</A>.
<P>
<LI>
The child doesn't inherit alarms set by the parent process.
See section <A HREF="library.html#SEC321">Setting an Alarm</A>.
<P>
<LI>
The set of pending signals (see section <A HREF="library.html#SEC334">How Signals Are Delivered</A>) for the child
process is cleared.  (The child process inherits its mask of blocked
signals and signal actions from the parent process.)
</UL>
<P>
<A NAME="IDX1701"></A>
<U>Function:</U> pid_t <B>vfork</B> <I>(void)</I><P>
The <CODE>vfork</CODE> function is similar to <CODE>fork</CODE> but more efficient;
however, there are restrictions you must follow to use it safely.
<P>
While <CODE>fork</CODE> makes a complete copy of the calling process's address
space and allows both the parent and child to execute independently,
<CODE>vfork</CODE> does not make this copy.  Instead, the child process
created with <CODE>vfork</CODE> shares its parent's address space until it calls
one of the <CODE>exec</CODE> functions.  In the meantime, the parent process
suspends execution.
<P>
You must be very careful not to allow the child process created with
<CODE>vfork</CODE> to modify any global data or even local variables shared
with the parent.  Furthermore, the child process cannot return from (or
do a long jump out of) the function that called <CODE>vfork</CODE>!  This
would leave the parent process's control information very confused.  If
in doubt, use <CODE>fork</CODE> instead.
<P>
Some operating systems don't really implement <CODE>vfork</CODE>.  The GNU C
library permits you to use <CODE>vfork</CODE> on all systems, but actually
executes <CODE>fork</CODE> if <CODE>vfork</CODE> isn't available.  If you follow
the proper precautions for using <CODE>vfork</CODE>, your program will still
work even if the system uses <CODE>fork</CODE> instead.
<P>
<A NAME="IDX1702"></A>
<A NAME="IDX1703"></A>
<H2><A NAME="SEC406" HREF="library_toc.html#SEC406">Executing a File</A></H2>
<P>
This section describes the <CODE>exec</CODE> family of functions, for executing
a file as a process image.  You can use these functions to make a child
process execute a new program after it has been forked.
<A NAME="IDX1704"></A>
<P>
The functions in this family differ in how you specify the arguments,
but otherwise they all do the same thing.  They are declared in the
header file <TT>`unistd.h'</TT>.
<P>
<A NAME="IDX1705"></A>
<U>Function:</U> int <B>execv</B> <I>(const char *<VAR>filename</VAR>, char *const <VAR>argv</VAR><TT>[]</TT>)</I><P>
The <CODE>execv</CODE> function executes the file named by <VAR>filename</VAR> as a
new process image.
<P>
The <VAR>argv</VAR> argument is an array of null-terminated strings that is
used to provide a value for the <CODE>argv</CODE> argument to the <CODE>main</CODE>
function of the program to be executed.  The last element of this array
must be a null pointer.  See section <A HREF="library.html#SEC386">Program Arguments</A>, for information on
how programs can access these arguments.
<P>
The environment for the new process image is taken from the
<CODE>environ</CODE> variable of the current process image; see section <A HREF="library.html#SEC392">Environment Variables</A>, for information about environments.
<P>
<A NAME="IDX1706"></A>
<U>Function:</U> int <B>execl</B> <I>(const char *<VAR>filename</VAR>, const char *<VAR>arg0</VAR>, ...)</I><P>
This is similar to <CODE>execv</CODE>, but the <VAR>argv</VAR> strings are
specified individually instead of as an array.  A null pointer must be
passed as the last such argument.
<P>
<A NAME="IDX1707"></A>
<U>Function:</U> int <B>execve</B> <I>(const char *<VAR>filename</VAR>, char *const <VAR>argv</VAR><TT>[]</TT>, char *const <VAR>env</VAR><TT>[]</TT>)</I><P>
This is similar to <CODE>execv</CODE>, but permits you to specify the environment
for the new program explicitly as the <VAR>env</VAR> argument.  This should
be an array of strings in the same format as for the <CODE>environ</CODE> 
variable; see section <A HREF="library.html#SEC393">Environment Access</A>.
<P>
<A NAME="IDX1708"></A>
<U>Function:</U> int <B>execle</B> <I>(const char *<VAR>filename</VAR>, const char *<VAR>arg0</VAR>, char *const <VAR>env</VAR><TT>[]</TT>, ...)</I><P>
This is similar to <CODE>execl</CODE>, but permits you to specify the
environment for the new program explicitly.  The environment argument is
passed following the null pointer that marks the last <VAR>argv</VAR>
argument, and should be an array of strings in the same format as for
the <CODE>environ</CODE> variable.
<P>
<A NAME="IDX1709"></A>
<U>Function:</U> int <B>execvp</B> <I>(const char *<VAR>filename</VAR>, char *const <VAR>argv</VAR><TT>[]</TT>)</I><P>
The <CODE>execvp</CODE> function is similar to <CODE>execv</CODE>, except that it
searches the directories listed in the <CODE>PATH</CODE> environment variable
(see section <A HREF="library.html#SEC394">Standard Environment Variables</A>) to find the full file name of a
file from <VAR>filename</VAR> if <VAR>filename</VAR> does not contain a slash.
<P>
This function is useful for executing system utility programs, because
it looks for them in the places that the user has chosen.  Shells use it
to run the commands that users type.
<P>
<A NAME="IDX1710"></A>
<U>Function:</U> int <B>execlp</B> <I>(const char *<VAR>filename</VAR>, const char *<VAR>arg0</VAR>, ...)</I><P>
This function is like <CODE>execl</CODE>, except that it performs the same
file name searching as the <CODE>execvp</CODE> function.
<P>
The size of the argument list and environment list taken together must
not be greater than <CODE>ARG_MAX</CODE> bytes.  See section <A HREF="library.html#SEC455">General Capacity Limits</A>.  In
the GNU system, the size (which compares against <CODE>ARG_MAX</CODE>)
includes, for each string, the number of characters in the string, plus
the size of a <CODE>char *</CODE>, plus one, rounded up to a multiple of the
size of a <CODE>char *</CODE>.  Other systems may have somewhat different
rules for counting.
<P>
These functions normally don't return, since execution of a new program
causes the currently executing program to go away completely.  A value
of <CODE>-1</CODE> is returned in the event of a failure.  In addition to the
usual file name syntax errors (see section <A HREF="library.html#SEC115">File Name Errors</A>), the following
<CODE>errno</CODE> error conditions are defined for these functions:
<P>
<DL COMPACT>
<DT><CODE>E2BIG</CODE>
<DD>The combined size of the new program's argument list and environment
list is larger than <CODE>ARG_MAX</CODE> bytes.  The GNU system has no
specific limit on the argument list size, so this error code cannot
result, but you may get <CODE>ENOMEM</CODE> instead if the arguments are too
big for available memory.
<P>
<DT><CODE>ENOEXEC</CODE>
<DD>The specified file can't be executed because it isn't in the right format.
<P>
<DT><CODE>ENOMEM</CODE>
<DD>Executing the specified file requires more storage than is available.
</DL>
<P>
If execution of the new file succeeds, it updates the access time field
of the file as if the file had been read.  See section <A HREF="library.html#SEC209">File Times</A>, for more
details about access times of files.
<P>
The point at which the file is closed again is not specified, but
is at some point before the process exits or before another process
image is executed.
<P>
Executing a new process image completely changes the contents of memory,
copying only the argument and environment strings to new locations.  But
many other attributes of the process are unchanged:
<P>
<UL>
<LI>
The process ID and the parent process ID.  See section <A HREF="library.html#SEC403">Process Creation Concepts</A>.
<P>
<LI>
Session and process group membership.  See section <A HREF="library.html#SEC412">Concepts of Job Control</A>.
<P>
<LI>
Real user ID and group ID, and supplementary group IDs.  See section <A HREF="library.html#SEC431">The Persona of a Process</A>.
<P>
<LI>
Pending alarms.  See section <A HREF="library.html#SEC321">Setting an Alarm</A>.
<P>
<LI>
Current working directory and root directory.  See section <A HREF="library.html#SEC188">Working Directory</A>.
<P>
<LI>
File mode creation mask.  See section <A HREF="library.html#SEC207">Assigning File Permissions</A>.
<P>
<LI>
Process signal mask; see section <A HREF="library.html#SEC371">Process Signal Mask</A>.
<P>
<LI>
Pending signals; see section <A HREF="library.html#SEC368">Blocking Signals</A>.
<P>
<LI>
Elapsed processor time associated with the process; see section <A HREF="library.html#SEC310">Processor Time</A>.
</UL>
<P>
If the set-user-ID and set-group-ID mode bits of the process image file
are set, this affects the effective user ID and effective group ID
(respectively) of the process.  These concepts are discussed in detail
in section <A HREF="library.html#SEC431">The Persona of a Process</A>.
<P>
Signals that are set to be ignored in the existing process image are
also set to be ignored in the new process image.  All other signals are
set to the default action in the new process image.  For more
information about signals, see section <A HREF="library.html#SEC330">Signal Handling</A>.
<P>
File descriptors open in the existing process image remain open in the
new process image, unless they have the <CODE>FD_CLOEXEC</CODE>
(close-on-exec) flag set.  The files that remain open inherit all
attributes of the open file description from the existing process image,
including file locks.  File descriptors are discussed in section <A HREF="library.html#SEC171">Low-Level Input/Output</A>.
<P>
Streams, by contrast, cannot survive through <CODE>exec</CODE> functions,
because they are located in the memory of the process itself.  The new
process image has no streams except those it creates afresh.  Each of
the streams in the pre-<CODE>exec</CODE> process image has a descriptor inside
it, and these descriptors do survive through <CODE>exec</CODE> (provided that
they do not have <CODE>FD_CLOEXEC</CODE> set.  The new process image can
reconnect these to new streams using <CODE>fdopen</CODE> (see section <A HREF="library.html#SEC175">Descriptors and Streams</A>).
<P>
<A NAME="IDX1711"></A>
<A NAME="IDX1712"></A>
<A NAME="IDX1713"></A>
<H2><A NAME="SEC407" HREF="library_toc.html#SEC407">Process Completion</A></H2>
<P>
The functions described in this section are used to wait for a child
process to terminate or stop, and determine its status.  These functions
are declared in the header file <TT>`sys/wait.h'</TT>.
<A NAME="IDX1714"></A>
<P>
<A NAME="IDX1715"></A>
<U>Function:</U> pid_t <B>waitpid</B> <I>(pid_t <VAR>pid</VAR>, int *<VAR>status_ptr</VAR>, int <VAR>options</VAR>)</I><P>
The <CODE>waitpid</CODE> function is used to request status information from a
child process whose process ID is <VAR>pid</VAR>.  Normally, the calling
process is suspended until the child process makes status information
available by terminating.
<P>
Other values for the <VAR>pid</VAR> argument have special interpretations.  A
value of <CODE>-1</CODE> or <CODE>WAIT_ANY</CODE> requests status information for
any child process; a value of <CODE>0</CODE> or <CODE>WAIT_MYPGRP</CODE> requests
information for any child process in the same process group as the
calling process; and any other negative value - <VAR>pgid</VAR>
requests information for any child process whose process group ID is
<VAR>pgid</VAR>.
<P>
If status information for a child process is available immediately, this
function returns immediately without waiting.  If more than one eligible
child process has status information available, one of them is chosen
randomly, and its status is returned immediately.  To get the status
from the other eligible child processes, you need to call <CODE>waitpid</CODE>
again.
<P>
The <VAR>options</VAR> argument is a bit mask.  Its value should be the
bitwise OR (that is, the <SAMP>`|'</SAMP> operator) of zero or more of the
<CODE>WNOHANG</CODE> and <CODE>WUNTRACED</CODE> flags.  You can use the
<CODE>WNOHANG</CODE> flag to indicate that the parent process shouldn't wait;
and the <CODE>WUNTRACED</CODE> flag to request status information from stopped
processes as well as processes that have terminated.
<P>
The status information from the child process is stored in the object
that <VAR>status_ptr</VAR> points to, unless <VAR>status_ptr</VAR> is a null pointer.
<P>
The return value is normally the process ID of the child process whose
status is reported.  If the <CODE>WNOHANG</CODE> option was specified and no
child process is waiting to be noticed, the value is zero.  A value of
<CODE>-1</CODE> is returned in case of error.  The following <CODE>errno</CODE>
error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EINTR</CODE>
<DD>The function was interrupted by delivery of a signal to the calling
process.  See section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<DT><CODE>ECHILD</CODE>
<DD>There are no child processes to wait for, or the specified <VAR>pid</VAR>
is not a child of the calling process.
<P>
<DT><CODE>EINVAL</CODE>
<DD>An invalid value was provided for the <VAR>options</VAR> argument.
</DL>
<P>
These symbolic constants are defined as values for the <VAR>pid</VAR> argument
to the <CODE>waitpid</CODE> function.
<P>
<DL COMPACT>
<DT><CODE>WAIT_ANY</CODE>
<DD><P>
This constant macro (whose value is <CODE>-1</CODE>) specifies that
<CODE>waitpid</CODE> should return status information about any child process.
<P>
<DT><CODE>WAIT_MYPGRP</CODE>
<DD>This constant (with value <CODE>0</CODE>) specifies that <CODE>waitpid</CODE> should
return status information about any child process in the same process
group as the calling process.
</DL>
<P>
These symbolic constants are defined as flags for the <VAR>options</VAR>
argument to the <CODE>waitpid</CODE> function.  You can bitwise-OR the flags
together to obtain a value to use as the argument.
<P>
<DL COMPACT>
<DT><CODE>WNOHANG</CODE>
<DD><P>
This flag specifies that <CODE>waitpid</CODE> should return immediately
instead of waiting, if there is no child process ready to be noticed.
<P>
<DT><CODE>WUNTRACED</CODE>
<DD><P>
This flag specifies that <CODE>waitpid</CODE> should report the status of any
child processes that have been stopped as well as those that have
terminated.
</DL>
<P>
<A NAME="IDX1716"></A>
<U>Function:</U> pid_t <B>wait</B> <I>(int *<VAR>status_ptr</VAR>)</I><P>
This is a simplified version of <CODE>waitpid</CODE>, and is used to wait
until any one child process terminates.  The call:
<P>
<PRE>
wait (&#38;status)
</PRE>
<P>
is exactly equivalent to:
<P>
<PRE>
waitpid (-1, &#38;status, 0)
</PRE>
<P>
Here's an example of how to use <CODE>waitpid</CODE> to get the status from
all child processes that have terminated, without ever waiting.  This
function is designed to be a handler for <CODE>SIGCHLD</CODE>, the signal that
indicates that at least one child process has terminated.
<P>
<PRE>
void
sigchld_handler (int signum)
{
  int pid;
  int status;
  while (1)
    {
      pid = waitpid (WAIT_ANY, &#38;status, WNOHANG);
      if (pid &#60; 0)
        {
          perror ("waitpid");
          break;
        }
      if (pid == 0)
        break;
      notice_termination (pid, status);
    }
}
</PRE>
<P>
<H2><A NAME="SEC408" HREF="library_toc.html#SEC408">Process Completion Status</A></H2>
<P>
If the exit status value (see section <A HREF="library.html#SEC395">Program Termination</A>) of the child
process is zero, then the status value reported by <CODE>waitpid</CODE> or
<CODE>wait</CODE> is also zero.  You can test for other kinds of information
encoded in the returned status value using the following macros.
These macros are defined in the header file <TT>`sys/wait.h'</TT>.
<A NAME="IDX1717"></A>
<P>
<A NAME="IDX1718"></A>
<U>Macro:</U> int <B>WIFEXITED</B> <I>(int <VAR>status</VAR>)</I><P>
This macro returns a nonzero value if the child process terminated
normally with <CODE>exit</CODE> or <CODE>_exit</CODE>.
<P>
<A NAME="IDX1719"></A>
<U>Macro:</U> int <B>WEXITSTATUS</B> <I>(int <VAR>status</VAR>)</I><P>
If <CODE>WIFEXITED</CODE> is true of <VAR>status</VAR>, this macro returns the
low-order 8 bits of the exit status value from the child process.
See section <A HREF="library.html#SEC397">Exit Status</A>.
<P>
<A NAME="IDX1720"></A>
<U>Macro:</U> int <B>WIFSIGNALED</B> <I>(int <VAR>status</VAR>)</I><P>
This macro returns a nonzero value if the child process terminated
because it received a signal that was not handled.
See section <A HREF="library.html#SEC330">Signal Handling</A>.
<P>
<A NAME="IDX1721"></A>
<U>Macro:</U> int <B>WTERMSIG</B> <I>(int <VAR>status</VAR>)</I><P>
If <CODE>WIFSIGNALED</CODE> is true of <VAR>status</VAR>, this macro returns the
signal number of the signal that terminated the child process.
<P>
<A NAME="IDX1722"></A>
<U>Macro:</U> int <B>WCOREDUMP</B> <I>(int <VAR>status</VAR>)</I><P>
This macro returns a nonzero value if the child process terminated
and produced a core dump.
<P>
<A NAME="IDX1723"></A>
<U>Macro:</U> int <B>WIFSTOPPED</B> <I>(int <VAR>status</VAR>)</I><P>
This macro returns a nonzero value if the child process is stopped.
<P>
<A NAME="IDX1724"></A>
<U>Macro:</U> int <B>WSTOPSIG</B> <I>(int <VAR>status</VAR>)</I><P>
If <CODE>WIFSTOPPED</CODE> is true of <VAR>status</VAR>, this macro returns the
signal number of the signal that caused the child process to stop.
<P>
<H2><A NAME="SEC409" HREF="library_toc.html#SEC409">BSD Process Wait Functions</A></H2>
<P>
The GNU library also provides these related facilities for compatibility
with BSD Unix.  BSD uses the <CODE>union wait</CODE> data type to represent
status values rather than an <CODE>int</CODE>.  The two representations are
actually interchangeable; they describe the same bit patterns.  The GNU
C Library defines macros such as <CODE>WEXITSTATUS</CODE> so that they will
work on either kind of object, and the <CODE>wait</CODE> function is defined
to accept either type of pointer as its <VAR>status_ptr</VAR> argument.
<P>
These functions are declared in <TT>`sys/wait.h'</TT>.
<A NAME="IDX1725"></A>
<P>
<A NAME="IDX1726"></A>
<U>Data Type:</U> <B>union wait</B><P>
This data type represents program termination status values.  It has
the following members:
<P>
<DL COMPACT>
<DT><CODE>int w_termsig</CODE>
<DD>This member is equivalent to the <CODE>WTERMSIG</CODE> macro.
<P>
<DT><CODE>int w_coredump</CODE>
<DD>This member is equivalent to the <CODE>WCOREDUMP</CODE> macro.
<P>
<DT><CODE>int w_retcode</CODE>
<DD>This member is equivalent to the <CODE>WEXISTATUS</CODE> macro.
<P>
<DT><CODE>int w_stopsig</CODE>
<DD>This member is equivalent to the <CODE>WSTOPSIG</CODE> macro.
</DL>
<P>
Instead of accessing these members directly, you should use the
equivalent macros.
<P>
<A NAME="IDX1727"></A>
<U>Function:</U> pid_t <B>wait3</B> <I>(union wait *<VAR>status_ptr</VAR>, int <VAR>options</VAR>, struct rusage *<VAR>usage</VAR>)</I><P>
If <VAR>usage</VAR> is a null pointer, <CODE>wait3</CODE> is equivalent to
<CODE>waitpid (-1, <VAR>status_ptr</VAR>, <VAR>options</VAR>)</CODE>.
<P>
If <VAR>usage</VAR> is not null, <CODE>wait3</CODE> stores usage figures for the
child process in <CODE>*<VAR>rusage</VAR></CODE> (but only if the child has
terminated, not if it has stopped).  See section <A HREF="library.html#SEC323">Resource Usage</A>.
<P>
<A NAME="IDX1728"></A>
<U>Function:</U> pid_t <B>wait4</B> <I>(pid_t <VAR>pid</VAR>, union wait *<VAR>status_ptr</VAR>, int <VAR>options</VAR>, struct rusage *<VAR>usage</VAR>)</I><P>
If <VAR>usage</VAR> is a null pointer, <CODE>wait4</CODE> is equivalent to
<CODE>waitpid (<VAR>pid</VAR>, <VAR>status_ptr</VAR>, <VAR>options</VAR>)</CODE>.
<P>
If <VAR>usage</VAR> is not null, <CODE>wait4</CODE> stores usage figures for the
child process in <CODE>*<VAR>rusage</VAR></CODE> (but only if the child has
terminated, not if it has stopped).  See section <A HREF="library.html#SEC323">Resource Usage</A>.
<P>
<H2><A NAME="SEC410" HREF="library_toc.html#SEC410">Process Creation Example</A></H2>
<P>
Here is an example program showing how you might write a function
similar to the built-in <CODE>system</CODE>.  It executes its <VAR>command</VAR>
argument using the equivalent of <SAMP>`sh -c <VAR>command</VAR>'</SAMP>.
<P>
<PRE>
#include &#60;stddef.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;unistd.h&#62;
#include &#60;sys/types.h&#62;
#include &#60;sys/wait.h&#62;

/* Execute the command using this shell program.  */
#define SHELL "/bin/sh"

int 
my_system (const char *command)
{
  int status;
  pid_t pid;

  pid = fork ();
  if (pid == 0)
    {
      /* This is the child process.  Execute the shell command. */
      execl (SHELL, SHELL, "-c", command, NULL);
      _exit (EXIT_FAILURE);
    }
  else if (pid &#60; 0)
    /* The fork failed.  Report failure.  */
    status = -1;
  else
    /* This is the parent process.  Wait for the child to complete.  */
    if (waitpid (pid, &#38;status, 0) != pid)
      status = -1;
  return status;
}
</PRE>
<P>
There are a couple of things you should pay attention to in this
example.
<P>
Remember that the first <CODE>argv</CODE> argument supplied to the program
represents the name of the program being executed.  That is why, in the
call to <CODE>execl</CODE>, <CODE>SHELL</CODE> is supplied once to name the program
to execute and a second time to supply a value for <CODE>argv[0]</CODE>.  
<P>
The <CODE>execl</CODE> call in the child process doesn't return if it is
successful.  If it fails, you must do something to make the child
process terminate.  Just returning a bad status code with <CODE>return</CODE>
would leave two processes running the original program.  Instead, the
right behavior is for the child process to report failure to its parent
process.
<P>
Call <CODE>_exit</CODE> to accomplish this.  The reason for using <CODE>_exit</CODE>
instead of <CODE>exit</CODE> is to avoid flushing fully buffered streams such
as <CODE>stdout</CODE>.  The buffers of these streams probably contain data
that was copied from the parent process by the <CODE>fork</CODE>, data that
will be output eventually by the parent process.  Calling <CODE>exit</CODE> in
the child would output the data twice.  See section <A HREF="library.html#SEC400">Termination Internals</A>.
<H1><A NAME="SEC411" HREF="library_toc.html#SEC411">Job Control</A></H1>
<A NAME="IDX1729"></A>
<A NAME="IDX1730"></A>
<A NAME="IDX1731"></A>
<A NAME="IDX1732"></A>
<P>
<DFN>Job control</DFN> refers to the protocol for allowing a user to move
between multiple <DFN>process groups</DFN> (or <DFN>jobs</DFN>) within a single
<DFN>login session</DFN>.  The job control facilities are set up so that
appropriate behavior for most programs happens automatically and they
need not do anything special about job control.  So you can probably
ignore the material in this chapter unless you are writing a shell or
login program.
<P>
You need to be familiar with concepts relating to process creation
(see section <A HREF="library.html#SEC403">Process Creation Concepts</A>) and signal handling (see section <A HREF="library.html#SEC330">Signal Handling</A>) in order to understand this material presented in this
chapter.
<P>
<H2><A NAME="SEC412" HREF="library_toc.html#SEC412">Concepts of Job Control</A></H2>
<A NAME="IDX1733"></A>
<P>
The fundamental purpose of an interactive shell is to read
commands from the user's terminal and create processes to execute the
programs specified by those commands.  It can do this using the
<CODE>fork</CODE> (see section <A HREF="library.html#SEC405">Creating a Process</A>) and <CODE>exec</CODE>
(see section <A HREF="library.html#SEC406">Executing a File</A>) functions.
<P>
A single command may run just one process--but often one command uses
several processes.  If you use the <SAMP>`|'</SAMP> operator in a shell command,
you explicitly request several programs in their own processes.  But
even if you run just one program, it can use multiple processes
internally.  For example, a single compilation command such as <SAMP>`cc
-c foo.c'</SAMP> typically uses four processes (though normally only two at any
given time).  If you run <CODE>make</CODE>, its job is to run other programs
in separate processes.
<P>
The processes belonging to a single command are called a <DFN>process
group</DFN> or <DFN>job</DFN>.  This is so that you can operate on all of them at
once.  For example, typing <KBD>C-c</KBD> sends the signal <CODE>SIGINT</CODE> to
terminate all the processes in the foreground process group.
<A NAME="IDX1734"></A>
<P>
A <DFN>session</DFN> is a larger group of processes.  Normally all the
proccesses that stem from a single login belong to the same session.
<P>
Every process belongs to a process group.  When a process is created, it
becomes a member of the same process group and session as its parent
process.  You can put it in another process group using the
<CODE>setpgid</CODE> function, provided the process group belongs to the same
session.
<A NAME="IDX1735"></A>
<P>
The only way to put a process in a different session is to make it the
initial process of a new session, or a <DFN>session leader</DFN>, using the
<CODE>setsid</CODE> function.  This also puts the session leader into a new
process group, and you can't move it out of that process group again.
<P>
Usually, new sessions are created by the system login program, and the
session leader is the process running the user's login shell.
<A NAME="IDX1736"></A>
<P>
A shell that supports job control must arrange to control which job can
use the terminal at any time.  Otherwise there might be multiple jobs
trying to read from the terminal at once, and confusion about which
process should receive the input typed by the user.  To prevent this,
the shell must cooperate with the terminal driver using the protocol
described in this chapter.
<A NAME="IDX1737"></A>
<A NAME="IDX1738"></A>
<P>
The shell can give unlimited access to the controlling terminal to only
one process group at a time.  This is called the <DFN>foreground job</DFN> on
that controlling terminal.  Other process groups managed by the shell
that are executing without such access to the terminal are called
<DFN>background jobs</DFN>.
<A NAME="IDX1739"></A>
<P>
If a background job needs to read from or write to its controlling
terminal, it is <DFN>stopped</DFN> by the terminal driver.  The user can stop
a foreground job by typing the SUSP character (see section <A HREF="library.html#SEC281">Special Characters</A>) and a program can stop any job by sending it a
<CODE>SIGSTOP</CODE> signal.  It's the responsibility of the shell to notice
when jobs stop, to notify the user about them, and to provide mechanisms
for allowing the user to interactively continue stopped jobs and switch
jobs between foreground and background.
<P>
See section <A HREF="library.html#SEC415">Access to the Controlling Terminal</A>, for more information about I/O to the
controlling terminal,
<P>
<A NAME="IDX1740"></A>
<H2><A NAME="SEC413" HREF="library_toc.html#SEC413">Job Control is Optional</A></H2>
<P>
Not all operating systems support job control.  The GNU system does
support job control, but if you are using the GNU library on some other
system, that system may not support job control itself.
<P>
You can use the <CODE>_POSIX_JOB_CONTROL</CODE> macro to test at compile-time
whether the system supports job control.  See section <A HREF="library.html#SEC456">Overall System Options</A>.
<P>
If job control is not supported, then there can be only one process
group per session, which behaves as if it were always in the foreground.
The functions for creating additional process groups simply fail with
the error code <CODE>ENOSYS</CODE>.
<P>
The macros naming the various job control signals (see section <A HREF="library.html#SEC340">Job Control Signals</A>) are defined even if job control is not supported.  However,
the system never generates these signals, and attempts to send a job
control signal or examine or specify their actions report errors or do
nothing.
<P>
<H2><A NAME="SEC414" HREF="library_toc.html#SEC414">Controlling Terminal of a Process</A></H2>
<P>
One of the attributes of a process is its controlling terminal.  Child
processes created with <CODE>fork</CODE> inherit the controlling terminal from
their parent process.  In this way, all the processes in a session
inherit the controlling terminal from the session leader.  A session
leader that has control of a terminal is called the <DFN>controlling
process</DFN> of that terminal.
<A NAME="IDX1741"></A>
<P>
You generally do not need to worry about the exact mechanism used to
allocate a controlling terminal to a session, since it is done for you
by the system when you log in.
<P>
An individual process disconnects from its controlling terminal when it
calls <CODE>setsid</CODE> to become the leader of a new session.
See section <A HREF="library.html#SEC427">Process Group Functions</A>.
<P>
<A NAME="IDX1742"></A>
<H2><A NAME="SEC415" HREF="library_toc.html#SEC415">Access to the Controlling Terminal</A></H2>
<P>
Processes in the foreground job of a controlling terminal have
unrestricted access to that terminal; background proesses do not.  This
section describes in more detail what happens when a process in a
background job tries to access its controlling terminal.
<A NAME="IDX1743"></A>
<P>
When a process in a background job tries to read from its controlling
terminal, the process group is usually sent a <CODE>SIGTTIN</CODE> signal.
This normally causes all of the processes in that group to stop (unless
they handle the signal and don't stop themselves).  However, if the
reading process is ignoring or blocking this signal, then <CODE>read</CODE>
fails with an <CODE>EIO</CODE> error instead.
<A NAME="IDX1744"></A>
<P>
Similarly, when a process in a background job tries to write to its
controlling terminal, the default behavior is to send a <CODE>SIGTTOU</CODE>
signal to the process group.  However, the behavior is modified by the
<CODE>TOSTOP</CODE> bit of the local modes flags (see section <A HREF="library.html#SEC279">Local Modes</A>).  If
this bit is not set (which is the default), then writing to the
controlling terminal is always permitted without sending a signal.
Writing is also permitted if the <CODE>SIGTTOU</CODE> signal is being ignored
or blocked by the writing process.
<P>
Most other terminal operations that a program can do are treated as
reading or as writing.  (The description of each operation should say
which.)
<P>
For more information about the primitive <CODE>read</CODE> and <CODE>write</CODE>
functions, see section <A HREF="library.html#SEC173">Input and Output Primitives</A>.
<P>
<A NAME="IDX1745"></A>
<H2><A NAME="SEC416" HREF="library_toc.html#SEC416">Orphaned Process Groups</A></H2>
<P>
When a controlling process terminates, its terminal becomes free and a
new session can be established on it.  (In fact, another user could log
in on the terminal.)  This could cause a problem if any processes from
the old session are still trying to use that terminal.
<P>
To prevent problems, process groups that continue running even after the
session leader has terminated are marked as <DFN>orphaned process
groups</DFN>.  Processes in an orphaned process group cannot read from or
write to the controlling terminal.  Attempts to do so will fail with an
<CODE>EIO</CODE> error.
<P>
When a process group becomes an orphan, its processes are sent a
<CODE>SIGHUP</CODE> signal.  Ordinarily, this causes the processes to
terminate.  However, if a program ignores this signal or establishes a
handler for it (see section <A HREF="library.html#SEC330">Signal Handling</A>), it can continue running as in
the orphan process group even after its controlling process terminates;
but it still cannot access the terminal any more.
<P>
<H2><A NAME="SEC417" HREF="library_toc.html#SEC417">Implementing a Job Control Shell</A></H2>
<P>
This section describes what a shell must do to implement job control, by
presenting an extensive sample program to illustrate the concepts
involved.
<P>
<UL>
<LI>
section <A HREF="library.html#SEC418">Data Structures for the Shell</A>, introduces the example and presents
its primary data structures.
<P>
<LI>
section <A HREF="library.html#SEC419">Initializing the Shell</A>, discusses actions which the shell must
perform to prepare for job control.
<P>
<LI>
section <A HREF="library.html#SEC420">Launching Jobs</A>, includes information about how to create jobs
to execute commands.
<P>
<LI>
section <A HREF="library.html#SEC421">Foreground and Background</A>, discusses what the shell should
do differently when launching a job in the foreground as opposed to
a background job.
<P>
<LI>
section <A HREF="library.html#SEC422">Stopped and Terminated Jobs</A>, discusses reporting of job status
back to the shell.
<P>
<LI>
section <A HREF="library.html#SEC423">Continuing Stopped Jobs</A>, tells you how to continue jobs that
have been stopped.
<P>
<LI>
section <A HREF="library.html#SEC424">The Missing Pieces</A>, discusses other parts of the shell.
</UL>
<P>
<H3><A NAME="SEC418" HREF="library_toc.html#SEC418">Data Structures for the Shell</A></H3>
<P>
All of the program examples included in this chapter are part of
a simple shell program.  This section presents data structures
and utility functions which are used throughout the example.
<P>
The sample shell deals mainly with two data structures.  The
<CODE>job</CODE> type contains information about a job, which is a
set of subprocesses linked together with pipes.  The <CODE>process</CODE> type
holds information about a single subprocess.  Here are the relevant
data structure declarations:
<P>
<PRE>
/* A process is a single process.  */
typedef struct process
{
  struct process *next;       /* next process in pipeline */
  char **argv;                /* for exec */
  pid_t pid;                  /* process ID */
  char completed;             /* true if process has completed */
  char stopped;               /* true if process has stopped */
  int status;                 /* reported status value */
} process;

/* A job is a pipeline of processes.  */
typedef struct job
{
  struct job *next;           /* next active job */
  char *command;              /* command line, used for messages */
  process *first_process;     /* list of processes in this job */
  pid_t pgid;                 /* process group ID */
  char notified;              /* true if user told about stopped job */
  struct termios tmodes;      /* saved terminal modes */
  int stdin, stdout, stderr;  /* standard i/o channels */
} job;

/* The active jobs are linked into a list.  This is its head.   */
job *first_job = NULL;
</PRE>
<P>
Here are some utility functions that are used for operating on <CODE>job</CODE>
objects.
<P>
<PRE>
/* Find the active job with the indicated <VAR>pgid</VAR>.  */
job *
find_job (pid_t pgid)
{
  job *j;
  
  for (j = first_job; j; j = j-&#62;next)
    if (j-&#62;pgid == pgid)
      return j;
  return NULL;
}

/* Return true if all processes in the job have stopped or completed.  */
int
job_is_stopped (job *j)
{
  process *p;
  
  for (p = j-&#62;first_process; p; p = p-&#62;next)
    if (!p-&#62;completed &#38;&#38; !p-&#62;stopped)
      return 0;
  return 1;
}

/* Return true if all processes in the job have completed.  */
int
job_is_completed (job *j)
{
  process *p;
  
  for (p = j-&#62;first_process; p; p = p-&#62;next)
    if (!p-&#62;completed)
      return 0;
  return 1;
}
</PRE>
<P>
<A NAME="IDX1746"></A>
<A NAME="IDX1747"></A>
<H3><A NAME="SEC419" HREF="library_toc.html#SEC419">Initializing the Shell</A></H3>
<P>
When a shell program that normally performs job control is started, it
has to be careful in case it has been invoked from another shell that is
already doing its own job control.  
<P>
A subshell that runs interactively has to ensure that it has been placed
in the foreground by its parent shell before it can enable job control
itself.  It does this by getting its initial process group ID with the
<CODE>getpgrp</CODE> function, and comparing it to the process group ID of the
current foreground job associated with its controlling terminal (which
can be retrieved using the <CODE>tcgetpgrp</CODE> function).
<P>
If the subshell is not running as a foreground job, it must stop itself
by sending a <CODE>SIGTTIN</CODE> signal to its own process group.  It may not
arbitrarily put itself into the foreground; it must wait for the user to
tell the parent shell to do this.  If the subshell is continued again,
it should repeat the check and stop itself again if it is still not in
the foreground.
<A NAME="IDX1748"></A>
<P>
Once the subshell has been placed into the foreground by its parent
shell, it can enable its own job control.  It does this by calling
<CODE>setpgid</CODE> to put itself into its own process group, and then
calling <CODE>tcsetpgrp</CODE> to place this process group into the
foreground.
<P>
When a shell enables job control, it should set itself to ignore all the
job control stop signals so that it doesn't accidentally stop itself.
You can do this by setting the action for all the stop signals to
<CODE>SIG_IGN</CODE>.
<P>
A subshell that runs non-interactively cannot and should not support job
control.  It must leave all processes it creates in the same process
group as the shell itself; this allows the non-interactive shell and its
child processes to be treated as a single job by the parent shell.  This
is easy to do--just don't use any of the job control primitives--but
you must remember to make the shell do it.
<P>
Here is the initialization code for the sample shell that shows how to
do all of this.
<P>
<PRE>
/* Keep track of attributes of the shell.  */

#include &#60;sys/types.h&#62;
#include &#60;termios.h&#62;
#include &#60;unistd.h&#62;

pid_t shell_pgid;
struct termios shell_tmodes;
int shell_terminal;
int shell_is_interactive;


/* Make sure the shell is running interactively as the foreground job
   before proceeding. */

void
init_shell ()
{
  
  /* See if we are running interactively.  */
  shell_terminal = STDIN_FILENO;
  shell_is_interactive = isatty (shell_terminal);

  if (shell_is_interactive)
    {
      /* Loop until we are in the foreground.  */
      while (tcgetpgrp (shell_terminal) != (shell_pgid = getpgrp ()))
        kill (- shell_pgid, SIGTTIN);

      /* Ignore interactive and job-control signals.  */
      signal (SIGINT, SIG_IGN);
      signal (SIGQUIT, SIG_IGN);
      signal (SIGTSTP, SIG_IGN);
      signal (SIGTTIN, SIG_IGN);
      signal (SIGTTOU, SIG_IGN);
      signal (SIGCHLD, SIG_IGN);

      /* Put ourselves in our own process group.  */
      shell_pgid = getpid ();
      if (setpgid (shell_pgid, shell_pgid) &#60; 0)
        {
          perror ("Couldn't put the shell in its own process group");
          exit (1);
        }

      /* Grab control of the terminal.  */
      tcsetpgrp (shell_terminal, shell_pgid);

      /* Save default terminal attributes for shell.  */
      tcgetattr (shell_terminal, &#38;shell_tmodes);
    }
}
</PRE>
<P>
<A NAME="IDX1749"></A>
<H3><A NAME="SEC420" HREF="library_toc.html#SEC420">Launching Jobs</A></H3>
<P>
Once the shell has taken responsibility for performing job control on
its controlling terminal, it can launch jobs in response to commands
typed by the user.
<P>
To create the processes in a process group, you use the same <CODE>fork</CODE>
and <CODE>exec</CODE> functions described in section <A HREF="library.html#SEC403">Process Creation Concepts</A>.
Since there are multiple child processes involved, though, things are a
little more complicated and you must be careful to do things in the
right order.  Otherwise, nasty race conditions can result.
<P>
You have two choices for how to structure the tree of parent-child
relationships among the processes.  You can either make all the
processes in the process group be children of the shell process, or you
can make one process in group be the ancestor of all the other processes
in that group.  The sample shell program presented in this chapter uses
the first approach because it makes bookkeeping somewhat simpler.
<A NAME="IDX1750"></A>
<A NAME="IDX1751"></A>
<P>
As each process is forked, it should put itself in the new process group
by calling <CODE>setpgid</CODE>; see section <A HREF="library.html#SEC427">Process Group Functions</A>.  The first
process in the new group becomes its <DFN>process group leader</DFN>, and its
process ID becomes the <DFN>process group ID</DFN> for the group.
<A NAME="IDX1752"></A>
<P>
The shell should also call <CODE>setpgid</CODE> to put each of its child
processes into the new process group.  This is because there is a
potential timing problem: each child process must be put in the process
group before it begins executing a new program, and the shell depends on
having all the child processes in the group before it continues
executing.  If both the child processes and the shell call
<CODE>setpgid</CODE>, this ensures that the right things happen no matter which
process gets to it first.
<P>
If the job is being launched as a foreground job, the new process group
also needs to be put into the foreground on the controlling terminal
using <CODE>tcsetpgrp</CODE>.  Again, this should be done by the shell as well
as by each of its child processes, to avoid race conditions.
<P>
The next thing each child process should do is to reset its signal
actions.
<P>
During initialization, the shell process set itself to ignore job
control signals; see section <A HREF="library.html#SEC419">Initializing the Shell</A>.  As a result, any child
processes it creates also ignore these signals by inheritance.  This is
definitely undesirable, so each child process should explicitly set the
actions for these signals back to <CODE>SIG_DFL</CODE> just after it is forked.
<P>
Since shells follow this convention, applications can assume that they
inherit the correct handling of these signals from the parent process.
But every application has a responsibility not to mess up the handling
of stop signals.  Applications that disable the normal interpretation of
the SUSP character should provide some other mechanism for the user to
stop the job.  When the user invokes this mechanism, the program should
send a <CODE>SIGTSTP</CODE> signal to the process group of the process, not
just to the process itself.  See section <A HREF="library.html#SEC365">Signaling Another Process</A>.
<P>
Finally, each child process should call <CODE>exec</CODE> in the normal way.
This is also the point at which redirection of the standard input and 
output channels should be handled.  See section <A HREF="library.html#SEC182">Duplicating Descriptors</A>,
for an explanation of how to do this.
<P>
Here is the function from the sample shell program that is responsible
for launching a program.  The function is executed by each child process
immediately after it has been forked by the shell, and never returns.
<P>
<PRE>
void
launch_process (process *p, pid_t pgid,
                int infile, int outfile, int errfile,
                int foreground)
{
  pid_t pid;

  if (shell_is_interactive)
    {
      /* Put the process into the process group and give the process group
         the terminal, if appropriate.
         This has to be done both by the shell and in the individual
         child processes because of potential race conditions.  */
      pid = getpid ();
      if (pgid == 0) pgid = pid;
      setpgid (pid, pgid);
      if (foreground)
        tcsetpgrp (shell_terminal, pgid);

      /* Set the handling for job control signals back to the default.  */
      signal (SIGINT, SIG_DFL);
      signal (SIGQUIT, SIG_DFL);
      signal (SIGTSTP, SIG_DFL);
      signal (SIGTTIN, SIG_DFL);
      signal (SIGTTOU, SIG_DFL);
      signal (SIGCHLD, SIG_DFL);
    }

  /* Set the standard input/output channels of the new process.  */
  if (infile != STDIN_FILENO)
    {
      dup2 (infile, STDIN_FILENO);
      close (infile);
    }
  if (outfile != STDOUT_FILENO)
    {
      dup2 (outfile, STDOUT_FILENO);
      close (outfile);
    }
  if (errfile != STDERR_FILENO)
    {
      dup2 (errfile, STDERR_FILENO);
      close (errfile);
    }    
  
  /* Exec the new process.  Make sure we exit.  */ 
  execvp (p-&#62;argv[0], p-&#62;argv);
  perror ("execvp");
  exit (1);
}
</PRE>
<P>
If the shell is not running interactively, this function does not do
anything with process groups or signals.  Remember that a shell not
performing job control must keep all of its subprocesses in the same
process group as the shell itself.
<P>
Next, here is the function that actually launches a complete job.
After creating the child processes, this function calls some other
functions to put the newly created job into the foreground or background;
these are discussed in section <A HREF="library.html#SEC421">Foreground and Background</A>.
<P>
<PRE>
void
launch_job (job *j, int foreground)
{
  process *p;
  pid_t pid;
  int mypipe[2], infile, outfile;
  
  infile = j-&#62;stdin;
  for (p = j-&#62;first_process; p; p = p-&#62;next)
    {
      /* Set up pipes, if necessary.  */
      if (p-&#62;next)
        {
          if (pipe (mypipe) &#60; 0)
            {
              perror ("pipe");
              exit (1);
            }
          outfile = mypipe[1];
        }
      else
        outfile = j-&#62;stdout;

      /* Fork the child processes.  */
      pid = fork ();
      if (pid == 0)
        /* This is the child process.  */
        launch_process (p, j-&#62;pgid, infile, outfile, j-&#62;stderr, foreground);
      else if (pid &#60; 0)
        {
          /* The fork failed.  */
          perror ("fork");
          exit (1);
        }
      else
        {
          /* This is the parent process.  */
          p-&#62;pid = pid;
          if (shell_is_interactive)
            {
              if (!j-&#62;pgid)
                j-&#62;pgid = pid;
              setpgid (pid, j-&#62;pgid);
            }
        }

      /* Clean up after pipes.  */
      if (infile != j-&#62;stdin)
        close (infile);
      if (outfile != j-&#62;stdout)
        close (outfile);
      infile = mypipe[0];
    }
  
  format_job_info (j, "launched");

  if (!shell_is_interactive)
    wait_for_job (j);
  else if (foreground)
    put_job_in_foreground (j, 0);
  else
    put_job_in_background (j, 0);
}
</PRE>
<P>
<H3><A NAME="SEC421" HREF="library_toc.html#SEC421">Foreground and Background</A></H3>
<P>
Now let's consider what actions must be taken by the shell when it
launches a job into the foreground, and how this differs from what
must be done when a background job is launched.
<A NAME="IDX1753"></A>
<P>
When a foreground job is launched, the shell must first give it access
to the controlling terminal by calling <CODE>tcsetpgrp</CODE>.  Then, the
shell should wait for processes in that process group to terminate or
stop.  This is discussed in more detail in section <A HREF="library.html#SEC422">Stopped and Terminated Jobs</A>.
<P>
When all of the processes in the group have either completed or stopped,
the shell should regain control of the terminal for its own process
group by calling <CODE>tcsetpgrp</CODE> again.  Since stop signals caused by
I/O from a background process or a SUSP character typed by the user
are sent to the process group, normally all the processes in the job
stop together.
<P>
The foreground job may have left the terminal in a strange state, so the
shell should restore its own saved terminal modes before continuing.  In
case the job is merely been stopped, the shell should first save the
current terminal modes so that it can restore them later if the job is
continued.  The functions for dealing with terminal modes are
<CODE>tcgetattr</CODE> and <CODE>tcsetattr</CODE>; these are described in
section <A HREF="library.html#SEC272">Terminal Modes</A>.
<P>
Here is the sample shell's function for doing all of this.
<P>
<PRE>
/* Put job <VAR>j</VAR> in the foreground.  If <VAR>cont</VAR> is nonzero,
   restore the saved terminal modes and send the process group a
   <CODE>SIGCONT</CODE> signal to wake it up before we block.  */

void
put_job_in_foreground (job *j, int cont)
{
  /* Put the job into the foreground.  */
  tcsetpgrp (shell_terminal, j-&#62;pgid);

  /* Send the job a continue signal, if necessary.  */
  if (cont)
    {
      tcsetattr (shell_terminal, TCSADRAIN, &#38;j-&#62;tmodes);
      if (kill (- j-&#62;pgid, SIGCONT) &#60; 0)
        perror ("kill (SIGCONT)");
    }
  
  /* Wait for it to report.  */
  wait_for_job (j);
    
  /* Put the shell back in the foreground.  */
  tcsetpgrp (shell_terminal, shell_pgid);
    
  /* Restore the shell's terminal modes.  */
  tcgetattr (shell_terminal, &#38;j-&#62;tmodes);
  tcsetattr (shell_terminal, TCSADRAIN, &#38;shell_tmodes);
}
</PRE>
<A NAME="IDX1754"></A>
<P>
If the process group is launched as a background job, the shell should
remain in the foreground itself and continue to read commands from
the terminal.  
<P>
In the sample shell, there is not much that needs to be done to put
a job into the background.  Here is the function it uses:
<P>
<PRE>
/* Put a job in the background.  If the cont argument is true, send
   the process group a <CODE>SIGCONT</CODE> signal to wake it up.  */

void
put_job_in_background (job *j, int cont)
{
  /* Send the job a continue signal, if necessary.  */
  if (cont)
    if (kill (-j-&#62;pgid, SIGCONT) &#60; 0)
      perror ("kill (SIGCONT)");
}
</PRE>
<P>
<H3><A NAME="SEC422" HREF="library_toc.html#SEC422">Stopped and Terminated Jobs</A></H3>
<A NAME="IDX1755"></A>
<A NAME="IDX1756"></A>
<P>
When a foreground process is launched, the shell must block until all of
the processes in that job have either terminated or stopped.  It can do
this by calling the <CODE>waitpid</CODE> function; see section <A HREF="library.html#SEC407">Process Completion</A>.  Use the <CODE>WUNTRACED</CODE> option so that status is reported
for processes that stop as well as processes that terminate.
<P>
The shell must also check on the status of background jobs so that it
can report terminated and stopped jobs to the user; this can be done by
calling <CODE>waitpid</CODE> with the <CODE>WNOHANG</CODE> option.  A good place to
put a such a check for terminated and stopped jobs is just before
prompting for a new command.
<A NAME="IDX1757"></A>
<P>
The shell can also receive asynchronous notification that there is
status information available for a child process by establishing a
handler for <CODE>SIGCHLD</CODE> signals.  See section <A HREF="library.html#SEC330">Signal Handling</A>.
<P>
In the sample shell program, the <CODE>SIGCHLD</CODE> signal is normally
ignored.  This is to avoid reentrancy problems involving the global data
structures the shell manipulates.  But at specific times when the shell
is not using these data structures--such as when it is waiting for
input on the terminal--it makes sense to enable a handler for
<CODE>SIGCHLD</CODE>.  The same function that is used to do the synchronous
status checks (<CODE>do_job_notification</CODE>, in this case) can also be
called from within this handler.
<P>
Here are the parts of the sample shell program that deal with checking
the status of jobs and reporting the information to the user.
<P>
<PRE>
/* Store the status of the process <VAR>pid</VAR> that was returned by waitpid.
   Return 0 if all went well, nonzero otherwise.  */

int
mark_process_status (pid_t pid, int status)
{
  job *j;
  process *p;

  if (pid &#62; 0)
    {
      /* Update the record for the process.  */
      for (j = first_job; j; j = j-&#62;next)
        for (p = j-&#62;first_process; p; p = p-&#62;next)
          if (p-&#62;pid == pid)
            {
              p-&#62;status = status;
              if (WIFSTOPPED (status))
                p-&#62;stopped = 1;
              else
                {
                  p-&#62;completed = 1;
                  if (WIFSIGNALED (status))
                    fprintf (stderr, "%d: Terminated by signal %d.\n",
                             (int) pid, WTERMSIG (p-&#62;status));
                }
              return 0;
             }
      fprintf (stderr, "No child process %d.\n", pid);
      return -1;
    }
  else if (pid == 0 || errno == ECHILD)
    /* No processes ready to report.  */
    return -1;
  else {
    /* Other weird errors.  */
    perror ("waitpid");
    return -1;
  }
}

/* Check for processes that have status information available,
   without blocking.  */

void
update_status (void)
{
  int status;
  pid_t pid;
  
  do
    pid = waitpid (WAIT_ANY, &#38;status, WUNTRACED|WNOHANG);
  while (!mark_process_status (pid, status));
}

/* Check for processes that have status information available,
   blocking until all processes in the given job have reported.  */

void
wait_for_job (job *j)
{
  int status;
  pid_t pid;
  
  do
    pid = waitpid (WAIT_ANY, &#38;status, WUNTRACED);
  while (!mark_process_status (pid, status) 
         &#38;&#38; !job_is_stopped (j) 
         &#38;&#38; !job_is_completed (j));
}

/* Format information about job status for the user to look at.  */

void
format_job_info (job *j, const char *status)
{
  fprintf (stderr, "%ld (%s): %s\n", (long)j-&#62;pgid, status, j-&#62;command);
}

/* Notify the user about stopped or terminated jobs.
   Delete terminated jobs from the active job list.  */

void
do_job_notification (void)
{
  job *j, *jlast, *jnext;
  process *p;

  /* Update status information for child processes.  */
  update_status ();
  
  jlast = NULL;
  for (j = first_job; j; j = jnext)
    {
      jnext = j-&#62;next;

      /* If all processes have completed, tell the user the job has
         completed and delete it from the list of active jobs.  */
      if (job_is_completed (j)) {
        format_job_info (j, "completed");
        if (jlast)
          jlast-&#62;next = jnext;
        else
          first_job = jnext;
        free_job (j);
      }

      /* Notify the user about stopped jobs,
         marking them so that we won't do this more than once.  */
      else if (job_is_stopped (j) &#38;&#38; !j-&#62;notified) {
        format_job_info (j, "stopped");
        j-&#62;notified = 1;
        jlast = j;
      }

      /* Don't say anything about jobs that are still running.  */
      else
        jlast = j;
    }
}
</PRE>
<P>
<H3><A NAME="SEC423" HREF="library_toc.html#SEC423">Continuing Stopped Jobs</A></H3>
<A NAME="IDX1758"></A>
<P>
The shell can continue a stopped job by sending a <CODE>SIGCONT</CODE> signal
to its process group.  If the job is being continued in the foreground,
the shell should first invoke <CODE>tcsetpgrp</CODE> to give the job access to
the terminal, and restore the saved terminal settings.  After continuing
a job in the foreground, the shell should wait for the job to stop or
complete, as if the job had just been launched in the foreground.
<P>
The sample shell program uses the same set of
functions---<CODE>put_job_in_foreground</CODE> and
<CODE>put_job_in_background</CODE>---to handle both newly created and
continued jobs.  The definitions of these functions were given in
section <A HREF="library.html#SEC421">Foreground and Background</A>.  When continuing a stopped job, a
nonzero value is passed as the <VAR>cont</VAR> argument to ensure that the
<CODE>SIGCONT</CODE> signal is sent and the terminal modes reset, as
appropriate.
<P>
This leaves only a function for updating the shell's internal bookkeeping
about the job being continued:
<P>
<PRE>
/* Mark a stopped job J as being running again.  */

void
mark_job_as_running (job *j)
{
  Process *p;

  for (p = j-&#62;first_process; p; p = p-&#62;next)
    p-&#62;stopped = 0;
  j-&#62;notified = 0;
}

/* Continue the job J.  */

void
continue_job (job *j, int foreground)
{
  mark_job_as_running (j);
  if (foreground)
    put_job_in_foreground (j, 1);
  else
    put_job_in_background (j, 1);
}
</PRE>
<P>
<H3><A NAME="SEC424" HREF="library_toc.html#SEC424">The Missing Pieces</A></H3>
<P>
The code extracts for the sample shell included in this chapter are only
a part of the entire shell program.  In particular, nothing at all has
been said about how <CODE>job</CODE> and <CODE>program</CODE> data structures are
allocated and initialized.
<P>
Most real shells provide a complex user interface that has support for
a command language; variables; abbreviations, substitutions, and pattern
matching on file names; and the like.  All of this is far too complicated
to explain here!  Instead, we have concentrated on showing how to 
implement the core process creation and job control functions that can
be called from such a shell.
<P>
Here is a table summarizing the major entry points we have presented:
<P>
<DL COMPACT>
<DT><CODE>void init_shell (void)</CODE>
<DD>Initialize the shell's internal state.  See section <A HREF="library.html#SEC419">Initializing the Shell</A>.
<P>
<DT><CODE>void launch_job (job *<VAR>j</VAR>, int <VAR>foreground</VAR>)</CODE>
<DD>Launch the job <VAR>j</VAR> as either a foreground or background job.
See section <A HREF="library.html#SEC420">Launching Jobs</A>.
<P>
<DT><CODE>void do_job_notification (void)</CODE>
<DD>Check for and report any jobs that have terminated or stopped.  Can be
called synchronously or within a handler for <CODE>SIGCHLD</CODE> signals.
See section <A HREF="library.html#SEC422">Stopped and Terminated Jobs</A>.
<P>
<DT><CODE>void continue_job (job *<VAR>j</VAR>, int <VAR>foreground</VAR>)</CODE>
<DD>Continue the job <VAR>j</VAR>.  See section <A HREF="library.html#SEC423">Continuing Stopped Jobs</A>.
</DL>
<P>
Of course, a real shell would also want to provide other functions for
managing jobs.  For example, it would be useful to have commands to list
all active jobs or to send a signal (such as <CODE>SIGKILL</CODE>) to a job.
<P>
<A NAME="IDX1759"></A>
<A NAME="IDX1760"></A>
<H2><A NAME="SEC425" HREF="library_toc.html#SEC425">Functions for Job Control</A></H2>
<P>
This section contains detailed descriptions of the functions relating
to job control.
<P>
<A NAME="IDX1761"></A>
<H3><A NAME="SEC426" HREF="library_toc.html#SEC426">Identifying the Controlling Terminal</A></H3>
<P>
You can use the <CODE>ctermid</CODE> function to get a file name that you can
use to open the controlling terminal.  In the GNU library, it returns
the same string all the time: <CODE>"/dev/tty"</CODE>.  That is a special
"magic" file name that refers to the controlling terminal of the
current process (if it has one).  The function <CODE>ctermid</CODE> is
declared in the header file <TT>`stdio.h'</TT>.
<A NAME="IDX1762"></A>
<P>
<A NAME="IDX1763"></A>
<U>Function:</U> char * <B>ctermid</B> <I>(char *<VAR>string</VAR>)</I><P>
The <CODE>ctermid</CODE> function returns a string containing the file name of
the controlling terminal for the current process.  If <VAR>string</VAR> is
not a null pointer, it should be an array that can hold at least
<CODE>L_ctermid</CODE> characters; the string is returned in this array.
Otherwise, a pointer to a string in a static area is returned, which
might get overwritten on subsequent calls to this function.
<P>
An empty string is returned if the file name cannot be determined for
any reason.  Even if a file name is returned, access to the file it
represents is not guaranteed.
<P>
<A NAME="IDX1764"></A>
<U>Macro:</U> int <B>L_ctermid</B><P>
The value of this macro is an integer constant expression that
represents the size of a string large enough to hold the file name
returned by <CODE>ctermid</CODE>.
<P>
See also the <CODE>isatty</CODE> and <CODE>ttyname</CODE> functions, in 
section <A HREF="library.html#SEC269">Identifying Terminals</A>.
<P>
<H3><A NAME="SEC427" HREF="library_toc.html#SEC427">Process Group Functions</A></H3>
<P>
Here are descriptions of the functions for manipulating process groups.
Your program should include the header files <TT>`sys/types.h'</TT> and
<TT>`unistd.h'</TT> to use these functions.
<A NAME="IDX1766"></A>
<A NAME="IDX1765"></A>
<P>
<A NAME="IDX1767"></A>
<U>Function:</U> pid_t <B>setsid</B> <I>(void)</I><P>
The <CODE>setsid</CODE> function creates a new session.  The calling process
becomes the session leader, and is put in a new process group whose
process group ID is the same as the process ID of that process.  There
are initially no other processes in the new process group, and no other
process groups in the new session.
<P>
This function also makes the calling process have no controlling terminal.
<P>
The <CODE>setsid</CODE> function returns the new process group ID of the
calling process if successful.  A return value of <CODE>-1</CODE> indicates an
error.  The following <CODE>errno</CODE> error conditions are defined for this
function:
<P>
<DL COMPACT>
<DT><CODE>EPERM</CODE>
<DD>The calling process is already a process group leader, or there is
already another process group around that has the same process group ID.
</DL>
<P>
The <CODE>getpgrp</CODE> function has two definitions: one derived from BSD
Unix, and one from the POSIX.1 standard.  The feature test macros you
have selected (see section <A HREF="library.html#SEC12">Feature Test Macros</A>) determine which definition
you get.  Specifically, you get the BSD version if you define
<CODE>_BSD_SOURCE</CODE>; otherwise, you get the POSIX version if you define
<CODE>_POSIX_SOURCE</CODE> or <CODE>_GNU_SOURCE</CODE>.  Programs written for old
BSD systems will not include <TT>`unistd.h'</TT>, which defines
<CODE>getpgrp</CODE> specially under <CODE>_BSD_SOURCE</CODE>.  You must link such
programs with the <CODE>-lbsd-compat</CODE> option to get the BSD definition.<A NAME="IDX1769"></A>
<A NAME="IDX1770"></A>
<A NAME="IDX1768"></A>
<P>
<A NAME="IDX1771"></A>
<U>POSIX.1 Function:</U> pid_t <B>getpgrp</B> <I>(void)</I><P>
The POSIX.1 definition of <CODE>getpgrp</CODE> returns the process group ID of
the calling process.
<P>
<A NAME="IDX1772"></A>
<U>BSD Function:</U> pid_t <B>getpgrp</B> <I>(pid_t <VAR>pid</VAR>)</I><P>
The BSD definition of <CODE>getpgrp</CODE> returns the process group ID of the
process <VAR>pid</VAR>.  You can supply a value of <CODE>0</CODE> for the <VAR>pid</VAR>
argument to get information about the calling process.
<P>
<A NAME="IDX1773"></A>
<U>Function:</U> int <B>setpgid</B> <I>(pid_t <VAR>pid</VAR>, pid_t <VAR>pgid</VAR>)</I><P>
The <CODE>setpgid</CODE> function puts the process <VAR>pid</VAR> into the process
group <VAR>pgid</VAR>.  As a special case, either <VAR>pid</VAR> or <VAR>pgid</VAR> can
be zero to indicate the process ID of the calling process.
<P>
This function fails on a system that does not support job control.
See section <A HREF="library.html#SEC413">Job Control is Optional</A>, for more information.
<P>
If the operation is successful, <CODE>setpgid</CODE> returns zero.  Otherwise
it returns <CODE>-1</CODE>.  The following <CODE>errno</CODE> error conditions are
defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EACCES</CODE>
<DD>The child process named by <VAR>pid</VAR> has executed an <CODE>exec</CODE>
function since it was forked.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The value of the <VAR>pgid</VAR> is not valid.
<P>
<DT><CODE>ENOSYS</CODE>
<DD>The system doesn't support job control.
<P>
<DT><CODE>EPERM</CODE>
<DD>The process indicated by the <VAR>pid</VAR> argument is a session leader,
or is not in the same session as the calling process, or the value of
the <VAR>pgid</VAR> argument doesn't match a process group ID in the same
session as the calling process.
<P>
<DT><CODE>ESRCH</CODE>
<DD>The process indicated by the <VAR>pid</VAR> argument is not the calling
process or a child of the calling process.
</DL>
<P>
<A NAME="IDX1774"></A>
<U>Function:</U> int <B>setpgrp</B> <I>(pid_t <VAR>pid</VAR>, pid_t <VAR>pgid</VAR>)</I><P>
This is the BSD Unix name for <CODE>setpgid</CODE>.  Both functions do exactly
the same thing.
<P>
<H3><A NAME="SEC428" HREF="library_toc.html#SEC428">Functions for Controlling Terminal Access</A></H3>
<P>
These are the functions for reading or setting the foreground
process group of a terminal.  You should include the header files
<TT>`sys/types.h'</TT> and <TT>`unistd.h'</TT> in your application to use
these functions.
<A NAME="IDX1776"></A>
<A NAME="IDX1775"></A>
<P>
Although these functions take a file descriptor argument to specify
the terminal device, the foreground job is associated with the terminal
file itself and not a particular open file descriptor.
<P>
<A NAME="IDX1777"></A>
<U>Function:</U> pid_t <B>tcgetpgrp</B> <I>(int <VAR>filedes</VAR>)</I><P>
This function returns the process group ID of the foreground process
group associated with the terminal open on descriptor <VAR>filedes</VAR>.
<P>
If there is no foreground process group, the return value is a number
greater than <CODE>1</CODE> that does not match the process group ID of any
existing process group.  This can happen if all of the processes in the
job that was formerly the foreground job have terminated, and no other
job has yet been moved into the foreground.
<P>
In case of an error, a value of <CODE>-1</CODE> is returned.  The
following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>ENOSYS</CODE>
<DD>The system doesn't support job control.
<P>
<DT><CODE>ENOTTY</CODE>
<DD>The terminal file associated with the <VAR>filedes</VAR> argument isn't the
controlling terminal of the calling process.
</DL>
<P>
<A NAME="IDX1778"></A>
<U>Function:</U> int <B>tcsetpgrp</B> <I>(int <VAR>filedes</VAR>, pid_t <VAR>pgid</VAR>)</I><P>
This function is used to set a terminal's foreground process group ID.
The argument <VAR>filedes</VAR> is a descriptor which specifies the terminal;
<VAR>pgid</VAR> specifies the process group.  The calling process must be a
member of the same session as <VAR>pgid</VAR> and must have the same
controlling terminal.
<P>
For terminal access purposes, this function is treated as output.  If it
is called from a background process on its controlling terminal,
normally all processes in the process group are sent a <CODE>SIGTTOU</CODE>
signal.  The exception is if the calling process itself is ignoring or
blocking <CODE>SIGTTOU</CODE> signals, in which case the operation is
performed and no signal is sent.
<P>
If successful, <CODE>tcsetpgrp</CODE> returns <CODE>0</CODE>.  A return value of
<CODE>-1</CODE> indicates an error.  The following <CODE>errno</CODE> error
conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>pgid</VAR> argument is not valid.
<P>
<DT><CODE>ENOSYS</CODE>
<DD>The system doesn't support job control.
<P>
<DT><CODE>ENOTTY</CODE>
<DD>The <VAR>filedes</VAR> isn't the controlling terminal of the calling process.
<P>
<DT><CODE>EPERM</CODE>
<DD>The <VAR>pgid</VAR> isn't a process group in the same session as the calling
process.
</DL>
<P>
<H1><A NAME="SEC429" HREF="library_toc.html#SEC429">Users and Groups</A></H1>
<P>
Every user who can log in on the system is identified by a unique number
called the <DFN>user ID</DFN>.  Each process has an effective user ID which
says which user's access permissions it has.
<P>
Users are classified into <DFN>groups</DFN> for access control purposes.  Each
process has one or more <DFN>group ID values</DFN> which say which groups the
process can use for access to files.
<P>
The effective user and group IDs of a process collectively form its
<DFN>persona</DFN>.  This determines which files the process can access.
Normally, a process inherits its persona from the parent process, but
under special circumstances a process can change its persona and thus
change its access permissions.
<P>
Each file in the system also has a user ID and a group ID.  Access
control works by comparing the user and group IDs of the file with those
of the running process.
<P>
The system keeps a database of all the registered users, and another
database of all the defined groups.  There are library functions you
can use to examine these databases.
<P>
<H2><A NAME="SEC430" HREF="library_toc.html#SEC430">User and Group IDs</A></H2>
<A NAME="IDX1779"></A>
<A NAME="IDX1780"></A>
<A NAME="IDX1781"></A>
<P>
Each user account on a computer system is identified by a <DFN>user
name</DFN> (or <DFN>login name</DFN>) and <DFN>user ID</DFN>.  Normally, each user name
has a unique user ID, but it is possible for several login names to have
the same user ID.  The user names and corresponding user IDs are stored
in a data base which you can access as described in section <A HREF="library.html#SEC441">User Database</A>.
<A NAME="IDX1782"></A>
<A NAME="IDX1783"></A>
<P>
Users are classified in <DFN>groups</DFN>.  Each user name also belongs to
one or more groups, and has one <DFN>default group</DFN>.  Users who are
members of the same group can share resources (such as files) that are
not accessible to users who are not a member of that group.  Each group
has a <DFN>group name</DFN> and <DFN>group ID</DFN>.  See section <A HREF="library.html#SEC446">Group Database</A>,
for how to find information about a group ID or group name.
<P>
<A NAME="IDX1784"></A>
<A NAME="IDX1785"></A>
<A NAME="IDX1786"></A>
<H2><A NAME="SEC431" HREF="library_toc.html#SEC431">The Persona of a Process</A></H2>
<P>
At any time, each process has a single user ID and a group ID which
determine the privileges of the process.  These are collectively called
the <DFN>persona</DFN> of the process, because they determine "who it is"
for purposes of access control.  These IDs are also called the
<DFN>effective user ID</DFN> and <DFN>effective group ID</DFN> of the process.
<P>
Your login shell starts out with a persona which consists of your user
ID and your default group ID.  
In normal circumstances, all your other processes inherit these values.
<A NAME="IDX1787"></A>
<A NAME="IDX1788"></A>
<P>
A process also has a <DFN>real user ID</DFN> which identifies the user who
created the process, and a <DFN>real group ID</DFN> which identifies that
user's default group.  These values do not play a role in access
control, so we do not consider them part of the persona.  But they are
also important.
<P>
Both the real and effective user ID can be changed during the lifetime
of a process.  See section <A HREF="library.html#SEC432">Why Change the Persona of a Process?</A>.
<A NAME="IDX1789"></A>
<P>
In addition, a user can belong to multiple groups, so the persona
includes <DFN>supplementary group IDs</DFN> that also contribute to access
permission.
<P>
For details on how a process's effective user IDs and group IDs affect
its permission to access files, see section <A HREF="library.html#SEC206">How Your Access to a File is Decided</A>.
<P>
The user ID of a process also controls permissions for sending signals
using the <CODE>kill</CODE> function.  See section <A HREF="library.html#SEC365">Signaling Another Process</A>.
<P>
<H2><A NAME="SEC432" HREF="library_toc.html#SEC432">Why Change the Persona of a Process?</A></H2>
<P>
The most obvious situation where it is necessary for a process to change
its user and/or group IDs is the <CODE>login</CODE> program.  When
<CODE>login</CODE> starts running, its user ID is <CODE>root</CODE>.  Its job is to
start a shell whose user and group IDs are those of the user who is
logging in.  (To accomplish this fully, <CODE>login</CODE> must set the real
user and group IDs as well as its persona.  But this is a special case.)
<P>
The more common case of changing persona is when an ordinary user
program needs access to a resource that wouldn't ordinarily be
accessible to the user actually running it.
<P>
For example, you may have a file that is controlled by your program but
that shouldn't be read or modified directly by other users, either
because it implements some kind of locking protocol, or because you want
to preserve the integrity or privacy of the information it contains.
This kind of restricted access can be implemented by having the program
change its effective user or group ID to match that of the resource.
<P>
Thus, imagine a game program that saves scores in a file.  The game
program itself needs to be able to update this file no matter who is
running it, but if users can write the file without going through the
game, they can give themselves any scores they like.  Some people
consider this undesirable, or even reprehensible.  It can be prevented
by creating a new user ID and login name (say, <CODE>games</CODE>) to own the
scores file, and make the file writable only by this user.  Then, when
the game program wants to update this file, it can change its effective
user ID to be that for <CODE>games</CODE>.  In effect, the program must
adopt the persona of <CODE>games</CODE> so it can write the scores file.
<P>
<A NAME="IDX1790"></A>
<H2><A NAME="SEC433" HREF="library_toc.html#SEC433">How an Application Can Change Persona</A></H2>
<P>
The ability to change the persona of a process can be a source of
unintentional privacy violations, or even intentional abuse.  Because of
the potential for problems, changing persona is restricted to special
circumstances.
<P>
You can't arbitrarily set your user ID or group ID to anything you want;
only privileged processes can do that.  Instead, the normal way for a
program to change its persona is that it has been set up in advance to
change to a particular user or group.  This is the function of the setuid
and setgid bits of a file's access mode.  See section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
When the setuid bit of an executable file is set, executing that file
automatically changes the effective user ID to the user that owns the
file.  Likewise, executing a file whose setgid bit is set changes the
effective group ID to the group of the file.  See section <A HREF="library.html#SEC406">Executing a File</A>.
Creating a file that changes to a particular user or group ID thus
requires full access to that user or group ID.
<P>
See section <A HREF="library.html#SEC200">File Attributes</A>, for a more general discussion of file modes and
accessibility.
<P>
A process can always change its effective user (or group) ID back to its
real ID.  Programs do this so as to turn off their special privileges
when they are not needed, which makes for more robustness.
<P>
<H2><A NAME="SEC434" HREF="library_toc.html#SEC434">Reading the Persona of a Process</A></H2>
<P>
Here are detailed descriptions of the functions for reading the user and
group IDs of a process, both real and effective.  To use these
facilities, you must include the header files <TT>`sys/types.h'</TT> and
<TT>`unistd.h'</TT>.
<A NAME="IDX1792"></A>
<A NAME="IDX1791"></A>
<P>
<A NAME="IDX1793"></A>
<U>Data Type:</U> <B>uid_t</B><P>
This is an integer data type used to represent user IDs.  In the GNU
library, this is an alias for <CODE>unsigned int</CODE>.
<P>
<A NAME="IDX1794"></A>
<U>Data Type:</U> <B>gid_t</B><P>
This is an integer data type used to represent group IDs.  In the GNU
library, this is an alias for <CODE>unsigned int</CODE>.
<P>
<A NAME="IDX1795"></A>
<U>Function:</U> uid_t <B>getuid</B> <I>(void)</I><P>
The <CODE>getuid</CODE> function returns the real user ID of the process.
<P>
<A NAME="IDX1796"></A>
<U>Function:</U> gid_t <B>getgid</B> <I>(void)</I><P>
The <CODE>getgid</CODE> function returns the real group ID of the process.
<P>
<A NAME="IDX1797"></A>
<U>Function:</U> uid_t <B>geteuid</B> <I>(void)</I><P>
The <CODE>geteuid</CODE> function returns the effective user ID of the process.
<P>
<A NAME="IDX1798"></A>
<U>Function:</U> gid_t <B>getegid</B> <I>(void)</I><P>
The <CODE>getegid</CODE> function returns the effective group ID of the process.
<P>
<A NAME="IDX1799"></A>
<U>Function:</U> int <B>getgroups</B> <I>(int <VAR>count</VAR>, gid_t *<VAR>groups</VAR>)</I><P>
The <CODE>getgroups</CODE> function is used to inquire about the supplementary
group IDs of the process.  Up to <VAR>count</VAR> of these group IDs are
stored in the array <VAR>groups</VAR>; the return value from the function is
the number of group IDs actually stored.  If <VAR>count</VAR> is smaller than
the total number of supplementary group IDs, then <CODE>getgroups</CODE>
returns a value of <CODE>-1</CODE> and <CODE>errno</CODE> is set to <CODE>EINVAL</CODE>.
<P>
If <VAR>count</VAR> is zero, then <CODE>getgroups</CODE> just returns the total
number of supplementary group IDs.  On systems that do not support
supplementary groups, this will always be zero.
<P>
Here's how to use <CODE>getgroups</CODE> to read all the supplementary group
IDs:
<P>
<PRE>
gid_t *
read_all_groups (void)
{
  int ngroups = getgroups (NULL, 0);
  gid_t *groups = (gid_t *) xmalloc (ngroups * sizeof (gid_t));
  int val = getgroups (ngroups, groups);
  if (val &#60; 0)
    {
      free (groups);
      return NULL;
    }
  return groups;
}
</PRE>
<P>
<H2><A NAME="SEC435" HREF="library_toc.html#SEC435">Setting the User ID</A></H2>
<P>
This section describes the functions for altering the user ID (real
and/or effective) of a process.  To use these facilities, you must
include the header files <TT>`sys/types.h'</TT> and <TT>`unistd.h'</TT>.
<A NAME="IDX1801"></A>
<A NAME="IDX1800"></A>
<P>
<A NAME="IDX1802"></A>
<U>Function:</U> int <B>setuid</B> <I>(uid_t <VAR>newuid</VAR>)</I><P>
This function sets both the real and effective user ID of the process
to <VAR>newuid</VAR>, provided that the process has appropriate privileges.
<P>
If the process is not privileged, then <VAR>newuid</VAR> must either be equal
to the real user ID or the saved user ID (if the system supports the
<CODE>_POSIX_SAVED_IDS</CODE> feature).  In this case, <CODE>setuid</CODE> sets only
the effective user ID and not the real user ID.
<P>
The <CODE>setuid</CODE> function returns a value of <CODE>0</CODE> to indicate
successful completion, and a value of <CODE>-1</CODE> to indicate an error.
The following <CODE>errno</CODE> error conditions are defined for this
function:
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>The value of the <VAR>newuid</VAR> argument is invalid.
<P>
<DT><CODE>EPERM</CODE>
<DD>The process does not have the appropriate privileges; you do not
have permission to change to the specified ID.
</DL>
<P>
<A NAME="IDX1803"></A>
<U>Function:</U> int <B>setreuid</B> <I>(uid_t <VAR>ruid</VAR>, uid_t <VAR>euid</VAR>)</I><P>
This function sets the real user ID of the process to <VAR>ruid</VAR> and
the effective user ID to <VAR>euid</VAR>.
<P>
The <CODE>setreuid</CODE> function exists for compatibility with 4.3 BSD Unix,
which does not support saved IDs.  You can use this function to swap the
effective and real user IDs of the process.  (Privileged processes are
not limited to this particular usage.)  If saved IDs are supported, you
should use that feature instead of this function.  See section <A HREF="library.html#SEC437">Enabling and Disabling Setuid Access</A>.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.
The following <CODE>errno</CODE> error conditions are defined for this
function:
<P>
<DL COMPACT>
<DT><CODE>EPERM</CODE>
<DD>The process does not have the appropriate privileges; you do not
have permission to change to the specified ID.
</DL>
<P>
<H2><A NAME="SEC436" HREF="library_toc.html#SEC436">Setting the Group IDs</A></H2>
<P>
This section describes the functions for altering the group IDs (real
and effective) of a process.  To use these facilities, you must include
the header files <TT>`sys/types.h'</TT> and <TT>`unistd.h'</TT>.
<A NAME="IDX1805"></A>
<A NAME="IDX1804"></A>
<P>
<A NAME="IDX1806"></A>
<U>Function:</U> int <B>setgid</B> <I>(gid_t <VAR>newgid</VAR>)</I><P>
This function sets both the real and effective group ID of the process
to <VAR>newgid</VAR>, provided that the process has appropriate privileges.
<P>
If the process is not privileged, then <VAR>newgid</VAR> must either be equal
to the real group ID or the saved group ID.  In this case, <CODE>setgid</CODE>
sets only the effective group ID and not the real group ID.
<P>
The return values and error conditions for <CODE>setgid</CODE> are the same
as those for <CODE>setuid</CODE>.
<P>
<A NAME="IDX1807"></A>
<U>Function:</U> int <B>setregid</B> <I>(gid_t <VAR>rgid</VAR>, fid_t <VAR>egid</VAR>)</I><P>
This function sets the real group ID of the process to <VAR>rgid</VAR> and
the effective group ID to <VAR>egid</VAR>.
<P>
The <CODE>setregid</CODE> function is provided for compatibility with 4.3 BSD
Unix, which does not support saved IDs.  You can use this function to
swap the effective and real group IDs of the process.  (Privileged
processes are not limited to this usage.)  If saved IDs are supported,
you should use that feature instead of using this function.
See section <A HREF="library.html#SEC437">Enabling and Disabling Setuid Access</A>.
<P>
The return values and error conditions for <CODE>setregid</CODE> are the same
as those for <CODE>setreuid</CODE>.
<P>
The GNU system also lets privileged processes change their supplementary 
group IDs.  To use <CODE>setgroups</CODE> or <CODE>initgroups</CODE>, your programs
should include the header file <TT>`grp.h'</TT>.
<A NAME="IDX1808"></A>
<P>
<A NAME="IDX1809"></A>
<U>Function:</U> int <B>setgroups</B> <I>(size_t <VAR>count</VAR>, gid_t *<VAR>groups</VAR>)</I><P>
This function sets the process's supplementary group IDs.  It can only
be called from privileged processes.  The <VAR>count</VAR> argument specifies
the number of group IDs in the array <VAR>groups</VAR>.
<P>
This function returns <CODE>0</CODE> if successful and <CODE>-1</CODE> on error.
The following <CODE>errno</CODE> error conditions are defined for this
function:
<P>
<DL COMPACT>
<DT><CODE>EPERM</CODE>
<DD>The calling process is not privileged.
</DL>
<P>
<A NAME="IDX1810"></A>
<U>Function:</U> int <B>initgroups</B> <I>(const char *<VAR>user</VAR>, gid_t <VAR>gid</VAR>)</I><P>
The <CODE>initgroups</CODE> function effectively calls <CODE>setgroups</CODE> to
set the process's supplementary group IDs to be the normal default for
the user name <VAR>user</VAR>.  The group ID <VAR>gid</VAR> is also included.
<P>
<H2><A NAME="SEC437" HREF="library_toc.html#SEC437">Enabling and Disabling Setuid Access</A></H2>
<P>
A typical setuid program does not need its special access all of the
time.  It's a good idea to turn off this access when it isn't needed,
so it can't possibly give unintended access.
<P>
If the system supports the saved user ID feature, you can accomplish
this with <CODE>setuid</CODE>.  When the game program starts, its real user ID
is <CODE>jdoe</CODE>, its effective user ID is <CODE>games</CODE>, and its saved
user ID is also <CODE>games</CODE>.  The program should record both user ID
values once at the beginning, like this:
<P>
<PRE>
user_user_id = getuid ();
game_user_id = geteuid ();
</PRE>
<P>
Then it can turn off game file access with 
<P>
<PRE>
setuid (user_user_id);
</PRE>
<P>
and turn it on with 
<P>
<PRE>
setuid (game_user_id);
</PRE>
<P>
Throughout this process, the real user ID remains <CODE>jdoe</CODE> and the
saved user ID remains <CODE>games</CODE>, so the program can always set its
effective user ID to either one.
<P>
On other systems that don't support the saved user ID feature, you can
turn setuid access on and off by using <CODE>setreuid</CODE> to swap the real
and effective user IDs of the process, as follows:
<P>
<PRE>
setreuid (geteuid (), getuid ());
</PRE>
<P>
This special case is always allowed--it cannot fail.
<P>
Why does this have the effect of toggling the setuid access?  Suppose a
game program has just started, and its real user ID is <CODE>jdoe</CODE> while
its effective user ID is <CODE>games</CODE>.  In this state, the game can
write the scores file.  If it swaps the two uids, the real becomes
<CODE>games</CODE> and the effective becomes <CODE>jdoe</CODE>; now the program has
only <CODE>jdoe</CODE> access.  Another swap brings <CODE>games</CODE> back to
the effective user ID and restores access to the scores file.
<P>
In order to handle both kinds of systems, test for the saved user ID
feature with a preprocessor conditional, like this:
<P>
<PRE>
#ifdef _POSIX_SAVED_IDS
  setuid (user_user_id);
#else
  setreuid (geteuid (), getuid ());
#endif
</PRE>
<P>
<H2><A NAME="SEC438" HREF="library_toc.html#SEC438">Setuid Program Example</A></H2>
<P>
Here's an example showing how to set up a program that changes its
effective user ID.
<P>
This is part of a game program called <CODE>caber-toss</CODE> that
manipulates a file <TT>`scores'</TT> that should be writable only by the game
program itself.  The program assumes that its executable
file will be installed with the set-user-ID bit set and owned by the
same user as the <TT>`scores'</TT> file.  Typically, a system
administrator will set up an account like <CODE>games</CODE> for this purpose.
<P>
The executable file is given mode <CODE>4755</CODE>, so that doing an 
<SAMP>`ls -l'</SAMP> on it produces output like:
<P>
<PRE>
-rwsr-xr-x   1 games    184422 Jul 30 15:17 caber-toss
</PRE>
<P>
The set-user-ID bit shows up in the file modes as the <SAMP>`s'</SAMP>.
<P>
The scores file is given mode <CODE>644</CODE>, and doing an <SAMP>`ls -l'</SAMP> on
it shows:
<P>
<PRE>
-rw-r--r--  1 games           0 Jul 31 15:33 scores
</PRE>
<P>
Here are the parts of the program that show how to set up the changed
user ID.  This program is conditionalized so that it makes use of the
saved IDs feature if it is supported, and otherwise uses <CODE>setreuid</CODE>
to swap the effective and real user IDs.
<P>
<PRE>
#include &#60;stdio.h&#62;
#include &#60;sys/types.h&#62;
#include &#60;unistd.h&#62;
#include &#60;stdlib.h&#62;


/* Save the effective and real UIDs. */

static uid_t euid, ruid;


/* Restore the effective UID to its original value. */

void
do_setuid (void)
{
  int status;

#ifdef _POSIX_SAVED_IDS
  status = setuid (euid);
#else
  status = setreuid (ruid, euid);
#endif
  if (status &#60; 0) {
    fprintf (stderr, "Couldn't set uid.\n");
    exit (status);
    }
}


/* Set the effective UID to the real UID. */

void
undo_setuid (void)
{
  int status;

#ifdef _POSIX_SAVED_IDS
  status = setuid (ruid);
#else
  status = setreuid (euid, ruid);
#endif
  if (status &#60; 0) {
    fprintf (stderr, "Couldn't set uid.\n");
    exit (status);
    }
}

/* Main program. */

int
main (void)
{
  /* Save the real and effective user IDs.  */
  ruid = getuid ();
  euid = geteuid ();
  undo_setuid ();

  /* Do the game and record the score.  */
  ...
}
</PRE>
<P>
Notice how the first thing the <CODE>main</CODE> function does is to set the
effective user ID back to the real user ID.  This is so that any other
file accesses that are performed while the user is playing the game use
the real user ID for determining permissions.  Only when the program
needs to open the scores file does it switch back to the original
effective user ID, like this:
<P>
<PRE>
/* Record the score. */

int
record_score (int score)
{
  FILE *stream;
  char *myname;

  /* Open the scores file. */
  do_setuid ();
  stream = fopen (SCORES_FILE, "a");
  undo_setuid ();

  /* Write the score to the file. */
  if (stream)
    {
      myname = cuserid (NULL);
      if (score &#60; 0)
        fprintf (stream, "%10s: Couldn't lift the caber.\n", myname);
      else
        fprintf (stream, "%10s: %d feet.\n", myname, score);
      fclose (stream);
      return 0;
    }
  else
    return -1;
}
</PRE>
<P>
<H2><A NAME="SEC439" HREF="library_toc.html#SEC439">Tips for Writing Setuid Programs</A></H2>
<P>
It is easy for setuid programs to give the user access that isn't 
intended--in fact, if you want to avoid this, you need to be careful.
Here are some guidelines for preventing unintended access and
minimizing its consequences when it does occur:
<P>
<UL>
<LI>
Don't have <CODE>setuid</CODE> programs with privileged user IDs such as
<CODE>root</CODE> unless it is absolutely necessary.  If the resource is
specific to your particular program, it's better to define a new,
nonprivileged user ID or group ID just to manage that resource.
<P>
<LI>
Be cautious about using the <CODE>system</CODE> and <CODE>exec</CODE> functions in
combination with changing the effective user ID.  Don't let users of
your program execute arbitrary programs under a changed user ID.
Executing a shell is especially bad news.  Less obviously, the
<CODE>execlp</CODE> and <CODE>execvp</CODE> functions are a potential risk (since
the program they execute depends on the user's <CODE>PATH</CODE> environment
variable).
<P>
If you must <CODE>exec</CODE> another program under a changed ID, specify an
absolute file name (see section <A HREF="library.html#SEC114">File Name Resolution</A>) for the executable,
and make sure that the protections on that executable and <EM>all</EM>
containing directories are such that ordinary users cannot replace it
with some other program.
<P>
<LI>
Only use the user ID controlling the resource in the part of the program
that actually uses that resource.  When you're finished with it, restore
the effective user ID back to the actual user's user ID.
See section <A HREF="library.html#SEC437">Enabling and Disabling Setuid Access</A>.
<P>
<LI>
If the <CODE>setuid</CODE> part of your program needs to access other files
besides the controlled resource, it should verify that the real user
would ordinarily have permission to access those files.  You can use the
<CODE>access</CODE> function (see section <A HREF="library.html#SEC206">How Your Access to a File is Decided</A>) to check this; it
uses the real user and group IDs, rather than the effective IDs.
</UL>
<P>
<A NAME="IDX1811"></A>
<A NAME="IDX1812"></A>
<H2><A NAME="SEC440" HREF="library_toc.html#SEC440">Identifying Who Logged In</A></H2>
<P>
You can use the functions listed in this section to determine the login
name of the user who is running a process, and the name of the user who
logged in the current session.  See also the function <CODE>getuid</CODE> and
friends (see section <A HREF="library.html#SEC434">Reading the Persona of a Process</A>).
<P>
The <CODE>getlogin</CODE> function is declared in <TT>`unistd.h'</TT>, while
<CODE>cuserid</CODE> and <CODE>L_cuserid</CODE> are declared in <TT>`stdio.h'</TT>.
<A NAME="IDX1814"></A>
<A NAME="IDX1813"></A>
<P>
<A NAME="IDX1815"></A>
<U>Function:</U> char * <B>getlogin</B> <I>(void)</I><P>
The <CODE>getlogin</CODE> function returns a pointer to a string containing the
name of the user logged in on the controlling terminal of the process,
or a null pointer if this information cannot be determined.  The string
is statically allocated and might be overwritten on subsequent calls to
this function or to <CODE>cuserid</CODE>.
<P>
<A NAME="IDX1816"></A>
<U>Function:</U> char * <B>cuserid</B> <I>(char *<VAR>string</VAR>)</I><P>
The <CODE>cuserid</CODE> function returns a pointer to a string containing a
user name associated with the effective ID of the process.  If
<VAR>string</VAR> is not a null pointer, it should be an array that can hold
at least <CODE>L_cuserid</CODE> characters; the string is returned in this
array.  Otherwise, a pointer to a string in a static area is returned.
This string is statically allocated and might be overwritten on
subsequent calls to this function or to <CODE>getlogin</CODE>.
<P>
<A NAME="IDX1817"></A>
<U>Macro:</U> int <B>L_cuserid</B><P>
An integer constant that indicates how long an array you might need to
store a user name.
<P>
These functions let your program identify positively the user who is
running or the user who logged in this session.  (These can differ when
setuid programs are involved; See section <A HREF="library.html#SEC431">The Persona of a Process</A>.)  The user cannot
do anything to fool these functions.
<P>
For most purposes, it is more useful to use the environment variable
<CODE>LOGNAME</CODE> to find out who the user is.  This is more flexible
precisely because the user can set <CODE>LOGNAME</CODE> arbitrarily.
See section <A HREF="library.html#SEC394">Standard Environment Variables</A>.
<P>
<A NAME="IDX1818"></A>
<A NAME="IDX1819"></A>
<A NAME="IDX1820"></A>
<H2><A NAME="SEC441" HREF="library_toc.html#SEC441">User Database</A></H2>
<P>
This section describes all about now to search and scan the database of
registered users.  The database itself is kept in the file
<TT>`/etc/passwd'</TT> on most systems, but on some systems a special
network server gives access to it.
<P>
<H3><A NAME="SEC442" HREF="library_toc.html#SEC442">The Data Structure that Describes a User</A></H3>
<P>
The functions and data structures for accessing the system user database
are declared in the header file <TT>`pwd.h'</TT>.
<A NAME="IDX1821"></A>
<P>
<A NAME="IDX1822"></A>
<U>Data Type:</U> <B>struct passwd</B><P>
The <CODE>passwd</CODE> data structure is used to hold information about 
entries in the system user data base.  It has at least the following members:
<P>
<DL COMPACT>
<DT><CODE>char *pw_name</CODE>
<DD>The user's login name.
<P>
<DT><CODE>char *pw_passwd.</CODE>
<DD>The encrypted password string.
<P>
<DT><CODE>uid_t pw_uid</CODE>
<DD>The user ID number.
<P>
<DT><CODE>gid_t pw_gid</CODE>
<DD>The user's default group ID number.
<P>
<DT><CODE>char *pw_gecos</CODE>
<DD>A string typically containing the user's real name, and possibly other
information such as a phone number.
<P>
<DT><CODE>char *pw_dir</CODE>
<DD>The user's home directory, or initial working directory.  This might be
a null pointer, in which case the interpretation is system-dependent.
<P>
<DT><CODE>char *pw_shell</CODE>
<DD>The user's default shell, or the initial program run when the user logs in.
This might be a null pointer, indicating that the system default should
be used.
</DL>
<P>
<A NAME="IDX1823"></A>
<A NAME="IDX1824"></A>
<H3><A NAME="SEC443" HREF="library_toc.html#SEC443">Looking Up One User</A></H3>
<P>
You can search the system user database for information about a
specific user using <CODE>getpwuid</CODE> or <CODE>getpwnam</CODE>.  These
functions are declared in <TT>`pwd.h'</TT>.
<P>
<A NAME="IDX1825"></A>
<U>Function:</U> struct passwd * <B>getpwuid</B> <I>(uid_t <VAR>uid</VAR>)</I><P>
This function returns a pointer to a statically-allocated structure
containing information about the user whose user ID is <VAR>uid</VAR>.  This
structure may be overwritten on subsequent calls to <CODE>getpwuid</CODE>.
<P>
A null pointer value indicates there is no user in the data base with
user ID <VAR>uid</VAR>.
<P>
<A NAME="IDX1826"></A>
<U>Function:</U> struct passwd * <B>getpwnam</B> <I>(const char *<VAR>name</VAR>)</I><P>
This function returns a pointer to a statically-allocated structure
containing information about the user whose user name is <VAR>name</VAR>.
This structure may be overwritten on subsequent calls to
<CODE>getpwnam</CODE>.
<P>
A null pointer value indicates there is no user named <VAR>name</VAR>.
<P>
<A NAME="IDX1827"></A>
<H3><A NAME="SEC444" HREF="library_toc.html#SEC444">Scanning the List of All Users</A></H3>
<P>
This section explains how a program can read the list of all users in
the system, one user at a time.  The functions described here are
declared in <TT>`pwd.h'</TT>.
<P>
The recommended way to scan the users is to open the user file and
then call <CODE>fgetpwent</CODE> for each successive user:
<P>
<A NAME="IDX1828"></A>
<U>Function:</U> struct passwd * <B>fgetpwent</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
This function reads the next user entry from <VAR>stream</VAR> and returns a
pointer to the entry.  The structure is statically allocated and is
rewritten on subsequent calls to <CODE>getpwent</CODE>.  You must copy the
contents of the structure if you wish to save the information.
<P>
This stream must correspond to a file in the same format as the standard
password database file.  This function comes from System V.
<P>
Another way to scan all the entries in the group database is with
<CODE>setpwent</CODE>, <CODE>getpwent</CODE>, and <CODE>endpwent</CODE>.  But this method
is less robust than <CODE>fgetpwent</CODE>, so we provide it only for
compatibility with SVID.  In particular, these functions are not
reentrant and are not suitable for use in programs with multiple threads
of control.
<P>
<A NAME="IDX1829"></A>
<U>Function:</U> void <B>setpwent</B> <I>(void)</I><P>
This function initializes a stream which <CODE>getpwent</CODE> uses to read
the user database.
<P>
<A NAME="IDX1830"></A>
<U>Function:</U> struct passwd * <B>getpwent</B> <I>(void)</I><P>
The <CODE>getpwent</CODE> function reads the next entry from the stream
initialized by <CODE>setpwent</CODE>.  It returns a pointer to the entry.  The
structure is statically allocated and is rewritten on subsequent calls
to <CODE>getpwent</CODE>.  You must copy the contents of the structure if you
wish to save the information.
<P>
<A NAME="IDX1831"></A>
<U>Function:</U> void <B>endpwent</B> <I>(void)</I><P>
This function closes the internal stream used by <CODE>getpwent</CODE>.
<P>
<H3><A NAME="SEC445" HREF="library_toc.html#SEC445">Writing a User Entry</A></H3>
<P>
<A NAME="IDX1832"></A>
<U>Function:</U> int <B>putpwent</B> <I>(const struct passwd *<VAR>p</VAR>, FILE *<VAR>stream</VAR>)</I><P>
This function writes the user entry <CODE>*<VAR>p</VAR></CODE> to the stream
<VAR>stream</VAR>, in the format used for the standard user database
file.  The return value is zero on success and nonzero on failure.
<P>
This function exists for compatibility with SVID.  We recommend that you
avoid using it, because it makes sense only on the assumption that the
<CODE>struct passwd</CODE> structure has no members except the standard ones;
on a system which merges the traditional Unix data base with other
extended information about users, adding an entry using this function
would inevitably leave out much of the important information.
<P>
The function <CODE>putpwent</CODE> is declared in <TT>`pwd.h'</TT>.
<P>
<A NAME="IDX1833"></A>
<A NAME="IDX1834"></A>
<H2><A NAME="SEC446" HREF="library_toc.html#SEC446">Group Database</A></H2>
<P>
This section describes all about how to search and scan the database of
registered groups.  The database itself is kept in the file
<TT>`/etc/group'</TT> on most systems, but on some systems a special network
service provides access to it.
<P>
<H3><A NAME="SEC447" HREF="library_toc.html#SEC447">The Data Structure for a Group</A></H3>
<P>
The functions and data structures for accessing the system group
database are declared in the header file <TT>`grp.h'</TT>.
<A NAME="IDX1835"></A>
<P>
<A NAME="IDX1836"></A>
<U>Data Type:</U> <B>struct group</B><P>
The <CODE>group</CODE> structure is used to hold information about an entry in
the system group database.  It has at least the following members:
<P>
<DL COMPACT>
<DT><CODE>char *gr_name</CODE>
<DD>The name of the group.
<P>
<DT><CODE>gid_t gr_gid</CODE>
<DD>The group ID of the group.
<P>
<DT><CODE>char **gr_mem</CODE>
<DD>A vector of pointers to the names of users in the group.  Each user name
is a null-terminated string, and the vector itself is terminated by a
null pointer.
</DL>
<P>
<A NAME="IDX1837"></A>
<A NAME="IDX1838"></A>
<H3><A NAME="SEC448" HREF="library_toc.html#SEC448">Looking Up One Group</A></H3>
<P>
You can search the group database for information about a specific
group using <CODE>getgrgid</CODE> or <CODE>getgrnam</CODE>.  These functions are
declared in <TT>`grp.h'</TT>.
<P>
<A NAME="IDX1839"></A>
<U>Function:</U> struct group * <B>getgrgid</B> <I>(gid_t <VAR>gid</VAR>)</I><P>
This function returns a pointer to a statically-allocated structure
containing information about the group whose group ID is <VAR>gid</VAR>.
This structure may be overwritten by subsequent calls to
<CODE>getgrgid</CODE>.
<P>
A null pointer indicates there is no group with ID <VAR>gid</VAR>.
<P>
<A NAME="IDX1840"></A>
<U>Function:</U> struct group * <B>getgrnam</B> <I>(const char *<VAR>name</VAR>)</I><P>
This function returns a pointer to a statically-allocated structure
containing information about the group whose group name is <VAR>name</VAR>.
This structure may be overwritten by subsequent calls to
<CODE>getgrnam</CODE>.
<P>
A null pointer indicates there is no group named <VAR>name</VAR>.
<P>
<A NAME="IDX1841"></A>
<H3><A NAME="SEC449" HREF="library_toc.html#SEC449">Scanning the List of All Groups</A></H3>
<P>
This section explains how a program can read the list of all groups in
the system, one group at a time.  The functions described here are
declared in <TT>`grp.h'</TT>.
<P>
The recommended way to scan the groups is to open the group file and
then call <CODE>fgetgrent</CODE> for each successive group:
<P>
<A NAME="IDX1842"></A>
<U>Function:</U> struct group * <B>fgetgrent</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
The <CODE>fgetgrent</CODE> function reads the next entry from <VAR>stream</VAR>.
It returns a pointer to the entry.  The structure is statically
allocated and is rewritten on subsequent calls to <CODE>getgrent</CODE>.  You
must copy the contents of the structure if you wish to save the
information.
<P>
The stream must correspond to a file in the same format as the standard
group database file.
<P>
Another way to scan all the entries in the group database is with
<CODE>setgrent</CODE>, <CODE>getgrent</CODE>, and <CODE>endgrent</CODE>.  But this method
is less robust than <CODE>fgetgrent</CODE>, so we provide it only for
compatibility with SVID.  In particular, these functions are not
reentrant and are not suitable for use in programs with multiple threads
of control.
<P>
<A NAME="IDX1843"></A>
<U>Function:</U> void <B>setgrent</B> <I>(void)</I><P>
This function initializes a stream for reading from the group data base.
You use this stream by calling <CODE>getgrent</CODE>.
<P>
<A NAME="IDX1844"></A>
<U>Function:</U> struct group * <B>getgrent</B> <I>(void)</I><P>
The <CODE>getgrent</CODE> function reads the next entry from the stream
initialized by <CODE>setgrent</CODE>.  It returns a pointer to the entry.  The
structure is statically allocated and is rewritten on subsequent calls
to <CODE>getgrent</CODE>.  You must copy the contents of the structure if you
wish to save the information.
<P>
<A NAME="IDX1845"></A>
<U>Function:</U> void <B>endgrent</B> <I>(void)</I><P>
This function closes the internal stream used by <CODE>getgrent</CODE>.
<P>
<H2><A NAME="SEC450" HREF="library_toc.html#SEC450">User and Group Database Example</A></H2>
<P>
Here is an example program showing the use of the system database inquiry
functions.  The program prints some information about the user running
the program.
<P>
<PRE>
#include &#60;grp.h&#62;
#include &#60;pwd.h&#62;
#include &#60;sys/types.h&#62;
#include &#60;unistd.h&#62;
#include &#60;stdlib.h&#62;

int
main (void)
{
  uid_t me;
  struct passwd *my_passwd;
  struct group *my_group;
  char **members;

  /* Get information about the user ID.  */
  me = getuid ();
  my_passwd = getpwuid (me);
  if (!my_passwd)
    {
      printf ("Couldn't find out about user %d.\n", (int) me);
      exit (EXIT_FAILURE);
    }

  /* Print the information.  */
  printf ("I am %s.\n", my_passwd-&#62;pw_gecos);
  printf ("My login name is %s.\n", my_passwd-&#62;pw_name);
  printf ("My uid is %d.\n", (int) (my_passwd-&#62;pw_uid));
  printf ("My home directory is %s.\n", my_passwd-&#62;pw_dir);
  printf ("My default shell is %s.\n", my_passwd-&#62;pw_shell);

  /* Get information about the default group ID.  */
  my_group = getgrgid (my_passwd-&#62;pw_gid);
  if (!my_group)
    {
      printf ("Couldn't find out about group %d.\n", (int) my_passwd-&#62;pw_gid);
      exit (EXIT_FAILURE);
    }

  /* Print the information.  */
  printf ("My default group is %s (%d).\n",
	  my_group-&#62;gr_name, (int) (my_passwd-&#62;pw_gid));
  printf ("The members of this group are:\n");
  members = my_group-&#62;gr_mem;
  while (*members)
    {
      printf ("  %s\n", *(members));
      members++;
    }

  return EXIT_SUCCESS;
}
</PRE>
<P>
Here is some output from this program:
<P>
<PRE>
I am Throckmorton Snurd.
My login name is snurd.
My uid is 31093.
My home directory is /home/fsg/snurd.
My default shell is /bin/sh.
My default group is guest (12).
The members of this group are:
  friedman
  tami
</PRE>
<H1><A NAME="SEC451" HREF="library_toc.html#SEC451">System Information</A></H1>
<P>
This chapter describes functions that return information about the
particular machine that is in use--the type of hardware, the type of
software, and the individual machine's name.
<P>
<H2><A NAME="SEC452" HREF="library_toc.html#SEC452">Host Identification</A></H2>
<P>
This section explains how to identify the particular machine that your
program is running on.  The identification of a machine consists of its
Internet host name and Internet address; see section <A HREF="library.html#SEC227">The Internet Namespace</A>.  
<A NAME="IDX1846"></A>
<A NAME="IDX1847"></A>
<A NAME="IDX1848"></A>
<P>
Prototypes for these functions appear in <TT>`unistd.h'</TT>.  The shell
commands <CODE>hostname</CODE> and <CODE>hostid</CODE> work by calling them.
<P>
<A NAME="IDX1849"></A>
<U>Function:</U> int <B>gethostname</B> <I>(char *<VAR>name</VAR>, size_t <VAR>size</VAR>)</I><P>
This function returns the name of the host machine in the array
<VAR>name</VAR>.  The <VAR>size</VAR> argument specifies the size of this array,
in bytes.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  In
the GNU C library, <CODE>gethostname</CODE> fails if <VAR>size</VAR> is not large
enough; then you can try again with a larger array.  The following
<CODE>errno</CODE> error condition is defined for this function:
<P>
<DL COMPACT>
<DT><CODE>ENAMETOOLONG</CODE>
<DD>The <VAR>size</VAR> argument is less than the size of the host name plus one.
</DL>
<A NAME="IDX1850"></A>
<P>
On some systems, there is a symbol for the maximum possible host name
length: <CODE>MAXHOSTNAMELEN</CODE>.  It is defined in <TT>`sys/param.h'</TT>.
But you can't count on this to exist, so it is cleaner to handle
failure and try again.
<P>
<CODE>gethostname</CODE> stores the beginning of the host name in <VAR>name</VAR>
even if the host name won't entirely fit.  For some purposes, a
truncated host name is good enough.  If it is, you can ignore the
error code.
<P>
<A NAME="IDX1851"></A>
<U>Function:</U> int <B>sethostname</B> <I>(const char *<VAR>name</VAR>, size_t <VAR>length</VAR>)</I><P>
The <CODE>sethostname</CODE> function sets the name of the host machine to
<VAR>name</VAR>, a string with length <VAR>length</VAR>.  Only privileged
processes are allowed to do this.  Usually it happens just once, at
system boot time.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.
The following <CODE>errno</CODE> error condition is defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EPERM</CODE>
<DD>This process cannot set the host name because it is not privileged.
</DL>
<P>
<A NAME="IDX1852"></A>
<U>Function:</U> long int <B>gethostid</B> <I>(void)</I><P>
This function returns the Internet address of the machine the program is
running on.
<P>
<A NAME="IDX1853"></A>
<U>Function:</U> int <B>sethostid</B> <I>(long int <VAR>id</VAR>)</I><P>
The <CODE>sethostid</CODE> function sets the address of the host machine to
<VAR>id</VAR>.  Only privileged processes are allowed to do this.  Usually it
happens just once, at system boot time.
<P>
The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.
The following <CODE>errno</CODE> error condition is defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EPERM</CODE>
<DD>This process cannot set the host name because it is not privileged.
</DL>
<P>
<H2><A NAME="SEC453" HREF="library_toc.html#SEC453">Hardware/Software Type Identification</A></H2>
<P>
You can use the <CODE>uname</CODE> function to find out some information about
the type of computer your program is running on.  This function and the
associated data type are declared in the header file
<TT>`sys/utsname.h'</TT>.
<A NAME="IDX1854"></A>
<P>
<A NAME="IDX1855"></A>
<U>Data Type:</U> <B>struct utsname</B><P>
The <CODE>utsname</CODE> structure is used to hold information returned
by the <CODE>uname</CODE> function.  It has the following members:
<P>
<DL COMPACT>
<DT><CODE>char sysname[]</CODE>
<DD>This is the name of the operating system in use.
<P>
<DT><CODE>char nodename[]</CODE>
<DD>This is the network name of this particular computer.  In the GNU
library, the value is the same as that returned by <CODE>gethostname</CODE>;
see section <A HREF="library.html#SEC452">Host Identification</A>.
<P>
<DT><CODE>char release[]</CODE>
<DD>This is the current release level of the operating system implementation.
<P>
<DT><CODE>char version[]</CODE>
<DD>This is the current version level within the release of the operating
system.
<P>
<DT><CODE>char machine[]</CODE>
<DD>This is a description of the type of hardware that is in use.
<P>
The GNU C Library fills in this field based on the configuration name
that was specified when building and installing the library.  GNU uses a
three-part name to describe a system configuration; the three parts are
<VAR>cpu</VAR>, <VAR>manufacturer</VAR> and <VAR>system-type</VAR>, and they are
separated with dashes.  Any possible combination of three names is
potentially meaningful, but most such combinations are meaningless in
practice and even the meaningful ones are not necessarily supported by
any particular GNU program.
<P>
Since the value in <CODE>machine</CODE> is supposed to describe just the
hardware, it consists of the first two parts of the configuration name:
<SAMP>`<VAR>cpu</VAR>-<VAR>manufacturer</VAR>'</SAMP>.
<P>
Here is a list of all the possible alternatives:
<P>
<BLOCKQUOTE>
<CODE>"i386-<VAR>anything</VAR>"</CODE>, <CODE>"m68k-hp"</CODE>, <CODE>"sparc-sun"</CODE>,
<CODE>"m68k-sun"</CODE>, <CODE>"m68k-sony"</CODE>, <CODE>"mips-dec"</CODE>
</BLOCKQUOTE>
</DL>
<P>
<A NAME="IDX1856"></A>
<U>Function:</U> int <B>uname</B> <I>(struct utsname *<VAR>info</VAR>)</I><P>
The <CODE>uname</CODE> function fills in the structure pointed to by
<VAR>info</VAR> with information about the operating system and host machine.
A non-negative value indicates that the data was successfully stored.
<P>
<CODE>-1</CODE> as the value indicates an error.  The only error possible is
<CODE>EFAULT</CODE>, which we normally don't mention as it is always a
possibility.
<P>
<H1><A NAME="SEC454" HREF="library_toc.html#SEC454">System Configuration Parameters</A></H1>
<P>
The functions and macros listed in this chapter give information about
configuration parameters of the operating system--for example, capacity
limits, presence of optional POSIX features, and the default path for
executable files (see section <A HREF="library.html#SEC469">String-Valued Parameters</A>).
<P>
<A NAME="IDX1857"></A>
<A NAME="IDX1858"></A>
<A NAME="IDX1859"></A>
<H2><A NAME="SEC455" HREF="library_toc.html#SEC455">General Capacity Limits</A></H2>
<P>
The POSIX.1 and POSIX.2 standards specify a number of parameters that
describe capacity limitations of the system.  These limits can be fixed
constants for a given operating system, or they can vary from machine to
machine.  For example, some limit values may be configurable by the
system administrator, either at run time or by rebuilding the kernel,
and this should not require recompiling application programs.
<A NAME="IDX1860"></A>
<P>
Each of the following limit parameters has a macro that is defined in
<TT>`limits.h'</TT> only if the system has a fixed, uniform limit for the
parameter in question.  If the system allows different file systems or
files to have different limits, then the macro is undefined; use
<CODE>sysconf</CODE> to find out the limit that applies at a particular time
on a particular machine.  See section <A HREF="library.html#SEC458">Using <CODE>sysconf</CODE></A>.
<P>
Each of these parameters also has another macro, with a name starting
with <SAMP>`_POSIX'</SAMP>, which gives the lowest value that the limit is
allowed to have on <EM>any</EM> POSIX system.  See section <A HREF="library.html#SEC462">Minimum Values for General Capacity Limits</A>.
<A NAME="IDX1861"></A>
<P>
<A NAME="IDX1862"></A>
<U>Macro:</U> int <B>ARG_MAX</B><P>
If defined, the unvarying maximum combined length of the <VAR>argv</VAR> and
<VAR>environ</VAR> arguments that can be passed to the <CODE>exec</CODE> functions.
<P>
<A NAME="IDX1863"></A>
<P>
<A NAME="IDX1864"></A>
<U>Macro:</U> int <B>CHILD_MAX</B><P>
If defined, the unvarying maximum number of processes that can exist
with the same real user ID at any one time.
<P>
<A NAME="IDX1865"></A>
<P>
<A NAME="IDX1866"></A>
<U>Macro:</U> int <B>OPEN_MAX</B><P>
If defined, the unvarying maximum number of files that a single process
can have open simultaneously.
<P>
<A NAME="IDX1867"></A>
<U>Macro:</U> int <B>STREAM_MAX</B><P>
If defined, the unvarying maximum number of streams that a single
process can have open simultaneously.  See section <A HREF="library.html#SEC120">Opening Streams</A>.
<P>
<A NAME="IDX1868"></A>
<P>
<A NAME="IDX1869"></A>
<U>Macro:</U> int <B>TZNAME_MAX</B><P>
If defined, the unvarying maximum length of a time zone name.
See section <A HREF="library.html#SEC319">Functions and Variables for Time Zones</A>.
<P>
These limit macros are always defined in <TT>`limits.h'</TT>.
<A NAME="IDX1870"></A>
<P>
<A NAME="IDX1871"></A>
<U>Macro:</U> int <B>NGROUPS_MAX</B><P>
The maximum number of supplementary group IDs that one process can have.
<P>
The value of this macro is actually a lower bound for the maximum.  That
is, you can count on being able to have that many supplementary group
IDs, but a particular machine might let you have even more.  You can use
<CODE>sysconf</CODE> to see whether a particular machine will let you have
more (see section <A HREF="library.html#SEC458">Using <CODE>sysconf</CODE></A>).
<P>
<A NAME="IDX1872"></A>
<U>Macro:</U> int <B>SSIZE_MAX</B><P>
The largest value that can fit in an object of type <CODE>ssize_t</CODE>.
Effectively, this is the limit on the number of bytes that can be read
or written in a single operation.
<P>
This macro is defined in all POSIX systems because this limit is never
configurable.
<P>
<A NAME="IDX1873"></A>
<U>Macro:</U> int <B>RE_DUP_MAX</B><P>
The largest number of repetitions you are guaranteed is allowed in the
construct <SAMP>`\{<VAR>min</VAR>,<VAR>max</VAR>\}'</SAMP> in a regular expression.
<P>
The value of this macro is actually a lower bound for the maximum.  That
is, you can count on being able to have that many supplementary group
IDs, but a particular machine might let you have even more.  You can use
<CODE>sysconf</CODE> to see whether a particular machine will let you have
more (see section <A HREF="library.html#SEC458">Using <CODE>sysconf</CODE></A>).  And even the value that <CODE>sysconf</CODE> tells
you is just a lower bound--larger values might work.
<P>
This macro is defined in all POSIX.2 systems, because POSIX.2 says it
should always be defined even if there is no specific imposed limit.
<P>
<A NAME="IDX1874"></A>
<A NAME="IDX1875"></A>
<H2><A NAME="SEC456" HREF="library_toc.html#SEC456">Overall System Options</A></H2>
<P>
POSIX defines certain system-specific options that not all POSIX systems
support.  Since these options are provided in the kernel, not in the
library, simply using the GNU C library does not guarantee any of these
features is supported; it depends on the system you are using.
<A NAME="IDX1876"></A>
<P>
You can test for the availability of a given option using the macros in
this section, together with the function <CODE>sysconf</CODE>.  The macros are
defined only if you include <TT>`unistd.h'</TT>.
<P>
For the following macros, if the macro is defined in <TT>`unistd.h'</TT>,
then the option is supported.  Otherwise, the option may or may not be
supported; use <CODE>sysconf</CODE> to find out.  See section <A HREF="library.html#SEC458">Using <CODE>sysconf</CODE></A>.
<P>
<A NAME="IDX1877"></A>
<U>Macro:</U> int <B>_POSIX_JOB_CONTROL</B><P>
If this symbol is defined, it indicates that the system supports job
control.  Otherwise, the implementation behaves as if all processes
within a session belong to a single process group.  See section <A HREF="library.html#SEC411">Job Control</A>.
<P>
<A NAME="IDX1878"></A>
<U>Macro:</U> int <B>_POSIX_SAVED_IDS</B><P>
If this symbol is defined, it indicates that the system remembers the
effective user and group IDs of a process before it executes an
executable file with the set-user-ID or set-group-ID bits set, and that
explicitly changing the effective user or group IDs back to these values
is permitted.  If this option is not defined, then if a nonprivileged
process changes its effective user or group ID to the real user or group
ID of the process, it can't change it back again.  See section <A HREF="library.html#SEC437">Enabling and Disabling Setuid Access</A>.
<P>
For the following macros, if the macro is defined in <TT>`unistd.h'</TT>,
then its value indicates whether the option is supported.  A value of
<CODE>-1</CODE> means no, and any other value means yes.  If the macro is not
defined, then the option may or may not be supported; use <CODE>sysconf</CODE>
to find out.  See section <A HREF="library.html#SEC458">Using <CODE>sysconf</CODE></A>.
<P>
<A NAME="IDX1879"></A>
<U>Macro:</U> int <B>_POSIX2_C_DEV</B><P>
If this symbol is defined, it indicates that the system has the POSIX.2
C compiler command, <CODE>c89</CODE>.  The GNU C library always defines this
as <CODE>1</CODE>, on the assumption that you would not have installed it if
you didn't have a C compiler.
<P>
<A NAME="IDX1880"></A>
<U>Macro:</U> int <B>_POSIX2_FORT_DEV</B><P>
If this symbol is defined, it indicates that the system has the POSIX.2
Fortran compiler command, <CODE>fort77</CODE>.  The GNU C library never
defines this, because we don't know what the system has.
<P>
<A NAME="IDX1881"></A>
<U>Macro:</U> int <B>_POSIX2_FORT_RUN</B><P>
If this symbol is defined, it indicates that the system has the POSIX.2
<CODE>asa</CODE> command to interpret Fortran carriage control.  The GNU C
library never defines this, because we don't know what the system has.
<P>
<A NAME="IDX1882"></A>
<U>Macro:</U> int <B>_POSIX2_LOCALEDEF</B><P>
If this symbol is defined, it indicates that the system has the POSIX.2
<CODE>localedef</CODE> command.  The GNU C library never defines this, because
we don't know what the system has.
<P>
<A NAME="IDX1883"></A>
<U>Macro:</U> int <B>_POSIX2_SW_DEV</B><P>
If this symbol is defined, it indicates that the system has the POSIX.2
commands <CODE>ar</CODE>, <CODE>make</CODE>, and <CODE>strip</CODE>.  The GNU C library
always defines this as <CODE>1</CODE>, on the assumption that you had to have
<CODE>ar</CODE> and <CODE>make</CODE> to install the library, and it's unlikely that
<CODE>strip</CODE> would be absent when those are present.
<P>
<H2><A NAME="SEC457" HREF="library_toc.html#SEC457">Which Version of POSIX is Supported</A></H2>
<P>
<A NAME="IDX1884"></A>
<U>Macro:</U> long int <B>_POSIX_VERSION</B><P>
This constant represents the version of the POSIX.1 standard to which
the implementation conforms.  For an implementation conforming to the
1990 POSIX.1 standard, the value is the integer <CODE>199009L</CODE>.
<P>
<CODE>_POSIX_VERSION</CODE> is always defined (in <TT>`unistd.h'</TT>) in any
POSIX system.
<P>
<STRONG>Usage Note:</STRONG> Don't try to test whether the system supports POSIX
by including <TT>`unistd.h'</TT> and then checking whether
<CODE>_POSIX_VERSION</CODE> is defined.  On a non-POSIX system, this will
probably fail because there is no <TT>`unistd.h'</TT>.  We do not know of
<EM>any</EM> way you can reliably test at compilation time whether your
target system supports POSIX or whether <TT>`unistd.h'</TT> exists.
<P>
The GNU C compiler predefines the symbol <CODE>__POSIX__</CODE> if the target
system is a POSIX system.  Provided you do not use any other compilers
on POSIX systems, testing <CODE>defined (__POSIX__)</CODE> will reliably
detect such systems.
<P>
<A NAME="IDX1885"></A>
<U>Macro:</U> long int <B>_POSIX2_C_VERSION</B><P>
This constant represents the version of the POSIX.2 standard which the
library and system kernel support.  We don't know what value this will
be for the first version of the POSIX.2 standard, because the value is
based on the year and month in which the standard is officially adopted.
<P>
The value of this symbol says nothing about the utilities installed on
the system.
<P>
<STRONG>Usage Note:</STRONG> You can use this macro to tell whether a POSIX.1
system library supports POSIX.2 as well.  Any POSIX.1 system contains
<TT>`unistd.h'</TT>, so include that file and then test <CODE>defined
(_POSIX2_C_VERSION)</CODE>.
<P>
<H2><A NAME="SEC458" HREF="library_toc.html#SEC458">Using <CODE>sysconf</CODE></A></H2>
<P>
When your system has configurable system limits, you can use the
<CODE>sysconf</CODE> function to find out the value that applies to any
particular machine.  The function and the associated <VAR>parameter</VAR>
constants are declared in the header file <TT>`unistd.h'</TT>.
<P>
<H3><A NAME="SEC459" HREF="library_toc.html#SEC459">Definition of <CODE>sysconf</CODE></A></H3>
<P>
<A NAME="IDX1886"></A>
<U>Function:</U> long int <B>sysconf</B> <I>(int <VAR>parameter</VAR>)</I><P>
This function is used to inquire about runtime system parameters.  The
<VAR>parameter</VAR> argument should be one of the <SAMP>`_SC_'</SAMP> symbols listed
below.
<P>
The normal return value from <CODE>sysconf</CODE> is the value you requested.
A value of <CODE>-1</CODE> is returned both if the implementation does not
impose a limit, and in case of an error.  
<P>
The following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>The value of the <VAR>parameter</VAR> is invalid.
</DL>
<P>
<H3><A NAME="SEC460" HREF="library_toc.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A></H3>
<P>
Here are the symbolic constants for use as the <VAR>parameter</VAR> argument
to <CODE>sysconf</CODE>.  The values are all integer constants (more
specifically, enumeration type values).
<P>
<DL COMPACT>
<DT><CODE>_SC_ARG_MAX</CODE>
<DD>Inquire about the parameter corresponding to <CODE>ARG_MAX</CODE>.
<P>
<DT><CODE>_SC_CHILD_MAX</CODE>
<DD>Inquire about the parameter corresponding to <CODE>CHILD_MAX</CODE>.
<P>
<DT><CODE>_SC_OPEN_MAX</CODE>
<DD>Inquire about the parameter corresponding to <CODE>OPEN_MAX</CODE>.
<P>
<DT><CODE>_SC_STREAM_MAX</CODE>
<DD>Inquire about the parameter corresponding to <CODE>STREAM_MAX</CODE>.
<P>
<DT><CODE>_SC_TZNAME_MAX</CODE>
<DD>Inquire about the parameter corresponding to <CODE>TZNAME_MAX</CODE>.
<P>
<DT><CODE>_SC_NGROUPS_MAX</CODE>
<DD>Inquire about the parameter corresponding to <CODE>NGROUPS_MAX</CODE>.
<P>
<DT><CODE>_SC_JOB_CONTROL</CODE>
<DD>Inquire about the parameter corresponding to <CODE>_POSIX_JOB_CONTROL</CODE>.
<P>
<DT><CODE>_SC_SAVED_IDS</CODE>
<DD>Inquire about the parameter corresponding to <CODE>_POSIX_SAVED_IDS</CODE>.
<P>
<DT><CODE>_SC_VERSION</CODE>
<DD>Inquire about the parameter corresponding to <CODE>_POSIX_VERSION</CODE>.
<P>
<DT><CODE>_SC_CLK_TCK</CODE>
<DD>Inquire about the parameter corresponding to <CODE>CLOCKS_PER_SEC</CODE>;
see section <A HREF="library.html#SEC311">Basic CPU Time Inquiry</A>.
<P>
<DT><CODE>_SC_2_C_DEV</CODE>
<DD>Inquire about whether the system has the POSIX.2 C compiler command,
<CODE>c89</CODE>.
<P>
<DT><CODE>_SC_2_FORT_DEV</CODE>
<DD>Inquire about whether the system has the POSIX.2 Fortran compiler
command, <CODE>fort77</CODE>.
<P>
<DT><CODE>_SC_2_FORT_RUN</CODE>
<DD>Inquire about whether the system has the POSIX.2 <CODE>asa</CODE> command to
interpret Fortran carriage control.
<P>
<DT><CODE>_SC_2_LOCALEDEF</CODE>
<DD>Inquire about whether the system has the POSIX.2 <CODE>localedef</CODE>
command.
<P>
<DT><CODE>_SC_2_SW_DEV</CODE>
<DD>Inquire about whether the system has the POSIX.2 commands <CODE>ar</CODE>,
<CODE>make</CODE>, and <CODE>strip</CODE>.
<P>
<DT><CODE>_SC_BC_BASE_MAX</CODE>
<DD>Inquire about the maximum value of <CODE>obase</CODE> in the <CODE>bc</CODE>
utility.
<P>
<DT><CODE>_SC_BC_DIM_MAX</CODE>
<DD>Inquire about the maximum size of an array in the <CODE>bc</CODE>
utility.
<P>
<DT><CODE>_SC_BC_SCALE_MAX</CODE>
<DD>Inquire about the maximum value of <CODE>scale</CODE> in the <CODE>bc</CODE>
utility.
<P>
<DT><CODE>_SC_BC_STRING_MAX</CODE>
<DD>Inquire about the maximum size of a string constant in the
<CODE>bc</CODE> utility.
<P>
<DT><CODE>_SC_COLL_WEIGHTS_MAX</CODE>
<DD>Inquire about the maximum number of weights that can necessarily
be used in defining the collating sequence for a locale.
<P>
<DT><CODE>_SC_EXPR_NEST_MAX</CODE>
<DD>Inquire about the maximum number of expressions nested within
parentheses when using the <CODE>expr</CODE> utility.
<P>
<DT><CODE>_SC_LINE_MAX</CODE>
<DD>Inquire about the maximum size of a text line that the POSIX.2 text
utilities can handle.
<P>
<DT><CODE>_SC_VERSION</CODE>
<DD>Inquire about the version number of POSIX.1 that the library and kernel
support.
<P>
<DT><CODE>_SC_2_VERSION</CODE>
<DD>Inquire about the version number of POSIX.2 that the system utilities
support.
</DL>
<P>
<H3><A NAME="SEC461" HREF="library_toc.html#SEC461">Examples of <CODE>sysconf</CODE></A></H3>
<P>
We recommend that you first test for a macro definition for the
parameter you are interested in, and call <CODE>sysconf</CODE> only if the
macro is not defined.  For example, here is how to test whether job
control is supported:
<P>
<PRE>
int
have_job_control (void)
{
#ifdef _POSIX_JOB_CONTROL
  return 1;
#else
  int value = sysconf (_SC_JOB_CONTROL);
  if (value &#60; 0)
    /* If the system is that badly wedged,
       there's no use trying to go on.  */
    fatal (strerror (errno));
  return value;
#endif
}
</PRE>
<P>
Here is how to get the value of a numeric limit:
<P>
<PRE>
int
get_child_max ()
{
#ifdef CHILD_MAX
  return CHILD_MAX;
#else
  int value = sysconf (_SC_CHILD_MAX);
  if (value &#60; 0)
    fatal (strerror (errno));
  return value;
#endif
}
</PRE>
<P>
<H2><A NAME="SEC462" HREF="library_toc.html#SEC462">Minimum Values for General Capacity Limits</A></H2>
<P>
Here are the names for the POSIX minimum upper bounds for the system
limit parameters.  The significance of these values is that you can
safely push to these limits without checking whether the particular
system you are using can go that far.
<P>
<DL COMPACT>
<DT><CODE>_POSIX_ARG_MAX</CODE>
<DD>The value of this macro is the most restrictive limit permitted by POSIX
for the maximum combined length of the <VAR>argv</VAR> and <VAR>environ</VAR>
arguments that can be passed to the <CODE>exec</CODE> functions.
Its value is <CODE>4096</CODE>.
<P>
<DT><CODE>_POSIX_CHILD_MAX</CODE>
<DD>The value of this macro is the most restrictive limit permitted by POSIX
for the maximum number of simultaneous processes per real user ID.  Its
value is <CODE>6</CODE>.
<P>
<DT><CODE>_POSIX_NGROUPS_MAX</CODE>
<DD>The value of this macro is the most restrictive limit permitted by POSIX
for the maximum number of supplementary group IDs per process.  Its
value is <CODE>0</CODE>.
<P>
<DT><CODE>_POSIX_OPEN_MAX</CODE>
<DD>The value of this macro is the most restrictive limit permitted by POSIX
for the maximum number of files that a single process can have open
simultaneously.  Its value is <CODE>16</CODE>.
<P>
<DT><CODE>_POSIX_SSIZE_MAX</CODE>
<DD>The value of this macro is the most restrictive limit permitted by POSIX
for the maximum value that can be stored in an object of type
<CODE>ssize_t</CODE>.  Its value is <CODE>32767</CODE>.
<P>
<DT><CODE>_POSIX_STREAM_MAX</CODE>
<DD>The value of this macro is the most restrictive limit permitted by POSIX
for the maximum number of streams that a single process can have open
simultaneously.  Its value is <CODE>8</CODE>.
<P>
<DT><CODE>_POSIX_TZNAME_MAX</CODE>
<DD>The value of this macro is the most restrictive limit permitted by POSIX
for the maximum length of a time zone name.  Its value is <CODE>3</CODE>.
<P>
<DT><CODE>_POSIX2_RE_DUP_MAX</CODE>
<DD>The value of this macro is the most restrictive limit permitted by POSIX
for the numbers used in the <SAMP>`\{<VAR>min</VAR>,<VAR>max</VAR>\}'</SAMP> construct
in a regular expression.  Its value is <CODE>255</CODE>.
</DL>
<P>
<H2><A NAME="SEC463" HREF="library_toc.html#SEC463">Limits on File System Capacity</A></H2>
<P>
The POSIX.1 standard specifies a number of parameters that describe the
limitations of the file system.  It's possible for the system to have a
fixed, uniform limit for a parameter, but this isn't the usual case.  On
most systems, it's possible for different file systems (and, for some
parameters, even different files) to have different maximum limits.  For
example, this is very likely if you use NFS to mount some of the file
systems from other machines.
<A NAME="IDX1887"></A>
<P>
Each of the following macros is defined in <TT>`limits.h'</TT> only if the
system has a fixed, uniform limit for the parameter in question.  If the
system allows different file systems or files to have different limits,
then the macro is undefined; use <CODE>pathconf</CODE> or <CODE>fpathconf</CODE> to
find out the limit that applies to a particular file.  See section <A HREF="library.html#SEC466">Using <CODE>pathconf</CODE></A>.
<P>
Each parameter also has another macro, with a name starting with
<SAMP>`_POSIX'</SAMP>, which gives the lowest value that the limit is allowed to
have on <EM>any</EM> POSIX system.  See section <A HREF="library.html#SEC465">Minimum Values for File System Limits</A>.
<A NAME="IDX1888"></A>
<P>
<A NAME="IDX1889"></A>
<U>Macro:</U> int <B>LINK_MAX</B><P>
The uniform system limit (if any) for the number of names for a given
file.  See section <A HREF="library.html#SEC195">Hard Links</A>.
<P>
<A NAME="IDX1890"></A>
<P>
<A NAME="IDX1891"></A>
<U>Macro:</U> int <B>MAX_CANON</B><P>
The uniform system limit (if any) for the amount of text in a line of
input when input editing is enabled.  See section <A HREF="library.html#SEC271">Two Styles of Input: Canonical or Not</A>.
<P>
<A NAME="IDX1892"></A>
<U>Macro:</U> int <B>MAX_INPUT</B><P>
The uniform system limit (if any) for the total number of characters
typed ahead as input.  See section <A HREF="library.html#SEC270">I/O Queues</A>.
<P>
<A NAME="IDX1893"></A>
<P>
<A NAME="IDX1894"></A>
<U>Macro:</U> int <B>NAME_MAX</B><P>
The uniform system limit (if any) for the length of a file name component.
<P>
<A NAME="IDX1895"></A>
<U>Macro:</U> int <B>PATH_MAX</B><P>
The uniform system limit (if any) for the length of an entire file name (that
is, the argument given to system calls such as <CODE>open</CODE>).
<P>
<A NAME="IDX1896"></A>
<P>
<A NAME="IDX1897"></A>
<U>Macro:</U> int <B>PIPE_BUF</B><P>
The uniform system limit (if any) for the number of bytes that can be
written atomically to a pipe.  If multiple processes are writing to the
same pipe simultaneously, output from different processes might be
interleaved in chunks of this size.  See section <A HREF="library.html#SEC211">Pipes and FIFOs</A>.
<P>
These are alternative macro names for some of the same information.
<P>
<A NAME="IDX1898"></A>
<U>Macro:</U> int <B>MAXNAMLEN</B><P>
This is the BSD name for <CODE>NAME_MAX</CODE>.  It is defined in
<TT>`dirent.h'</TT>.
<P>
<A NAME="IDX1899"></A>
<U>Macro:</U> int <B>FILENAME_MAX</B><P>
The value of this macro is an integer constant expression that
represents the maximum length of a file name string.  It is defined in
<TT>`stdio.h'</TT>.
<P>
Unlike <CODE>PATH_MAX</CODE>, this macro is defined even if there is no actual
limit imposed.  In such a case, its value is typically a very large
number.  <STRONG>This is always the case on the GNU system.</STRONG>
<P>
<STRONG>Usage Note:</STRONG> Don't use <CODE>FILENAME_MAX</CODE> as the size of an
array in which to store a file name!  You can't possibly make an array
that big!  Use dynamic allocation (see section <A HREF="library.html#SEC18">Memory Allocation</A>) instead.
<P>
<H2><A NAME="SEC464" HREF="library_toc.html#SEC464">Optional Features in File Support</A></H2>
<P>
POSIX defines certain system-specific options in the system calls for
operating on files.  Some systems support these options and others do
not.  Since these options are provided in the kernel, not in the
library, simply using the GNU C library does not guarantee any of these
features is supported; it depends on the system you are using.  They can
also vary between file systems on a single machine.
<A NAME="IDX1900"></A>
<P>
This section describes the macros you can test to determine whether a
particular option is supported on your machine.  If a given macro is
defined in <TT>`unistd.h'</TT>, then its value says whether the
corresponding feature is supported.  (A value of <CODE>-1</CODE> indicates no;
any other value indicates yes.)  If the macro is undefined, it means
particular files may or may not support the feature.
<P>
Since all the machines that support the GNU C library also support NFS,
one can never make a general statement about whether all file systems
support the <CODE>_POSIX_CHOWN_RESTRICTED</CODE> and <CODE>_POSIX_NO_TRUNC</CODE>
features.  So these names are never defined as macros in the GNU C
library.
<P>
<A NAME="IDX1901"></A>
<U>Macro:</U> int <B>_POSIX_CHOWN_RESTRICTED</B><P>
If this option is in effect, the <CODE>chown</CODE> function is restricted so
that the only changes permitted to nonprivileged processes is to change 
the group owner of a file to either be the effective group ID of the
process, or one of its supplementary group IDs.  See section <A HREF="library.html#SEC204">File Owner</A>.
<P>
<A NAME="IDX1902"></A>
<U>Macro:</U> int <B>_POSIX_NO_TRUNC</B><P>
If this option is in effect, file name components longer than
<CODE>NAME_MAX</CODE> generate an <CODE>ENAMETOOLONG</CODE> error.  Otherwise, file
name components that are too long are silently truncated.
<P>
<A NAME="IDX1903"></A>
<U>Macro:</U> unsigned char <B>_POSIX_VDISABLE</B><P>
This option is only meaningful for files that are terminal devices.
If it is enabled, then handling for special control characters can
be disabled individually.  See section <A HREF="library.html#SEC281">Special Characters</A>.
<P>
<A NAME="IDX1904"></A>
<P>
If one of these macros is undefined, that means that the option might be
in effect for some files and not for others.  To inquire about a
particular file, call <CODE>pathconf</CODE> or <CODE>fpathconf</CODE>.
See section <A HREF="library.html#SEC466">Using <CODE>pathconf</CODE></A>.
<P>
<H2><A NAME="SEC465" HREF="library_toc.html#SEC465">Minimum Values for File System Limits</A></H2>
<P>
Here are the names for the POSIX minimum upper bounds for some of the
above parameters.  The significance of these values is that you can
safely push to these limits without checking whether the particular
system you are using can go that far.
<P>
<DL COMPACT>
<DT><CODE>_POSIX_LINK_MAX</CODE>
<DD>The most restrictive limit permitted by POSIX for the maximum value of a
file's link count.  The value of this constant is <CODE>8</CODE>; thus, you
can always make up to eight names for a file without running into a
system limit.
<P>
<DT><CODE>_POSIX_MAX_CANON</CODE>
<DD>The most restrictive limit permitted by POSIX for the maximum number of
bytes in a canonical input line from a terminal device.  The value of
this constant is <CODE>255</CODE>.
<P>
<DT><CODE>_POSIX_MAX_INPUT</CODE>
<DD>The most restrictive limit permitted by POSIX for the maximum number of
bytes in a terminal device input queue (or typeahead buffer).
See section <A HREF="library.html#SEC276">Input Modes</A>.  The value of this constant is <CODE>255</CODE>.
<P>
<DT><CODE>_POSIX_NAME_MAX</CODE>
<DD>The most restrictive limit permitted by POSIX for the maximum number of
bytes in a file name component.  The value of this constant is
<CODE>14</CODE>.
<P>
<DT><CODE>_POSIX_PATH_MAX</CODE>
<DD>The most restrictive limit permitted by POSIX for the maximum number of
bytes in a file name.  The value of this constant is <CODE>255</CODE>.
<P>
<DT><CODE>_POSIX_PIPE_BUF</CODE>
<DD>The most restrictive limit permitted by POSIX for the maximum number of
bytes that can be written atomically to a pipe.  The value of this
constant is <CODE>512</CODE>.
</DL>
<P>
<H2><A NAME="SEC466" HREF="library_toc.html#SEC466">Using <CODE>pathconf</CODE></A></H2>
<P>
When your machine allows different files to have different values for a
file system parameter, you can use the functions in this section to find
out the value that applies to any particular file.
<P>
These functions and the associated constants for the <VAR>parameter</VAR>
argument are declared in the header file <TT>`unistd.h'</TT>.
<P>
<A NAME="IDX1905"></A>
<U>Function:</U> long int <B>pathconf</B> <I>(const char *<VAR>filename</VAR>, int <VAR>parameter</VAR>)</I><P>
This function is used to inquire about the limits that apply to
the file named <VAR>filename</VAR>.
<P>
The <VAR>parameter</VAR> argument should be one of the <SAMP>`_PC_'</SAMP> constants
listed below.
<P>
The normal return value from <CODE>pathconf</CODE> is the value you requested.
A value of <CODE>-1</CODE> is returned both if the implementation does not
impose a limit, and in case of an error.  In the former case,
<CODE>errno</CODE> is not set, while in the latter case, <CODE>errno</CODE> is set
to indicate the cause of the problem.  So the only way to use this
function robustly is to store <CODE>0</CODE> into <CODE>errno</CODE> just before
calling it.
<P>
Besides the usual file name syntax errors (see section <A HREF="library.html#SEC115">File Name Errors</A>),
the following error condition is defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>The value of <VAR>parameter</VAR> is invalid, or the implementation doesn't
support the <VAR>parameter</VAR> for the specific file.
</DL>
<P>
<A NAME="IDX1906"></A>
<U>Function:</U> long int <B>fpathconf</B> <I>(int <VAR>filedes</VAR>, int <VAR>parameter</VAR>)</I><P>
This is just like <CODE>pathconf</CODE> except that an open file descriptor
is used to specify the file for which information is requested, instead
of a file name.
<P>
The following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The value of <VAR>parameter</VAR> is invalid, or the implementation doesn't
support the <VAR>parameter</VAR> for the specific file.
</DL>
<P>
Here are the symbolic constants that you can use as the <VAR>parameter</VAR>
argument to <CODE>pathconf</CODE> and <CODE>fpathconf</CODE>.  The values are all
integer constants.
<P>
<DL COMPACT>
<DT><CODE>_PC_LINK_MAX</CODE>
<DD>Inquire about the parameter corresponding to <CODE>LINK_MAX</CODE>.
<P>
<DT><CODE>_PC_MAX_CANON</CODE>
<DD>Inquire about the parameter corresponding to <CODE>MAX_CANON</CODE>.
<P>
<DT><CODE>_PC_MAX_INPUT</CODE>
<DD>Inquire about the parameter corresponding to <CODE>MAX_INPUT</CODE>.
<P>
<DT><CODE>_PC_NAME_MAX</CODE>
<DD>Inquire about the parameter corresponding to <CODE>NAME_MAX</CODE>.
<P>
<DT><CODE>_PC_PATH_MAX</CODE>
<DD>Inquire about the parameter corresponding to <CODE>PATH_MAX</CODE>.
<P>
<DT><CODE>_PC_PIPE_BUF</CODE>
<DD>Inquire about the parameter corresponding to <CODE>PIPE_BUF</CODE>.
<P>
<DT><CODE>_PC_CHOWN_RESTRICTED</CODE>
<DD>Inquire about the parameter corresponding to <CODE>_POSIX_CHOWN_RESTRICTED</CODE>.
<P>
<DT><CODE>_PC_NO_TRUNC</CODE>
<DD>Inquire about the parameter corresponding to <CODE>_POSIX_NO_TRUNC</CODE>.
<P>
<DT><CODE>_PC_VDISABLE</CODE>
<DD>Inquire about the parameter corresponding to <CODE>_POSIX_VDISABLE</CODE>.
</DL>
<P>
<H2><A NAME="SEC467" HREF="library_toc.html#SEC467">Utility Program Capacity Limits</A></H2>
<P>
The POSIX.2 standard specifies certain system limits that you can access
through <CODE>sysconf</CODE> that apply to utility behavior rather than the
behavior of the library or the operating system.
<P>
The GNU C library defines macros for these limits, and <CODE>sysconf</CODE>
returns values for them if you ask; but these values convey no
meaningful information.  They are simply the smallest values that
POSIX.2 permits.
<P>
<A NAME="IDX1907"></A>
<U>Macro:</U> int <B>BC_BASE_MAX</B><P>
The largest value of <CODE>obase</CODE> that the <CODE>bc</CODE> utility is
guaranteed to support.
<P>
<A NAME="IDX1908"></A>
<U>Macro:</U> int <B>BC_SCALE_MAX</B><P>
The largest value of <CODE>scale</CODE> that the <CODE>bc</CODE> utility is
guaranteed to support.
<P>
<A NAME="IDX1909"></A>
<U>Macro:</U> int <B>BC_DIM_MAX</B><P>
The largest number of elements in one array that the <CODE>bc</CODE> utility
is guaranteed to support.
<P>
<A NAME="IDX1910"></A>
<U>Macro:</U> int <B>BC_STRING_MAX</B><P>
The largest number of characters in one string constant that the
<CODE>bc</CODE> utility is guaranteed to support.
<P>
<A NAME="IDX1911"></A>
<U>Macro:</U> int <B>BC_DIM_MAX</B><P>
The largest number of elements in one array that the <CODE>bc</CODE> utility
is guaranteed to support.
<P>
<A NAME="IDX1912"></A>
<U>Macro:</U> int <B>COLL_WEIGHTS_MAX</B><P>
The largest number of weights that can necessarily be used in defining
the collating sequence for a locale.
<P>
<A NAME="IDX1913"></A>
<U>Macro:</U> int <B>EXPR_NEST_MAX</B><P>
The maximum number of expressions that can be nested within parenthesis
by the <CODE>expr</CODE> utility.
<P>
<A NAME="IDX1914"></A>
<U>Macro:</U> int <B>LINE_MAX</B><P>
The largest text line that the text-oriented POSIX.2 utilities can
support.  (If you are using the GNU versions of these utilities, then
there is no actual limit except that imposed by the available virtual
memory, but there is no way that the library can tell you this.)
<P>
<H2><A NAME="SEC468" HREF="library_toc.html#SEC468">Minimum Values for Utility Limits</A></H2>
<P>
<DL COMPACT>
<DT><CODE>_POSIX2_BC_BASE_MAX</CODE>
<DD>The most restrictive limit permitted by POSIX.2 for the maximum value of
<CODE>obase</CODE> in the <CODE>bc</CODE> utility.  Its value is <CODE>99</CODE>.
<P>
<DT><CODE>_POSIX2_BC_DIM_MAX</CODE>
<DD>The most restrictive limit permitted by POSIX.2 for the maximum size of
an array in the <CODE>bc</CODE> utility.  Its value is <CODE>2048</CODE>.
<P>
<DT><CODE>_POSIX2_BC_SCALE_MAX</CODE>
<DD>The most restrictive limit permitted by POSIX.2 for the maximum value of
<CODE>scale</CODE> in the <CODE>bc</CODE> utility.  Its value is <CODE>99</CODE>.
<P>
<DT><CODE>_POSIX2_BC_STRING_MAX</CODE>
<DD>The most restrictive limit permitted by POSIX.2 for the maximum size of
a string constant in the <CODE>bc</CODE> utility.  Its value is <CODE>1000</CODE>.
<P>
<DT><CODE>_POSIX2_COLL_WEIGHTS_MAX</CODE>
<DD>The most restrictive limit permitted by POSIX.2 for the maximum number
of weights that can necessarily be used in defining the collating
sequence for a locale.  Its value is <CODE>2</CODE>.
<P>
<DT><CODE>_POSIX2_EXPR_NEST_MAX</CODE>
<DD>The most restrictive limit permitted by POSIX.2 for the maximum number
of expressions nested within parenthesis when using the <CODE>expr</CODE> utility.
Its value is <CODE>32</CODE>.
<P>
<DT><CODE>_POSIX2_LINE_MAX</CODE>
<DD>The most restrictive limit permitted by POSIX.2 for the maximum size of
a text line that the text utilities can handle.  Its value is
<CODE>2048</CODE>.
</DL>
<P>
<H2><A NAME="SEC469" HREF="library_toc.html#SEC469">String-Valued Parameters</A></H2>
<P>
POSIX.2 defines a way to get string-valued parameters from the operating
system with the function <CODE>confstr</CODE>:
<P>
<A NAME="IDX1915"></A>
<U>Function:</U> size_t <B>confstr</B> <I>(int <VAR>parameter</VAR>, char *<VAR>buf</VAR>, size_t <VAR>len</VAR>)</I><P>
This function reads the value of a string-valued system parameter,
storing the string into <VAR>len</VAR> bytes of memory space starting at
<VAR>buf</VAR>.  The <VAR>parameter</VAR> argument should be one of the
<SAMP>`_CS_'</SAMP> symbols listed below.
<P>
The normal return value from <CODE>confstr</CODE> is the length of the string
value that you asked for.  If you supply a null pointer for <VAR>buf</VAR>,
then <CODE>confstr</CODE> does not try to store the string; it just returns
its length.  A value of <CODE>0</CODE> indicates an error.
<P>
If the string you asked for is too long for the buffer (that is, longer
than <CODE><VAR>len</VAR> - 1</CODE>), then <CODE>confstr</CODE> stores just that much
(leaving room for the terminating null character).  You can tell that
this has happened because <CODE>confstr</CODE> returns a value greater than or
equal to <VAR>len</VAR>.
<P>
The following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>The value of the <VAR>parameter</VAR> is invalid.
</DL>
<P>
Currently there is just one parameter you can read with <CODE>confstr</CODE>:
<P>
<DL COMPACT>
<DT><CODE>_CS_PATH</CODE>
<DD>This parameter's value is the recommended default path for searching for
executable files.  This is the path that a user has by default just
after logging in.
</DL>
<P>
The way to use <CODE>confstr</CODE> without any arbitrary limit on string size
is to call it twice: first call it to get the length, allocate the
buffer accordingly, and then call <CODE>confstr</CODE> again to fill the
buffer, like this:
<P>
<PRE>
char *
get_default_path (void)
{
  size_t len = confstr (_CS_PATH, NULL, 0);
  char *buffer = (char *) xmalloc (len);

  if (confstr (_CS_PATH, buf, len + 1) == 0)
    {
      free (buffer);
      return NULL;
    }

  return buffer;
}
</PRE>
<H1><A NAME="SEC470" HREF="library_toc.html#SEC470">C Language Facilities Implemented By the Library</A></H1>
<P>
Some of the facilities implemented by the C library really should be
thought of as parts of the C language itself.  These facilities ought to
be documented in the C Language Manual, not in the library manual; but
since we don't have the language manual yet, and documentation for these
features has been written, we are publishing it here.
<P>
<A NAME="IDX1916"></A>
<A NAME="IDX1917"></A>
<A NAME="IDX1918"></A>
<H2><A NAME="SEC471" HREF="library_toc.html#SEC471">Explicitly Checking Internal Consistency</A></H2>
<P>
When you're writing a program, it's often a good idea to put in checks
at strategic places for "impossible" errors or violations of basic
assumptions.  These checks are helpful in debugging problems due to
misunderstandings between different parts of the program.
<A NAME="IDX1919"></A>
<P>
The <CODE>assert</CODE> macro, defined in the header file <TT>`assert.h'</TT>,
provides a convenient way to abort the program while printing a message
about where in the program the error was detected.
<A NAME="IDX1920"></A>
<P>
Once you think your program is debugged, you can disable the error
checks performed by the <CODE>assert</CODE> macro by recompiling with the
macro <CODE>NDEBUG</CODE> defined.  This means you don't actually have to
change the program source code to disable these checks.
<P>
But disabling these consistency checks is undesirable unless they make
the program significantly slower.  All else being equal, more error
checking is good no matter who is running the program.  A wise user
would rather have a program crash, visibly, than have it return nonsense
without indicating anything might be wrong.
<P>
<A NAME="IDX1921"></A>
<U>Macro:</U> void <B>assert</B> <I>(int <VAR>expression</VAR>)</I><P>
Verify the programmer's belief that <VAR>expression</VAR> should be nonzero
at this point in the program.
<P>
If <CODE>NDEBUG</CODE> is not defined, <CODE>assert</CODE> tests the value of
<VAR>expression</VAR>.  If it is false (zero), <CODE>assert</CODE> aborts the
program (see section <A HREF="library.html#SEC399">Aborting a Program</A>) after printing a message of the
form:
<P>
<PRE>
<TT>`<VAR>file</VAR>'</TT>:<VAR>linenum</VAR>: Assertion `<VAR>expression</VAR>' failed.
</PRE>
<P>
on the standard error stream <CODE>stderr</CODE> (see section <A HREF="library.html#SEC119">Standard Streams</A>).
The filename and line number are taken from the C preprocessor macros
<CODE>__FILE__</CODE> and <CODE>__LINE__</CODE> and specify where the call to
<CODE>assert</CODE> was written.
<P>
If the preprocessor macro <CODE>NDEBUG</CODE> is defined at the point where
<TT>`assert.h'</TT> is included, the <CODE>assert</CODE> macro is defined to do
absolutely nothing.
<P>
<STRONG>Warning:</STRONG> Even the argument expression <VAR>expression</VAR> is not
evaluated if <CODE>NDEBUG</CODE> is in effect.  So never use <CODE>assert</CODE>
with arguments that involve side effects.  For example, <CODE>assert
(++i &#62; 0);</CODE> is a bad idea, because <CODE>i</CODE> will not be incremented if
<CODE>NDEBUG</CODE> is defined.
<P>
<STRONG>Usage note:</STRONG> The <CODE>assert</CODE> facility is designed for
detecting <EM>internal inconsistency</EM>; it is not suitable for
reporting invalid input or improper usage by <EM>the user</EM> of the
program.
<P>
The information in the diagnostic messages printed by the <CODE>assert</CODE>
macro is intended to help you, the programmer, track down the cause of a
bug, but is not really useful for telling a user of your program why his
or her input was invalid or why a command could not be carried out.  So
you can't use <CODE>assert</CODE> to print the error messages for these
eventualities.
<P>
What's more, your program should not abort when given invalid input, as
<CODE>assert</CODE> would do--it should exit with nonzero status (see section <A HREF="library.html#SEC397">Exit Status</A>) after printing its error messages, or perhaps read another
command or move on to the next input file.
<P>
See section <A HREF="library.html#SEC17">Error Messages</A>, for information on printing error messages for
problems that <EM>do not</EM> represent bugs in the program.
<P>
<A NAME="IDX1922"></A>
<A NAME="IDX1923"></A>
<A NAME="IDX1924"></A>
<H2><A NAME="SEC472" HREF="library_toc.html#SEC472">Variadic Functions</A></H2>
<P>
ANSI C defines a syntax for declaring a function to take a variable
number or type of arguments.  (Such functions are referred to as
<DFN>varargs functions</DFN> or <DFN>variadic functions</DFN>.)  However, the
language itself provides no mechanism for such functions to access their
non-required arguments; instead, you use the variable arguments macros
defined in <TT>`stdarg.h'</TT>.
<P>
This section describes how to declare variadic functions, how to write
them, and how to call them properly.
<P>
<STRONG>Compatibility Note:</STRONG> Many older C dialects provide a similar,
but incompatible, mechanism for defining functions with variable numbers
of arguments, using <TT>`varargs.h'</TT>.
<P>
<H3><A NAME="SEC473" HREF="library_toc.html#SEC473">Why Variadic Functions are Used</A></H3>
<P>
Ordinary C functions take a fixed number of arguments.  When you define
a function, you specify the data type for each argument.  Every call to
the function should supply the expected number of arguments, with types
that can be converted to the specified ones.  Thus, if the function
<SAMP>`foo'</SAMP> is declared with <CODE>int foo (int, char *);</CODE> then you must
call it with two arguments, a number (any kind will do) and a string
pointer.
<P>
But some functions perform operations that can meaningfully accept an
unlimited number of arguments.
<P>
In some cases a function can handle any number of values by operating on
all of them as a block.  For example, consider a function that allocates
a one-dimensional array with <CODE>malloc</CODE> to hold a specified set of
values.  This operation makes sense for any number of values, as long as
the length of the array corresponds to that number.  Without facilities
for variable arguments, you would have to define a separate function for
each possible array size.
<P>
The library function <CODE>printf</CODE> (see section <A HREF="library.html#SEC128">Formatted Output</A>) is an
example of another class of function where variable arguments are
useful.  This function prints its arguments (which can vary in type as
well as number) under the control of a format template string.
<P>
These are good reasons to define a <DFN>variadic</DFN> function which can
handle as many arguments as the caller chooses to pass.
<P>
Some functions such as <CODE>open</CODE> take a fixed set of arguments, but
occasionally ignore the last few.  Strict adherence to ANSI C requires
these functions to be defined as variadic; in practice, however, the GNU
C compiler and most other C compilers let you define such a function to
take a fixed set of arguments--the most it can ever use--and then only
<EM>declare</EM> the function as variadic (or not declare its arguments
at all!).
<P>
<H3><A NAME="SEC474" HREF="library_toc.html#SEC474">How Variadic Functions are Defined and Used</A></H3>
<P>
Defining and using a variadic function involves three steps:
<P>
<UL>
<LI>
<EM>Define</EM> the function as variadic, using an ellipsis
(<SAMP>`...'</SAMP>) in the argument list, and using special macros to
access the variable arguments.  See section <A HREF="library.html#SEC476">Receiving the Argument Values</A>.
<P>
<LI>
<EM>Declare</EM> the function as variadic, using a prototype with an
ellipsis (<SAMP>`...'</SAMP>), in all the files which call it.
See section <A HREF="library.html#SEC475">Syntax for Variable Arguments</A>.
<P>
<LI>
<EM>Call</EM> the function by writing the fixed arguments followed by the
additional variable arguments.  See section <A HREF="library.html#SEC478">Calling Variadic Functions</A>.
</UL>
<P>
<A NAME="IDX1925"></A>
<A NAME="IDX1926"></A>
<A NAME="IDX1927"></A>
<H4><A NAME="SEC475" HREF="library_toc.html#SEC475">Syntax for Variable Arguments</A></H4>
<P>
A function that accepts a variable number of arguments must be declared
with a prototype that says so.   You write the fixed arguments as usual,
and then tack on <SAMP>`...'</SAMP> to indicate the possibility of 
additional arguments.  The syntax of ANSI C requires at least one fixed
argument before the <SAMP>`...'</SAMP>.  For example,
<P>
<PRE>
int 
func (const char *a, int b, ...)
{
  ...
}	
</PRE>
<P>
outlines a definition of a function <CODE>func</CODE> which returns an
<CODE>int</CODE> and takes two required arguments, a <CODE>const char *</CODE> and
an <CODE>int</CODE>.  These are followed by any number of anonymous
arguments.
<P>
<STRONG>Portability note:</STRONG> For some C compilers, the last required
argument must not be declared <CODE>register</CODE> in the function
definition.  Furthermore, this argument's type must be
<DFN>self-promoting</DFN>: that is, the default promotions must not change
its type.  This rules out array and function types, as well as
<CODE>float</CODE>, <CODE>char</CODE> (whether signed or not) and <CODE>short int</CODE>
(whether signed or not).  This is actually an ANSI C requirement.
<P>
<A NAME="IDX1928"></A>
<A NAME="IDX1929"></A>
<H4><A NAME="SEC476" HREF="library_toc.html#SEC476">Receiving the Argument Values</A></H4>
<P>
Ordinary fixed arguments have individual names, and you can use these
names to access their values.  But optional arguments have no
names--nothing but <SAMP>`...'</SAMP>.  How can you access them?
<A NAME="IDX1930"></A>
<P>
The only way to access them is sequentially, in the order they were
written, and you must use special macros from <TT>`stdarg.h'</TT> in the
following three step process:
<P>
<OL>
<LI>
You initialize an argument pointer variable of type <CODE>va_list</CODE> using
<CODE>va_start</CODE>.  The argument pointer when initialized points to the
first optional argument.
<P>
<LI>
You access the optional arguments by successive calls to <CODE>va_arg</CODE>.
The first call to <CODE>va_arg</CODE> gives you the first optional argument,
the next call gives you the second, and so on.
<P>
You can stop at any time if you wish to ignore any remaining optional
arguments.  It is perfectly all right for a function to access fewer
arguments than were supplied in the call, but you will get garbage
values if you try to access too many arguments.
<P>
<LI>
You indicate that you are finished with the argument pointer variable by
calling <CODE>va_end</CODE>.
<P>
(In practice, with most C compilers, calling <CODE>va_end</CODE> does nothing
and you do not really need to call it.  This is always true in the GNU C
compiler.  But you might as well call <CODE>va_end</CODE> just in case your
program is someday compiled with a peculiar compiler.)
</OL>
<P>
See section <A HREF="library.html#SEC479">Argument Access Macros</A>, for the full definitions of <CODE>va_start</CODE>, 
<CODE>va_arg</CODE> and <CODE>va_end</CODE>.
<P>
Steps 1 and 3 must be performed in the function that accepts the
optional arguments.  However, you can pass the <CODE>va_list</CODE> variable
as an argument to another function and perform all or part of step 2
there.
<P>
You can perform the entire sequence of the three steps multiple times
within a single function invocation.  If you want to ignore the optional
arguments, you can do these steps zero times.
<P>
You can have more than one argument pointer variable if you like.  You
can initialize each variable with <CODE>va_start</CODE> when you wish, and
then you can fetch arguments with each argument pointer as you wish.
Each argument pointer variable will sequence through the same set of
argument values, but at its own pace.
<P>
<STRONG>Portability note:</STRONG> With some compilers, once you pass an
argument pointer value to a subroutine, you must not keep using the same
argument pointer value after that subroutine returns.  For full
portability, you should just pass it to <CODE>va_end</CODE>.  This is actually
an ANSI C requirement, but most ANSI C compilers work happily
regardless.
<P>
<A NAME="IDX1931"></A>
<A NAME="IDX1932"></A>
<A NAME="IDX1933"></A>
<H4><A NAME="SEC477" HREF="library_toc.html#SEC477">How Many Arguments Were Supplied</A></H4>
<P>
There is no general way for a function to determine the number and type
of the optional arguments it was called with.  So whoever designs the
function typically designs a convention for the caller to tell it how
many arguments it has, and what kind.  It is up to you to define an
appropriate calling convention for each variadic function, and write all
calls accordingly.
<P>
One kind of calling convention is to pass the number of optional
arguments as one of the fixed arguments.  This convention works provided
all of the optional arguments are of the same type.
<P>
A similar alternative is to have one of the required arguments be a bit
mask, with a bit for each possible purpose for which an optional
argument might be supplied.  You would test the bits in a predefined
sequence; if the bit is set, fetch the value of the next argument,
otherwise use a default value.
<P>
A required argument can be used as a pattern to specify both the number
and types of the optional arguments.  The format string argument to
<CODE>printf</CODE> is one example of this (see section <A HREF="library.html#SEC135">Formatted Output Functions</A>).
<P>
Another possibility is to pass an "end marker" value as the last
optional argument.  For example, for a function that manipulates an
arbitrary number of pointer arguments, a null pointer might indicate the
end of the argument list.  (This assumes that a null pointer isn't
otherwise meaningful to the function.)  The <CODE>execl</CODE> function works
in just this way; see section <A HREF="library.html#SEC406">Executing a File</A>.
<P>
<A NAME="IDX1934"></A>
<A NAME="IDX1935"></A>
<A NAME="IDX1936"></A>
<H4><A NAME="SEC478" HREF="library_toc.html#SEC478">Calling Variadic Functions</A></H4>
<P>
You don't have to write anything special when you call a variadic function.
Just write the arguments (required arguments, followed by optional ones)
inside parentheses, separated by commas, as usual.  But you should prepare
by declaring the function with a prototype, and you must know how the
argument values are converted.
<P>
In principle, functions that are <EM>defined</EM> to be variadic must also
be <EM>declared</EM> to be variadic using a function prototype whenever
you call them.  (See section <A HREF="library.html#SEC475">Syntax for Variable Arguments</A>, for how.)  This is because
some C compilers use a different calling convention to pass the same set
of argument values to a function depending on whether that function
takes variable arguments or fixed arguments.
<P>
In practice, the GNU C compiler always passes a given set of argument
types in the same way regardless of whether they are optional or
required.  So, as long as the argument types are self-promoting, you can
safely omit declaring them.  Usually it is a good idea to declare the
argument types for variadic functions, and indeed for all functions.
But there are a few functions which it is extremely convenient not to
have to declare as variadic--for example, <CODE>open</CODE> and
<CODE>printf</CODE>.
<A NAME="IDX1937"></A>
<A NAME="IDX1938"></A>
<P>
Since the prototype doesn't specify types for optional arguments, in a
call to a variadic function the <DFN>default argument promotions</DFN> are
performed on the optional argument values.  This means the objects of
type <CODE>char</CODE> or <CODE>short int</CODE> (whether signed or not) are
promoted to either <CODE>int</CODE> or <CODE>unsigned int</CODE>, as
appropriate; and that objects of type <CODE>float</CODE> are promoted to type
<CODE>double</CODE>.  So, if the caller passes a <CODE>char</CODE> as an optional
argument, it is promoted to an <CODE>int</CODE>, and the function should get
it with <CODE>va_arg (<VAR>ap</VAR>, int)</CODE>.
<P>
Conversion of the required arguments is controlled by the function
prototype in the usual way: the argument expression is converted to the
declared argument type as if it were being assigned to a variable of
that type.
<P>
<H4><A NAME="SEC479" HREF="library_toc.html#SEC479">Argument Access Macros</A></H4>
<P>
Here are descriptions of the macros used to retrieve variable arguments.
These macros are defined in the header file <TT>`stdarg.h'</TT>.
<A NAME="IDX1939"></A>
<P>
<A NAME="IDX1940"></A>
<U>Data Type:</U> <B>va_list</B><P>
The type <CODE>va_list</CODE> is used for argument pointer variables.
<P>
<A NAME="IDX1941"></A>
<U>Macro:</U> void <B>va_start</B> <I>(va_list <VAR>ap</VAR>, <VAR>last_required</VAR>)</I><P>
This macro initializes the argument pointer variable <VAR>ap</VAR> to point
to the first of the optional arguments of the current function;
<VAR>last_required</VAR> must be the last required argument to the function.
<P>
See section <A HREF="library.html#SEC481">Old-Style Variadic Functions</A>, for an alternate definition of <CODE>va_start</CODE>
found in the header file <TT>`varargs.h'</TT>.
<P>
<A NAME="IDX1942"></A>
<U>Macro:</U> <VAR>type</VAR> <B>va_arg</B> <I>(va_list <VAR>ap</VAR>, <VAR>type</VAR>)</I><P>
The <CODE>va_arg</CODE> macro returns the value of the next optional argument,
and modifies the value of <VAR>ap</VAR> to point to the subsequent argument.
Thus, successive uses of <CODE>va_arg</CODE> return successive optional 
arguments.
<P>
The type of the value returned by <CODE>va_arg</CODE> is <VAR>type</VAR> as
specified in the call.  <VAR>type</VAR> must be a self-promoting type (not
<CODE>char</CODE> or <CODE>short int</CODE> or <CODE>float</CODE>) that matches the type
of the actual argument.
<P>
<A NAME="IDX1943"></A>
<U>Macro:</U> void <B>va_end</B> <I>(va_list <VAR>ap</VAR>)</I><P>
This ends the use of <VAR>ap</VAR>.  After a <CODE>va_end</CODE> call, further
<CODE>va_arg</CODE> calls with the same <VAR>ap</VAR> may not work.  You should invoke
<CODE>va_end</CODE> before returning from the function in which <CODE>va_start</CODE>
was invoked with the same <VAR>ap</VAR> argument.
<P>
In the GNU C library, <CODE>va_end</CODE> does nothing, and you need not ever
use it except for reasons of portability.
<P>
<H3><A NAME="SEC480" HREF="library_toc.html#SEC480">Example of a Variadic Function</A></H3>
<P>
Here is a complete sample function that accepts a variable number of
arguments.  The first argument to the function is the count of remaining
arguments, which are added up and the result returned.  While trivial,
this function is sufficient to illustrate how to use the variable
arguments facility.
<P>
<PRE>
#include &#60;stdarg.h&#62;
#include &#60;stdio.h&#62;

int
add_em_up (int count,...)
{
  va_list ap;
  int i, sum;

  va_start (ap, count);		/* Initialize the argument list.  */

  sum = 0;
  for (i = 0; i &#60; count; i++)
    sum += va_arg (ap, int);	/* Get the next argument value.  */

  va_end (ap);			/* Clean up.  */
  return sum;
}

int
main (void)
{
  /* This call prints 16.  */
  printf ("%d\n", add_em_up (3, 5, 5, 6));

  /* This call prints 55.  */
  printf ("%d\n", add_em_up (10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10));

  return 0;
}
</PRE>
<P>
<H4><A NAME="SEC481" HREF="library_toc.html#SEC481">Old-Style Variadic Functions</A></H4>
<A NAME="IDX1944"></A>
<P>
Before ANSI C, programmers used a slightly different facility for
writing variadic functions.  The GNU C compiler still supports it;
currently, it is more portable than the ANSI C facility, since support
for ANSI C is still not universal.  The header file which defines the
old-fashioned variadic facility is called <TT>`varargs.h'</TT>.
<P>
Using <TT>`varargs.h'</TT> is almost the same as using <TT>`stdarg.h'</TT>.
There is no difference in how you call a variadic function;
See section <A HREF="library.html#SEC478">Calling Variadic Functions</A>.  The only difference is in how you define
them.  First of all, you must use old-style non-prototype syntax, like
this:
<P>
<PRE>
tree
build (va_alist)
     va_dcl
{
</PRE>
<P>
Secondly, you must give <CODE>va_start</CODE> just one argument, like this:
<P>
<PRE>
  va_list p;
  va_start (p);
</PRE>
<P>
These are the special macros used for defining old-style variadic
functions:
<P>
<A NAME="IDX1945"></A>
<U>Macro:</U> <B>va_alist</B><P>
This macro stands for the argument name list required in a variadic
function.  
<P>
<A NAME="IDX1946"></A>
<U>Macro:</U> <B>va_dcl</B><P>
This macro declares the implicit argument or arguments for a variadic
function.
<P>
<A NAME="IDX1947"></A>
<U>Macro:</U> void <B>va_start</B> <I>(va_list <VAR>ap</VAR>)</I><P>
This macro, as defined in <TT>`varargs.h'</TT>, initializes the argument
pointer variable <VAR>ap</VAR> to point to the first argument of the current
function.
<P>
The other argument macros, <CODE>va_arg</CODE> and <CODE>va_end</CODE>, are the same
in <TT>`varargs.h'</TT> as in <TT>`stdarg.h'</TT>; see section <A HREF="library.html#SEC479">Argument Access Macros</A> for
details.
<P>
It does not work to include both <TT>`varargs.h'</TT> and <TT>`stdarg.h'</TT> in
the same compilation; they define <CODE>va_start</CODE> in conflicting ways.
<P>
<A NAME="IDX1948"></A>
<H2><A NAME="SEC482" HREF="library_toc.html#SEC482">Null Pointer Constant</A></H2>
<P>
The null pointer constant is guaranteed not to point to any real object.
You can assign it to any pointer variable since it has type <CODE>void
*</CODE>.  The preferred way to write a null pointer constant is with
<CODE>NULL</CODE>.
<P>
<A NAME="IDX1949"></A>
<U>Macro:</U> void * <B>NULL</B><P>
This is a null pointer constant.
<P>
You can also use <CODE>0</CODE> or <CODE>(void *)0</CODE> as a null pointer
constant, but using <CODE>NULL</CODE> is cleaner because it makes the purpose
of the constant more evident.
<P>
If you use the null pointer constant as a function argument, then for
complete portability you should make sure that the function has a
prototype declaration.  Otherwise, if the target machine has two
different pointer representations, the compiler won't know which
representation to use for that argument.  You can avoid the problem by
explicitly casting the constant to the proper pointer type, but we
recommend instead adding a prototype for the function you are calling.
<P>
<H2><A NAME="SEC483" HREF="library_toc.html#SEC483">Important Data Types</A></H2>
<P>
The result of subtracting two pointers in C is always an integer, but the
precise data type varies from C compiler to C compiler.  Likewise, the
data type of the result of <CODE>sizeof</CODE> also varies between compilers.
ANSI defines standard aliases for these two types, so you can refer to
them in a portable fashion.  They are defined in the header file 
<TT>`stddef.h'</TT>.
<A NAME="IDX1950"></A>
<P>
<A NAME="IDX1951"></A>
<U>Data Type:</U> <B>ptrdiff_t</B><P>
This is the signed integer type of the result of subtracting two
pointers.  For example, with the declaration <CODE>char *p1, *p2;</CODE>, the
expression <CODE>p2 - p1</CODE> is of type <CODE>ptrdiff_t</CODE>.  This will
probably be one of the standard signed integer types (<CODE>short
int</CODE>, <CODE>int</CODE> or <CODE>long int</CODE>), but might be a nonstandard
type that exists only for this purpose.
<P>
<A NAME="IDX1952"></A>
<U>Data Type:</U> <B>size_t</B><P>
This is an unsigned integer type used to represent the sizes of objects.
The result of the <CODE>sizeof</CODE> operator is of this type, and functions
such as <CODE>malloc</CODE> (see section <A HREF="library.html#SEC21">Unconstrained Allocation</A>) and
<CODE>memcpy</CODE> (see section <A HREF="library.html#SEC61">Copying and Concatenation</A>) accept arguments of
this type to specify object sizes.
<P>
<STRONG>Usage Note:</STRONG> <CODE>size_t</CODE> is the preferred way to declare any
arguments or variables that hold the size of an object.
<P>
In the GNU system <CODE>size_t</CODE> is equivalent to either
<CODE>unsigned int</CODE> or <CODE>unsigned long int</CODE>.  These types
have identical properties on the GNU system, and for most purposes, you
can use them interchangeably.  However, they are distinct as data types,
which makes a difference in certain contexts.
<P>
For example, when you specify the type of a function argument in a
function prototype, it makes a difference which one you use.  If the
system header files declare <CODE>malloc</CODE> with an argument of type
<CODE>size_t</CODE> and you declare <CODE>malloc</CODE> with an argument of type
<CODE>unsigned int</CODE>, you will get a compilation error if <CODE>size_t</CODE>
happens to be <CODE>unsigned long int</CODE> on your system.  To avoid any
possibility of error, when a function argument or value is supposed to
have type <CODE>size_t</CODE>, never declare its type in any other way.
<P>
<STRONG>Compatibility Note:</STRONG> Pre-ANSI C implementations generally used
<CODE>unsigned int</CODE> for representing object sizes and <CODE>int</CODE> for
pointer subtraction results.  They did not necessarily define either
<CODE>size_t</CODE> or <CODE>ptrdiff_t</CODE>.  Unix systems did define
<CODE>size_t</CODE>, in <TT>`sys/types.h'</TT>, but the definition was usually a
signed type.
<P>
<H2><A NAME="SEC484" HREF="library_toc.html#SEC484">Data Type Measurements</A></H2>
<P>
Most of the time, if you choose the proper C data type for each object
in your program, you need not be concerned with just how it is
represented or how many bits it uses.  When you do need such
information, the C language itself does not provide a way to get it.
The header files <TT>`limits.h'</TT> and <TT>`float.h'</TT> contain macros
which give you this information in full detail.
<P>
<A NAME="IDX1953"></A>
<A NAME="IDX1954"></A>
<A NAME="IDX1955"></A>
<H3><A NAME="SEC485" HREF="library_toc.html#SEC485">Computing the Width of an Integer Data Type</A></H3>
<P>
The most common reason that a program needs to know how many bits are in
an integer type is for using an array of <CODE>long int</CODE> as a bit vector.
You can access the bit at index <VAR>n</VAR> with
<P>
<PRE>
vector[<VAR>n</VAR> / LONGBITS] &#38; (1 &#60;&#60; (<VAR>n</VAR> % LONGBITS))
</PRE>
<P>
provided you define <CODE>LONGBITS</CODE> as the number of bits in a
<CODE>long int</CODE>.
<A NAME="IDX1956"></A>
<P>
There is no operator in the C language that can give you the number of
bits in an integer data type.  But you can compute it from the macro
<CODE>CHAR_BIT</CODE>, defined in the header file <TT>`limits.h'</TT>.
<P>
<DL COMPACT>
<DT><CODE>CHAR_BIT</CODE>
<DD>This is the number of bits in a <CODE>char</CODE>---eight, on most systems.
The value has type <CODE>int</CODE>.
<P>
You can compute the number of bits in any data type <VAR>type</VAR> like
this:
<P>
<PRE>
sizeof (<VAR>type</VAR>) * CHAR_BIT
</PRE>
</DL>
<P>
<A NAME="IDX1957"></A>
<A NAME="IDX1958"></A>
<A NAME="IDX1959"></A>
<H3><A NAME="SEC486" HREF="library_toc.html#SEC486">Range of an Integer Type</A></H3>
<P>
Suppose you need to store an integer value which can range from zero to
one million.  Which is the smallest type you can use?  There is no
general rule; it depends on the C compiler and target machine.  You can
use the <SAMP>`MIN'</SAMP> and <SAMP>`MAX'</SAMP> macros in <TT>`limits.h'</TT> to determine
which type will work.
<P>
Each signed integer type has a pair of macros which give the smallest
and largest values that it can hold.  Each unsigned integer type has one
such macro, for the maximum value; the minimum value is, of course,
zero.
<P>
The values of these macros are all integer constant expressions.  The
<SAMP>`MAX'</SAMP> and <SAMP>`MIN'</SAMP> macros for <CODE>char</CODE> and <CODE>short
int</CODE> types have values of type <CODE>int</CODE>.  The <SAMP>`MAX'</SAMP> and
<SAMP>`MIN'</SAMP> macros for the other types have values of the same type
described by the macro--thus, <CODE>ULONG_MAX</CODE> has type
<CODE>unsigned long int</CODE>.
<P>
<DL COMPACT>
<DT><CODE>SCHAR_MIN</CODE>
<DD><P>
This is the minimum value that can be represented by a <CODE>signed char</CODE>.
<P>
<DT><CODE>SCHAR_MAX</CODE>
<DD><DT><CODE>UCHAR_MAX</CODE>
<DD><P>
These are the maximum values that can be represented by a
<CODE>signed char</CODE> and <CODE>unsigned char</CODE>, respectively.
<P>
<DT><CODE>CHAR_MIN</CODE>
<DD><P>
This is the minimum value that can be represented by a <CODE>char</CODE>.
It's equal to <CODE>SCHAR_MIN</CODE> if <CODE>char</CODE> is signed, or zero
otherwise.
<P>
<DT><CODE>CHAR_MAX</CODE>
<DD><P>
This is the maximum value that can be represented by a <CODE>char</CODE>.
It's equal to <CODE>SCHAR_MAX</CODE> if <CODE>char</CODE> is signed, or
<CODE>UCHAR_MAX</CODE> otherwise.
<P>
<DT><CODE>SHRT_MIN</CODE>
<DD><P>
This is the minimum value that can be represented by a <CODE>signed
short int</CODE>.  On most machines that the GNU C library runs on,
<CODE>short</CODE> integers are 16-bit quantities.
<P>
<DT><CODE>SHRT_MAX</CODE>
<DD><DT><CODE>USHRT_MAX</CODE>
<DD><P>
These are the maximum values that can be represented by a
<CODE>signed short int</CODE> and <CODE>unsigned short int</CODE>,
respectively.
<P>
<DT><CODE>INT_MIN</CODE>
<DD><P>
This is the minimum value that can be represented by a <CODE>signed
int</CODE>.  On most machines that the GNU C system runs on, an <CODE>int</CODE> is
a 32-bit quantity.
<P>
<DT><CODE>INT_MAX</CODE>
<DD><DT><CODE>UINT_MAX</CODE>
<DD><P>
These are the maximum values that can be represented by, respectively,
the type <CODE>signed int</CODE> and the type <CODE>unsigned int</CODE>.
<P>
<DT><CODE>LONG_MIN</CODE>
<DD><P>
This is the minimum value that can be represented by a <CODE>signed
long int</CODE>.  On most machines that the GNU C system runs on, <CODE>long</CODE>
integers are 32-bit quantities, the same size as <CODE>int</CODE>.
<P>
<DT><CODE>LONG_MAX</CODE>
<DD><DT><CODE>ULONG_MAX</CODE>
<DD><P>
These are the maximum values that can be represented by a
<CODE>signed long int</CODE> and <CODE>unsigned long int</CODE>, respectively.
<P>
<DT><CODE>LONG_LONG_MIN</CODE>
<DD><P>
This is the minimum value that can be represented by a <CODE>signed
long long int</CODE>.  On most machines that the GNU C system runs on,
<CODE>long long</CODE> integers are 64-bit quantities.
<P>
<DT><CODE>LONG_LONG_MAX</CODE>
<DD><DT><CODE>ULONG_LONG_MAX</CODE>
<DD><P>
These are the maximum values that can be represented by a <CODE>signed
long long int</CODE> and <CODE>unsigned long long int</CODE>, respectively.
<P>
<DT><CODE>WCHAR_MAX</CODE>
<DD><P>
This is the maximum value that can be represented by a <CODE>wchar_t</CODE>.
@xref{Wide Character Intro}.
</DL>
<P>
The header file <TT>`limits.h'</TT> also defines some additional constants
that parameterize various operating system and file system limits.  These
constants are described in section <A HREF="library.html#SEC454">System Configuration Parameters</A>.
<P>
<A NAME="IDX1960"></A>
<A NAME="IDX1961"></A>
<A NAME="IDX1962"></A>
<A NAME="IDX1963"></A>
<H3><A NAME="SEC487" HREF="library_toc.html#SEC487">Floating Type Macros</A></H3>
<P>
The specific representation of floating point numbers varies from
machine to machine.  Because floating point numbers are represented
internally as approximate quantities, algorithms for manipulating
floating point data often need to take account of the precise details of
the machine's floating point representation.
<P>
Some of the functions in the C library itself need this information; for
example, the algorithms for printing and reading floating point numbers
(see section <A HREF="library.html#SEC117">Input/Output on Streams</A>) and for calculating trigonometric and
irrational functions (see section <A HREF="library.html#SEC290">Mathematics</A>) use it to avoid round-off
error and loss of accuracy.  User programs that implement numerical
analysis techniques also often need this information in order to
minimize or compute error bounds.
<P>
The header file <TT>`float.h'</TT> describes the format used by your
machine.
<P>
<H4><A NAME="SEC488" HREF="library_toc.html#SEC488">Floating Point Representation Concepts</A></H4>
<P>
This section introduces the terminology for describing floating point
representations.
<P>
You are probably already familiar with most of these concepts in terms
of scientific or exponential notation for floating point numbers.  For
example, the number <CODE>123456.0</CODE> could be expressed in exponential
notation as <CODE>1.23456e+05</CODE>, a shorthand notation indicating that the
mantissa <CODE>1.23456</CODE> is multiplied by the base <CODE>10</CODE> raised to
power <CODE>5</CODE>.
<P>
More formally, the internal representation of a floating point number
can be characterized in terms of the following parameters:
<P>
<UL>
<A NAME="IDX1964"></A>
<LI>
The <DFN>sign</DFN> is either <CODE>-1</CODE> or <CODE>1</CODE>.
<P>
<A NAME="IDX1965"></A>
<A NAME="IDX1966"></A>
<LI>
The <DFN>base</DFN> or <DFN>radix</DFN> for exponentiation, an integer greater
than <CODE>1</CODE>.  This is a constant for a particular representation.
<P>
<A NAME="IDX1967"></A>
<LI>
The <DFN>exponent</DFN> to which the base is raised.  The upper and lower
bounds of the exponent value are constants for a particular
representation.
<A NAME="IDX1968"></A>
<P>
Sometimes, in the actual bits representing the floating point number,
the exponent is <DFN>biased</DFN> by adding a constant to it, to make it
always be represented as an unsigned quantity.  This is only important
if you have some reason to pick apart the bit fields making up the
floating point number by hand, which is something for which the GNU
library provides no support.  So this is ignored in the discussion that
follows.
<P>
<A NAME="IDX1969"></A>
<A NAME="IDX1970"></A>
<LI>
The <DFN>mantissa</DFN> or <DFN>significand</DFN>, an unsigned integer which is a
part of each floating point number.
<P>
<A NAME="IDX1971"></A>
<LI>
The <DFN>precision</DFN> of the mantissa.  If the base of the representation
is <VAR>b</VAR>, then the precision is the number of base-<VAR>b</VAR> digits in
the mantissa.  This is a constant for a particular representation.
<A NAME="IDX1972"></A>
<P>
Many floating point representations have an implicit <DFN>hidden bit</DFN> in
the mantissa.  This is a bit which is present virtually in the mantissa,
but not stored in memory because its value is always 1 in a normalized
number.  The precision figure (see above) includes any hidden bits.
<P>
Again, the GNU library provides no facilities for dealing with such
low-level aspects of the representation.
</UL>
<P>
The mantissa of a floating point number actually represents an implicit
fraction whose denominator is the base raised to the power of the
precision.  Since the largest representable mantissa is one less than
this denominator, the value of the fraction is always strictly less than
<CODE>1</CODE>.  The mathematical value of a floating point number is then the
product of this fraction, the sign, and the base raised to the exponent.
<A NAME="IDX1973"></A>
<P>
We say that the floating point number is <DFN>normalized</DFN> if the
fraction is at least <CODE>1/<VAR>b</VAR></CODE>, where <VAR>b</VAR> is the base.  In
other words, the mantissa would be too large to fit if it were
multiplied by the base.  Non-normalized numbers are sometimes called
<DFN>denormal</DFN>; they contain less precision than the representation
normally can hold.
<P>
If the number is not normalized, then you can subtract <CODE>1</CODE> from the
exponent while multiplying the mantissa by the base, and get another
floating point number with the same value.  <DFN>Normalization</DFN> consists
of doing this repeatedly until the number is normalized.  Two distinct
normalized floating point numbers cannot be equal in value.
<P>
(There is an exception to this rule: if the mantissa is zero, it is
considered normalized.  Another exception happens on certain machines
where the exponent is as small as the representation can hold.  Then
it is impossible to subtract <CODE>1</CODE> from the exponent, so a number
may be normalized even if its fraction is less than <CODE>1/<VAR>b</VAR></CODE>.)
<P>
<H4><A NAME="SEC489" HREF="library_toc.html#SEC489">Floating Point Parameters</A></H4>
<A NAME="IDX1974"></A>
<P>
These macro definitions can be accessed by including the header file
<TT>`float.h'</TT> in your program.
<P>
Macro names starting with <SAMP>`FLT_'</SAMP> refer to the <CODE>float</CODE> type,
while names beginning with <SAMP>`DBL_'</SAMP> refer to the <CODE>double</CODE> type
and names beginning with <SAMP>`LDBL_'</SAMP> refer to the <CODE>long double</CODE>
type.  (Currently GCC does not support <CODE>long double</CODE> as a distinct
data type, so the values for the <SAMP>`LDBL_'</SAMP> constants are equal to the
corresponding constants for the <CODE>double</CODE> type.)<P>
Of these macros, only <CODE>FLT_RADIX</CODE> is guaranteed to be a constant
expression.  The other macros listed here cannot be reliably used in
places that require constant expressions, such as <SAMP>`#if'</SAMP>
preprocessing directives or in the dimensions of static arrays.
<P>
Although the ANSI C standard specifies minimum and maximum values for
most of these parameters, the GNU C implementation uses whatever values
describe the floating point representation of the target machine.  So in
principle GNU C actually satisfies the ANSI C requirements only if the
target machine is suitable.  In practice, all the machines currently
supported are suitable.
<P>
<DL COMPACT>
<DT><CODE>FLT_ROUNDS</CODE>
<DD>This value characterizes the rounding mode for floating point addition.
The following values indicate standard rounding modes:
<P>
<DL COMPACT>
<DT><CODE>-1</CODE>
<DD>The mode is indeterminable.
<DT><CODE>0</CODE>
<DD>Rounding is towards zero.
<DT><CODE>1</CODE>
<DD>Rounding is to the nearest number.
<DT><CODE>2</CODE>
<DD>Rounding is towards positive infinity.
<DT><CODE>3</CODE>
<DD>Rounding is towards negative infinity.
</DL>
<P>
Any other value represents a machine-dependent nonstandard rounding
mode.
<P>
On most machines, the value is <CODE>1</CODE>, in accordance with the IEEE
standard for floating point.
<P>
Here is a table showing how certain values round for each possible value
of <CODE>FLT_ROUNDS</CODE>, if the other aspects of the representation match
the IEEE single-precision standard.
<P>
<PRE>
                 0       1              2              3
 1.00000003     1.0     1.0            1.00000012     1.0
 1.00000007     1.0     1.00000012     1.00000012     1.0
-1.00000003    -1.0    -1.0           -1.0           -1.00000012
-1.00000007    -1.0    -1.00000012    -1.0           -1.00000012
</PRE>
<P>
<LI>FLT_RADIX
This is the value of the base, or radix, of exponent representation.
This is guaranteed to be a constant expression, unlike the other macros
described in this section.  The value is 2 on all machines we know of
except the IBM 360 and derivatives.
<P>
<LI>FLT_MANT_DIG
This is the number of base-<CODE>FLT_RADIX</CODE> digits in the floating point
mantissa for the <CODE>float</CODE> data type.  The following expression
yields <CODE>1.0</CODE> (even though mathematically it should not) due to the
limited number of mantissa digits:
<P>
<PRE>
float radix = FLT_RADIX;

1.0f + 1.0f / radix / radix / ... / radix
</PRE>
<P>
where <CODE>radix</CODE> appears <CODE>FLT_MANT_DIG</CODE> times.
<P>
<LI>DBL_MANT_DIG
<LI>LDBL_MANT_DIG
This is the number of base-<CODE>FLT_RADIX</CODE> digits in the floating point
mantissa for the data types <CODE>double</CODE> and <CODE>long double</CODE>,
respectively.
<P>
<LI>FLT_DIG
<P>
This is the number of decimal digits of precision for the <CODE>float</CODE>
data type.  Technically, if <VAR>p</VAR> and <VAR>b</VAR> are the precision and
base (respectively) for the representation, then the decimal precision
<VAR>q</VAR> is the maximum number of decimal digits such that any floating
point number with <VAR>q</VAR> base 10 digits can be rounded to a floating
point number with <VAR>p</VAR> base <VAR>b</VAR> digits and back again, without
change to the <VAR>q</VAR> decimal digits.
<P>
The value of this macro is supposed to be at least <CODE>6</CODE>, to satisfy
ANSI C.
<P>
<LI>DBL_DIG
<LI>LDBL_DIG
<P>
These are similar to <CODE>FLT_DIG</CODE>, but for the data types
<CODE>double</CODE> and <CODE>long double</CODE>, respectively.  The values of these
macros are supposed to be at least <CODE>10</CODE>.
<P>
<LI>FLT_MIN_EXP
This is the smallest possible exponent value for type <CODE>float</CODE>.
More precisely, is the minimum negative integer such that the value
<CODE>FLT_RADIX</CODE> raised to this power minus 1 can be represented as a
normalized floating point number of type <CODE>float</CODE>.
<P>
<LI>DBL_MIN_EXP
<LI>LDBL_MIN_EXP
<P>
These are similar to <CODE>FLT_MIN_EXP</CODE>, but for the data types
<CODE>double</CODE> and <CODE>long double</CODE>, respectively.
<P>
<LI>FLT_MIN_10_EXP
This is the minimum negative integer such that <CODE>10</CODE> raised to this
power minus 1 can be represented as a normalized floating point number
of type <CODE>float</CODE>.  This is supposed to be <CODE>-37</CODE> or even less.
<P>
<LI>DBL_MIN_10_EXP
<LI>LDBL_MIN_10_EXP
These are similar to <CODE>FLT_MIN_10_EXP</CODE>, but for the data types
<CODE>double</CODE> and <CODE>long double</CODE>, respectively.
<P>
<LI>FLT_MAX_EXP
This is the largest possible exponent value for type <CODE>float</CODE>.  More
precisely, this is the maximum positive integer such that value
<CODE>FLT_RADIX</CODE> raised to this power minus 1 can be represented as a
floating point number of type <CODE>float</CODE>.
<P>
<LI>DBL_MAX_EXP
<LI>LDBL_MAX_EXP
These are similar to <CODE>FLT_MAX_EXP</CODE>, but for the data types
<CODE>double</CODE> and <CODE>long double</CODE>, respectively.
<P>
<LI>FLT_MAX_10_EXP
This is the maximum positive integer such that <CODE>10</CODE> raised to this
power minus 1 can be represented as a normalized floating point number
of type <CODE>float</CODE>.  This is supposed to be at least <CODE>37</CODE>.
<P>
<LI>DBL_MAX_10_EXP
<LI>LDBL_MAX_10_EXP
These are similar to <CODE>FLT_MAX_10_EXP</CODE>, but for the data types
<CODE>double</CODE> and <CODE>long double</CODE>, respectively.
<P>
<LI>FLT_MAX
<P>
The value of this macro is the maximum number representable in type
<CODE>float</CODE>.  It is supposed to be at least <CODE>1E+37</CODE>.  The value
has type <CODE>float</CODE>.
<P>
The smallest representable number is <CODE>- FLT_MAX</CODE>.
<P>
<LI>DBL_MAX
<LI>LDBL_MAX
<P>
These are similar to <CODE>FLT_MAX</CODE>, but for the data types
<CODE>double</CODE> and <CODE>long double</CODE>, respectively.  The type of the
macro's value is the same as the type it describes.
<P>
<LI>FLT_MIN
<P>
The value of this macro is the minimum normalized positive floating
point number that is representable in type <CODE>float</CODE>.  It is supposed
to be no more than <CODE>1E-37</CODE>.
<P>
<LI>DBL_MIN
<LI>LDBL_MIN
<P>
These are similar to <CODE>FLT_MIN</CODE>, but for the data types
<CODE>double</CODE> and <CODE>long double</CODE>, respectively.  The type of the
macro's value is the same as the type it describes.
<P>
<LI>FLT_EPSILON
<P>
This is the minimum positive floating point number of type <CODE>float</CODE>
such that <CODE>1.0 + FLT_EPSILON != 1.0</CODE> is true.  It's supposed to
be no greater than <CODE>1E-5</CODE>.
<P>
<LI>DBL_EPSILON
<LI>LDBL_EPSILON
<P>
These are similar to <CODE>FLT_EPSILON</CODE>, but for the data types
<CODE>double</CODE> and <CODE>long double</CODE>, respectively.  The type of the
macro's value is the same as the type it describes.  The values are not
supposed to be greater than <CODE>1E-9</CODE>.
</DL>
<P>
<A NAME="IDX1975"></A>
<A NAME="IDX1976"></A>
<H4><A NAME="SEC490" HREF="library_toc.html#SEC490">IEEE Floating Point</A></H4>
<P>
Here is an example showing how the floating type measurements come out
for the most common floating point representation, specified by the
<CITE>IEEE Standard for Binary Floating Point Arithmetic (ANSI/IEEE Std
754-1985)</CITE>.  Nearly all computers designed since the 1980s use this
format.
<P>
The IEEE single-precision float representation uses a base of 2.  There
is a sign bit, a mantissa with 23 bits plus one hidden bit (so the total
precision is 24 base-2 digits), and an 8-bit exponent that can represent
values in the range -125 to 128, inclusive.
<P>
So, for an implementation that uses this representation for the
<CODE>float</CODE> data type, appropriate values for the corresponding
parameters are:
<P>
<PRE>
FLT_RADIX                             2
FLT_MANT_DIG                         24
FLT_DIG                               6
FLT_MIN_EXP                        -125
FLT_MIN_10_EXP                      -37
FLT_MAX_EXP                         128
FLT_MAX_10_EXP                      +38
FLT_MIN                 1.17549435E-38F
FLT_MAX                 3.40282347E+38F
FLT_EPSILON             1.19209290E-07F
</PRE>
<P>
Here are the values for the <CODE>double</CODE> data type:
<P>
<PRE>
DBL_MANT_DIG                         53
DBL_DIG                              15
DBL_MIN_EXP                       -1021
DBL_MIN_10_EXP                     -307
DBL_MAX_EXP                        1024
DBL_MAX_10_EXP                      308
DBL_MAX         1.7976931348623157E+308
DBL_MIN         2.2250738585072014E-308
DBL_EPSILON     2.2204460492503131E-016
</PRE>
<P>
<H3><A NAME="SEC491" HREF="library_toc.html#SEC491">Structure Field Offset Measurement</A></H3>
<P>
You can use <CODE>offsetof</CODE> to measure the location within a structure
type of a particular structure member.
<P>
<A NAME="IDX1977"></A>
<U>Macro:</U> size_t <B>offsetof</B> <I>(<VAR>type</VAR>, <VAR>member</VAR>)</I><P>
This expands to a integer constant expression that is the offset of the
structure member named <VAR>member</VAR> in a the structure type <VAR>type</VAR>.
For example, <CODE>offsetof (struct s, elem)</CODE> is the offset, in bytes,
of the member <CODE>elem</CODE> in a <CODE>struct s</CODE>.
<P>
This macro won't work if <VAR>member</VAR> is a bit field; you get an error
from the C compiler in that case.
<P>
<H1><A NAME="SEC492" HREF="library_toc.html#SEC492">Summary of Library Facilities</A></H1>
<P>
This appendix is a complete list of the facilities declared within the
header files supplied with the GNU C library.  Each entry also lists the
standard or other source from which each facility is derived, and tells
you where in the manual you can find more information about how to use
it.
<P>
<DL COMPACT>
<DT><CODE>char *tzname[2]</CODE>
<DD><TT>`time.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC319">Functions and Variables for Time Zones</A>.
<P>
<DT><CODE>AF_FILE</CODE>
<DD><TT>`sys/socket.h'</TT> (GNU):  section <A HREF="library.html#SEC220">Address Formats</A>.
<P>
<DT><CODE>AF_INET</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC220">Address Formats</A>.
<P>
<DT><CODE>AF_UNIX</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC220">Address Formats</A>.
<P>
<DT><CODE>AF_UNSPEC</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC220">Address Formats</A>.
<P>
<DT><CODE>ALTWERASE</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>int ARG_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC455">General Capacity Limits</A>.
<P>
<DT><CODE>B0</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>B110</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>B1200</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>B134</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>B150</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>B1800</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>B19200</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>B200</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>B2400</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>B300</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>B38400</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>B4800</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>B50</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>B600</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>B75</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>B9600</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>int BC_BASE_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC467">Utility Program Capacity Limits</A>.
<P>
<DT><CODE>int BC_DIM_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC467">Utility Program Capacity Limits</A>.
<P>
<DT><CODE>int BC_DIM_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC467">Utility Program Capacity Limits</A>.
<P>
<DT><CODE>int BC_SCALE_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC467">Utility Program Capacity Limits</A>.
<P>
<DT><CODE>int BC_STRING_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC467">Utility Program Capacity Limits</A>.
<P>
<DT><CODE>BRKINT</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC276">Input Modes</A>.
<P>
<DT><CODE>int BUFSIZ</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC163">Controlling Which Kind of Buffering</A>.
<P>
<DT><CODE>CCTS_OFLOW</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC278">Control Modes</A>.
<P>
<DT><CODE>CHAR_BIT</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC485">Computing the Width of an Integer Data Type</A>.
<P>
<DT><CODE>CHAR_MAX</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>CHAR_MIN</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>int CHILD_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC455">General Capacity Limits</A>.
<P>
<DT><CODE>int CLK_TCK</CODE>
<DD><TT>`time.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC311">Basic CPU Time Inquiry</A>.
<P>
<DT><CODE>CLOCAL</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC278">Control Modes</A>.
<P>
<DT><CODE>int CLOCKS_PER_SEC</CODE>
<DD><TT>`time.h'</TT> (ANSI):  section <A HREF="library.html#SEC311">Basic CPU Time Inquiry</A>.
<P>
<DT><CODE>int COLL_WEIGHTS_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC467">Utility Program Capacity Limits</A>.
<P>
<DT><CODE>CREAD</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC278">Control Modes</A>.
<P>
<DT><CODE>CRTS_IFLOW</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC278">Control Modes</A>.
<P>
<DT><CODE>CS5</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC278">Control Modes</A>.
<P>
<DT><CODE>CS6</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC278">Control Modes</A>.
<P>
<DT><CODE>CS7</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC278">Control Modes</A>.
<P>
<DT><CODE>CS8</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC278">Control Modes</A>.
<P>
<DT><CODE>CSIZE</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC278">Control Modes</A>.
<P>
<DT><CODE>CSTOPB</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC278">Control Modes</A>.
<P>
<DT><CODE>DBL_DIG</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>DBL_EPSILON</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>DBL_MANT_DIG</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>DBL_MAX</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>DBL_MAX_10_EXP</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>DBL_MAX_EXP</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>DBL_MIN</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>DBL_MIN_10_EXP</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>DBL_MIN_EXP</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>DIR</CODE>
<DD><TT>`dirent.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC191">Opening a Directory Stream</A>.
<P>
<DT><CODE>int E2BIG</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Argument list too long):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EACCES</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Permission denied):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EADDRINUSE</CODE>
<DD><TT>`errno.h'</TT> (BSD: Address already in use):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EADDRNOTAVAIL</CODE>
<DD><TT>`errno.h'</TT> (BSD: Can't assign requested address):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EAFNOSUPPORT</CODE>
<DD><TT>`errno.h'</TT> (BSD: Address family not supported by protocol family):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EAGAIN</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Resource temporarily unavailable):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EALREADY</CODE>
<DD><TT>`errno.h'</TT> (BSD: Operation already in progress):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EBADF</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Bad file descriptor):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EBUSY</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Device busy):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ECHILD</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: No child processes):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>ECHO</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>ECHOCTL</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>ECHOE</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>ECHOK</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>ECHOKE</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>ECHONL</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>ECHOPRT</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>int ECONNABORTED</CODE>
<DD><TT>`errno.h'</TT> (BSD: Software caused connection abort):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ECONNREFUSED</CODE>
<DD><TT>`errno.h'</TT> (BSD: Connection refused):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ECONNRESET</CODE>
<DD><TT>`errno.h'</TT> (BSD: Connection reset by peer):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ED</CODE>
<DD><TT>`errno.h'</TT> (GNU: ?):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EDEADLK</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Resource deadlock avoided):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EDESTADDRREQ</CODE>
<DD><TT>`errno.h'</TT> (BSD: Destination address required):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EDOM</CODE>
<DD><TT>`errno.h'</TT> (ANSI: Numerical argument out of domain):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EDQUOT</CODE>
<DD><TT>`errno.h'</TT> (BSD: Disc quota exceeded):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EEXIST</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: File exists):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EFAULT</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Bad address):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EFBIG</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: File too large):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EGRATUITOUS</CODE>
<DD><TT>`errno.h'</TT> (GNU: Gratuitous error):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EHOSTDOWN</CODE>
<DD><TT>`errno.h'</TT> (BSD: Host is down):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EHOSTUNREACH</CODE>
<DD><TT>`errno.h'</TT> (BSD: No route to host):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EINPROGRESS</CODE>
<DD><TT>`errno.h'</TT> (BSD: Operation now in progress):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EINTR</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Interrupted system call):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EINVAL</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Invalid argument):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EIO</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Input/output error):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EISCONN</CODE>
<DD><TT>`errno.h'</TT> (BSD: Socket is already connected):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EISDIR</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Is a directory):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ELOOP</CODE>
<DD><TT>`errno.h'</TT> (BSD: Too many levels of symbolic links):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EMFILE</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Too many open files):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EMLINK</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Too many links):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EMSGSIZE</CODE>
<DD><TT>`errno.h'</TT> (BSD: Message too long):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENAMETOOLONG</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: File name too long):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENETDOWN</CODE>
<DD><TT>`errno.h'</TT> (BSD: Network is down):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENETRESET</CODE>
<DD><TT>`errno.h'</TT> (BSD: Network dropped connection on reset):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENETUNREACH</CODE>
<DD><TT>`errno.h'</TT> (BSD: Network is unreachable):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENFILE</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Too many open files in system):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENOBUFS</CODE>
<DD><TT>`errno.h'</TT> (BSD: No buffer space available):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENODEV</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Operation not supported by device):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENOENT</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: No such file or directory):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENOEXEC</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Exec format error):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENOLCK</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: No locks available):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENOMEM</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Cannot allocate memory):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENOPROTOOPT</CODE>
<DD><TT>`errno.h'</TT> (BSD: Protocol not available):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENOSPC</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: No space left on device):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENOSYS</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Function not implemented):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENOTBLK</CODE>
<DD><TT>`errno.h'</TT> (BSD: Block device required):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENOTCONN</CODE>
<DD><TT>`errno.h'</TT> (BSD: Socket is not connected):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENOTDIR</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Not a directory):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENOTEMPTY</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Directory not empty):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENOTSOCK</CODE>
<DD><TT>`errno.h'</TT> (BSD: Socket operation on non-socket):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENOTTY</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Inappropriate ioctl for device):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ENXIO</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Device not configured):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EOF</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC156">End-Of-File and Errors</A>.
<P>
<DT><CODE>int EOPNOTSUPP</CODE>
<DD><TT>`errno.h'</TT> (BSD: Operation not supported):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EPERM</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Operation not permitted):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EPFNOSUPPORT</CODE>
<DD><TT>`errno.h'</TT> (BSD: Protocol family not supported):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EPIPE</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Broken pipe):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EPROTONOSUPPORT</CODE>
<DD><TT>`errno.h'</TT> (BSD: Protocol not supported):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EPROTOTYPE</CODE>
<DD><TT>`errno.h'</TT> (BSD: Protocol wrong type for socket):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ERANGE</CODE>
<DD><TT>`errno.h'</TT> (ANSI: Numerical result out of range):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EREMOTE</CODE>
<DD><TT>`errno.h'</TT> (BSD: Too many levels of remote in path):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EROFS</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Read-only file system):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ESHUTDOWN</CODE>
<DD><TT>`errno.h'</TT> (BSD: Can't send after socket shutdown):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ESOCKTNOSUPPORT</CODE>
<DD><TT>`errno.h'</TT> (BSD: Socket type not supported):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ESPIPE</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Illegal seek):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ESRCH</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: No such process):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ESTALE</CODE>
<DD><TT>`errno.h'</TT> (BSD: Stale NFS file handle):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ETIMEDOUT</CODE>
<DD><TT>`errno.h'</TT> (BSD: Connection timed out):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int ETXTBSY</CODE>
<DD><TT>`errno.h'</TT> (BSD: Text file busy):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EUSERS</CODE>
<DD><TT>`errno.h'</TT> (BSD: Too many users):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EWOULDBLOCK</CODE>
<DD><TT>`errno.h'</TT> (BSD: Operation would block):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EXDEV</CODE>
<DD><TT>`errno.h'</TT> (POSIX.1: Invalid cross-device link):  section <A HREF="library.html#SEC16">Error Codes</A>.
<P>
<DT><CODE>int EXIT_FAILURE</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC397">Exit Status</A>.
<P>
<DT><CODE>int EXIT_SUCCESS</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC397">Exit Status</A>.
<P>
<DT><CODE>int EXPR_NEST_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC467">Utility Program Capacity Limits</A>.
<P>
<DT><CODE>int FD_CLOEXEC</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC183">File Descriptor Flags</A>.
<P>
<DT><CODE>void FD_CLR (int <VAR>filedes</VAR>, fd_set *<VAR>set</VAR>)</CODE>
<DD><TT>`sys/types.h'</TT> (BSD):  section <A HREF="library.html#SEC180">Waiting for Input or Output</A>.
<P>
<DT><CODE>int FD_ISSET (int <VAR>filedes</VAR>, fd_set *<VAR>set</VAR>)</CODE>
<DD><TT>`sys/types.h'</TT> (BSD):  section <A HREF="library.html#SEC180">Waiting for Input or Output</A>.
<P>
<DT><CODE>void FD_SET (int <VAR>filedes</VAR>, fd_set *<VAR>set</VAR>)</CODE>
<DD><TT>`sys/types.h'</TT> (BSD):  section <A HREF="library.html#SEC180">Waiting for Input or Output</A>.
<P>
<DT><CODE>int FD_SETSIZE</CODE>
<DD><TT>`sys/types.h'</TT> (BSD):  section <A HREF="library.html#SEC180">Waiting for Input or Output</A>.
<P>
<DT><CODE>void FD_ZERO (fd_set *<VAR>set</VAR>)</CODE>
<DD><TT>`sys/types.h'</TT> (BSD):  section <A HREF="library.html#SEC180">Waiting for Input or Output</A>.
<P>
<DT><CODE>FILE</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC118">Streams</A>.
<P>
<DT><CODE>int FILENAME_MAX</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC463">Limits on File System Capacity</A>.
<P>
<DT><CODE>FLT_DIG</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>FLT_EPSILON</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>FLT_MANT_DIG</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>FLT_MAX</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>FLT_MAX_10_EXP</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>FLT_MAX_EXP</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>FLT_MIN</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>FLT_MIN_10_EXP</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>FLT_MIN_EXP</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>FLT_RADIX</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>FLT_ROUNDS</CODE>
<DD><TT>`float.h'</TT> (ANSI):  section <A HREF="library.html#SEC489">Floating Point Parameters</A>.
<P>
<DT><CODE>FLUSHO</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>FNM_CASEFOLD</CODE>
<DD><TT>`fnmatch.h'</TT> (GNU):  section <A HREF="library.html#SEC92">Wildcard Matching</A>.
<P>
<DT><CODE>FNM_FILE_NAME</CODE>
<DD><TT>`fnmatch.h'</TT> (GNU):  section <A HREF="library.html#SEC92">Wildcard Matching</A>.
<P>
<DT><CODE>FNM_LEADING_DIR</CODE>
<DD><TT>`fnmatch.h'</TT> (GNU):  section <A HREF="library.html#SEC92">Wildcard Matching</A>.
<P>
<DT><CODE>FNM_NOESCAPE</CODE>
<DD><TT>`fnmatch.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC92">Wildcard Matching</A>.
<P>
<DT><CODE>FNM_PATHNAME</CODE>
<DD><TT>`fnmatch.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC92">Wildcard Matching</A>.
<P>
<DT><CODE>FNM_PERIOD</CODE>
<DD><TT>`fnmatch.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC92">Wildcard Matching</A>.
<P>
<DT><CODE>int FOPEN_MAX</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC120">Opening Streams</A>.
<P>
<DT><CODE>FPE_DECOVF_TRAP</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<DT><CODE>FPE_FLTDIV_FAULT</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<DT><CODE>FPE_FLTDIV_TRAP</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<DT><CODE>FPE_FLTOVF_FAULT</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<DT><CODE>FPE_FLTOVF_TRAP</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<DT><CODE>FPE_FLTUND_FAULT</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<DT><CODE>FPE_FLTUND_TRAP</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<DT><CODE>FPE_INTDIV_TRAP</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<DT><CODE>FPE_INTOVF_TRAP</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<DT><CODE>FPE_SUBRNG_TRAP</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<DT><CODE>int F_DUPFD</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC182">Duplicating Descriptors</A>.
<P>
<DT><CODE>int F_GETFD</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC183">File Descriptor Flags</A>.
<P>
<DT><CODE>int F_GETFL</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC184">File Status Flags</A>.
<P>
<DT><CODE>int F_GETLK</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC185">File Locks</A>.
<P>
<DT><CODE>int F_GETOWN</CODE>
<DD><TT>`fcntl.h'</TT> (BSD):  section <A HREF="library.html#SEC186">Interrupt-Driven Input</A>.
<P>
<DT><CODE>int F_OK</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC208">Testing Permission to Access a File</A>.
<P>
<DT><CODE>F_RDLCK</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC185">File Locks</A>.
<P>
<DT><CODE>int F_SETFD</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC183">File Descriptor Flags</A>.
<P>
<DT><CODE>int F_SETFL</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC184">File Status Flags</A>.
<P>
<DT><CODE>int F_SETLK</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC185">File Locks</A>.
<P>
<DT><CODE>int F_SETLKW</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC185">File Locks</A>.
<P>
<DT><CODE>int F_SETOWN</CODE>
<DD><TT>`fcntl.h'</TT> (BSD):  section <A HREF="library.html#SEC186">Interrupt-Driven Input</A>.
<P>
<DT><CODE>F_UNLCK</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC185">File Locks</A>.
<P>
<DT><CODE>F_WRLCK</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC185">File Locks</A>.
<P>
<DT><CODE>GLOB_ABORTED</CODE>
<DD><TT>`glob.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC94">Calling <CODE>glob</CODE></A>.
<P>
<DT><CODE>GLOB_APPEND</CODE>
<DD><TT>`glob.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC95">Flags for Globbing</A>.
<P>
<DT><CODE>GLOB_DOOFFS</CODE>
<DD><TT>`glob.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC95">Flags for Globbing</A>.
<P>
<DT><CODE>GLOB_ERR</CODE>
<DD><TT>`glob.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC95">Flags for Globbing</A>.
<P>
<DT><CODE>GLOB_MARK</CODE>
<DD><TT>`glob.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC95">Flags for Globbing</A>.
<P>
<DT><CODE>GLOB_NOCHECK</CODE>
<DD><TT>`glob.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC95">Flags for Globbing</A>.
<P>
<DT><CODE>GLOB_NOESCAPE</CODE>
<DD><TT>`glob.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC95">Flags for Globbing</A>.
<P>
<DT><CODE>GLOB_NOMATCH</CODE>
<DD><TT>`glob.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC94">Calling <CODE>glob</CODE></A>.
<P>
<DT><CODE>GLOB_NOSORT</CODE>
<DD><TT>`glob.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC95">Flags for Globbing</A>.
<P>
<DT><CODE>GLOB_NOSPACE</CODE>
<DD><TT>`glob.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC94">Calling <CODE>glob</CODE></A>.
<P>
<DT><CODE>HOST_NOT_FOUND</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC233">Host Names</A>.
<P>
<DT><CODE>double HUGE_VAL</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC291">Domain and Range Errors</A>.
<P>
<DT><CODE>HUPCL</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC278">Control Modes</A>.
<P>
<DT><CODE>ICANON</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>ICRNL</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC276">Input Modes</A>.
<P>
<DT><CODE>IEXTEN</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>IGNBRK</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC276">Input Modes</A>.
<P>
<DT><CODE>IGNCR</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC276">Input Modes</A>.
<P>
<DT><CODE>IGNPAR</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC276">Input Modes</A>.
<P>
<DT><CODE>IMAXBEL</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC276">Input Modes</A>.
<P>
<DT><CODE>unsigned long int INADDR_ANY</CODE>
<DD><TT>`netinet/in.h'</TT> (BSD):  section <A HREF="library.html#SEC231">Host Address Data Type</A>.
<P>
<DT><CODE>INLCR</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC276">Input Modes</A>.
<P>
<DT><CODE>INPCK</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC276">Input Modes</A>.
<P>
<DT><CODE>INT_MAX</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>INT_MIN</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>int IPPORT_RESERVED</CODE>
<DD><TT>`netinet/in.h'</TT> (BSD):  section <A HREF="library.html#SEC234">Internet Ports</A>.
<P>
<DT><CODE>int IPPORT_USERRESERVED</CODE>
<DD><TT>`netinet/in.h'</TT> (BSD):  section <A HREF="library.html#SEC234">Internet Ports</A>.
<P>
<DT><CODE>ISIG</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>ISTRIP</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC276">Input Modes</A>.
<P>
<DT><CODE>ITIMER_PROF</CODE>
<DD><TT>`sys/time.h'</TT> (BSD):  section <A HREF="library.html#SEC321">Setting an Alarm</A>.
<P>
<DT><CODE>ITIMER_REAL</CODE>
<DD><TT>`sys/time.h'</TT> (BSD):  section <A HREF="library.html#SEC321">Setting an Alarm</A>.
<P>
<DT><CODE>ITIMER_VIRTUAL</CODE>
<DD><TT>`sys/time.h'</TT> (BSD):  section <A HREF="library.html#SEC321">Setting an Alarm</A>.
<P>
<DT><CODE>IXANY</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC276">Input Modes</A>.
<P>
<DT><CODE>IXOFF</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC276">Input Modes</A>.
<P>
<DT><CODE>IXON</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC276">Input Modes</A>.
<P>
<DT><CODE>LANG</CODE>
<DD><TT>`locale.h'</TT> (ANSI):  section <A HREF="library.html#SEC79">Categories of Activities that Locales Affect</A>.
<P>
<DT><CODE>LC_ALL</CODE>
<DD><TT>`locale.h'</TT> (ANSI):  section <A HREF="library.html#SEC79">Categories of Activities that Locales Affect</A>.
<P>
<DT><CODE>LC_COLLATE</CODE>
<DD><TT>`locale.h'</TT> (ANSI):  section <A HREF="library.html#SEC79">Categories of Activities that Locales Affect</A>.
<P>
<DT><CODE>LC_CTYPE</CODE>
<DD><TT>`locale.h'</TT> (ANSI):  section <A HREF="library.html#SEC79">Categories of Activities that Locales Affect</A>.
<P>
<DT><CODE>LC_MONETARY</CODE>
<DD><TT>`locale.h'</TT> (ANSI):  section <A HREF="library.html#SEC79">Categories of Activities that Locales Affect</A>.
<P>
<DT><CODE>LC_NUMERIC</CODE>
<DD><TT>`locale.h'</TT> (ANSI):  section <A HREF="library.html#SEC79">Categories of Activities that Locales Affect</A>.
<P>
<DT><CODE>LC_RESPONSE</CODE>
<DD><TT>`locale.h'</TT> (GNU):  section <A HREF="library.html#SEC79">Categories of Activities that Locales Affect</A>.
<P>
<DT><CODE>LC_TIME</CODE>
<DD><TT>`locale.h'</TT> (ANSI):  section <A HREF="library.html#SEC79">Categories of Activities that Locales Affect</A>.
<P>
<DT><CODE>int LINE_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC467">Utility Program Capacity Limits</A>.
<P>
<DT><CODE>int LINK_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC463">Limits on File System Capacity</A>.
<P>
<DT><CODE>LONG_LONG_MAX</CODE>
<DD><TT>`limits.h'</TT> (GNU):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>LONG_LONG_MIN</CODE>
<DD><TT>`limits.h'</TT> (GNU):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>LONG_MAX</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>LONG_MIN</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>L_INCR</CODE>
<DD><TT>`sys/file.h'</TT> (BSD):  section <A HREF="library.html#SEC158">File Positioning</A>.
<P>
<DT><CODE>L_SET</CODE>
<DD><TT>`sys/file.h'</TT> (BSD):  section <A HREF="library.html#SEC158">File Positioning</A>.
<P>
<DT><CODE>L_XTND</CODE>
<DD><TT>`sys/file.h'</TT> (BSD):  section <A HREF="library.html#SEC158">File Positioning</A>.
<P>
<DT><CODE>int L_ctermid</CODE>
<DD><TT>`stdio.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC426">Identifying the Controlling Terminal</A>.
<P>
<DT><CODE>int L_cuserid</CODE>
<DD><TT>`stdio.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC440">Identifying Who Logged In</A>.
<P>
<DT><CODE>int L_tmpnam</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC164">Temporary Files</A>.
<P>
<DT><CODE>int MAXNAMLEN</CODE>
<DD><TT>`dirent.h'</TT> (BSD):  section <A HREF="library.html#SEC463">Limits on File System Capacity</A>.
<P>
<DT><CODE>int MAX_CANON</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC463">Limits on File System Capacity</A>.
<P>
<DT><CODE>int MAX_INPUT</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC463">Limits on File System Capacity</A>.
<P>
<DT><CODE>int MB_CUR_MAX</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC69">Multibyte Characters</A>.
<P>
<DT><CODE>int MB_LEN_MAX</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC69">Multibyte Characters</A>.
<P>
<DT><CODE>MDMBUF</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC278">Control Modes</A>.
<P>
<DT><CODE>int MSG_DONTROUTE</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC252">Socket Data Options</A>.
<P>
<DT><CODE>int MSG_OOB</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC252">Socket Data Options</A>.
<P>
<DT><CODE>int MSG_PEEK</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC252">Socket Data Options</A>.
<P>
<DT><CODE>int NAME_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC463">Limits on File System Capacity</A>.
<P>
<DT><CODE>double NAN</CODE>
<DD><TT>`math.h'</TT> (GNU):  section <A HREF="library.html#SEC300">"Not a Number" Values</A>.
<P>
<DT><CODE>int NCCS</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC273">Terminal Mode Data Types</A>.
<P>
<DT><CODE>int NGROUPS_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC455">General Capacity Limits</A>.
<P>
<DT><CODE>NOFLSH</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>NOKERNINFO</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>NO_ADDRESS</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC233">Host Names</A>.
<P>
<DT><CODE>NO_RECOVERY</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC233">Host Names</A>.
<P>
<DT><CODE>int NSIG</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC335">Standard Signals</A>.
<P>
<DT><CODE>void * NULL</CODE>
<DD><TT>`stddef.h'</TT> (ANSI):  section <A HREF="library.html#SEC482">Null Pointer Constant</A>.
<P>
<DT><CODE>int ONLCR</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC277">Output Modes</A>.
<P>
<DT><CODE>int ONOEOT</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC277">Output Modes</A>.
<P>
<DT><CODE>int OPEN_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC455">General Capacity Limits</A>.
<P>
<DT><CODE>int OPOST</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC277">Output Modes</A>.
<P>
<DT><CODE>int OXTABS</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC277">Output Modes</A>.
<P>
<DT><CODE>int O_ACCMODE</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC184">File Status Flags</A>.
<P>
<DT><CODE>O_APPEND</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC184">File Status Flags</A>.
<P>
<DT><CODE>O_APPEND</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC172">Opening and Closing Files</A>.
<P>
<DT><CODE>O_CREAT</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC172">Opening and Closing Files</A>.
<P>
<DT><CODE>O_EXCL</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC172">Opening and Closing Files</A>.
<P>
<DT><CODE>O_NDELAY</CODE>
<DD><TT>`fcntl.h'</TT> (BSD):  section <A HREF="library.html#SEC184">File Status Flags</A>.
<P>
<DT><CODE>O_NOCTTY</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC172">Opening and Closing Files</A>.
<P>
<DT><CODE>O_NONBLOCK</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC184">File Status Flags</A>.
<P>
<DT><CODE>O_NONBLOCK</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC172">Opening and Closing Files</A>.
<P>
<DT><CODE>O_RDONLY</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC172">Opening and Closing Files</A>.
<P>
<DT><CODE>O_RDWR</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC172">Opening and Closing Files</A>.
<P>
<DT><CODE>O_TRUNC</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC172">Opening and Closing Files</A>.
<P>
<DT><CODE>O_WRONLY</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC172">Opening and Closing Files</A>.
<P>
<DT><CODE>PARENB</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC278">Control Modes</A>.
<P>
<DT><CODE>PARMRK</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC276">Input Modes</A>.
<P>
<DT><CODE>PARODD</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC278">Control Modes</A>.
<P>
<DT><CODE>int PATH_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC463">Limits on File System Capacity</A>.
<P>
<DT><CODE>PA_CHAR</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC138">Parsing a Template String</A>.
<P>
<DT><CODE>PA_DOUBLE</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC138">Parsing a Template String</A>.
<P>
<DT><CODE>PA_FLAG_LONG</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC138">Parsing a Template String</A>.
<P>
<DT><CODE>PA_FLAG_LONG_DOUBLE</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC138">Parsing a Template String</A>.
<P>
<DT><CODE>PA_FLAG_LONG_LONG</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC138">Parsing a Template String</A>.
<P>
<DT><CODE>int PA_FLAG_MASK</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC138">Parsing a Template String</A>.
<P>
<DT><CODE>PA_FLAG_PTR</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC138">Parsing a Template String</A>.
<P>
<DT><CODE>PA_FLAG_SHORT</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC138">Parsing a Template String</A>.
<P>
<DT><CODE>PA_FLOAT</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC138">Parsing a Template String</A>.
<P>
<DT><CODE>PA_INT</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC138">Parsing a Template String</A>.
<P>
<DT><CODE>PA_LAST</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC138">Parsing a Template String</A>.
<P>
<DT><CODE>PA_POINTER</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC138">Parsing a Template String</A>.
<P>
<DT><CODE>PA_STRING</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC138">Parsing a Template String</A>.
<P>
<DT><CODE>PENDIN</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>int PF_FILE</CODE>
<DD><TT>`sys/socket.h'</TT> (GNU):  section <A HREF="library.html#SEC225">Details of File Namespace</A>.
<P>
<DT><CODE>int PF_INET</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC227">The Internet Namespace</A>.
<P>
<DT><CODE>int PF_UNIX</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC225">Details of File Namespace</A>.
<P>
<DT><CODE>int PIPE_BUF</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC463">Limits on File System Capacity</A>.
<P>
<DT><CODE>PRIO_MAX</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC325">Process Priority</A>.
<P>
<DT><CODE>PRIO_MIN</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC325">Process Priority</A>.
<P>
<DT><CODE>PRIO_PGRP</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC325">Process Priority</A>.
<P>
<DT><CODE>PRIO_PROCESS</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC325">Process Priority</A>.
<P>
<DT><CODE>PRIO_USER</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC325">Process Priority</A>.
<P>
<DT><CODE>char * P_tmpdir</CODE>
<DD><TT>`stdio.h'</TT> (SVID):  section <A HREF="library.html#SEC164">Temporary Files</A>.
<P>
<DT><CODE>int RAND_MAX</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC297">ANSI C Random Number Functions</A>.
<P>
<DT><CODE>REG_BADBR</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC97">POSIX Regular Expression Compilation</A>.
<P>
<DT><CODE>REG_BADPAT</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC97">POSIX Regular Expression Compilation</A>.
<P>
<DT><CODE>REG_BADRPT</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC97">POSIX Regular Expression Compilation</A>.
<P>
<DT><CODE>REG_EBRACE</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC97">POSIX Regular Expression Compilation</A>.
<P>
<DT><CODE>REG_EBRACK</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC97">POSIX Regular Expression Compilation</A>.
<P>
<DT><CODE>REG_ECOLLATE</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC97">POSIX Regular Expression Compilation</A>.
<P>
<DT><CODE>REG_ECTYPE</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC97">POSIX Regular Expression Compilation</A>.
<P>
<DT><CODE>REG_EESCAPE</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC97">POSIX Regular Expression Compilation</A>.
<P>
<DT><CODE>REG_EPAREN</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC97">POSIX Regular Expression Compilation</A>.
<P>
<DT><CODE>REG_ERANGE</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC97">POSIX Regular Expression Compilation</A>.
<P>
<DT><CODE>REG_ESPACE</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC99">Matching a Compiled POSIX Regular Expression</A>.
<P>
<DT><CODE>REG_ESPACE</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC97">POSIX Regular Expression Compilation</A>.
<P>
<DT><CODE>REG_ESUBREG</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC97">POSIX Regular Expression Compilation</A>.
<P>
<DT><CODE>REG_EXTENDED</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC98">Flags for POSIX Regular Expressions</A>.
<P>
<DT><CODE>REG_ICASE</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC98">Flags for POSIX Regular Expressions</A>.
<P>
<DT><CODE>REG_NEWLINE</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC98">Flags for POSIX Regular Expressions</A>.
<P>
<DT><CODE>REG_NOMATCH</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC99">Matching a Compiled POSIX Regular Expression</A>.
<P>
<DT><CODE>REG_NOSUB</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC98">Flags for POSIX Regular Expressions</A>.
<P>
<DT><CODE>REG_NOTBOL</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC99">Matching a Compiled POSIX Regular Expression</A>.
<P>
<DT><CODE>REG_NOTEOL</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC99">Matching a Compiled POSIX Regular Expression</A>.
<P>
<DT><CODE>int RE_DUP_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC455">General Capacity Limits</A>.
<P>
<DT><CODE>RLIMIT_CORE</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC324">Limiting Resource Usage</A>.
<P>
<DT><CODE>RLIMIT_CPU</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC324">Limiting Resource Usage</A>.
<P>
<DT><CODE>RLIMIT_DATA</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC324">Limiting Resource Usage</A>.
<P>
<DT><CODE>RLIMIT_FSIZE</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC324">Limiting Resource Usage</A>.
<P>
<DT><CODE>RLIMIT_OPEN_FILES</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC324">Limiting Resource Usage</A>.
<P>
<DT><CODE>RLIMIT_RSS</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC324">Limiting Resource Usage</A>.
<P>
<DT><CODE>RLIMIT_STACK</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC324">Limiting Resource Usage</A>.
<P>
<DT><CODE>RLIM_NLIMITS</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC324">Limiting Resource Usage</A>.
<P>
<DT><CODE>RUSAGE_CHILDREN</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC323">Resource Usage</A>.
<P>
<DT><CODE>RUSAGE_SELF</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC323">Resource Usage</A>.
<P>
<DT><CODE>int R_OK</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC208">Testing Permission to Access a File</A>.
<P>
<DT><CODE>int SA_NOCLDSTOP</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC349">Flags for <CODE>sigaction</CODE></A>.
<P>
<DT><CODE>int SA_ONSTACK</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC349">Flags for <CODE>sigaction</CODE></A>.
<P>
<DT><CODE>int SA_RESTART</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC349">Flags for <CODE>sigaction</CODE></A>.
<P>
<DT><CODE>SCHAR_MAX</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>SCHAR_MIN</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>int SEEK_CUR</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC158">File Positioning</A>.
<P>
<DT><CODE>int SEEK_END</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC158">File Positioning</A>.
<P>
<DT><CODE>int SEEK_SET</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC158">File Positioning</A>.
<P>
<DT><CODE>SHRT_MAX</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>SHRT_MIN</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>int SIGABRT</CODE>
<DD><TT>`signal.h'</TT> (ANSI):  section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<DT><CODE>int SIGALRM</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC338">Alarm Signals</A>.
<P>
<DT><CODE>int SIGBUS</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<DT><CODE>int SIGCHLD</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC340">Job Control Signals</A>.
<P>
<DT><CODE>int SIGCONT</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC340">Job Control Signals</A>.
<P>
<DT><CODE>int SIGFPE</CODE>
<DD><TT>`signal.h'</TT> (ANSI):  section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<DT><CODE>int SIGHUP</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC337">Termination Signals</A>.
<P>
<DT><CODE>int SIGILL</CODE>
<DD><TT>`signal.h'</TT> (ANSI):  section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<DT><CODE>int SIGINT</CODE>
<DD><TT>`signal.h'</TT> (ANSI):  section <A HREF="library.html#SEC337">Termination Signals</A>.
<P>
<DT><CODE>int SIGIO</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC339">Asynchronous I/O Signals</A>.
<P>
<DT><CODE>int SIGKILL</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC337">Termination Signals</A>.
<P>
<DT><CODE>int SIGPIPE</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC341">Miscellaneous Signals</A>.
<P>
<DT><CODE>int SIGPROF</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC338">Alarm Signals</A>.
<P>
<DT><CODE>int SIGQUIT</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC337">Termination Signals</A>.
<P>
<DT><CODE>int SIGSEGV</CODE>
<DD><TT>`signal.h'</TT> (ANSI):  section <A HREF="library.html#SEC336">Program Error Signals</A>.
<P>
<DT><CODE>int SIGSTOP</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC340">Job Control Signals</A>.
<P>
<DT><CODE>int SIGTERM</CODE>
<DD><TT>`signal.h'</TT> (ANSI):  section <A HREF="library.html#SEC337">Termination Signals</A>.
<P>
<DT><CODE>int SIGTSTP</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC340">Job Control Signals</A>.
<P>
<DT><CODE>int SIGTTIN</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC340">Job Control Signals</A>.
<P>
<DT><CODE>int SIGTTOU</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC340">Job Control Signals</A>.
<P>
<DT><CODE>int SIGURG</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC339">Asynchronous I/O Signals</A>.
<P>
<DT><CODE>int SIGUSR1</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC341">Miscellaneous Signals</A>.
<P>
<DT><CODE>int SIGUSR2</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC341">Miscellaneous Signals</A>.
<P>
<DT><CODE>int SIGVTALRM</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC338">Alarm Signals</A>.
<P>
<DT><CODE>SIG_BLOCK</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC371">Process Signal Mask</A>.
<P>
<DT><CODE>sighandler_t SIG_ERR</CODE>
<DD><TT>`signal.h'</TT> (ANSI):  section <A HREF="library.html#SEC345">Basic Signal Handling</A>.
<P>
<DT><CODE>SIG_SETMASK</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC371">Process Signal Mask</A>.
<P>
<DT><CODE>SIG_UNBLOCK</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC371">Process Signal Mask</A>.
<P>
<DT><CODE>int SOCK_DGRAM</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC218">Communication Styles</A>.
<P>
<DT><CODE>int SOCK_RAW</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC218">Communication Styles</A>.
<P>
<DT><CODE>int SOCK_RDM</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC218">Communication Styles</A>.
<P>
<DT><CODE>int SOCK_SEQPACKET</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC218">Communication Styles</A>.
<P>
<DT><CODE>int SOCK_STREAM</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC218">Communication Styles</A>.
<P>
<DT><CODE>int SOL_SOCKET</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC266">Socket-Level Options</A>.
<P>
<DT><CODE>SO_BROADCAST</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC266">Socket-Level Options</A>.
<P>
<DT><CODE>SO_DEBUG</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC266">Socket-Level Options</A>.
<P>
<DT><CODE>SO_DONTROUTE</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC266">Socket-Level Options</A>.
<P>
<DT><CODE>SO_ERROR</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC266">Socket-Level Options</A>.
<P>
<DT><CODE>SO_KEEPALIVE</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC266">Socket-Level Options</A>.
<P>
<DT><CODE>SO_LINGER</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC266">Socket-Level Options</A>.
<P>
<DT><CODE>SO_OOBINLINE</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC266">Socket-Level Options</A>.
<P>
<DT><CODE>SO_RCVBUF</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC266">Socket-Level Options</A>.
<P>
<DT><CODE>SO_REUSEADDR</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC266">Socket-Level Options</A>.
<P>
<DT><CODE>SO_SNDBUF</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC266">Socket-Level Options</A>.
<P>
<DT><CODE>SO_STYLE</CODE>
<DD><TT>`sys/socket.h'</TT> (GNU):  section <A HREF="library.html#SEC266">Socket-Level Options</A>.
<P>
<DT><CODE>SO_TYPE</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC266">Socket-Level Options</A>.
<P>
<DT><CODE>int SSIZE_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC455">General Capacity Limits</A>.
<P>
<DT><CODE>STDERR_FILENO</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC175">Descriptors and Streams</A>.
<P>
<DT><CODE>STDIN_FILENO</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC175">Descriptors and Streams</A>.
<P>
<DT><CODE>STDOUT_FILENO</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC175">Descriptors and Streams</A>.
<P>
<DT><CODE>int STREAM_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC455">General Capacity Limits</A>.
<P>
<DT><CODE>int SV_INTERRUPT</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC382">BSD Function to Establish a Handler</A>.
<P>
<DT><CODE>int SV_ONSTACK</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC382">BSD Function to Establish a Handler</A>.
<P>
<DT><CODE>int SV_RESETHAND</CODE>
<DD><TT>`signal.h'</TT> (Sun):  section <A HREF="library.html#SEC382">BSD Function to Establish a Handler</A>.
<P>
<DT><CODE>S_IEXEC</CODE>
<DD><TT>`sys/stat.h'</TT> (BSD):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>S_IFBLK</CODE>
<DD><TT>`sys/stat.h'</TT> (BSD):  section <A HREF="library.html#SEC203">Testing the Type of a File</A>.
<P>
<DT><CODE>S_IFCHR</CODE>
<DD><TT>`sys/stat.h'</TT> (BSD):  section <A HREF="library.html#SEC203">Testing the Type of a File</A>.
<P>
<DT><CODE>S_IFDIR</CODE>
<DD><TT>`sys/stat.h'</TT> (BSD):  section <A HREF="library.html#SEC203">Testing the Type of a File</A>.
<P>
<DT><CODE>S_IFIFO</CODE>
<DD><TT>`sys/stat.h'</TT> (BSD):  section <A HREF="library.html#SEC203">Testing the Type of a File</A>.
<P>
<DT><CODE>S_IFLNK</CODE>
<DD><TT>`sys/stat.h'</TT> (BSD):  section <A HREF="library.html#SEC203">Testing the Type of a File</A>.
<P>
<DT><CODE>int S_IFMT</CODE>
<DD><TT>`sys/stat.h'</TT> (BSD):  section <A HREF="library.html#SEC203">Testing the Type of a File</A>.
<P>
<DT><CODE>S_IFREG</CODE>
<DD><TT>`sys/stat.h'</TT> (BSD):  section <A HREF="library.html#SEC203">Testing the Type of a File</A>.
<P>
<DT><CODE>S_IFSOCK</CODE>
<DD><TT>`sys/stat.h'</TT> (BSD):  section <A HREF="library.html#SEC203">Testing the Type of a File</A>.
<P>
<DT><CODE>S_IREAD</CODE>
<DD><TT>`sys/stat.h'</TT> (BSD):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>S_IRGRP</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>S_IROTH</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>S_IRUSR</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>S_IRWXG</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>S_IRWXO</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>S_IRWXU</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>int S_ISBLK (mode_t <VAR>m</VAR>)</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX):  section <A HREF="library.html#SEC203">Testing the Type of a File</A>.
<P>
<DT><CODE>int S_ISCHR (mode_t <VAR>m</VAR>)</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX):  section <A HREF="library.html#SEC203">Testing the Type of a File</A>.
<P>
<DT><CODE>int S_ISDIR (mode_t <VAR>m</VAR>)</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX):  section <A HREF="library.html#SEC203">Testing the Type of a File</A>.
<P>
<DT><CODE>int S_ISFIFO (mode_t <VAR>m</VAR>)</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX):  section <A HREF="library.html#SEC203">Testing the Type of a File</A>.
<P>
<DT><CODE>S_ISGID</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>int S_ISLNK (mode_t <VAR>m</VAR>)</CODE>
<DD><TT>`sys/stat.h'</TT> (GNU):  section <A HREF="library.html#SEC203">Testing the Type of a File</A>.
<P>
<DT><CODE>int S_ISREG (mode_t <VAR>m</VAR>)</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX):  section <A HREF="library.html#SEC203">Testing the Type of a File</A>.
<P>
<DT><CODE>int S_ISSOCK (mode_t <VAR>m</VAR>)</CODE>
<DD><TT>`sys/stat.h'</TT> (GNU):  section <A HREF="library.html#SEC203">Testing the Type of a File</A>.
<P>
<DT><CODE>S_ISUID</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>S_ISVTX</CODE>
<DD><TT>`sys/stat.h'</TT> (BSD):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>S_IWGRP</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>S_IWOTH</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>S_IWRITE</CODE>
<DD><TT>`sys/stat.h'</TT> (BSD):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>S_IWUSR</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>S_IXGRP</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>S_IXOTH</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>S_IXUSR</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC205">The Mode Bits for Access Permission</A>.
<P>
<DT><CODE>TCSADRAIN</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC274">Terminal Mode Functions</A>.
<P>
<DT><CODE>TCSAFLUSH</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC274">Terminal Mode Functions</A>.
<P>
<DT><CODE>TCSANOW</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC274">Terminal Mode Functions</A>.
<P>
<DT><CODE>TCSASOFT</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC274">Terminal Mode Functions</A>.
<P>
<DT><CODE>TEMP_FAILURE_RETRY (<VAR>expression</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (GNU):  section <A HREF="library.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<DT><CODE>int TMP_MAX</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC164">Temporary Files</A>.
<P>
<DT><CODE>TOSTOP</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC279">Local Modes</A>.
<P>
<DT><CODE>TRY_AGAIN</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC233">Host Names</A>.
<P>
<DT><CODE>int TZNAME_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC455">General Capacity Limits</A>.
<P>
<DT><CODE>UCHAR_MAX</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>UINT_MAX</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>ULONG_LONG_MAX</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>ULONG_MAX</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>USHRT_MAX</CODE>
<DD><TT>`limits.h'</TT> (ANSI):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>int VDISCARD</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC286">Other Special Characters</A>.
<P>
<DT><CODE>int VDSUSP</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC284">Characters that Cause Signals</A>.
<P>
<DT><CODE>int VEOF</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC282">Characters for Input Editing</A>.
<P>
<DT><CODE>int VEOL</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC282">Characters for Input Editing</A>.
<P>
<DT><CODE>int VEOL2</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC283">BSD Extensions to Editing Characters</A>.
<P>
<DT><CODE>int VERASE</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC282">Characters for Input Editing</A>.
<P>
<DT><CODE>int VINTR</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC284">Characters that Cause Signals</A>.
<P>
<DT><CODE>int VKILL</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC282">Characters for Input Editing</A>.
<P>
<DT><CODE>int VLNEXT</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC283">BSD Extensions to Editing Characters</A>.
<P>
<DT><CODE>int VMIN</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC287">Noncanonical Input</A>.
<P>
<DT><CODE>int VQUIT</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC284">Characters that Cause Signals</A>.
<P>
<DT><CODE>int VREPRINT</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC283">BSD Extensions to Editing Characters</A>.
<P>
<DT><CODE>int VSTART</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC285">Special Characters for Flow Control</A>.
<P>
<DT><CODE>int VSTATUS</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC286">Other Special Characters</A>.
<P>
<DT><CODE>int VSTOP</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC285">Special Characters for Flow Control</A>.
<P>
<DT><CODE>int VSUSP</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC284">Characters that Cause Signals</A>.
<P>
<DT><CODE>int VTIME</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC287">Noncanonical Input</A>.
<P>
<DT><CODE>int VWERASE</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC283">BSD Extensions to Editing Characters</A>.
<P>
<DT><CODE>WCHAR_MAX</CODE>
<DD><TT>`limits.h'</TT> (GNU):  section <A HREF="library.html#SEC486">Range of an Integer Type</A>.
<P>
<DT><CODE>int WCOREDUMP (int <VAR>status</VAR>)</CODE>
<DD><TT>`sys/wait.h'</TT> (BSD):  section <A HREF="library.html#SEC408">Process Completion Status</A>.
<P>
<DT><CODE>int WEXITSTATUS (int <VAR>status</VAR>)</CODE>
<DD><TT>`sys/wait.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC408">Process Completion Status</A>.
<P>
<DT><CODE>int WIFEXITED (int <VAR>status</VAR>)</CODE>
<DD><TT>`sys/wait.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC408">Process Completion Status</A>.
<P>
<DT><CODE>int WIFSIGNALED (int <VAR>status</VAR>)</CODE>
<DD><TT>`sys/wait.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC408">Process Completion Status</A>.
<P>
<DT><CODE>int WIFSTOPPED (int <VAR>status</VAR>)</CODE>
<DD><TT>`sys/wait.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC408">Process Completion Status</A>.
<P>
<DT><CODE>WRDE_APPEND</CODE>
<DD><TT>`wordexp.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC106">Flags for Word Expansion</A>.
<P>
<DT><CODE>WRDE_BADCHAR</CODE>
<DD><TT>`wordexp.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC105">Calling <CODE>wordexp</CODE></A>.
<P>
<DT><CODE>WRDE_BADVAL</CODE>
<DD><TT>`wordexp.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC105">Calling <CODE>wordexp</CODE></A>.
<P>
<DT><CODE>WRDE_CMDSUB</CODE>
<DD><TT>`wordexp.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC105">Calling <CODE>wordexp</CODE></A>.
<P>
<DT><CODE>WRDE_DOOFFS</CODE>
<DD><TT>`wordexp.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC106">Flags for Word Expansion</A>.
<P>
<DT><CODE>WRDE_NOCMD</CODE>
<DD><TT>`wordexp.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC106">Flags for Word Expansion</A>.
<P>
<DT><CODE>WRDE_NOSPACE</CODE>
<DD><TT>`wordexp.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC105">Calling <CODE>wordexp</CODE></A>.
<P>
<DT><CODE>WRDE_REUSE</CODE>
<DD><TT>`wordexp.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC106">Flags for Word Expansion</A>.
<P>
<DT><CODE>WRDE_SHOWERR</CODE>
<DD><TT>`wordexp.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC106">Flags for Word Expansion</A>.
<P>
<DT><CODE>WRDE_SYNTAX</CODE>
<DD><TT>`wordexp.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC105">Calling <CODE>wordexp</CODE></A>.
<P>
<DT><CODE>WRDE_UNDEF</CODE>
<DD><TT>`wordexp.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC106">Flags for Word Expansion</A>.
<P>
<DT><CODE>int WSTOPSIG (int <VAR>status</VAR>)</CODE>
<DD><TT>`sys/wait.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC408">Process Completion Status</A>.
<P>
<DT><CODE>int WTERMSIG (int <VAR>status</VAR>)</CODE>
<DD><TT>`sys/wait.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC408">Process Completion Status</A>.
<P>
<DT><CODE>int W_OK</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC208">Testing Permission to Access a File</A>.
<P>
<DT><CODE>int X_OK</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC208">Testing Permission to Access a File</A>.
<P>
<DT><CODE>_CS_PATH</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC469">String-Valued Parameters</A>.
<P>
<DT><CODE>int _IOFBF</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC163">Controlling Which Kind of Buffering</A>.
<P>
<DT><CODE>int _IOLBF</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC163">Controlling Which Kind of Buffering</A>.
<P>
<DT><CODE>int _IONBF</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC163">Controlling Which Kind of Buffering</A>.
<P>
<DT><CODE>_PC_CHOWN_RESTRICTED</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC466">Using <CODE>pathconf</CODE></A>.
<P>
<DT><CODE>_PC_LINK_MAX</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC466">Using <CODE>pathconf</CODE></A>.
<P>
<DT><CODE>_PC_MAX_CANON</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC466">Using <CODE>pathconf</CODE></A>.
<P>
<DT><CODE>_PC_MAX_INPUT</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC466">Using <CODE>pathconf</CODE></A>.
<P>
<DT><CODE>_PC_NAME_MAX</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC466">Using <CODE>pathconf</CODE></A>.
<P>
<DT><CODE>_PC_NO_TRUNC</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC466">Using <CODE>pathconf</CODE></A>.
<P>
<DT><CODE>_PC_PATH_MAX</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC466">Using <CODE>pathconf</CODE></A>.
<P>
<DT><CODE>_PC_PIPE_BUF</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC466">Using <CODE>pathconf</CODE></A>.
<P>
<DT><CODE>_PC_VDISABLE</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC466">Using <CODE>pathconf</CODE></A>.
<P>
<DT><CODE>_POSIX2_BC_BASE_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC468">Minimum Values for Utility Limits</A>.
<P>
<DT><CODE>_POSIX2_BC_DIM_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC468">Minimum Values for Utility Limits</A>.
<P>
<DT><CODE>_POSIX2_BC_SCALE_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC468">Minimum Values for Utility Limits</A>.
<P>
<DT><CODE>_POSIX2_BC_STRING_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC468">Minimum Values for Utility Limits</A>.
<P>
<DT><CODE>_POSIX2_COLL_WEIGHTS_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC468">Minimum Values for Utility Limits</A>.
<P>
<DT><CODE>int _POSIX2_C_DEV</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC456">Overall System Options</A>.
<P>
<DT><CODE>long int _POSIX2_C_VERSION</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC457">Which Version of POSIX is Supported</A>.
<P>
<DT><CODE>_POSIX2_EXPR_NEST_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC468">Minimum Values for Utility Limits</A>.
<P>
<DT><CODE>int _POSIX2_FORT_DEV</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC456">Overall System Options</A>.
<P>
<DT><CODE>int _POSIX2_FORT_RUN</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC456">Overall System Options</A>.
<P>
<DT><CODE>_POSIX2_LINE_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC468">Minimum Values for Utility Limits</A>.
<P>
<DT><CODE>int _POSIX2_LOCALEDEF</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC456">Overall System Options</A>.
<P>
<DT><CODE>_POSIX2_RE_DUP_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC462">Minimum Values for General Capacity Limits</A>.
<P>
<DT><CODE>int _POSIX2_SW_DEV</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC456">Overall System Options</A>.
<P>
<DT><CODE>_POSIX_ARG_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC462">Minimum Values for General Capacity Limits</A>.
<P>
<DT><CODE>_POSIX_CHILD_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC462">Minimum Values for General Capacity Limits</A>.
<P>
<DT><CODE>int _POSIX_CHOWN_RESTRICTED</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC464">Optional Features in File Support</A>.
<P>
<DT><CODE>int _POSIX_JOB_CONTROL</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC456">Overall System Options</A>.
<P>
<DT><CODE>_POSIX_LINK_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC465">Minimum Values for File System Limits</A>.
<P>
<DT><CODE>_POSIX_MAX_CANON</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC465">Minimum Values for File System Limits</A>.
<P>
<DT><CODE>_POSIX_MAX_INPUT</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC465">Minimum Values for File System Limits</A>.
<P>
<DT><CODE>_POSIX_NAME_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC465">Minimum Values for File System Limits</A>.
<P>
<DT><CODE>_POSIX_NGROUPS_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC462">Minimum Values for General Capacity Limits</A>.
<P>
<DT><CODE>int _POSIX_NO_TRUNC</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC464">Optional Features in File Support</A>.
<P>
<DT><CODE>_POSIX_OPEN_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC462">Minimum Values for General Capacity Limits</A>.
<P>
<DT><CODE>_POSIX_PATH_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC465">Minimum Values for File System Limits</A>.
<P>
<DT><CODE>_POSIX_PIPE_BUF</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC465">Minimum Values for File System Limits</A>.
<P>
<DT><CODE>int _POSIX_SAVED_IDS</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC456">Overall System Options</A>.
<P>
<DT><CODE>_POSIX_SSIZE_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC462">Minimum Values for General Capacity Limits</A>.
<P>
<DT><CODE>_POSIX_STREAM_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC462">Minimum Values for General Capacity Limits</A>.
<P>
<DT><CODE>_POSIX_TZNAME_MAX</CODE>
<DD><TT>`limits.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC462">Minimum Values for General Capacity Limits</A>.
<P>
<DT><CODE>unsigned char _POSIX_VDISABLE</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC464">Optional Features in File Support</A>.
<P>
<DT><CODE>long int _POSIX_VERSION</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC457">Which Version of POSIX is Supported</A>.
<P>
<DT><CODE>_SC_2_C_DEV</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_2_FORT_DEV</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_2_FORT_RUN</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_2_LOCALEDEF</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_2_SW_DEV</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_2_VERSION</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_ARG_MAX</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_BC_BASE_MAX</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_BC_DIM_MAX</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_BC_SCALE_MAX</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_BC_STRING_MAX</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_CHILD_MAX</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_CLK_TCK</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_COLL_WEIGHTS_MAX</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_EXPR_NEST_MAX</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_JOB_CONTROL</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_LINE_MAX</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_NGROUPS_MAX</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_OPEN_MAX</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_SAVED_IDS</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_STREAM_MAX</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_TZNAME_MAX</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_VERSION</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>_SC_VERSION</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC460">Constants for <CODE>sysconf</CODE> Parameters</A>.
<P>
<DT><CODE>__free_hook</CODE>
<DD><TT>`malloc.h'</TT> (GNU):  section <A HREF="library.html#SEC30">Storage Allocation Hooks</A>.
<P>
<DT><CODE>__malloc_hook</CODE>
<DD><TT>`malloc.h'</TT> (GNU):  section <A HREF="library.html#SEC30">Storage Allocation Hooks</A>.
<P>
<DT><CODE>__realloc_hook</CODE>
<DD><TT>`malloc.h'</TT> (GNU):  section <A HREF="library.html#SEC30">Storage Allocation Hooks</A>.
<P>
<DT><CODE>void _exit (int <VAR>status</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC400">Termination Internals</A>.
<P>
<DT><CODE>int _tolower (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (SVID):  section <A HREF="library.html#SEC56">Case Conversion</A>.
<P>
<DT><CODE>int _toupper (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (SVID):  section <A HREF="library.html#SEC56">Case Conversion</A>.
<P>
<DT><CODE>void abort (void)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC399">Aborting a Program</A>.
<P>
<DT><CODE>int abs (int <VAR>number</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC302">Absolute Value</A>.
<P>
<DT><CODE>int accept (int <VAR>socket</VAR>, struct sockaddr *<VAR>addr</VAR>, size_t *<VAR>length_ptr</VAR>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC247">Accepting Connections</A>.
<P>
<DT><CODE>int access (const char *<VAR>filename</VAR>, int <VAR>how</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC208">Testing Permission to Access a File</A>.
<P>
<DT><CODE>double acos (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC293">Inverse Trigonometric Functions</A>.
<P>
<DT><CODE>double acosh (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (BSD):  section <A HREF="library.html#SEC295">Hyperbolic Functions</A>.
<P>
<DT><CODE>int adjtime (const struct timeval *<VAR>delta</VAR>, struct timeval *<VAR>olddelta</VAR>)</CODE>
<DD><TT>`sys/time.h'</TT> (BSD):  section <A HREF="library.html#SEC315">High-Resolution Calendar</A>.
<P>
<DT><CODE>unsigned int alarm (unsigned int <VAR>seconds</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC321">Setting an Alarm</A>.
<P>
<DT><CODE>void * alloca (size_t <VAR>size</VAR>);</CODE>
<DD><TT>`stdlib.h'</TT> (GNU, BSD):  section <A HREF="library.html#SEC45">Automatic Storage with Variable Size</A>.
<P>
<DT><CODE>char * asctime (const struct tm *<VAR>brokentime</VAR>)</CODE>
<DD><TT>`time.h'</TT> (ANSI):  section <A HREF="library.html#SEC317">Formatting Date and Time</A>.
<P>
<DT><CODE>double asin (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC293">Inverse Trigonometric Functions</A>.
<P>
<DT><CODE>double asinh (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (BSD):  section <A HREF="library.html#SEC295">Hyperbolic Functions</A>.
<P>
<DT><CODE>int asprintf (char **<VAR>ptr</VAR>, const char *<VAR>template</VAR>, ...)</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC136">Dynamically Allocating Formatted Output</A>.
<P>
<DT><CODE>void assert (int <VAR>expression</VAR>)</CODE>
<DD><TT>`assert.h'</TT> (ANSI):  section <A HREF="library.html#SEC471">Explicitly Checking Internal Consistency</A>.
<P>
<DT><CODE>double atan (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC293">Inverse Trigonometric Functions</A>.
<P>
<DT><CODE>double atan2 (double <VAR>y</VAR>, double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC293">Inverse Trigonometric Functions</A>.
<P>
<DT><CODE>double atanh (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (BSD):  section <A HREF="library.html#SEC295">Hyperbolic Functions</A>.
<P>
<DT><CODE>int atexit (void (*<VAR>function</VAR>) (void))</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC398">Cleanups on Exit</A>.
<P>
<DT><CODE>double atof (const char *<VAR>string</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC308">Parsing of Floats</A>.
<P>
<DT><CODE>int atoi (const char *<VAR>string</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC307">Parsing of Integers</A>.
<P>
<DT><CODE>long int atol (const char *<VAR>string</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC307">Parsing of Integers</A>.
<P>
<DT><CODE>int bcmp (const void *<VAR>a1</VAR>, const void *<VAR>a2</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`string.h'</TT> (BSD):  section <A HREF="library.html#SEC62">String/Array Comparison</A>.
<P>
<DT><CODE>void * bcopy (void *<VAR>from</VAR>, const void *<VAR>to</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`string.h'</TT> (BSD):  section <A HREF="library.html#SEC61">Copying and Concatenation</A>.
<P>
<DT><CODE>int bind (int <VAR>socket</VAR>, struct sockaddr *<VAR>addr</VAR>, size_t <VAR>length</VAR>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC221">Setting a Socket's Address</A>.
<P>
<DT><CODE>void * bsearch (const void *<VAR>key</VAR>, const void *<VAR>array</VAR>, size_t <VAR>count</VAR>, size_t <VAR>size</VAR>, comparison_fn_t <VAR>compare</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC88">Array Search Function</A>.
<P>
<DT><CODE>void * bzero (void *<VAR>block</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`string.h'</TT> (BSD):  section <A HREF="library.html#SEC61">Copying and Concatenation</A>.
<P>
<DT><CODE>double cabs (struct { double real, imag; } <VAR>z</VAR>)</CODE>
<DD><TT>`math.h'</TT> (BSD):  section <A HREF="library.html#SEC302">Absolute Value</A>.
<P>
<DT><CODE>void * calloc (size_t <VAR>count</VAR>, size_t <VAR>eltsize</VAR>)</CODE>
<DD><TT>`malloc.h'</TT>, <TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC26">Allocating Cleared Space</A>.
<P>
<DT><CODE>double cbrt (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (GNU):  section <A HREF="library.html#SEC294">Exponentiation and Logarithms</A>.
<P>
<DT><CODE>cc_t</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC273">Terminal Mode Data Types</A>.
<P>
<DT><CODE>double ceil (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC304">Rounding and Remainder Functions</A>.
<P>
<DT><CODE>speed_t cfgetispeed (const struct termios *<VAR>termios_p</VAR>)</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>speed_t cfgetospeed (const struct termios *<VAR>termios_p</VAR>)</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>int cfmakeraw (struct termios *<VAR>termios_p</VAR>)</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>void cfree (void *<VAR>ptr</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (Sun):  section <A HREF="library.html#SEC24">Freeing Memory Allocated with <CODE>malloc</CODE></A>.
<P>
<DT><CODE>int cfsetispeed (struct termios *<VAR>termios_p</VAR>, speed_t <VAR>speed</VAR>)</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>int cfsetospeed (struct termios *<VAR>termios_p</VAR>, speed_t <VAR>speed</VAR>)</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>int cfsetspeed (struct termios *<VAR>termios_p</VAR>, speed_t <VAR>speed</VAR>)</CODE>
<DD><TT>`termios.h'</TT> (BSD):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>int chdir (const char *<VAR>filename</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC188">Working Directory</A>.
<P>
<DT><CODE>int chmod (const char *<VAR>filename</VAR>, mode_t <VAR>mode</VAR>)</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC207">Assigning File Permissions</A>.
<P>
<DT><CODE>int chown (const char *<VAR>filename</VAR>, uid_t <VAR>owner</VAR>, gid_t <VAR>group</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC204">File Owner</A>.
<P>
<DT><CODE>void clearerr (FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC156">End-Of-File and Errors</A>.
<P>
<DT><CODE>clock_t clock (void)</CODE>
<DD><TT>`time.h'</TT> (ANSI):  section <A HREF="library.html#SEC311">Basic CPU Time Inquiry</A>.
<P>
<DT><CODE>clock_t</CODE>
<DD><TT>`time.h'</TT> (ANSI):  section <A HREF="library.html#SEC311">Basic CPU Time Inquiry</A>.
<P>
<DT><CODE>int close (int <VAR>filedes</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC172">Opening and Closing Files</A>.
<P>
<DT><CODE>int closedir (DIR *<VAR>dirstream</VAR>)</CODE>
<DD><TT>`dirent.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC192">Reading and Closing a Directory Stream</A>.
<P>
<DT><CODE>size_t confstr (int <VAR>parameter</VAR>, char *<VAR>buf</VAR>, size_t <VAR>len</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC469">String-Valued Parameters</A>.
<P>
<DT><CODE>int connect (int <VAR>socket</VAR>, struct sockaddr *<VAR>addr</VAR>, size_t <VAR>length</VAR>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC245">Making a Connection</A>.
<P>
<DT><CODE>cookie_close_function</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC170">Custom Stream Hook Functions</A>.
<P>
<DT><CODE>cookie_read_function</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC170">Custom Stream Hook Functions</A>.
<P>
<DT><CODE>cookie_seek_function</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC170">Custom Stream Hook Functions</A>.
<P>
<DT><CODE>cookie_write_function</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC170">Custom Stream Hook Functions</A>.
<P>
<DT><CODE>double copysign (double <VAR>value</VAR>, double <VAR>sign</VAR>)</CODE>
<DD><TT>`math.h'</TT> (BSD):  section <A HREF="library.html#SEC303">Normalization Functions</A>.
<P>
<DT><CODE>double cos (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC292">Trigonometric Functions</A>.
<P>
<DT><CODE>double cosh (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC295">Hyperbolic Functions</A>.
<P>
<DT><CODE>int creat (const char *<VAR>filename</VAR>, mode_t <VAR>mode</VAR>)</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC172">Opening and Closing Files</A>.
<P>
<DT><CODE>char * ctermid (char *<VAR>string</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC426">Identifying the Controlling Terminal</A>.
<P>
<DT><CODE>char * ctime (const time_t *<VAR>time</VAR>)</CODE>
<DD><TT>`time.h'</TT> (ANSI):  section <A HREF="library.html#SEC317">Formatting Date and Time</A>.
<P>
<DT><CODE>char * cuserid (char *<VAR>string</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC440">Identifying Who Logged In</A>.
<P>
<DT><CODE>int daylight</CODE>
<DD><TT>`time.h'</TT> (SVID):  section <A HREF="library.html#SEC319">Functions and Variables for Time Zones</A>.
<P>
<DT><CODE>dev_t</CODE>
<DD><TT>`sys/types.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC201">What the File Attribute Values Mean</A>.
<P>
<DT><CODE>double difftime (time_t <VAR>time1</VAR>, time_t <VAR>time0</VAR>)</CODE>
<DD><TT>`time.h'</TT> (ANSI):  section <A HREF="library.html#SEC314">Simple Calendar Time</A>.
<P>
<DT><CODE>div_t div (int <VAR>numerator</VAR>, int <VAR>denominator</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC305">Integer Division</A>.
<P>
<DT><CODE>div_t</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC305">Integer Division</A>.
<P>
<DT><CODE>double drem (double <VAR>numerator</VAR>, double <VAR>denominator</VAR>)</CODE>
<DD><TT>`math.h'</TT> (BSD):  section <A HREF="library.html#SEC304">Rounding and Remainder Functions</A>.
<P>
<DT><CODE>int dup (int <VAR>old</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC182">Duplicating Descriptors</A>.
<P>
<DT><CODE>int dup2 (int <VAR>old</VAR>, int <VAR>new</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC182">Duplicating Descriptors</A>.
<P>
<DT><CODE>void endgrent (void)</CODE>
<DD><TT>`grp.h'</TT> (SVID, BSD):  section <A HREF="library.html#SEC449">Scanning the List of All Groups</A>.
<P>
<DT><CODE>void endhostent ()</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC233">Host Names</A>.
<P>
<DT><CODE>void endnetent (void)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC267">Networks Database</A>.
<P>
<DT><CODE>void endprotoent (void)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC237">Protocols Database</A>.
<P>
<DT><CODE>void endpwent (void)</CODE>
<DD><TT>`pwd.h'</TT> (SVID, BSD):  section <A HREF="library.html#SEC444">Scanning the List of All Users</A>.
<P>
<DT><CODE>void endservent (void)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC235">The Services Database</A>.
<P>
<DT><CODE>char ** environ</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC393">Environment Access</A>.
<P>
<DT><CODE>volatile int errno</CODE>
<DD><TT>`errno.h'</TT> (ANSI):  section <A HREF="library.html#SEC15">Checking for Errors</A>.
<P>
<DT><CODE>int execl (const char *<VAR>filename</VAR>, const char *<VAR>arg0</VAR>, ...)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC406">Executing a File</A>.
<P>
<DT><CODE>int execle (const char *<VAR>filename</VAR>, const char *<VAR>arg0</VAR>, char *const <VAR>env</VAR><TT>[]</TT>, ...)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC406">Executing a File</A>.
<P>
<DT><CODE>int execlp (const char *<VAR>filename</VAR>, const char *<VAR>arg0</VAR>, ...)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC406">Executing a File</A>.
<P>
<DT><CODE>int execv (const char *<VAR>filename</VAR>, char *const <VAR>argv</VAR><TT>[]</TT>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC406">Executing a File</A>.
<P>
<DT><CODE>int execve (const char *<VAR>filename</VAR>, char *const <VAR>argv</VAR><TT>[]</TT>, char *const <VAR>env</VAR><TT>[]</TT>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC406">Executing a File</A>.
<P>
<DT><CODE>int execvp (const char *<VAR>filename</VAR>, char *const <VAR>argv</VAR><TT>[]</TT>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC406">Executing a File</A>.
<P>
<DT><CODE>void exit (int <VAR>status</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC396">Normal Termination</A>.
<P>
<DT><CODE>double exp (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC294">Exponentiation and Logarithms</A>.
<P>
<DT><CODE>double expm1 (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (BSD):  section <A HREF="library.html#SEC294">Exponentiation and Logarithms</A>.
<P>
<DT><CODE>double fabs (double <VAR>number</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC302">Absolute Value</A>.
<P>
<DT><CODE>int fchmod (int <VAR>filedes</VAR>, int <VAR>mode</VAR>)</CODE>
<DD><TT>`sys/stat.h'</TT> (BSD):  section <A HREF="library.html#SEC207">Assigning File Permissions</A>.
<P>
<DT><CODE>int fchown (int <VAR>filedes</VAR>, int <VAR>owner</VAR>, int <VAR>group</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (BSD):  section <A HREF="library.html#SEC204">File Owner</A>.
<P>
<DT><CODE>int fclean (<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC179">Cleaning Streams</A>.
<P>
<DT><CODE>int fclose (FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC121">Closing Streams</A>.
<P>
<DT><CODE>int fcntl (int <VAR>filedes</VAR>, int <VAR>command</VAR>, ...)</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC181">Control Operations on Files</A>.
<P>
<DT><CODE>fd_set</CODE>
<DD><TT>`sys/types.h'</TT> (BSD):  section <A HREF="library.html#SEC180">Waiting for Input or Output</A>.
<P>
<DT><CODE>FILE * fdopen (int <VAR>filedes</VAR>, const char *<VAR>opentype</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC175">Descriptors and Streams</A>.
<P>
<DT><CODE>int feof (FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC156">End-Of-File and Errors</A>.
<P>
<DT><CODE>int ferror (FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC156">End-Of-File and Errors</A>.
<P>
<DT><CODE>int fflush (FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC162">Flushing Buffers</A>.
<P>
<DT><CODE>int fgetc (FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC123">Character Input</A>.
<P>
<DT><CODE>struct group * fgetgrent (FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`grp.h'</TT> (SVID):  section <A HREF="library.html#SEC449">Scanning the List of All Groups</A>.
<P>
<DT><CODE>int fgetpos (FILE *<VAR>stream</VAR>, fpos_t *<VAR>position</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC159">Portable File-Position Functions</A>.
<P>
<DT><CODE>struct passwd * fgetpwent (FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`pwd.h'</TT> (SVID):  section <A HREF="library.html#SEC444">Scanning the List of All Users</A>.
<P>
<DT><CODE>char * fgets (char *<VAR>s</VAR>, int <VAR>count</VAR>, FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC124">Line-Oriented Input</A>.
<P>
<DT><CODE>int fileno (FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC175">Descriptors and Streams</A>.
<P>
<DT><CODE>int finite (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (BSD):  section <A HREF="library.html#SEC301">Predicates on Floats</A>.
<P>
<DT><CODE>flock</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC185">File Locks</A>.
<P>
<DT><CODE>double floor (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC304">Rounding and Remainder Functions</A>.
<P>
<DT><CODE>FILE * fmemopen (void *<VAR>buf</VAR>, size_t <VAR>size</VAR>, const char *<VAR>opentype</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC166">String Streams</A>.
<P>
<DT><CODE>double fmod (double <VAR>numerator</VAR>, double <VAR>denominator</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC304">Rounding and Remainder Functions</A>.
<P>
<DT><CODE>int fnmatch (const char *<VAR>pattern</VAR>, const char *<VAR>string</VAR>, int <VAR>flags</VAR>)</CODE>
<DD><TT>`fnmatch.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC92">Wildcard Matching</A>.
<P>
<DT><CODE>FILE * fopen (const char *<VAR>filename</VAR>, const char *<VAR>opentype</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC120">Opening Streams</A>.
<P>
<DT><CODE>FILE * fopencookie (void *<VAR>cookie</VAR>, const char *<VAR>opentype</VAR>, struct cookie_functions <VAR>io_functions</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC169">Custom Streams and Cookies</A>.
<P>
<DT><CODE>pid_t fork (void)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC405">Creating a Process</A>.
<P>
<DT><CODE>long int fpathconf (int <VAR>filedes</VAR>, int <VAR>parameter</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC466">Using <CODE>pathconf</CODE></A>.
<P>
<DT><CODE>fpos_t</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC159">Portable File-Position Functions</A>.
<P>
<DT><CODE>int fprintf (FILE *<VAR>stream</VAR>, const char *<VAR>template</VAR>, ...)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC135">Formatted Output Functions</A>.
<P>
<DT><CODE>int fputc (int <VAR>c</VAR>, FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC122">Simple Output by Characters or Lines</A>.
<P>
<DT><CODE>int fputs (const char *<VAR>s</VAR>, FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC122">Simple Output by Characters or Lines</A>.
<P>
<DT><CODE>size_t fread (void *<VAR>data</VAR>, size_t <VAR>size</VAR>, size_t <VAR>count</VAR>, FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC155">Block Input/Output</A>.
<P>
<DT><CODE>void free (void *<VAR>ptr</VAR>)</CODE>
<DD><TT>`malloc.h'</TT>, <TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC24">Freeing Memory Allocated with <CODE>malloc</CODE></A>.
<P>
<DT><CODE>FILE * freopen (const char *<VAR>filename</VAR>, const char *<VAR>opentype</VAR>, FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC120">Opening Streams</A>.
<P>
<DT><CODE>double frexp (double <VAR>value</VAR>, int *<VAR>exponent</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC303">Normalization Functions</A>.
<P>
<DT><CODE>int fscanf (FILE *<VAR>stream</VAR>, const char *<VAR>template</VAR>, ...)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC153">Formatted Input Functions</A>.
<P>
<DT><CODE>int fseek (FILE *<VAR>stream</VAR>, long int <VAR>offset</VAR>, int <VAR>whence</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC158">File Positioning</A>.
<P>
<DT><CODE>int fsetpos (FILE *<VAR>stream</VAR>, const fpos_t <VAR>position</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC159">Portable File-Position Functions</A>.
<P>
<DT><CODE>int fstat (int <VAR>filedes</VAR>, struct stat *<VAR>buf</VAR>)</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC202">Reading the Attributes of a File</A>.
<P>
<DT><CODE>long int ftell (FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC158">File Positioning</A>.
<P>
<DT><CODE>size_t fwrite (const void *<VAR>data</VAR>, size_t <VAR>size</VAR>, size_t <VAR>count</VAR>, FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC155">Block Input/Output</A>.
<P>
<DT><CODE>int getc (FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC123">Character Input</A>.
<P>
<DT><CODE>int getchar (void)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC123">Character Input</A>.
<P>
<DT><CODE>char * getcwd (char *<VAR>buffer</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC188">Working Directory</A>.
<P>
<DT><CODE>ssize_t getdelim (char **<VAR>lineptr</VAR>, size_t *<VAR>n</VAR>, int <VAR>delimiter</VAR>, FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC124">Line-Oriented Input</A>.
<P>
<DT><CODE>gid_t getegid (void)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC434">Reading the Persona of a Process</A>.
<P>
<DT><CODE>char * getenv (const char *<VAR>name</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC393">Environment Access</A>.
<P>
<DT><CODE>uid_t geteuid (void)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC434">Reading the Persona of a Process</A>.
<P>
<DT><CODE>gid_t getgid (void)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC434">Reading the Persona of a Process</A>.
<P>
<DT><CODE>struct group * getgrent (void)</CODE>
<DD><TT>`grp.h'</TT> (SVID, BSD):  section <A HREF="library.html#SEC449">Scanning the List of All Groups</A>.
<P>
<DT><CODE>struct group * getgrgid (gid_t <VAR>gid</VAR>)</CODE>
<DD><TT>`grp.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC448">Looking Up One Group</A>.
<P>
<DT><CODE>struct group * getgrnam (const char *<VAR>name</VAR>)</CODE>
<DD><TT>`grp.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC448">Looking Up One Group</A>.
<P>
<DT><CODE>int getgroups (int <VAR>count</VAR>, gid_t *<VAR>groups</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC434">Reading the Persona of a Process</A>.
<P>
<DT><CODE>struct hostent * gethostbyaddr (const char *<VAR>addr</VAR>, int <VAR>length</VAR>, int <VAR>format</VAR>)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC233">Host Names</A>.
<P>
<DT><CODE>struct hostent * gethostbyname (const char *<VAR>name</VAR>)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC233">Host Names</A>.
<P>
<DT><CODE>struct hostent * gethostent ()</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC233">Host Names</A>.
<P>
<DT><CODE>long int gethostid (void)</CODE>
<DD><TT>`unistd.h'</TT> (BSD):  section <A HREF="library.html#SEC452">Host Identification</A>.
<P>
<DT><CODE>int gethostname (char *<VAR>name</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (BSD):  section <A HREF="library.html#SEC452">Host Identification</A>.
<P>
<DT><CODE>int getitimer (int <VAR>which</VAR>, struct itimerval *<VAR>old</VAR>)</CODE>
<DD><TT>`sys/time.h'</TT> (BSD):  section <A HREF="library.html#SEC321">Setting an Alarm</A>.
<P>
<DT><CODE>ssize_t getline (char **<VAR>lineptr</VAR>, size_t *<VAR>n</VAR>, FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC124">Line-Oriented Input</A>.
<P>
<DT><CODE>char * getlogin (void)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC440">Identifying Who Logged In</A>.
<P>
<DT><CODE>struct netent * getnetbyaddr (long <VAR>net</VAR>, int <VAR>type</VAR>)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC267">Networks Database</A>.
<P>
<DT><CODE>struct netent * getnetbyname (const char *<VAR>name</VAR>)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC267">Networks Database</A>.
<P>
<DT><CODE>struct netent * getnetent (void)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC267">Networks Database</A>.
<P>
<DT><CODE>int getopt (int <VAR>argc</VAR>, char **<VAR>argv</VAR>, const char *<VAR>options</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC388">Parsing Program Options</A>.
<P>
<DT><CODE>int getopt_long (int <VAR>argc</VAR>, char **<VAR>argv</VAR>, const char *<VAR>shortopts</VAR>, struct option *<VAR>longopts</VAR>, int *<VAR>indexptr</VAR>)</CODE>
<DD><TT>`getopt.h'</TT> (GNU):  section <A HREF="library.html#SEC390">Parsing Long Options</A>.
<P>
<DT><CODE>int getpeername (int <VAR>socket</VAR>, struct sockaddr *<VAR>addr</VAR>, size_t *<VAR>length_ptr</VAR>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC248">Who is Connected to Me?</A>.
<P>
<DT><CODE>pid_t getpgrp (pid_t <VAR>pid</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (BSD):  section <A HREF="library.html#SEC427">Process Group Functions</A>.
<P>
<DT><CODE>pid_t getpgrp (void)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC427">Process Group Functions</A>.
<P>
<DT><CODE>pid_t getpid (void)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC404">Process Identification</A>.
<P>
<DT><CODE>pid_t getppid (void)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC404">Process Identification</A>.
<P>
<DT><CODE>int getpriority (int <VAR>class</VAR>, int <VAR>id</VAR>)</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC325">Process Priority</A>.
<P>
<DT><CODE>struct protoent * getprotobyname (const char *<VAR>name</VAR>)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC237">Protocols Database</A>.
<P>
<DT><CODE>struct protoent * getprotobynumber (int <VAR>protocol</VAR>)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC237">Protocols Database</A>.
<P>
<DT><CODE>struct protoent * getprotoent (void)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC237">Protocols Database</A>.
<P>
<DT><CODE>struct passwd * getpwent (void)</CODE>
<DD><TT>`pwd.h'</TT> (SVID, BSD):  section <A HREF="library.html#SEC444">Scanning the List of All Users</A>.
<P>
<DT><CODE>struct passwd * getpwnam (const char *<VAR>name</VAR>)</CODE>
<DD><TT>`pwd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC443">Looking Up One User</A>.
<P>
<DT><CODE>struct passwd * getpwuid (uid_t <VAR>uid</VAR>)</CODE>
<DD><TT>`pwd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC443">Looking Up One User</A>.
<P>
<DT><CODE>int getrlimit (int <VAR>resource</VAR>, struct rlimit *<VAR>rlp</VAR>)</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC324">Limiting Resource Usage</A>.
<P>
<DT><CODE>int getrusage (int <VAR>processes</VAR>, struct rusage *<VAR>rusage</VAR>)</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC323">Resource Usage</A>.
<P>
<DT><CODE>char * gets (char *<VAR>s</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC124">Line-Oriented Input</A>.
<P>
<DT><CODE>struct servent * getservbyname (const char *<VAR>name</VAR>, const char *<VAR>proto</VAR>)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC235">The Services Database</A>.
<P>
<DT><CODE>struct servent * getservbyport (int <VAR>port</VAR>, const char *<VAR>proto</VAR>)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC235">The Services Database</A>.
<P>
<DT><CODE>struct servent * getservent (void)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC235">The Services Database</A>.
<P>
<DT><CODE>int getsockname (int <VAR>socket</VAR>, struct sockaddr *<VAR>addr</VAR>, size_t *<VAR>length_ptr</VAR>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC222">Reading a Socket's Address</A>.
<P>
<DT><CODE>int getsockopt (int <VAR>socket</VAR>, int <VAR>level</VAR>, int <VAR>optname</VAR>, void *<VAR>optval</VAR>, size_t *<VAR>optlen_ptr</VAR>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC265">Socket Option Functions</A>.
<P>
<DT><CODE>int gettimeofday (struct timeval *<VAR>tp</VAR>, struct timezone *<VAR>tzp</VAR>)</CODE>
<DD><TT>`sys/time.h'</TT> (BSD):  section <A HREF="library.html#SEC315">High-Resolution Calendar</A>.
<P>
<DT><CODE>uid_t getuid (void)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC434">Reading the Persona of a Process</A>.
<P>
<DT><CODE>mode_t getumask (void)</CODE>
<DD><TT>`sys/stat.h'</TT> (GNU):  section <A HREF="library.html#SEC207">Assigning File Permissions</A>.
<P>
<DT><CODE>int getw (FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (SVID):  section <A HREF="library.html#SEC123">Character Input</A>.
<P>
<DT><CODE>char * getwd (char *<VAR>buffer</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (BSD):  section <A HREF="library.html#SEC188">Working Directory</A>.
<P>
<DT><CODE>gid_t</CODE>
<DD><TT>`sys/types.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC434">Reading the Persona of a Process</A>.
<P>
<DT><CODE>int glob (const char *<VAR>pattern</VAR>, int <VAR>flags</VAR>, int (*<VAR>errfunc</VAR>) (const char *<VAR>filename</VAR>, int <VAR>error-code</VAR>), glob_t *<VAR>vector_ptr</VAR>)</CODE>
<DD><TT>`glob.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC94">Calling <CODE>glob</CODE></A>.
<P>
<DT><CODE>glob_t</CODE>
<DD><TT>`glob.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC94">Calling <CODE>glob</CODE></A>.
<P>
<DT><CODE>struct tm * gmtime (const time_t *<VAR>time</VAR>)</CODE>
<DD><TT>`time.h'</TT> (ANSI):  section <A HREF="library.html#SEC316">Broken-down Time</A>.
<P>
<DT><CODE>int gsignal (int <VAR>signum</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (SVID):  section <A HREF="library.html#SEC364">Signaling Yourself</A>.
<P>
<DT><CODE>unsigned long int htonl (unsigned long int <VAR>hostlong</VAR>)</CODE>
<DD><TT>`netinet/in.h'</TT> (BSD):  section <A HREF="library.html#SEC236">Byte Order Conversion</A>.
<P>
<DT><CODE>unsigned short int htons (unsigned short int <VAR>hostshort</VAR>)</CODE>
<DD><TT>`netinet/in.h'</TT> (BSD):  section <A HREF="library.html#SEC236">Byte Order Conversion</A>.
<P>
<DT><CODE>double hypot (double <VAR>x</VAR>, double <VAR>y</VAR>)</CODE>
<DD><TT>`math.h'</TT> (BSD):  section <A HREF="library.html#SEC294">Exponentiation and Logarithms</A>.
<P>
<DT><CODE>unsigned long int inet_addr (const char *<VAR>name</VAR>)</CODE>
<DD><TT>`arpa/inet.h'</TT> (BSD):  section <A HREF="library.html#SEC232">Host Address Functions</A>.
<P>
<DT><CODE>int inet_lnaof (struct in_addr <VAR>addr</VAR>)</CODE>
<DD><TT>`arpa/inet.h'</TT> (BSD):  section <A HREF="library.html#SEC232">Host Address Functions</A>.
<P>
<DT><CODE>struct in_addr inet_makeaddr (int <VAR>net</VAR>, int <VAR>local</VAR>)</CODE>
<DD><TT>`arpa/inet.h'</TT> (BSD):  section <A HREF="library.html#SEC232">Host Address Functions</A>.
<P>
<DT><CODE>int inet_netof (struct in_addr <VAR>addr</VAR>)</CODE>
<DD><TT>`arpa/inet.h'</TT> (BSD):  section <A HREF="library.html#SEC232">Host Address Functions</A>.
<P>
<DT><CODE>unsigned long int inet_network (const char *<VAR>name</VAR>)</CODE>
<DD><TT>`arpa/inet.h'</TT> (BSD):  section <A HREF="library.html#SEC232">Host Address Functions</A>.
<P>
<DT><CODE>char * inet_ntoa (struct in_addr <VAR>addr</VAR>)</CODE>
<DD><TT>`arpa/inet.h'</TT> (BSD):  section <A HREF="library.html#SEC232">Host Address Functions</A>.
<P>
<DT><CODE>double infnan (int <VAR>error</VAR>)</CODE>
<DD><TT>`math.h'</TT> (BSD):  section <A HREF="library.html#SEC301">Predicates on Floats</A>.
<P>
<DT><CODE>int initgroups (const char *<VAR>user</VAR>, gid_t <VAR>gid</VAR>)</CODE>
<DD><TT>`grp.h'</TT> (BSD):  section <A HREF="library.html#SEC436">Setting the Group IDs</A>.
<P>
<DT><CODE>void * initstate (unsigned int <VAR>seed</VAR>, void *<VAR>state</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (BSD):  section <A HREF="library.html#SEC298">BSD Random Number Functions</A>.
<P>
<DT><CODE>ino_t</CODE>
<DD><TT>`sys/types.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC201">What the File Attribute Values Mean</A>.
<P>
<DT><CODE>int RLIM_INFINITY</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC324">Limiting Resource Usage</A>.
<P>
<DT><CODE>int isalnum (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (ANSI):  section <A HREF="library.html#SEC55">Classification of Characters</A>.
<P>
<DT><CODE>int isalpha (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (ANSI):  section <A HREF="library.html#SEC55">Classification of Characters</A>.
<P>
<DT><CODE>int isascii (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (SVID, BSD):  section <A HREF="library.html#SEC55">Classification of Characters</A>.
<P>
<DT><CODE>int isatty (int <VAR>filedes</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC269">Identifying Terminals</A>.
<P>
<DT><CODE>int isblank (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (GNU):  section <A HREF="library.html#SEC55">Classification of Characters</A>.
<P>
<DT><CODE>int iscntrl (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (ANSI):  section <A HREF="library.html#SEC55">Classification of Characters</A>.
<P>
<DT><CODE>int isdigit (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (ANSI):  section <A HREF="library.html#SEC55">Classification of Characters</A>.
<P>
<DT><CODE>int isgraph (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (ANSI):  section <A HREF="library.html#SEC55">Classification of Characters</A>.
<P>
<DT><CODE>int isinf (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (BSD):  section <A HREF="library.html#SEC301">Predicates on Floats</A>.
<P>
<DT><CODE>int islower (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (ANSI):  section <A HREF="library.html#SEC55">Classification of Characters</A>.
<P>
<DT><CODE>int isnan (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (BSD):  section <A HREF="library.html#SEC301">Predicates on Floats</A>.
<P>
<DT><CODE>int isprint (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (ANSI):  section <A HREF="library.html#SEC55">Classification of Characters</A>.
<P>
<DT><CODE>int ispunct (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (ANSI):  section <A HREF="library.html#SEC55">Classification of Characters</A>.
<P>
<DT><CODE>int isspace (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (ANSI):  section <A HREF="library.html#SEC55">Classification of Characters</A>.
<P>
<DT><CODE>int isupper (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (ANSI):  section <A HREF="library.html#SEC55">Classification of Characters</A>.
<P>
<DT><CODE>int isxdigit (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (ANSI):  section <A HREF="library.html#SEC55">Classification of Characters</A>.
<P>
<DT><CODE>jmp_buf</CODE>
<DD><TT>`setjmp.h'</TT> (ANSI):  section <A HREF="library.html#SEC328">Details of Non-Local Exits</A>.
<P>
<DT><CODE>int kill (pid_t <VAR>pid</VAR>, int <VAR>signum</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC365">Signaling Another Process</A>.
<P>
<DT><CODE>int killpg (int <VAR>pgid</VAR>, int <VAR>signum</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC365">Signaling Another Process</A>.
<P>
<DT><CODE>long int labs (long int <VAR>number</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC302">Absolute Value</A>.
<P>
<DT><CODE>double ldexp (double <VAR>value</VAR>, int <VAR>exponent</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC303">Normalization Functions</A>.
<P>
<DT><CODE>ldiv_t ldiv (long int <VAR>numerator</VAR>, long int <VAR>denominator</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC305">Integer Division</A>.
<P>
<DT><CODE>ldiv_t</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC305">Integer Division</A>.
<P>
<DT><CODE>int link (const char *<VAR>oldname</VAR>, const char *<VAR>newname</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC195">Hard Links</A>.
<P>
<DT><CODE>int listen (int <VAR>socket</VAR>, unsigned int <VAR>n</VAR>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC246">Listening for Connections</A>.
<P>
<DT><CODE>struct lconv * localeconv (void)</CODE>
<DD><TT>`locale.h'</TT> (ANSI):  section <A HREF="library.html#SEC82">Numeric Formatting</A>.
<P>
<DT><CODE>struct tm * localtime (const time_t *<VAR>time</VAR>)</CODE>
<DD><TT>`time.h'</TT> (ANSI):  section <A HREF="library.html#SEC316">Broken-down Time</A>.
<P>
<DT><CODE>double log (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC294">Exponentiation and Logarithms</A>.
<P>
<DT><CODE>double log10 (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC294">Exponentiation and Logarithms</A>.
<P>
<DT><CODE>double log1p (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (BSD):  section <A HREF="library.html#SEC294">Exponentiation and Logarithms</A>.
<P>
<DT><CODE>double logb (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (BSD):  section <A HREF="library.html#SEC303">Normalization Functions</A>.
<P>
<DT><CODE>void longjmp (jmp_buf <VAR>state</VAR>, int <VAR>value</VAR>)</CODE>
<DD><TT>`setjmp.h'</TT> (ANSI):  section <A HREF="library.html#SEC328">Details of Non-Local Exits</A>.
<P>
<DT><CODE>off_t lseek (int <VAR>filedes</VAR>, off_t <VAR>offset</VAR>, int <VAR>whence</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC174">Setting the File Position of a Descriptor</A>.
<P>
<DT><CODE>int lstat (const char *<VAR>filename</VAR>, struct stat *<VAR>buf</VAR>)</CODE>
<DD><TT>`sys/stat.h'</TT> (BSD):  section <A HREF="library.html#SEC202">Reading the Attributes of a File</A>.
<P>
<DT><CODE>void * malloc (size_t <VAR>size</VAR>)</CODE>
<DD><TT>`malloc.h'</TT>, <TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC22">Basic Storage Allocation</A>.
<P>
<DT><CODE>int mblen (const char *<VAR>string</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC72">Multibyte Character Length</A>.
<P>
<DT><CODE>size_t mbstowcs (wchar_t *<VAR>wstring</VAR>, const char *<VAR>string</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC71">Conversion of Extended Strings</A>.
<P>
<DT><CODE>int mbtowc (wchar_t *<VAR>result</VAR>, const char *<VAR>string</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC73">Conversion of Extended Characters One by One</A>.
<P>
<DT><CODE>void mcheck (void (*<VAR>abortfn</VAR>) (void))</CODE>
<DD><TT>`malloc.h'</TT> (GNU):  section <A HREF="library.html#SEC29">Heap Consistency Checking</A>.
<P>
<DT><CODE>void * memalign (size_t <VAR>size</VAR>, int <VAR>boundary</VAR>)</CODE>
<DD><TT>`malloc.h'</TT>, <TT>`stdlib.h'</TT> (BSD):  section <A HREF="library.html#SEC28">Allocating Aligned Memory Blocks</A>.
<P>
<DT><CODE>void * memccpy (void *<VAR>to</VAR>, const void *<VAR>from</VAR>, int <VAR>c</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`string.h'</TT> (SVID):  section <A HREF="library.html#SEC61">Copying and Concatenation</A>.
<P>
<DT><CODE>void * memchr (const void *<VAR>block</VAR>, int <VAR>c</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC64">Search Functions</A>.
<P>
<DT><CODE>int memcmp (const void *<VAR>a1</VAR>, const void *<VAR>a2</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC62">String/Array Comparison</A>.
<P>
<DT><CODE>void * memcpy (void *<VAR>to</VAR>, const void *<VAR>from</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC61">Copying and Concatenation</A>.
<P>
<DT><CODE>void * memmem (const void *<VAR>needle</VAR>, size_t <VAR>needle_len</VAR>,<BR>const void *<VAR>haystack</VAR>, size_t <VAR>haystack_len</VAR>)</CODE>
<DD><TT>`string.h'</TT> (GNU):  section <A HREF="library.html#SEC64">Search Functions</A>.
<P>
<DT><CODE>void * memmove (void *<VAR>to</VAR>, const void *<VAR>from</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC61">Copying and Concatenation</A>.
<P>
<DT><CODE>void memory_warnings (void *<VAR>start</VAR>, void (*<VAR>warn_func</VAR>) (char *))</CODE>
<DD><TT>`malloc.h'</TT> (GNU):  section <A HREF="library.html#SEC53">Memory Usage Warnings</A>.
<P>
<DT><CODE>void * memset (void *<VAR>block</VAR>, int <VAR>c</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC61">Copying and Concatenation</A>.
<P>
<DT><CODE>int mkdir (const char *<VAR>filename</VAR>, mode_t <VAR>mode</VAR>)</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC199">Creating Directories</A>.
<P>
<DT><CODE>int mkfifo (const char *<VAR>filename</VAR>, mode_t <VAR>mode</VAR>)</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC214">FIFO Special Files</A>.
<P>
<DT><CODE>int mknod (const char *<VAR>filename</VAR>, int <VAR>mode</VAR>, int <VAR>dev</VAR>)</CODE>
<DD><TT>`sys/stat.h'</TT> (BSD):  section <A HREF="library.html#SEC210">Making Special Files</A>.
<P>
<DT><CODE>time_t mktime (struct tm *<VAR>brokentime</VAR>)</CODE>
<DD><TT>`time.h'</TT> (ANSI):  section <A HREF="library.html#SEC316">Broken-down Time</A>.
<P>
<DT><CODE>mode_t</CODE>
<DD><TT>`sys/types.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC201">What the File Attribute Values Mean</A>.
<P>
<DT><CODE>double modf (double <VAR>value</VAR>, double *<VAR>integer_part</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC304">Rounding and Remainder Functions</A>.
<P>
<DT><CODE>struct mstats mstats (void)</CODE>
<DD><TT>`malloc.h'</TT> (GNU):  section <A HREF="library.html#SEC31">Statistics for Storage Allocation with <CODE>malloc</CODE></A>.
<P>
<DT><CODE>int nice (int <VAR>increment</VAR>)</CODE>
<DD><TT>`dunno.h'</TT> (dunno.h):  section <A HREF="library.html#SEC325">Process Priority</A>.
<P>
<DT><CODE>nlink_t</CODE>
<DD><TT>`sys/types.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC201">What the File Attribute Values Mean</A>.
<P>
<DT><CODE>unsigned long int ntohl (unsigned long int <VAR>netlong</VAR>)</CODE>
<DD><TT>`netinet/in.h'</TT> (BSD):  section <A HREF="library.html#SEC236">Byte Order Conversion</A>.
<P>
<DT><CODE>unsigned short int ntohs (unsigned short int <VAR>netshort</VAR>)</CODE>
<DD><TT>`netinet/in.h'</TT> (BSD):  section <A HREF="library.html#SEC236">Byte Order Conversion</A>.
<P>
<DT><CODE>void obstack_1grow (struct obstack *<VAR>obstack_ptr</VAR>, char <VAR>c</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>void obstack_1grow_fast (struct obstack *<VAR>obstack_ptr</VAR>, char <VAR>c</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC40">Extra Fast Growing Objects</A>.
<P>
<DT><CODE>int obstack_alignment_mask (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC42">Alignment of Data in Obstacks</A>.
<P>
<DT><CODE>void * obstack_alloc (struct obstack *<VAR>obstack_ptr</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC36">Allocation in an Obstack</A>.
<P>
<DT><CODE>void * obstack_base (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC41">Status of an Obstack</A>.
<P>
<DT><CODE>void obstack_blank (struct obstack *<VAR>obstack_ptr</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>void obstack_blank_fast (struct obstack *<VAR>obstack_ptr</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC40">Extra Fast Growing Objects</A>.
<P>
<DT><CODE>size_t obstack_chunk_size (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC43">Obstack Chunks</A>.
<P>
<DT><CODE>void * obstack_copy (struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>address</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC36">Allocation in an Obstack</A>.
<P>
<DT><CODE>void * obstack_copy0 (struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>address</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC36">Allocation in an Obstack</A>.
<P>
<DT><CODE>void * obstack_finish (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>void obstack_free (struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>object</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC37">Freeing Objects in an Obstack</A>.
<P>
<DT><CODE>void obstack_grow (struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>data</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>void obstack_grow0 (struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>data</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>void obstack_init (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC35">Preparing for Using Obstacks</A>.
<P>
<DT><CODE>void * obstack_next_free (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC41">Status of an Obstack</A>.
<P>
<DT><CODE>size_t obstack_object_size (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>size_t obstack_object_size (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC41">Status of an Obstack</A>.
<P>
<DT><CODE>int obstack_printf (struct obstack *<VAR>obstack</VAR>, const char *<VAR>template</VAR>, ...)</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC136">Dynamically Allocating Formatted Output</A>.
<P>
<DT><CODE>size_t obstack_room (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC40">Extra Fast Growing Objects</A>.
<P>
<DT><CODE>int obstack_vprintf (struct obstack *<VAR>obstack</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC137">Variable Arguments Output Functions</A>.
<P>
<DT><CODE>off_t</CODE>
<DD><TT>`sys/types.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC174">Setting the File Position of a Descriptor</A>.
<P>
<DT><CODE>size_t offsetof (<VAR>type</VAR>, <VAR>member</VAR>)</CODE>
<DD><TT>`stddef.h'</TT> (ANSI):  section <A HREF="library.html#SEC491">Structure Field Offset Measurement</A>.
<P>
<DT><CODE>int on_exit (void (*<VAR>function</VAR>)(int <VAR>status</VAR>, void *<VAR>arg</VAR>), void *<VAR>arg</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (SunOS):  section <A HREF="library.html#SEC398">Cleanups on Exit</A>.
<P>
<DT><CODE>int open (const char *<VAR>filename</VAR>, int <VAR>flags</VAR>[, mode_t <VAR>mode</VAR>])</CODE>
<DD><TT>`fcntl.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC172">Opening and Closing Files</A>.
<P>
<DT><CODE>FILE * open_memstream (char **<VAR>ptr</VAR>, size_t *<VAR>sizeloc</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC166">String Streams</A>.
<P>
<DT><CODE>FILE * open_obstack_stream (struct obstack *<VAR>obstack</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC167">Obstack Streams</A>.
<P>
<DT><CODE>DIR * opendir (const char *<VAR>dirname</VAR>)</CODE>
<DD><TT>`dirent.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC191">Opening a Directory Stream</A>.
<P>
<DT><CODE>char * optarg</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC388">Parsing Program Options</A>.
<P>
<DT><CODE>int opterr</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC388">Parsing Program Options</A>.
<P>
<DT><CODE>int optind</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC388">Parsing Program Options</A>.
<P>
<DT><CODE>int optopt</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC388">Parsing Program Options</A>.
<P>
<DT><CODE>size_t parse_printf_format (const char *<VAR>template</VAR>, size_t <VAR>n</VAR>, int *<VAR>argtypes</VAR>)</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC138">Parsing a Template String</A>.
<P>
<DT><CODE>long int pathconf (const char *<VAR>filename</VAR>, int <VAR>parameter</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC466">Using <CODE>pathconf</CODE></A>.
<P>
<DT><CODE>int pause ()</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC377">Using <CODE>pause</CODE></A>.
<P>
<DT><CODE>int pclose (FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (POSIX.2, SVID, BSD):  section <A HREF="library.html#SEC213">Pipe to a Subprocess</A>.
<P>
<DT><CODE>void perror (const char *<VAR>message</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC17">Error Messages</A>.
<P>
<DT><CODE>pid_t</CODE>
<DD><TT>`sys/types.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC404">Process Identification</A>.
<P>
<DT><CODE>int pipe (int <VAR>filedes</VAR><TT>[2]</TT>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC212">Creating a Pipe</A>.
<P>
<DT><CODE>FILE * popen (const char *<VAR>command</VAR>, const char *<VAR>mode</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (POSIX.2, SVID, BSD):  section <A HREF="library.html#SEC213">Pipe to a Subprocess</A>.
<P>
<DT><CODE>double pow (double <VAR>base</VAR>, double <VAR>power</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC294">Exponentiation and Logarithms</A>.
<P>
<DT><CODE>int printf (const char *<VAR>template</VAR>, ...)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC135">Formatted Output Functions</A>.
<P>
<DT><CODE>printf_arginfo_function</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC143">Defining the Output Handler</A>.
<P>
<DT><CODE>printf_function</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC143">Defining the Output Handler</A>.
<P>
<DT><CODE>char * program_invocation_name</CODE>
<DD><TT>`errno.h'</TT> (GNU):  section <A HREF="library.html#SEC17">Error Messages</A>.
<P>
<DT><CODE>char * program_invocation_short_name</CODE>
<DD><TT>`errno.h'</TT> (GNU):  section <A HREF="library.html#SEC17">Error Messages</A>.
<P>
<DT><CODE>void psignal (int <VAR>signum</VAR>, const char *<VAR>message</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (BSD):  section <A HREF="library.html#SEC343">Signal Messages</A>.
<P>
<DT><CODE>ptrdiff_t</CODE>
<DD><TT>`stddef.h'</TT> (ANSI):  section <A HREF="library.html#SEC483">Important Data Types</A>.
<P>
<DT><CODE>int putc (int <VAR>c</VAR>, FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC122">Simple Output by Characters or Lines</A>.
<P>
<DT><CODE>int putchar (int <VAR>c</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC122">Simple Output by Characters or Lines</A>.
<P>
<DT><CODE>int putenv (const char *<VAR>string</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (SVID):  section <A HREF="library.html#SEC393">Environment Access</A>.
<P>
<DT><CODE>int putpwent (const struct passwd *<VAR>p</VAR>, FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`pwd.h'</TT> (SVID):  section <A HREF="library.html#SEC445">Writing a User Entry</A>.
<P>
<DT><CODE>int puts (const char *<VAR>s</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC122">Simple Output by Characters or Lines</A>.
<P>
<DT><CODE>int putw (int <VAR>w</VAR>, FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (SVID):  section <A HREF="library.html#SEC122">Simple Output by Characters or Lines</A>.
<P>
<DT><CODE>void qsort (void *<VAR>array</VAR>, size_t <VAR>count</VAR>, size_t <VAR>size</VAR>, comparison_fn_t <VAR>compare</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC89">Array Sort Function</A>.
<P>
<DT><CODE>void * r_alloc (void **<VAR>handleptr</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`malloc.h'</TT> (GNU):  section <A HREF="library.html#SEC52">Allocating and Freeing Relocatable Blocks</A>.
<P>
<DT><CODE>void r_alloc_free (void **<VAR>handleptr</VAR>)</CODE>
<DD><TT>`malloc.h'</TT> (GNU):  section <A HREF="library.html#SEC52">Allocating and Freeing Relocatable Blocks</A>.
<P>
<DT><CODE>void * r_re_alloc (void **<VAR>handleptr</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`malloc.h'</TT> (GNU):  section <A HREF="library.html#SEC52">Allocating and Freeing Relocatable Blocks</A>.
<P>
<DT><CODE>int raise (int <VAR>signum</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (ANSI):  section <A HREF="library.html#SEC364">Signaling Yourself</A>.
<P>
<DT><CODE>int rand ()</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC297">ANSI C Random Number Functions</A>.
<P>
<DT><CODE>long int random ()</CODE>
<DD><TT>`stdlib.h'</TT> (BSD):  section <A HREF="library.html#SEC298">BSD Random Number Functions</A>.
<P>
<DT><CODE>ssize_t read (int <VAR>filedes</VAR>, void *<VAR>buffer</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC173">Input and Output Primitives</A>.
<P>
<DT><CODE>struct dirent * readdir (DIR *<VAR>dirstream</VAR>)</CODE>
<DD><TT>`dirent.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC192">Reading and Closing a Directory Stream</A>.
<P>
<DT><CODE>int readlink (const char *<VAR>filename</VAR>, char *<VAR>buffer</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (BSD):  section <A HREF="library.html#SEC196">Symbolic Links</A>.
<P>
<DT><CODE>void * realloc (void *<VAR>ptr</VAR>, size_t <VAR>newsize</VAR>)</CODE>
<DD><TT>`malloc.h'</TT>, <TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC25">Changing the Size of a Block</A>.
<P>
<DT><CODE>int recv (int <VAR>socket</VAR>, void *<VAR>buffer</VAR>, size_t <VAR>size</VAR>, int <VAR>flags</VAR>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC251">Receiving Data</A>.
<P>
<DT><CODE>int recvfrom (int <VAR>socket</VAR>, void *<VAR>buffer</VAR>, size_t <VAR>size</VAR>, int <VAR>flags</VAR>, struct sockaddr *<VAR>addr</VAR>, size_t *<VAR>length_ptr</VAR>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC258">Receiving Datagrams</A>.
<P>
<DT><CODE>int recvmsg (int <VAR>socket</VAR>, struct msghdr *<VAR>message</VAR>, int <VAR>flags</VAR>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC258">Receiving Datagrams</A>.
<P>
<DT><CODE>int regcomp (regex_t *<VAR>compiled</VAR>, const char *<VAR>pattern</VAR>, int <VAR>cflags</VAR>)</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC97">POSIX Regular Expression Compilation</A>.
<P>
<DT><CODE>size_t regerror (int <VAR>errcode</VAR>, regex_t *<VAR>compiled</VAR>, char *<VAR>buffer</VAR>, size_t <VAR>length</VAR>)</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC102">POSIX Regexp Matching Cleanup</A>.
<P>
<DT><CODE>regex_t</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC97">POSIX Regular Expression Compilation</A>.
<P>
<DT><CODE>int regexec (regex_t *<VAR>compiled</VAR>, char *<VAR>string</VAR>, size_t <VAR>nmatch</VAR>, regmatch_t <VAR>matchptr</VAR> <TT>[]</TT>, int <VAR>eflags</VAR>)</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC99">Matching a Compiled POSIX Regular Expression</A>.
<P>
<DT><CODE>void regfree (regex_t *<VAR>compiled</VAR>)</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC102">POSIX Regexp Matching Cleanup</A>.
<P>
<DT><CODE>int register_printf_function (int <VAR>spec</VAR>, printf_function <VAR>handler_function</VAR>, printf_arginfo_function <VAR>arginfo_function</VAR>)</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC141">Registering New Conversions</A>.
<P>
<DT><CODE>regmatch_t</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC100">Subexpressions Match Results</A>.
<P>
<DT><CODE>regoff_t</CODE>
<DD><TT>`regex.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC100">Subexpressions Match Results</A>.
<P>
<DT><CODE>int remove (const char *<VAR>filename</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC197">Deleting Files</A>.
<P>
<DT><CODE>int rename (const char *<VAR>oldname</VAR>, const char *<VAR>newname</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC198">Renaming Files</A>.
<P>
<DT><CODE>void rewind (FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC158">File Positioning</A>.
<P>
<DT><CODE>void rewinddir (DIR *<VAR>dirstream</VAR>)</CODE>
<DD><TT>`dirent.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC194">Random Access in a Directory Stream</A>.
<P>
<DT><CODE>double rint (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (BSD):  section <A HREF="library.html#SEC304">Rounding and Remainder Functions</A>.
<P>
<DT><CODE>int rmdir (const char *<VAR>filename</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC197">Deleting Files</A>.
<P>
<DT><CODE>double scalb (double <VAR>value</VAR>, int <VAR>exponent</VAR>)</CODE>
<DD><TT>`math.h'</TT> (BSD):  section <A HREF="library.html#SEC303">Normalization Functions</A>.
<P>
<DT><CODE>int scanf (const char *<VAR>template</VAR>, ...)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC153">Formatted Input Functions</A>.
<P>
<DT><CODE>void seekdir (DIR *<VAR>dirstream</VAR>, off_t <VAR>pos</VAR>)</CODE>
<DD><TT>`dirent.h'</TT> (BSD):  section <A HREF="library.html#SEC194">Random Access in a Directory Stream</A>.
<P>
<DT><CODE>int select (int <VAR>nfds</VAR>, fd_set *<VAR>read_fds</VAR>, fd_set *<VAR>write_fds</VAR>, fd_set *<VAR>except_fds</VAR>, struct timeval *<VAR>timeout</VAR>)</CODE>
<DD><TT>`sys/types.h'</TT> (BSD):  section <A HREF="library.html#SEC180">Waiting for Input or Output</A>.
<P>
<DT><CODE>int send (int <VAR>socket</VAR>, void *<VAR>buffer</VAR>, size_t <VAR>size</VAR>, int <VAR>flags</VAR>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC250">Sending Data</A>.
<P>
<DT><CODE>int sendmsg (int <VAR>socket</VAR>, const struct msghdr *<VAR>message</VAR>, int <VAR>flags</VAR>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC258">Receiving Datagrams</A>.
<P>
<DT><CODE>int sendto (int <VAR>socket</VAR>, void *<VAR>buffer</VAR>. size_t <VAR>size</VAR>, int <VAR>flags</VAR>, struct sockaddr *<VAR>addr</VAR>, size_t <VAR>length</VAR>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC257">Sending Datagrams</A>.
<P>
<DT><CODE>void setbuf (FILE *<VAR>stream</VAR>, char *<VAR>buf</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC163">Controlling Which Kind of Buffering</A>.
<P>
<DT><CODE>void setbuffer (FILE *<VAR>stream</VAR>, char *<VAR>buf</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (BSD):  section <A HREF="library.html#SEC163">Controlling Which Kind of Buffering</A>.
<P>
<DT><CODE>int setgid (gid_t <VAR>newgid</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC436">Setting the Group IDs</A>.
<P>
<DT><CODE>void setgrent (void)</CODE>
<DD><TT>`grp.h'</TT> (SVID, BSD):  section <A HREF="library.html#SEC449">Scanning the List of All Groups</A>.
<P>
<DT><CODE>int setgroups (size_t <VAR>count</VAR>, gid_t *<VAR>groups</VAR>)</CODE>
<DD><TT>`grp.h'</TT> (BSD):  section <A HREF="library.html#SEC436">Setting the Group IDs</A>.
<P>
<DT><CODE>void sethostent (int <VAR>stayopen</VAR>)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC233">Host Names</A>.
<P>
<DT><CODE>int sethostid (long int <VAR>id</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (BSD):  section <A HREF="library.html#SEC452">Host Identification</A>.
<P>
<DT><CODE>int sethostname (const char *<VAR>name</VAR>, size_t <VAR>length</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (BSD):  section <A HREF="library.html#SEC452">Host Identification</A>.
<P>
<DT><CODE>int setitimer (int <VAR>which</VAR>, struct itimerval *<VAR>old</VAR>, struct itimerval *<VAR>new</VAR>)</CODE>
<DD><TT>`sys/time.h'</TT> (BSD):  section <A HREF="library.html#SEC321">Setting an Alarm</A>.
<P>
<DT><CODE>int setjmp (jmp_buf <VAR>state</VAR>)</CODE>
<DD><TT>`setjmp.h'</TT> (ANSI):  section <A HREF="library.html#SEC328">Details of Non-Local Exits</A>.
<P>
<DT><CODE>void setlinebuf (FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (BSD):  section <A HREF="library.html#SEC163">Controlling Which Kind of Buffering</A>.
<P>
<DT><CODE>char * setlocale (int <VAR>category</VAR>, const char *<VAR>locale</VAR>)</CODE>
<DD><TT>`locale.h'</TT> (ANSI):  section <A HREF="library.html#SEC80">How Programs Set the Locale</A>.
<P>
<DT><CODE>void setnetent (int <VAR>stayopen</VAR>)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC267">Networks Database</A>.
<P>
<DT><CODE>int setpgid (pid_t <VAR>pid</VAR>, pid_t <VAR>pgid</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC427">Process Group Functions</A>.
<P>
<DT><CODE>int setpgrp (pid_t <VAR>pid</VAR>, pid_t <VAR>pgid</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (BSD):  section <A HREF="library.html#SEC427">Process Group Functions</A>.
<P>
<DT><CODE>int setpriority (int <VAR>class</VAR>, int <VAR>id</VAR>, int <VAR>priority</VAR>)</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC325">Process Priority</A>.
<P>
<DT><CODE>void setprotoent (int <VAR>stayopen</VAR>)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC237">Protocols Database</A>.
<P>
<DT><CODE>void setpwent (void)</CODE>
<DD><TT>`pwd.h'</TT> (SVID, BSD):  section <A HREF="library.html#SEC444">Scanning the List of All Users</A>.
<P>
<DT><CODE>int setregid (gid_t <VAR>rgid</VAR>, fid_t <VAR>egid</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (BSD):  section <A HREF="library.html#SEC436">Setting the Group IDs</A>.
<P>
<DT><CODE>int setreuid (uid_t <VAR>ruid</VAR>, uid_t <VAR>euid</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (BSD):  section <A HREF="library.html#SEC435">Setting the User ID</A>.
<P>
<DT><CODE>int setrlimit (int <VAR>resource</VAR>, struct rlimit *<VAR>rlp</VAR>)</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC324">Limiting Resource Usage</A>.
<P>
<DT><CODE>void setservent (int <VAR>stayopen</VAR>)</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC235">The Services Database</A>.
<P>
<DT><CODE>pid_t setsid (void)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC427">Process Group Functions</A>.
<P>
<DT><CODE>int setsockopt (int <VAR>socket</VAR>, int <VAR>level</VAR>, int <VAR>optname</VAR>, void *<VAR>optval</VAR>, size_t <VAR>optlen</VAR>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC265">Socket Option Functions</A>.
<P>
<DT><CODE>void * setstate (void *<VAR>state</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (BSD):  section <A HREF="library.html#SEC298">BSD Random Number Functions</A>.
<P>
<DT><CODE>int settimeofday (const struct timeval *<VAR>tp</VAR>, const struct timezone *<VAR>tzp</VAR>)</CODE>
<DD><TT>`sys/time.h'</TT> (BSD):  section <A HREF="library.html#SEC315">High-Resolution Calendar</A>.
<P>
<DT><CODE>int setuid (uid_t <VAR>newuid</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC435">Setting the User ID</A>.
<P>
<DT><CODE>int setvbuf (FILE *<VAR>stream</VAR>, char *<VAR>buf</VAR>, int <VAR>mode</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC163">Controlling Which Kind of Buffering</A>.
<P>
<DT><CODE>int shutdown (int <VAR>socket</VAR>, int <VAR>how</VAR>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC242">Closing a Socket</A>.
<P>
<DT><CODE>sig_atomic_t</CODE>
<DD><TT>`signal.h'</TT> (ANSI):  section <A HREF="library.html#SEC360">Atomic Types</A>.
<P>
<DT><CODE>int sigaction (int <VAR>signum</VAR>, const struct sigaction *<VAR>action</VAR>, struct sigaction *<VAR>old_action</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC346">Advanced Signal Handling</A>.
<P>
<DT><CODE>int sigaddset (sigset_t *<VAR>set</VAR>, int <VAR>signum</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC370">Signal Sets</A>.
<P>
<DT><CODE>int sigblock (int <VAR>mask</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC383">BSD Functions for Blocking Signals</A>.
<P>
<DT><CODE>int sigdelset (sigset_t *<VAR>set</VAR>, int <VAR>signum</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC370">Signal Sets</A>.
<P>
<DT><CODE>int sigemptyset (sigset_t *<VAR>set</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC370">Signal Sets</A>.
<P>
<DT><CODE>int sigfillset (sigset_t *<VAR>set</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC370">Signal Sets</A>.
<P>
<DT><CODE>sighandler_t</CODE>
<DD><TT>`signal.h'</TT> (GNU):  section <A HREF="library.html#SEC345">Basic Signal Handling</A>.
<P>
<DT><CODE>int siginterrupt (int <VAR>signum</VAR>, int <VAR>failflag</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC382">BSD Function to Establish a Handler</A>.
<P>
<DT><CODE>int sigismember (const sigset_t *<VAR>set</VAR>, int <VAR>signum</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC370">Signal Sets</A>.
<P>
<DT><CODE>sigjmp_buf</CODE>
<DD><TT>`setjmp.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC329">Non-Local Exits and Signals</A>.
<P>
<DT><CODE>void siglongjmp (sigjmp_buf <VAR>state</VAR>, int <VAR>value</VAR>)</CODE>
<DD><TT>`setjmp.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC329">Non-Local Exits and Signals</A>.
<P>
<DT><CODE>int sigmask (int <VAR>signum</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC383">BSD Functions for Blocking Signals</A>.
<P>
<DT><CODE>sighandler_t signal (int <VAR>signum</VAR>, sighandler_t <VAR>action</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (ANSI):  section <A HREF="library.html#SEC345">Basic Signal Handling</A>.
<P>
<DT><CODE>int sigpause (int <VAR>mask</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC383">BSD Functions for Blocking Signals</A>.
<P>
<DT><CODE>int sigpending (sigset_t *<VAR>set</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC374">Checking for Pending Signals</A>.
<P>
<DT><CODE>int sigprocmask (int <VAR>how</VAR>, const sigset_t *<VAR>set</VAR>, sigset_t *<VAR>oldset</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC371">Process Signal Mask</A>.
<P>
<DT><CODE>sigset_t</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC370">Signal Sets</A>.
<P>
<DT><CODE>int sigsetjmp (sigjmp_buf <VAR>state</VAR>, int <VAR>savesigs</VAR>)</CODE>
<DD><TT>`setjmp.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC329">Non-Local Exits and Signals</A>.
<P>
<DT><CODE>int sigsetmask (int <VAR>mask</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC383">BSD Functions for Blocking Signals</A>.
<P>
<DT><CODE>int sigstack (const struct sigstack *<VAR>stack</VAR>, struct sigstack *<VAR>oldstack</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC384">Using a Separate Signal Stack</A>.
<P>
<DT><CODE>int sigsuspend (const sigset_t *<VAR>set</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC379">Using <CODE>sigsuspend</CODE></A>.
<P>
<DT><CODE>int sigvec (int <VAR>signum</VAR>, const struct sigvec *<VAR>action</VAR>,struct sigvec *<VAR>old_action</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC382">BSD Function to Establish a Handler</A>.
<P>
<DT><CODE>double sin (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC292">Trigonometric Functions</A>.
<P>
<DT><CODE>double sinh (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC295">Hyperbolic Functions</A>.
<P>
<DT><CODE>size_t</CODE>
<DD><TT>`stddef.h'</TT> (ANSI):  section <A HREF="library.html#SEC483">Important Data Types</A>.
<P>
<DT><CODE>unsigned int sleep (unsigned int <VAR>seconds</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC322">Sleeping</A>.
<P>
<DT><CODE>int snprintf (char *<VAR>s</VAR>, size_t <VAR>size</VAR>, const char *<VAR>template</VAR>, ...)</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC135">Formatted Output Functions</A>.
<P>
<DT><CODE>int socket (int <VAR>namespace</VAR>, int <VAR>style</VAR>, int <VAR>protocol</VAR>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC241">Creating a Socket</A>.
<P>
<DT><CODE>int socketpair (int <VAR>namespace</VAR>, int <VAR>style</VAR>, int <VAR>protocol</VAR>, int <VAR>filedes</VAR><TT>[2]</TT>)</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC243">Socket Pairs</A>.
<P>
<DT><CODE>speed_t</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC280">Line Speed</A>.
<P>
<DT><CODE>int sprintf (char *<VAR>s</VAR>, const char *<VAR>template</VAR>, ...)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC135">Formatted Output Functions</A>.
<P>
<DT><CODE>double sqrt (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC294">Exponentiation and Logarithms</A>.
<P>
<DT><CODE>void srand (unsigned int <VAR>seed</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC297">ANSI C Random Number Functions</A>.
<P>
<DT><CODE>void srandom (unsigned int <VAR>seed</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (BSD):  section <A HREF="library.html#SEC298">BSD Random Number Functions</A>.
<P>
<DT><CODE>int sscanf (const char *<VAR>s</VAR>, const char *<VAR>template</VAR>, ...)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC153">Formatted Input Functions</A>.
<P>
<DT><CODE>sighandler_t ssignal (int <VAR>signum</VAR>, sighandler_t <VAR>action</VAR>)</CODE>
<DD><TT>`signal.h'</TT> (SVID):  section <A HREF="library.html#SEC345">Basic Signal Handling</A>.
<P>
<DT><CODE>ssize_t</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC173">Input and Output Primitives</A>.
<P>
<DT><CODE>int stat (const char *<VAR>filename</VAR>, struct stat *<VAR>buf</VAR>)</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC202">Reading the Attributes of a File</A>.
<P>
<DT><CODE>FILE * stderr</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC119">Standard Streams</A>.
<P>
<DT><CODE>FILE * stdin</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC119">Standard Streams</A>.
<P>
<DT><CODE>FILE * stdout</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC119">Standard Streams</A>.
<P>
<DT><CODE>char * stpcpy (char *<VAR>to</VAR>, const char *<VAR>from</VAR>)</CODE>
<DD><TT>`string.h'</TT> (Unknown origin):  section <A HREF="library.html#SEC61">Copying and Concatenation</A>.
<P>
<DT><CODE>int strcasecmp (const char *<VAR>s1</VAR>, const char *<VAR>s2</VAR>)</CODE>
<DD><TT>`string.h'</TT> (BSD):  section <A HREF="library.html#SEC62">String/Array Comparison</A>.
<P>
<DT><CODE>char * strcat (char *<VAR>to</VAR>, const char *<VAR>from</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC61">Copying and Concatenation</A>.
<P>
<DT><CODE>char * strchr (const char *<VAR>string</VAR>, int <VAR>c</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC64">Search Functions</A>.
<P>
<DT><CODE>int strcmp (const char *<VAR>s1</VAR>, const char *<VAR>s2</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC62">String/Array Comparison</A>.
<P>
<DT><CODE>int strcoll (const char *<VAR>s1</VAR>, const char *<VAR>s2</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC63">Collation Functions</A>.
<P>
<DT><CODE>char * strcpy (char *<VAR>to</VAR>, const char *<VAR>from</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC61">Copying and Concatenation</A>.
<P>
<DT><CODE>size_t strcspn (const char *<VAR>string</VAR>, const char *<VAR>stopset</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC64">Search Functions</A>.
<P>
<DT><CODE>char * strdup (const char *<VAR>s</VAR>)</CODE>
<DD><TT>`string.h'</TT> (SVID):  section <A HREF="library.html#SEC61">Copying and Concatenation</A>.
<P>
<DT><CODE>char * strerror (int <VAR>errnum</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC17">Error Messages</A>.
<P>
<DT><CODE>size_t strftime (char *<VAR>s</VAR>, size_t <VAR>size</VAR>, const char *<VAR>template</VAR>, const struct tm *<VAR>brokentime</VAR>)</CODE>
<DD><TT>`time.h'</TT> (ANSI):  section <A HREF="library.html#SEC317">Formatting Date and Time</A>.
<P>
<DT><CODE>size_t strlen (const char *<VAR>s</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC60">String Length</A>.
<P>
<DT><CODE>int strncasecmp (const char *<VAR>s1</VAR>, const char *<VAR>s2</VAR>, size_t <VAR>n</VAR>)</CODE>
<DD><TT>`string.h'</TT> (BSD):  section <A HREF="library.html#SEC62">String/Array Comparison</A>.
<P>
<DT><CODE>char * strncat (char *<VAR>to</VAR>, const char *<VAR>from</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC61">Copying and Concatenation</A>.
<P>
<DT><CODE>int strncmp (const char *<VAR>s1</VAR>, const char *<VAR>s2</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC62">String/Array Comparison</A>.
<P>
<DT><CODE>char * strncpy (char *<VAR>to</VAR>, const char *<VAR>from</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC61">Copying and Concatenation</A>.
<P>
<DT><CODE>char * strpbrk (const char *<VAR>string</VAR>, const char *<VAR>stopset</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC64">Search Functions</A>.
<P>
<DT><CODE>char * strrchr (const char *<VAR>string</VAR>, int <VAR>c</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC64">Search Functions</A>.
<P>
<DT><CODE>char * strsignal (int <VAR>signum</VAR>)</CODE>
<DD><TT>`string.h'</TT> (GNU):  section <A HREF="library.html#SEC343">Signal Messages</A>.
<P>
<DT><CODE>size_t strspn (const char *<VAR>string</VAR>, const char *<VAR>skipset</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC64">Search Functions</A>.
<P>
<DT><CODE>char * strstr (const char *<VAR>haystack</VAR>, const char *<VAR>needle</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC64">Search Functions</A>.
<P>
<DT><CODE>double strtod (const char *<VAR>string</VAR>, char **<VAR>tailptr</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC308">Parsing of Floats</A>.
<P>
<DT><CODE>char * strtok (char *<VAR>newstring</VAR>, const char *<VAR>delimiters</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC65">Finding Tokens in a String</A>.
<P>
<DT><CODE>long int strtol (const char *<VAR>string</VAR>, char **<VAR>tailptr</VAR>, int <VAR>base</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC307">Parsing of Integers</A>.
<P>
<DT><CODE>unsigned long int strtoul (const char *<VAR>string</VAR>, char **<VAR>tailptr</VAR>, int <VAR>base</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC307">Parsing of Integers</A>.
<P>
<DT><CODE>struct cookie_io_functions</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC169">Custom Streams and Cookies</A>.
<P>
<DT><CODE>struct dirent</CODE>
<DD><TT>`dirent.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC190">Format of a Directory Entry</A>.
<P>
<DT><CODE>struct group</CODE>
<DD><TT>`grp.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC447">The Data Structure for a Group</A>.
<P>
<DT><CODE>struct hostent</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC233">Host Names</A>.
<P>
<DT><CODE>struct in_addr</CODE>
<DD><TT>`netinet/in.h'</TT> (BSD):  section <A HREF="library.html#SEC231">Host Address Data Type</A>.
<P>
<DT><CODE>struct itimerval</CODE>
<DD><TT>`sys/time.h'</TT> (BSD):  section <A HREF="library.html#SEC321">Setting an Alarm</A>.
<P>
<DT><CODE>struct lconv</CODE>
<DD><TT>`locale.h'</TT> (ANSI):  section <A HREF="library.html#SEC82">Numeric Formatting</A>.
<P>
<DT><CODE>struct linger</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC266">Socket-Level Options</A>.
<P>
<DT><CODE>struct msghdr</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC258">Receiving Datagrams</A>.
<P>
<DT><CODE>struct mstats</CODE>
<DD><TT>`malloc.h'</TT> (GNU):  section <A HREF="library.html#SEC31">Statistics for Storage Allocation with <CODE>malloc</CODE></A>.
<P>
<DT><CODE>struct netent</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC267">Networks Database</A>.
<P>
<DT><CODE>struct obstack</CODE>
<DD><TT>`obstack.h'</TT> (GNU):  section <A HREF="library.html#SEC34">Creating Obstacks</A>.
<P>
<DT><CODE>struct option</CODE>
<DD><TT>`getopt.h'</TT> (GNU):  section <A HREF="library.html#SEC390">Parsing Long Options</A>.
<P>
<DT><CODE>struct passwd</CODE>
<DD><TT>`pwd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC442">The Data Structure that Describes a User</A>.
<P>
<DT><CODE>struct printf_info</CODE>
<DD><TT>`printf.h'</TT> (GNU):  section <A HREF="library.html#SEC142">Conversion Specifier Options</A>.
<P>
<DT><CODE>struct protoent</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC237">Protocols Database</A>.
<P>
<DT><CODE>struct rlimit</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC324">Limiting Resource Usage</A>.
<P>
<DT><CODE>struct rusage</CODE>
<DD><TT>`sys/resource.h'</TT> (BSD):  section <A HREF="library.html#SEC323">Resource Usage</A>.
<P>
<DT><CODE>struct servent</CODE>
<DD><TT>`netdb.h'</TT> (BSD):  section <A HREF="library.html#SEC235">The Services Database</A>.
<P>
<DT><CODE>struct sigaction</CODE>
<DD><TT>`signal.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC346">Advanced Signal Handling</A>.
<P>
<DT><CODE>struct sigstack</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC384">Using a Separate Signal Stack</A>.
<P>
<DT><CODE>struct sigvec</CODE>
<DD><TT>`signal.h'</TT> (BSD):  section <A HREF="library.html#SEC382">BSD Function to Establish a Handler</A>.
<P>
<DT><CODE>struct sockaddr</CODE>
<DD><TT>`sys/socket.h'</TT> (BSD):  section <A HREF="library.html#SEC220">Address Formats</A>.
<P>
<DT><CODE>struct sockaddr_in</CODE>
<DD><TT>`netinet/in.h'</TT> (BSD):  section <A HREF="library.html#SEC228">Internet Socket Address Format</A>.
<P>
<DT><CODE>struct sockaddr_un</CODE>
<DD><TT>`sys/un.h'</TT> (BSD):  section <A HREF="library.html#SEC225">Details of File Namespace</A>.
<P>
<DT><CODE>struct stat</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC201">What the File Attribute Values Mean</A>.
<P>
<DT><CODE>struct termios</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC273">Terminal Mode Data Types</A>.
<P>
<DT><CODE>struct timeval</CODE>
<DD><TT>`sys/time.h'</TT> (BSD):  section <A HREF="library.html#SEC315">High-Resolution Calendar</A>.
<P>
<DT><CODE>struct timezone</CODE>
<DD><TT>`sys/time.h'</TT> (BSD):  section <A HREF="library.html#SEC315">High-Resolution Calendar</A>.
<P>
<DT><CODE>struct tm</CODE>
<DD><TT>`time.h'</TT> (ANSI):  section <A HREF="library.html#SEC316">Broken-down Time</A>.
<P>
<DT><CODE>struct tms</CODE>
<DD><TT>`sys/times.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC312">Detailed Elapsed CPU Time Inquiry</A>.
<P>
<DT><CODE>struct utimbuf</CODE>
<DD><TT>`time.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC209">File Times</A>.
<P>
<DT><CODE>struct utsname</CODE>
<DD><TT>`sys/utsname.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC453">Hardware/Software Type Identification</A>.
<P>
<DT><CODE>size_t strxfrm (char *<VAR>to</VAR>, const char *<VAR>from</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`string.h'</TT> (ANSI):  section <A HREF="library.html#SEC63">Collation Functions</A>.
<P>
<DT><CODE>int symlink (const char *<VAR>oldname</VAR>, const char *<VAR>newname</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (BSD):  section <A HREF="library.html#SEC196">Symbolic Links</A>.
<P>
<DT><CODE>long int sysconf (int <VAR>parameter</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC459">Definition of <CODE>sysconf</CODE></A>.
<P>
<DT><CODE>int system (const char *<VAR>command</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC402">Running a Command</A>.
<P>
<DT><CODE>double tan (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC292">Trigonometric Functions</A>.
<P>
<DT><CODE>double tanh (double <VAR>x</VAR>)</CODE>
<DD><TT>`math.h'</TT> (ANSI):  section <A HREF="library.html#SEC295">Hyperbolic Functions</A>.
<P>
<DT><CODE>int tcdrain (int <VAR>filedes</VAR>)</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC288">Line Control Functions</A>.
<P>
<DT><CODE>tcflag_t</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC273">Terminal Mode Data Types</A>.
<P>
<DT><CODE>int tcflow (int <VAR>filedes</VAR>, int <VAR>action</VAR>)</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC288">Line Control Functions</A>.
<P>
<DT><CODE>int tcflush (int <VAR>filedes</VAR>, int <VAR>queue</VAR>)</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC288">Line Control Functions</A>.
<P>
<DT><CODE>int tcgetattr (int <VAR>filedes</VAR>, struct termios *<VAR>termios_p</VAR>)</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC274">Terminal Mode Functions</A>.
<P>
<DT><CODE>pid_t tcgetpgrp (int <VAR>filedes</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC428">Functions for Controlling Terminal Access</A>.
<P>
<DT><CODE>int tcsendbreak (int <VAR>filedes</VAR>, int <VAR>duration</VAR>)</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC288">Line Control Functions</A>.
<P>
<DT><CODE>int tcsetattr (int <VAR>filedes</VAR>, int <VAR>when</VAR>, const struct termios *<VAR>termios_p</VAR>)</CODE>
<DD><TT>`termios.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC274">Terminal Mode Functions</A>.
<P>
<DT><CODE>int tcsetpgrp (int <VAR>filedes</VAR>, pid_t <VAR>pgid</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC428">Functions for Controlling Terminal Access</A>.
<P>
<DT><CODE>off_t telldir (DIR *<VAR>dirstream</VAR>)</CODE>
<DD><TT>`dirent.h'</TT> (BSD):  section <A HREF="library.html#SEC194">Random Access in a Directory Stream</A>.
<P>
<DT><CODE>char * tempnam (const char *<VAR>dir</VAR>, const char *<VAR>prefix</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (SVID):  section <A HREF="library.html#SEC164">Temporary Files</A>.
<P>
<DT><CODE>time_t time (time_t *<VAR>result</VAR>)</CODE>
<DD><TT>`time.h'</TT> (ANSI):  section <A HREF="library.html#SEC314">Simple Calendar Time</A>.
<P>
<DT><CODE>time_t</CODE>
<DD><TT>`time.h'</TT> (ANSI):  section <A HREF="library.html#SEC314">Simple Calendar Time</A>.
<P>
<DT><CODE>clock_t times (struct tms *<VAR>buffer</VAR>)</CODE>
<DD><TT>`sys/times.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC312">Detailed Elapsed CPU Time Inquiry</A>.
<P>
<DT><CODE>long int timezone</CODE>
<DD><TT>`time.h'</TT> (SVID):  section <A HREF="library.html#SEC319">Functions and Variables for Time Zones</A>.
<P>
<DT><CODE>FILE * tmpfile (void)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC164">Temporary Files</A>.
<P>
<DT><CODE>char * tmpnam (char *<VAR>result</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC164">Temporary Files</A>.
<P>
<DT><CODE>int toascii (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (SVID, BSD):  section <A HREF="library.html#SEC56">Case Conversion</A>.
<P>
<DT><CODE>int tolower (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (ANSI):  section <A HREF="library.html#SEC56">Case Conversion</A>.
<P>
<DT><CODE>int toupper (int <VAR>c</VAR>)</CODE>
<DD><TT>`ctype.h'</TT> (ANSI):  section <A HREF="library.html#SEC56">Case Conversion</A>.
<P>
<DT><CODE>char * ttyname (int <VAR>filedes</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC269">Identifying Terminals</A>.
<P>
<DT><CODE>void tzset (void)</CODE>
<DD><TT>`time.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC319">Functions and Variables for Time Zones</A>.
<P>
<DT><CODE>uid_t</CODE>
<DD><TT>`sys/types.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC434">Reading the Persona of a Process</A>.
<P>
<DT><CODE>mode_t umask (mode_t <VAR>mask</VAR>)</CODE>
<DD><TT>`sys/stat.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC207">Assigning File Permissions</A>.
<P>
<DT><CODE>int uname (struct utsname *<VAR>info</VAR>)</CODE>
<DD><TT>`sys/utsname.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC453">Hardware/Software Type Identification</A>.
<P>
<DT><CODE>int ungetc (int <VAR>c</VAR>, FILE *<VAR>stream</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC127">Using <CODE>ungetc</CODE> To Do Unreading</A>.
<P>
<DT><CODE>union wait</CODE>
<DD><TT>`sys/wait.h'</TT> (BSD):  section <A HREF="library.html#SEC409">BSD Process Wait Functions</A>.
<P>
<DT><CODE>int unlink (const char *<VAR>filename</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC197">Deleting Files</A>.
<P>
<DT><CODE>int utime (const char *<VAR>filename</VAR>, const struct utimbuf *<VAR>times</VAR>)</CODE>
<DD><TT>`time.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC209">File Times</A>.
<P>
<DT><CODE>int utimes (const char *<VAR>filename</VAR>, struct timeval <VAR>tvp</VAR><TT>[2]</TT>)</CODE>
<DD><TT>`sys/time.h'</TT> (BSD):  section <A HREF="library.html#SEC209">File Times</A>.
<P>
<DT><CODE>va_alist</CODE>
<DD><TT>`varargs.h'</TT> (Unix):  section <A HREF="library.html#SEC481">Old-Style Variadic Functions</A>.
<P>
<DT><CODE><VAR>type</VAR> va_arg (va_list <VAR>ap</VAR>, <VAR>type</VAR>)</CODE>
<DD><TT>`stdarg.h'</TT> (ANSI):  section <A HREF="library.html#SEC479">Argument Access Macros</A>.
<P>
<DT><CODE>va_dcl</CODE>
<DD><TT>`varargs.h'</TT> (Unix):  section <A HREF="library.html#SEC481">Old-Style Variadic Functions</A>.
<P>
<DT><CODE>void va_end (va_list <VAR>ap</VAR>)</CODE>
<DD><TT>`stdarg.h'</TT> (ANSI):  section <A HREF="library.html#SEC479">Argument Access Macros</A>.
<P>
<DT><CODE>va_list</CODE>
<DD><TT>`stdarg.h'</TT> (ANSI):  section <A HREF="library.html#SEC479">Argument Access Macros</A>.
<P>
<DT><CODE>void va_start (va_list <VAR>ap</VAR>)</CODE>
<DD><TT>`varargs.h'</TT> (Unix):  section <A HREF="library.html#SEC481">Old-Style Variadic Functions</A>.
<P>
<DT><CODE>void va_start (va_list <VAR>ap</VAR>, <VAR>last_required</VAR>)</CODE>
<DD><TT>`stdarg.h'</TT> (ANSI):  section <A HREF="library.html#SEC479">Argument Access Macros</A>.
<P>
<DT><CODE>void * valloc (size_t <VAR>size</VAR>)</CODE>
<DD><TT>`malloc.h'</TT>, <TT>`stdlib.h'</TT> (BSD):  section <A HREF="library.html#SEC28">Allocating Aligned Memory Blocks</A>.
<P>
<DT><CODE>int vasprintf (char **<VAR>ptr</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC137">Variable Arguments Output Functions</A>.
<P>
<DT><CODE>pid_t vfork (void)</CODE>
<DD><TT>`unistd.h'</TT> (BSD):  section <A HREF="library.html#SEC405">Creating a Process</A>.
<P>
<DT><CODE>int vfprintf (FILE *<VAR>stream</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC137">Variable Arguments Output Functions</A>.
<P>
<DT><CODE>int vfscanf (FILE *<VAR>stream</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC154">Variable Arguments Input Functions</A>.
<P>
<DT><CODE>int vprintf (const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC137">Variable Arguments Output Functions</A>.
<P>
<DT><CODE>int vscanf (const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC154">Variable Arguments Input Functions</A>.
<P>
<DT><CODE>int vsnprintf (char *<VAR>s</VAR>, size_t <VAR>size</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC137">Variable Arguments Output Functions</A>.
<P>
<DT><CODE>int vsprintf (char *<VAR>s</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (ANSI):  section <A HREF="library.html#SEC137">Variable Arguments Output Functions</A>.
<P>
<DT><CODE>int vsscanf (const char *<VAR>s</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</CODE>
<DD><TT>`stdio.h'</TT> (GNU):  section <A HREF="library.html#SEC154">Variable Arguments Input Functions</A>.
<P>
<DT><CODE>pid_t wait (int *<VAR>status_ptr</VAR>)</CODE>
<DD><TT>`sys/wait.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC407">Process Completion</A>.
<P>
<DT><CODE>pid_t wait3 (union wait *<VAR>status_ptr</VAR>, int <VAR>options</VAR>, struct rusage *<VAR>usage</VAR>)</CODE>
<DD><TT>`sys/wait.h'</TT> (BSD):  section <A HREF="library.html#SEC409">BSD Process Wait Functions</A>.
<P>
<DT><CODE>pid_t wait4 (pid_t <VAR>pid</VAR>, union wait *<VAR>status_ptr</VAR>, int <VAR>options</VAR>, struct rusage *<VAR>usage</VAR>)</CODE>
<DD><TT>`sys/wait.h'</TT> (BSD):  section <A HREF="library.html#SEC409">BSD Process Wait Functions</A>.
<P>
<DT><CODE>pid_t waitpid (pid_t <VAR>pid</VAR>, int *<VAR>status_ptr</VAR>, int <VAR>options</VAR>)</CODE>
<DD><TT>`sys/wait.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC407">Process Completion</A>.
<P>
<DT><CODE>wchar_t</CODE>
<DD><TT>`stddef.h'</TT> (ANSI):  section <A HREF="library.html#SEC70">Wide Character Introduction</A>.
<P>
<DT><CODE>size_t wcstombs (char *<VAR>string</VAR>, const wchar_t <VAR>wstring</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC71">Conversion of Extended Strings</A>.
<P>
<DT><CODE>int wctomb (char *<VAR>string</VAR>, wchar_t <VAR>wchar</VAR>)</CODE>
<DD><TT>`stdlib.h'</TT> (ANSI):  section <A HREF="library.html#SEC73">Conversion of Extended Characters One by One</A>.
<P>
<DT><CODE>int wordexp (const char *<VAR>words</VAR>, wordexp_t *<VAR>word-vector-ptr</VAR>, int <VAR>flags</VAR>)</CODE>
<DD><TT>`wordexp.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC105">Calling <CODE>wordexp</CODE></A>.
<P>
<DT><CODE>wordexp_t</CODE>
<DD><TT>`wordexp.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC105">Calling <CODE>wordexp</CODE></A>.
<P>
<DT><CODE>void wordfree (wordexp_t *<VAR>word-vector-ptr</VAR>)</CODE>
<DD><TT>`wordexp.h'</TT> (POSIX.2):  section <A HREF="library.html#SEC105">Calling <CODE>wordexp</CODE></A>.
<P>
<DT><CODE>ssize_t write (int <VAR>filedes</VAR>, const void *<VAR>buffer</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD><TT>`unistd.h'</TT> (POSIX.1):  section <A HREF="library.html#SEC173">Input and Output Primitives</A>.
<P>
</DL>
<P>
<H1><A NAME="SEC493" HREF="library_toc.html#SEC493">Library Maintenance</A></H1>
<P>
<A NAME="IDX1978"></A>
<H2><A NAME="SEC494" HREF="library_toc.html#SEC494">How to Install the GNU C Library</A></H2>
<P>
Installation of the GNU C library is relatively simple.
<P>
You need the latest version of GNU <CODE>make</CODE>.  Modifying the GNU C
Library to work with other <CODE>make</CODE> programs would be so hard that we
recommend you port GNU <CODE>make</CODE> instead.  <STRONG>Really.</STRONG><P>
To configure the GNU C library for your system, run the shell script
<TT>`configure'</TT> with <CODE>sh</CODE>.  Use an argument which is the
conventional GNU name for your system configuration--for example,
<SAMP>`sparc-sun-sunos4.1'</SAMP>, for a Sun 4 running Sunos 4.1.
See section 'Installing GNU CC' in <CITE>Using and Porting GNU CC</CITE>, for a full description of standard GNU configuration
names.
<P>
The GNU C Library currently supports configurations that match the
following patterns:
<P>
<PRE>
sparc-sun-sunos4.<VAR>n</VAR>
m68k-hp-bsd4.3
m68k-sun-sunos4.<VAR>n</VAR>
m68k-sony-bsd4.3
mips-dec-ultrix4.<VAR>n</VAR>
i386-bsd4.3
i386-sysv
i386-sysv4
</PRE>
<P>
While no other configurations are supported, there are handy aliases for
these few.  (These aliases work in other GNU software as well.)
<P>
<PRE>
sun4-sunos4.<VAR>n</VAR>
hp320-bsd4.3
sun3-sunos4.<VAR>n</VAR>
news
decstation-ultrix
i386-svr4
</PRE>
<P>
Here are some options that you should specify (if appropriate) when
you run <CODE>configure</CODE>:
<P>
<DL COMPACT>
<DT><SAMP>`--with-gnu-ld'</SAMP>
<DD>Use this option if you plan to use GNU <CODE>ld</CODE> to link programs with
the GNU C Library.  (We strongly recommend that you do.)
<P>
<DT><SAMP>`--with-gnu-as'</SAMP>
<DD>Use this option if you plan to use the GNU assembler, <CODE>gas</CODE>, when
building the GNU C Library.  On some systems, the library may not build
properly if you do <EM>not</EM> use <CODE>gas</CODE>.
<P>
<DT><SAMP>`--nfp'</SAMP>
<DD><P>
Use this option if your computer lacks hardware floating point support.
<P>
<DT><SAMP>`--prefix=<VAR>directory</VAR>'</SAMP>
<DD>Install machine-independent data files in subdirectories of
<TT>`<VAR>directory</VAR>'</TT>.  (You can also set this in <TT>`configparms'</TT>;
see below.)
<P>
<DT><SAMP>`--exec-prefix=<VAR>directory</VAR>'</SAMP>
<DD>Install the library and other machine-dependent files in subdirectories
of <TT>`<VAR>directory</VAR>'</TT>.  (You can also set this in
<TT>`configparms'</TT>; see below.)
</DL>
<P>
The simplest way to run <CODE>configure</CODE> is to do it in the directory
that contains the library sources.  This prepares to build the library
in that very directory.
<P>
You can prepare to build the library in some other directory by going
to that other directory to run <CODE>configure</CODE>.  In order to run
configure, you will have to specify a directory for it, like this:
<P>
<PRE>
mkdir ../hp320
cd ../hp320
../src/configure hp320-bsd4.3
</PRE>
<P>
<CODE>configure</CODE> looks for the sources in whatever directory you
specified for finding <CODE>configure</CODE> itself.  It does not matter where
in the file system the source and build directories are--as long as you
specify the source directory when you run <CODE>configure</CODE>, you will get
the proper results.
<P>
This feature lets you keep sources and binaries in different
directories, and that makes it easy to build the library for several
different machines from the same set of sources.  Simply create a 
build directory for each target machine, and run <CODE>configure</CODE> in
that directory specifying the target machine's configuration name.
<P>
The library has a number of special-purpose configuration parameters.
These are defined in the file <TT>`Makeconfig'</TT>; see the comments in
that file for the details.
<P>
But don't edit the file <TT>`Makeconfig'</TT> yourself--instead, create a
file <TT>`configparms'</TT> in the directory where you are building the
library, and define in that file the parameters you want to specify.
<TT>`configparms'</TT> should <STRONG>not</STRONG> be an edited copy of
<TT>`Makeconfig'</TT>; specify only the parameters that you want to
override.
<P>
Some of the machine-dependent code for some machines uses extensions in
the GNU C compiler, so you may need to compile the library with GCC.
(In fact, all of the existing complete ports require GCC.)
<P>
The current release of the C library contains some header files that the
compiler normally provides: <TT>`stddef.h'</TT>, <TT>`stdarg.h'</TT>, and
several files with names of the form <TT>`va-<VAR>machine</VAR>.h'</TT>.  The
versions of these files that came with older releases of GCC do not work
properly with the GNU C library.  The <TT>`stddef.h'</TT> file in release
2.2 and later of GCC is correct.  If you have release 2.2 or later of
GCC, use its version of <TT>`stddef.h'</TT> instead of the C library's.  To
do this, put the line <SAMP>`override stddef.h ='</SAMP> in
<TT>`configparms'</TT>.  The other files are corrected in release 2.3 and
later of GCC.  <TT>`configure'</TT> will automatically detect whether the
installed <TT>`stdarg.h'</TT> and <TT>`va-<VAR>machine</VAR>.h'</TT> files are
compatible with the C library, and use its own if not.
<P>
There is a potential problem with the <CODE>size_t</CODE> type and versions of
GCC prior to release 2.4.  ANSI C requires that <CODE>size_t</CODE> always be
an unsigned type.  For compatibility with existing systems' header
files, GCC defines <CODE>size_t</CODE> in <TT>`stddef.h'</TT> to be whatever type
the system's <TT>`sys/types.h'</TT> defines it to be.  Most Unix systems
that define <CODE>size_t</CODE> in <TT>`sys/types.h'</TT>, define it to be a
signed type.  Some code in the library depends on <CODE>size_t</CODE> being an
unsigned type, and will not work correctly if it is signed.
<P>
The GNU C library code which expects <CODE>size_t</CODE> to be unsigned is
correct.  The definition of <CODE>size_t</CODE> as a signed type is incorrect.
We plan that in version 2.4, GCC will always define <CODE>size_t</CODE> as an
unsigned type, and the <TT>`fixincludes'</TT> script will massage the
system's <TT>`sys/types.h'</TT> so as not to conflict with this.
<P>
In the meantime, we work around this problem by telling GCC explicitly
to use an unsigned type for <CODE>size_t</CODE> when compiling the GNU C
library.  <TT>`configure'</TT> will automatically detect what type GCC uses
for <CODE>size_t</CODE> arrange to override it if necessary.
<P>
To build the library, type <CODE>make lib</CODE>.  This will produce a lot of
output, some of which looks like errors from <CODE>make</CODE> (but isn't).
Look for error messages from <CODE>make</CODE> containing <SAMP>`***'</SAMP>.  Those
indicate that something is really wrong.  Using the <SAMP>`-w'</SAMP> option to
<CODE>make</CODE> may make the output easier to understand (this option tells
<CODE>make</CODE> to print messages telling you what subdirectories it is
working on).<P>
To install the library and header files, type <CODE>make install</CODE>, after
setting the installation directories in <TT>`configparms'</TT>.  This will
build things if necessary, before installing them.<P>
<A NAME="IDX1979"></A>
<H2><A NAME="SEC495" HREF="library_toc.html#SEC495">Reporting Bugs</A></H2>
<P>
There are probably bugs in the GNU C library.  If you report them,
they will get fixed.  If you don't, no one will ever know about them
and they will remain unfixed for all eternity, if not longer.
<P>
To report a bug, first you must find it.  Hopefully, this will be the
hard part.  Once you've found a bug, make sure it's really a bug.  A
good way to do this is to see if the GNU C library behaves the same way
some other C library does.  If so, probably you are wrong and the
libraries are right (but not necessarily).  If not, one of the libraries
is probably wrong.
<P>
Once you're sure you've found a bug, try to narrow it down to the
smallest test case that reproduces the problem.  In the case of a C
library, you really only need to narrow it down to one library
function call, if possible.  This should not be too difficult.
<P>
The final step when you have a simple test case is to report the
bug.  When reporting a bug, send your test case, the results you
got, the results you expected, what you think the problem might be
(if you've thought of anything), your system type, and the version
of the GNU C library which you are using.
<P>
If you think you have found some way in which the GNU C library does not
conform to the ANSI and POSIX standards (see section <A HREF="library.html#SEC3">Standards and Portability</A>), that is definitely a bug.  Report it!<P>
Send bug reports to the Internet address
<SAMP>`bug-glibc@prep.ai.mit.edu'</SAMP> or the UUCP path
<SAMP>`mit-eddie!prep.ai.mit.edu!bug-glibc'</SAMP>.  If you have other problems
with installation, use, or the documentation, please report those as
well.<P>
<H2><A NAME="SEC496" HREF="library_toc.html#SEC496">Adding New Functions</A></H2>
<P>
The process of building the library is driven by the makefiles, which
make heavy use of special features of GNU <CODE>make</CODE>.  The makefiles
are very complex, and you probably don't want to try to understand them.
But what they do is fairly straightforward, and only requires that you
define a few variables in the right places.
<P>
The library sources are divided into subdirectories, grouped by topic.
The <TT>`string'</TT> subdirectory has all the string-manipulation
functions, <TT>`stdio'</TT> has all the standard I/O functions, etc.
<P>
Each subdirectory contains a simple makefile, called <TT>`Makefile'</TT>,
which defines a few <CODE>make</CODE> variables and then includes the global
makefile <TT>`Rules'</TT> with a line like:
<P>
<PRE>
include ../Rules
</PRE>
<P>
The basic variables that a subdirectory makefile defines are:
<P>
<DL COMPACT>
<DT><CODE>subdir</CODE>
<DD>The name of the subdirectory, for example <TT>`stdio'</TT>.
This variable <STRONG>must</STRONG> be defined.
<P>
<DT><CODE>headers</CODE>
<DD>The names of the header files in this section of the library,
such as <TT>`stdio.h'</TT>.
<P>
<DT><CODE>routines</CODE>
<DD><DT><CODE>aux</CODE>
<DD>The names of the modules (source files) in this section of the library.
These should be simple names, such as <SAMP>`strlen'</SAMP> (rather than
complete file names, such as <TT>`strlen.c'</TT>).  Use <CODE>routines</CODE> for
modules that define functions in the library, and <CODE>aux</CODE> for
auxiliary modules containing things like data definitions.  But the
values of <CODE>routines</CODE> and <CODE>aux</CODE> are just concatenated, so there
really is no practical difference.<P>
<DT><CODE>tests</CODE>
<DD>The names of test programs for this section of the library.  These
should be simple names, such as <SAMP>`tester'</SAMP> (rather than complete file
names, such as <TT>`tester.c'</TT>).  <SAMP>`make tests'</SAMP> will build and
run all the test programs.  If a test program needs input, put the test
data in a file called <TT>`<VAR>test-program</VAR>.input'</TT>; it will be given to
the test program on its standard input.  If a test program wants to be
run with arguments, put the arguments (all on a single line) in a file
called <TT>`<VAR>test-program</VAR>.args'</TT>.<P>
<DT><CODE>others</CODE>
<DD>The names of "other" programs associated with this section of the
library.  These are programs which are not tests per se, but are other
small programs included with the library.  They are built by
<SAMP>`make others'</SAMP>.<P>
<DT><CODE>install-lib</CODE>
<DD><DT><CODE>install-data</CODE>
<DD><DT><CODE>install</CODE>
<DD>Files to be installed by <SAMP>`make install'</SAMP>.  Things listed in
<SAMP>`install-lib'</SAMP> are installed in the directory specified by
<SAMP>`libdir'</SAMP> in <TT>`Makeconfig'</TT> (see section <A HREF="library.html#SEC494">How to Install the GNU C Library</A>).  Files listed
in <CODE>install-data</CODE> are installed in the directory specified by
<SAMP>`datadir'</SAMP> in <TT>`configparms'</TT> or <TT>`Makeconfig'</TT>.  Files listed
in <CODE>install</CODE> are installed in the directory specified by
<SAMP>`bindir'</SAMP> in <TT>`Makeconfig'</TT>.<P>
<DT><CODE>distribute</CODE>
<DD>Other files from this subdirectory which should be put into a
distribution tar file.  You need not list here the makefile itself or
the source and header files listed in the other standard variables.
Only define <CODE>distribute</CODE> if there are files used in an unusual way
that should go into the distribution.
<P>
<DT><CODE>generated</CODE>
<DD>Files which are generated by <TT>`Makefile'</TT> in this subdirectory.
These files will be removed by <SAMP>`make clean'</SAMP>, and they will
never go into a distribution.
<P>
<DT><CODE>extra-objs</CODE>
<DD>Extra object files which are built by <TT>`Makefile'</TT> in this
subdirectory.  This should be a list of file names like <TT>`foo.o'</TT>;
the files will actually be found in whatever directory object files are
being built in.  These files will be removed by <SAMP>`make clean'</SAMP>.
This variable is used for secondary object files needed to build
<CODE>others</CODE> or <CODE>tests</CODE>.
</DL>
<P>
<H2><A NAME="SEC497" HREF="library_toc.html#SEC497">Porting the GNU C Library</A></H2>
<P>
The GNU C library is written to be easily portable to a variety of
machines and operating systems.  Machine- and operating system-dependent
functions are well separated to make it easy to add implementations for
new machines or operating systems.  This section describes the layout of
the library source tree and explains the mechanisms used to select
machine-dependent code to use.
<P>
All the machine-dependent and operating system-dependent files in the
library are in the subdirectory <TT>`sysdeps'</TT> under the top-level
library source directory.  This directory contains a hierarchy of
subdirectories (see section <A HREF="library.html#SEC498">The Layout of the <TT>`sysdeps'</TT> Directory Hierarchy</A>).
<P>
Each subdirectory of <TT>`sysdeps'</TT> contains source files for a
particular machine or operating system, or for a class of machine or
operating system (for example, systems by a particular vendor, or all
machines that use IEEE 754 floating-point format).  A configuration
specifies an ordered list of these subdirectories.  Each subdirectory
implicitly appends its parent directory to the list.  For example,
specifying the list <TT>`unix/bsd/vax'</TT> is equivalent to specifying the
list <TT>`unix/bsd/vax unix/bsd unix'</TT>.  A subdirectory can also specify
that it implies other subdirectories which are not directly above it in
the directory hierarchy.  If the file <TT>`Implies'</TT> exists in a
subdirectory, it lists other subdirectories of <TT>`sysdeps'</TT> which are
appended to the list, appearing after the subdirectory containing the
<TT>`Implies'</TT> file.  Lines in an <TT>`Implies'</TT> file that begin with a
<SAMP>`#'</SAMP> character are ignored as comments.  For example,
<TT>`unix/bsd/Implies'</TT> contains:<PRE>
# BSD has Internet-related things.
unix/inet
</PRE>
and <TT>`unix/Implies'</TT> contains:
<PRE>
posix
</PRE>
<P>
So the final list is <TT>`unix/bsd/vax unix/bsd vax unix/inet unix posix'</TT>.
<P>
<TT>`sysdeps'</TT> has two "special" subdirectories, called <TT>`generic'</TT>
and <TT>`stub'</TT>.  These two are always implicitly appended to the list
of subdirectories (in that order), so you needn't put them in an
<TT>`Implies'</TT> file, and you should not create any subdirectories under
them.  <TT>`generic'</TT> is for things that can be implemented in
machine-independent C, using only other machine-independent functions in
the C library.  <TT>`stub'</TT> is for <DFN>stub</DFN> versions of functions
which cannot be implemented on a particular machine or operating system.
The stub functions always return an error, and set <CODE>errno</CODE> to
<CODE>ENOSYS</CODE> (Function not implemented).  See section <A HREF="library.html#SEC14">Error Reporting</A>.
<P>
A source file is known to be system-dependent by its having a version in
<TT>`generic'</TT> or <TT>`stub'</TT>; every system-dependent function should
have either a generic or stub implementation (there is no point in
having both).
<P>
If you come across a file that is in one of the main source directories
(<TT>`string'</TT>, <TT>`stdio'</TT>, etc.), and you want to write a machine- or
operating system-dependent version of it, move the file into
<TT>`sysdeps/generic'</TT> and write your new implementation in the
appropriate system-specific subdirectory.  Note that if a file is to be
system-dependent, it <STRONG>must not</STRONG> appear in one of the main source
directories.<P>
There are a few special files that may exist in each subdirectory of
<TT>`sysdeps'</TT>:
<P>
<DL COMPACT>
<DT><TT>`Makefile'</TT>
<DD>A makefile for this machine or operating system, or class of machine or
operating system.  This file is included by the library makefile
<TT>`Makerules'</TT>, which is used by the top-level makefile and the
subdirectory makefiles.  It can change the variables set in the
including makefile or add new rules.  It can use GNU <CODE>make</CODE>
conditional directives based on the variable <SAMP>`subdir'</SAMP> (see above) to
select different sets of variables and rules for different sections of
the library.  It can also set the <CODE>make</CODE> variable
<SAMP>`sysdep-routines'</SAMP>, to specify extra modules to be included in the
library.  You should use <SAMP>`sysdep-routines'</SAMP> rather than adding
modules to <SAMP>`routines'</SAMP> because the latter is used in determining
what to distribute for each subdirectory of the main source tree.<P>
Each makefile in a subdirectory in the ordered list of subdirectories to
be searched is included in order.  Since several system-dependent
makefiles may be included, each should append to <SAMP>`sysdep-routines'</SAMP>
rather than simply setting it:
<P>
<PRE>
sysdep-routines := $(sysdep-routines) foo bar
</PRE>
<P>
<DT><TT>`Subdirs'</TT>
<DD>This file contains the names of new whole subdirectories under the
top-level library source tree that should be included for this system.
These subdirectories are treated just like the system-independent
subdirectories in the library source tree, such as <TT>`stdio'</TT> and
<TT>`math'</TT>.
<P>
Use this when there are whole new sets of routines and header files that
should go into the library for the system this subdirectory of
<TT>`sysdeps'</TT> implements.  For example,
<TT>`sysdeps/unix/inet/Subdirs'</TT> contains <TT>`inet'</TT>; the <TT>`inet'</TT>
directory contains various network-oriented operations which only make
sense to put in the library on systems that support the Internet.<P>
<DT><TT>`Dist'</TT>
<DD>This file contains the names of files (relative the the subdirectory of
<TT>`sysdeps'</TT> in which it appears) which should be included in the
distribution.  List any new files used by rules in the <TT>`Makefile'</TT>
in the same directory, or header files used by the source files in that
directory.  You don't need to list files that are implementations
(either C or assembly source) of routines whose names are given in the
machine-independent makefiles in the main source tree.
</DL>
<P>
That is the general system for how system-dependencies are isolated.
The next section explains how to decide what directories in
<TT>`sysdeps'</TT> to use.  section <A HREF="library.html#SEC499">Porting the GNU C Library to Unix Systems</A>, has some tips on porting
the library to Unix variants.
<P>
<H3><A NAME="SEC498" HREF="library_toc.html#SEC498">The Layout of the <TT>`sysdeps'</TT> Directory Hierarchy</A></H3>
<P>
A GNU configuration name has three parts: the CPU type, the
manufacturer's name, and the operating system.  <TT>`configure'</TT> uses
these to pick the list of system-dependent directories to look for.  If
the <SAMP>`--nfp'</SAMP> option is <EM>not</EM> passed to <TT>`configure'</TT>, the
directory <TT>`<VAR>machine</VAR>/fpu'</TT> is also used.  The operating system
often has a <DFN>base operating system</DFN>; for example, if the operating
system is <SAMP>`sunos4.1'</SAMP>, the base operating system is <SAMP>`unix/bsd'</SAMP>.
The algorithm used to pick the list of directories is simple:
<TT>`configure'</TT> makes a list of the base operating system,
manufacturer, CPU type, and operating system, in that order.  It then
concatenates all these together with slashes in between, to produce a
directory name; for example, the configuration <SAMP>`sparc-sun-sunos4.1'</SAMP>
results in <TT>`unix/bsd/sun/sparc/sunos4.1'</TT>.  <TT>`configure'</TT> then
tries removing each element of the list in turn, so
<TT>`unix/bsd/sparc'</TT> and <TT>`sun/sparc'</TT> are also tried, among others.
Since the precise version number of the operating system is often not
important, and it would be very inconvenient, for example, to have
identical <TT>`sunos4.1.1'</TT> and <TT>`sunos4.1.2'</TT> directories,
<TT>`configure'</TT> tries successively less specific operating system names
by removing trailing suffixes starting with a period.
<P>
Here is the complete list of directories that would be tried for the
configuration <SAMP>`sparc-sun-sunos4.1'</SAMP>:
<P>
<PRE>
sparc/fpu
unix/bsd/sun/sunos4.1/sparc
unix/bsd/sun/sunos4.1
unix/bsd/sun/sunos4/sparc
unix/bsd/sun/sunos4
unix/bsd/sun/sparc
unix/bsd/sun
unix/bsd/sunos4.1/sparc
unix/bsd/sunos4.1
unix/bsd/sunos4/sparc
unix/bsd/sunos4
unix/bsd/sparc
unix/bsd
sun/sunos4.1/sparc
sun/sunos4.1
sun/sunos4/sparc
sun/sunos4
sun/sparc
sun
sunos4.1/sparc
sunos4.1
sunos4/sparc
sunos4
sparc
</PRE>
<P>
Different machine architectures are generally at the top level of the
<TT>`sysdeps'</TT> directory tree.  For example, <TT>`sysdeps/sparc'</TT>
and <TT>`sysdeps/m68k'</TT>.  These contain files specific to those
machine architectures, but not specific to any particular operating
system.  There might be subdirectories for specializations of those
architectures, such as <TT>`sysdeps/m68k/68020'</TT>. Code which is
specific to the floating-point coprocessor used with a particular
machine should go in <TT>`sysdeps/<VAR>machine</VAR>/fpu'</TT>.
<P>
There are a few directories at the top level of the <TT>`sysdeps'</TT>
hierarchy that are not for particular machine architectures.
<P>
<DL COMPACT>
<DT><TT>`generic'</TT>
<DD><DT><TT>`stub'</TT>
<DD>As described above (see section <A HREF="library.html#SEC497">Porting the GNU C Library</A>), these are the two subdirectories
that every configuration implicitly uses after all others.
<P>
<DT><TT>`ieee754'</TT>
<DD>This directory is for code using the IEEE 754 floating-point format,
where the C type <CODE>float</CODE> is IEEE 754 single-precision format, and
<CODE>double</CODE> is IEEE 754 double-precision format.  Usually this
directory is referred to in the <TT>`Implies'</TT> file in a machine
architecture-specific directory, such as <TT>`m68k/Implies'</TT>.
<P>
<DT><TT>`posix'</TT>
<DD>This directory contains implementations of things in the library in
terms of POSIX.1 functions.  This includes some of the POSIX.1
functions themselves.  Of course, POSIX.1 cannot be completely
implemented in terms of itself, so a configuration using just
<TT>`posix'</TT> cannot be complete.
<P>
<DT><TT>`unix'</TT>
<DD>This is the directory for Unix-like things.  See See section <A HREF="library.html#SEC499">Porting the GNU C Library to Unix Systems</A>.
<TT>`unix'</TT> implies <TT>`posix'</TT>.  There are some special-purpose
subdirectories of <TT>`unix'</TT>:
<P>
<DL COMPACT>
<DT><TT>`unix/common'</TT>
<DD>This directory is for things common to both BSD and System V release 4.
Both <TT>`unix/bsd'</TT> and <TT>`unix/sysv/sysv4'</TT> imply <TT>`unix/common'</TT>.
<P>
<DT><TT>`unix/inet'</TT>
<DD>This directory is for <CODE>socket</CODE> and related functions on Unix systems.
The <TT>`inet'</TT> top-level subdirectory is enabled by <TT>`unix/inet/Subdirs'</TT>.
<TT>`unix/common'</TT> implies <TT>`unix/inet'</TT>.
</DL>
<P>
<LI>mach
This is the directory for things based on the Mach microkernel from CMU
(including the GNU operating system).  Other basic operating systems
(VMS, for example) would have their own directories at the top level of
the <TT>`sysdeps'</TT> hierarchy, parallel to <TT>`unix'</TT> and <TT>`mach'</TT>.
</DL>
<P>
<H3><A NAME="SEC499" HREF="library_toc.html#SEC499">Porting the GNU C Library to Unix Systems</A></H3>
<P>
Most Unix systems are fundamentally very similar.  There are variations
between different machines, and variations in what facilities are
provided by the kernel.  But the interface to the operating system
facilities is, for the most part, pretty uniform and simple.
<P>
The code for Unix systems is in the directory <TT>`unix'</TT>, at the top
level of the <TT>`sysdeps'</TT> hierarchy.  This directory contains
subdirectories (and subdirectory trees) for various Unix variants.
<P>
The functions which are system calls in most Unix systems are
implemented in assembly code in files in <TT>`sysdeps/unix'</TT>.  These
files are named with a suffix of <SAMP>`.S'</SAMP>; for example,
<TT>`__open.S'</TT>.  Files ending in <SAMP>`.S'</SAMP> are run through the C
preprocessor before being fed to the assembler.
<P>
These files all use a set of macros that should be defined in
<TT>`sysdep.h'</TT>.  The <TT>`sysdep.h'</TT> file in <TT>`sysdeps/unix'</TT>
partially defines them; a <TT>`sysdep.h'</TT> file in another directory must
finish defining them for the particular machine and operating system
variant.  See <TT>`sysdeps/unix/sysdep.h'</TT> and the machine-specific
<TT>`sysdep.h'</TT> implementations to see what these macros are and what
they should do.<P>
The system-specific makefile for the <TT>`unix'</TT> directory,
<TT>`sysdeps/unix/Makefile'</TT>, gives rules to generate several files from
the Unix system you are building the library on (which is assumed to be
the target system you are building the library <EM>for</EM>).  All the
generated files are put in the directory where the object files are
kept; they should not affect the source tree itself.  The files
generated are <TT>`ioctls.h'</TT>, <TT>`errnos.h'</TT>, <TT>`sys/param.h'</TT>, and
<TT>`errlist.c'</TT> (for the <TT>`stdio'</TT> section of the library).
<P>
<H2><A NAME="SEC500" HREF="library_toc.html#SEC500">Contributors to the GNU C Library</A></H2>
<P>
The GNU C library was written almost entirely by Roland McGrath.
Some parts of the library were contributed by other people.
<P>
<UL>
<LI>
The <CODE>getopt</CODE> function and related code were written by
Richard Stallman, David J. MacKenzie, and Roland McGrath.
<P>
<LI>
Most of the math functions are taken from 4.4 BSD; they have been
modified only slightly to work with the GNU C library.  The
Internet-related code (most of the <TT>`inet'</TT> subdirectory) and several
other miscellaneous functions and header files have been included with
little or no modification.
<P>
All code incorporated from 4.4 BSD is under the following copyright:
<P>
<BLOCKQUOTE>
<PRE>
Copyright (C) 1991 Regents of the University of California.
All rights reserved.
</PRE>
<P>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
<P>
<OL>
<LI>
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
<LI>
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
<LI>
All advertising materials mentioning features or use of this software
must display the following acknowledgement:
<BLOCKQUOTE>
	This product includes software developed by the University of
	California, Berkeley and its contributors.
</BLOCKQUOTE>
<LI>
Neither the name of the University nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
</OL>
<P>
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
</BLOCKQUOTE>
<P>
<LI>
The random number generation functions <CODE>random</CODE>, <CODE>srandom</CODE>,
<CODE>setstate</CODE> and <CODE>initstate</CODE>, which are also the basis for the
<CODE>rand</CODE> and <CODE>srand</CODE> functions, were written by Earl T. Cohen
for the University of California at Berkeley and are copyrighted by the
Regents of the University of California.  They have undergone minor
changes to fit into the GNU C library and to fit the ANSI C standard,
but the functional code is Berkeley's.<P>
<LI>
The merge sort function <CODE>qsort</CODE> was written by Michael J. Haertel.
<P>
<LI>
The quick sort function used as a fallback by <CODE>qsort</CODE> was written
by Douglas C. Schmidt.
<P>
<LI>
The memory allocation functions <CODE>malloc</CODE>, <CODE>realloc</CODE> and
<CODE>free</CODE> and related code were written by Michael J. Haertel.
<P>
<LI>
Fast implementations of many of the string functions (<CODE>memcpy</CODE>,
<CODE>strlen</CODE>, etc.) were written by
Granlund.<P>
<LI>
Some of the support code for Mach is taken from Mach 3.0 by CMU,
and is under the following copyright terms:
<P>
<BLOCKQUOTE>
<PRE>
Mach Operating System
Copyright (C) 1991,1990,1989 Carnegie Mellon University
All Rights Reserved.
</PRE>
<P>
Permission to use, copy, modify and distribute this software and its
documentation is hereby granted, provided that both the copyright
notice and this permission notice appear in all copies of the
software, derivative works or modified versions, and any portions
thereof, and that both notices appear in supporting documentation.
<P>
CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
<P>
Carnegie Mellon requests users of this software to return to
<P>
<PRE>
 Software Distribution Coordinator
 School of Computer Science
 Carnegie Mellon University
 Pittsburgh PA 15213-3890
</PRE>
<P>
or <SAMP>`Software.Distribution@CS.CMU.EDU'</SAMP> any improvements or
extensions that they make and grant Carnegie Mellon the rights to
redistribute these changes.
</BLOCKQUOTE>
<P>
<LI>
The <TT>`tar.h'</TT> header file was written by David J. MacKenzie.
<P>
<LI>
The port to the MIPS DECStation running Ultrix 4
(<CODE>mips-dec-ultrix4</CODE>)
was contributed by Brendan Kehoe and Ian Lance Taylor.
<P>
<LI>
The DES encryption function <CODE>crypt</CODE> and related functions were
contributed by Michael Glad.
<P>
<LI>
The <CODE>ftw</CODE> function was contributed by Ian Lance Taylor.
<P>
<LI>
The code to support SunOS shared libraries was contributed by Tom Quinn.
<P>
<LI>
The <CODE>mktime</CODE> function was contributed by Noel Cragg.
<P>
<LI>
The port to the Sequent Symmetry running Dynix version 3
(<CODE>i386-sequent-bsd</CODE>) was contributed by Jason Merrill.
</UL>
<P>
<H1><A NAME="SEC501" HREF="library_toc.html#SEC501">GNU LIBRARY GENERAL PUBLIC LICENSE</A></H1>
Version 2, June 1991
<P>
<PRE>
Copyright (C) 1991 Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

[This is the first released version of the library GPL.  It is
 numbered 2 because it goes with version 2 of the ordinary GPL.]
</PRE>
<P>
<H2><A NAME="SEC502" HREF="library_toc.html#SEC502">Preamble</A></H2>
<P>
  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software--to make sure the software is free for all its users.
<P>
  This license, the Library General Public License, applies to some
specially designated Free Software Foundation software, and to any
other libraries whose authors decide to use it.  You can use it for
your libraries, too.
<P>
  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.
<P>
  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if
you distribute copies of the library, or if you modify it.
<P>
  For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you.  You must make sure that they, too, receive or can get the source
code.  If you link a program with the library, you must provide
complete object files to the recipients so that they can relink them
with the library, after making changes to the library and recompiling
it.  And you must show them these terms so they know their rights.
<P>
  Our method of protecting your rights has two steps: (1) copyright
the library, and (2) offer you this license which gives you legal
permission to copy, distribute and/or modify the library.
<P>
  Also, for each distributor's protection, we want to make certain
that everyone understands that there is no warranty for this free
library.  If the library is modified by someone else and passed on, we
want its recipients to know that what they have is not the original
version, so that any problems introduced by others will not reflect on
the original authors' reputations.
<P>
  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that companies distributing free
software will individually obtain patent licenses, thus in effect
transforming the program into proprietary software.  To prevent this,
we have made it clear that any patent must be licensed for everyone's
free use or not licensed at all.
<P>
  Most GNU software, including some libraries, is covered by the ordinary
GNU General Public License, which was designed for utility programs.  This
license, the GNU Library General Public License, applies to certain
designated libraries.  This license is quite different from the ordinary
one; be sure to read it in full, and don't assume that anything in it is
the same as in the ordinary license.
<P>
  The reason we have a separate public license for some libraries is that
they blur the distinction we usually make between modifying or adding to a
program and simply using it.  Linking a program with a library, without
changing the library, is in some sense simply using the library, and is
analogous to running a utility program or application program.  However, in
a textual and legal sense, the linked executable is a combined work, a
derivative of the original library, and the ordinary General Public License
treats it as such.
<P>
  Because of this blurred distinction, using the ordinary General
Public License for libraries did not effectively promote software
sharing, because most developers did not use the libraries.  We
concluded that weaker conditions might promote sharing better.
<P>
  However, unrestricted linking of non-free programs would deprive the
users of those programs of all benefit from the free status of the
libraries themselves.  This Library General Public License is intended to
permit developers of non-free programs to use free libraries, while
preserving your freedom as a user of such programs to change the free
libraries that are incorporated in them.  (We have not seen how to achieve
this as regards changes in header files, but we have achieved it as regards
changes in the actual functions of the Library.)  The hope is that this
will lead to faster development of free libraries.
<P>
  The precise terms and conditions for copying, distribution and
modification follow.  Pay close attention to the difference between a
"work based on the library" and a "work that uses the library".  The
former contains code derived from the library, while the latter only
works together with the library.
<P>
  Note that it is possible for a library to be covered by the ordinary
General Public License rather than by this special one.
<P>
<H2><A NAME="SEC503" HREF="library_toc.html#SEC503">TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</A></H2>
<P>
<OL>
<LI>
This License Agreement applies to any software library which
contains a notice placed by the copyright holder or other authorized
party saying it may be distributed under the terms of this Library
General Public License (also called "this License").  Each licensee is
addressed as "you".
<P>
  A "library" means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.
<P>
  The "Library", below, refers to any such software library or work
which has been distributed under these terms.  A "work based on the
Library" means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language.  (Hereinafter, translation is
included without limitation in the term "modification".)
<P>
  "Source code" for a work means the preferred form of the work for
making modifications to it.  For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control compilation
and installation of the library.
<P>
  Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it).  Whether that is true depends on what the Library does
and what the program that uses the Library does.
  
<LI>
You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
Library.
<P>
  You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.
<P>
<LI>
You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
<P>
<OL>
<LI>
The modified work must itself be a software library.
<P>
<LI>
You must cause the files modified to carry prominent notices
stating that you changed the files and the date of any change.
<P>
<LI>
You must cause the whole of the work to be licensed at no
charge to all third parties under the terms of this License.
<P>
<LI>
If a facility in the modified Library refers to a function or a
table of data to be supplied by an application program that uses
the facility, other than as an argument passed when the facility
is invoked, then you must make a good faith effort to ensure that,
in the event an application does not supply such function or
table, the facility still operates, and performs whatever part of
its purpose remains meaningful.
<P>
(For example, a function in a library to compute square roots has
a purpose that is entirely well-defined independent of the
application.  Therefore, Subsection 2d requires that any
application-supplied function or table used by this function must
be optional: if the application does not supply it, the square
root function must still compute square roots.)
</OL>
<P>
These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Library,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Library, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.
<P>
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Library.
<P>
In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
<P>
<LI>
You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library.  To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License.  (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.)  Do not make any other change in
these notices.
<P>
  Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.
<P>
  This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.
<P>
<LI>
You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.
<P>
  If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.
<P>
<LI>
A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a "work that uses the Library".  Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.
<P>
  However, linking a "work that uses the Library" with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a "work that uses the
library".  The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.
<P>
  When a "work that uses the Library" uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library.  The
threshold for this to be true is not precisely defined by law.
<P>
  If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work.  (Executables containing this object code plus portions of the
Library will still fall under Section 6.)
<P>
  Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.
<P>
<LI>
As an exception to the Sections above, you may also compile or
link a "work that uses the Library" with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.
<P>
  You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License.  You must supply a copy of this License.  If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License.  Also, you must do one
of these things:
<P>
<OL>
<LI>
Accompany the work with the complete corresponding
machine-readable source code for the Library including whatever
changes were used in the work (which must be distributed under
Sections 1 and 2 above); and, if the work is an executable linked
with the Library, with the complete machine-readable "work that
uses the Library", as object code and/or source code, so that the
user can modify the Library and then relink to produce a modified
executable containing the modified Library.  (It is understood
that the user who changes the contents of definitions files in the
Library will not necessarily be able to recompile the application
to use the modified definitions.)
<P>
<LI>
Accompany the work with a written offer, valid for at
least three years, to give the same user the materials
specified in Subsection 6a, above, for a charge no more
than the cost of performing this distribution.
<P>
<LI>
If distribution of the work is made by offering access to copy
from a designated place, offer equivalent access to copy the above
specified materials from the same place.
<P>
<LI>
Verify that the user has already received a copy of these
materials or that you have already sent this user a copy.
</OL>
<P>
  For an executable, the required form of the "work that uses the
Library" must include any data and utility programs needed for
reproducing the executable from it.  However, as a special exception,
the source code distributed need not include anything that is normally
distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies
the executable.
<P>
  It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system.  Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.
<P>
<LI>
You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:
<P>
<OL>
<LI>
Accompany the combined library with a copy of the same work
based on the Library, uncombined with any other library
facilities.  This must be distributed under the terms of the
Sections above.
<P>
<LI>
Give prominent notice with the combined library of the fact
that part of it is a work based on the Library, and explaining
where to find the accompanying uncombined form of the same work.
</OL>
<P>
<LI>
You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License.  Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License.  However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.
<P>
<LI>
You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Library or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.
<P>
<LI>
Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.
<P>
<LI>
If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all.  For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.
<P>
If any portion of this section is held invalid or unenforceable under any
particular circumstance, the balance of the section is intended to apply,
and the section as a whole is intended to apply in other circumstances.
<P>
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
<P>
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
<P>
<LI>
If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License may add
an explicit geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not thus
excluded.  In such case, this License incorporates the limitation as if
written in the body of this License.
<P>
<LI>
The Free Software Foundation may publish revised and/or new
versions of the Library General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.
<P>
Each version is given a distinguishing version number.  If the Library
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation.  If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.
<P>
<LI>
If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission.  For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this.  Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.
<P>
<H2>NO WARRANTY</H2>
<P>
<LI>
BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
<P>
<LI>
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
</OL>
<P>
<H2>END OF TERMS AND CONDITIONS</H2>
<P>
<H2><A NAME="SEC504" HREF="library_toc.html#SEC504">How to Apply These Terms to Your New Libraries</A></H2>
<P>
  If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change.  You can do so by permitting
redistribution under these terms (or, alternatively, under the terms of the
ordinary General Public License).
<P>
  To apply these terms, attach the following notices to the library.  It is
safest to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.
<P>
<PRE>
<VAR>one line to give the library's name and an idea of what it does.</VAR>
Copyright (C) <VAR>year</VAR>  <VAR>name of author</VAR>

This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Library General Public License as published
by the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.

This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Library General Public License for more details.

You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
</PRE>
<P>
Also add information on how to contact you by electronic and paper mail.
<P>
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the library, if
necessary.  Here is a sample; alter the names:
<P>
<PRE>
Yoyodyne, Inc., hereby disclaims all copyright interest in the
library `Frob' (a library for tweaking knobs) written by James Random Hacker.

<VAR>signature of Ty Coon</VAR>, 1 April 1990
Ty Coon, President of Vice
</PRE>
<P>
That's all there is to it!
<P>
<H1><A NAME="SEC505" HREF="library_toc.html#SEC505">Concept Index</A></H1>
<P>
<DIR>
<H2>4</H2>
<LI><A HREF="library.html#IDX11">4.x BSD Unix</A>
<H2>_</H2>
<LI><A HREF="library.html#IDX1664">_POSIX_OPTION_ORDER environment variable.</A>
<H2>a</H2>
<LI><A HREF="library.html#IDX1485">abort signal</A>
<LI><A HREF="library.html#IDX1675">aborting a program</A>
<LI><A HREF="library.html#IDX432">absolute file name</A>
<LI><A HREF="library.html#IDX1303">absolute value functions</A>
<LI><A HREF="library.html#IDX1036">accepting connections</A>
<LI><A HREF="library.html#IDX839">access permission for a file</A>
<LI><A HREF="library.html#IDX851">access, testing for</A>
<LI><A HREF="library.html#IDX732">accessing directories</A>
<LI><A HREF="library.html#IDX910">address of socket</A>
<LI><A HREF="library.html#IDX1500">alarm signal</A>
<LI><A HREF="library.html#IDX1397">alarms, setting</A>
<LI><A HREF="library.html#IDX201">alignment (in obstacks)</A>
<LI><A HREF="library.html#IDX153">alignment (with <CODE>malloc</CODE>)</A>
<LI><A HREF="library.html#IDX212"><CODE>alloca</CODE> disadvantages</A>
<LI><A HREF="library.html#IDX207"><CODE>alloca</CODE> function</A>
<LI><A HREF="library.html#IDX176">allocation (obstacks)</A>
<LI><A HREF="library.html#IDX161">allocation hooks, for <CODE>malloc</CODE></A>
<LI><A HREF="library.html#IDX138">allocation of memory with <CODE>malloc</CODE></A>
<LI><A HREF="library.html#IDX272">allocation size of string</A>
<LI><A HREF="library.html#IDX166">allocation statistics</A>
<LI><A HREF="library.html#IDX235">alphabetic character</A>
<LI><A HREF="library.html#IDX240">alphanumeric character</A>
<LI><A HREF="library.html#IDX3">ANSI C</A>
<LI><A HREF="library.html#IDX627">append mode (file status flag)</A>
<LI><A HREF="library.html#IDX424">append-access files</A>
<LI><A HREF="library.html#IDX1626">argc (program argument count)</A>
<LI><A HREF="library.html#IDX1938">argument promotion</A>
<LI><A HREF="library.html#IDX1929">arguments (variadic functions)</A>
<LI><A HREF="library.html#IDX1933">arguments, how many</A>
<LI><A HREF="library.html#IDX1627">argv (program argument vector)</A>
<LI><A HREF="library.html#IDX412">arithmetic expansion</A>
<LI><A HREF="library.html#IDX298">array comparison functions</A>
<LI><A HREF="library.html#IDX281">array copy functions</A>
<LI><A HREF="library.html#IDX384">array search function</A>
<LI><A HREF="library.html#IDX389">array sort function</A>
<LI><A HREF="library.html#IDX256">ASCII character</A>
<LI><A HREF="library.html#IDX1918">assertions</A>
<LI><A HREF="library.html#IDX781">attributes of a file</A>
<LI><A HREF="library.html#IDX134">automatic allocation</A>
<LI><A HREF="library.html#IDX206">automatic freeing</A>
<LI><A HREF="library.html#IDX208">automatic storage with variable size</A>
<H2>b</H2>
<LI><A HREF="library.html#IDX1738">background job</A>
<LI><A HREF="library.html#IDX1754">background job, launching</A>
<LI><A HREF="library.html#IDX1965">base (of floating point number)</A>
<LI><A HREF="library.html#IDX333">basic byte sequence</A>
<LI><A HREF="library.html#IDX1156">baud rate</A>
<LI><A HREF="library.html#IDX12">Berkeley Unix</A>
<LI><A HREF="library.html#IDX1968">bias (of floating point number exponent)</A>
<LI><A HREF="library.html#IDX984">big-endian</A>
<LI><A HREF="library.html#IDX543">binary I/O to a stream</A>
<LI><A HREF="library.html#IDX383">binary search function (for arrays)</A>
<LI><A HREF="library.html#IDX557">binary stream</A>
<LI><A HREF="library.html#IDX912">binding a socket address</A>
<LI><A HREF="library.html#IDX248">blank character</A>
<LI><A HREF="library.html#IDX544">block I/O to a stream</A>
<LI><A HREF="library.html#IDX1456">blocked signals</A>
<LI><A HREF="library.html#IDX1599">blocked signals, checking for</A>
<LI><A HREF="library.html#IDX1581">blocking signals</A>
<LI><A HREF="library.html#IDX1597">blocking signals, in a handler</A>
<LI><A HREF="library.html#IDX1109">break condition, detecting</A>
<LI><A HREF="library.html#IDX1225">break condition, generating</A>
<LI><A HREF="library.html#IDX326">breaking a string into tokens</A>
<LI><A HREF="library.html#IDX1525">broken pipe signal</A>
<LI><A HREF="library.html#IDX1376">broken-down time</A>
<LI><A HREF="library.html#IDX1770">BSD compatibility library</A>
<LI><A HREF="library.html#IDX10">BSD Unix</A>
<LI><A HREF="library.html#IDX576">buffering of streams</A>
<LI><A HREF="library.html#IDX583">buffering, controlling</A>
<LI><A HREF="library.html#IDX1483">bus error</A>
<LI><A HREF="library.html#IDX982">byte order conversion, for socket</A>
<LI><A HREF="library.html#IDX894">byte stream</A>
<H2>c</H2>
<LI><A HREF="library.html#IDX1361">calendar time</A>
<LI><A HREF="library.html#IDX1377">calendar time and broken-down time</A>
<LI><A HREF="library.html#IDX1935">calling variadic functions</A>
<LI><A HREF="library.html#IDX1088">canonical input processing</A>
<LI><A HREF="library.html#IDX1859">capacity limits, POSIX</A>
<LI><A HREF="library.html#IDX1122">carrier detect</A>
<LI><A HREF="library.html#IDX259">case conversion of characters</A>
<LI><A HREF="library.html#IDX1460">catching signals</A>
<LI><A HREF="library.html#IDX359">categories for locales</A>
<LI><A HREF="library.html#IDX726">change working directory</A>
<LI><A HREF="library.html#IDX368">changing the locale</A>
<LI><A HREF="library.html#IDX146">changing the size of a block (<CODE>malloc</CODE>)</A>
<LI><A HREF="library.html#IDX184">changing the size of a block (obstacks)</A>
<LI><A HREF="library.html#IDX664">channels</A>
<LI><A HREF="library.html#IDX258">character case conversion</A>
<LI><A HREF="library.html#IDX341">character code</A>
<LI><A HREF="library.html#IDX229">character predicates</A>
<LI><A HREF="library.html#IDX226">character testing</A>
<LI><A HREF="library.html#IDX1600">checking for pending signals</A>
<LI><A HREF="library.html#IDX1691">child process</A>
<LI><A HREF="library.html#IDX1512">child process signal</A>
<LI><A HREF="library.html#IDX204">chunks</A>
<LI><A HREF="library.html#IDX227">classification of characters</A>
<LI><A HREF="library.html#IDX669">cleaning up a stream</A>
<LI><A HREF="library.html#IDX1230">clearing terminal input queue</A>
<LI><A HREF="library.html#IDX1024">client</A>
<LI><A HREF="library.html#IDX1347">clock ticks</A>
<LI><A HREF="library.html#IDX700">close-on-exec (file descriptor flag)</A>
<LI><A HREF="library.html#IDX619">closing a file descriptor</A>
<LI><A HREF="library.html#IDX1013">closing a socket</A>
<LI><A HREF="library.html#IDX454">closing a stream</A>
<LI><A HREF="library.html#IDX340">code, character</A>
<LI><A HREF="library.html#IDX308">collating strings</A>
<LI><A HREF="library.html#IDX358">combining locales</A>
<LI><A HREF="library.html#IDX1630">command argument syntax</A>
<LI><A HREF="library.html#IDX1633">command arguments, parsing</A>
<LI><A HREF="library.html#IDX1624">command line arguments</A>
<LI><A HREF="library.html#IDX411">command substitution</A>
<LI><A HREF="library.html#IDX891">communication style (of a socket)</A>
<LI><A HREF="library.html#IDX296">comparing strings and arrays</A>
<LI><A HREF="library.html#IDX380">Comparison Function</A>
<LI><A HREF="library.html#IDX282">concatenating strings</A>
<LI><A HREF="library.html#IDX1026">connecting a socket</A>
<LI><A HREF="library.html#IDX1023">connection</A>
<LI><A HREF="library.html#IDX1916">consistency checking</A>
<LI><A HREF="library.html#IDX158">consistency checking, of heap</A>
<LI><A HREF="library.html#IDX1514">continue signal</A>
<LI><A HREF="library.html#IDX254">control character</A>
<LI><A HREF="library.html#IDX684">control operations on files</A>
<LI><A HREF="library.html#IDX1741">controlling process</A>
<LI><A HREF="library.html#IDX1736">controlling terminal</A>
<LI><A HREF="library.html#IDX1742">controlling terminal, access to</A>
<LI><A HREF="library.html#IDX1761">controlling terminal, determining</A>
<LI><A HREF="library.html#IDX482">conversion specifications (<CODE>printf</CODE>)</A>
<LI><A HREF="library.html#IDX530">conversion specifications (<CODE>scanf</CODE>)</A>
<LI><A HREF="library.html#IDX983">converting byte order</A>
<LI><A HREF="library.html#IDX260">converting case of characters</A>
<LI><A HREF="library.html#IDX352">converting extended characters</A>
<LI><A HREF="library.html#IDX343">converting extended strings</A>
<LI><A HREF="library.html#IDX650">converting file descriptor to stream</A>
<LI><A HREF="library.html#IDX1319">converting floats to integers</A>
<LI><A HREF="library.html#IDX1838">converting group ID to group name</A>
<LI><A HREF="library.html#IDX1837">converting group name to group ID</A>
<LI><A HREF="library.html#IDX953">converting host address to name</A>
<LI><A HREF="library.html#IDX952">converting host name to address</A>
<LI><A HREF="library.html#IDX1071">converting network name to network number</A>
<LI><A HREF="library.html#IDX1070">converting network number to network name</A>
<LI><A HREF="library.html#IDX973">converting port number to service name</A>
<LI><A HREF="library.html#IDX972">converting service name to port number</A>
<LI><A HREF="library.html#IDX312">converting string to collation order</A>
<LI><A HREF="library.html#IDX1334">converting strings to numbers</A>
<LI><A HREF="library.html#IDX1823">converting user ID to user name</A>
<LI><A HREF="library.html#IDX1824">converting user name to user ID</A>
<LI><A HREF="library.html#IDX609">cookie, for custom stream</A>
<LI><A HREF="library.html#IDX279">copying strings and arrays</A>
<LI><A HREF="library.html#IDX1345">CPU time</A>
<LI><A HREF="library.html#IDX629">create on open (file status flag)</A>
<LI><A HREF="library.html#IDX774">creating a directory</A>
<LI><A HREF="library.html#IDX885">creating a FIFO special file</A>
<LI><A HREF="library.html#IDX875">creating a pipe</A>
<LI><A HREF="library.html#IDX880">creating a pipe to a subprocess</A>
<LI><A HREF="library.html#IDX1689">creating a process</A>
<LI><A HREF="library.html#IDX1007">creating a socket</A>
<LI><A HREF="library.html#IDX1018">creating a socket pair</A>
<LI><A HREF="library.html#IDX869">creating special files</A>
<LI><A HREF="library.html#IDX1269">cube root function</A>
<LI><A HREF="library.html#IDX379">currency symbols</A>
<LI><A HREF="library.html#IDX724">current working directory</A>
<LI><A HREF="library.html#IDX607">custom streams</A>
<LI><A HREF="library.html#IDX517">customizing <CODE>printf</CODE></A>
<H2>d</H2>
<LI><A HREF="library.html#IDX897">data loss on sockets</A>
<LI><A HREF="library.html#IDX1052">datagram socket</A>
<LI><A HREF="library.html#IDX1055">datagrams, transmitting</A>
<LI><A HREF="library.html#IDX1360">date and time</A>
<LI><A HREF="library.html#IDX1380">Daylight Saving Time</A>
<LI><A HREF="library.html#IDX238">decimal digit character</A>
<LI><A HREF="library.html#IDX377">decimal-point separator</A>
<LI><A HREF="library.html#IDX20">declaration (compared to definition)</A>
<LI><A HREF="library.html#IDX1936">declaring variadic functions</A>
<LI><A HREF="library.html#IDX1458">default action (for a signal)</A>
<LI><A HREF="library.html#IDX1542">default action for a signal</A>
<LI><A HREF="library.html#IDX1937">default argument promotions</A>
<LI><A HREF="library.html#IDX518">defining new <CODE>printf</CODE> conversions</A>
<LI><A HREF="library.html#IDX19">definition (compared to declaration)</A>
<LI><A HREF="library.html#IDX1211">delayed suspend character</A>
<LI><A HREF="library.html#IDX770">deleting a directory</A>
<LI><A HREF="library.html#IDX761">deleting a file</A>
<LI><A HREF="library.html#IDX1454">delivery of signals</A>
<LI><A HREF="library.html#IDX666">descriptors and streams</A>
<LI><A HREF="library.html#IDX237">digit character</A>
<LI><A HREF="library.html#IDX734">directories, accessing</A>
<LI><A HREF="library.html#IDX775">directories, creating</A>
<LI><A HREF="library.html#IDX769">directories, deleting</A>
<LI><A HREF="library.html#IDX426">directory</A>
<LI><A HREF="library.html#IDX428">directory entry</A>
<LI><A HREF="library.html#IDX735">directory stream</A>
<LI><A HREF="library.html#IDX213">disadvantages of <CODE>alloca</CODE></A>
<LI><A HREF="library.html#IDX1217">DISCARD character</A>
<LI><A HREF="library.html#IDX899">domain (of socket)</A>
<LI><A HREF="library.html#IDX1247">domain error</A>
<LI><A HREF="library.html#IDX940">dot notation, for Internet addresses</A>
<LI><A HREF="library.html#IDX1210">DSUSP character</A>
<LI><A HREF="library.html#IDX688">duplicating file descriptors</A>
<LI><A HREF="library.html#IDX132">dynamic allocation</A>
<H2>e</H2>
<LI><A HREF="library.html#IDX1139">echo of terminal input</A>
<LI><A HREF="library.html#IDX1786">effective group ID</A>
<LI><A HREF="library.html#IDX1785">effective user ID</A>
<LI><A HREF="library.html#IDX151">efficiency and <CODE>malloc</CODE></A>
<LI><A HREF="library.html#IDX192">efficiency and obstacks</A>
<LI><A HREF="library.html#IDX203">efficiency of chunks</A>
<LI><A HREF="library.html#IDX550">end of file, on a stream</A>
<LI><A HREF="library.html#IDX641">end-of-file, on a file descriptor</A>
<LI><A HREF="library.html#IDX1644">environment</A>
<LI><A HREF="library.html#IDX1645">environment access</A>
<LI><A HREF="library.html#IDX1646">environment representation</A>
<LI><A HREF="library.html#IDX1643">environment variable</A>
<LI><A HREF="library.html#IDX1186">EOF character</A>
<LI><A HREF="library.html#IDX1188">EOL character</A>
<LI><A HREF="library.html#IDX1194">EOL2 character</A>
<LI><A HREF="library.html#IDX1366">epoch</A>
<LI><A HREF="library.html#IDX1190">ERASE character</A>
<LI><A HREF="library.html#IDX43">error codes</A>
<LI><A HREF="library.html#IDX41">error reporting</A>
<LI><A HREF="library.html#IDX1536">establishing a handler</A>
<LI><A HREF="library.html#IDX1469">exception</A>
<LI><A HREF="library.html#IDX708">exclusive lock</A>
<LI><A HREF="library.html#IDX1703"><CODE>exec</CODE> functions</A>
<LI><A HREF="library.html#IDX1702">executing a file</A>
<LI><A HREF="library.html#IDX1669">exit status</A>
<LI><A HREF="library.html#IDX1667">exit status value</A>
<LI><A HREF="library.html#IDX407">expansion of shell words</A>
<LI><A HREF="library.html#IDX1967">exponent (of floating point number)</A>
<LI><A HREF="library.html#IDX1260">exponentiation functions</A>
<LI><A HREF="library.html#IDX330">extended character sets</A>
<LI><A HREF="library.html#IDX351">extended characters, converting</A>
<LI><A HREF="library.html#IDX342">extended strings, converting representations</A>
<LI><A HREF="library.html#IDX519">extending <CODE>printf</CODE></A>
<LI><A HREF="library.html#IDX651">extracting file descriptor from stream</A>
<H2>f</H2>
<LI><A HREF="library.html#IDX685"><CODE>fcntl</CODE> function</A>
<LI><A HREF="library.html#IDX35">feature test macros</A>
<LI><A HREF="library.html#IDX413">field splitting</A>
<LI><A HREF="library.html#IDX874">FIFO special file</A>
<LI><A HREF="library.html#IDX840">file access permission</A>
<LI><A HREF="library.html#IDX860">file access time</A>
<LI><A HREF="library.html#IDX862">file attribute modification time</A>
<LI><A HREF="library.html#IDX782">file attributes</A>
<LI><A HREF="library.html#IDX841">file creation mask</A>
<LI><A HREF="library.html#IDX695">file descriptor flags</A>
<LI><A HREF="library.html#IDX676">file descriptor sets, for <CODE>select</CODE></A>
<LI><A HREF="library.html#IDX656">file descriptors, standard</A>
<LI><A HREF="library.html#IDX706">file locks</A>
<LI><A HREF="library.html#IDX861">file modification time</A>
<LI><A HREF="library.html#IDX425">file name</A>
<LI><A HREF="library.html#IDX429">file name component</A>
<LI><A HREF="library.html#IDX430">file name resolution</A>
<LI><A HREF="library.html#IDX435">file name syntax errors</A>
<LI><A HREF="library.html#IDX751">file names, multiple</A>
<LI><A HREF="library.html#IDX924">file namespace, for sockets</A>
<LI><A HREF="library.html#IDX809">file owner</A>
<LI><A HREF="library.html#IDX818">file permission bits</A>
<LI><A HREF="library.html#IDX437">file pointer</A>
<LI><A HREF="library.html#IDX421">file position</A>
<LI><A HREF="library.html#IDX644">file positioning on a file descriptor</A>
<LI><A HREF="library.html#IDX559">file positioning on a stream</A>
<LI><A HREF="library.html#IDX701">file status flags</A>
<LI><A HREF="library.html#IDX882">filtering i/o through subprocess</A>
<LI><A HREF="library.html#IDX483">flag character (<CODE>printf</CODE>)</A>
<LI><A HREF="library.html#IDX532">flag character (<CODE>scanf</CODE>)</A>
<LI><A HREF="library.html#IDX1552">flags for <CODE>sigaction</CODE></A>
<LI><A HREF="library.html#IDX1976">floating point, IEEE</A>
<LI><A HREF="library.html#IDX1960">floating type measurements</A>
<LI><A HREF="library.html#IDX1470">floating-point exception</A>
<LI><A HREF="library.html#IDX1236">flow control, terminal</A>
<LI><A HREF="library.html#IDX580">flushing a stream</A>
<LI><A HREF="library.html#IDX1227">flushing terminal output queue</A>
<LI><A HREF="library.html#IDX1737">foreground job</A>
<LI><A HREF="library.html#IDX1753">foreground job, launching</A>
<LI><A HREF="library.html#IDX1690">forking a process</A>
<LI><A HREF="library.html#IDX478">format string, for <CODE>printf</CODE></A>
<LI><A HREF="library.html#IDX528">format string, for <CODE>scanf</CODE></A>
<LI><A HREF="library.html#IDX526">formatted input from a stream</A>
<LI><A HREF="library.html#IDX480">formatted output to a stream</A>
<LI><A HREF="library.html#IDX180">freeing (obstacks)</A>
<LI><A HREF="library.html#IDX141">freeing memory allocated with <CODE>malloc</CODE></A>
<LI><A HREF="library.html#IDX579">fully buffered stream</A>
<LI><A HREF="library.html#IDX1925">function prototypes (variadic)</A>
<H2>g</H2>
<LI><A HREF="library.html#IDX1453">generation of signals</A>
<LI><A HREF="library.html#IDX396">globbing</A>
<LI><A HREF="library.html#IDX250">graphic character</A>
<LI><A HREF="library.html#IDX1358">Gregorian calendar</A>
<LI><A HREF="library.html#IDX1833">group database</A>
<LI><A HREF="library.html#IDX1783">group ID</A>
<LI><A HREF="library.html#IDX1782">group name</A>
<LI><A HREF="library.html#IDX811">group owner of a file</A>
<LI><A HREF="library.html#IDX378">grouping of digits</A>
<LI><A HREF="library.html#IDX183">growing objects (in obstacks)</A>
<H2>h</H2>
<LI><A HREF="library.html#IDX216">handle</A>
<LI><A HREF="library.html#IDX1562">handling multiple signals</A>
<LI><A HREF="library.html#IDX1488">hangup signal</A>
<LI><A HREF="library.html#IDX748">hard link</A>
<LI><A HREF="library.html#IDX18">header files</A>
<LI><A HREF="library.html#IDX157">heap consistency checking</A>
<LI><A HREF="library.html#IDX137">heap, dynamic allocation from</A>
<LI><A HREF="library.html#IDX142">heap, freeing memory from</A>
<LI><A HREF="library.html#IDX242">hexadecimal digit character</A>
<LI><A HREF="library.html#IDX1972">hidden bit (of floating point number mantissa)</A>
<LI><A HREF="library.html#IDX1050">high-priority data</A>
<LI><A HREF="library.html#IDX1362">high-resolution time</A>
<LI><A HREF="library.html#IDX1653">home directory</A>
<LI><A HREF="library.html#IDX1652">HOME environment variable</A>
<LI><A HREF="library.html#IDX613">hook functions (of custom streams)</A>
<LI><A HREF="library.html#IDX935">host address, Internet</A>
<LI><A HREF="library.html#IDX951">hosts database</A>
<LI><A HREF="library.html#IDX1932">how many arguments</A>
<LI><A HREF="library.html#IDX1274">hyperbolic functions</A>
<H2>i</H2>
<LI><A HREF="library.html#IDX1081">identifying terminals</A>
<LI><A HREF="library.html#IDX1296">IEEE floating point</A>
<LI><A HREF="library.html#IDX1975">IEEE floating point representation</A>
<LI><A HREF="library.html#IDX7">IEEE Std 1003.1</A>
<LI><A HREF="library.html#IDX9">IEEE Std 1003.2</A>
<LI><A HREF="library.html#IDX1544">ignore action for a signal</A>
<LI><A HREF="library.html#IDX1479">illegal instruction</A>
<LI><A HREF="library.html#IDX1917">impossible events</A>
<LI><A HREF="library.html#IDX670">independent channels</A>
<LI><A HREF="library.html#IDX1558">initial signal actions</A>
<LI><A HREF="library.html#IDX786">inode number</A>
<LI><A HREF="library.html#IDX1506">input available signal</A>
<LI><A HREF="library.html#IDX535">input conversions, for <CODE>scanf</CODE></A>
<LI><A HREF="library.html#IDX674">input from multiple files</A>
<LI><A HREF="library.html#IDX1978">installing the library</A>
<LI><A HREF="library.html#IDX1327">integer division functions</A>
<LI><A HREF="library.html#IDX1957">integer type range</A>
<LI><A HREF="library.html#IDX1953">integer type width</A>
<LI><A HREF="library.html#IDX1144">interactive signals, from terminal</A>
<LI><A HREF="library.html#IDX1518">interactive stop signal</A>
<LI><A HREF="library.html#IDX356">internationalization</A>
<LI><A HREF="library.html#IDX936">Internet host address</A>
<LI><A HREF="library.html#IDX930">Internet namespace, for sockets</A>
<LI><A HREF="library.html#IDX886">interprocess communication, with FIFO</A>
<LI><A HREF="library.html#IDX877">interprocess communication, with pipes</A>
<LI><A HREF="library.html#IDX1580">interprocess communication, with signals</A>
<LI><A HREF="library.html#IDX890">interprocess communication, with sockets</A>
<LI><A HREF="library.html#IDX1203">interrupt character</A>
<LI><A HREF="library.html#IDX1490">interrupt signal</A>
<LI><A HREF="library.html#IDX720">interrupt-driven input</A>
<LI><A HREF="library.html#IDX1396">interval timer, setting</A>
<LI><A HREF="library.html#IDX1202">INTR character</A>
<LI><A HREF="library.html#IDX1278">inverse hyperbolic functions</A>
<LI><A HREF="library.html#IDX1255">inverse trigonmetric functions</A>
<H2>j</H2>
<LI><A HREF="library.html#IDX1731">job</A>
<LI><A HREF="library.html#IDX1730">job control</A>
<LI><A HREF="library.html#IDX1760">job control functions</A>
<LI><A HREF="library.html#IDX1740">job control is optional</A>
<LI><A HREF="library.html#IDX1510">job control signals</A>
<LI><A HREF="library.html#IDX1748">job control, enabling</A>
<H2>k</H2>
<LI><A HREF="library.html#IDX393">Kermit the frog</A>
<LI><A HREF="library.html#IDX1192">KILL character</A>
<LI><A HREF="library.html#IDX1498">kill signal</A>
<LI><A HREF="library.html#IDX1576">killing a process</A>
<H2>l</H2>
<LI><A HREF="library.html#IDX1658">LANG environment variable</A>
<LI><A HREF="library.html#IDX1749">launching jobs</A>
<LI><A HREF="library.html#IDX1659">LC_COLLATE environment variable</A>
<LI><A HREF="library.html#IDX1660">LC_CTYPE environment variable</A>
<LI><A HREF="library.html#IDX1661">LC_MONETARY environment variable</A>
<LI><A HREF="library.html#IDX1662">LC_NUMERIC environment variable</A>
<LI><A HREF="library.html#IDX1663">LC_TIME environment variable</A>
<LI><A HREF="library.html#IDX1379">leap second</A>
<LI><A HREF="library.html#IDX348">length of multibyte character</A>
<LI><A HREF="library.html#IDX271">length of string</A>
<LI><A HREF="library.html#IDX1061">level, for socket options</A>
<LI><A HREF="library.html#IDX1">library</A>
<LI><A HREF="library.html#IDX1416">limits on resource usage</A>
<LI><A HREF="library.html#IDX1893">limits, file name length</A>
<LI><A HREF="library.html#IDX1963">limits, floating types</A>
<LI><A HREF="library.html#IDX1959">limits, integer types</A>
<LI><A HREF="library.html#IDX1888">limits, link count of files</A>
<LI><A HREF="library.html#IDX1865">limits, number of open files</A>
<LI><A HREF="library.html#IDX1863">limits, number of processes</A>
<LI><A HREF="library.html#IDX1870">limits, number of supplementary group IDs</A>
<LI><A HREF="library.html#IDX1896">limits, pipe buffer size</A>
<LI><A HREF="library.html#IDX1858">limits, POSIX</A>
<LI><A HREF="library.html#IDX1861">limits, program argument size</A>
<LI><A HREF="library.html#IDX1890">limits, terminal input queue</A>
<LI><A HREF="library.html#IDX1868">limits, time zone name length</A>
<LI><A HREF="library.html#IDX578">line buffered stream</A>
<LI><A HREF="library.html#IDX1155">line speed</A>
<LI><A HREF="library.html#IDX558">lines (in a text file)</A>
<LI><A HREF="library.html#IDX427">link</A>
<LI><A HREF="library.html#IDX749">link, hard</A>
<LI><A HREF="library.html#IDX755">link, soft</A>
<LI><A HREF="library.html#IDX757">link, symbolic</A>
<LI><A HREF="library.html#IDX668">linked channels</A>
<LI><A HREF="library.html#IDX1031">listening (sockets)</A>
<LI><A HREF="library.html#IDX985">little-endian</A>
<LI><A HREF="library.html#IDX1200">LNEXT character</A>
<LI><A HREF="library.html#IDX938">local network address number</A>
<LI><A HREF="library.html#IDX1363">local time</A>
<LI><A HREF="library.html#IDX360">locale categories</A>
<LI><A HREF="library.html#IDX369">locale, changing</A>
<LI><A HREF="library.html#IDX357">locales</A>
<LI><A HREF="library.html#IDX1262">logarithm functions</A>
<LI><A HREF="library.html#IDX1779">login name</A>
<LI><A HREF="library.html#IDX1811">login name, determining</A>
<LI><A HREF="library.html#IDX1654">LOGNAME environment variable</A>
<LI><A HREF="library.html#IDX1443">long jumps</A>
<LI><A HREF="library.html#IDX1631">long-named options</A>
<LI><A HREF="library.html#IDX211">longjmp</A>
<LI><A HREF="library.html#IDX896">loss of data on sockets</A>
<LI><A HREF="library.html#IDX231">lower-case character</A>
<H2>m</H2>
<LI><A HREF="library.html#IDX182">macros</A>
<LI><A HREF="library.html#IDX1625"><CODE>main</CODE> function</A>
<LI><A HREF="library.html#IDX136"><CODE>malloc</CODE> function</A>
<LI><A HREF="library.html#IDX1969">mantissa (of floating point number)</A>
<LI><A HREF="library.html#IDX531">matching failure, in <CODE>scanf</CODE></A>
<LI><A HREF="library.html#IDX533">maximum field width (<CODE>scanf</CODE>)</A>
<LI><A HREF="library.html#IDX1961">measurements of floating types</A>
<LI><A HREF="library.html#IDX130">memory allocation</A>
<LI><A HREF="library.html#IDX221">memory usage warnings</A>
<LI><A HREF="library.html#IDX1564">merging of signals</A>
<LI><A HREF="library.html#IDX1221">MIN termios slot</A>
<LI><A HREF="library.html#IDX484">minimum field width (<CODE>printf</CODE>)</A>
<LI><A HREF="library.html#IDX667">mixing descriptors and streams</A>
<LI><A HREF="library.html#IDX1123">modem disconnect</A>
<LI><A HREF="library.html#IDX1121">modem status lines</A>
<LI><A HREF="library.html#IDX373">monetary value formatting</A>
<LI><A HREF="library.html#IDX347">multibyte character, length of</A>
<LI><A HREF="library.html#IDX332">multibyte characters</A>
<LI><A HREF="library.html#IDX750">multiple names for one file</A>
<LI><A HREF="library.html#IDX673">multiplexing input</A>
<H2>n</H2>
<LI><A HREF="library.html#IDX127">name of running program</A>
<LI><A HREF="library.html#IDX911">name of socket</A>
<LI><A HREF="library.html#IDX25">name space</A>
<LI><A HREF="library.html#IDX1462">names of signals</A>
<LI><A HREF="library.html#IDX898">namespace (of socket)</A>
<LI><A HREF="library.html#IDX1294">NaN</A>
<LI><A HREF="library.html#IDX986">network byte order</A>
<LI><A HREF="library.html#IDX937">network number</A>
<LI><A HREF="library.html#IDX902">network protocol</A>
<LI><A HREF="library.html#IDX1069">networks database</A>
<LI><A HREF="library.html#IDX633">non-blocking mode (file status flag)</A>
<LI><A HREF="library.html#IDX1560">non-local exit, from signal handler</A>
<LI><A HREF="library.html#IDX1442">non-local exits</A>
<LI><A HREF="library.html#IDX1089">noncanonical input processing</A>
<LI><A HREF="library.html#IDX1310">normalization functions (floating-point)</A>
<LI><A HREF="library.html#IDX1973">normalized floating point number</A>
<LI><A HREF="library.html#IDX1295">not a number</A>
<LI><A HREF="library.html#IDX269">null character</A>
<LI><A HREF="library.html#IDX1948">null pointer constant</A>
<LI><A HREF="library.html#IDX1931">number of arguments passed</A>
<LI><A HREF="library.html#IDX1335">number syntax, parsing</A>
<LI><A HREF="library.html#IDX374">numeric value formatting</A>
<H2>o</H2>
<LI><A HREF="library.html#IDX196">obstack status</A>
<LI><A HREF="library.html#IDX170">obstacks</A>
<LI><A HREF="library.html#IDX420">opening a file</A>
<LI><A HREF="library.html#IDX618">opening a file descriptor</A>
<LI><A HREF="library.html#IDX876">opening a pipe</A>
<LI><A HREF="library.html#IDX1009">opening a socket</A>
<LI><A HREF="library.html#IDX1020">opening a socket pair</A>
<LI><A HREF="library.html#IDX449">opening a stream</A>
<LI><A HREF="library.html#IDX1924">optional arguments</A>
<LI><A HREF="library.html#IDX1875">optional POSIX features</A>
<LI><A HREF="library.html#IDX1745">orphaned process group</A>
<LI><A HREF="library.html#IDX1049">out-of-band data</A>
<LI><A HREF="library.html#IDX487">output conversions, for <CODE>printf</CODE></A>
<LI><A HREF="library.html#IDX1507">output possible signal</A>
<LI><A HREF="library.html#IDX810">owner of a file</A>
<H2>p</H2>
<LI><A HREF="library.html#IDX893">packet</A>
<LI><A HREF="library.html#IDX152">page boundary</A>
<LI><A HREF="library.html#IDX434">parent directory</A>
<LI><A HREF="library.html#IDX1692">parent process</A>
<LI><A HREF="library.html#IDX1104">parity checking</A>
<LI><A HREF="library.html#IDX502">parsing a template string</A>
<LI><A HREF="library.html#IDX1333">parsing numbers (in formatted input)</A>
<LI><A HREF="library.html#IDX1634">parsing program arguments</A>
<LI><A HREF="library.html#IDX327">parsing tokens from a string</A>
<LI><A HREF="library.html#IDX1819">password database</A>
<LI><A HREF="library.html#IDX1655">PATH environment variable</A>
<LI><A HREF="library.html#IDX1605"><CODE>pause</CODE> function</A>
<LI><A HREF="library.html#IDX474">peeking at input</A>
<LI><A HREF="library.html#IDX1455">pending signals</A>
<LI><A HREF="library.html#IDX1598">pending signals, checking for</A>
<LI><A HREF="library.html#IDX838">permission to access a file</A>
<LI><A HREF="library.html#IDX1784">persona</A>
<LI><A HREF="library.html#IDX1251">pi (trigonometric constant)</A>
<LI><A HREF="library.html#IDX873">pipe</A>
<LI><A HREF="library.html#IDX1524">pipe signal</A>
<LI><A HREF="library.html#IDX881">pipe to a subprocess</A>
<LI><A HREF="library.html#IDX967">port number</A>
<LI><A HREF="library.html#IDX645">positioning a file descriptor</A>
<LI><A HREF="library.html#IDX560">positioning a stream</A>
<LI><A HREF="library.html#IDX5">POSIX</A>
<LI><A HREF="library.html#IDX1857">POSIX capacity limits</A>
<LI><A HREF="library.html#IDX1874">POSIX optional features</A>
<LI><A HREF="library.html#IDX6">POSIX.1</A>
<LI><A HREF="library.html#IDX8">POSIX.2</A>
<LI><A HREF="library.html#IDX1261">power functions</A>
<LI><A HREF="library.html#IDX1971">precision (of floating point number)</A>
<LI><A HREF="library.html#IDX485">precision (<CODE>printf</CODE>)</A>
<LI><A HREF="library.html#IDX300">predicates on arrays</A>
<LI><A HREF="library.html#IDX228">predicates on characters</A>
<LI><A HREF="library.html#IDX299">predicates on strings</A>
<LI><A HREF="library.html#IDX252">printing character</A>
<LI><A HREF="library.html#IDX1432">priority of a process</A>
<LI><A HREF="library.html#IDX1680">process</A>
<LI><A HREF="library.html#IDX1711">process completion</A>
<LI><A HREF="library.html#IDX1759">process group functions</A>
<LI><A HREF="library.html#IDX1751">process group ID</A>
<LI><A HREF="library.html#IDX1750">process group leader</A>
<LI><A HREF="library.html#IDX1729">process groups</A>
<LI><A HREF="library.html#IDX1687">process ID</A>
<LI><A HREF="library.html#IDX1693">process image</A>
<LI><A HREF="library.html#IDX1688">process lifetime</A>
<LI><A HREF="library.html#IDX1431">process priority</A>
<LI><A HREF="library.html#IDX1591">process signal mask</A>
<LI><A HREF="library.html#IDX1666">process termination</A>
<LI><A HREF="library.html#IDX1346">processor time</A>
<LI><A HREF="library.html#IDX1504">profiling alarm signal</A>
<LI><A HREF="library.html#IDX1401">profiling timer</A>
<LI><A HREF="library.html#IDX1628">program argument syntax</A>
<LI><A HREF="library.html#IDX1623">program arguments</A>
<LI><A HREF="library.html#IDX1632">program arguments, parsing</A>
<LI><A HREF="library.html#IDX1466">program error signals</A>
<LI><A HREF="library.html#IDX126">program name</A>
<LI><A HREF="library.html#IDX1665">program termination</A>
<LI><A HREF="library.html#IDX1486">program termination signals</A>
<LI><A HREF="library.html#IDX608">programming your own streams</A>
<LI><A HREF="library.html#IDX903">protocol (of socket)</A>
<LI><A HREF="library.html#IDX905">protocol family</A>
<LI><A HREF="library.html#IDX992">protocols database</A>
<LI><A HREF="library.html#IDX1926">prototypes for variadic functions</A>
<LI><A HREF="library.html#IDX1283">pseudo-random numbers</A>
<LI><A HREF="library.html#IDX244">punctuation character</A>
<LI><A HREF="library.html#IDX476">pushing input back</A>
<H2>q</H2>
<LI><A HREF="library.html#IDX388">quick sort function (for arrays)</A>
<LI><A HREF="library.html#IDX1205">QUIT character</A>
<LI><A HREF="library.html#IDX1493">quit signal</A>
<LI><A HREF="library.html#IDX415">quote removal</A>
<H2>r</H2>
<LI><A HREF="library.html#IDX1752">race conditions, relating to job control</A>
<LI><A HREF="library.html#IDX1561">race conditions, relating to signals</A>
<LI><A HREF="library.html#IDX1966">radix (of floating point number)</A>
<LI><A HREF="library.html#IDX1571">raising signals</A>
<LI><A HREF="library.html#IDX1282">random numbers</A>
<LI><A HREF="library.html#IDX423">random-access files</A>
<LI><A HREF="library.html#IDX1248">range error</A>
<LI><A HREF="library.html#IDX1958">range of integer type</A>
<LI><A HREF="library.html#IDX711">read lock</A>
<LI><A HREF="library.html#IDX733">reading from a directory</A>
<LI><A HREF="library.html#IDX639">reading from a file descriptor</A>
<LI><A HREF="library.html#IDX1039">reading from a socket</A>
<LI><A HREF="library.html#IDX545">reading from a stream, by blocks</A>
<LI><A HREF="library.html#IDX464">reading from a stream, by characters</A>
<LI><A HREF="library.html#IDX527">reading from a stream, formatted</A>
<LI><A HREF="library.html#IDX1788">real group ID</A>
<LI><A HREF="library.html#IDX1787">real user ID</A>
<LI><A HREF="library.html#IDX1399">real-time timer</A>
<LI><A HREF="library.html#IDX1058">receiving datagrams</A>
<LI><A HREF="library.html#IDX707">record locking</A>
<LI><A HREF="library.html#IDX689">redirecting input and output</A>
<LI><A HREF="library.html#IDX1567">reentrant functions</A>
<LI><A HREF="library.html#IDX433">relative file name</A>
<LI><A HREF="library.html#IDX215">relocating memory allocator</A>
<LI><A HREF="library.html#IDX1318">remainder functions</A>
<LI><A HREF="library.html#IDX416">removal of quotes</A>
<LI><A HREF="library.html#IDX762">removing a file</A>
<LI><A HREF="library.html#IDX22">removing macros that shadow functions</A>
<LI><A HREF="library.html#IDX772">renaming a file</A>
<LI><A HREF="library.html#IDX1979">reporting bugs</A>
<LI><A HREF="library.html#IDX42">reporting errors</A>
<LI><A HREF="library.html#IDX1198">REPRINT character</A>
<LI><A HREF="library.html#IDX24">reserved names</A>
<LI><A HREF="library.html#IDX1415">resource limits</A>
<LI><A HREF="library.html#IDX1565">restrictions on signal handler functions</A>
<LI><A HREF="library.html#IDX431">root directory</A>
<LI><A HREF="library.html#IDX1317">rounding functions</A>
<LI><A HREF="library.html#IDX1683">running a command</A>
<H2>s</H2>
<LI><A HREF="library.html#IDX1841">scanning the group list</A>
<LI><A HREF="library.html#IDX1827">scanning the user list</A>
<LI><A HREF="library.html#IDX382">search function (for arrays)</A>
<LI><A HREF="library.html#IDX315">search functions (for strings)</A>
<LI><A HREF="library.html#IDX1284">seed (for random numbers)</A>
<LI><A HREF="library.html#IDX646">seeking on a file descriptor</A>
<LI><A HREF="library.html#IDX561">seeking on a stream</A>
<LI><A HREF="library.html#IDX1481">segmentation violation</A>
<LI><A HREF="library.html#IDX1053">sending a datagram</A>
<LI><A HREF="library.html#IDX1570">sending signals</A>
<LI><A HREF="library.html#IDX422">sequential-access files</A>
<LI><A HREF="library.html#IDX1025">server</A>
<LI><A HREF="library.html#IDX971">services database</A>
<LI><A HREF="library.html#IDX1734">session</A>
<LI><A HREF="library.html#IDX1735">session leader</A>
<LI><A HREF="library.html#IDX1395">setting an alarm</A>
<LI><A HREF="library.html#IDX1790"><CODE>setuid</CODE> programs</A>
<LI><A HREF="library.html#IDX852">setuid programs and file access</A>
<LI><A HREF="library.html#IDX21">shadowing functions with macros</A>
<LI><A HREF="library.html#IDX710">shared lock</A>
<LI><A HREF="library.html#IDX1733">shell</A>
<LI><A HREF="library.html#IDX191">shrinking objects</A>
<LI><A HREF="library.html#IDX1014">shutting down a socket</A>
<LI><A HREF="library.html#IDX1553"><CODE>sigaction</CODE> flags</A>
<LI><A HREF="library.html#IDX1547"><CODE>sigaction</CODE> function</A>
<LI><A HREF="library.html#IDX1757"><CODE>SIGCHLD</CODE>, handling of</A>
<LI><A HREF="library.html#IDX1964">sign (of floating point number)</A>
<LI><A HREF="library.html#IDX1452">signal</A>
<LI><A HREF="library.html#IDX1459">signal action</A>
<LI><A HREF="library.html#IDX1535">signal actions</A>
<LI><A HREF="library.html#IDX1551">signal flags</A>
<LI><A HREF="library.html#IDX1537"><CODE>signal</CODE> function</A>
<LI><A HREF="library.html#IDX1559">signal handler function</A>
<LI><A HREF="library.html#IDX1590">signal mask</A>
<LI><A HREF="library.html#IDX1529">signal messages</A>
<LI><A HREF="library.html#IDX1461">signal names</A>
<LI><A HREF="library.html#IDX1464">signal number</A>
<LI><A HREF="library.html#IDX1582">signal set</A>
<LI><A HREF="library.html#IDX1608">signal stack</A>
<LI><A HREF="library.html#IDX1572">signals, generating</A>
<LI><A HREF="library.html#IDX1970">significand (of floating point number)</A>
<LI><A HREF="library.html#IDX1743"><CODE>SIGTTIN</CODE>, from background job</A>
<LI><A HREF="library.html#IDX1744"><CODE>SIGTTOU</CODE>, from background job</A>
<LI><A HREF="library.html#IDX273">size of string</A>
<LI><A HREF="library.html#IDX889">socket</A>
<LI><A HREF="library.html#IDX913">socket address (name) binding</A>
<LI><A HREF="library.html#IDX901">socket domain</A>
<LI><A HREF="library.html#IDX900">socket namespace</A>
<LI><A HREF="library.html#IDX1062">socket option level</A>
<LI><A HREF="library.html#IDX1060">socket options</A>
<LI><A HREF="library.html#IDX1019">socket pair</A>
<LI><A HREF="library.html#IDX904">socket protocol</A>
<LI><A HREF="library.html#IDX1015">socket shutdown</A>
<LI><A HREF="library.html#IDX1029">socket, client actions</A>
<LI><A HREF="library.html#IDX1012">socket, closing</A>
<LI><A HREF="library.html#IDX1027">socket, connecting</A>
<LI><A HREF="library.html#IDX1008">socket, creating</A>
<LI><A HREF="library.html#IDX1028">socket, initiating a connection</A>
<LI><A HREF="library.html#IDX1035">sockets, accepting connections</A>
<LI><A HREF="library.html#IDX1033">sockets, listening</A>
<LI><A HREF="library.html#IDX1032">sockets, server actions</A>
<LI><A HREF="library.html#IDX754">soft link</A>
<LI><A HREF="library.html#IDX387">sort function (for arrays)</A>
<LI><A HREF="library.html#IDX870">special files</A>
<LI><A HREF="library.html#IDX1457">specified action (for a signal)</A>
<LI><A HREF="library.html#IDX1267">square root function</A>
<LI><A HREF="library.html#IDX392">stable sorting</A>
<LI><A HREF="library.html#IDX939">standard dot notation, for Internet addresses</A>
<LI><A HREF="library.html#IDX1651">standard environment variables</A>
<LI><A HREF="library.html#IDX663">standard error file descriptor</A>
<LI><A HREF="library.html#IDX448">standard error stream</A>
<LI><A HREF="library.html#IDX655">standard file descriptors</A>
<LI><A HREF="library.html#IDX659">standard input file descriptor</A>
<LI><A HREF="library.html#IDX444">standard input stream</A>
<LI><A HREF="library.html#IDX661">standard output file descriptor</A>
<LI><A HREF="library.html#IDX446">standard output stream</A>
<LI><A HREF="library.html#IDX440">standard streams</A>
<LI><A HREF="library.html#IDX2">standards</A>
<LI><A HREF="library.html#IDX1213">START character</A>
<LI><A HREF="library.html#IDX133">static allocation</A>
<LI><A HREF="library.html#IDX1219">STATUS character</A>
<LI><A HREF="library.html#IDX44">status codes</A>
<LI><A HREF="library.html#IDX780">status of a file</A>
<LI><A HREF="library.html#IDX197">status of obstack</A>
<LI><A HREF="library.html#IDX836">sticky bit</A>
<LI><A HREF="library.html#IDX1215">STOP character</A>
<LI><A HREF="library.html#IDX1516">stop signal</A>
<LI><A HREF="library.html#IDX1739">stopped job</A>
<LI><A HREF="library.html#IDX1758">stopped jobs, continuing</A>
<LI><A HREF="library.html#IDX1755">stopped jobs, detecting</A>
<LI><A HREF="library.html#IDX131">storage allocation</A>
<LI><A HREF="library.html#IDX895">stream (sockets)</A>
<LI><A HREF="library.html#IDX601">stream, for I/O to a string</A>
<LI><A HREF="library.html#IDX665">streams and descriptors</A>
<LI><A HREF="library.html#IDX649">streams, and file descriptors</A>
<LI><A HREF="library.html#IDX441">streams, standard</A>
<LI><A HREF="library.html#IDX268">string</A>
<LI><A HREF="library.html#IDX275">string allocation</A>
<LI><A HREF="library.html#IDX309">string collation functions</A>
<LI><A HREF="library.html#IDX297">string comparison functions</A>
<LI><A HREF="library.html#IDX283">string concatenation functions</A>
<LI><A HREF="library.html#IDX280">string copy functions</A>
<LI><A HREF="library.html#IDX274">string length</A>
<LI><A HREF="library.html#IDX270">string literal</A>
<LI><A HREF="library.html#IDX316">string search functions</A>
<LI><A HREF="library.html#IDX602">string stream</A>
<LI><A HREF="library.html#IDX267">string, representation of</A>
<LI><A HREF="library.html#IDX892">style of communication (of a socket)</A>
<LI><A HREF="library.html#IDX1747">subshell</A>
<LI><A HREF="library.html#IDX410">substitution of variables and commands</A>
<LI><A HREF="library.html#IDX1563">successive signals</A>
<LI><A HREF="library.html#IDX1381">summer time</A>
<LI><A HREF="library.html#IDX13">SunOS</A>
<LI><A HREF="library.html#IDX1789">supplementary group IDs</A>
<LI><A HREF="library.html#IDX1207">SUSP character</A>
<LI><A HREF="library.html#IDX1208">suspend character</A>
<LI><A HREF="library.html#IDX15">SVID</A>
<LI><A HREF="library.html#IDX756">symbolic link</A>
<LI><A HREF="library.html#IDX1629">syntax, for program arguments</A>
<LI><A HREF="library.html#IDX1336">syntax, for reading numbers</A>
<LI><A HREF="library.html#IDX16">System V Unix</A>
<H2>t</H2>
<LI><A HREF="library.html#IDX993">TCP (Internet protocol)</A>
<LI><A HREF="library.html#IDX479">template, for <CODE>printf</CODE></A>
<LI><A HREF="library.html#IDX529">template, for <CODE>scanf</CODE></A>
<LI><A HREF="library.html#IDX1656">TERM environment variable</A>
<LI><A HREF="library.html#IDX1237">terminal flow control</A>
<LI><A HREF="library.html#IDX1080">terminal identification</A>
<LI><A HREF="library.html#IDX1085">terminal input queue</A>
<LI><A HREF="library.html#IDX1231">terminal input queue, clearing</A>
<LI><A HREF="library.html#IDX1520">terminal input signal</A>
<LI><A HREF="library.html#IDX1224">terminal line control functions</A>
<LI><A HREF="library.html#IDX1158">terminal line speed</A>
<LI><A HREF="library.html#IDX1091">terminal mode data types</A>
<LI><A HREF="library.html#IDX1096">terminal mode functions</A>
<LI><A HREF="library.html#IDX1087">terminal output queue</A>
<LI><A HREF="library.html#IDX1228">terminal output queue, flushing</A>
<LI><A HREF="library.html#IDX1522">terminal output signal</A>
<LI><A HREF="library.html#IDX1756">terminated jobs, detecting</A>
<LI><A HREF="library.html#IDX1495">termination signal</A>
<LI><A HREF="library.html#IDX850">testing access permission</A>
<LI><A HREF="library.html#IDX1713">testing exit status of child process</A>
<LI><A HREF="library.html#IDX556">text stream</A>
<LI><A HREF="library.html#IDX1348">ticks, clock</A>
<LI><A HREF="library.html#IDX408">tilde expansion</A>
<LI><A HREF="library.html#IDX1223">TIME termios slot</A>
<LI><A HREF="library.html#IDX1390">time zone</A>
<LI><A HREF="library.html#IDX1359">time, calendar</A>
<LI><A HREF="library.html#IDX1349">time, elapsed CPU</A>
<LI><A HREF="library.html#IDX1398">timers, setting</A>
<LI><A HREF="library.html#IDX1603">timing error in signal handling</A>
<LI><A HREF="library.html#IDX599">TMPDIR environment variable</A>
<LI><A HREF="library.html#IDX325">tokenizing strings</A>
<LI><A HREF="library.html#IDX1054">transmitting datagrams</A>
<LI><A HREF="library.html#IDX1250">trigonometric functions</A>
<LI><A HREF="library.html#IDX1962">type measurements, floating</A>
<LI><A HREF="library.html#IDX1955">type measurements, integer</A>
<LI><A HREF="library.html#IDX486">type modifier character (<CODE>printf</CODE>)</A>
<LI><A HREF="library.html#IDX534">type modifier character (<CODE>scanf</CODE>)</A>
<LI><A HREF="library.html#IDX1086">typeahead buffer</A>
<LI><A HREF="library.html#IDX1657">TZ environment variable</A>
<H2>u</H2>
<LI><A HREF="library.html#IDX842">umask</A>
<LI><A HREF="library.html#IDX577">unbuffered stream</A>
<LI><A HREF="library.html#IDX135">unconstrained storage allocation</A>
<LI><A HREF="library.html#IDX23">undefining macros that shadow functions</A>
<LI><A HREF="library.html#IDX14">Unix, Berkeley</A>
<LI><A HREF="library.html#IDX17">Unix, System V</A>
<LI><A HREF="library.html#IDX763">unlinking a file</A>
<LI><A HREF="library.html#IDX475">unreading characters</A>
<LI><A HREF="library.html#IDX233">upper-case character</A>
<LI><A HREF="library.html#IDX1509">urgent data signal</A>
<LI><A HREF="library.html#IDX1051">urgent socket condition</A>
<LI><A HREF="library.html#IDX1417">usage limits</A>
<LI><A HREF="library.html#IDX1818">user database</A>
<LI><A HREF="library.html#IDX1781">user ID</A>
<LI><A HREF="library.html#IDX1812">user ID, determining</A>
<LI><A HREF="library.html#IDX1780">user name</A>
<LI><A HREF="library.html#IDX1528">user signals</A>
<LI><A HREF="library.html#IDX436">usual file name syntax errors</A>
<H2>v</H2>
<LI><A HREF="library.html#IDX1922">variable number of arguments</A>
<LI><A HREF="library.html#IDX409">variable substitution</A>
<LI><A HREF="library.html#IDX214">variable-sized arrays</A>
<LI><A HREF="library.html#IDX1928">variadic function argument access</A>
<LI><A HREF="library.html#IDX1927">variadic function prototypes</A>
<LI><A HREF="library.html#IDX1923">variadic functions</A>
<LI><A HREF="library.html#IDX1934">variadic functions, calling</A>
<LI><A HREF="library.html#IDX1502">virtual time alarm signal</A>
<LI><A HREF="library.html#IDX1400">virtual timer</A>
<LI><A HREF="library.html#IDX1566"><CODE>volatile</CODE> declarations</A>
<H2>w</H2>
<LI><A HREF="library.html#IDX1604">waiting for a signal</A>
<LI><A HREF="library.html#IDX1712">waiting for completion of child process</A>
<LI><A HREF="library.html#IDX672">waiting for input or output</A>
<LI><A HREF="library.html#IDX222">warnings of memory almost full</A>
<LI><A HREF="library.html#IDX1196">WERASE character</A>
<LI><A HREF="library.html#IDX246">whitespace character</A>
<LI><A HREF="library.html#IDX331">wide characters</A>
<LI><A HREF="library.html#IDX1954">width of integer type</A>
<LI><A HREF="library.html#IDX414">wildcard expansion</A>
<LI><A HREF="library.html#IDX406">word expansion</A>
<LI><A HREF="library.html#IDX725">working directory</A>
<LI><A HREF="library.html#IDX709">write lock</A>
<LI><A HREF="library.html#IDX642">writing to a file descriptor</A>
<LI><A HREF="library.html#IDX1040">writing to a socket</A>
<LI><A HREF="library.html#IDX546">writing to a stream, by blocks</A>
<LI><A HREF="library.html#IDX456">writing to a stream, by characters</A>
<LI><A HREF="library.html#IDX481">writing to a stream, formatted</A>
</DIR>
<P>
<H1><A NAME="SEC506" HREF="library_toc.html#SEC506">Type Index</A></H1>
<P>
<DIR>
<H2>c</H2>
<LI><A HREF="library.html#IDX1094">cc_t</A>
<LI><A HREF="library.html#IDX1353">clock_t</A>
<LI><A HREF="library.html#IDX381">comparison_fn_t</A>
<LI><A HREF="library.html#IDX617">cookie_close_function</A>
<LI><A HREF="library.html#IDX614">cookie_read_function</A>
<LI><A HREF="library.html#IDX616">cookie_seek_function</A>
<LI><A HREF="library.html#IDX615">cookie_write_function</A>
<H2>d</H2>
<LI><A HREF="library.html#IDX788">dev_t</A>
<LI><A HREF="library.html#IDX739">DIR</A>
<LI><A HREF="library.html#IDX1329">div_t</A>
<H2>f</H2>
<LI><A HREF="library.html#IDX677">fd_set</A>
<LI><A HREF="library.html#IDX439">FILE</A>
<LI><A HREF="library.html#IDX713">flock</A>
<LI><A HREF="library.html#IDX573">fpos_t</A>
<H2>g</H2>
<LI><A HREF="library.html#IDX1794">gid_t</A>
<LI><A HREF="library.html#IDX397">glob_t</A>
<H2>i</H2>
<LI><A HREF="library.html#IDX787">ino_t</A>
<H2>j</H2>
<LI><A HREF="library.html#IDX1445">jmp_buf</A>
<H2>l</H2>
<LI><A HREF="library.html#IDX1331">ldiv_t</A>
<H2>m</H2>
<LI><A HREF="library.html#IDX785">mode_t</A>
<H2>n</H2>
<LI><A HREF="library.html#IDX789">nlink_t</A>
<H2>o</H2>
<LI><A HREF="library.html#IDX648">off_t</A>
<H2>p</H2>
<LI><A HREF="library.html#IDX1696">pid_t</A>
<LI><A HREF="library.html#IDX525">printf_arginfo_function</A>
<LI><A HREF="library.html#IDX524">printf_function</A>
<LI><A HREF="library.html#IDX1951">ptrdiff_t</A>
<H2>r</H2>
<LI><A HREF="library.html#IDX399">regex_t</A>
<LI><A HREF="library.html#IDX402">regmatch_t</A>
<LI><A HREF="library.html#IDX403">regoff_t</A>
<H2>s</H2>
<LI><A HREF="library.html#IDX1568">sig_atomic_t</A>
<LI><A HREF="library.html#IDX1539">sighandler_t</A>
<LI><A HREF="library.html#IDX1449">sigjmp_buf</A>
<LI><A HREF="library.html#IDX1584">sigset_t</A>
<LI><A HREF="library.html#IDX1952">size_t</A>
<LI><A HREF="library.html#IDX1164">speed_t</A>
<LI><A HREF="library.html#IDX638">ssize_t</A>
<LI><A HREF="library.html#IDX611">struct cookie_io_functions</A>
<LI><A HREF="library.html#IDX737">struct dirent</A>
<LI><A HREF="library.html#IDX1836">struct group</A>
<LI><A HREF="library.html#IDX956">struct hostent</A>
<LI><A HREF="library.html#IDX942">struct in_addr</A>
<LI><A HREF="library.html#IDX1404">struct itimerval</A>
<LI><A HREF="library.html#IDX376">struct lconv</A>
<LI><A HREF="library.html#IDX1068">struct linger</A>
<LI><A HREF="library.html#IDX168">struct mstats</A>
<LI><A HREF="library.html#IDX1074">struct netent</A>
<LI><A HREF="library.html#IDX172">struct obstack</A>
<LI><A HREF="library.html#IDX1641">struct option</A>
<LI><A HREF="library.html#IDX1822">struct passwd</A>
<LI><A HREF="library.html#IDX523">struct printf_info</A>
<LI><A HREF="library.html#IDX996">struct protoent</A>
<LI><A HREF="library.html#IDX1421">struct rlimit</A>
<LI><A HREF="library.html#IDX1414">struct rusage</A>
<LI><A HREF="library.html#IDX976">struct servent</A>
<LI><A HREF="library.html#IDX1549">struct sigaction</A>
<LI><A HREF="library.html#IDX1620">struct sigstack</A>
<LI><A HREF="library.html#IDX1610">struct sigvec</A>
<LI><A HREF="library.html#IDX915">struct sockaddr</A>
<LI><A HREF="library.html#IDX934">struct sockaddr_in</A>
<LI><A HREF="library.html#IDX929">struct sockaddr_un</A>
<LI><A HREF="library.html#IDX784">struct stat</A>
<LI><A HREF="library.html#IDX1092">struct termios</A>
<LI><A HREF="library.html#IDX1371">struct timeval</A>
<LI><A HREF="library.html#IDX1372">struct timezone</A>
<LI><A HREF="library.html#IDX1378">struct tm</A>
<LI><A HREF="library.html#IDX1356">struct tms</A>
<LI><A HREF="library.html#IDX865">struct utimbuf</A>
<LI><A HREF="library.html#IDX1855">struct utsname</A>
<H2>t</H2>
<LI><A HREF="library.html#IDX1093">tcflag_t</A>
<LI><A HREF="library.html#IDX1367">time_t</A>
<H2>u</H2>
<LI><A HREF="library.html#IDX1793">uid_t</A>
<LI><A HREF="library.html#IDX1726">union wait</A>
<H2>v</H2>
<LI><A HREF="library.html#IDX1940">va_list</A>
<H2>w</H2>
<LI><A HREF="library.html#IDX338">wchar_t</A>
<LI><A HREF="library.html#IDX417">wordexp_t</A>
</DIR>
<P>
<H1><A NAME="SEC507" HREF="library_toc.html#SEC507">Function and Macro Index</A></H1>
<P>
<DIR>
<H2>-</H2>
<LI><A HREF="library.html#IDX1768">-lbsd-compat</A>
<H2>_</H2>
<LI><A HREF="library.html#IDX1679">_exit</A>
<LI><A HREF="library.html#IDX265">_tolower</A>
<LI><A HREF="library.html#IDX266">_toupper</A>
<H2>a</H2>
<LI><A HREF="library.html#IDX1677">abort</A>
<LI><A HREF="library.html#IDX1306">abs</A>
<LI><A HREF="library.html#IDX1037">accept</A>
<LI><A HREF="library.html#IDX854">access</A>
<LI><A HREF="library.html#IDX1257">acos</A>
<LI><A HREF="library.html#IDX1280">acosh</A>
<LI><A HREF="library.html#IDX1375">adjtime</A>
<LI><A HREF="library.html#IDX1410">alarm</A>
<LI><A HREF="library.html#IDX210">alloca</A>
<LI><A HREF="library.html#IDX1386">asctime</A>
<LI><A HREF="library.html#IDX1256">asin</A>
<LI><A HREF="library.html#IDX1279">asinh</A>
<LI><A HREF="library.html#IDX493">asprintf</A>
<LI><A HREF="library.html#IDX1921">assert</A>
<LI><A HREF="library.html#IDX1258">atan</A>
<LI><A HREF="library.html#IDX1259">atan2</A>
<LI><A HREF="library.html#IDX1281">atanh</A>
<LI><A HREF="library.html#IDX1673">atexit</A>
<LI><A HREF="library.html#IDX1344">atof</A>
<LI><A HREF="library.html#IDX1341">atoi</A>
<LI><A HREF="library.html#IDX1340">atol</A>
<H2>b</H2>
<LI><A HREF="library.html#IDX307">bcmp</A>
<LI><A HREF="library.html#IDX294">bcopy</A>
<LI><A HREF="library.html#IDX921">bind</A>
<LI><A HREF="library.html#IDX1769">bsd-compat</A>
<LI><A HREF="library.html#IDX386">bsearch</A>
<LI><A HREF="library.html#IDX295">bzero</A>
<H2>c</H2>
<LI><A HREF="library.html#IDX1309">cabs</A>
<LI><A HREF="library.html#IDX150">calloc</A>
<LI><A HREF="library.html#IDX1270">cbrt</A>
<LI><A HREF="library.html#IDX1321">ceil</A>
<LI><A HREF="library.html#IDX1160">cfgetispeed</A>
<LI><A HREF="library.html#IDX1159">cfgetospeed</A>
<LI><A HREF="library.html#IDX1183">cfmakeraw</A>
<LI><A HREF="library.html#IDX145">cfree</A>
<LI><A HREF="library.html#IDX1162">cfsetispeed</A>
<LI><A HREF="library.html#IDX1161">cfsetospeed</A>
<LI><A HREF="library.html#IDX1163">cfsetspeed</A>
<LI><A HREF="library.html#IDX731">chdir</A>
<LI><A HREF="library.html#IDX848">chmod</A>
<LI><A HREF="library.html#IDX815">chown</A>
<LI><A HREF="library.html#IDX553">clearerr</A>
<LI><A HREF="library.html#IDX1354">clock</A>
<LI><A HREF="library.html#IDX636">close</A>
<LI><A HREF="library.html#IDX743">closedir</A>
<LI><A HREF="library.html#IDX1915">confstr</A>
<LI><A HREF="library.html#IDX1030">connect</A>
<LI><A HREF="library.html#IDX1316">copysign</A>
<LI><A HREF="library.html#IDX1253">cos</A>
<LI><A HREF="library.html#IDX1276">cosh</A>
<LI><A HREF="library.html#IDX635">creat</A>
<LI><A HREF="library.html#IDX1763">ctermid</A>
<LI><A HREF="library.html#IDX1387">ctime</A>
<LI><A HREF="library.html#IDX1816">cuserid</A>
<H2>d</H2>
<LI><A HREF="library.html#IDX1368">difftime</A>
<LI><A HREF="library.html#IDX1330">div</A>
<LI><A HREF="library.html#IDX1326">drem</A>
<LI><A HREF="library.html#IDX692">dup</A>
<LI><A HREF="library.html#IDX693">dup2</A>
<H2>e</H2>
<LI><A HREF="library.html#IDX1845">endgrent</A>
<LI><A HREF="library.html#IDX966">endhostent</A>
<LI><A HREF="library.html#IDX1079">endnetent</A>
<LI><A HREF="library.html#IDX1001">endprotoent</A>
<LI><A HREF="library.html#IDX1831">endpwent</A>
<LI><A HREF="library.html#IDX981">endservent</A>
<LI><A HREF="library.html#IDX1706">execl</A>
<LI><A HREF="library.html#IDX1708">execle</A>
<LI><A HREF="library.html#IDX1710">execlp</A>
<LI><A HREF="library.html#IDX1705">execv</A>
<LI><A HREF="library.html#IDX1707">execve</A>
<LI><A HREF="library.html#IDX1709">execvp</A>
<LI><A HREF="library.html#IDX1668">exit</A>
<LI><A HREF="library.html#IDX1263">exp</A>
<LI><A HREF="library.html#IDX1272">expm1</A>
<H2>f</H2>
<LI><A HREF="library.html#IDX1308">fabs</A>
<LI><A HREF="library.html#IDX849">fchmod</A>
<LI><A HREF="library.html#IDX816">fchown</A>
<LI><A HREF="library.html#IDX671">fclean</A>
<LI><A HREF="library.html#IDX455">fclose</A>
<LI><A HREF="library.html#IDX687">fcntl</A>
<LI><A HREF="library.html#IDX681">FD_CLR</A>
<LI><A HREF="library.html#IDX682">FD_ISSET</A>
<LI><A HREF="library.html#IDX680">FD_SET</A>
<LI><A HREF="library.html#IDX679">FD_ZERO</A>
<LI><A HREF="library.html#IDX653">fdopen</A>
<LI><A HREF="library.html#IDX554">feof</A>
<LI><A HREF="library.html#IDX555">ferror</A>
<LI><A HREF="library.html#IDX582">fflush</A>
<LI><A HREF="library.html#IDX466">fgetc</A>
<LI><A HREF="library.html#IDX1842">fgetgrent</A>
<LI><A HREF="library.html#IDX574">fgetpos</A>
<LI><A HREF="library.html#IDX1828">fgetpwent</A>
<LI><A HREF="library.html#IDX472">fgets</A>
<LI><A HREF="library.html#IDX654">fileno</A>
<LI><A HREF="library.html#IDX1301">finite</A>
<LI><A HREF="library.html#IDX1322">floor</A>
<LI><A HREF="library.html#IDX604">fmemopen</A>
<LI><A HREF="library.html#IDX1325">fmod</A>
<LI><A HREF="library.html#IDX395">fnmatch</A>
<LI><A HREF="library.html#IDX451">fopen</A>
<LI><A HREF="library.html#IDX612">fopencookie</A>
<LI><A HREF="library.html#IDX1700">fork</A>
<LI><A HREF="library.html#IDX1906">fpathconf</A>
<LI><A HREF="library.html#IDX490">fprintf</A>
<LI><A HREF="library.html#IDX458">fputc</A>
<LI><A HREF="library.html#IDX461">fputs</A>
<LI><A HREF="library.html#IDX548">fread</A>
<LI><A HREF="library.html#IDX144">free</A>
<LI><A HREF="library.html#IDX453">freopen</A>
<LI><A HREF="library.html#IDX1312">frexp</A>
<LI><A HREF="library.html#IDX538">fscanf</A>
<LI><A HREF="library.html#IDX564">fseek</A>
<LI><A HREF="library.html#IDX575">fsetpos</A>
<LI><A HREF="library.html#IDX791">fstat</A>
<LI><A HREF="library.html#IDX563">ftell</A>
<LI><A HREF="library.html#IDX549">fwrite</A>
<H2>g</H2>
<LI><A HREF="library.html#IDX467">getc</A>
<LI><A HREF="library.html#IDX468">getchar</A>
<LI><A HREF="library.html#IDX729">getcwd</A>
<LI><A HREF="library.html#IDX471">getdelim</A>
<LI><A HREF="library.html#IDX1798">getegid</A>
<LI><A HREF="library.html#IDX1648">getenv</A>
<LI><A HREF="library.html#IDX1797">geteuid</A>
<LI><A HREF="library.html#IDX1796">getgid</A>
<LI><A HREF="library.html#IDX1844">getgrent</A>
<LI><A HREF="library.html#IDX1839">getgrgid</A>
<LI><A HREF="library.html#IDX1840">getgrnam</A>
<LI><A HREF="library.html#IDX1799">getgroups</A>
<LI><A HREF="library.html#IDX958">gethostbyaddr</A>
<LI><A HREF="library.html#IDX957">gethostbyname</A>
<LI><A HREF="library.html#IDX965">gethostent</A>
<LI><A HREF="library.html#IDX1852">gethostid</A>
<LI><A HREF="library.html#IDX1849">gethostname</A>
<LI><A HREF="library.html#IDX1406">getitimer</A>
<LI><A HREF="library.html#IDX470">getline</A>
<LI><A HREF="library.html#IDX1815">getlogin</A>
<LI><A HREF="library.html#IDX1076">getnetbyaddr</A>
<LI><A HREF="library.html#IDX1075">getnetbyname</A>
<LI><A HREF="library.html#IDX1078">getnetent</A>
<LI><A HREF="library.html#IDX1640">getopt</A>
<LI><A HREF="library.html#IDX1642">getopt_long</A>
<LI><A HREF="library.html#IDX1038">getpeername</A>
<LI><A HREF="library.html#IDX1772">getpgrp</A>
<LI><A HREF="library.html#IDX1697">getpid</A>
<LI><A HREF="library.html#IDX1698">getppid</A>
<LI><A HREF="library.html#IDX1436">getpriority</A>
<LI><A HREF="library.html#IDX997">getprotobyname</A>
<LI><A HREF="library.html#IDX998">getprotobynumber</A>
<LI><A HREF="library.html#IDX1000">getprotoent</A>
<LI><A HREF="library.html#IDX1830">getpwent</A>
<LI><A HREF="library.html#IDX1826">getpwnam</A>
<LI><A HREF="library.html#IDX1825">getpwuid</A>
<LI><A HREF="library.html#IDX1419">getrlimit</A>
<LI><A HREF="library.html#IDX1413">getrusage</A>
<LI><A HREF="library.html#IDX473">gets</A>
<LI><A HREF="library.html#IDX977">getservbyname</A>
<LI><A HREF="library.html#IDX978">getservbyport</A>
<LI><A HREF="library.html#IDX980">getservent</A>
<LI><A HREF="library.html#IDX923">getsockname</A>
<LI><A HREF="library.html#IDX1064">getsockopt</A>
<LI><A HREF="library.html#IDX1373">gettimeofday</A>
<LI><A HREF="library.html#IDX1795">getuid</A>
<LI><A HREF="library.html#IDX847">getumask</A>
<LI><A HREF="library.html#IDX469">getw</A>
<LI><A HREF="library.html#IDX730">getwd</A>
<LI><A HREF="library.html#IDX398">glob</A>
<LI><A HREF="library.html#IDX1383">gmtime</A>
<LI><A HREF="library.html#IDX1575">gsignal</A>
<H2>h</H2>
<LI><A HREF="library.html#IDX990">htonl</A>
<LI><A HREF="library.html#IDX988">htons</A>
<LI><A HREF="library.html#IDX1271">hypot</A>
<H2>i</H2>
<LI><A HREF="library.html#IDX945">inet_addr</A>
<LI><A HREF="library.html#IDX949">inet_lnaof</A>
<LI><A HREF="library.html#IDX948">inet_makeaddr</A>
<LI><A HREF="library.html#IDX950">inet_netof</A>
<LI><A HREF="library.html#IDX946">inet_network</A>
<LI><A HREF="library.html#IDX947">inet_ntoa</A>
<LI><A HREF="library.html#IDX1302">infnan</A>
<LI><A HREF="library.html#IDX1810">initgroups</A>
<LI><A HREF="library.html#IDX1292">initstate</A>
<LI><A HREF="library.html#IDX241">isalnum</A>
<LI><A HREF="library.html#IDX236">isalpha</A>
<LI><A HREF="library.html#IDX257">isascii</A>
<LI><A HREF="library.html#IDX1083">isatty</A>
<LI><A HREF="library.html#IDX249">isblank</A>
<LI><A HREF="library.html#IDX255">iscntrl</A>
<LI><A HREF="library.html#IDX239">isdigit</A>
<LI><A HREF="library.html#IDX251">isgraph</A>
<LI><A HREF="library.html#IDX1299">isinf</A>
<LI><A HREF="library.html#IDX232">islower</A>
<LI><A HREF="library.html#IDX1300">isnan</A>
<LI><A HREF="library.html#IDX253">isprint</A>
<LI><A HREF="library.html#IDX245">ispunct</A>
<LI><A HREF="library.html#IDX247">isspace</A>
<LI><A HREF="library.html#IDX234">isupper</A>
<LI><A HREF="library.html#IDX243">isxdigit</A>
<LI><A HREF="library.html#IDX1409">ITIMER_PROF</A>
<LI><A HREF="library.html#IDX1407">ITIMER_REAL</A>
<LI><A HREF="library.html#IDX1408">ITIMER_VIRTUAL</A>
<H2>k</H2>
<LI><A HREF="library.html#IDX1578">kill</A>
<LI><A HREF="library.html#IDX1579">killpg</A>
<H2>l</H2>
<LI><A HREF="library.html#IDX1307">labs</A>
<LI><A HREF="library.html#IDX1313">ldexp</A>
<LI><A HREF="library.html#IDX1332">ldiv</A>
<LI><A HREF="library.html#IDX753">link</A>
<LI><A HREF="library.html#IDX1034">listen</A>
<LI><A HREF="library.html#IDX375">localeconv</A>
<LI><A HREF="library.html#IDX1382">localtime</A>
<LI><A HREF="library.html#IDX1264">log</A>
<LI><A HREF="library.html#IDX1265">log10</A>
<LI><A HREF="library.html#IDX1273">log1p</A>
<LI><A HREF="library.html#IDX1315">logb</A>
<LI><A HREF="library.html#IDX1447">longjmp</A>
<LI><A HREF="library.html#IDX647">lseek</A>
<LI><A HREF="library.html#IDX792">lstat</A>
<H2>m</H2>
<LI><A HREF="library.html#IDX140">malloc</A>
<LI><A HREF="library.html#IDX349">mblen</A>
<LI><A HREF="library.html#IDX345">mbstowcs</A>
<LI><A HREF="library.html#IDX354">mbtowc</A>
<LI><A HREF="library.html#IDX160">mcheck</A>
<LI><A HREF="library.html#IDX155">memalign</A>
<LI><A HREF="library.html#IDX286">memccpy</A>
<LI><A HREF="library.html#IDX317">memchr</A>
<LI><A HREF="library.html#IDX302">memcmp</A>
<LI><A HREF="library.html#IDX284">memcpy</A>
<LI><A HREF="library.html#IDX321">memmem</A>
<LI><A HREF="library.html#IDX285">memmove</A>
<LI><A HREF="library.html#IDX224">memory_warnings</A>
<LI><A HREF="library.html#IDX287">memset</A>
<LI><A HREF="library.html#IDX777">mkdir</A>
<LI><A HREF="library.html#IDX888">mkfifo</A>
<LI><A HREF="library.html#IDX872">mknod</A>
<LI><A HREF="library.html#IDX1384">mktime</A>
<LI><A HREF="library.html#IDX1324">modf</A>
<LI><A HREF="library.html#IDX169">mstats</A>
<H2>n</H2>
<LI><A HREF="library.html#IDX1441">nice</A>
<LI><A HREF="library.html#IDX991">ntohl</A>
<LI><A HREF="library.html#IDX989">ntohs</A>
<H2>o</H2>
<LI><A HREF="library.html#IDX188">obstack_1grow</A>
<LI><A HREF="library.html#IDX194">obstack_1grow_fast</A>
<LI><A HREF="library.html#IDX202">obstack_alignment_mask</A>
<LI><A HREF="library.html#IDX177">obstack_alloc</A>
<LI><A HREF="library.html#IDX198">obstack_base</A>
<LI><A HREF="library.html#IDX185">obstack_blank</A>
<LI><A HREF="library.html#IDX195">obstack_blank_fast</A>
<LI><A HREF="library.html#IDX173">obstack_chunk_alloc</A>
<LI><A HREF="library.html#IDX174">obstack_chunk_free</A>
<LI><A HREF="library.html#IDX205">obstack_chunk_size</A>
<LI><A HREF="library.html#IDX178">obstack_copy</A>
<LI><A HREF="library.html#IDX179">obstack_copy0</A>
<LI><A HREF="library.html#IDX189">obstack_finish</A>
<LI><A HREF="library.html#IDX181">obstack_free</A>
<LI><A HREF="library.html#IDX186">obstack_grow</A>
<LI><A HREF="library.html#IDX187">obstack_grow0</A>
<LI><A HREF="library.html#IDX175">obstack_init</A>
<LI><A HREF="library.html#IDX199">obstack_next_free</A>
<LI><A HREF="library.html#IDX200">obstack_object_size</A>
<LI><A HREF="library.html#IDX494">obstack_printf</A>
<LI><A HREF="library.html#IDX193">obstack_room</A>
<LI><A HREF="library.html#IDX501">obstack_vprintf</A>
<LI><A HREF="library.html#IDX1977">offsetof</A>
<LI><A HREF="library.html#IDX1674">on_exit</A>
<LI><A HREF="library.html#IDX622">open</A>
<LI><A HREF="library.html#IDX605">open_memstream</A>
<LI><A HREF="library.html#IDX606">open_obstack_stream</A>
<LI><A HREF="library.html#IDX740">opendir</A>
<H2>p</H2>
<LI><A HREF="library.html#IDX503">parse_printf_format</A>
<LI><A HREF="library.html#IDX1905">pathconf</A>
<LI><A HREF="library.html#IDX1606">pause</A>
<LI><A HREF="library.html#IDX884">pclose</A>
<LI><A HREF="library.html#IDX125">perror</A>
<LI><A HREF="library.html#IDX879">pipe</A>
<LI><A HREF="library.html#IDX883">popen</A>
<LI><A HREF="library.html#IDX1266">pow</A>
<LI><A HREF="library.html#IDX489">printf</A>
<LI><A HREF="library.html#IDX1532">psignal</A>
<LI><A HREF="library.html#IDX459">putc</A>
<LI><A HREF="library.html#IDX460">putchar</A>
<LI><A HREF="library.html#IDX1649">putenv</A>
<LI><A HREF="library.html#IDX1832">putpwent</A>
<LI><A HREF="library.html#IDX462">puts</A>
<LI><A HREF="library.html#IDX463">putw</A>
<H2>q</H2>
<LI><A HREF="library.html#IDX391">qsort</A>
<H2>r</H2>
<LI><A HREF="library.html#IDX218">r_alloc</A>
<LI><A HREF="library.html#IDX219">r_alloc_free</A>
<LI><A HREF="library.html#IDX220">r_re_alloc</A>
<LI><A HREF="library.html#IDX1574">raise</A>
<LI><A HREF="library.html#IDX1287">rand</A>
<LI><A HREF="library.html#IDX1290">random</A>
<LI><A HREF="library.html#IDX640">read</A>
<LI><A HREF="library.html#IDX742">readdir</A>
<LI><A HREF="library.html#IDX760">readlink</A>
<LI><A HREF="library.html#IDX148">realloc</A>
<LI><A HREF="library.html#IDX1044">recv</A>
<LI><A HREF="library.html#IDX1059">recvfrom</A>
<LI><A HREF="library.html#IDX400">regcomp</A>
<LI><A HREF="library.html#IDX405">regerror</A>
<LI><A HREF="library.html#IDX401">regexec</A>
<LI><A HREF="library.html#IDX404">regfree</A>
<LI><A HREF="library.html#IDX521">register_printf_function</A>
<LI><A HREF="library.html#IDX766">remove</A>
<LI><A HREF="library.html#IDX773">rename</A>
<LI><A HREF="library.html#IDX568">rewind</A>
<LI><A HREF="library.html#IDX745">rewinddir</A>
<LI><A HREF="library.html#IDX1323">rint</A>
<LI><A HREF="library.html#IDX768">rmdir</A>
<H2>s</H2>
<LI><A HREF="library.html#IDX796">S_ISBLK</A>
<LI><A HREF="library.html#IDX795">S_ISCHR</A>
<LI><A HREF="library.html#IDX794">S_ISDIR</A>
<LI><A HREF="library.html#IDX798">S_ISFIFO</A>
<LI><A HREF="library.html#IDX799">S_ISLNK</A>
<LI><A HREF="library.html#IDX797">S_ISREG</A>
<LI><A HREF="library.html#IDX800">S_ISSOCK</A>
<LI><A HREF="library.html#IDX1314">scalb</A>
<LI><A HREF="library.html#IDX537">scanf</A>
<LI><A HREF="library.html#IDX747">seekdir</A>
<LI><A HREF="library.html#IDX683">select</A>
<LI><A HREF="library.html#IDX1042">send</A>
<LI><A HREF="library.html#IDX1057">sendto</A>
<LI><A HREF="library.html#IDX590">setbuf</A>
<LI><A HREF="library.html#IDX591">setbuffer</A>
<LI><A HREF="library.html#IDX1806">setgid</A>
<LI><A HREF="library.html#IDX1843">setgrent</A>
<LI><A HREF="library.html#IDX1809">setgroups</A>
<LI><A HREF="library.html#IDX964">sethostent</A>
<LI><A HREF="library.html#IDX1853">sethostid</A>
<LI><A HREF="library.html#IDX1851">sethostname</A>
<LI><A HREF="library.html#IDX1405">setitimer</A>
<LI><A HREF="library.html#IDX1446">setjmp</A>
<LI><A HREF="library.html#IDX592">setlinebuf</A>
<LI><A HREF="library.html#IDX371">setlocale</A>
<LI><A HREF="library.html#IDX1077">setnetent</A>
<LI><A HREF="library.html#IDX1773">setpgid</A>
<LI><A HREF="library.html#IDX1774">setpgrp</A>
<LI><A HREF="library.html#IDX1437">setpriority</A>
<LI><A HREF="library.html#IDX999">setprotoent</A>
<LI><A HREF="library.html#IDX1829">setpwent</A>
<LI><A HREF="library.html#IDX1807">setregid</A>
<LI><A HREF="library.html#IDX1803">setreuid</A>
<LI><A HREF="library.html#IDX1420">setrlimit</A>
<LI><A HREF="library.html#IDX979">setservent</A>
<LI><A HREF="library.html#IDX1767">setsid</A>
<LI><A HREF="library.html#IDX1065">setsockopt</A>
<LI><A HREF="library.html#IDX1293">setstate</A>
<LI><A HREF="library.html#IDX1374">settimeofday</A>
<LI><A HREF="library.html#IDX1802">setuid</A>
<LI><A HREF="library.html#IDX585">setvbuf</A>
<LI><A HREF="library.html#IDX1017">shutdown</A>
<LI><A HREF="library.html#IDX1550">sigaction</A>
<LI><A HREF="library.html#IDX1587">sigaddset</A>
<LI><A HREF="library.html#IDX1617">sigblock</A>
<LI><A HREF="library.html#IDX1588">sigdelset</A>
<LI><A HREF="library.html#IDX1585">sigemptyset</A>
<LI><A HREF="library.html#IDX1586">sigfillset</A>
<LI><A HREF="library.html#IDX1615">siginterrupt</A>
<LI><A HREF="library.html#IDX1589">sigismember</A>
<LI><A HREF="library.html#IDX1451">siglongjmp</A>
<LI><A HREF="library.html#IDX1616">sigmask</A>
<LI><A HREF="library.html#IDX1540">signal</A>
<LI><A HREF="library.html#IDX1619">sigpause</A>
<LI><A HREF="library.html#IDX1602">sigpending</A>
<LI><A HREF="library.html#IDX1593">sigprocmask</A>
<LI><A HREF="library.html#IDX1450">sigsetjmp</A>
<LI><A HREF="library.html#IDX1618">sigsetmask</A>
<LI><A HREF="library.html#IDX1621">sigstack</A>
<LI><A HREF="library.html#IDX1607">sigsuspend</A>
<LI><A HREF="library.html#IDX1614">sigvec</A>
<LI><A HREF="library.html#IDX1252">sin</A>
<LI><A HREF="library.html#IDX1275">sinh</A>
<LI><A HREF="library.html#IDX1411">sleep</A>
<LI><A HREF="library.html#IDX492">snprintf</A>
<LI><A HREF="library.html#IDX1011">socket</A>
<LI><A HREF="library.html#IDX1022">socketpair</A>
<LI><A HREF="library.html#IDX491">sprintf</A>
<LI><A HREF="library.html#IDX1268">sqrt</A>
<LI><A HREF="library.html#IDX1288">srand</A>
<LI><A HREF="library.html#IDX1291">srandom</A>
<LI><A HREF="library.html#IDX539">sscanf</A>
<LI><A HREF="library.html#IDX1545">ssignal</A>
<LI><A HREF="library.html#IDX790">stat</A>
<LI><A HREF="library.html#IDX291">stpcpy</A>
<LI><A HREF="library.html#IDX304">strcasecmp</A>
<LI><A HREF="library.html#IDX292">strcat</A>
<LI><A HREF="library.html#IDX318">strchr</A>
<LI><A HREF="library.html#IDX303">strcmp</A>
<LI><A HREF="library.html#IDX311">strcoll</A>
<LI><A HREF="library.html#IDX288">strcpy</A>
<LI><A HREF="library.html#IDX323">strcspn</A>
<LI><A HREF="library.html#IDX290">strdup</A>
<LI><A HREF="library.html#IDX124">strerror</A>
<LI><A HREF="library.html#IDX1388">strftime</A>
<LI><A HREF="library.html#IDX277">strlen</A>
<LI><A HREF="library.html#IDX305">strncasecmp</A>
<LI><A HREF="library.html#IDX293">strncat</A>
<LI><A HREF="library.html#IDX306">strncmp</A>
<LI><A HREF="library.html#IDX289">strncpy</A>
<LI><A HREF="library.html#IDX324">strpbrk</A>
<LI><A HREF="library.html#IDX319">strrchr</A>
<LI><A HREF="library.html#IDX1530">strsignal</A>
<LI><A HREF="library.html#IDX322">strspn</A>
<LI><A HREF="library.html#IDX320">strstr</A>
<LI><A HREF="library.html#IDX1343">strtod</A>
<LI><A HREF="library.html#IDX329">strtok</A>
<LI><A HREF="library.html#IDX1338">strtol</A>
<LI><A HREF="library.html#IDX1339">strtoul</A>
<LI><A HREF="library.html#IDX313">strxfrm</A>
<LI><A HREF="library.html#IDX759">symlink</A>
<LI><A HREF="library.html#IDX1886">sysconf</A>
<LI><A HREF="library.html#IDX1684">system</A>
<H2>t</H2>
<LI><A HREF="library.html#IDX1254">tan</A>
<LI><A HREF="library.html#IDX1277">tanh</A>
<LI><A HREF="library.html#IDX1229">tcdrain</A>
<LI><A HREF="library.html#IDX1238">tcflow</A>
<LI><A HREF="library.html#IDX1232">tcflush</A>
<LI><A HREF="library.html#IDX1097">tcgetattr</A>
<LI><A HREF="library.html#IDX1777">tcgetpgrp</A>
<LI><A HREF="library.html#IDX1226">tcsendbreak</A>
<LI><A HREF="library.html#IDX1098">tcsetattr</A>
<LI><A HREF="library.html#IDX1778">tcsetpgrp</A>
<LI><A HREF="library.html#IDX746">telldir</A>
<LI><A HREF="library.html#IDX1569">TEMP_FAILURE_RETRY</A>
<LI><A HREF="library.html#IDX598">tempnam</A>
<LI><A HREF="library.html#IDX1369">time</A>
<LI><A HREF="library.html#IDX1357">times</A>
<LI><A HREF="library.html#IDX594">tmpfile</A>
<LI><A HREF="library.html#IDX595">tmpnam</A>
<LI><A HREF="library.html#IDX264">toascii</A>
<LI><A HREF="library.html#IDX262">tolower</A>
<LI><A HREF="library.html#IDX263">toupper</A>
<LI><A HREF="library.html#IDX1084">ttyname</A>
<LI><A HREF="library.html#IDX1392">tzset</A>
<H2>u</H2>
<LI><A HREF="library.html#IDX846">umask</A>
<LI><A HREF="library.html#IDX1856">uname</A>
<LI><A HREF="library.html#IDX477">ungetc</A>
<LI><A HREF="library.html#IDX764">unlink</A>
<LI><A HREF="library.html#IDX866">utime</A>
<LI><A HREF="library.html#IDX868">utimes</A>
<H2>v</H2>
<LI><A HREF="library.html#IDX1945">va_alist</A>
<LI><A HREF="library.html#IDX1942">va_arg</A>
<LI><A HREF="library.html#IDX1946">va_dcl</A>
<LI><A HREF="library.html#IDX1943">va_end</A>
<LI><A HREF="library.html#IDX1947">va_start</A>
<LI><A HREF="library.html#IDX156">valloc</A>
<LI><A HREF="library.html#IDX500">vasprintf</A>
<LI><A HREF="library.html#IDX1701">vfork</A>
<LI><A HREF="library.html#IDX497">vfprintf</A>
<LI><A HREF="library.html#IDX541">vfscanf</A>
<LI><A HREF="library.html#IDX496">vprintf</A>
<LI><A HREF="library.html#IDX540">vscanf</A>
<LI><A HREF="library.html#IDX499">vsnprintf</A>
<LI><A HREF="library.html#IDX498">vsprintf</A>
<LI><A HREF="library.html#IDX542">vsscanf</A>
<H2>w</H2>
<LI><A HREF="library.html#IDX1716">wait</A>
<LI><A HREF="library.html#IDX1727">wait3</A>
<LI><A HREF="library.html#IDX1728">wait4</A>
<LI><A HREF="library.html#IDX1715">waitpid</A>
<LI><A HREF="library.html#IDX1722">WCOREDUMP</A>
<LI><A HREF="library.html#IDX346">wcstombs</A>
<LI><A HREF="library.html#IDX355">wctomb</A>
<LI><A HREF="library.html#IDX1719">WEXITSTATUS</A>
<LI><A HREF="library.html#IDX1718">WIFEXITED</A>
<LI><A HREF="library.html#IDX1720">WIFSIGNALED</A>
<LI><A HREF="library.html#IDX1723">WIFSTOPPED</A>
<LI><A HREF="library.html#IDX418">wordexp</A>
<LI><A HREF="library.html#IDX419">wordfree</A>
<LI><A HREF="library.html#IDX643">write</A>
<LI><A HREF="library.html#IDX1724">WSTOPSIG</A>
<LI><A HREF="library.html#IDX1721">WTERMSIG</A>
</DIR>
<P>
<H1><A NAME="SEC508" HREF="library_toc.html#SEC508">Variable and Constant Macro Index</A></H1>
<P>
<DIR>
<H2>*</H2>
<LI><A HREF="library.html#IDX1391">*tzname[2]</A>
<H2>_</H2>
<LI><A HREF="library.html#IDX165">__free_hook</A>
<LI><A HREF="library.html#IDX163">__malloc_hook</A>
<LI><A HREF="library.html#IDX164">__realloc_hook</A>
<LI><A HREF="library.html#IDX38">_BSD_SOURCE</A>
<LI><A HREF="library.html#IDX40">_GNU_SOURCE</A>
<LI><A HREF="library.html#IDX586">_IOFBF</A>
<LI><A HREF="library.html#IDX587">_IOLBF</A>
<LI><A HREF="library.html#IDX588">_IONBF</A>
<LI><A HREF="library.html#IDX1879">_POSIX2_C_DEV</A>
<LI><A HREF="library.html#IDX1885">_POSIX2_C_VERSION</A>
<LI><A HREF="library.html#IDX1880">_POSIX2_FORT_DEV</A>
<LI><A HREF="library.html#IDX1881">_POSIX2_FORT_RUN</A>
<LI><A HREF="library.html#IDX1882">_POSIX2_LOCALEDEF</A>
<LI><A HREF="library.html#IDX1883">_POSIX2_SW_DEV</A>
<LI><A HREF="library.html#IDX37">_POSIX_C_SOURCE</A>
<LI><A HREF="library.html#IDX1901">_POSIX_CHOWN_RESTRICTED</A>
<LI><A HREF="library.html#IDX1877">_POSIX_JOB_CONTROL</A>
<LI><A HREF="library.html#IDX1902">_POSIX_NO_TRUNC</A>
<LI><A HREF="library.html#IDX1878">_POSIX_SAVED_IDS</A>
<LI><A HREF="library.html#IDX36">_POSIX_SOURCE</A>
<LI><A HREF="library.html#IDX1903">_POSIX_VDISABLE</A>
<LI><A HREF="library.html#IDX1884">_POSIX_VERSION</A>
<LI><A HREF="library.html#IDX39">_SVID_SOURCE</A>
<H2>a</H2>
<LI><A HREF="library.html#IDX916">AF_FILE</A>
<LI><A HREF="library.html#IDX918">AF_INET</A>
<LI><A HREF="library.html#IDX917">AF_UNIX</A>
<LI><A HREF="library.html#IDX919">AF_UNSPEC</A>
<LI><A HREF="library.html#IDX1151">ALTWERASE</A>
<LI><A HREF="library.html#IDX1862">ARG_MAX</A>
<H2>b</H2>
<LI><A HREF="library.html#IDX1165">B0</A>
<LI><A HREF="library.html#IDX1168">B110</A>
<LI><A HREF="library.html#IDX1174">B1200</A>
<LI><A HREF="library.html#IDX1169">B134</A>
<LI><A HREF="library.html#IDX1170">B150</A>
<LI><A HREF="library.html#IDX1175">B1800</A>
<LI><A HREF="library.html#IDX1179">B19200</A>
<LI><A HREF="library.html#IDX1171">B200</A>
<LI><A HREF="library.html#IDX1176">B2400</A>
<LI><A HREF="library.html#IDX1172">B300</A>
<LI><A HREF="library.html#IDX1180">B38400</A>
<LI><A HREF="library.html#IDX1177">B4800</A>
<LI><A HREF="library.html#IDX1166">B50</A>
<LI><A HREF="library.html#IDX1173">B600</A>
<LI><A HREF="library.html#IDX1167">B75</A>
<LI><A HREF="library.html#IDX1178">B9600</A>
<LI><A HREF="library.html#IDX1907">BC_BASE_MAX</A>
<LI><A HREF="library.html#IDX1911">BC_DIM_MAX</A>
<LI><A HREF="library.html#IDX1908">BC_SCALE_MAX</A>
<LI><A HREF="library.html#IDX1910">BC_STRING_MAX</A>
<LI><A HREF="library.html#IDX1110">BRKINT</A>
<LI><A HREF="library.html#IDX589">BUFSIZ</A>
<H2>c</H2>
<LI><A HREF="library.html#IDX1134">CCTS_OFLOW</A>
<LI><A HREF="library.html#IDX1864">CHILD_MAX</A>
<LI><A HREF="library.html#IDX1352">CLK_TCK</A>
<LI><A HREF="library.html#IDX1120">CLOCAL</A>
<LI><A HREF="library.html#IDX1351">CLOCKS_PER_SEC</A>
<LI><A HREF="library.html#IDX1912">COLL_WEIGHTS_MAX</A>
<LI><A HREF="library.html#IDX1467">COREFILE</A>
<LI><A HREF="library.html#IDX1125">CREAD</A>
<LI><A HREF="library.html#IDX1135">CRTS_IFLOW</A>
<LI><A HREF="library.html#IDX1130">CS5</A>
<LI><A HREF="library.html#IDX1131">CS6</A>
<LI><A HREF="library.html#IDX1132">CS7</A>
<LI><A HREF="library.html#IDX1133">CS8</A>
<LI><A HREF="library.html#IDX1129">CSIZE</A>
<LI><A HREF="library.html#IDX1126">CSTOPB</A>
<H2>d</H2>
<LI><A HREF="library.html#IDX1394">daylight</A>
<H2>e</H2>
<LI><A HREF="library.html#IDX56">E2BIG</A>
<LI><A HREF="library.html#IDX62">EACCES</A>
<LI><A HREF="library.html#IDX98">EADDRINUSE</A>
<LI><A HREF="library.html#IDX99">EADDRNOTAVAIL</A>
<LI><A HREF="library.html#IDX97">EAFNOSUPPORT</A>
<LI><A HREF="library.html#IDX84">EAGAIN</A>
<LI><A HREF="library.html#IDX87">EALREADY</A>
<LI><A HREF="library.html#IDX1243">EBADF</A>
<LI><A HREF="library.html#IDX65">EBUSY</A>
<LI><A HREF="library.html#IDX59">ECHILD</A>
<LI><A HREF="library.html#IDX1138">ECHO</A>
<LI><A HREF="library.html#IDX1150">ECHOCTL</A>
<LI><A HREF="library.html#IDX1140">ECHOE</A>
<LI><A HREF="library.html#IDX1141">ECHOK</A>
<LI><A HREF="library.html#IDX1148">ECHOKE</A>
<LI><A HREF="library.html#IDX1142">ECHONL</A>
<LI><A HREF="library.html#IDX1149">ECHOPRT</A>
<LI><A HREF="library.html#IDX103">ECONNABORTED</A>
<LI><A HREF="library.html#IDX110">ECONNREFUSED</A>
<LI><A HREF="library.html#IDX104">ECONNRESET</A>
<LI><A HREF="library.html#IDX122">ED</A>
<LI><A HREF="library.html#IDX60">EDEADLK</A>
<LI><A HREF="library.html#IDX89">EDESTADDRREQ</A>
<LI><A HREF="library.html#IDX82">EDOM</A>
<LI><A HREF="library.html#IDX117">EDQUOT</A>
<LI><A HREF="library.html#IDX66">EEXIST</A>
<LI><A HREF="library.html#IDX63">EFAULT</A>
<LI><A HREF="library.html#IDX76">EFBIG</A>
<LI><A HREF="library.html#IDX123">EGRATUITOUS</A>
<LI><A HREF="library.html#IDX113">EHOSTDOWN</A>
<LI><A HREF="library.html#IDX114">EHOSTUNREACH</A>
<LI><A HREF="library.html#IDX86">EINPROGRESS</A>
<LI><A HREF="library.html#IDX53">EINTR</A>
<LI><A HREF="library.html#IDX1245">EINVAL</A>
<LI><A HREF="library.html#IDX54">EIO</A>
<LI><A HREF="library.html#IDX106">EISCONN</A>
<LI><A HREF="library.html#IDX70">EISDIR</A>
<LI><A HREF="library.html#IDX111">ELOOP</A>
<LI><A HREF="library.html#IDX73">EMFILE</A>
<LI><A HREF="library.html#IDX80">EMLINK</A>
<LI><A HREF="library.html#IDX90">EMSGSIZE</A>
<LI><A HREF="library.html#IDX112">ENAMETOOLONG</A>
<LI><A HREF="library.html#IDX100">ENETDOWN</A>
<LI><A HREF="library.html#IDX102">ENETRESET</A>
<LI><A HREF="library.html#IDX101">ENETUNREACH</A>
<LI><A HREF="library.html#IDX72">ENFILE</A>
<LI><A HREF="library.html#IDX105">ENOBUFS</A>
<LI><A HREF="library.html#IDX68">ENODEV</A>
<LI><A HREF="library.html#IDX51">ENOENT</A>
<LI><A HREF="library.html#IDX57">ENOEXEC</A>
<LI><A HREF="library.html#IDX120">ENOLCK</A>
<LI><A HREF="library.html#IDX61">ENOMEM</A>
<LI><A HREF="library.html#IDX92">ENOPROTOOPT</A>
<LI><A HREF="library.html#IDX77">ENOSPC</A>
<LI><A HREF="library.html#IDX121">ENOSYS</A>
<LI><A HREF="library.html#IDX64">ENOTBLK</A>
<LI><A HREF="library.html#IDX107">ENOTCONN</A>
<LI><A HREF="library.html#IDX69">ENOTDIR</A>
<LI><A HREF="library.html#IDX115">ENOTEMPTY</A>
<LI><A HREF="library.html#IDX88">ENOTSOCK</A>
<LI><A HREF="library.html#IDX1244">ENOTTY</A>
<LI><A HREF="library.html#IDX1650">environ</A>
<LI><A HREF="library.html#IDX55">ENXIO</A>
<LI><A HREF="library.html#IDX552">EOF</A>
<LI><A HREF="library.html#IDX95">EOPNOTSUPP</A>
<LI><A HREF="library.html#IDX50">EPERM</A>
<LI><A HREF="library.html#IDX96">EPFNOSUPPORT</A>
<LI><A HREF="library.html#IDX81">EPIPE</A>
<LI><A HREF="library.html#IDX93">EPROTONOSUPPORT</A>
<LI><A HREF="library.html#IDX91">EPROTOTYPE</A>
<LI><A HREF="library.html#IDX83">ERANGE</A>
<LI><A HREF="library.html#IDX119">EREMOTE</A>
<LI><A HREF="library.html#IDX79">EROFS</A>
<LI><A HREF="library.html#IDX47">errno</A>
<LI><A HREF="library.html#IDX108">ESHUTDOWN</A>
<LI><A HREF="library.html#IDX94">ESOCKTNOSUPPORT</A>
<LI><A HREF="library.html#IDX78">ESPIPE</A>
<LI><A HREF="library.html#IDX52">ESRCH</A>
<LI><A HREF="library.html#IDX118">ESTALE</A>
<LI><A HREF="library.html#IDX109">ETIMEDOUT</A>
<LI><A HREF="library.html#IDX75">ETXTBSY</A>
<LI><A HREF="library.html#IDX116">EUSERS</A>
<LI><A HREF="library.html#IDX85">EWOULDBLOCK</A>
<LI><A HREF="library.html#IDX67">EXDEV</A>
<LI><A HREF="library.html#IDX1672">EXIT_FAILURE</A>
<LI><A HREF="library.html#IDX1671">EXIT_SUCCESS</A>
<LI><A HREF="library.html#IDX1913">EXPR_NEST_MAX</A>
<LI><A HREF="library.html#IDX1181">EXTA</A>
<LI><A HREF="library.html#IDX1182">EXTB</A>
<H2>f</H2>
<LI><A HREF="library.html#IDX694">F_DUPFD</A>
<LI><A HREF="library.html#IDX697">F_GETFD</A>
<LI><A HREF="library.html#IDX703">F_GETFL</A>
<LI><A HREF="library.html#IDX714">F_GETLK</A>
<LI><A HREF="library.html#IDX722">F_GETOWN</A>
<LI><A HREF="library.html#IDX859">F_OK</A>
<LI><A HREF="library.html#IDX717">F_RDLCK</A>
<LI><A HREF="library.html#IDX698">F_SETFD</A>
<LI><A HREF="library.html#IDX704">F_SETFL</A>
<LI><A HREF="library.html#IDX715">F_SETLK</A>
<LI><A HREF="library.html#IDX716">F_SETLKW</A>
<LI><A HREF="library.html#IDX723">F_SETOWN</A>
<LI><A HREF="library.html#IDX719">F_UNLCK</A>
<LI><A HREF="library.html#IDX718">F_WRLCK</A>
<LI><A HREF="library.html#IDX699">FD_CLOEXEC</A>
<LI><A HREF="library.html#IDX678">FD_SETSIZE</A>
<LI><A HREF="library.html#IDX1899">FILENAME_MAX</A>
<LI><A HREF="library.html#IDX1152">FLUSHO</A>
<LI><A HREF="library.html#IDX452">FOPEN_MAX</A>
<LI><A HREF="library.html#IDX1477">FPE_DECOVF_TRAP</A>
<LI><A HREF="library.html#IDX1475">FPE_FLTDIV_TRAP</A>
<LI><A HREF="library.html#IDX1474">FPE_FLTOVF_TRAP</A>
<LI><A HREF="library.html#IDX1476">FPE_FLTUND_TRAP</A>
<LI><A HREF="library.html#IDX1472">FPE_INTDIV_TRAP</A>
<LI><A HREF="library.html#IDX1471">FPE_INTOVF_TRAP</A>
<LI><A HREF="library.html#IDX1473">FPE_SUBRNG_TRAP</A>
<H2>h</H2>
<LI><A HREF="library.html#IDX959">h_errno</A>
<LI><A HREF="library.html#IDX960">HOST_NOT_FOUND</A>
<LI><A HREF="library.html#IDX1249">HUGE_VAL</A>
<LI><A HREF="library.html#IDX1124">HUPCL</A>
<H2>i</H2>
<LI><A HREF="library.html#IDX1137">ICANON</A>
<LI><A HREF="library.html#IDX1112">ICRNL</A>
<LI><A HREF="library.html#IDX1145">IEXTEN</A>
<LI><A HREF="library.html#IDX1108">IGNBRK</A>
<LI><A HREF="library.html#IDX1111">IGNCR</A>
<LI><A HREF="library.html#IDX1105">IGNPAR</A>
<LI><A HREF="library.html#IDX943">INADDR_ANY</A>
<LI><A HREF="library.html#IDX1113">INLCR</A>
<LI><A HREF="library.html#IDX1103">INPCK</A>
<LI><A HREF="library.html#IDX1430">int</A>
<LI><A HREF="library.html#IDX969">IPPORT_RESERVED</A>
<LI><A HREF="library.html#IDX970">IPPORT_USERRESERVED</A>
<LI><A HREF="library.html#IDX1143">ISIG</A>
<LI><A HREF="library.html#IDX1107">ISTRIP</A>
<LI><A HREF="library.html#IDX1114">IXOFF</A>
<LI><A HREF="library.html#IDX1115">IXON</A>
<H2>l</H2>
<LI><A HREF="library.html#IDX1764">L_ctermid</A>
<LI><A HREF="library.html#IDX1817">L_cuserid</A>
<LI><A HREF="library.html#IDX570">L_INCR</A>
<LI><A HREF="library.html#IDX569">L_SET</A>
<LI><A HREF="library.html#IDX596">L_tmpnam</A>
<LI><A HREF="library.html#IDX571">L_XTND</A>
<LI><A HREF="library.html#IDX367">LANG</A>
<LI><A HREF="library.html#IDX366">LC_ALL</A>
<LI><A HREF="library.html#IDX361">LC_COLLATE</A>
<LI><A HREF="library.html#IDX362">LC_CTYPE</A>
<LI><A HREF="library.html#IDX363">LC_MONETARY</A>
<LI><A HREF="library.html#IDX364">LC_NUMERIC</A>
<LI><A HREF="library.html#IDX365">LC_TIME</A>
<LI><A HREF="library.html#IDX1914">LINE_MAX</A>
<LI><A HREF="library.html#IDX1889">LINK_MAX</A>
<H2>m</H2>
<LI><A HREF="library.html#IDX1891">MAX_CANON</A>
<LI><A HREF="library.html#IDX1892">MAX_INPUT</A>
<LI><A HREF="library.html#IDX1898">MAXNAMLEN</A>
<LI><A HREF="library.html#IDX336">MB_CUR_MAX</A>
<LI><A HREF="library.html#IDX334">MB_LEN_MAX</A>
<LI><A HREF="library.html#IDX1136">MDMBUF</A>
<LI><A HREF="library.html#IDX1048">MSG_DONTROUTE</A>
<LI><A HREF="library.html#IDX1046">MSG_OOB</A>
<LI><A HREF="library.html#IDX1047">MSG_PEEK</A>
<H2>n</H2>
<LI><A HREF="library.html#IDX1894">NAME_MAX</A>
<LI><A HREF="library.html#IDX1297">NAN</A>
<LI><A HREF="library.html#IDX1095">NCCS</A>
<LI><A HREF="library.html#IDX1920">NDEBUG</A>
<LI><A HREF="library.html#IDX1871">NGROUPS_MAX</A>
<LI><A HREF="library.html#IDX963">NO_ADDRESS</A>
<LI><A HREF="library.html#IDX962">NO_RECOVERY</A>
<LI><A HREF="library.html#IDX1146">NOFLSH</A>
<LI><A HREF="library.html#IDX1153">NOKERNINFO</A>
<LI><A HREF="library.html#IDX1465">NSIG</A>
<LI><A HREF="library.html#IDX1949">NULL</A>
<H2>o</H2>
<LI><A HREF="library.html#IDX705">O_ACCMODE</A>
<LI><A HREF="library.html#IDX626">O_APPEND</A>
<LI><A HREF="library.html#IDX628">O_CREAT</A>
<LI><A HREF="library.html#IDX630">O_EXCL</A>
<LI><A HREF="library.html#IDX631">O_NOCTTY</A>
<LI><A HREF="library.html#IDX632">O_NONBLOCK</A>
<LI><A HREF="library.html#IDX623">O_RDONLY</A>
<LI><A HREF="library.html#IDX625">O_RDWR</A>
<LI><A HREF="library.html#IDX634">O_TRUNC</A>
<LI><A HREF="library.html#IDX624">O_WRONLY</A>
<LI><A HREF="library.html#IDX1117">ONLCR</A>
<LI><A HREF="library.html#IDX1119">ONOEOT</A>
<LI><A HREF="library.html#IDX1866">OPEN_MAX</A>
<LI><A HREF="library.html#IDX1116">OPOST</A>
<LI><A HREF="library.html#IDX1639">optarg</A>
<LI><A HREF="library.html#IDX1636">opterr</A>
<LI><A HREF="library.html#IDX1638">optind</A>
<LI><A HREF="library.html#IDX1637">optopt</A>
<LI><A HREF="library.html#IDX1118">OXTABS</A>
<H2>p</H2>
<LI><A HREF="library.html#IDX600">P_tmpdir</A>
<LI><A HREF="library.html#IDX506">PA_CHAR</A>
<LI><A HREF="library.html#IDX510">PA_DOUBLE</A>
<LI><A HREF="library.html#IDX514">PA_FLAG_LONG</A>
<LI><A HREF="library.html#IDX516">PA_FLAG_LONG_DOUBLE</A>
<LI><A HREF="library.html#IDX515">PA_FLAG_LONG_LONG</A>
<LI><A HREF="library.html#IDX504">PA_FLAG_MASK</A>
<LI><A HREF="library.html#IDX512">PA_FLAG_PTR</A>
<LI><A HREF="library.html#IDX513">PA_FLAG_SHORT</A>
<LI><A HREF="library.html#IDX509">PA_FLOAT</A>
<LI><A HREF="library.html#IDX505">PA_INT</A>
<LI><A HREF="library.html#IDX511">PA_LAST</A>
<LI><A HREF="library.html#IDX508">PA_POINTER</A>
<LI><A HREF="library.html#IDX507">PA_STRING</A>
<LI><A HREF="library.html#IDX1127">PARENB</A>
<LI><A HREF="library.html#IDX1106">PARMRK</A>
<LI><A HREF="library.html#IDX1128">PARODD</A>
<LI><A HREF="library.html#IDX1895">PATH_MAX</A>
<LI><A HREF="library.html#IDX1154">PENDIN</A>
<LI><A HREF="library.html#IDX1004">PF_CCITT</A>
<LI><A HREF="library.html#IDX926">PF_FILE</A>
<LI><A HREF="library.html#IDX1005">PF_IMPLINK</A>
<LI><A HREF="library.html#IDX932">PF_INET</A>
<LI><A HREF="library.html#IDX1003">PF_ISO</A>
<LI><A HREF="library.html#IDX1002">PF_NS</A>
<LI><A HREF="library.html#IDX1006">PF_ROUTE</A>
<LI><A HREF="library.html#IDX927">PF_UNIX</A>
<LI><A HREF="library.html#IDX1897">PIPE_BUF</A>
<LI><A HREF="library.html#IDX1435">PRIO_MAX</A>
<LI><A HREF="library.html#IDX1434">PRIO_MIN</A>
<LI><A HREF="library.html#IDX1439">PRIO_PGRP</A>
<LI><A HREF="library.html#IDX1438">PRIO_PROCESS</A>
<LI><A HREF="library.html#IDX1440">PRIO_USER</A>
<LI><A HREF="library.html#IDX128">program_invocation_name</A>
<LI><A HREF="library.html#IDX129">program_invocation_short_name</A>
<H2>r</H2>
<LI><A HREF="library.html#IDX856">R_OK</A>
<LI><A HREF="library.html#IDX1286">RAND_MAX</A>
<LI><A HREF="library.html#IDX1873">RE_DUP_MAX</A>
<LI><A HREF="library.html#IDX1429">RLIM_NLIMITS</A>
<LI><A HREF="library.html#IDX1426">RLIMIT_CORE</A>
<LI><A HREF="library.html#IDX1422">RLIMIT_CPU</A>
<LI><A HREF="library.html#IDX1424">RLIMIT_DATA</A>
<LI><A HREF="library.html#IDX1423">RLIMIT_FSIZE</A>
<LI><A HREF="library.html#IDX1428">RLIMIT_OPEN_FILES</A>
<LI><A HREF="library.html#IDX1427">RLIMIT_RSS</A>
<LI><A HREF="library.html#IDX1425">RLIMIT_STACK</A>
<H2>s</H2>
<LI><A HREF="library.html#IDX824">S_IEXEC</A>
<LI><A HREF="library.html#IDX804">S_IFBLK</A>
<LI><A HREF="library.html#IDX803">S_IFCHR</A>
<LI><A HREF="library.html#IDX802">S_IFDIR</A>
<LI><A HREF="library.html#IDX808">S_IFIFO</A>
<LI><A HREF="library.html#IDX806">S_IFLNK</A>
<LI><A HREF="library.html#IDX801">S_IFMT</A>
<LI><A HREF="library.html#IDX805">S_IFREG</A>
<LI><A HREF="library.html#IDX807">S_IFSOCK</A>
<LI><A HREF="library.html#IDX820">S_IREAD</A>
<LI><A HREF="library.html#IDX826">S_IRGRP</A>
<LI><A HREF="library.html#IDX830">S_IROTH</A>
<LI><A HREF="library.html#IDX819">S_IRUSR</A>
<LI><A HREF="library.html#IDX829">S_IRWXG</A>
<LI><A HREF="library.html#IDX833">S_IRWXO</A>
<LI><A HREF="library.html#IDX825">S_IRWXU</A>
<LI><A HREF="library.html#IDX835">S_ISGID</A>
<LI><A HREF="library.html#IDX834">S_ISUID</A>
<LI><A HREF="library.html#IDX837">S_ISVTX</A>
<LI><A HREF="library.html#IDX827">S_IWGRP</A>
<LI><A HREF="library.html#IDX831">S_IWOTH</A>
<LI><A HREF="library.html#IDX822">S_IWRITE</A>
<LI><A HREF="library.html#IDX821">S_IWUSR</A>
<LI><A HREF="library.html#IDX828">S_IXGRP</A>
<LI><A HREF="library.html#IDX832">S_IXOTH</A>
<LI><A HREF="library.html#IDX823">S_IXUSR</A>
<LI><A HREF="library.html#IDX1555">SA_NOCLDSTOP</A>
<LI><A HREF="library.html#IDX1556">SA_ONSTACK</A>
<LI><A HREF="library.html#IDX1557">SA_RESTART</A>
<LI><A HREF="library.html#IDX566">SEEK_CUR</A>
<LI><A HREF="library.html#IDX567">SEEK_END</A>
<LI><A HREF="library.html#IDX565">SEEK_SET</A>
<LI><A HREF="library.html#IDX1594">SIG_BLOCK</A>
<LI><A HREF="library.html#IDX1541">SIG_DFL</A>
<LI><A HREF="library.html#IDX1546">SIG_ERR</A>
<LI><A HREF="library.html#IDX1543">SIG_IGN</A>
<LI><A HREF="library.html#IDX1596">SIG_SETMASK</A>
<LI><A HREF="library.html#IDX1595">SIG_UNBLOCK</A>
<LI><A HREF="library.html#IDX1484">SIGABRT</A>
<LI><A HREF="library.html#IDX1499">SIGALRM</A>
<LI><A HREF="library.html#IDX1482">SIGBUS</A>
<LI><A HREF="library.html#IDX1511">SIGCHLD</A>
<LI><A HREF="library.html#IDX1513">SIGCONT</A>
<LI><A HREF="library.html#IDX1468">SIGFPE</A>
<LI><A HREF="library.html#IDX1487">SIGHUP</A>
<LI><A HREF="library.html#IDX1478">SIGILL</A>
<LI><A HREF="library.html#IDX1489">SIGINT</A>
<LI><A HREF="library.html#IDX1505">SIGIO</A>
<LI><A HREF="library.html#IDX1497">SIGKILL</A>
<LI><A HREF="library.html#IDX1523">SIGPIPE</A>
<LI><A HREF="library.html#IDX1503">SIGPROF</A>
<LI><A HREF="library.html#IDX1491">SIGQUIT</A>
<LI><A HREF="library.html#IDX1480">SIGSEGV</A>
<LI><A HREF="library.html#IDX1515">SIGSTOP</A>
<LI><A HREF="library.html#IDX1494">SIGTERM</A>
<LI><A HREF="library.html#IDX1517">SIGTSTP</A>
<LI><A HREF="library.html#IDX1519">SIGTTIN</A>
<LI><A HREF="library.html#IDX1521">SIGTTOU</A>
<LI><A HREF="library.html#IDX1508">SIGURG</A>
<LI><A HREF="library.html#IDX1526">SIGUSR1</A>
<LI><A HREF="library.html#IDX1527">SIGUSR2</A>
<LI><A HREF="library.html#IDX1501">SIGVTALRM</A>
<LI><A HREF="library.html#IDX908">SOCK_DGRAM</A>
<LI><A HREF="library.html#IDX909">SOCK_RAW</A>
<LI><A HREF="library.html#IDX907">SOCK_STREAM</A>
<LI><A HREF="library.html#IDX1066">SOL_SOCKET</A>
<LI><A HREF="library.html#IDX1872">SSIZE_MAX</A>
<LI><A HREF="library.html#IDX447">stderr</A>
<LI><A HREF="library.html#IDX662">STDERR_FILENO</A>
<LI><A HREF="library.html#IDX443">stdin</A>
<LI><A HREF="library.html#IDX658">STDIN_FILENO</A>
<LI><A HREF="library.html#IDX445">stdout</A>
<LI><A HREF="library.html#IDX660">STDOUT_FILENO</A>
<LI><A HREF="library.html#IDX1867">STREAM_MAX</A>
<LI><A HREF="library.html#IDX1612">SV_INTERRUPT</A>
<LI><A HREF="library.html#IDX1611">SV_ONSTACK</A>
<LI><A HREF="library.html#IDX1613">SV_RESETHAND</A>
<LI><A HREF="library.html#IDX1534">sys_siglist</A>
<H2>t</H2>
<LI><A HREF="library.html#IDX1233">TCIFLUSH</A>
<LI><A HREF="library.html#IDX1241">TCIOFF</A>
<LI><A HREF="library.html#IDX1235">TCIOFLUSH</A>
<LI><A HREF="library.html#IDX1242">TCION</A>
<LI><A HREF="library.html#IDX1234">TCOFLUSH</A>
<LI><A HREF="library.html#IDX1239">TCOOFF</A>
<LI><A HREF="library.html#IDX1240">TCOON</A>
<LI><A HREF="library.html#IDX1100">TCSADRAIN</A>
<LI><A HREF="library.html#IDX1101">TCSAFLUSH</A>
<LI><A HREF="library.html#IDX1099">TCSANOW</A>
<LI><A HREF="library.html#IDX1102">TCSASOFT</A>
<LI><A HREF="library.html#IDX1393">timezone</A>
<LI><A HREF="library.html#IDX597">TMP_MAX</A>
<LI><A HREF="library.html#IDX1147">TOSTOP</A>
<LI><A HREF="library.html#IDX961">TRY_AGAIN</A>
<LI><A HREF="library.html#IDX1869">TZNAME_MAX</A>
<H2>v</H2>
<LI><A HREF="library.html#IDX1216">VDISCARD</A>
<LI><A HREF="library.html#IDX1209">VDSUSP</A>
<LI><A HREF="library.html#IDX1185">VEOF</A>
<LI><A HREF="library.html#IDX1187">VEOL</A>
<LI><A HREF="library.html#IDX1193">VEOL2</A>
<LI><A HREF="library.html#IDX1189">VERASE</A>
<LI><A HREF="library.html#IDX1201">VINTR</A>
<LI><A HREF="library.html#IDX1191">VKILL</A>
<LI><A HREF="library.html#IDX1199">VLNEXT</A>
<LI><A HREF="library.html#IDX1220">VMIN</A>
<LI><A HREF="library.html#IDX1204">VQUIT</A>
<LI><A HREF="library.html#IDX1197">VREPRINT</A>
<LI><A HREF="library.html#IDX1212">VSTART</A>
<LI><A HREF="library.html#IDX1218">VSTATUS</A>
<LI><A HREF="library.html#IDX1214">VSTOP</A>
<LI><A HREF="library.html#IDX1206">VSUSP</A>
<LI><A HREF="library.html#IDX1222">VTIME</A>
<LI><A HREF="library.html#IDX1195">VWERASE</A>
<H2>w</H2>
<LI><A HREF="library.html#IDX857">W_OK</A>
<H2>x</H2>
<LI><A HREF="library.html#IDX858">X_OK</A>
</DIR>
<P>
<H1><A NAME="SEC509" HREF="library_toc.html#SEC509">Program and File Index</A></H1>
<P>
<DIR>
<H2>/</H2>
<LI><A HREF="library.html#IDX1834">/etc/group</A>
<LI><A HREF="library.html#IDX954">/etc/hosts</A>
<LI><A HREF="library.html#IDX1072">/etc/networks</A>
<LI><A HREF="library.html#IDX1820">/etc/passwd</A>
<LI><A HREF="library.html#IDX994">/etc/protocols</A>
<LI><A HREF="library.html#IDX974">/etc/services</A>
<H2>a</H2>
<LI><A HREF="library.html#IDX944">arpa/inet.h</A>
<LI><A HREF="library.html#IDX1919">assert.h</A>
<H2>c</H2>
<LI><A HREF="library.html#IDX727">cd</A>
<LI><A HREF="library.html#IDX813">chgrp</A>
<LI><A HREF="library.html#IDX843">chmod</A>
<LI><A HREF="library.html#IDX812">chown</A>
<LI><A HREF="library.html#IDX261">ctype.h</A>
<H2>d</H2>
<LI><A HREF="library.html#IDX744">dirent.h</A>
<H2>e</H2>
<LI><A HREF="library.html#IDX49">errno.h</A>
<H2>f</H2>
<LI><A HREF="library.html#IDX721">fcntl.h</A>
<LI><A HREF="library.html#IDX1974">float.h</A>
<LI><A HREF="library.html#IDX394">fnmatch.h</A>
<H2>g</H2>
<LI><A HREF="library.html#IDX4">gcc</A>
<LI><A HREF="library.html#IDX1835">grp.h</A>
<H2>h</H2>
<LI><A HREF="library.html#IDX1847">hostid</A>
<LI><A HREF="library.html#IDX1846">hostname</A>
<H2>k</H2>
<LI><A HREF="library.html#IDX1496">kill</A>
<H2>l</H2>
<LI><A HREF="library.html#IDX1956">limits.h</A>
<LI><A HREF="library.html#IDX372">locale.h</A>
<LI><A HREF="library.html#IDX779">ls</A>
<H2>m</H2>
<LI><A HREF="library.html#IDX223">malloc.c</A>
<LI><A HREF="library.html#IDX217">malloc.h</A>
<LI><A HREF="library.html#IDX1320">math.h</A>
<LI><A HREF="library.html#IDX776">mkdir</A>
<H2>n</H2>
<LI><A HREF="library.html#IDX1073">netdb.h</A>
<LI><A HREF="library.html#IDX987">netinet/in.h</A>
<H2>o</H2>
<LI><A HREF="library.html#IDX171">obstack.h</A>
<H2>p</H2>
<LI><A HREF="library.html#IDX522">printf.h</A>
<LI><A HREF="library.html#IDX1821">pwd.h</A>
<H2>s</H2>
<LI><A HREF="library.html#IDX1448">setjmp.h</A>
<LI><A HREF="library.html#IDX1685">sh</A>
<LI><A HREF="library.html#IDX1609">signal.h</A>
<LI><A HREF="library.html#IDX1939">stdarg.h</A>
<LI><A HREF="library.html#IDX1950">stddef.h</A>
<LI><A HREF="library.html#IDX1813">stdio.h</A>
<LI><A HREF="library.html#IDX1686">stdlib.h</A>
<LI><A HREF="library.html#IDX1531">string.h</A>
<LI><A HREF="library.html#IDX1850">sys/param.h</A>
<LI><A HREF="library.html#IDX1433">sys/resource.h</A>
<LI><A HREF="library.html#IDX1067">sys/socket.h</A>
<LI><A HREF="library.html#IDX887">sys/stat.h</A>
<LI><A HREF="library.html#IDX1403">sys/time.h</A>
<LI><A HREF="library.html#IDX1355">sys/times.h</A>
<LI><A HREF="library.html#IDX1805">sys/types.h</A>
<LI><A HREF="library.html#IDX928">sys/un.h</A>
<LI><A HREF="library.html#IDX1854">sys/utsname.h</A>
<LI><A HREF="library.html#IDX1725">sys/wait.h</A>
<H2>t</H2>
<LI><A HREF="library.html#IDX1090">termios.h</A>
<LI><A HREF="library.html#IDX1389">time.h</A>
<H2>u</H2>
<LI><A HREF="library.html#IDX844">umask</A>
<LI><A HREF="library.html#IDX1904">unistd.h</A>
<LI><A HREF="library.html#IDX864">utime.h</A>
<H2>v</H2>
<LI><A HREF="library.html#IDX1944">varargs.h</A>
</DIR>
<P>