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.
#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.

## 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.
int | link_ssl_wrap_connect (struct link *link, const char *sni_hostname)
| Wrap a connect link with an ssl context and state.
struct link * | link_attach_to_file (FILE *file)
| Turn a FILE* into a link.
struct link * | link_attach_to_fd (int fd)
| Turn an fd into a link.
struct link * | link_serve (int port)
| Prepare to accept connections.
struct link * | link_serve_range (int low, int high)
| Prepare to accept connections.
struct link * | link_serve_address (const char *addr, int port)
| Prepare to accept connections on one network interface.
struct link * | link_serve_address_range (const char *addr, int low, int high)
| Prepare to accept connections on one network interface.
struct link * | link_serve_addrrange (const char *addr, int low, int high)
| Prepare to accept connections on one network interface.
struct link * | link_accept (struct link *parent, time_t stoptime)
| Accept one connection.
int | link_ssl_wrap_accept (struct link *lnk, const char *key, const char *cert)
| Wrap an accepted link with an ssl context.
ssize_t | link_read (struct link *link, char *data, size_t length, time_t stoptime)
| Read data from a connection.
ssize_t | link_read_avail (struct link *link, char *data, size_t length, time_t stoptime)
| Read available data from a connection.
ssize_t | link_write (struct link *link, const char *data, size_t length, time_t stoptime)
| Write data to a connection.
ssize_t | link_printf (struct link *link, time_t stoptime, const char *fmt,...) __attribute__((format(printf
| Write formatted data to a connection.
ssize_t ssize_t | link_vprintf (struct link *link, time_t stoptime, const char *fmt, va_list va)
| Write formatted data to a connection.
int | link_usleep (struct link *link, int usec, int reading, int writing)
| Block until a link is readable or writable.
int | link_sleep (struct link *link, time_t stoptime, int reading, int writing)
| Block until a link is readable or writable.
void | link_close (struct link *link)
| Close a connection.
void | link_detach (struct link *link)
| Detach a link from the underlying file descriptor.
void | link_window_set (int send_window, int recv_window)
| Set the TCP window size to be used for all links.
void | link_window_get (struct link *link, int *send_window, int *recv_window)
| Get the TCP window size actually allocated for this link.
int | link_readline (struct link *link, char *line, size_t length, time_t stoptime)
| Read a line of text from a link.
int | link_fd (struct link *link)
| Get the underlying file descriptor of a link.
int | link_buffer_output (struct link *link, size_t size)
| Enable output buffering for link_printf.
int | link_flush_output (struct link *link)
| Flush buffered output from link_printf.
int | link_using_ssl (struct link *link)
| Whether the link is using ssl.
int | link_buffer_empty (struct link *link)
| Check whether a link has unread contents in its buffer.
int | link_address_local (struct link *link, char *addr, int *port)
| Return the local address of the link in text format.
int | link_address_remote (struct link *link, char *addr, int *port)
| Return the remote address of the link in text format.
int | link_tune (struct link *link, link_tune_t mode)
| Tune a link for interactive or bulk performance.
int | link_poll (struct link_info *array, int nlinks, int msec)
| Wait for a activity on a an array of links.
int | link_get_buffer_bytes (struct link *link)
| Get the number of bytes in the output buffer of a link.

## 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

## LINK_ADDRESS_MAX

#define LINK_ADDRESS_MAX 48

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

## LINK_PORT_ANY

#define LINK_PORT_ANY 0

Value to usewhen any listen port is acceptable.

## LINK_FOREVER

#define LINK_FOREVER ((time_t)INT_MAX)

Stoptime to give when you wish to wait forever.

## LINK_READ

#define LINK_READ 1

Indicates a link is ready to read via link_poll.

## LINK_WRITE

#define LINK_WRITE 2

Indicates a link is ready to write via link_poll.

## Enumeration Type Documentation

## link_tune_t

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

## link_connect()

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.

## link_ssl_wrap_connect()

int link_ssl_wrap_connect | ( | struct link * | link,
|  | const char * | sni_hostname )

Wrap a connect link with an ssl context and state.

Parameters

  link | A link returned from link_connect
  sni_hostname | Optional domainame for tls routing.

Returns
  0 on failure, 1 on success

## link_attach_to_file()

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.

## link_attach_to_fd()

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.

## link_serve()

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.

## link_serve_range()

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.

## link_serve_address()

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.

## link_serve_address_range()

struct link * link_serve_address_range | ( | 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.

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.

## link_serve_addrrange()

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.

## link_accept()

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.

## link_ssl_wrap_accept()

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

Wrap an accepted link with an ssl context.

If successful, the connection is now encrypted.

Parameters

  lnk | 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

## link_read()

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.

## link_read_avail()

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.

## link_write()

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.

## link_printf()

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

Write formatted data to a connection.

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

Parameters

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

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

## link_vprintf()

ssize_t ssize_t link_vprintf | ( | struct link * | link,
|  | time_t | stoptime,
|  | const char * | fmt,
|  | 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.
  stoptime | The time at which to abort.
  fmt | A pointer to the data.
  va | Format arguments.

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

## link_usleep()

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.

## link_sleep()

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.

## link_close()

void link_close | ( | struct link * | link | ) |

Close a connection.

Parameters

  link | The connection to close.

## link_detach()

void link_detach | ( | struct link * | link | ) |

Detach a link from the underlying file descriptor.

Deletes the link structure.

Parameters

  link | The link to detach.

## link_window_set()

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.

## link_window_get()

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.

## link_readline()

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.

## link_fd()

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.

## link_buffer_output()

int link_buffer_output | ( | struct link * | link,
|  | size_t | size )

Enable output buffering for link_printf.

Parameters

  link | The link to modify.
  size | The number of bytes to buffer. Zero disables buffering and flushes pending output.

## link_flush_output()

int link_flush_output | ( | struct link * | link | ) |

Flush buffered output from link_printf.

Parameters

  link | The link to modify.

## link_using_ssl()

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

## link_buffer_empty()

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.

## link_address_local()

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.

## link_address_remote()

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.

## link_tune()

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.

## link_poll()

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.

## link_get_buffer_bytes()

int link_get_buffer_bytes | ( | struct link * | link | ) |

Get the number of bytes in the output buffer of a link.

Parameters

  link | The link to examine.

Returns
  The number of bytes in the output buffer of a link.