 
<html><head><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title></title><style type="text/css">
<!--
.style1 {font-size: 18px;font-weight: bold;font-family: Georgia, "Times New Roman", Times, serif;}
a{color:#0000cc;text-decoration:none}
a:visited{color:#0000cc;text-decoration:none}
.style2 {color: #660000}
-->
</style></head>
<body style="margin:0px 0px 0px 0px;">
<table width="100%" border="0" cellpadding="0" cellspacing="0">
  <tr>
    <td bgcolor="#cccccc"><span class="style1" style="margin-left:5px">SYS_RECVMSG</span></td>
  </tr>
  <tr>
    <td><p style="margin-left:22px;margin-top:0px"><br />
      Receive messages from a socket, and may be used to receive data on a socket  whether or not it is connection-oriented. </p>
      <p style="margin-left:10px"><strong>Arguments:</strong></p>
      <table width="100%" border="0" style="margin-left:20px; margin-right:20px">
        <tr>
          <td width="6%" valign="top"><code><em>1st </em></code></td>
          <td width="94%">Socket descriptor. </td>
        </tr>
        <tr>
          <td valign="top"><code><em>2nd</em></code></td>
          <td>Pointer to a properly initialized<em> msghdr</em> structure:<br />
            <table width="100%" border="0" style="border:dashed;border-bottom-width:1px;border-left-width:1px;border-right-width:1px;border-top-width:1px;border-color:#333333">
              <tr>
                <td><code>struc msghdr<br>
                  {<br />
                  .msg_name             &nbsp;&nbsp;&nbsp;     &nbsp;&nbsp;rd 1 <br />
                  .msg_namelen          &nbsp;&nbsp;&nbsp;rd 1 <br />
                  .msg_iov              &nbsp;&nbsp;&nbsp;     &nbsp;&nbsp;&nbsp;rd 1 <br />
                  .msg_iovlen           &nbsp;&nbsp;&nbsp; rd 1 <br />
                  .msg_control     &nbsp;&nbsp;&nbsp;rd 1 <br />
                  .msg_controllen  rd 1 <br />
                  .msg_flags            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;rd 1 <br />
                }</code></td>
              </tr>
            </table>
          <br />
          <code><em><u>msghdr</u></em><u> members:<br />
          </u><br />
          <span style="margin-left:10px"><strong><em>msg_name</em></strong></span><br />
          </code>
          <div style="margin-left:25px;"><code>Pointer to a <em>sockaddr</em> structure specifying the source address if the socket is unconnected</code>. It may be 0.            </div>
          <code> <span style="margin-left:10px"><strong><em>msg_namelen</em></strong><br />
          </span> </code>
          <div style="margin-left:25px"><code>Size of the structure </code>pointed by <em><code>msg_namelen</code></em></div>
          <code> <span style="margin-left:10px"><strong><em>msg_iov</em></strong><br />
          </span> </code>
          <div style="margin-left:25px">Pointer to an array of <em>iovec</em> structures describe scatter-gather locations, as discussed in <a href="145.html">sys_readv</a>. </div>
          <code> <span style="margin-left:10px"><strong><em>msg_iovlen</em></strong><br />
          </span> </code>
          <div style="margin-left:25px"><code>Number of elements in the <em>iovec</em> array. </code></div>
          <code><span style="margin-left:10px"><strong><em>msg_control</em></strong><br />
          </span> </code>
          <div style="margin-left:25px">Pointer to a buffer for other protocol control related messages or miscellaneous  ancillary data.</div>
          <code><span style="margin-left:10px"><strong><em>msg_controllen</em></strong><br />
          </span> </code>
          <div style="margin-left:25px"><code>Size of the buffer pointed by <em>msg_control</em>. </code>Upon return this member will contain the length of the control message sequence. </div>
          <code><span style="margin-left:10px"><strong><em>msg_flags</em></strong><br />
          </span> </code>
          <div style="margin-left:25px">This member  is set on return of SYS_RECVMSG. It can contain several  flags: 
            <table width="100%" border="0" style="border:dashed;border-bottom-width:1px;border-left-width:1px;border-right-width:1px;border-top-width:1px;border-color:#333333">
              <tr>
                <td><table width="100%" border="0">
                    <tr>
                      <td width="13%"><code>MSG_EOR </code></td>
                      <td width="87%"><code>Indicates end-of-record; the data returned completed a record (generally used  with sockets of type SOCK_SEQPACKET). </code></td>
                    </tr>
                    <tr>
                      <td><code>MSG_TRUNC </code></td>
                      <td><code>Indicates that the trailing portion of a datagram was discarded because the  datagram was larger than the buffer supplied. </code></td>
                    </tr>
                    <tr>
                      <td><code>MSG_CTRUNC </code></td>
                      <td><code>Indicates that some control data were discarded due to lack of space in the  buffer for ancillary data. </code></td>
                    </tr>
                    <tr>
                      <td><code>MSG_OOB</code></td>
                      <td><code>Is returned to indicate that expedited or out-of-band data were received</code></td>
                    </tr>
                    <tr>
                      <td><code>MSG_ERRQUEUE </code></td>
                      <td><code>Indicates that no data was received but an extended error from the socket error  queue. </code></td>
                    </tr>
                </table></td>
              </tr>
            </table>
          </div></td>
        </tr>
        <tr>
          <td valign="top"><code><em>3rd</em></code></td>
          <td>Flags:
            <table width="100%" border="0" style="border:dashed;border-bottom-width:1px;border-left-width:1px;border-right-width:1px;border-top-width:1px;border-color:#333333">
              <tr>
                <td><table width="100%" border="0">
                    <tr>
                      <td width="12%" valign="top"><code>MSG_OOB</code></td>
                      <td width="88%"><code>This flag requests receipt of out-of-band data that would not be received in the  normal data stream. Some protocols place expedited data at the head of the  normal data queue, and thus this flag cannot be used with such protocols. </code></td>
                    </tr>
                    <tr>
                      <td valign="top"><code>MSG_PEEK</code></td>
                      <td><code>This flag causes the receive operation to return data from the beginning of the  receive queue without removing that data from the queue. Thus, a subsequent  receive call will return the same data. </code></td>
                    </tr>
                    <tr>
                      <td valign="top"><code>MSG_DONTROUTE</code></td>
                      <td><code><span class="style2">*to be documented* </span></code></td>
                    </tr>
                    <tr>
                      <td valign="top"><code>MSG_TRYHARD</code></td>
                      <td><code><span class="style2">*to be documented* </span></code></td>
                    </tr>
                    <tr>
                      <td valign="top"><code>MSG_CTRUNC</code></td>
                      <td><code><span class="style2">*to be documented* </span></code></td>
                    </tr>
                    <tr>
                      <td valign="top"><code>MSG_PROBE</code></td>
                      <td><code><span class="style2">*to be documented* </span></code></td>
                    </tr>
                    <tr>
                      <td valign="top"><code>MSG_TRUNC</code></td>
                      <td><code>Return the real length of the packet, even when it was longer than the passed  buffer. Only valid for packet sockets. </code></td>
                    </tr>
                    <tr>
                      <td valign="top"><code>MSG_DONTWAIT</code></td>
                      <td><code>Enables non-blocking operation; if the operation would block, -EAGAIN is  returned (this can also be enabled using the O_NONBLOCK with the F_SETFL <a href="55.html">sys_fcntl</a>). </code></td>
                    </tr>
                    <tr>
                      <td valign="top"><code>MSG_EOR</code></td>
                      <td><code><span class="style2">*to be documented* </span></code></td>
                    </tr>
                    <tr>
                      <td valign="top"><code>MSG_WAITALL</code></td>
                      <td><code>This flag requests that the operation block until the full request is satisfied.  However, the call may still return less data than requested if a signal is  caught, an error or disconnect occurs, or the next data to be received is of a  different type than that returned. </code></td>
                    </tr>
                    <tr>
                      <td valign="top"><code>MSG_FIN</code></td>
                      <td><code><span class="style2">*to be documented* </span></code></td>
                    </tr>
                    <tr>
                      <td valign="top"><code>MSG_SYN</code></td>
                      <td><code><span class="style2">*to be documented* </span></code></td>
                    </tr>
                    <tr>
                      <td valign="top"><code>MSG_CONFIRM</code></td>
                      <td><code><span class="style2">*to be documented* </span></code></td>
                    </tr>
                    <tr>
                      <td valign="top"><code>MSG_RST </code></td>
                      <td><code><span class="style2">*to be documented* </span></code></td>
                    </tr>
                    <tr>
                      <td valign="top"><code>MSG_ERRQUEUE</code></td>
                      <td><code>This flag specifies that queued errors should be received from the socket  error queue. The error is passed in an ancillary message with a type dependent  on the protocol (for IPv4 IP_RECVERR). The user should supply a buffer of  sufficient size. See <em>man 3 cmsg</em> and <em>man 7 ip</em> for more information. The payload of the  original packet that caused the error is passed as normal data via <em>msg_iovec</em>. The original destination address of the datagram that caused  the error is supplied via <em>msg_name</em>.<br />
                            <br />
                        For local errors, no address is passed (this can be checked with the <em>cmsg_len</em> member of the <em>cmsghdr</em>). For error receives, the MSG_ERRQUEUE is set in the <em>msghdr</em>. After an error has been passed,  the pending socket error is regenerated based on the next queued error and will  be passed on the next socket operation. </code>
                          <p><code>The error is supplied in a <em>sock_extended_err</em> structure: </code></p>
                        <table width="100%" border="0" style="border:dashed;border-bottom-width:1px;border-left-width:1px;border-right-width:1px;border-top-width:1px;border-color:#333333">
                            <tr>
                              <td><code>struc sock_extended_err<br>
{<br />
.ee_errno&nbsp; rd 1 <br />
.ee_origin       rb 1 <br />
.ee_type         &nbsp;&nbsp;rb 1 <br />
.ee_code         &nbsp;&nbsp;rb 1 <br />
.ee_pad          &nbsp;&nbsp;&nbsp;rb 1 <br />
.ee_info         &nbsp;&nbsp;rd 1 <br />
.ee_data         &nbsp;&nbsp;rd 1 <br />
}</code></td>
                            </tr>
                          </table>
                        <code><br />
                          <em><u>sock_extended_err</u></em><u> members:<br />
                          </u><br />
                          <span style="margin-left:10px"><strong><em>ee_errno</em></strong></span><br />
                          </code>
                          <div style="margin-left:25px;"><code>Error number. Curreently defined values are: </code>
                              <table width="100%" border="0" style="border:dashed;border-bottom-width:1px;border-left-width:1px;border-right-width:1px;border-top-width:1px;border-color:#333333">
                                <tr>
                                  <td><table width="100%" border="0">
                                      <tr>
                                        <td width="22%"><code>SO_EE_ORIGIN_NONE</code></td>
                                        <td width="78%"><code><span class="style2">*to be documented* </span></code></td>
                                      </tr>
                                      <tr>
                                        <td><code>SO_EE_ORIGIN_LOCAL</code></td>
                                        <td><code><span class="style2">*to be documented* </span></code></td>
                                      </tr>
                                      <tr>
                                        <td><code>SO_EE_ORIGIN_ICMP </code></td>
                                        <td><code><span class="style2">*to be documented* </span></code></td>
                                      </tr>
                                      <tr>
                                        <td><code>SO_EE_ORIGIN_ICMP6</code></td>
                                        <td><code><span class="style2">*to be documented* </span></code></td>
                                      </tr>
                                  </table></td>
                                </tr>
                              </table>
                          </div>
                        <code> <span style="margin-left:10px"><strong><em>ee_origin</em></strong><br />
                          </span> </code>
                          <div style="margin-left:25px"><code>Origin code of where the error originated.</code></div>
                        <code> <span style="margin-left:10px"><strong><em>ee_type</em></strong><br />
                          </span> </code>
                          <div style="margin-left:25px"><code>This field is protocol specific. <span class="style2">*to be documented* </span></code></div>
                        <code> <span style="margin-left:10px"><strong><em>ee_code</em></strong><br />
                          </span> </code>
                          <div style="margin-left:25px"><code>This field is protocol specific. <span class="style2">*to be documented* </span></code></div>
                        <code><span style="margin-left:10px"><strong><em>ee_pad</em></strong><br />
                          </span> </code>
                          <div style="margin-left:25px"><code>Padding.</code></div>
                        <code><span style="margin-left:10px"><strong><em>ee_info</em></strong><br />
                          </span> </code>
                          <div style="margin-left:25px"><code>This field is protocol specific. <span class="style2">*to be documented* </span></code></div>
                        <code><span style="margin-left:10px"><strong><em>ee_data</em></strong><br />
                          </span> </code>
                          <div style="margin-left:25px"><code>This field is protocol specific. <span class="style2">*to be documented* </span></code></div></td>
                    </tr>
                    <tr>
                      <td valign="top"><code>MSG_NOSIGNAL</code></td>
                      <td><code><span class="style2">*to be documented* </span></code></td>
                    </tr>
                    <tr>
                      <td valign="top"><code>MSG_MORE</code></td>
                      <td><code><span class="style2">*to be documented* </span></code></td>
                    </tr>
                </table></td>
              </tr>
            </table></td>
        </tr>
      </table>
      <p style="margin-left:10px" ><strong>Return values</strong></p>
      <p style="margin-left:22px;margin-right:10px" >If the system call succeeds the return value is the number of bytes received.<br />
If the system call fails the return value is one of the following <em>errno</em> values (These are some standard errors generated by the socket layer. Additional errors  may be generated and returned from the underlying protocol modules):</p>
      <table width="100%" border="0" style="border:dashed;border-bottom-width:1px;border-left-width:1px;border-right-width:1px;border-top-width:1px;border-color:#333333;margin-left:22px;margin-right:22px">
        <tr>
          <td><table width="100%" border="0">
              <tr>
                <td width="10%" valign="top"><code>-EAGAIN </code></td>
                <td width="90%"><code>The socket is marked non-blocking and the receive operation would block, or a  receive timeout had been set and the timeout expired before data was received. </code></td>
              </tr>
              <tr>
                <td valign="top"><code>-EBADF </code></td>
                <td><code>The <em>1st</em> argument is an invalid descriptor. </code></td>
              </tr>
              <tr>
                <td valign="top"><code>-ECONNREFUSED </code></td>
                <td><code>A remote host refused to allow the network connection (typically because it is  not running the requested service). </code></td>
              </tr>
              <tr>
                <td valign="top"><code>-EFAULT </code></td>
                <td><code>The receive buffer pointer(s) point outside the process's address space. </code></td>
              </tr>
              <tr>
                <td valign="top"><code>-EINTR </code></td>
                <td><code>The receive was interrupted by delivery of a signal before any data were  available. </code></td>
              </tr>
              <tr>
                <td valign="top"><code>-EINVAL </code></td>
                <td><code>Invalid argument passed. </code></td>
              </tr>
              <tr>
                <td valign="top"><code>-ENOTCONN </code></td>
                <td><code>The socket is associated with a connection-oriented protocol and has not been  connected (see <a href="sys_connect.html">SYS_CONNECT</a> and <a href="sys_accept.html">SYS_ACCEPT</a>). </code></td>
              </tr>
              <tr>
                <td valign="top"><code>-ENOTSOCK </code></td>
                <td><code>The <em>1st</em> argument does not refer to a socket. </code></td>
              </tr>
              <tr>
                <td valign="top"><code>-ENOMEM </code></td>
                <td><code>Could not allocate memory.</code></td>
              </tr>
          </table></td>
        </tr>
      </table>
      <p style="margin-left:10px"><strong>Remarks</strong></p>
      <p style="margin-left:22px">n/a</p>
      <p style="margin-left:10px"><strong>Compatibility</strong></p>
    <p style="margin-left:22px">n/a</p></td>
  </tr>
</table></body></html>