1 .\" (C) Copyright 1999-2000 David A. Wheeler (dwheeler@dwheeler.com)
3 .\" %%%LICENSE_START(VERBATIM)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
25 .\" Fragments of this document are directly derived from IETF standards.
26 .\" For those fragments which are directly derived from such standards,
27 .\" the following notice applies, which is the standard copyright and
28 .\" rights announcement of The Internet Society:
30 .\" Copyright (C) The Internet Society (1998). All Rights Reserved.
31 .\" This document and translations of it may be copied and furnished to
32 .\" others, and derivative works that comment on or otherwise explain it
33 .\" or assist in its implementation may be prepared, copied, published
34 .\" and distributed, in whole or in part, without restriction of any
35 .\" kind, provided that the above copyright notice and this paragraph are
36 .\" included on all such copies and derivative works. However, this
37 .\" document itself may not be modified in any way, such as by removing
38 .\" the copyright notice or references to the Internet Society or other
39 .\" Internet organizations, except as needed for the purpose of
40 .\" developing Internet standards in which case the procedures for
41 .\" copyrights defined in the Internet Standards process must be
42 .\" followed, or as required to translate it into languages other than English.
44 .\" Modified Fri Jul 25 23:00:00 1999 by David A. Wheeler (dwheeler@dwheeler.com)
45 .\" Modified Fri Aug 21 23:00:00 1999 by David A. Wheeler (dwheeler@dwheeler.com)
46 .\" Modified Tue Mar 14 2000 by David A. Wheeler (dwheeler@dwheeler.com)
48 .TH URI 7 2017-09-15 "Linux" "Linux Programmer's Manual"
50 uri, url, urn \- uniform resource identifier (URI), including a URL or URN
54 URI = [ absoluteURI | relativeURI ] [ "#" fragment ]
56 absoluteURI = scheme ":" ( hierarchical_part | opaque_part )
58 relativeURI = ( net_path | absolute_path | relative_path ) [ "?" query ]
60 scheme = "http" | "ftp" | "gopher" | "mailto" | "news" | "telnet" |
61 "file" | "man" | "info" | "whatis" | "ldap" | "wais" | \&...
63 hierarchical_part = ( net_path | absolute_path ) [ "?" query ]
65 net_path = "//" authority [ absolute_path ]
67 absolute_path = "/" path_segments
69 relative_path = relative_segment [ absolute_path ]
73 A Uniform Resource Identifier (URI) is a short string of characters
74 identifying an abstract or physical resource (for example, a web page).
75 A Uniform Resource Locator (URL) is a URI
76 that identifies a resource through its primary access
77 mechanism (e.g., its network "location"), rather than
78 by name or some other attribute of that resource.
79 A Uniform Resource Name (URN) is a URI
80 that must remain globally unique and persistent even when
81 the resource ceases to exist or becomes unavailable.
83 URIs are the standard way to name hypertext link destinations
84 for tools such as web browsers.
85 The string "http://www.kernel.org" is a URL (and thus it
87 Many people use the term URL loosely as a synonym for URI
88 (though technically URLs are a subset of URIs).
90 URIs can be absolute or relative.
91 An absolute identifier refers to a resource independent of
92 context, while a relative
93 identifier refers to a resource by describing the difference
94 from the current context.
95 Within a relative path reference, the complete path segments "." and
96 ".." have special meanings: "the current hierarchy level" and "the
97 level above this hierarchy level", respectively, just like they do in
99 A path segment which contains a colon
100 character can't be used as the first segment of a relative URI path
101 (e.g., "this:that"), because it would be mistaken for a scheme name;
102 precede such segments with ./ (e.g., "./this:that").
103 Note that descendants of MS-DOS (e.g., Microsoft Windows) replace
104 devicename colons with the vertical bar ("|") in URIs, so "C:" becomes "C|".
106 A fragment identifier, if included, refers to a particular named portion
107 (fragment) of a resource; text after a \(aq#\(aq identifies the fragment.
108 A URI beginning with \(aq#\(aq refers to that fragment in the current resource.
110 There are many different URI schemes, each with specific
111 additional rules and meanings, but they are intentionally made to be
112 as similar as possible.
113 For example, many URL schemes
114 permit the authority to be the following format, called here an
116 (square brackets show what's optional):
118 .IR "ip_server = " [ user " [ : " password " ] @ ] " host " [ : " port ]
120 This format allows you to optionally insert a username,
121 a user plus password, and/or a port number.
124 is the name of the host computer, either its name as determined by DNS
125 or an IP address (numbers separated by periods).
127 <http://fred:fredpassword@example.com:8080/>
128 logs into a web server on host example.com
129 as fred (using fredpassword) using port 8080.
130 Avoid including a password in a URI if possible because of the many
131 security risks of having a password written down.
132 If the URL supplies a username but no password, and the remote
133 server requests a password, the program interpreting the URL
134 should request one from the user.
136 Here are some of the most common schemes in use on UNIX-like systems
137 that are understood by many tools.
138 Note that many tools using URIs also have internal schemes or specialized
139 schemes; see those tools' documentation for information on those schemes.
141 .B "http \- Web (HTTP) server"
143 .RI http:// ip_server / path
145 .RI http:// ip_server / path ? query
147 This is a URL accessing a web (HTTP) server.
148 The default port is 80.
149 If the path refers to a directory, the web server will choose what
150 to return; usually if there is a file named "index.html" or "index.htm"
151 its content is returned, otherwise, a list of the files in the current
152 directory (with appropriate links) is generated and returned.
153 An example is <http://lwn.net>.
155 A query can be given in the archaic "isindex" format, consisting of a
156 word or phrase and not including an equal sign (=).
157 A query can also be in the longer "GET" format, which has one or more
158 query entries of the form
160 separated by the ampersand character (&).
163 can be repeated more than once, though it's up to the web server
164 and its application programs to determine if there's any meaning to that.
165 There is an unfortunate interaction with HTML/XML/SGML and
166 the GET query format; when such URIs with more than one key
167 are embedded in SGML/XML documents (including HTML), the ampersand
168 (&) has to be rewritten as &.
169 Note that not all queries use this format; larger forms
170 may be too long to store as a URI, so they use a different
171 interaction mechanism (called POST) which does
172 not include the data in the URI.
173 See the Common Gateway Interface specification at
174 .UR http://www.w3.org\:/CGI
176 for more information.
178 .B "ftp \- File Transfer Protocol (FTP)"
180 .RI ftp:// ip_server / path
182 This is a URL accessing a file through the file transfer protocol (FTP).
183 The default port (for control) is 21.
184 If no username is included, the username "anonymous" is supplied, and
185 in that case many clients provide as the password the requestor's
186 Internet email address.
188 <ftp://ftp.is.co.za/rfc/rfc1808.txt>.
190 .B "gopher \- Gopher server"
192 .RI gopher:// ip_server / "gophertype selector"
194 .RI gopher:// ip_server / "gophertype selector" %09 search
196 .RI gopher:// ip_server / "gophertype selector" %09 search %09 gopher+_string
199 The default gopher port is 70.
201 is a single-character field to denote the
202 Gopher type of the resource to
203 which the URL refers.
204 The entire path may also be empty, in
205 which case the delimiting "/" is also optional and the gophertype
209 is the Gopher selector string.
210 In the Gopher protocol,
211 Gopher selector strings are a sequence of octets which may contain
212 any octets except 09 hexadecimal (US-ASCII HT or tab), 0A hexadecimal
213 (US-ASCII character LF), and 0D (US-ASCII character CR).
215 .B "mailto \- Email address"
217 .RI mailto: email-address
219 This is an email address, usually of the form
220 .IR name @ hostname .
223 for more information on the correct format of an email address.
224 Note that any % character must be rewritten as %25.
225 An example is <mailto:dwheeler@dwheeler.com>.
227 .B "news \- Newsgroup or News message"
229 .RI news: newsgroup-name
235 is a period-delimited hierarchical name, such as
236 "comp.infosystems.www.misc".
237 If <newsgroup-name> is "*" (as in <news:*>), it is used to refer
238 to "all available news groups".
239 An example is <news:comp.lang.ada>.
243 corresponds to the Message-ID of
244 .UR http://www.ietf.org\:/rfc\:/rfc1036.txt
247 without the enclosing "<"
248 and ">"; it takes the form
249 .IR unique @ full_domain_name .
250 A message identifier may be distinguished from a news group name by the
251 presence of the "@" character.
253 .B "telnet \- Telnet login"
255 .RI telnet:// ip_server /
257 The Telnet URL scheme is used to designate interactive text services that
258 may be accessed by the Telnet protocol.
259 The final "/" character may be omitted.
260 The default port is 23.
261 An example is <telnet://melvyl.ucop.edu/>.
263 .B "file \- Normal file"
265 .RI file:// ip_server / path_segments
267 .RI file: path_segments
269 This represents a file or directory accessible locally.
272 can be the string "localhost" or the empty
273 string; this is interpreted as "the machine from which the URL is
275 If the path is to a directory, the viewer should display the
276 directory's contents with links to each containee;
277 not all viewers currently do this.
278 KDE supports generated files through the URL <file:/cgi-bin>.
279 If the given file isn't found, browser writers may want to try to expand
280 the filename via filename globbing
286 The second format (e.g., <file:/etc/passwd>)
287 is a correct format for referring to
289 However, older standards did not permit this format,
290 and some programs don't recognize this as a URI.
291 A more portable syntax is to use an empty string as the server name,
293 <file:///etc/passwd>; this form does the same thing
294 and is easily recognized by pattern matchers and older programs as a URI.
295 Note that if you really mean to say "start from the current location," don't
296 specify the scheme at all; use a relative address like <../test.txt>,
297 which has the side-effect of being scheme-independent.
298 An example of this scheme is <file:///etc/passwd>.
300 .B "man \- Man page documentation"
302 .RI man: command-name
304 .RI man: command-name ( section )
306 This refers to local online manual (man) reference pages.
307 The command name can optionally be followed by a
308 parenthesis and section number; see
310 for more information on the meaning of the section numbers.
311 This URI scheme is unique to UNIX-like systems (such as Linux)
312 and is not currently registered by the IETF.
313 An example is <man:ls(1)>.
315 .B "info \- Info page documentation"
317 .RI info: virtual-filename
319 .RI info: virtual-filename # nodename
321 .RI info:( virtual-filename )
323 .RI info:( virtual-filename ) nodename
325 This scheme refers to online info reference pages (generated from
327 a documentation format used by programs such as the GNU tools.
328 This URI scheme is unique to UNIX-like systems (such as Linux)
329 and is not currently registered by the IETF.
330 As of this writing, GNOME and KDE differ in their URI syntax
331 and do not accept the other's syntax.
332 The first two formats are the GNOME format; in nodenames all spaces
333 are written as underscores.
334 The second two formats are the KDE format;
335 spaces in nodenames must be written as spaces, even though this
336 is forbidden by the URI standards.
337 It's hoped that in the future most tools will understand all of these
338 formats and will always accept underscores for spaces in nodenames.
339 In both GNOME and KDE, if the form without the nodename is used the
340 nodename is assumed to be "Top".
341 Examples of the GNOME format are <info:gcc> and <info:gcc#G++_and_GCC>.
342 Examples of the KDE format are <info:(gcc)> and <info:(gcc)G++ and GCC>.
344 .B "whatis \- Documentation search"
348 This scheme searches the database of short (one-line) descriptions of
349 commands and returns a list of descriptions containing that string.
350 Only complete word matches are returned.
353 This URI scheme is unique to UNIX-like systems (such as Linux)
354 and is not currently registered by the IETF.
356 .B "ghelp \- GNOME help documentation"
358 .RI ghelp: name-of-application
360 This loads GNOME help for the given application.
361 Note that not much documentation currently exists in this format.
363 .B "ldap \- Lightweight Directory Access Protocol"
367 .RI ldap:// hostport /
369 .RI ldap:// hostport / dn
371 .RI ldap:// hostport / dn ? attributes
373 .RI ldap:// hostport / dn ? attributes ? scope
375 .RI ldap:// hostport / dn ? attributes ? scope ? filter
377 .RI ldap:// hostport / dn ? attributes ? scope ? filter ? extensions
379 This scheme supports queries to the
380 Lightweight Directory Access Protocol (LDAP), a protocol for querying
381 a set of servers for hierarchically organized information
382 (such as people and computing resources).
384 .UR http://www.ietf.org\:/rfc\:/rfc2255.txt
387 for more information on the LDAP URL scheme.
388 The components of this URL are:
390 the LDAP server to query, written as a hostname optionally followed by
391 a colon and the port number.
392 The default LDAP port is TCP port 389.
393 If empty, the client determines which the LDAP server to use.
395 the LDAP Distinguished Name, which identifies
396 the base object of the LDAP search (see
397 .UR http://www.ietf.org\:/rfc\:/rfc2253.txt
402 a comma-separated list of attributes to be returned;
403 see RFC\ 2251 section 4.1.5.
404 If omitted, all attributes should be returned.
406 specifies the scope of the search, which can be one of
407 "base" (for a base object search), "one" (for a one-level search),
408 or "sub" (for a subtree search).
409 If scope is omitted, "base" is assumed.
411 specifies the search filter (subset of entries
413 If omitted, all entries should be returned.
415 .UR http://www.ietf.org\:/rfc\:/rfc2254.txt
420 a comma-separated list of type=value
421 pairs, where the =value portion may be omitted for options not
423 An extension prefixed with a \(aq!\(aq is critical
424 (must be supported to be valid), otherwise it is noncritical (optional).
426 LDAP queries are easiest to explain by example.
427 Here's a query that asks ldap.itd.umich.edu for information about
428 the University of Michigan in the U.S.:
431 ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US
434 To just get its postal address attribute, request:
437 ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress
440 To ask a host.com at port 6666 for information about the person
441 with common name (cn) "Babs Jensen" at University of Michigan, request:
444 ldap://host.com:6666/o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen)
447 .B "wais \- Wide Area Information Servers"
449 .RI wais:// hostport / database
451 .RI wais:// hostport / database ? search
453 .RI wais:// hostport / database / wtype / wpath
455 This scheme designates a WAIS database, search, or document
457 .UR http://www.ietf.org\:/rfc\:/rfc1625.txt
460 for more information on WAIS).
461 Hostport is the hostname, optionally followed by a colon and port number
462 (the default port number is 210).
464 The first form designates a WAIS database for searching.
465 The second form designates a particular search of the WAIS database
467 The third form designates a particular document within a WAIS
468 database to be retrieved.
470 is the WAIS designation of the type of the object and
472 is the WAIS document-id.
476 There are many other URI schemes.
477 Most tools that accept URIs support a set of internal URIs
478 (e.g., Mozilla has the about: scheme for internal information,
479 and the GNOME help browser has the toc: scheme for various starting
481 There are many schemes that have been defined but are not as widely
482 used at the current time
484 The nntp: scheme is deprecated in favor of the news: scheme.
485 URNs are to be supported by the urn: scheme, with a hierarchical name space
486 (e.g., urn:ietf:... would identify IETF documents); at this time
487 URNs are not widely implemented.
488 Not all tools support all schemes.
489 .SS Character encoding
491 URIs use a limited number of characters so that they can be
492 typed in and used in a variety of situations.
494 The following characters are reserved, that is, they may appear in a
495 URI but their use is limited to their reserved purpose
496 (conflicting data must be escaped before forming the URI):
500 Unreserved characters may be included in a URI.
501 Unreserved characters
502 include uppercase and lowercase English letters,
503 decimal digits, and the following
504 limited set of punctuation marks and symbols:
508 All other characters must be escaped.
509 An escaped octet is encoded as a character triplet, consisting of the
510 percent character "%" followed by the two hexadecimal digits
511 representing the octet code (you can use uppercase or lowercase letters
512 for the hexadecimal digits).
513 For example, a blank space must be escaped
514 as "%20", a tab character as "%09", and the "&" as "%26".
515 Because the percent "%" character always has the reserved purpose of
516 being the escape indicator, it must be escaped as "%25".
517 It is common practice to escape space characters as the plus symbol (+)
518 in query text; this practice isn't uniformly defined
519 in the relevant RFCs (which recommend %20 instead) but any tool accepting
520 URIs with query text should be prepared for them.
521 A URI is always shown in its "escaped" form.
523 Unreserved characters can be escaped without changing the semantics
524 of the URI, but this should not be done unless the URI is being used
525 in a context that does not allow the unescaped character to appear.
526 For example, "%7e" is sometimes used instead of "~" in an HTTP URL
527 path, but the two are equivalent for an HTTP URL.
529 For URIs which must handle characters outside the US ASCII character set,
530 the HTML 4.01 specification (section B.2) and
531 IETF RFC\ 2718 (section 2.2.5) recommend the following approach:
533 translate the character sequences into UTF-8 (IETF RFC\ 2279)\(emsee
537 use the URI escaping mechanism, that is,
538 use the %HH encoding for unsafe octets.
540 When written, URIs should be placed inside double quotes
541 (e.g., "http://www.kernel.org"),
542 enclosed in angle brackets (e.g., <http://lwn.net>),
543 or placed on a line by themselves.
544 A warning for those who use double-quotes:
546 move extraneous punctuation (such as the period ending a sentence or the
548 inside a URI, since this will change the value of the URI.
549 Instead, use angle brackets instead, or
550 switch to a quoting system that never includes extraneous characters
551 inside quotation marks.
552 This latter system, called the 'new' or 'logical' quoting system by
553 "Hart's Rules" and the "Oxford Dictionary for Writers and Editors",
554 is preferred practice in Great Britain and hackers worldwide
556 Jargon File's section on Hacker Writing Style,
557 .UR http://www.fwi.uva.nl\:/~mes\:/jargon\:/h\:/HackerWritingStyle.html
559 for more information).
560 Older documents suggested inserting the prefix "URL:"
561 just before the URI, but this form has never caught on.
563 The URI syntax was designed to be unambiguous.
564 However, as URIs have become commonplace, traditional media
565 (television, radio, newspapers, billboards, etc.) have increasingly
566 used abbreviated URI references consisting of
567 only the authority and path portions of the identified resource
568 (e.g., <www.w3.org/Addressing>).
569 Such references are primarily
570 intended for human interpretation rather than machine, with the
571 assumption that context-based heuristics are sufficient to complete
572 the URI (e.g., hostnames beginning with "www" are likely to have
573 a URI prefix of "http://" and hostnames beginning with "ftp" likely
574 to have a prefix of "ftp://").
575 Many client implementations heuristically resolve these references.
577 change over time, particularly when new schemes are introduced.
578 Since an abbreviated URI has the same syntax as a relative URL path,
579 abbreviated URI references cannot be used where relative URIs are
580 permitted, and can be used only when there is no defined base
581 (such as in dialog boxes).
582 Don't use abbreviated URIs as hypertext links inside a document;
583 use the standard format as described here.
586 .UR http://www.ietf.org\:/rfc\:/rfc2396.txt
589 .UR http://www.w3.org\:/TR\:/REC\-html40
593 Any tool accepting URIs (e.g., a web browser) on a Linux system should
594 be able to handle (directly or indirectly) all of the
595 schemes described here, including the man: and info: schemes.
596 Handling them by invoking some other program is
597 fine and in fact encouraged.
599 Technically the fragment isn't part of the URI.
601 For information on how to embed URIs (including URLs) in a data format,
602 see documentation on that format.
603 HTML uses the format <A HREF="\fIuri\fP">
606 Texinfo files use the format @uref{\fIuri\fP}.
607 Man and mdoc have the recently added UR macro, or just include the
608 URI in the text (viewers should be able to detect :// as part of a URI).
610 The GNOME and KDE desktop environments currently vary in the URIs
611 they accept, in particular in their respective help browsers.
612 To list man pages, GNOME uses <toc:man> while KDE uses <man:(index)>, and
613 to list info pages, GNOME uses <toc:info> while KDE uses <info:(dir)>
614 (the author of this man page prefers the KDE approach here, though a more
615 regular format would be even better).
616 In general, KDE uses <file:/cgi-bin/> as a prefix to a set of generated
618 KDE prefers documentation in HTML, accessed via the
619 <file:/cgi-bin/helpindex>.
620 GNOME prefers the ghelp scheme to store and find documentation.
621 Neither browser handles file: references to directories at the time
622 of this writing, making it difficult to refer to an entire directory with
624 As noted above, these environments differ in how they handle the
625 info: scheme, probably the most important variation.
626 It is expected that GNOME and KDE
627 will converge to common URI formats, and a future
628 version of this man page will describe the converged result.
629 Efforts to aid this convergence are encouraged.
632 A URI does not in itself pose a security threat.
633 There is no general guarantee that a URL, which at one time
634 located a given resource, will continue to do so.
636 guarantee that a URL will not locate a different resource at some
637 later point in time; such a guarantee can be
638 obtained only from the person(s) controlling that namespace and the
639 resource in question.
641 It is sometimes possible to construct a URL such that an attempt to
642 perform a seemingly harmless operation, such as the
643 retrieval of an entity associated with the resource, will in fact
644 cause a possibly damaging remote operation to occur.
646 is typically constructed by specifying a port number other than that
647 reserved for the network protocol in question.
648 The client unwittingly contacts a site that is in fact
649 running a different protocol.
650 The content of the URL contains instructions that, when
651 interpreted according to this other protocol, cause an unexpected
653 An example has been the use of a gopher URL to cause an
654 unintended or impersonating message to be sent via a SMTP server.
656 Caution should be used when using any URL that specifies a port
657 number other than the default for the protocol, especially when it is
658 a number within the reserved space.
660 Care should be taken when a URI contains escaped delimiters for a
661 given protocol (for example, CR and LF characters for telnet
662 protocols) that these are not unescaped before transmission.
663 This might violate the protocol, but avoids the potential for such
664 characters to be used to simulate an extra operation or parameter in
665 that protocol, which might lead to an unexpected and possibly harmful
666 remote operation to be performed.
668 It is clearly unwise to use a URI that contains a password which is
669 intended to be secret.
670 In particular, the use of a password within
671 the "userinfo" component of a URI is strongly recommended against except
672 in those rare cases where the "password" parameter is intended to be public.
675 Documentation may be placed in a variety of locations, so there
676 currently isn't a good URI scheme for general online documentation
677 in arbitrary formats.
678 References of the form
679 <file:///usr/doc/ZZZ> don't work because different distributions and
680 local installation requirements may place the files in different
682 (it may be in /usr/doc, or /usr/local/doc, or /usr/share,
684 Also, the directory ZZZ usually changes when a version changes
685 (though filename globbing could partially overcome this).
686 Finally, using the file: scheme doesn't easily support people
687 who dynamically load documentation from the Internet (instead of
688 loading the files onto a local filesystem).
689 A future URI scheme may be added (e.g., "userdoc:") to permit
690 programs to include cross-references to more detailed documentation
691 without having to know the exact location of that documentation.
692 Alternatively, a future version of the filesystem specification may
693 specify file locations sufficiently so that the file: scheme will
694 be able to locate documentation.
696 Many programs and file formats don't include a way to incorporate
697 or implement links using URIs.
699 Many programs can't handle all of these different URI formats; there
700 should be a standard mechanism to load an arbitrary URI that automatically
701 detects the users' environment (e.g., text or graphics,
702 desktop environment, local user preferences, and currently executing
703 tools) and invokes the right tool for any URI.
705 .\" David A. Wheeler (dwheeler@dwheeler.com) wrote this man page.
712 .UR http://www.ietf.org\:/rfc\:/rfc2255.txt