listen()--Invite Incoming Connections Requests
Syntax
#include <sys/socket.h> int listen(int socket_descriptor, int back_log)
Service Program Name: QSOSRV1
Default Public Authority: *USE
Threadsafe: Yes
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>).
Authorities
No authorization is required.
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_INET6, 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:
|
[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). |
[EPERM] | The operation is not permitted.
A user exit program registered for the exit point, QIBM_QSO_LISTEN, has denied the listen() API successful completion. |
[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
- 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_INET6, the
system automatically selects an address (in6addr_any and an available
port number) and binds it to the socket.
- AF_UNIX, the listen() fails with [EINVAL].
- AF_INET, the system automatically selects an address
(INADDR_ANY and an available port number) and binds it to the socket.
- listen() can be issued multiple times for a particular socket.
- If the back_log parameter specifies a value greater than the
maximum {SOMAXCONN} allowed, the specified value will be ignored and SOMAXCONN
will be used. If the
back_log parameter specifies a negative value, the specified value
will be ignored and zero will be used.
- 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.
- 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.
- When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, the listen() API is mapped to qso_listen98().
- A user exit point, QIBM_QSO_LISTEN, exists to optionally allow or deny the listen() API to successfully complete based on the return code from the registered user exit program. For more information refer to Sockets listen() API Exit Program.
Related Information
- _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98
compatible interface
- accept()--Wait for Connection Request and Make Connection
API introduced: V3R1