usr/src/man/man3xnet/send.3xnet

   1 '\" te
   2 .\" Copyright (c) 1992, X/Open Company Limited  All Rights Reserved.  Portions Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   4 .\" http://www.opengroup.org/bookstore/.
   5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   6 .\"  This notice shall appear on any product containing this material.
   7 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   9 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  10 .TH SEND 3XNET "Dec 3, 2014"
  11 .SH NAME
  12 send \- send a message on a socket
  13 .SH SYNOPSIS
  14 .LP
  15 .nf
  16 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ]
  17 #include <sys/socket.h>
  18
  19 \fBssize_t\fR \fBsend\fR(\fBint\fR \fIsocket\fR, \fBconst void *\fR\fIbuffer\fR, \fBsize_t\fR \fIlength\fR, \fBint flags\fR);
  20 .fi
  21
  22 .SH PARAMETERS
  23 .ne 2
  24 .na
  25 \fB\fIsocket\fR\fR
  26 .ad
  27 .RS 10n
  28 Specifies the socket file descriptor.
  29 .RE
  30
  31 .sp
  32 .ne 2
  33 .na
  34 \fB\fIbuffer\fR\fR
  35 .ad
  36 .RS 10n
  37 Points to the buffer containing the message to send.
  38 .RE
  39
  40 .sp
  41 .ne 2
  42 .na
  43 \fB\fIlength\fR\fR
  44 .ad
  45 .RS 10n
  46 Specifies the length of the message in bytes.
  47 .RE
  48
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fIflags\fR\fR
  53 .ad
  54 .RS 10n
  55 Specifies the type of message transmission. Values of this argument are formed
  56 by logically OR'ing zero or more of the following flags:
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fBMSG_EOR\fR\fR
  61 .ad
  62 .RS 11n
  63 Terminates a record (if supported by the protocol)
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fBMSG_OOB\fR\fR
  70 .ad
  71 .RS 11n
  72 Sends out-of-band data on sockets that support out-of-band communications. The
  73 significance and semantics of out-of-band data are protocol-specific.
  74 .RE
  75
  76 .RE
  77
  78 .SH DESCRIPTION
  79 .LP
  80 The \fBsend()\fR function initiates transmission of a message from the
  81 specified socket to its peer.  The \fBsend()\fR function sends a message only
  82 when the socket is connected (including when the peer of a connectionless
  83 socket has been set via \fBconnect\fR(3XNET)).
  84 .sp
  85 .LP
  86 The length of the message to be sent is specified by the \fIlength\fR argument.
  87 If the message is too long to pass through the underlying protocol,
  88 \fBsend()\fR fails and no data is transmitted.
  89 .sp
  90 .LP
  91 Successful completion of a call to \fBsend()\fR does not guarantee delivery of
  92 the message.  A return value of \(mi1 indicates only locally-detected errors.
  93 .sp
  94 .LP
  95 If space is not available at the sending socket to hold the message to be
  96 transmitted and the socket file descriptor does not have \fBO_NONBLOCK\fR set,
  97 \fBsend()\fR blocks until space is available.  If space is not available at the
  98 sending socket to hold the message to be transmitted and the socket file
  99 descriptor does have \fBO_NONBLOCK\fR set, \fBsend()\fR will fail. The
 100 \fBselect\fR(3C) and \fBpoll\fR(2) functions can be used to determine when it
 101 is possible to send more data.
 102 .sp
 103 .LP
 104 The socket in use may require the process to have appropriate privileges to use
 105 the \fBsend()\fR function.
 106 .SH USAGE
 107 .LP
 108 The \fBsend()\fR function is identical to \fBsendto\fR(3XNET) with a null
 109 pointer \fIdest_len\fR argument, and to \fBwrite()\fR if no flags are used.
 110 .SH RETURN VALUES
 111 .LP
 112 Upon successful completion, \fBsend()\fR returns the number of bytes sent.
 113 Otherwise, \(mi1 is returned and \fBerrno\fR is set to indicate the error.
 114 .SH ERRORS
 115 .LP
 116 The \fBsend()\fR function will fail if:
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBEAGAIN\fR \fR
 121 .ad
 122 .br
 123 .na
 124 \fB\fBEWOULDBLOCK\fR\fR
 125 .ad
 126 .RS 16n
 127 The socket's file descriptor is marked \fBO_NONBLOCK\fR and the requested
 128 operation would block.
 129 .RE
 130
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fBEBADF\fR\fR
 135 .ad
 136 .RS 16n
 137 The \fIsocket\fR argument is not a valid file descriptor.
 138 .RE
 139
 140 .sp
 141 .ne 2
 142 .na
 143 \fB\fBECONNRESET\fR\fR
 144 .ad
 145 .RS 16n
 146 The \fIsocket\fR argument refers to a connection oriented socket and the
 147 connection was forcibly closed by the peer and is no longer valid. I/O can no
 148 longer be performed to \fIfiledes\fR.
 149 .RE
 150
 151 .sp
 152 .ne 2
 153 .na
 154 \fB\fBEDESTADDRREQ\fR\fR
 155 .ad
 156 .RS 16n
 157 The socket is not connection-mode and no peer address is set.
 158 .RE
 159
 160 .sp
 161 .ne 2
 162 .na
 163 \fB\fBEFAULT\fR\fR
 164 .ad
 165 .RS 16n
 166 The  \fIbuffer\fR parameter can not be accessed.
 167 .RE
 168
 169 .sp
 170 .ne 2
 171 .na
 172 \fB\fBEINTR\fR\fR
 173 .ad
 174 .RS 16n
 175 A signal interrupted \fBsend()\fR before any data was transmitted.
 176 .RE
 177
 178 .sp
 179 .ne 2
 180 .na
 181 \fB\fBEMSGSIZE\fR\fR
 182 .ad
 183 .RS 16n
 184 The message is too large be sent all at once, as the socket requires.
 185 .RE
 186
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fBENOTCONN\fR\fR
 191 .ad
 192 .RS 16n
 193 The socket is not connected or otherwise has not had the peer prespecified.
 194 .RE
 195
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fBENOTSOCK\fR\fR
 200 .ad
 201 .RS 16n
 202 The \fIsocket\fR argument does not refer to a socket.
 203 .RE
 204
 205 .sp
 206 .ne 2
 207 .na
 208 \fB\fBEOPNOTSUPP\fR\fR
 209 .ad
 210 .RS 16n
 211 The \fIsocket\fR argument is associated with a socket that does not support one
 212 or more of the values set in \fIflags\fR.
 213 .RE
 214
 215 .sp
 216 .ne 2
 217 .na
 218 \fB\fBEPIPE\fR\fR
 219 .ad
 220 .RS 16n
 221 The socket is shut down for writing, or the socket is connection-mode and is no
 222 longer connected. In the latter case, and if the socket is of type
 223 \fBSOCK_STREAM\fR, the \fBSIGPIPE\fR signal is generated to the calling thread.
 224 .RE
 225
 226 .sp
 227 .LP
 228 The \fBsend()\fR function may fail if:
 229 .sp
 230 .ne 2
 231 .na
 232 \fB\fBEACCES\fR\fR
 233 .ad
 234 .RS 15n
 235 The calling process does not have the appropriate privileges.
 236 .RE
 237
 238 .sp
 239 .ne 2
 240 .na
 241 \fB\fBEIO\fR\fR
 242 .ad
 243 .RS 15n
 244 An I/O error occurred while reading from or writing to the file system.
 245 .RE
 246
 247 .sp
 248 .ne 2
 249 .na
 250 \fB\fBENETDOWN\fR\fR
 251 .ad
 252 .RS 15n
 253 The local interface used to reach the destination is down.
 254 .RE
 255
 256 .sp
 257 .ne 2
 258 .na
 259 \fB\fBENETUNREACH\fR\fR
 260 .ad
 261 .RS 15n
 262 No route to the network is present.
 263 .RE
 264
 265 .sp
 266 .ne 2
 267 .na
 268 \fB\fBENOBUFS\fR\fR
 269 .ad
 270 .RS 15n
 271 Insufficient resources were available in the system to perform the operation.
 272 .RE
 273
 274 .sp
 275 .ne 2
 276 .na
 277 \fB\fBENOSR\fR\fR
 278 .ad
 279 .RS 15n
 280 There were insufficient STREAMS resources available for the operation to
 281 complete.
 282 .RE
 283
 284 .SH ATTRIBUTES
 285 .LP
 286 See \fBattributes\fR(5) for descriptions of the following attributes:
 287 .sp
 288
 289 .sp
 290 .TS
 291 box;
 292 c | c
 293 l | l .
 294 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 295 _
 296 Interface Stability     Standard
 297 _
 298 MT-Level        MT-Safe
 299 .TE
 300
 301 .SH SEE ALSO
 302 .LP
 303 \fBconnect\fR(3XNET), \fBgetsockopt\fR(3XNET), \fBpoll\fR(2),
 304 \fBrecv\fR(3XNET), \fBrecvfrom\fR(3XNET), \fBrecvmsg\fR(3XNET),
 305 \fBselect\fR(3C), \fBsendmsg\fR(3XNET), \fBsendto\fR(3XNET),
 306 \fBsetsockopt\fR(3XNET), \fBshutdown\fR(3XNET), \fBsocket\fR(3XNET),
 307 \fBattributes\fR(5), \fBstandards\fR(5)