1.\" $NetBSD: send.2,v 1.31 2013/07/14 14:29:09 njoly 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 June 22, 2012 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 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.Pp 77.Bd -literal 78struct mmsghdr { 79 struct msghdr msg_hdr; /* the message to be sent */ 80 unsigned int msg_len; /* number of bytes transmitted */ 81}; 82.Ed 83.Pp 84The 85.Fa msg_len 86member contains the number of bytes sent for each 87.Fa msg_hdr 88member. 89The array has 90.Fa vlen 91elements, which is limited to 92.Dv 1024 . 93If there is an error, a number fewer than 94.Fa vlen 95may be returned, and the error may be retrieved using 96.Xr getsockopt 2 97with 98.Dv SO_ERROR . 99.Pp 100The address of the target is given by 101.Fa to 102with 103.Fa tolen 104specifying its size. 105The length of the message is given by 106.Fa len . 107If the message is too long to pass atomically through the 108underlying protocol, the error 109.Er EMSGSIZE 110is returned, and 111the message is not transmitted. 112.Pp 113No indication of failure to deliver is implicit in a 114.Fn send . 115Locally detected errors are indicated by a return value of \-1. 116.Pp 117If no messages space is available at the socket to hold 118the message to be transmitted, then 119.Fn send 120normally blocks, unless the socket has been placed in 121non-blocking I/O mode. 122The 123.Xr select 2 124or 125.Xr poll 2 126call may be used to determine when it is possible to 127send more data. 128Unfortunately this does not work when the interface queue which is used to 129send the message is full, and the call returns 130.Er ENOBUFS . 131.Pp 132The 133.Fa flags 134parameter may include one or more of the following: 135.Bd -literal 136#define MSG_OOB 0x0001 /* process out-of-band data */ 137#define MSG_PEEK 0x0002 /* peek at incoming message */ 138#define MSG_DONTROUTE 0x0004 /* bypass routing, use direct interface */ 139#define MSG_EOR 0x0008 /* data completes record */ 140#define MSG_NOSIGNAL 0x0400 /* do not generate SIGPIPE on EOF */ 141.Ed 142.Pp 143The flag 144.Dv MSG_OOB 145is used to send 146.Dq out-of-band 147data on sockets that support this notion (e.g. 148.Dv SOCK_STREAM ) ; 149the underlying protocol must also support 150.Dq out-of-band 151data. 152.Dv MSG_EOR 153is used to indicate a record mark for protocols which support the 154concept. 155.\" .Dv MSG_EOF 156.\" requests that the sender side of a socket be shut down, and that an 157.\" appropriate indication be sent at the end of the specified data; 158.\" this flag is only implemented for 159.\" .Dv SOCK_STREAM 160.\" sockets in the 161.\" .Dv PF_INET 162.\" protocol family, and is used to implement Transaction 163.\" .Tn TCP 164.\" (see 165.\" .Xr ttcp 4 ) . 166.Dv MSG_DONTROUTE 167is usually used only by diagnostic or routing programs. 168.Pp 169See 170.Xr recv 2 171for a description of the 172.Fa msghdr 173structure. 174.Dv MSG_NOSIGNAL 175is used to prevent 176.Dv SIGPIPE 177generation when writing a socket that 178may be closed. 179.Sh RETURN VALUES 180The 181.Fn send , 182.Fn sendto , 183and 184.Fn sendmsg 185calls return the number of characters sent, or \-1 186if an error occurred. 187The 188.Fn sendmmsg 189call returns the number of messages sent, or \-1 190if an error occured. 191.Sh ERRORS 192.Fn send , 193.Fn sendto , 194.Fn sendmsg , 195and 196.Fn sendmmsg 197fail if: 198.Bl -tag -width Er 199.It Bq Er EACCES 200The SO_BROADCAST option is not set on the socket, and a broadcast address 201was given as the destination. 202.It Bq Er EAFNOSUPPORT 203Addresses in the specified address family cannot be used with this socket. 204.It Bq Er EAGAIN|EWOULDBLOCK 205The socket is marked non-blocking and the requested operation 206would block. 207.It Bq Er EBADF 208An invalid descriptor was specified. 209.It Bq Er EDSTADDRREQ 210In a non-connected socket a destination address has not been specified. 211.It Bq Er EFAULT 212An invalid user space address was specified for a parameter. 213.It Bq Er EHOSTDOWN 214The destination is a host on the local subnet and does not respond to 215.Xr arp 4 . 216.It Bq Er EHOSTUNREACH 217The destination for the message is unreachable. 218.It Bq Er EINVAL 219The total length of the I/O is more than can be expressed by the ssize_t 220return value. 221.It Bq Er EMSGSIZE 222The socket requires that message be sent atomically, 223and the size of the message to be sent made this impossible. 224.It Bq Er ENOBUFS 225The system was unable to allocate an internal buffer. 226The operation may succeed when buffers become available. 227.Pp 228An alternative reason: the output queue for a network interface was full. 229This generally indicates that the interface has stopped sending, 230but may be caused by transient congestion. 231.It Bq Er ENOTSOCK 232The argument 233.Fa s 234is not a socket. 235.It Bq Er EPIPE 236In a connected socket the connection has been broken. 237.El 238.Pp 239.Fn sendto 240will also fail if: 241.Bl -tag -width Er 242.It Bq Er EISCONN 243A destination address was specified and the socket is already connected. 244.El 245.Pp 246.Fn sendmsg 247and 248.Fn sendmmsg 249will also fail if: 250.Bl -tag -width Er 251.It Bq Er EMSGSIZE 252The 253.Fa msg_iovlen 254member of the 255.Fa msg 256structure is less than or equal to 0 257or is greater than 258.Brq Dv IOV_MAX . 259.El 260.Sh SEE ALSO 261.Xr fcntl 2 , 262.Xr getsockopt 2 , 263.Xr recv 2 , 264.Xr select 2 , 265.Xr socket 2 , 266.Xr write 2 267.Sh HISTORY 268The 269.Fn send 270function call appeared in 271.Bx 4.2 . 272The 273.Fn sendmmsg 274function call appeared in 275.Tn Linux 3.0 276and 277.Nx 7.0 . 278