This is libc.info, produced by makeinfo version 4.0 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.09 DRAFT, last updated 28 Aug 1999, of `The GNU C
Library Reference Manual', for Version 2.2 Beta.

   Copyright (C) 1993, '94, '95, '96, '97, '98, '99 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 translation of the section
entitled "GNU Library General Public License" must be approved for
accuracy by the Foundation.


File: libc.info,  Node: Traditional Scheduling Functions,  Prev: Traditional Scheduling Intro,  Up: Traditional Scheduling

Functions For Traditional Scheduling
....................................

   This section describes how you can read and set the nice value of a
process.  All these symbols are declared in `sys/resource.h'.

   The function and macro names are defined by POSIX, and refer to
"priority," but the functions actually have to do with nice values, as
the terms are used both in the manual and POSIX.

   The range of valid nice values depends on the kernel, but typically
it runs from `-20' to `20'.  A lower nice value corresponds to higher
priority for the process.  These constants describe the range of
priority values:

`PRIO_MIN'
     The lowest valid nice value.

`PRIO_MAX'
     The highest valid nice value.

 - Function: int getpriority (int CLASS, int ID)
     Return the nice value of a set of processes; CLASS and ID specify
     which ones (see below).  If the processes specified do not all
     have the same nice value, this returns the lowest value that any
     of them has.

     On success, the return value is `0'.  Otherwise, it is `-1' and
     `ERRNO' is set accordingly.  The `errno' values specific to this
     function are:

    `ESRCH'
          The combination of CLASS and ID does not match any existing
          process.

    `EINVAL'
          The value of CLASS is not valid.

     If the return value is `-1', it could indicate failure, or it could
     be the nice value.  The only way to make certain is to set `errno =
     0' before calling `getpriority', then use `errno != 0' afterward
     as the criterion for failure.

 - Function: int setpriority (int CLASS, int ID, int NICEVAL)
     Set the nice value of a set of processes to NICEVAL; CLASS and ID
     specify which ones (see below).

     The return value is the nice value on success, and `-1' on
     failure.  The following `errno' error condition are possible for
     this function:

    `ESRCH'
          The combination of CLASS and ID does not match any existing
          process.

    `EINVAL'
          The value of CLASS is not valid.

    `EPERM'
          The call would set the nice value of a process which is owned
          by a different user than the calling process (i.e. the target
          process' real or effective uid does not match the calling
          process' effective uid) and the calling process does not have
          `CAP_SYS_NICE' permission.

    `EACCES'
          The call would lower the process' nice value and the process
          does not have `CAP_SYS_NICE' permission.


   The arguments CLASS and ID together specify a set of processes in
which you are interested.  These are the possible values of CLASS:

`PRIO_PROCESS'
     One particular process.  The argument ID is a process ID (pid).

`PRIO_PGRP'
     All the processes in a particular process group.  The argument ID
     is a process group ID (pgid).

`PRIO_USER'
     All the processes owned by a particular user (i.e. whose real uid
     indicates the user).  The argument ID is a user ID (uid).

   If the argument ID is 0, it stands for the calling process, its
process group, or its owner (real uid), according to CLASS.

 - Function: int nice (int INCREMENT)
     Increment the nice value of the calling process by INCREMENT.  The
     return value is the same as for `setpriority'.

     Here is an equivalent definition of `nice':

          int
          nice (int increment)
          {
            int old = getpriority (PRIO_PROCESS, 0);
            return setpriority (PRIO_PROCESS, 0, old + increment);
          }


File: libc.info,  Node: Memory Resources,  Next: Processor Resources,  Prev: Priority,  Up: Resource Usage And Limitation

Querying memory available resources
===================================

   The amount of memory available in the system and the way it is
organized determines oftentimes the way programs can and have to work.
For functions like `mmap' it is necessary to know about the size of
individual memory pages and knowing how much memory is available enables
a program to select appropriate sizes for, say, caches.  Before we get
into these details a few words about memory subsystems in traditional
Unix systems will be given.

* Menu:

* Memory Subsystem::           Overview about traditional Unix memory handling.
* Query Memory Parameters::    How to get information about the memory
                                subsystem?


File: libc.info,  Node: Memory Subsystem,  Next: Query Memory Parameters,  Up: Memory Resources

Overview about traditional Unix memory handling
-----------------------------------------------

   Unix systems normally provide processes virtual address spaces.  This
means that the addresses of the memory regions do not have to correspond
directly to the addresses of the actual physical memory which stores the
data.  An extra level of indirection is introduced which translates
virtual addresses into physical addresses.  This is normally done by the
hardware of the processor.

   Using a virtual address space has several advantage.  The most
important is process isolation.  The different processes running on the
system cannot interfere directly with each other.  No process can write
into the address space of another process (except when shared memory is
used but then it is wanted and controlled).

   Another advantage of virtual memory is that the address space the
processes see can actually be larger than the physical memory available.
The physical memory can be extended by storage on an external media
where the content of currently unused memory regions is stored.  The
address translation can then intercept accesses to these memory regions
and make memory content available again by loading the data back into
memory.  This concept makes it necessary that programs which have to use
lots of memory know the difference between available virtual address
space and available physical memory.  If the working set of virtual
memory of all the processes is larger than the available physical memory
the system will slow down dramatically due to constant swapping of
memory content from the memory to the storage media and back.  This is
called "thrashing".

   A final aspect of virtual memory which is important and follows from
what is said in the last paragraph is the granularity of the virtual
address space handling.  When we said that the virtual address handling
stores memory content externally it cannot do this on a byte-by-byte
basis.  The administrative overhead does not allow this (leaving alone
the processor hardware).  Instead several thousand bytes are handled
together and form a "page".  The size of each page is always a power of
two byte.  The smallest page size in use today is 4096, with 8192,
16384, and 65536 being other popular sizes.


File: libc.info,  Node: Query Memory Parameters,  Prev: Memory Subsystem,  Up: Memory Resources

How to get information about the memory subsystem?
--------------------------------------------------

   The page size of the virtual memory the process sees is essential to
know in several situations.  Some programming interface (e.g., `mmap',
*note Memory-mapped I/O::) require the user to provide information
adjusted to the page size.  In the case of `mmap' is it necessary to
provide a length argument which is a multiple of the page size.
Another place where the knowledge about the page size is useful is in
memory allocation.  If one allocates pieces of memory in larger chunks
which are then subdivided by the application code it is useful to
adjust the size of the larger blocks to the page size.  If the total
memory requirement for the block is close (but not larger) to a multiple
of the page size the kernel's memory handling can work more effectively
since it only has to allocate memory pages which are fully used.  (To do
this optimization it is necessary to know a bit about the memory
allocator which will require a bit of memory itself for each block and
this overhead must not push the total size over the page size multiple.

   The page size traditionally was a compile time constant.  But recent
development of processors changed this.  Processors now support
different page sizes and they can possibly even vary among different
processes on the same system.  Therefore the system should be queried at
runtime about the current page size and no assumptions (except about it
being a power of two) should be made.

   The correct interface to query about the page size is `sysconf'
