Major update/merge of POSIX manual.

1 files changed, 198 insertions, 161 deletions

diff --git a/doc/posix_users/signal.texi b/doc/posix_users/signal.t
index 6d90b8cfff..f37708bd4a 100644
--- a/doc/posix_users/signal.texi
+++ b/doc/posix_users/signal.t
@@ -6,22 +6,8 @@
 @c  $Id$
 @c
 
-@ifinfo
-@node Signal Manager, Signal Manager Introduction, pthread_getschedparam, Top
-@end ifinfo
 @chapter Signal Manager
-@ifinfo
-@menu
-* Signal Manager Introduction::
-* Signal Manager Background::
-* Signal Manager Operations::
-* Signal Manager Directives::
-@end menu
-@end ifinfo
-
-@ifinfo
-@node Signal Manager Introduction, Signal Manager Background, Signal Manager, Signal Manager
-@end ifinfo
+
 @section Introduction
 
 The signal manager ...
@@ -29,40 +15,28 @@ The signal manager ...
 The directives provided by the signal manager are:
 
 @itemize @bullet
-@item @code{sigaddset} - 
-@item @code{sigdelset} - 
-@item @code{sigfillset} - 
-@item @code{sigismember} - 
-@item @code{sigemptyset} - 
-@item @code{sigaction} - 
-@item @code{pthread_kill} - 
-@item @code{sigprocmask} - 
-@item @code{pthread_sigmask} - 
-@item @code{kill} - 
-@item @code{sigpending} - 
-@item @code{sigsuspend} - 
-@item @code{pause} - 
-@item @code{sigwait} - 
-@item @code{sigwaitinfo} - 
-@item @code{sigtimedwait} - 
-@item @code{sigqueue} - 
-@item @code{alarm} - 
+@item @code{sigaddset} - Add a Signal to a Signal Set
+@item @code{sigdelset} - Delete a Signal from a Signal Set
+@item @code{sigfillset} - Fill a Signal Set
+@item @code{sigismember} - Is Signal a Member of a Signal Set
+@item @code{sigemptyset} - Empty a Signal Set
+@item @code{sigaction} - Examine and Change Signal Action
+@item @code{pthread_kill} - Send a Signal to a Thread
+@item @code{sigprocmask} - Examine and Change Process Blocked Signals
+@item @code{pthread_sigmask} - Examine and Change Thread Blocked Signals
+@item @code{kill} - Send a Signal to a Process
+@item @code{sigpending} - Examine Pending Signals
+@item @code{sigsuspend} - Wait for a Signal
+@item @code{pause} - Suspend Process Execution
+@item @code{sigwait} - Synchronously Accept a Signal
+@item @code{sigwaitinfo} - Synchronously Accept a Signal
+@item @code{sigtimedwait} - Synchronously Accept a Signal with Timeout
+@item @code{sigqueue} - Queue a Signal to a Process
+@item @code{alarm} - Schedule Alarm
 @end itemize
 
-@ifinfo
-@node Signal Manager Background, Signal Delivery, Signal Manager Introduction, Signal Manager
-@end ifinfo
 @section Background
-@ifinfo
-@menu
-* Signal Delivery::
-@end menu
-@end ifinfo
-
 
-@ifinfo
-@node Signal Delivery, Signal Manager Operations, Signal Manager Background, Signal Manager Background
-@end ifinfo
 @subsection Signal Delivery
 
 Signals directed at a thread are delivered to the specified thread.
@@ -71,14 +45,14 @@ Signals directed at a process are delivered to a thread which is selected
 based on the following algorithm:
 
 @enumerate
-@item If the action for this signal is currently SIG_IGN, then the signal
-is simply ignored.
+@item If the action for this signal is currently @code{SIG_IGN},
+then the signal is simply ignored.
 
 @item If the currently executing thread has the signal unblocked, then
 the signal is delivered to it.
 
 @item If any threads are currently blocked waiting for this signal 
