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 18</head> 19<body> 20 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 33<hr> 34 35 36<h2>NAME 37<a name="NAME"></a> 38</h2> 39 40 41<p style="margin-left:11%; margin-top: 1em">mtcp_peek 42− Peek into the bytestream from a monitoring 43socket</p> 44 45<h2>SYNOPSIS 46<a name="SYNOPSIS"></a> 47</h2> 48 49 50<p style="margin-left:11%; margin-top: 1em"><b>#include 51<mos_api.h></b></p> 52 53<p style="margin-left:11%; margin-top: 1em"><b>ssize_t 54mtcp_peek(mctx_t</b> <i>mctx</i><b>, int</b> 55<i>sockid</i><b>, int</b> <i>side</i><b>, char 56*</b><i>buf</i><b>, size_t</b> <i>len</i><b>);</b></p> 57 58<h2>DESCRIPTION 59<a name="DESCRIPTION"></a> 60</h2> 61 62 63 64<p style="margin-left:11%; margin-top: 1em"><b>mtcp_peek</b>() 65can be used to peek up to <i>len</i> number of bytes from a 66monitoring socket via socket descriptor <i>sockid</i> into 67the buffer (unfragmented) starting at <i>buf.</i> It is the 68responsibility of the user to allocate memory for <i>buf</i> 69array.</p> 70 71<p style="margin-left:11%; margin-top: 1em">For cases when 72the total number of buffered unread bytes in the socket are 73less than <i>len,</i> <b>mtcp_peek()</b> copies entire data 74to <i>buf</i> and returns the actual number of bytes that 75can be used by the application.</p> 76 77<p style="margin-left:11%; margin-top: 1em">An 78<b>mtcp_peek</b>() call takes two additional argument named 79<i>mctx ,</i> that represents the per-core mTCP context in 80an application (see <b>mtcp_create_context()</b> for 81details); and <i>side</i> that informs the stack whether it 82needs to peek the client (MOS_SIDE_CLI) or server 83(MOS_SIDE_SVR) side.</p> 84 85<h2>RETURN VALUE 86<a name="RETURN VALUE"></a> 87</h2> 88 89 90<p style="margin-left:11%; margin-top: 1em">On success, the 91number of bytes read is returned. It is not an error if this 92number is smaller than the number of bytes requested; this 93may happen when the socket has fewer number of bytes 94buffered at that moment. On all errors, -1 is returned and 95<i>errno</i> is set appropriately.</p> 96 97<h2>ERRORS 98<a name="ERRORS"></a> 99</h2> 100 101 102<table width="100%" border="0" rules="none" frame="void" 103 cellspacing="0" cellpadding="0"> 104<tr valign="top" align="left"> 105<td width="11%"></td> 106<td width="12%"> 107 108 109<p style="margin-top: 1em"><b>EACCES</b></p></td> 110<td width="3%"></td> 111<td width="74%"> 112 113 114<p style="margin-top: 1em">The <i>mctx</i> argument is 115invalid.</p> </td></tr> 116<tr valign="top" align="left"> 117<td width="11%"></td> 118<td width="12%"> 119 120 121<p><b>EBADF</b></p></td> 122<td width="3%"></td> 123<td width="74%"> 124 125 126<p>The socket descriptor <i>sockid</i> is invalid.</p></td></tr> 127<tr valign="top" align="left"> 128<td width="11%"></td> 129<td width="12%"> 130 131 132<p><b>EINVAL</b></p></td> 133<td width="3%"></td> 134<td width="74%"> 135 136 137<p>The buffer management of the monitoring socket with 138<i>sockid</i> was already disabled.</p></td></tr> 139<tr valign="top" align="left"> 140<td width="11%"></td> 141<td width="12%"> 142 143 144<p><b>ENOTSOCK</b></p></td> 145<td width="3%"></td> 146<td width="74%"> 147 148 149<p>The socket referred to by <i>sockid</i> has invalid 150<i>type</i></p> </td></tr> 151<tr valign="top" align="left"> 152<td width="11%"></td> 153<td width="12%"> 154 155 156<p><b>ENOTCONN</b></p></td> 157<td width="3%"></td> 158<td width="74%"> 159 160 161<p>Th socket referred to by <i>sockid</i> is in a TCP state 162that disallows read operations.</p></td></tr> 163<tr valign="top" align="left"> 164<td width="11%"></td> 165<td width="12%"> 166 167 168<p><b>ENODATA</b></p></td> 169<td width="3%"></td> 170<td width="74%"> 171 172 173<p>The socket referred to by <i>sockid</i> does not have 174any available bytes in its buffer for reading.</p></td></tr> 175<tr valign="top" align="left"> 176<td width="11%"></td> 177<td width="12%"> 178 179 180<p><b>EPERM</b></p></td> 181<td width="3%"></td> 182<td width="74%"> 183 184 185<p>The caller is not permitted to access this function.</p></td></tr> 186</table> 187 188<h2>NOTES 189<a name="NOTES"></a> 190</h2> 191 192 193<p style="margin-left:11%; margin-top: 1em">Since TCP flow 194control applies between end-hosts, the receive buffer 195managed by mOS can become full while new packets continue to 196arrive. Silent TCP ring buffer overwriting is undesirable 197since the application may not notice the buffer overflow. 198Instead, mOS raises an error event to explicitly notify the 199application about the buffer overflow. The application can 200either drain the buffer by reading the data (by calling 201<b>mtcp_peek())</b> or enlarge the buffer (by calling 202<b>mtcp_setsockopt()).</b> Otherwise, the stack overwrites 203the buffer with the new data, and adjusts the internal peek 204pointer. To notify the application about the overwriting, 205<b>mtcp_peek()</b> fails right after overwriting. Subsequent 206function calls continue to read the data from the new 207position.</p> 208 209<h2>AUTHORS 210<a name="AUTHORS"></a> 211</h2> 212 213 214<p style="margin-left:11%; margin-top: 1em">mOS development 215team <[email protected]></p> 216 217<h2>SEE ALSO 218<a name="SEE ALSO"></a> 219</h2> 220 221 222 223<p style="margin-left:11%; margin-top: 1em"><b>mtcp_ppeek</b>(), 224<b>mtcp_socket</b>(), <b>mtcp_getsockopt</b>()</p> 225 226<h2>COLOPHON 227<a name="COLOPHON"></a> 228</h2> 229 230 231<p style="margin-left:11%; margin-top: 1em">This page is 232part of mOS release 0.3 <i>docs</i> section. A description 233of the project, and information about reporting bugs, can be 234found at http://mos.kaist.edu/.</p> 235<hr> 236</body> 237</html> 238