   This file documents the GNU C library.

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

   Copyright (C) 1993 Free Software Foundation, Inc.

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

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

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

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 (see Feature Test Macros.).

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

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

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

   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:

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

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

   The names of all library types, macros, variables and functions that
come from the ANSI C standard are reserved unconditionally; your program
*may not* 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:

   * 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
     (see Variadic Functions.) and non-local exits (see Non-Local Exits.),
     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.

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

   * Names beginning with a capital `E' followed a digit or uppercase
     letter may be used for additional error code names.  See 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.  See Character Handling.

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

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

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

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

   * Names beginning with `str', `mem', or `wcs' followed by a
     lowercase letter are reserved for additional string and array
     functions. See 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.

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
ANSI C library features, unless you explicitly request additional
features by defining one or more of the feature macros. See Options (gcc.info),
for more information about GCC options.

   You should define these macros by using `#define' preprocessor
directives at the top of your source code files.  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.

 -- 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
     ANSI C facilities.

 -- Macro: _POSIX_C_SOURCE
     If you define this macro with a value of `1', then the
     functionality from the POSIX.1 standard (IEEE Standard 1003.1) is
     made available.  If you define this macro with a value of `2',
     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.

 -- Macro: _BSD_SOURCE
     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.

     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.

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

 -- Macro: _GNU_SOURCE
     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.

     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

   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 as the same as defining `_GNU_SOURCE'.

   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.

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

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

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

   * See 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', and
     how to write functions accepting variable numbers of arguments.

   * See Memory Allocation, 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.

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

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

   * See Extended Characters, contains information about
     manipulating characters and strings using character sets larger
     than will fit in the usual `char' data type.

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

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

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

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

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

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

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

   * See 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, such as `/etc/hosts'.

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

   * See Consistency Checking, contains information about a simple
     debugging mechanism.  You can put assertions in your code, and
     diagnostic messages are printed if the test fails.

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

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

   * See Non-Local Exits, contains descriptions of the `setjmp' and
     `longjmp' functions.

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

   * See Child Processes, contains information about how to start
     new processes and run programs.

   * See Process Startup, tells how your programs can access their
     command-line arguments and environment variables.

   * See Job Control, describes functions for manipulating process
     groups. This material is probably only of interest if you are
     writing a shell.

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

   * See System Information, describes functions for getting
     information about the hardware and software configuration your
     program is executing under.

   * See Range of Type, 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.

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

   If you already know the name of the facility you are interested in,
you can look it up in 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.

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.

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

     *Portability Note:* ANSI 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.  See
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.

Error Codes
===========

   The error code macros are defined in the header file `errno.h'. 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.

 -- Macro: int EPERM
     Operation not permitted; only the owner of the file (or other
     resource) or processes with special privileges can perform the
     operation.

 -- Macro: int ENOENT
     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.

 -- Macro: int ESRCH
     No process matches the specified process ID.

 -- Macro: int EINTR
     Interrupted function call; an asynchronous signal occured and
     prevented completion of the call.  When this happens, you should
     try the call again.

     You can choose to have functions resume after a signal that is
     handled, rather than failing with `EINTR'; see Interrupted Primitives.

 -- Macro: int EIO
     Input/output error; usually used for physical read or write errors.

 -- Macro: int ENXIO
     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.

 -- Macro: int E2BIG
     Argument list too long; used when the arguments passed to a new
     program being executed with one of the `exec' functions (see
     Executing a File.) occupy too much memory space.  This condition
     never arises in the GNU system.

 -- Macro: int ENOEXEC
     Invalid executable file format.  This condition is detected by the
     `exec' functions; see Executing a File.

 -- Macro: int EBADF
     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).

 -- Macro: int ECHILD
     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.

 -- Macro: int EDEADLK
     Deadlock avoided; allocating a system resource would have resulted
     in a deadlock situation.  See File Locks, for an example.

 -- Macro: int ENOMEM
     No memory available.  The system cannot allocate more virtual
     memory because its capacity is full.

 -- Macro: int EACCES
     Permission denied; the file permissions do not allow the attempted
     operation.

 -- Macro: int EFAULT
     Bad address; an invalid pointer was detected.

 -- Macro: int ENOTBLK
     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.

 -- Macro: int EBUSY
     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.

 -- Macro: int EEXIST
     File exists; an existing file was specified in a context where it
     only makes sense to specify a new file.

 -- Macro: int EXDEV
     An attempt to make an improper link across file systems was
     detected.

 -- Macro: int ENODEV
     The wrong type of device was given to a function that expects a
     particular sort of device.

 -- Macro: int ENOTDIR
     A file that isn't a directory was specified when a directory is
     required.

 -- Macro: int EISDIR
     File is a directory; attempting to open a directory for writing
     gives this error.

 -- Macro: int EINVAL
     Invalid argument.  This is used to indicate various kinds of
     problems with passing the wrong argument to a library function.

 -- Macro: int ENFILE
     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 Linked Channels.

 -- Macro: int EMFILE
     The current process has too many files open and can't open any
     more. Duplicate descriptors do count toward this limit.

 -- Macro: int ENOTTY
     Inappropriate I/O control operation, such as trying to set terminal
     modes on an ordinary file.

 -- Macro: int ETXTBSY
     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.

 -- Macro: int EFBIG
     File too big; the size of a file would be larger than allowed by
     the system.

 -- Macro: int ENOSPC
     No space left on device; write operation on a file failed because
     the disk is full.

 -- Macro: int ESPIPE
     Invalid seek operation (such as on a pipe).

 -- Macro: int EROFS
     An attempt was made to modify a file on a read-only file system.

 -- Macro: int EMLINK
     Too many links; the link count of a single file is too large.

 -- Macro: int EPIPE
     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 `SIGPIPE' signal; this signal terminates the program
     if not handled or blocked.  Thus, your program will never actually
     see `EPIPE' unless it has handled or blocked `SIGPIPE'.

 -- Macro: int EDOM
     Domain error; used by mathematical functions when an argument
     value does not fall into the domain over which the function is
     defined.

 -- Macro: int ERANGE
     Range error; used by mathematical functions when the result value
     is not representable because of overflow or underflow.

 -- Macro: int EAGAIN
     Resource temporarily unavailable; the call might work if you try
     again later.  Only `fork' returns error code `EAGAIN' for such a
     reason.

 -- Macro: int EWOULDBLOCK
     An operation that would block was attempted on an object that has
     non-blocking mode selected.

     *Portability Note:* In 4.4BSD and GNU, `EWOULDBLOCK' and `EAGAIN'
     are the same.  Earlier versions of BSD (see Berkeley Unix.)
     have two distinct codes, and use `EWOULDBLOCK' to indicate an I/O
     operation that would block on an object with non-blocking mode
     set, and `EAGAIN' for other kinds of errors.

 -- Macro: int EINPROGRESS
     An operation that cannot complete immediately was initiated on an
     object that has non-blocking mode selected.

 -- Macro: int EALREADY
     An operation is already in progress on an object that has
     non-blocking mode selected.

 -- Macro: int ENOTSOCK
     A file that isn't a socket was specified when a socket is required.

 -- Macro: int EDESTADDRREQ
     No destination address was supplied on a socket operation.

 -- Macro: int EMSGSIZE
     The size of a message sent on a socket was larger than the
     supported maximum size.

 -- Macro: int EPROTOTYPE
     The socket type does not support the requested communications
     protocol.

 -- Macro: int ENOPROTOOPT
     You specified a socket option that doesn't make sense for the
     particular protocol being used by the socket.  See Socket Options.

 -- Macro: int EPROTONOSUPPORT
     The socket domain does not support the requested communications
     protocol. See Creating a Socket.

 -- Macro: int ESOCKTNOSUPPORT
     The socket type is not supported.

 -- Macro: int EOPNOTSUPP
     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.

 -- Macro: int EPFNOSUPPORT
     The socket communications protocol family you requested is not
     supported.

 -- Macro: int EAFNOSUPPORT
     The address family specified for a socket is not supported; it is
     inconsistent with the protocol being used on the socket.  See
     Sockets.

 -- Macro: int EADDRINUSE
     The requested socket address is already in use.  See Socket Addresses.

 -- Macro: int EADDRNOTAVAIL
     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 Socket Addresses.

 -- Macro: int ENETDOWN
     A socket operation failed because the network was down.

 -- Macro: int ENETUNREACH
     A socket operation failed because the subnet containing the remost
     host was unreachable.

 -- Macro: int ENETRESET
     A network connection was reset because the remote host crashed.

 -- Macro: int ECONNABORTED
     A network connection was aborted locally.

 -- Macro: int ECONNRESET
     A network connection was closed for reasons outside the control of
     the local host, such as by the remote machine rebooting.

 -- Macro: int ENOBUFS
     The kernel's buffers for I/O operations are all in use.

 -- Macro: int EISCONN
     You tried to connect a socket that is already connected. See
     Connecting.

 -- Macro: int ENOTCONN
     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.

 -- Macro: int ESHUTDOWN
     The socket has already been shut down.

 -- Macro: int ETIMEDOUT
     A socket operation with a specified timeout received no response
     during the timeout period.

 -- Macro: int ECONNREFUSED
     A remote host refused to allow the network connection (typically
     because it is not running the requested service).

 -- Macro: int ELOOP
     Too many levels of symbolic links were encountered in looking up a
     file name. This often indicates a cycle of symbolic links.

 -- Macro: int ENAMETOOLONG
     Filename too long (longer than `PATH_MAX'; see Limits for Files.)
     or host name too long (in `gethostname' or
     `sethostname'; see Host Identification.).

 -- Macro: int EHOSTDOWN
     The remote host for a requested network connection is down.

 -- Macro: int EHOSTUNREACH
     The remote host for a requested network connection is not
     reachable.

 -- Macro: int ENOTEMPTY
     Directory not empty, where an empty directory was expected.
     Typically, this error occurs when you are trying to delete a
     directory.

 -- Macro: int EUSERS
     The file quota system is confused because there are too many users.

 -- Macro: int EDQUOT
     The user's disk quota was exceeded.

 -- Macro: int ESTALE
     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.

 -- Macro: int EREMOTE
     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.)

 -- Macro: int ENOLCK
     No locks available.  This is used by the file locking facilities;
     see File Locks.

 -- Macro: int ENOSYS
     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.

 -- Macro: int ED
     The experienced user will know what is wrong.

 -- Macro: int EGRATUITOUS
     This error code has no purpose.

Error Messages
==============

   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 `strerror'
and `perror' give you the standard error message for a given error
code; the variable `program_invocation_short_name' gives you convenient
access to the name of the program that encountered the error.

 -- Function: char * strerror (int ERRNUM)
     The `strerror' function maps the error code (see Checking for Errors.)
     specified by the ERRNUM argument to a descriptive error
     message string.  The return value is a pointer to this string.

     The value ERRNUM normally comes from the variable `errno'.

     You should not modify the string returned by `strerror'.  Also, if
     you make subsequent calls to `strerror', the string might be
     overwritten.  (But it's guaranteed that no library function ever
     calls `strerror' behind your back.)

     The function `strerror' is declared in `string.h'.

 -- Function: void perror (const char *MESSAGE)
     This function prints an error message to the stream `stderr'; see
     Standard Streams.

     If you call `perror' with a MESSAGE that is either a null pointer
     or an empty string, `perror' just prints the error message
     corresponding to `errno', adding a trailing newline.

     If you supply a non-null MESSAGE argument, then `perror' prefixes
     its output with this string.  It adds a colon and a space
     character to separate the MESSAGE from the error string
     corresponding to `errno'.

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

   `strerror' and `perror' 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.

   *Compatibility Note:*  The `strerror' function is a new feature of
ANSI C.  Many older C systems do not support this function yet.

   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 `program_invocation_short_name';
the full file name is stored the variable `program_invocation_name':

 -- Variable: char * program_invocation_name
     This variable's value is the name that was used to invoke the
     program running in the current process.  It is the same as
     `argv[0]'.

 -- Variable: char * program_invocation_short_name
     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
     `program_invocation_name' minus everything up to the last slash,
     if any.)

   Both `program_invocation_name' and `program_invocation_short_name'
are set up by the system before `main' is called.

   *Portability Note:* These two variables are GNU extensions.  If you
want your program to work with non-GNU libraries, you must save the
value of `argv[0]' in `main', 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 `main'.

   Here is an example showing how to handle failure to open a file
correctly.  The function `open_sesame' tries to open the named file for
reading and returns a stream if successful.  The `fopen' library
function returns a null pointer if it couldn't open the file for some
reason.  In that situation, `open_sesame' constructs an appropriate
error message using the `strerror' function, and terminates the
program.  If we were going to make some other library calls before
passing the error code to `strerror', we'd have to save it in a local
variable instead, because those other library functions might overwrite
`errno' in the meantime.

     #include <errno.h>
     #include <stdio.h>
     #include <stdlib.h>
     #include <string.h>

     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;
     }

Memory Allocation
*****************

   The GNU system provides several methods for allocating memory space
under explicit program control.  They vary in generality and in
efficiency.

Dynamic Memory Allocation Concepts
==================================

   "Dynamic memory allocation" 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.

   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.

   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.

   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.

Dynamic Allocation and C
========================

   The C language supports two kinds of memory allocation through the
variables in C programs:

   * "Static allocation" 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.

   * "Automatic allocation" 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.

     In GNU C, the length of the automatic storage can be an expression
     that varies.  In other C implementations, it must be a constant.

   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.

   For example, if you want to allocate dynamically some space to hold a
`struct foobar', you cannot declare a variable of type `struct foobar'
whose contents are the dynamically allocated space.  But you can
declare a variable of pointer type `struct foobar *' and assign it the
address of the space.  Then you can use the operators `*' and `->' on
this pointer variable to refer to the contents of the space:

     {
       struct foobar *ptr
          = (struct foobar *) malloc (sizeof (struct foobar));
       ptr->name = x;
       ptr->next = current_foobar;
       current_foobar = ptr;
     }

Unconstrained Allocation
========================

   The most general dynamic allocation facility is `malloc'.  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).

Basic Storage Allocation
------------------------

   To allocate a block of memory, call `malloc'.  The prototype for
this function is in `stdlib.h'.

 -- Function: void * malloc (size_t SIZE)
     This function returns a pointer to a newly allocated block SIZE
     bytes long, or a null pointer if the block could not be allocated.

   The contents of the block are undefined; you must initialize it
yourself (or use `calloc' instead; see Allocating Cleared Space.).
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
`memset' (see Copying and Concatenation.):

     struct foo *ptr;
     ...
     ptr = (struct foo *) malloc (sizeof (struct foo));
     if (ptr == 0) abort ();
     memset (ptr, 0, sizeof (struct foo));

   You can store the result of `malloc' into any pointer variable
without a cast, because ANSI C automatically converts the type `void *'
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.

   Remember that when allocating space for a string, the argument to
`malloc' 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:

     char *ptr;
     ...
     ptr = (char *) malloc (length + 1);

See Representation of Strings, for more information about this.