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 90number of bytes read is returned. It is not an error if this 91number is smaller than the number of bytes requested; this 92may happen when the socket has fewer number of bytes 93buffered at that moment. On all errors, -1 is returned and 94<i>errno</i> is set appropriately.</p> 95 96<h2>ERRORS 97<a name="ERRORS"></a> 98</h2> 99 100 101<table width="100%" border="0" rules="none" frame="void" 102 cellspacing="0" cellpadding="0"> 103<tr valign="top" align="left"> 104<td width="11%"></td> 105<td width="12%"> 106 107 108<p style="margin-top: 1em"><b>EACCES</b></p></td> 109<td width="3%"></td> 110<td width="74%"> 111 112 113<p style="margin-top: 1em">The <i>mctx</i> argument is 114invalid.</p> </td></tr> 115<tr valign="top" align="left"> 116<td width="11%"></td> 117<td width="12%"> 118 119 120<p><b>EBADF</b></p></td> 121<td width="3%"></td> 122<td width="74%"> 123 124 125<p>The socket descriptor <i>sockid</i> is invalid.</p></td></tr> 126<tr valign="top" align="left"> 127<td width="11%"></td> 128<td width="12%"> 129 130 131<p><b>EINVAL</b></p></td> 132<td width="3%"></td> 133<td width="74%"> 134 135 136<p>The buffer management of the monitoring socket with 137<i>sockid</i> was already disabled.</p></td></tr> 138<tr valign="top" align="left"> 139<td width="11%"></td> 140<td width="12%"> 141 142 143<p><b>ENOTSOCK</b></p></td> 144<td width="3%"></td> 145<td width="74%"> 146 147 148<p>The socket referred to by <i>sockid</i> has invalid 149<i>type</i></p> </td></tr> 150<tr valign="top" align="left"> 151<td width="11%"></td> 152<td width="12%"> 153 154 155<p><b>ENOTCONN</b></p></td> 156<td width="3%"></td> 157<td width="74%"> 158 159 160<p>Th socket referred to by <i>sockid</i> is in a TCP state 161that disallows read operations.</p></td></tr> 162<tr valign="top" align="left"> 163<td width="11%"></td> 164<td width="12%"> 165 166 167<p><b>ENODATA</b></p></td> 168<td width="3%"></td> 169<td width="74%"> 170 171 172<p>The socket referred to by <i>sockid</i> does not have 173any available bytes in its buffer for reading.</p></td></tr> 174<tr valign="top" align="left"> 175<td width="11%"></td> 176<td width="12%"> 177 178 179<p><b>EPERM</b></p></td> 180<td width="3%"></td> 181<td width="74%"> 182 183 184<p>The caller is not permitted to access this function.</p></td></tr> 185</table> 186 187<h2>NOTES 188<a name="NOTES"></a> 189</h2> 190 191 192<p style="margin-left:11%; margin-top: 1em">Since TCP flow 193control applies between end-hosts, the receive buffer 194managed by mOS can become full while new packets continue to 195arrive. Silent TCP ring buffer overwriting is undesirable 196since the application may not notice the buffer overflow. 197Instead, mOS raises an error event to explicitly notify the 198application about the buffer overflow. The application can 199either drain the buffer by reading the data (by calling 200<b>mtcp_peek())</b> or enlarge the buffer (by calling 201<b>mtcp_setsockopt()).</b> Otherwise, the stack overwrites 202the buffer with the new data, and adjusts the internal peek 203pointer. To notify the application about the overwriting, 204<b>mtcp_peek()</b> fails right after overwriting. Subsequent 205function calls continue to read the data from the new 206position.</p> 207 208<h2>AUTHORS 209<a name="AUTHORS"></a> 210</h2> 211 212 213<p style="margin-left:11%; margin-top: 1em">mOS development 214team <[email protected]></p> 215 216<h2>SEE ALSO 217<a name="SEE ALSO"></a> 218</h2> 219 220 221 222<p style="margin-left:11%; margin-top: 1em"><b>mtcp_ppeek</b>(), 223<b>mtcp_socket</b>(), <b>mtcp_getsockopt</b>()</p> 224 225<h2>COLOPHON 226<a name="COLOPHON"></a> 227</h2> 228 229 230<p style="margin-left:11%; margin-top: 1em">This page is 231part of mOS release 0.3 <i>docs</i> section. A description 232of the project, and information about reporting bugs, can be 233found at http://mos.kaist.edu/.</p> 234<!-- <hr> --> 235<br> 236<div class="footer"> 237 <img src="back-arrow.jpg" width="2%" height="2%"><a href="http://mos.kaist.edu/index_man.html">Back to Index</a> 238</div> 239</div> 240</body> 241</html> 242
