Rearranged BSD sections, moved sigstacks out of BSD section.

1 files changed, 143 insertions, 162 deletions

diff --git a/manual/signal.texi b/manual/signal.texi
index 413dedaebe..456cb89b88 100644
--- a/manual/signal.texi
+++ b/manual/signal.texi
@@ -35,9 +35,9 @@ and synchronize.
 * Blocking Signals::            Making the system hold signals temporarily.
 * Waiting for a Signal::        Suspending your program until a signal
                                  arrives. 
+* Signal Stack::                Using a Separate Signal Stack.
 * BSD Signal Handling::         Additional functions for backward
 			         compatibility with BSD.
-* BSD Handler::                 BSD Function to Establish a Handler.
 @end menu
 
 @node Concepts of Signals
@@ -3026,6 +3026,142 @@ This technique takes a few more lines of preparation, but that is needed
 just once for each kind of wait criterion you want to use.  The code
 that actually waits is just four lines.
 
+@node Signal Stack
+@section Using a Separate Signal Stack
+
+A signal stack is a special area of memory to be used as the execution
+stack during signal handlers.  It should be fairly large, to avoid any
+danger that it will overflow in turn; the macro @code{SIGSTKSZ} is
+defined to a canonical size for signal stacks.  You can use
+@code{malloc} to allocate the space for the stack.  Then call
+@code{sigaltstack} or @code{sigstack} to tell the system to use that
+space for the signal stack.
+
+You don't need to write signal handlers differently in order to use a
+signal stack.  Switching from one stack to the other happens
+automatically.  (Some non-GNU debuggers on some machines may get
+confused if you examine a stack trace while a handler that uses the
+signal stack is running.)
+
+There are two interfaces for telling the system to use a separate signal
+stack.  @code{sigstack} is the older interface, which comes from 4.2
+BSD.  @code{sigaltstack} is the newer interface, and comes from 4.4
+BSD.  The @code{sigaltstack} interface has the advantage that it does
+not require your program to know which direction the stack grows, which
+depends on the specific machine and operating system.
+
+@comment signal.h
+@comment BSD
+@deftp {Data Type} {struct sigaltstack}
+This structure describes a signal stack.  It contains the following members:
+
+@table @code
+@item void *ss_sp
+This points to the base of the signal stack.
+
+@item size_t ss_size
+This is the size (in bytes) of the signal stack which @samp{ss_sp} points to.
+You should set this to however much space you allocated for the stack.
+
+There are two macros defined in @file{signal.h} that you should use in
+calculating this size:
+
+@vtable @code
+@item SIGSTKSZ
+This is the canonical size for a signal stack.  It is judged to be
+sufficient for normal uses.
+
+@item MINSIGSTKSZ
+This is the amount of signal stack space the operating system needs just
+to implement signal delivery.  The size of a signal stack @strong{must}
+be greater than this.
+
+For most cases, just using @code{SIGSTKSZ} for @code{ss_size} is
+sufficient.  But if you know how much stack space your program's signal
+handlers will need, you may want to use a different size.  In this case,
+you should allocate @code{MINSIGSTKSZ} additional bytes for the signal
+stack and increase @code{ss_size} accordinly.
+@end vtable
+
+@item int ss_flags
+This field contains the bitwise @sc{or} of these flags:
+
+@vtable @code
+@item SA_DISABLE
+This tells the system that it should not use the signal stack.
+
+@item SA_ONSTACK
+This is set by the system, and indicates that the signal stack is
+currently in use.  If this bit is not set, then signals will be
+delivered on the normal user stack.
+@end vtable
+@end table
+@end deftp
+
+@comment signal.h
+@comment BSD
+@deftypefun int sigaltstack (const struct sigaltstack *@var{stack}, struct sigaltstack *@var{oldstack})
+The @code{sigaltstack} function specifies an alternate stack for use
+during signal handling.  When a signal is received by the process and
+its action indicates that the signal stack is used, the system arranges
+a switch to the currently installed signal stack while the handler for
+that signal is executed.
+
+If @var{oldstack} is not a null pointer, information about the currently
+installed signal stack is returned in the location it points to.  If
+@var{stack} is not a null pointer, then this is installed as the new
+stack for use by signal handlers.
+
+The return value is @code{0} on success and @code{-1} on failure.  If
+@code{sigaltstack} fails, it sets @code{errno} to one of these values:
+
+@table @code
+@item
+@item EINVAL
+You tried to disable a stack that was in fact currently in use.
+
+@item ENOMEM
+The size of the alternate stack was too small.  
+It must be greater than @code{MINSIGSTKSZ}.
+@end table
+@end deftypefun
+
+Here is the older @code{sigstack} interface.  You should use
+@code{sigaltstack} instead on systems that have it.
+
+@comment signal.h
+@comment BSD
+@deftp {Data Type} {struct sigstack}
+This structure describes a signal stack.  It contains the following members:
+
+@table @code
+@item void *ss_sp
+This is the stack pointer.  If the stack grows downwards on your
+machine, this should point to the top of the area you allocated.  If the
+stack grows upwards, it should point to the bottom.
+
+@item int ss_onstack
+This field is true if the process is currently using this stack.
+@end table
+@end deftp
+
+@comment signal.h
+@comment BSD
+@deftypefun int sigstack (const struct sigstack *@var{stack}, struct sigstack *@var{oldstack})
+The @code{sigstack} function specifies an alternate stack for use during
+signal handling.  When a signal is received by the process and its
+action indicates that the signal stack is used, the system arranges a
+switch to the currently installed signal stack while the handler for
+that signal is executed.
+
+If @var{oldstack} is not a null pointer, information about the currently
+installed signal stack is returned in the location it points to.  If
+@var{stack} is not a null pointer, then this is installed as the new
+stack for use by signal handlers.
+
+The return value is @code{0} on success and @code{-1} on failure.
+@end deftypefun
+
 @node BSD Signal Handling
 @section BSD Signal Handling
 
@@ -3034,19 +3170,6 @@ from BSD Unix.  These facilities were an advance, in their time; today,
 they are mostly obsolete, and supported mainly for compatibility with
 BSD Unix.
 
-They do provide one feature that is not available through the POSIX
-functions: You can specify a separate stack for use in certain signal
-handlers.  Using a signal stack is the only way you can handle a signal
-caused by stack overflow.
-
-@menu
-* POSIX vs BSD::                Overview comparing BSD and POSIX signal
-                                 functions. 
-@end menu
-
-@node POSIX vs BSD
-@subsection POSIX and BSD Signal Facilities 
-
 There are many similarities between the BSD and POSIX signal handling
 facilities, because the POSIX facilities were inspired by the BSD
 facilities.  Besides having different names for all the functions to
@@ -3063,19 +3186,18 @@ primitive should fail or resume.  The POSIX facilities make system
 calls fail unless you specify that they should resume.  With the BSD
 facility, the default is to make system calls resume unless you say they
 should fail.  @xref{Interrupted Primitives}.
-
-@item
-BSD Unix has a concept of a @dfn{signal stack}.  This is an alternate
-stack that can be used during the execution of signal handler functions,
-instead of its normal execution stack.
-@cindex signal stack
 @end itemize
 
 The BSD facilities are declared in @file{signal.h}.
 @pindex signal.h
 
+@menu
+* BSD Handler::                 BSD Function to Establish a Handler.
+* Blocking in BSD::             BSD Functions for Blocking Signals. 
+@end menu
+
 @node BSD Handler
-@section BSD Function to Establish a Handler
+@subsection BSD Function to Establish a Handler
 
 @comment signal.h
 @comment BSD
@@ -3147,11 +3269,6 @@ true, handling @var{signum} causes these primitives to fail with error
 code @code{EINTR}.  @xref{Interrupted Primitives}.
 @end deftypefun
 
-@menu
-* Blocking in BSD::             BSD Functions for Blocking Signals. 
-* Signal Stack::                Using a Separate Signal Stack.
-@end menu
-
 @node Blocking in BSD
 @subsection BSD Functions for Blocking Signals 
 
@@ -3197,139 +3314,3 @@ for a Signal}):  it sets the calling process's signal mask to @var{mask},
 and waits for a signal to arrive.  On return the previous set of blocked
 signals is restored.
 @end deftypefun
