diff options
Diffstat (limited to 'man7/uri.7')
| -rw-r--r-- | man7/uri.7 | 164 |
1 files changed, 82 insertions, 82 deletions
@@ -25,7 +25,7 @@ .\" Modified Fri Aug 21 23:00:00 1999 by David A. Wheeler (dwheeler@dwheeler.com) .\" Modified Tue Mar 14 2000 by David A. Wheeler (dwheeler@dwheeler.com) .\" -.TH uri 7 2023-04-30 "Linux man-pages 6.05.01" +.TH uri 7 2023-10-31 "Linux man-pages 6.7" .SH NAME uri, url, urn \- uniform resource identifier (URI), including a URL or URN .SH SYNOPSIS @@ -36,7 +36,7 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN .RB [\~\[dq] # \[dq]\~\c .IR fragment \~] .YS -.PP +.P .SY "\fIabsoluteURI\fP \fR=\fP" .I scheme\~\c .RB \[dq] : \[dq] @@ -44,7 +44,7 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN | .IR opaque_part \~) .YS -.PP +.P .SY "\fIrelativeURI\fP \fR=\fP" .RI (\~ net_path | @@ -54,7 +54,7 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN .RB [\~\[dq] ? \[dq]\~\c .IR query \~] .YS -.PP +.P .SY "\fIscheme\fP \fR=\fP" .RB \[dq] http \[dq] | @@ -83,7 +83,7 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN .RB \[dq] wais \[dq] | \&... .YS -.PP +.P .SY "\fIhierarchical_part\fP \fR=\fP" .RI (\~ net_path | @@ -91,18 +91,18 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN .RB [\~\[dq] ? \[dq]\~\c .IR query \~] .YS -.PP +.P .SY "\fInet_path\fP \fR=\fP" .RB \[dq] // \[dq]\~\c .I authority .RI [\~ absolute_path \~] .YS -.PP +.P .SY "\fIabsolute_path\fP \fR=\fP" .RB \[dq] / \[dq]\~\c .I path_segments .YS -.PP +.P .SY "\fIrelative_path\fP \fR=\fP" .I relative_segment .RI [\~ absolute_path \~] @@ -117,14 +117,14 @@ by name or some other attribute of that resource. A Uniform Resource Name (URN) is a URI that must remain globally unique and persistent even when the resource ceases to exist or becomes unavailable. -.PP +.P URIs are the standard way to name hypertext link destinations for tools such as web browsers. The string "http://www.kernel.org" is a URL (and thus it is also a URI). Many people use the term URL loosely as a synonym for URI (though technically URLs are a subset of URIs). -.PP +.P URIs can be absolute or relative. An absolute identifier refers to a resource independent of context, while a relative @@ -140,7 +140,7 @@ character can't be used as the first segment of a relative URI path precede such segments with ./ (e.g., "./this:that"). Note that descendants of MS-DOS (e.g., Microsoft Windows) replace devicename colons with the vertical bar ("|") in URIs, so "C:" becomes "C|". -.PP +.P A fragment identifier, if included, refers to a particular named portion (fragment) of a resource; @@ -155,9 +155,9 @@ For example, many URL schemes permit the authority to be the following format, called here an .I ip_server (square brackets show what's optional): -.PP +.P .IR "ip_server = " [ user " [ : " password " ] @ ] " host " [ : " port ] -.PP +.P This format allows you to optionally insert a username, a user plus password, and/or a port number. The @@ -173,18 +173,18 @@ security risks of having a password written down. If the URL supplies a username but no password, and the remote server requests a password, the program interpreting the URL should request one from the user. -.PP +.P Here are some of the most common schemes in use on UNIX-like systems that are understood by many tools. Note that many tools using URIs also have internal schemes or specialized schemes; see those tools' documentation for information on those schemes. -.PP +.P .B "http \- Web (HTTP) server" -.PP +.P .RI http:// ip_server / path .br .RI http:// ip_server / path ? query -.PP +.P This is a URL accessing a web (HTTP) server. The default port is 80. If the path refers to a directory, the web server will choose what @@ -192,7 +192,7 @@ to return; usually if there is a file named "index.html" or "index.htm" its content is returned, otherwise, a list of the files in the current directory (with appropriate links) is generated and returned. An example is <http://lwn.net>. -.PP +.P A query can be given in the archaic "isindex" format, consisting of a word or phrase and not including an equal sign (=). A query can also be in the longer "GET" format, which has one or more @@ -215,11 +215,11 @@ See the Common Gateway Interface specification at .UR http://www.w3.org\:/CGI .UE for more information. -.PP +.P .B "ftp \- File Transfer Protocol (FTP)" -.PP +.P .RI ftp:// ip_server / path -.PP +.P This is a URL accessing a file through the file transfer protocol (FTP). The default port (for control) is 21. If no username is included, the username "anonymous" is supplied, and @@ -227,16 +227,16 @@ in that case many clients provide as the password the requestor's Internet email address. An example is <ftp://ftp.is.co.za/rfc/rfc1808.txt>. -.PP +.P .B "gopher \- Gopher server" -.PP +.P .RI gopher:// ip_server / "gophertype selector" .br .RI gopher:// ip_server / "gophertype selector" %09 search .br .RI gopher:// ip_server / "gophertype selector" %09 search %09 gopher+_string .br -.PP +.P The default gopher port is 70. .I gophertype is a single-character field to denote the @@ -245,18 +245,18 @@ which the URL refers. The entire path may also be empty, in which case the delimiting "/" is also optional and the gophertype defaults to "1". -.PP +.P .I selector is the Gopher selector string. In the Gopher protocol, Gopher selector strings are a sequence of octets which may contain any octets except 09 hexadecimal (US-ASCII HT or tab), 0A hexadecimal (US-ASCII character LF), and 0D (US-ASCII character CR). -.PP +.P .B "mailto \- Email address" -.PP +.P .RI mailto: email-address -.PP +.P This is an email address, usually of the form .IR name @ hostname . See @@ -264,13 +264,13 @@ See for more information on the correct format of an email address. Note that any % character must be rewritten as %25. An example is <mailto:dwheeler@dwheeler.com>. -.PP +.P .B "news \- Newsgroup or News message" -.PP +.P .RI news: newsgroup-name .br .RI news: message-id -.PP +.P A .I newsgroup-name is a period-delimited hierarchical name, such as @@ -278,7 +278,7 @@ is a period-delimited hierarchical name, such as If <newsgroup-name> is "*" (as in <news:*>), it is used to refer to "all available news groups". An example is <news:comp.lang.ada>. -.PP +.P A .I message-id corresponds to the Message-ID of @@ -290,23 +290,23 @@ and ">"; it takes the form .IR unique @ full_domain_name . A message identifier may be distinguished from a news group name by the presence of the "@" character. -.PP +.P .B "telnet \- Telnet login" -.PP +.P .RI telnet:// ip_server / -.PP +.P The Telnet URL scheme is used to designate interactive text services that may be accessed by the Telnet protocol. The final "/" character may be omitted. The default port is 23. An example is <telnet://melvyl.ucop.edu/>. -.PP +.P .B "file \- Normal file" -.PP +.P .RI file:// ip_server / path_segments .br .RI file: path_segments -.PP +.P This represents a file or directory accessible locally. As a special case, .I ip_server @@ -323,7 +323,7 @@ the filename via filename globbing .BR glob (7) and .BR glob (3)). -.PP +.P The second format (e.g., <file:/etc/passwd>) is a correct format for referring to a local file. @@ -337,13 +337,13 @@ Note that if you really mean to say "start from the current location", don't specify the scheme at all; use a relative address like <../test.txt>, which has the side-effect of being scheme-independent. An example of this scheme is <file:///etc/passwd>. -.PP +.P .B "man \- Man page documentation" -.PP +.P .RI man: command-name .br .RI man: command-name ( section ) -.PP +.P This refers to local online manual (man) reference pages. The command name can optionally be followed by a parenthesis and section number; see @@ -352,9 +352,9 @@ for more information on the meaning of the section numbers. This URI scheme is unique to UNIX-like systems (such as Linux) and is not currently registered by the IETF. An example is <man:ls(1)>. -.PP +.P .B "info \- Info page documentation" -.PP +.P .RI info: virtual-filename .br .RI info: virtual-filename # nodename @@ -362,7 +362,7 @@ An example is <man:ls(1)>. .RI info:( virtual-filename ) .br .RI info:( virtual-filename ) nodename -.PP +.P This scheme refers to online info reference pages (generated from texinfo files), a documentation format used by programs such as the GNU tools. @@ -381,11 +381,11 @@ In both GNOME and KDE, if the form without the nodename is used the nodename is assumed to be "Top". Examples of the GNOME format are <info:gcc> and <info:gcc#G++_and_GCC>. Examples of the KDE format are <info:(gcc)> and <info:(gcc)G++ and GCC>. -.PP +.P .B "whatis \- Documentation search" -.PP +.P .RI whatis: string -.PP +.P This scheme searches the database of short (one-line) descriptions of commands and returns a list of descriptions containing that string. Only complete word matches are returned. @@ -393,16 +393,16 @@ See .BR whatis (1). This URI scheme is unique to UNIX-like systems (such as Linux) and is not currently registered by the IETF. -.PP +.P .B "ghelp \- GNOME help documentation" -.PP +.P .RI ghelp: name-of-application -.PP +.P This loads GNOME help for the given application. Note that not much documentation currently exists in this format. -.PP +.P .B "ldap \- Lightweight Directory Access Protocol" -.PP +.P .RI ldap:// hostport .br .RI ldap:// hostport / @@ -416,7 +416,7 @@ Note that not much documentation currently exists in this format. .RI ldap:// hostport / dn ? attributes ? scope ? filter .br .RI ldap:// hostport / dn ? attributes ? scope ? filter ? extensions -.PP +.P This scheme supports queries to the Lightweight Directory Access Protocol (LDAP), a protocol for querying a set of servers for hierarchically organized information @@ -469,36 +469,36 @@ pairs, where the =value portion may be omitted for options not requiring it. An extension prefixed with a \[aq]!\[aq] is critical (must be supported to be valid), otherwise it is noncritical (optional). -.PP +.P LDAP queries are easiest to explain by example. Here's a query that asks ldap.itd.umich.edu for information about the University of Michigan in the U.S.: -.PP +.P .nf ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US .fi -.PP +.P To just get its postal address attribute, request: -.PP +.P .nf ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress .fi -.PP +.P To ask a host.com at port 6666 for information about the person with common name (cn) "Babs Jensen" at University of Michigan, request: -.PP +.P .nf ldap://host.com:6666/o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen) .fi -.PP +.P .B "wais \- Wide Area Information Servers" -.PP +.P .RI wais:// hostport / database .br .RI wais:// hostport / database ? search .br .RI wais:// hostport / database / wtype / wpath -.PP +.P This scheme designates a WAIS database, search, or document (see .UR http://www.ietf.org\:/rfc\:/rfc1625.txt @@ -507,7 +507,7 @@ IETF RFC\ 1625 for more information on WAIS). Hostport is the hostname, optionally followed by a colon and port number (the default port number is 210). -.PP +.P The first form designates a WAIS database for searching. The second form designates a particular search of the WAIS database .IR database . @@ -517,9 +517,9 @@ database to be retrieved. is the WAIS designation of the type of the object and .I wpath is the WAIS document-id. -.PP +.P .B "other schemes" -.PP +.P There are many other URI schemes. Most tools that accept URIs support a set of internal URIs (e.g., Mozilla has the about: scheme for internal information, @@ -536,7 +536,7 @@ Not all tools support all schemes. .SS Character encoding URIs use a limited number of characters so that they can be typed in and used in a variety of situations. -.PP +.P The following characters are reserved, that is, they may appear in a URI but their use is limited to their reserved purpose (conflicting data must be escaped before forming the URI): @@ -546,7 +546,7 @@ URI but their use is limited to their reserved purpose ; / ? : @ & = + $ , .EE .in -.PP +.P Unreserved characters may be included in a URI. Unreserved characters include uppercase and lowercase Latin letters, @@ -558,7 +558,7 @@ limited set of punctuation marks and symbols: \- _ . ! \[ti] * ' ( ) .EE .in -.PP +.P All other characters must be escaped. An escaped octet is encoded as a character triplet, consisting of the percent character "%" followed by the two hexadecimal digits @@ -573,13 +573,13 @@ in query text; this practice isn't uniformly defined in the relevant RFCs (which recommend %20 instead) but any tool accepting URIs with query text should be prepared for them. A URI is always shown in its "escaped" form. -.PP +.P Unreserved characters can be escaped without changing the semantics of the URI, but this should not be done unless the URI is being used in a context that does not allow the unescaped character to appear. For example, "%7e" is sometimes used instead of "\[ti]" in an HTTP URL path, but the two are equivalent for an HTTP URL. -.PP +.P For URIs which must handle characters outside the US ASCII character set, the HTML 4.01 specification (section B.2) and IETF RFC\~3986 (last paragraph of section 2.5) @@ -609,7 +609,7 @@ This latter system, called the 'new' or 'logical' quoting system by is preferred practice in Great Britain and in various European languages. Older documents suggested inserting the prefix "URL:" just before the URI, but this form has never caught on. -.PP +.P The URI syntax was designed to be unambiguous. However, as URIs have become commonplace, traditional media (television, radio, newspapers, billboards, etc.) have increasingly @@ -644,9 +644,9 @@ be able to handle (directly or indirectly) all of the schemes described here, including the man: and info: schemes. Handling them by invoking some other program is fine and in fact encouraged. -.PP +.P Technically the fragment isn't part of the URI. -.PP +.P For information on how to embed URIs (including URLs) in a data format, see documentation on that format. HTML uses the format <A HREF="\fIuri\fP"> @@ -655,7 +655,7 @@ HTML uses the format <A HREF="\fIuri\fP"> Texinfo files use the format @uref{\fIuri\fP}. Man and mdoc have the recently added UR macro, or just include the URI in the text (viewers should be able to detect :// as part of a URI). -.PP +.P The GNOME and KDE desktop environments currently vary in the URIs they accept, in particular in their respective help browsers. To list man pages, GNOME uses <toc:man> while KDE uses <man:(index)>, and @@ -685,7 +685,7 @@ guarantee that a URL will not locate a different resource at some later point in time; such a guarantee can be obtained only from the person(s) controlling that namespace and the resource in question. -.PP +.P It is sometimes possible to construct a URL such that an attempt to perform a seemingly harmless operation, such as the retrieval of an entity associated with the resource, will in fact @@ -700,11 +700,11 @@ interpreted according to this other protocol, cause an unexpected operation. An example has been the use of a gopher URL to cause an unintended or impersonating message to be sent via a SMTP server. -.PP +.P Caution should be used when using any URL that specifies a port number other than the default for the protocol, especially when it is a number within the reserved space. -.PP +.P Care should be taken when a URI contains escaped delimiters for a given protocol (for example, CR and LF characters for telnet protocols) that these are not unescaped before transmission. @@ -712,7 +712,7 @@ This might violate the protocol, but avoids the potential for such characters to be used to simulate an extra operation or parameter in that protocol, which might lead to an unexpected and possibly harmful remote operation to be performed. -.PP +.P It is clearly unwise to use a URI that contains a password which is intended to be secret. In particular, the use of a password within @@ -739,10 +739,10 @@ without having to know the exact location of that documentation. Alternatively, a future version of the filesystem specification may specify file locations sufficiently so that the file: scheme will be able to locate documentation. -.PP +.P Many programs and file formats don't include a way to incorporate or implement links using URIs. -.PP +.P Many programs can't handle all of these different URI formats; there should be a standard mechanism to load an arbitrary URI that automatically detects the users' environment (e.g., text or graphics, @@ -755,7 +755,7 @@ tools) and invokes the right tool for any URI. .BR man2html (1), .BR mailaddr (7), .BR utf\-8 (7) -.PP +.P .UR http://www.ietf.org\:/rfc\:/rfc2255.txt IETF RFC\ 2255 .UE |