.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "TIMER_CREATE" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" timer_create 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
timer_create \- create a per-process timer (\fBREALTIME\fP)
.SH SYNOPSIS
.LP
\fB#include <signal.h>
.br
#include <time.h>
.br
.sp
int timer_create(clockid_t\fP \fIclockid\fP\fB, struct sigevent *restrict\fP
\fIevp\fP\fB,
.br
\ \ \ \ \ \  timer_t *restrict\fP \fItimerid\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fItimer_create\fP() function shall create a per-process timer
using the specified clock, \fIclock_id\fP, as the timing
base. The \fItimer_create\fP() function shall return, in the location
referenced by \fItimerid\fP, a timer ID of type
\fBtimer_t\fP used to identify the timer in timer requests. This timer
ID shall be unique within the calling process until the
timer is deleted. The particular clock, \fIclock_id\fP, is defined
in \fI<time.h>\fP.
The timer whose ID is returned shall be in a disarmed state upon return
from \fItimer_create\fP().
.LP
The \fIevp\fP argument, if non-NULL, points to a \fBsigevent\fP structure.
This structure, allocated by the application,
defines the asynchronous notification to occur as specified in \fISignal
Generation and
Delivery\fP when the timer expires. If the \fIevp\fP argument is NULL,
the effect is as if the \fIevp\fP argument pointed to
a \fBsigevent\fP structure with the \fIsigev_notify\fP member having
the value SIGEV_SIGNAL, the \fIsigev_signo\fP having a
default signal number, and the \fIsigev_value\fP member having the
value of the timer ID.
.LP
Each implementation shall define a set of clocks that can be used
as timing bases for per-process timers. All implementations
shall support a \fIclock_id\fP of CLOCK_REALTIME.  If the Monotonic
Clock option is supported, implementations shall
support a \fIclock_id\fP of CLOCK_MONOTONIC. 
.LP
Per-process timers shall not be inherited by a child process across
a \fIfork\fP() and
shall be disarmed and deleted by an \fIexec\fP.
.LP
If _POSIX_CPUTIME is defined, implementations shall support \fIclock_id\fP
values representing the CPU-time clock of the calling
process. 
.LP
If _POSIX_THREAD_CPUTIME is defined, implementations shall support
\fIclock_id\fP values representing the CPU-time clock of the
calling thread. 
.LP
It is implementation-defined whether a \fItimer_create\fP() function
will succeed if the value defined by \fIclock_id\fP
corresponds to the CPU-time clock of a process or thread different
from the process or thread invoking the function. 
.SH RETURN VALUE
.LP
If the call succeeds, \fItimer_create\fP() shall return zero and update
the location referenced by \fItimerid\fP to a
\fBtimer_t\fP, which can be passed to the per-process timer calls.
If an error occurs, the function shall return a value of -1 and
set \fIerrno\fP to indicate the error. The value of \fItimerid\fP
is undefined if an error occurs.
.SH ERRORS
.LP
The \fItimer_create\fP() function shall fail if:
.TP 7
.B EAGAIN
The system lacks sufficient signal queuing resources to honor the
request.
.TP 7
.B EAGAIN
The calling process has already created all of the timers it is allowed
by this implementation.
.TP 7
.B EINVAL
The specified clock ID is not defined.
.TP 7
.B ENOTSUP
The implementation does not support the creation of a timer attached
to the CPU-time clock that is specified by
\fIclock_id\fP and associated with a process or thread different from
the process or thread invoking \fItimer_create\fP(). 
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
None.
.br
.SH RATIONALE
.LP
.SS Periodic Timer Overrun and Resource Allocation
.LP
The specified timer facilities may deliver realtime signals (that
is, queued signals) on implementations that support this
option. Since realtime applications cannot afford to lose notifications
of asynchronous events, like timer expirations or
asynchronous I/O completions, it must be possible to ensure that sufficient
resources exist to deliver the signal when the event
occurs. In general, this is not a difficulty because there is a one-to-one
correspondence between a request and a subsequent signal
generation. If the request cannot allocate the signal delivery resources,
it can fail the call with an [EAGAIN] error.
.LP
Periodic timers are a special case. A single request can generate
an unspecified number of signals. This is not a problem if the
requesting process can service the signals as fast as they are generated,
thus making the signal delivery resources available for
delivery of subsequent periodic timer expiration signals. But, in
general, this cannot be assured-processing of periodic timer
signals may "overrun''; that is, subsequent periodic timer expirations
may occur before the currently pending signal has been
delivered.
.LP
Also, for signals, according to the POSIX.1-1990 standard, if subsequent
occurrences of a pending signal are generated, it is
implementation-defined whether a signal is delivered for each occurrence.
This is not adequate for some realtime applications. So a
mechanism is required to allow applications to detect how many timer
expirations were delayed without requiring an indefinite
amount of system resources to store the delayed expirations.
.LP
The specified facilities provide for an overrun count. The overrun
count is defined as the number of extra timer expirations
that occurred between the time a timer expiration signal is generated
and the time the signal is delivered. The signal-catching
function, if it is concerned with overruns, can retrieve this count
on entry. With this method, a periodic timer only needs one
"signal queuing resource" that can be allocated at the time of the
\fItimer_create\fP() function call.
.LP
A function is defined to retrieve the overrun count so that an application
need not allocate static storage to contain the
count, and an implementation need not update this storage asynchronously
on timer expirations. But, for some high-frequency
periodic applications, the overhead of an additional system call on
each timer expiration may be prohibitive. The functions, as
defined, permit an implementation to maintain the overrun count in
user space, associated with the \fItimerid\fP. The \fItimer_getoverrun\fP()
function can then be implemented as a macro that uses the
\fItimerid\fP argument (which may just be a pointer to a user space
structure containing the counter) to locate the overrun count
with no system call overhead. Other implementations, less concerned
with this class of applications, can avoid the asynchronous
update of user space by maintaining the count in a system structure
at the cost of the extra system call to obtain it.
.SS Timer Expiration Signal Parameters
.LP
The Realtime Signals Extension option supports an application-specific
datum that is delivered to the extended signal handler.
This value is explicitly specified by the application, along with
the signal number to be delivered, in a \fBsigevent\fP
structure. The type of the application-defined value can be either
an integer constant or a pointer. This explicit specification of
the value, as opposed to always sending the timer ID, was selected
based on existing practice.
.LP
It is common practice for realtime applications (on non-POSIX systems
or realtime extended POSIX systems) to use the parameters
of event handlers as the case label of a switch statement or as a
pointer to an application-defined data structure. Since
\fItimer_id\fPs are dynamically allocated by the \fItimer_create\fP()
function, they can be used for neither of these functions
without additional application overhead in the signal handler; for
example, to search an array of saved timer IDs to associate the
ID with a constant or application data structure.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIclock_getres\fP(), \fItimer_delete\fP(), \fItimer_getoverrun\fP(),
the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<time.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .