| blob | 35813d7413fe2730de7059c1148aadaecb4e7c1b |
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 .\" $FreeBSD: src/lib/libfetch/fetch.3,v 1.63 2007/05/24 20:28:14 des Exp $
26 .\" $DragonFly: src/lib/libfetch/fetch.3,v 1.5 2007/11/23 23:16:36 swildner Exp $
27 .\"
28 .Dd July 1, 1998
29 .Dt FETCH 3
30 .Os
31 .Sh NAME
32 .Nm fetchMakeURL ,
33 .Nm fetchParseURL ,
34 .Nm fetchFreeURL ,
35 .Nm fetchXGetURL ,
36 .Nm fetchGetURL ,
37 .Nm fetchPutURL ,
38 .Nm fetchStatURL ,
39 .Nm fetchListURL ,
40 .Nm fetchXGet ,
41 .Nm fetchGet ,
42 .Nm fetchPut ,
43 .Nm fetchStat ,
44 .Nm fetchList ,
45 .Nm fetchXGetFile ,
46 .Nm fetchGetFile ,
47 .Nm fetchPutFile ,
48 .Nm fetchStatFile ,
49 .Nm fetchListFile ,
50 .Nm fetchXGetHTTP ,
51 .Nm fetchGetHTTP ,
52 .Nm fetchPutHTTP ,
53 .Nm fetchStatHTTP ,
54 .Nm fetchListHTTP ,
55 .Nm fetchXGetFTP ,
56 .Nm fetchGetFTP ,
57 .Nm fetchPutFTP ,
58 .Nm fetchStatFTP ,
59 .Nm fetchListFTP
60 .Nd file transfer functions
61 .Sh LIBRARY
62 .Lb libfetch
63 .Sh SYNOPSIS
64 .In sys/param.h
65 .In stdio.h
66 .In fetch.h
67 .Ft struct url *
68 .Fn fetchMakeURL "const char *scheme" "const char *host" "int port" "const char *doc" "const char *user" "const char *pwd"
69 .Ft struct url *
70 .Fn fetchParseURL "const char *URL"
71 .Ft void
72 .Fn fetchFreeURL "struct url *u"
73 .Ft FILE *
74 .Fn fetchXGetURL "const char *URL" "struct url_stat *us" "const char *flags"
75 .Ft FILE *
76 .Fn fetchGetURL "const char *URL" "const char *flags"
77 .Ft FILE *
78 .Fn fetchPutURL "const char *URL" "const char *flags"
79 .Ft int
80 .Fn fetchStatURL "const char *URL" "struct url_stat *us" "const char *flags"
81 .Ft struct url_ent *
82 .Fn fetchListURL "const char *URL" "const char *flags"
83 .Ft FILE *
84 .Fn fetchXGet "struct url *u" "struct url_stat *us" "const char *flags"
85 .Ft FILE *
86 .Fn fetchGet "struct url *u" "const char *flags"
87 .Ft FILE *
88 .Fn fetchPut "struct url *u" "const char *flags"
89 .Ft int
90 .Fn fetchStat "struct url *u" "struct url_stat *us" "const char *flags"
91 .Ft struct url_ent *
92 .Fn fetchList "struct url *u" "const char *flags"
93 .Ft FILE *
94 .Fn fetchXGetFile "struct url *u" "struct url_stat *us" "const char *flags"
95 .Ft FILE *
96 .Fn fetchGetFile "struct url *u" "const char *flags"
97 .Ft FILE *
98 .Fn fetchPutFile "struct url *u" "const char *flags"
99 .Ft int
100 .Fn fetchStatFile "struct url *u" "struct url_stat *us" "const char *flags"
101 .Ft struct url_ent *
102 .Fn fetchListFile "struct url *u" "const char *flags"
103 .Ft FILE *
104 .Fn fetchXGetHTTP "struct url *u" "struct url_stat *us" "const char *flags"
105 .Ft FILE *
106 .Fn fetchGetHTTP "struct url *u" "const char *flags"
107 .Ft FILE *
108 .Fn fetchPutHTTP "struct url *u" "const char *flags"
109 .Ft int
110 .Fn fetchStatHTTP "struct url *u" "struct url_stat *us" "const char *flags"
111 .Ft struct url_ent *
112 .Fn fetchListHTTP "struct url *u" "const char *flags"
113 .Ft FILE *
114 .Fn fetchXGetFTP "struct url *u" "struct url_stat *us" "const char *flags"
115 .Ft FILE *
116 .Fn fetchGetFTP "struct url *u" "const char *flags"
117 .Ft FILE *
118 .Fn fetchPutFTP "struct url *u" "const char *flags"
119 .Ft int
120 .Fn fetchStatFTP "struct url *u" "struct url_stat *us" "const char *flags"
121 .Ft struct url_ent *
122 .Fn fetchListFTP "struct url *u" "const char *flags"
123 .Sh DESCRIPTION
124 These functions implement a high-level library for retrieving and
125 uploading files using Uniform Resource Locators (URLs).
126 .Pp
127 .Fn fetchParseURL
128 takes a URL in the form of a null-terminated string and splits it into
129 its components function according to the Common Internet Scheme Syntax
130 detailed in RFC 1738.
131 A regular expression which produces this syntax is:
132 .Bd -literal
133 <scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)?
134 .Ed
135 .Pp
136 If the URL does not seem to begin with a scheme name, the following
137 syntax is assumed:
138 .Bd -literal
139 ((<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)?
140 .Ed
141 .Pp
142 Note that some components of the URL are not necessarily relevant to
143 all URL schemes.
144 For instance, the file scheme only needs the <scheme> and <document>
145 components.
146 .Pp
147 .Fn fetchMakeURL
148 and
149 .Fn fetchParseURL
150 return a pointer to a
151 .Vt url
152 structure, which is defined as follows in
153 .In fetch.h :
154 .Bd -literal
155 #define URL_SCHEMELEN 16
156 #define URL_USERLEN 256
157 #define URL_PWDLEN 256
159 struct url {
160 char scheme[URL_SCHEMELEN+1];
161 char user[URL_USERLEN+1];
162 char pwd[URL_PWDLEN+1];
163 char host[MAXHOSTNAMELEN+1];
164 int port;
165 char *doc;
166 off_t offset;
167 size_t length;
168 };
169 .Ed
170 .Pp
171 The pointer returned by
172 .Fn fetchMakeURL
173 or
174 .Fn fetchParseURL
175 should be freed using
176 .Fn fetchFreeURL .
177 .Pp
178 .Fn fetchXGetURL ,
179 .Fn fetchGetURL ,
180 and
181 .Fn fetchPutURL
182 constitute the recommended interface to the
183 .Nm fetch
184 library.
185 They examine the URL passed to them to determine the transfer
186 method, and call the appropriate lower-level functions to perform the
187 actual transfer.
188 .Fn fetchXGetURL
189 also returns the remote document's metadata in the
190 .Vt url_stat
191 structure pointed to by the
192 .Fa us
193 argument.
194 .Pp
195 The
196 .Fa flags
197 argument is a string of characters which specify transfer options.
198 The
199 meaning of the individual flags is scheme-dependent, and is detailed
200 in the appropriate section below.
201 .Pp
202 .Fn fetchStatURL
203 attempts to obtain the requested document's metadata and fill in the
204 structure pointed to by its second argument.
205 The
206 .Vt url_stat
207 structure is defined as follows in
208 .In fetch.h :
209 .Bd -literal
210 struct url_stat {
211 off_t size;
212 time_t atime;
213 time_t mtime;
214 };
215 .Ed
216 .Pp
217 If the size could not be obtained from the server, the
218 .Fa size
219 field is set to -1.
220 If the modification time could not be obtained from the server, the
221 .Fa mtime
222 field is set to the epoch.
223 If the access time could not be obtained from the server, the
224 .Fa atime
225 field is set to the modification time.
226 .Pp
227 .Fn fetchListURL
228 attempts to list the contents of the directory pointed to by the URL
229 provided.
230 If successful, it returns a malloced array of
231 .Vt url_ent
232 structures.
233 The
234 .Vt url_ent
235 structure is defined as follows in
236 .In fetch.h :
237 .Bd -literal
238 struct url_ent {
239 char name[MAXPATHLEN];
240 struct url_stat stat;
241 };
242 .Ed
243 .Pp
244 The list is terminated by an entry with an empty name.
245 .Pp
246 The pointer returned by
247 .Fn fetchListURL
248 should be freed using
249 .Fn free .
250 .Pp
251 .Fn fetchXGet ,
252 .Fn fetchGet ,
253 .Fn fetchPut
254 and
255 .Fn fetchStat
256 are similar to
257 .Fn fetchXGetURL ,
258 .Fn fetchGetURL ,
259 .Fn fetchPutURL
260 and
261 .Fn fetchStatURL ,
262 except that they expect a pre-parsed URL in the form of a pointer to
263 a
264 .Vt struct url
265 rather than a string.
266 .Pp
267 All of the
268 .Fn fetchXGetXXX ,
269 .Fn fetchGetXXX
270 and
271 .Fn fetchPutXXX
272 functions return a pointer to a stream which can be used to read or
273 write data from or to the requested document, respectively.
274 Note that
275 although the implementation details of the individual access methods
276 vary, it can generally be assumed that a stream returned by one of the
277 .Fn fetchXGetXXX
278 or
279 .Fn fetchGetXXX
280 functions is read-only, and that a stream returned by one of the
281 .Fn fetchPutXXX
282 functions is write-only.
283 .Sh FILE SCHEME
284 .Fn fetchXGetFile ,
285 .Fn fetchGetFile
286 and
287 .Fn fetchPutFile
288 provide access to documents which are files in a locally mounted file
289 system.
290 Only the <document> component of the URL is used.
291 .Pp
292 .Fn fetchXGetFile
293 and
294 .Fn fetchGetFile
295 do not accept any flags.
296 .Pp
297 .Fn fetchPutFile
298 accepts the
299 .Ql a
300 (append to file) flag.
301 If that flag is specified, the data written to
302 the stream returned by
303 .Fn fetchPutFile
304 will be appended to the previous contents of the file, instead of
305 replacing them.
306 .Sh FTP SCHEME
307 .Fn fetchXGetFTP ,
308 .Fn fetchGetFTP
309 and
310 .Fn fetchPutFTP
311 implement the FTP protocol as described in RFC 959.
312 .Pp
313 If the
314 .Ql p
315 (passive) flag is specified, a passive (rather than active) connection
316 will be attempted.
317 .Pp
318 If the
319 .Ql l
320 (low) flag is specified, data sockets will be allocated in the low (or
321 default) port range instead of the high port range (see
322 .Xr ip 4 ) .
323 .Pp
324 If the
325 .Ql d
326 (direct) flag is specified,
327 .Fn fetchXGetFTP ,
328 .Fn fetchGetFTP
329 and
330 .Fn fetchPutFTP
331 will use a direct connection even if a proxy server is defined.
332 .Pp
333 If no user name or password is given, the
334 .Nm fetch
335 library will attempt an anonymous login, with user name "anonymous"
336 and password "anonymous@<hostname>".
337 .Sh HTTP SCHEME
338 The
339 .Fn fetchXGetHTTP ,
340 .Fn fetchGetHTTP
341 and
342 .Fn fetchPutHTTP
343 functions implement the HTTP/1.1 protocol.
344 With a little luck, there is
345 even a chance that they comply with RFC 2616 and RFC 2617.
346 .Pp
347 If the
348 .Ql d
349 (direct) flag is specified,
350 .Fn fetchXGetHTTP ,
351 .Fn fetchGetHTTP
352 and
353 .Fn fetchPutHTTP
354 will use a direct connection even if a proxy server is defined.
355 .Pp
356 Since there seems to be no good way of implementing the HTTP PUT
357 method in a manner consistent with the rest of the
358 .Nm fetch
359 library,
360 .Fn fetchPutHTTP
361 is currently unimplemented.
362 .Sh AUTHENTICATION
363 Apart from setting the appropriate environment variables and
364 specifying the user name and password in the URL or the
365 .Vt struct url ,
366 the calling program has the option of defining an authentication
367 function with the following prototype:
368 .Pp
369 .Ft int
370 .Fn myAuthMethod "struct url *u"
371 .Pp
372 The callback function should fill in the
373 .Fa user
374 and
375 .Fa pwd
376 fields in the provided
377 .Vt struct url
378 and return 0 on success, or any other value to indicate failure.
379 .Pp
380 To register the authentication callback, simply set
381 .Va fetchAuthMethod
382 to point at it.
383 The callback will be used whenever a site requires authentication and
384 the appropriate environment variables are not set.
385 .Pp
386 This interface is experimental and may be subject to change.
387 .Sh RETURN VALUES
388 .Fn fetchParseURL
389 returns a pointer to a
390 .Vt struct url
391 containing the individual components of the URL.
392 If it is
393 unable to allocate memory, or the URL is syntactically incorrect,
394 .Fn fetchParseURL
395 returns a NULL pointer.
396 .Pp
397 The
398 .Fn fetchStat
399 functions return 0 on success and -1 on failure.
400 .Pp
401 All other functions return a stream pointer which may be used to
402 access the requested document, or NULL if an error occurred.
403 .Pp
404 The following error codes are defined in
405 .In fetch.h :
406 .Bl -tag -width 18n
407 .It Bq Er FETCH_ABORT
408 Operation aborted
409 .It Bq Er FETCH_AUTH
410 Authentication failed
411 .It Bq Er FETCH_DOWN
412 Service unavailable
413 .It Bq Er FETCH_EXISTS
414 File exists
415 .It Bq Er FETCH_FULL
416 File system full
417 .It Bq Er FETCH_INFO
418 Informational response
419 .It Bq Er FETCH_MEMORY
420 Insufficient memory
421 .It Bq Er FETCH_MOVED
422 File has moved
423 .It Bq Er FETCH_NETWORK
424 Network error
425 .It Bq Er FETCH_OK
426 No error
427 .It Bq Er FETCH_PROTO
428 Protocol error
429 .It Bq Er FETCH_RESOLV
430 Resolver error
431 .It Bq Er FETCH_SERVER
432 Server error
433 .It Bq Er FETCH_TEMP
434 Temporary error
435 .It Bq Er FETCH_TIMEOUT
436 Operation timed out
437 .It Bq Er FETCH_UNAVAIL
438 File is not available
439 .It Bq Er FETCH_UNKNOWN
440 Unknown error
441 .It Bq Er FETCH_URL
442 Invalid URL
443 .El
444 .Pp
445 The accompanying error message includes a protocol-specific error code
446 and message, e.g.\& "File is not available (404 Not Found)"
447 .Sh ENVIRONMENT
448 .Bl -tag -width ".Ev FETCH_BIND_ADDRESS"
449 .It Ev FETCH_BIND_ADDRESS
450 Specifies a hostname or IP address to which sockets used for outgoing
451 connections will be bound.
452 .It Ev FTP_LOGIN
453 Default FTP login if none was provided in the URL.
454 .It Ev FTP_PASSIVE_MODE
455 If set to anything but
456 .Ql no ,
457 forces the FTP code to use passive mode.
458 .It Ev FTP_PASSWORD
459 Default FTP password if the remote server requests one and none was
460 provided in the URL.
461 .It Ev FTP_PROXY
462 URL of the proxy to use for FTP requests.
463 The document part is ignored.
464 FTP and HTTP proxies are supported; if no scheme is specified, FTP is
465 assumed.
466 If the proxy is an FTP proxy,
467 .Nm libfetch
468 will send
469 .Ql user@host
470 as user name to the proxy, where
471 .Ql user
472 is the real user name, and
473 .Ql host
474 is the name of the FTP server.
475 .Pp
476 If this variable is set to an empty string, no proxy will be used for
477 FTP requests, even if the
478 .Ev HTTP_PROXY
479 variable is set.
480 .It Ev ftp_proxy
481 Same as
482 .Ev FTP_PROXY ,
483 for compatibility.
484 .It Ev HTTP_AUTH
485 Specifies HTTP authorization parameters as a colon-separated list of
486 items.
487 The first and second item are the authorization scheme and realm
488 respectively; further items are scheme-dependent.
489 Currently, only basic authorization is supported.
490 .Pp
491 Basic authorization requires two parameters: the user name and
492 password, in that order.
493 .Pp
494 This variable is only used if the server requires authorization and
495 no user name or password was specified in the URL.
496 .It Ev HTTP_PROXY
497 URL of the proxy to use for HTTP requests.
498 The document part is ignored.
499 Only HTTP proxies are supported for HTTP requests.
500 If no port number is specified, the default is 3128.
501 .Pp
502 Note that this proxy will also be used for FTP documents, unless the
503 .Ev FTP_PROXY
504 variable is set.
505 .It Ev http_proxy
506 Same as
507 .Ev HTTP_PROXY ,
508 for compatibility.
509 .It Ev HTTP_PROXY_AUTH
510 Specifies authorization parameters for the HTTP proxy in the same
511 format as the
512 .Ev HTTP_AUTH
513 variable.
514 .Pp
515 This variable is used if and only if connected to an HTTP proxy, and
516 is ignored if a user and/or a password were specified in the proxy
517 URL.
518 .It Ev HTTP_REFERER
519 Specifies the referrer URL to use for HTTP requests.
520 If set to
521 .Dq auto ,
522 the document URL will be used as referrer URL.
523 .It Ev HTTP_USER_AGENT
524 Specifies the User-Agent string to use for HTTP requests.
525 This can be useful when working with HTTP origin or proxy servers that
526 differentiate between user agents.
527 .It Ev NETRC
528 Specifies a file to use instead of
529 .Pa ~/.netrc
530 to look up login names and passwords for FTP sites.
531 See
532 .Xr ftp 1
533 for a description of the file format.
534 This feature is experimental.
535 .El
536 .Sh EXAMPLES
537 To access a proxy server on
538 .Pa proxy.example.com
539 port 8080, set the
540 .Ev HTTP_PROXY
541 environment variable in a manner similar to this:
542 .Pp
543 .Dl HTTP_PROXY=http://proxy.example.com:8080
544 .Pp
545 If the proxy server requires authentication, there are
546 two options available for passing the authentication data.
547 The first method is by using the proxy URL:
548 .Pp
549 .Dl HTTP_PROXY=http://<user>:<pwd>@proxy.example.com:8080
550 .Pp
551 The second method is by using the
552 .Ev HTTP_PROXY_AUTH
553 environment variable:
554 .Bd -literal -offset indent
555 HTTP_PROXY=http://proxy.example.com:8080
556 HTTP_PROXY_AUTH=basic:*:<user>:<pwd>
557 .Ed
558 .Sh SEE ALSO
559 .Xr fetch 1 ,
560 .Xr ftpio 3 ,
561 .Xr ip 4
562 .Rs
563 .%A J. Postel
564 .%A J. K. Reynolds
565 .%D October 1985
566 .%B File Transfer Protocol
567 .%O RFC 959
568 .Re
569 .Rs
570 .%A P. Deutsch
571 .%A A. Emtage
572 .%A A. Marine.
573 .%D May 1994
574 .%T How to Use Anonymous FTP
575 .%O RFC 1635
576 .Re
577 .Rs
578 .%A T. Berners-Lee
579 .%A L. Masinter
580 .%A M. McCahill
581 .%D December 1994
582 .%T Uniform Resource Locators (URL)
583 .%O RFC 1738
584 .Re
585 .Rs
586 .%A R. Fielding
587 .%A J. Gettys
588 .%A J. Mogul
589 .%A H. Frystyk
590 .%A L. Masinter
591 .%A P. Leach
592 .%A T. Berners-Lee
593 .%D January 1999
594 .%B Hypertext Transfer Protocol -- HTTP/1.1
595 .%O RFC 2616
596 .Re
597 .Rs
598 .%A J. Franks
599 .%A P. Hallam-Baker
600 .%A J. Hostetler
601 .%A S. Lawrence
602 .%A P. Leach
603 .%A A. Luotonen
604 .%A L. Stewart
605 .%D June 1999
606 .%B HTTP Authentication: Basic and Digest Access Authentication
607 .%O RFC 2617
608 .Re
609 .Sh HISTORY
610 The
611 .Nm fetch
612 library first appeared in
613 .Fx 3.0 .
614 .Sh AUTHORS
615 .An -nosplit
616 The
617 .Nm fetch
618 library was mostly written by
619 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org
620 with numerous suggestions from
621 .An Jordan K. Hubbard Aq jkh@FreeBSD.org ,
622 .An Eugene Skepner Aq eu@qub.com
623 and other
624 .Fx
625 developers.
626 It replaces the older
627 .Nm ftpio
628 library written by
629 .An Poul-Henning Kamp Aq phk@FreeBSD.org
630 and
631 .An Jordan K. Hubbard Aq jkh@FreeBSD.org .
632 .Pp
633 This manual page was written by
634 .An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org .
635 .Sh BUGS
636 Some parts of the library are not yet implemented.
637 The most notable
638 examples of this are
639 .Fn fetchPutHTTP ,
640 .Fn fetchListHTTP ,
641 .Fn fetchListFTP
642 and FTP proxy support.
643 .Pp
644 There is no way to select a proxy at run-time other than setting the
645 .Ev HTTP_PROXY
646 or
647 .Ev FTP_PROXY
648 environment variables as appropriate.
649 .Pp
650 .Nm libfetch
651 does not understand or obey 305 (Use Proxy) replies.
652 .Pp
653 Error numbers are unique only within a certain context; the error
654 codes used for FTP and HTTP overlap, as do those used for resolver and
655 system errors.
656 For instance, error code 202 means "Command not
657 implemented, superfluous at this site" in an FTP context and
658 "Accepted" in an HTTP context.
659 .Pp
660 .Fn fetchStatFTP
661 does not check that the result of an MDTM command is a valid date.
662 .Pp
663 The man page is incomplete, poorly written and produces badly
664 formatted text.
665 .Pp
666 The error reporting mechanism is unsatisfactory.
667 .Pp
668 Some parts of the code are not fully reentrant.