Standards
Standards / Extensions |
C or C++ |
Dependencies |
XPG4.2
Single UNIX Specification, Version 3
|
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_len);
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
The sendto()
function sends data on the socket with descriptor
socket.
The sendto() call applies to either connected or unconnected sockets.
- Parameter
- Description
- 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
- Setting these flags is not supported in the AF_UNIX domain. The
following flags are available:
- 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.
Before
out-of-band data can be sent between two programs, there must be some
coordination of effort. If the data is intended to not be read inline,
the recipient of the out-of-band data must specify the recipient of
the SIGURG signal that is generated when the out-of-band data is sent.
If no recipient is set, no signal is sent. The recipient is set up
by using F_SETOWN operand of the fcntl() command, specifying either
a pid or gid. For more information on this operand, refer to the fcntl()
command.
The recipient of the data determines whether to receive
out-of-band data inline or not inline by the setting of the SO_OOBINLINE
option of setsockopt(). For more information on receiving out-of-band
data, refer to the setsockopt(), recv(), recvfrom() and recvmsg()
commands.
- 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.
- address
- The address of the target.
- addr_len
- The size of the address pointed to by address.
If there is not enough available buffer space
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
-1 and sets the error code to EWOULDBLOCK. See fcntl() — Control open file descriptors or ioctl() — Control device for
a description of how to set nonblocking mode.
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.
Socket
address structure for IPv6: The sockaddr_in6 structure is added
to the netinit/in.h header. It is used to pass IPv6 specific
addresses between applications and the system.
Special behavior
for C++: To
use this function with C++, you
must use the _XOPEN_SOURCE_EXTENDED 1 feature test macro.
Note: The
sendto() function has a dependency on the level of the Enhanced ASCII
Extensions. See
Enhanced ASCII support for details.
Returned value
If successful, sendto()
returns the number of characters sent.
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 not complete.
No indication of failure to deliver
is implied in the return value of this call when used with datagram
sockets.
If unsuccessful, sendto() returns -1 and sets errno
to one of the following values:
- Error Code
- Description
- EAFNOSUPPORT
- The address family is not supported (it is not AF_UNIX or AF_INET).
- 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 msg and length parameters
would result in an attempt to access storage outside the caller's
address space.
- EINTR
- A signal interrupted sendto() before any data was transmitted.
- EINVAL
- addr_len is not the size of a valid
address for the specified address family.
- EIO
- There has been a network or transport failure.
- 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.
- EWOULDBLOCK
- socket is in nonblocking mode and no
data buffers are available or the SO_SNDTIMEO timeout value was reached
before buffers became available.
The following are for AF_UNIX only:
- Error Code
- Description
- EACCES
- Search permission is denied for a component of the path prefix,
or write access to the named socket is denied.
- 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.