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

FreeBSD Manual Pages


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

       getitimer, setitimer - get or set value of interval timer

       #include	<sys/time.h>

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

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

       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

       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-

       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:


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


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


	   Decrements both in process virtual time and when the	system is run-
	   ning	on behalf of the process.  It is designed to be	used by	inter-
	   preters in statistically profiling  the  execution  of  interpreted
	   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.


	   Decrements in real time. It is designed to be  used	for  real-time
	   profiling  of multithreaded programs. Each time the ITIMER_REALPROF
	   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 except	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 defined
	   in <sys/msacct.h>.

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

       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	unrec-

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

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Standard			   |
       |MT-Level		     |MT-Safe			   |

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

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

       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.10			  6 Jun	2001			  getitimer(2)


Want to link to this manual page? Use this URL:

home | help