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.\" 4. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" From: @(#)send.2 8.2 (Berkeley) 2/21/94 29.\" $FreeBSD$ 30.\" 31.Dd February 5, 2009 32.Dt SEND 2 33.Os 34.Sh NAME 35.Nm send , 36.Nm sendto , 37.Nm sendmsg 38.Nd send a message from a socket 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In sys/types.h 43.In 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 51The 52.Fn send 53function, 54and 55.Fn sendto 56and 57.Fn sendmsg 58system calls 59are used to transmit a message to another socket. 60The 61.Fn send 62function 63may be used only when the socket is in a 64.Em connected 65state, while 66.Fn sendto 67and 68.Fn sendmsg 69may be used at any time. 70.Pp 71The address of the target is given by 72.Fa to 73with 74.Fa tolen 75specifying its size. 76The length of the message is given by 77.Fa len . 78If the message is too long to pass atomically through the 79underlying protocol, the error 80.Er EMSGSIZE 81is returned, and 82the message is not transmitted. 83.Pp 84No indication of failure to deliver is implicit in a 85.Fn send . 86Locally detected errors are indicated by a return value of -1. 87.Pp 88If no messages space is available at the socket to hold 89the message to be transmitted, then 90.Fn send 91normally blocks, unless the socket has been placed in 92non-blocking I/O mode. 93The 94.Xr select 2 95system call may be used to determine when it is possible to 96send more data. 97.Pp 98The 99.Fa flags 100argument may include one or more of the following: 101.Bd -literal 102#define MSG_OOB 0x00001 /* process out-of-band data */ 103#define MSG_DONTROUTE 0x00004 /* bypass routing, use direct interface */ 104#define MSG_EOR 0x00008 /* data completes record */ 105#define MSG_EOF 0x00100 /* data completes transaction */ 106#define MSG_NOSIGNAL 0x20000 /* do not generate SIGPIPE on EOF */ 107.Ed 108.Pp 109The flag 110.Dv MSG_OOB 111is used to send 112.Dq out-of-band 113data on sockets that support this notion (e.g.\& 114.Dv SOCK_STREAM ) ; 115the underlying protocol must also support 116.Dq out-of-band 117data. 118.Dv MSG_EOR 119is used to indicate a record mark for protocols which support the 120concept. 121.Dv MSG_EOF 122requests that the sender side of a socket be shut down, and that an 123appropriate indication be sent at the end of the specified data; 124this flag is only implemented for 125.Dv SOCK_STREAM 126sockets in the 127.Dv PF_INET 128protocol family. 129.Dv MSG_DONTROUTE 130is usually used only by diagnostic or routing programs. 131.Dv MSG_NOSIGNAL 132is used to prevent 133.Dv SIGPIPE 134generation when writing a socket that 135may be closed. 136.Pp 137See 138.Xr recv 2 139for a description of the 140.Fa msghdr 141structure. 142.Sh RETURN VALUES 143The call returns the number of characters sent, or -1 144if an error occurred. 145.Sh ERRORS 146The 147.Fn send 148function and 149.Fn sendto 150and 151.Fn sendmsg 152system calls 153fail if: 154.Bl -tag -width Er 155.It Bq Er EBADF 156An invalid descriptor was specified. 157.It Bq Er EACCES 158The destination address is a broadcast address, and 159.Dv SO_BROADCAST 160has not been set on the socket. 161.It Bq Er ENOTSOCK 162The argument 163.Fa s 164is not a socket. 165.It Bq Er EFAULT 166An invalid user space address was specified for an argument. 167.It Bq Er EMSGSIZE 168The socket requires that message be sent atomically, 169and the size of the message to be sent made this impossible. 170.It Bq Er EAGAIN 171The socket is marked non-blocking and the requested operation 172would block. 173.It Bq Er ENOBUFS 174The system was unable to allocate an internal buffer. 175The operation may succeed when buffers become available. 176.It Bq Er ENOBUFS 177The output queue for a network interface was full. 178This generally indicates that the interface has stopped sending, 179but may be caused by transient congestion. 180.It Bq Er EHOSTUNREACH 181The remote host was unreachable. 182.It Bq Er EISCONN 183A destination address was specified and the socket is already connected. 184.It Bq Er ECONNREFUSED 185The socket received an ICMP destination unreachable message 186from the last message sent. 187This typically means that the 188receiver is not listening on the remote port. 189.It Bq Er EHOSTDOWN 190The remote host was down. 191.It Bq Er ENETDOWN 192The remote network was down. 193.It Bq Er EADDRNOTAVAIL 194The process using a 195.Dv SOCK_RAW 196socket was jailed and the source 197address specified in the IP header did not match the IP 198address bound to the prison. 199.It Bq Er EPIPE 200The socket is unable to send anymore data 201.Dv ( SBS_CANTSENDMORE 202has been set on the socket). 203This typically means that the socket 204is not connected. 205.El 206.Sh SEE ALSO 207.Xr fcntl 2 , 208.Xr getsockopt 2 , 209.Xr recv 2 , 210.Xr select 2 , 211.Xr socket 2 , 212.Xr write 2 213.Sh HISTORY 214The 215.Fn send 216function appeared in 217.Bx 4.2 . 218.Sh BUGS 219Because 220.Fn sendmsg 221does not necessarily block until the data has been transferred, it 222is possible to transfer an open file descriptor across an 223.Dv AF_UNIX 224domain socket 225(see 226.Xr recv 2 ) , 227then 228.Fn close 229it before it has actually been sent, the result being that the receiver 230gets a closed file descriptor. 231It is left to the application to 232implement an acknowledgment mechanism to prevent this from happening. 233