(*note Sysconf Definition::) with the parameter `_SC_PAGESIZE'.  There
is a much older interface available, too.

 - Function: int getpagesize (void)
     The `getpagesize' function returns the page size of the process.
     This value is fixed for the runtime of the process but can vary in
     different runs of the application.

     The function is declared in `unistd.h'.

   Widely available on System V derived systems is a method to get
information about the physical memory the system has.  The call

       sysconf (_SC_PHYS_PAGES)

returns the total number of pages of physical the system has.  This
does not mean all this memory is available.  This information can be
found using

       sysconf (_SC_AVPHYS_PAGES)

   These two values help to optimize applications.  The value returned
for `_SC_AVPHYS_PAGES' is the amount of memory the application can use
without hindering any other process (given that no other process
increases its memory usage).  The value returned for `_SC_PHYS_PAGES'
is more or less a hard limit for the working set.  If all applications
together constantly use more than that amount of memory the system is
in trouble.

   The GNU C library provides in addition to these already described
way to get this information two functions.  They are declared in the
file `sys/sysinfo.h'.  Programmers should prefer to use the `sysconf'
method described above.

 - Function: long int get_phys_pages (void)
     The `get_phys_pages' function returns the total number of pages of
     physical the system has.  To get the amount of memory this number
     has to be multiplied by the page size.

     This function is a GNU extension.

 - Function: long int get_avphys_pages (void)
     The `get_phys_pages' function returns the number of available
     pages of physical the system has.  To get the amount of memory
     this number has to be multiplied by the page size.

     This function is a GNU extension.


File: libc.info,  Node: Processor Resources,  Prev: Memory Resources,  Up: Resource Usage And Limitation

Learn about the processors available
====================================

   The use of threads or processes with shared memory allows an
application to take advantage of all the processing power a system can
provide.  If the task can be parallelized the optimal way to write an
application is to have at any time as many processes running as there
are processors.  To determine the number of processors available to the
system one can run

       sysconf (_SC_NPROCESSORS_CONF)

which returns the number of processors the operating system configured.
But it might be possible for the operating system to disable individual
processors and so the call

       sysconf (_SC_NPROCESSORS_ONLN)

returns the number of processors which are currently inline (i.e.,
available).

   For these two pieces of information the GNU C library also provides
