send(2) send(2)
NAME
send(), sendmsg(), sendto() - 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);
_XOPEN_SOURCE_EXTENDED only
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,
size_t tolen
);
ssize_t sendmsg(int s, const struct msghdr *msg, int flags);
DESCRIPTION
The send(), sendmsg(), and sendto() system calls transmit a message to
another socket. send() can be used only when the socket is in a
connected state, whereas sendmsg() and sendto() 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 socket is contained in a socket address
structure pointed to 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). Otherwise there is no size limit.
When send() or sendto() returns a positive value, it only indicates
this number of bytes have been sent to the local transport provider.
It does not mean this number of bytes have been delivered to the peer
socket application. A SOCK_DGRAM socket does not guarantee end-to-end
delivery. A SOCK_STREAM socket guarantees eventual end-to-end
delivery, however its underlying transport provider may later detect
an irrecoverable error and returns a value of -1 at another socket
function call.
When send() or sendto() returns a value of -1 , it indicates a locally
detected error. errno is set to indicate the error.
If no buffer space is available to hold the data to be transmitted,
send() blocks unless nonblocking mode is enabled. The three ways to
enable nonblocking mode are:
o with the FIOSNBIO ioctl() request,
o with the O_NONBLOCK flag, and
o with the O_NDELAY fcntl() flag.
If nonblocking 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 the use of FIONBIO is not recommended, the
send() request completes in one of three ways:
o If there is enough space available in the system to buffer all
of the data, send() completes successfully, having written out
all of the data, and returns the number of bytes written.
o 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.
o 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 nonblocking 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 nonblocking I/O
is enabled. In this case, the send() request completes in one of
three ways:
o If there is enough space available in the system to buffer all
of the data, send() completes successfully, having written out
all of the data, and returns the number of bytes written.
o 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.
o 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)), nonblocking I/O is enabled.
In this case, the send() request completes in one of three ways:
o If there is enough space available in the system to buffer all
of the data, send() completes successfully, having written out
all of the data, and returns the number of bytes written.
o 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.
o 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(), nonblocking I/O is
disabled. In this case, the send() always executes completely
(blocking as necessary) and returns the number of bytes written.
Since the fcntl() O_NONBLOCK and O_NDELAY flags and ioctl() FIOSNBIO
requests are supported, the following clarifies on how these features
interact. 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 flag nor the O_NDELAY flag has been set,
FIOSNBIO requests control the behavior of send().
By default nonblocking I/O is disabled.
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.
select(2) 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
nonblocking I/O. If the available buffer space is not large enough
for the entire message and the socket is in nonblocking mode, errno is
set to [EWOULDBLOCK]. If the amount of data in the send() exceeds the
maximum outbound message size, errno is set to [EMSGSIZE].
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 the 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 an 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 nonblocking 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)).
_XOPEN_SOURCE_EXTENDED only
X/Open Sockets msghdr has the following form :
struct msghdr {
void *msg_name; /* optional address */
size_t msg_namelen; /* size of address */
struct iovec *msg_iov; /* scatter array for data */
int msg_iovlen; /* # of elements in msg_iov */
void *msg_control; /* ancillary data, see below */
size_t msg_controllen; /* ancillary data buffer len */
int msg_flags; /* flags on received message */
}
msg_control specifies a buffer of ancillary data to send along with
the message. Ancillary data consists of a sequence of pairs, each
consisting of a cmsghdr structure followed by a data array. The data
array contains the ancillary data message, and the cmsghdr structure
contains descriptive information that allows an application to
correctly parse the data. cmsghdr has the following structure:
struct cmsghdr {
size_t cmsg_len; /* data byte count, including hdr*/
int cmsg_level; /* originating protocol */
int cmsg_type; /* protocol-specific type */
}
The supported value for cmsg_level is SOL_SOCKET. and the supported
value for cmsg_type is SCM_RIGHTS. Together they indicate the data
array contains the access rights to be sent. Access rights are
supported only for AF_UNIX. Access rights are limited to file
descriptors of size int. If ancillary data are not being transferred,
set the msg_control field to NULL and set the msg_controllen field to
0.
The msg_flags member is ignored.
RETURN VALUE
send(), sendmsg(), and sendto() return the following values:
n Successful completion. n is the number of bytes sent.
-1 Failure. errno is set to indicate the error.
ERRORS
If send(), sendmsg(), or sendto() fails, errno is set to one of the
following values.
[EACCES] Process doing a send() of a broadcast packet
does not have broadcast capability enabled
for the socket. Use setsockopt() to enable
broadcast capability.
[EAFNOSUPPORT] The specified address is not a valid address
for the address family of this socket.
[EAGAIN] Nonblocking I/O is enabled using the
O_NONBLOCK flag with fcntl(), and the
requested operation would block, or the
socket has an error that was set
asynchronously. An asynchronous error can be
caused by a gateway failing to forward a
datagram from this socket because the
datagram exceeds the MTU of the next-hop
network and the "Don't Fragment" (DF) bit in
the datagram is set. (See SO_PMTU in
getsockopt(2)).
[EBADF] s is not a valid file descriptor.
[ECONNRESET] A connection was forcibly closed by a peer.
[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)).
[EFAULT] An invalid pointer was specified in the msg
or to parameter, or in the msghdr structure.
[EINTR] The operation was interrupted by a signal
before any data was sent. (If some data was
sent, send() returns the number of bytes sent
before the signal, and [EINTR] is not set).
[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.
[EIO] A timeout occurred.
[EISCONN] An address was specified by to for a
SOCK_DGRAM socket which is already connected.
[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 or SOCK_STREAM/AF_CCITT:
The message size exceeded the outbound buffer
size.
[ENETDOWN] The interface used for the specified address
is "down" (see ifconfig(1M)), no interface
for the specified address can be found
(SO_DONTROUTE socket option in use), or the
X.25 Level 2 is down.
[EHOSTUNREACH] The destination host is not reachable.
[ENETUNREACH] The destination network is not reachable.
Some of the possible causes for this error
are:
(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, connections are loose on the
interface hoods at the modem, the modem
failed, 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).
[ENOBUFS] No buffer space is available in the system to
perform the operation.
[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.
[ENOTSOCK] s is a valid file descriptor, but it is not a
socket.
[EOPNOTSUPP] The MSG_OOB flag was specified; it is not
supported for AF_UNIX sockets.
[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.
[EWOULDBLOCK] Nonblocking I/O is enabled using ioctl()
FIOSNBIO request and the requested operation
would block.
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 too many
fragments and overrun a receiver's ability to receive them. If this
happens the complete message cannot be reassembled. This affects the
apparent reliability and throughput of the network as viewed by the
end user.
The 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.
AUTHOR
send() was developed at the University of California, Berkeley.
FUTURE DIRECTION
The default behavior in this release is still the classic HP-UX BSD
Sockets, however it will be changed to X/Open Sockets in some future
release. At that time, any HP-UX BSD Sockets behavior which is
incompatible with X/Open Sockets may be obsoleted. HP customers are
advised to migrate their applications to conform to X/Open
specification( see xopen_networking(7) ).
SEE ALSO
ifconfig(1M), lanconfig(1M), getsockopt(2), recv(2), select(2),
setsockopt(2), socket(2), socket(7), socketx25(7), af_ccitt(7F),
inet(7F), tcp(7P), udp(7P), unix(7P), xopen_networking(7).
STANDARDS CONFORMANCE
send(): XPG4
Hewlett-Packard Company - 8 - HP-UX Release 10.20: July 1996