4. Inter Process Communication

This chapter describes the details of the Mach IPC system. First the actual calls concerned with sending and receiving messages are discussed, then the details of the port system are described in detail.

4.1 Major Concepts

The Mach kernel provides message-oriented, capability-based interprocess communication. The interprocess communication (IPC) primitives efficiently support many different styles of interaction, including remote procedure calls (RPC), object-oriented distributed programming, streaming of data, and sending very large amounts of data.

The IPC primitives operate on three abstractions: messages, ports, and port sets. User tasks access all other kernel services and abstractions via the IPC primitives.

The message primitives let tasks send and receive messages. Tasks send messages to ports. Messages sent to a port are delivered reliably (messages may not be lost) and are received in the order in which they were sent. Messages contain a fixed-size header and a variable amount of typed data following the header. The header describes the destination and size of the message.

The IPC implementation makes use of the VM system to efficiently transfer large amounts of data. The message body can contain the address of a region in the sender's address space which should be transferred as part of the message. When a task receives a message containing an out-of-line region of data, the data appears in an unused portion of the receiver's address space. This transmission of out-of-line data is optimized so that sender and receiver share the physical pages of data copy-on-write, and no actual data copy occurs unless the pages are written. Regions of memory up to the size of a full address space may be sent in this manner.

Ports hold a queue of messages. Tasks operate on a port to send and receive messages by exercising capabilities for the port. Multiple tasks can hold send capabilities, or rights, for a port. Tasks can also hold send-once rights, which grant the ability to send a single message. Only one task can hold the receive capability, or receive right, for a port. Port rights can be transferred between tasks via messages. The sender of a message can specify in the message body that the message contains a port right. If a message contains a receive right for a port, then the receive right is removed from the sender of the message and the right is transferred to the receiver of the message. While the receive right is in transit, tasks holding send rights can still send messages to the port, and they are queued until a task acquires the receive right and uses it to receive the messages.

Tasks can receive messages from ports and port sets. The port set abstraction allows a single thread to wait for a message from any of several ports. Tasks manipulate port sets with a capability, or port-set right, which is taken from the same space as the port capabilities. The port-set right may not be transferred in a message. A port set holds receive rights, and a receive operation on a port set blocks waiting for a message sent to any of the constituent ports. A port may not belong to more than one port set, and if a port is a member of a port set, the holder of the receive right can't receive directly from the port.

Port rights are a secure, location-independent way of naming ports. The port queue is a protected data structure, only accessible via the kernel's exported message primitives. Rights are also protected by the kernel; there is no way for a malicious user task to guess a port name and send a message to a port to which it shouldn't have access. Port rights do not carry any location information. When a receive right for a port moves from task to task, and even between tasks on different machines, the send rights for the port remain unchanged and continue to function.

4.2 Messaging Interface

This section describes how messages are composed, sent and received within the Mach IPC system.

4.2.1 Mach Message Call

To use the mach_msg call, you can include the header files `mach/port.h' and `mach/message.h'.

Function: mach_msg_return_t mach_msg (mach_msg_header_t *msg, mach_msg_option_t option, mach_msg_size_t send_size, mach_msg_size_t rcv_size, mach_port_t rcv_name, mach_msg_timeout_t timeout, mach_port_t notify)

The mach_msg function is used to send and receive messages. Mach messages contain typed data, which can include port rights and references to large regions of memory.

msg is the address of a buffer in the caller's address space. Message buffers should be aligned on long-word boundaries. The message options option are bit values, combined with bitwise-or. One or both of MACH_SEND_MSG and MACH_RCV_MSG should be used. Other options act as modifiers. When sending a message, send_size specifies the size of the message buffer. Otherwise zero should be supplied. When receiving a message, rcv_size specifies the size of the message buffer. Otherwise zero should be supplied. When receiving a message, rcv_name specifies the port or port set. Otherwise MACH_PORT_NULL should be supplied. When using the MACH_SEND_TIMEOUT and MACH_RCV_TIMEOUT options, timeout specifies the time in milliseconds to wait before giving up. Otherwise MACH_MSG_TIMEOUT_NONE should be supplied. When using the MACH_SEND_NOTIFY, MACH_SEND_CANCEL, and MACH_RCV_NOTIFY options, notify specifies the port used for the notification. Otherwise MACH_PORT_NULL should be supplied.

If the option argument is MACH_SEND_MSG, it sends a message. The send_size argument specifies the size of the message to send. The msgh_remote_port field of the message header specifies the destination of the message.

If the option argument is MACH_RCV_MSG, it receives a message. The rcv_size argument specifies the size of the message buffer that will receive the message; messages larger than rcv_size are not received. The rcv_name argument specifies the port or port set from which to receive.

If the option argument is MACH_SEND_MSG|MACH_RCV_MSG, then mach_msg does both send and receive operations. If the send operation encounters an error (any return code other than MACH_MSG_SUCCESS), then the call returns immediately without attempting the receive operation. Semantically the combined call is equivalent to separate send and receive calls, but it saves a system call and enables other internal optimizations.

If the option argument specifies neither MACH_SEND_MSG nor MACH_RCV_MSG, then mach_msg does nothing.

Some options, like MACH_SEND_TIMEOUT and MACH_RCV_TIMEOUT, share a supporting argument. If these options are used together, they make independent use of the supporting argument's value.

Data type: mach_msg_timeout_t

This is a natural_t used by the timeout mechanism. The units are milliseconds. The value to be used when there is no timeout is MACH_MSG_TIMEOUT_NONE.

4.2.2 Message Format

A Mach message consists of a fixed size message header, a mach_msg_header_t, followed by zero or more data items. Data items are typed. Each item has a type descriptor followed by the actual data (or the address of the data, for out-of-line memory regions).

The following data types are related to Mach ports:

Data type: mach_port_t

The mach_port_t data type is an unsigned integer type which represents a port name in the task's port name space. In GNU Mach, this is an unsigned int.

The following data types are related to Mach messages:

Data type: mach_msg_bits_t

The mach_msg_bits_t data type is an unsigned int used to store various flags for a message.

Data type: mach_msg_size_t

The mach_msg_size_t data type is an unsigned int used to store the size of a message.

Data type: mach_msg_id_t

The mach_msg_id_t data type is an integer_t typically used to convey a function or operation id for the receiver.

Data type: mach_msg_header_t

This structure is the start of every message in the Mach IPC system. It has the following members:

mach_msg_bits_t msgh_bits

The msgh_bits field has the following bits defined, all other bits should be zero:

MACH_MSGH_BITS_REMOTE_MASK

MACH_MSGH_BITS_LOCAL_MASK

The remote and local bits encode mach_msg_type_name_t values that specify the port rights in the msgh_remote_port and msgh_local_port fields. The remote value must specify a send or send-once right for the destination of the message. If the local value doesn't specify a send or send-once right for the message's reply port, it must be zero and msgh_local_port must be MACH_PORT_NULL.

MACH_MSGH_BITS_COMPLEX

