## mach_port_destroy

Function - Deallocate all port rights associated with specified name.

### SYNOPSIS

    kern_return_t   mach_port_destroy
                    (ipc_space_t                               task,
                     mach_port_name_t                          name);

### PARAMETERS

task
  [in task send right] The task holding the right.

name
  [in scalar] The task's name for the right.

### DESCRIPTION

The mach_port_destroy function de-allocates 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. 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 destruction of the send-once right produces 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 a port-deleted notification is generated (as opposed to a dead-name notification).

### NOTES

This interface is machine word length specific because of the port name parameter.

### RETURN VALUES

KERN_INVALID_NAME
  The name parameter did not denote a right.

### RELATED INFORMATION

Functions: mach_port_allocate, mach_port_allocate_name, mach_port_mod_refs, mach_port_deallocate, mach_port_request_notification.