mirror of https://github.com/mkerrisk/man-pages
198 lines
8.4 KiB
Plaintext
198 lines
8.4 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "TIMER_CREATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" timer_create
|
|
.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 .
|