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>
56This field specifies the following properties of the message:
57<dl>
58  <p>
59<dt> <strong>MACH_MSGH_BITS_REMOTE_MASK</strong>
60<dd>
61Encodes <var>mach_msg_type_name_t</var> values that specify the port 
62rights in the <var>msgh_remote_port</var> field.  The value must specify 
63a send or send-once right for the destination of the message.
64     <p>
65<dt> <strong>MACH_MSGH_BITS_LOCAL_MASK</strong>
66<dd>
67Encodes <var>mach_msg_type_name_t</var> values that specify the port 
68rights in the <var>msgh_local_port</var> field.  If the value doesn't
69specify a send or send-once right for the message's reply port, it 
70must 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>
74The complex bit must be specified if the message body
75contains additional port rights or out-of-line memory regions.
76     <p>
77<dt> <strong>MACH_MSGH_BITS_REMOTE</strong>(<var>bits</var>)
78<dd>
79This macro returns the appropriate <var>mach_msg_type_name_t</var> 
80values, given a <var>msgh_bits</var> value.
81     <p>
82<dt> <strong>MACH_MSGH_BITS_LOCAL</strong>(<var>bits</var>)
83<dd>
84This macro returns the appropriate <var>mach_msg_type_name_t</var> 
85values, given a <var>msgh_bits</var> value.
86     <p>
87<dt> <strong>MACH_MSGH_BITS</strong>(<var>remote</var>, <var>local</var>)
88<dd>
89This 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>
95This 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 
97receive to the sum of 
98the message header and body sizes (in bytes).  Note that this value may 
99be different from the send size specified by the sender if the sender and 
100receiver machines have differing sizes for port names, memory
101addresses or memory range sizes.
102     <p>
103<dt> <var>msgh_remote_port</var>
104<dd>
105When sending, specifies the destination port of the message.  The field 
106must carry a legitimate send or send-once right for a port.  When
107received, this field is swapped with <var>msgh_local_port</var>.
108     <p>
109<dt> <var>msgh_local_port</var>
110<dd>
111When sending, specifies an auxiliary port right, which is
112conventionally used as a reply port by the recipient of the message.
113The field must 
114carry 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>
120Not set or read by the <strong>mach_msg</strong> call.  The conventional meaning is to 
121convey an operation or function ID.
122     <p>
123<dt> <var>msgh_descriptor_count</var>
124<dd>
125The number of descriptors of kernel processed data (port rights and
126out-of-line data).
127     <p>
128<dt> <var>msgh_trailer_type</var>
129<dd>
130An identifier of the trailer version.  Different values indicate not
131necessarily compatible trailer formats.  The current (and only) trailer format 
132is <strong>MACH_MSG_TRAILER_FORMAT_0</strong>.  There is currently only one 
133attribute defined within this trailer type: the sender's identity.
134     <p>
135<dt> <var>msgh_trailer_size</var>
136<dd>
137The length, in bytes, of the message trailer, including the trailer type 
138and length fields.
139     <p>
140<dt> <var>msgh_seqno</var>
141<dd>
142The sequence number of this message relative to the port from which it 
143is received.
144     <p>
145<dt> <var>msgh_sender</var>
146<dd>
147The security ID of the sender of the message.
148</dl>
149<h3>DESCRIPTION</h3>
150<p>
151The <strong>mach_msg_header</strong> structure defines the fixed size header of a Mach
152message.  The header is followed by a message body containing data and port
153descriptors and zero or more data bytes.
154<p>
155If the <strong>MACH_MSGH_BITS_COMPLEX</strong> flag in the <var>msgh_bits</var> field is not set, 
156then this is a simple message described by <strong>mach_msg_header_t</strong>.  
157In this case, the header is immediately followed by untyped data.
158<p>
159If 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
161containing a count followed by an array of descriptors specifying
162the disposition 
163(processing) to be performed for the out-of-line memory regions and additional 
164port rights.
165<p>
166Following the header (and any kernel processed descriptors), at natural
167alignment can be additional (un-typed) data, up to the size of the message 
168(<var>msgh_size</var>).  This extra data typically carries information
169used to decode the data stream and out-of-line data.
170<p>
171At 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
173trailer.  If the length is greater than sizeof (<strong>mach_msg_trailer_t</strong>),
174additional fields 
175follow providing kernel-generated message attributes.
176<h3>RELATED INFORMATION</h3>
177<p>
178Functions:
179<a href="mach_msg.html"><strong>mach_msg</strong></a>.
180<p>
181Data Structures:
182<a href="mach_msg_descriptor.html"><strong>mach_msg_descriptor</strong></a>.
183
184