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: fetch.3,v 1.1.1.1 1998/07/09 16:52:43 des Exp $ 26.\" 27.Dd July 1, 1998 28.Dt FETCH 3 29.Os 30.Sh NAME 31.Nm fetchGetURL , 32.Nm fetchPutURL , 33.Nm fetchParseURL , 34.Nm fetchFreeURL , 35.Nm fetchGet , 36.Nm fetchPut , 37.Nm fetchGetFile , 38.Nm fetchPutFile , 39.Nm fetchGetHTTP , 40.Nm fetchPutHTTP , 41.Nm fetchGetFTP , 42.Nm fetchPutFTP 43.Nd file transfer library 44.Sh SYNOPSIS 45.Fd #include <fetch.h> 46.Ft FILE * 47.Fn fetchGetURL "char *URL" "char *flags" 48.Ft FILE * 49.Fn fetchPutURL "char *URL" "char *flags" 50.Ft url_t * 51.Fn fetchParseURL "char *URL" "char *flags" 52.Ft void 53.Fn fetchFreeURL "url_t *u" 54.Ft FILE * 55.Fn fetchGet "url_t *URL" "char *flags" 56.Ft FILE * 57.Fn fetchPut "url_t *URL" "char *flags" 58.Ft FILE * 59.Fn fetchGetFile "url_t *u" "char *flags" 60.Ft FILE * 61.Fn fetchPutFile "url_t *u" "char *flags" 62.Ft FILE * 63.Fn fetchGetHTTP "url_t *u" "char *flags" 64.Ft FILE * 65.Fn fetchPutHTTP "url_t *u" "char *flags" 66.Ft FILE * 67.Fn fetchGetFTP "url_t *u" "char *flags" 68.Ft FILE * 69.Fn fetchPutFTP "url_t *u" "char *flags" 70.Sh DESCRIPTION 71These functions implement a high-level library for retrieving and 72uploading files using Uniform Resource Locators (URLs). 73.Pp 74.Fn fetchGetURL 75and 76.Fn fetchPutURL 77constitute the recommended interface to the 78.Nm fetch 79library. They examine the URL passed to them to determine the transfer 80method, and call the appropriate lower-level functions to perform the 81actual transfer. The 82.Fa flags 83argument is a string of characters which specify transfer options. The 84meaning of the individual flags is scheme-dependent, and is detailed 85in the appropriate section below. 86.Pp 87.Fn fetchParseURL 88takes a URL in the form of a null-terminated string and splits it into 89its components function according to the Common Internet Scheme Syntax 90detailed in RFC1738. A regular expression which produces this syntax 91is: 92.Bd -literal 93 <scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)? 94.Ed 95.Pp 96Note that some components of the URL are not necessarily relevant to 97all URL schemes. For instance, the file scheme only needs the <scheme> 98and <document> components. 99.Pp 100The pointer returned by 101.Fn fetchParseURL 102should be freed using 103.Fn fetchFreeURL . 104.Pp 105.Fn fetchGet 106and 107.Fn fetchPut 108are similar to 109.Fn fetchGetURL 110and 111.Fn fetchPutURL , 112except that they expect a pre-parsed URL in the form of a pointer to 113an 114.Fa url_t 115structure rather than a string. 116.Pp 117All of the 118.Fn fetchGetXXX 119and 120.Fn fetchPutXXX 121functions return a pointer to a stream which can be used to read or 122write data from or to the requested document, respectively. Note that 123although the implementation details of the individual access methods 124vary, it can generally be assumed that a stream returned by one of the 125.Fn fetchGetXXX 126functions is read-only, and that a stream returned by one of the 127.Fn fetchPutXXX 128functions is write-only. 129.Sh FILE SCHEME 130.Fn fetchGetFile 131and 132.Fn fetchPutFile 133provide access to documents which are files in a locally mounted file 134system. Only the <document> component of the URL is used. 135.Pp 136.Fn fetchGetFile 137does not accept any flags. 138.Pp 139.Fn fetchPutFile 140accepts the 141.Fa a 142(append to file) flag. If that flag is specified, the data written to 143the stream returned by 144.Fn fetchPutFile 145will be appended to the previous contents of the file, instead of 146replacing them. 147.Sh FTP SCHEME 148.Fn fetchGetFTP 149and 150.Fn fetchPutFTP 151implement the FTP protocol as described in RFC959. 152.Pp 153If the 154.Fa p 155(passive) flag is specified, a passive (rather than active) connection 156will be attempted. 157.Pp 158If no user name or password is given, the 159.Nm fetch 160library will attempt an anonymous login, with user name "ftp" and 161password "ftp". 162.Sh HTTP SCHEME 163The 164.Fn fetchGetHTTP 165and 166.Fn fetchPutHTTP 167functions implement the HTTP/1.1 protocol. With a little luck, there's 168even a chance that they comply with RFC2068. 169.Pp 170Since there seems to be no good way of implementing the HTTP PUT 171method in a manner consistent with the rest of the 172.Nm fetch 173library, 174.Fn fetchPutHTTP 175is currently unimplemented. 176.Sh RETURN VALUES 177.Fn fetchParseURL 178returns a pointer to a 179.Fa url_t 180structure containing the individual components of the URL. If it is 181unable to allocate memory, or the URL is syntactically incorrect, 182.Fn fetchParseURL 183returns a NULL pointer. 184.Pp 185.Fn fetchFreeURL 186does not return any value. 187.Pp 188All other functions return a stream pointer which may be used to 189access the requested document. Upon failure of any kind, they return a 190NULL pointer. 191.Sh ENVIRONMENT 192The FTP and HTTP related functions use the 193.Ev HTTP_PROXY 194and 195.Ev FTP_PROXY 196environment variables, respectively, as the address of a proxy server 197to use for transferring files. 198.Sh SEE ALSO 199.Xr fetch 1 , 200.Xr ftpio 3 201.Rs 202.%A T. Berners-Lee, L. Masinter & M. McCahill 203.%D December 1994 204.%T Uniform Resource Locators (URL) 205.%O RFC1738 206.Re 207.Rs 208.%A R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners-Lee 209.%D Januray 1997 210.%B Hypertext Transfer Protocol -- HTTP/1.1 211.%O RFC2068 212.Re 213.Rs 214.%A J. Postel, J. K. Reynolds 215.%D October 1985 216.%B File Transfer Protocol 217.%O RFC959 218.Re 219.Sh DIAGNOSTICS 220Add later. 221.Sh NOTES 222Some parts of the library are not yet implemented. The most notable 223examples of this are 224.Fn fetchPutHTTP 225and proxy support for the FTP access method. 226.Sh HISTORY 227The 228.Nm fetch 229library first appeared in 230.Fx 3.0 . 231.Sh AUTHORS 232The 233.Nm fetch 234library was mostly written by 235.An Dag-Erling Co�dan Sm�rgrav Aq des@FreeBSD.org 236with numerous suggestions from 237.An Jordan K. Hubbard Aq jkh@FreeBSD.org 238and other FreeBSD developers. 239It incorporates the older 240.Nm ftpio 241library, which was originally written by 242.Nm Poul-Henning Kamp Aq pkh@FreeBSD.org 243and later turned inside out by 244.An Jordan K. Hubbard Aq jkh@FreeBSD.org . 245.Pp 246This manual page was written by 247.An Dag-Erling Co�dan Sm�rgrav Aq des@FreeBSD.org 248.Sh BUGS 249There's no way to select a proxy at run-time other than setting the 250.Ev HTTP_PROXY 251or 252.Ev FTP_PROXY 253environment variables as appropriate. There is also no way to stop the 254FTP and HTTP functions from trying to use a proxy if these variables 255are set. 256.Pp 257HTTP authentication doesn't work. I'm not sure that's a bug in my 258code; as far as I can determine, 259.Nm libfetch 260handles HTTP/1.1 basic authentication correctly as outlined in 261RFC2068, but I haven't been able to find an HTTP server that honors 262the Authentication: header field. 263.Pp 264Tons of other stuff. 265