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.3 (Berkeley) 05/16/95 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. 110.Sh RETURN VALUES 111If the calls succeed, a value of 0 is returned. If an error occurs, 112the value -1 is returned, and a more precise error code is placed 113in the global variable 114.Va errno . 115.Sh ERRORS 116.Fn Getitimer 117and 118.Fn setitimer 119will fail if: 120.Bl -tag -width Er 121.It Bq Er EFAULT 122The 123.Fa value 124parameter specified a bad address. 125.It Bq Er EINVAL 126A 127.Fa value 128parameter specified a time that was too large 129to be handled. 130.El 131.Sh SEE ALSO 132.Xr select 2 , 133.Xr sigvec 2 , 134.Xr gettimeofday 2 135.Sh HISTORY 136The 137.Nm 138function call appeared in 139.Bx 4.2 . 140