'\"macro stdmacro
.Op c p a
.TH timer_create 3c
.SH NAME
\f4timer_create\fP \- create a posix timer
.SH SYNOPSIS
.nf
\f4#include <signal.h>\f1
\f4#include <time.h>\f1
.fi
.PP
\f4timer_create(clockid_t \f2clock_id\fP, struct sigevent *\f2evp\fP, timer_t *\f2timerid\fP);\f1
.SH DESCRIPTION
\f4timer_create\fP creates an interval timer for the calling process based on
the clock named
by \f2clock_id\fP.
The new timer ID is recorded at the memory address \f2timerid\fP, and is
unique for the calling process until the timer is deleted.  A process may
create up to {\f4TIMER_MAX\fP} posix timers [see \f4sysconf\fP(3C)].
.P
Supported clocks for
\f2clock_id\fP
are:
.TP15
.SM
\%\f4CLOCK_REALTIME\f1
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)).
.TP15
.SM
\%\f4CLOCK_SGI_FAST\f1
This clock has a higher resolution than \f4CLOCK_REALTIME\fP and is
available to privileged users only.
This clock is SGI specific and is not portable.
.PP
The resolution of the clocks can be obtained by calling the \f4clock_getres\f1 function.
.PP
The timer created can be started by calling the function
\f4timer_settime\fP.
If the value of \f2evp\fP is non-NULL, then a notification
specified in the \f2evp\fP sigevent structure is sent to the process.
.PP
If the \f2sigev_notify\fP member of \f2evp\fP is SIGEV_SIGNAL then
the specified signal is sent to the process and if the value is SIGEV_NONE
no signal is sent upon timer expiration.
.PP
If the \f2sigev_notify\fP member of \f2evp\fP is SIGEV_THREAD then
the function \f2sigev_notify_function\fP will be called
by a new thread (see pthreads(5))
with \f2sigev_value\fP as the argument.
This thread is created when the event arrives with the attributes
specified in \f2sigev_notify_attributes\fP except that
it is automatically detached.
The calling process should ensure there are sufficient resources to
create the thread.
.PP
If the \f2evp\fP argument is
NULL, then the signal SIGALRM is sent to the process, upon timer expiration.
.PP
The timers are not inherited across the \f4fork\fP, \f4sproc\fP, or \f4exec\fP
system calls.
.PP
\f4timer_create\fP
will fail if one or more of the following are true:
.TP 15
[EAGAIN]
The calling process has reached its per-process timer creation
limit of {\f4TIMER_MAX\fP}.
.TP 
[EAGAIN]
The system lacks sufficient resources for queuing additional signals.
.TP
[EINVAL]
The specified clock ID is invalid. Or the signal specified in the \f2evp\fP
structure is invalid.
.TP
[EPERM]
The process is not privileged to create a timer of the specified clock type.
.TP
[EFAULT]
The address specified by either \f2timerid\fP or \f2evp\fP is outside the
range of the address space of the calling process.
.SH "SEE ALSO"
\f4timer_delete\fP(3C),
\f4timer_settime\fP(3C),
\f4timer_gettime\fP(3C),
\f4timer_getoverrun\fP(3C),
\f4clock_getres\fP(2),
\f4sigaction\fP(2),
\f4sysconf\fP(3C),
\f4pthreads\fP(5)
.SH "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 \f2timerid\fP
argument.
Otherwise, a value of \-1 is returned and \f4errno\fP
is set to indicate the error.