listen

Article
11/18/2015

A version of this page is also available for

4/8/2010

This function places a socket at a state where it is listening for an incoming connection.

Syntax

int listen(
  SOCKET s,
  int backlog
);

Parameters

s
[in] Descriptor identifying a bound, unconnected socket.

backlog
[in] Maximum length of the queue of pending connections. If backlog is set to SOMAXCONN, the underlying service provider responsible for socket s will set the backlog to a maximum reasonable value. There is no standard provision to obtain the actual backlog value.

Return Value

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

The following table shows a list of possible error codes.

Error code	Description
WSANOTINITIALISED	A successful WSAStartup call 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 (Windows Sockets) function, but it could be delayed until the listen function if the bind was to a partially wildcard address (involving ADDR_ANY) and if a specific address needs to be committed at the time of the listen function.
WSAEINPROGRESS	A blocking Winsock 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.

Remarks

To accept connections, a socket is first created with the socket (Windows Sockets) function and bound to a local address with the bind (Windows Sockets) function, a backlog for incoming connections is specified with listen, and the connections are accepted with the accept (Windows Sockets) function. Sockets that are connection-oriented, those of type SOCK_STREAM for example, are used with listen. 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.

Notes for IrDA Sockets

The Af_irda.h header file must be explicitly included.

For more inforamtion about IrDA support in Windows Embedded CE, see Infrared Communications.

Notes for Bluetooth

An RFCOMM Winsock server calls listen to put RFCOMM into a mode in which it will accept connections on the channel. The backlog value for RFCOMM would be 0. Calling listen does not advertise the service in the SDP database.

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.

Requirements

Header	winsock2.h
Library	Ws2.lib
Windows Embedded CE	Windows CE 1.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later

Partager via