The complex bit must be specified if the message body contains port rights or out-of-line memory regions. If it is not specified, then the message body carries no port rights or memory, no matter what the type descriptors may seem to indicate.

MACH_MSGH_BITS_REMOTE and MACH_MSGH_BITS_LOCAL macros return the appropriate mach_msg_type_name_t values, given a msgh_bits value. The MACH_MSGH_BITS macro constructs a value for msgh_bits, given two mach_msg_type_name_t values.

mach_msg_size_t msgh_size

The msgh_size field in the header of a received message contains the message's size. The message size, a byte quantity, includes the message header, type descriptors, and in-line data. For out-of-line memory regions, the message size includes the size of the in-line address, not the size of the actual memory region. There are no arbitrary limits on the size of a Mach message, the number of data items in a message, or the size of the data items.

mach_port_t msgh_remote_port

The msgh_remote_port field specifies the destination port of the message. The field must carry a legitimate send or send-once right for a port.

mach_port_t msgh_local_port

The msgh_local_port field specifies an auxiliary port right, which is conventionally used as a reply port by the recipient of the message. The field must carry a send right, a send-once right, MACH_PORT_NULL, or MACH_PORT_DEAD.

mach_port_seqno_t msgh_seqno

The msgh_seqno field provides a sequence number for the message. It is only valid in received messages; its value in sent messages is overwritten.

mach_msg_id_t msgh_id

The mach_msg call doesn't use the msgh_id field, but it conventionally conveys an operation or function id.

Macro: mach_msg_bits_t MACH_MSGH_BITS (mach_msg_type_name_t remote, mach_msg_type_name_t local)

This macro composes two mach_msg_type_name_t values that specify the port rights in the msgh_remote_port and msgh_local_port fields of a mach_msg call into an appropriate mach_msg_bits_t value.

Macro: mach_msg_type_name_t MACH_MSGH_BITS_REMOTE (mach_msg_bits_t bits)

This macro extracts the mach_msg_type_name_t value for the remote port right in a mach_msg_bits_t value.

Macro: mach_msg_type_name_t MACH_MSGH_BITS_LOCAL (mach_msg_bits_t bits)

This macro extracts the mach_msg_type_name_t value for the local port right in a mach_msg_bits_t value.

Macro: mach_msg_bits_t MACH_MSGH_BITS_PORTS (mach_msg_bits_t bits)

This macro extracts the mach_msg_bits_t component consisting of the mach_msg_type_name_t values for the remote and local port right in a mach_msg_bits_t value.

Macro: mach_msg_bits_t MACH_MSGH_BITS_OTHER (mach_msg_bits_t bits)

This macro extracts the mach_msg_bits_t component consisting of everything except the mach_msg_type_name_t values for the remote and local port right in a mach_msg_bits_t value.

Each data item has a type descriptor, a mach_msg_type_t or a mach_msg_type_long_t. The mach_msg_type_long_t type descriptor allows larger values for some fields. The msgtl_header field in the long descriptor is only used for its inline, longform, and deallocate bits.

Data type: mach_msg_type_name_t

This is an unsigned int and can be used to hold the msgt_name component of the mach_msg_type_t and mach_msg_type_long_t structure.

Data type: mach_msg_type_size_t

This is an unsigned int and can be used to hold the msgt_size component of the mach_msg_type_t and mach_msg_type_long_t structure.

Data type: mach_msg_type_number_t

This is an natural_t and can be used to hold the msgt_number component of the mach_msg_type_t and mach_msg_type_long_t structure.

Data type: mach_msg_type_t

This structure has the following members:

unsigned int msgt_name : 8

The msgt_name field specifies the data's type. The following types are predefined:

MACH_MSG_TYPE_UNSTRUCTURED

MACH_MSG_TYPE_BIT

MACH_MSG_TYPE_BOOLEAN

MACH_MSG_TYPE_INTEGER_16

MACH_MSG_TYPE_INTEGER_32

MACH_MSG_TYPE_CHAR

MACH_MSG_TYPE_BYTE

MACH_MSG_TYPE_INTEGER_8

MACH_MSG_TYPE_REAL

MACH_MSG_TYPE_STRING

MACH_MSG_TYPE_STRING_C

MACH_MSG_TYPE_PORT_NAME

The following predefined types specify port rights, and receive special treatment. The next section discusses these types in detail. The type MACH_MSG_TYPE_PORT_NAME describes port right names, when no rights are being transferred, but just names. For this purpose, it should be used in preference to MACH_MSG_TYPE_INTEGER_32.

MACH_MSG_TYPE_MOVE_RECEIVE

MACH_MSG_TYPE_MOVE_SEND

MACH_MSG_TYPE_MOVE_SEND_ONCE

MACH_MSG_TYPE_COPY_SEND

MACH_MSG_TYPE_MAKE_SEND

MACH_MSG_TYPE_MAKE_SEND_ONCE

msgt_size : 8

The msgt_size field specifies the size of each datum, in bits. For example, the msgt_size of MACH_MSG_TYPE_INTEGER_32 data is 32.

msgt_number : 12

The msgt_number field specifies how many data elements comprise the data item. Zero is a legitimate number.

The total length specified by a type descriptor is (msgt_size * msgt_number), rounded up to an integral number of bytes. In-line data is then padded to an integral number of long-words. This ensures that type descriptors always start on long-word boundaries. It implies that message sizes are always an integral multiple of a long-word's size.

msgt_inline : 1

The msgt_inline bit specifies, when FALSE, that the data actually resides in an out-of-line region. The address of the memory region (a vm_offset_t or vm_address_t) follows the type descriptor in the message body. The msgt_name, msgt_size, and msgt_number fields describe the memory region, not the address.

msgt_longform : 1

The msgt_longform bit specifies, when TRUE, that this type descriptor is a mach_msg_type_long_t instead of a mach_msg_type_t. The msgt_name, msgt_size, and msgt_number fields should be zero. Instead, mach_msg uses the following msgtl_name, msgtl_size, and msgtl_number fields.

msgt_deallocate : 1

The msgt_deallocate bit is used with out-of-line regions. When TRUE, it specifies that the memory region should be deallocated from the sender's address space (as if with vm_deallocate) when the message is sent.

msgt_unused : 1

The msgt_unused bit should be zero.

Macro: boolean_t MACH_MSG_TYPE_PORT_ANY (mach_msg_type_name_t type)

This macro returns TRUE if the given type name specifies a port type, otherwise it returns FALSE.

Macro: boolean_t MACH_MSG_TYPE_PORT_ANY_SEND (mach_msg_type_name_t type)

This macro returns TRUE if the given type name specifies a port type with a send or send-once right, otherwise it returns FALSE.

Macro: boolean_t MACH_MSG_TYPE_PORT_ANY_RIGHT (mach_msg_type_name_t type)

This macro returns TRUE if the given type name specifies a port right type which is moved, otherwise it returns FALSE.

Data type: mach_msg_type_long_t

This structure has the following members:

mach_msg_type_t msgtl_header

