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