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. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 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.\" $Id$ 26.\" 27.Dd July 1, 1998 28.Dt FETCH 3 29.Os 30.Sh NAME 31.Nm fetchParseURL , 32.Nm fetchFreeURL , 33.Nm fetchGetURL , 34.Nm fetchPutURL , 35.Nm fetchGetFile , 36.Nm fetchPutFile , 37.Nm fetchGetHTTP , 38.Nm fetchPutHTTP , 39.Nm fetchGetFTP , 40.Nm fetchPutFTP 41.Nd file transfer library 42.Sh SYNOPSIS 43.Fd #include <fetch.h> 44.Ft url_t * 45.Fn fetchParseURL "char *URL" "char *flags" 46.Ft void 47.Fn fetchFreeURL "url_t *u" 48.Ft FILE * 49.Fn fetchGetFile "url_t *u" "char *flags" 50.Ft FILE * 51.Fn fetchPutFile "url_t *u" "char *flags" 52.Ft FILE * 53.Fn fetchGetHTTP "url_t *u" "char *flags" 54.Ft FILE * 55.Fn fetchPutHTTP "url_t *u" "char *flags" 56.Ft FILE * 57.Fn fetchGetFTP "url_t *u" "char *flags" 58.Ft FILE * 59.Fn fetchPutFTP "url_t *u" "char *flags" 60.Sh DESCRIPTION 61These functions implement a high-level library for retrieving and 62uploading files using Uniform Resource Locators (URLs). 63.Pp 64.Fn fetchParseURL 65takes a URL in the form of a null-terminated string and splits it into 66its components function according to the Common Internet Scheme Syntax 67detailed in RFC1738. A regular expression which produces this syntax 68is: 69.Bd -literal 70 <scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)? 71.Ed 72.Pp 73Note that some components of the URL are not necessarily relevant to 74all URL schemes. For instance, the file scheme only needs the <scheme> 75and <document> components. 76.Pp 77The pointer returned by 78.Fn fetchParseURL 79should be freed using 80.Fn fetchFreeURL . 81.Pp 82.Fn fetchGetURL 83and 84.Fn fetchPutURL 85constitute the recommended interface to the 86.Nm fetch 87library. They examine the URL passed to them to determine the transfer 88method, and call the appropriate lower-level functions to perform the 89actual transfer. The 90.Fa flags 91argument is a string of characters which specify transfer options. The 92meaning of the individual flags is scheme-dependent, and is detailed 93in the appropriate section below. 94.Pp 95All of the 96.Fn fetchGetXXX 97and 98.Fn fetchPutXXX 99functions return a pointer to a stream which can be used to read or 100write data from or to the requested document, respectively. Not that 101although the implementation details of the individual access methods 102vary, it can generally be assumed that a stream returned by one of the 103.Fn fetchGetXXX 104functions is read-only, and that a stream returned by one of the 105.Fn fetchPutXXX 106functions is write-only. 107.Sh FILE SCHEME 108.Fn fetchGetFile 109and 110.Fn fetchPutFile 111provide access to documents which are files in a locally mounted file 112system. Only the <document> component of the URL is used. 113.Pp 114.Fn fetchGetFile 115does not accept any flags. 116.Pp 117.Fn fetchPutFile 118accepts the 119.Fa a 120(append to file) flag. If that flag is specified, the data written to 121the stream returned by 122.Fn fetchPutFile 123will be appended to the previous contents of the file, instead of 124replacing them. 125.Sh FTP SCHEME 126.Fn fetchGetFTP 127and 128.Fn fetchPutFTP 129implement the FTP protocol as described in RFC959. 130.Pp 131If the 132.Fa p 133(passive) flag is specified, a passive (rather than active) connection 134will be attempted. 135.Pp 136If no user name or password is given, the 137.Nm fetch 138library will attempt an anonymous login, with user name "ftp" and 139password "ftp". 140.Sh HTTP SCHEME 141The 142.Fn fetchGetHTTP 143and 144.Fn fetchPutHTTP 145functions implement the HTTP/1.1 protocol. With a little luck, there's 146even a chance that they comply with RFC2068. 147.Pp 148Since there seems to be no good way of implementing the HTTP PUT 149method in a manner consistent with the rest of the 150.Nm fetch 151library, 152.Fn fetchPutHTTP 153is currently unimplemented. 154.Sh RETURN VALUES 155.Fn fetchParseURL 156returns a pointer to a 157.Fa url_t 158structure containing the individual components of the URL. If it is 159unable to allocate memory, or the URL is syntactically incorrect, 160.Fn fetchParseURL 161returns a NULL pointer. 162.Pp 163.Fn fetchFreeURL 164does not return any value. 165.Pp 166All other functions return a stream pointer which may be used to 167access the requested document. Upon failure of any kind, they return a 168NULL pointer. 169.Sh ENVIRONMENT 170The FTP and HTTP functions use the 171.Ev HTTP_PROXY 172and 173.Ev FTP_PROXY 174environment variables, respectively, as the address of a proxy server 175to use for transferring files. 176.Sh SEE ALSO 177.Xr fetch 1 , 178.Xr ftpio 3 , 179.Xr lots_of_other_stuff 180.Rs 181.%A T. Berners-Lee, L. Masinter & M. McCahill 182.%D December 1994 183.%T Uniform Resource Locators (URL) 184.%O RFC1738 185.Re 186.Rs 187.%A R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners-Lee 188.%D Januray 1997 189.%B Hypertext Transfer Protocol -- HTTP/1.1 190.%O RFC2068 191.Re 192.Rs 193.%A J. Postel, J. K. Reynolds 194.%D October 1985 195.%B File Transfer Protocol 196.%O RFC959 197.Re 198.Sh DIAGNOSTICS 199Add later. 200.Sh NOTES 201Some parts of the library are not yet implemented. The most notable 202examples of this are 203.Fn fetchPutHTTP 204and proxy support for the FTP access method. 205.Pp 206I hate HTTP. 207.Pp 208Why does the \.Pp macro sometimes insert two blank lines instead of 209one? 210.Sh HISTORY 211The 212.Nm fetch 213library first appeared in 214.Fx 3.0 . 215.Sh AUTHORS 216The 217.Nm fetch 218library was mostly written by 219.An Dag-Erling Co�dan Sm�rgrav Aq des@FreeBSD.org 220with numerous suggestions from 221.An Jordan K. Hubbard Aq jkh@FreeBSD.org 222and other FreeBSD developers. 223It incorporates the older 224.Nm ftpio 225library, which was originally written by 226.Nm Poul-Henning Kamp Aq pkh@FreeBSD.org 227and later turned inside out by 228.An Jordan K. Hubbard Aq jkh@FreeBSD.org . 229.Pp 230This manual page was written by 231.An Dag-Erling Co�dan Sm�rgrav Aq des@FreeBSD.org 232.Sh BUGS 233If I knew, I'd have fixed them. 234