mtcp_socket

NAME

mtcp_socket − instantiate an mTCP socket for communication or monitoring

SYNOPSIS

#include <mtcp_api.h>

int mtcp_socket(mctx_t mctx, int domain, int type, int protocol);

DESCRIPTION

mtcp_socket() can be used to create either a communication endpoint or a middlebox viewpoint for mTCP-based network connection. In many ways, it behaves similar to a BSD socket. An mtcp_socket() call takes an additional argument named mctx that represents the per-core mTCP context in an application (see mtcp_create_context() for details).

The domain argument is used to specify a communication domain; in mTCP, the only available protocol family for the domain is AF_INET which represents IPv4 Internet protocol.

The socket has the indicated type , which specifies the communication semantics. Currently defined types in mTCP are:

	SOCK_STREAM		Provides sequenced, reliable, full-duplex, connection-based byte streams.
	MOS_SOCK_MONITOR_STREAM		Provides a middlebox viewpoint for ongoing connection-oriented flows.
	MOS_SOCK_MONITOR_RAW		Provides a middlebox viewpoint for connection-less flows. This can be used as a tap to glean unsynchronized TCP packets (no connection handshakes) or any other IP datagrams.

The protocol argument represents the specific protocol ID to be used with the socket. mTCP assumes this argument to be 0 (since it only supports single-protocol sockets).

Sockets of type SOCK_STREAM represent full-duplex bytestreams. A stream socket must be in ESTABLISHED TCP state before data can be sent or received on it. A connection to another peer endpoint can be created with an mtcp_connect() call. Once connected, data may be exchanged using mtcp_read() and mtcp_write() calls. When a session needs to be terminated, mtcp_close() can be called. Socket operations can be manipulated using socket level options via mtcp_setsockopt() and mtcp_getsockopt() function calls. mTCP sockets run in non-blocking mode by default.

Sockets of type MOS_SOCK_MONITOR_STREAM represent middlebox viewpoint of full-duplex bytestreams. A monitoring stream socket must be in ESTABLISHED TCP state before TCP bytestreams can be snooped from the TCP ring buffers of either client or server TCP emulated stacks using either mtcp_peek() or mtcp_ppeek() functions. A stream monitoring socket can be bound with a connection filter using mtcp_bind_monitor_filter() function. The user can use mtcp_register_callback() function to register the socket with relevant mOS events. These can either be built-in events or user-defined (custom) events. Like SOCK_STREAM sockets, operations can be manipulated using socket level options via mtcp_setsockopt() and mtcp_getsockopt() function calls. A call to mtcp_close() function unregisters all flow events for the socket, but it does not terminate the ongoing connection.

Sockets of type MOS_SOCK_MONITOR_RAW can be used to monitor network traffic without connection semantics. Only packet-based functions such as mtcp_getlastpkt() can be utilized using these sockets.

RETURN VALUE

Returns an mTCP descriptor ID on success; -1 on failure. In case of failure, errno is set appropriately. Please note that each mTCP context (referred to by mctx ) creates its own dedicated pool of sockets.

ERRORS

	EACCES		mctx is not valid.
	EAFNOSUPPORT		domain is not supported.
	EINVAL		The socket type is invalid.
	ENFILE		No socket descriptor is available in the pool at the moment.

AUTHORS

mOS development team <mtcp-user@list.ndsl.kaist.edu>

EXAMPLES

http://mos.kaist.edu/guide/programmer/05_api_example.html#per-core-initialization-routine

COLOPHON

This page is part of mOS release 0.3 docs section. A description of the project, and information about reporting bugs, can be found at http://mos.kaist.edu/.