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