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_t msgh_protected_payload

The msgh_protected_payload field carries a payload that is set by the kernel during message delivery. The payload is an opaque identifier that can be used by the receiver to lookup the associated data structure.

It is only valid in received messages. See Message Receive for further information.

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

MACH_MSG_TYPE_PROTECTED_PAYLOAD

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

The type MACH_MSG_TYPE_PROTECTED_PAYLOAD is used by the kernel to indicate that a delivered message carries a payload in the msgh_protected_payload field. See Message Receive for more information.

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.