send(3)

NAME
send, sendto - send a message from a socket

SYNOPSIS
#include <sys/socket.h>

int send(int s, void *msg, size_t len, int flags);

  AF_UNIX only:
#include <sys/un.h>

int sendto(int s, void *msg, size_t len, int flags,
    struct sockaddr *to, size_t tolen);

DESCRIPTION
send and sendto are used to transmit a message to another socket. send can be used only when the socket is in a connected state, whereas sendto can be used at any time.

s is a socket descriptor that specifies the socket on which the message will be sent. msg points to the buffer containing the message.

If the socket uses connection-based communications, such as a SOCK_STREAM socket, these calls can only be used after the connection has been established (see connect(3)). In this case, any destination specified by to is ignored. For connectionless sockets, such as SOCK_DGRAM, sendto must be used unless the destination address has already been specified by connect(3). If the destination address has been specified and sendto is used, an error results if any address is specified by to.

The address of the target is contained in a socket address structure pointed at by to, with tolen specifying the size of the structure.

If a sendto is attempted on a SOCK_DGRAM socket before any local address has been bound to it, the system automatically selects a local address to be used for the message. In this case, there is no guarantee that the same local address will be used for successive sendto requests on the same socket.

The length of the message is given by len, in bytes. The length of data actually sent is returned. If the message is too long to pass atomically through the underlying protocol, the message is not transmitted, -1 is returned, and errno is set to EMSGSIZE. For SOCK_DGRAM sockets, this size is limited by the implementation (see the DEPENDENCIES section below). Otherwise there is no size limit.

No indication of failure to deliver is implicit in a send/sendto. Return values of -1 indicate some locally-detected errors.

If no buffer space is available to hold the data to be transmitted, send blocks unless non-blocking mode is enabled. You can enable non-blocking mode by setting the O_NDELAY flag using fcntl. O_NDELAY is defined in <fcntl.h>. If non-blocking mode is enabled, the send request completes in one of three ways:

    •   If there is enough space available in the system to buffer all the data, send completes successfully, having written out all of the data, and returns the number of bytes written.

    •   If there is not enough space in the buffer to write out the entire request, send completes successfully, having written as much data as possible, and returns the number of bytes it was able to write.

    •   If there is no space in the system to buffer any of the data, send completes successfully, having written no data, and returns 0.

If the O_NDELAY flag is cleared using fcntl, non-blocking I/O is disabled. In this case, the send always executes completely (blocking as necessary) and returns the number of bytes written. The default is that non-blocking I/O is not enabled.

The supported values for flags are zero, or MSG_OOB (to send out-of-band data). A write(3) call made to a socket behaves in exactly the same way as send with flags set to zero. MSG_OOB is not supported for AF_UNIX sockets.

The select(3) call can be used to determine when it is possible to send more data.

DEPENDENCIES
Default and maximum buffer sizes are protocol-specific. The buffer size can be set by calling setsockopt(3) with SO_SNDBUF.

RETURN VALUE
If successful, the call returns the number of bytes sent. If the call fails, -1 is returned.

DIAGNOSTICS
send or sendto fails if:

    [EBADF]
        An invalid descriptor was specified.

    [EMSGSIZE]
        The socket requires that messages be sent atomically, and the size of the message to be sent made this impossible.

    [EINTR]
        The operation was interrupted by a signal before any data were sent. (If some data was sent, send returns the number of bytes sent before the signal, and EINTR is not given.)

    [EINVAL]
        The len or tolen parameter is invalid or the specified destination address is not valid. The argument s is not a socket.

    [EDESTADDRREQ]
        The to parameter needs to specify a destination address for the message.

    [ENOTCONN]
        A send on a socket that is not connected, or a send on a socket that has not completed the connect sequence with its peer, or is no longer connected to its peer.

    [EISCONN]
        An address was specified by to for a SOCK_DGRAM socket which is already connected.

    [EAFNOSUPPORT]
        Requested address does not match the address family of this socket.

    [EPIPE] and SIGPIPE signal
        An attempt was made to send on a socket that was connected, but the connection has been shut down, either by the remote peer or by this side of the connection. Note that the default action for SIGPIPE, unless the process has established a signal handler for this signal, is to terminate the process.

    [EOPNOTSUPP]
        The MSG_OOB flag was specified; it is not supported for AF_UNIX sockets.

SEE ALSO
getsockopt(3), recv(3), select(3), setsockopt(3), socket(3).