1.\" $NetBSD: send.2,v 1.34 2021/12/10 20:36:02 andvar Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)send.2 8.2 (Berkeley) 2/21/94 31.\" 32.Dd March 27, 2021 33.Dt SEND 2 34.Os 35.Sh NAME 36.Nm send , 37.Nm sendto , 38.Nm sendmsg , 39.Nm sendmmsg 40.Nd send a message from a socket 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In sys/socket.h 45.Ft ssize_t 46.Fn send "int s" "const void *msg" "size_t len" "int flags" 47.Ft ssize_t 48.Fn sendto "int s" "const void *msg" "size_t len" "int flags" "const struct sockaddr *to" "socklen_t tolen" 49.Ft ssize_t 50.Fn sendmsg "int s" "const struct msghdr *msg" "int flags" 51.Ft int 52.Fn sendmmsg "int s" "struct mmsghdr *mmsg" "unsigned int vlen" "unsigned int flags" 53.Sh DESCRIPTION 54.Fn send , 55.Fn sendto , 56.Fn sendmsg , 57and 58.Fn sendmmsg 59are used to transmit a message to another socket. 60.Fn send 61may be used only when the socket is in a 62.Em connected 63state, while 64.Fn sendto , 65.Fn sendmsg 66and 67.Fn sendmmsg 68may be used at any time. 69.Pp 70The 71.Fn sendmmsg 72call can be used to send multiple messages in the same call using an array of 73.Fa mmsghdr 74elements with the following form, as defined in 75.Ao Pa sys/socket.h Ac : 76.Bd -literal 77struct mmsghdr { 78 struct msghdr msg_hdr; /* the message to be sent */ 79 unsigned int msg_len; /* number of bytes transmitted */ 80}; 81.Ed 82.Pp 83The 84.Fa msg_len 85member contains the number of bytes sent for each 86.Fa msg_hdr 87member. 88The array has 89.Fa vlen 90elements, which is limited to 91.Dv 1024 . 92If there is an error, a number fewer than 93.Fa vlen 94may be returned, and the error may be retrieved using 95.Xr getsockopt 2 96with 97.Dv SO_ERROR . 98.Pp 99The address of the target is given by 100.Fa to , 101with 102.Fa tolen 103specifying its size. 104The length of the message is given by 105.Fa len . 106If the message is too long to pass atomically through the 107underlying protocol, the error 108.Er EMSGSIZE 109is returned, and 110the message is not transmitted. 111.Pp 112No indication of failure to deliver is implicit in a 113.Fn send . 114Locally detected errors are indicated by a return value of \-1. 115.Pp 116If no messages space is available at the socket to hold 117the message to be transmitted, then 118.Fn send 119normally blocks, unless the socket has been placed in 120non-blocking I/O mode. 121The 122.Xr select 2 123or 124.Xr poll 2 125call may be used to determine when it is possible to 126send more data. 127Unfortunately this does not work when the interface queue which is used to 128send the message is full, and the call returns 129.Er ENOBUFS . 130.Pp 131The 132.Fa flags 133parameter may include one or more of the following: 134.Bd -literal 135#define MSG_OOB 0x0001 /* process out-of-band data */ 136#define MSG_PEEK 0x0002 /* peek at incoming message */ 137#define MSG_DONTROUTE 0x0004 /* bypass routing, use direct interface */ 138#define MSG_EOR 0x0008 /* data completes record */ 139#define MSG_NOSIGNAL 0x0400 /* do not generate SIGPIPE on EOF */ 140.Ed 141.Pp 142The flag 143.Dv MSG_OOB 144is used to send 145.Dq out-of-band 146data on sockets that support this notion (e.g. 147.Dv SOCK_STREAM ) ; 148the underlying protocol must also support 149.Dq out-of-band 150data. 151.Dv MSG_EOR 152is used to indicate a record mark for protocols which support the 153concept. 154.\" .Dv MSG_EOF 155.\" requests that the sender side of a socket be shut down, and that an 156.\" appropriate indication be sent at the end of the specified data; 157.\" this flag is only implemented for 158.\" .Dv SOCK_STREAM 159.\" sockets in the 160.\" .Dv PF_INET 161.\" protocol family, and is used to implement Transaction 162.\" .Tn TCP 163.\" (see 164.\" .Xr ttcp 4 ) . 165.Dv MSG_DONTROUTE 166is usually used only by diagnostic or routing programs. 167.Pp 168See 169.Xr recv 2 170for a description of the 171.Fa msghdr 172structure. 173.Dv MSG_NOSIGNAL 174is used to prevent 175.Dv SIGPIPE 176generation when writing a socket that 177may be closed. 178.Sh RETURN VALUES 179The 180.Fn send , 181.Fn sendto , 182and 183.Fn sendmsg 184calls return the number of characters sent, or \-1 185if an error occurred. 186The 187.Fn sendmmsg 188call returns the number of messages sent, or \-1 189if an error occurred. 190.Sh ERRORS 191.Fn send , 192.Fn sendto , 193.Fn sendmsg , 194and 195.Fn sendmmsg 196fail if: 197.Bl -tag -width Er 198.It Bq Er EACCES 199The SO_BROADCAST option is not set on the socket, and a broadcast address 200was given as the destination. 201.It Bq Er EAFNOSUPPORT 202Addresses in the specified address family cannot be used with this socket. 203.It Bq Er EAGAIN|EWOULDBLOCK 204The socket is marked non-blocking and the requested operation 205would block. 206.It Bq Er EBADF 207An invalid descriptor was specified. 208.It Bq Er EDSTADDRREQ 209In a non-connected socket a destination address has not been specified. 210.It Bq Er EFAULT 211An invalid user space address was specified for a parameter. 212.It Bq Er EHOSTDOWN 213The destination is a host on the local subnet and does not respond to 214.Xr arp 4 . 215.It Bq Er EHOSTUNREACH 216The destination for the message is unreachable. 217.It Bq Er EINVAL 218The total length of the I/O is more than can be expressed by the ssize_t 219return value. 220.It Bq Er EINVAL 221The socket address length passed was outside the allowable range. 222.It Bq Er EMSGSIZE 223The socket requires that message be sent atomically, 224and the size of the message to be sent made this impossible. 225.It Bq Er ENOBUFS 226The system was unable to allocate an internal buffer. 227The operation may succeed when buffers become available. 228.Pp 229An alternative reason: the output queue for a network interface was full. 230This generally indicates that the interface has stopped sending, 231but may be caused by transient congestion. 232.It Bq Er ENOTSOCK 233The argument 234.Fa s 235is not a socket. 236.It Bq Er EPIPE 237In a connected socket the connection has been broken. 238.El 239.Pp 240.Fn sendto 241will also fail if: 242.Bl -tag -width Er 243.It Bq Er EISCONN 244A destination address was specified and the socket is already connected. 245.El 246.Pp 247.Fn sendmsg 248and 249.Fn sendmmsg 250will also fail if: 251.Bl -tag -width Er 252.It Bq Er EMSGSIZE 253The 254.Fa msg_iovlen 255member of the 256.Fa msg 257structure is less than or equal to 0 258or is greater than 259.Brq Dv IOV_MAX . 260.El 261.Sh SEE ALSO 262.Xr fcntl 2 , 263.Xr getsockopt 2 , 264.Xr recv 2 , 265.Xr select 2 , 266.Xr socket 2 , 267.Xr write 2 268.Sh HISTORY 269The 270.Fn send 271function call appeared in 272.Bx 4.2 . 273The 274.Fn sendmmsg 275function call appeared in 276.Tn Linux 3.0 277and 278.Nx 7.0 . 279