listen()

mark a socket as accepting connections 

Function

SYNOPSIS

#include <sys/socket.h>

int listen(int s, int backlog);

DESCRIPTION

The listen() function marks a connection-mode socket (for example, those of type SOCK_STREAM), specified by the socket argument s, as accepting connections, and limits the number of outstanding connections in the socket's listen queue to the value specified by the backlog argument. The socket s is put into 'passive' mode where incoming connection requests are acknowledged and queued pending acceptance by the process.

The backlog parameter of this function is typically used by servers that could have more than one connection request at a time: if a connection request arrives with the queue full, the client receives an error with an indication of ECONNREFUSED.

listen() attempts to continue to function rationally when there are no available descriptors. It accepts connections until the queue is emptied. If descriptors become available, a later call to listen() or accept() re-fills the queue to the current or most recent backlog', if possible, and resume listening for incoming connections.

An application may 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 are reset and dropped.

backlog is limited (silently) to a reasonable value as determined by the underlying service provider. Illegal values are replaced by the nearest legal value.

PARAMETERS

s 

Is a descriptor identifying a bound, unconnected socket.

backlog 

Is the maximum length that the queue of pending connections may grow to. If this value is SOMAXCONN, then the underlying service provider responsible for socket s sets the backlog to a maximum "reasonable" value.

RETURN VALUES

If successful, listen() returns a value of zero. On failure, it returns -1 and sets errno to one of the following values:

EBADF 

s is not a valid descriptor

EINCONN 

s is already connected.

EINVAL 

s has not been bound to a local address.

EMFILE 

No more socket descriptors are available.

ENETDOWN 

Network subsystem has failed.

ENOBUFS 

No buffer space is available.

ENOTSOCK 

s is not a socket

EOPNOTSUPP 

s is not a socket that supports listen().

CONFORMANCE

UNIX 98, with exceptions.

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

The NuTCRACKER Platform supports all the address families that WinSock 2.0 supports. Applications may not call listen() more than once for the same socket for AF_UNIX sockets.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Functions:
accept(), connect(), socket()

PTC MKS Toolkit 10.4 Documentation Build 39.