functions to get the information directly.  The functions are declared
in `sys/sysinfo.h'.

 - Function: int get_nprocs_conf (void)
     The `get_nprocs_conf' function returns the number of processors the
     operating system configured.

     This function is a GNU extension.

 - Function: int get_nprocs (void)
     The `get_nprocs' function returns the number of available
     processors.

     This function is a GNU extension.

   Before starting more threads it should be checked whether the
processors are not already overused.  Unix systems calculate something
called the "load average".  This is a number indicating how many
processes were running.  This number is average over different periods
of times (normally 1, 5, and 15 minutes).

 - Function: int getloadavg (double LOADAVG[], int NELEM)
     This function gets the 1, 5 and 15 minute load averages of the
     system. The values are placed in LOADAVG.  `getloadavg' will place
     at most NELEM elements into the array but never more than three
     elements.  The return value is the number of elements written to
     LOADAVG, or -1 on error.

     This function is declared in `stdlib.h'.


File: libc.info,  Node: Non-Local Exits,  Next: Signal Handling,  Prev: Resource Usage And Limitation,  Up: Top

Non-Local Exits
***************

   Sometimes when your program detects an unusual situation inside a
deeply nested set of function calls, you would like to be able to
immediately return to an outer level of control.  This section
describes how you can do such "non-local exits" using the `setjmp' and
`longjmp' functions.

* Menu:

* Intro: Non-Local Intro.        When and how to use these facilities.
* Details: Non-Local Details.   Functions for non-local exits.
* Non-Local Exits and Signals::  Portability issues.


File: libc.info,  Node: Non-Local Intro,  Next: Non-Local Details,  Up: Non-Local Exits

Introduction to Non-Local Exits
===============================

   As an example of a situation where a non-local exit can be useful,
suppose you have an interactive program that has a "main loop" that
prompts for and executes commands.  Suppose the "read" command reads
input from a file, doing some lexical analysis and parsing of the input
while processing it.  If a low-level input error is detected, it would
be useful to be able to return immediately to the "main loop" instead
of having to make each of the lexical analysis, parsing, and processing
phases all have to explicitly deal with error situations initially
detected by nested calls.

   (On the other hand, if each of these phases has to do a substantial
amount of cleanup when it exits--such as closing files, deallocating
buffers or other data structures, and the like--then it can be more
appropriate to do a normal return and have each phase do its own
cleanup, because a non-local exit would bypass the intervening phases
and their associated cleanup code entirely.  Alternatively, you could
use a non-local exit but do the cleanup explicitly either before or
after returning to the "main loop".)

   In some ways, a non-local exit is similar to using the `return'
statement to return from a function.  But while `return' abandons only
a single function call, transferring control back to the point at which
it was called, a non-local exit can potentially abandon many levels of
nested function calls.

   You identify return points for non-local exits by calling the
function `setjmp'.  This function saves information about the execution
environment in which the call to `setjmp' appears in an object of type
`jmp_buf'.  Execution of the program continues normally after the call
to `setjmp', but if an exit is later made to this return point by
calling `longjmp' with the corresponding `jmp_buf' object, control is
transferred back to the point where `setjmp' was called.  The return
value from `setjmp' is used to distinguish between an ordinary return
and a return made by a call to `longjmp', so calls to `setjmp' usually
appear in an `if' statement.

   Here is how the example program described above might be set up:

     #include <setjmp.h>
     #include <stdlib.h>
     #include <stdio.h>
     
     jmp_buf main_loop;
     
     void
     abort_to_main_loop (int status)
     {
       longjmp (main_loop, status);
     }
     
     int
     main (void)
     {
       while (1)
         if (setjmp (main_loop))
           puts ("Back at main loop....");
         else
           do_command ();
     }
     
     
     void
     do_command (void)
     {
       char buffer[128];
       if (fgets (buffer, 128, stdin) == NULL)
         abort_to_main_loop (-1);
       else
         exit (EXIT_SUCCESS);
     }

   The function `abort_to_main_loop' causes an immediate transfer of
control back to the main loop of the program, no matter where it is
called from.

   The flow of control inside the `main' function may appear a little
mysterious at first, but it is actually a common idiom with `setjmp'.
A normal call to `setjmp' returns zero, so the "else" clause of the
conditional is executed.  If `abort_to_main_loop' is called somewhere
within the execution of `do_command', then it actually appears as if
the _same_ call to `setjmp' in `main' were returning a second time with
a value of `-1'.

   So, the general pattern for using `setjmp' looks something like:

     if (setjmp (BUFFER))
       /* Code to clean up after premature return. */
       ...
     else
       /* Code to be executed normally after setting up the return point. */
       ...


File: libc.info,  Node: Non-Local Details,  Next: Non-Local Exits and Signals,  Prev: Non-Local Intro,  Up: Non-Local Exits

