1.\" $NetBSD: send.2,v 1.19 2002/02/08 01:28:21 ross 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 October 16, 2001 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 \*[Lt]sys/socket.h\*[Gt] 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 95call 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 SO_BROADCAST option is not set on the socket, and a broadcast address 156was given as the destination. 157.It Bq Er EHOSTUNREACH 158The destination for the message is unreachable. 159.It Bq Er EINVAL 160The total length of the I/O is more than can be expressed by the ssize_t 161return value. 162.It Bq Er EAFNOSUPPORT 163Addresses in the specified address family cannot be used with this socket. 164.El 165.Pp 166.Fn sendmsg 167will also fail if: 168.Bl -tag -width Er 169.It Bq Er EMSGSIZE 170The 171.Fa msg_iovlen 172member of the 173.Fa msg 174structure is less than or equal to 0 175or is greater than 176.Dv {IOV_MAX} . 177.El 178.Sh SEE ALSO 179.Xr fcntl 2 , 180.Xr getsockopt 2 , 181.Xr recv 2 , 182.Xr select 2 , 183.Xr socket 2 , 184.Xr write 2 185.Sh HISTORY 186The 187.Fn send 188function call appeared in 189.Bx 4.2 . 190