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. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. 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 a list of reason codes, see Reason codes in 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 for SRB mode routines for more information about programming considerations for SRB mode.
Characteristics and restrictions
None.