link.h File Reference
A high level TCP connection library.
More...
#include "int_sizes.h"
#include <time.h>
#include <limits.h>
#include <stdio.h>
#include <stdarg.h>
#include <sys/types.h>
Go to the source code of this file.
Data Structures |
struct | link_info |
| Activity structure passed to link_poll. More...
|
Defines |
#define | LINK_ADDRESS_MAX 48 |
| Maximum number of characters in the text representation of a link address.
|
#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.
|
struct link * | link_serve (int port) |
| 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_accept (struct link *master, time_t stoptime) |
| Accept one connection.
|
int | link_read (struct link *link, char *data, size_t length, time_t stoptime) |
| Read data from a connection.
|
int | link_read_avail (struct link *link, char *data, size_t length, time_t stoptime) |
| Read available data from a connection.
|
int | link_write (struct link *link, const char *data, size_t length, time_t stoptime) |
| Write data to a connection.
|
int | link_putfstring (struct link *link, const char *fmt, time_t stoptime,...) |
| Write formatted data to a connection.
|
int | link_putvfstring (struct link *link, const char *fmt, time_t stoptime, 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.
|
void | link_close (struct link *link) |
| Close a connection.
|
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_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.
|
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);
Define Documentation
#define LINK_ADDRESS_MAX 48 |
Maximum number of characters in the text representation of a link address.
This must be large enough to accomodate ipv6 in the future.
Value to usewhen any listen port is acceptable.
#define LINK_FOREVER ((time_t)INT_MAX) |
Stoptime to give when you wish to wait forever.
Indicates a link is ready to read via link_poll.
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 | |
|
) |
| | [read] |
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.
struct link* link_serve |
( |
int |
port |
) |
[read] |
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. |
- 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 | |
|
) |
| | [read] |
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. |
- Returns:
- link A server endpoint that can be passed to link_accept, or null on failure.
struct link* link_accept |
( |
struct link * |
master, |
|
|
time_t |
stoptime | |
|
) |
| | [read] |
Accept one connection.
- Parameters:
-
- Returns:
- link A connection to a client, or null on failure.
int 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.
int 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.
int 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.
int 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.
int 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.
void link_close |
( |
struct link * |
link |
) |
|
Close a connection.
- Parameters:
-
| link | The connection to close. |
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:
- If greater than zero, a line was read, and the return value indicates the length in bytes. If equal to zero, end of stream was reached. If less than zero, an error occurred.
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_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.
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.