listen
The listen function places a socket in a state in which it is listening for an incoming connection.
Syntax
int listen(
SOCKET s,
int backlog
)
Parameters
s
Type: SOCKET
[in] A descriptor identifying a bound, unconnected socket.
backlog
Type: int
[in] The maximum length of the queue of pending connections. If 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
Type: int
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.
Return codes
| Return 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 function, but could be delayed until this 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 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. |
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.
A value for the backlog of SOMAXCONN is a special constant that instructs the underlying service provider responsible for socket s to set the length of the queue of pending connections to a maximum reasonable value.
On Windows Sockets 2, this maximum value defaults to a large value (typically several hundred or more). When calling the listen function in a Bluetooth application, it is strongly recommended that a much lower value be used for the backlog parameter (typically 2 to 4), since only a few client connections are accepted. This reduces the system resources that are allocated for use by the listening socket. This same recommendation applies to other network applications that expect only a few client connections.
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 value specified for the backlog parameter, if possible, and resume listening for incoming connections.
If the listen function is called on an already listening socket, it will return success without changing the value for the backlog parameter. Setting the backlog parameter to 0 in a subsequent call to listen on a listening socket is not considered a proper reset, especially if there are connections on the socket.
Note
When issuing a blocking Winsock call such as listen, Winsock may need to wait for a network event before the call can complete. Winsock performs an alertable wait in this situation, which can be interrupted by an asynchronous procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock call inside an APC that interrupted an ongoing blocking Winsock call on the same thread will lead to undefined behavior, and must never be attempted by Winsock clients.
Example Code
Example
The following example demonstrates the use of the listen function.
Example Code
For another example that uses the listen function, see Getting Started With Winsock.
Notes for IrDA Sockets
- The Af_irda.h header file must be explicitly included.
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.
Windows Phone 8: This API is supported.
Requirements
Header: Declared in winsock2.h.
Library: Use ws2_32.lib.