<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation"> <title>send()--Send Data</title> <!-- All rights reserved. Licensed Materials Property of IBM --> <!-- US Government Users Restricted Rights --> <!-- Use, duplication or disclosure restricted by --> <!-- GSA ADP Schedule Contract with IBM Corp. --> <!-- Begin Header Records ========================================== --> <!-- Unix8 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 --> <!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 --> <!--End Header Records --> <link rel="stylesheet" type="text/css" href="../rzahg/ic.css"> </head> <body> <a name="Top_Of_Page"></a> <!-- Java sync-link --> <script type="text/javascript" language="Javascript" src="../rzahg/synch.js"> </script> <h2>send()--Send Data</h2> <div class="box" style="width: 60%;"> <br> BSD 4.3 Syntax<br> <pre> #include <sys/types.h> #include <sys/socket.h> int send(int <em>socket_descriptor</em>, char *<em>buffer</em>, int <em>buffer_length</em>, int <em>flags</em>) </pre> <br> Service Program Name: QSOSRV1<br> <!-- iddvc RMBR --> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Threadsafe: Yes<br> <!-- iddvc RMBR --> <br> </div> <br> <div class="box" style="width: 60%;"> <br> <a href="_xopen_source.htm">UNIX 98 Compatible Syntax</a><br> <pre> #define _XOPEN_SOURCE 520 #include <sys/socket.h> ssize_t send(int <em>socket_descriptor</em>, const void *<em>buffer</em>, size_t <em>buffer_length</em>, int <em>flags</em>) </pre> <br> Service Program Name: QSOSRV1<br> <!-- iddvc RMBR --> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Threadsafe: Yes<br> <!-- iddvc RMBR --> <br> </div> <br> <p>The <em>send()</em> function is used to send data through a connected socket.</p> <p> There are two versions of the API, as shown above. The base i5/OS API uses BSD 4.3 structures and syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the UNIX 98 compatible interface with the <a href="_xopen_source.htm">_XOPEN_SOURCE</a> macro.</p> <br> <h3>Parameters</h3> <dl> <dt><strong>socket_descriptor</strong></dt> <dd>(Input) The socket descriptor that is to be written to.<br> <br> </dd> <dt><strong>buffer</strong></dt> <dd>(Input) The pointer to the buffer in which the data that is to be written is stored.<br> <br> </dd> <dt><strong>buffer_length</strong></dt> <dd>(Input) The length of the <em>buffer</em>.<br> <br> </dd> <dt><strong>flags</strong></dt> <dd>(Input) A flag value that controls the transmission of the data. The <em>flags</em> value is either zero, or is obtained by performing an OR operation on the following constants:<br> <table cellpadding="5"> <!-- cols="15 85" --> <tr> <td align="left" valign="top"><em><samp>MSG_EOR</samp></em></td> <td align="left" valign="top">Terminate a record, if supported by the protocol.</td> </tr> <tr> <td align="left" valign="top"><em><samp>MSG_OOB</samp></em></td> <td align="left" valign="top">Send data as out-of-band data. Valid only for sockets with an address family of <samp>AF_INET</samp> or <samp>AF_INET6</samp> and type <samp>SOCK_STREAM</samp>.</td> </tr> <tr> <td align="left" valign="top"><em><samp>MSG_DONTROUTE</samp></em></td> <td align="left" valign="top">Bypass routing. Valid only for sockets with address family of <samp>AF_INET</samp>. It is ignored for other address families.</td> </tr> </table> </dd> </dl> <br> <h3>Authorities</h3> <p>No authorization is required.</p> <br> <h3>Return Value</h3> <p><em>send()</em> returns an integer. Possible values are:</p> <ul> <li>-1 (unsuccessful)<br> <br> </li> <li>n (successful), where n is the number of bytes sent.</li> </ul> <br> <h3>Error Conditions</h3> <p>When <em>send()</em> fails, <em>errno</em> can be set to one of the following:</p> <table cellpadding="5"> <!-- cols="20 80" --> <tr> <td align="left" valign="top"><em>[EACCES]</em></td> <td align="left" valign="top">Permission denied. <p>This error code indicates one of the following:</p> <ul> <li>Destination address specified a broadcast address and the socket option <samp>SO_BROADCAST</samp> was not set (with a <em>setsockopt()</em>).<br> <br> </li> <li>The process does not have the appropriate privileges to the destination address. This error code can only be returned on a socket with a type of <samp>SOCK_DGRAM</samp> and an address family of <samp>AF_INET</samp>.</li> </ul><br> </td> </tr> <tr> <td align="left" valign="top"><em>[EBADF]</em></td> <td align="left" valign="top">Descriptor not valid.<br><br></td> </tr> <tr> <td align="left" valign="top"><em>[ECONNREFUSED]</em></td> <td align="left" valign="top">The destination socket refused an attempted connect operation. <p>This error code can only be returned on sockets that use a connectionless transport service.</p> </td> </tr> <tr> <td align="left" valign="top"><em>[EDESTADDRREQ]</em></td> <td align="left" valign="top">Operation requires destination address. <p>A destination address has not been associated with the socket pointed to by the <em>socket_descriptor</em> parameter. This error code can only be returned on sockets that use a connectionless transport service.</p> </td> </tr> <tr> <td align="left" valign="top"><em>[EFAULT]</em></td> <td align="left" valign="top">Bad address. <p>The system detected an address which was not valid while attempting to access the <em>buffer</em> parameter.</p> </td> </tr> <tr> <td align="left" valign="top"><em>[EHOSTDOWN]</em></td> <td align="left" valign="top">A remote host is not available. <p>This error code can only be returned on sockets that use a connectionless transport service.</p> </td> </tr> <tr> <td align="left" valign="top"><em>[EHOSTUNREACH]</em></td> <td align="left" valign="top">A route to the remote host is not available. <p>This error code can only be returned on sockets that use a connectionless transport service.</p> </td> </tr> <tr> <td align="left" valign="top"><em>[EINTR]</em></td> <td align="left" valign="top">Interrupted function call.<br><br></td> </tr> <tr> <td align="left" valign="top"><em>[EINVAL]</em></td> <td align="left" valign="top">Parameter not valid. <p>The <em>buffer_length</em> parameter specifies a negative value.</p> </td> </tr> <tr> <td align="left" valign="top"><em>[EIO]</em></td> <td align="left" valign="top">Input/output error.<br><br></td> </tr> <tr> <td align="left" valign="top"><em>[EMSGSIZE]</em></td> <td align="left" valign="top">Message size out of range. <p>The data to be sent could not be sent atomically because the size specified by <em>buffer_length</em> is too large.</p> </td> </tr> <tr> <td align="left" valign="top"><em>[ENETDOWN]</em></td> <td align="left" valign="top">The network is not currently available. <p>This error code can only be returned on sockets that use a connectionless transport service.</p> </td> </tr> <tr> <td align="left" valign="top"><em>[ENETUNREACH]</em></td> <td align="left" valign="top">Cannot reach the destination network. <p>This error code can only be returned on sockets that use a connectionless transport service.</p> </td> </tr> <tr> <td align="left" valign="top"><em>[ENOBUFS]</em></td> <td align="left" valign="top">There is not enough buffer space for the requested operation.<br><br></td> </tr> <tr> <td align="left" valign="top"><em>[ENOTCONN]</em></td> <td align="left" valign="top">Requested operation requires a connection. <p>This error code can only be returned on sockets that use a connection-oriented transport service.</p> </td> </tr> <tr> <td align="left" valign="top"><em>[ENOTSOCK]</em></td> <td align="left" valign="top">The specified descriptor does not reference a socket.<br><br></td> </tr> <tr> <td align="left" valign="top"><em>[EOPNOTSUPP]</em></td> <td align="left" valign="top">Operation not supported. <p>This error code indicates one of the following:</p> <ul> <li>The <em>flags</em> parameter specifies a value that includes the <samp>MSG_OOB</samp> flag, but the <em>socket_descriptor</em> parameter points to a connectionless socket.<br> <br> </li> <li>The <em>flags</em> parameter specifies a value that includes the <samp>MSG_OOB</samp> flag, but the <em>socket_descriptor</em> parameter points to a socket that does not have an address family of <samp>AF_INET</samp> or <samp>AF_INET6</samp>.</li> </ul><br> </td> </tr> <tr> <td align="left" valign="top"><em>[EPIPE]</em></td> <td align="left" valign="top">Broken pipe.<br><br></td> </tr> <tr> <td align="left" valign="top"><em>[EUNATCH]</em></td> <td align="left" valign="top">The protocol required to support the specified address family is not available at this time.<br><br></td> </tr> <tr> <td align="left" valign="top"><em>[EUNKNOWN]</em></td> <td align="left" valign="top">Unknown system state.<br><br></td> </tr> <tr> <td align="left" valign="top"><em>[EWOULDBLOCK]</em></td> <td align="left" valign="top">Operation would have caused the thread to be suspended.</td> </tr> </table> <br> <br> <h3>Error Messages</h3> <table width="100%" cellpadding="5"> <!-- cols="15 85" --> <tr> <th align="left" valign="top">Message ID</th> <th align="left" valign="top">Error Message Text</th> </tr> <tr> <td align="left" valign="top">CPE3418 E</td> <td align="left" valign="top">Possible APAR condition or hardware failure.</td> </tr> <tr> <td align="left" valign="top">CPF9872 E</td> <td align="left" valign="top">Program or service program &1 in library &2 ended. Reason code &3.</td> </tr> <tr> <td align="left" valign="top">CPFA081 E</td> <td align="left" valign="top">Unable to set return value or error code.</td> </tr> </table> <br> <br> <h3>Usage Notes</h3> <ol> <li><em>send()</em> only works with sockets on which a <em>connect()</em> has been issued, since it does not allow the caller to specify a destination address.<br> <br> </li> <li>To broadcast on an <samp>AF_INET</samp> socket, the socket option <samp>SO_BROADCAST</samp> must be set (with a <em>setsockopt()</em>).<br> <br> </li> <li>When using a connection-oriented transport service, all errors except <samp>[EUNATCH]</samp> and <samp>[EUNKNOWN]</samp> are mapped to <samp>[EPIPE]</samp> on an output operation when either of the following occurs: <ul> <li>A connection that is in progress is unsuccessful.<br> <br> </li> <li>An established connection is broken.</li> </ul> To get the actual error, use <em>getsockopt()</em> with the <samp>SO_ERROR</samp> option, or perform an input operation (for example, <em>read()</em>).<br><br></li> <li>When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, the <em>send()</em> API is mapped to <em>qso_send98()</em>.</li> </ol> <br> <h3>Related Information</h3> <ul> <li><a href= "_xopen_source.htm">_XOPEN_SOURCE</a>--Using _XOPEN_SOURCE for the UNIX 98 compatible interface<br> <br> </li> <li><a href="fcntl.htm">fcntl()</a>--Perform File Control Command<br> <br> </li> <li><a href="ioctl.htm">ioctl()</a>--Perform I/O Control Request<br> <br> </li> <li><a href="sendto.htm">sendto()</a>--Send Data<br> <br> </li> <li><a href="sendms.htm">sendmsg()</a>--Send Data or Descriptors or Both<br> <br> </li> <li><a href="write.htm">write()</a>--Write to Descriptor<br> <br> </li> <li><a href="writev.htm">writev()</a>--Write to Descriptor Using Multiple Buffers</li> </ul> <br> <hr> API introduced: V3R1 <hr> <center> <table cellpadding="2" cellspacing="2"> <tr align="center"> <td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href="unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a> </td> </tr> </table> </center> </body> </html>