Decorate definitions with info about header file and source.

1 files changed, 406 insertions, 14 deletions

diff --git a/manual/signal.texi b/manual/signal.texi
index bf5c48a1f6..6a1ed1c022 100644
--- a/manual/signal.texi
+++ b/manual/signal.texi
@@ -28,6 +28,8 @@ synchronize.
 * Generating Signals::     	How to send a signal to a process.
 * Blocking Signals::		Making the system hold signals temporarily.
 * Waiting for a Signal::	Suspending your program until a signal arrives.
+* BSD Signal Handling::		Additional functions for backward
+				 compatibility with BSD.
 @end menu
 
 
@@ -112,6 +114,7 @@ integer constant.
 * Miscellanous Signals::	Used to report various random conditions.
 * Job Control Signals:: 	Signals used to support job control.
 * Other Signals::		Implementations can support other signals.
+* Signal Messages::		Printing a message describing a signal.
 @end menu
 
 @node Program Error Signals
@@ -129,6 +132,8 @@ for them that returns normally, your program will probably break
 horribly unless the signals were generated by @code{raise} or
 @code{kill} instead of a real program bug.
 
+@comment signal.h
+@comment ANSI
 @defvr Macro SIGFPE
 The @code{SIGFPE} signal reports a fatal arithmetic error.  Although
 the name is derived from ``floating-point exception'', this signal
@@ -154,6 +159,8 @@ you'll have to look at the documentation for your specific computer and
 operating system to find out how.
 @end defvr
 
+@comment signal.h
+@comment ANSI
 @defvr Macro SIGILL
 The name of this signal is derived from ``illegal instruction''; it
 means your program is trying to execute garbage or a privileged
@@ -167,6 +174,8 @@ return address from a function call.
 @end defvr
 @cindex illegal instruction
 
