]> git.saurik.com Git - apple/xnu.git/blame_incremental - bsd/man/man2/send.2
xnu-7195.101.1.tar.gz
[apple/xnu.git] / bsd / man / man2 / send.2
... / ...
CommitLineData
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 ,
71and
72.Fn sendmsg
73are used to transmit a message to another socket.
74.Fn send
75may be used only when the socket is in a
76.Em connected
77state, while
78.Fn sendto
79and
80.Fn sendmsg
81may be used at any time.
82.Pp
83The address of the target is given by
84.Fa dest_addr
85with
86.Fa dest_len
87specifying its size.
88The length of the message is given by
89.Fa length .
90If the message is too long to pass atomically through the
91underlying protocol, the error
92.Er EMSGSIZE
93is returned, and
94the message is not transmitted.
95.Pp
96No indication of failure to deliver is implicit in a
97.Fn send .
98Locally detected errors are indicated by a return value of -1.
99.Pp
100If no messages space is available at the socket to hold
101the message to be transmitted, then
102.Fn send
103normally blocks, unless the socket has been placed in
104non-blocking I/O mode.
105The
106.Xr select 2
107call may be used to determine when it is possible to
108send more data.
109.Pp
110The
111.Fa flags
112parameter 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
118The flag
119.Dv MSG_OOB
120is used to send
121.Dq out-of-band
122data on sockets that support this notion (e.g.
123.Dv SOCK_STREAM ) ;
124the underlying protocol must also support
125.Dq out-of-band
126data.
127.Dv MSG_DONTROUTE
128is usually used only by diagnostic or routing programs.
129.Pp
130The
131.Fn sendmsg
132system call uses a
133.Fa msghdr
134structure to minimize the number of directly supplied arguments.
135The
136.Fa msg_iov
137and
138.Fa msg_iovlen
139fields of message specify zero or more buffers
140containing the data to be sent.
141.Fa msg_iov
142points to an array of iovec structures;
143.Fa msg_iovlen
144shall be set to the dimension of this array.
145In each iovec structure, the
146.Fa iov_base
147field specifies a storage area and
148the
149.Fa iov_len
150field gives its size in bytes. Some of these sizes can be zero.
151The data from each storage area indicated by
152.Fa msg_iov
153is sent in turn.
154See
155.Xr recv 2
156for a complete description of the
157.Fa msghdr
158structure.
159.Sh RETURN VALUES
160Upon successful completion,
161the number of bytes which were sent is returned.
162Otherwise, -1 is returned and the global variable
163.Va errno
164is set to indicate the error.
165.Sh ERRORS
166The
167.Fn send ,
168.Fn sendmsg ,
169and
170.Fn sendto
171system calls will fail if:
172.Bl -tag -width Er
173.\" ===========
174.It Bq Er EACCES
175The SO_BROADCAST option is not set on the socket
176and a broadcast address is given as the destination.
177.\" ===========
178.It Bq Er EAGAIN
179The socket is marked non-blocking
180and the requested operation would block.
181.\" ===========
182.It Bq Er EBADF
183An invalid descriptor is specified.
184.\" ===========
185.It Bq Er ECONNRESET
186A connection is forcibly closed by a peer.
187.\" ===========
188.It Bq Er EFAULT
189An invalid user space address is specified for a parameter.
190.\" ===========
191.It Bq Er EHOSTUNREACH
192The destination address specifies an unreachable host.
193.\" ===========
194.It Bq Er EINTR
195A signal interrupts the system call
196before any data is transmitted.
197.\" ===========
198.It Bq Er EMSGSIZE
199The socket requires that message be sent atomically,
200and the size of the message to be sent makes this impossible.
201.Dv IOV_MAX .
202.\" ===========
203.It Bq Er ENETDOWN
204The local network interface used to reach the destination is down.
205.\" ===========
206.It Bq Er ENETUNREACH
207No route to the network is present.
208.\" ===========
209.It Bq Er ENOBUFS
210The system is unable to allocate an internal buffer.
211The operation may succeed when buffers become available.
212.\" ===========
213.It Bq Er ENOBUFS
214The output queue for a network interface is full.
215This generally indicates that the interface has stopped sending,
216but may be caused by transient congestion.
217.\" ===========
218.It Bq Er ENOTSOCK
219The argument
220.Fa socket
221is not a socket.
222.\" ===========
223.It Bq Er EOPNOTSUPP
224.Fa socket
225does not support (some of) the option(s) specified in
226.Fa flags .
227.\" ===========
228.It Bq Er EPIPE
229The socket is shut down for writing
230or the socket is connection-mode and is no longer connected.
231In the latter case, and if the socket is of type SOCK_STREAM,
232the SIGPIPE signal is generated to the calling thread.
233.\" ==========
234.It Bq Er EADDRNOTAVAIL
235The specified address is not available or no longer available on this machine.
236.El
237.Pp
238The
239.Fn sendmsg
240and
241.Fn sendto
242system calls will fail if:
243.Bl -tag -width Er
244.\" ===========
245.It Bq Er EAFNOSUPPORT
246Addresses in the specified address family cannot be used
247with this socket.
248.\" ===========
249.It Bq Er EDESTADDRREQ
250The socket is not connection-mode and does not have its peer address set,
251and no destination address is specified.
252.\" ===========
253.It Bq Er EISCONN
254A destination address was specified and the socket is already connected.
255.\" ===========
256.It Bq Er ENOENT
257A component of the pathname does not name an existing file
258or the path name is an empty string.
259.\" ===========
260.It Bq Er ENOMEM
261Insufficient memory is available to fulfill the request.
262.\" ===========
263.It Bq Er ENOTCONN
264The socket is connection-mode, but is not connected.
265.\" ===========
266.It Bq Er ENOTDIR
267A component of the path prefix of the pathname in the socket address
268is not a directory.
269.El
270.Pp
271The
272.Fn send
273system call will fail if:
274.Bl -tag -width Er
275.\" ===========
276.It Bq Er EDESTADDRREQ
277The socket is not connection-mode and no peer address is set.
278.\" ===========
279.It Bq Er ENOTCONN
280The socket is not connected or otherwise has not had the peer pre-specified.
281.El
282.Pp
283The
284.Fn sendmsg
285system call will fail if:
286.Bl -tag -width Er
287.\" ===========
288.It Bq Er EINVAL
289The sum of the iov_len values overflows an ssize_t.
290.\" ===========
291.It Bq Er EMSGSIZE
292The socket requires that message be sent atomically,
293and the size of the message to be sent makes this impossible,
294or the msg_iovlen member of the msghdr structure pointed to by message
295is 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
302The 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
313The
314.Fn send
315function call appeared in
316.Bx 4.2 .