accept (BPX1ACP, BPX4ACP) — Accept a connection request from a client socket
Function
The accept callable service allows a server to accept a connection request from a client. It extracts the first connection on the queue of pending connections, creates a new socket with the same properties as the specified socket, and allocates a new descriptor for that socket. If there are no connections pending, the service either blocks until a connection request is received, or fails with an EWOULDBLOCK, depending on whether the specified socket is marked as blocking or nonblocking.
Requirements
| Operation | Environment |
|---|---|
| Authorization: | Supervisor state or problem state, any PSW key |
| Dispatchable unit mode: | Task or SRB |
| Cross memory mode: | PASN = HASN |
| AMODE (BPX1ACP): | 31-bit task or SRB mode |
| AMODE (BPX4ACP): | 64-bit task mode only |
| ASC mode: | Primary 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
The syntax format is as follows:CALL BPX1ACP,(Socket_descriptor,
Sockaddr_length,
Sockaddr,
Return_value,
Return_code,
Reason_code)AMODE 64 callers use BPX4ACP 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 accept is to be done.
- Sockaddr_length
- Supplied and returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a field that contains the length of Sockaddr. On return, this field specifies the size required to represent the address of the connecting socket. If this value is larger than the size supplied on input, the information contained in Sockaddr is truncated to the length supplied on input. The field can be zero if no value is passed for Sockaddr. The size of the field should be less than 4096 bytes (4KB) in length.
- Sockaddr
- Supplied and returned parameter
- Type:
- Structure
- Length:
- Length specified by Sockaddr_length
The name of a field that contains the socket address of the connecting client. The format of Sockaddr is determined by the domain in which the client resides. This field can be null if the caller is not interested in the client address. For more information about the format of this structure, see BPXYSOCK — Map SOCKADDR structure and constants.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the accept service returns one of the following:- A socket descriptor, 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 accept service stores the return code. The accept 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 following table lists the values that can be returned in the Return_code parameter:Return_code Explanation EBADF An incorrect file descriptor was specified. The following reason codes can accompany the return code: JRFileDesNotInUse, or JRFileNotOpen. ECONNABORTED Software-caused connection termination. EINTR A signal interrupted the accept service before any connections were available. The following reason code can accompany the return code: JRSignalReceived. EINVAL The socket is not accepting connections. A listen must be done prior to the accept. The following reason code can accompany the return code: JRListenNotDone. EIO There has been a network or transport failure. The following reason codes can accompany the return code: JRInetRecycled, JRPrevSockError. ENFILE Too many files are open in the system. The following reason code can accompany the return code: JRMaxSockets. 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 referenced socket is not a type that supports the requested function. EWOULDBLOCK The socket file descriptor is marked nonblocking, and no connections are present to be accepted. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword where the accept service stores the reason code. The accept 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
- The Socket_descriptor that is passed refers to the socket that
was created with the socket callable service, was bound to an address
with the bind callable service, and that has issued a successful call
to the listen callable service.
Before calling the accept service, you can find out if the socket is pending a connection by doing a read select with the select callable service.
- In order for Sockaddr to be returned for a UNIX domain socket, the client application doing the connect must bind a unique local name to the socket using the bind service before running the connect service.
- See Callable services for SRB mode routines for more information about programming considerations for SRB mode.
Related services
- asyncio (BPX1AIO, BPX4AIO) — Asynchronous I/O for sockets
- bind (BPX1BND, BPX4BND) — Bind a unique local name to a socket descriptor
- listen (BPX1LSN, BPX4LSN) — Prepare a server socket to queue incoming connection requests from clients
- select/selectex (BPX1SEL, BPX4SEL) — Select on file descriptors and message queues
- socket or socketpair (BPX1SOC, BPX4SOC) — Create a socket or a pair of sockets
Characteristics and restrictions
There are no restrictions on the use of the accept service.