1SEND(2)                    Linux Programmer's Manual                   SEND(2)
2
3
4

NAME

6       send, sendto, sendmsg - send a message on a socket
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/socket.h>
11
12       ssize_t send(int sockfd, const void *buf, size_t len, int flags);
13
14       ssize_t sendto(int sockfd, const void *buf, size_t len, int flags,
15                      const struct sockaddr *dest_addr, socklen_t addrlen);
16
17       ssize_t sendmsg(int sockfd, const struct msghdr *msg, int flags);
18

DESCRIPTION

20       The system calls send(), sendto(), and sendmsg() are used to transmit a
21       message to another socket.
22
23       The send() call may be used only when the  socket  is  in  a  connected
24       state  (so  that the intended recipient is known).  The only difference
25       between send() and write(2) is the presence of flags.  With zero  flags
26       argument, send() is equivalent to write(2).  Also, the following call
27
28           send(sockfd, buf, len, flags);
29
30       is equivalent to
31
32           sendto(sockfd, buf, len, flags, NULL, 0);
33
34       The argument sockfd is the file descriptor of the sending socket.
35
36       If  sendto() is used on a connection-mode (SOCK_STREAM, SOCK_SEQPACKET)
37       socket, the arguments dest_addr and addrlen are ignored (and the  error
38       EISCONN  may  be  returned when they are not NULL and 0), and the error
39       ENOTCONN is returned when the socket was not actually connected.   Oth‐
40       erwise,  the  address  of the target is given by dest_addr with addrlen
41       specifying its size.  For sendmsg(), the address of the target is given
42       by msg.msg_name, with msg.msg_namelen specifying its size.
43
44       For  send()  and  sendto(),  the message is found in buf and has length
45       len.  For sendmsg(), the message is pointed to by the elements  of  the
46       array  msg.msg_iov.   The  sendmsg() call also allows sending ancillary
47       data (also known as control information).
48
49       If the message is too long to pass atomically  through  the  underlying
50       protocol, the error EMSGSIZE is returned, and the message is not trans‐
51       mitted.
52
53       No indication of failure to deliver is implicit in a  send().   Locally
54       detected errors are indicated by a return value of -1.
55
56       When  the  message  does  not  fit  into the send buffer of the socket,
57       send() normally blocks, unless the socket has been placed in  nonblock‐
58       ing  I/O mode.  In nonblocking mode it would fail with the error EAGAIN
59       or EWOULDBLOCK in this case.  The select(2) call may be used to  deter‐
60       mine when it is possible to send more data.
61
62       The  flags  argument is the bitwise OR of zero or more of the following
63       flags.
64
65       MSG_CONFIRM (Since Linux 2.3.15)
66              Tell the link layer that forward progress happened:  you  got  a
67              successful reply from the other side.  If the link layer doesn't
68              get this it will regularly reprobe the  neighbor  (e.g.,  via  a
69              unicast ARP).  Only valid on SOCK_DGRAM and SOCK_RAW sockets and
70              currently only implemented for IPv4 and IPv6.   See  arp(7)  for
71              details.
72
73       MSG_DONTROUTE
74              Don't  use  a gateway to send out the packet, only send to hosts
75              on directly connected networks.  This is usually  used  only  by
76              diagnostic or routing programs.  This is only defined for proto‐
77              col families that route; packet sockets don't.
78
79       MSG_DONTWAIT (since Linux 2.2)
80              Enables nonblocking operation; if  the  operation  would  block,
81              EAGAIN  or  EWOULDBLOCK  is  returned  (this can also be enabled
82              using the O_NONBLOCK flag with the F_SETFL fcntl(2)).
83
84       MSG_EOR (since Linux 2.2)
85              Terminates a record (when this notion is supported, as for sock‐
86              ets of type SOCK_SEQPACKET).
87
88       MSG_MORE (Since Linux 2.4.4)
89              The  caller  has  more data to send.  This flag is used with TCP
90              sockets to obtain the same effect as the TCP_CORK socket  option
91              (see tcp(7)), with the difference that this flag can be set on a
92              per-call basis.
93
94              Since Linux 2.6, this flag is also supported  for  UDP  sockets,
95              and  informs the kernel to package all of the data sent in calls
96              with this flag set into a single datagram which is  only  trans‐
97              mitted when a call is performed that does not specify this flag.
98              (See also the UDP_CORK socket option described in udp(7).)
99
100       MSG_NOSIGNAL (since Linux 2.2)
101              Requests not to send SIGPIPE on errors on stream oriented  sock‐
102              ets  when  the other end breaks the connection.  The EPIPE error
103              is still returned.
104
105       MSG_OOB
106              Sends out-of-band data  on  sockets  that  support  this  notion
107              (e.g.,  of  type SOCK_STREAM); the underlying protocol must also
108              support out-of-band data.
109
110       The definition of the msghdr structure follows.  See recv(2) and  below
111       for an exact description of its fields.
112
113           struct msghdr {
114               void         *msg_name;       /* optional address */
115               socklen_t     msg_namelen;    /* size of address */
116               struct iovec *msg_iov;        /* scatter/gather array */
117               size_t        msg_iovlen;     /* # elements in msg_iov */
118               void         *msg_control;    /* ancillary data, see below */
119               socklen_t     msg_controllen; /* ancillary data buffer len */
120               int           msg_flags;      /* flags on received message */
121           };
122
123       You  may  send  control  information using the msg_control and msg_con‐
124       trollen members.  The maximum control  buffer  length  the  kernel  can
125       process  is  limited per socket by the value in /proc/sys/net/core/opt‐
126       mem_max; see socket(7).
127

