1.\" $OpenBSD: getitimer.2,v 1.29 2015/11/10 23:48:18 jmc 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: November 10 2015 $ 34.Dt GETITIMER 2 35.Os 36.Sh NAME 37.Nm getitimer , 38.Nm setitimer , 39.Nm timerclear , 40.Nm timerisset , 41.Nm timercmp , 42.Nm timersub , 43.Nm timeradd 44.Nd get/set value of interval timer 45.Sh SYNOPSIS 46.In sys/time.h 47.Pp 48.Fd #define ITIMER_REAL 0 49.Fd #define ITIMER_VIRTUAL 1 50.Fd #define ITIMER_PROF 2 51.Ft int 52.Fn getitimer "int which" "struct itimerval *value" 53.Ft int 54.Fn setitimer "int which" "const struct itimerval *value" "struct itimerval *ovalue" 55.Ft void 56.Fn timerclear "struct timeval *" 57.Ft int 58.Fn timerisset "struct timeval *" 59.Ft int 60.Fn timercmp "struct timeval *a" "struct timeval *b" CMP 61.Ft void 62.Fn timersub "struct timeval *a" "struct timeval *b" "struct timeval *res" 63.Ft void 64.Fn timeradd "struct timeval *a" "struct timeval *b" "struct timeval *res" 65.Sh DESCRIPTION 66The system provides each process with three interval timers, 67defined in 68.In sys/time.h . 69The 70.Fn getitimer 71call returns the current value for the timer specified in 72.Fa which 73in the structure at 74.Fa value . 75The 76.Fn setitimer 77call sets a timer to the specified 78.Fa value 79(returning the previous value of the timer if 80.Fa ovalue 81is non-null). 82.Pp 83A timer value is defined by the 84.Fa itimerval 85structure: 86.Bd -literal -offset indent 87struct itimerval { 88 struct timeval it_interval; /* timer interval */ 89 struct timeval it_value; /* current value */ 90}; 91.Ed 92.Pp 93If 94.Fa it_value 95is non-zero, it indicates the time to the next timer expiration. 96If 97.Fa it_interval 98is non-zero, it specifies a value to be used in reloading 99.Fa it_value 100when the timer expires. 101Setting 102.Fa it_value 103to 0 disables a timer. 104Setting 105.Fa it_interval 106to 0 causes a timer to be disabled after its next expiration (assuming 107.Fa it_value 108is non-zero). 109.Pp 110Time values smaller than the resolution of the 111system clock are rounded up to this resolution 112(typically 10 milliseconds). 113.Pp 114The 115.Dv ITIMER_REAL 116timer decrements in real time. 117A 118.Dv SIGALRM 119signal is 120delivered when this timer expires. 121.Pp 122The 123.Dv ITIMER_VIRTUAL 124timer decrements in process virtual time. 125It runs only when the process is executing. 126A 127.Dv SIGVTALRM 128signal is delivered when it expires. 129.Pp 130The 131.Dv ITIMER_PROF 132timer decrements both in process virtual time and 133when the system is running on behalf of the process. 134It is designed to be used by interpreters in statistically profiling 135the execution of interpreted programs. 136Each time the 137.Dv ITIMER_PROF 138timer expires, the 139.Dv SIGPROF 140signal is delivered. 141Because this signal may interrupt in-progress 142system calls, programs using this timer must be prepared to 143restart interrupted system calls. 144.Pp 145The remaining five functions are in fact macros for manipulating time 146values, defined in 147.In sys/time.h . 148.Pp 149.Fn timerclear "a" 150sets the time value in 151.Fa a 152to zero. 153.Pp 154.Fn timerisset "a" 155tests if the time value in 156.Fa a 157is non-zero. 158.Pp 159.Fn timercmp a b CMP 160compares two time values in the form 161.Fa a 162CMP 163.Fa b , 164where 165.Fa CMP 166is <, <=, ==, !=, >=, or > . 167.Pp 168.Fn timersub a b res 169subtracts 170.Fa a 171- 172.Fa b 173and stores the result in 174.Fa res . 175.Pp 176.Fn timeradd a b res 177adds two timers and stores the result in 178.Fa res . 179.Sh RETURN VALUES 180.Rv -std 181.Sh ERRORS 182.Fn getitimer 183and 184.Fn setitimer 185will fail if: 186.Bl -tag -width Er 187.It Bq Er EFAULT 188The 189.Fa value 190parameter specified a bad address. 191.It Bq Er EINVAL 192An unrecognized value for 193.Fa which 194was specified. 195.El 196.Pp 197In addition, 198.Fn setitimer 199may return the following error: 200.Bl -tag -width Er 201.It Bq Er EINVAL 202.Fa value 203or 204.Fa ovalue 205specified a time that was too large to be handled. 206.El 207.Sh SEE ALSO 208.Xr clock_gettime 2 , 209.Xr gettimeofday 2 , 210.Xr poll 2 , 211.Xr select 2 , 212.Xr sigaction 2 213.Sh STANDARDS 214The 215.Fn getitimer 216and 217.Fn setitimer 218functions conform to 219.St -p1003.1-2008 . 220.Sh HISTORY 221The 222.Fn getitimer 223and 224.Fn setitimer 225system calls first appeared in 226.Bx 4.1c . 227