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 s, const void *buf, size_t len, int flags);
13       ssize_t  sendto(int  s,  const  void *buf, size_t len, int flags, const
14       struct sockaddr *to, socklen_t tolen);
15       ssize_t sendmsg(int s, const struct msghdr *msg, int flags);
16

DESCRIPTION

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

RETURN VALUE

122       On success, these calls return  the  number  of  characters  sent.   On
123       error, -1 is returned, and errno is set appropriately.
124

ERRORS

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

CONFORMING TO

186       4.4BSD, SVr4, POSIX.1-2001.  These function calls appeared in 4.2BSD.
187
188       POSIX.1-2001  only  describes  the  MSG_OOB  and  MSG_EOR  flags.   The
189       MSG_CONFIRM flag is a Linux extension.
190

NOTES

192       The prototypes given above follow the  Single  Unix  Specification,  as
193       glibc2  also  does;  the  flags  argument  was  `int'  in  4.x BSD, but
194       `unsigned int' in libc4 and libc5; the len argument was  `int'  in  4.x
195       BSD  and  libc4, but `size_t' in libc5; the tolen argument was `int' in
196       4.x BSD and libc4 and libc5.  See also accept(2).
197
198       According to POSIX.1-2001,  the  msg_controllen  field  of  the  msghdr
199       structure should be typed as socklen_t, but glibc currently (2.4) types
200       it as size_t.
201

BUGS

203       Linux may return EPIPE instead of ENOTCONN.
204

SEE ALSO

206       fcntl(2), getsockopt(2), recv(2), select(2), sendfile(2),  shutdown(2),
207       socket(2), write(2), cmsg(3), ip(7), socket(7), tcp(7), udp(7)
208
209
210
211Linux 2.6.7                       2004-07-01                           SEND(2)
Impressum