+@comment signal.h
+@comment ANSI
 @defvr Macro SIGSEGV
 This signal is generated when a program tries to read or write outside
 the memory that is allocated for it.  (Actually, the signals only occur
@@ -181,7 +190,8 @@ step through an array, but fail to check for the end of the array.
 @end defvr
 @cindex segment violation
 
-@comment this is a GNU extension.
+@comment signal.h
+@comment BSD
 @defvr Macro SIGBUS
 This signal is generated when an invalid pointer is dereferenced.  Like
 @code{SIGSEGV}, this signal is typically the result of dereferencing a
@@ -204,12 +214,16 @@ for each one.
 The (obvious) default action for all of these signals is to cause the
 process to terminate.
 
+@comment signal.h
+@comment ANSI
 @defvr Macro SIGABRT
 This signal is used to indicate abnormal program termination.  The
 @code{abort} function (@xref{Aborting a Program}) uses this signal.
 @end defvr
 @cindex abort signal
 
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SIGHUP
 The @code{SIGHUP} (``hang-up'') signal is used to report that the user's
 terminal is disconnected, perhaps because the cable was pulled out or
@@ -222,6 +236,8 @@ information, @pxref{Process Termination Details}.
 @end defvr
 @cindex hangup signal
 
+@comment signal.h
+@comment ANSI
 @defvr Macro SIGINT
 The @code{SIGINT} (``program interrupt'') signal is sent when the user
 wants to abort the program by pressing @kbd{C-c}, or whatever equivalent
@@ -235,6 +251,8 @@ information to a file, release locks on resources, and the like.
 @end defvr
 @cindex interrupt signal
 
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SIGQUIT
 The @code{SIGQUIT} signal is similar to @code{SIGINT}, except that it's
 controlled by a different key --- the QUIT character, usually @kbd{C-\}
@@ -243,6 +261,8 @@ information about terminal driver support.
 @end defvr
 @cindex quit signal
 
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SIGKILL
 The @code{SIGKILL} signal is used to cause immediate program termination.
 It cannot be caught or ignored, and is therefore always fatal.  It is
@@ -250,6 +270,8 @@ also not possible to block this signal.
 @end defvr
 @cindex kill signal
 
+@comment signal.h
+@comment ANSI
 @defvr Macro SIGTERM
 The @code{SIGTERM} signal is a generic signal used to cause program
 termination.  Unlike @code{SIGKILL}, this signal can be blocked, caught,
@@ -270,6 +292,8 @@ If you simply want an alarm to wake up your process, though, this is not
 very useful.  So, if you want to use these signals you should provide a
 signal handler for them.
 
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SIGALRM
 This signal is typically used to indicate expiration of a timer that
 measures real or clock time.  It is used by the @code{alarm} function,
@@ -277,14 +301,16 @@ for example.
 @end defvr
 @cindex alarm signal
 
-@comment This is derived from BSD.
+@comment signal.h
+@comment BSD
 @defvr Macro SIGVTALRM
 This signal is typically used to indicate expiration of a timer that
 measures CPU time used by the current process.  The name is an abbreviation
 for ``virtual alarm''.
 @end defvr
 
-@comment This is derived from BSD.
+@comment signal.h
+@comment BSD
 @defvr Macro SIGPROF
 This signal is typically used to indicate expiration of a profiling timer.
 @end defvr
@@ -296,6 +322,8 @@ This signal is typically used to indicate expiration of a profiling timer.
 These signals are used to report various other conditions.  The default
 action for all of them is to cause the process to terminate.
 
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SIGPIPE
 If you use pipes, you have to design your application so that one
 process has opened the pipe for reading before another starts writing.
@@ -314,8 +342,12 @@ Pipes are discussed in more detail in @ref{Pipes and FIFOs}.
 @cindex pipe signal
 @cindex broken pipe signal
 
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SIGUSR1
 @end defvr
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SIGUSR2
 The @code{SIGUSR1} and @code{SIGUSR2} signals are set aside for you to
 use any way you want.  They're useful for interprocess communication.
@@ -338,6 +370,8 @@ You should generally leave these signals alone unless you really
 understand how job control works.  Go read about job control before
 you mess with them; @pxref{Job Control}.
 
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SIGCHLD
 This signal is sent to a parent process whenever one of its child
 processes terminates or stops.
@@ -350,6 +384,8 @@ your new handler applies to those processes or not.
 @end defvr
 @cindex child process signal
 
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SIGCONT
 The @code{SIGCONT} signal is used to tell a stopped process to continue.
 The default behavior for this signal is to make the process continue if
@@ -357,12 +393,16 @@ it is stopped, and for it to be ignored otherwise.
 @end defvr
 @cindex continue signal
 
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SIGSTOP
 The @code{SIGSTOP} signal stops the process.  It cannot be caught or
 ignored.
 @end defvr
 @cindex stop signals
 
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SIGTSTP
 The @code{SIGTSTP} signal is an interactive stop signal.  Unlike
 @code{SIGSTOP}, this signal can be caught or ignored.  Typically, you
@@ -374,6 +414,8 @@ This signal is generated when the user types the SUSP character
 support, @pxref{Special Characters}.
 @end defvr
 
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SIGTTIN
 A process cannot read from the the user's terminal while it is running 
 as a background job.  When any process in a background job tries to
@@ -383,6 +425,8 @@ stop the process.  For more information about how this interacts with
 the terminal driver, @pxref{Access to the Controlling Terminal}.
 @end defvr
 
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SIGTTOU
 This is similar to @code{SIGTTIN}, but is used when a process in a
 background job attempts to write to the terminal.  Again, the default
@@ -431,6 +475,98 @@ block signals you don't know anything about, or try to establish some
 catch-all handler to take care of all random signals delivered to your
 program.
 
+@comment signal.h
+@comment GNU
+@defvr Macro NSIG
+The value of this symbolic constant is the total number of signals
+defined.
+@end defvr
+
+@strong{Incomplete:}  The other signals listed are:
+
+@table @code
+@item SIGCLD
+Obsolete name for @code{SIGCHLD}.
+
+@item SIGTRAP
+Generated by the machine's breakpoint instruction.  Used by debuggers.
+Default action is to dump core.
+
+@item SIGIOT
+Generated by the PDP-11 ``iot'' instruction; equivalent to @code{SIGABRT}.
+Default action is to dump core.
+
+@item SIGEMT
+Emulator trap, such as when you execute an unsupported instruction.
+Default action is to dump core.
+
+@item SIGSYS
+Bad system call.
+Default action is to dump core.
+
+@item SIGURG
+Urgent data on a socket.  You don't get this without explicitly setting
+up some combination of @code{fcntl} and/or @code{ioctl} first.
+Default action is to ignore it.
+
+@code SIGPOLL
+This is a System V thing, more or less equivalent to @code{SIGIO}.
+
+@code SIGIO
+Asynchronous input available; set @code{O_ASYNC} flag on file descriptor
+with @code{fcntl}; use @code{F_SETOWN} to select process to receive
+the signal.  Usually you send it to yourself
+Default action is to ignore it.
+
+@code SIGXCPU
+CPU time limit exceeded.
+Default action is program termination.
+
+@code SIGXFSZ
+File size limit exceeded.
+Default action is program termination.
+
+@code SIGWINCH
+Window size change.  Sent by the system in response to @code{TIOCSWINSZ}
+ioctl.
+Default action is to ignore it.
+@end table
+
+
+@node Signal Messages
+@subsection Signal Messages
+
+You can use the @code{strsignal} and @code{psignal} functions to get or
+print a message string describing a signal.  The prototype for
+@code{strsignal} is in @file{<string.h>}, and that for @code{psignal} in
+@file{<stdio.h>}.
+
+@comment string.h
+@comment GNU
+@deftypefun {char *} strsignal (int @var{signum})
+This function returns a pointer to a statically-allocated string
+containing a message describing the signal @var{signum}.  You
+should not modify the contents of this string; and, since it can be
+rewritten on subsequent calls, you should save a copy of it if you need
+to reference it later.
+@end deftypefun
+
+@comment stdio.h
+@comment GNU
+@deftypefun void psignal (int @var{signum}, const char *@var{message})
+This function prints a message describing the signal @var{signum}
+to the stream @code{stderr}; @pxref{Standard Streams}.
+
+If you call @code{psignal} with a @var{message} that is either a null
+pointer or an empty string, @code{psignal} just prints the message 
+corresponding to @var{signum}, adding a trailing newline.
+
+If you supply a non-null @var{message} argument, then @code{psignal}
+prefixes its output with this string.  It adds a colon and a space 
+character to separate the @var{message} from the string corresponding
+to @var{signum}.
+@end deftypefun
+
 
 @node Specifying Signal Actions
 @section Specifying Signal Actions
@@ -456,6 +592,8 @@ The @code{signal} function provides a simple interface for establishing
 an action for a particular signal.  The function and associated macros
 are declared in the header file @file{<signal.h>}.
 
+@comment signal.h
+@comment GNU
 @deftp {Data Type} __sighandler_t
 This is the type of signal handler functions.  Signal handlers take one
 integer argument specifying the signal number, and have return type
@@ -466,6 +604,8 @@ void @var{handler} (int @var{signum})
 @end example
 @end deftp
 
+@comment signal.h
+@comment ANSI
 @deftypefun __sighandler_t signal (int @var{signum}, __sighandler_t @var{action})
 The @code{signal} function establishes @var{action} as the action for
 the signal @var{signum}.
@@ -517,18 +657,32 @@ caught), it returns @code{SIG_ERR} instead, and sets @code{errno} to a
 positive value.
 @end deftypefun
 
