1.\" $NetBSD: send.2,v 1.6 1996/01/15 01:17:18 thorpej 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)send.2 8.2 (Berkeley) 2/21/94 35.\" 36.Dd February 21, 1994 37.Dt SEND 2 38.Os BSD 4.2 39.Sh NAME 40.Nm send , 41.Nm sendmsg , 42.Nm sendto 43.Nd send a message from a socket 44.Sh SYNOPSIS 45.Fd #include <sys/socket.h> 46.Ft ssize_t 47.Fo send 48.Fa "int socket" 49.Fa "const void *buffer" 50.Fa "size_t length" 51.Fa "int flags" 52.Fc 53.Ft ssize_t 54.Fo sendmsg 55.Fa "int socket" 56.Fa "const struct msghdr *message" 57.Fa "int flags" 58.Fc 59.Ft ssize_t 60.Fo sendto 61.Fa "int socket" 62.Fa "const void *buffer" 63.Fa "size_t length" 64.Fa "int flags" 65.Fa "const struct sockaddr *dest_addr" 66.Fa "socklen_t dest_len" 67.Fc 68.Sh DESCRIPTION 69.Fn send , 70.Fn sendto , 71and 72.Fn sendmsg 73are used to transmit a message to another socket. 74.Fn send 75may be used only when the socket is in a 76.Em connected 77state, while 78.Fn sendto 79and 80.Fn sendmsg 81may be used at any time. 82.Pp 83The address of the target is given by 84.Fa dest_addr 85with 86.Fa dest_len 87specifying its size. 88The length of the message is given by 89.Fa length . 90If the message is too long to pass atomically through the 91underlying protocol, the error 92.Er EMSGSIZE 93is returned, and 94the message is not transmitted. 95.Pp 96No indication of failure to deliver is implicit in a 97.Fn send . 98Locally detected errors are indicated by a return value of -1. 99.Pp 100If no messages space is available at the socket to hold 101the message to be transmitted, then 102.Fn send 103normally blocks, unless the socket has been placed in 104non-blocking I/O mode. 105The 106.Xr select 2 107call may be used to determine when it is possible to 108send more data. 109.Pp 110The 111.Fa flags 112parameter may include one or more of the following: 113.Bd -literal 114#define MSG_OOB 0x1 /* process out-of-band data */ 115#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */ 116.Ed 117.Pp 118The flag 119.Dv MSG_OOB 120is used to send 121.Dq out-of-band 122data on sockets that support this notion (e.g. 123.Dv SOCK_STREAM ) ; 124the underlying protocol must also support 125.Dq out-of-band 126data. 127.Dv MSG_DONTROUTE 128is usually used only by diagnostic or routing programs. 129.Pp 130The 131.Fn sendmsg 132system call uses a 133.Fa msghdr 134structure to minimize the number of directly supplied arguments. 135The 136.Fa msg_iov 137and 138.Fa msg_iovlen 139fields of message specify zero or more buffers 140containing the data to be sent. 141.Fa msg_iov 142points to an array of iovec structures; 143.Fa msg_iovlen 144shall be set to the dimension of this array. 145In each iovec structure, the 146.Fa iov_base 147field specifies a storage area and 148the 149.Fa iov_len 150field gives its size in bytes. Some of these sizes can be zero. 151The data from each storage area indicated by 152.Fa msg_iov 153is sent in turn. 154See 155.Xr recv 2 156for a complete description of the 157.Fa msghdr 158structure. 159.Sh RETURN VALUES 160Upon successful completion, 161the number of bytes which were sent is returned. 162Otherwise, -1 is returned and the global variable 163.Va errno 164is set to indicate the error. 165.Sh ERRORS 166The 167.Fn send , 168.Fn sendmsg , 169and 170.Fn sendto 171system calls will fail if: 172.Bl -tag -width Er 173.\" =========== 174.It Bq Er EACCES 175The SO_BROADCAST option is not set on the socket 176and a broadcast address is given as the destination. 177.\" =========== 178.It Bq Er EAGAIN 179The socket is marked non-blocking 180and the requested operation would block. 181.\" =========== 182.It Bq Er EBADF 183An invalid descriptor is specified. 184.\" =========== 185.It Bq Er ECONNRESET 186A connection is forcibly closed by a peer. 187.\" =========== 188.It Bq Er EFAULT 189An invalid user space address is specified for a parameter. 190.\" =========== 191.It Bq Er EHOSTUNREACH 192The destination address specifies an unreachable host. 193.\" =========== 194.It Bq Er EINTR 195A signal interrupts the system call 196before any data is transmitted. 197.\" =========== 198.It Bq Er EMSGSIZE 199The socket requires that message be sent atomically, 200and the size of the message to be sent makes this impossible. 201.Dv IOV_MAX . 202.\" =========== 203.It Bq Er ENETDOWN 204The local network interface used to reach the destination is down. 205.\" =========== 206.It Bq Er ENETUNREACH 207No route to the network is present. 208.\" =========== 209.It Bq Er ENOBUFS 210The system is unable to allocate an internal buffer. 211The operation may succeed when buffers become available. 212.\" =========== 213.It Bq Er ENOBUFS 214The output queue for a network interface is full. 215This generally indicates that the interface has stopped sending, 216but may be caused by transient congestion. 217.\" =========== 218.It Bq Er ENOTSOCK 219The argument 220.Fa socket 221is not a socket. 222.\" =========== 223.It Bq Er EOPNOTSUPP 224.Fa socket 225does not support (some of) the option(s) specified in 226.Fa flags . 227.\" =========== 228.It Bq Er EPIPE 229The socket is shut down for writing 230or the socket is connection-mode and is no longer connected. 231In the latter case, and if the socket is of type SOCK_STREAM, 232the SIGPIPE signal is generated to the calling thread. 233.\" ========== 234.It Bq Er EADDRNOTAVAIL 235The specified address is not available or no longer available on this machine. 236.El 237.Pp 238The 239.Fn sendmsg 240and 241.Fn sendto 242system calls will fail if: 243.Bl -tag -width Er 244.\" =========== 245.It Bq Er EAFNOSUPPORT 246Addresses in the specified address family cannot be used 247with this socket. 248.\" =========== 249.It Bq Er EDESTADDRREQ 250The socket is not connection-mode and does not have its peer address set, 251and no destination address is specified. 252.\" =========== 253.It Bq Er EISCONN 254A destination address was specified and the socket is already connected. 255.\" =========== 256.It Bq Er ENOENT 257A component of the pathname does not name an existing file 258or the path name is an empty string. 259.\" =========== 260.It Bq Er ENOMEM 261Insufficient memory is available to fulfill the request. 262.\" =========== 263.It Bq Er ENOTCONN 264The socket is connection-mode, but is not connected. 265.\" =========== 266.It Bq Er ENOTDIR 267A component of the path prefix of the pathname in the socket address 268is not a directory. 269.El 270.Pp 271The 272.Fn send 273system call will fail if: 274.Bl -tag -width Er 275.\" =========== 276.It Bq Er EDESTADDRREQ 277The socket is not connection-mode and no peer address is set. 278.\" =========== 279.It Bq Er ENOTCONN 280The socket is not connected or otherwise has not had the peer pre-specified. 281.El 282.Pp 283The 284.Fn sendmsg 285system call will fail if: 286.Bl -tag -width Er 287.\" =========== 288.It Bq Er EINVAL 289The sum of the iov_len values overflows an ssize_t. 290.\" =========== 291.It Bq Er EMSGSIZE 292The socket requires that message be sent atomically, 293and the size of the message to be sent makes this impossible, 294or the msg_iovlen member of the msghdr structure pointed to by message 295is less than or equal to 0 or is greater than 296.Dv IOV_MAX . 297.El 298.Sh LEGACY SYNOPSIS 299.Fd #include <sys/types.h> 300.Fd #include <sys/socket.h> 301.Pp 302The include file 303.In sys/types.h is necessary. 304.Sh SEE ALSO 305.Xr fcntl 2 , 306.Xr getsockopt 2 , 307.Xr recv 2 , 308.Xr select 2 , 309.Xr socket 2 , 310.Xr write 2 , 311.Xr compat 5 312.Sh HISTORY 313The 314.Fn send 315function call appeared in 316.Bx 4.2 . 317