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

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

   This file documents the GNU C library.

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

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

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

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

   A GNU Manual

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

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


File: libc.info,  Node: Introduction,  Next: Error Reporting,  Prev: Top,  Up: Top

Introduction
************

   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 "library", which you compile and link with your programs.

   The GNU C library, described in this document, defines all of the
library functions that are specified by the ISO 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.

   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 non-portable
to other systems.  But the emphasis in this manual is not on strict
portability.

* Menu:

* Getting Started::             What this manual is for and how to use it.
* Standards and Portability::   Standards and sources upon which the GNU
                                 C library is based.
* Using the Library::           Some practical uses for the library.
* Roadmap to the Manual::       Overview of the remaining chapters in
                                 this manual.


File: libc.info,  Node: Getting Started,  Next: Standards and Portability,  Up: Introduction

Getting Started
===============

   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 ISO standard C (*note ISO
C::), rather than "traditional" pre-ISO C dialects, is assumed.

   The GNU C library includes several "header files", 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 `stdio.h' declares facilities for
performing input and output, and the header file `string.h' declares
string processing utilities.  The organization of this manual generally
follows the same division as the header files.

   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 _lot_ of functions in the GNU C library and it's not
realistic to expect that you will be able to remember exactly _how_ 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
_when_ to make use of library functions, and _where_ in this manual you
can find more specific information about them.


File: libc.info,  Node: Standards and Portability,  Next: Using the Library,  Prev: Getting Started,  Up: Introduction

Standards and Portability
=========================

   This section discusses the various standards and other sources that
the GNU C library is based upon.  These sources include the ISO C and
POSIX standards, and the System V and Berkeley Unix implementations.

   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.

   *Note Library Summary::, 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.

* Menu:

* ISO C::                       The international standard for the C
                                 programming language.
* POSIX::                       The ISO/IEC 9945 (aka IEEE 1003) standards
                                 for operating systems.
* Berkeley Unix::               BSD and SunOS.
* SVID::                        The System V Interface Description.
* XPG::                         The X/Open Portability Guide.


File: libc.info,  Node: ISO C,  Next: POSIX,  Up: Standards and Portability

ISO C
-----

   The GNU C library is compatible with the C standard adopted by the
American National Standards Institute (ANSI): `American National
Standard X3.159-1989--"ANSI C"' and later by the International
Standardization Organization (ISO): `ISO/IEC 9899:1990, "Programming
languages--C"'.  We here refer to the standard as ISO C since this is
the more general standard in respect of ratification.  The header files
and library facilities that make up the GNU library are a superset of
those specified by the ISO C standard.

   If you are concerned about strict adherence to the ISO C standard,
you should use the `-ansi' option when you compile your programs with
the GNU C compiler.  This tells the compiler to define _only_ ISO
standard features from the library header files, unless you explicitly
ask for additional features.  *Note Feature Test Macros::, for
information on how to do this.

   Being able to restrict the library to include only ISO C features is
important because ISO C puts limitations on what names can be defined
by the library implementation, and the GNU extensions don't fit these
limitations.  *Note Reserved Names::, for more information about these
restrictions.

   This manual does not attempt to give you complete details on the
differences between ISO 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.


File: libc.info,  Node: POSIX,  Next: Berkeley Unix,  Prev: ISO C,  Up: Standards and Portability

POSIX (The Portable Operating System Interface)
-----------------------------------------------

   The GNU library is also compatible with the ISO "POSIX" family of
standards, known more formally as the "Portable Operating System
Interface for Computer Environments" (ISO/IEC 9945).  They were also
published as ANSI/IEEE Std 1003.  POSIX is derived mostly from various
versions of the Unix operating system.

   The library facilities specified by the POSIX standards are a
superset of those required by ISO C; POSIX specifies additional
features for ISO C functions, as well as specifying new additional
functions.  In general, the additional requirements and functionality
defined by the POSIX standards 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.

   The GNU C library implements all of the functions specified in
`ISO/IEC 9945-1:1996, the POSIX System Application Program Interface',
commonly referred to as POSIX.1.  The primary extensions to the ISO C
facilities specified by this standard include file system interface
primitives (*note File System Interface::), device-specific terminal
control functions (*note Low-Level Terminal Interface::), and process
control functions (*note Processes::).

   Some facilities from `ISO/IEC 9945-2:1993, the POSIX Shell and
Utilities standard' (POSIX.2) are also implemented in the GNU library.
These include utilities for dealing with regular expressions and other
pattern matching facilities (*note Pattern Matching::).


File: libc.info,  Node: Berkeley Unix,  Next: SVID,  Prev: POSIX,  Up: Standards and Portability

Berkeley Unix
-------------

   The GNU C library defines facilities from some versions of Unix which
are not formally standardized, specifically from the 4.2 BSD, 4.3 BSD,
and 4.4 BSD Unix systems (also known as "Berkeley Unix") and from
"SunOS" (a popular 4.2 BSD derivative that includes some Unix System V
functionality).  These systems support most of the ISO C and POSIX
facilities, and 4.4 BSD and newer releases of SunOS in fact support
them all.

   The BSD facilities include symbolic links (*note Symbolic Links::),
the `select' function (*note Waiting for I/O::), the BSD signal
functions (*note BSD Signal Handling::), and sockets (*note Sockets::).


