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

Function

The sendmsg callable service sends messages on a socket.

Requirements

Parameters

Socket_descriptor

Supplied parameter

Type:

Integer

Length:

Fullword

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

Message_hdr

Supplied parameter

Type:

Structure

Length:

Length of BPXYMSGH

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

Flags

Supplied parameter

Type:

Structure

Length:

Fullword

The name of a field that contains information about how the data is to be sent. 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 sendmsg service returns one of the following:

• The number of bytes sent from 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 sendmsg service stores the return code. The sendmsg 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 sendmsg service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	For AF_UNIX sockets, search permission is denied for a component of the path prefix or write access to the named socket is denied.
EAFNOSUPPORT	The address family that was specified in the message header is not the same as the address family that owns the socket.
EBADF	A file descriptor that was not valid was supplied. The following reason codes can accompany the return code: JRFileDesNotInUse, JRFileNotOpen.
ECONNRESET	Connection reset by peer. The following reason code can accompany the return code: JRSockNotCon.
EINTR	A signal interrupted the sendmsg service before any data was written. The following reason code can accompany the return code: JRSockRdwrSignal.
EINVAL	Data that was not valid was sent to the request.The following reason codes can accompany the return code: JRInvalidMsgh, JRSocketCallParmError, and JRSockNoName.
EIO	There has been a network or transport failure. The following reason codes can accompany the return code: JRInetRecycled, JRPrevSockError.
EMSGSIZE	The message is too large to be sent all at once, as the socket requires. The following reason code can accompany the return code: JRSockBufMax.
ENOBUFS	A buffer could not be obtained. The following reason code can accompany the return code: JROutofSocketCells.
ENOTCONN	The socket was not connected. The following reason code can accompany the return code: JRSocketNotCon.
ENOTSOCK	Socket_descriptor does not refer to a valid socket descriptor. The following reason code can accompany the return code: JRMustBeSocket.
EPIPE	An attempt was made to send a message to a socket that is shut down or closed. The following reason code can accompany the return code: JRSocketClosed. This error also generates a SIGPIPE signal.
EWOULDBLOCK	The socket is marked nonblocking and no space is available for data to be written, or the SO_SNDTIMEO timeout value was reached before space became available. The socket is marked blocking. The call is blocked, without sending any data, for that time period which was specified in the SO_SNDTIMEO option. The following reason codes can accompany the return code: JRWouldBlock and JRTimeout.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

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

1. The socket can be either connected or unconnected.
2. If there is not enough room to write the data to an output buffer, the service either blocks waiting for an output buffer to become available, or returns an EWOULDBLOCK (depending on whether the socket is marked as blocking or nonblocking, and whether SO_SNDTIMEO timeout value was reached before space became available).
3. The BPX2SMS/BPX4SMS call supersedes the BPX1SMS call, which is still available for migration purposes only.
4. If the recvmsg security label is not equivalent to the sendmsg security label when access rights are passed on the sendmsg, the new descriptors are not created.
5. 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).
6. See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.

Related services

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

Characteristics and restrictions

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