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

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

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_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].
   
   
2. listen() can be issued multiple times for a particular socket.
   
   
3. 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.
   
   
4. 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.
   
   
5. 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().

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

[ Back to top | UNIX-Type APIs | APIs by category ]