Commit | Line | Data |
---|---|---|
931b8415 | 1 | .\" Copyright (c) 1983, 1991 The Regents of the University of California. |
88b3ccf2 | 2 | .\" All rights reserved. |
616f8a75 | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
88b3ccf2 | 5 | .\" |
931b8415 | 6 | .\" @(#)getitimer.2 6.6 (Berkeley) %G% |
616f8a75 | 7 | .\" |
931b8415 CL |
8 | .Dd |
9 | .Dt GETITIMER 2 | |
10 | .Os BSD 4.2 | |
11 | .Sh NAME | |
12 | .Nm getitimer , | |
13 | .Nm setitimer | |
14 | .Nd get/set value of interval timer | |
15 | .Sh SYNOPSIS | |
16 | .Fd #include <sys/time.h> | |
17 | .Fd #define ITIMER_REAL 0 | |
18 | .Fd #define ITIMER_VIRTUAL 1 | |
19 | .Fd #define ITIMER_PROF 2 | |
20 | .Ft int | |
21 | .Fn getitimer "int which" "struct itimerval *value" | |
22 | .Ft int | |
23 | .Fn setitimer "int which" "struct itimerval *value" "struct itimerval *ovalue" | |
24 | .Sh DESCRIPTION | |
616f8a75 KM |
25 | The system provides each process with three interval timers, |
26 | defined in | |
931b8415 | 27 | .Ao Pa sys/time.h Ac . |
616f8a75 | 28 | The |
931b8415 | 29 | .Fn getitimer |
616f8a75 | 30 | call returns the current value for the timer specified in |
931b8415 | 31 | .Fa which |
1d87bb13 | 32 | in the structure at |
931b8415 | 33 | .Fa value . |
1d87bb13 | 34 | The |
931b8415 | 35 | .Fn setitimer |
1d87bb13 | 36 | call sets a timer to the specified |
931b8415 | 37 | .Fa value |
1d87bb13 | 38 | (returning the previous value of the timer if |
931b8415 CL |
39 | .Fa ovalue |
40 | is non-nil). | |
41 | .Pp | |
616f8a75 | 42 | A timer value is defined by the |
931b8415 | 43 | .Fa itimerval |
616f8a75 | 44 | structure: |
931b8415 | 45 | .Bd -literal -offset indent |
616f8a75 KM |
46 | struct itimerval { |
47 | struct timeval it_interval; /* timer interval */ | |
48 | struct timeval it_value; /* current value */ | |
49 | }; | |
931b8415 CL |
50 | .Ed |
51 | .Pp | |
616f8a75 | 52 | If |
931b8415 | 53 | .Fa it_value |
616f8a75 KM |
54 | is non-zero, it indicates the time to the next timer expiration. |
55 | If | |
931b8415 | 56 | .Fa it_interval |
616f8a75 | 57 | is non-zero, it specifies a value to be used in reloading |
931b8415 | 58 | .Fa it_value |
616f8a75 KM |
59 | when the timer expires. |
60 | Setting | |
931b8415 | 61 | .Fa it_value |
616f8a75 | 62 | to 0 disables a timer. Setting |
931b8415 | 63 | .Fa it_interval |
616f8a75 | 64 | to 0 causes a timer to be disabled after its next expiration (assuming |
931b8415 | 65 | .Fa it_value |
616f8a75 | 66 | is non-zero). |
931b8415 | 67 | .Pp |
616f8a75 KM |
68 | Time values smaller than the resolution of the |
69 | system clock are rounded up to this resolution | |
931b8415 CL |
70 | (typically 10 milliseconds). |
71 | .Pp | |
72 | The | |
73 | .Dv ITIMER_REAL | |
74 | timer decrements in real time. A | |
75 | .Dv SIGALRM | |
76 | signal is | |
616f8a75 | 77 | delivered when this timer expires. |
931b8415 CL |
78 | .Pp |
79 | The | |
80 | .Dv ITIMER_VIRTUAL | |
81 | timer decrements in process virtual time. | |
82 | It runs only when the process is executing. A | |
83 | .Dv SIGVTALRM | |
84 | signal | |
616f8a75 | 85 | is delivered when it expires. |
931b8415 CL |
86 | .Pp |
87 | The | |
88 | .Dv ITIMER_PROF | |
89 | timer decrements both in process virtual time and | |
616f8a75 KM |
90 | when the system is running on behalf of the process. It is designed |
91 | to be used by interpreters in statistically profiling the execution | |
92 | of interpreted programs. | |
931b8415 CL |
93 | Each time the |
94 | .Dv ITIMER_PROF | |
95 | timer expires, the | |
96 | .Dv SIGPROF | |
97 | signal is | |
616f8a75 KM |
98 | delivered. Because this signal may interrupt in-progress |
99 | system calls, programs using this timer must be prepared to | |
100 | restart interrupted system calls. | |
931b8415 | 101 | .Sh NOTES |
616f8a75 | 102 | Three macros for manipulating time values are defined in |
931b8415 CL |
103 | .Ao Pa sys/time.h Ac . |
104 | .Fa Timerclear | |
616f8a75 | 105 | sets a time value to zero, |
931b8415 | 106 | .Fa timerisset |
616f8a75 | 107 | tests if a time value is non-zero, and |
931b8415 | 108 | .Fa timercmp |
616f8a75 KM |
109 | compares two time values (beware that >= and <= do not |
110 | work with this macro). | |
931b8415 | 111 | .Sh RETURN VALUES |
616f8a75 | 112 | If the calls succeed, a value of 0 is returned. If an error occurs, |
931b8415 CL |
113 | the value -1 is returned, and a more precise error code is placed |
114 | in the global variable | |
115 | .Va errno . | |
116 | .Sh ERRORS | |
117 | .Fn Getitimer | |
118 | and | |
119 | .Fn setitimer | |
120 | will fail if: | |
121 | .Bl -tag -width Er | |
122 | .It Bq Er EFAULT | |
123 | The | |
124 | .Fa value | |
125 | parameter specified a bad address. | |
126 | .It Bq Er EINVAL | |
127 | A | |
128 | .Fa value | |
129 | parameter specified a time was too large | |
616f8a75 | 130 | to be handled. |
931b8415 CL |
131 | .El |
132 | .Sh SEE ALSO | |
133 | .Xr select 2 , | |
134 | .Xr sigvec 2 , | |
135 | .Xr gettimeofday 2 | |
136 | .Sh HISTORY | |
137 | The | |
138 | .Nm | |
139 | function call appeared in | |
140 | .Bx 4.2 . |