Details of Non-Local Exits
==========================

   Here are the details on the functions and data structures used for
performing non-local exits.  These facilities are declared in
`setjmp.h'.

 - Data Type: jmp_buf
     Objects of type `jmp_buf' hold the state information to be
     restored by a non-local exit.  The contents of a `jmp_buf'
     identify a specific place to return to.

 - Macro: int setjmp (jmp_buf STATE)
     When called normally, `setjmp' stores information about the
     execution state of the program in STATE and returns zero.  If
     `longjmp' is later used to perform a non-local exit to this STATE,
     `setjmp' returns a nonzero value.

 - Function: void longjmp (jmp_buf STATE, int VALUE)
     This function restores current execution to the state saved in
     STATE, and continues execution from the call to `setjmp' that
     established that return point.  Returning from `setjmp' by means of
     `longjmp' returns the VALUE argument that was passed to `longjmp',
     rather than `0'.  (But if VALUE is given as `0', `setjmp' returns
     `1').

   There are a lot of obscure but important restrictions on the use of
`setjmp' and `longjmp'.  Most of these restrictions are present because
non-local exits require a fair amount of magic on the part of the C
compiler and can interact with other parts of the language in strange
ways.

   The `setjmp' function is actually a macro without an actual function
definition, so you shouldn't try to `#undef' it or take its address.
In addition, calls to `setjmp' are safe in only the following contexts:

   * As the test expression of a selection or iteration statement (such
     as `if', `switch', or `while').

   * As one operand of a equality or comparison operator that appears
     as the test expression of a selection or iteration statement.  The
     other operand must be an integer constant expression.

   * As the operand of a unary `!' operator, that appears as the test
     expression of a selection or iteration statement.

   * By itself as an expression statement.

   Return points are valid only during the dynamic extent of the
function that called `setjmp' to establish them.  If you `longjmp' to a
return point that was established in a function that has already
returned, unpredictable and disastrous things are likely to happen.

   You should use a nonzero VALUE argument to `longjmp'.  While
`longjmp' refuses to pass back a zero argument as the return value from
`setjmp', this is intended as a safety net against accidental misuse
and is not really good programming style.

   When you perform a non-local exit, accessible objects generally
retain whatever values they had at the time `longjmp' was called.  The
exception is that the values of automatic variables local to the
function containing the `setjmp' call that have been changed since the
call to `setjmp' are indeterminate, unless you have declared them
`volatile'.


File: libc.info,  Node: Non-Local Exits and Signals,  Prev: Non-Local Details,  Up: Non-Local Exits

Non-Local Exits and Signals
===========================

   In BSD Unix systems, `setjmp' and `longjmp' also save and restore
