Describe IGNORE-SIGNAL and HANDLE-SIGNAL-DEFAULT

doc/scsh-manual/syscalls.tex

@@ -1695,7 +1695,7 @@ delimiter.
            allocated when the file is opened. This will work if the file
            only needs to be opened once.
         \item If the file needs to be opened twice or more, create it in a 
-           protected directory, \eg, \verb|$HOME|.
+           protected directory, \eg, \verb|$HOME|.%$
         \item Ensure that \ex{/var/tmp} has its sticky bit set. This
            requires system administrator privileges.
     \end{enumerate}
@@ -1824,7 +1824,7 @@ The path-searching variants search the directories in the list
 A path-search is not performed if the program name contains
 a slash character---it is used directly. So a program with a name like
 \ex{"bin/prog"} always executes the program \ex{bin/prog} in the current working
-directory. See \verb|$path| and \verb|exec-path-list|, below.
+directory. See \verb|$path| and \verb|exec-path-list|, below.%$
 
 Note that there is no analog to the C function \ex{\urlh{http://www.FreeBSD.org/cgi/man.cgi?query=execv&apropos=0&sektion=0&manpath=FreeBSD+4.3-RELEASE&format=html}{execv()}}.
 To get the effect just do
@@ -1881,7 +1881,7 @@ it with \ex{\%exec}, the file's status might change.
 The only atomic way to do the search is to loop over the candidate
 file names, exec'ing each one and looping when the exec operation fails.
 
-See \cd{$path} and \ex{exec-path-list}, below.
+See \cd{$path} and \ex{exec-path-list}, below.%$
 \end{desc}
 
 \defun  {exit} {[status]} \noreturn
@@ -2591,7 +2591,7 @@ This means that {\Unix} signals are delivered in two stages: first,
 {\Unix} delivers the signal to the {\scm} virtual machine, then
 the {\scm} virtual machine delivers the signal to the executing Scheme program
 as a {\scm} interrupt.
-This ensures that signal delivery happens between two vm instructions,
+This ensures that signal delivery happens between two VM instructions,
 keeping individual instructions atomic.
 
 The {\scm} machine has its own set of interrupts, which includes the
@@ -2670,13 +2670,7 @@ Unix signal & Type & OS Variant \\ \hline\hline
          here.}
 \label{table:uncatchable-signals}
 \end{table}
-Note that scsh does \emph{not} support signal handlers for
+
-``synchronous'' {\Unix} signals, such as \ex{signal/ill} or
-\ex{signal/pipe} (see table~\ref{table:uncatchable-signals}).
-Synchronous occurrences of these signals are better handled by raising
-a Scheme exception.  We recommend you avoid using signal handlers
-unless you absolutely have to; Section \ref{sec:event-interf-interr}
-describes a better interface to signals.
 \begin{defundesc}{signal->interrupt}{\integer}{\integer}
 The programmer maps from {\Unix} signals to {\scm} interrupts with the
 \ex{signal->interrupt} procedure.
@@ -2722,6 +2716,7 @@ the \ex{interrupt-set} function).
 \end{desc}
 
 
+
 \begin{defundesc}{set-interrupt-handler}{interrupt handler}{old-handler}
 Assigns a handler for a given interrupt, 
 and returns the interrupt's old handler.
@@ -2741,6 +2736,10 @@ handler, see \ex{set-enabled-interrupts})
 \note{If you set a handler for the \ex{interrupt/chld} interrupt,
       you may break scsh's autoreaping process machinery. See the
       discussion of autoreaping in section~\ref{sec:proc-objects}.}
+
+\note{We recommend you avoid using interrupt handlers unless you absolutely
+have to; Section \ref{sec:event-interf-interr} describes a better
+interface to handling signals.}
 \end{defundesc}
 
 \begin{defundesc}{interrupt-handler}{interrupt}{handler}
@@ -2750,6 +2749,28 @@ A handler is either \ex{\#f} (ignore), \ex{\#t} (default), or a
 procedure taking an integer argument.
 \end{defundesc}
 
+Note that scsh does \emph{not} support interrupt handlers for
+``synchronous'' {\Unix} signals, such as \ex{signal/ill} or
+\ex{signal/pipe} (see table~\ref{table:uncatchable-signals}).
+Synchronous occurrences of these signals are better handled by raising
+a Scheme exception. There are, however, some rare situtations where it
+is necessary to ignore the occurrence of a synchronous signal. For
+this case, the following procedures exist:
+
+\defun{ignore-signal}{\integer}{\undefined}
+\defunx{handle-signal-default}{\integer}{\undefined}
+\begin{desc}
+  The procedure \ex{ignore-signal} tells the process to ignore the
+  given signal. The procedure \ex{handle-signal-default} resets the
+  signal handler to the default handler.
+
+  These procedures manipulate the raw signal handler of the scsh
+  process and therfore undermine the signal handling facility of the
+  VM.  They are intended to be used for igoring synchronous signals if
+  system calls cannot succeed otherwise. Do not use these procedures
+  for asynchronous signals!
+\end{desc}
+
 %         %set-unix-signal-handler
 %         %unix-signal-handler