Provided by: manpages-posix-dev_2017a-2_all bug

PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of
       this interface may differ (consult 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

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

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

       If a timer is created which  has  evp->sigev_sigev_notify  set  to  SIGEV_THREAD  and  the
       attribute  pointed to by evp->sigev_notify_attributes has a thread stack address specified
       by a call to pthread_attr_setstack(), 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
       detachstate   is   PTHREAD_CREATE_JOINABLE.   In   neither   case  is  it  valid  to  call
       pthread_join(), which makes it impossible to determine the lifetime of the created  thread
       which thus means the stack memory cannot be reused.

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

       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.

   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 POSIX.1‐2017, <signal.h>, <time.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1-2017,  Standard  for  Information Technology -- Portable Operating System Interface
       (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C)  2018  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 .

       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 .