File: libc.info,  Node: SVID,  Next: XPG,  Prev: Berkeley Unix,  Up: Standards and Portability

SVID (The System V Interface Description)
-----------------------------------------

   The "System V Interface Description" (SVID) is a document describing
the AT&T Unix System V operating system.  It is to some extent a
superset of the POSIX standard (*note POSIX::).

   The GNU C library defines most of the facilities required by the SVID
that are not also required by the ISO C 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.)

   The supported facilities from System V include the methods for
inter-process communication and shared memory, the `hsearch' and
`drand48' families of functions, `fmtmsg' and several of the
mathematical functions.


File: libc.info,  Node: XPG,  Prev: SVID,  Up: Standards and Portability

XPG (The X/Open Portability Guide)
----------------------------------

   The X/Open Portability Guide, published by the X/Open Company, Ltd.,
is a more general standard than POSIX.  X/Open owns the Unix copyright
and the XPG specifies the requirements for systems which are intended
to be a Unix system.

   The GNU C library complies to the X/Open Portability Guide, Issue
4.2, with all extensions common to XSI (X/Open System Interface)
compliant systems and also all X/Open UNIX extensions.

   The additions on top of POSIX are mainly derived from functionality
available in System V and BSD systems.  Some of the really bad mistakes
in System V systems were corrected, though.  Since fulfilling the XPG
standard with the Unix extensions is a precondition for getting the
Unix brand chances are good that the functionality is available on
commercial systems.


File: libc.info,  Node: Using the Library,  Next: Roadmap to the Manual,  Prev: Standards and Portability,  Up: Introduction

Using the Library
=================

   This section describes some of the practical issues involved in using
the GNU C library.

* Menu:

* Header Files::                How to include the header files in your
                                 programs.
* Macro Definitions::           Some functions in the library may really
                                 be implemented as macros.
* Reserved Names::              The C standard reserves some names for
                                 the library, and some for users.
* Feature Test Macros::         How to control what names are defined.


File: libc.info,  Node: Header Files,  Next: Macro Definitions,  Up: Using the Library

Header Files
------------

   Libraries for use by C programs really consist of two parts: "header
files" that define types and macros and declare variables and
functions; and the actual library or "archive" that contains the
definitions of the variables and functions.

   (Recall that in C, a "declaration" 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 "definition", on the other hand, actually allocates storage for a
variable or says what a function does.)

   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.

   Header files are included into a program source file by the
`#include' preprocessor directive.  The C language supports two forms
of this directive; the first,

     #include "HEADER"

is typically used to include a header file HEADER that you write
yourself; this would contain definitions and declarations describing the
interfaces between the different parts of your particular application.
By contrast,

     #include <file.h>

is typically used to include a header file `file.h' 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.

   Typically, `#include' 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 `#include' directives immediately afterwards, following the
