mach_msg_header

Structure - Specifies the content of an IPC message header.

SYNOPSIS

typedef struct
{
       mach_msg_bits_t                     msgh_bits;
       mach_msg_size_t                     msgh_size;
       mach_port_t                  msgh_remote_port;
       mach_port_t                   msgh_local_port;
       mach_msg_size_t                 msgh_reserved;
       mach_msg_id_t                         msgh_id;
} mach_msg_header_t;

typedef struct
{
       mach_msg_size_t         msgh_descriptor_count;
} mach_msg_body_t;

typedef struct
{
       mach_msg_trailer_type_t     msgh_trailer_type;
       mach_msg_trailer_size_t     msgh_trailer_size;
} mach_msg_trailer_t;

typedef struct
{
       mach_msg_trailer_type_t     msgh_trailer_type;
       mach_msg_trailer_size_t     msgh_trailer_size;
       mach_port_seqno_t                  msgh_seqno;
} mach_msg_seqno_trailer_t;

typedef struct
{
       mach_msg_trailer_type_t    msgh_trailer_type;
       mach_msg_trailer_size_t    msgh_trailer_size;
       mach_port_seqno_t                 msgh_seqno;
       security_token_t                 msgh_sender;
} mach_msg_security_trailer_t;

typedef struct
{
       mach_msg_trailer_type_t    msgh_trailer_type;
       mach_msg_trailer_size_t    msgh_trailer_size;
       mach_port_seqno_t                 msgh_seqno;
       security_token_t                  msgh_sender;
       unsigned int                 dipc_sender_kmsg;
} mach_msg_dipc_trailer_t;

FIELDS

msgh_bits

This field specifies the following properties of the message:

MACH_MSGH_BITS_REMOTE_MASK

Encodes mach_msg_type_name_t values that specify the port rights in the msgh_remote_port field. The value must specify a send or send-once right for the destination of the message.

MACH_MSGH_BITS_LOCAL_MASK

Encodes mach_msg_type_name_t values that specify the port rights in the msgh_local_port field. If the 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 additional port rights or out-of-line memory regions.

MACH_MSGH_BITS_REMOTE(bits)

This macro returns the appropriate mach_msg_type_name_t values, given a msgh_bits value.

MACH_MSGH_BITS_LOCAL(bits)

This macro returns the appropriate mach_msg_type_name_t values, given a msgh_bits value.

MACH_MSGH_BITS(remote, local)

This macro constructs a value for msgh_bits, given two mach_msg_type_name_t values.

msgh_size

This field is ignored on send (the size to send is specified by the send_size parameter to mach_msg); the field is set on receive to the sum of the message header and body sizes (in bytes). Note that this value may be different from the send size specified by the sender if the sender and receiver machines have differing sizes for port names, memory addresses or memory range sizes.

msgh_remote_port

When sending, specifies the destination port of the message. The field must carry a legitimate send or send-once right for a port. When received, this field is swapped with msgh_local_port.

msgh_local_port

When sending, 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. When received, this field is swapped with msgh_remote_port.

msgh_id

Not set or read by the mach_msg call. The conventional meaning is to convey an operation or function ID.

msgh_descriptor_count

The number of descriptors of kernel processed data (port rights and out-of-line data).

msgh_trailer_type

An identifier of the trailer version. Different values indicate not necessarily compatible trailer formats. The current (and only) trailer format is MACH_MSG_TRAILER_FORMAT_0. There is currently only one attribute defined within this trailer type: the sender's identity.

msgh_trailer_size

The length, in bytes, of the message trailer, including the trailer type and length fields.

msgh_seqno

The sequence number of this message relative to the port from which it is received.

msgh_sender

The security ID of the sender of the message.

DESCRIPTION

The mach_msg_header structure defines the fixed size header of a Mach message. The header is followed by a message body containing data and port descriptors and zero or more data bytes.

If the MACH_MSGH_BITS_COMPLEX flag in the msgh_bits field is not set, then this is a simple message described by mach_msg_header_t. In this case, the header is immediately followed by untyped data.

If the complex flag is set, then this is a "complex" message consisting of a mach_msg_header_t structure followed by a mach_msg_body_t structure containing a count followed by an array of descriptors specifying the disposition (processing) to be performed for the out-of-line memory regions and additional port rights.

Following the header (and any kernel processed descriptors), at natural alignment can be additional (un-typed) data, up to the size of the message (msgh_size). This extra data typically carries information used to decode the data stream and out-of-line data.

At the next natural boundary following the message data is the message trailer (mach_msg_trailer_t). This structure indicates the type and length of the trailer. If the length is greater than sizeof (mach_msg_trailer_t), additional fields follow providing kernel-generated message attributes.

RELATED INFORMATION

Functions: mach_msg.

Data Structures: mach_msg_descriptor.