2 .\" (C) Copyright 1999-2000 David A. Wheeler (dwheeler@dwheeler.com)
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.
24 .\" Fragments of this document are directly derived from IETF standards.
25 .\" For those fragments which are directly derived from such standards,
26 .\" the following notice applies, which is the standard copyright and
27 .\" rights announcement of The Internet Society:
29 .\" Copyright (C) The Internet Society (1998). All Rights Reserved.
30 .\" This document and translations of it may be copied and furnished to
31 .\" others, and derivative works that comment on or otherwise explain it
32 .\" or assist in its implementation may be prepared, copied, published
33 .\" and distributed, in whole or in part, without restriction of any
34 .\" kind, provided that the above copyright notice and this paragraph are
35 .\" included on all such copies and derivative works. However, this
36 .\" document itself may not be modified in any way, such as by removing
37 .\" the copyright notice or references to the Internet Society or other
38 .\" Internet organizations, except as needed for the purpose of
39 .\" developing Internet standards in which case the procedures for
40 .\" copyrights defined in the Internet Standards process must be
41 .\" followed, or as required to translate it into languages other than English.
43 .\" Modified Fri Jul 25 23:00:00 1999 by David A. Wheeler (dwheeler@dwheeler.com)
44 .\" Modified Fri Aug 21 23:00:00 1999 by David A. Wheeler (dwheeler@dwheeler.com)
45 .\" Modified Tue Mar 14 2000 by David A. Wheeler (dwheeler@dwheeler.com)
47 .TH URI 7 2000-03-14 "Linux" "Linux Programmer's Manual"
49 uri, url, urn \- uniform resource identifier (URI), including a URL or URN
53 URI = [ absoluteURI | relativeURI ] [ "#" fragment ]
55 absoluteURI = scheme ":" ( hierarchical_part | opaque_part )
57 relativeURI = ( net_path | absolute_path | relative_path ) [ "?" query ]
59 scheme = "http" | "ftp" | "gopher" | "mailto" | "news" | "telnet" |
60 "file" | "man" | "info" | "whatis" | "ldap" | "wais" | \&...
62 hierarchical_part = ( net_path | absolute_path ) [ "?" query ]
64 net_path = "//" authority [ absolute_path ]
66 absolute_path = "/" path_segments
68 relative_path = relative_segment [ absolute_path ]
72 A Uniform Resource Identifier (URI) is a short string of characters
73 identifying an abstract or physical resource (for example, a web page).
74 A Uniform Resource Locator (URL) is a URI
75 that identifies a resource through its primary access
76 mechanism (e.g., its network "location"), rather than
77 by name or some other attribute of that resource.
78 A Uniform Resource Name (URN) is a URI
79 that must remain globally unique and persistent even when
80 the resource ceases to exist or becomes unavailable.
82 URIs are the standard way to name hypertext link destinations
83 for tools such as web browsers.
84 The string "http://www.kernelnotes.org" is a URL (and thus it
86 Many people use the term URL loosely as a synonym for URI
87 (though technically URLs are a subset of URIs).
89 URIs can be absolute or relative.
90 An absolute identifier refers to a resource independent of
91 context, while a relative
92 identifier refers to a resource by describing the difference
93 from the current context.
94 Within a relative path reference, the complete path segments "." and
95 ".." have special meanings: "the current hierarchy level" and "the
96 level above this hierarchy level", respectively, just like they do in
98 A path segment which contains a colon
99 character can't be used as the first segment of a relative URI path
100 (e.g., "this:that"), because it would be mistaken for a scheme name;
101 precede such segments with ./ (e.g., "./this:that").
102 Note that descendants of MS-DOS (e.g., Microsoft Windows) replace
103 devicename colons with the vertical bar ("|") in URIs, so "C:" becomes "C|".
105 A fragment identifier, if included, refers to a particular named portion
106 (fragment) of a resource; text after a \(aq#\(aq identifies the fragment.
107 A URI beginning with \(aq#\(aq refers to that fragment in the current resource.
109 There are many different URI schemes, each with specific
110 additional rules and meanings, but they are intentionally made to be
111 as similar as possible.
112 For example, many URL schemes
113 permit the authority to be the following format, called here an
115 (square brackets show what's optional):
117 .IR "ip_server = " [ user " [ : " password " ] @ ] " host " [ : " port ]
119 This format allows you to optionally insert a username,
120 a user plus password, and/or a port number.
123 is the name of the host computer, either its name as determined by DNS
124 or an IP address (numbers separated by periods).
126 <http://fred:fredpassword@xyz.com:8080/>
127 logs into a web server on host xyz.com
128 as fred (using fredpassword) using port 8080.
129 Avoid including a password in a URI if possible because of the many
130 security risks of having a password written down.
131 If the URL supplies a username but no password, and the remote
132 server requests a password, the program interpreting the URL
133 should request one from the user.
135 Here are some of the most common schemes in use on UNIX-like systems
136 that are understood by many tools.
137 Note that many tools using URIs also have internal schemes or specialized
138 schemes; see those tools' documentation for information on those schemes.
140 .B "http \- Web (HTTP) server"
142 .RI http:// ip_server / path
144 .RI http:// ip_server / path ? query
146 This is a URL accessing a web (HTTP) server.
147 The default port is 80.
148 If the path refers to a directory, the web server will choose what
149 to return; usually if there is a file named "index.html" or "index.htm"
150 its content is returned, otherwise, a list of the files in the current
151 directory (with appropriate links) is generated and returned.
152 An example is <http://lwn.net>.
154 A query can be given in the archaic "isindex" format, consisting of a
155 word or phrase and not including an equal sign (=).
156 A query can also be in the longer "GET" format, which has one or more
157 query entries of the form
159 separated by the ampersand character (&).
162 can be repeated more than once, though it's up to the web server
163 and its application programs to determine if there's any meaning to that.
164 There is an unfortunate interaction with HTML/XML/SGML and
165 the GET query format; when such URIs with more than one key
166 are embedded in SGML/XML documents (including HTML), the ampersand
167 (&) has to be rewritten as &.
168 Note that not all queries use this format; larger forms
169 may be too long to store as a URI, so they use a different
170 interaction mechanism (called POST) which does
171 not include the data in the URI.
172 See the Common Gateway Interface specification at
173 <http://www.w3.org/CGI> for more information.
175 .B "ftp \- File Transfer Protocol (FTP)"
177 .RI ftp:// ip_server / path
179 This is a URL accessing a file through the file transfer protocol (FTP).
180 The default port (for control) is 21.
181 If no username is included, the username "anonymous" is supplied, and
182 in that case many clients provide as the password the requestor's
183 Internet email address.
185 <ftp://ftp.is.co.za/rfc/rfc1808.txt>.
187 .B "gopher \- Gopher server"
189 .RI gopher:// ip_server / "gophertype selector"
191 .RI gopher:// ip_server / "gophertype selector" %09 search
193 .RI gopher:// ip_server / "gophertype selector" %09 search %09 gopher+_string
196 The default gopher port is 70.
198 is a single-character field to denote the
199 Gopher type of the resource to
200 which the URL refers.
201 The entire path may also be empty, in
202 which case the delimiting "/" is also optional and the gophertype
206 is the Gopher selector string.
207 In the Gopher protocol,
208 Gopher selector strings are a sequence of octets which may contain
209 any octets except 09 hexadecimal (US-ASCII HT or tab), 0A hexadecimal
210 (US-ASCII character LF), and 0D (US-ASCII character CR).
212 .B "mailto \- Email address"
214 .RI mailto: email-address
216 This is an email address, usually of the form
217 .IR name @ hostname .
220 for more information on the correct format of an email address.
221 Note that any % character must be rewritten as %25.
222 An example is <mailto:dwheeler@dwheeler.com>.
224 .B "news \- Newsgroup or News message"
226 .RI news: newsgroup-name
232 is a period-delimited hierarchical name, such as
233 "comp.infosystems.www.misc".
234 If <newsgroup-name> is "*" (as in <news:*>), it is used to refer
235 to "all available news groups".
236 An example is <news:comp.lang.ada>.
240 corresponds to the Message-ID of
241 .UR http://www.ietf.org/rfc/rfc1036.txt
244 without the enclosing "<"
245 and ">"; it takes the form
246 .IR unique @ full_domain_name .
247 A message identifier may be distinguished from a news group name by the
248 presence of the "@" character.
250 .B "telnet \- Telnet login"
252 .RI telnet:// ip_server /
254 The Telnet URL scheme is used to designate interactive text services that
255 may be accessed by the Telnet protocol.
256 The final "/" character may be omitted.
257 The default port is 23.
258 An example is <telnet://melvyl.ucop.edu/>.
260 .B "file \- Normal file"
262 .RI file:// ip_server / path_segments
264 .RI file: path_segments
266 This represents a file or directory accessible locally.
269 can be the string "localhost" or the empty
270 string; this is interpreted as "the machine from which the URL is
272 If the path is to a directory, the viewer should display the
273 directory's contents with links to each containee;
274 not all viewers currently do this.
275 KDE supports generated files through the URL <file:/cgi-bin>.
276 If the given file isn't found, browser writers may want to try to expand
277 the filename via filename globbing
283 The second format (e.g., <file:/etc/passwd>)
284 is a correct format for referring to
286 However, older standards did not permit this format,
287 and some programs don't recognize this as a URI.
288 A more portable syntax is to use an empty string as the server name,
290 <file:///etc/passwd>; this form does the same thing
291 and is easily recognized by pattern matchers and older programs as a URI.
292 Note that if you really mean to say "start from the current location," don't
293 specify the scheme at all; use a relative address like <../test.txt>,
294 which has the side-effect of being scheme-independent.
295 An example of this scheme is <file:///etc/passwd>.
297 .B "man \- Man page documentation"
299 .RI man: command-name
301 .RI man: command-name ( section )
303 This refers to local online manual (man) reference pages.
304 The command name can optionally be followed by a
305 parenthesis and section number; see
307 for more information on the meaning of the section numbers.
308 This URI scheme is unique to UNIX-like systems (such as Linux)
309 and is not currently registered by the IETF.
310 An example is <man:ls(1)>.
312 .B "info \- Info page documentation"
314 .RI info: virtual-filename
316 .RI info: virtual-filename # nodename
318 .RI info:( virtual-filename )
320 .RI info:( virtual-filename ) nodename
322 This scheme refers to online info reference pages (generated from
324 a documentation format used by programs such as the GNU tools.
325 This URI scheme is unique to UNIX-like systems (such as Linux)
326 and is not currently registered by the IETF.
327 As of this writing, GNOME and KDE differ in their URI syntax
328 and do not accept the other's syntax.
329 The first two formats are the GNOME format; in nodenames all spaces
330 are written as underscores.
331 The second two formats are the KDE format;
332 spaces in nodenames must be written as spaces, even though this
333 is forbidden by the URI standards.
334 It's hoped that in the future most tools will understand all of these
335 formats and will always accept underscores for spaces in nodenames.
336 In both GNOME and KDE, if the form without the nodename is used the
337 nodename is assumed to be "Top".
338 Examples of the GNOME format are <info:gcc> and <info:gcc#G++_and_GCC>.
339 Examples of the KDE format are <info:(gcc)> and <info:(gcc)G++ and GCC>.
341 .B "whatis \- Documentation search"
345 This scheme searches the database of short (one-line) descriptions of
346 commands and returns a list of descriptions containing that string.
347 Only complete word matches are returned.
350 This URI scheme is unique to UNIX-like systems (such as Linux)
351 and is not currently registered by the IETF.
353 .B "ghelp \- GNOME help documentation"
355 .RI ghelp: name-of-application
357 This loads GNOME help for the given application.
358 Note that not much documentation currently exists in this format.
360 .B "ldap \- Lightweight Directory Access Protocol"
364 .RI ldap:// hostport /
366 .RI ldap:// hostport / dn
368 .RI ldap:// hostport / dn ? attributes
370 .RI ldap:// hostport / dn ? attributes ? scope
372 .RI ldap:// hostport / dn ? attributes ? scope ? filter
374 .RI ldap:// hostport / dn ? attributes ? scope ? filter ? extensions
376 This scheme supports queries to the
377 Lightweight Directory Access Protocol (LDAP), a protocol for querying
378 a set of servers for hierarchically organized information
379 (such as people and computing resources).
380 More information on the LDAP URL scheme is available in
381 .UR http://www.ietf.org/rfc/rfc2255.txt
384 The components of this URL are:
386 the LDAP server to query, written as a hostname optionally followed by
387 a colon and the port number.
388 The default LDAP port is TCP port 389.
389 If empty, the client determines which the LDAP server to use.
391 the LDAP Distinguished Name, which identifies
392 the base object of the LDAP search (see
393 .UR http://www.ietf.org/rfc/rfc2253.txt
398 a comma-separated list of attributes to be returned;
399 see RFC\ 2251 section 4.1.5.
400 If omitted, all attributes should be returned.
402 specifies the scope of the search, which can be one of
403 "base" (for a base object search), "one" (for a one-level search),
404 or "sub" (for a subtree search).
405 If scope is omitted, "base" is assumed.
407 specifies the search filter (subset of entries
409 If omitted, all entries should be returned.
411 .UR http://www.ietf.org/rfc/rfc2254.txt
416 a comma-separated list of type=value
417 pairs, where the =value portion may be omitted for options not
419 An extension prefixed with a \(aq!\(aq is critical
420 (must be supported to be valid), otherwise it is noncritical (optional).
422 LDAP queries are easiest to explain by example.
423 Here's a query that asks ldap.itd.umich.edu for information about
424 the University of Michigan in the U.S.:
427 ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US
430 To just get its postal address attribute, request:
433 ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress
436 To ask a host.com at port 6666 for information about the person
437 with common name (cn) "Babs Jensen" at University of Michigan, request:
440 ldap://host.com:6666/o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen)
443 .B "wais \- Wide Area Information Servers"
445 .RI wais:// hostport / database
447 .RI wais:// hostport / database ? search
449 .RI wais:// hostport / database / wtype / wpath
451 This scheme designates a WAIS database, search, or document
453 .UR http://www.ietf.org/rfc/rfc1625.txt
456 for more information on WAIS).
457 Hostport is the hostname, optionally followed by a colon and port number
458 (the default port number is 210).
460 The first form designates a WAIS database for searching.
461 The second form designates a particular search of the WAIS database
463 The third form designates a particular document within a WAIS
464 database to be retrieved.
466 is the WAIS designation of the type of the object and
468 is the WAIS document-id.
472 There are many other URI schemes.
473 Most tools that accept URIs support a set of internal URIs
474 (e.g., Mozilla has the about: scheme for internal information,
475 and the GNOME help browser has the toc: scheme for various starting
477 There are many schemes that have been defined but are not as widely
478 used at the current time
480 The nntp: scheme is deprecated in favor of the news: scheme.
481 URNs are to be supported by the urn: scheme, with a hierarchical name space
482 (e.g., urn:ietf:... would identify IETF documents); at this time
483 URNs are not widely implemented.
484 Not all tools support all schemes.
485 .SS "Character Encoding"
487 URIs use a limited number of characters so that they can be
488 typed in and used in a variety of situations.
490 The following characters are reserved, that is, they may appear in a
491 URI but their use is limited to their reserved purpose
492 (conflicting data must be escaped before forming the URI):
496 Unreserved characters may be included in a URI.
497 Unreserved characters
498 include upper and lower case English letters,
499 decimal digits, and the following
500 limited set of punctuation marks and symbols:
504 All other characters must be escaped.
505 An escaped octet is encoded as a character triplet, consisting of the
506 percent character "%" followed by the two hexadecimal digits
507 representing the octet code (you can use upper or lower case letters
508 for the hexadecimal digits).
509 For example, a blank space must be escaped
510 as "%20", a tab character as "%09", and the "&" as "%26".
511 Because the percent "%" character always has the reserved purpose of
512 being the escape indicator, it must be escaped as "%25".
513 It is common practice to escape space characters as the plus symbol (+)
514 in query text; this practice isn't uniformly defined
515 in the relevant RFCs (which recommend %20 instead) but any tool accepting
516 URIs with query text should be prepared for them.
517 A URI is always shown in its "escaped" form.
519 Unreserved characters can be escaped without changing the semantics
520 of the URI, but this should not be done unless the URI is being used
521 in a context that does not allow the unescaped character to appear.
522 For example, "%7e" is sometimes used instead of "~" in an HTTP URL
523 path, but the two are equivalent for an HTTP URL.
525 For URIs which must handle characters outside the US ASCII character set,
526 the HTML 4.01 specification (section B.2) and
527 IETF RFC\ 2718 (section 2.2.5) recommend the following approach:
529 translate the character sequences into UTF-8 (IETF RFC\ 2279) \(em see
533 use the URI escaping mechanism, that is,
534 use the %HH encoding for unsafe octets.
536 When written, URIs should be placed inside double quotes
537 (e.g., "http://www.kernelnotes.org"),
538 enclosed in angle brackets (e.g., <http://lwn.net>),
539 or placed on a line by themselves.
540 A warning for those who use double-quotes:
542 move extraneous punctuation (such as the period ending a sentence or the
544 inside a URI, since this will change the value of the URI.
545 Instead, use angle brackets instead, or
546 switch to a quoting system that never includes extraneous characters
547 inside quotation marks.
548 This latter system, called the 'new' or 'logical' quoting system by
549 "Hart's Rules" and the "Oxford Dictionary for Writers and Editors",
550 is preferred practice in Great Britain and hackers worldwide
552 Jargon File's section on Hacker Writing Style,
553 .IR http://www.fwi.uva.nl/~mes/jargon/h/HackerWritingStyle.html ,
554 for more information).
555 Older documents suggested inserting the prefix "URL:"
556 just before the URI, but this form has never caught on.
558 The URI syntax was designed to be unambiguous.
559 However, as URIs have become commonplace, traditional media
560 (television, radio, newspapers, billboards, etc.) have increasingly
561 used abbreviated URI references consisting of
562 only the authority and path portions of the identified resource
563 (e.g., <www.w3.org/Addressing>).
564 Such references are primarily
565 intended for human interpretation rather than machine, with the
566 assumption that context-based heuristics are sufficient to complete
567 the URI (e.g., hostnames beginning with "www" are likely to have
568 a URI prefix of "http://" and hostnames beginning with "ftp" likely
569 to have a prefix of "ftp://").
570 Many client implementations heuristically resolve these references.
572 change over time, particularly when new schemes are introduced.
573 Since an abbreviated URI has the same syntax as a relative URL path,
574 abbreviated URI references cannot be used where relative URIs are
575 permitted, and can only be used when there is no defined base
576 (such as in dialog boxes).
577 Don't use abbreviated URIs as hypertext links inside a document;
578 use the standard format as described here.
581 .I http://www.ietf.org/rfc/rfc2396.txt
583 .I http://www.w3.org/TR/REC-html40
586 Any tool accepting URIs (e.g., a web browser) on a Linux system should
587 be able to handle (directly or indirectly) all of the
588 schemes described here, including the man: and info: schemes.
589 Handling them by invoking some other program is
590 fine and in fact encouraged.
592 Technically the fragment isn't part of the URI.
594 For information on how to embed URIs (including URLs) in a data format,
595 see documentation on that format.
596 HTML uses the format <A HREF="\fIuri\fP">
599 Texinfo files use the format @uref{\fIuri\fP}.
600 Man and mdoc have the recently added UR macro, or just include the
601 URI in the text (viewers should be able to detect :// as part of a URI).
603 The GNOME and KDE desktop environments currently vary in the URIs
604 they accept, in particular in their respective help browsers.
605 To list man pages, GNOME uses <toc:man> while KDE uses <man:(index)>, and
606 to list info pages, GNOME uses <toc:info> while KDE uses <info:(dir)>
607 (the author of this man page prefers the KDE approach here, though a more
608 regular format would be even better).
609 In general, KDE uses <file:/cgi-bin/> as a prefix to a set of generated
611 KDE prefers documentation in HTML, accessed via the
612 <file:/cgi-bin/helpindex>.
613 GNOME prefers the ghelp scheme to store and find documentation.
614 Neither browser handles file: references to directories at the time
615 of this writing, making it difficult to refer to an entire directory with
617 As noted above, these environments differ in how they handle the
618 info: scheme, probably the most important variation.
619 It is expected that GNOME and KDE
620 will converge to common URI formats, and a future
621 version of this man page will describe the converged result.
622 Efforts to aid this convergence are encouraged.
625 A URI does not in itself pose a security threat.
626 There is no general guarantee that a URL, which at one time
627 located a given resource, will continue to do so.
629 guarantee that a URL will not locate a different resource at some
630 later point in time; such a guarantee can only be
631 obtained from the person(s) controlling that namespace and the
632 resource in question.
634 It is sometimes possible to construct a URL such that an attempt to
635 perform a seemingly harmless operation, such as the
636 retrieval of an entity associated with the resource, will in fact
637 cause a possibly damaging remote operation to occur.
639 is typically constructed by specifying a port number other than that
640 reserved for the network protocol in question.
641 The client unwittingly contacts a site that is in fact
642 running a different protocol.
643 The content of the URL contains instructions that, when
644 interpreted according to this other protocol, cause an unexpected
646 An example has been the use of a gopher URL to cause an
647 unintended or impersonating message to be sent via a SMTP server.
649 Caution should be used when using any URL that specifies a port
650 number other than the default for the protocol, especially when it is
651 a number within the reserved space.
653 Care should be taken when a URI contains escaped delimiters for a
654 given protocol (for example, CR and LF characters for telnet
655 protocols) that these are not unescaped before transmission.
656 This might violate the protocol, but avoids the potential for such
657 characters to be used to simulate an extra operation or parameter in
658 that protocol, which might lead to an unexpected and possibly harmful
659 remote operation to be performed.
661 It is clearly unwise to use a URI that contains a password which is
662 intended to be secret.
663 In particular, the use of a password within
664 the "userinfo" component of a URI is strongly recommended against except
665 in those rare cases where the "password" parameter is intended to be public.
668 Documentation may be placed in a variety of locations, so there
669 currently isn't a good URI scheme for general online documentation
670 in arbitrary formats.
671 References of the form
672 <file:///usr/doc/ZZZ> don't work because different distributions and
673 local installation requirements may place the files in different
675 (it may be in /usr/doc, or /usr/local/doc, or /usr/share,
677 Also, the directory ZZZ usually changes when a version changes
678 (though filename globbing could partially overcome this).
679 Finally, using the file: scheme doesn't easily support people
680 who dynamically load documentation from the Internet (instead of
681 loading the files onto a local file system).
682 A future URI scheme may be added (e.g., "userdoc:") to permit
683 programs to include cross-references to more detailed documentation
684 without having to know the exact location of that documentation.
685 Alternatively, a future version of the file-system specification may
686 specify file locations sufficiently so that the file: scheme will
687 be able to locate documentation.
689 Many programs and file formats don't include a way to incorporate
690 or implement links using URIs.
692 Many programs can't handle all of these different URI formats; there
693 should be a standard mechanism to load an arbitrary URI that automatically
694 detects the users' environment (e.g., text or graphics,
695 desktop environment, local user preferences, and currently executing
696 tools) and invokes the right tool for any URI.
698 .\" David A. Wheeler (dwheeler@dwheeler.com) wrote this man page.
704 .UR http://www.ietf.org/rfc/rfc2255.txt
OSDN Git Service