Same meaning as msgt_header.

unsigned short msgtl_name

Same meaning as msgt_name.

unsigned short msgtl_size

Same meaning as msgt_size.

unsigned int msgtl_number

Same meaning as msgt_number.

4.2.3 Exchanging Port Rights

Each task has its own space of port rights. Port rights are named with positive integers. Except for the reserved values MACH_PORT_NULL (0)(3) and MACH_PORT_DEAD (~0), this is a full 32-bit name space. When the kernel chooses a name for a new right, it is free to pick any unused name (one which denotes no right) in the space.

There are five basic kinds of rights: receive rights, send rights, send-once rights, port-set rights, and dead names. Dead names are not capabilities. They act as place-holders to prevent a name from being otherwise used.

A port is destroyed, or dies, when its receive right is deallocated. When a port dies, send and send-once rights for the port turn into dead names. Any messages queued at the port are destroyed, which deallocates the port rights and out-of-line memory in the messages.

Tasks may hold multiple user-references for send rights and dead names. When a task receives a send right which it already holds, the kernel increments the right's user-reference count. When a task deallocates a send right, the kernel decrements its user-reference count, and the task only loses the send right when the count goes to zero.

Send-once rights always have a user-reference count of one, although a port can have multiple send-once rights, because each send-once right held by a task has a different name. In contrast, when a task holds send rights or a receive right for a port, the rights share a single name.

A message body can carry port rights; the msgt_name (msgtl_name) field in a type descriptor specifies the type of port right and how the port right is to be extracted from the caller. The values MACH_PORT_NULL and MACH_PORT_DEAD are always valid in place of a port right in a message body. In a sent message, the following msgt_name values denote port rights:

MACH_MSG_TYPE_MAKE_SEND

The message will carry a send right, but the caller must supply a receive right. The send right is created from the receive right, and the receive right's make-send count is incremented.

MACH_MSG_TYPE_COPY_SEND

The message will carry a send right, and the caller should supply a send right. The user reference count for the supplied send right is not changed. The caller may also supply a dead name and the receiving task will get MACH_PORT_DEAD.

MACH_MSG_TYPE_MOVE_SEND

The message will carry a send right, and the caller should supply a send right. The user reference count for the supplied send right is decremented, and the right is destroyed if the count becomes zero. Unless a receive right remains, the name becomes available for recycling. The caller may also supply a dead name, which loses a user reference, and the receiving task will get MACH_PORT_DEAD.

MACH_MSG_TYPE_MAKE_SEND_ONCE

The message will carry a send-once right, but the caller must supply a receive right. The send-once right is created from the receive right.

MACH_MSG_TYPE_MOVE_SEND_ONCE

The message will carry a send-once right, and the caller should supply a send-once right. The caller loses the supplied send-once right. The caller may also supply a dead name, which loses a user reference, and the receiving task will get MACH_PORT_DEAD.

MACH_MSG_TYPE_MOVE_RECEIVE

The message will carry a receive right, and the caller should supply a receive right. The caller loses the supplied receive right, but retains any send rights with the same name.

If a message carries a send or send-once right, and the port dies while the message is in transit, then the receiving task will get MACH_PORT_DEAD instead of a right. The following msgt_name values in a received message indicate that it carries port rights:

MACH_MSG_TYPE_PORT_SEND

This name is an alias for MACH_MSG_TYPE_MOVE_SEND. The message carried a send right. If the receiving task already has send and/or receive rights for the port, then that name for the port will be reused. Otherwise, the new right will have a new name. If the task already has send rights, it gains a user reference for the right (unless this would cause the user-reference count to overflow). Otherwise, it acquires the send right, with a user-reference count of one.

MACH_MSG_TYPE_PORT_SEND_ONCE

This name is an alias for MACH_MSG_TYPE_MOVE_SEND_ONCE. The message carried a send-once right. The right will have a new name.

MACH_MSG_TYPE_PORT_RECEIVE

This name is an alias for MACH_MSG_TYPE_MOVE_RECEIVE. The message carried a receive right. If the receiving task already has send rights for the port, then that name for the port will be reused. Otherwise, the right will have a new name. The make-send count of the receive right is reset to zero, but the port retains other attributes like queued messages, extant send and send-once rights, and requests for port-destroyed and no-senders notifications.

When the kernel chooses a new name for a port right, it can choose any name, other than MACH_PORT_NULL and MACH_PORT_DEAD, which is not currently being used for a port right or dead name. It might choose a name which at some previous time denoted a port right, but is currently unused.

4.2.4 Memory

A message body can contain the address of a region in the sender's address space which should be transferred as part of the message. The message carries a logical copy of the memory, but the kernel uses VM techniques to defer any actual page copies. Unless the sender or the receiver modifies the data, the physical pages remain shared.

An out-of-line transfer occurs when the data's type descriptor specifies msgt_inline as FALSE. The address of the memory region (a vm_offset_t or vm_address_t) should follow the type descriptor in the message body. The type descriptor and the address contribute to the message's size (send_size, msgh_size). The out-of-line data does not contribute to the message's size.

The name, size, and number fields in the type descriptor describe the type and length of the out-of-line data, not the in-line address. Out-of-line memory frequently requires long type descriptors (mach_msg_type_long_t), because the msgt_number field is too small to describe a page of 4K bytes.

Out-of-line memory arrives somewhere in the receiver's address space as new memory. It has the same inheritance and protection attributes as newly vm_allocate'd memory. The receiver has the responsibility of deallocating (with vm_deallocate) the memory when it is no longer needed. Security-conscious receivers should exercise caution when using out-of-line memory from untrustworthy sources, because the memory may be backed by an unreliable memory manager.

Null out-of-line memory is legal. If the out-of-line region size is zero (for example, because msgtl_number is zero), then the region's specified address is ignored. A received null out-of-line memory region always has a zero address.

Unaligned addresses and region sizes that are not page multiples are legal. A received message can also contain memory with unaligned addresses and funny sizes. In the general case, the first and last pages in the new memory region in the receiver do not contain only data from the sender, but are partly zero.(4) The received address points to the start of the data in the first page. This possibility doesn't complicate deallocation, because vm_deallocate does the right thing, rounding the start address down and the end address up to deallocate all arrived pages.

Out-of-line memory has a deallocate option, controlled by the msgt_deallocate bit. If it is TRUE and the out-of-line memory region is not null, then the region is implicitly deallocated from the sender, as if by vm_deallocate. In particular, the start and end addresses are rounded so that every page overlapped by the memory region is deallocated. The use of msgt_deallocate effectively changes the memory copy into a memory movement. In a received message, msgt_deallocate is TRUE in type descriptors for out-of-line memory.

Out-of-line memory can carry port rights.

4.2.5 Message Send

The send operation queues a message to a port. The message carries a copy of the caller's data. After the send, the caller can freely modify the message buffer or the out-of-line memory regions and the message contents will remain unchanged.

Message delivery is reliable and sequenced. Messages are not lost, and messages sent to a port, from a single thread, are received in the order in which they were sent.

