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> 17*e5df9dc1SAsim Jamshed<link rel="stylesheet" href="./common.css"> 1891df013fSAsim Jamshed</head> 1991df013fSAsim Jamshed<body> 20*e5df9dc1SAsim Jamshed<div class="main"> 2191df013fSAsim Jamshed<h1 align="center">mtcp_peek</h1> 22*e5df9dc1SAsim 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> 33*e5df9dc1SAsim 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 Jamshednumber of bytes read is returned. It is not an error if this 9191df013fSAsim Jamshednumber is smaller than the number of bytes requested; this 9291df013fSAsim Jamshedmay happen when the socket has fewer number of bytes 9391df013fSAsim Jamshedbuffered at that moment. On all errors, -1 is returned and 9491df013fSAsim Jamshed<i>errno</i> is set appropriately.</p> 9591df013fSAsim Jamshed 9691df013fSAsim Jamshed<h2>ERRORS 9791df013fSAsim Jamshed<a name="ERRORS"></a> 9891df013fSAsim Jamshed</h2> 9991df013fSAsim Jamshed 10091df013fSAsim Jamshed 10191df013fSAsim Jamshed<table width="100%" border="0" rules="none" frame="void" 10291df013fSAsim Jamshed cellspacing="0" cellpadding="0"> 10391df013fSAsim Jamshed<tr valign="top" align="left"> 10491df013fSAsim Jamshed<td width="11%"></td> 10591df013fSAsim Jamshed<td width="12%"> 10691df013fSAsim Jamshed 10791df013fSAsim Jamshed 10891df013fSAsim Jamshed<p style="margin-top: 1em"><b>EACCES</b></p></td> 10991df013fSAsim Jamshed<td width="3%"></td> 11091df013fSAsim Jamshed<td width="74%"> 11191df013fSAsim Jamshed 11291df013fSAsim Jamshed 11391df013fSAsim Jamshed<p style="margin-top: 1em">The <i>mctx</i> argument is 11491df013fSAsim Jamshedinvalid.</p> </td></tr> 11591df013fSAsim Jamshed<tr valign="top" align="left"> 11691df013fSAsim Jamshed<td width="11%"></td> 11791df013fSAsim Jamshed<td width="12%"> 11891df013fSAsim Jamshed 11991df013fSAsim Jamshed 12091df013fSAsim Jamshed<p><b>EBADF</b></p></td> 12191df013fSAsim Jamshed<td width="3%"></td> 12291df013fSAsim Jamshed<td width="74%"> 12391df013fSAsim Jamshed 12491df013fSAsim Jamshed 12591df013fSAsim Jamshed<p>The socket descriptor <i>sockid</i> is invalid.</p></td></tr> 12691df013fSAsim Jamshed<tr valign="top" align="left"> 12791df013fSAsim Jamshed<td width="11%"></td> 12891df013fSAsim Jamshed<td width="12%"> 12991df013fSAsim Jamshed 13091df013fSAsim Jamshed 13191df013fSAsim Jamshed<p><b>EINVAL</b></p></td> 13291df013fSAsim Jamshed<td width="3%"></td> 13391df013fSAsim Jamshed<td width="74%"> 13491df013fSAsim Jamshed 13591df013fSAsim Jamshed 13691df013fSAsim Jamshed<p>The buffer management of the monitoring socket with 13791df013fSAsim Jamshed<i>sockid</i> was already disabled.</p></td></tr> 13891df013fSAsim Jamshed<tr valign="top" align="left"> 13991df013fSAsim Jamshed<td width="11%"></td> 14091df013fSAsim Jamshed<td width="12%"> 14191df013fSAsim Jamshed 14291df013fSAsim Jamshed 14391df013fSAsim Jamshed<p><b>ENOTSOCK</b></p></td> 14491df013fSAsim Jamshed<td width="3%"></td> 14591df013fSAsim Jamshed<td width="74%"> 14691df013fSAsim Jamshed 14791df013fSAsim Jamshed 14891df013fSAsim Jamshed<p>The socket referred to by <i>sockid</i> has invalid 14991df013fSAsim Jamshed<i>type</i></p> </td></tr> 15091df013fSAsim Jamshed<tr valign="top" align="left"> 15191df013fSAsim Jamshed<td width="11%"></td> 15291df013fSAsim Jamshed<td width="12%"> 15391df013fSAsim Jamshed 15491df013fSAsim Jamshed 15591df013fSAsim Jamshed<p><b>ENOTCONN</b></p></td> 15691df013fSAsim Jamshed<td width="3%"></td> 15791df013fSAsim Jamshed<td width="74%"> 15891df013fSAsim Jamshed 15991df013fSAsim Jamshed 16091df013fSAsim Jamshed<p>Th socket referred to by <i>sockid</i> is in a TCP state 16191df013fSAsim Jamshedthat disallows read operations.</p></td></tr> 16291df013fSAsim Jamshed<tr valign="top" align="left"> 16391df013fSAsim Jamshed<td width="11%"></td> 16491df013fSAsim Jamshed<td width="12%"> 16591df013fSAsim Jamshed 16691df013fSAsim Jamshed 16791df013fSAsim Jamshed<p><b>ENODATA</b></p></td> 16891df013fSAsim Jamshed<td width="3%"></td> 16991df013fSAsim Jamshed<td width="74%"> 17091df013fSAsim Jamshed 17191df013fSAsim Jamshed 17291df013fSAsim Jamshed<p>The socket referred to by <i>sockid</i> does not have 17391df013fSAsim Jamshedany available bytes in its buffer for reading.</p></td></tr> 17491df013fSAsim Jamshed<tr valign="top" align="left"> 17591df013fSAsim Jamshed<td width="11%"></td> 17691df013fSAsim Jamshed<td width="12%"> 17791df013fSAsim Jamshed 17891df013fSAsim Jamshed 17991df013fSAsim Jamshed<p><b>EPERM</b></p></td> 18091df013fSAsim Jamshed<td width="3%"></td> 18191df013fSAsim Jamshed<td width="74%"> 18291df013fSAsim Jamshed 18391df013fSAsim Jamshed 18491df013fSAsim Jamshed<p>The caller is not permitted to access this function.</p></td></tr> 18591df013fSAsim Jamshed</table> 18691df013fSAsim Jamshed 18791df013fSAsim Jamshed<h2>NOTES 18891df013fSAsim Jamshed<a name="NOTES"></a> 18991df013fSAsim Jamshed</h2> 19091df013fSAsim Jamshed 19191df013fSAsim Jamshed 19291df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em">Since TCP flow 19391df013fSAsim Jamshedcontrol applies between end-hosts, the receive buffer 19491df013fSAsim Jamshedmanaged by mOS can become full while new packets continue to 19591df013fSAsim Jamshedarrive. Silent TCP ring buffer overwriting is undesirable 19691df013fSAsim Jamshedsince the application may not notice the buffer overflow. 19791df013fSAsim JamshedInstead, mOS raises an error event to explicitly notify the 19891df013fSAsim Jamshedapplication about the buffer overflow. The application can 19991df013fSAsim Jamshedeither drain the buffer by reading the data (by calling 20091df013fSAsim Jamshed<b>mtcp_peek())</b> or enlarge the buffer (by calling 20191df013fSAsim Jamshed<b>mtcp_setsockopt()).</b> Otherwise, the stack overwrites 20291df013fSAsim Jamshedthe buffer with the new data, and adjusts the internal peek 20391df013fSAsim Jamshedpointer. To notify the application about the overwriting, 20491df013fSAsim Jamshed<b>mtcp_peek()</b> fails right after overwriting. Subsequent 20591df013fSAsim Jamshedfunction calls continue to read the data from the new 20691df013fSAsim Jamshedposition.</p> 20791df013fSAsim Jamshed 20891df013fSAsim Jamshed<h2>AUTHORS 20991df013fSAsim Jamshed<a name="AUTHORS"></a> 21091df013fSAsim Jamshed</h2> 21191df013fSAsim Jamshed 21291df013fSAsim Jamshed 21391df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em">mOS development 21491df013fSAsim Jamshedteam <[email protected]></p> 21591df013fSAsim Jamshed 21691df013fSAsim Jamshed<h2>SEE ALSO 21791df013fSAsim Jamshed<a name="SEE ALSO"></a> 21891df013fSAsim Jamshed</h2> 21991df013fSAsim Jamshed 22091df013fSAsim Jamshed 22191df013fSAsim Jamshed 22291df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em"><b>mtcp_ppeek</b>(), 22391df013fSAsim Jamshed<b>mtcp_socket</b>(), <b>mtcp_getsockopt</b>()</p> 22491df013fSAsim Jamshed 22591df013fSAsim Jamshed<h2>COLOPHON 22691df013fSAsim Jamshed<a name="COLOPHON"></a> 22791df013fSAsim Jamshed</h2> 22891df013fSAsim Jamshed 22991df013fSAsim Jamshed 23091df013fSAsim Jamshed<p style="margin-left:11%; margin-top: 1em">This page is 23191df013fSAsim Jamshedpart of mOS release 0.3 <i>docs</i> section. A description 23291df013fSAsim Jamshedof the project, and information about reporting bugs, can be 23391df013fSAsim Jamshedfound at http://mos.kaist.edu/.</p> 234*e5df9dc1SAsim Jamshed<!-- <hr> --> 235*e5df9dc1SAsim Jamshed<br> 236*e5df9dc1SAsim Jamshed<div class="footer"> 237*e5df9dc1SAsim Jamshed <img src="back-arrow.jpg" width="2%" height="2%"><a href="http://mos.kaist.edu/index_man.html">Back to Index</a> 238*e5df9dc1SAsim Jamshed</div> 239*e5df9dc1SAsim Jamshed</div> 24091df013fSAsim Jamshed</body> 24191df013fSAsim Jamshed</html> 242
