URI

Here are some of the most common schemes in use on Unix-like systemsthat are understood by many tools.Note that many tools using URIs also have internal schemes or specializedschemes; see those tools' documentation for information on those schemes. 

http - Web (HTTP) server

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 whatto 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 currentdirectory (with appropriate links) is generated and returned.An example is <http://lwn.net>.

A query can be given in the archaic "isindex" format, consisting of aword or phrase and not including an equal sign (=).A query can also be in the longer "GET" format, which has one or morequery entries of the formkey=valueseparated by the ampersand character (&).Note thatkeycan be repeated more than once, though it's up to the web serverand its application programs to determine if there's any meaning to that.There is an unfortunate interaction with HTML/XML/SGML andthe GET query format; when such URIs with more than one keyare embedded in SGML/XML documents (including HTML), the ampersand(&) has to be rewritten as &amp;.Note that not all queries use this format; larger formsmay be too long to store as a URI, so they use a differentinteraction mechanism (called POST) which does not include the data in the URI.See the Common Gateway Interface specification at<http://www.w3.org/CGI> for more information. 

ftp - File Transfer Protocol (FTP)

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 user name "anonymous" is supplied, andin that case many clients provide as the password the requestor'sInternet email address.An example is<ftp://ftp.is.co.za/rfc/rfc1808.txt>. 

gopher - Gopher server

The default gopher port is 70.gophertypeis a single-character field to denote theGopher type of the resource towhich the URL refers.The entire path may also be empty, inwhich case the delimiting "/" is also optional and the gophertypedefaults to "1".

selectoris the Gopher selector string. In the Gopher protocol,Gopher selector strings are a sequence of octets which may containany octets except 09 hexadecimal (US-ASCII HT or tab), 0A hexadecimal(US-ASCII character LF), and 0D (US-ASCII character CR). 

mailto - Email address

This is an email address, usually of the formname@hostname.Seemailaddr(7)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>. 

news - Newsgroup or News message

Anewsgroup-nameis a period-delimited hierarchical name, such as"comp.infosystems.www.misc".If <newsgroup-name> is "*" (as in <news:*>), it is used to referto "all available news groups".An example is <news:comp.lang.ada>.

Amessage-idcorresponds to the Message-ID ofIETF RFC 1036,without the enclosing "<"and ">"; it takes the formunique@full_domain_name.A message identifier may be distinguished from a news group name by thepresence of the "@" character. 

telnet - Telnet login

The Telnet URL scheme is used to designate interactive text services thatmay be accessed by the Telnet protocol. The final "/" character may be omitted.The default port is 23.An example is <telnet://melvyl.ucop.edu/>. 

file - Normal file

