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:
- The command completes the bind process, if it has not already
been done explicitly.
- 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
.-,--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.