1.\" $OpenBSD: send.2,v 1.34 2019/01/11 06:10:13 jsg Exp $ 2.\" $NetBSD: send.2,v 1.6 1996/01/15 01:17:18 thorpej Exp $ 3.\" 4.\" Copyright (c) 1983, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)send.2 8.2 (Berkeley) 2/21/94 32.\" 33.Dd $Mdocdate: January 11 2019 $ 34.Dt SEND 2 35.Os 36.Sh NAME 37.Nm send , 38.Nm sendto , 39.Nm sendmsg 40.Nd send a message from a socket 41.Sh SYNOPSIS 42.In sys/socket.h 43.Ft ssize_t 44.Fn send "int s" "const void *msg" "size_t len" "int flags" 45.Ft ssize_t 46.Fn sendto "int s" "const void *msg" "size_t len" "int flags" "const struct sockaddr *to" "socklen_t tolen" 47.Ft ssize_t 48.Fn sendmsg "int s" "const struct msghdr *msg" "int flags" 49.Sh DESCRIPTION 50.Fn send , 51.Fn sendto , 52and 53.Fn sendmsg 54are used to transmit a message to another socket. 55.Fn send 56may be used only when the socket is in a 57.Em connected 58state, while 59.Fn sendto 60and 61.Fn sendmsg 62may be used at any time. 63.Pp 64The address of the target is given by 65.Fa to 66with 67.Fa tolen 68specifying its size. 69The length of the message is given by 70.Fa len . 71If the message is too long to pass atomically through the 72underlying protocol, the error 73.Er EMSGSIZE 74is returned, and 75the message is not transmitted. 76.Pp 77No indication of failure to deliver is implicit in a 78.Fn send . 79Locally detected errors are indicated by a return value of \-1. 80.Pp 81If no messages space is available at the socket to hold 82the message to be transmitted, then 83.Fn send 84normally blocks, unless the socket has been placed in 85non-blocking I/O mode. 86The 87.Xr select 2 88or 89.Xr poll 2 90system calls may be used to determine when it is possible to 91send more data. 92.Pp 93The 94.Fa flags 95parameter may include one or more of the following: 96.Pp 97.Bl -tag -width "MSG_DONTROUTEXX" -offset indent -compact 98.It Dv MSG_DONTROUTE 99bypass routing tables, silently ignored 100.It Dv MSG_DONTWAIT 101don't block 102.It Dv MSG_EOR 103terminate the record (SOCK_SEQPACKET only) 104.It Dv MSG_NOSIGNAL 105don't send 106.Dv SIGPIPE 107.It Dv MSG_OOB 108process out-of-band data 109.El 110.Pp 111The flag 112.Dv MSG_OOB 113is used to send 114.Dq out-of-band 115data on sockets that support this notion (e.g., 116.Dv SOCK_STREAM ) ; 117the underlying protocol must also support 118.Dq out-of-band 119data. 120.Dv MSG_NOSIGNAL 121is used to request not to send the 122.Dv SIGPIPE 123signal if an attempt to send is made on a socket that is shut down for 124writing or no longer connected. 125.Pp 126See 127.Xr recv 2 128for a description of the 129.Fa msghdr 130structure. 131.Sh RETURN VALUES 132The call returns the number of characters sent, or \-1 133if an error occurred. 134.Sh ERRORS 135.Fn send , 136.Fn sendto , 137and 138.Fn sendmsg 139fail if: 140.Bl -tag -width Er 141.It Bq Er EBADF 142An invalid descriptor was specified. 143.It Bq Er ENOTSOCK 144The argument 145.Fa s 146is not a socket. 147.It Bq Er EFAULT 148An invalid user space address was specified for a parameter. 149.It Bq Er EMSGSIZE 150The socket requires that message be sent atomically, 151and the size of the message to be sent made this impossible. 152.It Bq Er EAGAIN 153The socket is marked non-blocking or the 154.Dv MSG_DONTWAIT 155flag is set and the requested operation 156would block. 157.It Bq Er ENOBUFS 158The system was unable to allocate an internal buffer. 159The operation may succeed when buffers become available. 160.It Bq Er ENOBUFS 161The output queue for a network interface was full. 162This generally indicates that the interface has stopped sending, 163but may be caused by transient congestion. 164.It Bq Er EACCES 165The connection was blocked by 166.Xr pf 4 , 167or 168.Dv SO_BROADCAST 169is not set on the socket 170and a broadcast address was given as the destination. 171.It Bq Er EHOSTUNREACH 172The destination address specified an unreachable host. 173.It Bq Er EINVAL 174The 175.Fa flags 176parameter is invalid. 177.It Bq Er EHOSTDOWN 178The destination address specified a host that is down. 179.It Bq Er ENETDOWN 180The destination address specified a network that is down. 181.It Bq Er ECONNREFUSED 182The destination host rejected the message (or a previous one). 183This error can only be returned by connected sockets. 184.It Bq Er ENOPROTOOPT 185There was a problem sending the message. 186This error can only be returned by connected sockets. 187.It Bq Er EDESTADDRREQ 188The socket is not connected, and no destination address was specified. 189.It Bq Er EPIPE 190The socket is shut down for writing or not longer connected and the 191.Dv MSG_NOSIGNAL 192flag is set. 193.El 194.Pp 195In addition, 196.Fn send 197and 198.Fn sendto 199may return the following error: 200.Bl -tag -width Er 201.It Bq Er EINVAL 202.Fa len 203was larger than 204.Dv SSIZE_MAX . 205.El 206.Pp 207.Fn sendto 208and 209.Fn sendmsg 210may return the following errors: 211.Bl -tag -width Er 212.It Bq Er EADDRNOTAVAIL 213No suitable address is available on the local machine. 214.It Bq Er EAFNOSUPPORT 215Addresses in the specified address family cannot be used with this socket. 216.It Bq Er EISCONN 217The socket is already connected, and a destination address was specified. 218.El 219.Pp 220.Fn sendmsg 221may return the following errors: 222.Bl -tag -width Er 223.It Bq Er EINVAL 224The sum of the 225.Fa iov_len 226values in the 227.Fa msg_iov 228array overflowed an 229.Em ssize_t . 230.It Bq Er EMSGSIZE 231The 232.Fa msg_iovlen 233member of 234.Fa msg 235was less than 0 or larger than 236.Dv IOV_MAX . 237.It Bq Er EMFILE 238The message contains control information utilizing 239.Xr CMSG_DATA 3 240to pass file descriptors, but too many file descriptors 241are already in-flight. 242.El 243.Sh SEE ALSO 244.Xr fcntl 2 , 245.Xr getsockopt 2 , 246.Xr poll 2 , 247.Xr recv 2 , 248.Xr select 2 , 249.Xr socket 2 , 250.Xr write 2 , 251.Xr CMSG_DATA 3 252.Sh STANDARDS 253The 254.Fn send , 255.Fn sendto , 256and 257.Fn sendmsg 258functions conform to 259.St -p1003.1-2008 . 260The 261.Dv MSG_DONTWAIT 262and 263.Dv MSG_NOSIGNAL 264flags are extensions to that specification. 265.Sh HISTORY 266The 267.Fn send 268function call appeared in 269.Bx 4.1c . 270