the set of blocked signals; see *Note Blocking Signals::.  However, the
POSIX.1 standard requires `setjmp' and `longjmp' not to change the set
of blocked signals, and provides an additional pair of functions
(`sigsetjmp' and `siglongjmp') to get the BSD behavior.

   The behavior of `setjmp' and `longjmp' in the GNU library is
controlled by feature test macros; see *Note Feature Test Macros::.  The
default in the GNU system is the POSIX.1 behavior rather than the BSD
behavior.

   The facilities in this section are declared in the header file
`setjmp.h'.

 - Data Type: sigjmp_buf
     This is similar to `jmp_buf', except that it can also store state
     information about the set of blocked signals.

 - Function: int sigsetjmp (sigjmp_buf STATE, int SAVESIGS)
     This is similar to `setjmp'.  If SAVESIGS is nonzero, the set of
     blocked signals is saved in STATE and will be restored if a
     `siglongjmp' is later performed with this STATE.

 - Function: void siglongjmp (sigjmp_buf STATE, int VALUE)
     This is similar to `longjmp' except for the type of its STATE
     argument.  If the `sigsetjmp' call that set this STATE used a
     nonzero SAVESIGS flag, `siglongjmp' also restores the set of
     blocked signals.


File: libc.info,  Node: Signal Handling,  Next: Program Basics,  Prev: Non-Local Exits,  Up: Top

Signal Handling
***************

   A "signal" is a software interrupt delivered to a process.  The
operating system uses signals to report exceptional situations to an
executing program.  Some signals report errors such as references to
invalid memory addresses; others report asynchronous events, such as
disconnection of a phone line.

   The GNU C library defines a variety of signal types, each for a
particular kind of event.  Some kinds of events make it inadvisable or
impossible for the program to proceed as usual, and the corresponding
signals normally abort the program.  Other kinds of signals that report
harmless events are ignored by default.

   If you anticipate an event that causes signals, you can define a
handler function and tell the operating system to run it when that
particular type of signal arrives.

   Finally, one process can send a signal to another process; this
allows a parent process to abort a child, or two related processes to
communicate and synchronize.

* Menu:

* Concepts of Signals::         Introduction to the signal facilities.
* Standard Signals::            Particular kinds of signals with
                                 standard names and meanings.
* Signal Actions::              Specifying what happens when a
                                 particular signal is delivered.
* Defining Handlers::           How to write a signal handler function.
* Interrupted Primitives::	Signal handlers affect use of `open',
				 `read', `write' and other functions.
* Generating Signals::          How to send a signal to a process.
* Blocking Signals::            Making the system hold signals temporarily.
* Waiting for a Signal::        Suspending your program until a signal
                                 arrives.
* Signal Stack::                Using a Separate Signal Stack.
* BSD Signal Handling::         Additional functions for backward
			         compatibility with BSD.


File: libc.info,  Node: Concepts of Signals,  Next: Standard Signals,  Up: Signal Handling

Basic Concepts of Signals
=========================

   This section explains basic concepts of how signals are generated,
what happens after a signal is delivered, and how programs can handle
signals.

* Menu:

* Kinds of Signals::            Some examples of what can cause a signal.
* Signal Generation::           Concepts of why and how signals occur.
* Delivery of Signal::          Concepts of what a signal does to the
                                 process.


File: libc.info,  Node: Kinds of Signals,  Next: Signal Generation,  Up: Concepts of Signals

Some Kinds of Signals
---------------------

   A signal reports the occurrence of an exceptional event.  These are
some of the events that can cause (or "generate", or "raise") a signal:

   * A program error such as dividing by zero or issuing an address
     outside the valid range.

   * A user request to interrupt or terminate the program.  Most
     environments are set up to let a user suspend the program by
     typing `C-z', or terminate it with `C-c'.  Whatever key sequence
     is used, the operating system sends the proper signal to interrupt
     the process.

   * The termination of a child process.

   * Expiration of a timer or alarm.

   * A call to `kill' or `raise' by the same process.

   * A call to `kill' from another process.  Signals are a limited but
     useful form of interprocess communication.

   * An attempt to perform an I/O operation that cannot be done.
     Examples are reading from a pipe that has no writer (*note Pipes
     and FIFOs::), and reading or writing to a terminal in certain
     situations (*note Job Control::).

   Each of these kinds of events (excepting explicit calls to `kill'
and `raise') generates its own particular kind of signal.  The various
kinds of signals are listed and described in detail in *Note Standard
Signals::.


File: libc.info,  Node: Signal Generation,  Next: Delivery of Signal,  Prev: Kinds of Signals,  Up: Concepts of Signals

Concepts of Signal Generation
-----------------------------

   In general, the events that generate signals fall into three major
categories: errors, external events, and explicit requests.

   An error means that a program has done something invalid and cannot
continue execution.  But not all kinds of errors generate signals--in
fact, most do not.  For example, opening a nonexistent file is an error,
but it does not raise a signal; instead, `open' returns `-1'.  In
general, errors that are necessarily associated with certain library
functions are reported by returning a value that indicates an error.
The errors which raise signals are those which can happen anywhere in
the program, not just in library calls.  These include division by zero
and invalid memory addresses.

   An external event generally has to do with I/O or other processes.
These include the arrival of input, the expiration of a timer, and the
termination of a child process.

   An explicit request means the use of a library function such as
`kill' whose purpose is specifically to generate a signal.

   Signals may be generated "synchronously" or "asynchronously".  A
synchronous signal pertains to a specific action in the program, and is
delivered (unless blocked) during that action.  Most errors generate
signals synchronously, and so do explicit requests by a process to
generate a signal for that same process.  On some machines, certain
kinds of hardware errors (usually floating-point exceptions) are not
reported completely synchronously, but may arrive a few instructions
later.

   Asynchronous signals are generated by events outside the control of
the process that receives them.  These signals arrive at unpredictable
times during execution.  External events generate signals
asynchronously, and so do explicit requests that apply to some other
process.

   A given type of signal is either typically synchronous or typically
asynchronous.  For example, signals for errors are typically synchronous
because errors generate signals synchronously.  But any type of signal
can be generated synchronously or asynchronously with an explicit
request.


File: libc.info,  Node: Delivery of Signal,  Prev: Signal Generation,  Up: Concepts of Signals

How Signals Are Delivered
-------------------------

   When a signal is generated, it becomes "pending".  Normally it
remains pending for just a short period of time and then is "delivered"
to the process that was signaled.  However, if that kind of signal is
currently "blocked", it may remain pending indefinitely--until signals
of that kind are "unblocked".  Once unblocked, it will be delivered
immediately.  *Note Blocking Signals::.

   When the signal is delivered, whether right away or after a long
delay, the "specified action" for that signal is taken.  For certain
signals, such as `SIGKILL' and `SIGSTOP', the action is fixed, but for
most signals, the program has a choice: ignore the signal, specify a
"handler function", or accept the "default action" for that kind of
signal.  The program specifies its choice using functions such as
`signal' or `sigaction' (*note Signal Actions::).  We sometimes say
that a handler "catches" the signal.  While the handler is running,
that particular signal is normally blocked.

   If the specified action for a kind of signal is to ignore it, then
any such signal which is generated is discarded immediately.  This
happens even if the signal is also blocked at the time.  A signal
discarded in this way will never be delivered, not even if the program
subsequently specifies a different action for that kind of signal and
then unblocks it.

   If a signal arrives which the program has neither handled nor
ignored, its "default action" takes place.  Each kind of signal has its
own default action, documented below (*note Standard Signals::).  For
most kinds of signals, the default action is to terminate the process.
For certain kinds of signals that represent "harmless" events, the
default action is to do nothing.

   When a signal terminates a process, its parent process can determine
the cause of termination by examining the termination status code
reported by the `wait' or `waitpid' functions.  (This is discussed in
more detail in *Note Process Completion::.)  The information it can get
includes the fact that termination was due to a signal and the kind of
signal involved.  If a program you run from a shell is terminated by a
signal, the shell typically prints some kind of error message.

   The signals that normally represent program errors have a special
