listen()--Invite Incoming Connections Requests

#include <sys/socket.h>

int listen(int socket_descriptor,
           int back_log)

The listen() function is used to indicate a willingness to accept incoming connection requests. If a listen() is not done, incoming connections are silently discarded.

Parameters

socket_descriptor

(Input) The descriptor of the socket that is to be prepared to receive incoming connection requests.

back_log

(Input) The maximum number of connection requests that can be queued before the system starts rejecting incoming requests. The maximum number of connection requests that can be queued is defined by {SOMAXCONN} (defined in <sys/socket.h>).

Return Value

listen() returns an integer. Possible values are:

• -1 (unsuccessful)

• 0 (successful)

Error Conditions

When listen() fails, errno can be set to one of the following:

[EADDRNOTAVAIL]

Address not available.

The socket has an address family of AF_INET or AF_NS, the socket was not bound, and the system tried to bind the socket but could not because a port was not available.

[EBADF]

Descriptor not valid.

[EINVAL]

Parameter not valid.

This error code indicates one of the following:

• The back_log parameter specifies a negative value.

• The back_log parameter specifies a value greater than the maximum {SOMAXCONN} allowed.

• A connect() has been issued on the socket pointed to by the socket_descriptor parameter.

• The socket_descriptor parameter points to a socket with an address family of AF_UNIX that has not been bound to an address.

[EIO]

Input/output error.

[ENOBUFS]

There is not enough buffer space for the requested operation.

[ENOTSOCK]

The specified descriptor does not reference a socket.

[EOPNOTSUPP]

Operation not supported.

The socket_descriptor parameter points to a socket that does not support listen(). listen() is only supported on sockets that are using a connection-oriented protocol (socket type of SOCK_STREAM).

[EUNKNOWN]

Unknown system state.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

Error Messages

CPE3418 E

Possible APAR condition or hardware failure.

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.

CPFA081 E

Unable to set return value or error code.

Usage Notes

1. If the socket is not bound to an address and the address family is:

   • AF_INET, the system automatically selects an address (INADDR_ANY and an available port number) and binds it to the socket.

   • AF_NS, the system automatically selects an address and a generated value for the port number and binds it to the socket.

   • AF_UNIX, the listen() fails with [EINVAL].

   • AF_TELEPHONY, the system will bind the socket to TELADDR_ANY, which indicates that calls will be answered for any of the local telephone numbers for which the associated devices have been configured.

2. listen() can be issued multiple times for a particular socket.

3. The optimal setting of the listen() back_log value is dependent on the following factors:

   • The design of the server--how the server processes connection requests. Does it handle each connection request itself or does it pass the actual processing of the connection to a child or worker job? In other words, how long does it take for the server to handle an incoming connection until it can handle the next one? The shorter the time, the smaller the back_log value can be.

   • The number and rate of connection requests the server can expect over a given period of time will help determine the back_log value. More connection requests coming in over a shorter period of time requires a larger back_log value.

   • The following may determine how the server performs and thus how long it will take for an accept request to be serviced:

     • The system processor size

     • How storage pools used by the server are allocated

     • Machine performance

     The faster the server performance, the smaller the back_log value can be.

   Also, to help you determine how much main storage is consumed by a connection request in the listen() back_log, consider the following:

   • Each connection request in the backlog consumes at least 1KB of storage.

   • Each connection request can consume an additional storage amount equal to the size of TCP receive buffer. You can determine the TCP receive buffer size by looking at the TCPRCVBUF parameter value on the Change TCP Attributes (CHGTCPA) CL command. This storage amount will be consumed only if the remote peer (client) sends data after the connection is established and put into the backlog.

4. For AF_TELEPHONY sockets, the back_log value is ignored.

Related Information

• accept()--Wait for Connection Request and Make Connection