summaryrefslogtreecommitdiff
path: root/lib/libfetch/fetch.3
diff options
context:
space:
mode:
Diffstat (limited to 'lib/libfetch/fetch.3')
-rw-r--r--lib/libfetch/fetch.3668
1 files changed, 0 insertions, 668 deletions
diff --git a/lib/libfetch/fetch.3 b/lib/libfetch/fetch.3
deleted file mode 100644
index 67c29b08..00000000
--- a/lib/libfetch/fetch.3
+++ /dev/null
@@ -1,668 +0,0 @@
-.\"-
-.\" Copyright (c) 1998-2004 Dag-Erling Coïdan Smørgrav
-.\" All rights reserved.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\" notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\" notice, this list of conditions and the following disclaimer in the
-.\" documentation and/or other materials provided with the distribution.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
-.\"
-.\" $FreeBSD: /repoman/r/ncvs/src/lib/libfetch/fetch.3,v 1.61 2005/11/30 04:08:45 tmclaugh Exp $
-.\"
-.Dd July 1, 1998
-.Dt FETCH 3
-.Os
-.Sh NAME
-.Nm fetchMakeURL ,
-.Nm fetchParseURL ,
-.Nm fetchFreeURL ,
-.Nm fetchXGetURL ,
-.Nm fetchGetURL ,
-.Nm fetchPutURL ,
-.Nm fetchStatURL ,
-.Nm fetchListURL ,
-.Nm fetchXGet ,
-.Nm fetchGet ,
-.Nm fetchPut ,
-.Nm fetchStat ,
-.Nm fetchList ,
-.Nm fetchXGetFile ,
-.Nm fetchGetFile ,
-.Nm fetchPutFile ,
-.Nm fetchStatFile ,
-.Nm fetchListFile ,
-.Nm fetchXGetHTTP ,
-.Nm fetchGetHTTP ,
-.Nm fetchPutHTTP ,
-.Nm fetchStatHTTP ,
-.Nm fetchListHTTP ,
-.Nm fetchXGetFTP ,
-.Nm fetchGetFTP ,
-.Nm fetchPutFTP ,
-.Nm fetchStatFTP ,
-.Nm fetchListFTP
-.Nd file transfer functions
-.Sh LIBRARY
-.Lb libfetch
-.Sh SYNOPSIS
-.In sys/param.h
-.In stdio.h
-.In fetch.h
-.Ft struct url *
-.Fn fetchMakeURL "const char *scheme" "const char *host" "int port" "const char *doc" "const char *user" "const char *pwd"
-.Ft struct url *
-.Fn fetchParseURL "const char *URL"
-.Ft void
-.Fn fetchFreeURL "struct url *u"
-.Ft FILE *
-.Fn fetchXGetURL "const char *URL" "struct url_stat *us" "const char *flags"
-.Ft FILE *
-.Fn fetchGetURL "const char *URL" "const char *flags"
-.Ft FILE *
-.Fn fetchPutURL "const char *URL" "const char *flags"
-.Ft int
-.Fn fetchStatURL "const char *URL" "struct url_stat *us" "const char *flags"
-.Ft struct url_ent *
-.Fn fetchListURL "const char *URL" "const char *flags"
-.Ft FILE *
-.Fn fetchXGet "struct url *u" "struct url_stat *us" "const char *flags"
-.Ft FILE *
-.Fn fetchGet "struct url *u" "const char *flags"
-.Ft FILE *
-.Fn fetchPut "struct url *u" "const char *flags"
-.Ft int
-.Fn fetchStat "struct url *u" "struct url_stat *us" "const char *flags"
-.Ft struct url_ent *
-.Fn fetchList "struct url *u" "const char *flags"
-.Ft FILE *
-.Fn fetchXGetFile "struct url *u" "struct url_stat *us" "const char *flags"
-.Ft FILE *
-.Fn fetchGetFile "struct url *u" "const char *flags"
-.Ft FILE *
-.Fn fetchPutFile "struct url *u" "const char *flags"
-.Ft int
-.Fn fetchStatFile "struct url *u" "struct url_stat *us" "const char *flags"
-.Ft struct url_ent *
-.Fn fetchListFile "struct url *u" "const char *flags"
-.Ft FILE *
-.Fn fetchXGetHTTP "struct url *u" "struct url_stat *us" "const char *flags"
-.Ft FILE *
-.Fn fetchGetHTTP "struct url *u" "const char *flags"
-.Ft FILE *
-.Fn fetchPutHTTP "struct url *u" "const char *flags"
-.Ft int
-.Fn fetchStatHTTP "struct url *u" "struct url_stat *us" "const char *flags"
-.Ft struct url_ent *
-.Fn fetchListHTTP "struct url *u" "const char *flags"
-.Ft FILE *
-.Fn fetchXGetFTP "struct url *u" "struct url_stat *us" "const char *flags"
-.Ft FILE *
-.Fn fetchGetFTP "struct url *u" "const char *flags"
-.Ft FILE *
-.Fn fetchPutFTP "struct url *u" "const char *flags"
-.Ft int
-.Fn fetchStatFTP "struct url *u" "struct url_stat *us" "const char *flags"
-.Ft struct url_ent *
-.Fn fetchListFTP "struct url *u" "const char *flags"
-.Sh DESCRIPTION
-These functions implement a high-level library for retrieving and
-uploading files using Uniform Resource Locators (URLs).
-.Pp
-.Fn fetchParseURL
-takes a URL in the form of a null-terminated string and splits it into
-its components function according to the Common Internet Scheme Syntax
-detailed in RFC1738.
-A regular expression which produces this syntax is:
-.Bd -literal
- <scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)?
-.Ed
-.Pp
-If the URL does not seem to begin with a scheme name, the following
-syntax is assumed:
-.Bd -literal
- ((<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)?
-.Ed
-.Pp
-Note that some components of the URL are not necessarily relevant to
-all URL schemes.
-For instance, the file scheme only needs the <scheme> and <document>
-components.
-.Pp
-.Fn fetchMakeURL
-and
-.Fn fetchParseURL
-return a pointer to a
-.Vt url
-structure, which is defined as follows in
-.In fetch.h :
-.Bd -literal
-#define URL_SCHEMELEN 16
-#define URL_USERLEN 256
-#define URL_PWDLEN 256
-
-struct url {
- char scheme[URL_SCHEMELEN+1];
- char user[URL_USERLEN+1];
- char pwd[URL_PWDLEN+1];
- char host[MAXHOSTNAMELEN+1];
- int port;
- char *doc;
- off_t offset;
- size_t length;
-};
-.Ed
-.Pp
-The pointer returned by
-.Fn fetchMakeURL
-or
-.Fn fetchParseURL
-should be freed using
-.Fn fetchFreeURL .
-.Pp
-.Fn fetchXGetURL ,
-.Fn fetchGetURL ,
-and
-.Fn fetchPutURL
-constitute the recommended interface to the
-.Nm fetch
-library.
-They examine the URL passed to them to determine the transfer
-method, and call the appropriate lower-level functions to perform the
-actual transfer.
-.Fn fetchXGetURL
-also returns the remote document's metadata in the
-.Vt url_stat
-structure pointed to by the
-.Fa us
-argument.
-.Pp
-The
-.Fa flags
-argument is a string of characters which specify transfer options.
-The
-meaning of the individual flags is scheme-dependent, and is detailed
-in the appropriate section below.
-.Pp
-.Fn fetchStatURL
-attempts to obtain the requested document's metadata and fill in the
-structure pointed to by its second argument.
-The
-.Vt url_stat
-structure is defined as follows in
-.In fetch.h :
-.Bd -literal
-struct url_stat {
- off_t size;
- time_t atime;
- time_t mtime;
-};
-.Ed
-.Pp
-If the size could not be obtained from the server, the
-.Fa size
-field is set to -1.
-If the modification time could not be obtained from the server, the
-.Fa mtime
-field is set to the epoch.
-If the access time could not be obtained from the server, the
-.Fa atime
-field is set to the modification time.
-.Pp
-.Fn fetchListURL
-attempts to list the contents of the directory pointed to by the URL
-provided.
-If successful, it returns a malloced array of
-.Vt url_ent
-structures.
-The
-.Vt url_ent
-structure is defined as follows in
-.In fetch.h :
-.Bd -literal
-struct url_ent {
- char name[MAXPATHLEN];
- struct url_stat stat;
-};
-.Ed
-.Pp
-The list is terminated by an entry with an empty name.
-.Pp
-The pointer returned by
-.Fn fetchListURL
-should be freed using
-.Fn free .
-.Pp
-.Fn fetchXGet ,
-.Fn fetchGet ,
-.Fn fetchPut
-and
-.Fn fetchStat
-are similar to
-.Fn fetchXGetURL ,
-.Fn fetchGetURL ,
-.Fn fetchPutURL
-and
-.Fn fetchStatURL ,
-except that they expect a pre-parsed URL in the form of a pointer to
-a
-.Vt struct url
-rather than a string.
-.Pp
-All of the
-.Fn fetchXGetXXX ,
-.Fn fetchGetXXX
-and
-.Fn fetchPutXXX
-functions return a pointer to a stream which can be used to read or
-write data from or to the requested document, respectively.
-Note that
-although the implementation details of the individual access methods
-vary, it can generally be assumed that a stream returned by one of the
-.Fn fetchXGetXXX
-or
-.Fn fetchGetXXX
-functions is read-only, and that a stream returned by one of the
-.Fn fetchPutXXX
-functions is write-only.
-.Sh FILE SCHEME
-.Fn fetchXGetFile ,
-.Fn fetchGetFile
-and
-.Fn fetchPutFile
-provide access to documents which are files in a locally mounted file
-system.
-Only the <document> component of the URL is used.
-.Pp
-.Fn fetchXGetFile
-and
-.Fn fetchGetFile
-do not accept any flags.
-.Pp
-.Fn fetchPutFile
-accepts the
-.Ql a
-(append to file) flag.
-If that flag is specified, the data written to
-the stream returned by
-.Fn fetchPutFile
-will be appended to the previous contents of the file, instead of
-replacing them.
-.Sh FTP SCHEME
-.Fn fetchXGetFTP ,
-.Fn fetchGetFTP
-and
-.Fn fetchPutFTP
-implement the FTP protocol as described in RFC959.
-.Pp
-If the
-.Ql p
-(passive) flag is specified, a passive (rather than active) connection
-will be attempted.
-.Pp
-If the
-.Ql l
-(low) flag is specified, data sockets will be allocated in the low (or
-default) port range instead of the high port range (see
-.Xr ip 4 ) .
-.Pp
-If the
-.Ql d
-(direct) flag is specified,
-.Fn fetchXGetFTP ,
-.Fn fetchGetFTP
-and
-.Fn fetchPutFTP
-will use a direct connection even if a proxy server is defined.
-.Pp
-If no user name or password is given, the
-.Nm fetch
-library will attempt an anonymous login, with user name "anonymous"
-and password "anonymous@<hostname>".
-.Sh HTTP SCHEME
-The
-.Fn fetchXGetHTTP ,
-.Fn fetchGetHTTP
-and
-.Fn fetchPutHTTP
-functions implement the HTTP/1.1 protocol.
-With a little luck, there is
-even a chance that they comply with RFC2616 and RFC2617.
-.Pp
-If the
-.Ql d
-(direct) flag is specified,
-.Fn fetchXGetHTTP ,
-.Fn fetchGetHTTP
-and
-.Fn fetchPutHTTP
-will use a direct connection even if a proxy server is defined.
-.Pp
-Since there seems to be no good way of implementing the HTTP PUT
-method in a manner consistent with the rest of the
-.Nm fetch
-library,
-.Fn fetchPutHTTP
-is currently unimplemented.
-.Sh AUTHENTICATION
-Apart from setting the appropriate environment variables and
-specifying the user name and password in the URL or the
-.Vt struct url ,
-the calling program has the option of defining an authentication
-function with the following prototype:
-.Pp
-.Ft int
-.Fn myAuthMethod "struct url *u"
-.Pp
-The callback function should fill in the
-.Fa user
-and
-.Fa pwd
-fields in the provided
-.Vt struct url
-and return 0 on success, or any other value to indicate failure.
-.Pp
-To register the authentication callback, simply set
-.Va fetchAuthMethod
-to point at it.
-The callback will be used whenever a site requires authentication and
-the appropriate environment variables are not set.
-.Pp
-This interface is experimental and may be subject to change.
-.Sh RETURN VALUES
-.Fn fetchParseURL
-returns a pointer to a
-.Vt struct url
-containing the individual components of the URL.
-If it is
-unable to allocate memory, or the URL is syntactically incorrect,
-.Fn fetchParseURL
-returns a NULL pointer.
-.Pp
-The
-.Fn fetchStat
-functions return 0 on success and -1 on failure.
-.Pp
-All other functions return a stream pointer which may be used to
-access the requested document, or NULL if an error occurred.
-.Pp
-The following error codes are defined in
-.In fetch.h :
-.Bl -tag -width 18n
-.It Bq Er FETCH_ABORT
-Operation aborted
-.It Bq Er FETCH_AUTH
-Authentication failed
-.It Bq Er FETCH_DOWN
-Service unavailable
-.It Bq Er FETCH_EXISTS
-File exists
-.It Bq Er FETCH_FULL
-File system full
-.It Bq Er FETCH_INFO
-Informational response
-.It Bq Er FETCH_MEMORY
-Insufficient memory
-.It Bq Er FETCH_MOVED
-File has moved
-.It Bq Er FETCH_NETWORK
-Network error
-.It Bq Er FETCH_OK
-No error
-.It Bq Er FETCH_PROTO
-Protocol error
-.It Bq Er FETCH_RESOLV
-Resolver error
-.It Bq Er FETCH_SERVER
-Server error
-.It Bq Er FETCH_TEMP
-Temporary error
-.It Bq Er FETCH_TIMEOUT
-Operation timed out
-.It Bq Er FETCH_UNAVAIL
-File is not available
-.It Bq Er FETCH_UNKNOWN
-Unknown error
-.It Bq Er FETCH_URL
-Invalid URL
-.El
-.Pp
-The accompanying error message includes a protocol-specific error code
-and message, e.g.\& "File is not available (404 Not Found)"
-.Sh ENVIRONMENT
-.Bl -tag -width ".Ev FETCH_BIND_ADDRESS"
-.It Ev FETCH_BIND_ADDRESS
-Specifies a hostname or IP address to which sockets used for outgoing
-connections will be bound.
-.It Ev FTP_LOGIN
-Default FTP login if none was provided in the URL.
-.It Ev FTP_PASSIVE_MODE
-If set to anything but
-.Ql no ,
-forces the FTP code to use passive mode.
-.It Ev FTP_PASSWORD
-Default FTP password if the remote server requests one and none was
-provided in the URL.
-.It Ev FTP_PROXY
-URL of the proxy to use for FTP requests.
-The document part is ignored.
-FTP and HTTP proxies are supported; if no scheme is specified, FTP is
-assumed.
-If the proxy is an FTP proxy,
-.Nm libfetch
-will send
-.Ql user@host
-as user name to the proxy, where
-.Ql user
-is the real user name, and
-.Ql host
-is the name of the FTP server.
-.Pp
-If this variable is set to an empty string, no proxy will be used for
-FTP requests, even if the
-.Ev HTTP_PROXY
-variable is set.
-.It Ev ftp_proxy
-Same as
-.Ev FTP_PROXY ,
-for compatibility.
-.It Ev HTTP_AUTH
-Specifies HTTP authorization parameters as a colon-separated list of
-items.
-The first and second item are the authorization scheme and realm
-respectively; further items are scheme-dependent.
-Currently, only basic authorization is supported.
-.Pp
-Basic authorization requires two parameters: the user name and
-password, in that order.
-.Pp
-This variable is only used if the server requires authorization and
-no user name or password was specified in the URL.
-.It Ev HTTP_PROXY
-URL of the proxy to use for HTTP requests.
-The document part is ignored.
-Only HTTP proxies are supported for HTTP requests.
-If no port number is specified, the default is 3128.
-.Pp
-Note that this proxy will also be used for FTP documents, unless the
-.Ev FTP_PROXY
-variable is set.
-.It Ev http_proxy
-Same as
-.Ev HTTP_PROXY ,
-for compatibility.
-.It Ev HTTP_PROXY_AUTH
-Specifies authorization parameters for the HTTP proxy in the same
-format as the
-.Ev HTTP_AUTH
-variable.
-.Pp
-This variable is used if and only if connected to an HTTP proxy, and
-is ignored if a user and/or a password were specified in the proxy
-URL.
-.It Ev HTTP_REFERER
-Specifies the referrer URL to use for HTTP requests.
-If set to
-.Dq auto ,
-the document URL will be used as referrer URL.
-.It Ev HTTP_USER_AGENT
-Specifies the User-Agent string to use for HTTP requests.
-This can be useful when working with HTTP origin or proxy servers that
-differentiate between user agents.
-.It Ev NETRC
-Specifies a file to use instead of
-.Pa ~/.netrc
-to look up login names and passwords for FTP sites.
-See
-.Xr ftp 1
-for a description of the file format.
-This feature is experimental.
-.El
-.Sh EXAMPLES
-To access a proxy server on
-.Pa proxy.example.com
-port 8080, set the
-.Ev HTTP_PROXY
-environment variable in a manner similar to this:
-.Pp
-.Dl HTTP_PROXY=http://proxy.example.com:8080
-.Pp
-If the proxy server requires authentication, there are
-two options available for passing the authentication data.
-The first method is by using the proxy URL:
-.Pp
-.Dl HTTP_PROXY=http://<user>:<pwd>@proxy.example.com:8080
-.Pp
-The second method is by using the
-.Ev HTTP_PROXY_AUTH
-environment variable:
-.Bd -literal -offset indent
-HTTP_PROXY=http://proxy.example.com:8080
-HTTP_PROXY_AUTH=basic:*:<user>:<pwd>
-.Ed
-.Sh SEE ALSO
-.Xr fetch 1 ,
-.Xr ftpio 3 ,
-.Xr ip 4
-.Rs
-.%A J. Postel
-.%A J. K. Reynolds
-.%D October 1985
-.%B File Transfer Protocol
-.%O RFC959
-.Re
-.Rs
-.%A P. Deutsch
-.%A A. Emtage
-.%A A. Marine.
-.%D May 1994
-.%T How to Use Anonymous FTP
-.%O RFC1635
-.Re
-.Rs
-.%A T. Berners-Lee
-.%A L. Masinter
-.%A M. McCahill
-.%D December 1994
-.%T Uniform Resource Locators (URL)
-.%O RFC1738
-.Re
-.Rs
-.%A R. Fielding
-.%A J. Gettys
-.%A J. Mogul
-.%A H. Frystyk
-.%A L. Masinter
-.%A P. Leach
-.%A T. Berners-Lee
-.%D January 1999
-.%B Hypertext Transfer Protocol -- HTTP/1.1
-.%O RFC2616
-.Re
-.Rs
-.%A J. Franks
-.%A P. Hallam-Baker
-.%A J. Hostetler
-.%A S. Lawrence
-.%A P. Leach
-.%A A. Luotonen
-.%A L. Stewart
-.%D June 1999
-.%B HTTP Authentication: Basic and Digest Access Authentication
-.%O RFC2617
-.Re
-.Sh HISTORY
-The
-.Nm fetch
-library first appeared in
-.Fx 3.0 .
-.Sh AUTHORS
-.An -nosplit
-The
-.Nm fetch
-library was mostly written by
-.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org
-with numerous suggestions from
-.An Jordan K. Hubbard Aq jkh@FreeBSD.org ,
-.An Eugene Skepner Aq eu@qub.com
-and other
-.Fx
-developers.
-It replaces the older
-.Nm ftpio
-library written by
-.An Poul-Henning Kamp Aq phk@FreeBSD.org
-and
-.An Jordan K. Hubbard Aq jkh@FreeBSD.org .
-.Pp
-This manual page was written by
-.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
-.Sh BUGS
-Some parts of the library are not yet implemented.
-The most notable
-examples of this are
-.Fn fetchPutHTTP ,
-.Fn fetchListHTTP ,
-.Fn fetchListFTP
-and FTP proxy support.
-.Pp
-There is no way to select a proxy at run-time other than setting the
-.Ev HTTP_PROXY
-or
-.Ev FTP_PROXY
-environment variables as appropriate.
-.Pp
-.Nm libfetch
-does not understand or obey 305 (Use Proxy) replies.
-.Pp
-Error numbers are unique only within a certain context; the error
-codes used for FTP and HTTP overlap, as do those used for resolver and
-system errors.
-For instance, error code 202 means "Command not
-implemented, superfluous at this site" in an FTP context and
-"Accepted" in an HTTP context.
-.Pp
-.Fn fetchStatFTP
-does not check that the result of an MDTM command is a valid date.
-.Pp
-The man page is incomplete, poorly written and produces badly
-formatted text.
-.Pp
-The error reporting mechanism is unsatisfactory.
-.Pp
-Some parts of the code are not fully reentrant.