If the destination port's queue is full, then several things can happen. If the message is sent to a send-once right (msgh_remote_port carries a send-once right), then the kernel ignores the queue limit and delivers the message. Otherwise the caller blocks until there is room in the queue, unless the MACH_SEND_TIMEOUT or MACH_SEND_NOTIFY options are used. If a port has several blocked senders, then any of them may queue the next message when space in the queue becomes available, with the proviso that a blocked sender will not be indefinitely starved.

These options modify MACH_SEND_MSG. If MACH_SEND_MSG is not also specified, they are ignored.

MACH_SEND_TIMEOUT

The timeout argument should specify a maximum time (in milliseconds) for the call to block before giving up.(5) If the message can't be queued before the timeout interval elapses, then the call returns MACH_SEND_TIMED_OUT. A zero timeout is legitimate.

MACH_SEND_NOTIFY

The notify argument should specify a receive right for a notify port. If the send were to block, then instead the message is queued, MACH_SEND_WILL_NOTIFY is returned, and a msg-accepted notification is requested. If MACH_SEND_TIMEOUT is also specified, then MACH_SEND_NOTIFY doesn't take effect until the timeout interval elapses.

With MACH_SEND_NOTIFY, a task can forcibly queue to a send right one message at a time. A msg-accepted notification is sent to the the notify port when another message can be forcibly queued. If an attempt is made to use MACH_SEND_NOTIFY before then, the call returns a MACH_SEND_NOTIFY_IN_PROGRESS error.

The msg-accepted notification carries the name of the send right. If the send right is deallocated before the msg-accepted notification is generated, then the msg-accepted notification carries the value MACH_PORT_NULL. If the destination port is destroyed before the notification is generated, then a send-once notification is generated instead.

MACH_SEND_INTERRUPT

If specified, the mach_msg call will return MACH_SEND_INTERRUPTED if a software interrupt aborts the call. Otherwise, the send operation will be retried.

MACH_SEND_CANCEL

The notify argument should specify a receive right for a notify port. If the send operation removes the destination port right from the caller, and the removed right had a dead-name request registered for it, and notify is the notify port for the dead-name request, then the dead-name request may be silently canceled (instead of resulting in a port-deleted notification).

This option is typically used to cancel a dead-name request made with the MACH_RCV_NOTIFY option. It should only be used as an optimization.

The send operation can generate the following return codes. These return codes imply that the call did nothing:

MACH_SEND_MSG_TOO_SMALL

The specified send_size was smaller than the minimum size for a message.

MACH_SEND_NO_BUFFER

A resource shortage prevented the kernel from allocating a message buffer.

MACH_SEND_INVALID_DATA

The supplied message buffer was not readable.

MACH_SEND_INVALID_HEADER

The msgh_bits value was invalid.

MACH_SEND_INVALID_DEST

The msgh_remote_port value was invalid.

MACH_SEND_INVALID_REPLY

The msgh_local_port value was invalid.

MACH_SEND_INVALID_NOTIFY

When using MACH_SEND_CANCEL, the notify argument did not denote a valid receive right.

These return codes imply that some or all of the message was destroyed:

MACH_SEND_INVALID_MEMORY

The message body specified out-of-line data that was not readable.

MACH_SEND_INVALID_RIGHT

The message body specified a port right which the caller didn't possess.

MACH_SEND_INVALID_TYPE

A type descriptor was invalid.

MACH_SEND_MSG_TOO_SMALL

The last data item in the message ran over the end of the message.

These return codes imply that the message was returned to the caller with a pseudo-receive operation:

MACH_SEND_TIMED_OUT

The timeout interval expired.

MACH_SEND_INTERRUPTED

A software interrupt occurred.

MACH_SEND_INVALID_NOTIFY

When using MACH_SEND_NOTIFY, the notify argument did not denote a valid receive right.

MACH_SEND_NO_NOTIFY

A resource shortage prevented the kernel from setting up a msg-accepted notification.

MACH_SEND_NOTIFY_IN_PROGRESS

A msg-accepted notification was already requested, and hasn't yet been generated.

These return codes imply that the message was queued:

MACH_SEND_WILL_NOTIFY

The message was forcibly queued, and a msg-accepted notification was requested.

MACH_MSG_SUCCESS

The message was queued.

Some return codes, like MACH_SEND_TIMED_OUT, imply that the message was almost sent, but could not be queued. In these situations, the kernel tries to return the message contents to the caller with a pseudo-receive operation. This prevents the loss of port rights or memory which only exist in the message. For example, a receive right which was moved into the message, or out-of-line memory sent with the deallocate bit.

The pseudo-receive operation is very similar to a normal receive operation. The pseudo-receive handles the port rights in the message header as if they were in the message body. They are not reversed. After the pseudo-receive, the message is ready to be resent. If the message is not resent, note that out-of-line memory regions may have moved and some port rights may have changed names.

The pseudo-receive operation may encounter resource shortages. This is similar to a MACH_RCV_BODY_ERROR return code from a receive operation. When this happens, the normal send return codes are augmented with the MACH_MSG_IPC_SPACE, MACH_MSG_VM_SPACE, MACH_MSG_IPC_KERNEL, and MACH_MSG_VM_KERNEL bits to indicate the nature of the resource shortage.

The queueing of a message carrying receive rights may create a circular loop of receive rights and messages, which can never be received. For example, a message carrying a receive right can be sent to that receive right. This situation is not an error, but the kernel will garbage-collect such loops, destroying the messages and ports involved.

4.2.6 Message Receive

The receive operation dequeues a message from a port. The receiving task acquires the port rights and out-of-line memory regions carried in the message.

The rcv_name argument specifies a port or port set from which to receive. If a port is specified, the caller must possess the receive right for the port and the port must not be a member of a port set. If no message is present, then the call blocks, subject to the MACH_RCV_TIMEOUT option.

If a port set is specified, the call will receive a message sent to any of the member ports. It is permissible for the port set to have no member ports, and ports may be added and removed while a receive from the port set is in progress. The received message can come from any of the member ports which have messages, with the proviso that a member port with messages will not be indefinitely starved. The msgh_local_port field in the received message header specifies from which port in the port set the message came.

The rcv_size argument specifies the size of the caller's message buffer. The mach_msg call will not receive a message larger than rcv_size. Messages that are too large are destroyed, unless the MACH_RCV_LARGE option is used.

The destination and reply ports are reversed in a received message header. The msgh_local_port field names the destination port, from which the message was received, and the msgh_remote_port field names the reply port right. The bits in msgh_bits are also reversed. The MACH_MSGH_BITS_LOCAL bits have the value MACH_MSG_TYPE_PORT_SEND if the message was sent to a send right, and the value MACH_MSG_TYPE_PORT_SEND_ONCE if was sent to a send-once right. The MACH_MSGH_BITS_REMOTE bits describe the reply port right.

