CONTENTS

LIBRARY

SYNOPSIS

DESCRIPTION

fetchParseURL takes a URL in the form of a null-terminated string and splits it into its components function according to the Common Internet Scheme Syntax detailed in RFC1738. A regular expression which produces this syntax is:
<scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)?

If the URL does not seem to begin with a scheme name, the following syntax is assumed:
((<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)?

Note that some components of the URL are not necessarily relevant to all URL schemes. For instance, the file scheme only needs the <scheme> and <document> components.

fetchMakeURL and fetchParseURL return a pointer to a
.Vt url structure, which is defined as follows in
.In fetch.h :
#define URL_SCHEMELEN 16
#define URL_USERLEN 256
#define URL_PWDLEN 256

struct url {
char scheme[URL_SCHEMELEN+1];
char user[URL_USERLEN+1];
char pwd[URL_PWDLEN+1];
char host[MAXHOSTNAMELEN+1];
intport;
char *doc;
off_t offset;
size_t length;
};

The pointer returned by fetchMakeURL or fetchParseURL should be freed using fetchFreeURL.

fetchXGetURL, fetchGetURL, and fetchPutURL constitute the recommended interface to the fetch library. They examine the URL passed to them to determine the transfer method, and call the appropriate lower-level functions to perform the actual transfer. fetchXGetURL also returns the remote document’s metadata in the
.Vt url_stat structure pointed to by the us argument.

The flags argument is a string of characters which specify transfer options. The meaning of the individual flags is scheme-dependent, and is detailed in the appropriate section below.

fetchStatURL attempts to obtain the requested document’s metadata and fill in the structure pointed to by its second argument. The
.Vt url_stat structure is defined as follows in
.In fetch.h :
struct url_stat {
off_t size;
time_t atime;
time_t mtime;
};

If the size could not be obtained from the server, the size field is set to -1. If the modification time could not be obtained from the server, the mtime field is set to the epoch. If the access time could not be obtained from the server, the atime field is set to the modification time.

fetchListURL attempts to list the contents of the directory pointed to by the URL provided. If successful, it returns a malloced array of
.Vt url_ent structures. The
.Vt url_ent structure is defined as follows in
.In fetch.h :
struct url_ent {
char name[MAXPATHLEN];
struct url_stat stat;
};

The list is terminated by an entry with an empty name.

The pointer returned by fetchListURL should be freed using free.

fetchXGet, fetchGet, fetchPut and fetchStat are similar to fetchXGetURL, fetchGetURL, fetchPutURL and fetchStatURL, except that they expect a pre-parsed URL in the form of a pointer to a
.Vt struct url rather than a string.

fetchXGetFile and fetchGetFile do not accept any flags.

If the ‘p’ (passive) flag is specified, a passive (rather than active) connection will be attempted.

If the ‘l’ (low) flag is specified, data sockets will be allocated in the low (or default) port range instead of the high port range (see ip(4)).

If the ‘d’ (direct) flag is specified, fetchXGetFTP, fetchGetFTP and fetchPutFTP will use a direct connection even if a proxy server is defined.

If the ‘d’ (direct) flag is specified, fetchXGetHTTP, fetchGetHTTP and fetchPutHTTP will use a direct connection even if a proxy server is defined.

int myAuthMethod "struct url *u"

The callback function should fill in the user and pwd fields in the provided
.Vt struct url and return 0 on success, or any other value to indicate failure.

To register the authentication callback, simply set fetchAuthMethod to point at it. The callback will be used whenever a site requires authentication and the appropriate environment variables are not set.

The fetchStat functions return 0 on success and -1 on failure.

All other functions return a stream pointer which may be used to access the requested document, or NULL if an error occurred.

The following error codes are defined in
.In fetch.h :

EXAMPLES

HISTORY

AUTHORS

BUGS