| 9bccf70c |
1 | <h2>mach_msg_header</h2>\r<hr>\r<p>\r<strong>Structure</strong> - Specifies the content of an IPC message header.\r<h3>SYNOPSIS</h3>\r<pre>\r<strong>typedef struct</strong>\r<strong>{</strong>\r <strong>mach_msg_bits_t </strong> <var>msgh_bits</var><strong>;</strong>\r <strong>mach_msg_size_t</strong> <var>msgh_size</var><strong>;</strong>\r <strong>mach_port_t</strong> <var>msgh_remote_port</var><strong>;</strong>\r <strong>mach_port_t</strong> <var>msgh_local_port</var><strong>;</strong>\r <strong>mach_msg_size_t</strong> <var>msgh_reserved</var><strong>;</strong>\r <strong>mach_msg_id_t</strong> <var>msgh_id</var><strong>;</strong>\r<strong>} mach_msg_header_t;</strong>\r\r<strong>typedef struct</strong>\r<strong>{</strong>\r <strong>mach_msg_size_t</strong> <var>msgh_descriptor_count</var><strong>;</strong>\r<strong>} mach_msg_body_t;</strong>\r\r<strong>typedef struct</strong>\r<strong>{</strong>\r <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong>\r <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong>\r<strong>} mach_msg_trailer_t;</strong>\r\r<strong>typedef struct</strong>\r<strong>{</strong>\r <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong>\r <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong>\r <strong>mach_port_seqno_t</strong> <var>msgh_seqno</var><strong>;</strong>\r<strong>} mach_msg_seqno_trailer_t;</strong>\r\r<strong>typedef struct</strong>\r<strong>{</strong>\r <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong>\r <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong>\r <strong>mach_port_seqno_t</strong> <var>msgh_seqno</var><strong>;</strong>\r <strong>security_token_t</strong> <var>msgh_sender</var><strong>;</strong>\r<strong>} mach_msg_security_trailer_t;</strong>\r\r<strong>typedef struct</strong>\r<strong>{</strong>\r <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong>\r <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong>\r <strong>mach_port_seqno_t</strong> <var>msgh_seqno</var><strong>;</strong>\r <strong>security_token_t</strong> <var>msgh_sender</var><strong>;</strong>\r <strong>unsigned int</strong> <var>dipc_sender_kmsg</var><strong>;</strong>\r<strong>} mach_msg_dipc_trailer_t;</strong>\r</pre>\r<h3>FIELDS</h3>\r<dl>\r<dt> <var>msgh_bits</var>\r<dd>\rThis field specifies the following properties of the message:\r<dl>\r <p>\r<dt> <strong>MACH_MSGH_BITS_REMOTE_MASK</strong>\r<dd>\rEncodes <var>mach_msg_type_name_t</var> values that specify the port \rrights in the <var>msgh_remote_port</var> field. The value must specify \ra send or send-once right for the destination of the message.\r <p>\r<dt> <strong>MACH_MSGH_BITS_LOCAL_MASK</strong>\r<dd>\rEncodes <var>mach_msg_type_name_t</var> values that specify the port \rrights in the <var>msgh_local_port</var> field. If the value doesn't\rspecify a send or send-once right for the message's reply port, it \rmust be zero and <var>msgh_local_port</var> must be <strong>MACH_PORT_NULL</strong>.\r <p>\r<dt> <strong>MACH_MSGH_BITS_COMPLEX</strong>\r<dd>\rThe complex bit must be specified if the message body\rcontains additional port rights or out-of-line memory regions.\r <p>\r<dt> <strong>MACH_MSGH_BITS_REMOTE</strong>(<var>bits</var>)\r<dd>\rThis macro returns the appropriate <var>mach_msg_type_name_t</var> \rvalues, given a <var>msgh_bits</var> value.\r <p>\r<dt> <strong>MACH_MSGH_BITS_LOCAL</strong>(<var>bits</var>)\r<dd>\rThis macro returns the appropriate <var>mach_msg_type_name_t</var> \rvalues, given a <var>msgh_bits</var> value.\r <p>\r<dt> <strong>MACH_MSGH_BITS</strong>(<var>remote</var>, <var>local</var>)\r<dd>\rThis macro constructs a value for <var>msgh_bits</var>, given two \r<var>mach_msg_type_name_t</var> values. \r</dl>\r<p>\r<dt> <var>msgh_size</var>\r<dd>\rThis field is ignored on send (the size to send is specified by the\r<var>send_size</var> parameter to <strong>mach_msg</strong>); the field is set on \rreceive to the sum of \rthe message header and body sizes (in bytes). Note that this value may \rbe different from the send size specified by the sender if the sender and \rreceiver machines have differing sizes for port names, memory\raddresses or memory range sizes.\r <p>\r<dt> <var>msgh_remote_port</var>\r<dd>\rWhen sending, specifies the destination port of the message. The field \rmust carry a legitimate send or send-once right for a port. When\rreceived, this field is swapped with <var>msgh_local_port</var>.\r <p>\r<dt> <var>msgh_local_port</var>\r<dd>\rWhen sending, specifies an auxiliary port right, which is\rconventionally used as a reply port by the recipient of the message.\rThe field must \rcarry a send right, a send-once right, <strong>MACH_PORT_NULL</strong>, or \r<strong>MACH_PORT_DEAD</strong>. When received, this field is swapped with\r<var>msgh_remote_port</var>.\r <p>\r<dt> <var>msgh_id</var>\r<dd>\rNot set or read by the <strong>mach_msg</strong> call. The conventional meaning is to \rconvey an operation or function ID.\r <p>\r<dt> <var>msgh_descriptor_count</var>\r<dd>\rThe number of descriptors of kernel processed data (port rights and\rout-of-line data).\r <p>\r<dt> <var>msgh_trailer_type</var>\r<dd>\rAn identifier of the trailer version. Different values indicate not\rnecessarily compatible trailer formats. The current (and only) trailer format \ris <strong>MACH_MSG_TRAILER_FORMAT_0</strong>. There is currently only one \rattribute defined within this trailer type: the sender's identity.\r <p>\r<dt> <var>msgh_trailer_size</var>\r<dd>\rThe length, in bytes, of the message trailer, including the trailer type \rand length fields.\r <p>\r<dt> <var>msgh_seqno</var>\r<dd>\rThe sequence number of this message relative to the port from which it \ris received.\r <p>\r<dt> <var>msgh_sender</var>\r<dd>\rThe security ID of the sender of the message.\r</dl>\r<h3>DESCRIPTION</h3>\r<p>\rThe <strong>mach_msg_header</strong> structure defines the fixed size header of a Mach\rmessage. The header is followed by a message body containing data and port\rdescriptors and zero or more data bytes.\r<p>\rIf the <strong>MACH_MSGH_BITS_COMPLEX</strong> flag in the <var>msgh_bits</var> field is not set, \rthen this is a simple message described by <strong>mach_msg_header_t</strong>. \rIn this case, the header is immediately followed by untyped data.\r<p>\rIf the complex flag is set, then this is a "complex" message consisting of a \r<strong>mach_msg_header_t</strong> structure followed by a <strong>mach_msg_body_t</strong> structure\rcontaining a count followed by an array of descriptors specifying\rthe disposition \r(processing) to be performed for the out-of-line memory regions and additional \rport rights.\r<p>\rFollowing the header (and any kernel processed descriptors), at natural\ralignment can be additional (un-typed) data, up to the size of the message \r(<var>msgh_size</var>). This extra data typically carries information\rused to decode the data stream and out-of-line data.\r<p>\rAt the next natural boundary following the message data is the message trailer \r(<strong>mach_msg_trailer_t</strong>). This structure indicates the type and length of the\rtrailer. If the length is greater than sizeof (<strong>mach_msg_trailer_t</strong>),\radditional fields \rfollow providing kernel-generated message attributes.\r<h3>RELATED INFORMATION</h3>\r<p>\rFunctions:\r<a href="mach_msg.html"><strong>mach_msg</strong></a>.\r<p>\rData Structures:\r<a href="mach_msg_descriptor.html"><strong>mach_msg_descriptor</strong></a>.\r\r |
projects / apple / xnu.git / blame