feature test macro definition (*note Feature Test Macros::).

   For more information about the use of header files and `#include'
directives, *note Header Files: (cpp.info)Header Files..

   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.

   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.

   *Compatibility Note:* Inclusion of standard header files in any
order and any number of times works in any ISO C implementation.
However, this has traditionally not been the case in many older C
implementations.

   Strictly speaking, you don't _have to_ 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.


File: libc.info,  Node: Macro Definitions,  Next: Reserved Names,  Prev: Header Files,  Up: Using the Library

Macro Definitions of Functions
------------------------------

   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.

   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 a macro call.

   You might occasionally want to avoid using the macro definition of a
function--perhaps to make your program easier to debug.  There are two
ways you can do this:

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

   * You can suppress any macro definition for a whole source file by
     using the `#undef' preprocessor directive, unless otherwise stated
     explicitly in the description of that facility.

   For example, suppose the header file `stdlib.h' declares a function
named `abs' with

     extern int abs (int);

and also provides a macro definition for `abs'.  Then, in:

     #include <stdlib.h>
     int f (int *i) { return abs (++*i); }

the reference to `abs' 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.

     #include <stdlib.h>
     int g (int *i) { return (abs) (++*i); }
     
     #undef abs
     int h (int *i) { return abs (++*i); }

   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.


File: libc.info,  Node: Reserved Names,  Next: Feature Test Macros,  Prev: Macro Definitions,  Up: Using the Library

Reserved Names
--------------

   The names of all library types, macros, variables and functions that
come from the ISO C standard are reserved unconditionally; your program
*may not* redefine these names.  All other library names are reserved
if your program explicitly includes the header file that defines or
declares them.  There are several reasons for these restrictions:

   * Other people reading your code could get very confused if you were
     using a function named `exit' to do something completely different
     from what the standard `exit' function does, for example.
     Preventing this situation helps to make your programs easier to
     understand and contributes to modularity and maintainability.

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

   * 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
     (*note Variadic Functions::) and non-local exits (*note Non-Local
     Exits::), actually require a considerable amount of cooperation on
     the part of the C compiler, and with respect to the
     implementation, it might be easier for the compiler to treat these
     as built-in parts of the language.

   In addition to the names documented in this manual, reserved names
