Go to the first, previous, next, last section, table of contents.
This chapter describes the details of the Mach IPC system. Only the actual calls concerned with sending and receiving messages are discussed here. The details of the port system are described in the next chapter.
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, 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.
This section describes how messages are composed, sent and received within the Mach IPC system.
To use the mach_msg call, you can include the header files
`mach/port.h' and `mach/message.h'.
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.
MACH_MSG_TIMEOUT_NONE.
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:
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:
mach_msg_bits_t data type is an unsigned int used to
store various flags for a message.
mach_msg_size_t data type is an unsigned int used to
store the size of a message.
mach_msg_id_t data type is an integer_t typically used to
convey a function or operation id for the receiver.
mach_msg_bits_t msgh_bits
msgh_bits field has the following bits defined, all other
bits should be zero:
MACH_MSGH_BITS_REMOTE_MASK
MACH_MSGH_BITS_LOCAL_MASK
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
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
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
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
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
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
mach_msg call doesn't use the msgh_id field, but it
conventionally conveys an operation or function id.
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.
mach_msg_type_name_t value for the remote
port right in a mach_msg_bits_t value.
mach_msg_type_name_t value for the local
port right in a mach_msg_bits_t value.
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.
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.
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.
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.
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.
unsigned int msgt_name : 8
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
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
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
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
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
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
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
msgt_unused bit should be zero.
TRUE if the given type name specifies a port
type, otherwise it returns FALSE.
TRUE if the given type name specifies a port
type with a send or send-once right, otherwise it returns FALSE.
TRUE if the given type name specifies a port
right type which is moved, otherwise it returns FALSE.
mach_msg_type_t msgtl_header
msgt_header.
unsigned short msgtl_name
msgt_name.
unsigned short msgtl_size
msgt_size.
unsigned int msgtl_number
msgt_number.
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
MACH_MSG_TYPE_COPY_SEND
MACH_PORT_DEAD.
MACH_MSG_TYPE_MOVE_SEND
MACH_PORT_DEAD.
MACH_MSG_TYPE_MAKE_SEND_ONCE
MACH_MSG_TYPE_MOVE_SEND_ONCE
MACH_PORT_DEAD.
MACH_MSG_TYPE_MOVE_RECEIVE
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
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
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
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.
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.
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
MACH_SEND_TIMED_OUT. A zero timeout is legitimate.
MACH_SEND_NOTIFY
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
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
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
MACH_SEND_NO_BUFFER
MACH_SEND_INVALID_DATA
MACH_SEND_INVALID_HEADER
msgh_bits value was invalid.
MACH_SEND_INVALID_DEST
msgh_remote_port value was invalid.
MACH_SEND_INVALID_REPLY
msgh_local_port value was invalid.
MACH_SEND_INVALID_NOTIFY
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
MACH_SEND_INVALID_RIGHT
MACH_SEND_INVALID_TYPE
MACH_SEND_MSG_TOO_SMALL
These return codes imply that the message was returned to the caller with a pseudo-receive operation:
MACH_SEND_TIMED_OUT
MACH_SEND_INTERRUPTED
MACH_SEND_INVALID_NOTIFY
MACH_SEND_NOTIFY, the notify argument did not denote a
valid receive right.
MACH_SEND_NO_NOTIFY
MACH_SEND_NOTIFY_IN_PROGRESS
These return codes imply that the message was queued:
MACH_SEND_WILL_NOTIFY
MACH_MSG_SUCCESS
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.
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
MACH_RCV_TIMED_OUT. A zero timeout is legitimate.
MACH_RCV_NOTIFY
MACH_RCV_INTERRUPT
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
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
rcv_name was invalid.
MACH_RCV_IN_SET
MACH_RCV_TIMED_OUT
MACH_RCV_INTERRUPTED
MACH_RCV_PORT_DIED
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
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
MACH_RCV_INVALID_NOTIFY
MACH_RCV_NOTIFY, the notify argument did not denote a
valid receive right.
MACH_RCV_TOO_LARGE
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
MACH_RCV_INVALID_DATA
MACH_MSG_SUCCESS
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
MACH_MSG_VM_SPACE
MACH_MSG_IPC_KERNEL
MACH_MSG_VM_KERNEL
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.
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.
This section describes the interface to create, destroy and manipulate ports and port sets.
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.
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.
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.
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.
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.
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.
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
MACH_PORT_TYPE_RECEIVE
MACH_PORT_TYPE_SEND_ONCE
MACH_PORT_TYPE_PORT_SET
MACH_PORT_TYPE_DEAD_NAME
MACH_PORT_TYPE_DNREQUEST
MACH_PORT_TYPE_MAREQUEST
MACH_PORT_TYPE_COMPAT
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.
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.
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.
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.
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.
mach_msg.
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.
mach_port_seqno_t data type is an unsigned int which
contains the sequence number of a port.
mach_port_mscount_t data type is an unsigned int which
contains the make-send count for a port.
mach_port_msgcount_t data type is an unsigned int which
contains a number of messages.
mach_port_rights_t data type is an unsigned int which
contains a number of rights for a port.
mach_port_get_receive_status. It has the following
members:
mach_port_t mps_pset
mach_port_seqno_t mps_seqno
mach_port_mscount_t mps_mscount
mach_port_msgcount_t mps_qlimit
mach_port_msgcount_t mps_msgcount
mach_port_rights_t mps_sorights
boolean_t mps_srights
TRUE when 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.
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.
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.
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.
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.
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.
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.
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
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
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
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.
Go to the first, previous, next, last section, table of contents.