1.\" $OpenBSD: send.2,v 1.35 2022/09/09 13:52:59 mbuhl 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: September 9 2022 $ 34.Dt SEND 2 35.Os 36.Sh NAME 37.Nm send , 38.Nm sendto , 39.Nm sendmsg , 40.Nm sendmmsg 41.Nd send a message from a socket 42.Sh SYNOPSIS 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.Ft int 51.Fn sendmmsg "int s" "const struct mmsghdr *mmsg" "unsigned int vlen" "int flags" 52.Sh DESCRIPTION 53.Fn send , 54.Fn sendto , 55.Fn sendmsg , 56and 57.Fn sendmmsg 58are used to transmit a message to another socket. 59.Fn send 60may be used only when the socket is in a 61.Em connected 62state, while 63.Fn sendto , 64.Fn sendmsg , 65and 66.Fn sendmmsg 67may be used at any time. 68.Pp 69The address of the target is given by 70.Fa to 71with 72.Fa tolen 73specifying its size. 74The length of the message is given by 75.Fa len . 76If the message is too long to pass atomically through the 77underlying protocol, the error 78.Er EMSGSIZE 79is returned, and 80the message is not transmitted. 81.Pp 82No indication of failure to deliver is implicit in a 83.Fn send . 84Locally detected errors are indicated by a return value of \-1. 85.Pp 86If no messages space is available at the socket to hold 87the message to be transmitted, then 88.Fn send 89normally blocks, unless the socket has been placed in 90non-blocking I/O mode. 91The 92.Xr select 2 93or 94.Xr poll 2 95system calls may be used to determine when it is possible to 96send more data. 97.Pp 98The 99.Fa flags 100parameter may include one or more of the following: 101.Pp 102.Bl -tag -width "MSG_DONTROUTEXX" -offset indent -compact 103.It Dv MSG_DONTROUTE 104bypass routing tables, silently ignored 105.It Dv MSG_DONTWAIT 106don't block 107.It Dv MSG_EOR 108terminate the record (SOCK_SEQPACKET only) 109.It Dv MSG_NOSIGNAL 110don't send 111.Dv SIGPIPE 112.It Dv MSG_OOB 113process out-of-band data 114.El 115.Pp 116The flag 117.Dv MSG_OOB 118is used to send 119.Dq out-of-band 120data on sockets that support this notion (e.g., 121.Dv SOCK_STREAM ) ; 122the underlying protocol must also support 123.Dq out-of-band 124data. 125.Dv MSG_NOSIGNAL 126is used to request not to send the 127.Dv SIGPIPE 128signal if an attempt to send is made on a socket that is shut down for 129writing or no longer connected. 130.Pp 131See 132.Xr recv 2 133for a description of the 134.Fa msghdr 135and 136.Fa mmsghdr 137structures. 138.Sh RETURN VALUES 139The 140.Fn send , 141.Fn sendto , 142and 143.Fn sendmsg 144calls return the number of characters sent, or \-1 145if an error occurred. 146The 147.Fn sendmmsg 148call returns the number of messages sent, or \-1 149if an error occurred before the first message has been sent. 150.Sh ERRORS 151.Fn send , 152.Fn sendto , 153and 154.Fn sendmsg 155fail if: 156.Bl -tag -width Er 157.It Bq Er EBADF 158An invalid descriptor was specified. 159.It Bq Er ENOTSOCK 160The argument 161.Fa s 162is not a socket. 163.It Bq Er EFAULT 164An invalid user space address was specified for a parameter. 165.It Bq Er EMSGSIZE 166The socket requires that message be sent atomically, 167and the size of the message to be sent made this impossible. 168.It Bq Er EAGAIN 169The socket is marked non-blocking or the 170.Dv MSG_DONTWAIT 171flag is set 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 EACCES 181The connection was blocked by 182.Xr pf 4 , 183or 184.Dv SO_BROADCAST 185is not set on the socket 186and a broadcast address was given as the destination. 187.It Bq Er EHOSTUNREACH 188The destination address specified an unreachable host. 189.It Bq Er EINVAL 190The 191.Fa flags 192parameter is invalid. 193.It Bq Er EHOSTDOWN 194The destination address specified a host that is down. 195.It Bq Er ENETDOWN 196The destination address specified a network that is down. 197.It Bq Er ECONNREFUSED 198The destination host rejected the message (or a previous one). 199This error can only be returned by connected sockets. 200.It Bq Er ENOPROTOOPT 201There was a problem sending the message. 202This error can only be returned by connected sockets. 203.It Bq Er EDESTADDRREQ 204The socket is not connected, and no destination address was specified. 205.It Bq Er EPIPE 206The socket is shut down for writing or not longer connected and the 207.Dv MSG_NOSIGNAL 208flag is set. 209.El 210.Pp 211In addition, 212.Fn send 213and 214.Fn sendto 215may return the following error: 216.Bl -tag -width Er 217.It Bq Er EINVAL 218.Fa len 219was larger than 220.Dv SSIZE_MAX . 221.El 222.Pp 223.Fn sendto 224and 225.Fn sendmsg 226may return the following errors: 227.Bl -tag -width Er 228.It Bq Er EADDRNOTAVAIL 229No suitable address is available on the local machine. 230.It Bq Er EAFNOSUPPORT 231Addresses in the specified address family cannot be used with this socket. 232.It Bq Er EISCONN 233The socket is already connected, and a destination address was specified. 234.El 235.Pp 236.Fn sendmsg 237may return the following errors: 238.Bl -tag -width Er 239.It Bq Er EINVAL 240The sum of the 241.Fa iov_len 242values in the 243.Fa msg_iov 244array overflowed an 245.Em ssize_t . 246.It Bq Er EMSGSIZE 247The 248.Fa msg_iovlen 249member of 250.Fa msg 251was less than 0 or larger than 252.Dv IOV_MAX . 253.It Bq Er EMFILE 254The message contains control information utilizing 255.Xr CMSG_DATA 3 256to pass file descriptors, but too many file descriptors 257are already in-flight. 258.El 259.Sh SEE ALSO 260.Xr fcntl 2 , 261.Xr getsockopt 2 , 262.Xr poll 2 , 263.Xr recv 2 , 264.Xr select 2 , 265.Xr socket 2 , 266.Xr write 2 , 267.Xr CMSG_DATA 3 268.Sh STANDARDS 269The 270.Fn send , 271.Fn sendto , 272and 273.Fn sendmsg 274functions conform to 275.St -p1003.1-2008 . 276The 277.Dv MSG_DONTWAIT 278and 279.Dv MSG_NOSIGNAL 280flags are extensions to that specification. 281.Sh HISTORY 282The 283.Fn send 284function call appeared in 285.Bx 4.1c . 286The 287.Fn sendmmsg 288syscall first appeared in Linux 3.0 and was added to 289.Ox 7.2 . 290