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 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. 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 EPERM 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 BUGS 207Because 208.Fn sendmsg 209doesn't necessarily block until the data has been transferred, it 210is possible to transfer an open file descriptor across an 211.Dv AF_UNIX 212domain socket 213(see 214.Xr recv 2 ) , 215then 216.Fn close 217it before it has actually been sent, the result being that the receiver 218gets a closed file descriptor. 219It is left to the application to 220implement an acknowledgment mechanism to prevent this from happening. 221.Sh SEE ALSO 222.Xr fcntl 2 , 223.Xr getsockopt 2 , 224.Xr recv 2 , 225.Xr select 2 , 226.Xr socket 2 , 227.Xr write 2 228.Sh HISTORY 229The 230.Fn send 231function appeared in 232.Bx 4.2 . 233