listen (BPX1LSN, BPX4LSN) — Prepare a server socket to queue incoming connection requests from clients

Function

The listen callable service creates a connection request queue for a server socket to queue incoming connection requests from a client.

Listen is used for connection-oriented sockets only. If a connection request arrives with the backlog queue full, the client may receive an ECONNREFUSED.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN = HASN
AMODE (BPX1LSN):	31-bit task mode or SRB mode
AMODE (BPX4LSN):	64-bit task mode only
ASC mode:	AR mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1LSN,(Socket_descriptor,
              Backlog,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4LSN with the same parameters.

Parameters

Socket_descriptor

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the socket file descriptor for which the listen is to be done.

Backlog

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a field that contains the maximum length of the connection queue. For network sockets, if Backlog is greater than SOMAXCONN, this field is set to SOMAXCONN. For AF_UNIX sockets, there is no maximum value for this field.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword to which the listen service returns one of the following:

0, if the request is successful.
-1, if the request is not successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the listen service stores the return code. The listen service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The listen service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EBADF	The socket descriptor is incorrect. The following reason codes can accompany the return code: JRFileDesNotInUse, JRFileNotOpen.
EINVAL	An incorrect argument was supplied. The socket is not named (a bind has not been done); or the socket is ready to accept connections (a listen has already been done). The following reason code can accompany the return code: JRListenNotAccepted.
ENOBUFS	A buffer could not be obtained. The following reason code can accompany the return code: JROutofSocketCells.
ENOTSOCK	Socket_descriptor does not refer to a valid socket descriptor. The following reason code can accompany the return code: JRMustBeSocket.
EOPNOTSUPP	The socket descriptor specified a datagram socket. The listen service is valid only for stream sockets. The following reason code can accompany the return code: JRListenNotStream.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the listen service stores the reason code. The listen service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

If a bind is not called before the listen request, the listen callable service returns an EINVAL.
See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.

Characteristics and restrictions

There are no restrictions on the use of the listen service.

Examples

For an example using this callable service, see BPX1LSN (listen) example.