diff options
| -rw-r--r-- | net/libfetch/files/fetch.3 | 82 |
1 files changed, 46 insertions, 36 deletions
diff --git a/net/libfetch/files/fetch.3 b/net/libfetch/files/fetch.3 index fa5976fb10a..31e79361bb7 100644 --- a/net/libfetch/files/fetch.3 +++ b/net/libfetch/files/fetch.3 @@ -24,7 +24,7 @@ .\" SUCH DAMAGE. .\" .\" $FreeBSD: fetch.3,v 1.64 2007/12/18 11:03:26 des Exp $ -.\" $NetBSD: fetch.3,v 1.7 2008/04/25 19:59:30 joerg Exp $ +.\" $NetBSD: fetch.3,v 1.8 2008/04/30 11:43:59 wiz Exp $ .\" .Dd April 25, 2008 .Dt FETCH 3 @@ -146,10 +146,10 @@ uploading files using Uniform Resource Locators (URLs). .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. +detailed in RFC 1738. A regular expression which produces this syntax is: .Bd -literal - <scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)? + \*[Lt]scheme\*[Gt]:(//(\*[Lt]user\*[Gt](:\*[Lt]pwd\*[Gt])?@)?\*[Lt]host\*[Gt](:\*[Lt]port\*[Gt])?)?/(\*[Lt]document\*[Gt])? .Ed .Pp If the URL does not seem to begin with a scheme name, it is assumed to be a local path. @@ -157,7 +157,10 @@ Only absolute path names are accepted. .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> +For instance, the file scheme only needs the +.Aq scheme +and +.Aq document components. .Fn fetchParseURL quotes any unsafe character in the URL automatically. @@ -169,7 +172,7 @@ copies an existing structure. .Pp .Fn fetchMakeURL , -.Fn fetchParseURL +.Fn fetchParseURL , and .Fn fetchCopyURL return a pointer to a @@ -196,7 +199,7 @@ struct url { .Pp The pointer returned by .Fn fetchMakeURL , -.Fn fetchCopyURL +.Fn fetchCopyURL , and .Fn fetchParseURL should be freed using @@ -243,7 +246,7 @@ struct url_stat { .Pp If the size could not be obtained from the server, the .Fa size -field is set to -1. +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. @@ -255,7 +258,7 @@ field is set to the modification time. attempts to list the contents of the directory pointed to by the URL provided. The pattern can be a simple glob-like expression as hint. Callers should not depend on the server to filter names. -If successful, it appends the list of entries to the +If successful, it appends the list of entries to the .Vt url_list structure. The @@ -270,7 +273,7 @@ struct url_list { }; .Ed .Pp -The list should be initialised by calling +The list should be initialized by calling .Fn fetchInitURLList and the entries be freed by calling .Fn fetchFreeURLList . @@ -284,7 +287,7 @@ Query arguments and fragment identifiers are not included. returns the last component of the path name as returned by .Fn fetchUnquotePath . .Fn fetchStringifyURL , -.Fn fetchUnquotePath +.Fn fetchUnquotePath , and .Fn fetchUnquoteFilename return a string that should be deallocated with @@ -293,13 +296,13 @@ after use. .Pp .Fn fetchXGet , .Fn fetchGet , -.Fn fetchPut +.Fn fetchPut , and .Fn fetchStat are similar to .Fn fetchXGetURL , .Fn fetchGetURL , -.Fn fetchPutURL +.Fn fetchPutURL , and .Fn fetchStatURL , except that they expect a pre-parsed URL in the form of a pointer to @@ -309,7 +312,7 @@ rather than a string. .Pp All of the .Fn fetchXGetXXX , -.Fn fetchGetXXX +.Fn fetchGetXXX , and .Fn fetchPutXXX functions return a pointer to a stream which can be used to read or @@ -325,12 +328,14 @@ functions is read-only, and that a stream returned by one of the functions is write-only. .Sh FILE SCHEME .Fn fetchXGetFile , -.Fn fetchGetFile +.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. +Only the +.Aq document +component of the URL is used. .Pp .Fn fetchXGetFile and @@ -348,10 +353,10 @@ will be appended to the previous contents of the file, instead of replacing them. .Sh FTP SCHEME .Fn fetchXGetFTP , -.Fn fetchGetFTP +.Fn fetchGetFTP , and .Fn fetchPutFTP -implement the FTP protocol as described in RFC959. +implement the FTP protocol as described in RFC 959. .Pp If the .Ql p @@ -368,7 +373,7 @@ If the .Ql d (direct) flag is specified, .Fn fetchXGetFTP , -.Fn fetchGetFTP +.Fn fetchGetFTP , and .Fn fetchPutFTP will use a direct connection even if a proxy server is defined. @@ -376,22 +381,22 @@ will use a direct connection even if a proxy server is defined. 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>". +and password "anonymous@\*[Lt]hostname\*[Gt]". .Sh HTTP SCHEME The .Fn fetchXGetHTTP , -.Fn fetchGetHTTP +.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. +even a chance that they comply with RFC 2616 and RFC 2617. .Pp If the .Ql d (direct) flag is specified, .Fn fetchXGetHTTP , -.Fn fetchGetHTTP +.Fn fetchGetHTTP , and .Fn fetchPutHTTP will use a direct connection even if a proxy server is defined. @@ -435,14 +440,18 @@ 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. +returns a +.Dv NULL +pointer. .Pp The .Fn fetchStat -functions return 0 on success and -1 on failure. +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. +access the requested document, or +.Dv NULL +if an error occurred. .Pp The following error codes are defined in .In fetch.h : @@ -490,7 +499,7 @@ 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 +Specifies a host name 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. @@ -597,14 +606,14 @@ 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 +.Dl HTTP_PROXY=http://\*[Lt]user\*[Gt]:\*[Lt]pwd\*[Gt]@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> +HTTP_PROXY_AUTH=basic:*:\*[Lt]user\*[Gt]:\*[Lt]pwd\*[Gt] .Ed .Pp To disable the use of a proxy for an HTTP server running on the local @@ -615,23 +624,24 @@ as follows: NO_PROXY=localhost,127.0.0.1 .Ed .Sh SEE ALSO -.Xr fetch 1 , -.Xr ftpio 3 , +.\" .Xr fetch 1 , +.\" .Xr ftpio 3 , +.Xr ftp 1 , .Xr ip 4 .Rs .%A J. Postel .%A J. K. Reynolds .%D October 1985 .%B File Transfer Protocol -.%O RFC959 +.%O RFC 959 .Re .Rs .%A P. Deutsch .%A A. Emtage -.%A A. Marine. +.%A A. Marine .%D May 1994 .%T How to Use Anonymous FTP -.%O RFC1635 +.%O RFC 1635 .Re .Rs .%A T. Berners-Lee @@ -639,7 +649,7 @@ NO_PROXY=localhost,127.0.0.1 .%A M. McCahill .%D December 1994 .%T Uniform Resource Locators (URL) -.%O RFC1738 +.%O RFC 1738 .Re .Rs .%A R. Fielding @@ -651,7 +661,7 @@ NO_PROXY=localhost,127.0.0.1 .%A T. Berners-Lee .%D January 1999 .%B Hypertext Transfer Protocol -- HTTP/1.1 -.%O RFC2616 +.%O RFC 2616 .Re .Rs .%A J. Franks @@ -663,7 +673,7 @@ NO_PROXY=localhost,127.0.0.1 .%A L. Stewart .%D June 1999 .%B HTTP Authentication: Basic and Digest Access Authentication -.%O RFC2617 +.%O RFC 2617 .Re .Sh HISTORY The |