Technical Reference: Communications, Volume 2

listen Subroutine

Purpose

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

Syntax

#include <sys/socket.h>

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

Description

The listen subroutine performs the following activities:

Identifies the socket that receives the connections.
Marks the socket as accepting connections.
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.

Parameters

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:

Returns a value of -1 to the calling program.
Moves an error code, indicating the specific error, into the errno global variable.

Error Codes

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

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

Implementation Specifics

The listen subroutine is part of Base Operating System (BOS) Runtime.

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

Related Information

The accept subroutine, connect subroutine, socket subroutine.

Accepting Internet Stream Connections Example Program, Sockets Overview, Understanding Socket Connections in AIX 5L Version 5.1 Communications Programming Concepts.