1.\" $NetBSD: send.2,v 1.15 1999/12/02 21:42:39 kleink 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 39.Sh NAME 40.Nm send , 41.Nm sendto , 42.Nm sendmsg 43.Nd send a message from a socket 44.Sh LIBRARY 45.Lb libc 46.Sh SYNOPSIS 47.Fd #include <sys/types.h> 48.Fd #include <sys/socket.h> 49.Ft ssize_t 50.Fn send "int s" "const void *msg" "size_t len" "int flags" 51.Ft ssize_t 52.Fn sendto "int s" "const void *msg" "size_t len" "int flags" "const struct sockaddr *to" "socklen_t tolen" 53.Ft ssize_t 54.Fn sendmsg "int s" "const struct msghdr *msg" "int flags" 55.Sh DESCRIPTION 56.Fn send , 57.Fn sendto , 58and 59.Fn sendmsg 60are used to transmit a message to another socket. 61.Fn send 62may be used only when the socket is in a 63.Em connected 64state, while 65.Fn sendto 66and 67.Fn sendmsg 68may be used at any time. 69.Pp 70The address of the target is given by 71.Fa to 72with 73.Fa tolen 74specifying its size. 75The length of the message is given by 76.Fa len . 77If the message is too long to pass atomically through the 78underlying protocol, the error 79.Er EMSGSIZE 80is returned, and 81the message is not transmitted. 82.Pp 83No indication of failure to deliver is implicit in a 84.Fn send . 85Locally detected errors are indicated by a return value of -1. 86.Pp 87If no messages space is available at the socket to hold 88the message to be transmitted, then 89.Fn send 90normally blocks, unless the socket has been placed in 91non-blocking I/O mode. 92The 93.Xr select 2 94or 95.Xr poll 2 96call may be used to determine when it is possible to 97send more data. 98.Pp 99The 100.Fa flags 101parameter may include one or more of the following: 102.Bd -literal 103#define MSG_OOB 0x1 /* process out-of-band data */ 104#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */ 105.Ed 106.Pp 107The flag 108.Dv MSG_OOB 109is used to send 110.Dq out-of-band 111data on sockets that support this notion (e.g. 112.Dv SOCK_STREAM ) ; 113the underlying protocol must also support 114.Dq out-of-band 115data. 116.Dv MSG_DONTROUTE 117is usually used only by diagnostic or routing programs. 118.Pp 119See 120.Xr recv 2 121for a description of the 122.Fa msghdr 123structure. 124.Sh RETURN VALUES 125The call returns the number of characters sent, or -1 126if an error occurred. 127.Sh ERRORS 128.Fn send , 129.Fn sendto , 130and 131.Fn sendmsg 132fail if: 133.Bl -tag -width Er 134.It Bq Er EBADF 135An invalid descriptor was specified. 136.It Bq Er ENOTSOCK 137The argument 138.Fa s 139is not a socket. 140.It Bq Er EFAULT 141An invalid user space address was specified for a parameter. 142.It Bq Er EMSGSIZE 143The socket requires that message be sent atomically, 144and the size of the message to be sent made this impossible. 145.It Bq Er EAGAIN 146The socket is marked non-blocking and the requested operation 147would block. 148.It Bq Er ENOBUFS 149The system was unable to allocate an internal buffer. 150The operation may succeed when buffers become available. 151.It Bq Er ENOBUFS 152The output queue for a network interface was full. 153This generally indicates that the interface has stopped sending, 154but may be caused by transient congestion. 155.It Bq Er EACCES 156The SO_BROADCAST option is not set on the socket, and a broadcast address 157was given as the destination. 158.It Bq Er EHOSTUNREACH 159The destination for the message is unreachable. 160.It Bq Er EINVAL 161The total length of the I/O is more than can be expressed by the ssize_t 162return value. 163.It Bq Er EAFNOSUPPORT 164Addresses in the specified address family cannot be used with this socket. 165.El 166.Pp 167.Fn sendmsg 168will also fail if: 169.Bl -tag -width Er 170.It Bq Er EMSGSIZE 171The 172.Fa msg_iovlen 173member of the 174.Fa msg 175structure is less than or equal to 0 176or is greater than 177.Dv {IOV_MAX} . 178.El 179.Sh SEE ALSO 180.Xr fcntl 2 , 181.Xr recv 2 , 182.Xr select 2 , 183.Xr getsockopt 2 , 184.Xr socket 2 , 185.Xr write 2 186.Sh HISTORY 187The 188.Fn send 189function call appeared in 190.Bx 4.2 . 191