RETURN VALUE

129       On success, these calls return  the  number  of  characters  sent.   On
130       error, -1 is returned, and errno is set appropriately.
131

ERRORS

133       These  are  some  standard errors generated by the socket layer.  Addi‐
134       tional errors may be generated and returned from the underlying  proto‐
135       col modules; see their respective manual pages.
136
137       EACCES (For  Unix  domain  sockets,  which  are identified by pathname)
138              Write permission is denied on the destination  socket  file,  or
139              search  permission is denied for one of the directories the path
140              prefix.  (See path_resolution(7).)
141
142       EAGAIN or EWOULDBLOCK
143              The socket is marked nonblocking  and  the  requested  operation
144              would  block.   POSIX.1-2001  allows either error to be returned
145              for this case, and does not require these constants to have  the
146              same value, so a portable application should check for both pos‐
147              sibilities.
148
149       EBADF  An invalid descriptor was specified.
150
151       ECONNRESET
152              Connection reset by peer.
153
154       EDESTADDRREQ
155              The socket is not connection-mode, and no peer address is set.
156
157       EFAULT An invalid user space address was specified for an argument.
158
159       EINTR  A signal occurred before any  data  was  transmitted;  see  sig‐
160              nal(7).
161
162       EINVAL Invalid argument passed.
163
164       EISCONN
165              The connection-mode socket was connected already but a recipient
166              was specified.  (Now either  this  error  is  returned,  or  the
167              recipient specification is ignored.)
168
169       EMSGSIZE
170              The  socket  type  requires that message be sent atomically, and
171              the size of the message to be sent made this impossible.
172
173       ENOBUFS
174              The output queue for a network interface was full.  This  gener‐
175              ally  indicates  that the interface has stopped sending, but may
176              be caused by transient congestion.   (Normally,  this  does  not
177              occur in Linux.  Packets are just silently dropped when a device
178              queue overflows.)
179
180       ENOMEM No memory available.
181
182       ENOTCONN
183              The socket is not connected, and no target has been given.
184
185       ENOTSOCK
186              The argument sockfd is not a socket.
187
188       EOPNOTSUPP
189              Some bit in the flags argument is inappropriate for  the  socket
190              type.
191
192       EPIPE  The  local  end  has  been  shut  down  on a connection oriented
193              socket.  In this case the process will also  receive  a  SIGPIPE
194              unless MSG_NOSIGNAL is set.
195

CONFORMING TO

197       4.4BSD, SVr4, POSIX.1-2001.  These function calls appeared in 4.2BSD.
198
199       POSIX.1-2001  only  describes  the  MSG_OOB  and  MSG_EOR  flags.   The
200       MSG_CONFIRM flag is a Linux extension.
201

NOTES

203       The prototypes given above follow the  Single  Unix  Specification,  as
204       glibc2  also  does; the flags argument was int in 4.x BSD, but unsigned
205       int in libc4 and libc5; the len argument was int in 4.x BSD and  libc4,
206       but  size_t in libc5; the addrlen argument was int in 4.x BSD and libc4
207       and libc5.  See also accept(2).
208
209       According to POSIX.1-2001,  the  msg_controllen  field  of  the  msghdr
210       structure should be typed as socklen_t, but glibc currently (2.4) types
211       it as size_t.
212

BUGS

214       Linux may return EPIPE instead of ENOTCONN.
215

EXAMPLE

217       An example of the use of sendto() is shown in getaddrinfo(3).
218

SEE ALSO

220       fcntl(2), getsockopt(2), recv(2), select(2), sendfile(2),  shutdown(2),
221       socket(2), write(2), cmsg(3), ip(7), socket(7), tcp(7), udp(7)
222

COLOPHON

224       This  page  is  part of release 3.25 of the Linux man-pages project.  A
225       description of the project, and information about reporting  bugs,  can
226       be found at http://www.kernel.org/doc/man-pages/.
227
228
229
230Linux                             2009-02-23                           SEND(2)
Impressum