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 null pointer). 70.Pp 71A timer value is defined by the 72.Fa itimerval 73structure: 74.Bd -literal -offset indent 75struct itimerval { 76 struct timeval it_interval; /* timer interval */ 77 struct timeval it_value; /* current value */ 78}; 79.Ed 80.Pp 81If 82.Fa it_value 83is non-zero, it indicates the time to the next timer expiration. 84If 85.Fa it_interval 86is non-zero, it specifies a value to be used in reloading 87.Fa it_value 88when the timer expires. 89Setting 90.Fa it_value 91to 0 disables a timer, regardless of the value of 92.Fa it_interval . 93Setting 94.Fa it_interval 95to 0 causes a timer to be disabled after its next expiration (assuming 96.Fa it_value 97is non-zero). 98.Pp 99Time values smaller than the resolution of the 100system clock are rounded up to this resolution 101(typically 10 milliseconds). 102.Pp 103The 104.Dv ITIMER_REAL 105timer decrements in real time. 106A 107.Dv SIGALRM 108signal is 109delivered when this timer expires. 110.Pp 111The 112.Dv ITIMER_VIRTUAL 113timer decrements in process virtual time. 114It runs only when the process is executing. 115A 116.Dv SIGVTALRM 117signal 118is delivered when it expires. 119.Pp 120The 121.Dv ITIMER_PROF 122timer decrements both in process virtual time and 123when the system is running on behalf of the process. 124It is designed 125to be used by interpreters in statistically profiling the execution 126of interpreted programs. 127Each time the 128.Dv ITIMER_PROF 129timer expires, the 130.Dv SIGPROF 131signal is 132delivered. 133Because this signal may interrupt in-progress 134system calls, programs using this timer must be prepared to 135restart interrupted system calls. 136.Pp 137The maximum number of seconds allowed for 138.Fa it_interval 139and 140.Fa it_value 141in 142.Fn setitimer 143is 100000000. 144.Sh NOTES 145Three macros for manipulating time values are defined in 146.In sys/time.h . 147The 148.Fn timerclear 149macro 150sets a time value to zero, 151.Fn timerisset 152tests if a time value is non-zero, and 153.Fn timercmp 154compares two time values. 155.Sh RETURN VALUES 156.Rv -std 157.Sh ERRORS 158The 159.Fn getitimer 160and 161.Fn setitimer 162system calls 163will fail if: 164.Bl -tag -width Er 165.It Bq Er EFAULT 166The 167.Fa value 168argument specified a bad address. 169.It Bq Er EINVAL 170The 171.Fa value 172argument specified a time that was too large 173to be handled. 174.El 175.Sh SEE ALSO 176.Xr gettimeofday 2 , 177.Xr select 2 , 178.Xr sigvec 2 , 179.Xr clocks 7 180.Sh HISTORY 181The 182.Fn getitimer 183system call appeared in 184.Bx 4.2 . 185