A received message can contain port rights and out-of-line memory. The msgh_local_port field does not receive a port right; the act of receiving the message destroys the send or send-once right for the destination port. The msgh_remote_port field does name a received port right, the reply port right, and the message body can carry port rights and memory if MACH_MSGH_BITS_COMPLEX is present in msgh_bits. Received port rights and memory should be consumed or deallocated in some fashion.

In almost all cases, msgh_local_port will specify the name of a receive right, either rcv_name or if rcv_name is a port set, a member of rcv_name. If other threads are concurrently manipulating the receive right, the situation is more complicated. If the receive right is renamed during the call, then msgh_local_port specifies the right's new name. If the caller loses the receive right after the message was dequeued from it, then mach_msg will proceed instead of returning MACH_RCV_PORT_DIED. If the receive right was destroyed, then msgh_local_port specifies MACH_PORT_DEAD. If the receive right still exists, but isn't held by the caller, then msgh_local_port specifies MACH_PORT_NULL.

Received messages are stamped with a sequence number, taken from the port from which the message was received. (Messages received from a port set are stamped with a sequence number from the appropriate member port.) Newly created ports start with a zero sequence number, and the sequence number is reset to zero whenever the port's receive right moves between tasks. When a message is dequeued from the port, it is stamped with the port's sequence number and the port's sequence number is then incremented. The dequeue and increment operations are atomic, so that multiple threads receiving messages from a port can use the msgh_seqno field to reconstruct the original order of the messages.

These options modify MACH_RCV_MSG. If MACH_RCV_MSG is not also specified, they are ignored.

MACH_RCV_TIMEOUT

The timeout argument should specify a maximum time (in milliseconds) for the call to block before giving up.(6) If no message arrives before the timeout interval elapses, then the call returns MACH_RCV_TIMED_OUT. A zero timeout is legitimate.

MACH_RCV_NOTIFY

The notify argument should specify a receive right for a notify port. If receiving the reply port creates a new port right in the caller, then the notify port is used to request a dead-name notification for the new port right.

MACH_RCV_INTERRUPT

If specified, the mach_msg call will return MACH_RCV_INTERRUPTED if a software interrupt aborts the call. Otherwise, the receive operation will be retried.

MACH_RCV_LARGE

If the message is larger than rcv_size, then the message remains queued instead of being destroyed. The call returns MACH_RCV_TOO_LARGE and the actual size of the message is returned in the msgh_size field of the message header.

The receive operation can generate the following return codes. These return codes imply that the call did not dequeue a message:

MACH_RCV_INVALID_NAME

The specified rcv_name was invalid.

MACH_RCV_IN_SET

The specified port was a member of a port set.

MACH_RCV_TIMED_OUT

The timeout interval expired.

MACH_RCV_INTERRUPTED

A software interrupt occurred.

MACH_RCV_PORT_DIED

The caller lost the rights specified by rcv_name.

MACH_RCV_PORT_CHANGED

rcv_name specified a receive right which was moved into a port set during the call.

MACH_RCV_TOO_LARGE

When using MACH_RCV_LARGE, and the message was larger than rcv_size. The message is left queued, and its actual size is returned in the msgh_size field of the message buffer.

These return codes imply that a message was dequeued and destroyed:

MACH_RCV_HEADER_ERROR

A resource shortage prevented the reception of the port rights in the message header.

MACH_RCV_INVALID_NOTIFY

When using MACH_RCV_NOTIFY, the notify argument did not denote a valid receive right.

MACH_RCV_TOO_LARGE

When not using MACH_RCV_LARGE, a message larger than rcv_size was dequeued and destroyed.

In these situations, when a message is dequeued and then destroyed, the reply port and all port rights and memory in the message body are destroyed. However, the caller receives the message's header, with all fields correct, including the destination port but excepting the reply port, which is MACH_PORT_NULL.

These return codes imply that a message was received:

MACH_RCV_BODY_ERROR

A resource shortage prevented the reception of a port right or out-of-line memory region in the message body. The message header, including the reply port, is correct. The kernel attempts to transfer all port rights and memory regions in the body, and only destroys those that can't be transferred.

MACH_RCV_INVALID_DATA

The specified message buffer was not writable. The calling task did successfully receive the port rights and out-of-line memory regions in the message.

MACH_MSG_SUCCESS

A message was received.

Resource shortages can occur after a message is dequeued, while transferring port rights and out-of-line memory regions to the receiving task. The mach_msg call returns MACH_RCV_HEADER_ERROR or MACH_RCV_BODY_ERROR in this situation. These return codes always carry extra bits (bitwise-ored) that indicate the nature of the resource shortage:

MACH_MSG_IPC_SPACE

There was no room in the task's IPC name space for another port name.

MACH_MSG_VM_SPACE

There was no room in the task's VM address space for an out-of-line memory region.

MACH_MSG_IPC_KERNEL

A kernel resource shortage prevented the reception of a port right.

MACH_MSG_VM_KERNEL

A kernel resource shortage prevented the reception of an out-of-line memory region.

If a resource shortage prevents the reception of a port right, the port right is destroyed and the caller sees the name MACH_PORT_NULL. If a resource shortage prevents the reception of an out-of-line memory region, the region is destroyed and the caller receives a zero address. In addition, the msgt_size (msgtl_size) field in the data's type descriptor is changed to zero. If a resource shortage prevents the reception of out-of-line memory carrying port rights, then the port rights are always destroyed if the memory region can not be received. A task never receives port rights or memory regions that it isn't told about.

4.2.7 Atomicity

The mach_msg call handles port rights in a message header atomically. Port rights and out-of-line memory in a message body do not enjoy this atomicity guarantee. The message body may be processed front-to-back, back-to-front, first out-of-line memory then port rights, in some random order, or even atomically.

For example, consider sending a message with the destination port specified as MACH_MSG_TYPE_MOVE_SEND and the reply port specified as MACH_MSG_TYPE_COPY_SEND. The same send right, with one user-reference, is supplied for both the msgh_remote_port and msgh_local_port fields. Because mach_msg processes the message header atomically, this succeeds. If msgh_remote_port were processed before msgh_local_port, then mach_msg would return MACH_SEND_INVALID_REPLY in this situation.

On the other hand, suppose the destination and reply port are both specified as MACH_MSG_TYPE_MOVE_SEND, and again the same send right with one user-reference is supplied for both. Now the send operation fails, but because it processes the header atomically, mach_msg can return either MACH_SEND_INVALID_DEST or MACH_SEND_INVALID_REPLY.

For example, consider receiving a message at the same time another thread is deallocating the destination receive right. Suppose the reply port field carries a send right for the destination port. If the deallocation happens before the dequeuing, then the receiver gets MACH_RCV_PORT_DIED. If the deallocation happens after the receive, then the msgh_local_port and the msgh_remote_port fields both specify the same right, which becomes a dead name when the receive right is deallocated. If the deallocation happens between the dequeue and the receive, then the msgh_local_port and msgh_remote_port fields both specify MACH_PORT_DEAD. Because the header is processed atomically, it is not possible for just one of the two fields to hold MACH_PORT_DEAD.