include all external identifiers (global functions and variables) that
begin with an underscore (`_') 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.

   Some additional classes of identifier names are reserved for future
extensions to the C language or the POSIX.1 environment.  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
or POSIX standards, so you should avoid these names.

   * Names beginning with a capital `E' followed a digit or uppercase
     letter may be used for additional error code names.  *Note Error
     Reporting::.

   * Names that begin with either `is' or `to' followed by a lowercase
     letter may be used for additional character testing and conversion
     functions.  *Note Character Handling::.

   * Names that begin with `LC_' followed by an uppercase letter may be
     used for additional macros specifying locale attributes.  *Note
     Locales::.

   * Names of all existing mathematics functions (*note Mathematics::)
     suffixed with `f' or `l' are reserved for corresponding functions
     that operate on `float' and `long double' arguments, respectively.

   * Names that begin with `SIG' followed by an uppercase letter are
     reserved for additional signal names.  *Note Standard Signals::.

   * Names that begin with `SIG_' followed by an uppercase letter are
     reserved for additional signal actions.  *Note Basic Signal
     Handling::.

   * Names beginning with `str', `mem', or `wcs' followed by a
     lowercase letter are reserved for additional string and array
     functions.  *Note String and Array Utilities::.

   * Names that end with `_t' are reserved for additional type names.

   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.

   * The header file `dirent.h' reserves names prefixed with `d_'.

   * The header file `fcntl.h' reserves names prefixed with `l_', `F_',
     `O_', and `S_'.

   * The header file `grp.h' reserves names prefixed with `gr_'.

   * The header file `limits.h' reserves names suffixed with `_MAX'.

   * The header file `pwd.h' reserves names prefixed with `pw_'.

   * The header file `signal.h' reserves names prefixed with `sa_' and
     `SA_'.

   * The header file `sys/stat.h' reserves names prefixed with `st_'
     and `S_'.

   * The header file `sys/times.h' reserves names prefixed with `tms_'.

   * The header file `termios.h' reserves names prefixed with `c_',
     `V', `I', `O', and `TC'; and names prefixed with `B' followed by a
     digit.


File: libc.info,  Node: Feature Test Macros,  Prev: Reserved Names,  Up: Using the Library

Feature Test Macros
-------------------

   The exact set of features available when you compile a source file
is controlled by which "feature test macros" you define.

   If you compile your programs using `gcc -ansi', you get only the
ISO C library features, unless you explicitly request additional
features by defining one or more of the feature macros.  *Note GNU CC
Command Options: (gcc.info)Invoking GCC, for more information about GCC
options.

   You should define these macros by using `#define' preprocessor
directives at the top of your source code files.  These directives
_must_ come before any `#include' of a system header file.  It is best
to make them the very first thing in the file, preceded only by
comments.  You could also use the `-D' option to GCC, but it's better
if you make the source files indicate their own meaning in a
self-contained way.

   This system exists to allow the library to conform to multiple
standards.  Although the different standards are often described as
supersets of each other, they are usually incompatible because larger
standards require functions with names that smaller ones reserve to the
user program.  This is not mere pedantry -- it has been a problem in
practice.  For instance, some non-GNU programs define functions named
`getline' that have nothing to do with this library's `getline'.  They
would not be compilable if all features were enabled indiscriminately.

   This should not be used to verify that a program conforms to a
limited standard.  It is insufficient for this purpose, as it will not
protect you from including header files outside the standard, or
relying on semantics undefined within the standard.

 - Macro: _POSIX_SOURCE
     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
     ISO C facilities.

     The state of `_POSIX_SOURCE' is irrelevant if you define the macro
     `_POSIX_C_SOURCE' to a positive integer.

 - Macro: _POSIX_C_SOURCE
     Define this macro to a positive integer to control which POSIX
     functionality is made available.  The greater the value of this
     macro, the more functionality is made available.

     If you define this macro to a value greater than or equal to `1',
     then the functionality from the 1990 edition of the POSIX.1
     standard (IEEE Standard 1003.1-1990) is made available.

     If you define this macro to a value greater than or equal to `2',
     then the functionality from the 1992 edition of the POSIX.2
     standard (IEEE Standard 1003.2-1992) is made available.

     If you define this macro to a value greater than or equal to
     `199309L', then the functionality from the 1993 edition of the
     POSIX.1b standard (IEEE Standard 1003.1b-1993) is made available.

     Greater values for `_POSIX_C_SOURCE' will enable future extensions.
     The POSIX standards process will define these values as necessary,
     and the GNU C Library should support them some time after they
     become standardized.  The 1996 edition of POSIX.1 (ISO/IEC 9945-1:
     1996) states that if you define `_POSIX_C_SOURCE' to a value
     greater than or equal to `199506L', then the functionality from
     the 1996 edition is made available.

 - Macro: _BSD_SOURCE
     If you define this macro, functionality derived from 4.3 BSD Unix
     is included as well as the ISO C, POSIX.1, and POSIX.2 material.

     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.

     Due to the nature of some of the conflicts between 4.3 BSD and
     POSIX.1, you need to use a special "BSD compatibility library"
     when linking programs compiled for BSD compatibility.  This is
     because some functions must be defined in two different ways, one
     of them in the normal C library, and one of them in the
     compatibility library.  If your program defines `_BSD_SOURCE', you
     must give the option `-lbsd-compat' to the compiler or linker when
     linking the program, to tell it to find functions in this special
     compatibility library before looking for them in the normal C
     library.

 - Macro: _SVID_SOURCE
     If you define this macro, functionality derived from SVID is
     included as well as the ISO C, POSIX.1, POSIX.2, and X/Open
     material.

 - Macro: _XOPEN_SOURCE
 - Macro: _XOPEN_SOURCE_EXTENDED
     If you define this macro, functionality described in the X/Open
     Portability Guide is included.  This is a superset of the POSIX.1
     and POSIX.2 functionality and in fact `_POSIX_SOURCE' and
     `_POSIX_C_SOURCE' are automatically defined.

     As the unification of all Unices, functionality only available in
     BSD and SVID is also included.

     If the macro `_XOPEN_SOURCE_EXTENDED' is also defined, even more
     functionality is available.  The extra functions will make all
     functions available which are necessary for the X/Open Unix brand.

     If the macro `_XOPEN_SOURCE' has the value 500 this includes all
     functionality described so far plus some new definitions from the
     Single Unix Specification, version 2.

 - Macro: _LARGEFILE_SOURCE
     If this macro is defined some extra functions are available which
     rectify a few shortcomings in all previous standards.
     Specifically, the functions `fseeko' and `ftello' are available.
     Without these functions the difference between the ISO C interface
     (`fseek', `ftell') and the low-level POSIX interface (`lseek')
     would lead to problems.

     This macro was introduced as part of the Large File Support
     extension (LFS).

 - Macro: _LARGEFILE64_SOURCE
     If you define this macro an additional set of functions is made
     available which enables 32 bit systems to use files of sizes beyond
     the usual limit of 2GB.  This interface is not available if the
     system does not support files that large.  On systems where the
     natural file size limit is greater than 2GB (i.e., on 64 bit
     systems) the new functions are identical to the replaced functions.

     The new functionality is made available by a new set of types and
     functions which replace the existing ones.  The names of these new
     objects contain `64' to indicate the intention, e.g., `off_t' vs.
     `off64_t' and `fseeko' vs. `fseeko64'.

     This macro was introduced as part of the Large File Support
     extension (LFS).  It is a transition interface for the period when
     64 bit offsets are not generally used (see `_FILE_OFFSET_BITS').

 - Macro: _FILE_OFFSET_BITS
     This macro determines which file system interface shall be used,
     one replacing the other.  Whereas `_LARGEFILE64_SOURCE' makes the
     64 bit interface available as an additional interface,
     `_FILE_OFFSET_BITS' allows the 64 bit interface to replace the old
     interface.

     If `_FILE_OFFSET_BITS' is undefined, or if it is defined to the
     value `32', nothing changes.  The 32 bit interface is used and
     types like `off_t' have a size of 32 bits on 32 bit systems.

     If the macro is defined to the value `64', the large file interface
     replaces the old interface.  I.e., the functions are not made
     available under different names (as they are with
     `_LARGEFILE64_SOURCE').  Instead the old function names now
     reference the new functions, e.g., a call to `fseeko' now indeed
     calls `fseeko64'.

     This macro should only be selected if the system provides
     mechanisms for handling large files.  On 64 bit systems this macro
     has no effect since the `*64' functions are identical to the
     normal functions.

     This macro was introduced as part of the Large File Support
     extension (LFS).

 - Macro: _ISOC99_SOURCE
     Until the revised ISO C standard is widely adopted the new features
     are not automatically enabled.  The GNU libc nevertheless has a
     complete implementation of the new standard and to enable the new
     features the macro `_ISOC99_SOURCE' should be defined.

 - Macro: _GNU_SOURCE
     If you define this macro, everything is included: ISO C89,
     ISO C99, POSIX.1, POSIX.2, BSD, SVID, X/Open, LFS, and GNU
     extensions.  In the cases where POSIX.1 conflicts with BSD, the
     POSIX definitions take precedence.

     If you want to get the full effect of `_GNU_SOURCE' but make the
     BSD definitions take precedence over the POSIX definitions, use
     this sequence of definitions:

          #define _GNU_SOURCE
          #define _BSD_SOURCE
          #define _SVID_SOURCE

     Note that if you do this, you must link your program with the BSD
     compatibility library by passing the `-lbsd-compat' option to the
     compiler or linker.  *Note:* If you forget to do this, you may get
     very strange errors at run time.

 - Macro: _REENTRANT
 - Macro: _THREAD_SAFE
     If you define one of these macros, reentrant versions of several
     functions get declared.  Some of the functions are specified in
     POSIX.1c but many others are only available on a few other systems
     or are unique to GNU libc.  The problem is the delay in the
     standardization of the thread safe C library interface.

     Unlike on some other systems, no special version of the C library
     must be used for linking.  There is only one version but while
     compiling this it must have been specified to compile as thread
     safe.

   We recommend you use `_GNU_SOURCE' in new programs.  If you don't
specify the `-ansi' option to GCC and don't define any of these macros
explicitly, the effect is the same as defining `_POSIX_C_SOURCE' to 2
and `_POSIX_SOURCE', `_SVID_SOURCE', and `_BSD_SOURCE' to 1.

   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
`_POSIX_C_SOURCE', then defining `_POSIX_SOURCE' as well has no effect.
Likewise, if you define `_GNU_SOURCE', then defining either
`_POSIX_SOURCE' or `_POSIX_C_SOURCE' or `_SVID_SOURCE' as well has no
effect.

   Note, however, that the features of `_BSD_SOURCE' 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
`_BSD_SOURCE' 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.


File: libc.info,  Node: Roadmap to the Manual,  Prev: Using the Library,  Up: Introduction

Roadmap to the Manual
=====================

   Here is an overview of the contents of the remaining chapters of
this manual.

   * *Note Error Reporting::, describes how errors detected by the
     library are reported.

   * *Note Language Features::, contains information about library
     support for standard parts of the C language, including things
     like the `sizeof' operator and the symbolic constant `NULL', how
     to write functions accepting variable numbers of arguments, and
     constants describing the ranges and other properties of the
     numerical types.  There is also a simple debugging mechanism which
     allows you to put assertions in your code, and have diagnostic
     messages printed if the tests fail.

   * *Note Memory::, describes the GNU library's facilities for
     managing and using virtual and real memory, including dynamic
     allocation of virtual memory.  If you do not know in advance how
     much memory your program needs, you can allocate it dynamically
     instead, and manipulate it via pointers.

   * *Note Character Handling::, contains information about character
     classification functions (such as `isspace') and functions for
     performing case conversion.

   * *Note String and Array Utilities::, has descriptions of functions
     for manipulating strings (null-terminated character arrays) and
     general byte arrays, including operations such as copying and
     comparison.

   * *Note I/O Overview::, gives an overall look at the input and output
     facilities in the library, and contains information about basic
     concepts such as file names.

   * *Note I/O on Streams::, describes I/O operations involving streams
     (or `FILE *' objects).  These are the normal C library functions
     from `stdio.h'.

   * *Note Low-Level I/O::, contains information about I/O operations
     on file descriptors.  File descriptors are a lower-level mechanism
     specific to the Unix family of operating systems.

   * *Note File System Interface::, 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.

   * *Note Pipes and FIFOs::, 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 on the same machine.

   * *Note Sockets::, 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.

   * *Note Low-Level Terminal Interface::, 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.

   * *Note Mathematics::, 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.

   * *Note Low-Level Arithmetic Functions: Arithmetic, describes
     functions for simple arithmetic, analysis of floating-point
     values, and reading numbers from strings.

   * *Note Searching and Sorting::, 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.

   * *Note Pattern Matching::, presents functions for matching regular
     expressions and shell file name patterns, and for expanding words
     as the shell does.

   * *Note Date and Time::, describes functions for measuring both
     calendar time and CPU time, as well as functions for setting
     alarms and timers.

   * *Note Character Set Handling::, contains information about
     manipulating characters and strings using character sets larger
     than will fit in the usual `char' data type.

   * *Note Locales::, 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.

   * *Note Non-Local Exits::, contains descriptions of the `setjmp' and
     `longjmp' functions.  These functions provide a facility for
     `goto'-like jumps which can jump from one function to another.

   * *Note Signal Handling::, 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.

   * *Note Program Basics::, tells how your programs can access their
     command-line arguments and environment variables.

   * *Note Processes::, contains information about how to start new
     processes and run programs.

   * *Note Job Control::, describes functions for manipulating process
     groups and the controlling terminal.  This material is probably
     only of interest if you are writing a shell or other program which
     handles job control specially.

   * *Note Name Service Switch::, describes the services which are
     available for looking up names in the system databases, how to
     determine which service is used for which database, and how these
     services are implemented so that contributors can design their own
     services.

   * *Note User Database::, and *Note Group Database::, tell you how to
     access the system user and group databases.

   * *Note System Management::, describes functions for controlling and
     getting information about the hardware and software configuration
     your program is executing under.

   * *Note System Configuration::, tells you how you can get
     information about various operating system limits.  Most of these
     parameters are provided for compatibility with POSIX.

   * *Note Library Summary::, gives a summary of all the functions,
     variables, and macros in the library, with complete data types and
     function prototypes, and says what standard or system each is
     derived from.

   * *Note Maintenance::, explains how to build and install the GNU C
     library on your system, how to report any bugs you might find, and
     how to add new functions or port the library to a new system.

   If you already know the name of the facility you are interested in,
you can look it up in *Note Library Summary::.  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.  It also tells you what standard or system each function,
variable, or macro is derived from.


File: libc.info,  Node: Error Reporting,  Next: Memory,  Prev: Introduction,  Up: Top

Error Reporting
***************

   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.

   This chapter describes how the error reporting facility works.  Your
program should include the header file `errno.h' to use this facility.

* Menu:

* Checking for Errors::         How errors are reported by library functions.
* Error Codes::                 Error code macros; all of these expand
                                 into integer constant values.
* Error Messages::              Mapping error codes onto error messages.


File: libc.info,  Node: Checking for Errors,  Next: Error Codes,  Up: Error Reporting

Checking for Errors
===================

   Most library functions return a special value to indicate that they
have failed.  The special value is typically `-1', a null pointer, or a
constant such as `EOF' 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 `errno'.  This variable is declared in the header file
`errno.h'.

 - Variable: volatile int errno
     The variable `errno' contains the system error number.  You can
     change the value of `errno'.

     Since `errno' is declared `volatile', it might be changed
     asynchronously by a signal handler; see *Note Defining Handlers::.
     However, a properly written signal handler saves and restores the
     value of `errno', so you generally do not need to worry about this
     possibility except when writing signal handlers.

     The initial value of `errno' 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 `errno' when they succeed; thus, the value of `errno' after
     a successful call is not necessarily zero, and you should not use
     `errno' to determine _whether_ a call failed.  The proper way to
     do that is documented for each function.  _If_ the call failed,
     you can examine `errno'.

     Many library functions can set `errno' to a nonzero value as a
     result of calling other library functions which might fail.  You
     should assume that any library function might alter `errno' when
     the function returns an error.

     *Portability Note:* ISO C specifies `errno' 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 `*_errno ()'.  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.

     There are a few library functions, like `sqrt' and `atan', that
     return a perfectly legitimate value in case of an error, but also
     set `errno'.  For these functions, if you want to check to see
     whether an error occurred, the recommended method is to set `errno'
     to zero before calling the function, and then check its value
     afterward.

   All the error codes have symbolic names; they are macros defined in
`errno.h'.  The names start with `E' and an upper-case letter or digit;
you should consider names of this form to be reserved names.  *Note
Reserved Names::.

   The error code values are all positive integers and are all distinct,
with one exception: `EWOULDBLOCK' and `EAGAIN' are the same.  Since the
values are distinct, you can use them as labels in a `switch'
statement; just don't use both `EWOULDBLOCK' and `EAGAIN'.  Your
program should not make any other assumptions about the specific values
of these symbolic constants.

   The value of `errno' 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.

   On non-GNU systems, almost any system call can return `EFAULT' 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
`EFAULT' in the descriptions of individual functions.

   In some Unix systems, many system calls can also return `EFAULT' if
given as an argument a pointer into the stack, and the kernel for some
obscure reason fails in its attempt to extend the stack.  If this ever
happens, you should probably try using statically or dynamically
allocated memory instead of stack memory on that system.