-(sigwait()), then the signal is delivered to the highest priority 
+(@code{sigwait()}), then the signal is delivered to the highest priority 
 thread waiting for this signal.
 
 @item If any other threads are willing to accept delivery of the signal, then
@@ -89,43 +63,17 @@ blocked on calls which may be interrupted, and finally to threads blocked
 on non-interruptible calls.
 
 @item In the event the signal still can not be delivered, then it is left
-pending.  The first thread to unblock the signal (sigprocmask() or
-pthread_sigprocmask()) or to wait for this signal (sigwait()) will be
-the recipient of the signal.
+pending.  The first thread to unblock the signal (@code{sigprocmask()} or
+@code{pthread_sigprocmask()}) or to wait for this signal
+(@code{sigwait()}) will be the recipient of the signal.
 
 @end enumerate
 
-@ifinfo
-@node Signal Manager Operations, Signal Manager Directives, Signal Delivery, Signal Manager
-@end ifinfo
 @section Operations
 
-@ifinfo
-@node Signal Manager Directives, sigaddset, Signal Manager Operations, Signal Manager
-@end ifinfo
+There is currently no text in this section.
+
 @section Directives
-@ifinfo
-@menu
-* sigaddset::
-* sigdelset::
-* sigfillset::
-* sigismember::
-* sigemptyset::
-* sigaction::
-* pthread_kill::
-* sigprocmask::
-* pthread_sigmask::
-* kill::
-* sigpending::
-* sigsuspend::
-* pause::
-* sigwait::
-* sigwaitinfo::
-* sigtimedwait::
-* sigqueue::
-* alarm::
-@end menu
-@end ifinfo
 
 This section details the signal manager's directives.
 A subsection is dedicated to each of this manager's directives
@@ -133,10 +81,7 @@ and describes the calling sequence, related constants, usage,
 and status codes.
 
 @page
-@ifinfo
-@node sigaddset, sigdelset, Signal Manager Directives, Signal Manager Directives
-@end ifinfo
-@subsection sigaddset
+@subsection sigaddset - Add a Signal to a Signal Set
 
 @subheading CALLING SEQUENCE:
 
@@ -159,13 +104,14 @@ Invalid argument passed.
 
 @subheading DESCRIPTION:
 
+This function adds the @code{signo} to the specified signal @code{set}.
+
 @subheading NOTES:
 
+NONE
+
 @page
-@ifinfo
-@node sigdelset, sigfillset, sigaddset, Signal Manager Directives
-@end ifinfo
-@subsection sigdelset
+@subsection sigdelset - Delete a Signal from a Signal Set
 
 @subheading CALLING SEQUENCE:
 
@@ -188,13 +134,14 @@ Invalid argument passed.
 
 @subheading DESCRIPTION:
 
+This function deletes the @code{signo} to the specified signal @code{set}.
+
 @subheading NOTES:
 
+NONE
+
 @page
-@ifinfo
-@node sigfillset, sigismember, sigdelset, Signal Manager Directives
-@end ifinfo
-@subsection sigfillset
+@subsection sigfillset - Fill a Signal Set
 
 @subheading CALLING SEQUENCE:
 
