👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for timer_create (linux section 3posix)

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

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 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  repre-
       senting 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 expirations or asynchronous I/O com-
       pletions, 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-pro-
       cessing of periodic timer signals may "overrun''; that is, subsequent periodic timer expi-
       rations 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  with-
       out 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  allo-
       cate static storage to contain the count, and an implementation need not update this stor-
       age asynchronously on timer expirations. But, for some  high-frequency  periodic  applica-
       tions,  the overhead of an additional system call on each timer expiration may be prohibi-
       tive. 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 exam-
       ple, to search an array of saved timer IDs to associate the ID with a constant or applica-
       tion 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, 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				  TIMER_CREATE(P)


All times are GMT -4. The time now is 03:17 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password