]>
Commit | Line | Data |
---|---|---|
1 | .\" $NetBSD: send.2,v 1.6 1996/01/15 01:17:18 thorpej Exp $ | |
2 | .\" | |
3 | .\" Copyright (c) 1983, 1991, 1993 | |
4 | .\" The Regents of the University of California. All rights reserved. | |
5 | .\" | |
6 | .\" Redistribution and use in source and binary forms, with or without | |
7 | .\" modification, are permitted provided that the following conditions | |
8 | .\" are met: | |
9 | .\" 1. Redistributions of source code must retain the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer. | |
11 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
12 | .\" notice, this list of conditions and the following disclaimer in the | |
13 | .\" documentation and/or other materials provided with the distribution. | |
14 | .\" 3. All advertising materials mentioning features or use of this software | |
15 | .\" must display the following acknowledgement: | |
16 | .\" This product includes software developed by the University of | |
17 | .\" California, Berkeley and its contributors. | |
18 | .\" 4. Neither the name of the University nor the names of its contributors | |
19 | .\" may be used to endorse or promote products derived from this software | |
20 | .\" without specific prior written permission. | |
21 | .\" | |
22 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
23 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
24 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
25 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
26 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
27 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
28 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
29 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
30 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
31 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
32 | .\" SUCH DAMAGE. | |
33 | .\" | |
34 | .\" @(#)send.2 8.2 (Berkeley) 2/21/94 | |
35 | .\" | |
36 | .Dd February 21, 1994 | |
37 | .Dt SEND 2 | |
38 | .Os BSD 4.2 | |
39 | .Sh NAME | |
40 | .Nm send , | |
41 | .Nm sendmsg , | |
42 | .Nm sendto | |
43 | .Nd send a message from a socket | |
44 | .Sh SYNOPSIS | |
45 | .Fd #include <sys/socket.h> | |
46 | .Ft ssize_t | |
47 | .Fo send | |
48 | .Fa "int socket" | |
49 | .Fa "const void *buffer" | |
50 | .Fa "size_t length" | |
51 | .Fa "int flags" | |
52 | .Fc | |
53 | .Ft ssize_t | |
54 | .Fo sendmsg | |
55 | .Fa "int socket" | |
56 | .Fa "const struct msghdr *message" | |
57 | .Fa "int flags" | |
58 | .Fc | |
59 | .Ft ssize_t | |
60 | .Fo sendto | |
61 | .Fa "int socket" | |
62 | .Fa "const void *buffer" | |
63 | .Fa "size_t length" | |
64 | .Fa "int flags" | |
65 | .Fa "const struct sockaddr *dest_addr" | |
66 | .Fa "socklen_t dest_len" | |
67 | .Fc | |
68 | .Sh DESCRIPTION | |
69 | .Fn send , | |
70 | .Fn sendto , | |
71 | and | |
72 | .Fn sendmsg | |
73 | are used to transmit a message to another socket. | |
74 | .Fn send | |
75 | may be used only when the socket is in a | |
76 | .Em connected | |
77 | state, while | |
78 | .Fn sendto | |
79 | and | |
80 | .Fn sendmsg | |
81 | may be used at any time. | |
82 | .Pp | |
83 | The address of the target is given by | |
84 | .Fa dest_addr | |
85 | with | |
86 | .Fa dest_len | |
87 | specifying its size. | |
88 | The length of the message is given by | |
89 | .Fa length . | |
90 | If the message is too long to pass atomically through the | |
91 | underlying protocol, the error | |
92 | .Er EMSGSIZE | |
93 | is returned, and | |
94 | the message is not transmitted. | |
95 | .Pp | |
96 | No indication of failure to deliver is implicit in a | |
97 | .Fn send . | |
98 | Locally detected errors are indicated by a return value of -1. | |
99 | .Pp | |
100 | If no messages space is available at the socket to hold | |
101 | the message to be transmitted, then | |
102 | .Fn send | |
103 | normally blocks, unless the socket has been placed in | |
104 | non-blocking I/O mode. | |
105 | The | |
106 | .Xr select 2 | |
107 | call may be used to determine when it is possible to | |
108 | send more data. | |
109 | .Pp | |
110 | The | |
111 | .Fa flags | |
112 | parameter may include one or more of the following: | |
113 | .Bd -literal | |
114 | #define MSG_OOB 0x1 /* process out-of-band data */ | |
115 | #define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */ | |
116 | .Ed | |
117 | .Pp | |
118 | The flag | |
119 | .Dv MSG_OOB | |
120 | is used to send | |
121 | .Dq out-of-band | |
122 | data on sockets that support this notion (e.g. | |
123 | .Dv SOCK_STREAM ) ; | |
124 | the underlying protocol must also support | |
125 | .Dq out-of-band | |
126 | data. | |
127 | .Dv MSG_DONTROUTE | |
128 | is usually used only by diagnostic or routing programs. | |
129 | .Pp | |
130 | The | |
131 | .Fn sendmsg | |
132 | system call uses a | |
133 | .Fa msghdr | |
134 | structure to minimize the number of directly supplied arguments. | |
135 | The | |
136 | .Fa msg_iov | |
137 | and | |
138 | .Fa msg_iovlen | |
139 | fields of message specify zero or more buffers | |
140 | containing the data to be sent. | |
141 | .Fa msg_iov | |
142 | points to an array of iovec structures; | |
143 | .Fa msg_iovlen | |
144 | shall be set to the dimension of this array. | |
145 | In each iovec structure, the | |
146 | .Fa iov_base | |
147 | field specifies a storage area and | |
148 | the | |
149 | .Fa iov_len | |
150 | field gives its size in bytes. Some of these sizes can be zero. | |
151 | The data from each storage area indicated by | |
152 | .Fa msg_iov | |
153 | is sent in turn. | |
154 | See | |
155 | .Xr recv 2 | |
156 | for a complete description of the | |
157 | .Fa msghdr | |
158 | structure. | |
159 | .Sh RETURN VALUES | |
160 | Upon successful completion, | |
161 | the number of bytes which were sent is returned. | |
162 | Otherwise, -1 is returned and the global variable | |
163 | .Va errno | |
164 | is set to indicate the error. | |
165 | .Sh ERRORS | |
166 | The | |
167 | .Fn send , | |
168 | .Fn sendmsg , | |
169 | and | |
170 | .Fn sendto | |
171 | system calls will fail if: | |
172 | .Bl -tag -width Er | |
173 | .\" =========== | |
174 | .It Bq Er EACCES | |
175 | The SO_BROADCAST option is not set on the socket | |
176 | and a broadcast address is given as the destination. | |
177 | .\" =========== | |
178 | .It Bq Er EAGAIN | |
179 | The socket is marked non-blocking | |
180 | and the requested operation would block. | |
181 | .\" =========== | |
182 | .It Bq Er EBADF | |
183 | An invalid descriptor is specified. | |
184 | .\" =========== | |
185 | .It Bq Er ECONNRESET | |
186 | A connection is forcibly closed by a peer. | |
187 | .\" =========== | |
188 | .It Bq Er EFAULT | |
189 | An invalid user space address is specified for a parameter. | |
190 | .\" =========== | |
191 | .It Bq Er EHOSTUNREACH | |
192 | The destination address specifies an unreachable host. | |
193 | .\" =========== | |
194 | .It Bq Er EINTR | |
195 | A signal interrupts the system call | |
196 | before any data is transmitted. | |
197 | .\" =========== | |
198 | .It Bq Er EMSGSIZE | |
199 | The socket requires that message be sent atomically, | |
200 | and the size of the message to be sent makes this impossible. | |
201 | .Dv IOV_MAX . | |
202 | .\" =========== | |
203 | .It Bq Er ENETDOWN | |
204 | The local network interface used to reach the destination is down. | |
205 | .\" =========== | |
206 | .It Bq Er ENETUNREACH | |
207 | No route to the network is present. | |
208 | .\" =========== | |
209 | .It Bq Er ENOBUFS | |
210 | The system is unable to allocate an internal buffer. | |
211 | The operation may succeed when buffers become available. | |
212 | .\" =========== | |
213 | .It Bq Er ENOBUFS | |
214 | The output queue for a network interface is full. | |
215 | This generally indicates that the interface has stopped sending, | |
216 | but may be caused by transient congestion. | |
217 | .\" =========== | |
218 | .It Bq Er ENOTSOCK | |
219 | The argument | |
220 | .Fa socket | |
221 | is not a socket. | |
222 | .\" =========== | |
223 | .It Bq Er EOPNOTSUPP | |
224 | .Fa socket | |
225 | does not support (some of) the option(s) specified in | |
226 | .Fa flags . | |
227 | .\" =========== | |
228 | .It Bq Er EPIPE | |
229 | The socket is shut down for writing | |
230 | or the socket is connection-mode and is no longer connected. | |
231 | In the latter case, and if the socket is of type SOCK_STREAM, | |
232 | the SIGPIPE signal is generated to the calling thread. | |
233 | .\" ========== | |
234 | .It Bq Er EADDRNOTAVAIL | |
235 | The specified address is not available or no longer available on this machine. | |
236 | .El | |
237 | .Pp | |
238 | The | |
239 | .Fn sendmsg | |
240 | and | |
241 | .Fn sendto | |
242 | system calls will fail if: | |
243 | .Bl -tag -width Er | |
244 | .\" =========== | |
245 | .It Bq Er EAFNOSUPPORT | |
246 | Addresses in the specified address family cannot be used | |
247 | with this socket. | |
248 | .\" =========== | |
249 | .It Bq Er EDESTADDRREQ | |
250 | The socket is not connection-mode and does not have its peer address set, | |
251 | and no destination address is specified. | |
252 | .\" =========== | |
253 | .It Bq Er EISCONN | |
254 | A destination address was specified and the socket is already connected. | |
255 | .\" =========== | |
256 | .It Bq Er ENOENT | |
257 | A component of the pathname does not name an existing file | |
258 | or the path name is an empty string. | |
259 | .\" =========== | |
260 | .It Bq Er ENOMEM | |
261 | Insufficient memory is available to fulfill the request. | |
262 | .\" =========== | |
263 | .It Bq Er ENOTCONN | |
264 | The socket is connection-mode, but is not connected. | |
265 | .\" =========== | |
266 | .It Bq Er ENOTDIR | |
267 | A component of the path prefix of the pathname in the socket address | |
268 | is not a directory. | |
269 | .El | |
270 | .Pp | |
271 | The | |
272 | .Fn send | |
273 | system call will fail if: | |
274 | .Bl -tag -width Er | |
275 | .\" =========== | |
276 | .It Bq Er EDESTADDRREQ | |
277 | The socket is not connection-mode and no peer address is set. | |
278 | .\" =========== | |
279 | .It Bq Er ENOTCONN | |
280 | The socket is not connected or otherwise has not had the peer pre-specified. | |
281 | .El | |
282 | .Pp | |
283 | The | |
284 | .Fn sendmsg | |
285 | system call will fail if: | |
286 | .Bl -tag -width Er | |
287 | .\" =========== | |
288 | .It Bq Er EINVAL | |
289 | The sum of the iov_len values overflows an ssize_t. | |
290 | .\" =========== | |
291 | .It Bq Er EMSGSIZE | |
292 | The socket requires that message be sent atomically, | |
293 | and the size of the message to be sent makes this impossible, | |
294 | or the msg_iovlen member of the msghdr structure pointed to by message | |
295 | is less than or equal to 0 or is greater than | |
296 | .Dv IOV_MAX . | |
297 | .El | |
298 | .Sh LEGACY SYNOPSIS | |
299 | .Fd #include <sys/types.h> | |
300 | .Fd #include <sys/socket.h> | |
301 | .Pp | |
302 | The include file | |
303 | .In sys/types.h is necessary. | |
304 | .Sh SEE ALSO | |
305 | .Xr fcntl 2 , | |
306 | .Xr getsockopt 2 , | |
307 | .Xr recv 2 , | |
308 | .Xr select 2 , | |
309 | .Xr socket 2 , | |
310 | .Xr write 2 , | |
311 | .Xr compat 5 | |
312 | .Sh HISTORY | |
313 | The | |
314 | .Fn send | |
315 | function call appeared in | |
316 | .Bx 4.2 . |