93ce759c73
This commit introduces the following features:
a) the fetchStat*() functions, which return meta-information for a
document, such as size, modification time, etc.
b) the use of the com_err(3) facilities to report errors.
It also fixes a bunch of style bugs and a few logic bugs and somewhat
improves the man page.
Changed files, in alphabetical order:
Makefile:
Don't generate macros in {ftp,http}err.c.
Generate category fields for the error message lists.
Compile the error table.
Install fetch_err.h along with fetch.h.
common.c:
Remove the _netdb_errstring() macro, and add FETCH_ERR_NETDB to the
error code in the _netdb_seterr() macro.
Add categories to the _netdb_errlist table.
Report errors through the Common Error library.
common.h:
Add the DEBUG macros.
Add prototype for fetchConnect().
Remove the prototype for _fetch_errstring(), which is local to common.c
Add a categroy field to struct fetcherr, and define constants for
error categories.
Define macros for _{url,netdb,ftp,http}_seterr().
errors.et: (new file)
List error categories.
fetch.3:
Document the fetchStat*() functions.
Move the "unimplemented functionality" comments from NOTES to BUGS.
Document that applications which use libfetch must also use
libcom_err, and list existing error codes.
Undocument fetchLastErr{Code,String}.
Remove the (empty) DIAGNOSTICS section.
Mention Eugene Skepner in the AUTHORS section.
fetch.c:
Move the DEBUG macros to common.c
Add fetchStat() and fetchStatURL().
Generate error messages for URL parser errors, and fix a minor bug
in the parser.
Use 'struct url' instead of 'url_t'.
Remove fetchLastErr{Code,String}.
fetch.h:
Use 'struct url' instead of 'url_t', and remove the typedef.
Define struct url_stat (used by fetchStat()).
Add prototypes for fetchStat*().
Remove the declarations for fetchLastErr{Code,String}.
Include fetch_err.h.
fetch_err.et: (new file)
Error table for libfetch.
file.c:
Add fetchStatFile().
Use 'struct url' instead of 'url_t'.
ftp.c:
Add fetchStatFTP().
Use 'struct url' instead of 'url_t'.
Don't use fetchLastErrCode.
ftp.errors:
Add categories to all error messages.
http.c:
Add fetchStatHTTP().
Use 'struct url' instead of 'url_t'.
Don't use fetchLastErr{Code,Text}.
http.errors:
Add categories to all error messages.
Prompted by: jkh and Eugene Skepner
Numerous sugestions from: Garett Wollman and Eugene Skepner
366 lines
10 KiB
Groff
366 lines
10 KiB
Groff
.\" Copyright (c) 1998 Dag-Erling Coïdan Smørgrav
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $Id: fetch.3,v 1.3 1998/11/05 19:48:16 des Exp $
|
|
.\"
|
|
.Dd July 1, 1998
|
|
.Dt FETCH 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm fetchGetURL ,
|
|
.Nm fetchPutURL ,
|
|
.Nm fetchStatURL ,
|
|
.Nm fetchParseURL ,
|
|
.Nm fetchGet ,
|
|
.Nm fetchPut ,
|
|
.Nm fetchStat ,
|
|
.Nm fetchGetFile ,
|
|
.Nm fetchPutFile ,
|
|
.Nm fetchStatFile ,
|
|
.Nm fetchGetHTTP ,
|
|
.Nm fetchPutHTTP ,
|
|
.Nm fetchStatHTTP ,
|
|
.Nm fetchGetFTP ,
|
|
.Nm fetchPutFTP
|
|
.Nm fetchStatFTP
|
|
.Nd file transfer library
|
|
.Sh SYNOPSIS
|
|
.Fd #include <fetch.h>
|
|
.Ft FILE *
|
|
.Fn fetchGetURL "char *URL" "char *flags"
|
|
.Ft FILE *
|
|
.Fn fetchPutURL "char *URL" "char *flags"
|
|
.Ft int
|
|
.Fn fetchStatURL "char *URL" "struct url_stat *us" "char *flags"
|
|
.Ft struct url *
|
|
.Fn fetchParseURL "char *URL" "char *flags"
|
|
.Ft FILE *
|
|
.Fn fetchGet "struct url *URL" "char *flags"
|
|
.Ft FILE *
|
|
.Fn fetchPut "struct url *URL" "char *flags"
|
|
.Ft int
|
|
.Fn fetchStat "struct url *URL" "struct url_stat *us" "char *flags"
|
|
.Ft FILE *
|
|
.Fn fetchGetFile "struct url *u" "char *flags"
|
|
.Ft FILE *
|
|
.Fn fetchPutFile "struct url *u" "char *flags"
|
|
.Ft int
|
|
.Fn fetchStatFile "struct url *URL" "struct url_stat *us" "char *flags"
|
|
.Ft FILE *
|
|
.Fn fetchGetHTTP "struct url *u" "char *flags"
|
|
.Ft FILE *
|
|
.Fn fetchPutHTTP "struct url *u" "char *flags"
|
|
.Ft int
|
|
.Fn fetchStatHTTP "struct url *URL" "struct url_stat *us" "char *flags"
|
|
.Ft FILE *
|
|
.Fn fetchGetFTP "struct url *u" "char *flags"
|
|
.Ft FILE *
|
|
.Fn fetchPutFTP "struct url *u" "char *flags"
|
|
.Ft int
|
|
.Fn fetchStatFTP "struct url *URL" "struct url_stat *us" "char *flags"
|
|
.Sh DESCRIPTION
|
|
.Pp
|
|
These functions implement a high-level library for retrieving and
|
|
uploading files using Uniform Resource Locators (URLs).
|
|
.Pp
|
|
.Fn fetchGetURL
|
|
and
|
|
.Fn fetchPutURL
|
|
constitute the recommended interface to the
|
|
.Nm 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. The
|
|
.Fa 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.
|
|
.Pp
|
|
.Fn fetchStatURL
|
|
attempts to obtain the requested document's metadata and fill in the
|
|
structure pointed to by it's second argument. The
|
|
.Fa url_stat
|
|
structure is defined as follows in
|
|
.Aq Pa fetch.h :
|
|
.Bd -literal
|
|
struct url_stat {
|
|
off_t size;
|
|
time_t time;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
.Fn 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:
|
|
.Bd -literal
|
|
<scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)?
|
|
.Ed
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
The pointer returned by
|
|
.Fn fetchParseURL
|
|
should be freed using
|
|
.Fn free .
|
|
.Pp
|
|
.Fn fetchGet ,
|
|
.Fn fetchPut
|
|
and
|
|
.Fn fetchStat
|
|
are similar to
|
|
.Fn fetchGetURL ,
|
|
.Fn fetchPutURL
|
|
and
|
|
.Fn fetchStatURL ,
|
|
except that they expect a pre-parsed URL in the form of a pointer to
|
|
a
|
|
.Fa struct url
|
|
rather than a string.
|
|
.Pp
|
|
All of the
|
|
.Fn fetchGetXXX
|
|
and
|
|
.Fn fetchPutXXX
|
|
functions return a pointer to a stream which can be used to read or
|
|
write data from or to the requested document, respectively. Note that
|
|
although the implementation details of the individual access methods
|
|
vary, it can generally be assumed that a stream returned by one of the
|
|
.Fn fetchGetXXX
|
|
functions is read-only, and that a stream returned by one of the
|
|
.Fn fetchPutXXX
|
|
functions is write-only.
|
|
.Sh FILE SCHEME
|
|
.Fn fetchGetFile
|
|
and
|
|
.Fn fetchPutFile
|
|
provide access to documents which are files in a locally mounted file
|
|
system. Only the <document> component of the URL is used.
|
|
.Pp
|
|
.Fn fetchGetFile
|
|
does not accept any flags.
|
|
.Pp
|
|
.Fn fetchPutFile
|
|
accepts the
|
|
.Fa a
|
|
(append to file) flag. If that flag is specified, the data written to
|
|
the stream returned by
|
|
.Fn fetchPutFile
|
|
will be appended to the previous contents of the file, instead of
|
|
replacing them.
|
|
.Sh FTP SCHEME
|
|
.Fn fetchGetFTP
|
|
and
|
|
.Fn fetchPutFTP
|
|
implement the FTP protocol as described in RFC959.
|
|
.Pp
|
|
If the
|
|
.Fa p
|
|
(passive) flag is specified, a passive (rather than active) connection
|
|
will be attempted.
|
|
.Pp
|
|
If no user name or password is given, the
|
|
.Nm fetch
|
|
library will attempt an anonymous login, with user name "ftp" and
|
|
password "ftp".
|
|
.Sh HTTP SCHEME
|
|
The
|
|
.Fn fetchGetHTTP
|
|
and
|
|
.Fn fetchPutHTTP
|
|
functions implement the HTTP/1.1 protocol. With a little luck, there's
|
|
even a chance that they comply with RFC2068.
|
|
.Pp
|
|
Since there seems to be no good way of implementing the HTTP PUT
|
|
method in a manner consistent with the rest of the
|
|
.Nm fetch
|
|
library,
|
|
.Fn fetchPutHTTP
|
|
is currently unimplemented.
|
|
.Sh RETURN VALUES
|
|
.Fn fetchParseURL
|
|
returns a pointer to a
|
|
.Fa struct url
|
|
containing the individual components of the URL. If it is
|
|
unable to allocate memory, or the URL is syntactically incorrect,
|
|
.Fn fetchParseURL
|
|
returns a NULL pointer.
|
|
.Pp
|
|
The
|
|
.Fn fetchStat
|
|
functions return 0 on success and -1 on failure.
|
|
.Pp
|
|
All other functions return a stream pointer which may be used to
|
|
access the requested document, or NULL if an error occurred.
|
|
.Pp
|
|
.Nm Libfetch
|
|
uses the Common Error Library
|
|
.Nm ( libcom_err )
|
|
to report errors. The error code passed to
|
|
.Fn com_err
|
|
is one of:
|
|
.Bl -tag -width Er
|
|
.It Bq Er FETCH_ABORT
|
|
Operation aborted
|
|
.It Bq Er FETCH_AUTH
|
|
Authentication failed
|
|
.It Bq Er FETCH_DOWN
|
|
Service unavailable
|
|
.It Bq Er FETCH_EXISTS
|
|
File exists
|
|
.It Bq Er FETCH_FULL
|
|
File system full
|
|
.It Bq Er FETCH_INFO
|
|
Informational response
|
|
.It Bq Er FETCH_MEMORY
|
|
Insufficient memory
|
|
.It Bq Er FETCH_MOVED
|
|
File has moved
|
|
.It Bq Er FETCH_NETWORK
|
|
Network error
|
|
.It Bq Er FETCH_OK
|
|
No error
|
|
.It Bq Er FETCH_PROTO
|
|
Protocol error
|
|
.It Bq Er FETCH_RESOLV
|
|
Resolver error
|
|
.It Bq Er FETCH_SERVER
|
|
Server error
|
|
.It Bq Er FETCH_TEMP
|
|
Temporary error
|
|
.It Bq Er FETCH_TIMEOUT
|
|
Operation timed out
|
|
.It Bq Er FETCH_UNAVAIL
|
|
File is not available
|
|
.It Bq Er FETCH_UNKNOWN
|
|
Unknown error
|
|
.It Bq Er FETCH_URL
|
|
Invalid URL
|
|
.El
|
|
.Pp
|
|
The accompanying error message includes a protocol-specific error code
|
|
and message, e.g. "File is not available (404 Not Found)"
|
|
.Sh ENVIRONMENT
|
|
The FTP and HTTP related functions use the
|
|
.Ev HTTP_PROXY
|
|
and
|
|
.Ev FTP_PROXY
|
|
environment variables, respectively, as the address of a proxy server
|
|
to use for transferring files.
|
|
.Sh SEE ALSO
|
|
.Xr com_err 3 ,
|
|
.Xr fetch 1 ,
|
|
.Xr ftpio 3
|
|
.Rs
|
|
.%A T. Berners-Lee, L. Masinter & M. McCahill
|
|
.%D December 1994
|
|
.%T Uniform Resource Locators (URL)
|
|
.%O RFC1738
|
|
.Re
|
|
.Rs
|
|
.%A R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners-Lee
|
|
.%D Januray 1997
|
|
.%B Hypertext Transfer Protocol -- HTTP/1.1
|
|
.%O RFC2068
|
|
.Re
|
|
.Rs
|
|
.%A J. Postel, J. K. Reynolds
|
|
.%D October 1985
|
|
.%B File Transfer Protocol
|
|
.%O RFC959
|
|
.Re
|
|
.Sh NOTES
|
|
The
|
|
.Nm fetch
|
|
library uses the Common Error library, and applications which link
|
|
with
|
|
.Nm libfetch
|
|
must therefore also link with
|
|
.Nm libcom_err .
|
|
.Sh HISTORY
|
|
The
|
|
.Nm fetch
|
|
library first appeared in
|
|
.Fx 3.0 .
|
|
.Sh AUTHORS
|
|
The
|
|
.Nm fetch
|
|
library was mostly written by
|
|
.An Dag-Erling Coïdan Smørgrav Aq des@FreeBSD.org
|
|
with numerous suggestions from
|
|
.An Jordan K. Hubbard Aq jkh@FreeBSD.org ,
|
|
.An Eugene Skepner Aq eu@qub.com
|
|
and other FreeBSD developers.
|
|
It replaces the older
|
|
.Nm ftpio
|
|
library written by
|
|
.An Poul-Henning Kamp Aq pkh@FreeBSD.org
|
|
and
|
|
.An Jordan K. Hubbard Aq jkh@FreeBSD.org .
|
|
.Pp
|
|
This manual page was written by
|
|
.An Dag-Erling Coïdan Smørgrav Aq des@FreeBSD.org
|
|
.Sh BUGS
|
|
Some parts of the library are not yet implemented. The most notable
|
|
examples of this are
|
|
.Fn fetchPutHTTP ,
|
|
.Fn fetchStatFTP ,
|
|
.Fn fetchStatHTTP
|
|
and FTP proxy support.
|
|
.Pp
|
|
There's no way to select a proxy at run-time other than setting the
|
|
.Ev HTTP_PROXY
|
|
or
|
|
.Ev FTP_PROXY
|
|
environment variables as appropriate. There is also no way to stop the
|
|
FTP and HTTP functions from trying to use a proxy if these variables
|
|
are set.
|
|
.Pp
|
|
HTTP authentication doesn't work. I'm not sure that's a bug in my
|
|
code; as far as I can determine,
|
|
.Nm libfetch
|
|
handles HTTP/1.1 basic authentication correctly as outlined in
|
|
RFC2068, but I haven't been able to find an HTTP server that honors
|
|
the Authentication: header field. Also,
|
|
.Nm libfetch
|
|
does not attempt to interpret and respond to authentication requests
|
|
from the HTTP server.
|
|
.Pp
|
|
No attempt is made to encode spaces etc. within URLs. Spaces in the
|
|
document part of an URLshould be replaced with "%20" in HTTP URLs and
|
|
"\\ " in FTP URLs.
|
|
.Pp
|
|
Error numbers are unique only within a certain context; the error
|
|
codes used for FTP and HTTP overlap, as do those used for resolver and
|
|
system errors. For instance, error code 202 means "Command not
|
|
implemented, superfluous at this site" in an FTP context and
|
|
"Accepted" in an HTTP context.
|
|
.Pp
|
|
The man page is poorly written and produces badly formatted text.
|
|
.Pp
|
|
Tons of other stuff.
|