Next: , Previous: Host Information, Up: Host Interface

8.3 Host Time

— Data type: time_value_t

This is the representation of a time in Mach. It is a struct time_value and consists of the following members:

integer_t seconds
The number of seconds.
integer_t microseconds
The number of microseconds.

The number of microseconds should always be smaller than TIME_MICROS_MAX (100000). A time with this property is normalized. Normalized time values can be manipulated with the following macros:

— Macro: time_value_add_usec (time_value_t *val, integer_t *micros)

Add micros microseconds to val. If val is normalized and micros smaller than TIME_MICROS_MAX, val will be normalized afterwards.

— Macro: time_value_add (time_value_t *result, time_value_t *addend)

Add the values in addend to result. If both are normalized, result will be normalized afterwards.

A variable of type time_value_t can either represent a duration or a fixed point in time. In the latter case, it shall be interpreted as the number of seconds and microseconds after the epoch 1. Jan 1970.

— Function: kern_return_t host_get_time (host_t host, time_value_t *current_time)

Get the current time as seen by host. On success, the time passed since the epoch is returned in current_time.

— Function: kern_return_t host_set_time (host_priv_t host_priv, time_value_t new_time)

Set the time of host_priv to new_time.

— Function: kern_return_t host_adjust_time (host_priv_t host_priv, time_value_t new_adjustment, time_value_t *old_adjustment)

Arrange for the current time as seen by host_priv to be gradually changed by the adjustment value new_adjustment, and return the old adjustment value in old_adjustment.

For efficiency, the current time is available through a mapped-time interface.

— Data type: mapped_time_value_t

This structure defines the mapped-time interface. It has the following members:

integer_t seconds
The number of seconds.
integer_t microseconds
The number of microseconds.
integer_t check_seconds
This is a copy of the seconds value, which must be checked to protect against a race condition when reading out the two time values.

Here is an example how to read out the current time using the mapped-time interface: 

     do
       {
         secs = mtime->seconds;
         usecs = mtime->microseconds;
       }
     while (secs != mtime->check_seconds);