recvmsg (BPX2RMS, BPX4RMS) — Receive messages on a socket and store them in message buffers

Function

The recvmsg callable service receives messages on a socket and stores them in a set of buffers. The socket can be either connected or unconnected. If no messages are available at the socket, the service either waits for a message 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 (BPX2RMS):	31-bit
AMODE (BPX4RMS):	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 BPX2RMS,(Socket_descriptor,
              Message_hdr,
              Flags,
              Iov_alet,
              Iov_buffer_alet,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4RMS with the same parameters. All addresses in the Message_hdr structure are doublewords.

Parameters

Socket_descriptor

Supplied parameter

Type:: Integer
Length:: Fullword

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

Message_hdr

Supplied parameter

Type:: Structure
Length:: The length of BPXYMSGH

The name of a field that contains the message header, which describes how the message is to be received. See BPXYMSGH — Map the message header for more information about the format of this field. In 64-bit mode, Message_hdr contains doubleword pointer subfields, and points to an Iov_struct structure that contains doubleword pointer and length subfields.

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.

Iov_alet

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a field that contains the ALET for the IOV structure that is specified in Message_hdr.

Iov_buffer_alet

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a field that contains the ALET for the buffers that are pointed to by the IOV structure that is specified in Message_hdr.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

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

The number of bytes that were read into the buffers, 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 recvmsg service stores the return code. The recvmsg 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 recvmsg 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 recvmsg service before any data was available. The following reason code can accompany the return code: JRSockRdwrSignal.
EINVAL	The socket is marked shutdown for read; or incorrect data was received as a parameter. The following reason codes can accompany the return code: JRInvalidMsgh, JRSocketClosed, JRSocketCallParmError.
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: JRWouldBlock, JRTimeout.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the recvmsg service stores the reason code. The recvmsg 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

See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.
The BPX2RMS/BPX4RMS call supersedes the BPX1RMS call, which is still available for migration purposes only.
If the sendmsg security label is not equivalent to the recvmsg security label when access rights are passed on the sendmsg, the new descriptors are not created.
The number of buffers that are pointed to by the IOV structure in Message_hdr may not exceed IOV_MAX (defined in BPXYIOV — Map the I/O vector structure).
For the IP_PKTINFO ancillary data item, the program has to call setsockopt() or BPXIOPT(Sock#OptOptSetSockOpt) with the IP_RECVPKTINFO option to have the TCPIP stack pass the client's return information in the IN_PKTINFO structure as an ancillary data item on the recvmsg() or BPX2RMS call. That IP_PKTINFO data is used unchanged on the subsequent sendmsg() or BPX2SMS calls to have the reply flow out the same interface through which the request arrived.

Related services

sendmsg (BPX2SMS, BPX4SMS) — Send messages on a socket

Characteristics and restrictions

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

Examples

For an example using this callable service, see BPX2RMS (recvmsg) example.