Realtime Library Functions                      timer_create(3RT)

NAME
     timer_create - create a timer

SYNOPSIS
     cc [ flag... ] file... -lrt [ library... ]
     #include <signal.h>
     #include <time.h>

     int timer_create(clockid_t clock_id, struct  sigevent  *evp,
     timer_t *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 <time.h>.  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  willo  occur  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,
     timerid.

     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, not bound

          CLOCK_VIRTUAL
                user CPU usage clock

          CLOCK_PROF
                user and system CPU usage clock

          CLOCK_HIGHRES
                non-adjustable, high-resolution clock

     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.

SunOS 5.8           Last change: 12 Nov 1999                    1

Realtime Library Functions                      timer_create(3RT)

      The actual hardware source used is transparent to the  user
     and  may change over the lifetime of the timer. For example,
     if the LWP that created the timer were to change its proces-
     sor  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.

     ENOSYS
           The timer_create() function is not  supported  by  the
           system.

     EPERM The specified clock ID, clock_id, is CLOCK_HIGHRES and
           the  effective  user  of  the  calling  LWP   is   not
           superuser.

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

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | MT-Level                    | MT-Safe with exceptions     |
    |_____________________________|_____________________________|

SunOS 5.8           Last change: 12 Nov 1999                    2

Realtime Library Functions                      timer_create(3RT)

SEE ALSO
     exec(2), fork(2), time(2),  clock_settime(3RT),  signal(3C),
     timer_delete(3RT), timer_settime(3RT), attributes(5)

SunOS 5.8           Last change: 12 Nov 1999                    3