1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)getitimer.2 8.3 (Berkeley) 5/16/95 33.\" $FreeBSD$ 34.\" 35.Dd May 16, 1995 36.Dt GETITIMER 2 37.Os 38.Sh NAME 39.Nm getitimer , 40.Nm setitimer 41.Nd get/set value of interval timer 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In sys/time.h 46.Fd "#define ITIMER_REAL 0" 47.Fd "#define ITIMER_VIRTUAL 1" 48.Fd "#define ITIMER_PROF 2" 49.Ft int 50.Fn getitimer "int which" "struct itimerval *value" 51.Ft int 52.Fn setitimer "int which" "const struct itimerval *value" "struct itimerval *ovalue" 53.Sh DESCRIPTION 54The system provides each process with three interval timers, 55defined in 56.In sys/time.h . 57The 58.Fn getitimer 59system call returns the current value for the timer specified in 60.Fa which 61in the structure at 62.Fa value . 63The 64.Fn setitimer 65system call sets a timer to the specified 66.Fa value 67(returning the previous value of the timer if 68.Fa ovalue 69is not a 70.Dv NULL 71pointer). 72.Pp 73A timer value is defined by the 74.Fa itimerval 75structure: 76.Bd -literal -offset indent 77struct itimerval { 78 struct timeval it_interval; /* timer interval */ 79 struct timeval it_value; /* current value */ 80}; 81.Ed 82.Pp 83If 84.Fa it_value 85is non-zero, it indicates the time to the next timer expiration. 86If 87.Fa it_interval 88is non-zero, it specifies a value to be used in reloading 89.Fa it_value 90when the timer expires. 91Setting 92.Fa it_value 93to 0 disables a timer, regardless of the value of 94.Fa it_interval . 95Setting 96.Fa it_interval 97to 0 causes a timer to be disabled after its next expiration (assuming 98.Fa it_value 99is non-zero). 100.Pp 101Time values smaller than the resolution of the 102system clock are rounded up to this resolution 103(typically 10 milliseconds). 104.Pp 105The 106.Dv ITIMER_REAL 107timer decrements in real time. 108A 109.Dv SIGALRM 110signal is 111delivered when this timer expires. 112.Pp 113The 114.Dv ITIMER_VIRTUAL 115timer decrements in process virtual time. 116It runs only when the process is executing. 117A 118.Dv SIGVTALRM 119signal 120is delivered when it expires. 121.Pp 122The 123.Dv ITIMER_PROF 124timer decrements both in process virtual time and 125when the system is running on behalf of the process. 126It is designed 127to be used by interpreters in statistically profiling the execution 128of interpreted programs. 129Each time the 130.Dv ITIMER_PROF 131timer expires, the 132.Dv SIGPROF 133signal is 134delivered. 135Because this signal may interrupt in-progress 136system calls, programs using this timer must be prepared to 137restart interrupted system calls. 138.Pp 139The maximum number of seconds allowed for 140.Fa it_interval 141and 142.Fa it_value 143in 144.Fn setitimer 145is 100000000. 146.Sh NOTES 147Three macros for manipulating time values are defined in 148.In sys/time.h . 149The 150.Fn timerclear 151macro 152sets a time value to zero, 153.Fn timerisset 154tests if a time value is non-zero, and 155.Fn timercmp 156compares two time values. 157.Sh RETURN VALUES 158.Rv -std 159.Sh ERRORS 160The 161.Fn getitimer 162and 163.Fn setitimer 164system calls 165will fail if: 166.Bl -tag -width Er 167.It Bq Er EFAULT 168The 169.Fa value 170argument specified a bad address. 171.It Bq Er EINVAL 172The 173.Fa value 174argument specified a time that was too large 175to be handled. 176.El 177.Sh SEE ALSO 178.Xr gettimeofday 2 , 179.Xr select 2 , 180.Xr sigvec 2 , 181.Xr clocks 7 182.Sh HISTORY 183The 184.Fn getitimer 185system call appeared in 186.Bx 4.2 . 187