recvfrom (BPX1RFM, BPX4RFM) — Receive data from a socket and store it in a buffer
Function
The recvfrom callable service receives data on a socket and stores it in a buffer. It can be used by an application program to receive data from sockets. When no data is available at the socket, the service either waits for data to arrive, or returns an EWOULDBLOCK — depending on whether the socket is defined as blocking or nonblocking, and whether the SO_RCVTIMEO socket option is in effect.
Requirements
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task or SRB |
Cross memory mode: | PASN = HASN |
AMODE (BPX1RFM): | 31-bit task or SRB mode |
AMODE (BPX4RFM): | 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
|
AMODE 64 callers use BPX4RFM 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 recvfrom is to be done.
- Buffer_length
- Supplied and returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a field that contains the length of Buffer.
- Buffer
- Supplied parameter
- Type:
- Character
- Length:
- Length specified by Buffer_length
The name of a field into which the data is to be received.
- Buffer_alet
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a field that contains the ALET for Buffer. You should specify a Buffer_alet of 0 for the normal case of a buffer in the user's address space (current primary address space). If a value other than 0 is specified for the Buffer_alet, the value must represent a valid entry in the dispatchable unit access list (DUAL).
- Flags
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a field that contains information about how the data is to be received. See BPXYMSGF — Map the message flags for more information about the format of this field.
- Sockaddr_length
- Supplied and returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a field that, on input, contains the length of the Sockaddr buffer. 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 value in this field should be less than 4096 bytes (4KB) in length, and should represent the maximum possible length of the Sockaddr on output.
- Sockaddr
- Supplied and returned parameter
- Type:
- Structure
- Length:
- Length specified by Sockaddr_length
The name of a buffer area that, on return, contains the socket address of the sender of the data. See BPXYSOCK — Map SOCKADDR structure and constants for more information about the format of this field.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the recvfrom service returns one of the following:- The number of bytes received into the buffer, 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 recvfrom service stores the return code. The recvfrom 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 recvfrom service can return one of the following values 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, JRFileNotOpen. EINTR A signal interrupted the recvfrom function before any data was available. The following reason code can accompany the return code: JRSockRdwrSignal. EINVAL The socket is marked shutdown for read. The following reason codes can accompany the return code: JRSocketCallParmError, JRSocketClosed. EIO There has been a network or transport failure. The following reason codes can accompany the return code: JRInetRecycled, JRPrevSockError. 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. EWOULDBLOCK - The socket is marked nonblocking and no data is waiting to be read, or the SO_RCVTIMEO timeout value was reached before data was available.
- The socket is marked blocking, and the call has blocked for that time period which was specified in the SO_RCVTIMEO option without receiving any data.
The following reason codes can accompany the return code: JRTimeout, JRWouldBlock.
- Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the recvfrom service stores the reason code. The recvfrom 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
- The recvfrom callable service can be used with datagram or stream sockets. For datagram sockets, it returns the entire datagram that was sent, providing that the datagram fits into the specified buffer. The excess is discarded. For stream sockets, data is not discarded. Multiple invocations of recvfrom may be needed to return all the data.
- See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.
Related services
Characteristics and restrictions
There are no restrictions on the use of the recvfrom service.
Examples
For an example using this callable service, see BPX1RFM (recvfrom) example.