103 lines
3.4 KiB
Plaintext
103 lines
3.4 KiB
Plaintext
'\"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.
|