listen()

Description

Establish a socket to listen for incoming connection.

#include <winsock.h>

int PASCAL FAR listen(SOCKET s, int backlog );

s

A descriptor identifying a bound, unconnected socket.
backlog
The maximum length to which the queue of pending connections may grow.

Remarks

To accept connections, a socket is first created with socket(), a backlog for incoming connections is specified with listen(), and then the connections are accepted with accept(). listen() applies only to sockets that support connections, i.e. those of type SOCK_STREAM. The socket s is put into "passive" mode where incoming connections are acknowledged and queued pending acceptance by the process.

This function is typically used by servers that could have more than one connection request at a time: if a connection request arrives with the queue full, the client will receive an error with an indication of WSAECONNREFUSED. listen() attempts to continue to function rationally when there are no available descriptors. It will accept connections until the queue is emptied. If descriptors become available, a later call to listen() or accept() will re-fill the queue to the current or most recent "backlog", if possible, and resume listening for incoming connections.

Compatibility backlog is currently limited (silently) to 5. As in 4.3BSD, illegal values (less than 1 or greater than 5) are replaced by the nearest legal value.

Return Value

If no error occurs, listen() returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

WSANOTINITIALISED

A successful WSAStartup() must occur before using this API.
WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEADDRINUSE
An attempt has been made to listen() on an address in use.
WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.
WSAEFAULT
An invalid argument was given.
WSAEINVAL
The socket has not been bound with bind() or is already connected.
WSAEISCONN
The socket is already connected.
WSAEMFILE
No more file descriptors are available.
WSAENOBUFS
No buffer space is available.
WSAENOTSOCK
The descriptor is not a socket.
WSAEOPNOTSUPP
The referenced socket is not of a type that supports the listen() operation.

See Also

accept(), connect(), socket()

---

[Back: ioctlsocket()]
[Next: ntohl()]