This function prepares a socket to listen for incoming connections.
At a Glance
| Header file: | Winsock.h |
| Windows CE versions: | 1.0 and later |
Syntax
int listen (SOCKET s, int backlog);
Parameters
s
[in] Descriptor that identifies a bound, unconnected socket.
backlog
[in] 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.
Return Values
Zero indicates success. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.
As in 4.3BSD, illegal values (less than 1 or greater than 5) are replaced by the nearest valid value.
Remarks
For Infrared Sockets (IrSock), this function has the following additional requirements and behaviors:
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.
See Also