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: head/lib/libc/sys/send.2 108087 2002-12-19 09:40:28Z ru $
34.\"
35.Dd February 15, 1995
36.Dt SEND 2
37.Os
38.Sh NAME
39.Nm send ,
40.Nm sendto ,
41.Nm sendmsg
42.Nd send a message from a socket
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.In sys/types.h
47.In sys/socket.h
48.Ft ssize_t
49.Fn send "int s" "const void *msg" "size_t len" "int flags"
50.Ft ssize_t
51.Fn sendto "int s" "const void *msg" "size_t len" "int flags" "const struct sockaddr *to" "socklen_t tolen"
52.Ft ssize_t
53.Fn sendmsg "int s" "const struct msghdr *msg" "int flags"
54.Sh DESCRIPTION
55The
56.Fn send
57function,
58and
59.Fn sendto
60and
61.Fn sendmsg
62system calls
63are used to transmit a message to another socket.
64The
65.Fn send
66function
67may be used only when the socket is in a
68.Em connected
69state, while
70.Fn sendto
71and
72.Fn sendmsg
73may be used at any time.
74.Pp
75The address of the target is given by
76.Fa to
77with
78.Fa tolen
79specifying its size.
80The length of the message is given by
81.Fa len .
82If the message is too long to pass atomically through the
83underlying protocol, the error
84.Er EMSGSIZE
85is returned, and
86the message is not transmitted.
87.Pp
88No indication of failure to deliver is implicit in a
89.Fn send .
90Locally detected errors are indicated by a return value of -1.
91.Pp
92If no messages space is available at the socket to hold
93the message to be transmitted, then
94.Fn send
95normally blocks, unless the socket has been placed in
96non-blocking I/O mode.
97The
98.Xr select 2
99system call may be used to determine when it is possible to
100send more data.
101.Pp
102The
103.Fa flags
104argument may include one or more of the following:
105.Bd -literal
106#define MSG_OOB 0x1 /* process out-of-band data */
107#define MSG_PEEK 0x2 /* peek at incoming message */
108#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */
109#define MSG_EOR 0x8 /* data completes record */
110#define MSG_EOF 0x100 /* data completes transaction */
111.Ed
112.Pp
113The flag
114.Dv MSG_OOB
115is used to send
116.Dq out-of-band
117data on sockets that support this notion (e.g.\&
118.Dv SOCK_STREAM ) ;
119the underlying protocol must also support
120.Dq out-of-band
121data.
122.Dv MSG_EOR
123is used to indicate a record mark for protocols which support the
124concept.
125.Dv MSG_EOF
126requests that the sender side of a socket be shut down, and that an
127appropriate indication be sent at the end of the specified data;
128this flag is only implemented for
129.Dv SOCK_STREAM
130sockets in the
131.Dv PF_INET
132protocol family, and is used to implement Transaction
133.Tn TCP
134(see
135.Xr ttcp 4 ) .
136.Dv MSG_DONTROUTE
137is usually used only by diagnostic or routing programs.
138.Pp
139See
140.Xr recv 2
141for a description of the
142.Fa msghdr
143structure.
144.Sh RETURN VALUES
145The call returns the number of characters sent, or -1
146if an error occurred.
147.Sh ERRORS
148The
149.Fn send
150function and
151.Fn sendto
152and
153.Fn sendmsg
154system calls
155fail if:
156.Bl -tag -width Er
157.It Bq Er EBADF
158An invalid descriptor was specified.
159.It Bq Er EACCES
160The destination address is a broadcast address, and
161.Dv SO_BROADCAST
162has not been set on the socket.
163.It Bq Er ENOTSOCK
164The argument
165.Fa s
166is not a socket.
167.It Bq Er EFAULT
168An invalid user space address was specified for an argument.
169.It Bq Er EMSGSIZE
170The socket requires that message be sent atomically,
171and the size of the message to be sent made this impossible.
172.It Bq Er EAGAIN
173The socket is marked non-blocking and the requested operation
174would block.
175.It Bq Er ENOBUFS
176The system was unable to allocate an internal buffer.
177The operation may succeed when buffers become available.
178.It Bq Er ENOBUFS
179The output queue for a network interface was full.
180This generally indicates that the interface has stopped sending,
181but may be caused by transient congestion.
182.It Bq Er EHOSTUNREACH
183The remote host was unreachable.
184.It Bq Er ECONNREFUSED
185The socket received an ICMP destination unreachable message
186from the last message sent. This typically means that the
187receiver is not listening on the remote port.
188.It Bq Er EHOSTDOWN
189The remote host was down.
190.It Bq Er ENETDOWN
191The remote network was down.
192.El
193.Sh BUGS
194Because
195.Fn sendmsg
196doesn't necessarily block until the data has been transferred, it
197is possible to transfer an open file descriptor across an
198.Dv AF_UNIX
199domain socket
200(see
201.Xr recv 2 ) ,
202then
203.Fn close
204it before it has actually been sent, the result being that the receiver
205gets a closed file descriptor. It is left to the application to
206implement an acknowlegment mechanism to prevent this from happening.
207.Sh SEE ALSO
208.Xr fcntl 2 ,
209.Xr getsockopt 2 ,
210.Xr recv 2 ,
211.Xr select 2 ,
212.Xr socket 2 ,
213.Xr write 2
214.Sh HISTORY
215The
216.Fn send
217function appeared in
218.Bx 4.2 .
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: head/lib/libc/sys/send.2 108087 2002-12-19 09:40:28Z ru $
34.\"
35.Dd February 15, 1995
36.Dt SEND 2
37.Os
38.Sh NAME
39.Nm send ,
40.Nm sendto ,
41.Nm sendmsg
42.Nd send a message from a socket
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.In sys/types.h
47.In sys/socket.h
48.Ft ssize_t
49.Fn send "int s" "const void *msg" "size_t len" "int flags"
50.Ft ssize_t
51.Fn sendto "int s" "const void *msg" "size_t len" "int flags" "const struct sockaddr *to" "socklen_t tolen"
52.Ft ssize_t
53.Fn sendmsg "int s" "const struct msghdr *msg" "int flags"
54.Sh DESCRIPTION
55The
56.Fn send
57function,
58and
59.Fn sendto
60and
61.Fn sendmsg
62system calls
63are used to transmit a message to another socket.
64The
65.Fn send
66function
67may be used only when the socket is in a
68.Em connected
69state, while
70.Fn sendto
71and
72.Fn sendmsg
73may be used at any time.
74.Pp
75The address of the target is given by
76.Fa to
77with
78.Fa tolen
79specifying its size.
80The length of the message is given by
81.Fa len .
82If the message is too long to pass atomically through the
83underlying protocol, the error
84.Er EMSGSIZE
85is returned, and
86the message is not transmitted.
87.Pp
88No indication of failure to deliver is implicit in a
89.Fn send .
90Locally detected errors are indicated by a return value of -1.
91.Pp
92If no messages space is available at the socket to hold
93the message to be transmitted, then
94.Fn send
95normally blocks, unless the socket has been placed in
96non-blocking I/O mode.
97The
98.Xr select 2
99system call may be used to determine when it is possible to
100send more data.
101.Pp
102The
103.Fa flags
104argument may include one or more of the following:
105.Bd -literal
106#define MSG_OOB 0x1 /* process out-of-band data */
107#define MSG_PEEK 0x2 /* peek at incoming message */
108#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */
109#define MSG_EOR 0x8 /* data completes record */
110#define MSG_EOF 0x100 /* data completes transaction */
111.Ed
112.Pp
113The flag
114.Dv MSG_OOB
115is used to send
116.Dq out-of-band
117data on sockets that support this notion (e.g.\&
118.Dv SOCK_STREAM ) ;
119the underlying protocol must also support
120.Dq out-of-band
121data.
122.Dv MSG_EOR
123is used to indicate a record mark for protocols which support the
124concept.
125.Dv MSG_EOF
126requests that the sender side of a socket be shut down, and that an
127appropriate indication be sent at the end of the specified data;
128this flag is only implemented for
129.Dv SOCK_STREAM
130sockets in the
131.Dv PF_INET
132protocol family, and is used to implement Transaction
133.Tn TCP
134(see
135.Xr ttcp 4 ) .
136.Dv MSG_DONTROUTE
137is usually used only by diagnostic or routing programs.
138.Pp
139See
140.Xr recv 2
141for a description of the
142.Fa msghdr
143structure.
144.Sh RETURN VALUES
145The call returns the number of characters sent, or -1
146if an error occurred.
147.Sh ERRORS
148The
149.Fn send
150function and
151.Fn sendto
152and
153.Fn sendmsg
154system calls
155fail if:
156.Bl -tag -width Er
157.It Bq Er EBADF
158An invalid descriptor was specified.
159.It Bq Er EACCES
160The destination address is a broadcast address, and
161.Dv SO_BROADCAST
162has not been set on the socket.
163.It Bq Er ENOTSOCK
164The argument
165.Fa s
166is not a socket.
167.It Bq Er EFAULT
168An invalid user space address was specified for an argument.
169.It Bq Er EMSGSIZE
170The socket requires that message be sent atomically,
171and the size of the message to be sent made this impossible.
172.It Bq Er EAGAIN
173The socket is marked non-blocking and the requested operation
174would block.
175.It Bq Er ENOBUFS
176The system was unable to allocate an internal buffer.
177The operation may succeed when buffers become available.
178.It Bq Er ENOBUFS
179The output queue for a network interface was full.
180This generally indicates that the interface has stopped sending,
181but may be caused by transient congestion.
182.It Bq Er EHOSTUNREACH
183The remote host was unreachable.
184.It Bq Er ECONNREFUSED
185The socket received an ICMP destination unreachable message
186from the last message sent. This typically means that the
187receiver is not listening on the remote port.
188.It Bq Er EHOSTDOWN
189The remote host was down.
190.It Bq Er ENETDOWN
191The remote network was down.
192.El
193.Sh BUGS
194Because
195.Fn sendmsg
196doesn't necessarily block until the data has been transferred, it
197is possible to transfer an open file descriptor across an
198.Dv AF_UNIX
199domain socket
200(see
201.Xr recv 2 ) ,
202then
203.Fn close
204it before it has actually been sent, the result being that the receiver
205gets a closed file descriptor. It is left to the application to
206implement an acknowlegment mechanism to prevent this from happening.
207.Sh SEE ALSO
208.Xr fcntl 2 ,
209.Xr getsockopt 2 ,
210.Xr recv 2 ,
211.Xr select 2 ,
212.Xr socket 2 ,
213.Xr write 2
214.Sh HISTORY
215The
216.Fn send
217function appeared in
218.Bx 4.2 .