| 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 &. |
| 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 |