NAME

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

SYNOPSIS

#include <sys/socket.h>

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

int sendto(

int s,
const void *msg,
int len,
int flags,
const void *to,
int tolen);

int sendmsg(int s, const struct msghdr msg[], int flags);

DESCRIPTION

send(), sendto(), and sendmsg() are used to transmit a message to another socket.  send() can be used only when the socket is in a connected state, whereas sendto() and sendmsg() can be used at any time.  sendmsg() allows the send data to be gathered from several buffers specified in the msghdr structure.  See recv(2) for a description of the msghdr structure. 

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(2)). 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().  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 fixed 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.  There are three ways to enable non-blocking mode:

• With the FIOSNBIO ioctl() request,

• With the O_NONBLOCK flag, and

• With the O_NDELAY fcntl() flag. 

If non-blocking I/O is enabled using FIOSNBIO or the equivalent FIONBIO request (defined in <sys/ioctl.h> and explained in ioctl(2) ioctl(5), and socket(7)), although use of FIONBIO is not recommended, 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() fails, having written no data, and errno is set to EWOULDBLOCK. 

If non-blocking I/O is disabled using FIOSNBIO, send() always executes completely (blocking as necessary) and returns the number of bytes written. 

If the O_NONBLOCK flag is set using fcntl() (defined in <sys/fcntl.h> and explained in fcntl(2) and fcntl(5)), POSIX-style non-blocking I/O is enabled.  In this case, 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, having written no data, and returns −1, with errno set to EAGAIN. 

If the O_NDELAY flag is set using fcntl() (defined in <sys/fcntl.h> and explained in fcntl(2) and fcntl(5)), non-blocking I/O is enabled.  In this case, 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. 

Since both the fcntl() O_NONBLOCK and O_NDELAY flags and FIOSNBIO ioctl() request are supported, some clarification on how these features interact is necessary.  If the O_NONBLOCK or O_NDELAY flag has been set, send() requests behave accordingly, regardless of any FIOSNBIO requests.  If neither the O_NONBLOCK nor O_NDELAY flag has been set, FIOSNBIO requests control the behavior of send().  If the O_NDELAY flag has not been set, FIOSNBIO requests control the behavior of send(). 

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() 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(2) call can be used to determine when it is possible to send more data.

AF_CCITT only:

Sockets of the address family AF_CCITT operate in message mode.  Although they are specified as connection-based (SOCK_STREAM) sockets, the X.25 subsystem communicates via messages.  They require that a connection be established with the connect() or accept() calls. 

The O_NDELAY flag is not supported, use FIOSNBIO requests to control non-blocking I/O.  If the available buffer space is not large enough for the entire message, and the socket is in non-blocking mode, the error EWOULDBLOCK is returned.  If the amount of data in the send() exceeds the maximum outbound message size, EMSGSIZE is returned. 

The sendto() call is not supported. 

Each call sends either a complete or a partial X.25 message.  This is controlled by the setting of More-Data-To-Follow (MDTF) bit.  If the user wants to send a partial message, MDTF should be set to 1 before the send() call.  The MDTF bit should be cleared to 0 before sending the final message fragment. 

Message fragment length may range from 0 bytes up to the size of the socket’s send buffer (see af_ccitt(7F)). The MDTF bit and multiple send() calls can be combined to transmit complete X.25 packet sequences (i.e., zero or more DATA packets in which the More Data bit is set, followed by one DATA packet in which the More Data bit is clear) of arbitrary length.  Note that a 0-byte message is not actually sent, but may be necessary to flush a complete X.25 message if the user is controlling the MDTF bit. 

Sockets of the AF_CCITT address family can send 1 byte of out-of-band data (known as INTERRUPT Data packet in X.25 terminology), or up to 32 bytes if the X.25 interface is configured for 1984 CCITT X.25 recommendations.  INTERRUPT data packets sent in blocking mode cause the process to block until confirmation is received.  INTERRUPT data packets sent with the socket in non-blocking mode do not cause the process to block; instead, an out-of-band message is queued to the socket when the INTERRUPT confirmation packet is received (see recv(2)).

