NAME
port_set_backup - changes a port’s backup port

SYNOPSIS
#include <mach.h>

kern_return_t port_set_backup(task, primary, backup, previous)
task_t task;
port_name_t primary;
port_t backup;
port_t *previous; /* out */

ARGUMENTS
task The task owning the named port right.

primary task’s name for the primary port.

backup The new backup port to be set.

previous The previous backup port.

DESCRIPTION
A backup port provides a automatic mechanism to transfer port
receive rights to another task or thread in the event of a primary
port’s attempted death. To be more precise, if a primary port has
a backup port, and the primary would have been destroyed by the
deallocation of its receive rights, then instead the receive right
for the primary port is sent in a notify message
(NOTIFY_PORT_DESTROYED) to the backup port.

A newly allocated port does not have a backup port. The
port_set_backup call changes the backup of the primary port. The
target task must hold receive rights for the primary port. The
caller supplies send rights for the new backup port to which
notification will be sent. The caller receives send rights for the
previous backup port or PORT_NULL if the target did not have a
backup. port_set_backup works atomically, so that if one backup
port is exchanged for another, the primary port is never left
without a backup.

When the primary port is sent in a notify message to the backup
port, the primary port is left without a backup port. When the
task receives the notification and the receive rights to the
primary port, it may wish to use port_set_backup to reestablish the
same or a different backup port. If the backup port is destroyed
before the primary, then the primary port is left without a backup.
(A subsequent port_set_backup call would return PORT_NULL).

DIAGNOSTICS
KERN_SUCCESS The call succeeded.

KERN_NOT_RECEIVER primary doesn’t name receive rights
in task.

KERN_INVALID_ARGUMENT task was invalid or primary or backup
do not name a valid port.

SEE ALSO
port_deallocate(2)