cctools
Data Structures | Macros | Enumerations | Functions
link.h File Reference

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>

Go to the source code of this file.

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_server (struct link *l, const char *key, const char *cert)
 Wrap a server link with an ssl context and state. 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

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
addrIP address of server in string form.
portPort of server.
stoptimeAbsolute 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
linkA 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
fileFile 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
fdFile 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
portThe 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
lowThe low port in a range to listen on (inclusive).
highThe 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
addrIP address of the network interface.
portThe 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
addrIP address of the network interface.
lowThe low port in a range to listen on (inclusive).
highThe 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
parentA link returned from link_serve or link_serve_address.
stoptimeThe time at which to abort.
Returns
link A connection to a client, or null on failure.
int link_ssl_wrap_server ( struct link *  l,
const char *  key,
const char *  cert 
)

Wrap a server link with an ssl context and state.

Parameters
parentA link returned from link_serve or link_serve_address.
keyThe ssl key of the server.
certThe 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
linkThe link from which to read.
dataA buffer to hold the data.
lengthThe number of bytes to read.
stoptimeThe 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
linkThe link from which to read.
dataA buffer to hold the data.
lengthThe number of bytes to read.
stoptimeThe 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
linkThe link to write.
dataA pointer to the data.
lengthThe number of bytes to write.
stoptimeThe 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
linkThe link to write.
fmtA pointer to the data.
stoptimeThe 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
linkThe link to write.
fmtA pointer to the data.
stoptimeThe time at which to abort.
vaFormat 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
linkThe link to wait on.
usecThe maximum number of microseconds to wait.
readingWait for the link to become readable.
writingWait 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
linkThe link to wait on.
stoptimeThe time at which to abort.
readingWait for the link to become readable.
writingWait 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
linkThe connection to close.
void link_detach ( struct link *  link)

Detach a link from the underlying file descriptor.

Deletes the link structure.
Parameters
linkThe 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_windowThe size of the send window, in bytes.
recv_windowThe 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
linkThe link to examine.
send_windowA pointer where to store the send window.
recv_windowA 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
linkThe link to read from.
lineA pointer to a buffer to fill with data.
lengthThe length of the buffer in bytes.
stoptimeThe 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
linkThe 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
linkThe 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
linkThe 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
linkThe link to examine.
addrPointer to a string of at least LINK_ADDRESS_MAX bytes, which will be filled with a text representation of the local IP address.
portPointer 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
linkThe link to examine.
addrPointer to a string of at least LINK_ADDRESS_MAX bytes, which will be filled with a text representation of the remote IP address.
portPointer 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
linkThe link to be tuned.
modeThe 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
arrayPointer 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.
nlinksThe length of the array.
msecThe 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.