diff options
Diffstat (limited to 'src/lib/bsdsignal.c.pamphlet')
| -rw-r--r-- | src/lib/bsdsignal.c.pamphlet | 320 |
1 files changed, 0 insertions, 320 deletions
diff --git a/src/lib/bsdsignal.c.pamphlet b/src/lib/bsdsignal.c.pamphlet deleted file mode 100644 index 5807659b..00000000 --- a/src/lib/bsdsignal.c.pamphlet +++ /dev/null @@ -1,320 +0,0 @@ -\documentclass{article} -\usepackage{axiom} - -\newcommand{\var}[1]{\textsl{#1}} - -\title{\File{src/lib/bsdsignal.c} Pamphlet} -\author{The Axiom Team} - -\begin{document} -\maketitle - -\begin{abstract} -\end{abstract} -\eject - -\tableofcontents -\newpage - -\section{Executive Overview} - -\section{Signals} - -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 -normally blocked from further occurrence, the current process context is -saved, -and a new one is built. A process may specify a \emph{handler} to -which a signal -is delivered, or specify that a signal is to be \emph{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 \emph{blocked}, in which case its delivery is -postponed until it is \emph{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 \emph{signal stack}. - -Signal routines normally execute with the signal that caused their invocation -\emph{blocked}, but other signals may yet occur. A global \emph{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 \emph{[[sigprocmask]](2)} call, or -when a signal is delivered to the process. - -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 \emph{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 muliple 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 retuned by the -\emph{[[sigpending]](2)} system call. 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. - -When a signal is delivered to a proces a new signal mask is installed for the -duration of the process's signal handler (or until a \emph{[[sigprocmask]](2)} -system 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. - -The \emph{[[sigaction]]()} system call assigns an action for a signal -specified by \var{sig}. If \var{act} is non-zero, it specifies an action -([[SIG_DFL]], [[SIG_IGN]], or a handler routine) and mask to be used when -delivering the specified signal. -If \var{oact} is non-zero, the previous handling information for the signal is -returned to the user. - -Once a signal handler is installed, it normally remains installed until -another -[[sigaction()]] system call is made, or an \emph{[[execve]](2)} is performed. -A -signal-specific default action may be reset by setting [[sa_handler]] to -[[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 [[sa_handler]] is [[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 -[[sa_handler]] is set to [[SIG_IGN]] current and pending instances of the -signal -are ignored and discarded. - -Options may be specified by setting [[sa_flags]]. The meaning of the various -bits is as follows: -\begin{tabular}{ll} -SA\_NOCLDSTOP & If this bit is set when installing a catching function for\\ - & the SIGCHLD signal, the SIGCHLD signal will be generated only\\ - & when a child process exits, not when a child process stops.\\ -SA\_NOCLDWAIT & If this bit is set when calling {\sl sigaction()} for the\\ - & SIGCHLD signal, the system will not create zombie processes\\ - & when children of the calling process exit. If the calling\\ - & process subsequently issues a {\sf wait()} (or equivalent),\\ - & it blocks until all of the calling process's child processes\\ - & terminate, and then returns a value of -1 with errno set to\\ - & ECHILD.\\ -SA\_ONSTACK & If this bit is set, the system will deliver the signal to\\ - & the process on a {\sl signal stack}, specified with\\ - & {\bf sigaltstack(2)}.\\ -SA\_NODEFER & If this bit is set, further occurrences of the delivered\\ - & signal are not masked during the execution of the handler.\\ -SA\_RESETHAND & If this bit is set, the handler is reset back to SIG\_DFL\\ - & at the moment the signal is delivered.\\ -SA\_RESTART & See the paragraph below\\ -SA\_SIGINFO & If this bit is set, the handler function is assumed to be\\ - & pointed to by the sa\_sigaction member of struct sigaction\\ - & and should match the prototype shown above or as below in\\ - & EXAMPLES. This bit should not be set when assigning SIG\_DFL\\ - & or SIG\_IGN -\end{tabular} - -If a signal is caught during the system calls listed below, the call may be -forced to terminate with the error [[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 SA\_RESTART bit in {\sl sa\_flags}. -The affected system calls include {\bf open(2)}, {\bf read(2)}, {\bf write(2)}, -{\bf sendto(2)}, {\bf recvfrom(2)}, {\bf sendmsg(2)} and {\bf recvmsg(2)} -on a communications channel or a slow device (such as a terminal, but not a -regular file) and during a {\bf wait(2)} or {\bf ioctl(2)}. However, calls -that have already committed are not restarted, but instead return a partial -success (for example, a short read count). - -After a {\bf fork(2)} or {\bf vfork(2)} all signals, the signal mask, the -signal stack, and the restart/interrupt flags are inherited by the child. - -The {\bf execve(2)} system call 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. - -The following is a list of all signals with names as in the include file -{\sl <signal.h>}: - -\begin{tabular}{lll} -{\bf NAME} & {\bf Default Action} & Description\\ -SIGHUP & terminate process & terminal line hangup\\ -SIGINT & terminate process & interrupt program\\ -SIGQUIT & create core image & quit program\\ -SIGILL & create core image & illegal instruction\\ -SIGTRAP & create core image & trace trap\\ -SIGABRT & create core image & {\bf abort(3)} call (formerly SIGIOT)\\ -SIGEMT & create core image & emulate instruction executed\\ -SIGFPE & create core image & floating-point exception\\ -SIGKILL & terminate process & kill program\\ -SIGBUS & create core image & bus error\\ -SIGSEGV & create core image & segmentation violation\\ -SIGSYS & create core image & non-existent system call invoked\\ -SIGPIPE & terminate process & write on a pipe with no reader\\ -SIGALRM & terminate process & real-time timer expired\\ -SIGTERM & terminate process & software termination signal\\ -SIGURG & discard signal & urgent condition present on socket\\ -SIGSTOP & stop process & stop (cannot be caught or ignored)\\ -SIGSTP & stop process & stop signal generated from keyboard\\ -SIGCONT & discard signal & continue after stop\\ -SIGCHLD & discard signal & child status has changed\\ -SIGTTIN & stop process & background read attempted from \\ - & & control terminal\\ -SIGTTOU & stop process & background write attempted from\\ - & & control terminal\\ -SIGIO & discard signal & I/O is possible on a descriptor {\bf fcntl(2)}\\ -SIGXCPU & terminate process & cpu time limit exceeded {\bf setrlimit(2)}\\ -SIGXFSZ & terminate process & file size limit exceeded {\bf setrlimit(2)}\\ -SIGVTALRM & terminate process & virtual time alarm {\bf setitimer(2)}\\ -SIGPROF & terminate process & profiling timer alarm {\bf setitimer(2)}\\ -SIGWINCH & discard signal & Window size change\\ -SIGINFO & discard signal & status request from keyboard\\ -SIGUSR1 & terminate process & User defined signal 1\\ -SIGUSR2 & terminate process & User defined signal 2 -\end{tabular} - -The {\sl sigaction()} function returns the value 0 if successful; otherwise -the value -1 is returned and the global variable {\sl errno} is set to indicate -the error. - -Signal handlers should have either the ANSI C prototype: -\begin{verbatim} - void handler(int); -\end{verbatim} -or the POSIX SA\_SIGINFO prototype: -\begin{verbatim} - void handler(int, siginfo\_t *info, ucontext\_t *uap); -\end{verbatim} - -The handler function should match the SA\_SIGINFO prototype if the SA\_SIGINFO -bit is set in flags. It then should be pointed to by the sa\_sigaction member -of struct sigaction. Note that you should not assign SIG\_DFL or SIG\_IGN this way. - -If the SA\_SIGINFO flag is not set, the handler function should match either -the ANSI C or traditional BSD prototype and be pointed to by the sa\_handler -member of struct sigaction. In practice, FreeBSD always sends the three -arguments of the latter and since the ANSI C prototype is a subset, both -will work. The sa\_handler member declaration in FreeBSD include files is -that of ANSI C (as required by POSIX), so a function pointer of a BSD-style -function needs to be casted to compile without warning. The traditional BSD -style is not portable and since its capabilities are a full subset of a -SA\_SIGNFO handler its use is deprecated. - -The {\sl sig} argument is the signal number, one of the SIG\ldots values from -{\sl <signal.h>}. - -The {\sl code} argument of the BSD-style handler and the si\_code member of the -info argument to a SA\_SIGINFO handler contain a numeric code explaining the -cause of the signal, usually on of the SI\_\ldots values from {\sl <sys/signal.h>} -or codes specific to a signal, i.e. one of the FPE\_\ldots values for SIGFPE. - -The {\sl uap} argument to a POSIX SA\_SIGINFO handler points to an instance of -ucontext\_t. - -The {\bf sigaction()} system call will fail and no new signal handler will be -installed if one of the following occurs: -\begin{tabular}{ll} -EFAULT & Either {\sl act} or {\sl oact} points to memory that is not a\\ - & valid part of the process address space\\ -EINVAL & The {\sl sig} argument is not a valid signal number\\ -EINVAL & An attempt is made to ignore or supply a handler for SIGKILL\\ - & or SIGSTOP -\end{tabular} -\section{MAC OSX and BSD platform change} -<<*>>= -<<license>> - -#include "axiom-c-macros.h" -#include "bsdsignal.h" - -@ -The MACOSX platform is broken because no matter what you do it seems to -include files from [[/usr/include/sys]] ahead of [[/usr/include]]. On linux -systems these files include themselves which causes an infinite regression -of includes that fails. GCC gracefully steps over that problem but the -build fails anyway. On MACOSX the [[/usr/include/sys]] versions -of files are badly broken with respect to the [[/usr/include]] versions. -<<*>>= -#if defined(MACOSXplatform) -#include "/usr/include/signal.h" -#else -#include <signal.h> -#endif - -#include "bsdsignal.H1" - - -SignalHandlerFunc -bsdSignal(int sig, SignalHandlerFunc action, int restartSystemCall) -{ -#if HAVE_DECL_SIGACTION - - struct sigaction in,out; - in.sa_handler = action; - /* handler is reinstalled - calls are restarted if restartSystemCall */ -@ - -We needed to change [[SIGCLD]] to [[SIGCHLD]] for the [[MAC OSX]] platform -and we need to create a new platform variable. This change is made to -propogate that platform variable. -<<*>>= -#ifdef SA_RESTART - if(restartSystemCall) in.sa_flags = SA_RESTART; - else in.sa_flags = 0; -#elif defined(SA_INTERRUPT) - if (restartSystemCall) in.sa_flags = 0; - else in.sa_flags = SA_INTERRUPT; -#else - in.sa_flags = 0; -#endif - - return (sigaction(sig, &in, &out) ? (SignalHandlerFunc) -1 : - (SignalHandlerFunc) out.sa_handler); -#else /* !HAVE_DECL_SIGACTION */ - return (SignalHandlerFunc) -1; -#endif /* HAVE_DECL_SIGACTION */ -} - - -@ -\section{License} -<<license>>= -/* -Copyright (c) 1991-2002, The Numerical ALgorithms Group Ltd. -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - - Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - - 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. - - - Neither the name of The Numerical ALgorithms Group Ltd. 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 COPYRIGHT HOLDERS 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 COPYRIGHT OWNER -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. -*/ -@ -\newpage -\begin{thebibliography}{99} -\bibitem{1} nothing -\end{thebibliography} -\end{document} |