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$ 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 0x00001 /* process out-of-band data */ 107#define MSG_PEEK 0x00002 /* peek at incoming message */ 108#define MSG_DONTROUTE 0x00004 /* bypass routing, use direct interface */ 109#define MSG_EOR 0x00008 /* data completes record */ 110#define MSG_EOF 0x00100 /* data completes transaction */ 111#define MSG_NOSIGNAL 0x20000 /* do not generate SIGPIPE on EOF */ 112.Ed 113.Pp 114The flag 115.Dv MSG_OOB 116is used to send 117.Dq out-of-band 118data on sockets that support this notion (e.g.\& 119.Dv SOCK_STREAM ) ; 120the underlying protocol must also support 121.Dq out-of-band 122data. 123.Dv MSG_EOR 124is used to indicate a record mark for protocols which support the 125concept. 126.Dv MSG_EOF 127requests that the sender side of a socket be shut down, and that an 128appropriate indication be sent at the end of the specified data; 129this flag is only implemented for 130.Dv SOCK_STREAM 131sockets in the 132.Dv PF_INET 133protocol family, and is used to implement Transaction 134.Tn TCP 135(see 136.Xr ttcp 4 ) . 137.Dv MSG_DONTROUTE 138is usually used only by diagnostic or routing programs. 139.Dv MSG_NOSIGNAL 140is used to prevent 141.Dv SIGPIPE 142generation when writing a socket that 143may be closed. 144.Pp 145See 146.Xr recv 2 147for a description of the 148.Fa msghdr 149structure. 150.Sh RETURN VALUES 151The call returns the number of characters sent, or -1 152if an error occurred. 153.Sh ERRORS 154The 155.Fn send 156function and 157.Fn sendto 158and 159.Fn sendmsg 160system calls 161fail if: 162.Bl -tag -width Er 163.It Bq Er EBADF 164An invalid descriptor was specified. 165.It Bq Er EACCES 166The destination address is a broadcast address, and 167.Dv SO_BROADCAST 168has not been set on the socket. 169.It Bq Er ENOTSOCK 170The argument 171.Fa s 172is not a socket. 173.It Bq Er EFAULT 174An invalid user space address was specified for an argument. 175.It Bq Er EMSGSIZE 176The socket requires that message be sent atomically, 177and the size of the message to be sent made this impossible. 178.It Bq Er EAGAIN 179The socket is marked non-blocking and the requested operation 180would block. 181.It Bq Er ENOBUFS 182The system was unable to allocate an internal buffer. 183The operation may succeed when buffers become available. 184.It Bq Er ENOBUFS 185The output queue for a network interface was full. 186This generally indicates that the interface has stopped sending, 187but may be caused by transient congestion. 188.It Bq Er EHOSTUNREACH 189The remote host was unreachable. 190.It Bq Er EISCONN 191A destination address was specified and the socket is already connected. 192.It Bq Er ECONNREFUSED 193The socket received an ICMP destination unreachable message 194from the last message sent. 195This typically means that the 196receiver is not listening on the remote port. 197.It Bq Er EHOSTDOWN 198The remote host was down. 199.It Bq Er ENETDOWN 200The remote network was down. 201.It Bq Er EPERM 202The process using a 203.Dv SOCK_RAW 204socket was jailed and the source 205address specified in the IP header did not match the IP 206address bound to the prison. 207.It Bq Er EPIPE 208The socket is unable to send anymore data 209.Dv ( SBS_CANTSENDMORE 210has been set on the socket). 211This typically means that the socket 212is not connected. 213.El 214.Sh SEE ALSO 215.Xr fcntl 2 , 216.Xr getsockopt 2 , 217.Xr recv 2 , 218.Xr select 2 , 219.Xr socket 2 , 220.Xr write 2 221.Sh HISTORY 222The 223.Fn send 224function appeared in 225.Bx 4.2 . 226.Sh BUGS 227Because 228.Fn sendmsg 229does not necessarily block until the data has been transferred, it 230is possible to transfer an open file descriptor across an 231.Dv AF_UNIX 232domain socket 233(see 234.Xr recv 2 ) , 235then 236.Fn close 237it before it has actually been sent, the result being that the receiver 238gets a closed file descriptor. 239It is left to the application to 240implement an acknowledgment mechanism to prevent this from happening. 241