NAME

timer_create - create a per-process timer (REALTIME)

 SYNOPSIS

#include <time.h>
#include <signal.h>

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

 DESCRIPTION

The timer_create() function creates a per-process timer using the specified clock, clock_id, as the timing base. The timer_create() function returns, in the location referenced by timerid, a timer ID of type timer_t used to identify the timer in timer requests. This timer ID will be unique within the calling process until the timer is deleted. The particular clock, clock_id, is defined in <time.h>. The timer whose ID is returned will be in a disarmed state upon return from timer_create().

The evp argument, if non-NULL, points to a sigevent structure. This structure, allocated by the application, defines the asynchronous notification to occur as specified in Signal Generation and Delivery when the timer expires. If the evp argument is NULL, the effect is as if the evp argument pointed to a sigevent structure with the sigev_notify member having the value SIGEV_SIGNAL, the sigev_signo having a default signal number, and the sigev_value member having the value of the timer ID.

Each implementation defines a set of clocks that can be used as timing bases for per-process timers. All implementations support a clock_id of CLOCK_REALTIME.

Per-process timers are not inherited by a child process across a fork() and are disarmed and deleted by an exec.

 RETURN VALUE

If the call succeeds, timer_create() returns zero and updates the location referenced by timerid to a timer_t, which can be passed to the per-process timer calls. If an error occurs, the function returns a value of -1 and sets errno to indicate the error. The value of timerid is undefined if an error occurs.

 ERRORS

The timer_create() function will fail if:

[EAGAIN]

The system lacks sufficient signal queuing resources to honour the request.

[EAGAIN]

The calling process has already created all of the timers it is allowed by this implementation.

[EINVAL]

The specified clock ID is not defined.

[ENOSYS]

The function timer_create() is not supported by this implementation.

 EXAMPLES

None.

 APPLICATION USAGE

None.

 FUTURE DIRECTIONS

None.

 SEE ALSO

timer_delete(), clock_gettime(), clock_settime(), clock_getres(), timer_gettime(), timer_settime(), <time.h>.

DERIVATION

Derived from the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995)