1.\" $OpenBSD: send.2,v 1.19 2000/10/18 05:12:11 aaron 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. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)send.2 8.2 (Berkeley) 2/21/94 36.\" 37.Dd July 28, 1998 38.Dt SEND 2 39.Os 40.Sh NAME 41.Nm send , 42.Nm sendto , 43.Nm sendmsg 44.Nd send a message from a socket 45.Sh SYNOPSIS 46.Fd #include <sys/types.h> 47.Fd #include <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 55.Fn send , 56.Fn sendto , 57and 58.Fn sendmsg 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 65and 66.Fn sendmsg 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.Bd -literal 102#define MSG_OOB 0x1 /* process out-of-band data */ 103#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */ 104.Ed 105.Pp 106The flag 107.Dv MSG_OOB 108is used to send 109.Dq out-of-band 110data on sockets that support this notion (e.g., 111.Dv SOCK_STREAM ) ; 112the underlying protocol must also support 113.Dq out-of-band 114data. 115.Dv MSG_DONTROUTE 116is usually used only by diagnostic or routing programs. 117.Pp 118See 119.Xr recv 2 120for a description of the 121.Fa msghdr 122structure. 123.Sh RETURN VALUES 124The call returns the number of characters sent, or \-1 125if an error occurred. 126.Sh ERRORS 127.Fn send , 128.Fn sendto , 129and 130.Fn sendmsg 131fail if: 132.Bl -tag -width Er 133.It Bq Er EBADF 134An invalid descriptor was specified. 135.It Bq Er ENOTSOCK 136The argument 137.Fa s 138is not a socket. 139.It Bq Er EFAULT 140An invalid user space address was specified for a parameter. 141.It Bq Er EMSGSIZE 142The socket requires that message be sent atomically, 143and the size of the message to be sent made this impossible. 144.It Bq Er EAGAIN 145The socket is marked non-blocking and the requested operation 146would block. 147.It Bq Er ENOBUFS 148The system was unable to allocate an internal buffer. 149The operation may succeed when buffers become available. 150.It Bq Er ENOBUFS 151The output queue for a network interface was full. 152This generally indicates that the interface has stopped sending, 153but may be caused by transient congestion. 154.It Bq Er EACCES 155The 156.Dv SO_BROADCAST 157option is not set on the socket, and a broadcast address 158was given as the destination. 159.It Bq Er EHOSTUNREACH 160The destination address specified an unreachable host. 161.It Bq Er EINVAL 162The 163.Fa flags 164parameter is invalid. 165.It Bq Er EHOSTDOWN 166The destination address specified a host that is down. 167.It Bq Er ENETDOWN 168The destination address specified a network that is down. 169.It Bq Er ECONNREFUSED 170The destination host rejected the message (or a previous one). 171This error can only be returned by connected sockets. 172.It Bq Er ENOPROTOOPT 173There was a problem sending the message. 174This error can only be returned by connected sockets. 175.It Bq Er EDESTADDRREQ 176The socket is not connected, and no destination address was specified. 177.It Bq Er EISCONN 178The socket is already connected, and a destination address was specified. 179.El 180.Pp 181In addition, 182.Fn send 183and 184.Fn sendto 185may return the following error: 186.Bl -tag -width Er 187.It Bq Er EINVAL 188.Fa len 189was larger than 190.Dv SSIZE_MAX . 191.El 192.Pp 193Also, 194.Fn sendmsg 195may return the following errors: 196.Bl -tag -width Er 197.It Bq Er EINVAL 198The sum of the 199.Fa iov_len 200values in the 201.Fa msg_iov 202array overflowed an 203.Em ssize_t . 204.It Bq Er EMSGSIZE 205The 206.Fa msg_iovlen 207member of 208.Fa msg 209was less than 0 or larger than 210.Dv IOV_MAX . 211.It Bq Er EAFNOSUPPORT 212Addresses in the specified address family cannot be used with this socket. 213.El 214.Sh SEE ALSO 215.Xr fcntl 2 , 216.Xr getsockopt 2 , 217.Xr poll 2 , 218.Xr recv 2 , 219.Xr select 2 , 220.Xr poll 2 , 221.Xr socket 2 , 222.Xr write 2 223.Sh HISTORY 224The 225.Fn send 226function call appeared in 227.Bx 4.2 . 228