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)