+@comment signal.h
+@comment SVID
+@deftypefun __sighandler_t ssignal (int @var{signum}, __sighandler_t @var{action})
+The @code{ssignal} function does the same thing as @code{signal}; it is
+provided only for compatibility with SVID.
+@end deftypefun
+
+
+@comment signal.h
+@comment ANSI
 @defvr Macro SIG_DFL
 The value of this macro is an object of the appropriate type for use as
 the @var{action} argument to the @code{signal} function.  It tells the
 system to use the default handling for the signal.
 @end defvr
 
+@comment signal.h
+@comment ANSI
 @defvr Macro SIG_IGN
 The value of this macro is an object of the appropriate type for use as
 the @var{action} argument to the @code{signal} function.  It tells the
 system to ignore the signal.
 @end defvr
 
+@comment signal.h
+@comment ANSI
 @defvr Macro SIG_ERR
 The value of this macro is an object of the appropriate type for the
 return value from the @code{signal} function.  It is used as the return
@@ -569,6 +723,8 @@ expense of more complexity.
 
 This function is declared in @file{<signal.h>}.
 
+@comment signal.h
+@comment POSIX.1
 @deftp {Data Type} {struct sigaction}
 Structures of type @code{sigaction} are used to specify signal actions
 for the @code{sigaction} function.  It contains at least the following
