ClockPeriod(), ClockPeriod_r()
Get or set a clock period
Synopsis:
#include <sys/neutrino.h> int ClockPeriod( clockid_t id, const struct _clockperiod * new, struct _clockperiod * old, int reserved ); int ClockPeriod_r( clockid_t id, const struct _clockperiod * new, struct _clockperiod * old, int reserved );
Arguments:
- id
- The clock ID of the clock; one of the following:
- CLOCK_REALTIME — the clock that maintains the system time.
- CLOCK_HARMONIC — the clock that maintains the harmonic timer boundary. Timers whose remaining time before expiry is greater than this boundary are considered for timer harmonization; for more information, see Clocks, timers, and power management in the Tick, Tock: Understanding the Microkernel's Concept of Time chapter of the BlackBerry 10 OS Programmer's Guide.
- new
- NULL, or a pointer to a _clockperiod
structure that contains the period to set the clock to.
This structure contains at least the following members:
- unsigned long nsec—the period of
the clock, in nanoseconds.
For CLOCK_HARMONIC, this period is in seconds, not nanoseconds.
- long fract—reserved for future fractional nanoseconds. Set this member to zero.
- unsigned long nsec—the period of
the clock, in nanoseconds.
- old
- NULL, or a pointer to a _clockperiod structure where the function can store the current period (before being changed by a non-NULL new).
- reserved
- Set this argument to 0.
Library:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
Description:
You can use the ClockPeriod() and ClockPeriod_r() kernel calls to get or set the clock period of the clock. These functions are identical except in the way they indicate errors. See the Returns section for details.
- If you want to get the clock period, consider calling clock_getres() instead of using these kernel calls directly.
- In order to set the clock period, your process must have the PROCMGR_AID_CLOCKPERIOD ability enabled. For more information, see procmgr_ability().
All the timer_*() calls operate with an accuracy no better than the clock period. Every moment within the QNX Neutrino microkernel is referred to as a tick. A tick's initial length is determined by the clock rate of your processor:
| CPU clock speed: | Default value: |
|---|---|
| ≥ 40MHz | 1 millisecond |
| < 40MHz | 10 milliseconds |
Since a very small tick size imposes an interrupt load on the system, and can consume all available processor cycles, the kernel call limits how small a period can be specified. The lowest clock period that can currently be set on any machine is 10 microseconds.
If an attempt is made to set a value that the kernel believes to be unsafe, the call fails with an EINVAL. The timeslice rate (for round-robin and other scheduling policies) is always four times the clock period (this isn't changeable).
Blocking states
These calls don't block.
Returns:
The only difference between these functions is the way they indicate errors:
- ClockPeriod()
- If an error occurs, this function returns -1 is and sets errno. Any other value returned indicates success.
- ClockPeriod_r()
- EOK is returned on success. This function does NOT set errno. If an error occurs, the function can return any value in the Errors section.
Errors:
- EFAULT
- A fault occurred when the kernel tried to access the buffers provided.
- EINVAL
- Invalid clock ID. A period was set which wasn't in a range considered safe.
- EPERM
- The process tried to change the period of the clock without having the required permission; see procmgr_ability().
Classification:
| Safety: | |
|---|---|
| Cancellation point | No |
| Interrupt handler | No |
| Signal handler | Yes |
| Thread | Yes |
Last modified: 2013-09-30