Correctly regen the cat page.

1 files changed, 484 insertions, 176 deletions

diff --git a/net/libfetch/files/fetch.cat3 b/net/libfetch/files/fetch.cat3
index 90556f69839..0e10929d612 100644
--- a/net/libfetch/files/fetch.cat3
+++ b/net/libfetch/files/fetch.cat3
@@ -1,198 +1,506 @@
-These functions implement a high-level library for retrieving and
-uploading files using Uniform Resource Locators (URLs).  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 RFC 1738.  A regular expression which produces
-this  syntax  is:  scheme:(//(user(:pwd)?@)?host(:port)?)?/(docu-
-ment)?   If the URL does not seem to begin with a scheme name, it
-is assumed to be a local path.  Only absolute path names are  ac-
-cepted.  Note that some components of the URL are not necessarily
-relevant to all URL schemes.  For instance, the file scheme  only
-needs the and components.  quotes any unsafe character in the URL
-automatically.  This is not done by copies an existing structure.
-and  return a pointer to a structure, which is defined as follows
-in #define  URL_SCHEMELEN  16  #define  URL_USERLEN  256  #define
-URL_PWDLEN 256 #define URL_HOSTLEN 255
-
-struct url {
-    char         scheme[URL_SCHEMELEN + 1];
-    char         user[URL_USERLEN + 1];
-    char         pwd[URL_PWDLEN + 1];
-    char         host[URL_HOSTLEN + 1];
-    int          port;
-    char        *doc;
-    off_t        offset;
-    size_t       length;
-    time_t        last_modified;  };  The pointer returned by and
-should be freed using The size of is not part of  the  ABI.   and
-constitute  the recommended interface to the library.  They exam-
-ine the URL passed to them to determine the transfer method,  and
-call  the appropriate lower-level functions to perform the actual
-transfer.  also returns the remote  document's  metadata  in  the
-structure  pointed  to by the argument.  The argument is a string
-of characters which specify transfer options.  The meaning of the
-individual  flags is scheme-dependent, and is detailed in the ap-
-propriate section below.  attempts to obtain the requested  docu-
-ment's  metadata and fill in the structure pointed to by its sec-
-ond argument.  The structure is  defined  as  follows  in  struct
-url_stat {
-    off_t        size;
-    time_t       atime;
-    time_t       mtime; }; If the size could not be obtained from
-the server, the field is set to -1.   If  the  modification  time
-could  not  be  obtained from the server, the field is set to the
-epoch.  If the access time could not be obtained from the server,
-the  field is set to the modification time.  attempts to list the
-contents of the directory pointed to by the  URL  provided.   The
-pattern  can  be  a simple glob-like expression as hint.  Callers
-should not depend on the server to filter names.  If  successful,
-it  appends  the list of entries to the structure.  The structure
-is defined as follows in struct url_list {
-    size_t      length;
-    size_t      alloc_size;
-    struct url  *urls; }; The list should be initialized by call-
-ing  and  the  entries  be  freed  by  calling returns the URL as
-string.  returns the path name part of the URL with  any  quoting
-undone.  Query arguments and fragment identifiers are not includ-
-ed.  returns the last component of the path name as  returned  by
-and  return  a  string that should be deallocated with after use.
-and are similar to and except that they expect a  pre-parsed  URL
-in  the  form of a pointer to a rather than a string.  All of the
-and functions return a pointer to a stream which can be  used  to
-read or write data from or to the requested document, respective-
-ly.  Note that although the implementation details of  the  indi-
-vidual  access  methods  vary, it can generally be assumed that a
-stream returned by one of the or functions is read-only, and that
-a  stream returned by one of the functions is write-only.  If the
-(if-modified-since) flag is specified, the library  will  try  to
-fetch the content only if it is newer than For HTTP an HTTP head-
-er is sent.  For FTP a command is sent first and compared  local-
-ly.  For FILE the source file is compared.  and provide access to
-documents which are files in a locally mounted file system.  Only
-the  component  of the URL is used.  and do not accept any flags.
-accepts the (append to file) flag.  If that  flag  is  specified,
-the  data  written  to the stream returned by will be appended to
-the previous contents of the file,  instead  of  replacing  them.
-and  implement  the FTP protocol as described in RFC 959.  By de-
-fault will attempt to use passive mode first and only fallback to
-active  mode  if  the server reports a syntax error.  If the (ac-
-tive) flag is specified, a passive connection is  not  tried  and
-active  mode  is  used directly.  If the (low) flag is specified,
-data sockets will be allocated in the low (or default) port range
-instead of the high port range (see If the (direct) flag is spec-
-ified, and will use a direct connection even if a proxy server is
-defined.   If no user name or password is given, the library will
-attempt an anonymous login, with user name "anonymous" and  pass-
-word  "anonymous@hostname".   The  and  functions  implement  the
-HTTP/1.1 protocol.  With a little luck, there is  even  a  chance
-that  they  comply  with  RFC 2616 and RFC 2617.  If the (direct)
-flag is specified, and will use a direct  connection  even  if  a
-proxy  server is defined.  Since there seems to be no good way of
-implementing the HTTP PUT method in a manner consistent with  the
-rest of the library, is currently unimplemented.  Apart from set-
-ting the appropriate environment variables and specifying the us-
-er  name  and  password in the URL or the the calling program has
-the option of defining an authentication function with  the  fol-
-lowing  prototype:  The  callback function should fill in the and
-fields in the provided and return 0 on success, or any other val-
-ue to indicate failure.  To register the authentication callback,
-simply set to point at it.  The callback will be used whenever  a
-site  requires  authentication  and  the  appropriate environment
-variables are not set.  This interface is experimental and may be
-subject  to  change.  returns a pointer to a containing the indi-
-vidual components of the URL.  If it is unable to allocate  memo-
-ry,  or  the  URL  is syntactically incorrect, returns a pointer.
-The 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 if an error occurred.  The following error
-codes are defined in Operation aborted Authentication failed Ser-
-vice unavailable File exists File system full  Informational  re-
-sponse  Insufficient memory File has moved Network error No error
-Protocol error Resolver error Server error Temporary error Opera-
-tion  timed  out  File is not available Unknown error Invalid URL
-The accompanying error message includes a protocol-specific error
-code  and  message,  e.g. "File is not available (404 Not Found)"
-Specifies a host name or IP address to  which  sockets  used  for
-outgoing  connections  will  be bound.  Default FTP login if none
-was provided in the URL.  If set to anything but forces  the  FTP
-code  to  use  passive  mode.  Default FTP password if the remote
-server requests one and none was provided in the URL.  URL of the
-proxy  to  use  for  FTP requests.  The document part is ignored.
-FTP and HTTP proxies are supported; if no  scheme  is  specified,
-FTP  is assumed.  If the proxy is an FTP proxy, will send as user
-name to the proxy, where is the real user name, and is  the  name
-of  the  FTP server.  If this variable is set to an empty string,
-no proxy will be used for FTP requests, even if the  variable  is
-set.   Same  as  for compatibility.  Specifies HTTP authorization
-parameters as a colon-separated list of  items.   The  first  and
-second  item are the authorization scheme and realm respectively;
-further items are scheme-dependent.  Currently, only basic autho-
-rization  is supported.  Basic authorization requires two parame-
-ters: the user name and password, in that order.   This  variable
-is  only  used  if  the server requires authorization and no user
-name or password was specified in the URL.  URL of the  proxy  to
-use  for HTTP requests.  The document part is ignored.  Only HTTP
-proxies are supported for HTTP requests.  If no  port  number  is
-specified,  the  default is 3128.  Note that this proxy will also
-be used for FTP documents, unless the variable is set.   Same  as
-for  compatibility.   Specifies  authorization parameters for the
-HTTP proxy in the same format as the variable.  This variable  is
-used if and only if connected to an HTTP proxy, and is ignored if
-a user and/or a password were specified in the proxy URL.  Speci-
-fies  the  referrer  URL to use for HTTP requests.  If set to the
-document URL will be used as referrer URL.  Specifies  the  User-
-Agent  string  to use for HTTP requests.  This can be useful when
-working with HTTP origin or proxy servers that differentiate  be-
-tween user agents.  Specifies a file to use instead of to look up
-login names and passwords for FTP sites.  See for  a  description
-of the file format.  This feature is experimental.  Either a sin-
-gle asterisk, which disables the use of proxies altogether, or  a
-comma-  or  whitespace-separated  list of hosts for which proxies
-should not be used.  Same as  for  compatibility.   To  access  a
-proxy server on port 8080, set the environment variable in a man-
-ner similar to this: If the proxy server requires authentication,
-there  are  two  options available for passing the authentication
-data.  The first method is by using the  proxy  URL:  The  second
-method     is     by     using    the    environment    variable:
-HTTP_PROXY=http://proxy.example.com:8080      HTTP_PROXY_AUTH=ba-
-sic:*:user:pwd  To  disable the use of a proxy for an HTTP server
-running on the local host,  define  as  follows:  NO_PROXY=local-
-host,127.0.0.1  The  library  first  appeared  in The library was
-mostly written by with numerous suggestions from and other devel-
-opers.   It replaces the older library written by and This manual
-page was written by Some parts of the library are not yet  imple-
-mented.  The most notable examples of this are and FTP proxy sup-
-port.  There is no way to select a proxy at run-time  other  than
-setting  the  or  environment variables as appropriate.  does not
-understand or obey 305 (Use Proxy) replies.   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 imple-
-mented, superfluous at this site" in an FTP context and  "Accept-
-ed"  in  an  HTTP  context.  does not check that the result of an
-MDTM command is a valid date.  The man page is incomplete, poorly
-written  and  produces badly formatted text.  The error reporting
-mechanism is unsatisfactory.  Some parts of the code are not ful-
-ly reentrant.
+FETCH(3)                NetBSD Library Functions Manual               FETCH(3)
 
+NNAAMMEE
+     ffeettcchhMMaakkeeUURRLL, ffeettcchhPPaarrsseeUURRLL, ffeettcchhCCooppyyUURRLL, ffeettcchhFFrreeeeUURRLL, ffeettcchhXXGGeettUURRLL,
+     ffeettcchhGGeettUURRLL, ffeettcchhPPuuttUURRLL, ffeettcchhSSttaattUURRLL, ffeettcchhLLiissttUURRLL, ffeettcchhXXGGeett,
+     ffeettcchhGGeett, ffeettcchhPPuutt, ffeettcchhSSttaatt, ffeettcchhLLiisstt, ffeettcchhXXGGeettFFiillee, ffeettcchhGGeettFFiillee,
+     ffeettcchhPPuuttFFiillee, ffeettcchhSSttaattFFiillee, ffeettcchhLLiissttFFiillee, ffeettcchhXXGGeettHHTTTTPP, ffeettcchhGGeettHHTTTTPP,
+     ffeettcchhPPuuttHHTTTTPP, ffeettcchhSSttaattHHTTTTPP, ffeettcchhLLiissttHHTTTTPP, ffeettcchhXXGGeettFFTTPP, ffeettcchhGGeettFFTTPP,
+     ffeettcchhPPuuttFFTTPP, ffeettcchhSSttaattFFTTPP, ffeettcchhLLiissttFFTTPP ffeettcchhIInniittUURRLLLLiisstt,
+     ffeettcchhFFrreeeeUURRLLLLiisstt, ffeettcchhUUnnqquuootteePPaatthh, ffeettcchhUUnnqquuootteeFFiilleennaammee,
+     ffeettcchhSSttrriinnggiiffyyUURRLL, ffeettcchh -- file transfer functions
 
+LLIIBBRRAARRYY
+               File Transfer Library for URLs (libfetch, -lfetch)
 
+SSYYNNOOPPSSIISS
+     ##iinncclluuddee <<ssttddiioo..hh>>
+     ##iinncclluuddee <<ffeettcchh..hh>>
 
+     _s_t_r_u_c_t _u_r_l _*
+     ffeettcchhMMaakkeeUURRLL(_c_o_n_s_t _c_h_a_r _*_s_c_h_e_m_e, _c_o_n_s_t _c_h_a_r _*_h_o_s_t, _i_n_t _p_o_r_t,
+         _c_o_n_s_t _c_h_a_r _*_d_o_c, _c_o_n_s_t _c_h_a_r _*_u_s_e_r, _c_o_n_s_t _c_h_a_r _*_p_w_d);
 
+     _s_t_r_u_c_t _u_r_l _*
+     ffeettcchhPPaarrsseeUURRLL(_c_o_n_s_t _c_h_a_r _*_U_R_L);
 
+     _s_t_r_u_c_t _u_r_l _*
+     ffeettcchhCCooppyyUURRLL(_c_o_n_s_t _s_t_r_u_c_t _u_r_l _*_u);
 
+     _v_o_i_d
+     ffeettcchhFFrreeeeUURRLL(_s_t_r_u_c_t _u_r_l _*_u);
 
+     _f_e_t_c_h_I_O _*
+     ffeettcchhXXGGeettUURRLL(_c_o_n_s_t _c_h_a_r _*_U_R_L, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
 
+     _f_e_t_c_h_I_O _*
+     ffeettcchhGGeettUURRLL(_c_o_n_s_t _c_h_a_r _*_U_R_L, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
 
+     _f_e_t_c_h_I_O _*
+     ffeettcchhPPuuttUURRLL(_c_o_n_s_t _c_h_a_r _*_U_R_L, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
 
+     _i_n_t
+     ffeettcchhSSttaattUURRLL(_c_o_n_s_t _c_h_a_r _*_U_R_L, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
 
+     _i_n_t
+     ffeettcchhLLiissttUURRLL(_s_t_r_u_c_t _u_r_l___l_i_s_t _*_l_i_s_t, _c_o_n_s_t _c_h_a_r _*_U_R_L, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
 
+     _f_e_t_c_h_I_O _*
+     ffeettcchhXXGGeett(_s_t_r_u_c_t _u_r_l _*_u, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
 
+     _f_e_t_c_h_I_O _*
+     ffeettcchhGGeett(_s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
 
+     _f_e_t_c_h_I_O _*
+     ffeettcchhPPuutt(_s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
 
+     _i_n_t
+     ffeettcchhSSttaatt(_s_t_r_u_c_t _u_r_l _*_u, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
 
+     _i_n_t
+     ffeettcchhLLiisstt(_s_t_r_u_c_t _u_r_l___l_i_s_t _*_l_i_s_t, _s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
 
+     _f_e_t_c_h_I_O _*
+     ffeettcchhXXGGeettFFiillee(_s_t_r_u_c_t _u_r_l _*_u, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
 
+     _f_e_t_c_h_I_O _*
+     ffeettcchhGGeettFFiillee(_s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
 
+     _f_e_t_c_h_I_O _*
+     ffeettcchhPPuuttFFiillee(_s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
 
+     _i_n_t
+     ffeettcchhSSttaattFFiillee(_s_t_r_u_c_t _u_r_l _*_u, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
 
+     _i_n_t
+     ffeettcchhLLiissttFFiillee(_s_t_r_u_c_t _u_r_l___l_i_s_t _*_l_i_s_t, _s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
+
+     _f_e_t_c_h_I_O _*
+     ffeettcchhXXGGeettHHTTTTPP(_s_t_r_u_c_t _u_r_l _*_u, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
+
+     _f_e_t_c_h_I_O _*
+     ffeettcchhGGeettHHTTTTPP(_s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
+
+     _f_e_t_c_h_I_O _*
+     ffeettcchhPPuuttHHTTTTPP(_s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
+
+     _i_n_t
+     ffeettcchhSSttaattHHTTTTPP(_s_t_r_u_c_t _u_r_l _*_u, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
+
+     _i_n_t
+     ffeettcchhLLiissttHHTTTTPP(_s_t_r_u_c_t _u_r_l___l_i_s_t _*_l_i_s_t, _s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
+
+     _f_e_t_c_h_I_O _*
+     ffeettcchhXXGGeettFFTTPP(_s_t_r_u_c_t _u_r_l _*_u, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
+
+     _f_e_t_c_h_I_O _*
+     ffeettcchhGGeettFFTTPP(_s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
+
+     _f_e_t_c_h_I_O _*
+     ffeettcchhPPuuttFFTTPP(_s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
+
+     _i_n_t
+     ffeettcchhSSttaattFFTTPP(_s_t_r_u_c_t _u_r_l _*_u, _s_t_r_u_c_t _u_r_l___s_t_a_t _*_u_s, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
+
+     _i_n_t
+     ffeettcchhLLiissttFFTTPP(_s_t_r_u_c_t _u_r_l___l_i_s_t _*_l_i_s_t, _s_t_r_u_c_t _u_r_l _*_u, _c_o_n_s_t _c_h_a_r _*_f_l_a_g_s);
+
+     _v_o_i_d
+     ffeettcchhIInniittUURRLLLLiisstt(_s_t_r_u_c_t _u_r_l___l_i_s_t _*_u_l);
+
+     _v_o_i_d
+     ffeettcchhFFrreeeeUURRLLLLiisstt(_s_t_r_u_c_t _u_r_l___l_i_s_t _*_u_l);
+
+     _c_h_a_r _*
+     ffeettcchhUUnnqquuootteePPaatthh(_s_t_r_u_c_t _u_r_l _*_u);
+
+     _c_h_a_r _*
+     ffeettcchhUUnnqquuootteeFFiilleennaammee(_s_t_r_u_c_t _u_r_l _*_u);
+
+     _c_h_a_r _*
+     ffeettcchhSSttrriinnggiiffyyUURRLL(_c_o_n_s_t _s_t_r_u_c_t _u_r_l _*_u);
+
+DDEESSCCRRIIPPTTIIOONN
+     These functions implement a high-level library for retrieving and upload-
+     ing files using Uniform Resource Locators (URLs).
+
+     ffeettcchhPPaarrsseeUURRLL() 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 RFC 1738.  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, it is assumed to be
+     a local path.  Only absolute path names are accepted.
+
+     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.  ffeettcchhPPaarrsseeUURRLL() quotes any unsafe character in
+     the URL automatically.  This is not done by ffeettcchhMMaakkeeUURRLL().
+     ffeettcchhCCooppyyUURRLL() copies an existing _u_r_l structure.
+
+     ffeettcchhMMaakkeeUURRLL(), ffeettcchhPPaarrsseeUURRLL(), and ffeettcchhCCooppyyUURRLL() return a pointer to a
+     _u_r_l structure, which is defined as follows in <_f_e_t_c_h_._h>:
+
+     #define URL_SCHEMELEN 16
+     #define URL_USERLEN 256
+     #define URL_PWDLEN 256
+     #define URL_HOSTLEN 255
+
+     struct url {
+         char         scheme[URL_SCHEMELEN + 1];
+         char         user[URL_USERLEN + 1];
+         char         pwd[URL_PWDLEN + 1];
+         char         host[URL_HOSTLEN + 1];
+         int          port;
+         char        *doc;
+         off_t        offset;
+         size_t       length;
+         time_t       last_modified;
+     };
+
+     The pointer returned by ffeettcchhMMaakkeeUURRLL(), ffeettcchhCCooppyyUURRLL(), and
+     ffeettcchhPPaarrsseeUURRLL() should be freed using ffeettcchhFFrreeeeUURRLL().  The size of _s_t_r_u_c_t
+     _U_R_L is not part of the ABI.
+
+     ffeettcchhXXGGeettUURRLL(), ffeettcchhGGeettUURRLL(), and ffeettcchhPPuuttUURRLL() constitute the recom-
+     mended interface to the ffeettcchh 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.  ffeettcchhXXGGeettUURRLL() also
+     returns the remote document's metadata in the _u_r_l___s_t_a_t structure pointed
+     to by the _u_s argument.
+
+     The _f_l_a_g_s 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.
+
+     ffeettcchhSSttaattUURRLL() attempts to obtain the requested document's metadata and
+     fill in the structure pointed to by its second argument.  The _u_r_l___s_t_a_t
+     structure is defined as follows in <_f_e_t_c_h_._h>:
+
+     struct url_stat {
+         off_t        size;
+         time_t       atime;
+         time_t       mtime;
+     };
+
+     If the size could not be obtained from the server, the _s_i_z_e field is set
+     to -1.  If the modification time could not be obtained from the server,
+     the _m_t_i_m_e field is set to the epoch.  If the access time could not be
+     obtained from the server, the _a_t_i_m_e field is set to the modification
+     time.
+
+     ffeettcchhLLiissttUURRLL() attempts to list the contents of the directory pointed to
+     by the URL provided.  The pattern can be a simple glob-like expression as
+     hint.  Callers should not depend on the server to filter names.  If suc-
+     cessful, it appends the list of entries to the _u_r_l___l_i_s_t structure.  The
+     _u_r_l___l_i_s_t structure is defined as follows in <_f_e_t_c_h_._h>:
+
+     struct url_list {
+         size_t      length;
+         size_t      alloc_size;
+         struct url  *urls;
+     };
+
+     The list should be initialized by calling ffeettcchhIInniittUURRLLLLiisstt() and the
+     entries be freed by calling ffeettcchhFFrreeeeUURRLLLLiisstt().
+
+     ffeettcchhSSttrriinnggiiffyyUURRLL() returns the URL as string.  ffeettcchhUUnnqquuootteePPaatthh()
+     returns the path name part of the URL with any quoting undone.  Query
+     arguments and fragment identifiers are not included.
+     ffeettcchhUUnnqquuootteeFFiilleennaammee() returns the last component of the path name as
+     returned by ffeettcchhUUnnqquuootteePPaatthh().  ffeettcchhSSttrriinnggiiffyyUURRLL(), ffeettcchhUUnnqquuootteePPaatthh(),
+     and ffeettcchhUUnnqquuootteeFFiilleennaammee() return a string that should be deallocated
+     with ffrreeee() after use.
+
+     ffeettcchhXXGGeett(), ffeettcchhGGeett(), ffeettcchhPPuutt(), and ffeettcchhSSttaatt() are similar to
+     ffeettcchhXXGGeettUURRLL(), ffeettcchhGGeettUURRLL(), ffeettcchhPPuuttUURRLL(), and ffeettcchhSSttaattUURRLL(), except
+     that they expect a pre-parsed URL in the form of a pointer to a _s_t_r_u_c_t
+     _u_r_l rather than a string.
+
+     All of the ffeettcchhXXGGeettXXXXXX(), ffeettcchhGGeettXXXXXX(), and ffeettcchhPPuuttXXXXXX() 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 gen-
+     erally be assumed that a stream returned by one of the ffeettcchhXXGGeettXXXXXX() or
+     ffeettcchhGGeettXXXXXX() functions is read-only, and that a stream returned by one
+     of the ffeettcchhPPuuttXXXXXX() functions is write-only.
+
+PPRROOTTOOCCOOLL IINNDDEEPPEENNDDEENNTT FFLLAAGGSS
+     If the `i' (if-modified-since) flag is specified, the library will try to
+     fetch the content only if it is newer than _l_a_s_t___m_o_d_i_f_i_e_d.  For HTTP an
+     If-Modified-Since HTTP header is sent.  For FTP a MTDM command is sent
+     first and compared locally.  For FILE the source file is compared.
+
+FFIILLEE SSCCHHEEMMEE
+     ffeettcchhXXGGeettFFiillee(), ffeettcchhGGeettFFiillee(), and ffeettcchhPPuuttFFiillee() provide access to
+     documents which are files in a locally mounted file system.  Only the
+     <document> component of the URL is used.
+
+     ffeettcchhXXGGeettFFiillee() and ffeettcchhGGeettFFiillee() do not accept any flags.
+
+     ffeettcchhPPuuttFFiillee() accepts the `a' (append to file) flag.  If that flag is
+     specified, the data written to the stream returned by ffeettcchhPPuuttFFiillee() will
+     be appended to the previous contents of the file, instead of replacing
+     them.
+
+FFTTPP SSCCHHEEMMEE
+     ffeettcchhXXGGeettFFTTPP(), ffeettcchhGGeettFFTTPP(), and ffeettcchhPPuuttFFTTPP() implement the FTP proto-
+     col as described in RFC 959.
+
+     By default lliibbffeettcchh will attempt to use passive mode first and only fall-
+     back to active mode if the server reports a syntax error.  If the `a'
+     (active) flag is specified, a passive connection is not tried and active
+     mode is used directly.
+
+     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, ffeettcchhXXGGeettFFTTPP(), ffeettcchhGGeettFFTTPP(), and
+     ffeettcchhPPuuttFFTTPP() will use a direct connection even if a proxy server is
+     defined.
+
+     If no user name or password is given, the ffeettcchh library will attempt an
+     anonymous login, with user name "anonymous" and password "anony-
+     mous@<hostname>".
+
+HHTTTTPP SSCCHHEEMMEE
+     The ffeettcchhXXGGeettHHTTTTPP(), ffeettcchhGGeettHHTTTTPP(), and ffeettcchhPPuuttHHTTTTPP() functions imple-
+     ment the HTTP/1.1 protocol.  With a little luck, there is even a chance
+     that they comply with RFC 2616 and RFC 2617.
+
+     If the `d' (direct) flag is specified, ffeettcchhXXGGeettHHTTTTPP(), ffeettcchhGGeettHHTTTTPP(),
+     and ffeettcchhPPuuttHHTTTTPP() will use a direct connection even if a proxy server is
+     defined.
+
+     Since there seems to be no good way of implementing the HTTP PUT method
+     in a manner consistent with the rest of the ffeettcchh library, ffeettcchhPPuuttHHTTTTPP()
+     is currently unimplemented.
+
+AAUUTTHHEENNTTIICCAATTIIOONN
+     Apart from setting the appropriate environment variables and specifying
+     the user name and password in the URL or the _s_t_r_u_c_t _u_r_l, the calling pro-
+     gram has the option of defining an authentication function with the fol-
+     lowing prototype:
+
+     _i_n_t mmyyAAuutthhMMeetthhoodd(_s_t_r_u_c_t _u_r_l _*_u)
+
+     The callback function should fill in the _u_s_e_r and _p_w_d fields in the pro-
+     vided _s_t_r_u_c_t _u_r_l and return 0 on success, or any other value to indicate
+     failure.
+
+     To register the authentication callback, simply set _f_e_t_c_h_A_u_t_h_M_e_t_h_o_d to
+     point at it.  The callback will be used whenever a site requires authen-
+     tication and the appropriate environment variables are not set.
+
+     This interface is experimental and may be subject to change.
+
+RREETTUURRNN VVAALLUUEESS
+     ffeettcchhPPaarrsseeUURRLL() returns a pointer to a _s_t_r_u_c_t _u_r_l containing the individ-
+     ual components of the URL.  If it is unable to allocate memory, or the
+     URL is syntactically incorrect, ffeettcchhPPaarrsseeUURRLL() returns a NULL pointer.
+
+     The ffeettcchhSSttaatt() 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 <_f_e_t_c_h_._h>:
+
+     [FETCH_ABORT]       Operation aborted
+
+     [FETCH_AUTH]        Authentication failed
+
+     [FETCH_DOWN]        Service unavailable
+
+     [FETCH_EXISTS]      File exists
+
+     [FETCH_FULL]        File system full
+
+     [FETCH_INFO]        Informational response
+
+     [FETCH_MEMORY]      Insufficient memory
+
+     [FETCH_MOVED]       File has moved
+
+     [FETCH_NETWORK]     Network error
+
+     [FETCH_OK]          No error
+
+     [FETCH_PROTO]       Protocol error
+
+     [FETCH_RESOLV]      Resolver error
+
+     [FETCH_SERVER]      Server error
+
+     [FETCH_TEMP]        Temporary error
+
+     [FETCH_TIMEOUT]     Operation timed out
+
+     [FETCH_UNAVAIL]     File is not available
+
+     [FETCH_UNKNOWN]     Unknown error
+
+     [FETCH_URL]         Invalid URL
+
+     The accompanying error message includes a protocol-specific error code
+     and message, e.g. "File is not available (404 Not Found)"
+
+EENNVVIIRROONNMMEENNTT
+     FETCH_BIND_ADDRESS  Specifies a host name or IP address to which sockets
+                         used for outgoing connections will be bound.
+
+     FTP_LOGIN           Default FTP login if none was provided in the URL.
+
+     FTP_PASSIVE_MODE    If set to anything but `no', forces the FTP code to
+                         use passive mode.
+
+     FTP_PASSWORD        Default FTP password if the remote server requests
+                         one and none was provided in the URL.
+
+     FTP_PROXY           URL of the proxy to use for FTP requests.  The docu-
+                         ment part is ignored.  FTP and HTTP proxies are sup-
+                         ported; if no scheme is specified, FTP is assumed.
+                         If the proxy is an FTP proxy, lliibbffeettcchh will send
+                         `user@host' as user name to the proxy, where `user'
+                         is the real user name, and `host' is the name of the
+                         FTP server.
+
+                         If this variable is set to an empty string, no proxy
+                         will be used for FTP requests, even if the HTTP_PROXY
+                         variable is set.
+
+     ftp_proxy           Same as FTP_PROXY, for compatibility.
+
+     HTTP_AUTH           Specifies HTTP authorization parameters as a colon-
+                         separated list of items.  The first and second item
+                         are the authorization scheme and realm respectively;
+                         further items are scheme-dependent.  Currently, only
+                         basic authorization is supported.
+
+                         Basic authorization requires two parameters: the user
+                         name and password, in that order.
+
+                         This variable is only used if the server requires
+                         authorization and no user name or password was speci-
+                         fied in the URL.
+
+     HTTP_PROXY          URL of the proxy to use for HTTP requests.  The docu-
+                         ment part is ignored.  Only HTTP proxies are sup-
+                         ported for HTTP requests.  If no port number is spec-
+                         ified, the default is 3128.
+
+                         Note that this proxy will also be used for FTP docu-
+                         ments, unless the FTP_PROXY variable is set.
+
+     http_proxy          Same as HTTP_PROXY, for compatibility.
+
+     HTTP_PROXY_AUTH     Specifies authorization parameters for the HTTP proxy
+                         in the same format as the HTTP_AUTH variable.
+
+                         This variable is used if and only if connected to an
+                         HTTP proxy, and is ignored if a user and/or a pass-
+                         word were specified in the proxy URL.
+
+     HTTP_REFERER        Specifies the referrer URL to use for HTTP requests.
+                         If set to ``auto'', the document URL will be used as
+                         referrer URL.
+
+     HTTP_USER_AGENT     Specifies the User-Agent string to use for HTTP
+                         requests.  This can be useful when working with HTTP
+                         origin or proxy servers that differentiate between
+                         user agents.
+
+     NETRC               Specifies a file to use instead of _~_/_._n_e_t_r_c to look
+                         up login names and passwords for FTP sites.  See
+                         ftp(1) for a description of the file format.  This
+                         feature is experimental.
+
+     NO_PROXY            Either a single asterisk, which disables the use of
+                         proxies altogether, or a comma- or whitespace-sepa-
+                         rated list of hosts for which proxies should not be
+                         used.
+
+     no_proxy            Same as NO_PROXY, for compatibility.
+
+EEXXAAMMPPLLEESS
+     To access a proxy server on _p_r_o_x_y_._e_x_a_m_p_l_e_._c_o_m port 8080, set the
+     HTTP_PROXY environment variable in a manner similar to this:
+
+           HTTP_PROXY=http://proxy.example.com:8080
+
+     If the proxy server requires authentication, there are two options avail-
+     able for passing the authentication data.  The first method is by using
+     the proxy URL:
+
+           HTTP_PROXY=http://<user>:<pwd>@proxy.example.com:8080
+
+     The second method is by using the HTTP_PROXY_AUTH environment variable:
+
+           HTTP_PROXY=http://proxy.example.com:8080
+           HTTP_PROXY_AUTH=basic:*:<user>:<pwd>
+
+     To disable the use of a proxy for an HTTP server running on the local
+     host, define NO_PROXY as follows:
+
+           NO_PROXY=localhost,127.0.0.1
+
+SSEEEE AALLSSOO
+     ftp(1), ip(4)
+
+     J. Postel and J. K. Reynolds, _F_i_l_e _T_r_a_n_s_f_e_r _P_r_o_t_o_c_o_l, October 1985, RFC
+     959.
+
+     P. Deutsch, A. Emtage, and A. Marine, _H_o_w _t_o _U_s_e _A_n_o_n_y_m_o_u_s _F_T_P, May 1994,
+     RFC 1635.
+
+     T. Berners-Lee, L. Masinter, and M. McCahill, _U_n_i_f_o_r_m _R_e_s_o_u_r_c_e _L_o_c_a_t_o_r_s
+     _(_U_R_L_), December 1994, RFC 1738.
+
+     R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, and
+     T. Berners-Lee, _H_y_p_e_r_t_e_x_t _T_r_a_n_s_f_e_r _P_r_o_t_o_c_o_l _-_- _H_T_T_P_/_1_._1, January 1999,
+     RFC 2616.
+
+     J. Franks, P. Hallam-Baker, J. Hostetler, S. Lawrence, P. Leach, A.
+     Luotonen, and L. Stewart, _H_T_T_P _A_u_t_h_e_n_t_i_c_a_t_i_o_n_: _B_a_s_i_c _a_n_d _D_i_g_e_s_t _A_c_c_e_s_s
+     _A_u_t_h_e_n_t_i_c_a_t_i_o_n, June 1999, RFC 2617.
+
+HHIISSTTOORRYY
+     The ffeettcchh library first appeared in FreeBSD 3.0.
+
+AAUUTTHHOORRSS
+     The ffeettcchh library was mostly written by Dag-Erling Smørgrav
+     <des@FreeBSD.org> with numerous suggestions from Jordan K. Hubbard
+     <jkh@FreeBSD.org>, Eugene Skepner <eu@qub.com> and other FreeBSD develop-
+     ers.  It replaces the older ffttppiioo library written by Poul-Henning Kamp
+     <phk@FreeBSD.org> and Jordan K. Hubbard <jkh@FreeBSD.org>.
+
+     This manual page was written by Dag-Erling Smørgrav <des@FreeBSD.org>.
+
+BBUUGGSS
+     Some parts of the library are not yet implemented.  The most notable
+     examples of this are ffeettcchhPPuuttHHTTTTPP() and FTP proxy support.
+
+     There is no way to select a proxy at run-time other than setting the
+     HTTP_PROXY or FTP_PROXY environment variables as appropriate.
+
+     lliibbffeettcchh does not understand or obey 305 (Use Proxy) replies.
+
+     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.
+
+     ffeettcchhSSttaattFFTTPP() does not check that the result of an MDTM command is a
+     valid date.
+
+     The man page is incomplete, poorly written and produces badly formatted
+     text.
+
+     The error reporting mechanism is unsatisfactory.
+
+     Some parts of the code are not fully reentrant.
+
+NetBSD 5.0                     February 4, 2009                     NetBSD 5.0