Next: , Previous: Mach Message Call, Up: Messaging Interface


4.2.2 Message Format

A Mach message consists of a fixed size message header, a mach_msg_header_t, followed by zero or more data items. Data items are typed. Each item has a type descriptor followed by the actual data (or the address of the data, for out-of-line memory regions).

The following data types are related to Mach ports:

— Data type: mach_port_t

The mach_port_t data type is an unsigned integer type which represents a port name in the task's port name space. In GNU Mach, this is an unsigned int.

The following data types are related to Mach messages:

— Data type: mach_msg_bits_t

The mach_msg_bits_t data type is an unsigned int used to store various flags for a message.

— Data type: mach_msg_size_t

The mach_msg_size_t data type is an unsigned int used to store the size of a message.

— Data type: mach_msg_id_t

The mach_msg_id_t data type is an integer_t typically used to convey a function or operation id for the receiver.

— Data type: mach_msg_header_t

This structure is the start of every message in the Mach IPC system. It has the following members:

mach_msg_bits_t msgh_bits
The msgh_bits field has the following bits defined, all other bits should be zero:
MACH_MSGH_BITS_REMOTE_MASK
MACH_MSGH_BITS_LOCAL_MASK
The remote and local bits encode mach_msg_type_name_t values that specify the port rights in the msgh_remote_port and msgh_local_port fields. The remote value must specify a send or send-once right for the destination of the message. If the local value doesn't specify a send or send-once right for the message's reply port, it must be zero and msgh_local_port must be MACH_PORT_NULL.
MACH_MSGH_BITS_COMPLEX
The complex bit must be specified if the message body contains port rights or out-of-line memory regions. If it is not specified, then the message body carries no port rights or memory, no matter what the type descriptors may seem to indicate.

MACH_MSGH_BITS_REMOTE and MACH_MSGH_BITS_LOCAL macros return the appropriate mach_msg_type_name_t values, given a msgh_bits value. The MACH_MSGH_BITS macro constructs a value for msgh_bits, given two mach_msg_type_name_t values.

mach_msg_size_t msgh_size
The msgh_size field in the header of a received message contains the message's size. The message size, a byte quantity, includes the message header, type descriptors, and in-line data. For out-of-line memory regions, the message size includes the size of the in-line address, not the size of the actual memory region. There are no arbitrary limits on the size of a Mach message, the number of data items in a message, or the size of the data items.
mach_port_t msgh_remote_port
The msgh_remote_port field specifies the destination port of the message. The field must carry a legitimate send or send-once right for a port.
mach_port_t msgh_local_port
The msgh_local_port field specifies an auxiliary port right, which is conventionally used as a reply port by the recipient of the message. The field must carry a send right, a send-once right, MACH_PORT_NULL, or MACH_PORT_DEAD.
mach_port_seqno_t msgh_seqno
The msgh_seqno field provides a sequence number for the message. It is only valid in received messages; its value in sent messages is overwritten.
mach_msg_id_t msgh_id
The mach_msg call doesn't use the msgh_id field, but it conventionally conveys an operation or function id.

— Macro: mach_msg_bits_t MACH_MSGH_BITS (mach_msg_type_name_t remote, mach_msg_type_name_t local)

This macro composes two mach_msg_type_name_t values that specify the port rights in the msgh_remote_port and msgh_local_port fields of a mach_msg call into an appropriate mach_msg_bits_t value.

— Macro: mach_msg_type_name_t MACH_MSGH_BITS_REMOTE (mach_msg_bits_t bits)

This macro extracts the mach_msg_type_name_t value for the remote port right in a mach_msg_bits_t value.

— Macro: mach_msg_type_name_t MACH_MSGH_BITS_LOCAL (mach_msg_bits_t bits)

This macro extracts the mach_msg_type_name_t value for the local port right in a mach_msg_bits_t value.

— Macro: mach_msg_bits_t MACH_MSGH_BITS_PORTS (mach_msg_bits_t bits)

This macro extracts the mach_msg_bits_t component consisting of the mach_msg_type_name_t values for the remote and local port right in a mach_msg_bits_t value.

— Macro: mach_msg_bits_t MACH_MSGH_BITS_OTHER (mach_msg_bits_t bits)

This macro extracts the mach_msg_bits_t component consisting of everything except the mach_msg_type_name_t values for the remote and local port right in a mach_msg_bits_t value.

