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 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     From: @(#)send.2        8.2 (Berkeley) 2/21/94
  33 .\" $FreeBSD: src/lib/libc/sys/send.2,v 1.10.2.6 2001/12/14 18:34:01 ru Exp $
  34 .\"
  35 .Dd February 15, 1995
  36 .Dt SEND 2
  37 .Os
  38 .Sh NAME
  39 .Nm send ,
  40 .Nm sendto ,
  41 .Nm sendmsg
  42 .Nd send a message from a socket
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In sys/types.h
  47 .In sys/socket.h
  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 ,
  57 and
  58 .Fn sendmsg
  59 are used to transmit a message to another socket.
  60 .Fn Send
  61 may be used only when the socket is in a
  62 .Em connected
  63 state, while
  64 .Fn sendto
  65 and
  66 .Fn sendmsg
  67 may be used at any time.
  68 .Pp
  69 The address of the target is given by
  70 .Fa to
  71 with
  72 .Fa tolen
  73 specifying its size.
  74 The length of the message is given by
  75 .Fa len .
  76 If the message is too long to pass atomically through the
  77 underlying protocol, the error
  78 .Er EMSGSIZE
  79 is returned, and
  80 the message is not transmitted.
  81 .Pp
  82 No indication of failure to deliver is implicit in a
  83 .Fn send .
  84 Locally detected errors are indicated by a return value of -1.
  85 .Pp
  86 If no messages space is available at the socket to hold
  87 the message to be transmitted, then
  88 .Fn send
  89 normally blocks, unless the socket has been placed in
  90 non-blocking I/O mode.
  91 The
  92 .Xr select 2
  93 call may be used to determine when it is possible to
  94 send more data.
  95 .Pp
  96 The
  97 .Fa flags
  98 parameter may include one or more of the following:
  99 .Bd -literal
 100 #define MSG_OOB         0x1   /* process out-of-band data */
 101 #define MSG_PEEK        0x2   /* peek at incoming message */
 102 #define MSG_DONTROUTE   0x4   /* bypass routing, use direct interface */
 103 #define MSG_EOR         0x8   /* data completes record */
 104 #define MSG_EOF         0x100 /* data completes transaction */
 105 .Ed
 106 .Pp
 107 The flag
 108 .Dv MSG_OOB
 109 is used to send
 110 .Dq out-of-band
 111 data on sockets that support this notion (e.g.\&
 112 .Dv SOCK_STREAM ) ;
 113 the underlying protocol must also support
 114 .Dq out-of-band
 115 data.
 116 .Dv MSG_EOR
 117 is used to indicate a record mark for protocols which support the
 118 concept.
 119 .Dv MSG_EOF
 120 requests that the sender side of a socket be shut down, and that an
 121 appropriate indication be sent at the end of the specified data;
 122 this flag is only implemented for
 123 .Dv SOCK_STREAM
 124 sockets in the
 125 .Dv PF_INET
 126 protocol family, and is used to implement Transaction
 127 .Tn TCP
 128 (see
 129 .Xr ttcp 4 ) .
 130 .Dv MSG_DONTROUTE
 131 is usually used only by diagnostic or routing programs.
 132 .Pp
 133 See
 134 .Xr recv 2
 135 for a description of the
 136 .Fa msghdr
 137 structure.
 138 .Sh RETURN VALUES
 139 The call returns the number of characters sent, or -1
 140 if an error occurred.
 141 .Sh ERRORS
 142 .Fn Send ,
 143 .Fn sendto ,
 144 and
 145 .Fn sendmsg
 146 fail if:
 147 .Bl -tag -width Er
 148 .It Bq Er EBADF
 149 An invalid descriptor was specified.
 150 .It Bq Er EACCES
 151 The destination address is a broadcast address, and
 152 .Dv SO_BROADCAST
 153 has not been set on the socket.
 154 .It Bq Er ENOTSOCK
 155 The argument
 156 .Fa s
 157 is not a socket.
 158 .It Bq Er EFAULT
 159 An invalid user space address was specified for a parameter.
 160 .It Bq Er EMSGSIZE
 161 The socket requires that message be sent atomically,
 162 and the size of the message to be sent made this impossible.
 163 .It Bq Er EAGAIN
 164 The socket is marked non-blocking and the requested operation
 165 would block.
 166 .It Bq Er ENOBUFS
 167 The system was unable to allocate an internal buffer.
 168 The operation may succeed when buffers become available.
 169 .It Bq Er ENOBUFS
 170 The output queue for a network interface was full.
 171 This generally indicates that the interface has stopped sending,
 172 but may be caused by transient congestion.
 173 .It Bq Er EHOSTUNREACH
 174 The remote host was unreachable.
 175 .It Bq Er ECONNREFUSED
 176 The socket received an ICMP destination unreachable message
 177 from the last message sent.  This typically means that the
 178 receiver is not listening on the remote port.
 179 .It Bq Er EHOSTDOWN
 180 The remote host was down.
 181 .El
 182 .Sh BUGS
 183 Because
 184 .Fn sendmsg
 185 doesn't necessarily block until the data has been transferred, it
 186 is possible to transfer an open file descriptor across an
 187 .Dv AF_UNIX
 188 domain socket
 189 (see
 190 .Xr recv 2 ) ,
 191 then
 192 .Fn close
 193 it before it has actually been sent, the result being that the receiver
 194 gets a closed file descriptor.  It is left to the application to
 195 implement an acknowlegment mechanism to prevent this from happening.
 196 .Sh SEE ALSO
 197 .Xr fcntl 2 ,
 198 .Xr getsockopt 2 ,
 199 .Xr recv 2 ,
 200 .Xr select 2 ,
 201 .Xr socket 2 ,
 202 .Xr write 2
 203 .Sh HISTORY
 204 The
 205 .Fn send
 206 function call appeared in
 207 .Bx 4.2 .