| 1 | <h2>mach_msg</h2> |
| 2 | <hr> |
| 3 | <p> |
| 4 | <strong>System Trap</strong> / <strong>Function</strong> - Send and/or receive a message from the target port. |
| 5 | <h3>SYNOPSIS</h3> |
| 6 | <pre> |
| 7 | <strong>mach_msg_return_t mach_msg</strong> |
| 8 | <strong>(mach_msg_header_t</strong> <var>msg</var>, |
| 9 | <strong>mach_msg_option_t</strong> <var>option</var>, |
| 10 | <strong>mach_msg_size_t</strong> <var>send_size</var>, |
| 11 | <strong>mach_msg_size_t</strong> <var>receive_limit</var>, |
| 12 | <strong>mach_port_t</strong> <var>receive_name</var>, |
| 13 | <strong>mach_msg_timeout_t</strong> <var>timeout</var>, |
| 14 | <strong>mach_port_t</strong> <var>notify</var><strong>);</strong> |
| 15 | |
| 16 | <strong>mach_msg_return_t mach_msg_overwrite</strong> |
| 17 | <strong>(mach_msg_header_t*</strong> <var>send_msg</var>, |
| 18 | <strong>mach_msg_option_t</strong> <var>option</var>, |
| 19 | <strong>mach_msg_size_t</strong> <var>send_size</var>, |
| 20 | <strong>mach_msg_size_t</strong> <var>receive_limit</var>, |
| 21 | <strong>mach_port_t</strong> <var>receive_name</var>, |
| 22 | <strong>mach_msg_timeout_t</strong> <var>timeout</var>, |
| 23 | <strong>mach_port_t</strong> <var>notify</var>, |
| 24 | <strong>mach_msg_header_t</strong> <var>*receive_msg</var>, |
| 25 | <strong>mach_msg_size_t</strong> <var>receive_msg_size</var><strong>);</strong> |
| 26 | </pre> |
| 27 | <h3>PARAMETERS</h3> |
| 28 | <dl> |
| 29 | <p> |
| 30 | <dt> <var>msg</var> |
| 31 | <dd> |
| 32 | [pointer to in/out structure containing random and reply rights] A |
| 33 | message buffer used by <strong>mach_msg</strong> both for send and receive. This must |
| 34 | be naturally aligned. |
| 35 | <p> |
| 36 | <dt> <var>send_msg</var> |
| 37 | <dd> |
| 38 | [pointer to in structure containing random and reply rights] The mes- |
| 39 | sage buffer to be sent. This must be naturally aligned. |
| 40 | <p> |
| 41 | <dt> <var>option</var> |
| 42 | <dd> |
| 43 | [in scalar] Message options are bit values, combined with bitwise-or. |
| 44 | One or both of MACH_SEND_MSG and MACH_RCV_MSG should be used. Other |
| 45 | options act as modifiers. |
| 46 | <p> |
| 47 | <dt> <var>send_size</var> |
| 48 | <dd> |
| 49 | [in scalar] When sending a message, specifies the size of the message |
| 50 | buffer to be sent (the size of the header and body) in |
| 51 | bytes. Otherwise zero should be supplied. |
| 52 | <p> |
| 53 | <dt> <var>receive_limit</var> |
| 54 | <dd> |
| 55 | [in scalar] When receiving a message, specifies the maximum size of |
| 56 | the msg or receive_msg buffer in bytes. Otherwise zero should be sup- |
| 57 | plied. |
| 58 | <p> |
| 59 | <dt> <var>receive_name</var> |
| 60 | <dd> |
| 61 | [in random right] When receiving a message, specifies the port or port |
| 62 | set. Otherwise MACH_PORT_NULL should be supplied. |
| 63 | <p> |
| 64 | <dt> <var>timeout</var> |
| 65 | <dd> |
| 66 | [in scalar] When using the MACH_SEND_TIMEOUT and MACH_RCV_TIMEOUT |
| 67 | options, specifies the time in milliseconds to wait before giving |
| 68 | up. Otherwise MACH_MSG_TIMEOUT_NONE should be supplied. |
| 69 | <p> |
| 70 | <dt> <var>notify</var> |
| 71 | <dd> |
| 72 | [in notify receive right] When using the MACH_SEND_CANCEL and |
| 73 | MACH_RCV_NOTIFY options, specifies the port used for the |
| 74 | notification. Otherwise MACH_PORT_NULL should be supplied. |
| 75 | <p> |
| 76 | <dt> <var>receive_msg</var> |
| 77 | <dd> |
| 78 | [pointer to in/out structure] A message buffer into which a message |
| 79 | (header and body) will be received. This must be naturally aligned. By |
| 80 | default (<strong>mach_msg</strong>), any received message will overwrite the send |
| 81 | message buffer. This buffer is in/out only if the MACH_RCV_OVERWRITE |
| 82 | option is used; otherwise this buffer is out only. |
| 83 | <p> |
| 84 | <dt> <var>receive_msg_size</var> |
| 85 | <dd> |
| 86 | [in scalar] When using the MACH_RCV_OVERWRITE option, specifies the |
| 87 | size (in bytes) of the receive "message" that is to be used by |
| 88 | <strong>mach_msg</strong> to indicate the disposition of received out-of-line regions. |
| 89 | </dl> |
| 90 | <h3>DESCRIPTION</h3> |
| 91 | <p> |
| 92 | The <strong>mach_msg</strong> system call sends and receives Mach messages. Mach |
| 93 | messages contain data, which can include port rights and addresses of |
| 94 | large regions of memory. <strong>mach_msg</strong> uses the same buffer for sending and |
| 95 | receiving a message; the other calls permit separate send and receive |
| 96 | buffers (although they may be specified to be the same). |
| 97 | If the option argument contains MACH_SEND_MSG, the call sends a |
| 98 | message. The <var>send_size</var> argument specifies the size of the message |
| 99 | buffer (header and body) to send. The msgh_remote_port field of the |
| 100 | message header specifies the destination of the message. |
| 101 | If the option argument contains MACH_RCV_MSG, it receives a |
| 102 | message. The receive_limit argument specifies the size of a buffer |
| 103 | that will receive the message; messages that are larger are not |
| 104 | received. The receive_name argument specifies the port or port set |
| 105 | from which to receive. |
| 106 | <p> |
| 107 | If the option argument contains both MACH_SEND_MSG and MACH_RCV_MSG, |
| 108 | then <strong>mach_msg</strong> does both send and receive operations (in that |
| 109 | order). If the send operation encounters an error (any return code |
| 110 | other than MACH_MSG_SUCCESS), the call returns immediately |
| 111 | without attempting the receive operation. Semantically the combined |
| 112 | call is equivalent to separate send and receive calls, but it saves |
| 113 | a system call and enables other internal optimizations. |
| 114 | |
| 115 | If the option argument specifies neither MACH_SEND_MSG nor |
| 116 | MACH_RCV_MSG, <strong>mach_msg</strong> does nothing. |
| 117 | Some options, like MACH_SEND_TIMEOUT and MACH_RCV_TIMEOUT, share a |
| 118 | supporting argument. If these options are used together, they make |
| 119 | independent use of the supporting argument's value. |
| 120 | <h3>NOTES</h3> |
| 121 | <p> |
| 122 | The Mach kernel provides message-oriented, capability-based |
| 123 | inter-process communication. The inter-process communication (IPC) |
| 124 | primitives efficiently support many different styles of interaction, |
| 125 | including remote procedure calls, object-oriented distributed |
| 126 | programming, streaming of data, and sending very large amounts of |
| 127 | data. |
| 128 | <h4>Major Concepts</h4> |
| 129 | <p> |
| 130 | The IPC primitives operate on three abstractions: messages, ports, and |
| 131 | port sets. User tasks access all other kernel services and |
| 132 | abstractions via the IPC primitives. |
| 133 | <p> |
| 134 | The message primitives let tasks send and receive messages. Tasks send |
| 135 | messages to ports. Messages sent to a port are delivered reliably |
| 136 | (messages may not be lost) and are received in the order in which they |
| 137 | were sent via send rights by a given sending task (or a given |
| 138 | kernel). (Messages sent to send-once rights are unordered.) |
| 139 | <p> |
| 140 | Messages |
| 141 | contain a fixed-size header and a variable-sized message body |
| 142 | containing kernel and user data, and a variable-size trailer of kernel |
| 143 | appended message attributes. The header describes the destination |
| 144 | and the size of the message (header plus body). The message body |
| 145 | contains descriptions of additional port rights to be transmitted, |
| 146 | descriptions of "out-of-line" memory regions to be sent and a |
| 147 | variable amount of user data, which typically includes type conversion |
| 148 | information. The out-of-line memory regions (including out-of-line |
| 149 | port arrays) are (typically) disjoint from the message body. |
| 150 | The IPC implementation makes use of the VM system to efficiently |
| 151 | transfer large amounts of data. The message can contain the addresses |
| 152 | of regions of the sender's address space which should be transferred |
| 153 | as part of the message. |
| 154 | <p> |
| 155 | When a task receives a message containing |
| 156 | such out-of-line regions of data, the data can appear in unused |
| 157 | portions or overwrite an existing portion of the receiver's address |
| 158 | space (depending on the requested receive options). Under favorable |
| 159 | circumstances, the transmission of out-of-line data is optimized so |
| 160 | that sender and receiver share the physical pages of data |
| 161 | copy-on-write, and no actual data copy occurs unless the pages are |
| 162 | written. Regions of memory up to 4 gigabytes may be sent in this |
| 163 | manner. |
| 164 | <p> |
| 165 | Ports hold a queue of messages. Tasks operate on a port to send and |
| 166 | receive messages by exercising capabilities (rights) for the |
| 167 | port. Multiple tasks can hold send rights for a port. |
| 168 | Tasks can also |
| 169 | hold send-once rights, which grant the ability to send a single |
| 170 | message. Only one task can hold the receive capability (receive |
| 171 | right) for a port. |
| 172 | <p> |
| 173 | Port rights can be transferred between tasks via |
| 174 | messages. The sender of a message can specify in the message that the |
| 175 | message contains a port right. If a message contains a receive right |
| 176 | for a port, the receive right is removed from the sender of the |
| 177 | message and transferred to the receiver of the |
| 178 | message. While the receive right is in transit, tasks holding send |
| 179 | rights can still send messages to the port, and they are queued until |
| 180 | a task acquires the receive right and uses it to receive the messages. |
| 181 | <p> |
| 182 | Tasks can receive messages from ports and port sets. The port set |
| 183 | abstraction allows a single thread to wait for a message from any of |
| 184 | several ports. Tasks manipulate port sets with a port set name, |
| 185 | which is taken from the same name space as are the port rights. The |
| 186 | port-set name may not be transferred in a message. A port set holds |
| 187 | receive rights, and a receive operation on a port set blocks waiting |
| 188 | for a message sent to any of the constituent ports. A port may not be- |
| 189 | long to more than one port set, and if a port is a member of a port |
| 190 | set, the holder of the receive right can't receive directly from the |
| 191 | port. |
| 192 | <p> |
| 193 | Port rights are a secure, location-independent way of naming |
| 194 | ports. The port queue is a protected data structure, only accessible |
| 195 | via the kernel's exported message primitives. Rights are also |
| 196 | protected by the kernel; there is no way for a malicious user task to |
| 197 | guess a port's internal name and send a message to a port to which it |
| 198 | shouldn't have access. Port rights do not carry any location in- |
| 199 | formation. When a receive right for a port moves from task to task, |
| 200 | and even between tasks on different machines, the send rights for |
| 201 | the port remain unchanged and continue to function. |
| 202 | <h4>Port Rights</h4> |
| 203 | <p> |
| 204 | Each task has its own space of port rights. Port rights are named with |
| 205 | positive (unsigned) integers. For all architectures, sizeof |
| 206 | (mach_port_t) = sizeof (mach_port_name_t) = sizeof (void*) and so user |
| 207 | space addresses may be used as port names, except for the reserved |
| 208 | values MACH_PORT_NULL (0) and MACH_PORT_DEAD (all 1 bits). When the |
| 209 | kernel chooses a name for a new right, however, it is free to pick any |
| 210 | unused name (one which denotes no right) in the space. |
| 211 | <p> |
| 212 | There are three basic kinds of rights: receive rights, send rights and |
| 213 | send-once rights. A port name can name any of these types of rights, |
| 214 | or name a port-set, be a dead name, or name nothing. Dead names are |
| 215 | not capabilities. They act as place-holders to prevent a name from |
| 216 | being otherwise used. |
| 217 | <p> |
| 218 | A port is destroyed, or dies, when its receive right is |
| 219 | de-allocated. When a port dies, send and send-once rights for the port |
| 220 | turn into dead names. Any messages queued at the port are destroyed, |
| 221 | which de-allocates the port rights and out-of-line memory in the |
| 222 | messages. |
| 223 | <p> |
| 224 | Each send-once right held by a task has a different name. In contrast, |
| 225 | when a task holds send rights or a receive right for a port, the |
| 226 | rights share a single name. |
| 227 | <p> |
| 228 | Tasks may hold multiple user-references for send rights. When a task |
| 229 | receives a send right which it already holds, the kernel increments |
| 230 | the right's user-reference count. When a task de-allocates a send |
| 231 | right, the kernel decrements its user-reference count, and the task |
| 232 | only loses the send right when the count goes to zero. |
| 233 | <p> |
| 234 | Send-once rights always have a user reference count of one. Tasks may |
| 235 | hold multiple user references for dead names. |
| 236 | Each send-once right generated guarantees the receipt of a single |
| 237 | message, either a message sent to that send-once right or, if the |
| 238 | send-once right is in any way destroyed, a send-once notification. |
| 239 | <p> |
| 240 | A message can carry port rights; the msgh_remote or msgh_local fields |
| 241 | in the message header or the disposition field in a message body |
| 242 | descriptor specify the type of port right and how the port right is to |
| 243 | be extracted from the caller. The values MACH_PORT_NULL and |
| 244 | MACH_PORT_DEAD are valid in place of a port right in a message body. |
| 245 | <p> |
| 246 | In a sent message, the following mach_msg_type_name_t values denote |
| 247 | port rights: |
| 248 | <dl> |
| 249 | <dt> MACH_MSG_TYPE_MAKE_SEND |
| 250 | <dd> |
| 251 | The message will carry a send right, but the caller must supply a |
| 252 | receive right. The send right is created from the receive right, and the |
| 253 | receive right's make-send count is incremented. |
| 254 | <dt> MACH_MSG_TYPE_COPY_SEND |
| 255 | <dd> |
| 256 | The message will carry a send right, and the caller must supply a send |
| 257 | right. The user reference count for the supplied send right is not |
| 258 | changed. The caller may also supply a dead name and the receiving |
| 259 | task will get MACH_PORT_DEAD. |
| 260 | <dt> MACH_MSG_TYPE_MOVE_SEND |
| 261 | <dd> |
| 262 | The message will carry a send right, and the caller must supply a send |
| 263 | right. The user reference count for the supplied send right is |
| 264 | decremented, and the right is destroyed if the count becomes |
| 265 | zero. Unless a receive right remains, the name becomes available for |
| 266 | recycling. The caller may also supply a dead name, which loses a user |
| 267 | reference, and the receiving task will get MACH_PORT_DEAD. |
| 268 | <dt> MACH_MSG_TYPE_MAKE_SEND_ONCE |
| 269 | <dd> |
| 270 | The message will carry a send-once right, but the caller must supply a |
| 271 | receive right. The send-once right is created from the receive right. |
| 272 | Note that send once rights can only be created from the receive right. |
| 273 | <dt> MACH_MSG_TYPE_MOVE_SEND_ONCE |
| 274 | <dd> |
| 275 | The message will carry a send-once right, and the caller must supply a |
| 276 | send-once right. The caller loses the supplied send-once right. The |
| 277 | caller may also supply a dead name, which loses a user reference, |
| 278 | and the receiving task will get MACH_PORT_DEAD. |
| 279 | <dt> MACH_MSG_TYPE_MOVE_RECEIVE |
| 280 | <dd> |
| 281 | The message will carry a receive right, and the caller must supply a |
| 282 | receive right. The caller loses the supplied receive right, but |
| 283 | retains any send rights with the same name. The make-send count and |
| 284 | sequence number of the receive right are reset to zero and |
| 285 | no-more-senders notification requests are cancelled (with a |
| 286 | send-once notification being sent to the no-more-senders notification |
| 287 | right), but the port retains other attributes like queued messages |
| 288 | and extant send and send-once rights. |
| 289 | If a message carries a send or send-once right, and the port dies |
| 290 | while the message is in transit, then the receiving task will get |
| 291 | MACH_PORT_DEAD instead of a right. |
| 292 | </dl> |
| 293 | <p> |
| 294 | The following mach_msg_type_name_t values in a received message |
| 295 | indicate that it carries port rights: |
| 296 | <dl> |
| 297 | <dt> MACH_MSG_TYPE_PORT_SEND |
| 298 | <dd> |
| 299 | This value is an alias for MACH_MSG_TYPE_MOVE_SEND. The |
| 300 | message carried a send right. If the receiving task already has send and/ |
| 301 | or receive rights for the port, then that name for the port will be reused. |
| 302 | Otherwise, the right will have a new, previously unused, name. If the |
| 303 | task already has send rights, it gains a user reference for the right (un- |
| 304 | less this would cause the user-reference count to overflow). Otherwise, |
| 305 | it acquires send rights, with a user-reference count of one. |
| 306 | <dt> MACH_MSG_TYPE_PORT_SEND_ONCE |
| 307 | <dd> |
| 308 | This value is an alias for MACH_MSG_TYPE_MOVE_SEND_ONCE. The message |
| 309 | carried a send-once right. The right will have a new, previously |
| 310 | unused, name. |
| 311 | <dt> MACH_MSG_TYPE_PORT_RECEIVE |
| 312 | <dd> |
| 313 | This value is an alias for MACH_MSG_TYPE_MOVE_RECEIVE. The message |
| 314 | carried a receive right. If the receiving task already has send rights |
| 315 | for the port, then that name for the port will be reused; otherwise, |
| 316 | the right will have a new, previously unused name. |
| 317 | </dl> |
| 318 | <p> |
| 319 | It is also possible to send a (nearly unbounded) array of port rights |
| 320 | "out-of-line". All of the rights named by the array must be of the |
| 321 | same type. The array is physically copied with the message body |
| 322 | proper. The array of port right (names) can be received by the |
| 323 | receiver using the same options available for out-of-line data |
| 324 | reception described below. |
| 325 | <h4>Memory</h4> |
| 326 | <p> |
| 327 | A message can contain one or more regions of the sender's address |
| 328 | space which are to be transferred as part of the message. The message |
| 329 | carries a logical copy of the memory. For this "out-of-line" memory, |
| 330 | the kernel can copy the data or use virtual memory techniques to defer |
| 331 | any actual page copies unless the sender or the receiver modifies |
| 332 | the data, the physical pages remain shared. |
| 333 | <p> |
| 334 | The sender of the message must explicitly request an out-of-line |
| 335 | transfer. Such a region is described as an arbitrary region of the |
| 336 | sender's address space. The sender always sees this memory as being |
| 337 | copied to the receiver. |
| 338 | <p> |
| 339 | For each region, the sender has a de-allocate option. If the option is |
| 340 | set and the out-of-line memory region is not null, then the region is |
| 341 | implicitly de-allocated from the sender, as if by vm_deallocate. In |
| 342 | particular, the start address is truncated down and the end address |
| 343 | rounded up so that every page overlapped by the memory region is |
| 344 | de-allocated (thereby possibly de-allocating more memory than is |
| 345 | effectively transmitted). The use of this option effectively changes |
| 346 | the memory copy to a memory movement. Aside from possibly optimizing |
| 347 | the sender's use of memory, the de-allocation option allows the kernel |
| 348 | to more efficiently handle the transfer of memory. |
| 349 | <p> |
| 350 | For each region, the sender has the choice of permitting the kernel to |
| 351 | choose a transmission strategy or the choice of requiring physical |
| 352 | copy: |
| 353 | <dl> |
| 354 | <dt> MACH_MSG_VIRTUAL_COPY |
| 355 | <dd> |
| 356 | In a sent message, this flag allows the kernel to choose any mechanism |
| 357 | to transmit the data. For large regions, this involves constructing a |
| 358 | virtual copy of the pages containing the region. The portion of the |
| 359 | first page preceding the data and the portion of the last page |
| 360 | following the data are not copied (and will appear as zero if the |
| 361 | virtual copy is dynamically allocated in the receiver). |
| 362 | <p> |
| 363 | In a received message, this flag indicates that the kernel transmitted |
| 364 | a virtual copy. Access to the received memory may involve interactions |
| 365 | with the memory manager managing the sender's original data. Integri- |
| 366 | ty-conscious receivers should exercise caution when dealing with out- |
| 367 | of-line memory from un-trustworthy sources. Receivers concerned about |
| 368 | deterministic access time should also exercise caution. The dynamic |
| 369 | allocation option guarantees that the virtual copy will not be di- |
| 370 | rectly referenced during the act of receiving the message. |
| 371 | <dt> MACH_MSG_PHYSICAL_COPY |
| 372 | <dd> |
| 373 | In a sent message, this flag requires that the kernel construct an |
| 374 | actual copy of the memory (either into wired kernel memory or default |
| 375 | memory managed space). There is a (fairly large) limit on the amount |
| 376 | of data that can be physically copied in a message. Port arrays always |
| 377 | assume this option when sent. |
| 378 | <p> |
| 379 | In a received message, this flag indicates that the kernel did |
| 380 | transmit a physical copy. |
| 381 | </dl> |
| 382 | <p> |
| 383 | The receiver has two options for the reception of out-of-line memory |
| 384 | (or "out-of-line" port arrays): allocation and overwrite. |
| 385 | In the absence of the MACH_RCV_OVERWRITE option, all out-of-line re- |
| 386 | gions are dynamically allocated. Allocated out-of-line memory arrives |
| 387 | somewhere in the receiver's address space as new memory. It has the |
| 388 | same inheritance and protection attributes as newly vm_allocate'ed |
| 389 | memory. The receiver has the responsibility of de-allocating (with |
| 390 | vm_deallocate) the memory when it is no longer needed. If the message |
| 391 | contains more than one region, each will be allocated its own region, |
| 392 | not necessarily contiguously. If the sender's data was transmitted as |
| 393 | a virtual copy the allocated region will have the same data alignment |
| 394 | within the page; otherwise, the received data will appear starting at |
| 395 | the beginning of a page. |
| 396 | <p> |
| 397 | If the MACH_RCV_OVERWRITE option is set, the receiver can specify how |
| 398 | each received region is to be processed (dynamically allocated as |
| 399 | described above, or written over existing memory). With this option, |
| 400 | the contents of the receive buffer (receive_msg) are examined by the |
| 401 | kernel. The kernel scans the descriptors in the receive buffer |
| 402 | "message" to determine how to handle each out-of-line region. (Note: |
| 403 | whereas receive_limit is the maximum size of the receive buffer, |
| 404 | receive_msg_size is the amount filled in with this "message".) The |
| 405 | kernel uses each out-of-line data descriptor (in order) to specify |
| 406 | the processing for each received data region in turn, each out-of-line |
| 407 | port array descriptor is used correspondingly. (Intermingled port |
| 408 | descriptors are ignored when matching descriptors between the |
| 409 | incoming message and the receive buffer list.) |
| 410 | <p> |
| 411 | The copy option in the |
| 412 | matching descriptor specifies the processing: |
| 413 | <dl> |
| 414 | <dt> MACH_MSG_OVERWRITE |
| 415 | <dd> |
| 416 | This flag indicates that the region should write over a specified |
| 417 | region of the receiver's address space, as indicated by the address |
| 418 | and size/ count fields of the descriptor. The full range overwritten |
| 419 | must already exist (be allocated or mapped) in the receiver's address |
| 420 | space. Depending on the nature of the data transmission this |
| 421 | overwrite may involve virtual memory manipulations or it may involve |
| 422 | actual data copy. |
| 423 | <dt> MACH_MSG_ALLOCATE |
| 424 | <dd> |
| 425 | This flag indicates that the region is to be dynamically allocated. No |
| 426 | other descriptor values are relevant. |
| 427 | </dl> |
| 428 | <p> |
| 429 | If not enough descriptors appear in the receive buffer to describe all |
| 430 | received regions, additional regions are dynamically allocated. If |
| 431 | the receiver specifies more descriptors than there are regions in the |
| 432 | received message, the additional descriptors are ignored (and do not |
| 433 | appear in the final received message). |
| 434 | <p> |
| 435 | Note that the receive buffer descriptors will be overwritten: |
| 436 | The size fields in descriptors will be updated (when scanned, they |
| 437 | specified the maximum sizes of regions, when received, they specify |
| 438 | the actual sizes of received regions). |
| 439 | The copy fields in descriptors will be updated (when scanned, they |
| 440 | specified allocate versus overwrite, when received, they indicate |
| 441 | whether the region was physically or virtually copied). |
| 442 | The descriptors may appear in different positions (given intermingled |
| 443 | port descriptors). |
| 444 | Descriptors that were not used (because there were not that many |
| 445 | received regions) will be discarded. |
| 446 | <p> |
| 447 | Null out-of-line memory is legal. If the out-of-line region size is |
| 448 | zero, then the region's specified address is ignored. A receive |
| 449 | allocated null out-of-line memory region always has a zero address. |
| 450 | Unaligned addresses and region sizes that are not page multiples are |
| 451 | legal. A received message can also contain regions with unaligned |
| 452 | addresses and sizes which are not multiples of the page size. |
| 453 | <h4>Message Send</h4> |
| 454 | <p> |
| 455 | The send operation queues a message to a port. The message carries a |
| 456 | copy of the caller's data. After the send, the caller can freely |
| 457 | modify the message buffer or the out-of-line memory regions and the |
| 458 | message contents will remain unchanged. |
| 459 | <p> |
| 460 | The message carries with it the security ID of the sender, which the |
| 461 | receiver can request in the message trailer. |
| 462 | <p> |
| 463 | Message delivery is reliable and sequenced. Reception of a message |
| 464 | guarantees that all messages previously sent to the port by a single |
| 465 | task (or a single kernel) via send rights have been received and that |
| 466 | they are received in the order in which they were sent. Messages sent |
| 467 | to send-once rights are unordered. |
| 468 | <p> |
| 469 | If the destination port's queue is full, several things can happen. If |
| 470 | the message is sent to a send-once right (msgh_remote_port carries a |
| 471 | send-once right), then the kernel ignores the queue limit and delivers |
| 472 | the message. Otherwise the caller blocks until there is room in the |
| 473 | queue, unless the MACH_SEND_TIMEOUT option is used. If a port has |
| 474 | several blocked senders, then any of them may queue the next message |
| 475 | when space in the queue becomes available, with the proviso that a |
| 476 | blocked sender will not be indefinitely starved. |
| 477 | These options modify MACH_SEND_MSG. If MACH_SEND_MSG is not also |
| 478 | specified, they are ignored. |
| 479 | <dl> |
| 480 | <dt> MACH_SEND_TIMEOUT |
| 481 | <dd> |
| 482 | The timeout argument should specify a maximum time (in milliseconds) |
| 483 | for the call to block before giving up. If the message can't be queued |
| 484 | before the timeout interval elapses, then the call returns |
| 485 | MACH_SEND_TIMED_OUT. A zero timeout is legitimate. |
| 486 | <dt> MACH_SEND_INTERRUPT |
| 487 | <dd> |
| 488 | If specified, the <strong>mach_msg</strong> call will return |
| 489 | MACH_SEND_INTERRUPTED if a software interrupt aborts the call. |
| 490 | Otherwise, the send operation will be retried. |
| 491 | <dt> MACH_SEND_TRAILER |
| 492 | <dd> |
| 493 | If set, the kernel, instead of determining the message attributes |
| 494 | itself, will accept a formatted message trailer from the sender. The |
| 495 | supplied trailer must be of the latest version supported by the |
| 496 | kernel, and must contain all message attributes defined by the |
| 497 | kernel. Only tasks with a security ID of KERNEL_SECURITY_ID can use |
| 498 | this option; the intended use of this option is in support of the |
| 499 | Net Message server. The trailer must follow the message in memory as |
| 500 | it would appear in a received message. (The send_size argument to |
| 501 | <strong>mach_msg</strong> still indicates the size of the message proper, not including |
| 502 | this trailer.) |
| 503 | </dl> |
| 504 | <p> |
| 505 | The queueing of a message carrying receive rights may create a |
| 506 | circular loop of receive rights and messages, which can never be |
| 507 | received. For example, a message carrying a receive right can be |
| 508 | sent to that receive right. This situation is not an error, but the |
| 509 | kernel will garbage-collect such loops, destroying the messages. |
| 510 | Some return codes, like MACH_SEND_TIMED_OUT, imply that the message |
| 511 | was almost sent, but could not be queued. In these situations, the |
| 512 | kernel tries to return the message contents to the caller with a |
| 513 | pseudo-receive operation. This prevents the loss of port rights or |
| 514 | memory which only exist in the message, for example, a receive right |
| 515 | which was moved into the message, or out-of-line memory sent with |
| 516 | the de-allocate option. |
| 517 | <p> |
| 518 | The intent of the pseudo-receive operation is to restore, as best as |
| 519 | possible, the state prior to attempting the send. This involves |
| 520 | restoring the port rights and out-of-line memory regions contained in |
| 521 | the message. The port right names and out-of-line addresses in the |
| 522 | message send buffer are updated to reflect the new values resulting |
| 523 | from their effective reception. The pseudo-receive handles the des- |
| 524 | tination and reply rights as any other rights; they are not reversed |
| 525 | as is the appearance in a normal received message. Also, no trailer is |
| 526 | appended to the message. After the pseudo-receive, the message is |
| 527 | ready to be resent. If the message is not resent, note that |
| 528 | out-of-line memory regions may have moved and some port rights may |
| 529 | have changed names. |
| 530 | <p> |
| 531 | Although unlikely, the pseudo-receive operation may encounter resource |
| 532 | shortages. This is similar to a MACH_RCV_BODY_ERROR return code from |
| 533 | a receive operation. When this happens, the normal send return codes |
| 534 | are augmented with the MACH_MSG_IPC_SPACE, MACH_MSG_VM_SPACE, |
| 535 | MACH_MSG_IPC_KERNEL and MACH_MSG_VM_KERNEL bits to indicate the |
| 536 | nature of the resource shortage. |
| 537 | <h4>Message Receive</h4> |
| 538 | <p> |
| 539 | The receive operation de-queues a message from a port. The receiving |
| 540 | task acquires the port rights and out-of-line memory regions carried |
| 541 | in the message. |
| 542 | The receive_name argument specifies a port or port set from which to |
| 543 | receive. If a port is specified, the caller must possess the receive |
| 544 | right for the port and the port must not be a member of a port set. If |
| 545 | no message is present, the call blocks, subject to the |
| 546 | MACH_RCV_TIMEOUT option. |
| 547 | <p> |
| 548 | If a port set is specified, the call will receive a message sent to |
| 549 | any of the member ports. It is permissible for the port set to have |
| 550 | no member ports, and ports may be added and removed while a receive |
| 551 | from the port set is in progress. The received message can come from |
| 552 | any of the member ports which have messages, with the proviso that a |
| 553 | member port with messages will not be indefinitely starved. The |
| 554 | msgh_local_port field in the received message header specifies from |
| 555 | which port in the port set the message came. |
| 556 | <p> |
| 557 | The receive_limit argument specifies the size of the caller's message |
| 558 | buffer (which must be big enough for the message header, body and |
| 559 | trailer); the msgh_size field of the received message indicates the |
| 560 | actual size of the received message header and body. The <strong>mach_msg</strong> call |
| 561 | will not receive a message larger than receive_limit. Messages that |
| 562 | are too large are destroyed, unless the MACH_RCV_LARGE option is used. |
| 563 | Following the received data, at the next natural boundary, is a |
| 564 | message trailer. The msgh_size field of the received message does not |
| 565 | include the length of this trailer; the trailer's length is given by |
| 566 | the msgh_trailer_size field within the trailer. The receiver of a |
| 567 | message is given a choice as to what trailer format is desired, and, |
| 568 | within that format, which of the leading trailer attributes are |
| 569 | desired (that is, to get trailer element three, the receiver must also |
| 570 | accept elements one and two). For any given trailer format (of which |
| 571 | there is currently only one), the trailer is compatibly extended by |
| 572 | adding additional elements to the end. |
| 573 | <p> |
| 574 | Received messages are stamped (in the trailer) with a sequence number, |
| 575 | taken from the port from which the message was received. (Messages |
| 576 | received from a port set are stamped with a sequence number from the |
| 577 | appropriate member port.) Newly created ports start with a zero |
| 578 | sequence number, and the sequence number is reset to zero whenever the |
| 579 | port's receive right moves between tasks. When a message is de-queued |
| 580 | from the port, it is stamped with the port's sequence number and the |
| 581 | port's sequence number is then incremented. (Note that this occurs |
| 582 | whether or not the receiver requests the sequence number in the trail- |
| 583 | er.) The de-queue and increment operations are atomic, so that |
| 584 | multiple threads receiving messages from a port can use the msgh_seqno |
| 585 | field to reconstruct the original order of the messages. |
| 586 | <p> |
| 587 | The destination and reply ports are reversed in a received message |
| 588 | header. The msgh_local_port field carries the name of the destination |
| 589 | port, from which the message was received, and the msgh_remote_port |
| 590 | field carries the reply port right. The bits in msgh_bits are also |
| 591 | reversed. The MACH_MSGH_BITS_LOCAL bits have a value of |
| 592 | MACH_MSG_TYPE_PORT_SEND_ONCE or MACH_MSG_TYPE_PORT_SEND depending on |
| 593 | the type of right to which the message was sent. The |
| 594 | MACH_MSGH_BITS_REMOTE bits describe the reply port right. |
| 595 | <p> |
| 596 | A received message can contain port rights and out-of-line memory. The |
| 597 | msgh_local_port field does not carry a port right; the act of |
| 598 | receiving the message consumes the send or send-once right for the |
| 599 | destination port. The msgh_remote_port field does carry a port right, |
| 600 | and the message can carry additional port rights and memory if the |
| 601 | MACH_MSGH_BITS_COMPLEX bit is set. Received port rights and memory |
| 602 | should be consumed or de-allocated in some fashion. |
| 603 | In almost all cases, msgh_local_port will specify the name of a |
| 604 | receive right, either receive_name, or, if receive_name is a port |
| 605 | set, a member of receive_name. |
| 606 | <p> |
| 607 | If other threads are concurrently |
| 608 | manipulating the receive right, the situation is more complicated. If |
| 609 | the receive right is renamed during the call, then msgh_local_port |
| 610 | specifies the right's new name. If the caller loses the receive right |
| 611 | after the message was de-queued from it, then <strong>mach_msg</strong> will proceed |
| 612 | instead of returning MACH_RCV_PORT_DIED. If the receive right was |
| 613 | destroyed, then msgh_local_port specifies MACH_PORT_DEAD. If the |
| 614 | receive right still exists, but isn't held by the caller, then |
| 615 | msgh_local_port specifies MACH_PORT_NULL. |
| 616 | <p> |
| 617 | The following options modify MACH_RCV_MSG. If MACH_RCV_MSG is not also |
| 618 | specified, they are ignored. |
| 619 | <dl> |
| 620 | <dt> MACH_RCV_TIMEOUT |
| 621 | <dd> |
| 622 | The timeout argument should specify a maximum time (in milliseconds) |
| 623 | for the call to block before giving up. If no message arrives before |
| 624 | the timeout interval elapses, then the call returns |
| 625 | MACH_RCV_TIMED_OUT. A zero timeout is legitimate. |
| 626 | <dt> MACH_RCV_NOTIFY |
| 627 | <dd> |
| 628 | The notify argument should specify a receive right for a notify |
| 629 | port. If receiving the reply port creates a new port right in the |
| 630 | caller, then the notify port is used to request a dead-name |
| 631 | notification for the new port right. |
| 632 | <dt> MACH_RCV_INTERRUPT |
| 633 | <dd> |
| 634 | If specified, the <strong>mach_msg</strong> call will return MACH_RCV_INTERRUPTED if a |
| 635 | software interrupt aborts the call. Otherwise, the receive operation |
| 636 | will be retried. |
| 637 | <dt> MACH_RCV_OVERWRITE |
| 638 | <dd> |
| 639 | If specified, the message buffer specified by receive_msg (or msg), of |
| 640 | length receive_msg_size, will be scanned for out-of-line descriptors to |
| 641 | specify the processing to be done when receiving out-of-line regions. |
| 642 | This option is only allowed for <strong>mach_msg_overwrite</strong>. |
| 643 | <dt> MACH_RCV_LARGE |
| 644 | <dd> |
| 645 | If the message is larger than receive_limit or an out-of-line region |
| 646 | is larger than the size allowed by a corresponding receive descriptor |
| 647 | (MACH_RCV_OVERWRITE), the message remains queued instead of being |
| 648 | destroyed. If the header, trailer and body would not fit into |
| 649 | receive_limit, only the message header (mach_msg_header) and trailer |
| 650 | header (mach_msg_trailer) are returned with the actual size of the |
| 651 | message returned in the msgh_size field, the actual size of the |
| 652 | trailer returned in the msgh_trailer_size field and an error return |
| 653 | value of MACH_RCV_TOO_LARGE. If receive_limit is sufficient but an |
| 654 | out-of-line descriptor is not, the message header, trailer and body |
| 655 | are received, with out-of-line descriptors set to indicate the |
| 656 | nature and size of the out-of-line regions, with an error return of |
| 657 | MACH_RCV_SCATTER_SMALL. No out-of-line regions or port rights |
| 658 | (including the reply right) will be received. If this option is not |
| 659 | specified, messages too large will be de-queued and then destroyed; |
| 660 | the caller receives the message header, with all fields correct, |
| 661 | including the destination port but excepting the reply port, which is |
| 662 | MACH_PORT_NULL and an empty (no additional element) message trailer. |
| 663 | <dt> MACH_RCV_TRAILER_TYPE(value) |
| 664 | <dd> |
| 665 | This macro encodes the type of trailer the kernel must return with the |
| 666 | message. If the kernel does not recognize this type, it returns |
| 667 | MACH_RCV_INVALID_TRAILER. Currently, only MACH_MSG_TRAILER_FORMAT_0 is |
| 668 | supported. |
| 669 | <dt> MACH_RCV_TRAILER_ELEMENTS(value) |
| 670 | <dd> |
| 671 | This macro encodes the number of trailer elements desired. If the ker- |
| 672 | nel does not support this number for the requested trailer type, the |
| 673 | kernel returns MACH_RCV_INVALID_TRAILER. Zero is a legal value. |
| 674 | </dl> |
| 675 | <p> |
| 676 | The following trailer elements are supported: |
| 677 | <dl> |
| 678 | <dt> MACH_RCV_TRAILER_SEQNO |
| 679 | <dd> |
| 680 | Returns the sequence number of the message relative to its port. This |
| 681 | value is of type mach_port_seqno_t. |
| 682 | <dt> MACH_RCV_TRAILER_SENDER |
| 683 | <dd> |
| 684 | Returns the security ID of the task that sent the message. This value |
| 685 | is of type security_id_t. |
| 686 | </dl> |
| 687 | <p> |
| 688 | If a resource shortage prevents the reception of a port right, the |
| 689 | port right is destroyed and the caller sees the name |
| 690 | MACH_PORT_NULL. If a resource shortage prevents the reception of an |
| 691 | out-of-line memory region, the region is destroyed and the caller sees |
| 692 | a zero address. In addition, the corresponding element in the size |
| 693 | array is set to zero. A task never receives port rights or memory for |
| 694 | which it is not told. |
| 695 | <p> |
| 696 | The MACH_RCV_HEADER_ERROR return code indicates a resource shortage |
| 697 | in the reception of the message header. The reply port and all port |
| 698 | rights and memory in the message are destroyed. The caller receives |
| 699 | the message header with all fields correct except for the reply |
| 700 | port. |
| 701 | <p> |
| 702 | The MACH_RCV_BODY_ERROR return code indicates a resource shortage in |
| 703 | the reception of the message body. The message header, including the |
| 704 | reply port, is correct. The kernel attempts to transfer all port |
| 705 | rights and memory regions in the body, and only destroys those that |
| 706 | can't be transferred. |
| 707 | <h4>Atomicity</h4> |
| 708 | <p> |
| 709 | The <strong>mach_msg</strong> call handles port rights in the message header |
| 710 | atomically. Out-of-line memory and port rights in the message body do |
| 711 | not enjoy this atomicity guarantee. These elements may be processed |
| 712 | front-to-back, back-to-front, in some random order, or even |
| 713 | atomically. |
| 714 | <p> |
| 715 | For example, consider sending a message with the destination port |
| 716 | specified as MACH_MSG_TYPE_MOVE_SEND and the reply port specified as |
| 717 | MACH_MSG_TYPE_COPY_SEND. The same send right, with one user-refer- |
| 718 | ence, is supplied for both the msgh_remote_port and msgh_local_port |
| 719 | fields. Because <strong>mach_msg</strong> processes the port rights atomically, this |
| 720 | succeeds. If msgh_remote_port were processed before msgh_local_port, |
| 721 | then <strong>mach_msg</strong> would return MACH_SEND_INVALID_REPLY in this situation. |
| 722 | <p> |
| 723 | On the other hand, suppose the destination and reply port are both |
| 724 | specified as MACH_MSG_TYPE_MOVE_SEND, and again the same send right |
| 725 | with one user-reference is supplied for both. Now the send operation |
| 726 | fails, but because it processes the rights atomically, <strong>mach_msg</strong> can |
| 727 | return either MACH_SEND_INVALID_DEST or MACH_SEND_INVALID_REPLY. |
| 728 | <p> |
| 729 | For example, consider receiving a message at the same time another |
| 730 | thread is deallocating the destination receive right. Suppose the |
| 731 | reply port field carries a send right for the destination port. If the |
| 732 | de-allocation happens before the dequeuing, the receiver gets |
| 733 | MACH_RCV_PORT_DIED. If the de-allocation happens after the receive, |
| 734 | the msgh_local_port and the msgh_remote_port fields both specify |
| 735 | the same right, which becomes a dead name when the receive right is |
| 736 | de-allocated. If the de-allocation happens between the de-queue and |
| 737 | the receive, the msgh_local_port and msgh_remote_port fields both |
| 738 | specify MACH_PORT_DEAD. Because the rights are processed atomically, |
| 739 | it is not possible for just one of the two fields to hold |
| 740 | MACH_PORT_DEAD. |
| 741 | <p> |
| 742 | The MACH_RCV_NOTIFY option provides a more likely example. Suppose a |
| 743 | message carrying a send-once right reply port is received with |
| 744 | MACH_RCV_NOTIFY at the same time the reply port is destroyed. If the |
| 745 | reply port is destroyed first, then msgh_remote_port specifies |
| 746 | MACH_PORT_DEAD and the kernel does not generate a dead-name |
| 747 | notification. If the reply port is destroyed after it is received, |
| 748 | then msgh_remote_port specifies a dead name for which the kernel |
| 749 | generates a dead-name notification. Either the reply port is dead on |
| 750 | arrival or notification is requested. |
| 751 | <h4>Implementation</h4> |
| 752 | <p> |
| 753 | <strong>mach_msg</strong> and <strong>mach_msg_overwrite</strong> are wrappers for a system call. They |
| 754 | have the responsibility for repeating the interrupted system call. |
| 755 | <h3>CAUTIONS</h3> |
| 756 | <p> |
| 757 | If MACH_RCV_TIMEOUT is used without MACH_RCV_INTERRUPT, then the |
| 758 | timeout duration might not be accurate. When the call is interrupted |
| 759 | and automatically retried, the original timeout is used. If |
| 760 | interrupts occur frequently enough, the timeout interval might never |
| 761 | expire. MACH_SEND_TIMEOUT without MACH_SEND_INTERRUPT suffers from the |
| 762 | same problem. |
| 763 | <h3>RETURN VALUES</h3> |
| 764 | <p> |
| 765 | The send operation can generate the following return codes. These |
| 766 | return codes imply that the call did nothing: |
| 767 | <dl> |
| 768 | <p> |
| 769 | <dt> MACH_SEND_MSG_TOO_SMALL |
| 770 | <dd> |
| 771 | The specified send_size was smaller than the minimum size for a |
| 772 | message. |
| 773 | <p> |
| 774 | <dt> MACH_SEND_NO_BUFFER |
| 775 | <dd> |
| 776 | A resource shortage prevented the kernel from allocating a message |
| 777 | buffer. |
| 778 | <p> |
| 779 | <dt> MACH_SEND_INVALID_DATA |
| 780 | <dd> |
| 781 | The supplied message buffer was not readable. |
| 782 | <p> |
| 783 | <dt> MACH_SEND_INVALID_HEADER |
| 784 | <dd> |
| 785 | The msgh_bits value was invalid. |
| 786 | <p> |
| 787 | <dt> MACH_SEND_INVALID_DEST |
| 788 | <dd> |
| 789 | The msgh_remote_port value was invalid. |
| 790 | <p> |
| 791 | <dt> MACH_SEND_INVALID_NOTIFY |
| 792 | <dd> |
| 793 | When using MACH_SEND_CANCEL, the notify argument did not |
| 794 | denote a valid receive right. |
| 795 | <p> |
| 796 | <dt> MACH_SEND_INVALID_REPLY |
| 797 | <dd> |
| 798 | The msgh_local_port value was invalid. |
| 799 | <p> |
| 800 | <dt> MACH_SEND_INVALID_TRAILER |
| 801 | <dd> |
| 802 | The trailer to be sent does not correspond to the current kernel format, |
| 803 | or the sending task does not have the privilege to supply the message |
| 804 | attributes. |
| 805 | </dl> |
| 806 | <p> |
| 807 | These return codes imply that some or all of the message was destroyed: |
| 808 | <dl> |
| 809 | <p> |
| 810 | <dt> MACH_SEND_INVALID_MEMORY |
| 811 | <dd> |
| 812 | The message body specified out-of-line data that was not readable. |
| 813 | <p> |
| 814 | <dt> MACH_SEND_INVALID_RIGHT |
| 815 | <dd> |
| 816 | The message body specified a port right which the caller didn't possess. |
| 817 | <p> |
| 818 | <dt> MACH_SEND_INVALID_TYPE |
| 819 | <dd> |
| 820 | A kernel processed descriptor was invalid. |
| 821 | <p> |
| 822 | <dt> MACH_SEND_MSG_TOO_SMALL |
| 823 | <dd> |
| 824 | The last data item in the message ran over the end of the message. |
| 825 | </dl> |
| 826 | <p> |
| 827 | These return codes imply that the message was returned to the caller with a |
| 828 | pseudo-receive operation: |
| 829 | <dl> |
| 830 | <p> |
| 831 | <dt> MACH_SEND_TIMED_OUT |
| 832 | <dd> |
| 833 | The timeout interval expired. |
| 834 | <p> |
| 835 | <dt> MACH_SEND_INTERRUPTED |
| 836 | <dd> |
| 837 | A software interrupt occurred. |
| 838 | </dl> |
| 839 | <p> |
| 840 | This return code implies that the message was queued: |
| 841 | <dl> |
| 842 | <p> |
| 843 | <dt> MACH_MSG_SUCCESS |
| 844 | <dd> |
| 845 | The message was queued. |
| 846 | </dl> |
| 847 | <p> |
| 848 | The receive operation can generate the following return codes. These return |
| 849 | codes imply that the call did not de-queue a message: |
| 850 | <dl> |
| 851 | <p> |
| 852 | <dt> MACH_RCV_INVALID_NAME |
| 853 | <dd> |
| 854 | The specified receive_name was invalid. |
| 855 | <p> |
| 856 | <dt> MACH_RCV_IN_SET |
| 857 | <dd> |
| 858 | The specified port was a member of a port set. |
| 859 | <p> |
| 860 | <dt> MACH_RCV_TIMED_OUT |
| 861 | <dd> |
| 862 | The timeout interval expired. |
| 863 | <p> |
| 864 | <dt> MACH_RCV_INTERRUPTED |
| 865 | <dd> |
| 866 | A software interrupt occurred. |
| 867 | <p> |
| 868 | <dt> MACH_RCV_PORT_DIED |
| 869 | <dd> |
| 870 | The caller lost the rights specified by receive_name. |
| 871 | <p> |
| 872 | <dt> MACH_RCV_PORT_CHANGED |
| 873 | <dd> |
| 874 | receive_name specified a receive right which was moved into a port set |
| 875 | during the call. |
| 876 | <p> |
| 877 | <dt> MACH_RCV_TOO_LARGE |
| 878 | <dd> |
| 879 | When using MACH_RCV_LARGE, the message was larger than |
| 880 | receive_limit. The message is left queued, and its actual size is |
| 881 | returned in the message header/message body. |
| 882 | <p> |
| 883 | <dt> MACH_RCV_SCATTER_SMALL |
| 884 | <dd> |
| 885 | When using MACH_RCV_LARGE with MACH_RCV_OVERWRITE, one or more scatter |
| 886 | list descriptors specified an overwrite region smaller than the |
| 887 | corresponding incoming region. The message is left queued, and the |
| 888 | proper descriptors are returned in the message header/message body. |
| 889 | <p> |
| 890 | <dt> MACH_RCV_INVALID_TRAILER |
| 891 | <dd> |
| 892 | The trailer type desired, or the number of trailer elements desired, is |
| 893 | not supported by the kernel. |
| 894 | </dl> |
| 895 | <p> |
| 896 | These return codes imply that a message was de-queued and destroyed: |
| 897 | <dl> |
| 898 | <p> |
| 899 | <dt> MACH_RCV_HEADER_ERROR |
| 900 | <dd> |
| 901 | A resource shortage prevented the reception of the port rights in the |
| 902 | message header. |
| 903 | <p> |
| 904 | <dt> MACH_RCV_INVALID_NOTIFY |
| 905 | <dd> |
| 906 | When using MACH_RCV_NOTIFY, the notify argument did not denote a |
| 907 | valid receive right. |
| 908 | <p> |
| 909 | <dt> MACH_RCV_INVALID_DATA |
| 910 | <dd> |
| 911 | The specified message buffer was not writable. |
| 912 | <p> |
| 913 | <dt> MACH_RCV_TOO_LARGE |
| 914 | <dd> |
| 915 | When not using MACH_RCV_LARGE, a message larger than |
| 916 | receive_limit was de-queued and destroyed. |
| 917 | <p> |
| 918 | <dt> MACH_RCV_SCATTER_SMALL |
| 919 | <dd> |
| 920 | When not using MACH_RCV_LARGE with MACH_RCV_OVERWRITE, one or more |
| 921 | scatter list descriptors specified an overwrite region smaller than |
| 922 | the corresponding incoming region. The message was de-queued and |
| 923 | destroyed. |
| 924 | <p> |
| 925 | <dt> MACH_RCV_OVERWRITE_ERROR |
| 926 | <dd> |
| 927 | A region specified by a receive overwrite descriptor |
| 928 | (MACH_RCV_OVERWRITE) was not allocated or could not be written. |
| 929 | <p> |
| 930 | <dt> MACH_RCV_INVALID_TYPE |
| 931 | <dd> |
| 932 | When using MACH_RCV_OVERWRITE, one or more scatter list descriptors |
| 933 | did not have the type matching the corresponding incoming message |
| 934 | descriptor or had an invalid copy (disposition) field. |
| 935 | <p> |
| 936 | <dt> MACH_RCV_LIMITS |
| 937 | <dd> |
| 938 | The combined size of all out-of-line memory regions or the total num- |
| 939 | ber of port rights in the message exceeds the limit set for the port. |
| 940 | These return codes imply that a message was received: |
| 941 | <p> |
| 942 | <dt> MACH_RCV_BODY_ERROR |
| 943 | <dd> |
| 944 | A resource shortage prevented the reception of a port right or out-of- |
| 945 | line memory region in the message body. |
| 946 | <p> |
| 947 | <dt> MACH_MSG_SUCCESS |
| 948 | <dd> |
| 949 | A message was received. |
| 950 | </dl> |
| 951 | <p> |
| 952 | Resource shortages can occur after a message is de-queued, while |
| 953 | transferring port rights and out-of-line memory regions to the |
| 954 | receiving task. The <strong>mach_msg</strong> call returns MACH_RCV_HEADER_ERROR or |
| 955 | MACH_RCV_BODY_ERROR in this situation. These return codes always carry |
| 956 | extra bits (bitwise-or'ed) that indicate the nature of the resource |
| 957 | shortage: |
| 958 | <dl> |
| 959 | <p> |
| 960 | <dt> MACH_MSG_IPC_SPACE |
| 961 | <dd> |
| 962 | There was no room in the task's IPC name space for another port name. |
| 963 | <p> |
| 964 | <dt> MACH_MSG_VM_SPACE |
| 965 | <dd> |
| 966 | There was no room in the task's VM address space for an out-of-line |
| 967 | memory region. |
| 968 | <p> |
| 969 | <dt> MACH_MSG_IPC_KERNEL |
| 970 | <dd> |
| 971 | A kernel resource shortage prevented the reception of a port right. |
| 972 | <p> |
| 973 | <dt> MACH_MSG_VM_KERNEL |
| 974 | <dd> |
| 975 | A kernel resource shortage prevented the reception of an out-of-line |
| 976 | memory region. |
| 977 | </dl> |
| 978 | <h3>RELATED INFORMATION</h3> |
| 979 | <p> |
| 980 | Functions: |
| 981 | <a href="vm_allocate.html"><strong>vm_allocate</strong></a>, |
| 982 | <a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>, |
| 983 | <a href="vm_write.html"><strong>vm_write</strong></a>, |
| 984 | <a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>, |
| 985 | <p> |
| 986 | Data Structures: |
| 987 | mach_msg_header. |