674 lines
15 KiB
HTML
674 lines
15 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of SEND</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>SEND</H1>
|
|
Section: Linux Programmer's Manual (2)<BR>Updated: 2017-09-15<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
send, sendto, sendmsg - send a message on a socket
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<PRE>
|
|
<B>#include <<A HREF="file:///usr/include/sys/types.h">sys/types.h</A>></B>
|
|
<B>#include <<A HREF="file:///usr/include/sys/socket.h">sys/socket.h</A>></B>
|
|
|
|
<B>ssize_t send(int </B><I>sockfd</I><B>, const void *</B><I>buf</I><B>, size_t </B><I>len</I><B>, int </B><I>flags</I><B>);</B>
|
|
|
|
<B>ssize_t sendto(int </B><I>sockfd</I><B>, const void *</B><I>buf</I><B>, size_t </B><I>len</I><B>, int </B><I>flags</I><B>,</B>
|
|
<B> const struct sockaddr *</B><I>dest_addr</I><B>, socklen_t </B><I>addrlen</I><B>);</B>
|
|
|
|
<B>ssize_t sendmsg(int </B><I>sockfd</I><B>, const struct msghdr *</B><I>msg</I><B>, int </B><I>flags</I><B>);</B>
|
|
</PRE>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
The system calls
|
|
<B>send</B>(),
|
|
|
|
<B>sendto</B>(),
|
|
|
|
and
|
|
<B>sendmsg</B>()
|
|
|
|
are used to transmit a message to another socket.
|
|
<P>
|
|
|
|
The
|
|
<B>send</B>()
|
|
|
|
call may be used only when the socket is in a
|
|
<I>connected</I>
|
|
|
|
state (so that the intended recipient is known).
|
|
The only difference between
|
|
<B>send</B>()
|
|
|
|
and
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
|
|
|
|
is the presence of
|
|
<I>flags</I>.
|
|
|
|
With a zero
|
|
<I>flags</I>
|
|
|
|
argument,
|
|
<B>send</B>()
|
|
|
|
is equivalent to
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2).
|
|
|
|
Also, the following call
|
|
<P>
|
|
|
|
<BR> send(sockfd, buf, len, flags);
|
|
<P>
|
|
|
|
is equivalent to
|
|
<P>
|
|
|
|
<BR> sendto(sockfd, buf, len, flags, NULL, 0);
|
|
<P>
|
|
|
|
The argument
|
|
<I>sockfd</I>
|
|
|
|
is the file descriptor of the sending socket.
|
|
<P>
|
|
|
|
If
|
|
<B>sendto</B>()
|
|
|
|
is used on a connection-mode
|
|
(<B>SOCK_STREAM</B>,
|
|
|
|
<B>SOCK_SEQPACKET</B>)
|
|
|
|
socket, the arguments
|
|
<I>dest_addr</I>
|
|
|
|
and
|
|
<I>addrlen</I>
|
|
|
|
are ignored (and the error
|
|
<B>EISCONN</B>
|
|
|
|
may be returned when they are
|
|
not NULL and 0), and the error
|
|
<B>ENOTCONN</B>
|
|
|
|
is returned when the socket was not actually connected.
|
|
Otherwise, the address of the target is given by
|
|
<I>dest_addr</I>
|
|
|
|
with
|
|
<I>addrlen</I>
|
|
|
|
specifying its size.
|
|
For
|
|
<B>sendmsg</B>(),
|
|
|
|
the address of the target is given by
|
|
<I>msg.msg_name</I>,
|
|
|
|
with
|
|
<I>msg.msg_namelen</I>
|
|
|
|
specifying its size.
|
|
<P>
|
|
|
|
For
|
|
<B>send</B>()
|
|
|
|
and
|
|
<B>sendto</B>(),
|
|
|
|
the message is found in
|
|
<I>buf</I>
|
|
|
|
and has length
|
|
<I>len</I>.
|
|
|
|
For
|
|
<B>sendmsg</B>(),
|
|
|
|
the message is pointed to by the elements of the array
|
|
<I>msg.msg_iov</I>.
|
|
|
|
The
|
|
<B>sendmsg</B>()
|
|
|
|
call also allows sending ancillary data (also known as control information).
|
|
<P>
|
|
|
|
If the message is too long to pass atomically through the
|
|
underlying protocol, the error
|
|
<B>EMSGSIZE</B>
|
|
|
|
is returned, and the message is not transmitted.
|
|
<P>
|
|
|
|
No indication of failure to deliver is implicit in a
|
|
<B>send</B>().
|
|
|
|
Locally detected errors are indicated by a return value of -1.
|
|
<P>
|
|
|
|
When the message does not fit into the send buffer of the socket,
|
|
<B>send</B>()
|
|
|
|
normally blocks, unless the socket has been placed in nonblocking I/O
|
|
mode.
|
|
In nonblocking mode it would fail with the error
|
|
<B>EAGAIN</B>
|
|
|
|
or
|
|
<B>EWOULDBLOCK</B>
|
|
|
|
in this case.
|
|
The
|
|
<B><A HREF="/cgi-bin/man/man2html?2+select">select</A></B>(2)
|
|
|
|
call may be used to determine when it is possible to send more data.
|
|
<A NAME="lbAE"> </A>
|
|
<H3>The flags argument</H3>
|
|
|
|
The
|
|
<I>flags</I>
|
|
|
|
argument is the bitwise OR
|
|
of zero or more of the following flags.
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><B>MSG_CONFIRM</B> (since Linux 2.3.15)
|
|
|
|
<DD>
|
|
Tell the link layer that forward progress happened: you got a successful
|
|
reply from the other side.
|
|
If the link layer doesn't get this
|
|
it will regularly reprobe the neighbor (e.g., via a unicast ARP).
|
|
Valid only on
|
|
<B>SOCK_DGRAM</B>
|
|
|
|
and
|
|
<B>SOCK_RAW</B>
|
|
|
|
sockets and currently implemented only for IPv4 and IPv6.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?7+arp">arp</A></B>(7)
|
|
|
|
for details.
|
|
<DT id="2"><B>MSG_DONTROUTE</B>
|
|
|
|
<DD>
|
|
Don't use a gateway to send out the packet, send to hosts only on
|
|
directly connected networks.
|
|
This is usually used only
|
|
by diagnostic or routing programs.
|
|
This is defined only for protocol
|
|
families that route; packet sockets don't.
|
|
<DT id="3"><B>MSG_DONTWAIT</B> (since Linux 2.2)
|
|
|
|
<DD>
|
|
Enables nonblocking operation; if the operation would block,
|
|
<B>EAGAIN</B>
|
|
|
|
or
|
|
<B>EWOULDBLOCK</B>
|
|
|
|
is returned.
|
|
This provides similar behavior to setting the
|
|
<B>O_NONBLOCK</B>
|
|
|
|
flag (via the
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fcntl">fcntl</A></B>(2)
|
|
|
|
<B>F_SETFL</B>
|
|
|
|
operation), but differs in that
|
|
<B>MSG_DONTWAIT</B>
|
|
|
|
is a per-call option, whereas
|
|
<B>O_NONBLOCK</B>
|
|
|
|
is a setting on the open file description (see
|
|
<B><A HREF="/cgi-bin/man/man2html?2+open">open</A></B>(2)),
|
|
|
|
which will affect all threads in the calling process
|
|
and as well as other processes that hold file descriptors
|
|
referring to the same open file description.
|
|
<DT id="4"><B>MSG_EOR</B> (since Linux 2.2)
|
|
|
|
<DD>
|
|
Terminates a record (when this notion is supported, as for sockets of type
|
|
<B>SOCK_SEQPACKET</B>).
|
|
|
|
<DT id="5"><B>MSG_MORE</B> (since Linux 2.4.4)
|
|
|
|
<DD>
|
|
The caller has more data to send.
|
|
This flag is used with TCP sockets to obtain the same effect
|
|
as the
|
|
<B>TCP_CORK</B>
|
|
|
|
socket option (see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+tcp">tcp</A></B>(7)),
|
|
|
|
with the difference that this flag can be set on a per-call basis.
|
|
<DT id="6"><DD>
|
|
Since Linux 2.6, this flag is also supported for UDP sockets, and informs
|
|
the kernel to package all of the data sent in calls with this flag set
|
|
into a single datagram which is transmitted only when a call is performed
|
|
that does not specify this flag.
|
|
(See also the
|
|
<B>UDP_CORK</B>
|
|
|
|
socket option described in
|
|
<B><A HREF="/cgi-bin/man/man2html?7+udp">udp</A></B>(7).)
|
|
|
|
<DT id="7"><B>MSG_NOSIGNAL</B> (since Linux 2.2)
|
|
|
|
<DD>
|
|
Don't generate a
|
|
<B>SIGPIPE</B>
|
|
|
|
signal if the peer on a stream-oriented socket has closed the connection.
|
|
The
|
|
<B>EPIPE</B>
|
|
|
|
error is still returned.
|
|
This provides similar behavior to using
|
|
<B><A HREF="/cgi-bin/man/man2html?2+sigaction">sigaction</A></B>(2)
|
|
|
|
to ignore
|
|
<B>SIGPIPE</B>,
|
|
|
|
but, whereas
|
|
<B>MSG_NOSIGNAL</B>
|
|
|
|
is a per-call feature,
|
|
ignoring
|
|
<B>SIGPIPE</B>
|
|
|
|
sets a process attribute that affects all threads in the process.
|
|
<DT id="8"><B>MSG_OOB</B>
|
|
|
|
<DD>
|
|
Sends
|
|
<I>out-of-band</I>
|
|
|
|
data on sockets that support this notion (e.g., of type
|
|
<B>SOCK_STREAM</B>);
|
|
|
|
the underlying protocol must also support
|
|
<I>out-of-band</I>
|
|
|
|
data.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H3>sendmsg()</H3>
|
|
|
|
The definition of the
|
|
<I>msghdr</I>
|
|
|
|
structure employed by
|
|
<B>sendmsg</B>()
|
|
|
|
is as follows:
|
|
<P>
|
|
|
|
|
|
|
|
struct msghdr {
|
|
<BR> void *msg_name; /* Optional address */
|
|
<BR> socklen_t msg_namelen; /* Size of address */
|
|
<BR> struct iovec *msg_iov; /* Scatter/gather array */
|
|
<BR> size_t msg_iovlen; /* # elements in msg_iov */
|
|
<BR> void *msg_control; /* Ancillary data, see below */
|
|
<BR> size_t msg_controllen; /* Ancillary data buffer len */
|
|
<BR> int msg_flags; /* Flags (unused) */
|
|
};
|
|
|
|
|
|
<P>
|
|
|
|
The
|
|
<I>msg_name</I>
|
|
|
|
field is used on an unconnected socket to specify the target
|
|
address for a datagram.
|
|
It points to a buffer containing the address; the
|
|
<I>msg_namelen</I>
|
|
|
|
field should be set to the size of the address.
|
|
For a connected socket, these fields should be specified as NULL and 0,
|
|
respectively.
|
|
<P>
|
|
|
|
The
|
|
<I>msg_iov</I>
|
|
|
|
and
|
|
<I>msg_iovlen</I>
|
|
|
|
fields specify scatter-gather locations, as for
|
|
<B><A HREF="/cgi-bin/man/man2html?2+writev">writev</A></B>(2).
|
|
|
|
<P>
|
|
|
|
You may send control information using the
|
|
<I>msg_control</I>
|
|
|
|
and
|
|
<I>msg_controllen</I>
|
|
|
|
members.
|
|
The maximum control buffer length the kernel can process is limited
|
|
per socket by the value in
|
|
<I>/proc/sys/net/core/optmem_max</I>;
|
|
|
|
see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+socket">socket</A></B>(7).
|
|
|
|
<P>
|
|
|
|
The
|
|
<I>msg_flags</I>
|
|
|
|
field is ignored.
|
|
|
|
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
On success, these calls return the number of bytes sent.
|
|
On error, -1 is returned, and
|
|
<I>errno</I>
|
|
|
|
is set appropriately.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
These are some standard errors generated by the socket layer.
|
|
Additional errors
|
|
may be generated and returned from the underlying protocol modules;
|
|
see their respective manual pages.
|
|
<DL COMPACT>
|
|
<DT id="9"><B>EACCES</B>
|
|
|
|
<DD>
|
|
(For UNIX domain sockets, which are identified by pathname)
|
|
Write permission is denied on the destination socket file,
|
|
or search permission is denied for one of the directories
|
|
the path prefix.
|
|
(See
|
|
<B><A HREF="/cgi-bin/man/man2html?7+path_resolution">path_resolution</A></B>(7).)
|
|
|
|
<DT id="10"><DD>
|
|
(For UDP sockets) An attempt was made to send to a
|
|
network/broadcast address as though it was a unicast address.
|
|
<DT id="11"><B>EAGAIN</B> or <B>EWOULDBLOCK</B>
|
|
|
|
<DD>
|
|
|
|
The socket is marked nonblocking and the requested operation
|
|
would block.
|
|
POSIX.1-2001 allows either error to be returned for this case,
|
|
and does not require these constants to have the same value,
|
|
so a portable application should check for both possibilities.
|
|
<DT id="12"><B>EAGAIN</B>
|
|
|
|
<DD>
|
|
(Internet domain datagram sockets)
|
|
The socket referred to by
|
|
<I>sockfd</I>
|
|
|
|
had not previously been bound to an address and,
|
|
upon attempting to bind it to an ephemeral port,
|
|
it was determined that all port numbers in the ephemeral port range
|
|
are currently in use.
|
|
See the discussion of
|
|
<I>/proc/sys/net/ipv4/ip_local_port_range</I>
|
|
|
|
in
|
|
<B><A HREF="/cgi-bin/man/man2html?7+ip">ip</A></B>(7).
|
|
|
|
<DT id="13"><B>EALREADY</B>
|
|
|
|
<DD>
|
|
Another Fast Open is in progress.
|
|
<DT id="14"><B>EBADF</B>
|
|
|
|
<DD>
|
|
<I>sockfd</I>
|
|
|
|
is not a valid open file descriptor.
|
|
<DT id="15"><B>ECONNRESET</B>
|
|
|
|
<DD>
|
|
Connection reset by peer.
|
|
<DT id="16"><B>EDESTADDRREQ</B>
|
|
|
|
<DD>
|
|
The socket is not connection-mode, and no peer address is set.
|
|
<DT id="17"><B>EFAULT</B>
|
|
|
|
<DD>
|
|
An invalid user space address was specified for an argument.
|
|
<DT id="18"><B>EINTR</B>
|
|
|
|
<DD>
|
|
A signal occurred before any data was transmitted; see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+signal">signal</A></B>(7).
|
|
|
|
<DT id="19"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
Invalid argument passed.
|
|
<DT id="20"><B>EISCONN</B>
|
|
|
|
<DD>
|
|
The connection-mode socket was connected already but a
|
|
recipient was specified.
|
|
(Now either this error is returned, or the recipient specification
|
|
is ignored.)
|
|
<DT id="21"><B>EMSGSIZE</B>
|
|
|
|
<DD>
|
|
The socket type
|
|
|
|
requires that message be sent atomically, and the size
|
|
of the message to be sent made this impossible.
|
|
<DT id="22"><B>ENOBUFS</B>
|
|
|
|
<DD>
|
|
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.
|
|
(Normally, this does not occur in Linux.
|
|
Packets are just silently dropped
|
|
when a device queue overflows.)
|
|
<DT id="23"><B>ENOMEM</B>
|
|
|
|
<DD>
|
|
No memory available.
|
|
<DT id="24"><B>ENOTCONN</B>
|
|
|
|
<DD>
|
|
The socket is not connected, and no target has been given.
|
|
<DT id="25"><B>ENOTSOCK</B>
|
|
|
|
<DD>
|
|
The file descriptor
|
|
<I>sockfd</I>
|
|
|
|
does not refer to a socket.
|
|
<DT id="26"><B>EOPNOTSUPP</B>
|
|
|
|
<DD>
|
|
Some bit in the
|
|
<I>flags</I>
|
|
|
|
argument is inappropriate for the socket type.
|
|
<DT id="27"><B>EPIPE</B>
|
|
|
|
<DD>
|
|
The local end has been shut down on a connection oriented socket.
|
|
In this case, the process
|
|
will also receive a
|
|
<B>SIGPIPE</B>
|
|
|
|
unless
|
|
<B>MSG_NOSIGNAL</B>
|
|
|
|
is set.
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
4.4BSD, SVr4, POSIX.1-2001.
|
|
These interfaces first appeared in 4.2BSD.
|
|
<P>
|
|
|
|
POSIX.1-2001 describes only the
|
|
<B>MSG_OOB</B>
|
|
|
|
and
|
|
<B>MSG_EOR</B>
|
|
|
|
flags.
|
|
POSIX.1-2008 adds a specification of
|
|
<B>MSG_NOSIGNAL</B>.
|
|
|
|
The
|
|
<B>MSG_CONFIRM</B>
|
|
|
|
flag is a Linux extension.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
According to POSIX.1-2001, the
|
|
<I>msg_controllen</I>
|
|
|
|
field of the
|
|
<I>msghdr</I>
|
|
|
|
structure should be typed as
|
|
<I>socklen_t</I>,
|
|
|
|
but glibc currently types it as
|
|
<I>size_t</I>.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?2+sendmmsg">sendmmsg</A></B>(2)
|
|
|
|
for information about a Linux-specific system call
|
|
that can be used to transmit multiple datagrams in a single call.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
Linux may return
|
|
<B>EPIPE</B>
|
|
|
|
instead of
|
|
<B>ENOTCONN</B>.
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H2>EXAMPLE</H2>
|
|
|
|
An example of the use of
|
|
<B>sendto</B>()
|
|
|
|
is shown in
|
|
<B><A HREF="/cgi-bin/man/man2html?3+getaddrinfo">getaddrinfo</A></B>(3).
|
|
|
|
<A NAME="lbAM"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fcntl">fcntl</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+getsockopt">getsockopt</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+recv">recv</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+select">select</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+sendfile">sendfile</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+sendmmsg">sendmmsg</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+shutdown">shutdown</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+socket">socket</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+cmsg">cmsg</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+ip">ip</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+ipv6">ipv6</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+socket">socket</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+tcp">tcp</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+udp">udp</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+unix">unix</A></B>(7)
|
|
|
|
<A NAME="lbAN"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="28"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="29"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="30"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="31"><A HREF="#lbAE">The flags argument</A><DD>
|
|
<DT id="32"><A HREF="#lbAF">sendmsg()</A><DD>
|
|
</DL>
|
|
<DT id="33"><A HREF="#lbAG">RETURN VALUE</A><DD>
|
|
<DT id="34"><A HREF="#lbAH">ERRORS</A><DD>
|
|
<DT id="35"><A HREF="#lbAI">CONFORMING TO</A><DD>
|
|
<DT id="36"><A HREF="#lbAJ">NOTES</A><DD>
|
|
<DT id="37"><A HREF="#lbAK">BUGS</A><DD>
|
|
<DT id="38"><A HREF="#lbAL">EXAMPLE</A><DD>
|
|
<DT id="39"><A HREF="#lbAM">SEE ALSO</A><DD>
|
|
<DT id="40"><A HREF="#lbAN">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:34 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|