VxWorks Reference Manual : Libraries

clockLib

NAME

clockLib - clock library (POSIX)

ROUTINES

clock_getres( ) - get the clock resolution (POSIX)
clock_setres( ) - set the clock resolution
clock_gettime( ) - get the current time of the clock (POSIX)
clock_settime( ) - set the clock to a specified time (POSIX)

DESCRIPTION

This library provides a clock interface, as defined in the IEEE standard, POSIX 1003.1b.

A clock is a software construct that keeps time in seconds and nanoseconds. The clock has a simple interface with three routines: clock_settime( ), clock_gettime( ), and clock_getres( ). The non-POSIX routine clock_setres( ) is provided (temporarily) so that clockLib is informed if there are changes in the system clock rate (e.g., after a call to sysClkRateSet( )).

Times used in these routines are stored in the timespec structure:

struct timespec
    {
    time_t      tv_sec;         /* seconds */
    long        tv_nsec;        /* nanoseconds (0 -1,000,000,000) */
    };

IMPLEMENTATION

Only one clock_id is supported, the required CLOCK_REALTIME. Conceivably, additional "virtual" clocks could be supported, or support for additional auxiliary clock hardware (if available) could be added.

INCLUDE FILES

timers.h

SEE ALSO

clockLib, IEEE VxWorks Programmer's Guide: Basic OS, POSIX 1003.1b documentation

---

Libraries : Routines

clock_getres( )

NAME

clock_getres( ) - get the clock resolution (POSIX)

SYNOPSIS

int clock_getres
    (
    clockid_t         clock_id, /* clock ID (always CLOCK_REALTIME) */
    struct timespec * res       /* where to store resolution */
    )

DESCRIPTION

This routine gets the clock resolution, in nanoseconds, based on the rate returned by sysClkRateGet( ). If res is non-NULL, the resolution is stored in the location pointed to.

RETURNS

0 (OK), or -1 (ERROR) if clock_id is invalid.

ERRNO

EINVAL

SEE ALSO

clockLib, clock_settime( ), sysClkRateGet( ), clock_setres( )

---

Libraries : Routines

clock_setres( )

NAME

clock_setres( ) - set the clock resolution

SYNOPSIS

int clock_setres
    (
    clockid_t         clock_id, /* clock ID (always CLOCK_REALTIME) */
    struct timespec * res       /* resolution to be set */
    )

DESCRIPTION

This routine sets the clock resolution in the POSIX timers data structures. It does not affect the system clock or auxiliary clocks. This routine should be called to inform the POSIX timers of the new clock resolution if sysClkRateSet( ) has been called after this library has been initialized.

If res is non-NULL, the resolution to be set is stored in the location pointed to; otherwise, this routine has no effect.

NOTE

Non-POSIX.

RETURNS

0 (OK), or -1 (ERROR) if clock_id is invalid or the resolution is greater than 1 second.

ERRNO

EINVAL

SEE ALSO

clockLib, clock_getres( ), sysClkRateSet( )

---

Libraries : Routines

clock_gettime( )

NAME

clock_gettime( ) - get the current time of the clock (POSIX)

SYNOPSIS

int clock_gettime
    (
    clockid_t         clock_id, /* clock ID (always CLOCK_REALTIME) */
    struct timespec * tp        /* where to store current time */
    )

DESCRIPTION

This routine gets the current value tp for the clock.

RETURNS

0 (OK), or -1 (ERROR) if clock_id is invalid or tp is NULL.

ERRNO

EINVAL, EFAULT

SEE ALSO

clockLib

---

Libraries : Routines

clock_settime( )

NAME

clock_settime( ) - set the clock to a specified time (POSIX)

SYNOPSIS

int clock_settime
    (
    clockid_t               clock_id, /* clock ID (always CLOCK_REALTIME) */
    const struct timespec * tp        /* time to set */
    )

DESCRIPTION

This routine sets the clock to the value tp, which should be a multiple of the clock resolution. If tp is not a multiple of the resolution, it is truncated to the next smallest multiple of the resolution.

RETURNS

0 (OK), or -1 (ERROR) if clock_id is invalid, tp is outside the supported range, or the tp nanosecond value is less than 0 or equal to or greater than 1,000,000,000.

ERRNO

EINVAL

SEE ALSO

clockLib, clock_getres( )