Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
getitimer(2)			 System	Calls			  getitimer(2)

NAME
       getitimer, setitimer - get or set value of interval timer

SYNOPSIS
       #include	<sys/time.h>

       int getitimer(int which,	struct itimerval *value);

       int  setitimer(int which, const struct itimerval	*value,	struct itimer-
       val *ovalue);

DESCRIPTION
       The system provides each	process	with four interval timers, defined  in
       sys/time.h.  The	 getitimer()  function stores the current value	of the
       timer specified by which	into the structure pointed to  by  value.  The
       setitimer()  function  call  sets  the  value of	the timer specified by
       which to	the value specified in the structure pointed to	by value,  and
       if  ovalue  is  not NULL, stores	the previous value of the timer	in the
       structure pointed to by ovalue.

       A timer value is	defined	by the	itimerval  structure  (see  gettimeof-
       day(3C))	 for  the definition of	timeval), which	includes the following
       members:

       struct timeval	 it_interval;	      /* timer interval	*/
       struct timeval	 it_value;	      /* current value */

       The it_value member indicates the time to the  next  timer  expiration.
       The  it_interval	 member	 specifies  a  value  to  be used in reloading
       it_value	when the timer expires.	 Setting  it_value  to	0  disables  a
       timer, regardless of the	value of it_interval. Setting it_interval to 0
       disables	a timer	after its next expiration (assuming it_value  is  non-
       zero).

       Time values smaller than	the resolution of the system clock are rounded
       up to the resolution of the system clock, except	for   ITIMER_REALPROF,
       whose  values  are rounded up to	the resolution of the profiling	clock.
       The four	timers are as follows:

       ITIMER_REAL
	     Decrements	in real	time.  A SIGALRM signal	is delivered when this
	     timer expires.

       ITIMER_VIRTUAL
	     Decrements	in process virtual time. It runs only when the process
	     is	executing.  A SIGVTALRM	signal is delivered when it expires.

       ITIMER_PROF
	     Decrements	both in	process	virtual	time and when  the  system  is
	     running  on  behalf of the	process.  It is	designed to be used by
	     interpreters in statistically profiling the execution  of	inter-
	     preted  programs.	 Each  time the	ITIMER_PROF timer expires, the
	     SIGPROF signal is delivered. Because this	signal	may  interrupt
	     in-progress functions, programs using this	timer must be prepared
	     to	restart	interrupted functions.

       ITIMER_REALPROF
	     Decrements	in real	time. It is designed to	be used	for  real-time
	     profiling	of  multithreaded programs. Each time the ITIMER_REAL-
	     PROF timer	expires, one counter in	a set of  counters  maintained
	     by	 the system for	each lightweight process (lwp) is incremented.
	     The counter corresponds to	the state of the lwp at	 the  time  of
	     the  timer	 tick.	All lwps executing in user mode	when the timer
	     expires are interrupted into system mode. When each  lwp  resumes
	     execution	in  user  mode,	 if  any of the	elements in its	set of
	     counters are non-zero, the	SIGPROF	signal	is  delivered  to  the
	     lwp.  The SIGPROF signal is delivered before any other signal ex-
	     cept SIGKILL.  This signal	does  not  interrupt  any  in-progress
	     function.	A   siginfo  structure,	defined	in <sys/siginfo.h>, is
	     associated	with the delivery of the SIGPROF signal, and  includes
	     the following members:

	     si_tstamp;	     /*	high resolution	timestamp */
	     si_syscall;     /*	current	syscall	*/
	     si_nsysarg;     /*	number of syscall arguments */
	     si_sysarg[];     /* actual	syscall	arguments */
	     si_fault;	     /*	last fault type	*/
	     si_faddr;	     /*	last fault address */
	     si_mstate[];     /* ticks in each microstate */

	     The  enumeration  of microstates (indices into  si_mstate)	is de-
	     fined in <sys/msacct.h>.

RETURN VALUES
       Upon successful completion, 0 is	returned. Otherwise,  -1  is  returned
       and errno is set	to indicate the	error.

ERRORS
       The getitimer() and setitimer() functions will fail if:

       EINVAL
	     The  specified number of seconds is greater than 100,000,000, the
	     number of microseconds is greater than or equal to	1,000,000,  or
	     the which argument	is unrecognized.

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       alarm(2),   gettimeofday(3C),  sleep(3C),  sysconf(3C),	attributes(5),
       standards(5)

NOTES
       The microseconds	field should not be equal to or	greater	than one  sec-
       ond.

       The setitimer() function	is independent of the alarm() function.

       Do not use setitimer(ITIMER_REAL) with the sleep() routine. A sleep(3C)
       call wipes out knowledge	of the user signal handler for SIGALRM.

       The ITIMER_PROF and ITIMER_REALPROF timers deliver the same signal  and
       have different semantics. They cannot be	used together.

       The granularity of the resolution of alarm time is platform-dependent.

SunOS 5.9			  6 Jun	2001			  getitimer(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=getitimer&sektion=2&manpath=SunOS+5.9>

home | help