spelling correction

[unix-history] / usr / src / lib / libc / gen / signal.3

diff --git a/usr/src/lib/libc/gen/signal.3 b/usr/src/lib/libc/gen/signal.3
index 795a426..fab5a00 100644 (file)
--- a/usr/src/lib/libc/gen/signal.3
+++ b/usr/src/lib/libc/gen/signal.3
@@ -2,58 +2,61 @@
 .\" All rights reserved.  The Berkeley software License Agreement
 .\" specifies the terms and conditions for redistribution.
 .\"
 .\" All rights reserved.  The Berkeley software License Agreement
 .\" specifies the terms and conditions for redistribution.
 .\"

-.\"    @(#)signal.3    4.1 (Berkeley) %G%
+.\"    @(#)signal.3    6.4 (Berkeley) %G%

 .\"
 .\"

-.TH SIGNAL 2 
+.TH SIGNAL 3C ""

 .UC 4
 .UC 4

+.ie t .ds d \(dg
+.el .ds d \z'|+'
+.ie t .ds b \(bu
+.el .ds b @

 .SH NAME
 .SH NAME

-signal \- catch or ignore signals
+signal \- simplified software signal facilities

 .SH SYNOPSIS
 .nf
 .B #include <signal.h>
 .PP
 .B (*signal(sig, func))()
 .SH SYNOPSIS
 .nf
 .B #include <signal.h>
 .PP
 .B (*signal(sig, func))()

-.B void (*func)();
+.B int (*func)();

 .fi
 .SH DESCRIPTION
 .fi
 .SH DESCRIPTION

-.IR N.B. :
-The system currently supports two signal implementations.
-The one described here is standard in version 7 UNIX systems,
-and is retained for backward compatabililty.
-The one described in
-.IR sigsys (2)
-as supplemented by
-.IR sigset (3)
-provides for the needs of the job control mechanisms 
-used by
-.IR csh (1),
-and corrects the bugs in this older implementation of signals,
-allowing programs
-which process interrupts
-to be written
-reliably.
+.I Signal
+is a simplified interface to the more general
+.IR sigvec (2)
+facility.

 .PP
 A signal
 is generated by some abnormal event,
 .PP
 A signal
 is generated by some abnormal event,

-initiated either by user at a terminal (quit, interrupt),
+initiated by a user at a terminal (quit, interrupt, stop),

 by a program error (bus error, etc.),
 by a program error (bus error, etc.),

-or by request of another program (kill).
-Normally all signals
-cause termination of the receiving process,
-but a
+by request of another program (kill),
+or when a process is stopped because it wishes to access
+its control terminal while in the background (see
+.IR tty (4)).
+Signals are optionally generated
+when a process resumes after being stopped,
+when the status of child processes changes,
+or when input is ready at the control terminal.
+Most signals cause termination of the receiving process if no action
+is taken; some signals instead cause the process receiving them
+to be stopped, or are simply discarded if the process has not
+requested otherwise.
+Except for the SIGKILL and SIGSTOP
+signals, the

 .I signal
 .I signal

-call allows them either to be ignored
+call allows signals either to be ignored

 or to cause an interrupt to a specified location.
 or to cause an interrupt to a specified location.

-Here is the list of signals with names as in
-the include file.
+The following is a list of all signals with
+names as in the include file
+.RI < signal.h >:

 .LP
 .nf
 .LP
 .nf

-.ta \w'SIGMMMM 'u +\w'15*  'u
+.ta \w'SIGVTALRM 'u +\w'15*  'u

 SIGHUP 1       hangup
 SIGINT 2       interrupt
 SIGQUIT        3*      quit
 SIGHUP 1       hangup
 SIGINT 2       interrupt
 SIGQUIT        3*      quit

-SIGILL 4*      illegal instruction (not reset when caught)
-SIGTRAP        5*      trace trap (not reset when caught)
+SIGILL 4*      illegal instruction
+SIGTRAP        5*      trace trap

 SIGIOT 6*      IOT instruction
 SIGEMT 7*      EMT instruction
 SIGFPE 8*      floating point exception
 SIGIOT 6*      IOT instruction
 SIGEMT 7*      EMT instruction
 SIGFPE 8*      floating point exception


@@ -64,12 +67,22 @@ SIGSYS      12*     bad argument to system call
 SIGPIPE        13      write on a pipe with no one to read it
 SIGALRM        14      alarm clock
 SIGTERM        15      software termination signal
 SIGPIPE        13      write on a pipe with no one to read it
 SIGALRM        14      alarm clock
 SIGTERM        15      software termination signal

-       16      unassigned
+SIGURG 16\*b   urgent condition present on socket
+SIGSTOP        17\*d   stop (cannot be caught or ignored)
+SIGTSTP        18\*d   stop signal generated from keyboard
+SIGCONT        19\*b   continue after stop
+SIGCHLD        20\*b   child status has changed
+SIGTTIN        21\*d   background read attempted from control terminal
+SIGTTOU        22\*d   background write attempted to control terminal
+SIGIO  23\*b   i/o is possible on a descriptor (see \fIfcntl\fP(2))
+SIGXCPU        24      cpu time limit exceeded (see \fIsetrlimit\fP(2))
+SIGXFSZ        25      file size limit exceeded (see \fIsetrlimit\fP(2))
+SIGVTALRM      26      virtual time alarm (see \fIsetitimer\fP(2))
+SIGPROF        27      profiling timer alarm (see \fIsetitimer\fP(2))
+SIGWINCH       28\*b   Window size change
+SIGUSR1        30      User defined signal 1
+SIGUSR2        31      User defined signal 2

 .fi
 .fi

-.IR N.B. :
-There are actually more signals; see
-.IR sigsys (2);
-the signals listed here are those of standard version 7.

 .PP
 The starred signals in the list above cause a core image
 if not caught or ignored.
 .PP
 The starred signals in the list above cause a core image
 if not caught or ignored.


@@ -79,48 +92,40 @@ If
 is SIG_DFL, the default action
 for signal
 .I sig
 is SIG_DFL, the default action
 for signal
 .I sig

-is reinstated; this default is termination,
-sometimes with a core image.
+is reinstated; this default is termination
+(with a core image for starred signals)
+except for signals marked with \*b or \*d.
+Signals marked with \*b are discarded if the action
+is SIG_DFL; signals marked
+with \*d cause the process to stop.

 If
 .I func
 If
 .I func

-is SIG_IGN the signal is ignored.
-Otherwise
-when the signal occurs
+is SIG_IGN the signal is subsequently ignored
+and pending instances of the signal are discarded.
+Otherwise, when the signal occurs
+further occurrences of the signal are
+automatically blocked and

 .I func
 .I func

-will be called with the
-signal number as argument.
-A return from the function will
-continue the process at the point it was interrupted.
+is called.

 .PP
 .PP

-Except as indicated,
-a signal is reset to SIG_DFL after being caught.
-Thus if it is desired to
-catch every such signal,
-the catching routine must
-issue another
-.I signal
-call.
+A return from the function unblocks
+the handled signal and
+continues the process at the point it was interrupted.
+\fBUnlike previous signal facilities, the handler \fIfunc\fP
+remains installed after a signal has been delivered.\fP

 .PP
 .PP

-If, when using this (older) signal interface,
-a caught signal occurs
-during certain system calls, the call terminates prematurely.
+If a caught signal occurs
+during certain system calls, causing
+the call to terminate prematurely, the call
+is automatically restarted.

 In particular this can occur
 In particular this can occur

-during an
-.IR ioctl ,
-.IR read ,
+during a
+.I read

 or
 .IR write (2)
 or
 .IR write (2)

-on a slow device (like a terminal; but not a file);
-and during
-.I pause
-or
+on a slow device (such as a terminal; but not a file)
+and during a

 .IR wait (2).
 .IR wait (2).

-When such a signal occurs, the saved user status
-is arranged in such a way that when return from the
-signal-catching takes place, it will appear that the
-system call returned an error status.
-The user's program may then, if it wishes,
-re-execute the call.

 .PP
 The value of
 .I signal
 .PP
 The value of
 .I signal


@@ -130,71 +135,88 @@ value of
 for the particular signal.
 .PP
 After a
 for the particular signal.
 .PP
 After a

-.IR  fork (2)
+.IR fork (2)
+or
+.IR vfork (2)

 the child inherits
 all signals.
 the child inherits
 all signals.

-.IR  Exec (2)
-resets all
-caught signals to default action.
-.PP
-If a process is using the mechanisms of
-.IR sigsys (2)
-and
-.IR sigset (3)
-then many of these calls are automatically restarted
-(See
-.IR sigsys (2)
-and
-.IR jobs (3)
-for details).
+.IR  Execve (2)
+resets all caught signals to the default action;
+ignored signals remain ignored.
+.SH "RETURN VALUE
+The previous action is returned on a successful call.
+Otherwise, \-1 is returned and 
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.I Signal
+will fail and no action will take place if one of the
+following occur:
+.TP 15
+[EINVAL]
+.I Sig
+is not a valid signal number.
+.TP 15
+[EINVAL]
+An attempt is made to ignore or supply a handler for SIGKILL
+or SIGSTOP.
+.TP 15
+[EINVAL]
+An attempt is made to ignore SIGCONT (by default SIGCONT
+is ignored).

 .SH "SEE ALSO"
 .SH "SEE ALSO"

-sigsys(2),

 kill(1),
 kill(1),

-kill(2),
-ptrace(2),
-setjmp(3),
-sigset(3)
-.SH DIAGNOSTICS
-The value (int)\-1 is returned if the
-given signal is out of range.
-.SH BUGS
-The traps should be distinguishable by extra arguments
-to the signal handler, and all hardware supplied parameters should
-be made available to the signal routine.
+ptrace(2), kill(2),
+sigvec(2), sigblock(2), sigsetmask(2), sigpause(2),
+sigstack(2), setjmp(3), tty(4)
+.SH "NOTES  (VAX-11)"
+The handler routine can be declared:

 .PP
 .PP

-If a repeated signal arrives before the last one can be
-reset, there is no chance to catch it
-(however this is
-.B not
-true if you use
-.IR sigsys (2)
-and
-.IR sigset (3)).
+    handler(sig, code, scp)

 .PP
 .PP

-The type specification of the routine and its
-.I func
-argument are problematical.
-.SH "ASSEMBLER (PDP-11)"
-(signal = 48.)
-.br
-.B sys  signal; sig; label
-.br
-(old label in r0)
+Here
+.I sig
+is the signal number, into which the hardware faults and traps are
+mapped as defined below.  Code is a parameter which is either a constant
+as given below or, for compatibility mode faults, the code provided by
+the hardware. 
+.I Scp
+is a pointer to the
+.I "struct sigcontext"
+used by the system to restore the process context from before
+the signal.
+Compatibility mode faults are distinguished from the
+other SIGILL traps by having PSL_CM set in the psl.

 .PP
 .PP

-If
-.I label
-is 0,
-default action is reinstated.
-If
-.I label
-is 1, the signal is ignored.
-Any other even
-.I label
-specifies an address in the process
-where an interrupt is simulated.
-An RTI or RTT instruction will return from the
-interrupt.
-.SH "NOTES (VAX-11)"
-See
-.IR sigsys (2)
-for information on how hardware faults are mapped into signals.
+The following defines the mapping of hardware traps to signals
+and codes.  All of these symbols are defined in
+.RI < signal.h >:
+.LP
+.ta \w'     Floating/decimal divide by zero   'u +\w'15*  'u +8n
+.nf
+   Hardware condition  Signal  Code
+
+Arithmetic traps:
+   Integer overflow    SIGFPE  FPE_INTOVF_TRAP
+   Integer division by zero    SIGFPE  FPE_INTDIV_TRAP
+   Floating overflow trap      SIGFPE  FPE_FLTOVF_TRAP
+   Floating/decimal division by zero   SIGFPE  FPE_FLTDIV_TRAP
+   Floating underflow trap     SIGFPE  FPE_FLTUND_TRAP
+   Decimal overflow trap       SIGFPE  FPE_DECOVF_TRAP
+   Subscript-range     SIGFPE  FPE_SUBRNG_TRAP
+   Floating overflow fault     SIGFPE  FPE_FLTOVF_FAULT
+   Floating divide by zero fault       SIGFPE  FPE_FLTDIV_FAULT
+   Floating underflow fault    SIGFPE  FPE_FLTUND_FAULT
+Length access control  SIGSEGV
+Protection violation   SIGBUS
+Reserved instruction   SIGILL  ILL_RESAD_FAULT
+Customer-reserved instr.       SIGEMT
+Reserved operand       SIGILL  ILL_PRIVIN_FAULT
+Reserved addressing    SIGILL  ILL_RESOP_FAULT
+Trace pending  SIGTRAP
+Bpt instruction        SIGTRAP
+Compatibility-mode     SIGILL  hardware supplied code
+Chme   SIGSEGV
+Chms   SIGSEGV
+Chmu   SIGSEGV
+.fi