The MACH_RCV_NOTIFY option provides a more likely example. Suppose a message carrying a send-once right reply port is received with MACH_RCV_NOTIFY at the same time the reply port is destroyed. If the reply port is destroyed first, then msgh_remote_port specifies MACH_PORT_DEAD and the kernel does not generate a dead-name notification. If the reply port is destroyed after it is received, then msgh_remote_port specifies a dead name for which the kernel generates a dead-name notification. It is not possible to receive the reply port right and have it turn into a dead name before the dead-name notification is requested; as part of the message header the reply port is received atomically.

4.3 Port Manipulation Interface

This section describes the interface to create, destroy and manipulate ports, port rights and port sets.

Data type: ipc_space_t

This is a task_t (and as such a mach_port_t), which holds a port name associated with a port that represents an IPC space in the kernel. An IPC space is used by the kernel to manage the port names and rights available to a task. The IPC space doesn't get a port name of its own. Instead the port name of the task containing the IPC space is used to name the IPC space of the task (as is indicated by the fact that the type of ipc_space_t is actually task_t).

The IPC spaces of tasks are the only ones accessible outside of the kernel.

4.3.1 Port Creation

Function: kern_return_t mach_port_allocate (ipc_space_t task, mach_port_right_t right, mach_port_t *name)

The mach_port_allocate function creates a new right in the specified task. The new right's name is returned in name, which may be any name that wasn't in use.

The right argument takes the following values:

MACH_PORT_RIGHT_RECEIVE

mach_port_allocate creates a port. The new port is not a member of any port set. It doesn't have any extant send or send-once rights. Its make-send count is zero, its sequence number is zero, its queue limit is MACH_PORT_QLIMIT_DEFAULT, and it has no queued messages. name denotes the receive right for the new port.

task does not hold send rights for the new port, only the receive right. mach_port_insert_right and mach_port_extract_right can be used to convert the receive right into a combined send/receive right.

MACH_PORT_RIGHT_PORT_SET

mach_port_allocate creates a port set. The new port set has no members.

MACH_PORT_RIGHT_DEAD_NAME

mach_port_allocate creates a dead name. The new dead name has one user reference.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_VALUE if right was invalid, KERN_NO_SPACE if there was no room in task's IPC name space for another right and KERN_RESOURCE_SHORTAGE if the kernel ran out of memory.

The mach_port_allocate call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

Function: mach_port_t mach_reply_port ()

The mach_reply_port system call creates a reply port in the calling task.

mach_reply_port creates a port, giving the calling task the receive right for the port. The call returns the name of the new receive right.

This is very much like creating a receive right with the mach_port_allocate call, with two differences. First, mach_reply_port is a system call and not an RPC (which requires a reply port). Second, the port created by mach_reply_port may be optimized for use as a reply port.

The function returns MACH_PORT_NULL if a resource shortage prevented the creation of the receive right.

Function: kern_return_t mach_port_allocate_name (ipc_space_t task, mach_port_right_t right, mach_port_t name)

The function mach_port_allocate_name creates a new right in the specified task, with a specified name for the new right. name must not already be in use for some right, and it can't be the reserved values MACH_PORT_NULL and MACH_PORT_DEAD.

The right argument takes the following values:

MACH_PORT_RIGHT_RECEIVE

mach_port_allocate_name creates a port. The new port is not a member of any port set. It doesn't have any extant send or send-once rights. Its make-send count is zero, its sequence number is zero, its queue limit is MACH_PORT_QLIMIT_DEFAULT, and it has no queued messages. name denotes the receive right for the new port.

task does not hold send rights for the new port, only the receive right. mach_port_insert_right and mach_port_extract_right can be used to convert the receive right into a combined send/receive right.

MACH_PORT_RIGHT_PORT_SET

mach_port_allocate_name creates a port set. The new port set has no members.

MACH_PORT_RIGHT_DEAD_NAME

mach_port_allocate_name creates a new dead name. The new dead name has one user reference.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_VALUE if right was invalid or name was MACH_PORT_NULL or MACH_PORT_DEAD, KERN_NAME_EXISTS if name was already in use for a port right and KERN_RESOURCE_SHORTAGE if the kernel ran out of memory.

The mach_port_allocate_name call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

4.3.2 Port Destruction

Function: kern_return_t mach_port_deallocate (ipc_space_t task, mach_port_t name)

The function mach_port_deallocate releases a user reference for a right in task's IPC name space. It allows a task to release a user reference for a send or send-once right without failing if the port has died and the right is now actually a dead name.

If name denotes a dead name, send right, or send-once right, then the right loses one user reference. If it only had one user reference, then the right is destroyed.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_NAME if name did not denote a right and KERN_INVALID_RIGHT if name denoted an invalid right.

The mach_port_deallocate call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

Function: kern_return_t mach_port_destroy (ipc_space_t task, mach_port_t name)

The function mach_port_destroy deallocates all rights denoted by a name. The name becomes immediately available for reuse.

For most purposes, mach_port_mod_refs and mach_port_deallocate are preferable.

If name denotes a port set, then all members of the port set are implicitly removed from the port set.

If name denotes a receive right that is a member of a port set, the receive right is implicitly removed from the port set. If there is a port-destroyed request registered for the port, then the receive right is not actually destroyed, but instead is sent in a port-destroyed notification to the backup port. If there is no registered port-destroyed request, remaining messages queued to the port are destroyed and extant send and send-once rights turn into dead names. If those send and send-once rights have dead-name requests registered, then dead-name notifications are generated for them.

If name denotes a send-once right, then the send-once right is used to produce a send-once notification for the port.

If name denotes a send-once, send, and/or receive right, and it has a dead-name request registered, then the registered send-once right is used to produce a port-deleted notification for the name.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_NAME if name did not denote a right.

The mach_port_destroy call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

4.3.3 Port Names

Function: kern_return_t mach_port_names (ipc_space_t task, mach_port_array_t *names, mach_msg_type_number_t *ncount, mach_port_type_array_t *types, mach_msg_type_number_t *tcount)

The function mach_port_names returns information about task's port name space. For each name, it also returns what type of rights task holds. (The same information returned by mach_port_type.) names and types are arrays that are automatically allocated when the reply message is received. The user should vm_deallocate them when the data is no longer needed.

mach_port_names will return in names the names of the ports, port sets, and dead names in the task's port name space, in no particular order and in ncount the number of names returned. It will return in types the type of each corresponding name, which indicates what kind of rights the task holds with that name. tcount should be the same as ncount.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_RESOURCE_SHORTAGE if the kernel ran out of memory.

The mach_port_names call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

Function: kern_return_t mach_port_type (ipc_space_t task, mach_port_t name, mach_port_type_t *ptype)

The function mach_port_type returns information about task's rights for a specific name in its port name space. The returned ptype is a bitmask indicating what rights task holds for the port, port set or dead name. The bitmask is composed of the following bits:

MACH_PORT_TYPE_SEND

The name denotes a send right.

MACH_PORT_TYPE_RECEIVE

