Debian Codegraph @

upstream/debian-unstable/man7/uri.7

raw
1 .\" Copyright 1999-2000, David A. Wheeler <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" Fragments of this document are directly derived from IETF standards.
7 .\" For those fragments which are directly derived from such standards,
8 .\" the following notice applies, which is the standard copyright and
9 .\" rights announcement of The Internet Society:
10 .\"
11 .\" Copyright 1998, The Internet Society.
12 .\" This document and translations of it may be copied and furnished to
13 .\" others, and derivative works that comment on or otherwise explain it
14 .\" or assist in its implementation may be prepared, copied, published
15 .\" and distributed, in whole or in part, without restriction of any
16 .\" kind, provided that the above copyright notice and this paragraph are
17 .\" included on all such copies and derivative works. However, this
18 .\" document itself may not be modified in any way, such as by removing
19 .\" the copyright notice or references to the Internet Society or other
20 .\" Internet organizations, except as needed for the purpose of
21 .\" developing Internet standards in which case the procedures for
22 .\" copyrights defined in the Internet Standards process must be
23 .\" followed, or as required to translate it into languages other than English.
24 .\"
25 .TH uri 7 2026-02-08 "Linux man-pages 6.18"
26 .SH NAME
27 uri, url, urn \- uniform resource identifier (URI), including a URL or URN
28 .SH SYNOPSIS
29 .SY \f[I]URI\f[]\~\f[R]=\f[]
30 .RI [\~ absoluteURI
31 |
32 .IR relativeURI \~]
33 .RB [\~\[dq] # \[dq]\~\c
34 .IR fragment \~]
35 .YS
36 .P
37 .SY \f[I]absoluteURI\f[]\~\f[R]=\f[]
38 .I scheme\~\c
39 .RB \[dq] : \[dq]
40 .RI (\~ hierarchical_part
41 |
42 .IR opaque_part \~)
43 .YS
44 .P
45 .SY \f[I]relativeURI\f[]\~\f[R]=\f[]
46 .RI (\~ net_path
47 |
48 .I absolute_path
49 |
50 .IR relative_path \~)
51 .RB [\~\[dq] ? \[dq]\~\c
52 .IR query \~]
53 .YS
54 .P
55 .SY \f[I]scheme\f[]\~\f[R]=\f[]
56 .RB \[dq] http \[dq]
57 |
58 .RB \[dq] ftp \[dq]
59 |
60 .RB \[dq] gopher \[dq]
61 |
62 .RB \[dq] mailto \[dq]
63 |
64 .RB \[dq] news \[dq]
65 |
66 .RB \[dq] telnet \[dq]
67 |
68 .RB \[dq] file \[dq]
69 |
70 .RB \[dq] ftp \[dq]
71 |
72 .RB \[dq] man \[dq]
73 |
74 .RB \[dq] info \[dq]
75 |
76 .RB \[dq] whatis \[dq]
77 |
78 .RB \[dq] ldap \[dq]
79 |
80 .RB \[dq] wais \[dq]
81 | \&...
82 .YS
83 .P
84 .SY \f[I]hierarchical_part\f[]\~\f[R]=\f[]
85 .RI (\~ net_path
86 |
87 .IR absolute_path \~)
88 .RB [\~\[dq] ? \[dq]\~\c
89 .IR query \~]
90 .YS
91 .P
92 .SY \f[I]net_path\f[]\~\f[R]=\f[]
93 .RB \[dq] // \[dq]\~\c
94 .I authority
95 .RI [\~ absolute_path \~]
96 .YS
97 .P
98 .SY \f[I]absolute_path\f[]\~\f[R]=\f[]
99 .RB \[dq] / \[dq]\~\c
100 .I path_segments
101 .YS
102 .P
103 .SY \f[I]relative_path\f[]\~\f[R]=\f[]
104 .I relative_segment
105 .RI [\~ absolute_path \~]
106 .YS
107 .SH DESCRIPTION
108 A Uniform Resource Identifier (URI) is a short string of characters
109 identifying an abstract or physical resource (for example, a web page).
110 A Uniform Resource Locator (URL) is a URI
111 that identifies a resource through its primary access
112 mechanism (e.g., its network "location"), rather than
113 by name or some other attribute of that resource.
114 A Uniform Resource Name (URN) is a URI
115 that must remain globally unique and persistent even when
116 the resource ceases to exist or becomes unavailable.
117 .P
118 URIs are the standard way to name hypertext link destinations
119 for tools such as web browsers.
120 The string "http://www.kernel.org" is a URL (and thus it
121 is also a URI).
122 Many people use the term URL loosely as a synonym for URI
123 (though technically URLs are a subset of URIs).
124 .P
125 URIs can be absolute or relative.
126 An absolute identifier refers to a resource independent of
127 context, while a relative
128 identifier refers to a resource by describing the difference
129 from the current context.
130 Within a relative path reference, the complete path segments "." and
131 ".." have special meanings: "the current hierarchy level" and "the
132 level above this hierarchy level", respectively, just like they do in
133 UNIX-like systems.
134 A path segment which contains a colon
135 character can't be used as the first segment of a relative URI path
136 (e.g., "this:that"), because it would be mistaken for a scheme name;
137 precede such segments with ./ (e.g., "./this:that").
138 Note that descendants of MS-DOS (e.g., Microsoft Windows) replace
139 devicename colons with the vertical bar ("|") in URIs, so "C:" becomes "C|".
140 .P
141 A fragment identifier,
142 if included,
143 refers to a particular named portion (fragment) of a resource;
144 text after a \[aq]#\[aq] identifies the fragment.
145 A URI beginning with \[aq]#\[aq]
146 refers to that fragment in the current resource.
147 .SS Usage
148 There are many different URI schemes, each with specific
149 additional rules and meanings, but they are intentionally made to be
150 as similar as possible.
151 For example, many URL schemes
152 permit the authority to be the following format, called here an
153 .I ip_server
154 (square brackets show what's optional):
155 .P
156 .IR "ip_server = " [ user " [ : " password " ] @ ] " host " [ : " port ]
157 .P
158 This format allows you to optionally insert a username,
159 a user plus password, and/or a port number.
160 The
161 .I host
162 is the name of the host computer, either its name as determined by DNS
163 or an IP address (numbers separated by periods).
164 Thus the URI
165 <http://fred:[email protected]:8080/>
166 logs into a web server on host example.com
167 as fred (using fredpassword) using port 8080.
168 Avoid including a password in a URI if possible because of the many
169 security risks of having a password written down.
170 If the URL supplies a username but no password, and the remote
171 server requests a password, the program interpreting the URL
172 should request one from the user.
173 .P
174 Here are some of the most common schemes in use on UNIX-like systems
175 that are understood by many tools.
176 Note that many tools using URIs
177 also have internal schemes or specialized schemes;
178 see those tools' documentation for information on those schemes.
179 .P
180 .B "http \- Web (HTTP) server"
181 .P
182 .RI http:// ip_server / path
183 .br
184 .RI http:// ip_server / path ? query
185 .P
186 This is a URL accessing a web (HTTP) server.
187 The default port is 80.
188 If the path refers to a directory,
189 the web server will choose what to return;
190 usually if there is a file named "index.html" or "index.htm",
191 its content is returned;
192 otherwise,
193 a list of the files in the current directory (with appropriate links)
194 is generated and returned.
195 An example is <http://lwn.net>.
196 .P
197 A query can be given in the archaic "isindex" format,
198 consisting of a word or phrase
199 and not including an equal sign (=).
200 A query can also be in the longer "GET" format,
201 which has one or more query entries of the form
202 .IR key = value
203 separated by the ampersand character (&).
204 Note that
205 .I key
206 can be repeated more than once,
207 though it's up to the web server
208 and its application programs
209 to determine if there's any meaning to that.
210 There is an unfortunate interaction with HTML/XML/SGML
211 and the GET query format;
212 when such URIs with more than one key
213 are embedded in SGML/XML documents (including HTML),
214 the ampersand (&) has to be rewritten as &amp;.
215 Note that not all queries use this format;
216 larger forms may be too long to store as a URI,
217 so they use a different interaction mechanism
218 (called POST)
219 which does not include the data in the URI.
220 See the Common Gateway Interface specification at
221 .UR http:\://www.w3.org\:/CGI
222 .UE
223 for more information.
224 .P
225 .B "ftp \- File Transfer Protocol (FTP)"
226 .P
227 .RI ftp:// ip_server / path
228 .P
229 This is a URL accessing a file through the file transfer protocol (FTP).
230 The default port (for control) is 21.
231 If no username is included,
232 the username "anonymous" is supplied,
233 and in that case many clients
234 provide as the password the requestor's Internet email address.
235 An example is
236 <ftp://ftp.is.co.za/rfc/rfc1808.txt>.
237 .P
238 .B "gopher \- Gopher server"
239 .P
240 .RI gopher:// ip_server / "gophertype selector"
241 .br
242 .RI gopher:// ip_server / "gophertype selector" %09 search
243 .br
244 .RI gopher:// ip_server / "gophertype selector" %09 search %09 gopher+_string
245 .br
246 .P
247 The default gopher port is 70.
248 .I gophertype
249 is a single-character field to denote
250 the Gopher type of the resource
251 to which the URL refers.
252 The entire path may also be empty,
253 in which case the delimiting "/" is also optional,
254 and the gophertype defaults to "1".
255 .P
256 .I selector
257 is the Gopher selector string.
258 In the Gopher protocol,
259 Gopher selector strings are a sequence of octets
260 which may contain any octets except
261 09 hexadecimal (US-ASCII HT or tab),
262 0A hexadecimal (US-ASCII character LF),
263 and 0D (US-ASCII character CR).
264 .P
265 .B "mailto \- Email address"
266 .P
267 .RI mailto: email-address
268 .P
269 This is an email address,
270 usually of the form
271 .IR name @ hostname .
272 See
273 .BR mailaddr (7)
274 for more information on the correct format of an email address.
275 Note that any % character must be rewritten as %25.
276 An example is <mailto:[email protected]>.
277 .P
278 .B "news \- Newsgroup or News message"
279 .P
280 .RI news: newsgroup-name
281 .br
282 .RI news: message-id
283 .P
284 A
285 .I newsgroup-name
286 is a period-delimited hierarchical name,
287 such as "comp.infosystems.www.misc".
288 If <newsgroup-name> is "*" (as in <news:*>),
289 it is used to refer to "all available news groups".
290 An example is <news:comp.lang.ada>.
291 .P
292 A
293 .I message-id
294 corresponds to the Message-ID of
295 .UR http:\://www.ietf.org\:/rfc\:/rfc1036.txt
296 IETF RFC\ 1036,
297 .UE
298 without the enclosing "<" and ">";
299 it takes the form
300 .IR unique @ full_domain_name .
301 A message identifier may be distinguished from a news group name
302 by the presence of the "@" character.
303 .P
304 .B "telnet \- Telnet login"
305 .P
306 .RI telnet:// ip_server /
307 .P
308 The Telnet URL scheme is used to designate interactive text services
309 that may be accessed by the Telnet protocol.
310 The final "/" character may be omitted.
311 The default port is 23.
312 An example is <telnet://melvyl.ucop.edu/>.
313 .P
314 .B "file \- Normal file"
315 .P
316 .RI file:// ip_server / path_segments
317 .br
318 .RI file: path_segments
319 .P
320 This represents a file or directory accessible locally.
321 As a special case,
322 .I ip_server
323 can be the string "localhost" or the empty string;
324 this is interpreted as
325 "the machine from which the URL is being interpreted".
326 If the path is to a directory,
327 the viewer should display
328 the directory's contents with links to each containee;
329 not all viewers currently do this.
330 KDE supports generated files through the URL <file:/cgi-bin>.
331 If the given file isn't found,
332 browser writers may want to try to
333 expand the filename via filename globbing
334 (see
335 .BR glob (7)
336 and
337 .BR glob (3)).
338 .P
339 The second format (e.g., <file:/etc/passwd>)
340 is a correct format for referring to
341 a local file.
342 However,
343 older standards did not permit this format,
344 and some programs don't recognize this as a URI.
345 A more portable syntax is to use an empty string as the server name,
346 for example,
347 <file:///etc/passwd>;
348 this form does the same thing
349 and is easily recognized by pattern matchers and older programs as a URI.
350 Note that if you really mean to say "start from the current location",
351 don't specify the scheme at all;
352 use a relative address like <../test.txt>,
353 which has the side-effect of being scheme-independent.
354 An example of this scheme is <file:///etc/passwd>.
355 .P
356 .B "man \- Man page documentation"
357 .P
358 .RI man: command-name
359 .br
360 .RI man: command-name ( section )
361 .P
362 This refers to local online manual (man) reference pages.
363 The command name can
364 optionally be followed by a parenthesis and section number;
365 see
366 .BR man (7)
367 for more information on the meaning of the section numbers.
368 This URI scheme is unique to UNIX-like systems (such as Linux)
369 and is not currently registered by the IETF.
370 An example is <man:ls(1)>.
371 .P
372 .B "info \- Info page documentation"
373 .P
374 .RI info: virtual-filename
375 .br
376 .RI info: virtual-filename # nodename
377 .br
378 .RI info:( virtual-filename )
379 .br
380 .RI info:( virtual-filename ) nodename
381 .P
382 This scheme refers to online info reference pages
383 (generated from texinfo files),
384 a documentation format used by programs such as the GNU tools.
385 This URI scheme is unique to UNIX-like systems (such as Linux)
386 and is not currently registered by the IETF.
387 As of this writing,
388 GNOME and KDE differ in their URI syntax
389 and do not accept the other's syntax.
390 The first two formats are the GNOME format;
391 in nodenames,
392 all spaces are written as underscores.
393 The second two formats are the KDE format;
394 spaces in nodenames must be written as spaces,
395 even though this is forbidden by the URI standards.
396 It's hoped that in the future most tools will understand all of these formats
397 and will always accept underscores for spaces in nodenames.
398 In both GNOME and KDE,
399 if the form without the nodename is used,
400 the nodename is assumed to be "Top".
401 Examples of the GNOME format are <info:gcc> and <info:gcc#G++_and_GCC>.
402 Examples of the KDE format are <info:(gcc)> and <info:(gcc)G++ and GCC>.
403 .P
404 .B "whatis \- Documentation search"
405 .P
406 .RI whatis: string
407 .P
408 This scheme searches the database of
409 short (one-line) descriptions of commands
410 and returns a list of descriptions containing that string.
411 Only complete word matches are returned.
412 See
413 .BR whatis (1).
414 This URI scheme is unique to UNIX-like systems (such as Linux)
415 and is not currently registered by the IETF.
416 .P
417 .B "ghelp \- GNOME help documentation"
418 .P
419 .RI ghelp: name-of-application
420 .P
421 This loads GNOME help for the given application.
422 Note that not much documentation currently exists in this format.
423 .P
424 .B "ldap \- Lightweight Directory Access Protocol"
425 .P
426 .RI ldap:// hostport
427 .br
428 .RI ldap:// hostport /
429 .br
430 .RI ldap:// hostport / dn
431 .br
432 .RI ldap:// hostport / dn ? attributes
433 .br
434 .RI ldap:// hostport / dn ? attributes ? scope
435 .br
436 .RI ldap:// hostport / dn ? attributes ? scope ? filter
437 .br
438 .RI ldap:// hostport / dn ? attributes ? scope ? filter ? extensions
439 .P
440 This scheme supports queries to
441 the Lightweight Directory Access Protocol (LDAP),
442 a protocol for querying
443 a set of servers for hierarchically organized information
444 (such as people and computing resources).
445 See
446 .UR http:\://www.ietf.org\:/rfc\:/rfc2255.txt
447 RFC\ 2255
448 .UE
449 for more information on the LDAP URL scheme.
450 The components of this URL are:
451 .TP
452 hostport
453 the LDAP server to query,
454 written as a hostname
455 optionally followed by a colon and the port number.
456 The default LDAP port is TCP port 389.
457 If empty,
458 the client determines which the LDAP server to use.
459 .TP
460 dn
461 the LDAP Distinguished Name,
462 which identifies
463 the base object of the LDAP search (see
464 .UR http:\://www.ietf.org\:/rfc\:/rfc2253.txt
465 RFC\ 2253
466 .UE
467 section 3).
468 .TP
469 attributes
470 a comma-separated list of attributes to be returned;
471 see RFC\ 2251 section 4.1.5.
472 If omitted,
473 all attributes should be returned.
474 .TP
475 scope
476 specifies the scope of the search,
477 which can be one of
478 "base" (for a base object search),
479 "one" (for a one-level search),
480 or "sub" (for a subtree search).
481 If scope is omitted,
482 "base" is assumed.
483 .TP
484 filter
485 specifies the search filter
486 (subset of entries to return).
487 If omitted,
488 all entries should be returned.
489 See
490 .UR http:\://www.ietf.org\:/rfc\:/rfc2254.txt
491 RFC\ 2254
492 .UE
493 section 4.
494 .TP
495 extensions
496 a comma-separated list of type=value pairs,
497 where the =value portion may be omitted for options not requiring it.
498 An extension prefixed with a \[aq]!\[aq] is critical
499 (must be supported to be valid),
500 otherwise it is noncritical (optional).
501 .P
502 LDAP queries are easiest to explain by example.
503 Here's a query that asks ldap.itd.umich.edu for information
504 about the University of Michigan in the U.S.:
505 .P
506 .nf
507 ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US
508 .fi
509 .P
510 To just get its postal address attribute, request:
511 .P
512 .nf
513 ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress
514 .fi
515 .P
516 To ask a host.com at port 6666 for information
517 about the person with common name (cn) "Babs Jensen" at University of Michigan,
518 request:
519 .P
520 .nf
521 ldap://host.com:6666/o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen)
522 .fi
523 .P
524 .B "wais \- Wide Area Information Servers"
525 .P
526 .RI wais:// hostport / database
527 .br
528 .RI wais:// hostport / database ? search
529 .br
530 .RI wais:// hostport / database / wtype / wpath
531 .P
532 This scheme designates a WAIS database, search, or document
533 (see
534 .UR http:\://www.ietf.org\:/rfc\:/rfc1625.txt
535 IETF RFC\ 1625
536 .UE
537 for more information on WAIS).
538 Hostport is the hostname,
539 optionally followed by a colon and port number
540 (the default port number is 210).
541 .P
542 The first form designates a WAIS database for searching.
543 The second form designates a particular search of the WAIS database
544 .IR database .
545 The third form designates a particular document within a WAIS database
546 to be retrieved.
547 .I wtype
548 is the WAIS designation of the type of the object,
549 and
550 .I wpath
551 is the WAIS document-id.
552 .P
553 .B "other schemes"
554 .P
555 There are many other URI schemes.
556 Most tools that accept URIs support a set of internal URIs
557 (e.g., Mozilla has the about: scheme for internal information,
558 and the GNOME help browser has the toc: scheme for various starting locations).
559 There are many schemes that have been defined
560 but are not as widely used at the current time
561 (e.g., prospero).
562 The nntp: scheme is deprecated in favor of the news: scheme.
563 URNs are to be supported by the urn: scheme,
564 with a hierarchical name space
565 (e.g., urn:ietf:...\& would identify IETF documents);
566 at this time,
567 URNs are not widely implemented.
568 Not all tools support all schemes.
569 .SS Character encoding
570 URIs use a limited number of characters
571 so that they can be typed in and used in a variety of situations.
572 .P
573 The following characters are reserved,
574 that is,
575 they may appear in a URI
576 but their use is limited to their reserved purpose
577 (conflicting data must be escaped before forming the URI):
578 .IP
579 .in +4n
580 .EX
581 ; / ? : @ & = + $ ,
582 .EE
583 .in
584 .P
585 Unreserved characters may be included in a URI.
586 Unreserved characters include
587 uppercase and lowercase Latin letters,
588 decimal digits,
589 and the following limited set of punctuation marks and symbols:
590 .IP
591 .in +4n
592 .EX
593 \- _ . ! \[ti] * ' ( )
594 .EE
595 .in
596 .P
597 All other characters must be escaped.
598 An escaped octet is encoded as a character triplet,
599 consisting of
600 the percent character "%"
601 followed by the two hexadecimal digits representing the octet code
602 (you can use uppercase or lowercase letters for the hexadecimal digits).
603 For example,
604 a blank space must be escaped as "%20",
605 a tab character as "%09",
606 and the "&" as "%26".
607 Because the percent "%" character
608 always has the reserved purpose of being the escape indicator,
609 it must be escaped as "%25".
610 It is common practice to
611 escape space characters as the plus symbol (+) in query text;
612 this practice isn't uniformly defined in the relevant RFCs
613 (which recommend %20 instead)
614 but any tool accepting URIs with query text should be prepared for them.
615 A URI is always shown in its "escaped" form.
616 .P
617 Unreserved characters can be escaped
618 without changing the semantics of the URI,
619 but this should not be done unless the URI is being used
620 in a context that does not allow the unescaped character to appear.
621 For example,
622 "%7e" is sometimes used instead of "\[ti]" in an HTTP URL path,
623 but the two are equivalent for an HTTP URL.
624 .P
625 For URIs which must handle characters outside the US ASCII character set,
626 the HTML 4.01 specification (section B.2)
627 and IETF RFC\~3986 (last paragraph of section 2.5)
628 recommend the following approach:
629 .IP (1) 5
630 translate the character sequences into UTF-8 (IETF RFC\~3629)
631 \[em]see
632 .BR utf\-8 (7)\[em]
633 and then
634 .IP (2)
635 use the URI escaping mechanism,
636 that is,
637 use the %HH encoding for unsafe octets.
638 .SS Writing a URI
639 When written,
640 URIs should be placed inside double quotes
641 (e.g., "http://www.kernel.org"),
642 enclosed in angle brackets (e.g., <http://lwn.net>),
643 or placed on a line by themselves.
644 A warning for those who use double-quotes:
645 .B never
646 move extraneous punctuation
647 (such as the period ending a sentence or the comma in a list)
648 inside a URI,
649 since this will change the value of the URI.
650 Instead,
651 use angle brackets instead,
652 or switch to a quoting system
653 that never includes extraneous characters inside quotation marks.
654 This latter system,
655 called the 'new' or 'logical' quoting system
656 by "Hart's Rules" and the "Oxford Dictionary for Writers and Editors",
657 is preferred practice in Great Britain and in various European languages.
658 Older documents suggested inserting the prefix "URL:"
659 just before the URI,
660 but this form has never caught on.
661 .P
662 The URI syntax was designed to be unambiguous.
663 However,
664 as URIs have become commonplace,
665 traditional media (television, radio, newspapers, billboards, etc.)
666 have increasingly used abbreviated URI references
667 consisting of only the authority and path portions of the identified resource
668 (e.g., <www.w3.org/Addressing>).
669 Such references are primarily intended
670 for human interpretation rather than machine,
671 with the assumption that
672 context-based heuristics are sufficient to complete the URI
673 (e.g.,
674 hostnames beginning with "www"
675 are likely to have a URI prefix of "http://"
676 and hostnames beginning with "ftp"
677 likely to have a prefix of "ftp://").
678 Many client implementations heuristically resolve these references.
679 Such heuristics may change over time,
680 particularly when new schemes are introduced.
681 Since an abbreviated URI has the same syntax as a relative URL path,
682 abbreviated URI references cannot be used where relative URIs are permitted,
683 and can be used only when there is no defined base
684 (such as in dialog boxes).
685 Don't use abbreviated URIs as hypertext links inside a document;
686 use the standard format as described here.
687 .SH STANDARDS
688 .UR http:\://www.ietf.org\:/rfc\:/rfc2396.txt
689 (IETF RFC\ 2396)
690 .UE ,
691 .UR http:\://www.w3.org\:/TR\:/REC\-html40
692 (HTML 4.0)
693 .UE .
694 .SH NOTES
695 Any tool accepting URIs (e.g., a web browser) on a Linux system
696 should be able to handle (directly or indirectly)
697 all of the schemes described here,
698 including the man: and info: schemes.
699 Handling them by invoking some other program is fine and in fact encouraged.
700 .P
701 Technically,
702 the fragment isn't part of the URI.
703 .P
704 For information on how to embed URIs (including URLs) in a data format,
705 see documentation on that format.
706 HTML uses the format
707 .RI "<A\ HREF=\[dq]" uri \[dq]>
708 .I text
709 </A>.
710 Texinfo files use the format
711 .RI @uref{ uri }.
712 Man and mdoc have the recently added UR macro,
713 or just include the URI in the text
714 (viewers should be able to detect :// as part of a URI).
715 .P
716 The GNOME and KDE desktop environments currently vary in the URIs they accept,
717 in particular in their respective help browsers.
718 To list man pages,
719 GNOME uses <toc:man> while KDE uses <man:(index)>,
720 and to list info pages,
721 GNOME uses <toc:info> while KDE uses <info:(dir)>
722 (the author of this man page prefers the KDE approach here,
723 though a more regular format would be even better).
724 In general,
725 KDE uses <file:/cgi-bin/> as a prefix to a set of generated files.
726 KDE prefers documentation in HTML,
727 accessed via the
728 <file:/cgi-bin/helpindex>.
729 GNOME prefers the ghelp scheme to store and find documentation.
730 Neither browser handles file: references to directories
731 at the time of this writing,
732 making it difficult to refer to an entire directory with a browsable URI.
733 As noted above,
734 these environments differ in how they handle the info: scheme,
735 probably the most important variation.
736 It is expected that GNOME and KDE will converge to common URI formats,
737 and a future version of this man page will describe the converged result.
738 Efforts to aid this convergence are encouraged.
739 .SS Security
740 A URI does not in itself pose a security threat.
741 There is no general guarantee that a URL,
742 which at one time located a given resource,
743 will continue to do so.
744 Nor is there any guarantee
745 that a URL will not locate a different resource at some later point in time;
746 such a guarantee can be obtained
747 only from the person(s) controlling
748 that namespace and the resource in question.
749 .P
750 It is sometimes possible to construct a URL
751 such that an attempt to perform a seemingly harmless operation,
752 such as the retrieval of an entity associated with the resource,
753 will in fact cause a possibly damaging remote operation to occur.
754 The unsafe URL
755 is typically constructed by specifying a port number other than
756 that reserved for the network protocol in question.
757 The client unwittingly contacts a site that is in fact
758 running a different protocol.
759 The content of the URL contains instructions that,
760 when interpreted according to this other protocol,
761 cause an unexpected operation.
762 An example has been
763 the use of a gopher URL
764 to cause an unintended or impersonating message
765 to be sent via a SMTP server.
766 .P
767 Caution should be used when
768 using any URL that specifies
769 a port number other than the default for the protocol;
770 especially,
771 when it is a number within the reserved space.
772 .P
773 Care should be taken when a URI contains
774 escaped delimiters for a given protocol
775 (for example, CR and LF characters for telnet protocols)
776 that these are not unescaped before transmission.
777 This might violate the protocol,
778 but avoids the potential for such characters
779 to be used to simulate an extra operation or parameter in that protocol,
780 which might lead to
781 an unexpected and possibly harmful remote operation to be performed.
782 .P
783 It is clearly unwise to use
784 a URI that contains a password
785 which is intended to be secret.
786 In particular,
787 the use of a password within the "userinfo" component of a URI
788 is strongly recommended against
789 except in those rare cases
790 where the "password" parameter is intended to be public.
791 .SH BUGS
792 Documentation may be placed in a variety of locations,
793 so there currently isn't a good URI scheme
794 for general online documentation in arbitrary formats.
795 References of the form
796 <file:///usr/doc/ZZZ>
797 don't work,
798 because different distributions and local installation requirements
799 may place the files in different directories
800 (it may be in /usr/doc, or /usr/local/doc, or /usr/share, or somewhere else).
801 Also,
802 the directory ZZZ usually changes when a version changes
803 (though filename globbing could partially overcome this).
804 Finally,
805 using the file: scheme doesn't easily support
806 people who dynamically load documentation from the Internet
807 (instead of loading the files onto a local filesystem).
808 A future URI scheme may be added (e.g., "userdoc:")
809 to permit programs to include cross-references to more detailed documentation
810 without having to know the exact location of that documentation.
811 Alternatively,
812 a future version of the filesystem specification
813 may specify file locations sufficiently
814 so that the file: scheme will be able to locate documentation.
815 .P
816 Many programs and file formats don't include
817 a way to incorporate or implement links using URIs.
818 .P
819 Many programs can't handle all of these different URI formats;
820 there should be a standard mechanism
821 to load an arbitrary URI
822 that automatically detects the users' environment
823 (e.g.,
824 text or graphics,
825 desktop environment,
826 local user preferences,
827 and currently executing tools)
828 and invokes the right tool for any URI.
829 .\" .SH AUTHOR
830 .\" David A.\& Wheeler ([email protected]) wrote this man page.
831 .SH SEE ALSO
832 .BR lynx (1),
833 .BR man2html (1),
834 .BR mailaddr (7),
835 .BR utf\-8 (7)
836 .P
837 .UR http:\://www.ietf.org\:/rfc\:/rfc2255.txt
838 IETF RFC\ 2255
839 .UE