VFER: src/vfer_api.h File Reference

#define SET_DF_BIT	(	SOCKFD,
		RET		)	{ RET = -1; }

Definition at line 57 of file vfer_api.h.

typedef void* vfer_trnsm_arg

generic transmit function argument

Definition at line 69 of file vfer_api.h.

typedef int(*) vfer_trnsm_fn(vfer_trnsm_arg sock, void *buf, size_t len)

generic transmit function type

vfer__recvfile() and vfer__sendfile can both use arbitrary function to send and retrieve packets. Because different transmit functions work with different sockets, the transmit functions are casted to this generic type before they are passed to vfer__recvfile() and vfer__sendfile().

Currently this technique is used to prevent code duplication between vls_sendfile() and vfer_sendfile() and vls_recvfile() and vfer_recvfile().

Definition at line 81 of file vfer_api.h.

int vfer__recvfile	(	vfer_trnsm_fn	fn,
		vfer_trnsm_arg	arg,
		uint32_t	frame_size,
		int	fd,
		off_t	offset,
		size_t	size
	)

Reads size bytes from socket arg using function fn and writes them into the file described by fd at offset offset.

Parameters:

`[in]`	fn	receive function to use
`[in]`	arg	socket argument to pass to receive function
`[in]`	frame_size	maximum frame size that fn can handle for arg
`[out]`	fd	file descriptor to write received data to
`[in]`	offset	writing starting position in the file
`[in]`	size	number of bytes to read

Returns:

Returns the actual number of bytes read on success (a positive number)
Every error code that fn can return
VFER_INVAL invalid offset or size

Definition at line 1006 of file vfer_api.c.

int vfer__sendfile	(	vfer_trnsm_fn	fn,
		vfer_trnsm_arg	arg,
		int	frame_size,
		int	fd,
		off_t	offset,
		size_t	size
	)

Mmap the file described by fd and send size bytes of data starting at offset into socket arg using function fn.

Parameters:

`[in]`	fn	send function to use
`[in]`	arg	socket argument to pass to send function
`[in]`	frame_size	maximum frame size that fn can handle for arg
`[in]`	fd	file descriptor to map into mem and to send
`[in]`	offset	writing starting position in the file
`[in]`	size	number of bytes to send

Returns:

Returns the actual number of bytes sent on success
VFER_BADFD error using mmap on fd
VFER_INVAL invalid offset or size
Every error code that fn can return

Definition at line 873 of file vfer_api.c.

vfer_fd vfer_accept	(	vfer_fd	vfd,
		struct sockaddr *	addr,
		socklen_t *	len
	)

For a socket in the listening state, removes the first pending connection request from the queue and establishes a connection on that socket.

The call returns a socket identifier for use with the connection. If, on entry, the listening socket is marked with an error, this call immediately returns VFER_BADSOCK without changing the error status.

Parameters:

	vfd	vfer socket identifier
	addr	pointer to an address structure to be filled in with information
	len	length of the address strucutre

Returns:

a positive vfer socket identifier on success
VFER_BADSOCK bad vfd argument
VFER_TIMEOUT accept connection attempt timedout
VFER_NOACCEPT socket is not able to perform an accept because it is not listening,
VFER_NOTSTREAM socket is not of type SOCK_STREAM
VFER_WOULDBLOCK socket is non-blocking and there are no waiting connections
VFER_IMPL underlying socket error

Definition at line 448 of file vfer_api.c.

int vfer_bind	(	vfer_fd	vfd,
		struct sockaddr *	addr,
		int	len
	)

Associate the socket with the specified addr.

This call returns BADSOCK immediately without changing the error status of sock if sock is marked with an error on entry.

Parameters:

	vfd	vfer socket identifier
	addr	a peer address
	len	length of addr

Returns:

0 on success
VFER_BADSOCK bad vfd argument
VFER_NOBIND socket is not able to perform a bind because it is bound
VFER_BADADDR address is unavailable or in use.

Definition at line 298 of file vfer_api.c.

int vfer_close ( vfer_fd vfd )

Closes the socket identified by a vfer identifier.

This call returns immediately without changing the error status of sock if sock is marked with an error on entry.

Parameters:

vfd

vfer socket identifier

Returns:

0 on success
VFER_BADSOCK bad vfd argument
VFER_IMPL failure closing underlying socket descriptor

Definition at line 189 of file vfer_api.c.

int vfer_connect	(	vfer_fd	vfd,
		const struct sockaddr *	serv_addr,
		int	addrlen
	)

Establishes a connection with a peer.

This works equally for a SOCK_DGRAM or SOCK_STREAM (if implemented): attempts a connection operation with the peer defined by addr and len. This call returns immediately without changing the error status of sock if sock is marked with an error on entry. If the socket is nonblocking then this call returns as soon as possible (connection will happen in the background ie. with the ControlT thread). A vfer_select() call can then determine if the connection succeded or not. For a nonblocking socket, this call returns VFER_INPROGRESS.

Parameters:

	vfd	vfer socket identifier
	serv_addr	a peer address
	addrlen	length of addr

Returns:

0 on success
VFER_BADSOCK bad vfd argument
VFER_TIMEOUT connection attempt timedout
VFER_REFUSED connection attempt refused
VFER_NOCONN socket is not able to perform a connect.
VFER_INPROGRESS only returned for nonblocking socket- indicates success

Definition at line 249 of file vfer_api.c.

int vfer_debug	(	FILE *	debug_file,
		FILE *	error_file,
		const char *	layers
	)

Controls debugging for the library.

By specifying a debug file output, and an error file output as FILE pointers, debug information can be outputted to specific files. Printing is also controlled by a selection of logical levels of the internal implementation (via character string wherein each char encodes one level) needing debug output.

Parameters:

	debug_file	output FILE pointer for debug messages
	error_file	output FILE pointer for error messages
	layers	a string containing chars specifying layers needing debugging output the char to component map is: q : accept queue component a : api component c : control component C : ccontrol component (congestion control) p : packet component

Returns:: 0 on succes -1 on error

Definition at line 1215 of file vfer_api.c.

char* vfer_errortext ( int err )

Returns a text description of the error code err.

Parameters:

err

error code

Returns:: a pointer to a text description of err

Definition at line 783 of file vfer_api.c.

int vfer_getsockname	(	vfer_fd	vfd,
		struct sockaddr *	name,
		socklen_t *	len
	)

Returns the current name for the specified socket. The namelen parameter should be initialized to indicate the amount of space pointed to by name. On return it contains the actual size of the name returned (in bytes).

Parameters:

`[in]`	vfd	vfer socket identifier
`[out]`	name	pointer to name structure
`[in]`	len	length of the name structure

Returns:

0 on success
VFER_BADSOCK bad vfd argument

Definition at line 1358 of file vfer_api.c.

int vfer_getsockopt	(	vfer_fd	vfd,
		int	optname,
		void *	optval,
		int *	optlen
	)

Returns data describing option optname of socket.

On entry optlen is the size of space pointed to by optval. On exit, optlen is changed to reflect the actual size of the returned data. If, on entry, sock is marked with an error, this call immediately returns without changing the error status. In addition to the option names valid for the vfer_setsockopt() call the following additional options are available.

SOCK_STREAM
SOCK_DGRAM
- MTU (int) current MTU
- MSGSIZE (int) The maximum size of an individual message.

Parameters:

	vfd	vfer socket identifier
	optname	option name pointer
	optval	option value pointer
	optlen	option length,description pointer

Returns:

0 on success
VFER_BADSOCK bad vfd argument
VFER_BADOPT unknown or illegal option/length

Definition at line 643 of file vfer_api.c.

bool vfer_is_stream ( vfer_fd fd )

Returns true if the given socket is stream and not datagram based.

Parameters:

[in] fd VFER FD to check

Returns:

true for a streamed connection
false for a datagram based connection

Todo:: Implement me properly

Definition at line 1384 of file vfer_api.c.

int vfer_listen	(	vfer_fd	vfd,
		int	backlog
	)

Configures socket to listen for incoming connection requests.

The call returns VFER_BADSOCK immediately without changing the error status of sock if sock is marked with an error on entry.

Parameters:

	vfd	vfer socket identifier
	backlog	the size of the queue for pending requests

Returns:

0 on success
VFER_BADSOCK bad vfd argument
VFER_NOLISTEN socket is not able to perform a listen

Definition at line 400 of file vfer_api.c.

ssize_t vfer_max_frame_size ( vfer_fd fd )

Returns the maximum size of a frame.

Parameters:

[in] fd VFER FD to check

Returns:

the maximum frame size > 0 on success

Todo:: Implement me properly

Definition at line 1397 of file vfer_api.c.

int vfer_recv	(	vfer_fd	vfd,
		void *	buf,
		size_t	len
	)

Read up to len bytes from socket into buf. If the socket is of type SOCK_DGRAM then an entire message is read into buf with bytes in excess of len being discarded.

Parameters:

	vfd	vfer socket identifier
	buf	a pointer to a buffer into which to receive
	len	maximum length of data to receive into buf

Returns:

number of bytes read on success
VFER_TIMEOUT timed out while waiting to receive data
VFER_BADSOCK bad vfd argument
VFER_UNCONN sock is not connected
VFER_INVAL invalid buf or len
VFER_WOULDBLOCK socket is non-blocking and requested operation would block

Definition at line 1053 of file vfer_api.c.

int vfer_recvfile	(	vfer_fd	vfd,
		int	fd,
		off_t	offset,
		size_t	size
	)

Reads size bytes from socket writing them into the file described by fd at offset offset.

Parameters:

	vfd	vfer socket identifier
	fd	file descriptor to write received data to
	offset	writing starting position in the file
	size	number of bytes to read

Returns:

Returns the actual number of bytes read on success (a positive number)
VFER_TIMEOUT timed out while waiting to receive file
VFER_BADSOCK bad vfd argument
VFER_INVAL invalid offset or size

Definition at line 979 of file vfer_api.c.

int vfer_select	(	int	len,
		vfer_fd *	vfds,
		struct timeval *	timeout
	)

Returns the number of sockets in an array that satisfy the marked conditions.

Timeout is the maximum time to wait before the call returns. If timeout is null the call blocks indefinitely. A timeout value of zero can be used to effect a poll operation. Timeout is not changed by the call.

Parameters:

	len	length of vfds array
	vfds	an array of socket vfer_fds to check for marked conditions
	timeout	a timeout value to control waiting time

Returns:

number of sockets in array socks that satisfy the marked conditions
VFER_BADSOCK one of the vfer_sock's in socks is bad
VFER_IMPL underlying select error
VFER_INVAL timeout value is invalid

Definition at line 1136 of file vfer_api.c.

int vfer_selectmark	(	vfer_fd	vfd,
		int	mark
	)

Marks socket with the conditions to be tested by the select call.

Called prior to using vfer_select(). Mark is a bitwise OR of VFER_READABLE, VFER_WRITABLE and VFER_EXCEPTION.

Parameters:

	vfd	vfer socket identifier
	mark	a mark to associate with the socket sock

Returns:

0 on succes
VFER_BADSOCK bad vfd argument
VFER_INVAL invalid mark value

Definition at line 1084 of file vfer_api.c.

int vfer_selecttest ( vfer_fd vfd )

Returns the result of the vfer_select() call for socket.

The return value will be a bitwise OR of VFER_READABLE, VFER_WRITABLE and VFER_EXCEPTION depending on how sock was marked and the result of the vfer_select() call.

Parameters:

vfd

vfer socket identifier

Returns:

bitwise OR of marks for socket sock on succes
VFER_BADSOCK bad vfer_sock

Definition at line 1108 of file vfer_api.c.

int vfer_send	(	vfer_fd	vfd,
		const void *	buf,
		size_t	len
	)

Sends len bytes from buf on a connected socket.

If the socket is of type SOCK_DGRAM then the data is treated as a single message and len must be less then the maximum message length. Messages greater than SNDSIZE are fragmented. On a fully reliable socket messages will be delivered intact. Messages always arrive *in* the original order. On an unreliable socket messages are either delivered intact or discarded also *in* the original order.

Parameters:

	vfd	vfer socket identifier
	buf	a pointer to a buffer to send
	len	length of the data to send starting at buf

Returns:

Returns the actual number of bytes sent on success (a positive number)
VFER_BADSOCK bad vfd argument
VFER_TIMEOUT timed out while sending data
VFER_UNCONN sock is not connected
VFER_INVAL invalid buf or len
VFER_WOULDBLOCK socket is non-blocking and requested operation would block

Definition at line 949 of file vfer_api.c.

int vfer_sendfile	(	vfer_fd	vfd,
		int	fd,
		off_t	offset,
		size_t	size
	)

Mmap the file described by fd and send size bytes of data starting at offset. For now we assume that this send call will use the current reliability function, ie. if the file will be arbitrarily parititioned into frames (into MAX_SEND_WINDOW chunks), each frame will be treated separately as far as reliability is concerned. Therefore this call makes most sense if the reliability function is the constant 1 (ie. full reliability).

Parameters:

	vfd	vfer socket identifier
	fd	file descriptor to map into mem and to send
	offset	data starting position in the file
	size	number of bytes to send

Returns:

Returns the actual number of bytes sent on success
VFER_BADSOCK bad vfd argument
VFER_BADFD error using mmap on fd
VFER_INVAL invalid offset or size

Definition at line 847 of file vfer_api.c.

int vfer_setsockopt	(	vfer_fd	vfd,
		int	optname,
		void *	optval,
		int	optlen
	)

Uses the data described by optval and optlen to set optname on socket.

