table of contents
| TIMER_CREATE(2) | System Calls Manual | TIMER_CREATE(2) |
NAME¶
timer_create —
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¶
Thetimer_create() system call creates a per-process
timer using the specified clock, clock_id, as the timing
base. The timer_create() system 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 notification to occur when the timer expires.
If evp->sigev_notify is
SIGEV_SIGNO or
SIGEV_THREAD_ID, the signal specified in
evp->sigev_signo will be sent to the calling
process (SIGEV_SIGNO) or to the thread whose LWP ID
is evp->sigev_notify_thread_id
(SIGEV_THREAD_ID). The information for the queued
signal will include:
| Member | Value |
| si_code | SI_TIMER |
| si_value | the value stored in evp->sigev_value |
| si_timerid | timer ID |
| si_overrun | timer overrun count |
| si_errno | If timer overrun is {DELAYTIMER_MAX}, an error
code defined in
<errno.h> |
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 (SIGALRM), and the
sigev_value member having the value of the timer
ID.
This implementation 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¶
Thetimer_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.
- [
EINVAL] - The specified asynchronous notification method 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), sigevent(3), siginfo(3)STANDARDS¶
Thetimer_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.| July 15, 2016 | Linux 4.19.0-10-amd64 |