lib/libc/sys/send.2

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     From: @(#)send.2        8.2 (Berkeley) 2/21/94
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd February 5, 2009
  32 .Dt SEND 2
  33 .Os
  34 .Sh NAME
  35 .Nm send ,
  36 .Nm sendto ,
  37 .Nm sendmsg
  38 .Nd send a message from a socket
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In sys/types.h
  43 .In sys/socket.h
  44 .Ft ssize_t
  45 .Fn send "int s" "const void *msg" "size_t len" "int flags"
  46 .Ft ssize_t
  47 .Fn sendto "int s" "const void *msg" "size_t len" "int flags" "const struct sockaddr *to" "socklen_t tolen"
  48 .Ft ssize_t
  49 .Fn sendmsg "int s" "const struct msghdr *msg" "int flags"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn send
  53 function,
  54 and
  55 .Fn sendto
  56 and
  57 .Fn sendmsg
  58 system calls
  59 are used to transmit a message to another socket.
  60 The
  61 .Fn send
  62 function
  63 may be used only when the socket is in a
  64 .Em connected
  65 state, while
  66 .Fn sendto
  67 and
  68 .Fn sendmsg
  69 may be used at any time.
  70 .Pp
  71 The address of the target is given by
  72 .Fa to
  73 with
  74 .Fa tolen
  75 specifying its size.
  76 The length of the message is given by
  77 .Fa len .
  78 If the message is too long to pass atomically through the
  79 underlying protocol, the error
  80 .Er EMSGSIZE
  81 is returned, and
  82 the message is not transmitted.
  83 .Pp
  84 No indication of failure to deliver is implicit in a
  85 .Fn send .
  86 Locally detected errors are indicated by a return value of -1.
  87 .Pp
  88 If no messages space is available at the socket to hold
  89 the message to be transmitted, then
  90 .Fn send
  91 normally blocks, unless the socket has been placed in
  92 non-blocking I/O mode.
  93 The
  94 .Xr select 2
  95 system call may be used to determine when it is possible to
  96 send more data.
  97 .Pp
  98 The
  99 .Fa flags
 100 argument may include one or more of the following:
 101 .Bd -literal
 102 #define MSG_OOB         0x00001 /* process out-of-band data */
 103 #define MSG_DONTROUTE   0x00004 /* bypass routing, use direct interface */
 104 #define MSG_EOR         0x00008 /* data completes record */
 105 #define MSG_EOF         0x00100 /* data completes transaction */
 106 #define MSG_NOSIGNAL    0x20000 /* do not generate SIGPIPE on EOF */
 107 .Ed
 108 .Pp
 109 The flag
 110 .Dv MSG_OOB
 111 is used to send
 112 .Dq out-of-band
 113 data on sockets that support this notion (e.g.\&
 114 .Dv SOCK_STREAM ) ;
 115 the underlying protocol must also support
 116 .Dq out-of-band
 117 data.
 118 .Dv MSG_EOR
 119 is used to indicate a record mark for protocols which support the
 120 concept.
 121 .Dv MSG_EOF
 122 requests that the sender side of a socket be shut down, and that an
 123 appropriate indication be sent at the end of the specified data;
 124 this flag is only implemented for
 125 .Dv SOCK_STREAM
 126 sockets in the
 127 .Dv PF_INET
 128 protocol family.
 129 .Dv MSG_DONTROUTE
 130 is usually used only by diagnostic or routing programs.
 131 .Dv MSG_NOSIGNAL
 132 is used to prevent
 133 .Dv SIGPIPE
 134 generation when writing a socket that
 135 may be closed.
 136 .Pp
 137 See
 138 .Xr recv 2
 139 for a description of the
 140 .Fa msghdr
 141 structure.
 142 .Sh RETURN VALUES
 143 The call returns the number of characters sent, or -1
 144 if an error occurred.
 145 .Sh ERRORS
 146 The
 147 .Fn send
 148 function and
 149 .Fn sendto
 150 and
 151 .Fn sendmsg
 152 system calls
 153 fail if:
 154 .Bl -tag -width Er
 155 .It Bq Er EBADF
 156 An invalid descriptor was specified.
 157 .It Bq Er EACCES
 158 The destination address is a broadcast address, and
 159 .Dv SO_BROADCAST
 160 has not been set on the socket.
 161 .It Bq Er ENOTSOCK
 162 The argument
 163 .Fa s
 164 is not a socket.
 165 .It Bq Er EFAULT
 166 An invalid user space address was specified for an argument.
 167 .It Bq Er EMSGSIZE
 168 The socket requires that message be sent atomically,
 169 and the size of the message to be sent made this impossible.
 170 .It Bq Er EAGAIN
 171 The socket is marked non-blocking and the requested operation
 172 would block.
 173 .It Bq Er ENOBUFS
 174 The system was unable to allocate an internal buffer.
 175 The operation may succeed when buffers become available.
 176 .It Bq Er ENOBUFS
 177 The output queue for a network interface was full.
 178 This generally indicates that the interface has stopped sending,
 179 but may be caused by transient congestion.
 180 .It Bq Er EHOSTUNREACH
 181 The remote host was unreachable.
 182 .It Bq Er EISCONN
 183 A destination address was specified and the socket is already connected.
 184 .It Bq Er ECONNREFUSED
 185 The socket received an ICMP destination unreachable message
 186 from the last message sent.
 187 This typically means that the
 188 receiver is not listening on the remote port.
 189 .It Bq Er EHOSTDOWN
 190 The remote host was down.
 191 .It Bq Er ENETDOWN
 192 The remote network was down.
 193 .It Bq Er EADDRNOTAVAIL
 194 The process using a
 195 .Dv SOCK_RAW
 196 socket was jailed and the source
 197 address specified in the IP header did not match the IP
 198 address bound to the prison.
 199 .It Bq Er EPIPE
 200 The socket is unable to send anymore data
 201 .Dv ( SBS_CANTSENDMORE
 202 has been set on the socket).
 203 This typically means that the socket
 204 is not connected.
 205 .El
 206 .Sh SEE ALSO
 207 .Xr fcntl 2 ,
 208 .Xr getsockopt 2 ,
 209 .Xr recv 2 ,
 210 .Xr select 2 ,
 211 .Xr socket 2 ,
 212 .Xr write 2
 213 .Sh HISTORY
 214 The
 215 .Fn send
 216 function appeared in
 217 .Bx 4.2 .
 218 .Sh BUGS
 219 Because
 220 .Fn sendmsg
 221 does not necessarily block until the data has been transferred, it
 222 is possible to transfer an open file descriptor across an
 223 .Dv AF_UNIX
 224 domain socket
 225 (see
 226 .Xr recv 2 ) ,
 227 then
 228 .Fn close
 229 it before it has actually been sent, the result being that the receiver
 230 gets a closed file descriptor.
 231 It is left to the application to
 232 implement an acknowledgment mechanism to prevent this from happening.