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: src/lib/libc/sys/getitimer.2,v 1.10.2.6 2001/12/14 18:34:00 ru Exp $ 34.\" $DragonFly: src/lib/libc/sys/getitimer.2,v 1.3 2006/05/26 19:39:37 swildner Exp $ 35.\" 36.Dd May 16, 1995 37.Dt GETITIMER 2 38.Os 39.Sh NAME 40.Nm getitimer , 41.Nm setitimer 42.Nd get/set value of interval timer 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In sys/time.h 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.Sh DESCRIPTION 55The system provides each process with three interval timers, 56defined in 57.In sys/time.h . 58The 59.Fn getitimer 60call returns the current value for the timer specified in 61.Fa which 62in the structure at 63.Fa value . 64The 65.Fn setitimer 66call sets a timer to the specified 67.Fa value 68(returning the previous value of the timer if 69.Fa ovalue 70is non-nil). 71.Pp 72A timer value is defined by the 73.Fa itimerval 74structure: 75.Bd -literal -offset indent 76struct itimerval { 77 struct timeval it_interval; /* timer interval */ 78 struct timeval it_value; /* current value */ 79}; 80.Ed 81.Pp 82If 83.Fa it_value 84is non-zero, it indicates the time to the next timer expiration. 85If 86.Fa it_interval 87is non-zero, it specifies a value to be used in reloading 88.Fa it_value 89when the timer expires. 90Setting 91.Fa it_value 92to 0 disables a timer, regardless of the value of 93.Fa it_interval . 94Setting 95.Fa it_interval 96to 0 causes a timer to be disabled after its next expiration (assuming 97.Fa it_value 98is non-zero). 99.Pp 100Time values smaller than the resolution of the 101system clock are rounded up to this resolution 102(typically 10 milliseconds). 103.Pp 104The 105.Dv ITIMER_REAL 106timer decrements in real time. A 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. A 115.Dv SIGVTALRM 116signal 117is delivered when it expires. 118.Pp 119The 120.Dv ITIMER_PROF 121timer decrements both in process virtual time and 122when the system is running on behalf of the process. It is designed 123to be used by interpreters in statistically profiling the execution 124of interpreted programs. 125Each time the 126.Dv ITIMER_PROF 127timer expires, the 128.Dv SIGPROF 129signal is 130delivered. Because this signal may interrupt in-progress 131system calls, programs using this timer must be prepared to 132restart interrupted system calls. 133.Pp 134The maximum number of seconds allowed for 135.Fa it_interval 136and 137.Fa it_value 138in 139.Fn setitimer 140is 100000000. 141.Sh NOTES 142Three macros for manipulating time values are defined in 143.In sys/time.h . 144.Fa Timerclear 145sets a time value to zero, 146.Fa timerisset 147tests if a time value is non-zero, and 148.Fa timercmp 149compares two time values. 150.Sh RETURN VALUES 151.Rv -std 152.Sh ERRORS 153.Fn Getitimer 154and 155.Fn setitimer 156will fail if: 157.Bl -tag -width Er 158.It Bq Er EFAULT 159The 160.Fa value 161parameter specified a bad address. 162.It Bq Er EINVAL 163A 164.Fa value 165parameter specified a time that was too large 166to be handled. 167.El 168.Sh SEE ALSO 169.Xr gettimeofday 2 , 170.Xr select 2 , 171.Xr sigvec 2 , 172.Xr clocks 7 173.Sh HISTORY 174The 175.Fn getitimer 176function call appeared in 177.Bx 4.2 . 178