| 1.\" Copyright (c) 1998 Dag-Erling Co�dan Sm�rgrav 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. --- 8 unchanged lines hidden (view full) --- 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" |
| 25.\" $FreeBSD: head/lib/libfetch/fetch.3 57686 2000-03-02 09:14:21Z sheldonh $ |
| 26.\" 27.Dd July 1, 1998 28.Dt FETCH 3 29.Os 30.Sh NAME 31.Nm fetchGetURL , 32.Nm fetchPutURL , 33.Nm fetchStatURL , --- 67 unchanged lines hidden (view full) --- 101These functions implement a high-level library for retrieving and 102uploading files using Uniform Resource Locators (URLs). 103.Pp 104.Fn fetchGetURL 105and 106.Fn fetchPutURL 107constitute the recommended interface to the 108.Nm fetch |
| 109library. 110They examine the URL passed to them to determine the transfer |
| 111method, and call the appropriate lower-level functions to perform the |
| 112actual transfer. 113The |
| 114.Fa flags |
| 115argument is a string of characters which specify transfer options. 116The |
| 117meaning of the individual flags is scheme-dependent, and is detailed 118in the appropriate section below. 119.Pp 120.Fn fetchStatURL 121attempts to obtain the requested document's metadata and fill in the |
| 122structure pointed to by it's second argument. 123The |
| 124.Fa url_stat 125structure is defined as follows in 126.Aq Pa fetch.h : 127.Bd -literal 128struct url_stat { 129 off_t size; 130 time_t atime; 131 time_t mtime; 132}; 133.Ed 134.Pp 135.Fn fetchListURL 136attempts to list the contents of the directory pointed to by the URL |
| 137provided. 138If successful, it returns a malloced array of |
| 139.Fa url_ent |
| 140structures. 141The |
| 142.Fa url_ent 143structure is defined as follows in 144.Aq Pa fetch.h : 145.Bd -literal 146struct url_ent { 147 char name[MAXPATHLEN]; 148 struct url_stat stat; 149}; --- 11 unchanged lines hidden (view full) --- 161its components function according to the Common Internet Scheme Syntax 162detailed in RFC1738. A regular expression which produces this syntax 163is: 164.Bd -literal 165 <scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)? 166.Ed 167.Pp 168Note that some components of the URL are not necessarily relevant to |
| 169all URL schemes. 170For instance, the file scheme only needs the <scheme> |
| 171and <document> components. 172.Pp 173The pointer returned by 174.Fn fetchParseURL 175should be freed using 176.Fn free . 177.Pp 178.Fn fetchGet , --- 10 unchanged lines hidden (view full) --- 189.Fa struct url 190rather than a string. 191.Pp 192All of the 193.Fn fetchGetXXX 194and 195.Fn fetchPutXXX 196functions return a pointer to a stream which can be used to read or |
| 197write data from or to the requested document, respectively. 198Note that |
| 199although the implementation details of the individual access methods 200vary, it can generally be assumed that a stream returned by one of the 201.Fn fetchGetXXX 202functions is read-only, and that a stream returned by one of the 203.Fn fetchPutXXX 204functions is write-only. 205.Sh FILE SCHEME 206.Fn fetchGetFile 207and 208.Fn fetchPutFile 209provide access to documents which are files in a locally mounted file |
| 210system. 211Only the <document> component of the URL is used. |
| 212.Pp 213.Fn fetchGetFile 214does not accept any flags. 215.Pp 216.Fn fetchPutFile 217accepts the 218.Fa a |
| 219(append to file) flag. 220If that flag is specified, the data written to |
| 221the stream returned by 222.Fn fetchPutFile 223will be appended to the previous contents of the file, instead of 224replacing them. 225.Sh FTP SCHEME 226.Fn fetchGetFTP 227and 228.Fn fetchPutFTP --- 22 unchanged lines hidden (view full) --- 251.Nm fetch 252library will attempt an anonymous login, with user name "ftp" and 253password "ftp". 254.Sh HTTP SCHEME 255The 256.Fn fetchGetHTTP 257and 258.Fn fetchPutHTTP |
| 259functions implement the HTTP/1.1 protocol. 260With a little luck, there's |
| 261even a chance that they comply with RFC2068. 262.Pp 263If the 264.Fa d 265(direct) flag is specified, 266.Fn fetchGetHTTP 267and 268.Fn fetchPutHTTP --- 4 unchanged lines hidden (view full) --- 273.Nm fetch 274library, 275.Fn fetchPutHTTP 276is currently unimplemented. 277.Sh RETURN VALUES 278.Fn fetchParseURL 279returns a pointer to a 280.Fa struct url |
| 281containing the individual components of the URL. 282If it is |
| 283unable to allocate memory, or the URL is syntactically incorrect, 284.Fn fetchParseURL 285returns a NULL pointer. 286.Pp 287The 288.Fn fetchStat 289functions return 0 on success and -1 on failure. 290.Pp 291All other functions return a stream pointer which may be used to 292access the requested document, or NULL if an error occurred. 293.Pp 294.Nm Libfetch 295uses the Common Error Library 296.Nm ( libcom_err ) |
| 297to report errors. 298The error code passed to |
| 299.Fn com_err 300is one of: 301.Bl -tag -width Er 302.It Bq Er FETCH_ABORT 303Operation aborted 304.It Bq Er FETCH_AUTH 305Authentication failed 306.It Bq Er FETCH_DOWN --- 89 unchanged lines hidden (view full) --- 396library written by 397.An Poul-Henning Kamp Aq pkh@FreeBSD.org 398and 399.An Jordan K. Hubbard Aq jkh@FreeBSD.org . 400.Pp 401This manual page was written by 402.An Dag-Erling Co�dan Sm�rgrav Aq des@FreeBSD.org 403.Sh BUGS |
| 404Some parts of the library are not yet implemented. 405The most notable |
| 406examples of this are 407.Fn fetchPutHTTP , 408.Fn fetchStatHTTP , 409.Fn fetchListHTTP , 410.Fn fetchListFTP , 411and FTP proxy support. 412.Pp 413There's no way to select a proxy at run-time other than setting the 414.Ev HTTP_PROXY 415or 416.Ev FTP_PROXY |
| 417environment variables as appropriate. 418There is also no way to stop the |
| 419FTP and HTTP functions from trying to use a proxy if these variables 420are set. 421.Pp |
| 422HTTP authentication doesn't work. 423I'm not sure that's a bug in my |
| 424code; as far as I can determine, 425.Nm libfetch 426handles HTTP/1.1 basic authentication correctly as outlined in 427RFC2068, but I haven't been able to find an HTTP server that honors |
| 428the Authentication: header field. 429Also, |
| 430.Nm libfetch 431does not attempt to interpret and respond to authentication requests 432from the HTTP server. 433.Pp |
| 434No attempt is made to encode spaces etc. within URLs. 435Spaces in the |
| 436document part of an URLshould be replaced with "%20" in HTTP URLs and 437"\\ " in FTP URLs. 438.Pp 439Error numbers are unique only within a certain context; the error 440codes used for FTP and HTTP overlap, as do those used for resolver and |
| 441system errors. 442For instance, error code 202 means "Command not |
| 443implemented, superfluous at this site" in an FTP context and 444"Accepted" in an HTTP context. 445.Pp 446.Fn fetchStatFTP 447does not check that the result of an MDTM command is a valid date. 448.Pp 449The HTTP code needs a complete rewrite, or at least a serious cleanup. 450.Pp 451The man page is poorly written and produces badly formatted text. 452.Pp 453Tons of other stuff. |