Major update/merge of POSIX manual.

1 files changed, 728 insertions, 0 deletions

diff --git a/doc/posix_users/signal.t b/doc/posix_users/signal.t
new file mode 100644
index 0000000000..f37708bd4a
--- /dev/null
+++ b/doc/posix_users/signal.t
@@ -0,0 +1,728 @@
+@c
+@c  COPYRIGHT (c) 1988-1998.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+@chapter Signal Manager
+
+@section Introduction
+
+The signal manager ...
+
+The directives provided by the signal manager are:
+
+@itemize @bullet
+@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
+
+@section Background
+
+@subsection Signal Delivery
+
+Signals directed at a thread are delivered to the specified thread.
+
+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 @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 
+(@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
+the signal is delivered to the highest priority thread of this set.  In the
+event, multiple threads of the same priority are willing to accept this
+signal, then priority is given first to ready threads, then to threads
+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 (@code{sigprocmask()} or
+@code{pthread_sigprocmask()}) or to wait for this signal
+(@code{sigwait()}) will be the recipient of the signal.
+
+@end enumerate
+
+@section Operations
+
+There is currently no text in this section.
+
+@section Directives
+
+This section details the signal manager's directives.
+A subsection is dedicated to each of this manager's directives
+and describes the calling sequence, related constants, usage,
+and status codes.
+
+@page
+@subsection sigaddset - Add a Signal to a Signal Set
+
+@subheading CALLING SEQUENCE:
+
+@example
+#include <signal.h>
+
+int sigaddset(
+  sigset_t   *set,
+  int         signo
+);
+@end example
+
+@subheading STATUS CODES:
+
+@table @b
+@item EINVAL
+Invalid argument passed.
+
+@end table
+
+@subheading DESCRIPTION:
+
+This function adds the @code{signo} to the specified signal @code{set}.
+
+@subheading NOTES:
+
+NONE
+
+@page
+@subsection sigdelset - Delete a Signal from a Signal Set
+
+@subheading CALLING SEQUENCE:
+
+@example
+#include <signal.h>
+
+int sigdelset(
+  sigset_t   *set,
+  int         signo
+);
+@end example
+
+@subheading STATUS CODES:
+
+@table @b
+@item EINVAL
+Invalid argument passed.
+
+@end table
+
+@subheading DESCRIPTION:
+
+This function deletes the @code{signo} to the specified signal @code{set}.
+
+@subheading NOTES:
+
+NONE
+
+@page
+@subsection sigfillset - Fill a Signal Set
+
+@subheading CALLING SEQUENCE:
+
+@example
+#include <signal.h>
+
+int sigfillset(
+  sigset_t   *set
+);
+@end example
+
+@subheading STATUS CODES:
+
+@table @b
+
+@item EINVAL
+Invalid argument passed.
+
+@end table
+
+@subheading DESCRIPTION:
+
+This function fills the specified signal @code{set} such that all
+signals are set.
+
+@subheading NOTES:
+
+NONE
+
+@page
+@subsection sigismember - Is Signal a Member of a Signal Set
+
+@subheading CALLING SEQUENCE:
+
+@example
+#include <signal.h>
+
+int sigismember(
+  const sigset_t   *set,
+  int               signo
+);
+@end example
+
+@subheading STATUS CODES:
+
+@table @b
+
+@item EINVAL
+Invalid argument passed.
+
+@end table
+
+@subheading DESCRIPTION:
+
+This function returns returns 1 if @code{signo} is a member of @code{set}
+and 0 otherwise.
+
+@subheading NOTES:
+
+NONE
+
+@page
+@subsection sigemptyset - Empty a Signal Set
+
+@subheading CALLING SEQUENCE:
+
+@example
+#include <signal.h>
+
+int sigemptyset(
+  sigset_t   *set
+);
+@end example
+
+@subheading STATUS CODES:
+
+@table @b
+
+@item EINVAL
+Invalid argument passed.
+
+@end table
+
+@subheading DESCRIPTION:
+
+This function fills the specified signal @code{set} such that all
+signals are cleared.
+
+@subheading NOTES:
+
+NONE
+
+@page
+@subsection sigaction - Examine and Change Signal Action
+
+@subheading CALLING SEQUENCE:
+
+@example
+#include <signal.h>
+
+int sigaction(
+  int                     sig,
+  const struct sigaction *act,
+  struct sigaction       *oact
+);
+@end example
+
+@subheading STATUS CODES:
+
+@table @b
+@item EINVAL
+Invalid argument passed.
+
+@item ENOTSUP
+Realtime Signals Extension option not supported.
+
+@end table
+
+@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
+@subsection pthread_kill - Send a Signal to a Thread
+
+@subheading CALLING SEQUENCE:
+
+@example
+#include <signal.h>
+
+int pthread_kill(
+  pthread_t   thread,
+  int         sig
+);
+@end example
+
+@subheading STATUS CODES:
+
+@table @b
+
+@item ESRCH
+The thread indicated by the parameter thread is invalid.
+
+@item EINVAL
+Invalid argument passed.
+
+@end table
+
+@subheading DESCRIPTION:
+
+This functions sends the specified signal @code{sig} to @code{thread}.
+
+@subheading NOTES:
+
+NONE
+
+@page
+@subsection sigprocmask - Examine and Change Process Blocked Signals
+ 
+@subheading CALLING SEQUENCE:
+ 
+@example
+#include <signal.h>
+ 
+int sigprocmask(
+  int               how,
+  const sigset_t   *set,
+  sigset_t         *oset
+);
+@end example
+ 
+@subheading STATUS CODES:
+
+@table @b
+
+@item EINVAL
+Invalid argument passed.
+ 
+@end table
+ 
+@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
+@subsection pthread_sigmask - Examine and Change Thread Blocked Signals
+
+@subheading CALLING SEQUENCE:
+
+@example
+#include <signal.h>
+
+int pthread_sigmask(
+  int               how,
+  const sigset_t   *set,
+  sigset_t         *oset
+);
+@end example
+
+@subheading STATUS CODES:
+@table @b
+@item EINVAL
+Invalid argument passed.
+
+@end table
+
+@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
+@subsection kill - Send a Signal to a Process
+
+@subheading CALLING SEQUENCE:
+
+@example
+#include <sys/types.h>
+#include <signal.h>
+
+int kill(
+  pid_t pid,
+  int   sig
+);
+@end example
+
+@subheading STATUS CODES:
+@table @b
+@item EINVAL
+Invalid argument passed.
+
+@item EPERM
+Process does not have permission to send the signal to any receiving process.
+
+@item ESRCH
+The process indicated by the parameter pid is invalid.
+
+@end table
+
+@subheading DESCRIPTION:
+
+This function sends the signal @code{sig} to the process @code{pid}.
+
+@subheading NOTES:
+
+NONE
+ 
+@page
+@subsection sigpending - Examine Pending Signals
+ 
+@subheading CALLING SEQUENCE:
+ 
+@example
+#include <signal.h>
+ 
+int sigpending(
+  const sigset_t  *set
+);
+@end example
+ 
+@subheading STATUS CODES:
+
+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
+@subsection sigsuspend - Wait for a Signal
+ 
+@subheading CALLING SEQUENCE:
+ 
+@example
+#include <signal.h>
+ 
+int sigsuspend(
+  const sigset_t  *sigmask
+);
+@end example
+ 
+@subheading STATUS CODES:
+
+On error, this routine returns -1 and sets @code{errno} to one of
+the following:
+
+@table @b
+
+@item EINTR
+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
+@subsection pause - Suspend Process Execution
+ 
+@subheading CALLING SEQUENCE:
+ 
+@example
+#include <signal.h>
+ 
+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
+ 
+@item EINTR
+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
+@subsection sigwait - Synchronously Accept a Signal
+
+@subheading CALLING SEQUENCE:
+
+@example
+#include <signal.h>
+
+int sigwait(
+  const sigset_t  *set,
+  int             *sig
+);
+@end example
+
+@subheading STATUS CODES:
+@table @b
+@item EINVAL
+Invalid argument passed.
+
+@item EINTR
+Signal interrupted this function.
+
+@end table
+
+@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
+@subsection sigwaitinfo - Synchronously Accept a Signal
+ 
+@subheading CALLING SEQUENCE:
+ 
+@example
+#include <signal.h>
+ 
+int sigwaitinfo(
+  const sigset_t  *set,
+  siginfo_t       *info
+);
+@end example
+ 
+@subheading STATUS CODES:
+@table @b
+@item EINTR
+Signal interrupted this function.
+ 
+@end table
+ 
+@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
+@subsection sigtimedwait - Synchronously Accept a Signal with Timeout
+ 
+@subheading CALLING SEQUENCE:
+ 
+@example
+#include <signal.h>
+ 
+int sigtimedwait(
+  const sigset_t         *set,
+  siginfo_t              *info,
+  const struct timespec  *timeout
+);
+@end example
+ 
+@subheading STATUS CODES:
+@table @b
+@item EAGAIN
+Timed out while waiting for the specified signal set.
+ 
+@item EINVAL
+Nanoseconds field of the timeout argument is invalid.
+ 
+@item EINTR
+Signal interrupted this function.
+ 
+@end table
+ 
+@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 @code{timeout} is NULL, then the calling thread will wait forever for
+the specified signal set.
+
+@page
+@subsection sigqueue - Queue a Signal to a Process
+ 
+@subheading CALLING SEQUENCE:
+ 
+@example
+#include <signal.h>
+ 
+int sigqueue(
+  pid_t               pid,
+  int                 signo,
+  const union sigval  value
+);
+@end example
+ 
+@subheading STATUS CODES:
+
+@table @b
+
+@item EAGAIN
+No resources available to queue the signal.  The process has already
+queued SIGQUEUE_MAX signals that are still pending at the receiver
+or the systemwide resource limit has been exceeded.
+ 
+@item EINVAL
+The value of the signo argument is an invalid or unsupported signal
+number.
+ 
+@item EPERM
+The process does not have the appropriate privilege to send the signal
+to the receiving process.
+
+@item ESRCH
+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
+@subsection alarm - Schedule Alarm
+ 
+@subheading CALLING SEQUENCE:
+ 
+@example
+#include <signal.h>
+ 
+unsigned int alarm(
+  unsigned int  seconds
+);
+@end example
+ 
+@subheading STATUS CODES:
+
+This call always succeeds.
+ 
+@subheading DESCRIPTION:
+ 
+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