listen

The Windows Sockets listen function places a socket a state where it is listening for an incoming connection.

int listen (
  SOCKET s,    
  int backlog  
);

Parameters

s: [in] A descriptor identifying a bound, unconnected socket.
backlog: [in] The maximum length of the queue of pending connections. If this value is SOMAXCONN, then the underlying service provider responsible for socket s will set the backlog to a maximum "reasonable" value. There is no standard provision to find out the actual backlog value.

Remarks

To accept connections, a socket is first created with the socket function and bound to a local address with the bind function, a backlog for incoming connections is specified with listen, and then the connections are accepted with the accept function. Sockets that are connection oriented, those of type SOCK_STREAM for example, are used with listen. The socket s is put into "passive'' mode where incoming connection requests are acknowledged and queued pending acceptance by the process.

The listen function is typically used by servers that can have more than one connection request at a time. If a connection request arrives and the queue is full, the client will receive an error with an indication of WSAECONNREFUSED.

If there are no available socket descriptors, listen attempts to continue to function. If descriptors become available, a later call to listen or accept will refill the queue to the current or most recent "backlog'', if possible, and resume listening for incoming connections.

An application can call listen more than once on the same socket. This has the effect of updating the current backlog for the listening socket. Should there be more pending connections than the new backlog value, the excess pending connections will be reset and dropped.

Windows CE: As in 4.3BSD, illegal values (less than 1 or greater than 5) are replaced by the nearest valid value.

For IrSockets implementation:

The Af_irda.h file must be explicitly included.
The WSAENETDOWN return value is not supported.
The backlog parameter is currently limited (silently) to 2.

Compatibility

The backlog parameter is limited (silently) to a reasonable value as determined by the underlying service provider. Illegal values are replaced by the nearest legal value. There is no standard provision to find out the actual backlog value.

Return Values

If no error occurs, listen returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEADDRINUSE	The socket's local address is already in use and the socket was not marked to allow address reuse with SO_REUSEADDR. This error usually occurs during execution of the bind function, but could be delayed until this function if the bind was to a partially wild-card address (involving ADDR_ANY) and if a specific address needs to be "committed" at the time of this function.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEINVAL	The socket has not been bound with bind.
WSAEISCONN	The socket is already connected.
WSAEMFILE	No more socket 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.

QuickInfo

  Windows NT: Yes
  Windows: Yes
  Windows CE: Use version 1.0 and later.
  Header: Declared in winsock2.h.
  Import Library: Link with ws2_32.lib.