| fetch.3 (55544) | fetch.3 (57686) |
|---|---|
| 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.\" | 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 55544 2000-01-07 10:59:12Z des $ | 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 | 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. They examine the URL passed to them to determine the transfer | 109library. 110They examine the URL passed to them to determine the transfer |
| 110method, and call the appropriate lower-level functions to perform the | 111method, and call the appropriate lower-level functions to perform the |
| 111actual transfer. The | 112actual transfer. 113The |
| 112.Fa flags | 114.Fa flags |
| 113argument is a string of characters which specify transfer options. The | 115argument is a string of characters which specify transfer options. 116The |
| 114meaning of the individual flags is scheme-dependent, and is detailed 115in the appropriate section below. 116.Pp 117.Fn fetchStatURL 118attempts to obtain the requested document's metadata and fill in the | 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 |
| 119structure pointed to by it's second argument. The | 122structure pointed to by it's second argument. 123The |
| 120.Fa url_stat 121structure is defined as follows in 122.Aq Pa fetch.h : 123.Bd -literal 124struct url_stat { 125 off_t size; 126 time_t atime; 127 time_t mtime; 128}; 129.Ed 130.Pp 131.Fn fetchListURL 132attempts to list the contents of the directory pointed to by the URL | 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 |
| 133provided. If successful, it returns a malloced array of | 137provided. 138If successful, it returns a malloced array of |
| 134.Fa url_ent | 139.Fa url_ent |
| 135structures. The | 140structures. 141The |
| 136.Fa url_ent 137structure is defined as follows in 138.Aq Pa fetch.h : 139.Bd -literal 140struct url_ent { 141 char name[MAXPATHLEN]; 142 struct url_stat stat; 143}; --- 11 unchanged lines hidden (view full) --- 155its components function according to the Common Internet Scheme Syntax 156detailed in RFC1738. A regular expression which produces this syntax 157is: 158.Bd -literal 159 <scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)? 160.Ed 161.Pp 162Note that some components of the URL are not necessarily relevant to | 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 |
| 163all URL schemes. For instance, the file scheme only needs the <scheme> | 169all URL schemes. 170For instance, the file scheme only needs the <scheme> |
| 164and <document> components. 165.Pp 166The pointer returned by 167.Fn fetchParseURL 168should be freed using 169.Fn free . 170.Pp 171.Fn fetchGet , --- 10 unchanged lines hidden (view full) --- 182.Fa struct url 183rather than a string. 184.Pp 185All of the 186.Fn fetchGetXXX 187and 188.Fn fetchPutXXX 189functions return a pointer to a stream which can be used to read or | 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 |
| 190write data from or to the requested document, respectively. Note that | 197write data from or to the requested document, respectively. 198Note that |
| 191although the implementation details of the individual access methods 192vary, it can generally be assumed that a stream returned by one of the 193.Fn fetchGetXXX 194functions is read-only, and that a stream returned by one of the 195.Fn fetchPutXXX 196functions is write-only. 197.Sh FILE SCHEME 198.Fn fetchGetFile 199and 200.Fn fetchPutFile 201provide access to documents which are files in a locally mounted file | 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 |
| 202system. Only the <document> component of the URL is used. | 210system. 211Only the <document> component of the URL is used. |
| 203.Pp 204.Fn fetchGetFile 205does not accept any flags. 206.Pp 207.Fn fetchPutFile 208accepts the 209.Fa a | 212.Pp 213.Fn fetchGetFile 214does not accept any flags. 215.Pp 216.Fn fetchPutFile 217accepts the 218.Fa a |
| 210(append to file) flag. If that flag is specified, the data written to | 219(append to file) flag. 220If that flag is specified, the data written to |
| 211the stream returned by 212.Fn fetchPutFile 213will be appended to the previous contents of the file, instead of 214replacing them. 215.Sh FTP SCHEME 216.Fn fetchGetFTP 217and 218.Fn fetchPutFTP --- 22 unchanged lines hidden (view full) --- 241.Nm fetch 242library will attempt an anonymous login, with user name "ftp" and 243password "ftp". 244.Sh HTTP SCHEME 245The 246.Fn fetchGetHTTP 247and 248.Fn fetchPutHTTP | 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 |
| 249functions implement the HTTP/1.1 protocol. With a little luck, there's | 259functions implement the HTTP/1.1 protocol. 260With a little luck, there's |
| 250even a chance that they comply with RFC2068. 251.Pp 252If the 253.Fa d 254(direct) flag is specified, 255.Fn fetchGetHTTP 256and 257.Fn fetchPutHTTP --- 4 unchanged lines hidden (view full) --- 262.Nm fetch 263library, 264.Fn fetchPutHTTP 265is currently unimplemented. 266.Sh RETURN VALUES 267.Fn fetchParseURL 268returns a pointer to a 269.Fa struct url | 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 |
| 270containing the individual components of the URL. If it is | 281containing the individual components of the URL. 282If it is |
| 271unable to allocate memory, or the URL is syntactically incorrect, 272.Fn fetchParseURL 273returns a NULL pointer. 274.Pp 275The 276.Fn fetchStat 277functions return 0 on success and -1 on failure. 278.Pp 279All other functions return a stream pointer which may be used to 280access the requested document, or NULL if an error occurred. 281.Pp 282.Nm Libfetch 283uses the Common Error Library 284.Nm ( libcom_err ) | 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 ) |
| 285to report errors. The error code passed to | 297to report errors. 298The error code passed to |
| 286.Fn com_err 287is one of: 288.Bl -tag -width Er 289.It Bq Er FETCH_ABORT 290Operation aborted 291.It Bq Er FETCH_AUTH 292Authentication failed 293.It Bq Er FETCH_DOWN --- 89 unchanged lines hidden (view full) --- 383library written by 384.An Poul-Henning Kamp Aq pkh@FreeBSD.org 385and 386.An Jordan K. Hubbard Aq jkh@FreeBSD.org . 387.Pp 388This manual page was written by 389.An Dag-Erling Co�dan Sm�rgrav Aq des@FreeBSD.org 390.Sh BUGS | 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 |
| 391Some parts of the library are not yet implemented. The most notable | 404Some parts of the library are not yet implemented. 405The most notable |
| 392examples of this are 393.Fn fetchPutHTTP , 394.Fn fetchStatHTTP , 395.Fn fetchListHTTP , 396.Fn fetchListFTP , 397and FTP proxy support. 398.Pp 399There's no way to select a proxy at run-time other than setting the 400.Ev HTTP_PROXY 401or 402.Ev FTP_PROXY | 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 |
| 403environment variables as appropriate. There is also no way to stop the | 417environment variables as appropriate. 418There is also no way to stop the |
| 404FTP and HTTP functions from trying to use a proxy if these variables 405are set. 406.Pp | 419FTP and HTTP functions from trying to use a proxy if these variables 420are set. 421.Pp |
| 407HTTP authentication doesn't work. I'm not sure that's a bug in my | 422HTTP authentication doesn't work. 423I'm not sure that's a bug in my |
| 408code; as far as I can determine, 409.Nm libfetch 410handles HTTP/1.1 basic authentication correctly as outlined in 411RFC2068, but I haven't been able to find an HTTP server that honors | 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 |
| 412the Authentication: header field. Also, | 428the Authentication: header field. 429Also, |
| 413.Nm libfetch 414does not attempt to interpret and respond to authentication requests 415from the HTTP server. 416.Pp | 430.Nm libfetch 431does not attempt to interpret and respond to authentication requests 432from the HTTP server. 433.Pp |
| 417No attempt is made to encode spaces etc. within URLs. Spaces in the | 434No attempt is made to encode spaces etc. within URLs. 435Spaces in the |
| 418document part of an URLshould be replaced with "%20" in HTTP URLs and 419"\\ " in FTP URLs. 420.Pp 421Error numbers are unique only within a certain context; the error 422codes used for FTP and HTTP overlap, as do those used for resolver and | 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 |
| 423system errors. For instance, error code 202 means "Command not | 441system errors. 442For instance, error code 202 means "Command not |
| 424implemented, superfluous at this site" in an FTP context and 425"Accepted" in an HTTP context. 426.Pp 427.Fn fetchStatFTP 428does not check that the result of an MDTM command is a valid date. 429.Pp 430The HTTP code needs a complete rewrite, or at least a serious cleanup. 431.Pp 432The man page is poorly written and produces badly formatted text. 433.Pp 434Tons of other stuff. | 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. |