NAME

timer_create – create a timer

SYNOPSIS

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

int timer_create(clockid_t clock_id , struct sigevent *evp,

timer_t *timerid );

struct sigevent {

int sigev_notify /* notification type */

int sigev_signo; /* signal number */

union sigval sigev_value; /* signal value */

};

union sigval {

int sival_int; /* integer value */

void *sival_ptr; /* pointer value */

};

DESCRIPTION

timer_create() creates a timer using the Realtime Clock ID, CLOCK_REALTIME, as the timing base. The timer ID is unique and meaningful only within the calling thread until the timer is deleted. The timer is initially disarmed upon return from timer_create().

The timer is created on a per-thread basis. Expiration signals for the timer will be sent to the creating thread. A timer will NOT be automatically deleted when the creating thread exits. Also, pthread_exit() does NOT delete the timer. The user must do this by calling timer_delete().

If evp is non-NULL: then evp points to a sigevent structure, allocated by the application, which defines the asynchronous notification that will occur when the timer expires.
If the sigev_notify member of evp is

SIGEV_SIGPOST,

then the structure also contains the signal number to be sent to the thread. The application specific data value, sigev_value, is not used. Upon timer expiration, the thread is sent the signal defined in sigev_signo and conditionally added to the ready-to-run queue.
If the sigev_notify member of evp is

SIGEV_NONE

then the sigev_signo and sigev_value are ignored. Upon timer expiration, the thread is added to the ready-to-run queue.

If evp is NULL, a default structure is used with values { SIGEV_SIGPOST, 0, {0} }.

RETURN VALUES

timer_create() returns 0 upon success and creates a timer_t, timerid , which can be passed to the timer calls; otherwise it returns -1 and sets errno.

ERRORS

EAGAIN

The system lacks sufficient signal queuing resources to honor the request. The calling thread has already created all of the timers it is allowed by this implementation.

EINVAL

The specified clock ID, clock_id, is not defined, only CLOCK_REALTIME may be used.
The specified signal notification type, evp->sigev_notify, is invalid.
The specified signal number, evp->sigev_signo, is invalid.

SEE ALSO

time(), clock_settime(), timer_delete(), timer_settime()