@@ -591,7 +747,9 @@ the signal.  These are described in more detail in @ref{Sigaction Flags}.
 @end table
 @end deftp
 
-@deftypefun int sigaction (int @var{signum}, const struct sigaction @var{*action}, struct sigaction @var{*old_action})
+@comment signal.h
+@comment POSIX.1
+@deftypefun int sigaction (int @var{signum}, const struct sigaction *@var{action}, struct sigaction *@var{old_action})
 The @var{action} argument is used to set up a new action for the signal
 @var{signum}, while the @var{old_action} argument is used to return
 information about the action previously associated with this symbol.
@@ -717,6 +875,8 @@ flags together, and assign them to the @code{sa_flags} member of your
 
 These macros are defined in the header file @file{<signal.h>}.
 
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SA_NOCLDSTOP
 The value of this macro is an integer constant that can be used as a
 flag for @code{sa_flags} when setting up an action for the
@@ -726,15 +886,15 @@ By default, @code{SIGCHLD} is delivered for both terminated children and
 stopped children.
 @end defvr
 
-@comment this is a BSD extension
+@comment signal.h
+@comment BSD
 @defvr Macro SA_ONSTACK
-If this flag is set, the system delivers the signal to the process on
-the signal stack.
-
-@strong{Incomplete:}  This is specified with the @code{sigstack} function.
+If this flag is set, the system uses the signal stack when delivering
+the signal.  @xref{BSD Signal Handling}.
 @end defvr
 
-@comment this is a BSD extension
+@comment signal.h
+@comment BSD
 @defvr Macro SA_RESTART
 If this flag is set, system calls interrupted by a signal return with
 an @code{EINTR} error instead of restarting.
@@ -1018,6 +1178,8 @@ the program that manipulate the variables, including in the handlers
 themselves.  @xref{Blocking Signals}, for information on how to do this.
 @end itemize
 
+@comment signal.h
+@comment ANSI
 @deftp {Data Type} sig_atomic_t
 This is an integer data type.  It identifies a type of object that can
 be accessed as an atomic entity, even in the presence of asynchronous
@@ -1045,6 +1207,8 @@ another process.
 A process can send itself a signal with the @code{raise} function.
 This function is declared in @file{<signal.h>}.
 
+@comment signal.h
+@comment ANSI
 @deftypefun int raise (int @var{signum})
 The @code{raise} function sends the signal @var{signum} to the calling
 process.  It returns zero if successful and a nonzero value if it fails.
@@ -1052,6 +1216,13 @@ About the only reason for failure would be if the value of @var{signum}
 is invalid.
 @end deftypefun
 
