listen Subroutine

Purpose

Listens for socket connections and limits the backlog of incoming connections.

Library

Standard C Library (libc.a)

Syntax

#include <sys/socket.h>

int listen ( Socket,  Backlog)
int Socket, Backlog;

Description

The listen subroutine performs the following activities:

  1. Identifies the socket that receives the connections.
  2. Marks the socket as accepting connections.
  3. Limits the number of outstanding connection requests in the system queue.

The outstanding connection request queue length limit is specified by the parameter backlog per listen call. A no parameter - somaxconn - defines the maximum queue length limit allowed on the system, so the effective queue length limit will be either backlog or somaxconn, whichever is smaller.

All applications containing the listen subroutine must be compiled with the _BSD macro set to a specific value. Acceptable values are 43 and 44. In addition, all socket applications must include the BSD libbsd.a library.

Parameters

Item Description
Socket Specifies the unique name for the socket.
Backlog Specifies the maximum number of outstanding connection requests.

Return Values

Upon successful completion, the listen subroutine returns a value 0.

If the listen subroutine is unsuccessful, the subroutine handler performs the following functions:

Error Codes

The subroutine is unsuccessful if any of the following errors occurs:

Error Description
EBADF The Socket parameter is not valid.
ECONNREFUSED The host refused service, usually due to a server process missing at the requested name or the request exceeding the backlog amount.
EINVAL The socket is already connected.
ENOTSOCK The Socket parameter refers to a file, not a socket.
EOPNOTSUPP The referenced socket is not a type that supports the listen subroutine.

Examples

The following program fragment illustrates the use of the listen subroutine with 5 as the maximum number of outstanding connections which may be queued awaiting acceptance by the server process.

listen(s,5)