If, on entry, the socket is marked with an error, this call immediately returns without changing the error status. The possible option names are:

SOCK_STREAM
SOCK_DGRAM
- QTTL (int) The duration (in msec) that unacknowledged messages will remain available for retransmission.
Both
- SNDSIZE (int) The packet size used for the underlying transport. This defaults to the MTU.
- NOPMTUD (int) Disable PMTUD.
- NONBLOCK (int) Set socket to use non-blocking mode for send, recv, accept and connect calls.

Parameters:

	vfd	vfer socket identifier
	optname	option name
	optval	option value
	optlen	option length,description

Returns:

0 on success

VFER_BADSOCK bad vfd argument
VFER_BADOPT unknown or illegal option/length

Definition at line 522 of file vfer_api.c.

int vfer_sockerror ( vfer_fd vfd )

Returns the error condition of a socket

Parameters:

vfd

vfer socket identifier

Returns:: the error condition of socket sock.

Definition at line 764 of file vfer_api.c.

vfer_fd vfer_socket ( int socktype )

Return a newly reserved vfer socket identifier

In case the call fails the error status can be obtained through vfer_sockstatus(). Only socktype of type SOCK_DGRAM is supported right now.

Parameters:

socktype

a SOCK_STREAM or SOCK_DGRAM

Returns:

a vfer_fd identifier >= 0
a negative vfer_fd identifier varrying the error code:
- VFER_BADTYPE invalid socktype error
- VFER_IMPL underlying socket descriptor failure

Definition at line 87 of file vfer_api.c.

vfer_stats vfer_sockstats ( vfer_fd vfd )

Computes and return current performance data for socket sock.

If, on entry, vfd is invalid or marked with an error this call immediately returns a zeroed out vfer_stats structure. On successfully return, this structure contains among many other things, average performance statistics for the socket and incremental statistics since the last call to vfer_sockstats(). Performance statistics include the following.

send rate in Mbps
recv rate in Mbps
retransmit traffic as a fraction of total traffic
round trip time statistics

For a SOCK_DGRAM socket, configured for partial reliability, the performance statistics also include the number of messages that expire after exceeding the QTTL limit.

Parameters:

vfd

vfer socket identifier

Returns:

a stats structure filled with current stats about socket sock
a zeroed out stats structure on error

Definition at line 745 of file vfer_api.c.


Defines
#define	SET_DF_BIT(SOCKFD, RET) { RET = -1; }
Typedefs
typedef void *	vfer_trnsm_arg
	generic transmit function argument
typedef int(*)	vfer_trnsm_fn (vfer_trnsm_arg sock, void *buf, size_t len)
	generic transmit function type
Functions
int	vfer__recvfile (vfer_trnsm_fn fn, vfer_trnsm_arg arg, uint32_t frame_size, int fd, off_t offset, size_t size)
int	vfer__sendfile (vfer_trnsm_fn fn, vfer_trnsm_arg arg, int frame_size, int fd, off_t offset, size_t size)
vfer_fd	vfer_accept (vfer_fd vfd, struct sockaddr addr, socklen_t len)
int	vfer_bind (vfer_fd vfd, struct sockaddr *addr, int len)
int	vfer_close (vfer_fd vfd)
int	vfer_connect (vfer_fd vfd, const struct sockaddr *serv_addr, int addrlen)
int	vfer_debug (FILE debug_file, FILE error_file, const char *layers)
char *	vfer_errortext (int err)
int	vfer_getsockname (vfer_fd vfd, struct sockaddr name, socklen_t len)
int	vfer_getsockopt (vfer_fd vfd, int optname, void optval, int optlen)
bool	vfer_is_stream (vfer_fd fd)
int	vfer_listen (vfer_fd vfd, int backlog)
ssize_t	vfer_max_frame_size (vfer_fd fd)
int	vfer_recv (vfer_fd vfd, void *buf, size_t len)
int	vfer_recvfile (vfer_fd vfd, int fd, off_t offset, size_t size)
int	vfer_select (int len, vfer_fd vfds, struct timeval timeout)
int	vfer_selectmark (vfer_fd vfd, int mark)
int	vfer_selecttest (vfer_fd vfd)
int	vfer_send (vfer_fd vfd, const void *buf, size_t len)
int	vfer_sendfile (vfer_fd vfd, int fd, off_t offset, size_t size)
int	vfer_setsockopt (vfer_fd vfd, int optname, void *optval, int optlen)
int	vfer_sockerror (vfer_fd vfd)
vfer_fd	vfer_socket (int socktype)
vfer_stats	vfer_sockstats (vfer_fd vfd)

src/vfer_api.h File Reference

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation