xref: /openbsd/lib/libc/sys/send.2 (revision 898184e3) 
1.\"	$OpenBSD: send.2,v 1.27 2012/10/05 01:30:28 yasuoka 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: October 5 2012 $
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.Fd #include <sys/types.h>
43.Fd #include <sys/socket.h>
44.Ft ssize_t
45.Fn send "int s" "const void *msg" "size_t len" "int flags"
46.Ft ssize_t
47.Fn sendto "int s" "const void *msg" "size_t len" "int flags" "const struct sockaddr *to" "socklen_t tolen"
48.Ft ssize_t
49.Fn sendmsg "int s" "const struct msghdr *msg" "int flags"
50.Sh DESCRIPTION
51.Fn send ,
52.Fn sendto ,
53and
54.Fn sendmsg
55are used to transmit a message to another socket.
56.Fn send
57may be used only when the socket is in a
58.Em connected
59state, while
60.Fn sendto
61and
62.Fn sendmsg
63may be used at any time.
64.Pp
65The address of the target is given by
66.Fa to
67with
68.Fa tolen
69specifying its size.
70The length of the message is given by
71.Fa len .
72If the message is too long to pass atomically through the
73underlying protocol, the error
74.Er EMSGSIZE
75is returned, and
76the message is not transmitted.
77.Pp
78No indication of failure to deliver is implicit in a
79.Fn send .
80Locally detected errors are indicated by a return value of \-1.
81.Pp
82If no messages space is available at the socket to hold
83the message to be transmitted, then
84.Fn send
85normally blocks, unless the socket has been placed in
86non-blocking I/O mode.
87The
88.Xr select 2
89or
90.Xr poll 2
91system calls may be used to determine when it is possible to
92send more data.
93.Pp
94The
95.Fa flags
96parameter may include one or more of the following:
97.Pp
98.Bl -tag -width "MSG_DONTROUTEXX" -offset indent -compact
99.It Dv MSG_OOB
100process out-of-band data
101.It Dv MSG_DONTROUTE
102bypass routing, use direct interface
103.It Dv MSG_NOSIGNAL
104don't send
105.Dv SIGPIPE
106.It Dv MSG_DONTWAIT
107don't block
108.El
109.Pp
110The flag
111.Dv MSG_OOB
112is used to send
113.Dq out-of-band
114data on sockets that support this notion (e.g.,
115.Dv SOCK_STREAM ) ;
116the underlying protocol must also support
117.Dq out-of-band
118data.
119.Dv MSG_DONTROUTE
120is usually used only by diagnostic or routing programs.
121.Dv MSG_NOSIGNAL
122is used to request not to send the
123.Dv SIGPIPE
124signal if an attempt to send is made on a socket that is shut down for
125writing or no longer connected.
126.Pp
127See
128.Xr recv 2
129for a description of the
130.Fa msghdr
131structure.
132.Sh RETURN VALUES
133The call returns the number of characters sent, or \-1
134if an error occurred.
135.Sh ERRORS
136.Fn send ,
137.Fn sendto ,
138and
139.Fn sendmsg
140fail if:
141.Bl -tag -width Er
142.It Bq Er EBADF
143An invalid descriptor was specified.
144.It Bq Er ENOTSOCK
145The argument
146.Fa s
147is not a socket.
148.It Bq Er EFAULT
149An invalid user space address was specified for a parameter.
150.It Bq Er EMSGSIZE
151The socket requires that message be sent atomically,
152and the size of the message to be sent made this impossible.
153.It Bq Er EAGAIN
154The socket is marked non-blocking and the requested operation
155would block.
156.It Bq Er ENOBUFS
157The system was unable to allocate an internal buffer.
158The operation may succeed when buffers become available.
159.It Bq Er ENOBUFS
160The output queue for a network interface was full.
161This generally indicates that the interface has stopped sending,
162but may be caused by transient congestion.
163.It Bq Er EACCES
164The
165.Dv SO_BROADCAST
166option is not set on the socket, and a broadcast address
167was given as the destination.
168.It Bq Er EHOSTUNREACH
169The destination address specified an unreachable host.
170.It Bq Er EINVAL
171The
172.Fa flags
173parameter is invalid.
174.It Bq Er EHOSTDOWN
175The destination address specified a host that is down.
176.It Bq Er ENETDOWN
177The destination address specified a network that is down.
178.It Bq Er ECONNREFUSED
179The destination host rejected the message (or a previous one).
180This error can only be returned by connected sockets.
181.It Bq Er ENOPROTOOPT
182There was a problem sending the message.
183This error can only be returned by connected sockets.
184.It Bq Er EDESTADDRREQ
185The socket is not connected, and no destination address was specified.
186.It Bq Er EISCONN
187The socket is already connected, and a destination address was specified.
188.It Bq Er EPIPE
189The socket is shut down for writing or not longer connected and the
190.Dv MSG_NOSIGNAL
191flag is set.
192.El
193.Pp
194In addition,
195.Fn send
196and
197.Fn sendto
198may return the following error:
199.Bl -tag -width Er
200.It Bq Er EINVAL
201.Fa len
202was larger than
203.Dv SSIZE_MAX .
204.El
205.Pp
206Also,
207.Fn sendmsg
208may return the following errors:
209.Bl -tag -width Er
210.It Bq Er EINVAL
211The sum of the
212.Fa iov_len
213values in the
214.Fa msg_iov
215array overflowed an
216.Em ssize_t .
217.It Bq Er EMSGSIZE
218The
219.Fa msg_iovlen
220member of
221.Fa msg
222was less than 0 or larger than
223.Dv IOV_MAX .
224.It Bq Er EAFNOSUPPORT
225Addresses in the specified address family cannot be used with this socket.
226.It Bq Er EMFILE
227The message contains control information utilizing
228.Xr CMSG_DATA 3
229to pass file descriptors, but too many file descriptors
230are already in-flight.
231.El
232.Sh SEE ALSO
233.Xr fcntl 2 ,
234.Xr getsockopt 2 ,
235.Xr poll 2 ,
236.Xr recv 2 ,
237.Xr select 2 ,
238.Xr socket 2 ,
239.Xr write 2 ,
240.Xr CMSG_DATA 3
241.Sh HISTORY
242The
243.Fn send
244function call appeared in
245.Bx 4.2 .
246