191df013fSAsim Jamshed<!-- Creator : groff version 1.22.2 --> 291df013fSAsim Jamshed<!-- CreationDate: Fri Feb 3 15:23:32 2017 --> 391df013fSAsim Jamshed<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 491df013fSAsim Jamshed"http://www.w3.org/TR/html4/loose.dtd"> 591df013fSAsim Jamshed<html> 691df013fSAsim Jamshed<head> 791df013fSAsim Jamshed<meta name="generator" content="groff -Thtml, see www.gnu.org"> 891df013fSAsim Jamshed<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 991df013fSAsim Jamshed<meta name="Content-Style" content="text/css"> 1091df013fSAsim Jamshed<style type="text/css"> 1191df013fSAsim Jamshed p { margin-top: 0; margin-bottom: 0; vertical-align: top } 1291df013fSAsim Jamshed pre { margin-top: 0; margin-bottom: 0; vertical-align: top } 1391df013fSAsim Jamshed table { margin-top: 0; margin-bottom: 0; vertical-align: top } 1491df013fSAsim Jamshed h1 { text-align: center } 1591df013fSAsim Jamshed</style> 1691df013fSAsim Jamshed<title>mtcp_peek</title> 17e5df9dc1SAsim Jamshed<link rel="stylesheet" href="./common.css"> 1891df013fSAsim Jamshed</head> 1991df013fSAsim Jamshed<body> 20e5df9dc1SAsim Jamshed<div class="main"> 2191df013fSAsim Jamshed<h1 align="center">mtcp_peek</h1> 22e5df9dc1SAsim Jamshed<!-- 2391df013fSAsim Jamshed<a href="#NAME">NAME</a><br> 2491df013fSAsim Jamshed<a href="#SYNOPSIS">SYNOPSIS</a><br> 2591df013fSAsim Jamshed<a href="#DESCRIPTION">DESCRIPTION</a><br> 2691df013fSAsim Jamshed<a href="#RETURN VALUE">RETURN VALUE</a><br> 2791df013fSAsim Jamshed<a href="#ERRORS">ERRORS</a><br> 2891df013fSAsim Jamshed<a href="#NOTES">NOTES</a><br> 2991df013fSAsim Jamshed<a href="#AUTHORS">AUTHORS</a><br> 3091df013fSAsim Jamshed<a href="#SEE ALSO">SEE ALSO</a><br> 3191df013fSAsim Jamshed<a href="#COLOPHON">COLOPHON</a><br> 3291df013fSAsim Jamshed<hr> 33e5df9dc1SAsim Jamshed--> 3491df013fSAsim Jamshed 3591df013fSAsim Jamshed<h2>NAME 3691df013fSAsim Jamshed<a name="NAME"></a> 3791df013fSAsim Jamshed</h2> 3891df013fSAsim Jamshed 3991df013fSAsim Jamshed 4091df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em">mtcp_peek 4191df013fSAsim Jamshed− Peek into the bytestream from a monitoring 4291df013fSAsim Jamshedsocket</p> 4391df013fSAsim Jamshed 4491df013fSAsim Jamshed<h2>SYNOPSIS 4591df013fSAsim Jamshed<a name="SYNOPSIS"></a> 4691df013fSAsim Jamshed</h2> 4791df013fSAsim Jamshed 4891df013fSAsim Jamshed 4991df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"><b>#include 5091df013fSAsim Jamshed<mos_api.h></b></p> 5191df013fSAsim Jamshed 5291df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"><b>ssize_t 5391df013fSAsim Jamshedmtcp_peek(mctx_t</b> <i>mctx</i><b>, int</b> 5491df013fSAsim Jamshed<i>sockid</i><b>, int</b> <i>side</i><b>, char 5591df013fSAsim Jamshed*</b><i>buf</i><b>, size_t</b> <i>len</i><b>);</b></p> 5691df013fSAsim Jamshed 5791df013fSAsim Jamshed<h2>DESCRIPTION 5891df013fSAsim Jamshed<a name="DESCRIPTION"></a> 5991df013fSAsim Jamshed</h2> 6091df013fSAsim Jamshed 6191df013fSAsim Jamshed 6291df013fSAsim Jamshed 6391df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"><b>mtcp_peek</b>() 6491df013fSAsim Jamshedcan be used to peek up to <i>len</i> number of bytes from a 6591df013fSAsim Jamshedmonitoring socket via socket descriptor <i>sockid</i> into 6691df013fSAsim Jamshedthe buffer (unfragmented) starting at <i>buf.</i> It is the 6791df013fSAsim Jamshedresponsibility of the user to allocate memory for <i>buf</i> 6891df013fSAsim Jamshedarray.</p> 6991df013fSAsim Jamshed 7091df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em">For cases when 7191df013fSAsim Jamshedthe total number of buffered unread bytes in the socket are 7291df013fSAsim Jamshedless than <i>len,</i> <b>mtcp_peek()</b> copies entire data 7391df013fSAsim Jamshedto <i>buf</i> and returns the actual number of bytes that 7491df013fSAsim Jamshedcan be used by the application.</p> 7591df013fSAsim Jamshed 7691df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em">An 7791df013fSAsim Jamshed<b>mtcp_peek</b>() call takes two additional argument named 7891df013fSAsim Jamshed<i>mctx ,</i> that represents the per-core mTCP context in 7991df013fSAsim Jamshedan application (see <b>mtcp_create_context()</b> for 8091df013fSAsim Jamsheddetails); and <i>side</i> that informs the stack whether it 8191df013fSAsim Jamshedneeds to peek the client (MOS_SIDE_CLI) or server 8291df013fSAsim Jamshed(MOS_SIDE_SVR) side.</p> 8391df013fSAsim Jamshed 8491df013fSAsim Jamshed<h2>RETURN VALUE 8591df013fSAsim Jamshed<a name="RETURN VALUE"></a> 8691df013fSAsim Jamshed</h2> 8791df013fSAsim Jamshed 8891df013fSAsim Jamshed 8991df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em">On success, the 9091df013fSAsim Jamshed number of bytes read is returned. It is not an error if this 9191df013fSAsim Jamshed number is smaller than the number of bytes requested; this 9291df013fSAsim Jamshed may happen when the socket has fewer number of bytes 93*626fc701SYoungGyoun buffered at that moment. On all errors except <i>ENODATA</i>, 94*626fc701SYoungGyoun -1 is returned and <i>errno</i> is set appropriately. 95*626fc701SYoungGyoun On <i>ENODATA</i> error, if the buffer outrun was occured, 96*626fc701SYoungGyoun it would return <i>(-1) * (the number of bytes overwritten 97*626fc701SYoungGyoun on the buffer)</i>. 98*626fc701SYoungGyoun</p> 99*626fc701SYoungGyoun 10091df013fSAsim Jamshed 10191df013fSAsim Jamshed<h2>ERRORS 10291df013fSAsim Jamshed<a name="ERRORS"></a> 10391df013fSAsim Jamshed</h2> 10491df013fSAsim Jamshed 10591df013fSAsim Jamshed 10691df013fSAsim Jamshed<table width="100%" border="0" rules="none" frame="void" 10791df013fSAsim Jamshed cellspacing="0" cellpadding="0"> 10891df013fSAsim Jamshed<tr valign="top" align="left"> 10991df013fSAsim Jamshed<td width="11%"></td> 11091df013fSAsim Jamshed<td width="12%"> 11191df013fSAsim Jamshed 11291df013fSAsim Jamshed 11391df013fSAsim Jamshed<p style="margin-top: 1em"><b>EACCES</b></p></td> 11491df013fSAsim Jamshed<td width="3%"></td> 11591df013fSAsim Jamshed<td width="74%"> 11691df013fSAsim Jamshed 11791df013fSAsim Jamshed 11891df013fSAsim Jamshed<p style="margin-top: 1em">The <i>mctx</i> argument is 11991df013fSAsim Jamshedinvalid.</p> </td></tr> 12091df013fSAsim Jamshed<tr valign="top" align="left"> 12191df013fSAsim Jamshed<td width="11%"></td> 12291df013fSAsim Jamshed<td width="12%"> 12391df013fSAsim Jamshed 12491df013fSAsim Jamshed 12591df013fSAsim Jamshed<p><b>EBADF</b></p></td> 12691df013fSAsim Jamshed<td width="3%"></td> 12791df013fSAsim Jamshed<td width="74%"> 12891df013fSAsim Jamshed 12991df013fSAsim Jamshed 13091df013fSAsim Jamshed<p>The socket descriptor <i>sockid</i> is invalid.</p></td></tr> 13191df013fSAsim Jamshed<tr valign="top" align="left"> 13291df013fSAsim Jamshed<td width="11%"></td> 13391df013fSAsim Jamshed<td width="12%"> 13491df013fSAsim Jamshed 13591df013fSAsim Jamshed 13691df013fSAsim Jamshed<p><b>EINVAL</b></p></td> 13791df013fSAsim Jamshed<td width="3%"></td> 13891df013fSAsim Jamshed<td width="74%"> 13991df013fSAsim Jamshed 14091df013fSAsim Jamshed 14191df013fSAsim Jamshed<p>The buffer management of the monitoring socket with 14291df013fSAsim Jamshed<i>sockid</i> was already disabled.</p></td></tr> 14391df013fSAsim Jamshed<tr valign="top" align="left"> 14491df013fSAsim Jamshed<td width="11%"></td> 14591df013fSAsim Jamshed<td width="12%"> 14691df013fSAsim Jamshed 14791df013fSAsim Jamshed 14891df013fSAsim Jamshed<p><b>ENOTSOCK</b></p></td> 14991df013fSAsim Jamshed<td width="3%"></td> 15091df013fSAsim Jamshed<td width="74%"> 15191df013fSAsim Jamshed 15291df013fSAsim Jamshed 15391df013fSAsim Jamshed<p>The socket referred to by <i>sockid</i> has invalid 15491df013fSAsim Jamshed<i>type</i></p> </td></tr> 15591df013fSAsim Jamshed<tr valign="top" align="left"> 15691df013fSAsim Jamshed<td width="11%"></td> 15791df013fSAsim Jamshed<td width="12%"> 15891df013fSAsim Jamshed 15991df013fSAsim Jamshed 16091df013fSAsim Jamshed<p><b>ENOTCONN</b></p></td> 16191df013fSAsim Jamshed<td width="3%"></td> 16291df013fSAsim Jamshed<td width="74%"> 16391df013fSAsim Jamshed 16491df013fSAsim Jamshed 16591df013fSAsim Jamshed<p>Th socket referred to by <i>sockid</i> is in a TCP state 16691df013fSAsim Jamshedthat disallows read operations.</p></td></tr> 16791df013fSAsim Jamshed<tr valign="top" align="left"> 16891df013fSAsim Jamshed<td width="11%"></td> 16991df013fSAsim Jamshed<td width="12%"> 17091df013fSAsim Jamshed 17191df013fSAsim Jamshed 17291df013fSAsim Jamshed<p><b>ENODATA</b></p></td> 17391df013fSAsim Jamshed<td width="3%"></td> 17491df013fSAsim Jamshed<td width="74%"> 17591df013fSAsim Jamshed 17691df013fSAsim Jamshed 17791df013fSAsim Jamshed<p>The socket referred to by <i>sockid</i> does not have 17891df013fSAsim Jamshedany available bytes in its buffer for reading.</p></td></tr> 17991df013fSAsim Jamshed<tr valign="top" align="left"> 18091df013fSAsim Jamshed<td width="11%"></td> 18191df013fSAsim Jamshed<td width="12%"> 18291df013fSAsim Jamshed 18391df013fSAsim Jamshed 18491df013fSAsim Jamshed<p><b>EPERM</b></p></td> 18591df013fSAsim Jamshed<td width="3%"></td> 18691df013fSAsim Jamshed<td width="74%"> 18791df013fSAsim Jamshed 18891df013fSAsim Jamshed 18991df013fSAsim Jamshed<p>The caller is not permitted to access this function.</p></td></tr> 19091df013fSAsim Jamshed</table> 19191df013fSAsim Jamshed 19291df013fSAsim Jamshed<h2>NOTES 19391df013fSAsim Jamshed<a name="NOTES"></a> 19491df013fSAsim Jamshed</h2> 19591df013fSAsim Jamshed 19691df013fSAsim Jamshed 19791df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em">Since TCP flow 19891df013fSAsim Jamshedcontrol applies between end-hosts, the receive buffer 19991df013fSAsim Jamshedmanaged by mOS can become full while new packets continue to 20091df013fSAsim Jamshedarrive. Silent TCP ring buffer overwriting is undesirable 20191df013fSAsim Jamshedsince the application may not notice the buffer overflow. 20291df013fSAsim JamshedInstead, mOS raises an error event to explicitly notify the 20391df013fSAsim Jamshedapplication about the buffer overflow. The application can 20491df013fSAsim Jamshedeither drain the buffer by reading the data (by calling 20591df013fSAsim Jamshed<b>mtcp_peek())</b> or enlarge the buffer (by calling 20691df013fSAsim Jamshed<b>mtcp_setsockopt()).</b> Otherwise, the stack overwrites 20791df013fSAsim Jamshedthe buffer with the new data, and adjusts the internal peek 20891df013fSAsim Jamshedpointer. To notify the application about the overwriting, 20991df013fSAsim Jamshed<b>mtcp_peek()</b> fails right after overwriting. Subsequent 21091df013fSAsim Jamshedfunction calls continue to read the data from the new 21191df013fSAsim Jamshedposition.</p> 21291df013fSAsim Jamshed 21391df013fSAsim Jamshed<h2>AUTHORS 21491df013fSAsim Jamshed<a name="AUTHORS"></a> 21591df013fSAsim Jamshed</h2> 21691df013fSAsim Jamshed 21791df013fSAsim Jamshed 21891df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em">mOS development 21991df013fSAsim Jamshedteam <[email protected]></p> 22091df013fSAsim Jamshed 221*626fc701SYoungGyoun 222*626fc701SYoungGyoun<!-----------------------------------------------------------> 223*626fc701SYoungGyoun<h2>EXAMPLES 224*626fc701SYoungGyoun <a name="EXAMPLES"></a> 225*626fc701SYoungGyoun</h2> 226*626fc701SYoungGyoun 227*626fc701SYoungGyoun<p style="margin-left:11%; margin-top: 1em"> 228*626fc701SYoungGyoun <a href="http://mos.kaist.edu/guide/programmer/05_api_example.html#monitoring-reassembled-tcp-payload"> 229*626fc701SYoungGyoun http://mos.kaist.edu/guide/programmer/05_api_example.html#monitoring-reassembled-tcp-payload 230*626fc701SYoungGyoun </a> 231*626fc701SYoungGyoun</p> 232*626fc701SYoungGyoun<!-----------------------------------------------------------> 233*626fc701SYoungGyoun 234*626fc701SYoungGyoun 23591df013fSAsim Jamshed<h2>SEE ALSO 23691df013fSAsim Jamshed<a name="SEE ALSO"></a> 23791df013fSAsim Jamshed</h2> 23891df013fSAsim Jamshed 23991df013fSAsim Jamshed 24091df013fSAsim Jamshed 24191df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"><b>mtcp_ppeek</b>(), 24291df013fSAsim Jamshed<b>mtcp_socket</b>(), <b>mtcp_getsockopt</b>()</p> 24391df013fSAsim Jamshed 24491df013fSAsim Jamshed<h2>COLOPHON 24591df013fSAsim Jamshed<a name="COLOPHON"></a> 24691df013fSAsim Jamshed</h2> 24791df013fSAsim Jamshed 24891df013fSAsim Jamshed 24991df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em">This page is 25091df013fSAsim Jamshedpart of mOS release 0.3 <i>docs</i> section. A description 25191df013fSAsim Jamshedof the project, and information about reporting bugs, can be 25291df013fSAsim Jamshedfound at http://mos.kaist.edu/.</p> 253e5df9dc1SAsim Jamshed<!-- <hr> --> 254e5df9dc1SAsim Jamshed<br> 255e5df9dc1SAsim Jamshed<div class="footer"> 256e5df9dc1SAsim Jamshed <img src="back-arrow.jpg" width="2%" height="2%"><a href="http://mos.kaist.edu/index_man.html">Back to Index</a> 257e5df9dc1SAsim Jamshed</div> 258e5df9dc1SAsim Jamshed</div> 25991df013fSAsim Jamshed</body> 26091df013fSAsim Jamshed</html> 261
