bsd/man/man2/send.2

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