osfmk/man/mach_msg_header.html

   1 <h2>mach_msg_header</h2>
   2 <hr>
   3 <p>
   4 <strong>Structure</strong> - Specifies the content of an IPC message header.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>typedef struct</strong>
   8 <strong>{</strong>
   9        <strong>mach_msg_bits_t </strong>                    <var>msgh_bits</var><strong>;</strong>
  10        <strong>mach_msg_size_t</strong>                     <var>msgh_size</var><strong>;</strong>
  11        <strong>mach_port_t</strong>                  <var>msgh_remote_port</var><strong>;</strong>
  12        <strong>mach_port_t</strong>                   <var>msgh_local_port</var><strong>;</strong>
  13        <strong>mach_msg_size_t</strong>                 <var>msgh_reserved</var><strong>;</strong>
  14        <strong>mach_msg_id_t</strong>                         <var>msgh_id</var><strong>;</strong>
  15 <strong>} mach_msg_header_t;</strong>
  16
  17 <strong>typedef struct</strong>
  18 <strong>{</strong>
  19        <strong>mach_msg_size_t</strong>         <var>msgh_descriptor_count</var><strong>;</strong>
  20 <strong>} mach_msg_body_t;</strong>
  21
  22 <strong>typedef struct</strong>
  23 <strong>{</strong>
  24        <strong>mach_msg_trailer_type_t</strong>     <var>msgh_trailer_type</var><strong>;</strong>
  25        <strong>mach_msg_trailer_size_t</strong>     <var>msgh_trailer_size</var><strong>;</strong>
  26 <strong>} mach_msg_trailer_t;</strong>
  27
  28 <strong>typedef struct</strong>
  29 <strong>{</strong>
  30        <strong>mach_msg_trailer_type_t</strong>     <var>msgh_trailer_type</var><strong>;</strong>
  31        <strong>mach_msg_trailer_size_t</strong>     <var>msgh_trailer_size</var><strong>;</strong>
  32        <strong>mach_port_seqno_t</strong>                  <var>msgh_seqno</var><strong>;</strong>
  33 <strong>} mach_msg_seqno_trailer_t;</strong>
  34
  35 <strong>typedef struct</strong>
  36 <strong>{</strong>
  37        <strong>mach_msg_trailer_type_t</strong>    <var>msgh_trailer_type</var><strong>;</strong>
  38        <strong>mach_msg_trailer_size_t</strong>    <var>msgh_trailer_size</var><strong>;</strong>
  39        <strong>mach_port_seqno_t</strong>                 <var>msgh_seqno</var><strong>;</strong>
  40        <strong>security_token_t</strong>                 <var>msgh_sender</var><strong>;</strong>
  41 <strong>} mach_msg_security_trailer_t;</strong>
  42
  43 <strong>typedef struct</strong>
  44 <strong>{</strong>
  45        <strong>mach_msg_trailer_type_t</strong>    <var>msgh_trailer_type</var><strong>;</strong>
  46        <strong>mach_msg_trailer_size_t</strong>    <var>msgh_trailer_size</var><strong>;</strong>
  47        <strong>mach_port_seqno_t</strong>                 <var>msgh_seqno</var><strong>;</strong>
  48        <strong>security_token_t</strong>                  <var>msgh_sender</var><strong>;</strong>
  49        <strong>unsigned int</strong>                 <var>dipc_sender_kmsg</var><strong>;</strong>
  50 <strong>} mach_msg_dipc_trailer_t;</strong>
  51 </pre>
  52 <h3>FIELDS</h3>
  53 <dl>
  54 <dt> <var>msgh_bits</var>
  55 <dd>
  56 This field specifies the following properties of the message:
  57 <dl>
  58   <p>
  59 <dt> <strong>MACH_MSGH_BITS_REMOTE_MASK</strong>
  60 <dd>
  61 Encodes <var>mach_msg_type_name_t</var> values that specify the port
  62 rights in the <var>msgh_remote_port</var> field.  The value must specify
  63 a send or send-once right for the destination of the message.
  64      <p>
  65 <dt> <strong>MACH_MSGH_BITS_LOCAL_MASK</strong>
  66 <dd>
  67 Encodes <var>mach_msg_type_name_t</var> values that specify the port
  68 rights in the <var>msgh_local_port</var> field.  If the value doesn't
  69 specify a send or send-once right for the message's reply port, it
  70 must be zero and <var>msgh_local_port</var> must be <strong>MACH_PORT_NULL</strong>.
  71      <p>
  72 <dt> <strong>MACH_MSGH_BITS_COMPLEX</strong>
  73 <dd>
  74 The complex bit must be specified if the message body
  75 contains additional port rights or out-of-line memory regions.
  76      <p>
  77 <dt> <strong>MACH_MSGH_BITS_REMOTE</strong>(<var>bits</var>)
  78 <dd>
  79 This macro returns the appropriate <var>mach_msg_type_name_t</var>
  80 values, given a <var>msgh_bits</var> value.
  81      <p>
  82 <dt> <strong>MACH_MSGH_BITS_LOCAL</strong>(<var>bits</var>)
  83 <dd>
  84 This macro returns the appropriate <var>mach_msg_type_name_t</var>
  85 values, given a <var>msgh_bits</var> value.
  86      <p>
  87 <dt> <strong>MACH_MSGH_BITS</strong>(<var>remote</var>, <var>local</var>)
  88 <dd>
  89 This macro constructs a value for <var>msgh_bits</var>, given two
  90 <var>mach_msg_type_name_t</var> values.
  91 </dl>
  92 <p>
  93 <dt> <var>msgh_size</var>
  94 <dd>
  95 This field is ignored on send (the size to send is specified by the
  96 <var>send_size</var> parameter to <strong>mach_msg</strong>); the field is set on
  97 receive to the sum of
  98 the message header and body sizes (in bytes).  Note that this value may
  99 be different from the send size specified by the sender if the sender and
 100 receiver machines have differing sizes for port names, memory
 101 addresses or memory range sizes.
 102      <p>
 103 <dt> <var>msgh_remote_port</var>
 104 <dd>
 105 When sending, specifies the destination port of the message.  The field
 106 must carry a legitimate send or send-once right for a port.  When
 107 received, this field is swapped with <var>msgh_local_port</var>.
 108      <p>
 109 <dt> <var>msgh_local_port</var>
 110 <dd>
 111 When sending, specifies an auxiliary port right, which is
 112 conventionally used as a reply port by the recipient of the message.
 113 The field must
 114 carry a send right, a send-once right, <strong>MACH_PORT_NULL</strong>, or
 115 <strong>MACH_PORT_DEAD</strong>.  When received, this field is swapped with
 116 <var>msgh_remote_port</var>.
 117      <p>
 118 <dt> <var>msgh_id</var>
 119 <dd>
 120 Not set or read by the <strong>mach_msg</strong> call.  The conventional meaning is to
 121 convey an operation or function ID.
 122      <p>
 123 <dt> <var>msgh_descriptor_count</var>
 124 <dd>
 125 The number of descriptors of kernel processed data (port rights and
 126 out-of-line data).
 127      <p>
 128 <dt> <var>msgh_trailer_type</var>
 129 <dd>
 130 An identifier of the trailer version.  Different values indicate not
 131 necessarily compatible trailer formats.  The current (and only) trailer format
 132 is <strong>MACH_MSG_TRAILER_FORMAT_0</strong>.  There is currently only one
 133 attribute defined within this trailer type: the sender's identity.
 134      <p>
 135 <dt> <var>msgh_trailer_size</var>
 136 <dd>
 137 The length, in bytes, of the message trailer, including the trailer type
 138 and length fields.
 139      <p>
 140 <dt> <var>msgh_seqno</var>
 141 <dd>
 142 The sequence number of this message relative to the port from which it
 143 is received.
 144      <p>
 145 <dt> <var>msgh_sender</var>
 146 <dd>
 147 The security ID of the sender of the message.
 148 </dl>
 149 <h3>DESCRIPTION</h3>
 150 <p>
 151 The <strong>mach_msg_header</strong> structure defines the fixed size header of a Mach
 152 message.  The header is followed by a message body containing data and port
 153 descriptors and zero or more data bytes.
 154 <p>
 155 If the <strong>MACH_MSGH_BITS_COMPLEX</strong> flag in the <var>msgh_bits</var> field is not set,
 156 then this is a simple message described by <strong>mach_msg_header_t</strong>.
 157 In this case, the header is immediately followed by untyped data.
 158 <p>
 159 If the complex flag is set, then this is a "complex" message consisting of a
 160 <strong>mach_msg_header_t</strong> structure followed by a <strong>mach_msg_body_t</strong> structure
 161 containing a count followed by an array of descriptors specifying
 162 the disposition
 163 (processing) to be performed for the out-of-line memory regions and additional
 164 port rights.
 165 <p>
 166 Following the header (and any kernel processed descriptors), at natural
 167 alignment can be additional (un-typed) data, up to the size of the message
 168 (<var>msgh_size</var>).  This extra data typically carries information
 169 used to decode the data stream and out-of-line data.
 170 <p>
 171 At the next natural boundary following the message data is the message trailer
 172 (<strong>mach_msg_trailer_t</strong>).  This structure indicates the type and length of the
 173 trailer.  If the length is greater than sizeof (<strong>mach_msg_trailer_t</strong>),
 174 additional fields
 175 follow providing kernel-generated message attributes.
 176 <h3>RELATED INFORMATION</h3>
 177 <p>
 178 Functions:
 179 <a href="mach_msg.html"><strong>mach_msg</strong></a>.
 180 <p>
 181 Data Structures:
 182 <a href="mach_msg_descriptor.html"><strong>mach_msg_descriptor</strong></a>.
 183