diff options
Diffstat (limited to 'man3p/timer_create.3p')
| -rw-r--r-- | man3p/timer_create.3p | 197 |
1 files changed, 197 insertions, 0 deletions
diff --git a/man3p/timer_create.3p b/man3p/timer_create.3p new file mode 100644 index 000000000..188f93a70 --- /dev/null +++ b/man3p/timer_create.3p @@ -0,0 +1,197 @@ +.\" 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 . |