1.\" $NetBSD: getitimer.2,v 1.6 1995/10/12 15:40:54 jtc 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.2 (Berkeley) 12/11/93 35.\" 36.Dd December 11, 1993 37.Dt GETITIMER 2 38.Os BSD 4.2 39.Sh NAME 40.Nm getitimer , 41.Nm setitimer 42.Nd get/set value of interval timer 43.Sh SYNOPSIS 44.Fd #include <sys/time.h> 45.Pp 46.Fd #define ITIMER_REAL 0 47.Fd #define ITIMER_VIRTUAL 1 48.Fd #define ITIMER_PROF 2 49.Ft int 50.Fo getitimer 51.Fa "int which" 52.Fa "struct itimerval *value" 53.Fc 54.Ft int 55.Fo setitimer 56.Fa "int which" 57.Fa "const struct itimerval *restrict value" 58.Fa "struct itimerval *restrict ovalue" 59.Fc 60.Sh DESCRIPTION 61The system provides each process with three interval timers, 62defined in 63.Ao Pa sys/time.h Ac . 64The 65.Fn getitimer 66call returns the current value for the timer specified in 67.Fa which 68in the structure at 69.Fa value . 70The 71.Fn setitimer 72call sets a timer to the specified 73.Fa value 74(returning the previous value of the timer if 75.Fa ovalue 76is non-nil). 77.Pp 78A timer value is defined by the 79.Fa itimerval 80structure: 81.Bd -literal -offset indent 82struct itimerval { 83 struct timeval it_interval; /* timer interval */ 84 struct timeval it_value; /* current value */ 85}; 86.Ed 87.Pp 88If 89.Fa it_value 90is non-zero, it indicates the time to the next timer expiration. 91If 92.Fa it_interval 93is non-zero, it specifies a value to be used in reloading 94.Fa it_value 95when the timer expires. 96Setting 97.Fa it_value 98to 0 disables a timer. Setting 99.Fa it_interval 100to 0 causes a timer to be disabled after its next expiration (assuming 101.Fa it_value 102is non-zero). 103.Pp 104Time values smaller than the resolution of the 105system clock are rounded up to this resolution 106(typically 10 milliseconds). 107.Pp 108The 109.Dv ITIMER_REAL 110timer decrements in real time. A 111.Dv SIGALRM 112signal is 113delivered when this timer expires. 114.Pp 115The 116.Dv ITIMER_VIRTUAL 117timer decrements in process virtual time. 118It runs only when the process is executing. A 119.Dv SIGVTALRM 120signal 121is delivered when it expires. 122.Pp 123The 124.Dv ITIMER_PROF 125timer decrements both in process virtual time and 126when the system is running on behalf of the process. It is designed 127to be used by interpreters in statistically profiling the execution 128of interpreted programs. 129Each time the 130.Dv ITIMER_PROF 131timer expires, the 132.Dv SIGPROF 133signal is 134delivered. Because this signal may interrupt in-progress 135system calls, programs using this timer must be prepared to 136restart interrupted system calls. 137.Sh NOTES 138Three macros for manipulating time values are defined in 139.Ao Pa sys/time.h Ac . 140.Fa Timerclear 141sets a time value to zero, 142.Fa timerisset 143tests if a time value is non-zero, and 144.Fa timercmp 145compares two time values (beware that >= and <= do not 146work with this macro). 147.Sh RETURN VALUES 148Upon successful completion, a value of 0 is returned. 149Otherwise, a value of -1 is returned and the global integer variable 150.Va errno 151is set to indicate the error. 152.Sh ERRORS 153.Fn getitimer 154and 155.Fn setitimer 156will fail if: 157.Bl -tag -width Er 158.\" ========== 159.It Bq Er EFAULT 160The 161.Fa value 162parameter specified a bad address. 163.\" ========== 164.It Bq Er EINVAL 165The 166.Fa value 167parameter specified a time that was too large to be handled 168or not in the canonical form. 169.\" ========== 170.It Bq Er EINVAL 171The 172.Fa which 173parameter was invalid. 174.El 175.Sh SEE ALSO 176.Xr gettimeofday 2 , 177.Xr select 2 , 178.Xr sigaction 2 179.Sh HISTORY 180The 181.Fn getitimer 182function call appeared in 183.Bx 4.2 . 184