timer_create(3c)                                              timer_create(3c)


NAME
     timer_create - create a POSIX timer

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

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

DESCRIPTION
     timer_create creates an interval timer for the calling process based on
     the clock named by clock_id.  The new timer ID is recorded at the memory
     address timerid, and is unique for the calling process until the timer is
     deleted.  A process may create up to {TIMER_MAX} POSIX timers [see
     sysconf(3C)].

     Supported clocks for clock_id are:

     CLOCK_REALTIME The system's notion of the current time is obtained with
                    this clock.  The time is expressed in seconds and
                    nanoseconds since midnight (00:00) Coordinated Universal
                    Time (UTC), January 1, 1970.  The resolution for of this
                    clock is never worse than 100 HZ (which equals 10
                    milliseconds).  The actual resolution of the clock depends
                    on the timer capability of the underlying hardware (see
                    timers(5)).

     CLOCK_SGI_FAST This clock has a higher resolution than CLOCK_REALTIME and
                    is available to privileged users only.  This clock is SGI
                    specific and is not portable.

     The resolution of the clocks can be obtained by calling the clock_getres
     function.

     The timer created can be started by calling the function timer_settime.
     If the value of evp is non-NULL, then a notification specified in the evp
     sigevent structure is sent to the process.

     If the sigev_notify member of evp is SIGEV_SIGNAL then the specified
     signal in the sigev_signo member of evp is sent to the process and if the
     value is SIGEV_NONE no signal is sent upon timer expiration.

     If the sigev_notify member of evp is SIGEV_THREAD then the function
     sigev_notify_function will be called by a new thread (see pthreads(5))
     with sigev_value as the argument.  This thread is created when the event
     arrives with the attributes specified in sigev_notify_attributes except
     that it is automatically detached.  The calling process should ensure
     there are sufficient resources to create the thread.


     If the evp argument is NULL, then the signal SIGALRM is sent to the
     process, upon timer expiration.

     The timers are not inherited across the fork, sproc, or exec system
     calls.

     timer_create will fail if one or more of the following are true:

     [EAGAIN]       The calling process has reached its per-process timer
                    creation limit of {TIMER_MAX}.

     [EAGAIN]       The system lacks sufficient resources for queuing
                    additional signals.

     [EINVAL]       The specified clock ID is invalid. Or the signal specified
                    in the evp structure is invalid.

     [EPERM]        The process is not privileged to create a timer of the
                    specified clock type.

     [EFAULT]       The address specified by either timerid or evp is outside
                    the range of the address space of the calling process.

SEE ALSO
     timer_delete(3C), timer_settime(3C), timer_gettime(3C),
     timer_getoverrun(3C), clock_getres(2), sigaction(2), sysconf(3C),
     pthreads(5)

DIAGNOSTICS
     Upon successful completion, a value of 0 is returned and the timer ID of
     the created timer is set in the location pointed to by the timerid
     argument.  Otherwise, a value of -1 is returned and errno is set to
     indicate the error.


                                                                        Page 2