xref: /dragonfly/lib/libc/sys/send.2 (revision 8e1c6f81) 
1.\" Copyright (c) 1983, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\"    must display the following acknowledgement:
14.\"	This product includes software developed by the University of
15.\"	California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"     From: @(#)send.2	8.2 (Berkeley) 2/21/94
33.\" $FreeBSD: src/lib/libc/sys/send.2,v 1.10.2.6 2001/12/14 18:34:01 ru Exp $
34.\" $DragonFly: src/lib/libc/sys/send.2,v 1.9 2007/06/30 19:03:52 swildner Exp $
35.\"
36.Dd February 15, 1995
37.Dt SEND 2
38.Os
39.Sh NAME
40.Nm send ,
41.Nm sendto ,
42.Nm sendmsg
43.Nd send a message from a socket
44.Sh LIBRARY
45.Lb libc
46.Sh SYNOPSIS
47.In sys/types.h
48.In sys/socket.h
49.Ft ssize_t
50.Fn send "int s" "const void *msgbuf" "size_t len" "int flags"
51.Ft ssize_t
52.Fn sendto "int s" "const void *msgbuf" "size_t len" "int flags" "const struct sockaddr *to" "socklen_t tolen"
53.Ft ssize_t
54.Fn sendmsg "int s" "const struct msghdr *msg" "int flags"
55.Sh DESCRIPTION
56.Fn Send ,
57.Fn sendto ,
58and
59.Fn sendmsg
60are used to transmit a message to another socket.
61.Fn Send
62may be used only when the socket is in a
63.Em connected
64state, while
65.Fn sendto
66and
67.Fn sendmsg
68may be used at any time.
69.Pp
70The socket file descriptor is given by
71.Fa s .
72.Fa msgbuf
73points to a buffer containing the message.
74.Fa msg
75points to a
76.Fa msghdr
77structure.
78The address of the target is given by
79.Fa to
80with
81.Fa tolen
82specifying its size.
83The length of the message is given by
84.Fa len .
85If the message is too long to pass atomically through the
86underlying protocol, the error
87.Er EMSGSIZE
88is returned, and
89the message is not transmitted.
90.Pp
91No indication of failure to deliver is implicit in a
92.Fn send .
93Locally detected errors are indicated by a return value of -1.
94.Pp
95If no messages space is available at the socket to hold
96the message to be transmitted, then
97.Fn send
98normally blocks, unless the socket has been placed in
99non-blocking I/O mode.
100The
101.Xr select 2
102call may be used to determine when it is possible to
103send more data.
104.Pp
105The
106.Fa flags
107parameter may include one or more of the following:
108.Bd -literal
109#define	MSG_OOB		0x1   /* process out-of-band data */
110#define	MSG_PEEK	0x2   /* peek at incoming message */
111#define	MSG_DONTROUTE	0x4   /* bypass routing, use direct interface */
112#define MSG_EOR		0x8   /* data completes record */
113#define	MSG_EOF		0x100 /* data completes transaction */
114.Ed
115.Pp
116The flag
117.Dv MSG_OOB
118is used to send
119.Dq out-of-band
120data on sockets that support this notion (e.g.\&
121.Dv SOCK_STREAM ) ;
122the underlying protocol must also support
123.Dq out-of-band
124data.
125.Dv MSG_EOR
126is used to indicate a record mark for protocols which support the
127concept.
128.Dv MSG_EOF
129requests that the sender side of a socket be shut down, and that an
130appropriate indication be sent at the end of the specified data;
131this flag is only implemented for
132.Dv SOCK_STREAM
133sockets in the
134.Dv PF_INET
135protocol family, and is used to implement Transaction
136.Tn TCP
137(see
138.Xr ttcp 4 ) .
139.Dv MSG_DONTROUTE
140is usually used only by diagnostic or routing programs.
141.Pp
142See
143.Xr recv 2
144for a description of the
145.Fa msghdr
146structure.
147.Sh RETURN VALUES
148Upon successful completion the number of characters which were sent is
149returned.  Otherwise -1 is returned and the global variable
150.Va errno
151is set to indicate the error.
152.Sh ERRORS
153.Fn Send ,
154.Fn sendto ,
155and
156.Fn sendmsg
157fail if:
158.Bl -tag -width Er
159.It Bq Er EBADF
160An invalid descriptor was specified.
161.It Bq Er EACCES
162The destination address is a broadcast address, and
163.Dv SO_BROADCAST
164has not been set on the socket.
165.It Bq Er ENOTSOCK
166The argument
167.Fa s
168is not a socket.
169.It Bq Er EFAULT
170An invalid user space address was specified for a parameter.
171.It Bq Er EMSGSIZE
172The socket requires that message be sent atomically,
173and the size of the message to be sent made this impossible.
174.It Bq Er EAGAIN
175The socket is marked non-blocking and the requested operation
176would block.
177.It Bq Er ENOBUFS
178The system was unable to allocate an internal buffer.
179The operation may succeed when buffers become available.
180.It Bq Er ENOBUFS
181The output queue for a network interface was full.
182This generally indicates that the interface has stopped sending,
183but may be caused by transient congestion.
184.It Bq Er EHOSTUNREACH
185The remote host was unreachable.
186.It Bq Er ECONNREFUSED
187The socket received an ICMP destination unreachable message
188from the last message sent.  This typically means that the
189receiver is not listening on the remote port.
190.It Bq Er EHOSTDOWN
191The remote host was down.
192.It Bq Er EPIPE
193The socket is unable to send anymore data (SS_CANTSENDMORE has
194been set on the socket). This typically means that the socket
195is not connected.
196.El
197.Sh SEE ALSO
198.Xr fcntl 2 ,
199.Xr getsockopt 2 ,
200.Xr recv 2 ,
201.Xr select 2 ,
202.Xr socket 2 ,
203.Xr write 2
204.Sh HISTORY
205The
206.Fn send
207function call appeared in
208.Bx 4.2 .
209.Sh BUGS
210Because
211.Fn sendmsg
212doesn't necessarily block until the data has been transferred, it
213is possible to transfer an open file descriptor across an
214.Dv AF_UNIX
215domain socket
216(see
217.Xr recv 2 ) ,
218then
219.Fn close
220it before it has actually been sent, the result being that the receiver
221gets a closed file descriptor.  It is left to the application to
222implement an acknowledgment mechanism to prevent this from happening.
223