— 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.