sendto: Send data on an unconnected socket

The sendto socket function sends data on unconnected sockets.

Last updated

  • Changed for PUT14.
  • Changed for PUT13.
  • Added for PUT00.

Format

#include    <sys/socket.h>
int         sendto(int s,
                   char *msg,
                   int len,
                   int flags;
                   struct sockaddr *to,
                   int tolen);
s
The socket descriptor.
msg
Pointer to the buffer containing the message to transmit.
len
Length of the message pointed to by the msg parameter.
Note:
  1. The maximum send buffer size is 1,048,576 bytes.
  2. The default value of the SO_SNDBUF option is 32767.
  3. For a TCP socket, the maximum length that you can specify is 1 GB.
  4. For a UDP or RAW socket, the maximum length that you can specify is the smaller of the following values:
    • 65,527 bytes (for a UDP socket) or 32,767 bytes (for a RAW socket).
    • The send buffer size defined by the SO_SNDBUF option.
flags
Set to 0 the following value:
MSG_DONTROUTE
The SO_DONTROUTE option is turned on for the duration of the operation. This is usually used only by diagnostic or routing programs.
to
Pointer to a sockaddr structure that contains the address of the socket to which the data will be sent.
tolen
Size, in bytes, of the sockaddr structure pointed to by the to parameter.

Normal return

If it succeeds, sendto returns the number of characters sent.

Error return

A return code equal to -1 indicates an error. You can get the specific error code by calling sock_errno. See z/TPF Transmission Control Protocol/Internet Protocol for more information about socket errors. The return value of this function when used with datagram sockets does not imply failure to deliver.
SOCDESTADDRREQ
Destination address is required.
SOCINVAL
The value of the tolen parameter is not the size of a valid address for the specified address family.
SOCMSGSIZE
The message was too large to be sent.
SOCNOBUFS
There is no buffer space available to send the message.
SOCNOTCONN
A stream socket was used to issue the sendto function, and the socket was not connected.
SOCNOTSOCK
The s parameter is not a valid socket descriptor.
SOCWOULDBLOCK
The s parameter is in nonblocking mode and no buffer space is available to hold the message to be sent.
E1052STATE
The socket was closed because the system was in or cycling down to 1052 state.
ESYSTEMERROR
A system error has occurred and closed the socket.
SOCTIMEDOUT
The operation timed out. The socket is still available.
SOCCONNREFUSED

A UNIX domain socket was used to issue the sendto function to a remote UDP UNIX domain socket that does not exist.

Programming considerations

  • The sendto function applies to any unconnected socket.
  • Use the send or write function instead of the sendto function for connected sockets.
  • If buffer space is not available at the socket to hold the message to be sent, the sendto function normally blocks, unless the socket is in nonblocking mode. See ioctl: Perform special operations on socket for a description of how to set nonblocking mode. If the socket is in nonblocking mode, sendto returns a -1 and sets sock_errno to SOCWOULDBLOCK.
  • For datagram sockets, this function sends the entire datagram, providing the datagram fits into the TCP/IP buffers.
  • If a bind has not yet been issued to the socket, a bind is issued on behalf of the application for a non-stream socket.
  • The send timeout value (the SO_SNDTIMEO setsockopt option) determines how long to wait for space to become available in the send buffer before the sendto function times out.
  • Applications are required to send complete messages. Sending a message in fragments on a RAW socket is not supported.
  • For TCP sockets, if the value you specify for the len parameter is less than or equal to the send buffer size of the socket, the send process will be atomic; that is, either all of the data will be sent or none of it will be sent. If all of the data is sent, the return code is set to the value of the len parameter. If none of the data is sent, the return code is set to -1.
  • For TCP sockets, if the value you specify for the len parameter is greater than the send buffer size of the socket, the z/TPF system will take as much data as possible and return to the application indicating that only part of the data was processed. The application must issue more send calls for the remaining data and the application must serialize the send calls if the socket is being shared by multiple ECBs. If the send call is successful, the return code is set to a value from 1 to the value of the len parameter, which indicates how much data was sent.
  • If the to parameter has an IP address that is set to 0, the system uses the loopback IP address (127.0.0.1).

Examples

In the following example, 100 bytes are sent to an application with IP address 129.5.24.1 and port number 5001. 
#include <sys/socket.h>
⋮
int    bytes_sent;
int    server_sock;
char   send_msg[100];
struct sockaddr_in to_addr;
⋮
to_addr.sin_family      = AF_INET;
to_addr.sin_port        = 5001;
to_addr.sin_addr.s_addr = inet_addr("129.5.24.1");
bytes_sent = sendto(server_sock, send_msg, sizeof(send_msg), 0,
                    (struct sockaddr *)&to_addr, sizeof(to_addr));
⋮