A high level TCP connection library. More...

#include <sys/types.h>
#include <limits.h>
#include <signal.h>
#include <stdarg.h>
#include <stdint.h>
#include <stdio.h>
#include <time.h>

Data Structures
struct	link_info
	Activity structure passed to link_poll. More...

Macros
#define	LINK_ADDRESS_MAX 48
	Maximum number of characters in the text representation of a link address, whether ipv4 or ipv6. More...

#define	LINK_PORT_ANY 0
	Value to usewhen any listen port is acceptable. More...

#define	LINK_FOREVER ((time_t)INT_MAX)
	Stoptime to give when you wish to wait forever. More...

#define	LINK_READ 1
	Indicates a link is ready to read via link_poll. More...

#define	LINK_WRITE 2
	Indicates a link is ready to write via link_poll. More...

Enumerations
enum	link_tune_t { LINK_TUNE_INTERACTIVE, LINK_TUNE_BULK }
	Options for link performance tuning. More...

Functions
struct link *	link_connect (const char *addr, int port, time_t stoptime)
	Connect to a remote host. More...

int	link_ssl_wrap_connect (struct link *link)
	Wrap a connect link with an ssl context and state. More...

struct link *	link_attach_to_file (FILE *file)
	Turn a FILE* into a link. More...

struct link *	link_attach_to_fd (int fd)
	Turn an fd into a link. More...

struct link *	link_serve (int port)
	Prepare to accept connections. More...

struct link *	link_serve_range (int low, int high)
	Prepare to accept connections. More...

struct link *	link_serve_address (const char *addr, int port)
	Prepare to accept connections on one network interface. More...

struct link *	link_serve_addrrange (const char *addr, int low, int high)
	Prepare to accept connections on one network interface. More...

struct link *	link_accept (struct link *parent, time_t stoptime)
	Accept one connection. More...

int	link_ssl_wrap_accept (struct link l, const char key, const char *cert)
	Wrap an accepted link with an ssl context. More...

ssize_t	link_read (struct link link, char data, size_t length, time_t stoptime)
	Read data from a connection. More...

ssize_t	link_read_avail (struct link link, char data, size_t length, time_t stoptime)
	Read available data from a connection. More...

ssize_t	link_write (struct link link, const char data, size_t length, time_t stoptime)
	Write data to a connection. More...

