Commit | Line | Data |
---|---|---|
616f8a75 KM |
1 | .\" Copyright (c) 1983 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
d0528fe6 | 5 | .\" @(#)getitimer.2 6.3 (Berkeley) %G% |
616f8a75 | 6 | .\" |
1d87bb13 | 7 | .TH GETITIMER 2 "" |
616f8a75 KM |
8 | .UC 5 |
9 | .SH NAME | |
10 | getitimer, setitimer \- get/set value of interval timer | |
11 | .SH SYNOPSIS | |
12 | .nf | |
13 | .ft B | |
14 | #include <sys/time.h> | |
15 | .PP | |
16 | .ft B | |
17 | #define ITIMER_REAL 0 /* real time intervals */ | |
18 | #define ITIMER_VIRTUAL 1 /* virtual time intervals */ | |
19 | #define ITIMER_PROF 2 /* user and system virtual time */ | |
20 | .sp | |
21 | .ft B | |
22 | getitimer(which, value) | |
23 | int which; | |
24 | struct itimerval *value; | |
25 | .PP | |
26 | .ft B | |
27 | setitimer(which, value, ovalue) | |
28 | int which; | |
29 | struct itimerval *value, *ovalue; | |
30 | .fi | |
31 | .SH DESCRIPTION | |
32 | The system provides each process with three interval timers, | |
33 | defined in | |
34 | .RI < sys/time.h >. | |
35 | The | |
36 | .I getitimer | |
37 | call returns the current value for the timer specified in | |
1d87bb13 KM |
38 | .I which |
39 | in the structure at | |
40 | .IR value . | |
41 | The | |
616f8a75 | 42 | .I setitimer |
1d87bb13 KM |
43 | call sets a timer to the specified |
44 | .I value | |
45 | (returning the previous value of the timer if | |
46 | .I ovalue | |
47 | is nonzero). | |
616f8a75 KM |
48 | .PP |
49 | A timer value is defined by the | |
50 | .I itimerval | |
51 | structure: | |
52 | .PP | |
53 | .nf | |
54 | .RS | |
55 | .DT | |
56 | struct itimerval { | |
57 | struct timeval it_interval; /* timer interval */ | |
58 | struct timeval it_value; /* current value */ | |
59 | }; | |
60 | .RE | |
61 | .fi | |
62 | .PP | |
63 | If | |
64 | .I it_value | |
65 | is non-zero, it indicates the time to the next timer expiration. | |
66 | If | |
67 | .I it_interval | |
68 | is non-zero, it specifies a value to be used in reloading | |
69 | .I it_value | |
70 | when the timer expires. | |
71 | Setting | |
72 | .I it_value | |
73 | to 0 disables a timer. Setting | |
74 | .I it_interval | |
75 | to 0 causes a timer to be disabled after its next expiration (assuming | |
76 | .I it_value | |
77 | is non-zero). | |
78 | .PP | |
79 | Time values smaller than the resolution of the | |
80 | system clock are rounded up to this resolution | |
1d87bb13 | 81 | (on the VAX, 10 milliseconds). |
616f8a75 KM |
82 | .PP |
83 | The ITIMER_REAL timer decrements in real time. A SIGALRM signal is | |
84 | delivered when this timer expires. | |
85 | .PP | |
86 | The ITIMER_VIRTUAL timer decrements in process virtual time. | |
87 | It runs only when the process is executing. A SIGVTALRM signal | |
88 | is delivered when it expires. | |
89 | .PP | |
90 | The ITIMER_PROF timer decrements both in process virtual time and | |
91 | when the system is running on behalf of the process. It is designed | |
92 | to be used by interpreters in statistically profiling the execution | |
93 | of interpreted programs. | |
94 | Each time the ITIMER_PROF timer expires, the SIGPROF signal is | |
95 | delivered. Because this signal may interrupt in-progress | |
96 | system calls, programs using this timer must be prepared to | |
97 | restart interrupted system calls. | |
98 | .SH NOTES | |
99 | Three macros for manipulating time values are defined in | |
100 | .RI < sys/time.h >. | |
101 | .I Timerclear | |
102 | sets a time value to zero, | |
103 | .I timerisset | |
104 | tests if a time value is non-zero, and | |
105 | .I timercmp | |
106 | compares two time values (beware that >= and <= do not | |
107 | work with this macro). | |
108 | .SH "RETURN VALUE | |
109 | If the calls succeed, a value of 0 is returned. If an error occurs, | |
110 | the value \-1 is returned, and a more precise error code is placed | |
111 | in the global variable \fIerrno\fP. | |
112 | .SH "ERRORS | |
113 | The possible errors are: | |
114 | .TP 15 | |
115 | [EFAULT] | |
fd690c8b | 116 | The \fIvalue\fP parameter specified a bad address. |
616f8a75 KM |
117 | .TP 15 |
118 | [EINVAL] | |
fd690c8b | 119 | A \fIvalue\fP parameter specified a time was too large |
616f8a75 KM |
120 | to be handled. |
121 | .SH "SEE ALSO" | |
d0528fe6 | 122 | select(2), sigvec(2), gettimeofday(2) |