sendto() — Send Data on a Socket

Standards / Extensions C or C++ Dependencies
XPG4.2 both  

Format

X/Open 
#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/socket.h>

ssize_t sendto(int socket, const void *buffer, size_t length, int flags,
    const struct sockaddr *address,
     size_t address_length);
Berkeley Sockets 
#define _OE_SOCKETS
#include <sys/socket.h>

int sendto(int socket, char *buffer, int length, int flags,
           struct sockaddr *address, int address_len);

General Description

Sends data on the socket with the socket descriptor. The sendto() call applies to either connected or unconnected sockets.
socket
The socket descriptor.
buffer
The pointer to the buffer containing the message to transmit.
length
The length of the message in the buffer pointed to by the msg parameter.
flags
A parameter that can be set to one or more of the following for sockets in the AF_INET and AF_INET6 domains. It is ignored for AF_IUCV and AF_UNIX.
MSG_OOB
Sends out-of-band data on the socket. Only SOCK_STREAM sockets support out-of-band data. The out-of-band data is a single byte.

The recipient of the data determines whether or not to receive out-of-band data inline by the setting of the SO_OOBINLINE option of setsockopt(). For more information on receiving out-of-band data, see recv() — Receive Data on a Socket, recvfrom() — Receive Messages on a Socket, recvmsg() — Receive Messages on a Socket and Store in an Array of Message Headers, and setsockopt() — Set Options Associated with a Socket.

MSG_DONTROUTE
Turns on for the duration of the operation. This option is usually used only by diagnostic or routing programs.
address
The address of the target. For connected sockets, this address is ignored.
address_len
The size of the address pointed to by address.

If not enough buffer space is available to hold the socket data to be transmitted, and the socket is in blocking mode, sendto() blocks the caller until additional buffer space becomes available. If the socket is in nonblocking mode, sendto() returns a value of -1 and sets errno to EWOULDBLOCK. For a description of how to set nonblocking mode, see fcntl() — Control Open File Descriptors or ioctl() — Control Device.

For datagram sockets, this call sends the entire datagram, provided that the datagram fits into the TCP/IP buffers. Stream sockets act like streams of information with no boundaries separating data. For example, if an application wishes to send 1000 bytes, each call to this function can send 1 byte, or 10 bytes, or the entire 1000 bytes. Therefore, applications using stream sockets should place this call in a loop, calling this function until all data has been sent.

Special Behavior for C++

To use this function with C++, you must use the _XOPEN_SOURCE_EXTENDED 1 feature test macro.

Returned Value

If successful, sendto() returns the number of characters sent.

If unsuccessful, sendto() returns a value of -1 and sets errno to one of the values listed below. When used with datagram sockets, no indication of delivery failure is implied in the return value of this call.

A value of 0 or greater indicates the number of bytes sent; however, this does not assure that data delivery was complete. A connection can be dropped by a peer socket and a SIGPIPE signal generated at a later time if data delivery is incomplete.
EAFNOSUPPORT
The address family is not supported (it is not AF_INET, AF_INET6, AF_IUCV, or AF_UNIX).
EBADF
socket is not a valid socket descriptor.
ECONNREFUSED
The attempt to connect was rejected.
ECONNRESET
A connection was forcibly closed by a peer.
EFAULT
Using the buffer and length parameters would result in an attempt to access storage outside the caller's virtual machine.
EINTR
A signal interrupted sendto() before any data was transmitted.
EINVAL
address_len is not the size of a valid address for the specified address family.
EIO
A network or transport failure has occurred.
EMSGSIZE
The message was too big to be sent as a single datagram. The default is large-envelope-size. (Envelopes are used to hold datagrams and fragments during TCP/IP processing. Large envelopes hold UDP datagrams greater than 2KB while they are processed for output and when they are waiting for an application program to receive them on input.)
ENOBUFS
Buffer space is not available to send the message.
ENOTCONN
The socket is not connected.
ENOTSOCK
The descriptor is for a file, not for a socket.
EOPNOTSUPP
The socket argument is associated with a socket that does not support one or more of the values set in flags.
EPIPE
For a connected stream socket, the connection to the peer socket has been lost. A SIGPIPE signal is sent to the calling process.
EPROTOTYPE
The protocol is the wrong type for this socket. A SIGPIPE signal is sent to the calling process.
ESHUTDOWN
There is no data to read on the socket, and it has been shut down for reading.
EWOULDBLOCK
The socket is in nonblocking mode, and no data buffers are available.
The following are for AF_UNIX only:
EACCES
The process does not have search permission on a component of the path prefix, or it does not have write access to the named socket.
EIO
An I/O error occurred while reading from or writing to the file system.
ELOOP
Too many symbolic links were encountered in translating the path name in the socket address.
ENAMETOOLONG
A component of a path name exceeded NAME_MAX characters, or an entire path name exceeded PATH_MAX characters.
ENOENT
A component of the path name does not name an existing file, or the path name is an empty string.
ENOTDIR
A component of the path prefix of the path name in the socket address is not a directory.

Related Information