Deleted Added
sdiff udiff text old ( 55544 ) new ( 57686 )
full compact
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 $
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
110method, and call the appropriate lower-level functions to perform the
111actual transfer. The
112.Fa flags
113argument is a string of characters which specify transfer options. The
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
119structure pointed to by it's second argument. The
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
133provided. If successful, it returns a malloced array of
134.Fa url_ent
135structures. The
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
163all URL schemes. For 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
190write data from or to the requested document, respectively. Note 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
202system. Only 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
210(append to file) flag. If 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
249functions implement the HTTP/1.1 protocol. With 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
270containing the individual components of the URL. If 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 )
285to report errors. The 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
391Some parts of the library are not yet implemented. The 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
403environment variables as appropriate. There is also no way to stop the
404FTP and HTTP functions from trying to use a proxy if these variables
405are set.
406.Pp
407HTTP authentication doesn't work. I'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
412the Authentication: header field. Also,
413.Nm libfetch
414does not attempt to interpret and respond to authentication requests
415from the HTTP server.
416.Pp
417No attempt is made to encode spaces etc. within URLs. Spaces 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
423system errors. For 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.