listen Function

listen Function

The listen function places a socket in a state in which it is listening for an incoming connection.

int listen(
  __in          SOCKET s,
  __in          int backlog
);

Parameters

s

Descriptor identifying a bound, unconnected socket.

backlog

Maximum length of the queue of pending connections. If set to SOMAXCONN, the underlying service provider responsible for sockets 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, listen returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by callingWSAGetLastError.

Error code	Meaning
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 thebind function, but could be delayed until this function if thebind 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 thebind function. A backlog for incoming connections is specified withlisten, and then the connections are accepted with the accept function. Sockets that are connection oriented, those of type SOCK_STREAM for example, are used withlisten. 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 sockets to set the length of the queue of pending connections to a maximum reasonable value.

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

If there are no available socket descriptors, listen attempts to continue to function. If descriptors become available, a later call tolisten or accept will refill the queue to the current or most recent value specified for thebacklog 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 thebacklog parameter. Setting the backlog parameter to 0 in a subsequent call tolisten on a listening socket is not considered a proper reset, especially if there are connections on the socket.

Example Code

The following example demonstrates the use of the listen function.

#include <stdio.h>
#include "winsock2.h"

void main() {

  //----------------------
  // Initialize Winsock
  WSADATA wsaData;
  int iResult = WSAStartup(MAKEWORD(2,2), &wsaData);
  if (iResult != NO_ERROR)
    printf("Error at WSAStartup()\n");

  //----------------------
  // Create a SOCKET for listening for
  // incoming connection requests.
  SOCKET ListenSocket;
  ListenSocket = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
  if (ListenSocket == INVALID_SOCKET) {
    printf("Error at socket(): %ld\n", WSAGetLastError());
    WSACleanup();
    return;
  }

  //----------------------
  // The sockaddr_in structure specifies the address family,
  // IP address, and port for the socket that is being bound.
  sockaddr_in service;
  service.sin_family = AF_INET;
  service.sin_addr.s_addr = inet_addr("127.0.0.1");
  service.sin_port = htons(27015);

  if (bind( ListenSocket, 
    (SOCKADDR*) &service, 
    sizeof(service)) == SOCKET_ERROR) {
    printf("bind() failed.\n");
    closesocket(ListenSocket);
    return;
  }

  //----------------------
  // Listen for incoming connection requests 
  // on the created socket
  if (listen( ListenSocket, SOMAXCONN ) == SOCKET_ERROR)
    printf("Error listening on socket.\n");

  printf("Listening on socket...\n");
  WSACleanup();
  return;
}

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.

Requirements

Client	Requires Windows Vista, Windows XP, Windows 2000 Professional, Windows NT Workstation, Windows Me, Windows 98, or Windows 95.
Server	Requires Windows Server 2008, Windows Server 2003, Windows 2000 Server, or Windows NT Server.
Header	Declared in Winsock2.h.
Library	Use Ws2_32.lib.
DLL	Requires Ws2_32.dll.

See Also

Winsock Reference
Winsock Functions
accept
connect
socket

Send comments about this topic to Microsoft

Build date: 8/15/2007