| blob | 30cf4f3b32ab99ce13ad00962c5501ee4a38b114 |
1 .\" $OpenBSD: send.2,v 1.31 2014/09/09 06:32:37 guenther Exp $
2 .\" $NetBSD: send.2,v 1.6 1996/01/15 01:17:18 thorpej Exp $
3 .\"
4 .\" Copyright (c) 1983, 1991, 1993
5 .\" The Regents of the University of California. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. Neither the name of the University nor the names of its contributors
16 .\" may be used to endorse or promote products derived from this software
17 .\" without specific prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 .\" SUCH DAMAGE.
30 .\"
31 .\" @(#)send.2 8.2 (Berkeley) 2/21/94
32 .\"
33 .Dd $Mdocdate: September 9 2014 $
34 .Dt SEND 2
35 .Os
36 .Sh NAME
37 .Nm send ,
38 .Nm sendto ,
39 .Nm sendmsg
40 .Nd send a message from a socket
41 .Sh SYNOPSIS
42 .In sys/socket.h
43 .Ft ssize_t
44 .Fn send "int s" "const void *msg" "size_t len" "int flags"
45 .Ft ssize_t
46 .Fn sendto "int s" "const void *msg" "size_t len" "int flags" "const struct sockaddr *to" "socklen_t tolen"
47 .Ft ssize_t
48 .Fn sendmsg "int s" "const struct msghdr *msg" "int flags"
49 .Sh DESCRIPTION
50 .Fn send ,
51 .Fn sendto ,
52 and
53 .Fn sendmsg
54 are used to transmit a message to another socket.
55 .Fn send
56 may be used only when the socket is in a
57 .Em connected
58 state, while
59 .Fn sendto
60 and
61 .Fn sendmsg
62 may be used at any time.
63 .Pp
64 The address of the target is given by
65 .Fa to
66 with
67 .Fa tolen
68 specifying its size.
69 The length of the message is given by
70 .Fa len .
71 If the message is too long to pass atomically through the
72 underlying protocol, the error
73 .Er EMSGSIZE
74 is returned, and
75 the message is not transmitted.
76 .Pp
77 No indication of failure to deliver is implicit in a
78 .Fn send .
79 Locally detected errors are indicated by a return value of \-1.
80 .Pp
81 If no messages space is available at the socket to hold
82 the message to be transmitted, then
83 .Fn send
84 normally blocks, unless the socket has been placed in
85 non-blocking I/O mode.
86 The
87 .Xr select 2
88 or
89 .Xr poll 2
90 system calls may be used to determine when it is possible to
91 send more data.
92 .Pp
93 The
94 .Fa flags
95 parameter may include one or more of the following:
96 .Pp
97 .Bl -tag -width "MSG_DONTROUTEXX" -offset indent -compact
98 .It Dv MSG_DONTROUTE
99 bypass routing tables, silently ignored
100 .It Dv MSG_DONTWAIT
101 don't block
102 .It Dv MSG_EOR
103 terminate the record (SOCK_SEQPACKET only)
104 .It Dv MSG_OOB
105 process out-of-band data
106 .El
107 .Pp
108 The flag
109 .Dv MSG_OOB
110 is used to send
111 .Dq out-of-band
112 data on sockets that support this notion (e.g.,
113 .Dv SOCK_STREAM ) ;
114 the underlying protocol must also support
115 .Dq out-of-band
116 data.
117 .Pp
118 See
119 .Xr recv 2
120 for a description of the
121 .Fa msghdr
122 structure.
123 .Sh RETURN VALUES
124 The call returns the number of characters sent, or \-1
125 if an error occurred.
126 .Sh ERRORS
127 .Fn send ,
128 .Fn sendto ,
129 and
130 .Fn sendmsg
131 fail if:
132 .Bl -tag -width Er
133 .It Bq Er EBADF
134 An invalid descriptor was specified.
135 .It Bq Er ENOTSOCK
136 The argument
137 .Fa s
138 is not a socket.
139 .It Bq Er EFAULT
140 An invalid user space address was specified for a parameter.
141 .It Bq Er EMSGSIZE
142 The socket requires that message be sent atomically,
143 and the size of the message to be sent made this impossible.
144 .It Bq Er EAGAIN
145 The socket is marked non-blocking or the
146 .Dv MSG_DONTWAIT
147 flag is set and the requested operation
148 would block.
149 .It Bq Er ENOBUFS
150 Insufficient resources were available in the system to perform the operation.
151 .It Bq Er EINVAL
152 The
153 .Fa flags
154 parameter is invalid.
155 .It Bq Er ECONNREFUSED
156 The destination host rejected the message (or a previous one).
157 This error can only be returned by connected sockets.
158 .It Bq Er ECONNRESET
159 The peer forcibly closed the connection. This error can only be returned by
160 connected sockets.
161 .It Bq Er EDESTADDRREQ
162 The socket is not connected, and no destination address was specified.
163 .It Bq Er EINTR
164 The operation was interrupted by a signal before any data was transmitted.
165 .It Bq Er EPIPE
166 The socket is shut down for writing or not longer connected. If the socket is
167 of type
168 .Dv SOCK_STREAM ,
169 the
170 .Dv SIGPIPE
171 signal is also sent to the calling thread.
172 .El
173 .Pp
174 In addition,
175 .Fn send
176 and
177 .Fn sendto
178 may return the following error:
179 .Bl -tag -width Er
180 .It Bq Er EINVAL
181 .Fa len
182 was larger than
183 .Dv SSIZE_MAX .
184 .El
185 .Pp
186 .Fn sendto
187 and
188 .Fn sendmsg
189 may return the following errors:
190 .Bl -tag -width Er
191 .It Bq Er EAFNOSUPPORT
192 Addresses in the specified address family cannot be used with this socket.
193 .It Bq Er EISCONN
194 The socket is already connected, and a destination address was specified.
195 .El
196 .Pp
197 .Fn sendmsg
198 may return the following errors:
199 .Bl -tag -width Er
200 .It Bq Er EINVAL
201 The sum of the
202 .Fa iov_len
203 values in the
204 .Fa msg_iov
205 array overflowed an
206 .Em ssize_t .
207 .It Bq Er EMSGSIZE
208 The
209 .Fa msg_iovlen
210 member of
211 .Fa msg
212 was less than 0 or larger than
213 .Dv IOV_MAX .
214 .It Bq Er EMFILE
215 The message contains control information utilizing
216 .Xr CMSG_DATA 3
217 to pass file descriptors, but too many file descriptors
218 are already in-flight.
219 .El
220 .Sh SEE ALSO
221 .Xr fcntl 2 ,
222 .Xr getsockopt 2 ,
223 .Xr poll 2 ,
224 .Xr recv 2 ,
225 .Xr select 2 ,
226 .Xr socket 2 ,
227 .Xr write 2 ,
228 .Xr CMSG_DATA 3
229 .Sh STANDARDS
230 The
231 .Fn send ,
232 .Fn sendto ,
233 and
234 .Fn sendmsg
235 functions conform to
236 .St -p1003.1-2008 .
237 The
238 .Dv MSG_DONTWAIT
239 flag is an extension to that specification.
240 .Sh HISTORY
241 The
242 .Fn send
243 function call appeared in
244 .Bx 4.2 .