May 9, 2008 SEND 2

### NAME

send, sendto, sendmsg - send a message from a socket

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```ssize_t` send(```int s``, const void *msg``, size_t len``, int flags`)
```ssize_t` sendto(```int s``, const void *msg``, size_t len``, int flags``, const struct sockaddr *to``, socklen_t tolen`)
```ssize_t` sendmsg(```int s``, const struct msghdr *msg``, int flags`)

### DESCRIPTION

send(``), sendto(``), and sendmsg(``) are used to transmit a message to another socket. send(``) may be used only when the socket is in a connected state, while sendto(``) and sendmsg(``) may be used at any time.

The address of the target is given by ```to` with ```tolen` specifying its size. The length of the message is given by ```len`. If the message is too long to pass atomically through the underlying protocol, the error ```EMSGSIZE` is returned, and the message is not transmitted.

No indication of failure to deliver is implicit in a send(``). Locally detected errors are indicated by a return value of -1.

If no messages space is available at the socket to hold the message to be transmitted, then send(``) normally blocks, unless the socket has been placed in non-blocking I/O mode. The select(2) or poll(2) call may be used to determine when it is possible to send more data.

The ```flags` parameter may include one or more of the following: ``

    #define MSG_OOB         0x0001 /* process out-of-band data */
    #define MSG_PEEK        0x0002 /* peek at incoming message */
    #define MSG_DONTROUTE   0x0004 /* bypass routing, use direct interface */
    #define MSG_EOR         0x0008 /* data completes record */
    #define MSG_NOSIGNAL    0x0400 /* do not generate SIGPIPE on EOF */

The flag ```MSG_OOB` is used to send ``out-of-band'' data on sockets that support this notion (e.g. ```SOCK_STREAM`); the underlying protocol must also support ``out-of-band'' data. ```MSG_EOR` is used to indicate a record mark for protocols which support the concept. ```MSG_DONTROUTE` is usually used only by diagnostic or routing programs.

See recv(2) for a description of the ```msghdr` structure. ```MSG_NOSIGNAL` is used to prevent ```SIGPIPE` generation when writing a socket that may be closed.

### RETURN VALUES

The call returns the number of characters sent, or -1 if an error occurred.

### ERRORS

send(``), sendto(``), and sendmsg(``) fail if:

[```EBADF`]
  An invalid descriptor was specified.

[```ENOTSOCK`]
  The argument ```s` is not a socket.

[```EFAULT`]
  An invalid user space address was specified for a parameter.

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

[```EPIPE`]
  In a connected socket the connection has been broken.

[```EDSTADDRREQ`]
  In a non-connected socket a destination address has not been specified.

[```EAGAIN|EWOULDBLOCK`]
  The socket is marked non-blocking and the requested operation would block.

[```ENOBUFS`]
  The system was unable to allocate an internal buffer. The operation may succeed when buffers become available.

[```ENOBUFS`]
  The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion.

[```EACCES`]
  The SO_BROADCAST option is not set on the socket, and a broadcast address was given as the destination.

[```EHOSTUNREACH`]
  The destination for the message is unreachable.

[```EHOSTDOWN`]
  The destination is a host on the local subnet and does not respond to arp(4).

[```EINVAL`]
  The total length of the I/O is more than can be expressed by the ssize_t return value.

[```EAFNOSUPPORT`]
  Addresses in the specified address family cannot be used with this socket.

sendto(``) will also fail if:

[```EISCONN`]
  A destination address was specified and the socket is already connected.

sendmsg(``) will also fail if:

[```EMSGSIZE`]
  The ```msg_iovlen` member of the ```msg` structure is less than or equal to 0 or is greater than ```{IOV_MAX}`.

### SEE ALSO

fcntl(2), getsockopt(2), recv(2), select(2), socket(2), write(2)

### HISTORY

The send(``) function call appeared in 4.2BSD.