.\"listen for connections on a socket
.DT
socket_listen
$MUDNAME$ driver help
socket_listen

.SH Name
.SI 5
socket_listen() - listen for connections on a socket
.EI

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

int socket_listen( int s, string | function listen_callback );
.EI

.SH Description
.SP 5 5
To accept connections, a socket is first created with socket_create(),
the socket is then put into listening mode with socket_listen(), and
the connections are accepted with socket_accept().  The socket_listen() call
applies only to sockets of type STREAM or MUD.

The argument `listen_callback' is the function or the name of a function for
the driver to call when a connection is requested on the listening socket.
The listen callback should follow this format:
.EP

.SI 5
void listen_callback( int fd )
.EI

.SP 5 5
Where fd is the listening socket.

socket_listen() returns EESUCCESS on success, and a negative value indicated
below on error.
.EP

.SH Errors
.SI 5
These errors are in <socket_errors.h>:
.EI

.SO 10 15 45
	EEFDRANGE	Descriptor out of range.
	EEBADF	Descriptor is invalid.
	EESECURITY	Security violation attempted.
	EEMODENOTSUPP	Socket mode not supported.
	EENOADDR	Socket not bound to an address.
	EEISCONN	Socket is already connected.
	EELISTEN	Problem with listen.
.EO

.SH See also
.SI 5
socket_accept(), socket_connect(), socket_create()
.EI
