listen

This function prepares a socket to listen for incoming connections.

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:

• 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.

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.

Requirements

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

accept, bind, connect, socket, WSAStartup

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.