From 2e83792c7555c93c250c69c4ffa2d0c1482d1bbc Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Fri, 9 Jan 2004 23:39:14 +0000 Subject: 2004-01-09 Joel Sherrill 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 | 7 +++++ doc/posix_users/clock.t | 62 +++++++++++++++++++++++++++++++++++++++--- doc/posix_users/signal.t | 68 ++++++++++++++++++++++++++++++++++++++++++++--- 3 files changed, 131 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/posix_users/ChangeLog b/doc/posix_users/ChangeLog index b3e046ce4b..f4ffad4aa6 100644 --- a/doc/posix_users/ChangeLog +++ b/doc/posix_users/ChangeLog @@ -1,3 +1,10 @@ +2004-01-09 Joel Sherrill + + 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 * Makefile.am: Cosmetics. diff --git a/doc/posix_users/clock.t b/doc/posix_users/clock.t index 07d1560775..63c0cf3412 100644 --- a/doc/posix_users/clock.t +++ b/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 +#include 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 + +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 diff --git a/doc/posix_users/signal.t b/doc/posix_users/signal.t index b56d325422..933faa56c0 100644 --- a/doc/posix_users/signal.t +++ b/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 +#include unsigned int alarm( unsigned int seconds @@ -871,13 +872,74 @@ unsigned int alarm( This call always succeeds. +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: -If there was a previous @code{alarm()} request with time remaining, +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: + +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 + +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: -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. + -- cgit v1.2.3