1<!-- Creator : groff version 1.22.2 --> 2<!-- CreationDate: Fri Feb 3 15:23:32 2017 --> 3<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 4"http://www.w3.org/TR/html4/loose.dtd"> 5<html> 6<head> 7<meta name="generator" content="groff -Thtml, see www.gnu.org"> 8<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 9<meta name="Content-Style" content="text/css"> 10<style type="text/css"> 11 p { margin-top: 0; margin-bottom: 0; vertical-align: top } 12 pre { margin-top: 0; margin-bottom: 0; vertical-align: top } 13 table { margin-top: 0; margin-bottom: 0; vertical-align: top } 14 h1 { text-align: center } 15</style> 16<title>mtcp_peek</title> 17<link rel="stylesheet" href="./common.css"> 18</head> 19<body> 20<div class="main"> 21<h1 align="center">mtcp_peek</h1> 22<!-- 23<a href="#NAME">NAME</a><br> 24<a href="#SYNOPSIS">SYNOPSIS</a><br> 25<a href="#DESCRIPTION">DESCRIPTION</a><br> 26<a href="#RETURN VALUE">RETURN VALUE</a><br> 27<a href="#ERRORS">ERRORS</a><br> 28<a href="#NOTES">NOTES</a><br> 29<a href="#AUTHORS">AUTHORS</a><br> 30<a href="#SEE ALSO">SEE ALSO</a><br> 31<a href="#COLOPHON">COLOPHON</a><br> 32<hr> 33--> 34 35<h2>NAME 36<a name="NAME"></a> 37</h2> 38 39 40<p style="margin-left:11%; margin-top: 1em">mtcp_peek 41− Peek into the bytestream from a monitoring 42socket</p> 43 44<h2>SYNOPSIS 45<a name="SYNOPSIS"></a> 46</h2> 47 48 49<p style="margin-left:11%; margin-top: 1em"><b>#include 50<mos_api.h></b></p> 51 52<p style="margin-left:11%; margin-top: 1em"><b>ssize_t 53mtcp_peek(mctx_t</b> <i>mctx</i><b>, int</b> 54<i>sockid</i><b>, int</b> <i>side</i><b>, char 55*</b><i>buf</i><b>, size_t</b> <i>len</i><b>);</b></p> 56 57<h2>DESCRIPTION 58<a name="DESCRIPTION"></a> 59</h2> 60 61 62 63<p style="margin-left:11%; margin-top: 1em"><b>mtcp_peek</b>() 64can be used to peek up to <i>len</i> number of bytes from a 65monitoring socket via socket descriptor <i>sockid</i> into 66the buffer (unfragmented) starting at <i>buf.</i> It is the 67responsibility of the user to allocate memory for <i>buf</i> 68array.</p> 69 70<p style="margin-left:11%; margin-top: 1em">For cases when 71the total number of buffered unread bytes in the socket are 72less than <i>len,</i> <b>mtcp_peek()</b> copies entire data 73to <i>buf</i> and returns the actual number of bytes that 74can be used by the application.</p> 75 76<p style="margin-left:11%; margin-top: 1em">An 77<b>mtcp_peek</b>() call takes two additional argument named 78<i>mctx ,</i> that represents the per-core mTCP context in 79an application (see <b>mtcp_create_context()</b> for 80details); and <i>side</i> that informs the stack whether it 81needs to peek the client (MOS_SIDE_CLI) or server 82(MOS_SIDE_SVR) side.</p> 83 84<h2>RETURN VALUE 85<a name="RETURN VALUE"></a> 86</h2> 87 88 89<p style="margin-left:11%; margin-top: 1em">On success, the 90 number of bytes read is returned. It is not an error if this 91 number is smaller than the number of bytes requested; this 92 may happen when the socket has fewer number of bytes 93 buffered at that moment. On all errors except <i>ENODATA</i>, 94 -1 is returned and <i>errno</i> is set appropriately. 95 On <i>ENODATA</i> error, if the buffer outrun was occured, 96 it would return <i>(-1) * (the number of bytes overwritten 97 on the buffer)</i>. 98</p> 99 100 101<h2>ERRORS 102<a name="ERRORS"></a> 103</h2> 104 105 106<table width="100%" border="0" rules="none" frame="void" 107 cellspacing="0" cellpadding="0"> 108<tr valign="top" align="left"> 109<td width="11%"></td> 110<td width="12%"> 111 112 113<p style="margin-top: 1em"><b>EACCES</b></p></td> 114<td width="3%"></td> 115<td width="74%"> 116 117 118<p style="margin-top: 1em">The <i>mctx</i> argument is 119invalid.</p> </td></tr> 120<tr valign="top" align="left"> 121<td width="11%"></td> 122<td width="12%"> 123 124 125<p><b>EBADF</b></p></td> 126<td width="3%"></td> 127<td width="74%"> 128 129 130<p>The socket descriptor <i>sockid</i> is invalid.</p></td></tr> 131<tr valign="top" align="left"> 132<td width="11%"></td> 133<td width="12%"> 134 135 136<p><b>EINVAL</b></p></td> 137<td width="3%"></td> 138<td width="74%"> 139 140 141<p>The buffer management of the monitoring socket with 142<i>sockid</i> was already disabled.</p></td></tr> 143<tr valign="top" align="left"> 144<td width="11%"></td> 145<td width="12%"> 146 147 148<p><b>ENOTSOCK</b></p></td> 149<td width="3%"></td> 150<td width="74%"> 151 152 153<p>The socket referred to by <i>sockid</i> has invalid 154<i>type</i></p> </td></tr> 155<tr valign="top" align="left"> 156<td width="11%"></td> 157<td width="12%"> 158 159 160<p><b>ENOTCONN</b></p></td> 161<td width="3%"></td> 162<td width="74%"> 163 164 165<p>Th socket referred to by <i>sockid</i> is in a TCP state 166that disallows read operations.</p></td></tr> 167<tr valign="top" align="left"> 168<td width="11%"></td> 169<td width="12%"> 170 171 172<p><b>ENODATA</b></p></td> 173<td width="3%"></td> 174<td width="74%"> 175 176 177<p>The socket referred to by <i>sockid</i> does not have 178any available bytes in its buffer for reading.</p></td></tr> 179<tr valign="top" align="left"> 180<td width="11%"></td> 181<td width="12%"> 182 183 184<p><b>EPERM</b></p></td> 185<td width="3%"></td> 186<td width="74%"> 187 188 189<p>The caller is not permitted to access this function.</p></td></tr> 190</table> 191 192<h2>NOTES 193<a name="NOTES"></a> 194</h2> 195 196 197<p style="margin-left:11%; margin-top: 1em">Since TCP flow 198control applies between end-hosts, the receive buffer 199managed by mOS can become full while new packets continue to 200arrive. Silent TCP ring buffer overwriting is undesirable 201since the application may not notice the buffer overflow. 202Instead, mOS raises an error event to explicitly notify the 203application about the buffer overflow. The application can 204either drain the buffer by reading the data (by calling 205<b>mtcp_peek())</b> or enlarge the buffer (by calling 206<b>mtcp_setsockopt()).</b> Otherwise, the stack overwrites 207the buffer with the new data, and adjusts the internal peek 208pointer. To notify the application about the overwriting, 209<b>mtcp_peek()</b> fails right after overwriting. Subsequent 210function calls continue to read the data from the new 211position.</p> 212 213<h2>AUTHORS 214<a name="AUTHORS"></a> 215</h2> 216 217 218<p style="margin-left:11%; margin-top: 1em">mOS development 219team <[email protected]></p> 220 221 222<!-----------------------------------------------------------> 223<h2>EXAMPLES 224 <a name="EXAMPLES"></a> 225</h2> 226 227<p style="margin-left:11%; margin-top: 1em"> 228 <a href="http://mos.kaist.edu/guide/programmer/05_api_example.html#monitoring-reassembled-tcp-payload"> 229 http://mos.kaist.edu/guide/programmer/05_api_example.html#monitoring-reassembled-tcp-payload 230 </a> 231</p> 232<!-----------------------------------------------------------> 233 234 235<h2>SEE ALSO 236<a name="SEE ALSO"></a> 237</h2> 238 239 240 241<p style="margin-left:11%; margin-top: 1em"><b>mtcp_ppeek</b>(), 242<b>mtcp_socket</b>(), <b>mtcp_getsockopt</b>()</p> 243 244<h2>COLOPHON 245<a name="COLOPHON"></a> 246</h2> 247 248 249<p style="margin-left:11%; margin-top: 1em">This page is 250part of mOS release 0.3 <i>docs</i> section. A description 251of the project, and information about reporting bugs, can be 252found at http://mos.kaist.edu/.</p> 253<!-- <hr> --> 254<br> 255<div class="footer"> 256 <img src="back-arrow.jpg" width="2%" height="2%"><a href="http://mos.kaist.edu/index_man.html">Back to Index</a> 257</div> 258</div> 259</body> 260</html> 261
