ClockTime(), ClockTime_r()

Get or set a clock

Synopsis:

#include <sys/neutrino.h>

int ClockTime( clockid_t id,
               const uint64_t * new,
               uint64_t * old );

int ClockTime_r( clockid_t id,
                 const uint64_t * new,
                 uint64_t * old );

Arguments:

id: The clock ID. This must be CLOCK_REALTIME or CLOCK_MONOTONIC, which is the ID of the clock that maintains the system time, or a CPU-time clock ID returned by ClockId().
new: NULL, or a pointer to the absolute time, in nanoseconds, to set the clock to. This is used only if id is CLOCK_REALTIME.
old: NULL, or a pointer to a location where the function can store the current time (before being changed by a non-NULL new).

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

You can use these kernel calls to:

get or set the system clock if id is CLOCK_REALTIME
get the system clock if id is CLOCK_MONOTONIC
get the CPU-time clock for a process or a particular thread in a process, if the ID is one that you obtained by calling ClockId(). On an SMP box, the time for a process may exceed the realtime number of nanoseconds that have elapsed because multiple threads in the process can run on several CPUs at the same time.

The ClockTime() and ClockTime_r() functions are identical except in the way they indicate errors. See the Returns section for details.

Instead of using these kernel calls directly, consider calling clock_gettime() or clock_settime().

If new isn't NULL, then it contains the absolute time, in nanoseconds, to set the system clock to. This affects the software clock maintained by the system. It doesn't change any underlying hardware clock that maintains the time when the system's power is turned off.

In order to set the clock, your process must have the PROCMGR_AID_CLOCKSET ability enabled. For more information, see procmgr_ability(). You set the time only when the id is CLOCK_REALTIME.

If you call ClockTime() to set the time of day, the kernel checks to see if the SYSPAGE_ENTRY(qtime)->boot_time field is zero. If it is, the kernel sets it to the appropriate value. There's a -T option for all startup programs that prevents the setting of this field, so that the kernel will set it the first time you call ClockTime() to change the time of day. This is useful if the RTC hardware isn't in UTC.

Once set, the system time increments by some number of nanoseconds, based on the resolution of the system clock. You can query or change this resolution by using the ClockPeriod() kernel call.

Blocking states

These calls don't block.

Returns:

The only difference between these functions is the way they indicate errors:

ClockTime(): If an error occurs, the function returns -1 and sets errno. Any other value returned indicates success.
ClockTime_r(): EOK is returned on success. This function does NOT set errno. If an error occurs, the function returns a value in the Errors section.

Errors:

EFAULT: A fault occurred when the kernel tried to access the buffers provided.
EINVAL: The clock ID isn't valid, or you tried to set the time for an ID other than CLOCK_REALTIME.
EPERM: The process tried to change the time without having the required permission; see procmgr_ability().
ESRCH: The process associated with this request doesn't exist.

Classification:

QNX Neutrino

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes

ClockTime(), ClockTime_r()

Synopsis:

Arguments:

Library:

Description:

Returns:

Errors:

Classification:

Related links