summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>2004-01-09 23:39:14 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>2004-01-09 23:39:14 +0000
commit2e83792c7555c93c250c69c4ffa2d0c1482d1bbc (patch)
tree7c9a9029685f7ce169e3b293b09ab25e5e35a039 /doc
parent234f7adb59e1d55116ad6dfd26ef65d1f31ac658 (diff)
downloadrtems-2e83792c7555c93c250c69c4ffa2d0c1482d1bbc.tar.bz2
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.
Diffstat (limited to 'doc')
-rw-r--r--doc/posix_users/ChangeLog7
-rw-r--r--doc/posix_users/clock.t62
-rw-r--r--doc/posix_users/signal.t68
3 files changed, 131 insertions, 6 deletions
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 <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.
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 <time.h>
+#include <unistd.h>
unsigned int sleep(
unsigned int seconds
@@ -190,6 +195,57 @@ This call is interruptible by a signal.
@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
+@page
@subsection nanosleep - Delay with High Resolution
@findex nanosleep
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 <signal.h>
+#include <unistd.h>
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 <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:
-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.
+