git.saurik.com Git - apple/xnu.git/blob - bsd/man/man2/getitimer.2

1 .\" $NetBSD: getitimer.2,v 1.6 1995/10/12 15:40:54 jtc Exp $

2 .\"

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

61 The system provides each process with three interval timers,

62 defined in

63 .Ao Pa sys/time.h Ac .

64 The

65 .Fn getitimer

66 call returns the current value for the timer specified in

67 .Fa which

68 in the structure at

69 .Fa value .

70 The

71 .Fn setitimer

72 call sets a timer to the specified

73 .Fa value

74 (returning the previous value of the timer if

75 .Fa ovalue

76 is non-nil).

77 .Pp

78 A timer value is defined by the

79 .Fa itimerval

80 structure:

81 .Bd -literal -offset indent

82 struct itimerval {

83 struct timeval it_interval; /* timer interval */

84 struct timeval it_value; /* current value */

85 };

86 .Ed

87 .Pp

88 If

89 .Fa it_value

90 is non-zero, it indicates the time to the next timer expiration.

91 If

92 .Fa it_interval

93 is non-zero, it specifies a value to be used in reloading

94 .Fa it_value

95 when the timer expires.

96 Setting

97 .Fa it_value

98 to 0 disables a timer. Setting

99 .Fa it_interval

100 to 0 causes a timer to be disabled after its next expiration (assuming

101 .Fa it_value

102 is non-zero).

103 .Pp

104 Time values smaller than the resolution of the

105 system clock are rounded up to this resolution

106 (typically 10 milliseconds).

107 .Pp

108 The

109 .Dv ITIMER_REAL

110 timer decrements in real time. A

111 .Dv SIGALRM

112 signal is

113 delivered when this timer expires.

114 .Pp

115 The

116 .Dv ITIMER_VIRTUAL

117 timer decrements in process virtual time.

118 It runs only when the process is executing. A

119 .Dv SIGVTALRM

120 signal

121 is delivered when it expires.

122 .Pp

123 The

124 .Dv ITIMER_PROF

125 timer decrements both in process virtual time and

126 when the system is running on behalf of the process. It is designed

127 to be used by interpreters in statistically profiling the execution

128 of interpreted programs.

129 Each time the

130 .Dv ITIMER_PROF

131 timer expires, the

132 .Dv SIGPROF

133 signal is

134 delivered. Because this signal may interrupt in-progress

135 system calls, programs using this timer must be prepared to

136 restart interrupted system calls.

137 .Sh NOTES

138 Three macros for manipulating time values are defined in

139 .Ao Pa sys/time.h Ac .

140 .Fa Timerclear

141 sets a time value to zero,

142 .Fa timerisset

143 tests if a time value is non-zero, and

144 .Fa timercmp

145 compares two time values (beware that >= and <= do not

146 work with this macro).

147 .Sh RETURN VALUES

148 Upon successful completion, a value of 0 is returned.

149 Otherwise, a value of -1 is returned and the global integer variable

150 .Va errno

151 is set to indicate the error.

152 .Sh ERRORS

153 .Fn getitimer

154 and

155 .Fn setitimer

156 will fail if:

157 .Bl -tag -width Er

158 .\" ==========

159 .It Bq Er EFAULT

160 The

161 .Fa value

162 parameter specified a bad address.

163 .\" ==========

164 .It Bq Er EINVAL

165 The

166 .Fa value

167 parameter specified a time that was too large to be handled

168 or not in the canonical form.

169 .\" ==========

170 .It Bq Er EINVAL

171 The

172 .Fa which

173 parameter was invalid.

174 .El

175 .Sh SEE ALSO

176 .Xr gettimeofday 2 ,

177 .Xr select 2 ,

178 .Xr sigaction 2

179 .Sh HISTORY

180 The

181 .Fn getitimer

182 function call appeared in

183 .Bx 4.2 .