1.\" $NetBSD: getitimer.2,v 1.14 2002/02/08 01:28:17 ross 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. Setting 93.Fa it_interval 94to 0 causes a timer to be disabled after its next expiration (assuming 95.Fa it_value 96is non-zero). 97.Pp 98Time values smaller than the resolution of the 99system clock are rounded up to this resolution 100(typically 10 milliseconds). 101.Pp 102The 103.Dv ITIMER_REAL 104timer decrements in real time. A 105.Dv SIGALRM 106signal is 107delivered when this timer expires. 108.Pp 109The 110.Dv ITIMER_VIRTUAL 111timer decrements in process virtual time. 112It runs only when the process is executing. A 113.Dv SIGVTALRM 114signal 115is delivered when it expires. 116.Pp 117The 118.Dv ITIMER_PROF 119timer decrements both in process virtual time and 120when the system is running on behalf of the process. It is designed 121to be used by interpreters in statistically profiling the execution 122of interpreted programs. 123Each time the 124.Dv ITIMER_PROF 125timer expires, the 126.Dv SIGPROF 127signal is 128delivered. Because this signal may interrupt in-progress 129system calls, programs using this timer must be prepared to 130restart interrupted system calls. 131.Sh NOTES 132Three macros for manipulating time values are defined in 133.Ao Pa sys/time.h Ac . 134.Fa timerclear 135sets a time value to zero, 136.Fa timerisset 137tests if a time value is non-zero, and 138.Fa timercmp 139compares two time values. 140.Sh RETURN VALUES 141If the calls succeed, a value of 0 is returned. If an error occurs, 142the value -1 is returned, and a more precise error code is placed 143in the global variable 144.Va errno . 145.Sh ERRORS 146.Fn getitimer 147and 148.Fn setitimer 149will fail if: 150.Bl -tag -width Er 151.It Bq Er EFAULT 152The 153.Fa value 154parameter specified a bad address. 155.It Bq Er EINVAL 156A 157.Fa value 158parameter specified a time that was too large 159to be handled. 160.El 161.Sh SEE ALSO 162.Xr gettimeofday 2 , 163.Xr poll 2 , 164.Xr select 2 , 165.Xr sigaction 2 166.Sh HISTORY 167The 168.Fn getitimer 169function call appeared in 170.Bx 4.2 . 171