1<!-- Creator : groff version 1.22.2 --> 2<!-- CreationDate: Thu Feb 2 22:36:46 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_getsockopt</title> 17<link rel="stylesheet" href="./common.css"> 18</head> 19<body> 20<div class="main"> 21<h1 align="center">mtcp_getsockopt</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="#AUTHORS">AUTHORS</a><br> 29<a href="#SEE ALSO">SEE ALSO</a><br> 30<a href="#COLOPHON">COLOPHON</a><br> 31<hr> 32--> 33 34<h2>NAME 35<a name="NAME"></a> 36</h2> 37 38 39 40<p style="margin-left:11%; margin-top: 1em">mtcp_getsockopt 41− get options on mTCP/mOS sockets</p> 42 43<h2>SYNOPSIS 44<a name="SYNOPSIS"></a> 45</h2> 46 47 48<p style="margin-left:11%; margin-top: 1em"><b>#include 49<mtcp_api.h></b></p> 50 51<p style="margin-left:11%; margin-top: 1em"><b>int 52mtcp_getsockopt(mctx_t</b> <i>mctx</i><b>, int</b> 53<i>sockid</i><b>, int</b> <i>level</i><b>, int</b> 54<i>optname</i><b>, const void *</b><i>optval</i><b>, 55socklen_t *</b><i>optlen</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_getsockopt</b>() 64manipulate options for the socket referred to by the 65<i>sockid</i> descriptor. These options may exist at 66multiple protocol levels. When manipulating socket options, 67the level at which the options resides and the name of the 68option must be specified. A user can use <b>SOL_SOCKET</b> 69<i>level</i> to adjust these options for mTCP endpoint 70applications; while <b>SOL_MONSOCKET</b> <i>level</i> can be 71used to adjust options for monitoring sockets.</p> 72 73<p style="margin-left:11%; margin-top: 1em">For 74<b>mtcp_getsockopt()</b> <i>optval</i> identifies the buffer 75in which the value for the requested option is to be 76returned and the <i>optlen</i> argument is updated to 77indicate the actual size of the <i>optval</i> returned. It 78is the user’s responsibility to allocate memory for 79both <i>optval</i> and <i>optlen</i> arguments.</p> 80 81<p style="margin-left:11%; margin-top: 1em">At the moment, 82mOS only provides one <i>optname</i> named <b>SO_ERROR</b> 83that can only be used for <b>mtcp_getsockopt()</b> function 84for SOL_SOCKET socket <i>level</i> with the specified option 85name returns the most recently recorded socket error for the 86particular connection (specific to the <i>sockid</i> socket 87descriptor).</p> 88 89<p style="margin-left:11%; margin-top: 1em">SOL_MONSOCKET 90socket <i>level</i> can be used by <b>mtcp_getsockopt()</b> 91to retrieve a number of socket options.</p> 92 93<table width="100%" border="0" rules="none" frame="void" 94 cellspacing="0" cellpadding="0"> 95<tr valign="top" align="left"> 96<td width="11%"></td> 97<td width="29%"> 98 99 100<p style="margin-top: 1em">MOS_FRAGINFO_CLIBUF</p></td> 101<td width="9%"></td> 102<td width="51%"> 103 104 105<p style="margin-top: 1em">Gives back offsets to fragments 106(non-contiguous data segments) currently stored in 107client’s TCP ring buffer. The <i>optval</i> is an 108array of struct tcp_ring_fragment which is defined as:</p></td></tr> 109</table> 110 111<p style="margin-left:49%; margin-top: 1em">struct 112tcp_ring_fragment { <br> 113uint64_t offset; <br> 114uint32_t len; <br> 115}</p> 116 117<p style="margin-left:49%; margin-top: 1em">where offset 118flow data starting from client’s TCP SYN sequence 119number, and len is the length of the tcp_ring_fragment. The 120<i>optval</i> holds the size of the array (in terms of the 121number of elements).</p> 122 123<table width="100%" border="0" rules="none" frame="void" 124 cellspacing="0" cellpadding="0"> 125<tr valign="top" align="left"> 126<td width="11%"></td> 127<td width="29%"> 128 129 130<p style="margin-top: 1em">MOS_FRAGINFO_SVRBUF</p></td> 131<td width="9%"></td> 132<td width="51%"> 133 134 135<p style="margin-top: 1em">Gives back offsets to fragments 136(non-contiguous data segments) currently stored in 137server’s TCP ring buffer. The <i>optval</i> is the 138array of struct tcp_ring_fragment</p></td></tr> 139</table> 140 141<p style="margin-left:49%; margin-top: 1em">where offset 142flow data starting from server’s TCP SYN sequence 143number, and len is the length of the tcp_ring_fragment. The 144<i>optlen</i> holds the size of the array (in terms of the 145number of elements).</p> 146 147<table width="100%" border="0" rules="none" frame="void" 148 cellspacing="0" cellpadding="0"> 149<tr valign="top" align="left"> 150<td width="11%"></td> 151<td width="23%"> 152 153 154<p style="margin-top: 1em">MOS_INFO_CLIBUF</p></td> 155<td width="15%"></td> 156<td width="51%"> 157 158 159<p style="margin-top: 1em">Returns meta-data regarding the 160client’s TCP ring buffer. This information is returned 161in the form of <i>optval</i> which is passed as struct 162tcp_buf_info.</p> </td></tr> 163</table> 164 165<p style="margin-left:49%; margin-top: 1em">struct 166tcp_buf_info { <br> 167/* The initial TCP sequence number <br> 168of TCP ring buffer. */ <br> 169uint32_t tcpbi_init_seq;</p> 170 171<p style="margin-left:49%; margin-top: 1em">/* TCP sequence 172number of the ’last <br> 173byte of payload that has already <br> 174been read by the end application’ <br> 175(applies in the case of embedded <br> 176monitor setup) */ <br> 177uint32_t tcpbi_last_byte_read;</p> 178 179<p style="margin-left:49%; margin-top: 1em">/* TCP sequence 180number of the ’last <br> 181byte of the payload that is <br> 182currently buffered and needs to <br> 183be read by the end application’ <br> 184(applies in the case of embedded <br> 185monitor setup). In case of standalone <br> 186monitors, tcpbi_last_byte_read = <br> 187tcpbi_next_byte_expected */ <br> 188uint32_t tcpbi_next_byte_expected;</p> 189 190<p style="margin-left:49%; margin-top: 1em">/* TCP sequence 191number of the ’last <br> 192byte of the payload that is <br> 193currently stored’ in the TCP <br> 194ring buffer. This value may be <br> 195greater than tcpbi_next_byte_expected <br> 196if packets arrive out of order. */ <br> 197uint32_t tcpbi_last_byte_received; <br> 198}</p> 199 200<p style="margin-left:49%; margin-top: 1em">The 201<i>optlen</i> value contains the sizeof(struct 202tcp_buf_info).</p> 203 204<table width="100%" border="0" rules="none" frame="void" 205 cellspacing="0" cellpadding="0"> 206<tr valign="top" align="left"> 207<td width="11%"></td> 208<td width="26%"> 209 210 211<p style="margin-top: 1em">MOS_INFO_SVRBUF</p></td> 212<td width="12%"></td> 213<td width="51%"> 214 215 216<p style="margin-top: 1em">Returns meta-data regarding the 217server’s TCP ring buffer. This information is returned 218in the form of <i>optval</i> which is passed as struct 219tcp_buf_info. The <i>optlen</i> value contains the 220sizeof(struct tcp_buf_info).</p></td></tr> 221<tr valign="top" align="left"> 222<td width="11%"></td> 223<td width="26%"> 224 225 226<p>MOS_TCP_STATE_CLI</p></td> 227<td width="12%"></td> 228<td width="51%"> 229 230 231<p>Returns the current emulated state of the client. The 232<i>optval</i> argument is a pointer to an int whereas the 233<i>optlen</i> argument contains the sizeof(int). The optval 234returns a value of type enum tcpstate which can carry any 235one of the following states.</p></td></tr> 236</table> 237 238<p style="margin-left:49%; margin-top: 1em">enum tcpstate { 239<br> 240TCP_CLOSED = 0, <br> 241TCP_LISTEN, <br> 242TCP_SYN_SENT, <br> 243TCP_SYN_RCVD, <br> 244TCP_ESTABLISHED, <br> 245TCP_FIN_WAIT_1, <br> 246TCP_FINE_WAIT_2, <br> 247TCP_CLOSE_WAIT, <br> 248TCP_CLOSING, <br> 249TCP_LAST_ACK, <br> 250TCP_TIME_WAIT <br> 251}</p> 252 253<table width="100%" border="0" rules="none" frame="void" 254 cellspacing="0" cellpadding="0"> 255<tr valign="top" align="left"> 256<td width="11%"></td> 257<td width="26%"> 258 259 260<p style="margin-top: 1em">MOS_TCP_STATE_SVR</p></td> 261<td width="12%"></td> 262<td width="51%"> 263 264 265<p style="margin-top: 1em">Returns the current emulated 266state of the server. The <i>optval</i> argument is a pointer 267to an int whereas the <i>optlen</i> argument contains the 268sizeof(int). The optval returns a value of type enum 269tcpstate.</p> </td></tr> 270</table> 271 272<p style="margin-left:11%; margin-top: 1em">Both the 273functions take an additional argument named <i>mctx</i> that 274represent the per-core mTCP context in an application (see 275<b>mtcp_create_context()</b> for details).</p> 276 277<h2>RETURN VALUE 278<a name="RETURN VALUE"></a> 279</h2> 280 281 282<p style="margin-left:11%; margin-top: 1em">Returns 0 on 283success; -1 on failure. In case of failure, <i>errno</i> is 284set appropriately.</p> 285 286<h2>ERRORS 287<a name="ERRORS"></a> 288</h2> 289 290 291<table width="100%" border="0" rules="none" frame="void" 292 cellspacing="0" cellpadding="0"> 293<tr valign="top" align="left"> 294<td width="11%"></td> 295<td width="12%"> 296 297 298<p style="margin-top: 1em"><b>EACCES</b></p></td> 299<td width="3%"></td> 300<td width="74%"> 301 302 303<p style="margin-top: 1em"><i>mctx</i> is not valid.</p></td></tr> 304<tr valign="top" align="left"> 305<td width="11%"></td> 306<td width="12%"> 307 308 309<p><b>EBADF</b></p></td> 310<td width="3%"></td> 311<td width="74%"> 312 313 314<p><i>sockid</i> is not a valid socket descriptor.</p></td></tr> 315<tr valign="top" align="left"> 316<td width="11%"></td> 317<td width="12%"> 318 319 320<p><b>ENOTSOCK</b></p></td> 321<td width="3%"></td> 322<td width="74%"> 323 324 325<p>The socket referred to by <i>sockid</i> is not 326valid.</p> </td></tr> 327<tr valign="top" align="left"> 328<td width="11%"></td> 329<td width="12%"> 330 331 332<p><b>ENOSYS</b></p></td> 333<td width="3%"></td> 334<td width="74%"> 335 336 337<p>Either the <i>level</i> or the <i>optname</i> is not 338implemented.</p> </td></tr> 339<tr valign="top" align="left"> 340<td width="11%"></td> 341<td width="12%"> 342 343 344<p><b>EPERM</b></p></td> 345<td width="3%"></td> 346<td width="74%"> 347 348 349<p>Permission to access a socket option is denied.</p></td></tr> 350</table> 351 352<h2>AUTHORS 353<a name="AUTHORS"></a> 354</h2> 355 356 357<p style="margin-left:22%; margin-top: 1em">mOS development 358team <[email protected]></p> 359 360<!-----------------------------------------------------------> 361<h2>EXAMPLES 362 <a name="EXAMPLES"></a> 363</h2> 364 365<p style="margin-left:11%; margin-top: 1em"> 366 <a href="http://mos.kaist.edu/guide/programmer/05_api_example.html#monitoring-fragmented-tcp-segments"> 367 http://mos.kaist.edu/guide/programmer/05_api_example.html#monitoring-fragmented-tcp-segments 368 </a><br> 369 <a href="http://mos.kaist.edu/guide/programmer/05_api_example.html#monitoring-tcp-connection-state"> 370 http://mos.kaist.edu/guide/programmer/05_api_example.html#monitoring-tcp-connection-state 371 </a> 372</p> 373<!-----------------------------------------------------------> 374 375<h2>SEE ALSO 376<a name="SEE ALSO"></a> 377</h2> 378 379 380 381<p style="margin-left:11%; margin-top: 1em"><b>mtcp_socket</b>(), 382<b>mtcp_setsockopt</b>()</p> 383 384<h2>COLOPHON 385<a name="COLOPHON"></a> 386</h2> 387 388 389<p style="margin-left:11%; margin-top: 1em">This page is 390part of mOS release 0.3 <i>docs</i> section. A description 391of the project, and information about reporting bugs, can be 392found at http://mos.kaist.edu/.</p> 393<!-- <hr> --> 394<br> 395<div class="footer"> 396 <img src="back-arrow.jpg" width="2%" height="2%"><a href="http://mos.kaist.edu/index_man.html">Back to Index</a> 397</div> 398</div> 399</body> 400</html> 401
