VxWorks Reference Manual : Libraries
timerLib - timer library (POSIX)
timer_cancel( ) - cancel a timer
timer_connect( ) - connect a user routine to the timer signal
timer_create( ) - allocate a timer using the specified clock for a timing base (POSIX)
timer_delete( ) - remove a previously created timer (POSIX)
timer_gettime( ) - get the remaining time before expiration and the reload value (POSIX)
timer_getoverrun( ) - return the timer expiration overrun (POSIX)
timer_settime( ) - set the time until the next expiration and arm timer (POSIX)
nanosleep( ) - suspend the current task until the time interval elapses (POSIX)
This library provides a timer interface, as defined in the IEEE standard, POSIX 1003.1b.
Timers are mechanisms by which tasks signal themselves after a designated interval. Timers are built on top of the clock and signal facilities. The clock facility provides an absolute time-base. Standard timer functions simply consist of creation, deletion and setting of a timer. When a timer expires, sigaction( ) (see sigLib) must be in place in order for the user to handle the event. The "high resolution sleep" facility, nanosleep( ), allows sub-second sleeping to the resolution of the clock.
The clockLib library should be installed and clock_settime( ) set before the use of any timer routines.
Two non-POSIX functions are provided for user convenience:
timer_cancel( ) quickly disables a timer by calling timer_settime( ).
timer_connect( ) easily hooks up a user routine by calling sigaction( ).
The task creating a timer with timer_create( ) will receive the signal no matter which task actually arms the timer.
When a timer expires and the task has previously exited, logMsg( ) indicates the expected task is not present. Similarly, logMsg( ) indicates when a task arms a timer without installing a signal handler. Timers may be armed but not created or deleted at interrupt level.
The actual clock resolution is hardware-specific and in many cases is 1/60th of a second. This is less than _POSIX_CLOCKRES_MIN, which is defined as 20 milliseconds (1/50th of a second).
timers.h
timerLib, clockLib, sigaction( ), POSIX 1003.1b documentation,
timer_cancel( ) - cancel a timer
int timer_cancel ( timer_t timerid /* timer ID */ )
This routine is a shorthand method of invoking timer_settime( ), which stops a timer.
Non-POSIX.
0 (OK), or -1 (ERROR) if timerid is invalid.
EINVAL
timer_connect( ) - connect a user routine to the timer signal
int timer_connect ( timer_t timerid, /* timer ID */ VOIDFUNCPTR routine, /* user routine */ int arg /* user argument */ )
This routine sets the specified routine to be invoked with arg when fielding a signal indicated by the timer's evp signal number, or if evp is NULL, when fielding the default signal (SIGALRM).
The signal handling routine should be declared as:
void my_handler ( timer_t timerid, /* expired timer ID */ int arg /* user argument */ )
Non-POSIX.
0 (OK), or -1 (ERROR) if the timer is invalid or cannot bind the signal handler.
EINVAL
timer_create( ) - allocate a timer using the specified clock for a timing base (POSIX)
int timer_create ( clockid_t clock_id, /* clock ID (always CLOCK_REALTIME) */ struct sigevent * evp, /* user event handler */ timer_t * pTimer /* ptr to return value */ )
This routine returns a value in pTimer that identifies the timer in subsequent timer requests. The evp argument, if non-NULL, points to a sigevent structure, which is allocated by the application and defines the signal number and application-specific data to be sent to the task when the timer expires. If evp is NULL, a default signal (SIGALRM) is queued to the task, and the signal data is set to the timer ID. Initially, the timer is disarmed.
0 (OK), or -1 (ERROR) if too many timers already are allocated or the signal number is invalid.
EMTIMERS, EINVAL, ENOSYS, EAGAIN, S_memLib_NOT_ENOUGH_MEMORY
timerLib, timer_delete( )
timer_delete( ) - remove a previously created timer (POSIX)
int timer_delete ( timer_t timerid /* timer ID */ )
This routine removes a timer.
0 (OK), or -1 (ERROR) if timerid is invalid.
EINVAL
timerLib, timer_create( )
timer_gettime( ) - get the remaining time before expiration and the reload value (POSIX)
int timer_gettime ( timer_t timerid, /* timer ID */ struct itimerspec * value /* where to return remaining time */ )
This routine gets the remaining time and reload value of a specified timer. Both values are copied to the value structure.
0 (OK), or -1 (ERROR) if timerid is invalid.
EINVAL
timer_getoverrun( ) - return the timer expiration overrun (POSIX)
int timer_getoverrun ( timer_t timerid /* timer ID */ )
This routine returns the timer expiration overrun count for timerid, when called from a timer expiration signal catcher. The overrun count is the number of extra timer expirations that have occurred, up to the implementation-defined maximum _POSIX_DELAYTIMER_MAX. If the count is greater than the maximum, it returns the maximum.
The number of overruns, or _POSIX_DELAYTIMER_MAX if the count equals or is greater than _POSIX_DELAYTIMER_MAX, or -1 (ERROR) if timerid is invalid.
EINVAL, ENOSYS
timer_settime( ) - set the time until the next expiration and arm timer (POSIX)
int timer_settime ( timer_t timerid, /* timer ID */ int flags, /* absolute or relative */ const struct itimerspec * value, /* time to be set */ struct itimerspec * ovalue /* previous time set (NULL=no result) */ )
This routine sets the next expiration of the timer, using the .it_value of value, thus arming the timer. If the timer is already armed, this call resets the time until the next expiration. If .it_value is zero, the timer is disarmed.
If flags is not equal to TIMER_ABSTIME, the interval is relative to the current time, the interval being the .it_value of the value parameter. If flags is equal to TIMER_ABSTIME, the expiration is set to the difference between the absolute time of .it_value and the current value of the clock associated with timerid. If the time has already passed, then the timer expiration notification is made immediately. The task that sets the timer receives the signal; in other words, the taskId is noted. If a timer is set by an ISR, the signal is delivered to the task that created the timer.
The reload value of the timer is set to the value specified by the .it_interval field of value. When a timer is armed with a nonzero .it_interval a periodic timer is set up.
Time values that are between two consecutive non-negative integer multiples of the resolution of the specified timer are rounded up to the larger multiple of the resolution.
If ovalue is non-NULL, the routine stores a value representing the previous amount of time before the timer would have expired. Or if the timer is disarmed, the routine stores zero, together with the previous timer reload value. The ovalue parameter is the same value as that returned by timer_gettime( ) and is subject to the timer resolution.
If clock_settime( ) is called to reset the absolute clock time after a timer has been set with timer_settime( ), and if flags is equal to TIMER_ABSTIME, then the timer will behave unpredictably. If you must reset the absolute clock time after setting a timer, do not use flags equal to TIMER_ABSTIME.
0 (OK), or -1 (ERROR) if timerid is invalid, the number of nanoseconds specified by value is less than 0 or greater than or equal to 1,000,000,000, or the time specified by value exceeds the maximum allowed by the timer.
EINVAL
nanosleep( ) - suspend the current task until the time interval elapses (POSIX)
int nanosleep ( const struct timespec * rqtp, /* time to delay */ struct timespec * rmtp /* premature wakeup (NULL=no result) */ )
This routine suspends the current task for a specified time rqtp or until a signal or event notification is made.
The suspension may be longer than requested due to the rounding up of the request to the timer's resolution or to other scheduling activities (e.g., a higher priority task intervenes).
If rmtp is non-NULL, the timespec structure is updated to contain the amount of time remaining. If rmtp is NULL, the remaining time is not returned. The rqtp parameter is greater than 0 or less than or equal to 1,000,000,000.
0 (OK), or -1 (ERROR) if the routine is interrupted by a signal or an asynchronous event notification, or rqtp is invalid.
EINVAL, EINTR