TIMER_CREATE(2) BSD System Calls Manual TIMER_CREATE(2)
NAME
timer_create -- create a per-process timer (REALTIME)
LIBRARY
POSIX Real-time Library (librt, -lrt)
SYNOPSIS
#include <time.h>
#include <signal.h>
int
timer_create(clockid_t clockid, struct sigevent *restrict evp, timer_t *restrict timerid);
DESCRIPTION
The timer_create() system call creates a per-process timer using the specified clock, clock_id, as the timing base. The timer_create() sys-
tem call 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 is 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 is 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 noti-
fication to occur 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.
The implementations supports a clock_id of CLOCK_REALTIME or CLOCK_MONOTONIC.
If evp->sigev_notify is SIGEV_THREAD and sev->sigev_notify_attributes is not NULL, if the attribute pointed to by
sev->sigev_notify_attributes has a thread stack address specified by a call to pthread_attr_setstack() or pthread_attr_setstackaddr(), the
results are unspecified if the signal is generated more than once.
RETURN VALUES
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 system call returns a value of -1 and the global variable errno is set to indicate the
error. The value of timerid is undefined if an error occurs.
ERRORS
The timer_create() system call will fail if:
[EAGAIN] The calling process has already created all of the timers it is allowed by this implementation.
[EINVAL] The specified clock ID is not supported.
[EFAULT] Any arguments point outside the allocated address space or there is a memory protection fault.
SEE ALSO
clock_getres(2), timer_delete(2), timer_getoverrun(2), siginfo(3)
STANDARDS
The timer_create() system call conforms to IEEE Std 1003.1-2004 (``POSIX.1'').
HISTORY
Support for POSIX per-process timer first appeared in FreeBSD 7.0.
BSD
January 12, 2009 BSD
