summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorwiz <wiz@pkgsrc.org>2008-04-30 11:43:59 +0000
committerwiz <wiz@pkgsrc.org>2008-04-30 11:43:59 +0000
commit5c4b0396866d3faed5b64ebcdddca01e52742609 (patch)
tree7addeeb1ec9a096bc7be0becfa889a69953b0d6e
parentbc762658a7abb177a021d4b67963d35fa6a3474d (diff)
downloadpkgsrc-5c4b0396866d3faed5b64ebcdddca01e52742609.tar.gz
Formatting improvements. Spelling. Use enough commas in enumeration.
Improve HTML output.
-rw-r--r--net/libfetch/files/fetch.382
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