timer_create(3c)					      timer_create(3c)

NAME    [Toc]    [Back]

     timer_create - create a posix timer

SYNOPSIS    [Toc]    [Back]

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

     timer_create(clockid_t clock_id<b>, struct sigevent *evp<b>, timer_t *timerid<b>);

DESCRIPTION    [Toc]    [Back]

     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.




									Page 1






timer_create(3c)					      timer_create(3c)



     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    [Toc]    [Back]

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

DIAGNOSTICS    [Toc]    [Back]

     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.


									PPPPaaaaggggeeee 2222