1: @node Signal Handling, Program Basics, Non-Local Exits, Top
    2: @c %MENU% How to send, block, and handle signals
    3: @chapter Signal Handling
    4: 
    5: @cindex signal
    6: A @dfn{signal} is a software interrupt delivered to a process.  The
    7: operating system uses signals to report exceptional situations to an
    8: executing program.  Some signals report errors such as references to
    9: invalid memory addresses; others report asynchronous events, such as
   10: disconnection of a phone line.
   11: 
   12: The GNU C library defines a variety of signal types, each for a
   13: particular kind of event.  Some kinds of events make it inadvisable or
   14: impossible for the program to proceed as usual, and the corresponding
   15: signals normally abort the program.  Other kinds of signals that report
   16: harmless events are ignored by default.
   17: 
   18: If you anticipate an event that causes signals, you can define a handler
   19: function and tell the operating system to run it when that particular
   20: type of signal arrives.
   21: 
   22: Finally, one process can send a signal to another process; this allows a
   23: parent process to abort a child, or two related processes to communicate
   24: and synchronize.
   25: 
   26: @menu
   27: * Concepts of Signals::         Introduction to the signal facilities.
   28: * Standard Signals::            Particular kinds of signals with
   29:                                  standard names and meanings.
   30: * Signal Actions::              Specifying what happens when a
   31:                                  particular signal is delivered.
   32: * Defining Handlers::           How to write a signal handler function.
   33: * Interrupted Primitives::      Signal handlers affect use of @code{open},
   34:                                  @code{read}, @code{write} and other functions.
   35: * Generating Signals::          How to send a signal to a process.
   36: * Blocking Signals::            Making the system hold signals temporarily.
   37: * Waiting for a Signal::        Suspending your program until a signal
   38:                                  arrives.
   39: * Signal Stack::                Using a Separate Signal Stack.
   40: * BSD Signal Handling::         Additional functions for backward
   41:                                  compatibility with BSD.
   42: @end menu
   43: 
   44: @node Concepts of Signals
   45: @section Basic Concepts of Signals
   46: 
   47: This section explains basic concepts of how signals are generated, what
   48: happens after a signal is delivered, and how programs can handle
   49: signals.
   50: 
   51: @menu
   52: * Kinds of Signals::            Some examples of what can cause a signal.
   53: * Signal Generation::           Concepts of why and how signals occur.
   54: * Delivery of Signal::          Concepts of what a signal does to the
   55:                                  process.
   56: @end menu
   57: 
   58: @node Kinds of Signals
   59: @subsection Some Kinds of Signals
   60: 
   61: A signal reports the occurrence of an exceptional event.  These are some
   62: of the events that can cause (or @dfn{generate}, or @dfn{raise}) a
   63: signal:
   64: 
   65: @itemize @bullet
   66: @item
   67: A program error such as dividing by zero or issuing an address outside
   68: the valid range.
   69: 
   70: @item
   71: A user request to interrupt or terminate the program.  Most environments
   72: are set up to let a user suspend the program by typing @kbd{C-z}, or
   73: terminate it with @kbd{C-c}.  Whatever key sequence is used, the
   74: operating system sends the proper signal to interrupt the process.
   75: 
   76: @item
   77: The termination of a child process.
   78: 
   79: @item
   80: Expiration of a timer or alarm.
   81: 
   82: @item
   83: A call to @code{kill} or @code{raise} by the same process.
   84: 
   85: @item
   86: A call to @code{kill} from another process.  Signals are a limited but
   87: useful form of interprocess communication.
   88: 
   89: @item
   90: An attempt to perform an I/O operation that cannot be done.  Examples
   91: are reading from a pipe that has no writer (@pxref{Pipes and FIFOs}),
   92: and reading or writing to a terminal in certain situations (@pxref{Job
   93: Control}).
   94: @end itemize
   95: 
   96: Each of these kinds of events (excepting explicit calls to @code{kill}
   97: and @code{raise}) generates its own particular kind of signal.  The
   98: various kinds of signals are listed and described in detail in
   99: @ref{Standard Signals}.
  100: 
  101: @node Signal Generation
  102: @subsection Concepts of Signal Generation
  103: @cindex generation of signals
  104: 
  105: In general, the events that generate signals fall into three major
  106: categories: errors, external events, and explicit requests.
  107: 
  108: An error means that a program has done something invalid and cannot
  109: continue execution.  But not all kinds of errors generate signals---in
  110: fact, most do not.  For example, opening a nonexistent file is an error,
  111: but it does not raise a signal; instead, @code{open} returns @code{-1}.
  112: In general, errors that are necessarily associated with certain library
  113: functions are reported by returning a value that indicates an error.
  114: The errors which raise signals are those which can happen anywhere in
  115: the program, not just in library calls.  These include division by zero
  116: and invalid memory addresses.
  117: 
  118: An external event generally has to do with I/O or other processes.
  119: These include the arrival of input, the expiration of a timer, and the
  120: termination of a child process.
  121: 
  122: An explicit request means the use of a library function such as
  123: @code{kill} whose purpose is specifically to generate a signal.
  124: 
  125: Signals may be generated @dfn{synchronously} or @dfn{asynchronously}.  A
  126: synchronous signal pertains to a specific action in the program, and is
  127: delivered (unless blocked) during that action.  Most errors generate
  128: signals synchronously, and so do explicit requests by a process to
  129: generate a signal for that same process.  On some machines, certain
  130: kinds of hardware errors (usually floating-point exceptions) are not
  131: reported completely synchronously, but may arrive a few instructions
  132: later.
  133: 
  134: Asynchronous signals are generated by events outside the control of the
  135: process that receives them.  These signals arrive at unpredictable times
  136: during execution.  External events generate signals asynchronously, and
  137: so do explicit requests that apply to some other process.
  138: 
  139: A given type of signal is either typically synchronous or typically
  140: asynchronous.  For example, signals for errors are typically synchronous
  141: because errors generate signals synchronously.  But any type of signal
  142: can be generated synchronously or asynchronously with an explicit
  143: request.
  144: 
  145: @node Delivery of Signal
  146: @subsection How Signals Are Delivered
  147: @cindex delivery of signals
  148: @cindex pending signals
  149: @cindex blocked signals
  150: 
  151: When a signal is generated, it becomes @dfn{pending}.  Normally it
  152: remains pending for just a short period of time and then is
  153: @dfn{delivered} to the process that was signaled.  However, if that kind
  154: of signal is currently @dfn{blocked}, it may remain pending
  155: indefinitely---until signals of that kind are @dfn{unblocked}.  Once
  156: unblocked, it will be delivered immediately.  @xref{Blocking Signals}.
  157: 
  158: @cindex specified action (for a signal)
  159: @cindex default action (for a signal)
  160: @cindex signal action
  161: @cindex catching signals
  162: When the signal is delivered, whether right away or after a long delay,
  163: the @dfn{specified action} for that signal is taken.  For certain
  164: signals, such as @code{SIGKILL} and @code{SIGSTOP}, the action is fixed,
  165: but for most signals, the program has a choice: ignore the signal,
  166: specify a @dfn{handler function}, or accept the @dfn{default action} for
  167: that kind of signal.  The program specifies its choice using functions
  168: such as @code{signal} or @code{sigaction} (@pxref{Signal Actions}).  We
  169: sometimes say that a handler @dfn{catches} the signal.  While the
  170: handler is running, that particular signal is normally blocked.
  171: 
  172: If the specified action for a kind of signal is to ignore it, then any
  173: such signal which is generated is discarded immediately.  This happens
  174: even if the signal is also blocked at the time.  A signal discarded in
  175: this way will never be delivered, not even if the program subsequently
  176: specifies a different action for that kind of signal and then unblocks
  177: it.
  178: 
  179: If a signal arrives which the program has neither handled nor ignored,
  180: its @dfn{default action} takes place.  Each kind of signal has its own
  181: default action, documented below (@pxref{Standard Signals}).  For most kinds
  182: of signals, the default action is to terminate the process.  For certain
  183: kinds of signals that represent ``harmless'' events, the default action
  184: is to do nothing.
  185: 
  186: When a signal terminates a process, its parent process can determine the
  187: cause of termination by examining the termination status code reported
  188: by the @code{wait} or @code{waitpid} functions.  (This is discussed in
  189: more detail in @ref{Process Completion}.)  The information it can get
  190: includes the fact that termination was due to a signal and the kind of
  191: signal involved.  If a program you run from a shell is terminated by a
  192: signal, the shell typically prints some kind of error message.
  193: 
  194: The signals that normally represent program errors have a special
  195: property: when one of these signals terminates the process, it also
  196: writes a @dfn{core dump file} which records the state of the process at
  197: the time of termination.  You can examine the core dump with a debugger
  198: to investigate what caused the error.
  199: 
  200: If you raise a ``program error'' signal by explicit request, and this
  201: terminates the process, it makes a core dump file just as if the signal
  202: had been due directly to an error.
  203: 
  204: @node Standard Signals
  205: @section Standard Signals
  206: @cindex signal names
  207: @cindex names of signals
  208: 
  209: @pindex signal.h
  210: @cindex signal number
  211: This section lists the names for various standard kinds of signals and
  212: describes what kind of event they mean.  Each signal name is a macro
  213: which stands for a positive integer---the @dfn{signal number} for that
  214: kind of signal.  Your programs should never make assumptions about the
  215: numeric code for a particular kind of signal, but rather refer to them
  216: always by the names defined here.  This is because the number for a
  217: given kind of signal can vary from system to system, but the meanings of
  218: the names are standardized and fairly uniform.
  219: 
  220: The signal names are defined in the header file @file{signal.h}.
  221: 
  222: @comment signal.h
  223: @comment BSD
  224: @deftypevr Macro int NSIG
  225: The value of this symbolic constant is the total number of signals
  226: defined.  Since the signal numbers are allocated consecutively,
  227: @code{NSIG} is also one greater than the largest defined signal number.
  228: @end deftypevr
  229: 
  230: @menu
  231: * Program Error Signals::       Used to report serious program errors.
  232: * Termination Signals::         Used to interrupt and/or terminate the
  233:                                  program.
  234: * Alarm Signals::               Used to indicate expiration of timers.
  235: * Asynchronous I/O Signals::    Used to indicate input is available.
  236: * Job Control Signals::         Signals used to support job control.
  237: * Operation Error Signals::     Used to report operational system errors.
  238: * Miscellaneous Signals::       Miscellaneous Signals.
  239: * Signal Messages::             Printing a message describing a signal.
  240: @end menu
  241: 
  242: @node Program Error Signals
  243: @subsection Program Error Signals
  244: @cindex program error signals
  245: 
  246: The following signals are generated when a serious program error is
  247: detected by the operating system or the computer itself.  In general,
  248: all of these signals are indications that your program is seriously
  249: broken in some way, and there's usually no way to continue the
  250: computation which encountered the error.
  251: 
  252: Some programs handle program error signals in order to tidy up before
  253: terminating; for example, programs that turn off echoing of terminal
  254: input should handle program error signals in order to turn echoing back
  255: on.  The handler should end by specifying the default action for the
  256: signal that happened and then reraising it; this will cause the program
  257: to terminate with that signal, as if it had not had a handler.
  258: (@xref{Termination in Handler}.)
  259: 
  260: Termination is the sensible ultimate outcome from a program error in
  261: most programs.  However, programming systems such as Lisp that can load
  262: compiled user programs might need to keep executing even if a user
  263: program incurs an error.  These programs have handlers which use
  264: @code{longjmp} to return control to the command level.
  265: 
  266: The default action for all of these signals is to cause the process to
  267: terminate.  If you block or ignore these signals or establish handlers
  268: for them that return normally, your program will probably break horribly
  269: when such signals happen, unless they are generated by @code{raise} or
  270: @code{kill} instead of a real error.
  271: 
  272: @vindex COREFILE
  273: When one of these program error signals terminates a process, it also
  274: writes a @dfn{core dump file} which records the state of the process at
  275: the time of termination.  The core dump file is named @file{core} and is
  276: written in whichever directory is current in the process at the time.
  277: (On the GNU system, you can specify the file name for core dumps with
  278: the environment variable @code{COREFILE}.)  The purpose of core dump
  279: files is so that you can examine them with a debugger to investigate
  280: what caused the error.
  281: 
  282: @comment signal.h
  283: @comment ISO
  284: @deftypevr Macro int SIGFPE
  285: The @code{SIGFPE} signal reports a fatal arithmetic error.  Although the
  286: name is derived from ``floating-point exception'', this signal actually
  287: covers all arithmetic errors, including division by zero and overflow.
  288: If a program stores integer data in a location which is then used in a
  289: floating-point operation, this often causes an ``invalid operation''
  290: exception, because the processor cannot recognize the data as a
  291: floating-point number.
  292: @cindex exception
  293: @cindex floating-point exception
  294: 
  295: Actual floating-point exceptions are a complicated subject because there
  296: are many types of exceptions with subtly different meanings, and the
  297: @code{SIGFPE} signal doesn't distinguish between them.  The @cite{IEEE
  298: Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985
  299: and ANSI/IEEE Std 854-1987)}
  300: defines various floating-point exceptions and requires conforming
  301: computer systems to report their occurrences.  However, this standard
  302: does not specify how the exceptions are reported, or what kinds of
  303: handling and control the operating system can offer to the programmer.
  304: @end deftypevr
  305: 
  306: BSD systems provide the @code{SIGFPE} handler with an extra argument
  307: that distinguishes various causes of the exception.  In order to access
  308: this argument, you must define the handler to accept two arguments,
  309: which means you must cast it to a one-argument function type in order to
  310: establish the handler.  The GNU library does provide this extra
  311: argument, but the value is meaningful only on operating systems that
  312: provide the information (BSD systems and GNU systems).
  313: 
  314: @table @code
  315: @comment signal.h
  316: @comment BSD
  317: @item FPE_INTOVF_TRAP
  318: @vindex FPE_INTOVF_TRAP
  319: Integer overflow (impossible in a C program unless you enable overflow
  320: trapping in a hardware-specific fashion).
  321: @comment signal.h
  322: @comment BSD
  323: @item FPE_INTDIV_TRAP
  324: @vindex FPE_INTDIV_TRAP
  325: Integer division by zero.
  326: @comment signal.h
  327: @comment BSD
  328: @item FPE_SUBRNG_TRAP
  329: @vindex FPE_SUBRNG_TRAP
  330: Subscript-range (something that C programs never check for).
  331: @comment signal.h
  332: @comment BSD
  333: @item FPE_FLTOVF_TRAP
  334: @vindex FPE_FLTOVF_TRAP
  335: Floating overflow trap.
  336: @comment signal.h
  337: @comment BSD
  338: @item FPE_FLTDIV_TRAP
  339: @vindex FPE_FLTDIV_TRAP
  340: Floating/decimal division by zero.
  341: @comment signal.h
  342: @comment BSD
  343: @item FPE_FLTUND_TRAP
  344: @vindex FPE_FLTUND_TRAP
  345: Floating underflow trap.  (Trapping on floating underflow is not
  346: normally enabled.)
  347: @comment signal.h
  348: @comment BSD
  349: @item FPE_DECOVF_TRAP
  350: @vindex FPE_DECOVF_TRAP
  351: Decimal overflow trap.  (Only a few machines have decimal arithmetic and
  352: C never uses it.)
  353: @ignore @c These seem redundant
  354: @comment signal.h
  355: @comment BSD
  356: @item FPE_FLTOVF_FAULT
  357: @vindex FPE_FLTOVF_FAULT
  358: Floating overflow fault.
  359: @comment signal.h
  360: @comment BSD
  361: @item FPE_FLTDIV_FAULT
  362: @vindex FPE_FLTDIV_FAULT
  363: Floating divide by zero fault.
  364: @comment signal.h
  365: @comment BSD
  366: @item FPE_FLTUND_FAULT
  367: @vindex FPE_FLTUND_FAULT
  368: Floating underflow fault.
  369: @end ignore
  370: @end table
  371: 
  372: @comment signal.h
  373: @comment ISO
  374: @deftypevr Macro int SIGILL
  375: The name of this signal is derived from ``illegal instruction''; it
  376: usually means your program is trying to execute garbage or a privileged
  377: instruction.  Since the C compiler generates only valid instructions,
  378: @code{SIGILL} typically indicates that the executable file is corrupted,
  379: or that you are trying to execute data.  Some common ways of getting
  380: into the latter situation are by passing an invalid object where a
  381: pointer to a function was expected, or by writing past the end of an
  382: automatic array (or similar problems with pointers to automatic
  383: variables) and corrupting other data on the stack such as the return
  384: address of a stack frame.
  385: 
  386: @code{SIGILL} can also be generated when the stack overflows, or when
  387: the system has trouble running the handler for a signal.
  388: @end deftypevr
  389: @cindex illegal instruction
  390: 
  391: @comment signal.h
  392: @comment ISO
  393: @deftypevr Macro int SIGSEGV
  394: @cindex segmentation violation
  395: This signal is generated when a program tries to read or write outside
  396: the memory that is allocated for it, or to write memory that can only be
  397: read.  (Actually, the signals only occur when the program goes far
  398: enough outside to be detected by the system's memory protection
  399: mechanism.)  The name is an abbreviation for ``segmentation violation''.
  400: 
  401: Common ways of getting a @code{SIGSEGV} condition include dereferencing
  402: a null or uninitialized pointer, or when you use a pointer to step
  403: through an array, but fail to check for the end of the array.  It varies
  404: among systems whether dereferencing a null pointer generates
  405: @code{SIGSEGV} or @code{SIGBUS}.
  406: @end deftypevr
  407: 
  408: @comment signal.h
  409: @comment BSD
  410: @deftypevr Macro int SIGBUS
  411: This signal is generated when an invalid pointer is dereferenced.  Like
  412: @code{SIGSEGV}, this signal is typically the result of dereferencing an
  413: uninitialized pointer.  The difference between the two is that
  414: @code{SIGSEGV} indicates an invalid access to valid memory, while
  415: @code{SIGBUS} indicates an access to an invalid address.  In particular,
  416: @code{SIGBUS} signals often result from dereferencing a misaligned
  417: pointer, such as referring to a four-word integer at an address not
  418: divisible by four.  (Each kind of computer has its own requirements for
  419: address alignment.)
  420: 
  421: The name of this signal is an abbreviation for ``bus error''.
  422: @end deftypevr
  423: @cindex bus error
  424: 
  425: @comment signal.h
  426: @comment ISO
  427: @deftypevr Macro int SIGABRT
  428: @cindex abort signal
  429: This signal indicates an error detected by the program itself and
  430: reported by calling @code{abort}.  @xref{Aborting a Program}.
  431: @end deftypevr
  432: 
  433: @comment signal.h
  434: @comment Unix
  435: @deftypevr Macro int SIGIOT
  436: Generated by the PDP-11 ``iot'' instruction.  On most machines, this is
  437: just another name for @code{SIGABRT}.
  438: @end deftypevr
  439: 
  440: @comment signal.h
  441: @comment BSD
  442: @deftypevr Macro int SIGTRAP
  443: Generated by the machine's breakpoint instruction, and possibly other
  444: trap instructions.  This signal is used by debuggers.  Your program will
  445: probably only see @code{SIGTRAP} if it is somehow executing bad
  446: instructions.
  447: @end deftypevr
  448: 
  449: @comment signal.h
  450: @comment BSD
  451: @deftypevr Macro int  SIGEMT
  452: Emulator trap; this results from certain unimplemented instructions
  453: which might be emulated in software, or the operating system's
  454: failure to properly emulate them.
  455: @end deftypevr
  456: 
  457: @comment signal.h
  458: @comment Unix
  459: @deftypevr Macro int  SIGSYS
  460: Bad system call; that is to say, the instruction to trap to the
  461: operating system was executed, but the code number for the system call
  462: to perform was invalid.
  463: @end deftypevr
  464: 
  465: @node Termination Signals
  466: @subsection Termination Signals
  467: @cindex program termination signals
  468: 
  469: These signals are all used to tell a process to terminate, in one way
  470: or another.  They have different names because they're used for slightly
  471: different purposes, and programs might want to handle them differently.
  472: 
  473: The reason for handling these signals is usually so your program can
  474: tidy up as appropriate before actually terminating.  For example, you
  475: might want to save state information, delete temporary files, or restore
  476: the previous terminal modes.  Such a handler should end by specifying
  477: the default action for the signal that happened and then reraising it;
  478: this will cause the program to terminate with that signal, as if it had
  479: not had a handler.  (@xref{Termination in Handler}.)
  480: 
  481: The (obvious) default action for all of these signals is to cause the
  482: process to terminate.
  483: 
  484: @comment signal.h
  485: @comment ISO
  486: @deftypevr Macro int SIGTERM
  487: @cindex termination signal
  488: The @code{SIGTERM} signal is a generic signal used to cause program
  489: termination.  Unlike @code{SIGKILL}, this signal can be blocked,
  490: handled, and ignored.  It is the normal way to politely ask a program to
  491: terminate.
  492: 
  493: The shell command @code{kill} generates @code{SIGTERM} by default.
  494: @pindex kill
  495: @end deftypevr
  496: 
  497: @comment signal.h
  498: @comment ISO
  499: @deftypevr Macro int SIGINT
  500: @cindex interrupt signal
  501: The @code{SIGINT} (``program interrupt'') signal is sent when the user
  502: types the INTR character (normally @kbd{C-c}).  @xref{Special
  503: Characters}, for information about terminal driver support for
  504: @kbd{C-c}.
  505: @end deftypevr
  506: 
  507: @comment signal.h
  508: @comment POSIX.1
  509: @deftypevr Macro int SIGQUIT
  510: @cindex quit signal
  511: @cindex quit signal
  512: The @code{SIGQUIT} signal is similar to @code{SIGINT}, except that it's
  513: controlled by a different key---the QUIT character, usually
  514: @kbd{C-\}---and produces a core dump when it terminates the process,
  515: just like a program error signal.  You can think of this as a
  516: program error condition ``detected'' by the user.
  517: 
  518: @xref{Program Error Signals}, for information about core dumps.
  519: @xref{Special Characters}, for information about terminal driver
  520: support.
  521: 
  522: Certain kinds of cleanups are best omitted in handling @code{SIGQUIT}.
  523: For example, if the program creates temporary files, it should handle
  524: the other termination requests by deleting the temporary files.  But it
  525: is better for @code{SIGQUIT} not to delete them, so that the user can
  526: examine them in conjunction with the core dump.
  527: @end deftypevr
  528: 
  529: @comment signal.h
  530: @comment POSIX.1
  531: @deftypevr Macro int SIGKILL
  532: The @code{SIGKILL} signal is used to cause immediate program termination.
  533: It cannot be handled or ignored, and is therefore always fatal.  It is
  534: also not possible to block this signal.
  535: 
  536: This signal is usually generated only by explicit request.  Since it
  537: cannot be handled, you should generate it only as a last resort, after
  538: first trying a less drastic method such as @kbd{C-c} or @code{SIGTERM}.
  539: If a process does not respond to any other termination signals, sending
  540: it a @code{SIGKILL} signal will almost always cause it to go away.
  541: 
  542: In fact, if @code{SIGKILL} fails to terminate a process, that by itself
  543: constitutes an operating system bug which you should report.
  544: 
  545: The system will generate @code{SIGKILL} for a process itself under some
  546: unusual conditions where the program cannot possibly continue to run
  547: (even to run a signal handler).
  548: @end deftypevr
  549: @cindex kill signal
  550: 
  551: @comment signal.h
  552: @comment POSIX.1
  553: @deftypevr Macro int SIGHUP
  554: @cindex hangup signal
  555: The @code{SIGHUP} (``hang-up'') signal is used to report that the user's
  556: terminal is disconnected, perhaps because a network or telephone
  557: connection was broken.  For more information about this, see @ref{Control
  558: Modes}.
  559: 
  560: This signal is also used to report the termination of the controlling
  561: process on a terminal to jobs associated with that session; this
  562: termination effectively disconnects all processes in the session from
  563: the controlling terminal.  For more information, see @ref{Termination
  564: Internals}.
  565: @end deftypevr
  566: 
  567: @node Alarm Signals
  568: @subsection Alarm Signals
  569: 
  570: These signals are used to indicate the expiration of timers.
  571: @xref{Setting an Alarm}, for information about functions that cause
  572: these signals to be sent.
  573: 
  574: The default behavior for these signals is to cause program termination.
  575: This default is rarely useful, but no other default would be useful;
  576: most of the ways of using these signals would require handler functions
  577: in any case.
  578: 
  579: @comment signal.h
  580: @comment POSIX.1
  581: @deftypevr Macro int SIGALRM
  582: This signal typically indicates expiration of a timer that measures real
  583: or clock time.  It is used by the @code{alarm} function, for example.
  584: @end deftypevr
  585: @cindex alarm signal
  586: 
  587: @comment signal.h
  588: @comment BSD
  589: @deftypevr Macro int SIGVTALRM
  590: This signal typically indicates expiration of a timer that measures CPU
  591: time used by the current process.  The name is an abbreviation for
  592: ``virtual time alarm''.
  593: @end deftypevr
  594: @cindex virtual time alarm signal
  595: 
  596: @comment signal.h
  597: @comment BSD
  598: @deftypevr Macro int SIGPROF
  599: This signal typically indicates expiration of a timer that measures
  600: both CPU time used by the current process, and CPU time expended on
  601: behalf of the process by the system.  Such a timer is used to implement
  602: code profiling facilities, hence the name of this signal.
  603: @end deftypevr
  604: @cindex profiling alarm signal
  605: 
  606: 
  607: @node Asynchronous I/O Signals
  608: @subsection Asynchronous I/O Signals
  609: 
  610: The signals listed in this section are used in conjunction with
  611: asynchronous I/O facilities.  You have to take explicit action by
  612: calling @code{fcntl} to enable a particular file descriptor to generate
  613: these signals (@pxref{Interrupt Input}).  The default action for these
  614: signals is to ignore them.
  615: 
  616: @comment signal.h
  617: @comment BSD
  618: @deftypevr Macro int SIGIO
  619: @cindex input available signal
  620: @cindex output possible signal
  621: This signal is sent when a file descriptor is ready to perform input
  622: or output.
  623: 
  624: On most operating systems, terminals and sockets are the only kinds of
  625: files that can generate @code{SIGIO}; other kinds, including ordinary
  626: files, never generate @code{SIGIO} even if you ask them to.
  627: 
  628: In the GNU system @code{SIGIO} will always be generated properly
  629: if you successfully set asynchronous mode with @code{fcntl}.
  630: @end deftypevr
  631: 
  632: @comment signal.h
  633: @comment BSD
  634: @deftypevr Macro int SIGURG
  635: @cindex urgent data signal
  636: This signal is sent when ``urgent'' or out-of-band data arrives on a
  637: socket.  @xref{Out-of-Band Data}.
  638: @end deftypevr
  639: 
  640: @comment signal.h
  641: @comment SVID
  642: @deftypevr Macro int SIGPOLL
  643: This is a System V signal name, more or less similar to @code{SIGIO}.
  644: It is defined only for compatibility.
  645: @end deftypevr
  646: 
  647: @node Job Control Signals
  648: @subsection Job Control Signals
  649: @cindex job control signals
  650: 
  651: These signals are used to support job control.  If your system
  652: doesn't support job control, then these macros are defined but the
  653: signals themselves can't be raised or handled.
  654: 
  655: You should generally leave these signals alone unless you really
  656: understand how job control works.  @xref{Job Control}.
  657: 
  658: @comment signal.h
  659: @comment POSIX.1
  660: @deftypevr Macro int SIGCHLD
  661: @cindex child process signal
  662: This signal is sent to a parent process whenever one of its child
  663: processes terminates or stops.
  664: 
  665: The default action for this signal is to ignore it.  If you establish a
  666: handler for this signal while there are child processes that have
  667: terminated but not reported their status via @code{wait} or
  668: @code{waitpid} (@pxref{Process Completion}), whether your new handler
  669: applies to those processes or not depends on the particular operating
  670: system.
  671: @end deftypevr
  672: 
  673: @comment signal.h
  674: @comment SVID
  675: @deftypevr Macro int SIGCLD
  676: This is an obsolete name for @code{SIGCHLD}.
  677: @end deftypevr
  678: 
  679: @comment signal.h
  680: @comment POSIX.1
  681: @deftypevr Macro int SIGCONT
  682: @cindex continue signal
  683: You can send a @code{SIGCONT} signal to a process to make it continue.
  684: This signal is special---it always makes the process continue if it is
  685: stopped, before the signal is delivered.  The default behavior is to do
  686: nothing else.  You cannot block this signal.  You can set a handler, but
  687: @code{SIGCONT} always makes the process continue regardless.
  688: 
  689: Most programs have no reason to handle @code{SIGCONT}; they simply
  690: resume execution without realizing they were ever stopped.  You can use
  691: a handler for @code{SIGCONT} to make a program do something special when
  692: it is stopped and continued---for example, to reprint a prompt when it
  693: is suspended while waiting for input.
  694: @end deftypevr
  695: 
  696: @comment signal.h
  697: @comment POSIX.1
  698: @deftypevr Macro int SIGSTOP
  699: The @code{SIGSTOP} signal stops the process.  It cannot be handled,
  700: ignored, or blocked.
  701: @end deftypevr
  702: @cindex stop signal
  703: 
  704: @comment signal.h
  705: @comment POSIX.1
  706: @deftypevr Macro int SIGTSTP
  707: The @code{SIGTSTP} signal is an interactive stop signal.  Unlike
  708: @code{SIGSTOP}, this signal can be handled and ignored.
  709: 
  710: Your program should handle this signal if you have a special need to
  711: leave files or system tables in a secure state when a process is
  712: stopped.  For example, programs that turn off echoing should handle
  713: @code{SIGTSTP} so they can turn echoing back on before stopping.
  714: 
  715: This signal is generated when the user types the SUSP character
  716: (normally @kbd{C-z}).  For more information about terminal driver
  717: support, see @ref{Special Characters}.
  718: @end deftypevr
  719: @cindex interactive stop signal
  720: 
  721: @comment signal.h
  722: @comment POSIX.1
  723: @deftypevr Macro int SIGTTIN
  724: A process cannot read from the user's terminal while it is running
  725: as a background job.  When any process in a background job tries to
  726: read from the terminal, all of the processes in the job are sent a
  727: @code{SIGTTIN} signal.  The default action for this signal is to
  728: stop the process.  For more information about how this interacts with
  729: the terminal driver, see @ref{Access to the Terminal}.
  730: @end deftypevr
  731: @cindex terminal input signal
  732: 
  733: @comment signal.h
  734: @comment POSIX.1
  735: @deftypevr Macro int SIGTTOU
  736: This is similar to @code{SIGTTIN}, but is generated when a process in a
  737: background job attempts to write to the terminal or set its modes.
  738: Again, the default action is to stop the process.  @code{SIGTTOU} is
  739: only generated for an attempt to write to the terminal if the
  740: @code{TOSTOP} output mode is set; @pxref{Output Modes}.
  741: @end deftypevr
  742: @cindex terminal output signal
  743: 
  744: While a process is stopped, no more signals can be delivered to it until
  745: it is continued, except @code{SIGKILL} signals and (obviously)
  746: @code{SIGCONT} signals.  The signals are marked as pending, but not
  747: delivered until the process is continued.  The @code{SIGKILL} signal
  748: always causes termination of the process and can't be blocked, handled
  749: or ignored.  You can ignore @code{SIGCONT}, but it always causes the
  750: process to be continued anyway if it is stopped.