2004-01-09 Joel Sherrill <joel@OARcorp.com>

PR 464/doc
	* clock.t, signal.t: Add documentation for usleep() and ualarm(). Also
	fixed a couple of calls which have the wrong .h files per the
	OpenGroup site documentation.

doc/posix_users/ChangeLog

@@ -1,3 +1,10 @@
+2004-01-09	Joel Sherrill <joel@OARcorp.com>
+
+	PR 464/doc
+	* clock.t, signal.t: Add documentation for usleep() and ualarm(). Also
+	fixed a couple of calls which have the wrong .h files per the
+	OpenGroup site documentation.
+
 2003-12-12	Ralf Corsepius <corsepiu@faw.uni-ulm.de>
 
 	* Makefile.am: Cosmetics.

doc/posix_users/clock.t

@@ -10,7 +10,11 @@
 
 @section Introduction
 
-The clock manager ...
+The clock manager provides services two primary classes
+of services.  The first focuses on obtaining and setting
+the current date and time.  The other category of services
+focus on allowing a thread to delay for a specific length
+of time.
 
 The directives provided by the clock manager are:
 
@@ -19,6 +23,7 @@ The directives provided by the clock manager are:
 @item @code{clock_settime} - Set Time of Day
 @item @code{clock_getres} - Get Clock Resolution
 @item @code{sleep} - Delay Process Execution
+@item @code{usleep} - Delay Process Execution in Microseconds
 @item @code{nanosleep} - Delay with High Resolution
 @item @code{gettimeofday} - Get the Time of Day
 @item @code{time} - Get time in seconds
@@ -39,7 +44,7 @@ A subsection is dedicated to each of this manager's directives
 and describes the calling sequence, related constants, usage,
 and status codes.
 
-@subsection clock_gettime -Obtain Time of Day
+@subsection clock_gettime - Obtain Time of Day
 
 @findex clock_gettime
 @cindex obtain time of day
@@ -166,7 +171,7 @@ If res is NULL, then the resolution is not returned.
 @subheading CALLING SEQUENCE:
 
 @example
-#include <time.h>
+#include <unistd.h>
 
 unsigned int sleep(
   unsigned int seconds
@@ -186,6 +191,57 @@ number of @code{seconds}.
 
 This call is interruptible by a signal.
 
+@c
+@c
+@c
+@page
+@subsection usleep - Delay Process Execution in Microseconds
+
+@findex usleep
+@cindex  delay process execution
+@cindex  delay process execution
+@cindex  usecs delay process execution
+@cindex  microsecond delay process execution
+
+@subheading CALLING SEQUENCE:
+
+@example
+#include <time.h>
+
+useconds_t usleep(
+  useconds_t useconds
+);
+@end example
+
+@subheading STATUS CODES:
+
+This routine returns the number of unslept seconds.
+
+@subheading DESCRIPTION:
+
+The @code{sleep()} function delays the calling thread by the specified
+number of @code{seconds}.
+
+The @code{usleep()} function suspends the calling thread from execution
+until either the number of microseconds specified by the
+@code{useconds} argument has elapsed or a signal is delivered to the
+calling thread and its action is to invoke a signal-catching function
+or to terminate the process.
+
+Because of other activity, or because of the time spent in
+processing the call, the actual length of time the thread is
+blocked may be longer than
+the amount of time specified.
+
+@subheading NOTES:
+
+This call is interruptible by a signal.
+
+The Single UNIX Specification allows this service to be implemented using
+the same timer as that used by the @code{alarm()} service.  This is 
+@b{NOT} the case for @b{RTEMS} and this call has no interaction with
+the @code{SIGALRM} signal.
+
 @c
 @c
 @c

doc/posix_users/signal.t

@@ -35,6 +35,7 @@ The directives provided by the signal manager are:
 @item @code{sigtimedwait} - Synchronously Accept a Signal with Timeout
 @item @code{sigqueue} - Queue a Signal to a Process
 @item @code{alarm} - Schedule Alarm
+@item @code{ualarm} - Schedule Alarm in Microseconds
 @end itemize
 
 @section Background
@@ -860,7 +861,7 @@ NONE
 @subheading CALLING SEQUENCE:
 
 @example
-#include <signal.h>
+#include <unistd.h>
 
 unsigned int alarm(
   unsigned int seconds
@@ -871,13 +872,74 @@ unsigned int alarm(
 
 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 DESCRIPTION:
+
+The @code{alarm()} service causes the @code{SIGALRM} signal to
+be generated after the number of seconds specified by
+@code{seconds} has elapsed.
+
 @subheading NOTES:
 
-NONE
+Alarm requests do not queue.  If @code{alarm} is called while
+a previous request is outstanding, the call will result in 
+rescheduling the time at which the @code{SIGALRM} signal
+will be generated.
+
+If the notification signal, @code{SIGALRM}, is not caught or ignored, the
+calling process is terminated.
+
+@c
+@c
+@c
+@page
+@subsection ualarm - Schedule Alarm in Microseconds
+
+@findex alarm
+@findex microseonds alarm
+@findex usecs alarm
+@cindex schedule alarm in microseonds
+
+@subheading CALLING SEQUENCE:
+
+@example
+#include <unistd.h>
+
+useconds_t ualarm(
+  useconds_t useconds,
+  useconds_t interval
+);
+@end example
+
+@subheading STATUS CODES:
+
+This call always succeeds.
+
+If there was a previous @code{ualarm()} 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 DESCRIPTION:
+
+The @code{ualarm()} service causes the @code{SIGALRM} signal to
+be generated after the number of microseconds specified by
+@code{useconds} has elapsed.
+
+When @code{interval} is non-zero, repeated timeout notification occurs
+with a period in microseconds specified by @code{interval}.
+
+@subheading NOTES:
+
+Alarm requests do not queue.  If @code{alarm} is called while
+a previous request is outstanding, the call will result in 
+rescheduling the time at which the @code{SIGALRM} signal
+will be generated.
+
+If the notification signal, @code{SIGALRM}, is not caught or ignored, the
+calling process is terminated.
+