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.Dd May 1, 2020 29.Dt GETITIMER 2 30.Os 31.Sh NAME 32.Nm getitimer , 33.Nm setitimer 34.Nd get/set value of interval timer 35.Sh LIBRARY 36.Lb libc 37.Sh SYNOPSIS 38.In sys/time.h 39.Fd "#define ITIMER_REAL 0" 40.Fd "#define ITIMER_VIRTUAL 1" 41.Fd "#define ITIMER_PROF 2" 42.Ft int 43.Fn getitimer "int which" "struct itimerval *value" 44.Ft int 45.Fn setitimer "int which" "const struct itimerval *value" "struct itimerval *ovalue" 46.Sh DESCRIPTION 47The system provides each process with three interval timers, 48defined in 49.In sys/time.h . 50The 51.Fn getitimer 52system call returns the current value for the timer specified in 53.Fa which 54in the structure at 55.Fa value . 56The 57.Fn setitimer 58system call sets a timer to the specified 59.Fa value 60(returning the previous value of the timer if 61.Fa ovalue 62is not a null pointer). 63.Pp 64A timer value is defined by the 65.Fa itimerval 66structure: 67.Bd -literal -offset indent 68struct itimerval { 69 struct timeval it_interval; /* timer interval */ 70 struct timeval it_value; /* current value */ 71}; 72.Ed 73.Pp 74If 75.Fa it_value 76is non-zero, it indicates the time to the next timer expiration. 77If 78.Fa it_interval 79is non-zero, it specifies a value to be used in reloading 80.Fa it_value 81when the timer expires. 82Setting 83.Fa it_value 84to 0 disables a timer, regardless of the value of 85.Fa it_interval . 86Setting 87.Fa it_interval 88to 0 causes a timer to be disabled after its next expiration (assuming 89.Fa it_value 90is non-zero). 91.Pp 92Time values smaller than the resolution of the 93system clock are rounded up to this resolution 94(typically 10 milliseconds). 95.Pp 96The 97.Dv ITIMER_REAL 98timer decrements in real time. 99A 100.Dv SIGALRM 101signal is 102delivered when this timer expires. 103.Pp 104The 105.Dv ITIMER_VIRTUAL 106timer decrements in process virtual time. 107It runs only when the process is executing. 108A 109.Dv SIGVTALRM 110signal 111is delivered when it expires. 112.Pp 113The 114.Dv ITIMER_PROF 115timer decrements both in process virtual time and 116when the system is running on behalf of the process. 117It is designed 118to be used by interpreters in statistically profiling the execution 119of interpreted programs. 120Each time the 121.Dv ITIMER_PROF 122timer expires, the 123.Dv SIGPROF 124signal is 125delivered. 126Because this signal may interrupt in-progress 127system calls, programs using this timer must be prepared to 128restart interrupted system calls. 129.Pp 130The maximum number of seconds allowed for 131.Fa it_interval 132and 133.Fa it_value 134in 135.Fn setitimer 136is 100000000. 137.Sh NOTES 138Three macros for manipulating time values are defined in 139.In sys/time.h . 140The 141.Fn timerclear 142macro 143sets a time value to zero, 144.Fn timerisset 145tests if a time value is non-zero, and 146.Fn timercmp 147compares two time values. 148.Sh RETURN VALUES 149.Rv -std 150.Sh ERRORS 151The 152.Fn getitimer 153and 154.Fn setitimer 155system calls 156will fail if: 157.Bl -tag -width Er 158.It Bq Er EFAULT 159The 160.Fa value 161argument specified a bad address. 162.It Bq Er EINVAL 163The 164.Fa value 165argument specified a time that was too large 166to be handled. 167.El 168.Sh SEE ALSO 169.Xr gettimeofday 2 , 170.Xr select 2 , 171.Xr sigaction 2 , 172.Xr clocks 7 173.Sh STANDARDS 174The 175.Fn getitimer 176and 177.Fn setitimer 178functions conform to 179.St -p1003.1-2001 . 180The later 181.St -p1003.1-2008 182revision however marked both functions as obsolescent, 183recommending the use of 184.Xr timer_gettime 2 185and 186.Xr timer_settime 2 187instead. 188.Sh HISTORY 189The 190.Fn getitimer 191system call appeared in 192.Bx 4.2 . 193