man7/uri.7

   1 '\"
   2 .\" (C) Copyright 1999-2000 David A. Wheeler (dwheeler@dwheeler.com)
   3 .\"
   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.
   7 .\"
   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.
  12 .\"
  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
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\"
  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:
  28 .\"
  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.
  42 .\"
  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)
  46 .\"
  47 .TH URI 7 2012-08-05 "Linux" "Linux Programmer's Manual"
  48 .SH NAME
  49 uri, url, urn \- uniform resource identifier (URI), including a URL or URN
  50 .SH SYNOPSIS
  51 .nf
  52 .HP 0.2i
  53 URI = [ absoluteURI | relativeURI ] [ "#" fragment ]
  54 .HP
  55 absoluteURI = scheme ":" ( hierarchical_part | opaque_part )
  56 .HP
  57 relativeURI = ( net_path | absolute_path | relative_path ) [ "?" query ]
  58 .HP
  59 scheme = "http" | "ftp" | "gopher" | "mailto" | "news" | "telnet" |
  60          "file" | "man" | "info" | "whatis" | "ldap" | "wais" | \&...
  61 .HP
  62 hierarchical_part = ( net_path | absolute_path ) [ "?" query ]
  63 .HP
  64 net_path = "//" authority [ absolute_path ]
  65 .HP
  66 absolute_path = "/"  path_segments
  67 .HP
  68 relative_path = relative_segment [ absolute_path ]
  69 .fi
  70 .SH DESCRIPTION
  71 .PP
  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.
  81 .PP
  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
  85 is also a URI).
  86 Many people use the term URL loosely as a synonym for URI
  87 (though technically URLs are a subset of URIs).
  88 .PP
  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
  97 UNIX-like systems.
  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|".
 104 .PP
 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.
 108 .SS Usage
 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
 114 .I ip_server
 115 (square brackets show what's optional):
 116 .HP
 117 .IR "ip_server = " [ user " [ : " password " ] @ ] " host " [ : " port ]
 118 .PP
 119 This format allows you to optionally insert a username,
 120 a user plus password, and/or a port number.
 121 The
 122 .I host
 123 is the name of the host computer, either its name as determined by DNS
 124 or an IP address (numbers separated by periods).
 125 Thus the URI
 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.
 134 .PP
 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.
 139 .PP
 140 .B "http \- Web (HTTP) server"
 141 .PP
 142 .RI http:// ip_server / path
 143 .br
 144 .RI http:// ip_server / path ? query
 145 .PP
 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>.
 153 .PP
 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
 158 .IR key = value
 159 separated by the ampersand character (&).
 160 Note that
 161 .I key
 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 &amp;.
 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 .UR http://www.w3.org\:/CGI
 174 .UE
 175 for more information.
 176 .PP
 177 .B "ftp \- File Transfer Protocol (FTP)"
 178 .PP
 179 .RI ftp:// ip_server / path
 180 .PP
 181 This is a URL accessing a file through the file transfer protocol (FTP).
 182 The default port (for control) is 21.
 183 If no username is included, the username "anonymous" is supplied, and
 184 in that case many clients provide as the password the requestor's
 185 Internet email address.
 186 An example is
 187 <ftp://ftp.is.co.za/rfc/rfc1808.txt>.
 188 .PP
 189 .B "gopher \- Gopher server"
 190 .PP
 191 .RI gopher:// ip_server / "gophertype selector"
 192 .br
 193 .RI gopher:// ip_server / "gophertype selector" %09 search
 194 .br
 195 .RI gopher:// ip_server / "gophertype selector" %09 search %09 gopher+_string
 196 .br
 197 .PP
 198 The default gopher port is 70.
 199 .I gophertype
 200 is a single-character field to denote the
 201 Gopher type of the resource to
 202 which the URL refers.
 203 The entire path may also be empty, in
 204 which case the delimiting "/" is also optional and the gophertype
 205 defaults to "1".
 206 .PP
 207 .I selector
 208 is the Gopher selector string.
 209 In the Gopher protocol,
 210 Gopher selector strings are a sequence of octets which may contain
 211 any octets except 09 hexadecimal (US-ASCII HT or tab), 0A hexadecimal
 212 (US-ASCII character LF), and 0D (US-ASCII character CR).
 213 .PP
 214 .B "mailto \- Email address"
 215 .PP
 216 .RI mailto: email-address
 217 .PP
 218 This is an email address, usually of the form
 219 .IR name @ hostname .
 220 See
 221 .BR mailaddr (7)
 222 for more information on the correct format of an email address.
 223 Note that any % character must be rewritten as %25.
 224 An example is <mailto:dwheeler@dwheeler.com>.
 225 .PP
 226 .B "news \- Newsgroup or News message"
 227 .PP
 228 .RI news: newsgroup-name
 229 .br
 230 .RI news: message-id
 231 .PP
 232 A
 233 .I newsgroup-name
 234 is a period-delimited hierarchical name, such as
 235 "comp.infosystems.www.misc".
 236 If <newsgroup-name> is "*" (as in <news:*>), it is used to refer
 237 to "all available news groups".
 238 An example is <news:comp.lang.ada>.
 239 .PP
 240 A
 241 .I message-id
 242 corresponds to the Message-ID of
 243 .UR http://www.ietf.org\:/rfc\:/rfc1036.txt
 244 IETF RFC\ 1036,
 245 .UE
 246 without the enclosing "<"
 247 and ">"; it takes the form
 248 .IR unique @ full_domain_name .
 249 A message identifier may be distinguished from a news group name by the
 250 presence of the "@" character.
 251 .PP
 252 .B "telnet \- Telnet login"
 253 .PP
 254 .RI telnet:// ip_server /
 255 .PP
 256 The Telnet URL scheme is used to designate interactive text services that
 257 may be accessed by the Telnet protocol.
 258 The final "/" character may be omitted.
 259 The default port is 23.
 260 An example is <telnet://melvyl.ucop.edu/>.
 261 .PP
 262 .B "file \- Normal file"
 263 .PP
 264 .RI file:// ip_server / path_segments
 265 .br
 266 .RI file: path_segments
 267 .PP
 268 This represents a file or directory accessible locally.
 269 As a special case,
 270 .I host
 271 can be the string "localhost" or the empty
 272 string; this is interpreted as "the machine from which the URL is
 273 being interpreted".
 274 If the path is to a directory, the viewer should display the
 275 directory's contents with links to each containee;
 276 not all viewers currently do this.
 277 KDE supports generated files through the URL <file:/cgi-bin>.
 278 If the given file isn't found, browser writers may want to try to expand
 279 the filename via filename globbing
 280 (see
 281 .BR glob (7)
 282 and
 283 .BR glob (3)).
 284 .PP
 285 The second format (e.g., <file:/etc/passwd>)
 286 is a correct format for referring to
 287 a local file.
 288 However, older standards did not permit this format,
 289 and some programs don't recognize this as a URI.
 290 A more portable syntax is to use an empty string as the server name,
 291 for example,
 292 <file:///etc/passwd>; this form does the same thing
 293 and is easily recognized by pattern matchers and older programs as a URI.
 294 Note that if you really mean to say "start from the current location," don't
 295 specify the scheme at all; use a relative address like <../test.txt>,
 296 which has the side-effect of being scheme-independent.
 297 An example of this scheme is <file:///etc/passwd>.
 298 .PP
 299 .B "man \- Man page documentation"
 300 .PP
 301 .RI man: command-name
 302 .br
 303 .RI man: command-name ( section )
 304 .PP
 305 This refers to local online manual (man) reference pages.
 306 The command name can optionally be followed by a
 307 parenthesis and section number; see
 308 .BR man (7)
 309 for more information on the meaning of the section numbers.
 310 This URI scheme is unique to UNIX-like systems (such as Linux)
 311 and is not currently registered by the IETF.
 312 An example is <man:ls(1)>.
 313 .PP
 314 .B "info \- Info page documentation"
 315 .PP
 316 .RI info: virtual-filename
 317 .br
 318 .RI info: virtual-filename # nodename
 319 .br
 320 .RI info:( virtual-filename )
 321 .br
 322 .RI info:( virtual-filename ) nodename
 323 .PP
 324 This scheme refers to online info reference pages (generated from
 325 texinfo files),
 326 a documentation format used by programs such as the GNU tools.
 327 This URI scheme is unique to UNIX-like systems (such as Linux)
 328 and is not currently registered by the IETF.
 329 As of this writing, GNOME and KDE differ in their URI syntax
 330 and do not accept the other's syntax.
 331 The first two formats are the GNOME format; in nodenames all spaces
 332 are written as underscores.
 333 The second two formats are the KDE format;
 334 spaces in nodenames must be written as spaces, even though this
 335 is forbidden by the URI standards.
 336 It's hoped that in the future most tools will understand all of these
 337 formats and will always accept underscores for spaces in nodenames.
 338 In both GNOME and KDE, if the form without the nodename is used the
 339 nodename is assumed to be "Top".
 340 Examples of the GNOME format are <info:gcc> and <info:gcc#G++_and_GCC>.
 341 Examples of the KDE format are <info:(gcc)> and <info:(gcc)G++ and GCC>.
 342 .PP
 343 .B "whatis \- Documentation search"
 344 .PP
 345 .RI whatis: string
 346 .PP
 347 This scheme searches the database of short (one-line) descriptions of
 348 commands and returns a list of descriptions containing that string.
 349 Only complete word matches are returned.
 350 See
 351 .BR whatis (1).
 352 This URI scheme is unique to UNIX-like systems (such as Linux)
 353 and is not currently registered by the IETF.
 354 .PP
 355 .B "ghelp \- GNOME help documentation"
 356 .PP
 357 .RI ghelp: name-of-application
 358 .PP
 359 This loads GNOME help for the given application.
 360 Note that not much documentation currently exists in this format.
 361 .PP
 362 .B "ldap \- Lightweight Directory Access Protocol"
 363 .PP
 364 .RI ldap:// hostport
 365 .br
 366 .RI ldap:// hostport /
 367 .br
 368 .RI ldap:// hostport / dn
 369 .br
 370 .RI ldap:// hostport / dn ? attributes
 371 .br
 372 .RI ldap:// hostport / dn ? attributes ? scope
 373 .br
 374 .RI ldap:// hostport / dn ? attributes ? scope ? filter
 375 .br
 376 .RI ldap:// hostport / dn ? attributes ? scope ? filter ? extensions
 377 .PP
 378 This scheme supports queries to the
 379 Lightweight Directory Access Protocol (LDAP), a protocol for querying
 380 a set of servers for hierarchically organized information
 381 (such as people and computing resources).
 382 See
 383 .UR http://www.ietf.org\:/rfc\:/rfc2255.txt
 384 RFC\ 2255
 385 .UE
 386 for more information on the LDAP URL scheme.
 387 The components of this URL are:
 388 .IP hostport 12
 389 the LDAP server to query, written as a hostname optionally followed by
 390 a colon and the port number.
 391 The default LDAP port is TCP port 389.
 392 If empty, the client determines which the LDAP server to use.
 393 .IP dn
 394 the LDAP Distinguished Name, which identifies
 395 the base object of the LDAP search (see
 396 .UR http://www.ietf.org\:/rfc\:/rfc2253.txt
 397 RFC\ 2253
 398 .UE
 399 section 3).
 400 .IP attributes
 401 a comma-separated list of attributes to be returned;
 402 see RFC\ 2251 section 4.1.5.
 403 If omitted, all attributes should be returned.
 404 .IP scope
 405 specifies the scope of the search, which can be one of
 406 "base" (for a base object search), "one" (for a one-level search),
 407 or "sub" (for a subtree search).
 408 If scope is omitted, "base" is assumed.
 409 .IP filter
 410 specifies the search filter (subset of entries
 411 to return).
 412 If omitted, all entries should be returned.
 413 See
 414 .UR http://www.ietf.org\:/rfc\:/rfc2254.txt
 415 RFC\ 2254
 416 .UE
 417 section 4.
 418 .IP extensions
 419 a comma-separated list of type=value
 420 pairs, where the =value portion may be omitted for options not
 421 requiring it.
 422 An extension prefixed with a \(aq!\(aq is critical
 423 (must be supported to be valid), otherwise it is noncritical (optional).
 424 .PP
 425 LDAP queries are easiest to explain by example.
 426 Here's a query that asks ldap.itd.umich.edu for information about
 427 the University of Michigan in the U.S.:
 428 .PP
 429 .nf
 430 ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US
 431 .fi
 432 .PP
 433 To just get its postal address attribute, request:
 434 .PP
 435 .nf
 436 ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress
 437 .fi
 438 .PP
 439 To ask a host.com at port 6666 for information about the person
 440 with common name (cn) "Babs Jensen" at University of Michigan, request:
 441 .PP
 442 .nf
 443 ldap://host.com:6666/o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen)
 444 .fi
 445 .PP
 446 .B "wais \- Wide Area Information Servers"
 447 .PP
 448 .RI wais:// hostport / database
 449 .br
 450 .RI wais:// hostport / database ? search
 451 .br
 452 .RI wais:// hostport / database / wtype / wpath
 453 .PP
 454 This scheme designates a WAIS database, search, or document
 455 (see
 456 .UR http://www.ietf.org\:/rfc\:/rfc1625.txt
 457 IETF RFC\ 1625
 458 .UE
 459 for more information on WAIS).
 460 Hostport is the hostname, optionally followed by a colon and port number
 461 (the default port number is 210).
 462 .PP
 463 The first form designates a WAIS database for searching.
 464 The second form designates a particular search of the WAIS database
 465 .IR database .
 466 The third form designates a particular document within a WAIS
 467 database to be retrieved.
 468 .I wtype
 469 is the WAIS designation of the type of the object and
 470 .I wpath
 471 is the WAIS document-id.
 472 .PP
 473 .B "other schemes"
 474 .PP
 475 There are many other URI schemes.
 476 Most tools that accept URIs support a set of internal URIs
 477 (e.g., Mozilla has the about: scheme for internal information,
 478 and the GNOME help browser has the toc: scheme for various starting
 479 locations).
 480 There are many schemes that have been defined but are not as widely
 481 used at the current time
 482 (e.g., prospero).
 483 The nntp: scheme is deprecated in favor of the news: scheme.
 484 URNs are to be supported by the urn: scheme, with a hierarchical name space
 485 (e.g., urn:ietf:... would identify IETF documents); at this time
 486 URNs are not widely implemented.
 487 Not all tools support all schemes.
 488 .SS "Character encoding"
 489 .PP
 490 URIs use a limited number of characters so that they can be
 491 typed in and used in a variety of situations.
 492 .PP
 493 The following characters are reserved, that is, they may appear in a
 494 URI but their use is limited to their reserved purpose
 495 (conflicting data must be escaped before forming the URI):
 496 .IP
 497    ; / ? : @ & = + $ ,
 498 .PP
 499 Unreserved characters may be included in a URI.
 500 Unreserved characters
 501 include upper and lower case English letters,
 502 decimal digits, and the following
 503 limited set of punctuation marks and symbols:
 504 .IP
 505  \- _ . ! ~ * ' ( )
 506 .PP
 507 All other characters must be escaped.
 508 An escaped octet is encoded as a character triplet, consisting of the
 509 percent character "%" followed by the two hexadecimal digits
 510 representing the octet code (you can use upper or lower case letters
 511 for the hexadecimal digits).
 512 For example, a blank space must be escaped
 513 as "%20", a tab character as "%09", and the "&" as "%26".
 514 Because the percent "%" character always has the reserved purpose of
 515 being the escape indicator, it must be escaped as "%25".
 516 It is common practice to escape space characters as the plus symbol (+)
 517 in query text; this practice isn't uniformly defined
 518 in the relevant RFCs (which recommend %20 instead) but any tool accepting
 519 URIs with query text should be prepared for them.
 520 A URI is always shown in its "escaped" form.
 521 .PP
 522 Unreserved characters can be escaped without changing the semantics
 523 of the URI, but this should not be done unless the URI is being used
 524 in a context that does not allow the unescaped character to appear.
 525 For example, "%7e" is sometimes used instead of "~" in an HTTP URL
 526 path, but the two are equivalent for an HTTP URL.
 527 .PP
 528 For URIs which must handle characters outside the US ASCII character set,
 529 the HTML 4.01 specification (section B.2) and
 530 IETF RFC\ 2718 (section 2.2.5) recommend the following approach:
 531 .IP 1. 4
 532 translate the character sequences into UTF-8 (IETF RFC\ 2279)\(emsee
 533 .BR utf-8 (7)\(emand
 534 then
 535 .IP 2.
 536 use the URI escaping mechanism, that is,
 537 use the %HH encoding for unsafe octets.
 538 .SS "Writing a URI"
 539 When written, URIs should be placed inside double quotes
 540 (e.g., "http://www.kernelnotes.org"),
 541 enclosed in angle brackets (e.g., <http://lwn.net>),
 542 or placed on a line by themselves.
 543 A warning for those who use double-quotes:
 544 .B never
 545 move extraneous punctuation (such as the period ending a sentence or the
 546 comma in a list)
 547 inside a URI, since this will change the value of the URI.
 548 Instead, use angle brackets instead, or
 549 switch to a quoting system that never includes extraneous characters
 550 inside quotation marks.
 551 This latter system, called the 'new' or 'logical' quoting system by
 552 "Hart's Rules" and the "Oxford Dictionary for Writers and Editors",
 553 is preferred practice in Great Britain and hackers worldwide
 554 (see the
 555 Jargon File's section on Hacker Writing Style,
 556 .UR http://www.fwi.uva.nl\:/~mes\:/jargon\:/h\:/HackerWritingStyle.html
 557 .UE ,
 558 for more information).
 559 Older documents suggested inserting the prefix "URL:"
 560 just before the URI, but this form has never caught on.
 561 .PP
 562 The URI syntax was designed to be unambiguous.
 563 However, as URIs have become commonplace, traditional media
 564 (television, radio, newspapers, billboards, etc.) have increasingly
 565 used abbreviated URI references consisting of
 566 only the authority and path portions of the identified resource
 567 (e.g., <www.w3.org/Addressing>).
 568 Such references are primarily
 569 intended for human interpretation rather than machine, with the
 570 assumption that context-based heuristics are sufficient to complete
 571 the URI (e.g., hostnames beginning with "www" are likely to have
 572 a URI prefix of "http://" and hostnames beginning with "ftp" likely
 573 to have a prefix of "ftp://").
 574 Many client implementations heuristically resolve these references.
 575 Such heuristics may
 576 change over time, particularly when new schemes are introduced.
 577 Since an abbreviated URI has the same syntax as a relative URL path,
 578 abbreviated URI references cannot be used where relative URIs are
 579 permitted, and can only be used when there is no defined base
 580 (such as in dialog boxes).
 581 Don't use abbreviated URIs as hypertext links inside a document;
 582 use the standard format as described here.
 583 .SH CONFORMING TO
 584 .PP
 585 .UR http://www.ietf.org\:/rfc\:/rfc2396.txt
 586 (IETF RFC\ 2396)
 587 .UE ,
 588 .UR http://www.w3.org\:/TR\:/REC-html40
 589 (HTML 4.0)
 590 .UE .
 591 .SH NOTES
 592 Any tool accepting URIs (e.g., a web browser) on a Linux system should
 593 be able to handle (directly or indirectly) all of the
 594 schemes described here, including the man: and info: schemes.
 595 Handling them by invoking some other program is
 596 fine and in fact encouraged.
 597 .PP
 598 Technically the fragment isn't part of the URI.
 599 .PP
 600 For information on how to embed URIs (including URLs) in a data format,
 601 see documentation on that format.
 602 HTML uses the format <A HREF="\fIuri\fP">
 603 .I text
 604 </A>.
 605 Texinfo files use the format @uref{\fIuri\fP}.
 606 Man and mdoc have the recently added UR macro, or just include the
 607 URI in the text (viewers should be able to detect :// as part of a URI).
 608 .PP
 609 The GNOME and KDE desktop environments currently vary in the URIs
 610 they accept, in particular in their respective help browsers.
 611 To list man pages, GNOME uses <toc:man> while KDE uses <man:(index)>, and
 612 to list info pages, GNOME uses <toc:info> while KDE uses <info:(dir)>
 613 (the author of this man page prefers the KDE approach here, though a more
 614 regular format would be even better).
 615 In general, KDE uses <file:/cgi-bin/> as a prefix to a set of generated
 616 files.
 617 KDE prefers documentation in HTML, accessed via the
 618 <file:/cgi-bin/helpindex>.
 619 GNOME prefers the ghelp scheme to store and find documentation.
 620 Neither browser handles file: references to directories at the time
 621 of this writing, making it difficult to refer to an entire directory with
 622 a browsable URI.
 623 As noted above, these environments differ in how they handle the
 624 info: scheme, probably the most important variation.
 625 It is expected that GNOME and KDE
 626 will converge to common URI formats, and a future
 627 version of this man page will describe the converged result.
 628 Efforts to aid this convergence are encouraged.
 629 .SS Security
 630 .PP
 631 A URI does not in itself pose a security threat.
 632 There is no general guarantee that a URL, which at one time
 633 located a given resource, will continue to do so.
 634 Nor is there any
 635 guarantee that a URL will not locate a different resource at some
 636 later point in time; such a guarantee can only be
 637 obtained from the person(s) controlling that namespace and the
 638 resource in question.
 639 .PP
 640 It is sometimes possible to construct a URL such that an attempt to
 641 perform a seemingly harmless operation, such as the
 642 retrieval of an entity associated with the resource, will in fact
 643 cause a possibly damaging remote operation to occur.
 644 The unsafe URL
 645 is typically constructed by specifying a port number other than that
 646 reserved for the network protocol in question.
 647 The client unwittingly contacts a site that is in fact
 648 running a different protocol.
 649 The content of the URL contains instructions that, when
 650 interpreted according to this other protocol, cause an unexpected
 651 operation.
 652 An example has been the use of a gopher URL to cause an
 653 unintended or impersonating message to be sent via a SMTP server.
 654 .PP
 655 Caution should be used when using any URL that specifies a port
 656 number other than the default for the protocol, especially when it is
 657 a number within the reserved space.
 658 .PP
 659 Care should be taken when a URI contains escaped delimiters for a
 660 given protocol (for example, CR and LF characters for telnet
 661 protocols) that these are not unescaped before transmission.
 662 This might violate the protocol, but avoids the potential for such
 663 characters to be used to simulate an extra operation or parameter in
 664 that protocol, which might lead to an unexpected and possibly harmful
 665 remote operation to be performed.
 666 .PP
 667 It is clearly unwise to use a URI that contains a password which is
 668 intended to be secret.
 669 In particular, the use of a password within
 670 the "userinfo" component of a URI is strongly recommended against except
 671 in those rare cases where the "password" parameter is intended to be public.
 672 .SH BUGS
 673 .PP
 674 Documentation may be placed in a variety of locations, so there
 675 currently isn't a good URI scheme for general online documentation
 676 in arbitrary formats.
 677 References of the form
 678 <file:///usr/doc/ZZZ> don't work because different distributions and
 679 local installation requirements may place the files in different
 680 directories
 681 (it may be in /usr/doc, or /usr/local/doc, or /usr/share,
 682 or somewhere else).
 683 Also, the directory ZZZ usually changes when a version changes
 684 (though filename globbing could partially overcome this).
 685 Finally, using the file: scheme doesn't easily support people
 686 who dynamically load documentation from the Internet (instead of
 687 loading the files onto a local file system).
 688 A future URI scheme may be added (e.g., "userdoc:") to permit
 689 programs to include cross-references to more detailed documentation
 690 without having to know the exact location of that documentation.
 691 Alternatively, a future version of the file-system specification may
 692 specify file locations sufficiently so that the file: scheme will
 693 be able to locate documentation.
 694 .PP
 695 Many programs and file formats don't include a way to incorporate
 696 or implement links using URIs.
 697 .PP
 698 Many programs can't handle all of these different URI formats; there
 699 should be a standard mechanism to load an arbitrary URI that automatically
 700 detects the users' environment (e.g., text or graphics,
 701 desktop environment, local user preferences, and currently executing
 702 tools) and invokes the right tool for any URI.
 703 .\" .SH AUTHOR
 704 .\" David A. Wheeler (dwheeler@dwheeler.com) wrote this man page.
 705 .SH SEE ALSO
 706 .BR lynx (1),
 707 .BR man2html (1),
 708 .BR mailaddr (7),
 709 .BR utf-8 (7)
 710
 711 .UR http://www.ietf.org\:/rfc\:/rfc2255.txt
 712 IETF RFC\ 2255
 713 .UE