2
Copyright (C) 2003-2004 Douglas Thain and the University of Wisconsin
3
Copyright (C) 2005- The University of Notre Dame
4
This software is distributed under the GNU General Public License.
5
See the file COPYING for details.
11
/** @file link.h A high level TCP connection library.
12
A <b>link</b> 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.
14
Timeouts are specified using an absolute stoptime. For example, if you want
15
a connection to be attempted for sixty seconds, specify <tt>time(0)+60</tt>.
16
The operation will be tried and retried until that absolute limit, giving
17
the caller much greater control over program behavior.
19
Note that this library manipulates IP addresses in the form of strings.
20
To convert a hostname into a string IP address, call @ref domain_name_cache_lookup. For example, here is how to make a simple HTTP request:
23
time_t stoptime = time(0)+300;
24
char addr[LINK_ADDRESS_MAX];
27
const char *request = "GET / HTTP/1.0\n\n";
29
result = domain_name_cache_lookup("www.google.com",addr);
30
if(!result) fatal("could not lookup name");
32
link = link_connect(addr,80,stoptime);
33
if(!link) fatal("could not connect");
35
result = link_write(link,request,strlen(request),stoptime);
36
if(result<0) fatal("could not send request");
38
link_stream_to_file(link,stdout,1000000,stoptime);
44
#include "int_sizes.h"
50
#include <sys/types.h>
52
/** Maximum number of characters in the text representation of a link address. This must be large enough to accomodate ipv6 in the future. */
53
#define LINK_ADDRESS_MAX 48
55
/** Value to usewhen any listen port is acceptable */
56
#define LINK_PORT_ANY 0
58
/** Stoptime to give when you wish to wait forever */
59
#define LINK_FOREVER ((time_t)INT_MAX)
61
/** Connect to a remote host.
62
@param addr IP address of server in string form.
63
@param port Port of server.
64
@param stoptime Absolute time at which to abort.
65
@return On success, returns a pointer to a link object. On failure, returns a null pointer with errno set appropriately.
67
struct link * link_connect( const char *addr, int port, time_t stoptime );
69
/** Prepare to accept connections.
70
@ref link_serve will accept connections on any network interface,
71
which is usually what you want.
72
@param port The port number to listen on.
73
@return link A server endpoint that can be passed to @ref link_accept, or null on failure.
75
struct link * link_serve( int port );
77
/** Prepare to accept connections on one network interface.
78
Functions like @ref link_serve, except that the server will
79
only be visible on the given network interface.
80
@param addr IP address of the network interface.
81
@param port The port number to listen on.
82
@return link A server endpoint that can be passed to @ref link_accept, or null on failure.
84
struct link * link_serve_address( const char *addr, int port );
86
/** Accept one connection.
87
@param master A link returned from @ref link_serve or @ref link_serve_address.
88
@param stoptime The time at which to abort.
89
@return link A connection to a client, or null on failure.
91
struct link * link_accept( struct link *master, time_t stoptime );
93
/** Read data from a connection.
94
This call will block until the given number of bytes have been read,
95
or the connection is dropped.
96
@param link The link from which to read.
97
@param data A buffer to hold the data.
98
@param length The number of bytes to read.
99
@param stoptime The time at which to abort.
100
@return The number of bytes actually read, or zero if the connection is closed, or less than zero on error.
102
int link_read( struct link *link, char *data, size_t length, time_t stoptime );
104
/** Read available data from a connection.
105
This call will read whatever data is immediately available, and then
106
return without blocking.
107
@param link The link from which to read.
108
@param data A buffer to hold the data.
109
@param length The number of bytes to read.
110
@param stoptime The time at which to abort.
111
@return The number of bytes actually read, or zero if the connection is closed, or less than zero on error.
113
int link_read_avail( struct link *link, char *data, size_t length, time_t stoptime );
115
/** Write data to a connection.
116
@param link The link to write.
117
@param data A pointer to the data.
118
@param length The number of bytes to write.
119
@param stoptime The time at which to abort.
120
@return The number of bytes actually written, or less than zero on error.
122
int link_write( struct link *link, const char *data, size_t length, time_t stoptime );
124
/* Write a string of length len to a connection. All data is written until
125
* finished or an error is encountered.
126
@param link The link to write.
127
@param str A pointer to the string.
128
@param len Length of the string.
129
@param stoptime The time at which to abort.
130
@return The number of bytes actually written, or less than zero on error.
132
int link_putlstring( struct link *link, const char *str, size_t len, time_t stoptime);
134
/* Write a C string to a connection. All data is written until finished or an
135
error is encountered. It is defined as a macro.
136
@param link The link to write.
137
@param str A pointer to the string.
138
@param stoptime The time at which to abort.
139
@return The number of bytes actually written, or less than zero on error.
141
#define link_putstring(l,s,t) (link_putlstring(l,s,strlen(s),t))
143
/* Write a C literal string to a connection. All data is written until finished
144
or an error is encountered. It is defined as a macro.
145
@param link The link to write.
146
@param str A pointer to the string.
147
@param stoptime The time at which to abort.
148
@return The number of bytes actually written, or less than zero on error.
150
#define link_putliteral(l,s,t) (link_putlstring(l,s "",((sizeof(s))-1),t))
152
/** Write formatted data to a connection. All data is written until finished
153
* or an error is encountered.
154
@param link The link to write.
155
@param fmt A pointer to the data.
156
@param stoptime The time at which to abort.
157
@param ... Format arguments.
158
@return The number of bytes actually written, or less than zero on error.
160
int link_putfstring( struct link *link, const char *fmt, time_t stoptime, ... );
162
/** Write formatted data to a connection. All data is written until finished
163
* or an error is encountered.
164
@param link The link to write.
165
@param fmt A pointer to the data.
166
@param stoptime The time at which to abort.
167
@param va Format arguments.
168
@return The number of bytes actually written, or less than zero on error.
170
int link_putvfstring( struct link *link, const char *fmt, time_t stoptime, va_list va );
172
/** Block until a link is readable or writable.
173
@param link The link to wait on.
174
@param usec The maximum number of microseconds to wait.
175
@param reading Wait for the link to become readable.
176
@param writing Wait for the link to become writable.
177
@return One if the link becomes readable or writable before the timeout expires, zero otherwise.
179
int link_usleep( struct link *link, int usec, int reading, int writing );
181
/** Close a connection.
182
@param link The connection to close.
184
void link_close( struct link *link );
186
/** Set the TCP window size to be used for all links.
187
Takes effect on future calls to @ref link_connect or @ref link_accept.
188
Default value is set by the system or by the environment variable
190
Note that the operating system may place limits on the buffer
191
sizes actually allocated. Use @ref link_window_get to retrieve
192
the buffer actually allocated for a given link.
193
@param send_window The size of the send window, in bytes.
194
@param recv_window The size of the recv window, in bytes.
197
void link_window_set( int send_window, int recv_window );
199
/** Get the TCP window size actually allocated for this link.
200
@param link The link to examine.
201
@param send_window A pointer where to store the send window.
202
@param recv_window A pointer where to store the receive window.
205
void link_window_get( struct link *link, int *send_window, int *recv_window );
207
/** Read a line of text from a link.
208
Reads a line of text, up to and including a newline, interpreted as either LF
209
or CR followed by LF. The line actually returned is null terminated and
210
does not contain the newline indicator. An internal buffer is used so that
211
readline can usually complete with zero or one system calls.
212
@param link The link to read from.
213
@param line A pointer to a buffer to fill with data.
214
@param length The length of the buffer in bytes.
215
@param stoptime The absolute time at which to abort.
216
@return 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.
218
int link_readline( struct link *link, char *line, size_t length, time_t stoptime );
220
/** Get the underlying file descriptor of a link.
221
@param link The link to examine.
222
@return The integer file descriptor of the link.
224
int link_fd( struct link *link );
226
int link_nonblocking( struct link *link, int onoff );
228
/** Return the local address of the link in text format.
229
@param link The link to examine.
230
@param addr Pointer to a string of at least @ref LINK_ADDRESS_MAX bytes, which will be filled with a text representation of the local IP address.
231
@param port Pointer to an integer, which will be filled with the TCP port number.
232
@return Positive on success, zero on failure.
234
int link_address_local( struct link *link, char *addr, int *port );
236
/** Return the remote address of the link in text format.
237
@param link The link to examine.
238
@param addr Pointer to a string of at least @ref LINK_ADDRESS_MAX bytes, which will be filled with a text representation of the remote IP address.
239
@param port Pointer to an integer, which will be filled with the TCP port number.
240
@return Positive on success, zero on failure.
242
int link_address_remote( struct link *link, char *addr, int *port );
244
INT64_T link_stream_to_buffer( struct link *link, char **buffer, time_t stoptime );
246
INT64_T link_stream_to_fd( struct link *link, int fd, INT64_T length, time_t stoptime );
247
INT64_T link_stream_to_file( struct link *link, FILE *file, INT64_T length, time_t stoptime );
249
INT64_T link_stream_from_fd( struct link *link, int fd, INT64_T length, time_t stoptime );
250
INT64_T link_stream_from_file( struct link *link, FILE *file, INT64_T length, time_t stoptime );
252
INT64_T link_soak( struct link *link, INT64_T length, time_t stoptime );
254
/** Options for link performance tuning. */
256
LINK_TUNE_INTERACTIVE, /**< Data is sent immediately to optimze interactive latency. */
257
LINK_TUNE_BULK /**< Data may be buffered to improve throughput of large transfers. */
260
/** Tune a link for interactive or bulk performance. A link may be tuned at any point in its lifecycle.
261
@ref LINK_TUNE_INTERACTIVE is best used for building latency-sensitive interactive or RPC applications.
262
@ref LINK_TUNE_BULK is best used to large data transfers.
263
@param link The link to be tuned.
264
@param mode The desired tuning mode.
266
int link_tune( struct link *link, link_tune_t mode );
268
/** Indicates a link is ready to read via @ref link_poll.*/
271
/** Indicates a link is ready to write via @ref link_poll.*/
274
/** Activity structure passed to @ref link_poll. */
276
struct link *link; /**< The link to be polled. */
277
int events; /**< The events to wait for (@ref LINK_READ or @ref LINK_WRITE) */
278
int revents; /**< The events returned (@ref LINK_READ or @ref LINK_WRITE) */
282
Wait for a activity on a an array of links.
283
@param array Pointer to an array of @ref link_info structures. Each one should contain a pointer to a valid link and have the events field set to the events (@ref LINK_READ or @ref LINK_WRITE) of interest. Upon return, each one will have the revents field filled with the events that actually occurred.
284
@param nlinks The length of the array.
285
@param msec The number of milliseconds to wait for activity. Zero indicates do not wait at all, while -1 indicates wait forever.
286
@return The number of links available to read or write.
289
int link_poll( struct link_info *array, int nlinks, int msec );
added
removed
dttools/src/link.h
