1 .\" Copyright (c) 1998 Dag-Erling Coïdan Smørgrav
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
59 .Nd file transfer functions
67 .Fn fetchMakeURL "const char *scheme" "const char *host" "int port" "const char *doc" "const char *user" "const char *pwd"
69 .Fn fetchParseURL "const char *URL"
71 .Fn fetchFreeURL "struct url *u"
73 .Fn fetchXGetURL "const char *URL" "struct url_stat *us" "const char *flags"
75 .Fn fetchGetURL "const char *URL" "const char *flags"
77 .Fn fetchPutURL "const char *URL" "const char *flags"
79 .Fn fetchStatURL "const char *URL" "struct url_stat *us" "const char *flags"
81 .Fn fetchListURL "const char *URL" "const char *flags"
83 .Fn fetchXGet "struct url *u" "struct url_stat *us" "const char *flags"
85 .Fn fetchGet "struct url *u" "const char *flags"
87 .Fn fetchPut "struct url *u" "const char *flags"
89 .Fn fetchStat "struct url *u" "struct url_stat *us" "const char *flags"
91 .Fn fetchList "struct url *u" "const char *flags"
93 .Fn fetchXGetFile "struct url *u" "struct url_stat *us" "const char *flags"
95 .Fn fetchGetFile "struct url *u" "const char *flags"
97 .Fn fetchPutFile "struct url *u" "const char *flags"
99 .Fn fetchStatFile "struct url *u" "struct url_stat *us" "const char *flags"
101 .Fn fetchListFile "struct url *u" "const char *flags"
103 .Fn fetchXGetHTTP "struct url *u" "struct url_stat *us" "const char *flags"
105 .Fn fetchGetHTTP "struct url *u" "const char *flags"
107 .Fn fetchPutHTTP "struct url *u" "const char *flags"
109 .Fn fetchStatHTTP "struct url *u" "struct url_stat *us" "const char *flags"
111 .Fn fetchListHTTP "struct url *u" "const char *flags"
113 .Fn fetchXGetFTP "struct url *u" "struct url_stat *us" "const char *flags"
115 .Fn fetchGetFTP "struct url *u" "const char *flags"
117 .Fn fetchPutFTP "struct url *u" "const char *flags"
119 .Fn fetchStatFTP "struct url *u" "struct url_stat *us" "const char *flags"
121 .Fn fetchListFTP "struct url *u" "const char *flags"
123 These functions implement a high-level library for retrieving and
124 uploading files using Uniform Resource Locators (URLs).
127 takes a URL in the form of a null-terminated string and splits it into
128 its components function according to the Common Internet Scheme Syntax
130 A regular expression which produces this syntax is:
132 <scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)?
135 If the URL does not seem to begin with a scheme name, the following
138 ((<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)?
141 Note that some components of the URL are not necessarily relevant to
143 For instance, the file scheme only needs the <scheme> and <document>
149 return a pointer to a
151 structure, which is defined as follows in
154 #define URL_SCHEMELEN 16
155 #define URL_USERLEN 256
156 #define URL_PWDLEN 256
159 char scheme[URL_SCHEMELEN+1];
160 char user[URL_USERLEN+1];
161 char pwd[URL_PWDLEN+1];
162 char host[MAXHOSTNAMELEN+1];
170 The pointer returned by
174 should be freed using
181 constitute the recommended interface to the
184 They examine the URL passed to them to determine the transfer
185 method, and call the appropriate lower-level functions to perform the
188 also returns the remote document's metadata in the
190 structure pointed to by the
196 argument is a string of characters which specify transfer options.
198 meaning of the individual flags is scheme-dependent, and is detailed
199 in the appropriate section below.
202 attempts to obtain the requested document's metadata and fill in the
203 structure pointed to by its second argument.
206 structure is defined as follows in
216 If the size could not be obtained from the server, the
219 If the modification time could not be obtained from the server, the
221 field is set to the epoch.
222 If the access time could not be obtained from the server, the
224 field is set to the modification time.
227 attempts to list the contents of the directory pointed to by the URL
229 If successful, it returns a malloced array of
234 structure is defined as follows in
238 char name[MAXPATHLEN];
239 struct url_stat stat;
243 The list is terminated by an entry with an empty name.
245 The pointer returned by
247 should be freed using
261 except that they expect a pre-parsed URL in the form of a pointer to
264 rather than a string.
271 functions return a pointer to a stream which can be used to read or
272 write data from or to the requested document, respectively.
274 although the implementation details of the individual access methods
275 vary, it can generally be assumed that a stream returned by one of the
279 functions is read-only, and that a stream returned by one of the
281 functions is write-only.
287 provide access to documents which are files in a locally mounted file
289 Only the <document> component of the URL is used.
294 do not accept any flags.
299 (append to file) flag.
300 If that flag is specified, the data written to
301 the stream returned by
303 will be appended to the previous contents of the file, instead of
310 implement the FTP protocol as described in RFC959.
314 (passive) flag is specified, a passive (rather than active) connection
319 (low) flag is specified, data sockets will be allocated in the low (or
320 default) port range instead of the hifh port range (see
325 (direct) flag is specified,
330 will use a direct connection even if a proxy server is defined.
332 If no user name or password is given, the
334 library will attempt an anonymous login, with user name "anonymous"
335 and password "anonymous@<hostname>".
342 functions implement the HTTP/1.1 protocol.
343 With a little luck, there's
344 even a chance that they comply with RFC2616 and RFC2617.
348 (direct) flag is specified,
353 will use a direct connection even if a proxy server is defined.
355 Since there seems to be no good way of implementing the HTTP PUT
356 method in a manner consistent with the rest of the
360 is currently unimplemented.
362 Apart from setting the appropriate environment variables and
363 specifying the user name and password in the URL or the
365 the calling program has the option of defining an authentication
366 function with the following prototype:
369 .Fn myAuthMethod "struct url *u"
371 The callback function should fill in the
375 fields in the provided
377 and return 0 on success, or any other value to indicate failure.
379 To register the authentication callback, simply set
382 The callback will be used whenever a site requires authentication and
383 the appropriate environment variables aren't set.
385 This interface is experimental and may be subject to change.
388 returns a pointer to a
390 containing the individual components of the URL.
392 unable to allocate memory, or the URL is syntactically incorrect,
394 returns a NULL pointer.
398 functions return 0 on success and -1 on failure.
400 All other functions return a stream pointer which may be used to
401 access the requested document, or NULL if an error occurred.
403 The following error codes are defined in
406 .It Bq Er FETCH_ABORT
409 Authentication failed
412 .It Bq Er FETCH_EXISTS
417 Informational response
418 .It Bq Er FETCH_MEMORY
420 .It Bq Er FETCH_MOVED
422 .It Bq Er FETCH_NETWORK
426 .It Bq Er FETCH_PROTO
428 .It Bq Er FETCH_RESOLV
430 .It Bq Er FETCH_SERVER
434 .It Bq Er FETCH_TIMEOUT
436 .It Bq Er FETCH_UNAVAIL
437 File is not available
438 .It Bq Er FETCH_UNKNOWN
444 The accompanying error message includes a protocol-specific error code
445 and message, e.g. "File is not available (404 Not Found)"
447 .Bl -tag -width FTP_PASSIVE_MODE
449 Default FTP login if none was provided in the URL.
450 .It Ev FTP_PASSIVE_MODE
451 If set to anything but
453 forces the FTP code to use passive mode.
455 Default FTP password if the remote server requests one and none was
458 URL of the proxy to use for FTP requests.
459 The document part is ignored.
460 FTP and HTTP proxies are supported; if no scheme is specified, FTP is
462 If the proxy is an FTP proxy,
466 as user name to the proxy, where
468 is the real user name, and
470 is the name of the FTP server.
472 If this variable is set to an empty string, no proxy will be used for
473 FTP requests, even if the
481 Specifies HTTP authorization parameters as a colon-separated list of
483 The first and second item are the authorization scheme and realm
484 respectively; further items are scheme-dependent.
485 Currently, only basic authorization is supported.
487 Basic authorization requires two parameters: the user name and
488 password, in that order.
490 This variable is only used if the server requires authorization and
491 no user name or password was specified in the URL.
493 URL of the proxy to use for HTTP requests.
494 The document part is ignored.
495 Only HTTP proxies are supported for HTTP requests.
496 If no port number is specified, the default is 3128.
498 Note that this proxy will also be used for FTP documents, unless the
505 .It Ev HTTP_PROXY_AUTH
506 Specifies authorization parameters for the HTTP proxy in the same
511 This variable is used if and only if connected to an HTTP proxy, and
512 is ignored if a user and/or a password were specified in the proxy
514 .It Ev HTTP_USER_AGENT
515 Specifies the User-Agent string to use for HTTP requests.
516 This can be useful when working with HTTP origin or proxy servers that
517 differentiate between user agents.
527 .%B File Transfer Protocol
535 .%T How to Use Anonymous FTP
543 .%T Uniform Resource Locators (URL)
555 .%B Hypertext Transfer Protocol -- HTTP/1.1
567 .%B HTTP Authentication: Basic and Digest Access Authentication
573 library first appeared in
579 library was mostly written by
580 .An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org
581 with numerous suggestions from
582 .An Jordan K. Hubbard Aq jkh@FreeBSD.org ,
583 .An Eugene Skepner Aq eu@qub.com
587 It replaces the older
590 .An Poul-Henning Kamp Aq pkh@FreeBSD.org
592 .An Jordan K. Hubbard Aq jkh@FreeBSD.org .
594 This manual page was written by
595 .An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org .
597 Some parts of the library are not yet implemented.
603 and FTP proxy support.
605 There's no way to select a proxy at run-time other than setting the
609 environment variables as appropriate.
612 does not understand or obey 305 (Use Proxy) replies.
614 Error numbers are unique only within a certain context; the error
615 codes used for FTP and HTTP overlap, as do those used for resolver and
617 For instance, error code 202 means "Command not
618 implemented, superfluous at this site" in an FTP context and
619 "Accepted" in an HTTP context.
622 does not check that the result of an MDTM command is a valid date.
624 The man page is incomplete, poorly written and produces badly
627 The error reporting mechanism is unsatisfactory.
629 Some parts of the code are not fully reentrant.