Clocks and timers services. More...

Collaboration diagram for Clocks and timers services.:

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_id	clock identifier, either CLOCK_REALTIME or CLOCK_MONOTONIC;
res	the address where the resolution of the specified clock will be stored on success.

Return values

0	on success;
-1	with 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_id	clock identifier, either CLOCK_REALTIME, CLOCK_MONOTONIC, or CLOCK_HOST_REALTIME;
tp	the address where the value of the specified clock will be stored.

Return values

0	on success;
-1	with 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_id	clock identifier, either CLOCK_REALTIME or CLOCK_MONOTONIC.
flags	one 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.
rqtp	address of the wakeup time.
rmtp	address 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_id	the id of the clock to be set, only CLOCK_REALTIME is supported.
tp	the address of a struct timespec specifying the new date.

Return values

0	on success;
-1	with 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

rqtp	address of the wakeup time.
rmtp	address where the remaining time before wakeup will be stored if the service is interrupted by a signal.

Return values

0	on success;
-1	with 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

clockid	clock used as a timing base;
evp	description of the asynchronous notification to occur when the timer expires;
timerid	address where the identifier of the created timer will be stored on success.

Return values

0	on success;
-1	with 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

timerid identifier of the timer to be removed;

Return values

0	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_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

timerid Timer 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

timerid	timer identifier;
value	address where the timer expiration date and reload value are stored on success.

Return values

0	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_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

timerid	identifier of the timer to be started or stopped;
flags	one of 0 or TIMER_ABSTIME;
value	address where the specified timer expiration date and reload value are read;
ovalue	address where the specified timer previous expiration date and reload value are stored if not NULL.

Return values

0	on success;
-1	with 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().

Functions

Detailed Description

Function Documentation