src/vfer_api.c File Reference

Implements the api calls that can be made to the library. More...

#include "vfer_api.h"

Go to the source code of this file.

Defines
#define	PROTOCOL_INIT_TEST
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)
static int	vfer_internal_init ()
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)
Variables
static int	Debug_Initialized = -1
static int	Initialized = -1

---

Detailed Description

Implements the api calls that can be made to the library.

Author:

Ivan Beschastnikh

The application may only call the functions prototyped in api.h. The API has been written by Steven Senger of Internet2, and can be found online at http://transport.internet2.edu/transport-api-06.pdf

• 05/08-11/06 ivan Moved to using vfer_fd data type for all api calls, mane changes due to new threading model
• 04/30/06 ivan implemented vfer_recvfile and vfer_sendfile
• 03/25/06 ivan added debugging support for congestion control (ccontrol.c) in the form of DEBUG_CCTL var in vfer_debug
• 12/29/05 ivan added VFERSO_SNDSIZE support to control packet|frag size dynamically with vfer_setsockopt added nonblocking socket vfer_connect() functionality, moved all connect logic to Control_ConnectT @ control.c
• 12/28/05 ivan tsci2 integration ; vfer_setsockopt and vfer_sendfile bug fixes
• 10/17/05 ivan added vfer_debug function to specify level of debug verbosity at runtime
• 10/13/05 ivan now includes a main page blurb for doxygen created docs
• 09/01/05 ivan modified to use new packet structures
• 08/28/05 ivan added recv/send buffer setting and udp checksum enable checking in vfer_bind
• 08/05/05 ivan changed vfer_connect to release socket correctly on error and support nonblocking vfer_sockets
• 07/28/05 ivan c_control hooks to vfer{accept,connect,send,recv}, debug printing for all api calls added
• 07/18,19,20/05 ivan select related function implementations
• 06/29/05 ivan migration to the api specified in I2's writeup (version 6), all doxygened
• 06/10/05 ivan renamed to api.[c,h] (from protocol.[c,h]) ; wrote Protocol_Init code & Accept code for barebones connection
• 05/24/05 ivan initially added to app_api layer & recoded for this
• 05/18/05 ivan created

Definition in file vfer_api.c.

---

Define Documentation

#define PROTOCOL_INIT_TEST

Value:

({ \
        if (Initialized == -1) \
                vfer_internal_init(); \
        -1;})

Definition at line 66 of file vfer_api.c.

---

Function Documentation

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.

static int vfer_internal_init

(

)

[static]

Initializes all the data structures & component used by the vfer protocol

This function runs only once for every time we load the protocol into a program. Note that this function is internal and should NOT be used outside of the protocol's scope. It does NOT set any socket's err field.

Returns:

0 on success -1 on error

Definition at line 1274 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.

---

Variable Documentation

int Debug_Initialized = -1 [static]

Definition at line 57 of file vfer_api.c.

int Initialized = -1 [static]

Definition at line 56 of file vfer_api.c.

---