added lots of useful info
diff --git a/Doc/lib/libsignal.tex b/Doc/lib/libsignal.tex
index 52251c4..88116d7 100644
--- a/Doc/lib/libsignal.tex
+++ b/Doc/lib/libsignal.tex
@@ -1,17 +1,57 @@
\section{Built-in Module \sectcode{signal}}
\bimodindex{signal}
-This module provides mechanisms to write signal handlers in Python.
+This module provides mechanisms to use signal handlers in Python.
+Some general rules for working with signals handlers:
-{\bf Warning:} Some care must be taken if both signals and threads
-will be used in the same program. The fundamental thing to remember
-in using signals and threads simultaneously is: always perform
-\code{signal()} operations in the main thread of execution. Any
-thread can perform a \code{alarm()}, \code{getsignal()}, or
-\code{pause()}; only the main thread can set a new signal handler, and
-the main thread will be the only one to receive signals. This means
-that signals can't be used as a means of interthread communication.
-Use locks instead.
+\begin{itemize}
+
+\item
+A handler for a particular signal, once set, remains installed until
+it is explicitly reset (i.e. Python uses the BSD style interface).
+
+\item
+There is no way to ``block'' signals temporarily from critical
+sections (since this is not supported by all Unix flavors).
+
+\item
+Although Python signal handlers are called asynchronously as far as
+the Python user is concerned, they can only occur between the
+``atomic'' instructions of the Python interpreter. This means that
+signals arriving during long calculations implemented purely in C
+(e.g. regular expression matches on large bodies of text) may be
+delayed for an arbitrary time.
+
+\item
+When a signal arrives during an I/O operation, it is possible that the
+I/O operation raises an exception after the signal handler returns.
+This is dependent on the underlying Unix system's semantics regarding
+interrupted system calls.
+
+\item
+Because the C signal handler always returns, it makes little sense to
+catch synchronous errors like \code{SIGFPE} or \code{SIGSEGV}.
+
+\item
+Python installs a small number of signal handlers by default:
+\code{SIGPIPE} is ignored (so write errors on pipes and sockets can be
+reported as ordinary Python exceptions), \code{SIGINT} is translated
+into a \code{KeyboardInterrupt} exception, and \code{SIGTERM} is
+caught so that necessary cleanup (especially \code{sys.exitfunc}) can
+be performed before actually terminating. All of these can be
+overridden.
+
+\item
+Some care must be taken if both signals and threads are used in the
+same program. The fundamental thing to remember in using signals and
+threads simultaneously is: always perform \code{signal()} operations
+in the main thread of execution. Any thread can perform a
+\code{alarm()}, \code{getsignal()}, or \code{pause()}; only the main
+thread can set a new signal handler, and the main thread will be the
+only one to receive signals. This means that signals can't be used as
+a means of interthread communication. Use locks instead.
+
+\end{itemize}
The variables defined in the signal module are:
@@ -40,6 +80,10 @@
those names defined by the system are defined by this module.
\end{datadesc}
+\begin{datadesc}{NSIG}
+ One more than the number of the highest signal number.
+\end{datadesc}
+
The signal module defines the following functions:
\begin{funcdesc}{alarm}{time}
@@ -58,7 +102,11 @@
\begin{funcdesc}{getsignal}{signalnum}
Returns the current signal handler for the signal \var{signalnum}.
The returned value may be a callable Python object, or one of the
- special values \code{signal.SIG_IGN} or \code{signal.SIG_DFL}.
+ special values \code{signal.SIG_IGN}, \code{signal.SIG_DFL} or
+ \code{None}. Here, \code{signal.SIG_IGN} means that the signal was
+ previously ignored, \code{signal.SIG_DFL} means that the default way
+ of handling the signal was previously in use, and \code{None} means
+ that the previous signal handler was not installed from Python.
\end{funcdesc}
\begin{funcdesc}{pause}{}
@@ -71,10 +119,11 @@
Sets the handler for signal \var{signalnum} to the function
\var{handler}. \var{handler} can be any callable Python object, or
one of the special values \code{signal.SIG_IGN} or
- \code{signal.SIG_DFL}. The previous signal handler will be
- returned. (See the UNIX man page \code{signal(2)}.)
+ \code{signal.SIG_DFL}. The previous signal handler will be returned
+ (see the description of \code{getsignal()} above). (See the UNIX
+ man page \code{signal(2)}.)
- If threads are enabled, this function can only be called from the
+ When threads are enabled, this function can only be called from the
main thread; attempting to call it from other threads will cause a
\code{ValueError} exception will be raised.
\end{funcdesc}
diff --git a/Doc/libsignal.tex b/Doc/libsignal.tex
index 52251c4..88116d7 100644
--- a/Doc/libsignal.tex
+++ b/Doc/libsignal.tex
@@ -1,17 +1,57 @@
\section{Built-in Module \sectcode{signal}}
\bimodindex{signal}
-This module provides mechanisms to write signal handlers in Python.
+This module provides mechanisms to use signal handlers in Python.
+Some general rules for working with signals handlers:
-{\bf Warning:} Some care must be taken if both signals and threads
-will be used in the same program. The fundamental thing to remember
-in using signals and threads simultaneously is: always perform
-\code{signal()} operations in the main thread of execution. Any
-thread can perform a \code{alarm()}, \code{getsignal()}, or
-\code{pause()}; only the main thread can set a new signal handler, and
-the main thread will be the only one to receive signals. This means
-that signals can't be used as a means of interthread communication.
-Use locks instead.
+\begin{itemize}
+
+\item
+A handler for a particular signal, once set, remains installed until
+it is explicitly reset (i.e. Python uses the BSD style interface).
+
+\item
+There is no way to ``block'' signals temporarily from critical
+sections (since this is not supported by all Unix flavors).
+
+\item
+Although Python signal handlers are called asynchronously as far as
+the Python user is concerned, they can only occur between the
+``atomic'' instructions of the Python interpreter. This means that
+signals arriving during long calculations implemented purely in C
+(e.g. regular expression matches on large bodies of text) may be
+delayed for an arbitrary time.
+
+\item
+When a signal arrives during an I/O operation, it is possible that the
+I/O operation raises an exception after the signal handler returns.
+This is dependent on the underlying Unix system's semantics regarding
+interrupted system calls.
+
+\item
+Because the C signal handler always returns, it makes little sense to
+catch synchronous errors like \code{SIGFPE} or \code{SIGSEGV}.
+
+\item
+Python installs a small number of signal handlers by default:
+\code{SIGPIPE} is ignored (so write errors on pipes and sockets can be
+reported as ordinary Python exceptions), \code{SIGINT} is translated
+into a \code{KeyboardInterrupt} exception, and \code{SIGTERM} is
+caught so that necessary cleanup (especially \code{sys.exitfunc}) can
+be performed before actually terminating. All of these can be
+overridden.
+
+\item
+Some care must be taken if both signals and threads are used in the
+same program. The fundamental thing to remember in using signals and
+threads simultaneously is: always perform \code{signal()} operations
+in the main thread of execution. Any thread can perform a
+\code{alarm()}, \code{getsignal()}, or \code{pause()}; only the main
+thread can set a new signal handler, and the main thread will be the
+only one to receive signals. This means that signals can't be used as
+a means of interthread communication. Use locks instead.
+
+\end{itemize}
The variables defined in the signal module are:
@@ -40,6 +80,10 @@
those names defined by the system are defined by this module.
\end{datadesc}
+\begin{datadesc}{NSIG}
+ One more than the number of the highest signal number.
+\end{datadesc}
+
The signal module defines the following functions:
\begin{funcdesc}{alarm}{time}
@@ -58,7 +102,11 @@
\begin{funcdesc}{getsignal}{signalnum}
Returns the current signal handler for the signal \var{signalnum}.
The returned value may be a callable Python object, or one of the
- special values \code{signal.SIG_IGN} or \code{signal.SIG_DFL}.
+ special values \code{signal.SIG_IGN}, \code{signal.SIG_DFL} or
+ \code{None}. Here, \code{signal.SIG_IGN} means that the signal was
+ previously ignored, \code{signal.SIG_DFL} means that the default way
+ of handling the signal was previously in use, and \code{None} means
+ that the previous signal handler was not installed from Python.
\end{funcdesc}
\begin{funcdesc}{pause}{}
@@ -71,10 +119,11 @@
Sets the handler for signal \var{signalnum} to the function
\var{handler}. \var{handler} can be any callable Python object, or
one of the special values \code{signal.SIG_IGN} or
- \code{signal.SIG_DFL}. The previous signal handler will be
- returned. (See the UNIX man page \code{signal(2)}.)
+ \code{signal.SIG_DFL}. The previous signal handler will be returned
+ (see the description of \code{getsignal()} above). (See the UNIX
+ man page \code{signal(2)}.)
- If threads are enabled, this function can only be called from the
+ When threads are enabled, this function can only be called from the
main thread; attempting to call it from other threads will cause a
\code{ValueError} exception will be raised.
\end{funcdesc}