Go to the first, previous, next, last section, table of contents.
This section describes the Mach interface to a host executing a Mach kernel. The intrface allows it to query statistics about a host and control its behaviour.
A host is represented by two ports, a name port host of type
host_t used to query information about the host accessible to
everyone and a control port host_priv of type host_priv_t
used to manipulate it. For example, you can query the current time over
the name port, but to change the time you need to send a message to the
host control port.
A send right to the name port of the host a task is running on is
available with the mach_host_self system trap. A send right to
the host control port is inserted into the first task at bootstrap.
Everything described in this section is declared in the header file `mach.h'.
mach_host_self system call returns the calling thread's host
port. It has an effect equivalent to receiving a send right for the
host port. mach_host_self returns the name of the send right.
In particular, successive calls will increase the calling task's
user-reference count for the send right.
As a special exception, the kernel will happily overrun the user reference count of the host name port, so that this function can not fail for that reason. Because of this, the user should not deallocate the port right if an overrun might have happened. Otherwise the reference count could drop to zero and the send right be destroyed while the user still expects to be able to use it. As the kernel does not make use of the number of extant send rights anyway, this is safe to do (the host port itself is never destroyed).
The function returns MACH_PORT_NULL if a resource shortage
prevented the reception of the send right.
This function is also available in `mach/mach_traps.h'.
host_info function returns various information about
host. host_info is an array of integers that is supplied by
the caller, and filled with specified information. host_infoCnt
is supplied as the maximum number of integers in host_info. On
return, it contains the actual number of integers in host_info.
The type of information returned is defined by flavor, which can be one of the following:
HOST_BASIC_INFO
host_basic_info_t. This includes the number of processors, their
type, and the amount of memory installed in the system. The number of
integers returned is HOST_BASIC_INFO_COUNT.
HOST_PROCESSOR_SLOTS
max_cpus, as
returned by the HOT_BASIC_INFO flavor of host_info.
HOST_SCHED_INFO
host_sched_info_t. The number of integers returned is
HOST_SCHED_INFO_COUNT.
The function returns KERN_SUCCESS if the call succeeded and
KERN_INVALID_ARGUMENT if host is not a host or flavor
is not recognized. The function returns MIG_ARRAY_TOO_LARGE if
the returned info array is too large for host_info. In this case,
host_info is filled as much as possible and host_infoCnt is
set to the number of elements that would be returned if there were
enough room.
host_info function and provides basic information about the host.
You can cast a variable of type host_info_t to a pointer of this
type if you provided it as the host_info parameter for the
HOST_BASIC_INFO flavor of host_info. It has the following
members:
int max_cpus
int avail_cpus
vm_size_t memory_size
cpu_type_t cpu_type
cpu_subtype_t cpu_subtype
struct host_basic_info.
host_info function and provides information of interest to
schedulers. You can cast a variable of type host_info_t to a
pointer of this type if you provided it as the host_info parameter
for the HOST_SCHED_INFO flavor of host_info. It has the
following members:
int min_timeout
int min_quantum
struct host_sched_info.
host_kernel_version function returns the version string
compiled into the kernel executing on host at the time it was
built in the character string version. This string describes the
version of the kernel. The constant KERNEL_VERSION_MAX should be
used to dimension storage for the returned string if the
kernel_version_t declaration is not used.
If the version string compiled into the kernel is longer than KERNEL_VERSION_MAX, the result is truncated and not necessarily null-terminated.
If host is not a valid send right to a host port, the function
returns KERN_INVALID_ARGUMENT. If version points to
inaccessible memory, it returns KERN_INVALID_ADDRESS, and
KERN_SUCCESS otherwise.
host_get_boot_info function returns the boot-time information
string supplied by the operator to the kernel executing on
host_priv in the character string boot_info. The constant
KERNEL_BOOT_INFO_MAX should be used to dimension storage for the
returned string if the kernel_boot_info_t declaration is not
used.
If the boot-time information string supplied by the operator is longer than KERNEL_BOOT_INFO_MAX, the result is truncated and not necessarily null-terminated.
struct
time_value and consists of the following members:
integer_t seconds
integer_t 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:
TIME_MICROS_MAX, val 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.
For efficiency, the current time is available through a mapped-time interface.
integer_t seconds
integer_t microseconds
integer_t check_seconds
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);
RB_HALT
RB_DEBUGGER
If successful, the function might not return.
Go to the first, previous, next, last section, table of contents.