timer_settime()
Arm a timer with the given expiration time, disarm it, or set its tolerance
Synopsis:
#include <time.h>
int timer_settime( timer_t timerid,
int flags,
const struct itimerspec * value,
struct itimerspec * ovalue );
Arguments:
- timerid
- A timer_t object representing the timer that you want to modify. This object holds a timer ID, as set by timer_create().
- flags
- Flags that specify what you want to set for the timer. The valid flags include:
- TIMER_ABSTIME — the it_value member in the
value object represents an absolute expiration date, in seconds and
nanoseconds from the start of 1970. If the specified date has already passed, the function
succeeds and the expiration notice is made.
If you don't set this bit, the it_value represents a relative expiration period that's offset from the current system time by the specified number of seconds and nanoseconds.
The following are QNX OS extensions:
- TIMER_TOLERANCE — specify the amount of the tolerance to allow the kernel in low-power situations. You can't set this and TIMER_ABSTIME in the same call.
- TIMER_PRECISE — override any default tolerance that was set for the process (see procmgr_timer_tolerance()). You can OR this into the flags if you're setting an expiration time (i.e., you didn't specify TIMER_TOLERANCE).
- TIMER_ABSTIME — the it_value member in the
value object represents an absolute expiration date, in seconds and
nanoseconds from the start of 1970. If the specified date has already passed, the function
succeeds and the expiration notice is made.
- value
- A pointer to an itimerspec structure that specifies the new amount of time left
before the timer expires, or the timer tolerance, depending on the flags.
For more information about this structure, see
timer_gettime().
If you specify the TIMER_TOLERANCE flag, this argument can be NULL.
- ovalue
- NULL, or a pointer to an itimerspec structure that the function fills in with either the timer's former time until expiry or its tolerance, depending on the flags.
Library:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
Description:
The timer_settime() function either sets the expiration time of the timer specified by timerid, or sets the tolerance for that timer, depending on the flags provided. When you don't specify TIMER_TOLERANCE, the expiration time is set from the it_value member of the value argument. If it_value is non-zero, then the timer is armed (or rearmed). If this member is zero, then the timer is disarmed. When you do specify TIMER_TOLERANCE, the tolerance is set from the it_value member.
The timer_settime() function rounds up time values that are between two consecutive nonnegative integer multiples of the resolution of the specified timer to the larger multiple of the resolution.
If the it_interval member of value is nonzero, then it specifies a repeat rate that is added to the timer once the it_value period has expired. Subsequently, the timer is automatically rearmed, causing it to become continuous with a period of it_interval.
If the ovalue parameter isn't NULL, then on return from this function it contains a value representing the previous amount of time left before the timer was to have expired, or zero if the timer was disarmed. The previous interval timer period is also stored in the it_interval member.
The timerid is local to the calling process, and must have been created using timer_create().
Understanding the Microkernel's Concept of Timechapter of the QNX OS Programmer's Guide.
Timer tolerance
As a QNX OS extension, if you specify the TIMER_TOLERANCE flag, then:
- If value isn't NULL, the it_value member specifies the amount of tolerance that the kernel is allowed with regard to the expiry time. If you want to specify infinite timer tolerance, call TimerSettime() instead of timer_settime().
- If ovalue isn't NULL, the function sets the it_value member to the previous tolerance.
In order to set the tolerance to a value between 0 and the clock period, you need to have the PROCMGR_AID_HIGH_RESOLUTION_TIMER ability enabled. For more information, see procmgr_ability().
You can set the tolerance at any time without affecting the active/inactive status of the timer.
For more information, see
Tolerant and high-resolution timers
in the
Understanding the Microkernel's Concept of Time
chapter of the QNX OS Programmer's Guide.
Returns:
- 0
- Success.
- -1
- An error occurred (errno is set).
Errors:
- EFAULT
- A fault occurred trying to access the buffers provided.
- EINVAL
- The timer timerid isn't attached to the calling process or the number of nanoseconds specified by the tv_nsec member of one of the timespec structures in the itimerspec structure pointed to by value is less than zero or greater than or equal to 1000 million.
- EOVERFLOW
- The sum of the current time and the provided relative time represented as nanoseconds results in a value that exceeds UINT64_MAX.
- EPERM
- The calling process doesn't have the required permission; see procmgr_ability().
Examples:
See timer_create().
Classification:
| Safety: | |
|---|---|
| Cancellation point | No |
| Signal handler | Yes |
| Thread | Yes |