The name denotes a receive right.

MACH_PORT_TYPE_SEND_ONCE

The name denotes a send-once right.

MACH_PORT_TYPE_PORT_SET

The name denotes a port set.

MACH_PORT_TYPE_DEAD_NAME

The name is a dead name.

MACH_PORT_TYPE_DNREQUEST

A dead-name request has been registered for the right.

MACH_PORT_TYPE_MAREQUEST

A msg-accepted request for the right is pending.

MACH_PORT_TYPE_COMPAT

The port right was created in the compatibility mode.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid and KERN_INVALID_NAME if name did not denote a right.

The mach_port_type call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

Function: kern_return_t mach_port_rename (ipc_space_t task, mach_port_t old_name, mach_port_t new_name)

The function mach_port_rename changes the name by which a port, port set, or dead name is known to task. old_name is the original name and new_name the new name for the port right. new_name must not already be in use, and it can't be the distinguished values MACH_PORT_NULL and MACH_PORT_DEAD.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_NAME if old_name did not denote a right, KERN_INVALID_VALUE if new_name was MACH_PORT_NULL or MACH_PORT_DEAD, KERN_NAME_EXISTS if new_name already denoted a right and KERN_RESOURCE_SHORTAGE if the kernel ran out of memory.

The mach_port_rename call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

4.3.4 Port Rights

Function: kern_return_t mach_port_get_refs (ipc_space_t task, mach_port_t name, mach_port_right_t right, mach_port_urefs_t *refs)

The function mach_port_get_refs returns the number of user references a task has for a right.

The right argument takes the following values:

• MACH_PORT_RIGHT_SEND
• MACH_PORT_RIGHT_RECEIVE
• MACH_PORT_RIGHT_SEND_ONCE
• MACH_PORT_RIGHT_PORT_SET
• MACH_PORT_RIGHT_DEAD_NAME

If name denotes a right, but not the type of right specified, then zero is returned. Otherwise a positive number of user references is returned. Note that a name may simultaneously denote send and receive rights.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_VALUE if right was invalid and KERN_INVALID_NAME if name did not denote a right.

The mach_port_get_refs call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

Function: kern_return_t mach_port_mod_refs (ipc_space_t task, mach_port_t name, mach_port_right_t right, mach_port_delta_t delta)

The function mach_port_mod_refs requests that the number of user references a task has for a right be changed. This results in the right being destroyed, if the number of user references is changed to zero. The task holding the right is task, name should denote the specified right. right denotes the type of right being modified. delta is the signed change to the number of user references.

The right argument takes the following values:

• MACH_PORT_RIGHT_SEND
• MACH_PORT_RIGHT_RECEIVE
• MACH_PORT_RIGHT_SEND_ONCE
• MACH_PORT_RIGHT_PORT_SET
• MACH_PORT_RIGHT_DEAD_NAME

The number of user references for the right is changed by the amount delta, subject to the following restrictions: port sets, receive rights, and send-once rights may only have one user reference. The resulting number of user references can't be negative. If the resulting number of user references is zero, the effect is to deallocate the right. For dead names and send rights, there is an implementation-defined maximum number of user references.

If the call destroys the right, then the effect is as described for mach_port_destroy, with the exception that mach_port_destroy simultaneously destroys all the rights denoted by a name, while mach_port_mod_refs can only destroy one right. The name will be available for reuse if it only denoted the one right.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_VALUE if right was invalid or the user-reference count would become negative, KERN_INVALID_NAME if name did not denote a right, KERN_INVALID_RIGHT if name denoted a right, but not the specified right and KERN_UREFS_OVERFLOW if the user-reference count would overflow.

The mach_port_mod_refs call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

4.3.5 Ports and other Tasks

Function: kern_return_t mach_port_insert_right (ipc_space_t task, mach_port_t name, mach_port_t right, mach_msg_type_name_t right_type)

The function mach_port_insert_right inserts into task the caller's right for a port, using a specified name for the right in the target task.

The specified name can't be one of the reserved values MACH_PORT_NULL or MACH_PORT_DEAD. The right can't be MACH_PORT_NULL or MACH_PORT_DEAD.

The argument right_type specifies a right to be inserted and how that right should be extracted from the caller. It should be a value appropriate for msgt_name; see mach_msg.

If right_type is MACH_MSG_TYPE_MAKE_SEND, MACH_MSG_TYPE_MOVE_SEND, or MACH_MSG_TYPE_COPY_SEND, then a send right is inserted. If the target already holds send or receive rights for the port, then name should denote those rights in the target. Otherwise, name should be unused in the target. If the target already has send rights, then those send rights gain an additional user reference. Otherwise, the target gains a send right, with a user reference count of one.

If right_type is MACH_MSG_TYPE_MAKE_SEND_ONCE or MACH_MSG_TYPE_MOVE_SEND_ONCE, then a send-once right is inserted. The name should be unused in the target. The target gains a send-once right.

If right_type is MACH_MSG_TYPE_MOVE_RECEIVE, then a receive right is inserted. If the target already holds send rights for the port, then name should denote those rights in the target. Otherwise, name should be unused in the target. The receive right is moved into the target task.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_VALUE if right was not a port right or name was MACH_PORT_NULL or MACH_PORT_DEAD, KERN_NAME_EXISTS if name already denoted a right, KERN_INVALID_CAPABILITY if right was MACH_PORT_NULL or MACH_PORT_DEAD KERN_RIGHT_EXISTS if task already had rights for the port, with a different name, KERN_UREFS_OVERFLOW if the user-reference count would overflow and KERN_RESOURCE_SHORTAGE if the kernel ran out of memory.

The mach_port_insert_right call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

Function: kern_return_t mach_port_extract_right (ipc_space_t task, mach_port_t name, mach_msg_type_name_t desired_type, mach_port_t *right, mach_msg_type_name_t *acquired_type)

The function mach_port_extract_right extracts a port right from the target task and returns it to the caller as if the task sent the right voluntarily, using desired_type as the value of msgt_name. See section 4.2.1 Mach Message Call.

The returned value of acquired_type will be MACH_MSG_TYPE_PORT_SEND if a send right is extracted, MACH_MSG_TYPE_PORT_RECEIVE if a receive right is extracted, and MACH_MSG_TYPE_PORT_SEND_ONCE if a send-once right is extracted.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_NAME if name did not denote a right, KERN_INVALID_RIGHT if name denoted a right, but an invalid one, KERN_INVALID_VALUE if desired_type was invalid.

The mach_port_extract_right call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

4.3.6 Receive Rights

Data type: mach_port_seqno_t

The mach_port_seqno_t data type is an unsigned int which contains the sequence number of a port.

Data type: mach_port_mscount_t

The mach_port_mscount_t data type is an unsigned int which contains the make-send count for a port.

Data type: mach_port_msgcount_t

The mach_port_msgcount_t data type is an unsigned int which contains a number of messages.

Data type: mach_port_rights_t

The mach_port_rights_t data type is an unsigned int which contains a number of rights for a port.

