1.\" $OpenBSD: getitimer.2,v 1.31 2019/01/20 04:55:06 schwarze Exp $ 2.\" $NetBSD: getitimer.2,v 1.6 1995/10/12 15:40:54 jtc Exp $ 3.\" 4.\" Copyright (c) 1983, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)getitimer.2 8.2 (Berkeley) 12/11/93 32.\" 33.Dd $Mdocdate: January 20 2019 $ 34.Dt GETITIMER 2 35.Os 36.Sh NAME 37.Nm getitimer , 38.Nm setitimer , 39.Nm timerclear , 40.Nm timerisset , 41.Nm timerisvalid , 42.Nm timercmp , 43.Nm timersub , 44.Nm timeradd 45.Nd get/set value of interval timer 46.Sh SYNOPSIS 47.In sys/time.h 48.Pp 49.Fd #define ITIMER_REAL 0 50.Fd #define ITIMER_VIRTUAL 1 51.Fd #define ITIMER_PROF 2 52.Ft int 53.Fn getitimer "int which" "struct itimerval *value" 54.Ft int 55.Fn setitimer "int which" "const struct itimerval *value" "struct itimerval *ovalue" 56.Ft void 57.Fn timerclear "struct timeval *" 58.Ft int 59.Fn timerisset "struct timeval *" 60.Ft int 61.Fn timerisvalid "struct timeval *" 62.Ft int 63.Fn timercmp "struct timeval *a" "struct timeval *b" CMP 64.Ft void 65.Fn timersub "struct timeval *a" "struct timeval *b" "struct timeval *res" 66.Ft void 67.Fn timeradd "struct timeval *a" "struct timeval *b" "struct timeval *res" 68.Sh DESCRIPTION 69The system provides each process with three interval timers, 70defined in 71.In sys/time.h . 72The 73.Fn getitimer 74call returns the current value for the timer specified in 75.Fa which 76in the structure at 77.Fa value . 78The 79.Fn setitimer 80call sets a timer to the specified 81.Fa value 82(returning the previous value of the timer if 83.Fa ovalue 84is non-null). 85.Pp 86A timer value is defined by the 87.Fa itimerval 88structure: 89.Bd -literal -offset indent 90struct itimerval { 91 struct timeval it_interval; /* timer interval */ 92 struct timeval it_value; /* current value */ 93}; 94.Ed 95.Pp 96If 97.Fa it_value 98is non-zero, it indicates the time to the next timer expiration. 99If 100.Fa it_interval 101is non-zero, it specifies a value to be used in reloading 102.Fa it_value 103when the timer expires. 104Setting 105.Fa it_value 106to 0 disables a timer. 107Setting 108.Fa it_interval 109to 0 causes a timer to be disabled after its next expiration (assuming 110.Fa it_value 111is non-zero). 112.Pp 113Time values smaller than the resolution of the 114system clock are rounded up to this resolution 115(typically 10 milliseconds). 116.Pp 117The 118.Dv ITIMER_REAL 119timer decrements in real time. 120A 121.Dv SIGALRM 122signal is 123delivered when this timer expires. 124.Pp 125The 126.Dv ITIMER_VIRTUAL 127timer decrements in process virtual time. 128It runs only when the process is executing. 129A 130.Dv SIGVTALRM 131signal is delivered when it expires. 132.Pp 133The 134.Dv ITIMER_PROF 135timer decrements both in process virtual time and 136when the system is running on behalf of the process. 137It is designed to be used by interpreters in statistically profiling 138the execution of interpreted programs. 139Each time the 140.Dv ITIMER_PROF 141timer expires, the 142.Dv SIGPROF 143signal is delivered. 144Because this signal may interrupt in-progress 145system calls, programs using this timer must be prepared to 146restart interrupted system calls. 147.Pp 148The remaining functions are implemented as macros: 149.Pp 150.Fn timerclear "a" 151sets the time value in 152.Fa a 153to zero. 154.Pp 155.Fn timerisset "a" 156tests if the time value in 157.Fa a 158is non-zero. 159.Pp 160.Fn timerisvalid "a" 161tests the validity of the microsecond value in 162.Fa a . 163.Pp 164.Fn timercmp a b CMP 165compares two time values in the form 166.Fa a 167CMP 168.Fa b , 169where 170.Fa CMP 171is <, <=, ==, !=, >=, or > . 172.Pp 173.Fn timersub a b res 174subtracts 175.Fa a 176- 177.Fa b 178and stores the result in 179.Fa res . 180.Pp 181.Fn timeradd a b res 182adds two timers and stores the result in 183.Fa res . 184.Sh RETURN VALUES 185.Rv -std getitimer setitimer 186.Pp 187.Fn timerisset 188returns a non-zero value if the time value in 189.Fa a 190is non-zero or 0 otherwise. 191.Pp 192.Fn timerisvalid 193returns 1 if the microsecond value in 194.Fa a 195is greater than or equal to zero and less than 1 million, 196or 0 otherwise. 197.Pp 198.Fn timercmp 199returns 1 if the given relation is true or 0 otherwise. 200.Sh ERRORS 201.Fn getitimer 202and 203.Fn setitimer 204will fail if: 205.Bl -tag -width Er 206.It Bq Er EFAULT 207The 208.Fa value 209parameter specified a bad address. 210.It Bq Er EINVAL 211An unrecognized value for 212.Fa which 213was specified. 214.El 215.Pp 216In addition, 217.Fn setitimer 218may return the following error: 219.Bl -tag -width Er 220.It Bq Er EINVAL 221.Fa value 222or 223.Fa ovalue 224specified a time that was too large to be handled. 225.El 226.Sh SEE ALSO 227.Xr clock_gettime 2 , 228.Xr gettimeofday 2 , 229.Xr poll 2 , 230.Xr select 2 , 231.Xr sigaction 2 232.Sh STANDARDS 233The 234.Fn getitimer 235and 236.Fn setitimer 237functions conform to 238.St -p1003.1-2008 . 239.Sh HISTORY 240The 241.Fn getitimer 242and 243.Fn setitimer 244system calls first appeared in 245.Bx 4.1c . 246.Pp 247The macros 248.Fn timerclear , 249.Fn timerisset , 250and 251.Fn timercmp 252first appeared in 253.Bx 4.1c , 254.Fn timersub 255and 256.Fn timeradd 257in 258.Nx 1.1 , 259and 260.Fn timerisvalid 261in 262.Ox 6.5 . 263