property: when one of these signals terminates the process, it also
writes a "core dump file" which records the state of the process at the
time of termination.  You can examine the core dump with a debugger to
investigate what caused the error.

   If you raise a "program error" signal by explicit request, and this
terminates the process, it makes a core dump file just as if the signal
had been due directly to an error.


File: libc.info,  Node: Standard Signals,  Next: Signal Actions,  Prev: Concepts of Signals,  Up: Signal Handling

Standard Signals
================

   This section lists the names for various standard kinds of signals
and describes what kind of event they mean.  Each signal name is a macro
which stands for a positive integer--the "signal number" for that kind
of signal.  Your programs should never make assumptions about the
numeric code for a particular kind of signal, but rather refer to them
always by the names defined here.  This is because the number for a
given kind of signal can vary from system to system, but the meanings of
the names are standardized and fairly uniform.

   The signal names are defined in the header file `signal.h'.

 - Macro: int NSIG
     The value of this symbolic constant is the total number of signals
     defined.  Since the signal numbers are allocated consecutively,
     `NSIG' is also one greater than the largest defined signal number.

* Menu:

* Program Error Signals::       Used to report serious program errors.
* Termination Signals::         Used to interrupt and/or terminate the
                                 program.
* Alarm Signals::               Used to indicate expiration of timers.
* Asynchronous I/O Signals::    Used to indicate input is available.
* Job Control Signals::         Signals used to support job control.
* Operation Error Signals::     Used to report operational system errors.
* Miscellaneous Signals::       Miscellaneous Signals.
* Signal Messages::             Printing a message describing a signal.


File: libc.info,  Node: Program Error Signals,  Next: Termination Signals,  Up: Standard Signals

Program Error Signals
---------------------

   The following signals are generated when a serious program error is
detected by the operating system or the computer itself.  In general,
all of these signals are indications that your program is seriously
broken in some way, and there's usually no way to continue the
computation which encountered the error.

   Some programs handle program error signals in order to tidy up before
terminating; for example, programs that turn off echoing of terminal
input should handle program error signals in order to turn echoing back
on.  The handler should end by specifying the default action for the
signal that happened and then reraising it; this will cause the program
to terminate with that signal, as if it had not had a handler.  (*Note
Termination in Handler::.)

   Termination is the sensible ultimate outcome from a program error in
most programs.  However, programming systems such as Lisp that can load
compiled user programs might need to keep executing even if a user
program incurs an error.  These programs have handlers which use
`longjmp' to return control to the command level.

   The default action for all of these signals is to cause the process
to terminate.  If you block or ignore these signals or establish
handlers for them that return normally, your program will probably
break horribly when such signals happen, unless they are generated by
`raise' or `kill' instead of a real error.

   When one of these program error signals terminates a process, it also
writes a "core dump file" which records the state of the process at the
time of termination.  The core dump file is named `core' and is written
in whichever directory is current in the process at the time.  (On the
GNU system, you can specify the file name for core dumps with the
environment variable `COREFILE'.)  The purpose of core dump files is so
that you can examine them with a debugger to investigate what caused
the error.

 - Macro: int SIGFPE
     The `SIGFPE' signal reports a fatal arithmetic error.  Although the
     name is derived from "floating-point exception", this signal
     actually covers all arithmetic errors, including division by zero
     and overflow.  If a program stores integer data in a location
     which is then used in a floating-point operation, this often
     causes an "invalid operation" exception, because the processor
     cannot recognize the data as a floating-point number.

     Actual floating-point exceptions are a complicated subject because
     there are many types of exceptions with subtly different meanings,
     and the `SIGFPE' signal doesn't distinguish between them.  The
     `IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std
     754-1985 and ANSI/IEEE Std 854-1987)' defines various
     floating-point exceptions and requires conforming computer systems
     to report their occurrences.  However, this standard does not
     specify how the exceptions are reported, or what kinds of handling
     and control the operating system can offer to the programmer.

   BSD systems provide the `SIGFPE' handler with an extra argument that