ssize_t	link_putfstring (struct link link, const char fmt, time_t stoptime,...) __attribute__((format(printf
	Write formatted data to a connection. More...

ssize_t ssize_t	link_putvfstring (struct link link, const char fmt, time_t stoptime, va_list va)
	Write formatted data to a connection. More...

int	link_usleep (struct link *link, int usec, int reading, int writing)
	Block until a link is readable or writable. More...

int	link_sleep (struct link *link, time_t stoptime, int reading, int writing)
	Block until a link is readable or writable. More...

void	link_close (struct link *link)
	Close a connection. More...

void	link_detach (struct link *link)
	Detach a link from the underlying file descriptor. More...

void	link_window_set (int send_window, int recv_window)
	Set the TCP window size to be used for all links. More...

void	link_window_get (struct link link, int send_window, int *recv_window)
	Get the TCP window size actually allocated for this link. More...

int	link_readline (struct link link, char line, size_t length, time_t stoptime)
	Read a line of text from a link. More...

int	link_fd (struct link *link)
	Get the underlying file descriptor of a link. More...

int	link_using_ssl (struct link *link)
	Whether the link is using ssl. More...

int	link_buffer_empty (struct link *link)
	Check whether a link has unread contents in its buffer. More...

int	link_address_local (struct link link, char addr, int *port)
	Return the local address of the link in text format. More...

int	link_address_remote (struct link link, char addr, int *port)
	Return the remote address of the link in text format. More...

int	link_tune (struct link *link, link_tune_t mode)
	Tune a link for interactive or bulk performance. More...

int	link_poll (struct link_info *array, int nlinks, int msec)
	Wait for a activity on a an array of links. More...

Detailed Description

A high level TCP connection library.

A link is a TCP connection to a process on another machine. This module works at a higher level of abstraction than the socket library, with an easier-to-use API and explicit support for timeouts.

Timeouts are specified using an absolute stoptime. For example, if you want a connection to be attempted for sixty seconds, specify time(0)+60. The operation will be tried and retried until that absolute limit, giving the caller much greater control over program behavior.

Note that this library manipulates IP addresses in the form of strings. To convert a hostname into a string IP address, call domain_name_cache_lookup. For example, here is how to make a simple HTTP request:

struct link *link;
time_t stoptime = time(0)+300;
char addr[LINK_ADDRESS_MAX];
int result;

const char *request = "GET / HTTP/1.0\n\n";

result = domain_name_cache_lookup("www.google.com",addr);
if(!result) fatal("could not lookup name");

link = link_connect(addr,80,stoptime);
if(!link) fatal("could not connect");

result = link_write(link,request,strlen(request),stoptime);
if(result<0) fatal("could not send request");

link_stream_to_file(link,stdout,1000000,stoptime);
link_close(link);

Macro Definition Documentation

#define LINK_ADDRESS_MAX 48

Maximum number of characters in the text representation of a link address, whether ipv4 or ipv6.

#define LINK_PORT_ANY 0

Value to usewhen any listen port is acceptable.

#define LINK_FOREVER ((time_t)INT_MAX)

Stoptime to give when you wish to wait forever.

#define LINK_READ 1

Indicates a link is ready to read via link_poll.

#define LINK_WRITE 2

Indicates a link is ready to write via link_poll.

Enumeration Type Documentation

enum link_tune_t

Options for link performance tuning.

Enumerator
LINK_TUNE_INTERACTIVE	Data is sent immediately to optimze interactive latency.
LINK_TUNE_BULK	Data may be buffered to improve throughput of large transfers.

Function Documentation

struct link* link_connect	(	const char *	addr,
		int	port,
		time_t	stoptime
	)

Connect to a remote host.

Parameters

addr	IP address of server in string form.
port	Port of server.
stoptime	Absolute time at which to abort.

Returns: On success, returns a pointer to a link object. On failure, returns a null pointer with errno set appropriately.

int link_ssl_wrap_connect ( struct link * link )

Wrap a connect link with an ssl context and state.

Parameters

link	A link returned from link_connect

Returns: 0 on failure, 1 on success

struct link* link_attach_to_file ( FILE * file )

Turn a FILE* into a link.

Useful when trying to poll both remote and local connections using link_poll

Parameters

file	File to create the link from.

Returns: On success, returns a pointer to a link object. On failure, returns a null pointer with errno set appropriately.

struct link* link_attach_to_fd ( int fd )

Turn an fd into a link.

Useful when trying to poll both remote and local connections using link_poll

Parameters

fd	File descriptor to create the link from.

Returns: On success, returns a pointer to a link object. On failure, returns a null pointer with errno set appropriately.

struct link* link_serve ( int port )

Prepare to accept connections.

link_serve will accept connections on any network interface, which is usually what you want.

Parameters

port	The port number to listen on. If less than 1, the first unused port between TCP_LOW_PORT and TCP_HIGH_PORT will be selected.

Returns: link A server endpoint that can be passed to link_accept, or null on failure.

struct link* link_serve_range	(	int	low,
		int	high
	)

Prepare to accept connections.

link_serve_range will accept connections on any network interface, which is usually what you want.

Parameters

low	The low port in a range to listen on (inclusive).
high	The high port in a range to listen on (inclusive).

Returns: link A server endpoint that can be passed to link_accept, or null on failure.

struct link* link_serve_address	(	const char *	addr,
		int	port
	)

Prepare to accept connections on one network interface.

Functions like link_serve, except that the server will only be visible on the given network interface.

Parameters

addr	IP address of the network interface.
port	The port number to listen on. If less than 1, the first unused port between TCP_LOW_PORT and TCP_HIGH_PORT will be selected.

Returns: link A server endpoint that can be passed to link_accept, or null on failure.

struct link* link_serve_addrrange	(	const char *	addr,
		int	low,
		int	high
	)

Prepare to accept connections on one network interface.

Functions like link_serve, except that the server will only be visible on the given network interface and allows for a port range.

Parameters

addr	IP address of the network interface.
low	The low port in a range to listen on (inclusive).
high	The high port in a range to listen on (inclusive).

Returns: link A server endpoint that can be passed to link_accept, or null on failure.

struct link* link_accept	(	struct link *	parent,
		time_t	stoptime
	)

Accept one connection.

Parameters

parent	A link returned from link_serve or link_serve_address.
stoptime	The time at which to abort.

Returns: link A connection to a client, or null on failure.

int link_ssl_wrap_accept	(	struct link *	l,
		const char *	key,
		const char *	cert
	)

Wrap an accepted link with an ssl context.

If successful, the connection is now encrypted.

Parameters

parent	A link returned from link_accept
key	The ssl key of the server.
cert	The ssl cert of the server.

Returns: 0 on failure, 1 on success

ssize_t link_read	(	struct link *	link,
		char *	data,
		size_t	length,
		time_t	stoptime
	)

Read data from a connection.

This call will block until the given number of bytes have been read, or the connection is dropped.

Parameters

link	The link from which to read.
data	A buffer to hold the data.
length	The number of bytes to read.
stoptime	The time at which to abort.

Returns: The number of bytes actually read, or zero if the connection is closed, or less than zero on error.

ssize_t link_read_avail	(	struct link *	link,
		char *	data,
		size_t	length,
		time_t	stoptime
	)

Read available data from a connection.

This call will read whatever data is immediately available, and then return without blocking.

Parameters

link	The link from which to read.
data	A buffer to hold the data.
length	The number of bytes to read.
stoptime	The time at which to abort.

Returns: The number of bytes actually read, or zero if the connection is closed, or less than zero on error.

ssize_t link_write	(	struct link *	link,
		const char *	data,
		size_t	length,
		time_t	stoptime
	)

Write data to a connection.

Parameters

link	The link to write.
data	A pointer to the data.
length	The number of bytes to write.
stoptime	The time at which to abort.

Returns: The number of bytes actually written, or less than zero on error.

ssize_t link_putfstring	(	struct link *	link,
		const char *	fmt,
		time_t	stoptime,
			...
	)

Write formatted data to a connection.

All data is written until finished or an error is encountered.

Parameters

link	The link to write.
fmt	A pointer to the data.
stoptime	The time at which to abort.
...	Format arguments.

Returns: The number of bytes actually written, or less than zero on error.

ssize_t ssize_t link_putvfstring	(	struct link *	link,
		const char *	fmt,
		time_t	stoptime,
		va_list	va
	)

Write formatted data to a connection.

All data is written until finished or an error is encountered.

Parameters

link	The link to write.
fmt	A pointer to the data.
stoptime	The time at which to abort.
va	Format arguments.

Returns: The number of bytes actually written, or less than zero on error.

int link_usleep	(	struct link *	link,
		int	usec,
		int	reading,
		int	writing
	)

Block until a link is readable or writable.

Parameters

link	The link to wait on.
usec	The maximum number of microseconds to wait.
reading	Wait for the link to become readable.
writing	Wait for the link to become writable.

Returns: One if the link becomes readable or writable before the timeout expires, zero otherwise.

int link_sleep	(	struct link *	link,
		time_t	stoptime,
		int	reading,
		int	writing
	)

Block until a link is readable or writable.

Parameters

link	The link to wait on.
stoptime	The time at which to abort.
reading	Wait for the link to become readable.
writing	Wait for the link to become writable.

Returns: One if the link becomes readable or writable before the timeout expires, zero otherwise.

void link_close ( struct link * link )

Close a connection.

Parameters

link	The connection to close.

void link_detach ( struct link * link )

Detach a link from the underlying file descriptor.

Deletes the link structure.

Parameters

link	The link to detach.

void link_window_set	(	int	send_window,
		int	recv_window
	)

Set the TCP window size to be used for all links.

Takes effect on future calls to link_connect or link_accept. Default value is set by the system or by the environment variable TCP_WINDOW_SIZE. Note that the operating system may place limits on the buffer sizes actually allocated. Use link_window_get to retrieve the buffer actually allocated for a given link.

Parameters

send_window	The size of the send window, in bytes.
recv_window	The size of the recv window, in bytes.

void link_window_get	(	struct link *	link,
		int *	send_window,
		int *	recv_window
	)

Get the TCP window size actually allocated for this link.

Parameters

link	The link to examine.
send_window	A pointer where to store the send window.
recv_window	A pointer where to store the receive window.

int link_readline	(	struct link *	link,
		char *	line,
		size_t	length,
		time_t	stoptime
	)

Read a line of text from a link.

Reads a line of text, up to and including a newline, interpreted as either LF or CR followed by LF. The line actually returned is null terminated and does not contain the newline indicator. An internal buffer is used so that readline can usually complete with zero or one system calls.

Parameters

link	The link to read from.
line	A pointer to a buffer to fill with data.
length	The length of the buffer in bytes.
stoptime	The absolute time at which to abort.

Returns: True if a line was successfully read. False if end of stream was reach or an error occured.

int link_fd ( struct link * link )

Get the underlying file descriptor of a link.

Parameters

link	The link to examine.

Returns: The integer file descriptor of the link.

int link_using_ssl ( struct link * link )

Whether the link is using ssl.

Parameters

link	The link to examine.

Returns: True if ssl context has been created, False otherwise

int link_buffer_empty ( struct link * link )

Check whether a link has unread contents in its buffer.

Parameters

link	The link to examine.

Returns: 1 if buffer is empty, 0 otherwise.

int link_address_local	(	struct link *	link,
		char *	addr,
		int *	port
	)

Return the local address of the link in text format.

Parameters

link	The link to examine.
addr	Pointer to a string of at least LINK_ADDRESS_MAX bytes, which will be filled with a text representation of the local IP address.
port	Pointer to an integer, which will be filled with the TCP port number.

Returns: Positive on success, zero on failure.

int link_address_remote	(	struct link *	link,
		char *	addr,
		int *	port
	)

Return the remote address of the link in text format.

Parameters

link	The link to examine.
addr	Pointer to a string of at least LINK_ADDRESS_MAX bytes, which will be filled with a text representation of the remote IP address.
port	Pointer to an integer, which will be filled with the TCP port number.

Returns: Positive on success, zero on failure.

int link_tune	(	struct link *	link,
		link_tune_t	mode
	)

Tune a link for interactive or bulk performance.

A link may be tuned at any point in its lifecycle. LINK_TUNE_INTERACTIVE is best used for building latency-sensitive interactive or RPC applications. LINK_TUNE_BULK is best used to large data transfers.

Parameters

link	The link to be tuned.
mode	The desired tuning mode.

int link_poll	(	struct link_info *	array,
		int	nlinks,
		int	msec
	)

Wait for a activity on a an array of links.

Parameters

array	Pointer to an array of link_info structures. Each one should contain a pointer to a valid link and have the events field set to the events (LINK_READ or LINK_WRITE) of interest. Upon return, each one will have the revents field filled with the events that actually occurred.
nlinks	The length of the array.
msec	The number of milliseconds to wait for activity. Zero indicates do not wait at all, while -1 indicates wait forever.

Returns: The number of links available to read or write.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation