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



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

NAME
       timer_create - create a per-process timer (REALTIME)

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

       int timer_create(clockid_t clockid, struct sigevent *restrict evp,
              timer_t *restrict timerid);


DESCRIPTION
       The timer_create() function shall create a per-process timer using the specified clock, clock_id, as the timing base. The
       timer_create() function shall return, in the location referenced by timerid, a timer ID of type timer_t 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, clock_id, is defined in <time.h>.  The timer whose ID is returned shall be in  a  disarmed  state  upon
       return from timer_create().

       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 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 hav-
       ing 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 implementa-
       tions shall support a clock_id of CLOCK_REALTIME.  If the Monotonic Clock option is supported, implementations shall sup-
       port 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  call-
       ing 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.

RETURN VALUE
       If  the call succeeds, timer_create() shall return zero and update the location referenced by timerid to a timer_t, which
       can be passed to the per-process timer calls.  If an error occurs, the function shall return a value of -1 and set  errno
       to indicate the error. The value of timerid is undefined if an error occurs.

ERRORS
       The timer_create() function shall fail if:

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

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

       EINVAL The specified clock ID is not defined.

       ENOTSUP
              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.

EXAMPLES
       None.

APPLICATION USAGE
       None.

RATIONALE
   Periodic Timer Overrun and Resource Allocation
       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 expira-
       tions or asynchronous I/O completions, it must be possible to ensure that sufficient resources exist to deliver the  sig-
       nal  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.

       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  expira-
       tions  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  peri-
       odic  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 over-
       head. 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.

   Timer Expiration Signal Parameters
       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
       sigevent  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 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.

FUTURE DIRECTIONS
       None.

SEE ALSO
       clock_getres(), timer_delete(), timer_getoverrun(), the Base Definitions volume of IEEE Std 1003.1-2001, <time.h>

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, Copy-
       right (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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                              TIMER_CREATE(3P)