Manual Pages for UNIX Operating System command usage for man timer_create

Standard C Library Functions                     timer_create(3C)



NAME
     timer_create - create a timer

SYNOPSIS
     #include 
     #include 

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


DESCRIPTION
     The timer_create() function creates a timer using the speci-
     fied clock, clock_id, as the timing base. The timer_create()
     function returns, in the location referenced by  timerid,  a
     timer ID of type timer_t used to identify the timer in timer
     requests. This timer ID will be unique  within  the  calling
     process  until  the  timer is deleted. The particular clock,
     clock_id, is defined in .  The  timer  whose  ID  is
     returned  will  be  in  a  disarmed  state  upon return from
     timer_create().


     The evp argument, if non-null, points to a  sigevent  struc-
     ture.  This structure, allocated by the application, defines
     the asynchronous notification that will occur when the timer
     expires   (see   signal.h(3HEAD)   for   event  notification
     details). 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  the value SIGALARM, and the sigev_value
     member having the value of the timer ID.


     The system defines a set of clocks that can be used as  tim-
     ing  bases  for per-process timers. The following values for
     clock_id are supported:

     CLOCK_REALTIME    wall clock


     CLOCK_VIRTUAL     user CPU usage clock


     CLOCK_PROF        user and system CPU usage clock


     CLOCK_HIGHRES     non-adjustable, high-resolution clock







SunOS 5.11           Last change: 5 Feb 2008                    1






Standard C Library Functions                     timer_create(3C)



     For timers created with a  clock_id  of  CLOCK_HIGHRES,  the
     system  will attempt to use an optimal hardware source. This
     may include, but is not limited to, per-CPU  timer  sources.
     The  actual  hardware source used is transparent to the user
     and may change over the lifetime of the timer. For  example,
     if the caller that created the timer were to change its pro-
     cessor binding or its processor set, the system may elect to
     drive the timer with a hardware source  that better reflects
     the new binding. Timers based on a clock_id of CLOCK_HIGHRES
     are  ideally  suited  for  interval timers that have minimal
     jitter tolerence.


     Timers are not inherited by a child process across a fork(2)
     and  are  disarmed  and deleted by a call to one of the exec
     functions (see exec(2)).

RETURN VALUES
     Upon successful completion,  timer_create()  returns  0  and
     updates  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  returns  -1 and sets errno to
     indicate the error. The value of timerid is undefined if  an
     error occurs.

ERRORS
     The timer_create() function will fail if:

     EAGAIN    The  system  lacks   sufficient   signal   queuing
               resources  to  honor  the  request, or the calling
               process has already created all of the  timers  it
               is allowed by the system.


     EINVAL    The specified clock ID, clock_id, is not defined.


     EPERM     The specified clock ID, clock_id, is CLOCK_HIGHRES
               and  the {PRIV_PROC_CLOCK_HIGHRES} is not asserted
               in the effective set of the calling process.


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:










SunOS 5.11           Last change: 5 Feb 2008                    2






Standard C Library Functions                     timer_create(3C)



     ____________________________________________________________
    | ATTRIBUTE TYPE              | ATTRIBUTE VALUE             |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe with exceptions     |
    |_____________________________|_____________________________|
    | Standard                    | See standards(5).           |
    |_____________________________|_____________________________|


SEE ALSO
     exec(2), fork(2),  time(2),  clock_settime(3C),  signal(3C),
     signal.h(3HEAD), timer_delete(3C), timer_settime(3C), attri-
     butes(5), privileges(5), standards(5)








































SunOS 5.11           Last change: 5 Feb 2008                    3