TIMER_CREATE(3)            POSIX Programmer's Manual           TIMER_CREATE(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       timer_create -- create a per-process timer

SSYYNNOOPPSSIISS
       #include <signal.h>
       #include <time.h>

       int timer_create(clockid_t _c_l_o_c_k_i_d, struct sigevent *restrict _e_v_p,
           timer_t *restrict _t_i_m_e_r_i_d);

DDEESSCCRRIIPPTTIIOONN
       The _t_i_m_e_r___c_r_e_a_t_e() function shall create a per-process timer using the
       specified clock, _c_l_o_c_k___i_d, as the timing base. The _t_i_m_e_r___c_r_e_a_t_e()
       function shall return, in the location referenced by _t_i_m_e_r_i_d, a timer
       ID of type ttiimmeerr__tt 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, _c_l_o_c_k___i_d, is defined in _<_t_i_m_e_._h_>.  The
       timer whose ID is returned shall be in a disarmed state upon return
       from _t_i_m_e_r___c_r_e_a_t_e().

       The _e_v_p argument, if non-NULL, points to a ssiiggeevveenntt structure. This
       structure, allocated by the application, defines the asynchronous
       notification to occur as specified in _S_e_c_t_i_o_n _2_._4_._1, _S_i_g_n_a_l _G_e_n_e_r_a_t_i_o_n
       _a_n_d _D_e_l_i_v_e_r_y when the timer expires. If the _e_v_p argument is NULL, the
       effect is as if the _e_v_p argument pointed to a ssiiggeevveenntt structure with
       the _s_i_g_e_v___n_o_t_i_f_y member having the value SIGEV_SIGNAL, the _s_i_g_e_v___s_i_g_n_o
       having a default signal number, and the _s_i_g_e_v___v_a_l_u_e 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 _c_l_o_c_k___i_d of CLOCK_REALTIME.  If the Monotonic Clock option is
       supported, implementations shall support a _c_l_o_c_k___i_d of CLOCK_MONOTONIC.

       Per-process timers shall not be inherited by a child process across a
       _f_o_r_k() and shall be disarmed and deleted by an _e_x_e_c.

       If _POSIX_CPUTIME is defined, implementations shall support _c_l_o_c_k___i_d
       values representing the CPU-time clock of the calling process.

       If _POSIX_THREAD_CPUTIME is defined, implementations shall support
       _c_l_o_c_k___i_d values representing the CPU-time clock of the calling thread.

       It is implementation-defined whether a _t_i_m_e_r___c_r_e_a_t_e() function will
       succeed if the value defined by _c_l_o_c_k___i_d corresponds to the CPU-time
       clock of a process or thread different from the process or thread
       invoking the function.

       If _e_v_p->_s_i_g_e_v___s_i_g_e_v___n_o_t_i_f_y is SIGEV_THREAD and
       _s_e_v->_s_i_g_e_v___n_o_t_i_f_y___a_t_t_r_i_b_u_t_e_s is not NULL, if the attribute pointed to
       by _s_e_v->_s_i_g_e_v___n_o_t_i_f_y___a_t_t_r_i_b_u_t_e_s has a thread stack address specified by
       a call to _p_t_h_r_e_a_d___a_t_t_r___s_e_t_s_t_a_c_k(), the results are unspecified if the
       signal is generated more than once.

RREETTUURRNN VVAALLUUEE
       If the call succeeds, _t_i_m_e_r___c_r_e_a_t_e() shall return zero and update the
       location referenced by _t_i_m_e_r_i_d to a ttiimmeerr__tt, which can be passed to the
       per-process timer calls. If an error occurs, the function shall return
       a value of -1 and set _e_r_r_n_o to indicate the error. The value of _t_i_m_e_r_i_d
       is undefined if an error occurs.

EERRRROORRSS
       The _t_i_m_e_r___c_r_e_a_t_e() function shall fail if:

       EEAAGGAAIINN The system lacks sufficient signal queuing resources to honor
              the request.

       EEAAGGAAIINN The calling process has already created all of the timers it is
              allowed by this implementation.

       EEIINNVVAALL The specified clock ID is not defined.

       EENNOOTTSSUUPP
              The implementation does not support the creation of a timer
              attached to the CPU-time clock that is specified by _c_l_o_c_k___i_d and
              associated with a process or thread different from the process
              or thread invoking _t_i_m_e_r___c_r_e_a_t_e().

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       If a timer is created which has _e_v_p->_s_i_g_e_v___s_i_g_e_v___n_o_t_i_f_y set to
       SIGEV_THREAD and the attribute pointed to by
       _e_v_p->_s_i_g_e_v___n_o_t_i_f_y___a_t_t_r_i_b_u_t_e_s has a thread stack address specified by a
       call to _p_t_h_r_e_a_d___a_t_t_r___s_e_t_s_t_a_c_k(), the memory dedicated as a thread stack
       cannot be recovered. The reason for this is that the threads created in
       response to a timer expiration are created detached, or in an
       unspecified way if the thread attribute's _d_e_t_a_c_h_s_t_a_t_e is
       PTHREAD_CREATE_JOINABLE. In neither case is it valid to call
       _p_t_h_r_e_a_d___j_o_i_n(), which makes it impossible to determine the lifetime of
       the created thread which thus means the stack memory cannot be reused.

RRAATTIIOONNAALLEE
   PPeerriiooddiicc TTiimmeerr OOvveerrrruunn aanndd RReessoouurrccee AAllllooccaattiioonn
       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
       [[EEAAGGAAIINN]] error.

       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 _t_i_m_e_r___c_r_e_a_t_e() 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 _t_i_m_e_r_i_d.
       The _t_i_m_e_r___g_e_t_o_v_e_r_r_u_n() function can then be implemented as a macro that
       uses the _t_i_m_e_r_i_d 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.

   TTiimmeerr EExxppiirraattiioonn SSiiggnnaall PPaarraammeetteerrss
       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 ssiiggeevveenntt 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.

       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 _t_i_m_e_r___i_ds are dynamically
       allocated by the _t_i_m_e_r___c_r_e_a_t_e() 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.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _c_l_o_c_k___g_e_t_r_e_s(), _t_i_m_e_r___d_e_l_e_t_e(), _t_i_m_e_r___g_e_t_o_v_e_r_r_u_n()

       The Base Definitions volume of POSIX.1-2008, <<ssiiggnnaall..hh>>, <<ttiimmee..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       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 .



IEEE/The Open Group                  2013                      TIMER_CREATE(3)
