|TIMER_CREATE(3P)||POSIX Programmer's Manual||TIMER_CREATE(3P)|
#include <signal.h> #include <time.h>
int timer_create(clockid_t clockid, struct sigevent *restrict evp, timer_t *restrict timerid);
The evp argument, if non-NULL, points to a sigevent structure. This structure, allocated by the application, defines the asynchronous notification to occur as specified in Section 2.4.1, Signal Generation and Delivery when the timer expires. If the evp argument is NULL, the effect is as if the evp argument pointed to a sigevent structure with the sigev_notify member having the value SIGEV_SIGNAL, the sigev_signo having a default signal number, and the sigev_value member having the value of the timer ID.
Each implementation shall define a set of clocks that can be used as timing bases for per-process timers. All implementations shall support a clock_id of CLOCK_REALTIME. If the Monotonic Clock option is supported, implementations shall support a clock_id of CLOCK_MONOTONIC.
Per-process timers shall not be inherited by a child process across a fork() and shall be disarmed and deleted by an exec.
If _POSIX_CPUTIME is defined, implementations shall support clock_id values representing the CPU-time clock of the calling process.
If _POSIX_THREAD_CPUTIME is defined, implementations shall support clock_id values representing the CPU-time clock of the calling thread.
It is implementation-defined whether a timer_create() function will succeed if the value defined by clock_id corresponds to the CPU-time clock of a process or thread different from the process or thread invoking the function.
If evp->sigev_sigev_notify is SIGEV_THREAD and sev->sigev_notify_attributes is not NULL, if the attribute pointed to by sev->sigev_notify_attributes has a thread stack address specified by a call to pthread_attr_setstack(), the results are unspecified if the signal is generated more than once.
- The system lacks sufficient signal queuing resources to honor the request.
- The calling process has already created all of the timers it is allowed by this implementation.
- The specified clock ID is not defined.
- The implementation does not support the creation of a timer attached to the CPU-time clock that is specified by clock_id and associated with a process or thread different from the process or thread invoking timer_create().
The following sections are informative.
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.
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.
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 timer_create() function call.
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 timerid. The timer_getoverrun() function can then be implemented as a macro that uses the timerid 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.
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 timer_ids are dynamically allocated by the timer_create() 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.
The Base Definitions volume of POSIX.1‐2017, <signal.h>, <time.h>
Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .
|2017||IEEE/The Open Group|