sendto (BPX1STO, BPX4STO) — Send data on a socket

Function

The sendto callable service sends data 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 sendto 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 from which the data is to be sent.

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:

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.

Sockaddr_length

Supplied and returned parameter

Type:

Integer

Length:

Fullword

The name of a field that contains the length of Sockaddr. The size of this field should be less than 4096 bytes (4KB) in length. The size of the buffer that is specified should be the maximum length that the sockaddr could be on output.

Sockaddr

Supplied and returned parameter

Type:

Structure

Length:

Length specified by Sockaddr_length

The name of a socket address structure to which the data is to be sent. 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 sendto service returns one of the following:

• The number of bytes that were sent on the socket, 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 sendto service stores the return code. The sendto 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 sendto 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 sockaddr is not the same address family as the socket.
EBADF	A file descriptor that was not valid was specified.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: JRSocketNotCon.
EINTR	A signal interrupted the sendto service before any data was written. The following reason code can accompany the return code: JRSocketRdwrSignal.
EINVAL	An input parameter was incorrect. The following reason codes can accompany the return code: JRSocketCallParmError, 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 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.
EPROTOTYPE	The address specifies a socket that is not the correct type for this request.
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, JRTimeout.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the sendto service stores the reason code. The sendto 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. A datagram socket can be unconnected.
2. If the sending socket has no space to hold the message that is to be transmitted, the sendto 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. See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.

Related services

• recvfrom (BPX1RFM, BPX4RFM) — Receive data from a socket and store it in a buffer

Characteristics and restrictions

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