TIMER_CREATE(3)

NAME
timer_create - create a POSIX timer

SYNOPSIS
cc [ flag ... ] file -lrt [ library ... ]

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

int timer_create(clockid_t which_clock, struct sigevent *timer_event_spec, timer_t *created_timer_id);

DESCRIPTION
timer_create creates an interval timer based on the POSIX 1003.1b standard using the clock type specified by which_clock. The timer ID is stored in the timer_t value pointed to by created_timer_id. The timer is started by timer_settime(3).

If timer_event_spec is non-NULL, it specifies the behavior on timer expiration. If the sigev_notify member of timer_event_spec is SIGEV_SIGNAL then the signal specified by sigev_signo is sent to the process on expiration.

If the value is SIGEV_THREAD_ID then the sigev_notify_thread_id member of timer_event_spec should contain the pthread_t id of the thread that is to receive the signal.

If the value is SIGEV_THREAD then the specified sigev_notify_function is created in a new thread with sigev_value as the argument.

If the value is SIGEV_NONE then no signal is sent.

SIGEV_THREAD_ID and SIGEV_SIGNAL are compatible and may be ORed together.

If timer_event_spec is NULL, SIGALRM is sent to the process upon timer expiration with the value of the timer ID, timer_id.

The maximum number of timers is a system-wide value, set at kernel configure time, which is generally quite high.

Each timer is owned by a specific thread. The owning thread is either the calling thread or the thread specified by SIGEV_THREAD_ID. The owning thread receives the signal on timer expiration. If the owning thread exits all of its timers are disabled and deleted. Any thread in a process, however, may make calls on the timer. Timers are not inherited by a child process across a fork(2) and are disabled and deleted by a call to one of the exec functions.

For a listing of valid clocks, see clock_gettime(3). Note CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID are not supported by timer_create(3).

  Thread support
Note SIGEV_THREAD_ID support requires thread groups. Currently the linuxthreads package does not use thread groups. NG-threads, based on GNU-pth, does use thread groups and is compatible.

RETURN VALUE
On success, timer_create returns a value of 0 and the timer ID of the new timer is placed in created_timer_id.

On failure, timer_create returns a value of -1 and errno is set appropriately.

ERRORS

EAGAIN
    The system is incapable of allocating a new timer or signal. Possible reasons include the number of timers exceeding the system wide maximum timers set at system configure time or insufficient resources.

EFAULT
    A specified memory address is outside the address range of the calling process.

EINVAL
    The specified clock ID, sigev_signo, sigev_notify, or SIGEV_THREAD_ID value is invalid.

ENOSYS
    The timer_create(3) function is not supported by the system.

CONFORMING TO
POSIX 1003.1b (formerly POSIX.4) as ammended by POSIX 1003.1j-2000.

The SIGEV_THREAD_ID value is an extension to this standard intended to overcome the lack of process signals in Linux.

SEE ALSO
clock_getres(3), clock_gettime(3), clock_settime(3), clock_nanosleep(3), timer_delete(3), timer_settime(3), timer_gettime(3), timer_getoverrun(3)

IEEE 1003.1b-1993 (POSIX.1b standard, formerly POSIX.4), Section 14 (Clocks and Timers).