initial import of NetBSD tree

1 files changed, 373 insertions, 0 deletions

diff --git a/lib/libc/sys/sigaction.2 b/lib/libc/sys/sigaction.2
new file mode 100644
index 00000000000..dc038623c01
--- /dev/null
+++ b/lib/libc/sys/sigaction.2
@@ -0,0 +1,373 @@
+.\"	$NetBSD: sigaction.2,v 1.6 1995/02/27 12:37:19 cgd Exp $
+.\"
+.\" Copyright (c) 1980, 1990, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by the University of
+.\"	California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"	@(#)sigaction.2	8.2 (Berkeley) 4/3/94
+.\"
+.Dd April 3, 1994
+.Dt SIGACTION 2
+.Os
+.Sh NAME
+.Nm sigaction
+.Nd software signal facilities
+.Sh SYNOPSIS
+.Fd #include <signal.h>
+.Bd -literal
+struct sigaction {
+	void     (*sa_handler)();
+	sigset_t sa_mask;
+	int	 sa_flags;
+};
+.Ed
+.Ft int
+.Fn sigaction "int sig" "struct sigaction *act" "struct sigaction *oact"
+.Sh DESCRIPTION
+The system defines a set of signals that may be delivered to a process.
+Signal delivery resembles the occurrence of a hardware interrupt:
+the signal is blocked from further occurrence, the current process 
+context is saved, and a new one is built.  A process may specify a
+.Em handler
+to which a signal is delivered, or specify that a signal is to be 
+.Em ignored .
+A process may also specify that a default action is to be taken
+by the system when a signal occurs.
+A signal may also be
+.Em blocked ,
+in which case its delivery is postponed until it is
+.Em unblocked .
+The action to be taken on delivery is determined at the time
+of delivery.
+Normally, signal handlers execute on the current stack
+of the process.  This may be changed, on a per-handler basis,
+so that signals are taken on a special
+.Em "signal stack" .
+.Pp
+Signal routines execute with the signal that caused their
+invocation
+.Em blocked ,
+but other signals may yet occur.
+A global 
+.Em "signal mask"
+defines the set of signals currently blocked from delivery
+to a process.  The signal mask for a process is initialized
+from that of its parent (normally empty).  It
+may be changed with a
+.Xr sigprocmask 2
+call, or when a signal is delivered to the process.
+.Pp
+When a signal
+condition arises for a process, the signal is added to a set of
+signals pending for the process.
+If the signal is not currently
+.Em blocked
+by the process then it is delivered to the process.
+Signals may be delivered any time a process enters the operating system
+(e.g., during a system call, page fault or trap, or clock interrupt).
+If multiple signals are ready to be delivered at the same time,
+any signals that could be caused by traps are delivered first.
+Additional signals may be processed at the same time, with each
+appearing to interrupt the handlers for the previous signals
+before their first instructions.
+The set of pending signals is returned by the
+.Xr sigpending 2
+function.
+When a caught signal
+is delivered, the current state of the process is saved,
+a new signal mask is calculated (as described below), 
+and the signal handler is invoked.  The call to the handler
+is arranged so that if the signal handling routine returns
+normally the process will resume execution in the context
+from before the signal's delivery.
+If the process wishes to resume in a different context, then it
+must arrange to restore the previous context itself.
+.Pp
+When a signal is delivered to a process a new signal mask is
+installed for the duration of the process' signal handler
+(or until a
+.Xr sigprocmask
+call is made).
+This mask is formed by taking the union of the current signal mask set,
+the signal to be delivered, and 
+the signal mask associated with the handler to be invoked.
+.Pp
+.Fn Sigaction
+assigns an action for a specific signal.
+If
+.Fa act
+is non-zero, it
+specifies an action
+.Pf ( Dv SIG_DFL ,
+.Dv SIG_IGN ,
+or a handler routine) and mask
+to be used when delivering the specified signal.
+If 
+.Fa oact
+is non-zero, the previous handling information for the signal
+is returned to the user.
+.Pp
+Once a signal handler is installed, it remains installed
+until another
+.Fn sigaction
+call is made, or an 
+.Xr execve 2
+is performed.
+A signal-specific default action may be reset by
+setting
+.Fa sa_handler
+to
+.Dv SIG_DFL .
+The defaults are process termination, possibly with core dump;
+no action; stopping the process; or continuing the process.
+See the signal list below for each signal's default action.
+If
+.Fa sa_handler
+is
+.Dv SIG_DFL ,
+the default action for the signal is to discard the signal,
+and if a signal is pending,
+the pending signal is discarded even if the signal is masked.
+If
+.Fa sa_handler
+is set to
+.Dv SIG_IGN
+current and pending instances
+of the signal are ignored and discarded.
+.Pp
+Options may be specified by setting
+.Em sa_flags .
+If the
+.Dv SA_NOCLDSTOP
+bit is set when installing a catching function
+for the
+.Dv SIGCHLD
+signal,
+the
+.Dv SIGCHLD
+signal will be generated only when a child process exits,
+not when a child process stops.
+Further, if the
+.Dv SA_ONSTACK
+bit is set in
+.Em sa_flags ,
+the system will deliver the signal to the process on a
+.Em "signal stack" ,
+specified with
+.Xr sigstack 2 .
+.Pp
+If a signal is caught during the system calls listed below,
+the call may be forced to terminate
+with the error
+.Dv EINTR ,
+the call may return with a data transfer shorter than requested,
+or the call may be restarted.
+Restart of pending calls is requested
+by setting the
+.Dv SA_RESTART
+bit in
+.Ar sa_flags .
+The affected system calls include
+.Xr open 2 ,
+.Xr read 2 ,
+.Xr write 2 ,
+.Xr sendto 2 ,
+.Xr recvfrom 2 ,
+.Xr sendmsg 2
+and
+.Xr recvmsg 2
+on a communications channel or a slow device (such as a terminal,
+but not a regular file)
+and during a
+.Xr wait 2
+or
+.Xr ioctl 2 .
+However, calls that have already committed are not restarted,
+but instead return a partial success (for example, a short read count).
+.Pp
+After a
+.Xr fork 2
+or
+.Xr vfork 2
+all signals, the signal mask, the signal stack,
+and the restart/interrupt flags are inherited by the child.
+.Pp
+.Xr Execve 2
+reinstates the default
+action for all signals which were caught and
+resets all signals to be caught on the user stack.
+Ignored signals remain ignored;
+the signal mask remains the same;
+signals that restart pending system calls continue to do so.
+.Pp
+The following is a list of all signals
+with names as in the include file
+.Aq Pa signal.h :
+.Bl -column SIGVTALARMXX "create core imagexxx"
+.It Sy "  NAME  " "	Default Action  " "	Description"
+.It Dv SIGHUP No "	terminate process" "	terminal line hangup"
+.It Dv SIGINT No "	terminate process" "	interrupt program"
+.It Dv SIGQUIT No "	create core image" "	quit program"
+.It Dv SIGILL No "	create core image" "	illegal instruction"
+.It Dv SIGTRAP No "	create core image" "	trace trap"
+.It Dv SIGABRT No "	create core image" Xr 	abort 2
+call (formerly
+.Dv SIGIOT )
+.It Dv SIGEMT No "	create core image" "	emulate instruction executed"
+.It Dv SIGFPE No "	create core image" "	floating-point exception"
+.It Dv SIGKILL No "	terminate process" "	kill program"
+.It Dv SIGBUS No "	create core image" "	bus error"
+.It Dv SIGSEGV No "	create core image" "	segmentation violation"
+.It Dv SIGSYS No "	create core image" "	system call given invalid argument"
+.It Dv SIGPIPE No "	terminate process" "	write on a pipe with no reader"
+.It Dv SIGALRM No "	terminate process" "	real-time timer expired"
+.It Dv SIGTERM No "	terminate process" "	software termination signal"
+.It Dv SIGURG No "	discard signal" "	urgent condition present on socket"
+.It Dv SIGSTOP No "	stop process" "	stop (cannot be caught or ignored)"
+.It Dv SIGTSTP No "	stop process" "	stop signal generated from keyboard"
+.It Dv SIGCONT No "	discard signal" "	continue after stop"
+.It Dv SIGCHLD No "	discard signal" "	child status has changed"
+.It Dv SIGTTIN No "	stop process" "	background read attempted from control terminal"
+.It Dv SIGTTOU No "	stop process" "	background write attempted to control terminal"
+.It Dv SIGIO No "	discard signal" Tn "	I/O"
+is possible on a descriptor (see
+.Xr fcntl 2 )
+.It Dv SIGXCPU No "	terminate process" "	cpu time limit exceeded (see"
+.Xr setrlimit 2 )
+.It Dv SIGXFSZ No "	terminate process" "	file size limit exceeded (see"
+.Xr setrlimit 2 )
+.It Dv SIGVTALRM No "	terminate process" "	virtual time alarm (see"
+.Xr setitimer 2 )
+.It Dv SIGPROF No "	terminate process" "	profiling timer alarm (see"
+.Xr setitimer 2 )
+.It Dv SIGWINCH No "	discard signal" "	Window size change"
+.It Dv SIGINFO No "	discard signal" "	status request from keyboard"
+.It Dv SIGUSR1 No "	terminate process" "	User defined signal 1"
+.It Dv SIGUSR2 No "	terminate process" "	User defined signal 2"
+.El
+.Sh NOTE
+The mask specified in 
+.Fa act
+is not allowed to block
+.Dv SIGKILL
+or
+.Dv SIGSTOP .
+This is done silently by the system.
+.Sh RETURN VALUES
+A 0 value indicated that the call succeeded.  A \-1 return value
+indicates an error occurred and
+.Va errno
+is set to indicated the reason.
+.Sh EXAMPLE
+The handler routine can be declared:
+.Bd -literal -offset indent
+void handler(sig, code, scp)
+int sig, code;
+struct sigcontext *scp;
+.Ed
+.Pp
+Here
+.Fa sig
+is the signal number, into which the hardware faults and traps are
+mapped.
+.Fa Code
+is a parameter that is either a constant
+or the code provided by
+the hardware.
+.Fa Scp
+is a pointer to the
+.Fa sigcontext
+structure (defined in
+.Aq Pa signal.h ) ,
+used to restore the context from before the signal.
+.Sh ERRORS
+.Fn Sigaction
+will fail and no new signal handler will be installed if one
+of the following occurs:
+.Bl -tag -width Er
+.It Bq Er EFAULT
+Either
+.Fa act
+or 
+.Fa oact
+points to memory that is not a valid part of the process
+address space.
+.It Bq Er EINVAL
+.Fa Sig
+is not a valid signal number.
+.It Bq Er EINVAL
+An attempt is made to ignore or supply a handler for
+.Dv SIGKILL
+or
+.Dv SIGSTOP .
+.El
+.Sh STANDARDS
+The
+.Nm sigaction
+function is defined by
+.St -p1003.1-88 .
+The
+.Dv SA_ONSTACK
+and
+.Dv SA_RESTART
+flags are Berkeley extensions,
+as are the signals,
+.Dv SIGTRAP ,
+.Dv SIGEMT ,
+.Dv SIGBUS ,
+.Dv SIGSYS ,
+.Dv SIGURG ,
+.Dv SIGIO ,
+.Dv SIGXCPU ,
+.Dv SIGXFSZ ,
+.Dv SIGVTALRM ,
+.Dv SIGPROF ,
+.Dv SIGWINCH ,
+and
+.Dv SIGINFO .
+Those signals are available on most
+.Tn BSD Ns \-derived
+systems.
+.Sh SEE ALSO
+.Xr kill 1 ,
+.Xr ptrace 2 ,
+.Xr kill 2 ,
+.Xr sigaction 2 ,
+.Xr sigprocmask 2 ,
+.Xr sigsuspend 2 ,
+.Xr sigblock 2 ,
+.Xr sigsetmask 2 ,
+.Xr sigpause 2 ,
+.Xr sigstack 2 ,
+.Xr sigvec 3 ,
+.Xr setjmp 3 ,
+.Xr siginterrupt 3 ,
+.Xr sigsetops 3 ,
+.Xr tty 4