1.\" $OpenBSD: getitimer.2,v 1.30 2019/01/18 09:36:47 cheloha 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 18 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 five functions are in fact macros for manipulating time 149values, defined in 150.In sys/time.h . 151.Pp 152.Fn timerclear "a" 153sets the time value in 154.Fa a 155to zero. 156.Pp 157.Fn timerisset "a" 158tests if the time value in 159.Fa a 160is non-zero. 161.Pp 162.Fn timerisvalid "a" 163tests if the microsecond value in 164.Fa a 165is greater than or equal to zero and less than 1 million. 166.Pp 167.Fn timercmp a b CMP 168compares two time values in the form 169.Fa a 170CMP 171.Fa b , 172where 173.Fa CMP 174is <, <=, ==, !=, >=, or > . 175.Pp 176.Fn timersub a b res 177subtracts 178.Fa a 179- 180.Fa b 181and stores the result in 182.Fa res . 183.Pp 184.Fn timeradd a b res 185adds two timers and stores the result in 186.Fa res . 187.Sh RETURN VALUES 188.Rv -std 189.Sh ERRORS 190.Fn getitimer 191and 192.Fn setitimer 193will fail if: 194.Bl -tag -width Er 195.It Bq Er EFAULT 196The 197.Fa value 198parameter specified a bad address. 199.It Bq Er EINVAL 200An unrecognized value for 201.Fa which 202was specified. 203.El 204.Pp 205In addition, 206.Fn setitimer 207may return the following error: 208.Bl -tag -width Er 209.It Bq Er EINVAL 210.Fa value 211or 212.Fa ovalue 213specified a time that was too large to be handled. 214.El 215.Sh SEE ALSO 216.Xr clock_gettime 2 , 217.Xr gettimeofday 2 , 218.Xr poll 2 , 219.Xr select 2 , 220.Xr sigaction 2 221.Sh STANDARDS 222The 223.Fn getitimer 224and 225.Fn setitimer 226functions conform to 227.St -p1003.1-2008 . 228.Sh HISTORY 229The 230.Fn getitimer 231and 232.Fn setitimer 233system calls first appeared in 234.Bx 4.1c . 235