recv (BPX1RCV, BPX4RCV) — Receive data on a socket and store it in a buffer

Function

The recv callable service receives data on a socket and stores it in a buffer. If no messages are available at the socket, the service either waits for a message to arrive, or fails with EWOULDBLOCK — depending on whether the socket has been 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: (BPX1RCV)	31-bit
AMODE: (BPX4RCV)	64-bit
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

CALL BPX1RCV,(Socket_descriptor,
              Buffer_length,
              Buffer,
              Buffer_alet,
              Flags,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4RCV 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 receive 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 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.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the recv service returns one of the following:

The number of bytes received into the buffer, if the request is successful. A value of 0 indicates that the connection is closed.
-1, if the request is not successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the recv service stores the return code. The recv 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 recv 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 recv() 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 code can accompany the return code: JRSocketClosed.
EIO	There has been a network or transport failure. The following reason code can accompany the return code: 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 received, 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 recv service stores the reason code. The recv 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 recv callable service applies only to connected sockets. It can be used with datagram or stream sockets. For datagram sockets, the recv service returns the entire datagram that was sent, providing that the datagram fits into the specified buffers. The excess is discarded. For stream sockets, data is not discarded. Multiple invocations of the recv service 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

send (BPX1SND, BPX4SND) — Send data on a socket

Characteristics and restrictions

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

Examples

For an example using this callable service, see BPX1RCV (recv) example.