1.\" $NetBSD: getitimer.2,v 1.15 2002/10/01 18:10:44 wiz 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)getitimer.2 8.3 (Berkeley) 5/16/95 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.Fd #include \*[Lt]sys/time.h\*[Gt] 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.Ao Pa sys/time.h Ac . 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. 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 to be used by interpreters in statistically profiling 125the execution of interpreted programs. 126Each time the 127.Dv ITIMER_PROF 128timer expires, the 129.Dv SIGPROF 130signal is 131delivered. 132Because this signal may interrupt in-progress 133system calls, programs using this timer must be prepared to 134restart interrupted system calls. 135.Sh NOTES 136Three macros for manipulating time values are defined in 137.Ao Pa sys/time.h Ac . 138.Fa timerclear 139sets a time value to zero, 140.Fa timerisset 141tests if a time value is non-zero, and 142.Fa timercmp 143compares two time values. 144.Sh RETURN VALUES 145If the calls succeed, a value of 0 is returned. 146If an error occurs, the value -1 is returned, and a more precise error 147code is placed in the global variable 148.Va errno . 149.Sh ERRORS 150.Fn getitimer 151and 152.Fn setitimer 153will fail if: 154.Bl -tag -width Er 155.It Bq Er EFAULT 156The 157.Fa value 158parameter specified a bad address. 159.It Bq Er EINVAL 160A 161.Fa value 162parameter specified a time that was too large 163to be handled. 164.El 165.Sh SEE ALSO 166.Xr gettimeofday 2 , 167.Xr poll 2 , 168.Xr select 2 , 169.Xr sigaction 2 170.Sh HISTORY 171The 172.Fn getitimer 173function call appeared in 174.Bx 4.2 . 175