forked from Imagelibrary/rtems
2e83792c75
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.
370 lines
6.7 KiB
Perl
370 lines
6.7 KiB
Perl
@c
|
|
@c COPYRIGHT (c) 1988-2002.
|
|
@c On-Line Applications Research Corporation (OAR).
|
|
@c All rights reserved.
|
|
@c
|
|
@c $Id$
|
|
@c
|
|
|
|
@chapter Clock Manager
|
|
|
|
@section Introduction
|
|
|
|
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:
|
|
|
|
@itemize @bullet
|
|
@item @code{clock_gettime} - Obtain Time of Day
|
|
@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
|
|
@end itemize
|
|
|
|
@section Background
|
|
|
|
There is currently no text in this section.
|
|
|
|
@section Operations
|
|
|
|
There is currently no text in this section.
|
|
|
|
@section Directives
|
|
|
|
This section details the clock 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.
|
|
|
|
@subsection clock_gettime - Obtain Time of Day
|
|
|
|
@findex clock_gettime
|
|
@cindex obtain time of day
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <time.h>
|
|
|
|
int clock_gettime(
|
|
clockid_t clock_id,
|
|
struct timespec *tp
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
On error, this routine returns -1 and sets errno to one of the following:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The tp pointer parameter is invalid.
|
|
|
|
@item EINVAL
|
|
The clock_id specified is invalid.
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
NONE
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@page
|
|
@subsection clock_settime - Set Time of Day
|
|
|
|
@findex clock_settime
|
|
@cindex set time of day
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <time.h>
|
|
|
|
int clock_settime(
|
|
clockid_t clock_id,
|
|
const struct timespec *tp
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
On error, this routine returns -1 and sets errno to one of the following:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The tp pointer parameter is invalid.
|
|
|
|
@item EINVAL
|
|
The clock_id specified is invalid.
|
|
|
|
@item EINVAL
|
|
The contents of the tp structure are invalid.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
NONE
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@page
|
|
@subsection clock_getres - Get Clock Resolution
|
|
|
|
@findex clock_getres
|
|
@cindex get clock resolution
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <time.h>
|
|
|
|
int clock_getres(
|
|
clockid_t clock_id,
|
|
struct timespec *res
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
On error, this routine returns -1 and sets errno to one of the following:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The res pointer parameter is invalid.
|
|
|
|
@item EINVAL
|
|
The clock_id specified is invalid.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
If res is NULL, then the resolution is not returned.
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@page
|
|
@subsection sleep - Delay Process Execution
|
|
|
|
@findex sleep
|
|
@cindex delay process execution
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <unistd.h>
|
|
|
|
unsigned int sleep(
|
|
unsigned int seconds
|
|
);
|
|
@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}.
|
|
|
|
@subheading NOTES:
|
|
|
|
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
|
|
@page
|
|
@subsection nanosleep - Delay with High Resolution
|
|
|
|
@findex nanosleep
|
|
@cindex delay with high resolution
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <time.h>
|
|
|
|
int nanosleep(
|
|
const struct timespec *rqtp,
|
|
struct timespec *rmtp
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
On error, this routine returns -1 and sets errno to one of the following:
|
|
|
|
@table @b
|
|
@item EINTR
|
|
The routine was interrupted by a signal.
|
|
|
|
@item EAGAIN
|
|
The requested sleep period specified negative seconds or nanoseconds.
|
|
|
|
@item EINVAL
|
|
The requested sleep period specified an invalid number for the nanoseconds
|
|
field.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
This call is interruptible by a signal.
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@page
|
|
@subsection gettimeofday - Get the Time of Day
|
|
|
|
@findex gettimeofday
|
|
@cindex get the time of day
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <sys/time.h>
|
|
#include <unistd.h>
|
|
|
|
int gettimeofday(
|
|
struct timeval *tp,
|
|
struct timezone *tzp
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
On error, this routine returns -1 and sets @code{errno} as appropriate.
|
|
|
|
@table @b
|
|
@item EPERM
|
|
@code{settimeofdat} is called by someone other than the superuser.
|
|
|
|
@item EINVAL
|
|
Timezone (or something else) is invalid.
|
|
|
|
@item EFAULT
|
|
One of @code{tv} or @code{tz} pointed outside your accessible address
|
|
space
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
This routine returns the current time of day in the @code{tp} structure.
|
|
|
|
@subheading NOTES:
|
|
|
|
Currently, the timezone information is not supported. The @code{tzp}
|
|
argument is ignored.
|
|
|
|
@c
|
|
@c
|
|
@c
|
|
@page
|
|
@subsection time - Get time in seconds
|
|
|
|
@findex time
|
|
@cindex get time in seconds
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <time.h>
|
|
|
|
int time(
|
|
time_t *tloc
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
This routine returns the number of seconds since the Epoch.
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@code{time} returns the time since 00:00:00 GMT, January 1, 1970,
|
|
measured in seconds
|
|
|
|
If @code{tloc} in non null, the return value is also stored in the
|
|
memory pointed to by @code{t}.
|
|
|
|
@subheading NOTES:
|
|
|
|
NONE
|
|
|