Second of a series of cleanups to libfetch.

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

1 files changed, 124 insertions, 38 deletions

diff --git a/lib/libfetch/fetch.3 b/lib/libfetch/fetch.3
index 2b4c63a..f384fd6 100644
--- a/lib/libfetch/fetch.3
+++ b/lib/libfetch/fetch.3
@@ -22,7 +22,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"	$Id: fetch.3,v 1.2 1998/09/26 20:42:44 des Exp $
+.\"	$Id: fetch.3,v 1.3 1998/11/05 19:48:16 des Exp $
 .\"
 .Dd July 1, 1998
 .Dt FETCH 3
@@ -30,15 +30,20 @@
 .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>
@@ -46,27 +51,36 @@
 .Fn fetchGetURL "char *URL" "char *flags"
 .Ft FILE *
 .Fn fetchPutURL "char *URL" "char *flags"
-.Ft url_t *
+.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 "url_t *URL" "char *flags"
+.Fn fetchGet "struct url *URL" "char *flags"
 .Ft FILE *
-.Fn fetchPut "url_t *URL" "char *flags"
+.Fn fetchPut "struct url *URL" "char *flags"
+.Ft int
+.Fn fetchStat "struct url *URL" "struct url_stat *us" "char *flags"
 .Ft FILE *
-.Fn fetchGetFile "url_t *u" "char *flags"
+.Fn fetchGetFile "struct url *u" "char *flags"
 .Ft FILE *
-.Fn fetchPutFile "url_t *u" "char *flags"
+.Fn fetchPutFile "struct url *u" "char *flags"
+.Ft int
+.Fn fetchStatFile "struct url *URL" "struct url_stat *us" "char *flags"
 .Ft FILE *
-.Fn fetchGetHTTP "url_t *u" "char *flags"
+.Fn fetchGetHTTP "struct url *u" "char *flags"
 .Ft FILE *
-.Fn fetchPutHTTP "url_t *u" "char *flags"
+.Fn fetchPutHTTP "struct url *u" "char *flags"
+.Ft int
+.Fn fetchStatHTTP "struct url *URL" "struct url_stat *us" "char *flags"
 .Ft FILE *
-.Fn fetchGetFTP "url_t *u" "char *flags"
+.Fn fetchGetFTP "struct url *u" "char *flags"
 .Ft FILE *
-.Fn fetchPutFTP "url_t *u" "char *flags"
-.Vt extern int         fetchLastErrCode;
-.Vt extern const char *fetchLastErrText;
+.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
@@ -83,6 +97,19 @@ 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
@@ -101,17 +128,19 @@ The pointer returned by
 should be freed using
 .Fn free .
 .Pp
-.Fn fetchGet
-and
+.Fn fetchGet ,
 .Fn fetchPut
+and
+.Fn fetchStat
 are similar to
-.Fn fetchGetURL
+.Fn fetchGetURL ,
+.Fn fetchPutURL
 and
-.Fn fetchPutURL ,
+.Fn fetchStatURL ,
 except that they expect a pre-parsed URL in the form of a pointer to
-an
-.Fa url_t
-structure rather than a string.
+a
+.Fa struct url
+rather than a string.
 .Pp
 All of the
 .Fn fetchGetXXX
@@ -175,19 +204,66 @@ is currently unimplemented.
 .Sh RETURN VALUES
 .Fn fetchParseURL
 returns a pointer to a
-.Fa url_t
-structure containing the individual components of the URL. If it is
+.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. In the
-latter case, the variables
-.Va fetchLastErrCode
-and
-.Va fetchLastErrText
-are set to appropriately descriptive values.
+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
@@ -196,6 +272,7 @@ and
 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
@@ -216,13 +293,14 @@ to use for transferring files.
 .%B File Transfer Protocol
 .%O RFC959
 .Re
-.Sh DIAGNOSTICS
-Add later.
 .Sh NOTES
-Some parts of the library are not yet implemented. The most notable
-examples of this are
-.Fn fetchPutHTTP
-and proxy support for the FTP access method.
+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
@@ -234,18 +312,26 @@ The
 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 Jordan K. Hubbard Aq jkh@FreeBSD.org ,
+.An Eugene Skepner Aq eu@qub.com
 and other FreeBSD developers.
-It incorporates the older
+It replaces the older
 .Nm ftpio
-library, which was originally written by
-.Nm Poul-Henning Kamp Aq pkh@FreeBSD.org
-and later turned inside out by
+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