DEPENDENCIES

UDP messages are fragmented at the IP level into Maximum Transmission Unit (MTU) sized pieces; MTU varies for different link types.  These pieces, called IP fragments, can be transmitted, but IP does not guarantee delivery.  Sending large messages may cause so many fragments to be created that some of them overrun a receiver’s ability to receive them, and hence are dropped.  If this happens, even if most of the fragments ultimately arrive at the destination, the complete message cannot be re-assembled.  This affects the apparent reliability and throughput of the network, as viewed by the end-user. 

Default and maximum buffer sizes are protocol-specific.  Refer to the appropriate entries in Sections 7F and 7P for details.  The buffer size can be set by calling setsockopt() with SO_SNDBUF. 

AF_CCITT

If the receiving process is on a Series 700/800 HP-UX system and the connection has been set up to use the D-bit, data sent with the D-bit set is acknowledged when the receiving process has read the data.  Otherwise, the acknowledgement is sent when the firmware receives it. 

If the receiving process is on a Series 300/400 HP-UX system, data sent with the D-bit set is acknowledged when the data reaches the X.25 interface card, but D-bit acknowledgement from a Series 300/400 does not imply that the receiving process has read the data. 

RETURN VALUE

Upon successful completion, send(), sendto(), and sendmsg() return the number of bytes sent.  Otherwise, they return −1 and set errno to indicate the error. 

DIAGNOSTICS

send(), sendto(), and sendmsg() fail if any of the following conditions are encountered:

[EACCES] Process doing a send() of a broadcast packet does not have broadcast capability enabled for the socket.  Use setsockopt() to enable broadcast capability. 

[EBADF] An invalid descriptor was specified. 

[ENOTSOCK] The argument s is not a socket. 

[EFAULT] An invalid pointer was specified in the msg or to parameter, or in the msghdr structure. 

[EMSGSIZE] A length in the msghdr structure is invalid.  The socket requires that messages be sent atomically, and the size of the message to be sent made this impossible.  SOCK_DGRAM/AF_INET and/or SOCK_STREAM/AF_CCITT Only: The message size exceeded the outbound buffer size. 

[EWOULDBLOCK] The socket is in non-blocking mode and the requested operation would block. 

[ENOBUFS] Insufficient network memory resources were available in the system to perform the operation. 

[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, or a length in the msghdr structure is invalid.  A sendto() system call was issued on an X.25 socket, or the connection is in its reset sequence and cannot accept data. 

[EDESTADDRREQ] The to parameter needs to specify a destination address for the message.  This is also given if the specified address contains unspecified fields (see inet(7F)).

[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. 

[EIO] A timeout occurred. 

[ENETDOWN] The interface used for the specified address is "down" (see ifconfig(1M)), or no interface for the specified address can be found, (SO_DONTROUTE socket option in use), or the X.25 Level 2 is down. 

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

[ENETUNREACH] (LAN) All encapsulations (e.g., ether, ieee) have been turned off (see also lanconfig(1M), and ifconfig(1M)).

(X.25) The X.25 Level 2 is down.  The X.25 link layer is not working (wires might be broken, or connections are loose on the interface hoods at the modem, or the modem failed, or the packet switch at the remote end lost power or failed for some reason, or electrical noise interfered with the line for an extremely long period of time). 

[ECONNRESET] A connection was forcibly closed by a peer. 

AUTHOR

send() was developed at the University of California, Berkeley. 

SEE ALSO

lanconfig(1M), ifconfig(1M), getsockopt(2), recv(2), select(2), setsockopt(2), socket(2), af_ccitt(7F), inet(7F), socket(7), socketx25(7), tcp(7P), udp(7P), unix(7P) .

Hewlett-Packard Company  —  HP-UX Release 9.03: April 1994