.\"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