Each data item has a type descriptor, a mach_msg_type_t or a mach_msg_type_long_t. The mach_msg_type_long_t type descriptor allows larger values for some fields. The msgtl_header field in the long descriptor is only used for its inline, longform, and deallocate bits.

— Data type: mach_msg_type_name_t

This is an unsigned int and can be used to hold the msgt_name component of the mach_msg_type_t and mach_msg_type_long_t structure.

— Data type: mach_msg_type_size_t

This is an unsigned int and can be used to hold the msgt_size component of the mach_msg_type_t and mach_msg_type_long_t structure.

— Data type: mach_msg_type_number_t

This is an natural_t and can be used to hold the msgt_number component of the mach_msg_type_t and mach_msg_type_long_t structure.

— Data type: mach_msg_type_t

This structure has the following members:

unsigned int msgt_name : 8
The msgt_name field specifies the data's type. The following types are predefined:
MACH_MSG_TYPE_UNSTRUCTURED
MACH_MSG_TYPE_BIT
MACH_MSG_TYPE_BOOLEAN
MACH_MSG_TYPE_INTEGER_16
MACH_MSG_TYPE_INTEGER_32
MACH_MSG_TYPE_CHAR
MACH_MSG_TYPE_BYTE
MACH_MSG_TYPE_INTEGER_8
MACH_MSG_TYPE_REAL
MACH_MSG_TYPE_STRING
MACH_MSG_TYPE_STRING_C
MACH_MSG_TYPE_PORT_NAME

The following predefined types specify port rights, and receive special treatment. The next section discusses these types in detail. The type MACH_MSG_TYPE_PORT_NAME describes port right names, when no rights are being transferred, but just names. For this purpose, it should be used in preference to MACH_MSG_TYPE_INTEGER_32.

MACH_MSG_TYPE_MOVE_RECEIVE
MACH_MSG_TYPE_MOVE_SEND
MACH_MSG_TYPE_MOVE_SEND_ONCE
MACH_MSG_TYPE_COPY_SEND
MACH_MSG_TYPE_MAKE_SEND
MACH_MSG_TYPE_MAKE_SEND_ONCE

msgt_size : 8
The msgt_size field specifies the size of each datum, in bits. For example, the msgt_size of MACH_MSG_TYPE_INTEGER_32 data is 32.
msgt_number : 12
The msgt_number field specifies how many data elements comprise the data item. Zero is a legitimate number.

The total length specified by a type descriptor is (msgt_size * msgt_number), rounded up to an integral number of bytes. In-line data is then padded to an integral number of long-words. This ensures that type descriptors always start on long-word boundaries. It implies that message sizes are always an integral multiple of a long-word's size.

msgt_inline : 1
The msgt_inline bit specifies, when FALSE, that the data actually resides in an out-of-line region. The address of the memory region (a vm_offset_t or vm_address_t) follows the type descriptor in the message body. The msgt_name, msgt_size, and msgt_number fields describe the memory region, not the address.
msgt_longform : 1
The msgt_longform bit specifies, when TRUE, that this type descriptor is a mach_msg_type_long_t instead of a mach_msg_type_t. The msgt_name, msgt_size, and msgt_number fields should be zero. Instead, mach_msg uses the following msgtl_name, msgtl_size, and msgtl_number fields.
msgt_deallocate : 1
The msgt_deallocate bit is used with out-of-line regions. When TRUE, it specifies that the memory region should be deallocated from the sender's address space (as if with vm_deallocate) when the message is sent.
msgt_unused : 1
The msgt_unused bit should be zero.

— Macro: boolean_t MACH_MSG_TYPE_PORT_ANY (mach_msg_type_name_t type)

This macro returns TRUE if the given type name specifies a port type, otherwise it returns FALSE.

— Macro: boolean_t MACH_MSG_TYPE_PORT_ANY_SEND (mach_msg_type_name_t type)

This macro returns TRUE if the given type name specifies a port type with a send or send-once right, otherwise it returns FALSE.

— Macro: boolean_t MACH_MSG_TYPE_PORT_ANY_RIGHT (mach_msg_type_name_t type)

This macro returns TRUE if the given type name specifies a port right type which is moved, otherwise it returns FALSE.

— Data type: mach_msg_type_long_t

This structure has the following members:

mach_msg_type_t msgtl_header
Same meaning as msgt_header.
unsigned short msgtl_name
Same meaning as msgt_name.
unsigned short msgtl_size
Same meaning as msgt_size.
unsigned int msgtl_number
Same meaning as msgt_number.