distinguishes various causes of the exception.  In order to access this
argument, you must define the handler to accept two arguments, which
means you must cast it to a one-argument function type in order to
establish the handler.  The GNU library does provide this extra
argument, but the value is meaningful only on operating systems that
provide the information (BSD systems and GNU systems).

`FPE_INTOVF_TRAP'
     Integer overflow (impossible in a C program unless you enable
     overflow trapping in a hardware-specific fashion).

`FPE_INTDIV_TRAP'
     Integer division by zero.

`FPE_SUBRNG_TRAP'
     Subscript-range (something that C programs never check for).

`FPE_FLTOVF_TRAP'
     Floating overflow trap.

`FPE_FLTDIV_TRAP'
     Floating/decimal division by zero.

`FPE_FLTUND_TRAP'
     Floating underflow trap.  (Trapping on floating underflow is not
     normally enabled.)

`FPE_DECOVF_TRAP'
     Decimal overflow trap.  (Only a few machines have decimal
     arithmetic and C never uses it.)

 - Macro: int SIGILL
     The name of this signal is derived from "illegal instruction"; it
     usually means your program is trying to execute garbage or a
     privileged instruction.  Since the C compiler generates only valid
     instructions, `SIGILL' typically indicates that the executable
     file is corrupted, or that you are trying to execute data.  Some
     common ways of getting into the latter situation are by passing an
     invalid object where a pointer to a function was expected, or by
     writing past the end of an automatic array (or similar problems
     with pointers to automatic variables) and corrupting other data on
     the stack such as the return address of a stack frame.

     `SIGILL' can also be generated when the stack overflows, or when
     the system has trouble running the handler for a signal.

 - Macro: int SIGSEGV
     This signal is generated when a program tries to read or write
     outside the memory that is allocated for it, or to write memory
     that can only be read.  (Actually, the signals only occur when the
     program goes far enough outside to be detected by the system's
     memory protection mechanism.)  The name is an abbreviation for
     "segmentation violation".

     Common ways of getting a `SIGSEGV' condition include dereferencing
     a null or uninitialized pointer, or when you use a pointer to step
     through an array, but fail to check for the end of the array.  It
     varies among systems whether dereferencing a null pointer generates
     `SIGSEGV' or `SIGBUS'.

 - Macro: int SIGBUS
     This signal is generated when an invalid pointer is dereferenced.
     Like `SIGSEGV', this signal is typically the result of
     dereferencing an uninitialized pointer.  The difference between
     the two is that `SIGSEGV' indicates an invalid access to valid
     memory, while `SIGBUS' indicates an access to an invalid address.
     In particular, `SIGBUS' signals often result from dereferencing a
     misaligned pointer, such as referring to a four-word integer at an
     address not divisible by four.  (Each kind of computer has its own
     requirements for address alignment.)

     The name of this signal is an abbreviation for "bus error".

 - Macro: int SIGABRT
     This signal indicates an error detected by the program itself and
     reported by calling `abort'.  *Note Aborting a Program::.

 - Macro: int SIGIOT
     Generated by the PDP-11 "iot" instruction.  On most machines, this
     is just another name for `SIGABRT'.

 - Macro: int SIGTRAP
     Generated by the machine's breakpoint instruction, and possibly
     other trap instructions.  This signal is used by debuggers.  Your
     program will probably only see `SIGTRAP' if it is somehow
     executing bad instructions.

 - Macro: int SIGEMT
     Emulator trap; this results from certain unimplemented instructions
     which might be emulated in software, or the operating system's
     failure to properly emulate them.

 - Macro: int SIGSYS
     Bad system call; that is to say, the instruction to trap to the
     operating system was executed, but the code number for the system
     call to perform was invalid.


File: libc.info,  Node: Termination Signals,  Next: Alarm Signals,  Prev: Program Error Signals,  Up: Standard Signals

Termination Signals
-------------------

   These signals are all used to tell a process to terminate, in one way
or another.  They have different names because they're used for slightly
different purposes, and programs might want to handle them differently.

   The reason for handling these signals is usually so your program can
tidy up as appropriate before actually terminating.  For example, you
might want to save state information, delete temporary files, or restore
the previous terminal modes.  Such a handler should end by specifying
the default action for the signal that happened and then reraising it;
this will cause the program to terminate with that signal, as if it had
not had a handler.  (*Note Termination in Handler::.)

   The (obvious) default action for all of these signals is to cause the
process to terminate.

 - Macro: int SIGTERM
     The `SIGTERM' signal is a generic signal used to cause program
     termination.  Unlike `SIGKILL', this signal can be blocked,
     handled, and ignored.  It is the normal way to politely ask a
     program to terminate.

     The shell command `kill' generates `SIGTERM' by default.

 - Macro: int SIGINT
     The `SIGINT' ("program interrupt") signal is sent when the user
     types the INTR character (normally `C-c').  *Note Special
     Characters::, for information about terminal driver support for
     `C-c'.

 - Macro: int SIGQUIT
     The `SIGQUIT' signal is similar to `SIGINT', except that it's
     controlled by a different key--the QUIT character, usually
     `C-\'--and produces a core dump when it terminates the process,
     just like a program error signal.  You can think of this as a
     program error condition "detected" by the user.

     *Note Program Error Signals::, for information about core dumps.
     *Note Special Characters::, for information about terminal driver
     support.

     Certain kinds of cleanups are best omitted in handling `SIGQUIT'.
     For example, if the program creates temporary files, it should
     handle the other termination requests by deleting the temporary
     files.  But it is better for `SIGQUIT' not to delete them, so that
     the user can examine them in conjunction with the core dump.

 - Macro: int SIGKILL
     The `SIGKILL' signal is used to cause immediate program
     termination.  It cannot be handled or ignored, and is therefore
     always fatal.  It is also not possible to block this signal.

     This signal is usually generated only by explicit request.  Since
     it cannot be handled, you should generate it only as a last
     resort, after first trying a less drastic method such as `C-c' or
     `SIGTERM'.  If a process does not respond to any other termination
     signals, sending it a `SIGKILL' signal will almost always cause it
     to go away.

     In fact, if `SIGKILL' fails to terminate a process, that by itself
     constitutes an operating system bug which you should report.

     The system will generate `SIGKILL' for a process itself under some
     unusual conditions where the program cannot possibly continue to
     run (even to run a signal handler).

 - Macro: int SIGHUP
     The `SIGHUP' ("hang-up") signal is used to report that the user's
     terminal is disconnected, perhaps because a network or telephone
     connection was broken.  For more information about this, see *Note
     Control Modes::.

     This signal is also used to report the termination of the
     controlling process on a terminal to jobs associated with that
     session; this termination effectively disconnects all processes in
     the session from the controlling terminal.  For more information,
     see *Note Termination Internals::.


