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.

Function: kern_return_t mach_port_set_protected_payload (ipc_space_t task, mach_port_t name, unsigned long payload)

The function mach_port_set_protected_payload sets the protected payload associated with the right name to payload. Section Message Receive describes how setting a protected payload affects the messages delivered to 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 and KERN_INVALID_RIGHT if name denoted a right, but not a receive right.

The mach_port_set_protected_payload 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_clear_protected_payload (ipc_space_t task, mach_port_t name, unsigned long payload)

The function mach_port_clear_protected_payload clears the protected payload associated with the right 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 and KERN_INVALID_RIGHT if name denoted a right, but not a receive right.

The mach_port_clear_protected_payload 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.