Regen cat page. Helps Solaris.

1 files changed, 176 insertions, 484 deletions

diff --git a/net/libfetch/files/fetch.cat3 b/net/libfetch/files/fetch.cat3
index 8057a34e717..90556f69839 100644
--- a/net/libfetch/files/fetch.cat3
+++ b/net/libfetch/files/fetch.cat3
@@ -1,506 +1,198 @@
-FETCH(3)                NetBSD Library Functions Manual               FETCH(3)
+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.
 
-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
-     library ``libfetch''
 
-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/orgrav
-     <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/orgrav <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