File: libc.info,  Node: Alarm Signals,  Next: Asynchronous I/O Signals,  Prev: Termination Signals,  Up: Standard Signals

Alarm Signals
-------------

   These signals are used to indicate the expiration of timers.  *Note
Setting an Alarm::, for information about functions that cause these
signals to be sent.

   The default behavior for these signals is to cause program
termination.  This default is rarely useful, but no other default would
be useful; most of the ways of using these signals would require
handler functions in any case.

 - Macro: int SIGALRM
     This signal typically indicates expiration of a timer that
     measures real or clock time.  It is used by the `alarm' function,
     for example.

 - Macro: int SIGVTALRM
     This signal typically indicates expiration of a timer that
     measures CPU time used by the current process.  The name is an
     abbreviation for "virtual time alarm".

 - Macro: int SIGPROF
     This signal typically indicates expiration of a timer that measures
     both CPU time used by the current process, and CPU time expended on
     behalf of the process by the system.  Such a timer is used to
     implement code profiling facilities, hence the name of this signal.


File: libc.info,  Node: Asynchronous I/O Signals,  Next: Job Control Signals,  Prev: Alarm Signals,  Up: Standard Signals

Asynchronous I/O Signals
------------------------

   The signals listed in this section are used in conjunction with
asynchronous I/O facilities.  You have to take explicit action by
calling `fcntl' to enable a particular file descriptor to generate
these signals (*note Interrupt Input::).  The default action for these
signals is to ignore them.

 - Macro: int SIGIO
     This signal is sent when a file descriptor is ready to perform
     input or output.

     On most operating systems, terminals and sockets are the only
     kinds of files that can generate `SIGIO'; other kinds, including
     ordinary files, never generate `SIGIO' even if you ask them to.

     In the GNU system `SIGIO' will always be generated properly if you
     successfully set asynchronous mode with `fcntl'.

 - Macro: int SIGURG
     This signal is sent when "urgent" or out-of-band data arrives on a
     socket.  *Note Out-of-Band Data::.

 - Macro: int SIGPOLL
     This is a System V signal name, more or less similar to `SIGIO'.
     It is defined only for compatibility.

