1SEND(2) Linux Programmer's Manual SEND(2)
2
6 send, sendto, sendmsg - send a message on a socket
7
9 #include <sys/types.h>
10 #include <sys/socket.h>
11 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
18 The system calls send(), sendto(), and sendmsg() are used to transmit a
19 message to another socket.
20 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 The parameter s is the file descriptor of the sending socket.
28 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 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 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 No indication of failure to deliver is implicit in a send(). Locally
47 detected errors are indicated by a return value of -1.
48 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 The flags parameter is the bitwise OR of zero or more of the following
56 flags.
57 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 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 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 MSG_EOR
78 Terminates a record (when this notion is supported, as for sock‐
79 ets of type SOCK_SEQPACKET).
80 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 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 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 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 The definition of the msghdr structure follows. See recv(2) and below
104 for an exact description of its fields.
105 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 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
122 On success, these calls return the number of characters sent. On
123 error, -1 is returned, and errno is set appropriately.
124
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 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 EAGAIN or EWOULDBLOCK
136 The socket is marked non-blocking and the requested operation
137 would block.
138 EBADF An invalid descriptor was specified.
140 ECONNRESET
142 Connection reset by peer.
143 EDESTADDRREQ
145 The socket is not connection-mode, and no peer address is set.
146 EFAULT An invalid user space address was specified for a parameter.
148 EINTR A signal occurred before any data was transmitted.
150 EINVAL Invalid argument passed.
152 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 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 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 ENOMEM No memory available.
170 ENOTCONN
172 The socket is not connected, and no target has been given.
173 ENOTSOCK
175 The argument s is not a socket.
176 EOPNOTSUPP
178 Some bit in the flags argument is inappropriate for the socket
179 type.
180 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
186 4.4BSD, SVr4, POSIX.1-2001. These function calls appeared in 4.2BSD.
187 POSIX.1-2001 only describes the MSG_OOB and MSG_EOR flags. The
189 MSG_CONFIRM flag is a Linux extension.
190
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 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
203 Linux may return EPIPE instead of ENOTCONN.
204
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)
208Linux 2.6.7 2004-07-01 SEND(2)