git.saurik.com Git - apple/xnu.git/blob - osfmk/man/clock

1 <h2>clock_alarm</h2>

2 <hr>

3 <p>

4 <strong>Function</strong> - Set off an alarm.

5 <h3>SYNOPSIS</h3>

6 <pre>

7 <strong>kern_return_t clock_alarm</strong>

8 <strong>(clock_t</strong> <var>clock_name</var>,

9 <strong>alarm_type_t</strong> <var>alarm_type</var>,

10 <strong>tvalspec_t</strong> <var>alarm_time</var>,

11 <strong>mach_port_t</strong> <var>alarm_reply_port</var><strong>);</strong>

12 </pre>

13 <h3>PARAMETERS</h3>

14 <dl>

15 <p>

16 <dt> <var>clock_name</var>

17 <dd>

18 [in clock-name send right]

19 The name (or control) port for the clock.

20 <p>

21 <dt> <var>alarm_type</var>

22 <dd>

23 [in scalar]

24 How to interpret the <var>alarm_time</var> value:

25 <dl>

26 <p>

27 <dt> <strong>TIME_RELATIVE</strong>

28 <dd>

29 Interpret the alarm time as relative to the current time.

30 <p>

31 <dt> <strong>TIME_ABSOLUTE</strong>

32 <dd>

33 Interpret the alarm time as an absolute time.

34 </dl>

35 <p>

36 <dt> <var>alarm_time</var>

37 <dd>

38 [in structure]

39 The time when the alarm is to be sent.

40 <p>

41 <dt> <var>alarm_reply_port</var>

42 <dd>

43 [in alarm receive (to be converted to send-once) right]

44 A port into

45 which the alarm message is to be sent.

46 </dl>

47 <h3>DESCRIPTION</h3>

48 <p>

49 The <strong>clock_alarm</strong> function requests that a clock send

50 an alarm message to a

51 specified port at a given future time. The alarm message is specified by the

52 <strong>clock_alarm_reply</strong> server interface.

53 <h3>NOTES</h3>

54 <p>

55 If the specified alarm time is in the past, the alarm message

56 is sent immediately

57 and time-stamped with the current time. Otherwise, the alarm is queued and

58 delivered at the specified alarm time and time-stamped at that time.

59 <p>

60 The alarm will be serviced at the service time nearest the specified

61 alarm time

62 as governed by the current clock alarm resolution.

63 <p>

64 Not all clocks implement this service, but the REALTIME clock must. If the

65 clock does not provide this service, this call is ignored.

66 <h3>RETURN VALUES</h3>

67 <p>

68 Only generic errors apply.

69 <h3>RELATED INFORMATION</h3>

70 <p>

71 Functions:

 <a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>,

 <a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>,

 <a href="clock_get_time.html"><strong>clock_get_time</strong></a>,

 <a href="clock_sleep.html"><strong>clock_sleep</strong></a>,

 <a href="clock_alarm_reply.html"><strong>clock_alarm_reply</strong></a>.

77 <p>

78 Data Structures:

 <a href="tvalspec.html"><strong>tvalspec</strong></a>.