This represents a file or directory accessible locally.As a special case,hostcan be the string "localhost" or the emptystring; this is interpreted as `the machine from which the URL isbeing interpreted'.If the path is to a directory, the viewer should display thedirectory's contents with links to each containee;not all viewers currently do this.KDE supports generated files through the URL <file:/cgi-bin>.If the given file isn't found, browser writers may want to try to expandthe filename via filename globbing(seeglob(7)andglob(3)).

The second format (e.g., <file:/etc/passwd>)is a correct format for referring toa local file. However, older standards did not permit this format,and some programs don't recognize this as a URI.A more portable syntax is to use an empty string as the server name, e.g.,<file:///etc/passwd>; this form does the same thingand is easily recognized by pattern matchers and older programs as a URI.Note that if you really mean to say "start from the current location," don'tspecify 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>. 

man - Man page documentation

This refers to local online manual (man) reference pages.The command name can optionally be followed by a parenthesis and section number;seeman(7)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)>. 

info - Info page documentation

This scheme refers to online info reference pages (generated fromtexinfo files), a documentation format used by programs such as the GNU tools.This URI scheme is unique to Unix-like systems (such as Linux)and is not currently registered by the IETF.As of this writing, GNOME and KDE differ in their URI syntaxand do not accept the other's syntax.The first two formats are the GNOME format; in nodenames all spacesare written as underscores.The second two formats are the KDE format;spaces in nodenames must be written as spaces, even though thisis forbidden by the URI standards.It's hoped that in the future most tools will understand all of theseformats and will always accept underscores for spaces in nodenames.In both GNOME and KDE, if the form without the nodename is used thenodename 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>. 

whatis - Documentation search

This scheme searches the database of short (one-line) descriptions of commandsand returns a list of descriptions containing that string.Only complete word matches are returned.Seewhatis(1).This URI scheme is unique to Unix-like systems (such as Linux)and is not currently registered by the IETF. 

ghelp - GNOME help documentation

This loads GNOME help for the given application.Note that not much documentation currently exists in this format. 

ldap - Lightweight Directory Access Protocol

This scheme supports queries to theLightweight Directory Access Protocol (LDAP), a protocol for queryinga set of servers for hierarchically-organized information(such as people and computing resources).More information on the LDAP URL scheme is available inRFC 2255.The components of this URL are:

hostport

the LDAP server to query, written as a hostname optionally followed bya colon and the port number.The default LDAP port is TCP port 389. If empty, the client determines which the LDAP server to use.

dn

the LDAP Distinguished Name, which identifiesthe base object of the LDAP search (seeRFC 2253section 3).

attributes

a comma-separated list of attributes to be returned;see RFC 2251 section 4.1.5. If omitted, all attributes should be returned.

scope

specifies the scope of the search, which can be one of"base" (for a base object search), "one" (for a one-level search),or "sub" (for a subtree search). If scope is omitted, "base" is assumed.

filter

specifies the search filter (subset of entriesto return). If omitted, all entries should be returned.SeeRFC 2254section 4.

extensions

a comma-separated list of type=valuepairs, where the =value portion may be omitted for options notrequiring it. An extension prefixed with a '!' is critical(must be supported to be valid), otherwise it's non-critical (optional).

LDAP queries are easiest to explain by example.Here's a query that asks ldap.itd.umich.edu for information aboutthe University of Michigan in the U.S.:

ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US

To just get its postal address attribute, request:

ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress

To ask a host.com at port 6666 for information about the personwith common name (cn) "Babs Jensen" at University of Michigan, request:

ldap://host.com:6666/o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen)

wais - Wide Area Information Servers

This scheme designates a WAIS database, search, or document(seeIETF RFC 1625for more information on WAIS).Hostport is the hostname, optionally followed by a colon and port number(the default port number is 210).

The first form designates a WAIS database for searching.The second form designates a particular search of the WAIS databasedatabase.The third form designates a particular document within a WAISdatabase to be retrieved.wtypeis the WAIS designation of the type of the object andwpathis the WAIS document-id. 

other schemes

CHARACTER ENCODING

URIs use a limited number of characters so that they can betyped in and used in a variety of situations.

The following characters are reserved, that is, they may appear in aURI but their use is limited to their reserved purpose(conflicting data must be escaped before forming the URI):

   ; / ? : @ & = + $ ,

Unreserved characters may be included in a URI.Unreserved charactersinclude include upper and lower case English letters,decimal digits, and the followinglimited set of punctuation marks and symbols:

 - _ . ! ~ * ' ( )

All other characters must be escaped.An escaped octet is encoded as a character triplet, consisting of thepercent character "%" followed by the two hexadecimal digitsrepresenting the octet code (you can use upper or lower case lettersfor the hexadecimal digits). For example, a blank space must be escapedas "%20", a tab character as "%09", and the "&" as "%26".Because the percent "%" character always has the reserved purpose ofbeing the escape indicator, it must be escaped as "%25".It is common practice to escape space characters as the plus symbol (+)in query text; this practice isn't uniformly definedin the relevant RFCs (which recommend %20 instead) but any tool acceptingURIs with query text should be prepared for them.A URI is always shown in its "escaped" form.

Unreserved characters can be escaped without changing the semanticsof the URI, but this should not be done unless the URI is being usedin a context that does not allow the unescaped character to appear.For example, "%7e" is sometimes used instead of "~" in an http URLpath, but the two are equivalent for an http URL.

For URIs which must handle characters outside the US ASCII character set,the HTML 4.01 specification (section B.2) andIETF RFC 2718 (section 2.2.5) recommend the following approach:

1.

translate the character sequences into UTF-8 (IETF RFC 2279) - seeutf-8(7)- and then

2.

use the URI escaping mechanism, that is,use the %HH encoding for unsafe octets.

WRITING A URI

The URI syntax was designed to be unambiguous.However, as URIs have become commonplace, traditional media(television, radio, newspapers, billboards, etc.) have increasinglyused abbreviated URI references consisting ofonly the authority and path portions of the identified resource(e.g., <www.w3.org/Addressing>).Such references are primarilyintended for human interpretation rather than machine, with theassumption that context-based heuristics are sufficient to completethe URI (e.g., hostnames beginning with "www" are likely to havea URI prefix of "http://" and hostnames beginning with "ftp" likelyto have a prefix of "ftp://").Many client implementations heuristically resolve these references.Such heuristics maychange over time, particularly when new schemes are introduced.Since an abbreviated URI has the same syntax as a relative URL path,abbreviated URI references cannot be used where relative URIs arepermitted, and can only be used when there is no defined base(such as in dialog boxes).Don't use abbreviated URIs as hypertext links inside a document;use the standard format as described here. 

NOTES

Technically the fragment isn't part of the URI.

For information on how to embed URIs (including URLs) in a data format,see documentation on that format.HTML uses the format <A HREF="uri">text</A>.Texinfo files use the format @uref{uri}.Man and mdoc have the recently-added UR macro, or just include theURI in the text (viewers should be able to detect :// as part of a URI).

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)>, andto list info pages, GNOME uses <toc:info> while KDE uses <info:(dir)>(the author of this man page prefers the KDE approach here, though a moreregular format would be even better).In general, KDE uses <file:/cgi-bin/> as a prefix to a set of generatedfiles.KDE prefers documentation in HTML, accessed via the<file:/cgi-bin/helpindex>.GNOME prefers the ghelp scheme to store and find documentation.Neither browser handles file: references to directories at the timeof this writing, making it difficult to refer to an entire directory witha browsable URI.As noted above, these environments differ in how they handle the info: scheme,probably the most important variation.It is expected that GNOME and KDEwill converge to common URI formats, and a futureversion of this man page will describe the converged result.Efforts to aid this convergence are encouraged. 

SECURITY

A URI does not in itself pose a security threat.There is no general guarantee that a URL, which at one timelocated a given resource, will continue to do so. Nor is there anyguarantee that a URL will not locate a different resource at somelater point in time; such a guarantee can only beobtained from the person(s) controlling that namespace and theresource in question.

It is sometimes possible to construct a URL such that an attempt toperform a seemingly harmless operation, such as theretrieval of an entity associated with the resource, will in factcause a possibly damaging remote operation to occur. The unsafe URLis typically constructed by specifying a port number other than thatreserved for the network protocol in question. The clientunwittingly contacts a site that is in fact running a differentprotocol. The content of the URL contains instructions that, wheninterpreted according to this other protocol, cause an unexpectedoperation. An example has been the use of a gopher URL to cause anunintended or impersonating message to be sent via a SMTP server.

Caution should be used when using any URL that specifies a portnumber other than the default for the protocol, especially when it isa number within the reserved space.

Care should be taken when a URI contains escaped delimiters for agiven protocol (for example, CR and LF characters for telnetprotocols) that these are not unescaped before transmission. Thismight violate the protocol, but avoids the potential for suchcharacters to be used to simulate an extra operation or parameter inthat protocol, which might lead to an unexpected and possibly harmfulremote operation to be performed.

It is clearly unwise to use a URI that contains a password which isintended to be secret. In particular, the use of a password withinthe 'userinfo' component of a URI is strongly disrecommended exceptin those rare cases where the 'password' parameter is intended to be public. 

CONFORMING TO

IETF RFC 2396,HTML 4.0. 

BUGS

Documentation may be placed in a variety of locations, so therecurrently isn't a good URI scheme for general online documentationin arbitrary formats.References of the form<file:///usr/doc/ZZZ> don't work because different distributions andlocal installation requirements may place the files in differentdirectories(it may be in /usr/doc, or /usr/local/doc, or /usr/share, or somewhere else).Also, the directory ZZZ usually changes when a version changes(though filename globbing could partially overcome this).Finally, using the file: scheme doesn't easily support people who dynamicallyload documentation from the Internet (instead of loading the filesonto a local filesystem).A future URI scheme may be added (e.g., "userdoc:") to permitprograms to include cross-references to more detailed documentation withouthaving to know the exact location of that documentation.Alternatively, a future version of the filesystem specification mayspecify file locations sufficiently so that the file: scheme willbe able to locate documentation.

Many programs and file formats don't include a way to incorporateor implement links using URIs.

Many programs can't handle all of these different URI formats; thereshould be a standard mechanism to load an arbitrary URI that automaticallydetects the users' environment (e.g., text or graphics, desktop environment,local user preferences, and currently-executing tools) and invokes theright tool for any URI. 

AUTHOR

SEE ALSO

Index

NAME

SYNOPSIS

DESCRIPTION

USAGE

http - Web (HTTP) server

ftp - File Transfer Protocol (FTP)

gopher - Gopher server

mailto - Email address

news - Newsgroup or News message

telnet - Telnet login

file - Normal file

man - Man page documentation

info - Info page documentation

whatis - Documentation search

ghelp - GNOME help documentation

ldap - Lightweight Directory Access Protocol

wais - Wide Area Information Servers

other schemes

CHARACTER ENCODING

WRITING A URI

NOTES

SECURITY

CONFORMING TO

BUGS

AUTHOR

SEE ALSO