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