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