Get information about a timer
Synopsis:
#include <sys/neutrino.h>
int TimerInfo( pid_t pid,
timer_t id,
int flags,
struct _timer_info* info );
int TimerInfo_r( pid_t pid,
timer_t id,
int flags,
struct _timer_info* info );
Arguments:
- pid
- The process ID that you're requesting the timer information for.
- id
- The ID of the timer, as returned by
TimerCreate().
- flags
- Supported flags are:
- _NTO_TIMER_SEARCH
— if this flag is specified and the timer ID doesn't exist,
return information on the next timer ID.
This provides a mechanism to discover all of the timers in the process.
- _NTO_TIMER_RESET_OVERRUNS
— reset the timer's overrun count to zero.
- _NTO_TI_REPORT_TOLERANCE — store the timer tolerance in the
otime.interval_nsec member of the _timer_info structure.
- info
- A pointer to a _timer_info structure where the function
can store the information about the specified timer.
For more details, see
"struct _timer_info,"
below.
You can pass NULL for this argument if the only bit set
in flags is _NTO_TIMER_RESET_OVERRUNS.
Library:
libc
Use the -l c option to
qcc
to link against this library.
This library is usually included automatically.
Description:
These kernel calls get information about a previously
created timer specified by id, and store the information in the buffer
pointed to by info.
The TimerInfo() and TimerInfo_r()
functions are identical except in the way they indicate errors.
See the Returns section for details.
Note:
- Instead of using these kernel calls directly, consider calling
timer_getexpstatus(),
timer_getoverrun(),
or
timer_gettime().
- In order to get timer information about a process belonging to a different user and
simultaneously use the _NTO_TIMER_RESET_OVERRUNS flag,
your process must have the PROCMGR_AID_TIMER ability enabled.
For more information, see
procmgr_ability().
- There's no generic way to query when a timer was activated. However, you can determine the
activation time by reading the timer information after activation (TimerSettime() activates the
timer) but before the first time the timer is fired, and then subtract the known initial
interval (that is, for TimerSettime(), the value of struct
_itimer
nsec).
struct _timer_info
The _timer_info structure pointed to by info
contains at least these members:
- uint32_t flags
- One or more of these bit flags:
- _NTO_TI_ABSOLUTE
- The timer is waiting for an absolute time to occur; otherwise, the timer is relative.
- _NTO_TI_ACTIVE
- The timer is active.
- _NTO_TI_EXPIRED
- The timer has expired.
- _NTO_TI_PRECISE
- The timer is precise, and excludes any default tolerance that was set for
the process (see
procmgr_timer_tolerance()).
- _NTO_TI_PROCESS_TOLERANT
- The timer is using the process's default tolerance.
- _NTO_TI_TARGET_PROCESS
- The timer targets the process, not a specific thread.
- _NTO_TI_TOD_BASED
- The timer the timer is based relative to the beginning of the Epoch (January 1, 1970, 00:00:00 GMT);
otherwise, it's relative to the time that QNX Neutrino was started on the machine
(see the system page qtime boot_time member).
- _NTO_TI_TOLERANT
- The timer has a nonzero tolerance (which could be the process's default tolerance).
- int32_t tid
- The thread to which the timer is directed (0 if it's directed to the process).
- int32_t notify
- The bottom 16 bits are the value of sigev_notify for the associated
sigevent.
The other bits are used internally.
- clockid_t clockid
- The type of clock used.
- uint32_t overruns
- The number of overruns.
- struct sigevent event
- The event dispatched when the timer expires.
- struct _itimer itime
A
struct _itimer with the following fields:
- uint64_t
nsec
- When the timer is next scheduled to fire.
- uint64_t
interval_nsec
- The timer's interval.
- struct _itimer otime
- The time remaining before the timer expires.
If you specified _NTO_TI_REPORT_TOLERANCE in the flags argument,
otime.interval_nsec is set to the timer tolerance.
For more information, see the description of
TimerCreate().
Blocking states
These calls don't block.
Returns:
The ID of the timer that the information is for.
If an error occurs:
- TimerInfo() returns -1 and sets
errno.
- TimerInfo_r() returns the negative of a value from the Errors section and
doesn't set errno.
Errors:
- EINVAL
- The timer specified by id doesn't exist.
- EPERM
- The calling process doesn't have the required permission; see
procmgr_ability().
- ESRCH
- The process specified by pid doesn't exist.
Classification:
QNX Neutrino
Safety: |
|
Cancellation point |
No |
Interrupt handler |
No |
Signal handler |
Yes |
Thread |
Yes |