@@ -207,7 +154,9 @@ int sigfillset(
 @end example
 
 @subheading STATUS CODES:
+
 @table @b
+
 @item EINVAL
 Invalid argument passed.
 
@@ -215,13 +164,15 @@ Invalid argument passed.
 
 @subheading DESCRIPTION:
 
+This function fills the specified signal @code{set} such that all
+signals are set.
+
 @subheading NOTES:
 
+NONE
+
 @page
-@ifinfo
-@node sigismember, sigemptyset, sigfillset, Signal Manager Directives
-@end ifinfo
-@subsection sigismember
+@subsection sigismember - Is Signal a Member of a Signal Set
 
 @subheading CALLING SEQUENCE:
 
@@ -235,7 +186,9 @@ int sigismember(
 @end example
 
 @subheading STATUS CODES:
+
 @table @b
+
 @item EINVAL
 Invalid argument passed.
 
@@ -243,13 +196,15 @@ Invalid argument passed.
 
 @subheading DESCRIPTION:
 
+This function returns returns 1 if @code{signo} is a member of @code{set}
+and 0 otherwise.
+
 @subheading NOTES:
 
+NONE
+
 @page
-@ifinfo
-@node sigemptyset, sigaction,  sigismember, Signal Manager Directives
-@end ifinfo
-@subsection sigemptyset
+@subsection sigemptyset - Empty a Signal Set
 
 @subheading CALLING SEQUENCE:
 
@@ -264,6 +219,7 @@ int sigemptyset(
 @subheading STATUS CODES:
 
 @table @b
+
 @item EINVAL
 Invalid argument passed.
 
@@ -271,13 +227,15 @@ Invalid argument passed.
 
 @subheading DESCRIPTION:
 
+This function fills the specified signal @code{set} such that all
+signals are cleared.
+
 @subheading NOTES:
 
+NONE
+
 @page
-@ifinfo
-@node sigaction, pthread_kill, sigemptyset, Signal Manager Directives
-@end ifinfo
-@subsection sigaction
+@subsection sigaction - Examine and Change Signal Action
 
 @subheading CALLING SEQUENCE:
 
@@ -304,14 +262,17 @@ Realtime Signals Extension option not supported.
 
 @subheading DESCRIPTION:
 
+This function is used to change the action taken by a process on 
+receipt of the specfic signal @code{sig}.  The new action is 
+specified by @code{act} and the previous action is returned
+via @code{oact}.
+
 @subheading NOTES:
 
 The signal number cannot be SIGKILL.
+
 @page
-@ifinfo
-@node pthread_kill, sigprocmask, sigaction, Signal Manager Directives
-@end ifinfo
-@subsection pthread_kill
+@subsection pthread_kill - Send a Signal to a Thread
 
 @subheading CALLING SEQUENCE:
 
@@ -325,7 +286,9 @@ int pthread_kill(
 @end example
 
 @subheading STATUS CODES:
+
 @table @b
+
 @item ESRCH
 The thread indicated by the parameter thread is invalid.
 
@@ -336,13 +299,14 @@ Invalid argument passed.
 
 @subheading DESCRIPTION:
 
+This functions sends the specified signal @code{sig} to @code{thread}.
+
 @subheading NOTES:
 
+NONE
+
 @page
-@ifinfo
-@node sigprocmask, pthread_sigmask, pthread_kill, Signal Manager Directives
-@end ifinfo
-@subsection sigprocmask
+@subsection sigprocmask - Examine and Change Process Blocked Signals
  
 @subheading CALLING SEQUENCE:
  
@@ -357,7 +321,9 @@ int sigprocmask(
 @end example
  
 @subheading STATUS CODES:
+
 @table @b
+
 @item EINVAL
 Invalid argument passed.
  
@@ -365,14 +331,35 @@ Invalid argument passed.
  
 @subheading DESCRIPTION:
  
+This function is used to alter the set of currently blocked signals
+on a process wide basis.  A blocked signal will not be received by the
+process.  The behavior of this function is dependent on the value of
+@code{how} which may be one of the following:
+
+@table @code
+
+@item SIG_BLOCK
+The set of blocked signals is set to the union of @code{set} and 
+those signals currently blocked.
+
+@item SIG_UNBLOCK
+The signals specific in @code{set} are removed from the currently
+blocked set.
+
+@item SIG_SETMASK
+The set of currently blocked signals is set to @code{set}.
+
+@end table
+
+If @code{oset} is not @code{NULL}, then the set of blocked signals
+prior to this call is returned in @code{oset}.
+
 @subheading NOTES:
- 
+
+It is not an error to unblock a signal which is not blocked.
 
 @page
-@ifinfo
-@node pthread_sigmask, kill, sigprocmask, Signal Manager Directives
-@end ifinfo
-@subsection pthread_sigmask
+@subsection pthread_sigmask - Examine and Change Thread Blocked Signals
 
 @subheading CALLING SEQUENCE:
 
@@ -395,14 +382,35 @@ Invalid argument passed.
 
 @subheading DESCRIPTION:
 
+This function is used to alter the set of currently blocked signals
+for the calling thread.  A blocked signal will not be received by the
+process.  The behavior of this function is dependent on the value of
+@code{how} which may be one of the following:
+
+@table @code
+@item SIG_BLOCK
+The set of blocked signals is set to the union of @code{set} and
+those signals currently blocked.
+
+@item SIG_UNBLOCK
+The signals specific in @code{set} are removed from the currently
+blocked set.
+
+@item SIG_SETMASK
+The set of currently blocked signals is set to @code{set}.
+
+@end table
+
+If @code{oset} is not @code{NULL}, then the set of blocked signals
+prior to this call is returned in @code{oset}.
+
 @subheading NOTES:
 
+It is not an error to unblock a signal which is not blocked.
+
 
 @page
-@ifinfo
-@node kill, sigpending, pthread_sigmask, Signal Manager Directives
-@end ifinfo
-@subsection kill
+@subsection kill - Send a Signal to a Process
 
 @subheading CALLING SEQUENCE:
 
@@ -431,14 +439,14 @@ The process indicated by the parameter pid is invalid.
 
 @subheading DESCRIPTION:
 
+This function sends the signal @code{sig} to the process @code{pid}.
+
 @subheading NOTES:
 
+NONE
  
 @page
-@ifinfo
-@node sigpending, sigsuspend, kill, Signal Manager Directives
-@end ifinfo
-@subsection sigpending
+@subsection sigpending - Examine Pending Signals
  
 @subheading CALLING SEQUENCE:
  
@@ -452,23 +460,28 @@ int sigpending(
  
 @subheading STATUS CODES:
 
-On error, this routine returns -1 and sets errno to one of the following:
+On error, this routine returns -1 and sets @code{errno} to one of
+the following:
  
 @table @b
+
 @item EFAULT
 Invalid address for set.
 
 @end table
 
 @subheading DESCRIPTION:
+
+This function allows the caller to examine the set of currently pending
+signals.  A pending signal is one which has been raised but is currently
+blocked.  The set of pending signals is returned in @code{set}.
  
 @subheading NOTES:
 
+NONE
+
 @page
-@ifinfo
-@node sigsuspend, pause, sigpending, Signal Manager Directives
-@end ifinfo
-@subsection sigsuspend
+@subsection sigsuspend - Wait for a Signal
  
 @subheading CALLING SEQUENCE:
  
@@ -481,8 +494,11 @@ int sigsuspend(
 @end example
  
 @subheading STATUS CODES:
+
+On error, this routine returns -1 and sets @code{errno} to one of
+the following:
+
 @table @b
-Returns -1 and sets errno.
 
 @item EINTR
 Signal interrupted this function.
@@ -490,14 +506,17 @@ Signal interrupted this function.
 @end table
  
 @subheading DESCRIPTION:
+
+This function temporarily replaces the signal mask for the process
+with that specified by @code{sigmask} and blocks the calling thread
+until the signal is raised.
  
 @subheading NOTES:
 
+NONE
+
 @page
-@ifinfo
-@node pause, sigwait, sigsuspend, Signal Manager Directives
-@end ifinfo
-@subsection pause
+@subsection pause - Suspend Process Execution
  
 @subheading CALLING SEQUENCE:
  
@@ -508,8 +527,11 @@ int pause( void );
 @end example
  
 @subheading STATUS CODES:
+
+On error, this routine returns -1 and sets @code{errno} to one of
+the following:
+
 @table @b
-Returns -1 and sets errno.
  
 @item EINTR
 Signal interrupted this function.
@@ -517,14 +539,16 @@ Signal interrupted this function.
 @end table
  
 @subheading DESCRIPTION:
+
+This function causes the calling thread to be blocked until the signal
+is received.
  
 @subheading NOTES:
+
+NONE
  
 @page
-@ifinfo
-@node sigwait, sigwaitinfo, pause, Signal Manager Directives
-@end ifinfo
-@subsection sigwait
+@subsection sigwait - Synchronously Accept a Signal
 
 @subheading CALLING SEQUENCE:
 
@@ -549,13 +573,17 @@ Signal interrupted this function.
 
 @subheading DESCRIPTION:
 
+This function selects a pending signal based on the set specified in
+@code{set}, atomically clears it from the set of pending signals, and
+returns the signal number for that signal in @code{sig}.
+
+
 @subheading NOTES:
 
+NONE
+
 @page
-@ifinfo
-@node sigwaitinfo, sigtimedwait, sigwait, Signal Manager Directives
-@end ifinfo
-@subsection sigwaitinfo
+@subsection sigwaitinfo - Synchronously Accept a Signal
  
 @subheading CALLING SEQUENCE:
  
@@ -577,13 +605,16 @@ Signal interrupted this function.
  
 @subheading DESCRIPTION:
  
+This function selects a pending signal based on the set specified in
+@code{set}, atomically clears it from the set of pending signals, and
+returns information about that signal in @code{info}.
+
 @subheading NOTES:
 
+NONE
+
 @page
-@ifinfo
-@node sigtimedwait, sigqueue, sigwaitinfo, Signal Manager Directives
-@end ifinfo
-@subsection sigtimedwait
+@subsection sigtimedwait - Synchronously Accept a Signal with Timeout
  
 @subheading CALLING SEQUENCE:
  
@@ -612,16 +643,18 @@ Signal interrupted this function.
  
 @subheading DESCRIPTION:
  
+This function selects a pending signal based on the set specified in
+@code{set}, atomically clears it from the set of pending signals, and
+returns information about that signal in @code{info}.  The calling thread
+will block up to @code{timeout} waiting for the signal to arrive.
+
 @subheading NOTES:
 
-If timeout is NULL, then the thread will wait forever for the specified 
-signal set.
+If @code{timeout} is NULL, then the calling thread will wait forever for
+the specified signal set.
 
 @page
-@ifinfo
-@node sigqueue, alarm, sigtimedwait, Signal Manager Directives
-@end ifinfo
-@subsection sigqueue
+@subsection sigqueue - Queue a Signal to a Process
  
 @subheading CALLING SEQUENCE:
  
@@ -658,15 +691,16 @@ The process pid does not exist.
 @end table
  
 @subheading DESCRIPTION:
+
+This function sends the signal specified by @code{signo} to the
+process @code{pid}
  
 @subheading NOTES:
 
+NONE
 
 @page
-@ifinfo
-@node alarm, Mutex Manager, sigqueue, Signal Manager Directives
-@end ifinfo
-@subsection alarm
+@subsection alarm - Schedule Alarm
  
 @subheading CALLING SEQUENCE:
  
@@ -680,12 +714,15 @@ unsigned int alarm(
  
 @subheading STATUS CODES:
 
-If there was a previous alarm() request with time remaining, then this routine
-returns the number of seconds until that outstanding alarm would have fired.
-If no previous alarm() request was outstanding, then zero is returned.
+This call always succeeds.
  
 @subheading DESCRIPTION:
  
-@subheading NOTES:
+If there was a previous @code{alarm()} request with time remaining,
+then this routine returns the number of seconds until that outstanding
+alarm would have fired.  If no previous @code{alarm()} request was
+outstanding, then zero is returned.
 
+@subheading NOTES:
 
+NONE