1.\" $OpenBSD: getitimer.2,v 1.16 2001/09/07 14:35:59 niklas 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. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)getitimer.2 8.2 (Berkeley) 12/11/93 36.\" 37.Dd December 11, 1993 38.Dt GETITIMER 2 39.Os 40.Sh NAME 41.Nm getitimer , 42.Nm setitimer 43.Nd get/set value of interval timer 44.Sh SYNOPSIS 45.Fd #include <sys/time.h> 46 47.Fd #define ITIMER_REAL 0 48.Fd #define ITIMER_VIRTUAL 1 49.Fd #define ITIMER_PROF 2 50.Ft int 51.Fn getitimer "int which" "struct itimerval *value" 52.Ft int 53.Fn setitimer "int which" "const struct itimerval *value" "struct itimerval *ovalue" 54.Ft void 55.Fn timerclear "struct timeval *" 56.Ft int 57.Fn timerisset "struct timeval *" 58.Ft int 59.Fn timercmp "struct timeval *a, struct timeval *b, CMP" 60.Ft void 61.Fn timersub "struct timeval *a, struct timeval *b, struct timeval *res" 62.Ft void 63.Fn timeradd "struct timeval *a, struct timeval *b, struct timeval *res" 64.Sh DESCRIPTION 65The system provides each process with three interval timers, 66defined in 67.Ao Pa sys/time.h Ac . 68The 69.Fn getitimer 70call returns the current value for the timer specified in 71.Fa which 72in the structure at 73.Fa value . 74The 75.Fn setitimer 76call sets a timer to the specified 77.Fa value 78(returning the previous value of the timer if 79.Fa ovalue 80is non-null). 81.Pp 82A timer value is defined by the 83.Fa itimerval 84structure: 85.Bd -literal -offset indent 86struct itimerval { 87 struct timeval it_interval; /* timer interval */ 88 struct timeval it_value; /* current value */ 89}; 90.Ed 91.Pp 92If 93.Fa it_value 94is non-zero, it indicates the time to the next timer expiration. 95If 96.Fa it_interval 97is non-zero, it specifies a value to be used in reloading 98.Fa it_value 99when the timer expires. 100Setting 101.Fa it_value 102to 0 disables a timer. 103Setting 104.Fa it_interval 105to 0 causes a timer to be disabled after its next expiration (assuming 106.Fa it_value 107is non-zero). 108.Pp 109Time values smaller than the resolution of the 110system clock are rounded up to this resolution 111(typically 10 milliseconds). 112.Pp 113The 114.Dv ITIMER_REAL 115timer decrements in real time. 116A 117.Dv SIGALRM 118signal is 119delivered when this timer expires. 120.Pp 121The 122.Dv ITIMER_VIRTUAL 123timer decrements in process virtual time. 124It runs only when the process is executing. 125A 126.Dv SIGVTALRM 127signal is delivered when it expires. 128.Pp 129The 130.Dv ITIMER_PROF 131timer decrements both in process virtual time and 132when the system is running on behalf of the process. 133It is designed to be used by interpreters in statistically profiling 134the execution of interpreted programs. 135Each time the 136.Dv ITIMER_PROF 137timer expires, the 138.Dv SIGPROF 139signal is delivered. 140Because this signal may interrupt in-progress 141system calls, programs using this timer must be prepared to 142restart interrupted system calls. 143.Pp 144The remaining five functions are in fact macros for manipulating time 145values, defined in 146.Ao Pa sys/time.h Ac . 147.Pp 148.Fn timerclear "a" 149sets the time value in 150.Fa a 151to zero. 152.Pp 153.Fn timerisset "a" 154tests if the time value in 155.Fa a 156is non-zero. 157.Pp 158.Fn timercmp "a, b, CMP" 159compares two time values in the form 160.Fa a 161CMP 162.Fa b Ns , 163where 164.Fa CMP 165is <, <=, ==, !=, >=, or > . 166.Pp 167.Fn timersub "a, b, res" 168subtracts 169.Fa a 170- 171.Fa b 172and stores the result in 173.Fa res Ns . 174.Pp 175.Fn timeradd "a, b, res" 176adds two timers and stores the result in 177.Fa res Ns . 178.Sh RETURN VALUES 179If the calls succeed, a value of 0 is returned. 180If an error occurs, the value \-1 is returned, and a more precise 181error code is placed in the global variable 182.Va errno . 183.Sh ERRORS 184.Fn getitimer 185and 186.Fn setitimer 187will fail if: 188.Bl -tag -width Er 189.It Bq Er EFAULT 190The 191.Fa value 192parameter specified a bad address. 193.It Bq Er EINVAL 194A 195.Fa value 196parameter specified a time that was too large to be handled. 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