1.\" $OpenBSD: send.2,v 1.31 2014/09/09 06:32:37 guenther 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 2014 $ 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 166.Dv SO_BROADCAST 167option is not set on the socket, and a broadcast address 168was given as the destination. 169.It Bq Er EHOSTUNREACH 170The destination address specified an unreachable host. 171.It Bq Er EINVAL 172The 173.Fa flags 174parameter is invalid. 175.It Bq Er EHOSTDOWN 176The destination address specified a host that is down. 177.It Bq Er ENETDOWN 178The destination address specified a network that is down. 179.It Bq Er ECONNREFUSED 180The destination host rejected the message (or a previous one). 181This error can only be returned by connected sockets. 182.It Bq Er ENOPROTOOPT 183There was a problem sending the message. 184This error can only be returned by connected sockets. 185.It Bq Er EDESTADDRREQ 186The socket is not connected, and no destination address was specified. 187.It Bq Er EPIPE 188The socket is shut down for writing or not longer connected and the 189.Dv MSG_NOSIGNAL 190flag is set. 191.El 192.Pp 193In addition, 194.Fn send 195and 196.Fn sendto 197may return the following error: 198.Bl -tag -width Er 199.It Bq Er EINVAL 200.Fa len 201was larger than 202.Dv SSIZE_MAX . 203.El 204.Pp 205.Fn sendto 206and 207.Fn sendmsg 208may return the following errors: 209.Bl -tag -width Er 210.It Bq Er EAFNOSUPPORT 211Addresses in the specified address family cannot be used with this socket. 212.It Bq Er EISCONN 213The socket is already connected, and a destination address was specified. 214.El 215.Pp 216.Fn sendmsg 217may return the following errors: 218.Bl -tag -width Er 219.It Bq Er EINVAL 220The sum of the 221.Fa iov_len 222values in the 223.Fa msg_iov 224array overflowed an 225.Em ssize_t . 226.It Bq Er EMSGSIZE 227The 228.Fa msg_iovlen 229member of 230.Fa msg 231was less than 0 or larger than 232.Dv IOV_MAX . 233.It Bq Er EMFILE 234The message contains control information utilizing 235.Xr CMSG_DATA 3 236to pass file descriptors, but too many file descriptors 237are already in-flight. 238.El 239.Sh SEE ALSO 240.Xr fcntl 2 , 241.Xr getsockopt 2 , 242.Xr poll 2 , 243.Xr recv 2 , 244.Xr select 2 , 245.Xr socket 2 , 246.Xr write 2 , 247.Xr CMSG_DATA 3 248.Sh STANDARDS 249The 250.Fn send , 251.Fn sendto , 252and 253.Fn sendmsg 254functions conform to 255.St -p1003.1-2008 . 256The 257.Dv MSG_DONTWAIT 258and 259.Dv MSG_NOSIGNAL 260flags are extensions to that specification. 261.Sh HISTORY 262The 263.Fn send 264function call appeared in 265.Bx 4.2 . 266