1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)getitimer.2 8.3 (Berkeley) 5/16/95 29.\" 30.Dd May 1, 2020 31.Dt GETITIMER 2 32.Os 33.Sh NAME 34.Nm getitimer , 35.Nm setitimer 36.Nd get/set value of interval timer 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In sys/time.h 41.Fd "#define ITIMER_REAL 0" 42.Fd "#define ITIMER_VIRTUAL 1" 43.Fd "#define ITIMER_PROF 2" 44.Ft int 45.Fn getitimer "int which" "struct itimerval *value" 46.Ft int 47.Fn setitimer "int which" "const struct itimerval *value" "struct itimerval *ovalue" 48.Sh DESCRIPTION 49The system provides each process with three interval timers, 50defined in 51.In sys/time.h . 52The 53.Fn getitimer 54system call returns the current value for the timer specified in 55.Fa which 56in the structure at 57.Fa value . 58The 59.Fn setitimer 60system call sets a timer to the specified 61.Fa value 62(returning the previous value of the timer if 63.Fa ovalue 64is not a null pointer). 65.Pp 66A timer value is defined by the 67.Fa itimerval 68structure: 69.Bd -literal -offset indent 70struct itimerval { 71 struct timeval it_interval; /* timer interval */ 72 struct timeval it_value; /* current value */ 73}; 74.Ed 75.Pp 76If 77.Fa it_value 78is non-zero, it indicates the time to the next timer expiration. 79If 80.Fa it_interval 81is non-zero, it specifies a value to be used in reloading 82.Fa it_value 83when the timer expires. 84Setting 85.Fa it_value 86to 0 disables a timer, regardless of the value of 87.Fa it_interval . 88Setting 89.Fa it_interval 90to 0 causes a timer to be disabled after its next expiration (assuming 91.Fa it_value 92is non-zero). 93.Pp 94Time values smaller than the resolution of the 95system clock are rounded up to this resolution 96(typically 10 milliseconds). 97.Pp 98The 99.Dv ITIMER_REAL 100timer decrements in real time. 101A 102.Dv SIGALRM 103signal is 104delivered when this timer expires. 105.Pp 106The 107.Dv ITIMER_VIRTUAL 108timer decrements in process virtual time. 109It runs only when the process is executing. 110A 111.Dv SIGVTALRM 112signal 113is delivered when it expires. 114.Pp 115The 116.Dv ITIMER_PROF 117timer decrements both in process virtual time and 118when the system is running on behalf of the process. 119It is designed 120to be used by interpreters in statistically profiling the execution 121of interpreted programs. 122Each time the 123.Dv ITIMER_PROF 124timer expires, the 125.Dv SIGPROF 126signal is 127delivered. 128Because this signal may interrupt in-progress 129system calls, programs using this timer must be prepared to 130restart interrupted system calls. 131.Pp 132The maximum number of seconds allowed for 133.Fa it_interval 134and 135.Fa it_value 136in 137.Fn setitimer 138is 100000000. 139.Sh NOTES 140Three macros for manipulating time values are defined in 141.In sys/time.h . 142The 143.Fn timerclear 144macro 145sets a time value to zero, 146.Fn timerisset 147tests if a time value is non-zero, and 148.Fn timercmp 149compares two time values. 150.Sh RETURN VALUES 151.Rv -std 152.Sh ERRORS 153The 154.Fn getitimer 155and 156.Fn setitimer 157system calls 158will fail if: 159.Bl -tag -width Er 160.It Bq Er EFAULT 161The 162.Fa value 163argument specified a bad address. 164.It Bq Er EINVAL 165The 166.Fa value 167argument specified a time that was too large 168to be handled. 169.El 170.Sh SEE ALSO 171.Xr gettimeofday 2 , 172.Xr select 2 , 173.Xr sigaction 2 , 174.Xr clocks 7 175.Sh STANDARDS 176The 177.Fn getitimer 178and 179.Fn setitimer 180functions conform to 181.St -p1003.1-2001 . 182The later 183.St -p1003.1-2008 184revision however marked both functions as obsolescent, 185recommending the use of 186.Xr timer_gettime 2 187and 188.Xr timer_settime 2 189instead. 190.Sh HISTORY 191The 192.Fn getitimer 193system call appeared in 194.Bx 4.2 . 195