-
-@node Signal Stack
-@subsection Using a Separate Signal Stack
-
-A signal stack is a special area of memory to be used as the execution
-stack during signal handlers.  It should be fairly large, to avoid any
-danger that it will overflow in turn; the macro @code{SIGSTKSZ} is
-defined to a canonical size for signal stacks.  You can use
-@code{malloc} to allocate the space for the stack.  Then call
-@code{sigaltstack} or @code{sigstack} to tell the system to use that
-space for the signal stack.
-
-You don't need to write signal handlers differently in order to use a
-signal stack.  Switching from one stack to the other happens
-automatically.  (Some non-GNU debuggers on some machines may get
-confused if you examine a stack trace while a handler that uses the
-signal stack is running.)
-
-There are two interfaces for telling the system to use a separate signal
-stack.  @code{sigstack} is the older interface, which comes from 4.2
-BSD.  @code{sigaltstack} is the newer interface, and comes from 4.4
-BSD.  The @code{sigaltstack} interface has the advantage that it does
-not require your program to know which direction the stack grows, which
-depends on the specific machine and operating system.
-
-@comment signal.h
-@comment BSD
-@deftp {Data Type} {struct sigaltstack}
-This structure describes a signal stack.  It contains the following members:
-
-@table @code
-@item void *ss_sp
-This points to the base of the signal stack.
-
-@item size_t ss_size
-This is the size (in bytes) of the signal stack which @samp{ss_sp} points to.
-You should set this to however much space you allocated for the stack.
-
-There are two macros defined in @file{signal.h} that you should use in
-calculating this size:
-
-@vtable @code
-@item SIGSTKSZ
-This is the canonical size for a signal stack.  It is judged to be
-sufficient for normal uses.
-
-@item MINSIGSTKSZ
-This is the amount of signal stack space the operating system needs just
-to implement signal delivery.  The size of a signal stack @strong{must}
-be greater than this.
-
-For most cases, just using @code{SIGSTKSZ} for @code{ss_size} is
-sufficient.  But if you know how much stack space your program's signal
-handlers will need, you may want to use a different size.  In this case,
-you should allocate @code{MINSIGSTKSZ} additional bytes for the signal
-stack and increase @code{ss_size} accordinly.
-@end vtable
-
-@item int ss_flags
-This field contains the bitwise @sc{or} of these flags:
-
-@vtable @code
-@item SA_DISABLE
-This tells the system that it should not use the signal stack.
-
-@item SA_ONSTACK
-This is set by the system, and indicates that the signal stack is
-currently in use.  If this bit is not set, then signals will be
-delivered on the normal user stack.
-@end vtable
-@end table
-@end deftp
-
-@comment signal.h
-@comment BSD
-@deftypefun int sigaltstack (const struct sigaltstack *@var{stack}, struct sigaltstack *@var{oldstack})
-The @code{sigaltstack} function specifies an alternate stack for use
-during signal handling.  When a signal is received by the process and
-its action indicates that the signal stack is used, the system arranges
-a switch to the currently installed signal stack while the handler for
-that signal is executed.
-
-If @var{oldstack} is not a null pointer, information about the currently
-installed signal stack is returned in the location it points to.  If
-@var{stack} is not a null pointer, then this is installed as the new
-stack for use by signal handlers.
-
-The return value is @code{0} on success and @code{-1} on failure.  If
-@code{sigaltstack} fails, it sets @code{errno} to one of these values:
-
-@table @code
-@item
-@item EINVAL
-You tried to disable a stack that was in fact currently in use.
-
-@item ENOMEM
-The size of the alternate stack was too small.  
-It must be greater than @code{MINSIGSTKSZ}.
-@end table
-@end deftypefun
-
-Here is the older @code{sigstack} interface.  You should use
-@code{sigaltstack} instead on systems that have it.
-
-@comment signal.h
-@comment BSD
-@deftp {Data Type} {struct sigstack}
-This structure describes a signal stack.  It contains the following members:
-
-@table @code
-@item void *ss_sp
-This is the stack pointer.  If the stack grows downwards on your
-machine, this should point to the top of the area you allocated.  If the
-stack grows upwards, it should point to the bottom.
-
-@item int ss_onstack
-This field is true if the process is currently using this stack.
-@end table
-@end deftp
-
-@comment signal.h
-@comment BSD
-@deftypefun int sigstack (const struct sigstack *@var{stack}, struct sigstack *@var{oldstack})
-The @code{sigstack} function specifies an alternate stack for use during
-signal handling.  When a signal is received by the process and its
-action indicates that the signal stack is used, the system arranges a
-switch to the currently installed signal stack while the handler for
-that signal is executed.
-
-If @var{oldstack} is not a null pointer, information about the currently
-installed signal stack is returned in the location it points to.  If
-@var{stack} is not a null pointer, then this is installed as the new
-stack for use by signal handlers.
-
-The return value is @code{0} on success and @code{-1} on failure.
-@end deftypefun