Data type: mach_port_status_t

This structure contains some status information about a port, which can be queried with mach_port_get_receive_status. It has the following members:

mach_port_t mps_pset

The containing port set.

mach_port_seqno_t mps_seqno

The sequence number.

mach_port_mscount_t mps_mscount

The make-send count.

mach_port_msgcount_t mps_qlimit

The maximum number of messages in the queue.

mach_port_msgcount_t mps_msgcount

The current number of messages in the queue.

mach_port_rights_t mps_sorights

The number of send-once rights that exist.

boolean_t mps_srights

TRUE if send rights exist.

boolean_t mps_pdrequest

TRUE if port-deleted notification is requested.

boolean_t mps_nsrequest

TRUE if no-senders notification is requested.

Function: kern_return_t mach_port_get_receive_status (ipc_space_t task, mach_port_t name, mach_port_status_t *status)

The function mach_port_get_receive_status returns the current status of the specified receive right.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_NAME if name did not denote a right and KERN_INVALID_RIGHT if name denoted a right, but not a receive right.

The mach_port_get_receive_status call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

Function: kern_return_t mach_port_set_mscount (ipc_space_t task, mach_port_t name, mach_port_mscount_t mscount)

The function mach_port_set_mscount changes the make-send count of task's receive right named name to mscount. All values for mscount are valid.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_NAME if name did not denote a right and KERN_INVALID_RIGHT if name denoted a right, but not a receive right.

The mach_port_set_mscount call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

Function: kern_return_t mach_port_set_qlimit (ipc_space_t task, mach_port_t name, mach_port_msgcount_t qlimit)

The function mach_port_set_qlimit changes the queue limit task's receive right named name to qlimit. Valid values for qlimit are between zero and MACH_PORT_QLIMIT_MAX, inclusive.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_NAME if name did not denote a right, KERN_INVALID_RIGHT if name denoted a right, but not a receive right and KERN_INVALID_VALUE if qlimit was invalid.

The mach_port_set_qlimit call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

Function: kern_return_t mach_port_set_seqno (ipc_space_t task, mach_port_t name, mach_port_seqno_t seqno)

The function mach_port_set_seqno changes the sequence number task's receive right named name to seqno. All sequence number values are valid. The next message received from the port will be stamped with the specified sequence number.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_NAME if name did not denote a right and KERN_INVALID_RIGHT if name denoted a right, but not a receive right.

The mach_port_set_seqno call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

4.3.7 Port Sets

Function: kern_return_t mach_port_get_set_status (ipc_space_t task, mach_port_t name, mach_port_array_t *members, mach_msg_type_number_t *count)

The function mach_port_get_set_status returns the members of a port set. members is an array that is automatically allocated when the reply message is received. The user should vm_deallocate it when the data is no longer needed.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_NAME if name did not denote a right, KERN_INVALID_RIGHT if name denoted a right, but not a receive right and KERN_RESOURCE_SHORTAGE if the kernel ran out of memory.

The mach_port_get_set_status call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

Function: kern_return_t mach_port_move_member (ipc_space_t task, mach_port_t member, mach_port_t after)

The function mach_port_move_member moves the receive right member into the port set after. If the receive right is already a member of another port set, it is removed from that set first (the whole operation is atomic). If the port set is MACH_PORT_NULL, then the receive right is not put into a port set, but removed from its current port set.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_NAME if member or after did not denote a right, KERN_INVALID_RIGHT if member denoted a right, but not a receive right or after denoted a right, but not a port set, and KERN_NOT_IN_SET if after was MACH_PORT_NULL, but member wasn't currently in a port set.

The mach_port_move_member call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.

4.3.8 Request Notifications

Function: kern_return_t mach_port_request_notification (ipc_space_t task, mach_port_t name, mach_msg_id_t variant, mach_port_mscount_t sync, mach_port_t notify, mach_msg_type_name_t notify_type, mach_port_t *previous)

The function mach_port_request_notification registers a request for a notification and supplies the send-once right notify to which the notification will be sent. The notify_type denotes the IPC type for the send-once right, which can be MACH_MSG_TYPE_MAKE_SEND_ONCE or MACH_MSG_TYPE_MOVE_SEND_ONCE. It is an atomic swap, returning the previously registered send-once right (or MACH_PORT_NULL for none) in previous. A previous notification request may be cancelled by providing MACH_PORT_NULL for notify.

The variant argument takes the following values:

MACH_NOTIFY_PORT_DESTROYED

sync must be zero. The name must specify a receive right, and the call requests a port-destroyed notification for the receive right. If the receive right were to have been destroyed, say by mach_port_destroy, then instead the receive right will be sent in a port-destroyed notification to the registered send-once right.

MACH_NOTIFY_DEAD_NAME

The call requests a dead-name notification. name specifies send, receive, or send-once rights for a port. If the port is destroyed (and the right remains, becoming a dead name), then a dead-name notification which carries the name of the right will be sent to the registered send-once right. If notify is not null and sync is non-zero, the name may specify a dead name, and a dead-name notification is immediately generated.

Whenever a dead-name notification is generated, the user reference count of the dead name is incremented. For example, a send right with two user refs has a registered dead-name request. If the port is destroyed, the send right turns into a dead name with three user refs (instead of two), and a dead-name notification is generated.

If the name is made available for reuse, perhaps because of mach_port_destroy or mach_port_mod_refs, or the name denotes a send-once right which has a message sent to it, then the registered send-once right is used to generate a port-deleted notification.

MACH_NOTIFY_NO_SENDERS

The call requests a no-senders notification. name must specify a receive right. If notify is not null, and the receive right's make-send count is greater than or equal to the sync value, and it has no extant send rights, than an immediate no-senders notification is generated. Otherwise the notification is generated when the receive right next loses its last extant send right. In either case, any previously registered send-once right is returned.

The no-senders notification carries the value the port's make-send count had when it was generated. The make-send count is incremented whenever MACH_MSG_TYPE_MAKE_SEND is used to create a new send right from the receive right. The make-send count is reset to zero when the receive right is carried in a message.

The function returns KERN_SUCCESS if the call succeeded, KERN_INVALID_TASK if task was invalid, KERN_INVALID_VALUE if variant was invalid, KERN_INVALID_NAME if name did not denote a right, KERN_INVALID_RIGHT if name denoted an invalid right and KERN_INVALID_CAPABILITY if notify was invalid.

When using MACH_NOTIFY_PORT_DESTROYED, the function returns KERN_INVALID_VALUE if sync wasn't zero.

When using MACH_NOTIFY_DEAD_NAME, the function returns KERN_RESOURCE_SHORTAGE if the kernel ran out of memory, KERN_INVALID_ARGUMENT if name denotes a dead name, but sync is zero or notify is MACH_PORT_NULL, and KERN_UREFS_OVERFLOW if name denotes a dead name, but generating an immediate dead-name notification would overflow the name's user-reference count.

The mach_port_request_notification call is actually an RPC to task, normally a send right for a task port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return mach_msg return codes.