timer_create(3c)timer_create(3c)NAMEtimer_create - create a POSIX timer
SYNOPSIS
#include <signal.h>
#include <time.h>
int timer_create(clockid_t clock_id, struct sigevent *evp, timer_t *
timerid);
DESCRIPTIONtimer_create creates an interval timer for the calling process based on
the clock named by clock_id. The new timer ID is recorded at the memory
address timerid, and is unique for the calling process until the timer is
deleted. A process may create up to {TIMER_MAX} POSIX timers [see
sysconf(3C)].
Supported clocks for clock_id are:
CLOCK_REALTIME The system's notion of the current time is obtained with
this clock. The time is expressed in seconds and
nanoseconds since midnight (00:00) Coordinated Universal
Time (UTC), January 1, 1970. The resolution for of this
clock is never worse than 100 HZ (which equals 10
milliseconds). The actual resolution of the clock depends
on the timer capability of the underlying hardware (see
timers(5)).
CLOCK_SGI_FAST This clock has a higher resolution than CLOCK_REALTIME and
is available to privileged users only. This clock is SGI
specific and is not portable.
The resolution of the clocks can be obtained by calling the clock_getres
function.
The timer created can be started by calling the function timer_settime.
If the value of evp is non-NULL, then a notification specified in the evp
sigevent structure is sent to the process.
If the sigev_notify member of evp is SIGEV_SIGNAL then the specified
signal in the sigev_signo member of evp is sent to the process and if the
value is SIGEV_NONE no signal is sent upon timer expiration.
If the sigev_notify member of evp is SIGEV_THREAD then the function
sigev_notify_function will be called by a new thread (see pthreads(5))
with sigev_value as the argument. This thread is created when the event
arrives with the attributes specified in sigev_notify_attributes except
that it is automatically detached. The calling process should ensure
there are sufficient resources to create the thread.
Page 1
timer_create(3c)timer_create(3c)
If the evp argument is NULL, then the signal SIGALRM is sent to the
process, upon timer expiration.
The timers are not inherited across the fork, sproc, or exec system
calls.
timer_create will fail if one or more of the following are true:
[EAGAIN] The calling process has reached its per-process timer
creation limit of {TIMER_MAX}.
[EAGAIN] The system lacks sufficient resources for queuing
additional signals.
[EINVAL] The specified clock ID is invalid. Or the signal specified
in the evp structure is invalid.
[EPERM] The process is not privileged to create a timer of the
specified clock type.
[EFAULT] The address specified by either timerid or evp is outside
the range of the address space of the calling process.
SEE ALSOtimer_delete(3C), timer_settime(3C), timer_gettime(3C),
timer_getoverrun(3C), clock_getres(2), sigaction(2), sysconf(3C),
pthreads(5)DIAGNOSTICS
Upon successful completion, a value of 0 is returned and the timer ID of
the created timer is set in the location pointed to by the timerid
argument. Otherwise, a value of -1 is returned and errno is set to
indicate the error.
Page 2