+@comment signal.h
+@comment SVID
+@deftypefun int gsignal (int @var{signum})
+The @code{gsignal} function does the same thing as @code{raise}; it is
+provided only for compatibility with SVID.
+@end deftypefun
+
 One convenient use for @code{raise} is to reproduce the default behavior
 of a signal that you have trapped.  For instance, suppose a user of your
 program types the SUSP character (usually @kbd{C-z}; @pxref{Special
@@ -1127,6 +1298,8 @@ This facility is declared in the header file @file{<sys/time.h>}.  The
 @code{alarm} function, declared in @file{<unistd.h>}, provides a somewhat
 simpler interface for setting the real-time timer.
 
+@comment sys/time.h
+@comment BSD
 @deftp {Data Type} {struct itimerval}
 This structure is used to specify when a timer should expire.  It contains
 the following members:
@@ -1144,6 +1317,8 @@ The @code{struct timeval} data type is described in @ref{High-Resolution
 Calendar}.
 @end deftp
 
+@comment sys/time.h
+@comment BSD
 @deftypefun int setitimer (int @var{which}, struct itimerval *@var{old}, struct itimerval *@var{new})
 The @code{setitimer} function sets the timer specified by @var{which} 
 according to @var{new}.  The @var{which} argument can have a value of
@@ -1164,6 +1339,8 @@ The timer interval was too large.
 @end table
 @end deftypefun
 
+@comment sys/time.h
+@comment BSD
 @deftypefun int getitimer (int @var{which}, struct itimerval *@var{old})
 The @code{getitimer} function stores information about the timer specified
 by @var{which} in the structure pointed at by @var{old}.
@@ -1171,18 +1348,24 @@ by @var{which} in the structure pointed at by @var{old}.
 The return value and error conditions are the same as for @code{setitimer}.
 @end deftypefun
 
+@comment sys/time.h
+@comment BSD
 @defvr Macro ITIMER_REAL
 This macro can be used as the @var{which} argument to the
 @code{setitimer} and @code{getitimer} functions to specify the real-time
 timer.
 @end defvr
 
+@comment sys/time.h
+@comment BSD
 @defvr Macro ITIMER_VIRTUAL
 This macro can be used as the @var{which} argument to the
 @code{setitimer} and @code{getitimer} functions to specify the virtual
 timer.
 @end defvr
 
+@comment sys/time.h
+@comment BSD
 @defvr Macro ITIMER_PROF
 This macro can be used as the @var{which} argument to the
 @code{setitimer} and @code{getitimer} functions to specify the profiling
@@ -1192,6 +1375,8 @@ timer.
 @strong{Incomplete:}  In @file{<sys/time.h>}, the @var{which} argument
 is given as an @code{enum}.  Does it matter?
 
+@comment unistd.h
+@comment POSIX.1
 @deftypefun {unsigned int} alarm (unsigned int @var{seconds})
 The @code{alarm} function sets the real-time timer to expire in
 @var{seconds} seconds.  If you want to cancel any existing alarm, you
@@ -1270,6 +1455,8 @@ work.  For more information on this subject, @pxref{Processes}.
 
 The @code{kill} function is declared in @file{<signal.h>}.
 
+@comment signal.h
+@comment POSIX.1
 @deftypefun int kill (pid_t @var{pid}, int @var{signum})
 The @code{kill} function sends the signal @var{signum} to the process
 or process group specified by @var{pid}.  Besides the signals listed in
@@ -1321,6 +1508,14 @@ The @var{pid} argument does not refer to an existing process or group.
 @end table
 @end deftypefun
 
+@comment signal.h
+@comment BSD
+@deftypefun int killpg (int @var{pgid}, int @var{signum})
+This is similar to @code{kill}, but sends signal @var{signum} to the
+process group @var{pgid}.  This function is provided for compatibility
+with BSD; using @code{kill} to do this is more portable.
+@end deftypefun
+
 There are restrictions on permissions that prevent you from using
 @code{kill} to send signals to any random process.  In typical use,
 @code{kill} is used to pass signals between parent, child, and sibling
@@ -1457,9 +1652,6 @@ You can set @code{sa_mask} in your @code{sigaction} call so that the
 signal handler can run without being interrupted.
 @end itemize
 
-@strong{Incomplete:} There should be some mention of the old BSD
-@code{sigblock} (etc.) facilities here.  Maybe in another section?
-
 @menu
 * Signal Sets::				How to specify which signals to block.
 * Process Signal Mask::			Blocking delivery of signals to your
@@ -1481,6 +1673,8 @@ it as an argument to some function that does what you want.
 
 These facilities are declared in the header file @file{<signal.h>}.
 
+@comment signal.h
+@comment POSIX.1
 @deftp {Data Type} sigset_t
 The @code{sigset_t} data type is used to represent signal sets.
 Internally, it may be implemented as either an integer or structure
@@ -1499,6 +1693,8 @@ set object, though.  You can't just set all the signals explicitly
 because the @code{sigset_t} object might include some other information
 (like a version field) that needs to be initialized as well.
 
+@comment signal.h
+@comment POSIX.1
 @deftypefun int sigemptyset (sigset_t *@var{set})
 This function is used to initialize the signal set @var{set} to 
 exclude all of the defined signals.  The return value is @code{0} if
@@ -1506,12 +1702,16 @@ successful, and @code{-1} if the function fails (but there's really
 no reason for it to fail).
 @end deftypefun
 
+@comment signal.h
+@comment POSIX.1
 @deftypefun int sigfillset (sigset_t *@var{set})
 This function is used to initialize the signal set @var{set} to include
 all of the defined signals.  Again, the return value is @code{0} on
 success and @code{-1} on failure.
 @end deftypefun
 
+@comment signal.h
+@comment POSIX.1
 @deftypefun int sigaddset (sigset_t *@var{set}, int @var{signum})
 This function adds the signal @var{signum} to the signal set @var{set}.
 The return value is @code{0} on success and @code{-1} on failure.
@@ -1524,6 +1724,8 @@ The @var{signum} argument doesn't specify a valid signal.
 @end table
 @end deftypefun
 
+@comment signal.h
+@comment POSIX.1
 @deftypefun int sigdelset (sigset_t *@var{set}, int @var{signum})
 This function removes the signal @var{signum} from the signal set
 @var{set}.  The return value and error conditions are the same as for
@@ -1532,6 +1734,8 @@ This function removes the signal @var{signum} from the signal set
 
 Finally, there is this predicate function:
 
+@comment signal.h
+@comment POSIX.1
 @deftypefun int sigismember (const sigset_t *@var{set}, int @var{signum})
 The @code{sigismember} function tests whether the signal @var{signum} is
 a member of the signal set @var{set}.  It returns @code{1} if the signal
@@ -1557,6 +1761,8 @@ its parent's mask.
 
 The prototype for the @code{sigprocmask} function is in @file{<signal.h>}.
 
+@comment signal.h
+@comment POSIX.1
 @deftypefun int sigprocmask (int @var{how}, const sigset_t *@var{set}, sigset_t *@var{oldset})
 The @code{sigprocmask} function is used to examine or change the calling
 process's signal mask.  The @var{how} argument determines how the signal
@@ -1611,6 +1817,8 @@ program error (as opposed to signals sent with @code{raise} or
 @code{kill}).
 @end deftypefun
 
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SIG_BLOCK
 The value of this macro is an integer suitable for use as the @var{how}
 argument to @code{sigprocmask}, to specify that the process signal mask
@@ -1618,12 +1826,16 @@ should be set to the union of the specified set with the current process
 signal mask.
 @end defvr
 
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SIG_UNBLOCK
 The value of this macro is an integer suitable for use as the @var{how}
 argument to @code{sigprocmask}, to specify that the signals in the
 specified set should be removed from the current process signal mask.
 @end defvr
 
+@comment signal.h
+@comment POSIX.1
 @defvr Macro SIG_SETMASK
 The value of this macro is an integer suitable for use as the @var{how}
 argument to @code{sigprocmask}, to specify that the process signal mask
@@ -1730,6 +1942,8 @@ the handler ran.
 You can find out which signals are pending at any time by calling
 @code{sigpending}.  This function is declared in @file{<signal.h>}.
 
+@comment signal.h
+@comment POSIX.1
 @deftypefun int sigpending (sigset_t *@var{set})
 The @code{sigpending} function stores information about pending signals
 in @var{set}.  If there is a pending signal that is blocked from delivery,
@@ -1772,7 +1986,6 @@ be discarded.  For example, if a @code{SIGINT} signal is pending when
 another @code{SIGINT} signal arrives, your program will probably only
 see one of them when you unblock this signal.
 
-
 @node Waiting for a Signal
 @section Waiting for a Signal
 
@@ -1786,6 +1999,8 @@ The @code{pause} and @code{sleep} functions are declared in the header
 file @file{<unistd.h>}, while @code{sigsuspend} is declared in
 @file{<signal.h>}.
 
+@comment unistd.h
+@comment POSIX.1
 @deftypefun int pause (void)
 The @code{pause} function suspends program execution until a signal
 arrives whose action is either to execute a handler function, or to
@@ -1813,6 +2028,8 @@ instead of @code{pause}.  A common situation is using @code{sleep} in a
 loop, to make the process ``wake up'' periodically to perform some
 actions.
 
+@comment unistd.h
+@comment POSIX.1
 @deftypefun {unsigned int} sleep (unsigned int @var{seconds})
 The @code{sleep} function is like @code{pause}, except that execution
 is suspended only for the amount of time specified by the @var{seconds}
@@ -1844,6 +2061,8 @@ has arrived yet, and then use @code{sigsuspend} to both restore the
 original signal mask and suspend execution in one uninterruptable
 operation.
 
+@comment signal.h
+@comment POSIX.1
 @deftypefun int sigsuspend (const sigset_t *@var{set})
 This function replaces the process's signal mask with @var{set} and then
 suspends the process until a signal is delivered whose action is either
@@ -1921,3 +2140,176 @@ other kinds of signals, as well --- for example, job control signals.
 If the process is woken up by a signal that doesn't set
 @code{usr_interrupt}, it just suspends itself again until the ``right''
 kind of signal eventually arrives.
+
+
+@node BSD Signal Handling
+@section BSD Signal Handling
+
+This section describes signal handling functions included in the GNU C
+Library for backward compability with BSD Unix.  In general, you should
+avoid these functions and use the POSIX-standard functions instead.
+
+The BSD signal handling facilities differ from those of POSIX in these
+ways:
+
+@itemize @bullet
+@item
+BSD Unix represents signal masks as an @code{int} bit mask, rather than
+as a @code{sigset_t} object.
+
+@item
+BSD Unix provides hooks that let you control whether signals interrupt
+system calls.  If a signal arrives during a system call (such as a read
+or write operation that blocks the process), it may either return with
+an @code{EINTR} error or be restarted.  POSIX provides no mechanism for
+controlling this, but BSD does.
+@cindex interrupted system call
+
+@item
+BSD Unix has a concept of a @dfn{signal stack}.  This is an alternate
+stack that is used during the execution of signal handler functions,
+instead of its normal execution stack.
+@cindex signal stack
+@end itemize
+
+These facilities are declared in @file{<signal.h>}.
+
+@comment signal.h
+@comment BSD
+@deftypefn Macro int sigmask (int @var{signum})
+This macro returns a signal mask that has the bit for signal @var{signum}
+set.  You can bitwise-OR the results of several calls to @code{sigmask}
+together to specify more than one signal.  For example,
+
+@example
+sigmask (SIGTSTP) | sigmask (SIGSTOP) | sigmask (SIGTTIN) | sigmask (SIGTTOU)
+@end example
+
+@noindent
+specifies a mask that includes all the job-control stop signals.
+@end deftypefn
+
+@comment signal.h
+@comment BSD
+@deftp {Data Type} {struct sigvec}
+This data type is the equivalent of @code{struct sigaction}
+(@pxref{Advanced Signal Handling}); it is used to specify signal actions
+to the @code{sigvec} function.  It contains the following members:
+
+@table @code
+@item __sighandler_t sv_handler
+This is the handler function.
+
+@item int sv_mask
+This is the mask of additional signals to be blocked while the handler
+function is being called.
+
+@item int sv_flags
+This is a bit mask used to specify various flags which affect the
+behavior of the signal.  You can also refer to this field as
+@code{sv_onstack}.
+@end table
+@end deftp
+
+@comment signal.h
+@comment BSD
+@defvr Macro SV_ONSTACK
+This macro can be used with the @code{sv_flags} field of a @code{sigvec}
+structure, to specify that the signal stack should be used when delivering
+the signal.
+@end defvr
+
+@comment signal.h
+@comment BSD
+@defvr Macro SV_INTERRUPT
+This macro can be used with the @code{sv_flags} field of a @code{sigvec}
+structure, to specify that interrupted system calls should not be restarted.
+@end defvr
+
+@comment signal.h
+@comment BSD
+@defvr Macro SV_RESETHAND
+This macro can be used with the @code{sv_flags} field of a @code{sigvec}
+structure, to specify that the action for the signal should be reset back
+to @code{SIG_DFL} when the signal is received.
+@end defvr
+
+@comment signal.h
+@comment BSD
+@deftypefun int sigvec (int @var{signum}, const struct sigvec *@var{action},
+struct sigvec *@var{old_action})
+This function is the equivalent of @code{sigaction} (@pxref{Advanced Signal
+Handling}); it installs the action @var{action} for the signal @var{signum},
+returning information about the previous action in effect for that signal
+in @var{old_action}.
+@end deftypefun
+
+@comment signal.h
+@comment BSD
+@deftypefun int sigblock (int @var{mask})
+This function is the equivalent of @code{sigprocmask} (@pxref{Process
+Signal Mask}) with a @var{how} argument of @code{SIG_BLOCK}: it adds the
+signals specified by @var{mask} to the calling process's signal mask.
+The return value is the previous set of blocked signals.
+@end deftypefun
+
+@comment signal.h
+@comment BSD
+@deftypefun int sigsetmask (int @var{mask})
+This function is the equivalent of @code{sigprocmask} (@pxref{Process
+Signal Mask}) with a @var{how} argument of @code{SIG_SETMASK}: it sets
+the calling process's signal mask to @var{mask}.  The return value is
+the previous set of blocked signals.
+@end deftypefun
+
+@comment signal.h
+@comment BSD
+@deftypefun int sigpause (int @var{mask})
+This function is the equivalent of @code{sigsuspend} (@pxref{Waiting
+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
+
+@comment signal.h
+@comment BSD
+@deftypefun int siginterrupt (int @var{signum}, int @var{interrupt})
+This function is used to change the system call interrupt behavior.  If
+@var{interrupt} is false, system calls will be restarted when
+interrupted by receipt of the signal @var{signum}.  If @var{interrupt}
+is true, system calls will return with a @code{EINTR} error when
+interrupted.
+@end deftypefun
+
+@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.
+
+@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 selects 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{stack} is not a null pointer, this stack is installed.  If
+@var{oldstack} is not a null pointer, information about the currently
+installed signal stack is returned in the location it points to.
+
+The return value is @code{0} on success and @code{1} on failure.
+@end deftypefun
+
+@strong{Incomplete:}  I don't think this is really enough information to
+tell people how to use this facility.