2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 1983, 1991 The Regents of the University of California.
|
|
|
|
.\" All rights reserved.
|
|
|
|
.\"
|
|
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
|
|
.\" modification, are permitted provided that the following conditions
|
|
|
|
.\" are met:
|
|
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
|
|
.\" must display the following acknowledgement:
|
|
|
|
.\" This product includes software developed by the University of
|
|
|
|
.\" California, Berkeley and its contributors.
|
|
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
|
|
.\" may be used to endorse or promote products derived from this software
|
|
|
|
.\" without specific prior written permission.
|
|
|
|
.\"
|
|
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
|
|
.\" SUCH DAMAGE.
|
|
|
|
.\"
|
|
|
|
.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
|
|
|
|
.\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
|
|
|
|
.\" Modified Oct 1998 by Andi Kleen
|
|
|
|
.\" Modified Oct 2003 by aeb
|
|
|
|
.\" Modified 2004-07-01 by mtk
|
|
|
|
.\"
|
|
|
|
.TH SEND 2 2004-07-01 "Linux 2.6.7" "Linux Programmer's Manual"
|
|
|
|
.SH NAME
|
2004-12-20 10:53:41 +00:00
|
|
|
send, sendto, sendmsg \- send a message on a socket
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH SYNOPSIS
|
|
|
|
.B #include <sys/types.h>
|
|
|
|
.br
|
|
|
|
.B #include <sys/socket.h>
|
|
|
|
.sp
|
|
|
|
.BI "ssize_t send(int " s ", const void *" buf ", size_t " len ,
|
|
|
|
.BI "int " flags );
|
|
|
|
.br
|
|
|
|
.BI "ssize_t sendto(int " s ", const void *" buf ", size_t " len ,
|
|
|
|
.BI "int " flags ", const struct sockaddr *" to ", socklen_t " tolen );
|
|
|
|
.br
|
|
|
|
.BI "ssize_t sendmsg(int " s ", const struct msghdr *" msg ,
|
|
|
|
.BI "int " flags );
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The system calls
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR send (),
|
|
|
|
.BR sendto (),
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR sendmsg ()
|
2004-11-03 13:51:07 +00:00
|
|
|
are used to transmit a message to another socket.
|
|
|
|
.PP
|
|
|
|
The
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR send ()
|
2004-11-03 13:51:07 +00:00
|
|
|
call may be used only when the socket is in a
|
|
|
|
.I connected
|
|
|
|
state (so that the intended recipient is known).
|
|
|
|
The only difference between
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR send ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR write ()
|
2004-11-03 13:51:07 +00:00
|
|
|
is the presence of
|
|
|
|
.IR flags .
|
|
|
|
With zero
|
|
|
|
.I flags
|
|
|
|
parameter,
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR send ()
|
2004-11-03 13:51:07 +00:00
|
|
|
is equivalent to
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR write ().
|
2004-11-03 13:51:07 +00:00
|
|
|
Also,
|
2006-06-05 04:51:40 +00:00
|
|
|
.RI send( s , buf , len , flags )
|
2004-11-03 13:51:07 +00:00
|
|
|
is equivalent to
|
2006-06-05 04:51:40 +00:00
|
|
|
.RI sendto( s , buf , len , flags ,NULL,0).
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
The parameter
|
|
|
|
.I s
|
|
|
|
is the file descriptor of the sending socket.
|
|
|
|
.PP
|
|
|
|
If
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR sendto ()
|
2004-11-03 13:51:07 +00:00
|
|
|
is used on a connection-mode (SOCK_STREAM, SOCK_SEQPACKET) socket,
|
|
|
|
the parameters
|
|
|
|
.I to
|
|
|
|
and
|
|
|
|
.I tolen
|
|
|
|
are ignored (and the error EISCONN may be returned when they are
|
|
|
|
not NULL and 0), and the error ENOTCONN is returned when the socket was
|
|
|
|
not actually connected. Otherwise, the address of the target is given by
|
|
|
|
.I to
|
|
|
|
with
|
|
|
|
.I tolen
|
|
|
|
specifying its size.
|
|
|
|
For
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR sendmsg (),
|
2004-11-03 13:51:07 +00:00
|
|
|
the address of the target is given by
|
|
|
|
.IR msg.msg_name ,
|
|
|
|
with
|
|
|
|
.I msg.msg_namelen
|
|
|
|
specifying its size.
|
|
|
|
.PP
|
|
|
|
For
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR send ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR sendto (),
|
2004-11-03 13:51:07 +00:00
|
|
|
the message is found in
|
|
|
|
.I buf
|
|
|
|
and has length
|
|
|
|
.IR len .
|
|
|
|
For
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR sendmsg (),
|
2004-11-03 13:51:07 +00:00
|
|
|
the message is pointed to by the elements of the array
|
|
|
|
.IR msg.msg_iov .
|
|
|
|
The
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR sendmsg ()
|
2004-11-03 13:51:07 +00:00
|
|
|
call also allows sending ancillary data (also known as control information).
|
|
|
|
.PP
|
|
|
|
If the message is too long to pass atomically through the
|
|
|
|
underlying protocol, the error
|
|
|
|
.B EMSGSIZE
|
|
|
|
is returned, and the message is not transmitted.
|
|
|
|
.PP
|
|
|
|
No indication of failure to deliver is implicit in a
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR send ().
|
2004-11-03 13:51:07 +00:00
|
|
|
Locally detected errors are indicated by a return value of \-1.
|
|
|
|
.PP
|
|
|
|
When the message does not fit into the send buffer of the socket,
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR send ()
|
2004-11-03 13:51:07 +00:00
|
|
|
normally blocks, unless the socket has been placed in non-blocking I/O
|
|
|
|
mode. In non-blocking mode it would return
|
|
|
|
.B EAGAIN
|
|
|
|
in this case.
|
|
|
|
The
|
|
|
|
.BR select (2)
|
|
|
|
call may be used to determine when it is possible to send more data.
|
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.I flags
|
|
|
|
parameter is the bitwise OR
|
|
|
|
of zero or more of the following flags.
|
2006-02-08 09:44:13 +00:00
|
|
|
.\" FIXME? document MSG_PROXY (which went away in 2.3.15)
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2005-12-14 16:41:14 +00:00
|
|
|
.BR MSG_CONFIRM " (Linux 2.3+ only)"
|
|
|
|
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
|
2006-06-03 01:26:30 +00:00
|
|
|
it will regularly reprobe the neighbour (e.g. via a unicast ARP).
|
2005-12-14 16:41:14 +00:00
|
|
|
Only valid on
|
|
|
|
.B SOCK_DGRAM
|
|
|
|
and
|
|
|
|
.B SOCK_RAW
|
|
|
|
sockets and currently only implemented for IPv4 and IPv6. See
|
|
|
|
.BR arp (7)
|
|
|
|
for details.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B MSG_DONTROUTE
|
|
|
|
Don't use a gateway to send out the packet, only send to hosts on
|
|
|
|
directly connected networks. This is usually used only
|
|
|
|
by diagnostic or routing programs. This is only defined for protocol
|
|
|
|
families that route; packet sockets don't.
|
|
|
|
.TP
|
|
|
|
.B MSG_DONTWAIT
|
|
|
|
Enables non-blocking operation; if the operation would block,
|
|
|
|
.B EAGAIN
|
|
|
|
is returned (this can also be enabled using the
|
|
|
|
.B O_NONBLOCK
|
|
|
|
with the
|
|
|
|
.B F_SETFL
|
|
|
|
.BR fcntl (2)).
|
|
|
|
.TP
|
2005-12-14 16:41:14 +00:00
|
|
|
.B MSG_EOR
|
|
|
|
Terminates a record (when this notion is supported, as for sockets of type
|
|
|
|
.BR SOCK_SEQPACKET ).
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.BR MSG_MORE " (Since Linux 2.4.4)"
|
|
|
|
The caller has more data to send.
|
|
|
|
This flag is used with TCP sockets to obtain the same effect
|
|
|
|
as the TCP_CORK socket option (see
|
|
|
|
.BR tcp (7)),
|
|
|
|
with the difference that this flag can be set on a per-call basis.
|
2005-12-14 16:30:49 +00:00
|
|
|
.sp
|
2004-11-03 13:51:07 +00:00
|
|
|
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 only transmitted when a call is performed
|
2005-12-14 16:30:49 +00:00
|
|
|
that does not specify this flag.
|
|
|
|
(See also the
|
|
|
|
.B UDP_CORK
|
|
|
|
socket option described in
|
|
|
|
.BR udp (7).)
|
2005-12-14 16:41:14 +00:00
|
|
|
.TP
|
|
|
|
.B MSG_NOSIGNAL
|
|
|
|
Requests not to send
|
|
|
|
.B SIGPIPE
|
|
|
|
on errors on stream oriented sockets when the other end breaks the
|
|
|
|
connection. The
|
|
|
|
.B EPIPE
|
|
|
|
error is still returned.
|
|
|
|
.TP
|
|
|
|
.B MSG_OOB
|
|
|
|
Sends
|
|
|
|
.I out-of-band
|
|
|
|
data on sockets that support this notion (e.g. of type
|
|
|
|
.BR SOCK_STREAM );
|
|
|
|
the underlying protocol must also support
|
|
|
|
.I out-of-band
|
|
|
|
data.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
The definition of the
|
|
|
|
.I msghdr
|
|
|
|
structure follows. See
|
|
|
|
.BR recv (2)
|
|
|
|
and below for an exact description of its fields.
|
2006-03-12 19:09:15 +00:00
|
|
|
.in +0.25i
|
2004-11-03 13:51:07 +00:00
|
|
|
.nf
|
2006-03-12 19:09:15 +00:00
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
struct msghdr {
|
2006-03-12 19:09:15 +00:00
|
|
|
void *msg_name; /* optional address */
|
|
|
|
socklen_t msg_namelen; /* size of address */
|
|
|
|
struct iovec *msg_iov; /* scatter/gather array */
|
|
|
|
size_t msg_iovlen; /* # elements in msg_iov */
|
|
|
|
void *msg_control; /* ancillary data, see below */
|
|
|
|
socklen_t msg_controllen; /* ancillary data buffer len */
|
|
|
|
int msg_flags; /* flags on received message */
|
2004-11-03 13:51:07 +00:00
|
|
|
};
|
|
|
|
.fi
|
2006-03-12 19:09:15 +00:00
|
|
|
.in -0.25i
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
You may send control information using the
|
|
|
|
.I msg_control
|
|
|
|
and
|
|
|
|
.I msg_controllen
|
|
|
|
members. The maximum control buffer length the kernel can process is limited
|
|
|
|
per socket by the
|
|
|
|
.B net.core.optmem_max
|
|
|
|
sysctl; see
|
|
|
|
.BR socket (7).
|
|
|
|
.\" Still to be documented:
|
|
|
|
.\" Send file descriptors and user credentials using the
|
|
|
|
.\" msg_control* fields.
|
|
|
|
.\" The flags returned in msg_flags.
|
|
|
|
.SH "RETURN VALUE"
|
2004-12-20 12:24:06 +00:00
|
|
|
On success, these calls return the number of characters sent.
|
|
|
|
On error, \-1 is returned, and
|
|
|
|
.I errno
|
|
|
|
is set appropriately.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH ERRORS
|
|
|
|
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.
|
|
|
|
.TP
|
|
|
|
.B EACCES
|
|
|
|
(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
|
|
|
|
.BR path_resolution (2).)
|
|
|
|
.TP
|
|
|
|
.BR EAGAIN " or " EWOULDBLOCK
|
|
|
|
The socket is marked non-blocking and the requested operation
|
|
|
|
would block.
|
|
|
|
.TP
|
|
|
|
.B EBADF
|
|
|
|
An invalid descriptor was specified.
|
|
|
|
.TP
|
|
|
|
.B ECONNRESET
|
|
|
|
Connection reset by peer.
|
|
|
|
.TP
|
|
|
|
.B EDESTADDRREQ
|
|
|
|
The socket is not connection-mode, and no peer address is set.
|
|
|
|
.TP
|
|
|
|
.B EFAULT
|
|
|
|
An invalid user space address was specified for a parameter.
|
|
|
|
.TP
|
|
|
|
.B EINTR
|
|
|
|
A signal occurred before any data was transmitted.
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
Invalid argument passed.
|
|
|
|
.TP
|
|
|
|
.B EISCONN
|
|
|
|
The connection-mode socket was connected already but a
|
|
|
|
recipient was specified.
|
|
|
|
(Now either this error is returned, or the recipient specification
|
|
|
|
is ignored.)
|
|
|
|
.TP
|
|
|
|
.B EMSGSIZE
|
|
|
|
The socket type
|
|
|
|
.\" (e.g., SOCK_DGRAM )
|
|
|
|
requires that message be sent atomically, and the size
|
|
|
|
of the message to be sent made this impossible.
|
|
|
|
.TP
|
|
|
|
.B 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.
|
|
|
|
(Normally, this does not occur in Linux. Packets are just silently dropped
|
|
|
|
when a device queue overflows.)
|
|
|
|
.TP
|
|
|
|
.B ENOMEM
|
|
|
|
No memory available.
|
|
|
|
.TP
|
|
|
|
.B ENOTCONN
|
|
|
|
The socket is not connected, and no target has been given.
|
|
|
|
.TP
|
|
|
|
.B ENOTSOCK
|
|
|
|
The argument
|
|
|
|
.I s
|
|
|
|
is not a socket.
|
|
|
|
.TP
|
|
|
|
.B EOPNOTSUPP
|
|
|
|
Some bit in the
|
|
|
|
.I flags
|
|
|
|
argument is inappropriate for the socket type.
|
|
|
|
.TP
|
|
|
|
.B EPIPE
|
|
|
|
The local end has been shut down on a connection oriented socket.
|
|
|
|
In this case the process
|
|
|
|
will also receive a
|
|
|
|
.B SIGPIPE
|
|
|
|
unless
|
|
|
|
.B MSG_NOSIGNAL
|
|
|
|
is set.
|
|
|
|
.SH "CONFORMING TO"
|
2006-08-03 13:57:17 +00:00
|
|
|
4.4BSD, SVr4, POSIX.1-2001.
|
2004-11-03 13:51:07 +00:00
|
|
|
These function calls appeared in 4.2BSD.
|
|
|
|
.LP
|
2006-08-03 13:57:17 +00:00
|
|
|
POSIX.1-2001 only describes the
|
2004-11-03 13:51:07 +00:00
|
|
|
.B MSG_OOB
|
|
|
|
and
|
|
|
|
.B MSG_EOR
|
|
|
|
flags.
|
|
|
|
The
|
|
|
|
.B MSG_CONFIRM
|
|
|
|
flag is a Linux extension.
|
2006-03-12 19:09:15 +00:00
|
|
|
.SH NOTES
|
2004-11-03 13:51:07 +00:00
|
|
|
The prototypes given above follow the Single Unix Specification,
|
|
|
|
as glibc2 also does; the
|
|
|
|
.I flags
|
2005-07-18 15:05:56 +00:00
|
|
|
argument was `int' in 4.x BSD, but `unsigned int' in libc4 and libc5;
|
2004-11-03 13:51:07 +00:00
|
|
|
the
|
|
|
|
.I len
|
2005-07-18 15:05:56 +00:00
|
|
|
argument was `int' in 4.x BSD and libc4, but `size_t' in libc5;
|
2004-11-03 13:51:07 +00:00
|
|
|
the
|
|
|
|
.I tolen
|
2005-07-18 15:05:56 +00:00
|
|
|
argument was `int' in 4.x BSD and libc4 and libc5.
|
2004-11-03 13:51:07 +00:00
|
|
|
See also
|
|
|
|
.BR accept (2).
|
2006-03-12 19:09:15 +00:00
|
|
|
|
|
|
|
According to POSIX.1-2001, the
|
|
|
|
.I msg_controllen
|
|
|
|
field of the
|
|
|
|
.I msghdr
|
|
|
|
structure should be typed as
|
|
|
|
.IR socklen_t ,
|
|
|
|
but glibc currently (2.4) types it as
|
|
|
|
.IR size_t .
|
2006-04-03 01:35:31 +00:00
|
|
|
.\" glibc bug raised 12 Mar 2006
|
2006-03-12 19:09:15 +00:00
|
|
|
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448
|
2006-04-03 01:35:31 +00:00
|
|
|
.\" The problem is an underlying kernel issue: the size of the
|
|
|
|
.\" __kernel_size_t type used to type this field varies
|
|
|
|
.\" across architectures, but socklen_t is always 32 bits.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH BUGS
|
|
|
|
Linux may return EPIPE instead of ENOTCONN.
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR fcntl (2),
|
|
|
|
.BR getsockopt (2),
|
|
|
|
.BR recv (2),
|
|
|
|
.BR select (2),
|
|
|
|
.BR sendfile (2),
|
2005-06-30 09:40:35 +00:00
|
|
|
.BR shutdown (2),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR socket (2),
|
|
|
|
.BR write (2),
|
2005-12-19 09:16:57 +00:00
|
|
|
.BR cmsg (3),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR ip (7),
|
|
|
|
.BR socket (7),
|
|
|
|
.BR tcp (7),
|
|
|
|
.BR udp (7)
|