.\"release ownership of a socket to another object
.DT
socket_release
$MUDNAME$ driver help
socket_release

.SH Name
.SI 5
socket_release() - release ownership of a socket to another object
.EI

.SH Synopsis
.SI 5
#include <socket_errors.h>

int socket_release( int socket, object ob,
                    string | function release_callback );
.EI

.SH Description
.SP 5 5
socket_release() is used to change ownership (and control) of a socket
to another object.  It is useful in daemon objects (like inetd) which
handle connection setup and then transfer a connected socket to another
object for further processing.

Socket ownership transfer involves a handshake between the current owner
object and the object to which the current owner wishes to transfer the
socket.  The handshake is initiated when socket_release() is called.
socket_release() does appropriate security/integrity checking and then
calls the `release_callback' function in object `ob'.  This function is used
to notify `ob' that socket ownership is being transferred to it.  It is
then `ob's responsibility to call socket_acquire() within the release
callback function.  If socket_acquire() is called, the handshake is
complete and socket ownership has been successfully transferred to `ob'.
`ob' may decline to accept responsibility for the socket by not calling
socket_acquire(), in which case ownership does not change and the
current socket owner must decide how to respond to this.

If the socket ownership is successfully transfered, socket_release()
returns EESUCCESS.  If `ob' does not accept ownership for the socket then
EESOCKNOTRLSD is returned.  Other errors can be returned based on
security violation, bad socket descriptor values, etc.
.EP

.SH See also
.SI 5
socket_acquire()
.EI
