1<!-- Creator : groff version 1.22.2 --> 2<!-- CreationDate: Thu Feb 2 01:56:08 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_socket</title> 17<link rel="stylesheet" href="./common.css"> 18</head> 19<body> 20<div class="main"> 21<h1 align="center">mtcp_socket</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<p style="margin-left:11%; margin-top: 1em">mtcp_socket 40− instantiate an mTCP socket for communication or 41monitoring</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_socket(mctx_t</b> <i>mctx</i><b>, int</b> 53<i>domain</i><b>, int</b> <i>type</i><b>, int</b> 54<i>protocol</i><b>);</b></p> 55 56<h2>DESCRIPTION 57<a name="DESCRIPTION"></a> 58</h2> 59 60 61 62<p style="margin-left:11%; margin-top: 1em"><b>mtcp_socket</b>() 63can be used to create either a communication endpoint or a 64middlebox viewpoint for mTCP-based network connection. In 65many ways, it behaves similar to a BSD socket. An 66<b>mtcp_socket</b>() call takes an additional argument named 67<i>mctx</i> that represents the per-core mTCP context in an 68application (see <b>mtcp_create_context()</b> for 69details).</p> 70 71<p style="margin-left:11%; margin-top: 1em">The 72<i>domain</i> argument is used to specify a communication 73domain; in mTCP, the only available protocol family for the 74domain is <b>AF_INET</b> which represents IPv4 Internet 75protocol.</p> 76 77<p style="margin-left:11%; margin-top: 1em">The socket has 78the indicated <i>type ,</i> which specifies the 79communication semantics. Currently defined types in mTCP 80are:</p> 81 82<table width="100%" border="0" rules="none" frame="void" 83 cellspacing="0" cellpadding="0"> 84<tr valign="top" align="left"> 85<td width="11%"></td> 86<td width="35%"> 87 88 89<p><b>SOCK_STREAM</b></p></td> 90<td width="3%"></td> 91<td width="51%"> 92 93 94<p>Provides sequenced, reliable, full-duplex, 95connection-based byte streams.</p></td></tr> 96<tr valign="top" align="left"> 97<td width="11%"></td> 98<td width="35%"> 99 100 101<p><b>MOS_SOCK_MONITOR_STREAM</b></p></td> 102<td width="3%"></td> 103<td width="51%"> 104 105 106<p>Provides a middlebox viewpoint for ongoing 107connection-oriented flows.</p></td></tr> 108<tr valign="top" align="left"> 109<td width="11%"></td> 110<td width="35%"> 111 112 113<p><b>MOS_SOCK_MONITOR_RAW</b></p></td> 114<td width="3%"></td> 115<td width="51%"> 116 117 118<p>Provides a middlebox viewpoint for connection-less 119flows. This can be used as a tap to glean unsynchronized TCP 120packets (no connection handshakes) or any other IP 121datagrams.</p> </td></tr> 122</table> 123 124<p style="margin-left:11%; margin-top: 1em">The 125<i>protocol</i> argument represents the specific protocol ID 126to be used with the socket. mTCP assumes this argument to be 1270 (since it only supports single-protocol sockets).</p> 128 129<p style="margin-left:11%; margin-top: 1em">Sockets of type 130<b>SOCK_STREAM</b> represent full-duplex bytestreams. A 131stream socket must be in <b>ESTABLISHED</b> TCP state before 132data can be sent or received on it. A connection to another 133peer endpoint can be created with an <b>mtcp_connect()</b> 134call. Once connected, data may be exchanged using 135<b>mtcp_read()</b> and <b>mtcp_write()</b> calls. When a 136session needs to be terminated, <b>mtcp_close()</b> can be 137called. Socket operations can be manipulated using socket 138level options via <b>mtcp_setsockopt()</b> and 139<b>mtcp_getsockopt()</b> function calls. mTCP sockets run in 140non-blocking mode by default.</p> 141 142<p style="margin-left:11%; margin-top: 1em">Sockets of type 143<b>MOS_SOCK_MONITOR_STREAM</b> represent middlebox viewpoint 144of full-duplex bytestreams. A monitoring stream socket must 145be in <b>ESTABLISHED</b> TCP state before TCP bytestreams 146can be snooped from the TCP ring buffers of either client or 147server TCP emulated stacks using either <b>mtcp_peek()</b> 148or <b>mtcp_ppeek()</b> functions. A stream monitoring socket 149can be bound with a connection filter using 150<b>mtcp_bind_monitor_filter()</b> function. The user can use 151<b>mtcp_register_callback()</b> function to register the 152socket with relevant mOS events. These can either be 153built-in events or user-defined (custom) events. Like 154<b>SOCK_STREAM</b> sockets, operations can be manipulated 155using socket level options via <b>mtcp_setsockopt()</b> and 156<b>mtcp_getsockopt()</b> function calls. A call to 157<b>mtcp_close()</b> function unregisters all flow events for 158the socket, but it does not terminate the ongoing 159connection.</p> 160 161<p style="margin-left:11%; margin-top: 1em">Sockets of type 162<b>MOS_SOCK_MONITOR_RAW</b> can be used to monitor network 163traffic without connection semantics. Only packet-based 164functions such as <b>mtcp_getlastpkt()</b> can be utilized 165using these sockets.</p> 166 167<h2>RETURN VALUE 168<a name="RETURN VALUE"></a> 169</h2> 170 171 172<p style="margin-left:11%; margin-top: 1em">Returns an mTCP 173descriptor ID on success; -1 on failure. In case of failure, 174<i>errno</i> is set appropriately. Please note that each 175mTCP context (referred to by <i>mctx</i> ) creates its own 176dedicated pool of sockets.</p> 177 178<h2>ERRORS 179<a name="ERRORS"></a> 180</h2> 181 182 183<table width="100%" border="0" rules="none" frame="void" 184 cellspacing="0" cellpadding="0"> 185<tr valign="top" align="left"> 186<td width="11%"></td> 187<td width="18%"> 188 189 190<p style="margin-top: 1em"><b>EACCES</b></p></td> 191<td width="5%"></td> 192<td width="66%"> 193 194 195<p style="margin-top: 1em"><i>mctx</i> is not valid.</p></td></tr> 196<tr valign="top" align="left"> 197<td width="11%"></td> 198<td width="18%"> 199 200 201<p><b>EAFNOSUPPORT</b></p></td> 202<td width="5%"></td> 203<td width="66%"> 204 205 206<p><i>domain</i> is not supported.</p></td></tr> 207<tr valign="top" align="left"> 208<td width="11%"></td> 209<td width="18%"> 210 211 212<p><b>EINVAL</b></p></td> 213<td width="5%"></td> 214<td width="66%"> 215 216 217<p>The socket <i>type</i> is invalid.</p></td></tr> 218<tr valign="top" align="left"> 219<td width="11%"></td> 220<td width="18%"> 221 222 223<p><b>ENFILE</b></p></td> 224<td width="5%"></td> 225<td width="66%"> 226 227 228<p>No socket descriptor is available in the pool at the 229moment.</p> </td></tr> 230</table> 231 232<h2>AUTHORS 233<a name="AUTHORS"></a> 234</h2> 235 236 237<p style="margin-left:11%; margin-top: 1em">mOS development 238team <[email protected]></p> 239 240<!-----------------------------------------------------------> 241<h2>EXAMPLES 242<a name="EXAMPLES"></a> 243</h2> 244 245<p style="margin-left:11%; margin-top: 1em"> 246 <a href="http://mos.kaist.edu/guide/programmer/05_api_example.html#per-core-initialization-routine"> 247 http://mos.kaist.edu/guide/programmer/05_api_example.html#per-core-initialization-routine 248 </a> 249</p> 250<!-----------------------------------------------------------> 251 252 253<h2>SEE ALSO 254<a name="SEE ALSO"></a> 255</h2> 256 257 258 259<p style="margin-left:11%; margin-top: 1em"><b>mtcp_bind</b>(), 260<b>mtcp_listen</b>(), <b>mtcp_accept</b>(), 261<b>mtcp_connect</b>(), <b>mtcp_read</b>(), 262<b>mtcp_write</b>(), <b>mtcp_peek</b>(), 263<b>mtcp_ppeek</b>(), <b>mtcp_bind_monitor_filter</b>(), 264<b>mtcp_register_callback</b>(), 265<b>mtcp_getlastpkt</b>()</p> 266 267<h2>COLOPHON 268<a name="COLOPHON"></a> 269</h2> 270 271 272<p style="margin-left:11%; margin-top: 1em">This page is 273part of mOS release 0.3 <i>docs</i> section. A description 274of the project, and information about reporting bugs, can be 275found at http://mos.kaist.edu/.</p> 276<!-- <hr> --> 277<br> 278<div class="footer"> 279 <img src="back-arrow.jpg" width="2%" height="2%"><a href="http://mos.kaist.edu/index_man.html">Back to Index</a> 280</div> 281</div> 282</body> 283</html> 284
