LISTEN

Use the LISTEN command to determine whether a socket is ready to accept client connection requests.

The LISTEN command applies only to stream sockets. The LISTEN command performs two actions:
  1. The command completes the bind process, if it has not already been done explicitly.
  2. Creates a connection request queue (the backlog queue). New connections received by the stack for this socket are placed on the backlog queue. The application then can issue the ACCEPT command to process these pending connections. If the backlog queue is full, the stack rejects new connection requests.
Guideline: Applications that issue the LISTEN command should bind to a well-known port using INADDR_ANY or IN6ADDR_ANY. If the LISTEN command completes the bind for IPv4, the socket is bound to AF_INET 0 INADDR_ANY. If the LISTEN command completes the bind for IPv6, the socket is bound to AF_INET 0 0 IN6ADDR_ANY 0.

Format

Read syntax diagramSkip visual syntax diagram
                                     .-,--10------.      
>>-SOCKET--(--"LISTEN"--,--socketid--+------------+--)---------><
                                     '-,--backlog-'      

Parameters

socketid
The socket descriptor
backlog
The number of pending connection requests. This parameter can have a value in the range 0 to the maximum number that is specified by the SOMAXCONN parameter in the TCPIP profile. If the backlog parameter is set to 0, 1, or 2, then the backlog queue uses the default value of 2. If the backlog parameter is not specified, by default it is set to 10.

Returned value

The command returns a string that contains the return code. The return code can be 0, a REXX socket API error number, or the REXX TCP/IP error number that is set by the socket command. The return code 0 indicates that the requested socket command was completed successfully.

See Socket call error return codes for additional information about the numeric error codes that are returned by this command.

The following REXX TCP/IP error numbers can be returned:
  • 9 EBADF
  • 22 EINVAL,
  • 38 ENOTSOCK,
  • 45 EOPNOTSUPP,
The following REXX socket API error numbers can be returned:
  • 2001 EINVALIDRXSOCKETCALL
  • 2005 ESUBTASKNOTACTIVE
  • 2006 ESOCKETNOTALLOCATED
  • 2009 ESOCKETNOTDEFINED
  • 2012 EINVALIDNAME

LE C/C++ equivalent

This command has no LE C/C++ equivalent.

Code example

See ACCEPT for an example of how to use the LISTEN command.