1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)getitimer.2 8.1 (Berkeley) 06/04/93 7.\" 8.Dd 9.Dt GETITIMER 2 10.Os BSD 4.2 11.Sh NAME 12.Nm getitimer , 13.Nm setitimer 14.Nd get/set value of interval timer 15.Sh SYNOPSIS 16.Fd #include <sys/time.h> 17.Fd #define ITIMER_REAL 0 18.Fd #define ITIMER_VIRTUAL 1 19.Fd #define ITIMER_PROF 2 20.Ft int 21.Fn getitimer "int which" "struct itimerval *value" 22.Ft int 23.Fn setitimer "int which" "struct itimerval *value" "struct itimerval *ovalue" 24.Sh DESCRIPTION 25The system provides each process with three interval timers, 26defined in 27.Ao Pa sys/time.h Ac . 28The 29.Fn getitimer 30call returns the current value for the timer specified in 31.Fa which 32in the structure at 33.Fa value . 34The 35.Fn setitimer 36call sets a timer to the specified 37.Fa value 38(returning the previous value of the timer if 39.Fa ovalue 40is non-nil). 41.Pp 42A timer value is defined by the 43.Fa itimerval 44structure: 45.Bd -literal -offset indent 46struct itimerval { 47 struct timeval it_interval; /* timer interval */ 48 struct timeval it_value; /* current value */ 49}; 50.Ed 51.Pp 52If 53.Fa it_value 54is non-zero, it indicates the time to the next timer expiration. 55If 56.Fa it_interval 57is non-zero, it specifies a value to be used in reloading 58.Fa it_value 59when the timer expires. 60Setting 61.Fa it_value 62to 0 disables a timer. Setting 63.Fa it_interval 64to 0 causes a timer to be disabled after its next expiration (assuming 65.Fa it_value 66is non-zero). 67.Pp 68Time values smaller than the resolution of the 69system clock are rounded up to this resolution 70(typically 10 milliseconds). 71.Pp 72The 73.Dv ITIMER_REAL 74timer decrements in real time. A 75.Dv SIGALRM 76signal is 77delivered when this timer expires. 78.Pp 79The 80.Dv ITIMER_VIRTUAL 81timer decrements in process virtual time. 82It runs only when the process is executing. A 83.Dv SIGVTALRM 84signal 85is delivered when it expires. 86.Pp 87The 88.Dv ITIMER_PROF 89timer decrements both in process virtual time and 90when the system is running on behalf of the process. It is designed 91to be used by interpreters in statistically profiling the execution 92of interpreted programs. 93Each time the 94.Dv ITIMER_PROF 95timer expires, the 96.Dv SIGPROF 97signal is 98delivered. Because this signal may interrupt in-progress 99system calls, programs using this timer must be prepared to 100restart interrupted system calls. 101.Sh NOTES 102Three macros for manipulating time values are defined in 103.Ao Pa sys/time.h Ac . 104.Fa Timerclear 105sets a time value to zero, 106.Fa timerisset 107tests if a time value is non-zero, and 108.Fa timercmp 109compares two time values (beware that >= and <= do not 110work with this macro). 111.Sh RETURN VALUES 112If the calls succeed, a value of 0 is returned. If an error occurs, 113the value -1 is returned, and a more precise error code is placed 114in the global variable 115.Va errno . 116.Sh ERRORS 117.Fn Getitimer 118and 119.Fn setitimer 120will fail if: 121.Bl -tag -width Er 122.It Bq Er EFAULT 123The 124.Fa value 125parameter specified a bad address. 126.It Bq Er EINVAL 127A 128.Fa value 129parameter specified a time was too large 130to be handled. 131.El 132.Sh SEE ALSO 133.Xr select 2 , 134.Xr sigvec 2 , 135.Xr gettimeofday 2 136.Sh HISTORY 137The 138.Nm 139function call appeared in 140.Bx 4.2 . 141