Xenomai API  2.6.5
Clocks and timers services.

Clocks and timers services. More...

Functions

int clock_getres (clockid_t clock_id, struct timespec *res)
 Get the resolution of the specified clock. More...
 
int clock_gettime (clockid_t clock_id, struct timespec *tp)
 Read the specified clock. More...
 
int clock_settime (clockid_t clock_id, const struct timespec *tp)
 Set the specified clock. More...
 
int clock_nanosleep (clockid_t clock_id, int flags, const struct timespec *rqtp, struct timespec *rmtp)
 Sleep some amount of time. More...
 
int nanosleep (const struct timespec *rqtp, struct timespec *rmtp)
 Sleep some amount of time. More...
 
int timer_create (clockid_t clockid, const struct sigevent *__restrict__ evp, timer_t *__restrict__ timerid)
 Create a timer object. More...
 
int timer_delete (timer_t timerid)
 Delete a timer object. More...
 
int timer_settime (timer_t timerid, int flags, const struct itimerspec *__restrict__ value, struct itimerspec *__restrict__ ovalue)
 Start or stop a timer. More...
 
int timer_gettime (timer_t timerid, struct itimerspec *value)
 Get timer next expiration date and reload value. More...
 
int timer_getoverrun (timer_t timerid)
 Get expiration overruns count since the most recent timer expiration signal delivery. More...
 

Detailed Description

Clocks and timers services.

Xenomai POSIX skin supports two clocks:

CLOCK_REALTIME maps to the nucleus system clock, keeping time as the amount of time since the Epoch, with a resolution of one system clock tick.

CLOCK_MONOTONIC maps to an architecture-dependent high resolution counter, so is suitable for measuring short time intervals. However, when used for sleeping (with clock_nanosleep()), the CLOCK_MONOTONIC clock has a resolution of one system clock tick, like the CLOCK_REALTIME clock.

Timer objects may be created with the timer_create() service using either of the two clocks, but the resolution of these timers is one system clock tick, as is the case for clock_nanosleep().

Note
The duration of the POSIX clock tick depends on the active time base (configurable at compile-time with the constant CONFIG_XENO_OPT_POSIX_PERIOD, and at run-time with the xeno_posix module parameter tick_arg). When the time base is aperiodic (which is the default) the system clock tick is one nanosecond.
See Also
Specification.

Function Documentation

int clock_getres ( clockid_t  clock_id,
struct timespec *  res 
)

Get the resolution of the specified clock.

This service returns, at the address res, if it is not NULL, the resolution of the clock clock_id.

For both CLOCK_REALTIME and CLOCK_MONOTONIC, this resolution is the duration of one system clock tick. No other clock is supported.

Parameters
clock_idclock identifier, either CLOCK_REALTIME or CLOCK_MONOTONIC;
resthe address where the resolution of the specified clock will be stored on success.
Return values
0on success;
-1with errno set if:
  • EINVAL, clock_id is invalid;
See Also
Specification.
int clock_gettime ( clockid_t  clock_id,
struct timespec *  tp 
)

Read the specified clock.

This service returns, at the address tp the current value of the clock clock_id. If clock_id is:

  • CLOCK_REALTIME, the clock value represents the amount of time since the Epoch, with a precision of one system clock tick;
  • CLOCK_MONOTONIC, the clock value is given by an architecture-dependent high resolution counter, with a precision independent from the system clock tick duration.
  • CLOCK_HOST_REALTIME, the clock value as seen by the host, typically Linux. Resolution and precision depend on the host, but it is guaranteed that both, host and Xenomai, see the same information.
Parameters
clock_idclock identifier, either CLOCK_REALTIME, CLOCK_MONOTONIC, or CLOCK_HOST_REALTIME;
tpthe address where the value of the specified clock will be stored.
Return values
0on success;
-1with errno set if:
  • EINVAL, clock_id is invalid.
See Also
Specification.

References xntbase_get_time().

int clock_nanosleep ( clockid_t  clock_id,
int  flags,
const struct timespec *  rqtp,
struct timespec *  rmtp 
)

Sleep some amount of time.

This service suspends the calling thread until the wakeup time specified by rqtp, or a signal is delivered to the caller. If the flag TIMER_ABSTIME is set in the flags argument, the wakeup time is specified as an absolute value of the clock clock_id. If the flag TIMER_ABSTIME is not set, the wakeup time is specified as a time interval.

If this service is interrupted by a signal, the flag TIMER_ABSTIME is not set, and rmtp is not NULL, the time remaining until the specified wakeup time is returned at the address rmtp.

The resolution of this service is one system clock tick.

Parameters
clock_idclock identifier, either CLOCK_REALTIME or CLOCK_MONOTONIC.
flagsone of:
  • 0 meaning that the wakeup time rqtp is a time interval;
  • TIMER_ABSTIME, meaning that the wakeup time is an absolute value of the clock clock_id.
rqtpaddress of the wakeup time.
rmtpaddress where the remaining time before wakeup will be stored if the service is interrupted by a signal.
Returns
0 on success;
an error number if:
  • EPERM, the caller context is invalid;
  • ENOTSUP, the specified clock is unsupported;
  • EINVAL, the specified wakeup time is invalid;
  • EINTR, this service was interrupted by a signal.
Valid contexts:
  • Xenomai kernel-space thread,
  • Xenomai user-space thread (switches to primary mode).
See Also
Specification.

References XNBREAK, XNDELAY, and xnpod_suspend_thread().

Referenced by nanosleep().

int clock_settime ( clockid_t  clock_id,
const struct timespec *  tp 
)

Set the specified clock.

This allow setting the CLOCK_REALTIME clock.

Parameters
clock_idthe id of the clock to be set, only CLOCK_REALTIME is supported.
tpthe address of a struct timespec specifying the new date.
Return values
0on success;
-1with errno set if:
  • EINVAL, clock_id is not CLOCK_REALTIME;
  • EINVAL, the date specified by tp is invalid.
See Also
Specification.

References xntbase_adjust_time(), and xntbase_get_time().

int nanosleep ( const struct timespec *  rqtp,
struct timespec *  rmtp 
)

Sleep some amount of time.

This service suspends the calling thread until the wakeup time specified by rqtp, or a signal is delivered. The wakeup time is specified as a time interval.

If this service is interrupted by a signal and rmtp is not NULL, the time remaining until the specified wakeup time is returned at the address rmtp.

The resolution of this service is one system clock tick.

Parameters
rqtpaddress of the wakeup time.
rmtpaddress where the remaining time before wakeup will be stored if the service is interrupted by a signal.
Return values
0on success;
-1with errno set if:
  • EPERM, the caller context is invalid;
  • EINVAL, the specified wakeup time is invalid;
  • EINTR, this service was interrupted by a signal.
Valid contexts:
  • Xenomai kernel-space thread,
  • Xenomai user-space thread (switches to primary mode).
See Also
Specification.

References clock_nanosleep().

int timer_create ( clockid_t  clockid,
const struct sigevent *__restrict__  evp,
timer_t *__restrict__  timerid 
)

Create a timer object.

This service creates a time object using the clock clockid.

If evp is not NULL, it describes the notification mechanism used on timer expiration. Only notification via signal delivery is supported (member sigev_notify of evp set to SIGEV_SIGNAL). The signal will be sent to the thread starting the timer with the timer_settime() service. If evp is NULL, the SIGALRM signal will be used.

Note that signals sent to user-space threads will cause them to switch to secondary mode.

If this service succeeds, an identifier for the created timer is returned at the address timerid. The timer is unarmed until started with the timer_settime() service.

Parameters
clockidclock used as a timing base;
evpdescription of the asynchronous notification to occur when the timer expires;
timeridaddress where the identifier of the created timer will be stored on success.
Return values
0on success;
-1with errno set if:
  • EINVAL, the clock clockid is invalid;
  • EINVAL, the member sigev_notify of the sigevent structure at the address evp is not SIGEV_SIGNAL;
  • EINVAL, the member sigev_signo of the sigevent structure is an invalid signal number;
  • EAGAIN, the maximum number of timers was exceeded, recompile with a larger value.
See Also
Specification.

References xntimer_init().

int timer_delete ( timer_t  timerid)

Delete a timer object.

This service deletes the timer timerid.

Parameters
timerididentifier of the timer to be removed;
Return values
0on success;
-1with errno set if:
  • EINVAL, timerid is invalid;
  • EPERM, the timer timerid does not belong to the current process.
See Also
Specification.
int timer_getoverrun ( timer_t  timerid)

Get expiration overruns count since the most recent timer expiration signal delivery.

This service returns timerid expiration overruns count since the most recent timer expiration signal delivery. If this count is more than DELAYTIMER_MAX expirations, DELAYTIMER_MAX is returned.

Parameters
timeridTimer identifier.
Returns
the overruns count on success;
-1 with errno set if:
  • EINVAL, timerid is invalid;
  • EPERM, the timer timerid does not belong to the current process.
See Also
Specification.
int timer_gettime ( timer_t  timerid,
struct itimerspec *  value 
)

Get timer next expiration date and reload value.

This service stores, at the address value, the expiration date (member it_value) and reload value (member it_interval) of the timer timerid. The values are returned as time intervals, and as multiples of the system clock tick duration (see note in section Clocks and timers services for details on the duration of the system clock tick). If the timer was not started, the returned members it_value and it_interval of value are zero.

Parameters
timeridtimer identifier;
valueaddress where the timer expiration date and reload value are stored on success.
Return values
0on success;
-1with errno set if:
  • EINVAL, timerid is invalid;
  • EPERM, the timer timerid does not belong to the current process.
See Also
Specification.
int timer_settime ( timer_t  timerid,
int  flags,
const struct itimerspec *__restrict__  value,
struct itimerspec *__restrict__  ovalue 
)

Start or stop a timer.

This service sets a timer expiration date and reload value of the timer timerid. If ovalue is not NULL, the current expiration date and reload value are stored at the address ovalue as with timer_gettime().

If the member it_value of the itimerspec structure at value is zero, the timer is stopped, otherwise the timer is started. If the member it_interval is not zero, the timer is periodic. The current thread must be a POSIX skin thread (created with pthread_create()) and will be notified via signal of timer expirations. Note that these notifications will cause user-space threads to switch to secondary mode.

When starting the timer, if flags is TIMER_ABSTIME, the expiration value is interpreted as an absolute date of the clock passed to the timer_create() service. Otherwise, the expiration value is interpreted as a time interval.

Expiration date and reload value are rounded to an integer count of system clock ticks (see note in section Clocks and timers services for details on the duration of the system tick).

Parameters
timerididentifier of the timer to be started or stopped;
flagsone of 0 or TIMER_ABSTIME;
valueaddress where the specified timer expiration date and reload value are read;
ovalueaddress where the specified timer previous expiration date and reload value are stored if not NULL.
Return values
0on success;
-1with errno set if:
  • EPERM, the caller context is invalid;
  • EINVAL, the specified timer identifier, expiration date or reload value is invalid;
  • EPERM, the timer timerid does not belong to the current process.
Valid contexts:
  • Xenomai kernel-space POSIX skin thread,
  • kernel-space thread cancellation cleanup routine,
  • Xenomai POSIX skin user-space thread (switches to primary mode),
  • user-space thread cancellation cleanup routine.
See Also
Specification.

References xntimer_start(), and xntimer_stop().