8089
PROPOSED STANDARD
The "file" URI Scheme
Authors: M. Kerwin
Date: February 2017
Area: art
Working Group: appsawg
Stream: IETF
Abstract
This document provides a more complete specification of the "file" Uniform Resource Identifier (URI) scheme and replaces the very brief definition in Section 3.10 of RFC 1738.
It defines a common syntax that is intended to interoperate across the broad spectrum of existing usages. At the same time, it notes some other current practices around the use of file URIs.
RFC 8089
PROPOSED STANDARD
Updated by: 9844 Errata Exist
Internet Engineering Task Force (IETF) M. Kerwin
Request for Comments: 8089 QUT
Updates: <a href="./rfc1738">1738</a> February 2017
Category: Standards Track
ISSN: 2070-1721
<span class="h1">The "file" URI Scheme</span>
Abstract
This document provides a more complete specification of the "file"
Uniform Resource Identifier (URI) scheme and replaces the very brief
definition in <a href="./rfc1738#section-3.10">Section 3.10 of RFC 1738</a>.
It defines a common syntax that is intended to interoperate across
the broad spectrum of existing usages. At the same time, it notes
some other current practices around the use of file URIs.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in <a href="./rfc7841#section-2">Section 2 of RFC 7841</a>.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
<a href="https://www.rfc-editor.org/info/rfc8089">http://www.rfc-editor.org/info/rfc8089</a>.
Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a> and the IETF Trust's Legal
Provisions Relating to IETF Documents
(<a href="http://trustee.ietf.org/license-info">http://trustee.ietf.org/license-info</a>) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
<span class="grey">Kerwin Standards Track [Page 1]</span><span id="page-2" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
Table of Contents
<a href="#section-1">1</a>. Introduction . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-2">2</a>
<a href="#section-1.1">1.1</a>. Notational Conventions . . . . . . . . . . . . . . . . . <a href="#page-3">3</a>
<a href="#section-2">2</a>. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-3">3</a>
<a href="#section-3">3</a>. Operations Involving <file> URIs . . . . . . . . . . . . . . <a href="#page-5">5</a>
<a href="#section-4">4</a>. File System Name Encoding . . . . . . . . . . . . . . . . . . <a href="#page-5">5</a>
<a href="#section-5">5</a>. Security Considerations . . . . . . . . . . . . . . . . . . . <a href="#page-5">5</a>
<a href="#section-6">6</a>. IANA Considerations . . . . . . . . . . . . . . . . . . . . . <a href="#page-6">6</a>
<a href="#section-7">7</a>. References . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-7.1">7.1</a>. Normative References . . . . . . . . . . . . . . . . . . <a href="#page-7">7</a>
<a href="#section-7.2">7.2</a>. Informative References . . . . . . . . . . . . . . . . . <a href="#page-8">8</a>
<a href="#appendix-A">Appendix A</a>. Differences from Previous Specifications . . . . . . <a href="#page-10">10</a>
<a href="#appendix-B">Appendix B</a>. Example URIs . . . . . . . . . . . . . . . . . . . . <a href="#page-10">10</a>
<a href="#appendix-C">Appendix C</a>. Similar Technologies . . . . . . . . . . . . . . . . <a href="#page-10">10</a>
<a href="#appendix-D">Appendix D</a>. System-Specific Operations . . . . . . . . . . . . . <a href="#page-11">11</a>
<a href="#appendix-D.1">D.1</a>. POSIX Systems . . . . . . . . . . . . . . . . . . . . . . <a href="#page-11">11</a>
<a href="#appendix-D.2">D.2</a>. DOS- and Windows-Like Systems . . . . . . . . . . . . . . <a href="#page-11">11</a>
<a href="#appendix-D.3">D.3</a>. Mac OS X Systems . . . . . . . . . . . . . . . . . . . . <a href="#page-12">12</a>
<a href="#appendix-D.4">D.4</a>. OpenVMS Files-11 Systems . . . . . . . . . . . . . . . . <a href="#page-12">12</a>
<a href="#appendix-E">Appendix E</a>. Nonstandard Syntax Variations . . . . . . . . . . . <a href="#page-12">12</a>
<a href="#appendix-E.1">E.1</a>. User Information . . . . . . . . . . . . . . . . . . . . <a href="#page-12">12</a>
<a href="#appendix-E.2">E.2</a>. DOS and Windows Drive Letters . . . . . . . . . . . . . . <a href="#page-13">13</a>
<a href="#appendix-E.2.1">E.2.1</a>. Relative Resolution . . . . . . . . . . . . . . . . . <a href="#page-13">13</a>
<a href="#appendix-E.2.2">E.2.2</a>. Vertical Line Character . . . . . . . . . . . . . . . <a href="#page-14">14</a>
<a href="#appendix-E.3">E.3</a>. UNC Strings . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-15">15</a>
<a href="#appendix-E.3.1">E.3.1</a>. <file> URI with Authority . . . . . . . . . . . . . . <a href="#page-15">15</a>
<a href="#appendix-E.3.2">E.3.2</a>. <file> URI with UNC Path . . . . . . . . . . . . . . <a href="#page-16">16</a>
<a href="#appendix-E.4">E.4</a>. Backslash as Separator . . . . . . . . . . . . . . . . . <a href="#page-17">17</a>
<a href="#appendix-F">Appendix F</a>. Collected Nonstandard Rules . . . . . . . . . . . . <a href="#page-17">17</a>
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-19">19</a>
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-19">19</a>
<span class="h2"><a class="selflink" id="section-1" href="#section-1">1</a>. Introduction</span>
A file URI identifies an object (a "file") stored in a structured
object naming and accessing environment on a host (a "file system").
The URI can be used in discussions about the file, and if other
conditions are met it can be dereferenced to directly access the
file.
This document specifies a syntax based on the generic syntax of
[<a href="./rfc3986" title=""Uniform Resource Identifier (URI): Generic Syntax"">RFC3986</a>] that is compatible with most existing usages. Where
incompatibilities arise, they are usually in parts of the scheme that
were underspecified in earlier definitions and have been tightened up
by more recent specifications. <a href="#appendix-A">Appendix A</a> lists significant changes
to syntax.
<span class="grey">Kerwin Standards Track [Page 2]</span><span id="page-3" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
Extensions to the syntax that might be encountered in practice are
listed in <a href="#appendix-E">Appendix E</a>; these extensions are listed for informational
purposes and are not a requirement of implementation.
The file URI scheme is not coupled with a specific protocol nor with
a specific media type [<a href="./rfc6838" title=""Media Type Specifications and Registration Procedures"">RFC6838</a>]. See <a href="#section-3">Section 3</a> for a discussion of
operations that can be performed on the object identified by a file
URI.
<span class="h3"><a class="selflink" id="section-1.1" href="#section-1.1">1.1</a>. Notational Conventions</span>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [<a href="./rfc2119" title=""Key words for use in RFCs to Indicate Requirement Levels"">RFC2119</a>] when they
appear in all upper case. They may also appear in lower or mixed
case as English words, without normative meaning.
Throughout this document, the term "local file" is used to describe
files that can be accessed through the local file system API using
only the information included in the file path, not relying on other
information (such as network addresses). It is important to note
that a local file may not be physically located on the local machine,
for example, if a networked file system is transparently mounted into
the local file system.
The term "local file URI" is used to describe file URIs that have no
"authority" component or where the authority is the special string
"localhost" or a fully qualified domain name that resolves to the
machine from which the URI is being interpreted (<a href="#section-2">Section 2</a>).
<span class="h2"><a class="selflink" id="section-2" href="#section-2">2</a>. Syntax</span>
The file URI syntax is defined here in Augmented Backus-Naur Form
(ABNF) [<a href="./rfc5234" title=""Augmented BNF for Syntax Specifications: ABNF"">RFC5234</a>], importing the "host" and "path-absolute" rules from
[<a href="./rfc3986" title=""Uniform Resource Identifier (URI): Generic Syntax"">RFC3986</a>] (as updated by [<a href="./rfc6874" title=""Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers"">RFC6874</a>]).
The generic syntax in [<a href="./rfc3986" title=""Uniform Resource Identifier (URI): Generic Syntax"">RFC3986</a>] includes "path" and "authority"
components, for each of which only a subset is used in the definition
of the file URI scheme. The relevant subset of "path" is "path-
absolute", and the subset of "authority" is "file-auth", given below.
The syntax definition below is different from those given in
[<a href="./rfc1630" title=""Universal Resource Identifiers in WWW: A Unifying Syntax for the Expression of Names and Addresses of Objects on the Network as used in the World-Wide Web"">RFC1630</a>] and [<a href="./rfc1738" title=""Uniform Resource Locators (URL)"">RFC1738</a>] as it is derived from the generic syntax of
[<a href="./rfc3986" title=""Uniform Resource Identifier (URI): Generic Syntax"">RFC3986</a>], which postdates the previous file URI specifications.
<a href="#appendix-A">Appendix A</a> enumerates significant differences.
<span class="grey">Kerwin Standards Track [Page 3]</span><span id="page-4" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
file-URI = file-scheme ":" file-hier-part
file-scheme = "file"
file-hier-part = ( "//" auth-path )
/ local-path
auth-path = [ file-auth ] path-absolute
local-path = path-absolute
file-auth = "localhost"
/ host
The "host" is the fully qualified domain name of the system on which
the file is accessible. This allows a client on another system to
know that it cannot access the file system, or perhaps that it needs
to use some other local mechanism to access the file.
As a special case, the "file-auth" rule can match the string
"localhost" that is interpreted as "the machine from which the URI is
being interpreted," exactly as if no authority were present. Some
current usages of the scheme incorrectly interpret all values in the
authority of a file URI, including "localhost", as non-local. Yet
others interpret any value as local, even if the "host" does not
resolve to the local machine. To maximize compatibility with
previous specifications, users MAY choose to include an "auth-path"
with no "file-auth" when creating a URI.
The path component represents the absolute path to the file in the
file system. See <a href="#appendix-D">Appendix D</a> for some discussion of system-specific
concerns including absolute file paths and file system roots.
Some file systems have case-sensitive file naming and some do not.
As such, the file URI scheme supports case sensitivity in order to
retain the case as given. Any transport-related handling of the file
URI scheme MUST retain the case as given. Any mapping to or from a
case-insensitive form is solely the responsibility of the
implementation processing the file URI on behalf of the referenced
file system.
Also see <a href="#appendix-E">Appendix E</a>, which lists some nonstandard syntax variations
that can be encountered in practice.
<span class="grey">Kerwin Standards Track [Page 4]</span><span id="page-5" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
<span class="h2"><a class="selflink" id="section-3" href="#section-3">3</a>. Operations Involving <file> URIs</span>
See the POSIX file and directory operations [<a href="#ref-POSIX" title=""IEEE Std 1003.1, 2013 Edition - Standard for Information Technology-- Portable Operating System Interface (POSIX(R)) Base Specifications, Issue 7"">POSIX</a>] for examples of
standardized operations that can be performed on files.
A file URI can be dependably dereferenced or translated to a local
file path only if it is local. A file URI is considered "local" if
it has no "file-auth", or the "file-auth" is the special string
"localhost", or a fully qualified domain name that resolves to the
machine from which the URI is being interpreted (<a href="#section-2">Section 2</a>).
This specification neither defines nor forbids any set of operations
that might be performed on a file identified by a non-local file URI.
<span class="h2"><a class="selflink" id="section-4" href="#section-4">4</a>. File System Name Encoding</span>
File systems use various encoding schemes to store file and directory
names. Many modern file systems store file and directory names as
arbitrary sequences of octets, in which case the representation as an
encoded string often depends on the user's localization settings or
defaults to UTF-8 [<a href="#ref-STD63" title=""UTF-8, a transformation format of ISO 10646"">STD63</a>].
When a file URI is produced that represents textual data consisting
of characters from the Unicode Standard coded character set
[<a href="#ref-UNICODE" title=""The Unicode Standard, Version 9.0.0"">UNICODE</a>], the data SHOULD be encoded as octets according to the
UTF-8 character encoding scheme [<a href="#ref-STD63" title=""UTF-8, a transformation format of ISO 10646"">STD63</a>] before percent-encoding is
applied (as per <a href="./rfc3986#section-2.5">Section 2.5 of [RFC3986]</a>).
A decision not to use percent-encoded UTF-8 is outside the scope of
this specification. It will typically require the use of heuristics
or explicit knowledge about the way the string will be processed.
<span class="h2"><a class="selflink" id="section-5" href="#section-5">5</a>. Security Considerations</span>
There are many security considerations for URI schemes discussed in
[<a href="./rfc3986" title=""Uniform Resource Identifier (URI): Generic Syntax"">RFC3986</a>].
File access and the granting of privileges for specific operations
are complex topics, and the use of file URIs can complicate the
security model in effect for file privileges.
Historically, user agents have granted content from the file URI
scheme a tremendous amount of privilege. However, granting all local
files such wide privileges can lead to privilege escalation attacks.
Some user agents have had success granting local files directory-
based privileges, but this approach has not been widely adopted.
Other user agents use globally unique identifiers as the origin for
each file URI [<a href="./rfc6454" title=""The Web Origin Concept"">RFC6454</a>], which is the most secure option.
<span class="grey">Kerwin Standards Track [Page 5]</span><span id="page-6" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
Treating a non-local file URI as local, or otherwise attempting to
perform local operations on a non-local URI, can result in security
problems.
File systems typically assign an operational meaning to special
characters, such as the "/", "\", ":", "[", and "]" characters, and
to special device names like ".", "..", "...", "aux", "lpt", etc. In
some cases, merely testing for the existence of such a name will
cause the operating system to pause or invoke unrelated system calls,
leading to significant security concerns regarding denial of service
and unintended data transfer. It would not be possible for this
specification to list all such significant characters and device
names. Implementers should research the reserved names and
characters for the types of storage devices that may be attached to
their application and restrict the use of data obtained from URI
components accordingly.
File systems vary in the way they handle case. Care must be taken to
avoid issues resulting from possibly unexpected aliasing from case-
only differences between file paths or URIs or from mismatched
encodings or Unicode equivalences [<a href="#ref-UAX15" title=""Unicode Standard Annex #15: Unicode Normalization Forms"">UAX15</a>] (see <a href="#section-4">Section 4</a>).
<span class="h2"><a class="selflink" id="section-6" href="#section-6">6</a>. IANA Considerations</span>
This document defines the following permanent URI scheme. The
"Uniform Resource Identifier (URI) Schemes" registry has been updated
accordingly. This registration complies with [<a href="#ref-BCP35" title=""Guidelines and Registration Procedures for URI Schemes"">BCP35</a>].
Scheme name:
file
Status:
permanent
Applications/protocols that use this scheme name:
Commonly used in hypertext documents to refer to files without
depending on network access. Supported by major browsers.
Used in development libraries, such as:
* Windows Shell (PathCreateFromUrl, UrlCreateFromPath)
* libwww-perl - The World-Wide Web library for Perl
Contact:
Applications and Real-Time Area <art@ietf.org>
<span class="grey">Kerwin Standards Track [Page 6]</span><span id="page-7" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
Change Controller:
IETF <ietf@ietf.org>
References:
This RFC
<span class="h2"><a class="selflink" id="section-7" href="#section-7">7</a>. References</span>
<span class="h3"><a class="selflink" id="section-7.1" href="#section-7.1">7.1</a>. Normative References</span>
[<a id="ref-RFC2119">RFC2119</a>] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a>, <a href="./rfc2119">RFC 2119</a>,
DOI 10.17487/RFC2119, March 1997,
<<a href="https://www.rfc-editor.org/info/rfc2119">http://www.rfc-editor.org/info/rfc2119</a>>.
[<a id="ref-RFC3986">RFC3986</a>] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
<a href="./rfc3986">RFC 3986</a>, DOI 10.17487/RFC3986, January 2005,
<<a href="https://www.rfc-editor.org/info/rfc3986">http://www.rfc-editor.org/info/rfc3986</a>>.
[<a id="ref-RFC5234">RFC5234</a>] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, <a href="./rfc5234">RFC 5234</a>,
DOI 10.17487/RFC5234, January 2008,
<<a href="https://www.rfc-editor.org/info/rfc5234">http://www.rfc-editor.org/info/rfc5234</a>>.
[<a id="ref-RFC6454">RFC6454</a>] Barth, A., "The Web Origin Concept", <a href="./rfc6454">RFC 6454</a>,
DOI 10.17487/RFC6454, December 2011,
<<a href="https://www.rfc-editor.org/info/rfc6454">http://www.rfc-editor.org/info/rfc6454</a>>.
[<a id="ref-RFC6874">RFC6874</a>] Carpenter, B., Cheshire, S., and R. Hinden, "Representing
IPv6 Zone Identifiers in Address Literals and Uniform
Resource Identifiers", <a href="./rfc6874">RFC 6874</a>, DOI 10.17487/RFC6874,
February 2013, <<a href="https://www.rfc-editor.org/info/rfc6874">http://www.rfc-editor.org/info/rfc6874</a>>.
[<a id="ref-STD63">STD63</a>] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, <a href="./rfc3629">RFC 3629</a>, November 2003,
<<a href="https://www.rfc-editor.org/info/std63">http://www.rfc-editor.org/info/std63</a>>.
<span class="grey">Kerwin Standards Track [Page 7]</span><span id="page-8" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
<span class="h3"><a class="selflink" id="section-7.2" href="#section-7.2">7.2</a>. Informative References</span>
[<a id="ref-Bash-Tilde">Bash-Tilde</a>]
Free Software Foundation, Inc, "Bash Reference Manual:
Tilde Expansion", September 2016,
<<a href="http://www.gnu.org/software/bash/manual/html_node/Tilde-Expansion.html">http://www.gnu.org/software/bash/manual/html_node/</a>
<a href="http://www.gnu.org/software/bash/manual/html_node/Tilde-Expansion.html">Tilde-Expansion.html</a>>.
[<a id="ref-BCP35">BCP35</a>] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines
and Registration Procedures for URI Schemes", <a href="https://www.rfc-editor.org/bcp/bcp35">BCP 35</a>,
<a href="./rfc7595">RFC 7595</a>, June 2015,
<<a href="https://www.rfc-editor.org/info/bcp35">http://www.rfc-editor.org/info/bcp35</a>>.
[<a id="ref-Bug107540">Bug107540</a>]
Bugzilla@Mozilla, "Bug 107540", October 2001,
<<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=107540">https://bugzilla.mozilla.org/show_bug.cgi?id=107540</a>>.
[<a id="ref-MS-DTYP">MS-DTYP</a>] Microsoft, "Windows Data Types: 2.2.57 UNC", October 2015,
<<a href="http://msdn.microsoft.com/en-us/library/gg465305.aspx">http://msdn.microsoft.com/en-us/library/gg465305.aspx</a>>.
[<a id="ref-POSIX">POSIX</a>] IEEE, "IEEE Std 1003.1, 2013 Edition - Standard for
Information Technology-- Portable Operating System
Interface (POSIX(R)) Base Specifications, Issue 7",
DOI 10.1109/IEEESTD.2013.6506091, April 2013.
[<a id="ref-RFC1630">RFC1630</a>] Berners-Lee, T., "Universal Resource Identifiers in WWW: A
Unifying Syntax for the Expression of Names and Addresses
of Objects on the Network as used in the World-Wide Web",
<a href="./rfc1630">RFC 1630</a>, DOI 10.17487/RFC1630, June 1994,
<<a href="https://www.rfc-editor.org/info/rfc1630">http://www.rfc-editor.org/info/rfc1630</a>>.
[<a id="ref-RFC1738">RFC1738</a>] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform
Resource Locators (URL)", <a href="./rfc1738">RFC 1738</a>, DOI 10.17487/RFC1738,
December 1994, <<a href="https://www.rfc-editor.org/info/rfc1738">http://www.rfc-editor.org/info/rfc1738</a>>.
[<a id="ref-RFC2396">RFC2396</a>] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifiers (URI): Generic Syntax", <a href="./rfc2396">RFC 2396</a>,
DOI 10.17487/RFC2396, August 1998,
<<a href="https://www.rfc-editor.org/info/rfc2396">http://www.rfc-editor.org/info/rfc2396</a>>.
[<a id="ref-RFC6838">RFC6838</a>] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", <a href="https://www.rfc-editor.org/bcp/bcp13">BCP 13</a>,
<a href="./rfc6838">RFC 6838</a>, DOI 10.17487/RFC6838, January 2013,
<<a href="https://www.rfc-editor.org/info/rfc6838">http://www.rfc-editor.org/info/rfc6838</a>>.
[<a id="ref-UAX15">UAX15</a>] Davis, M., Ed. and K. Whistler, Ed., "Unicode Standard
Annex #15: Unicode Normalization Forms", February 2016,
<<a href="http://www.unicode.org/reports/tr15/tr15-44.html">http://www.unicode.org/reports/tr15/tr15-44.html</a>>.
<span class="grey">Kerwin Standards Track [Page 8]</span><span id="page-9" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
[<a id="ref-UNICODE">UNICODE</a>] The Unicode Consortium, "The Unicode Standard, Version
9.0.0", ISBN 978-1-936213-13-9, June 2016,
<<a href="http://www.unicode.org/versions/Unicode9.0.0/">http://www.unicode.org/versions/Unicode9.0.0/</a>>.
[<a id="ref-WHATWG-URL">WHATWG-URL</a>]
WHATWG, "URL Living Standard", January 2017,
<<a href="https://url.spec.whatwg.org/">https://url.spec.whatwg.org/</a>>.
[<a id="ref-Win32-Namespaces">Win32-Namespaces</a>]
Microsoft Developer Network Blogs, "Naming Files, Paths,
and Namespaces", June 2013, <<a href="https://msdn.microsoft.com/">https://msdn.microsoft.com/</a>
en-us/library/windows/desktop/aa365247(v=vs.85).aspx>.
[<a id="ref-Zsh-Tilde">Zsh-Tilde</a>]
"The Z Shell Manual: 14.7 Filename Expansion", December
2015, <<a href="http://zsh.sourceforge.net/Doc/Release/Expansion.html#Filename-Expansion">http://zsh.sourceforge.net/Doc/Release/</a>
<a href="http://zsh.sourceforge.net/Doc/Release/Expansion.html#Filename-Expansion">Expansion.html#Filename-Expansion</a>>.
<span class="grey">Kerwin Standards Track [Page 9]</span><span id="page-10" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
<span class="h2"><a class="selflink" id="appendix-A" href="#appendix-A">Appendix A</a>. Differences from Previous Specifications</span>
The syntax definition in <a href="#section-2">Section 2</a> inherits incremental differences
from the general syntax of [<a href="./rfc1738" title=""Uniform Resource Locators (URL)"">RFC1738</a>], as described by <a href="./rfc2396#appendix-G">Appendix G of
[RFC2396]</a> and <a href="./rfc3986#appendix-D">Appendix D of [RFC3986]</a>.
According to the definition in [<a href="./rfc1738" title=""Uniform Resource Locators (URL)"">RFC1738</a>], a file URL always started
with the token "file://", followed by an (optionally blank) host name
and a "/". The syntax given in <a href="#section-2">Section 2</a> makes the entire authority
component, including the double slashes "//", optional.
<span class="h2"><a class="selflink" id="appendix-B" href="#appendix-B">Appendix B</a>. Example URIs</span>
The syntax in <a href="#section-2">Section 2</a> is intended to support file URIs that take
the following forms:
Local files:
o A traditional file URI for a local file with an empty authority.
This is the most common format in use today. For example:
* "file:///path/to/file"
o The minimal representation of a local file with no authority field
and an absolute path that begins with a slash "/". For example:
* "file:/path/to/file"
Non-local files:
o A non-local file with an explicit authority. For example:
* "file://host.example.com/path/to/file"
<span class="h2"><a class="selflink" id="appendix-C" href="#appendix-C">Appendix C</a>. Similar Technologies</span>
o The WHATWG URL specification [<a href="#ref-WHATWG-URL">WHATWG-URL</a>] defines browser behavior
for a variety of inputs, including file URIs. As a living
document, it changes to reflect updates in browser behavior. As a
result, its algorithms and syntax definitions may or may not be
consistent with this specification. Implementors should be aware
of this possible discrepancy if they expect to share file URIs
with browsers that follow the WHATWG specification.
o The Universal Naming Convention (UNC) [<a href="#ref-MS-DTYP" title=""Windows Data Types: 2.2.57 UNC"">MS-DTYP</a>] defines a string
format that can perform a similar role to the file URI scheme in
describing the location of files, except that files located by UNC
filespace selector strings are typically stored on a remote
<span class="grey">Kerwin Standards Track [Page 10]</span><span id="page-11" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
machine and accessed using a network protocol. <a href="#appendix-E.3">Appendix E.3</a> lists
some ways in which UNC filespace selector strings are currently
made to interoperate with the file URI scheme.
o The Microsoft Windows API defines Win32 Namespaces
[<a href="#ref-Win32-Namespaces">Win32-Namespaces</a>] for interacting with files and devices using
Windows API functions. These namespaced paths are prefixed by
"\\?\" for Win32 File Namespaces and "\\.\" for Win32 Device
Namespaces. There is also a special case for UNC file paths in
Win32 File Namespaces, referred to as "Long UNC", using the prefix
"\\?\UNC\". This specification does not define a mechanism for
translating namespaced paths to or from file URIs.
<span class="h2"><a class="selflink" id="appendix-D" href="#appendix-D">Appendix D</a>. System-Specific Operations</span>
This appendix is not normative. It highlights some observed
behaviors and provides system-specific guidance for interacting with
file URIs and paths. This is not an exhaustive list of operating or
file systems; rather, it is intended to illustrate certain types of
interactions that might be encountered.
<span class="h3"><a class="selflink" id="appendix-D.1" href="#appendix-D.1">D.1</a>. POSIX Systems</span>
In a POSIX file system, the root of the file system is represented as
a directory with a zero-length name, usually written as "/"; the
presence of this root in a file URI can be taken as given by the
initial slash in the "path-absolute" rule.
Common UNIX shells such as the Bourne-Again SHell (bash) and Z SHell
(zsh) provide a function known as "tilde expansion" [<a href="#ref-Bash-Tilde">Bash-Tilde</a>] or
"filename expansion" [<a href="#ref-Zsh-Tilde">Zsh-Tilde</a>], where a path that begins with a
tilde character "~" can be expanded out to a special directory name.
No such facility exists using the file URI scheme; a tilde in a file
URI is always just a tilde.
<span class="h3"><a class="selflink" id="appendix-D.2" href="#appendix-D.2">D.2</a>. DOS- and Windows-Like Systems</span>
When mapping a DOS- or Windows-like file path to a file URI, the
drive letter (e.g., "c:") is typically mapped into the first path
segment.
<a href="#appendix-E">Appendix E</a> lists some nonstandard techniques for interacting with
DOS- or Windows-like file paths and URIs.
<span class="grey">Kerwin Standards Track [Page 11]</span><span id="page-12" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
<span class="h3"><a class="selflink" id="appendix-D.3" href="#appendix-D.3">D.3</a>. Mac OS X Systems</span>
The Hierarchical File System Plus (HFS+) uses a nonstandard
normalization form, similar to Normalization Form D [<a href="#ref-UAX15" title=""Unicode Standard Annex #15: Unicode Normalization Forms"">UAX15</a>]. Take
care when transforming HFS+ file paths to and from URIs (<a href="#section-4">Section 4</a>).
<span class="h3"><a class="selflink" id="appendix-D.4" href="#appendix-D.4">D.4</a>. OpenVMS Files-11 Systems</span>
When mapping a Virtual Memory System (VMS) file path to a file URI,
the device name is mapped into the first path segment. Note that the
dollars sign "$" is a reserved character per the definition in
<a href="./rfc3986#section-2.2">Section 2.2 of [RFC3986]</a>, so it should be percent-encoded if present
in the device name.
If the VMS file path includes a node reference, that reference is
used as the authority. Where the original node reference includes a
user name and password in an access control string, they can be
transcribed into the authority using the nonstandard syntax extension
in <a href="#appendix-E.1">Appendix E.1</a>.
<span class="h2"><a class="selflink" id="appendix-E" href="#appendix-E">Appendix E</a>. Nonstandard Syntax Variations</span>
These variations may be encountered by existing usages of the file
URI scheme but are not supported by the normative syntax of
<a href="#section-2">Section 2</a>.
This appendix is not normative.
<span class="h3"><a class="selflink" id="appendix-E.1" href="#appendix-E.1">E.1</a>. User Information</span>
It might be necessary to include user information such as a user name
in a file URI, for example, when mapping a VMS file path with a node
reference that includes an access control string.
To allow user information to be included in a file URI, the "file-
auth" rule in <a href="#section-2">Section 2</a> can be replaced with the following:
file-auth = "localhost"
/ [ userinfo "@" ] host
This uses the "userinfo" rule from [<a href="./rfc3986" title=""Uniform Resource Identifier (URI): Generic Syntax"">RFC3986</a>].
As discussed in the HP OpenVMS Systems Documentation
<<a href="http://h71000.www7.hp.com/doc/84final/ba554_90015/ch03s09.html">http://h71000.www7.hp.com/doc/84final/ba554_90015/ch03s09.html</a>>,
"access control strings include sufficient information to allow
someone to break in to the remote account, [therefore] they create
serious security exposure." In a similar vein, the presence of a
<span class="grey">Kerwin Standards Track [Page 12]</span><span id="page-13" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
password in a "user:password" userinfo field is deprecated by
[<a href="./rfc3986" title=""Uniform Resource Identifier (URI): Generic Syntax"">RFC3986</a>]. Take care when dealing with information that can be used
to identify a user or grant access to a system.
<span class="h3"><a class="selflink" id="appendix-E.2" href="#appendix-E.2">E.2</a>. DOS and Windows Drive Letters</span>
On Windows- or DOS-like file systems, an absolute file path can begin
with a drive letter. To facilitate this, the "local-path" rule in
<a href="#section-2">Section 2</a> can be replaced with the following:
local-path = [ drive-letter ] path-absolute
drive-letter = ALPHA ":"
The "ALPHA" rule is defined in [<a href="./rfc5234" title=""Augmented BNF for Syntax Specifications: ABNF"">RFC5234</a>].
This is intended to support the minimal representation of a local
file in a DOS- or Windows-like environment, with no authority field
and an absolute path that begins with a drive letter. For example:
o "file:c:/path/to/file"
URIs of the form "file:///c:/path/to/file" are already supported by
the "path-absolute" rule.
Note that comparison of drive letters in DOS or Windows file paths is
case insensitive. In some usages of file URIs, drive letters are
canonicalized by converting them to uppercase; other usages treat
URIs that differ only in the case of the drive letter as identical.
<span class="h4"><a class="selflink" id="appendix-E.2.1" href="#appendix-E.2.1">E.2.1</a>. Relative Resolution</span>
To mimic the behavior of DOS- or Windows-like file systems, relative
references beginning with a slash "/" can be resolved relative to the
drive letter when present; resolution of ".." dot segments (per
<a href="./rfc3986#section-5.2.4">Section 5.2.4 of [RFC3986]</a>) can be modified to not ever overwrite the
drive letter.
For example:
base URI: file:///c:/path/to/file.txt
rel. ref.: /some/other/thing.bmp
resolved: file:///c:/some/other/thing.bmp
base URI: file:///c:/foo.txt
rel. ref.: ../bar.txt
resolved: file:///c:/bar.txt
<span class="grey">Kerwin Standards Track [Page 13]</span><span id="page-14" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
A relative reference starting with a drive letter would be
interpreted by a generic URI parser as a URI with the drive letter as
its scheme. Instead, such a reference ought to be constructed with a
leading slash "/" character (e.g., "/c:/foo.txt").
Relative references with a drive letter followed by a character other
than a slash (e.g., "/c:bar/baz.txt" or "/c:../foo.txt") might not be
accepted as dereferenceable URIs in DOS- or Windows-like systems.
<span class="h4"><a class="selflink" id="appendix-E.2.2" href="#appendix-E.2.2">E.2.2</a>. Vertical Line Character</span>
Historically, some usages of file URIs have included a vertical line
character "|" instead of a colon ":" in the drive letter construct.
[<a href="./rfc3986" title=""Uniform Resource Identifier (URI): Generic Syntax"">RFC3986</a>] forbids the use of the vertical line; however, it may be
necessary to interpret or update old URIs.
For interpreting such URIs, the "auth-path" and "local-path" rules in
<a href="#section-2">Section 2</a> and the "drive-letter" rule above can be replaced with the
following:
auth-path = [ file-auth ] path-absolute
/ [ file-auth ] file-absolute
local-path = [ drive-letter ] path-absolute
/ file-absolute
file-absolute = "/" drive-letter path-absolute
drive-letter = ALPHA ":"
/ ALPHA "|"
This is intended to support regular DOS or Windows file URIs with
vertical line characters in the drive letter construct. For example:
o "file:///c|/path/to/file"
o "file:/c|/path/to/file"
o "file:c|/path/to/file"
To update such an old URI, replace the vertical line "|" with a colon
":".
<span class="grey">Kerwin Standards Track [Page 14]</span><span id="page-15" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
<span class="h3"><a class="selflink" id="appendix-E.3" href="#appendix-E.3">E.3</a>. UNC Strings</span>
Some usages of the file URI scheme allow UNC filespace selector
strings [<a href="#ref-MS-DTYP" title=""Windows Data Types: 2.2.57 UNC"">MS-DTYP</a>] to be translated to and from file URIs, either by
mapping the equivalent segments of the two schemes (hostname to
authority, sharename+objectnames to path), or by mapping the entire
UNC string to the path segment of a URI.
<span class="h4"><a class="selflink" id="appendix-E.3.1" href="#appendix-E.3.1">E.3.1</a>. <file> URI with Authority</span>
The following is an algorithmic description of the process of
translating a UNC filespace selector string to a file URI by mapping
the equivalent segments of the two schemes:
1. Initialize the URI with the "file:" scheme identifier.
2. Append the authority:
1. Append the "//" authority sigil to the URI.
2. Append the host-name field of the UNC string to the URI.
3. Append the share-name:
1. Transform the share-name to a path segment (see <a href="./rfc3986#section-3.3">Section 3.3
of [RFC3986]</a>) to conform to the encoding rules of <a href="./rfc3986#section-2">Section 2
of [RFC3986]</a>.
2. Append a delimiting slash character "/" and the transformed
segment to the URI.
4. For each object-name:
1. Transform the objectname to a path segment as above.
The colon character ":" is allowed as a delimiter before
stream-name and stream-type in the file-name, if present.
2. Append a delimiting slash character "/" and the transformed
segment to the URI.
For example, the UNC String:
UNC String: \\host.example.com\Share\path\to\file.txt
would be transformed into the URI:
URI: file://host.example.com/Share/path/to/file.txt
<span class="grey">Kerwin Standards Track [Page 15]</span><span id="page-16" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
The inverse algorithm for translating a file URI to a UNC filespace
selector string is left as an exercise for the reader.
<span class="h4"><a class="selflink" id="appendix-E.3.2" href="#appendix-E.3.2">E.3.2</a>. <file> URI with UNC Path</span>
It is common to encounter file URIs that encode entire UNC strings in
the path, usually with all backslash "\" characters replaced with
slashes "/".
To interpret such URIs, the "auth-path" rule in <a href="#section-2">Section 2</a> can be
replaced with the following:
auth-path = [ file-auth ] path-absolute
/ unc-authority path-absolute
unc-authority = 2*3"/" file-host
file-host = inline-IP / IPv4address / reg-name
inline-IP = "%5B" ( IPv6address / IPvFuture ) "%5D"
This syntax uses the "IPv4address", "IPv6address", "IPvFuture", and
"reg-name" rules from [<a href="./rfc3986" title=""Uniform Resource Identifier (URI): Generic Syntax"">RFC3986</a>].
Note that the "file-host" rule is the same as "host" but with
percent-encoding applied to "[" and "]" characters.
This extended syntax is intended to support URIs that take the
following forms, in addition to those in <a href="#appendix-B">Appendix B</a>:
Non-local files:
o The representation of a non-local file with an empty authority and
a complete (transformed) UNC string in the path. For example:
* "file:////host.example.com/path/to/file"
o As above, with an extra slash between the empty authority and the
transformed UNC string, as per the syntax defined in [<a href="./rfc1738" title=""Uniform Resource Locators (URL)"">RFC1738</a>].
For example:
* "file://///host.example.com/path/to/file"
This representation is notably used by the Firefox web browser.
See Bugzilla#107540 [<a href="#ref-Bug107540">Bug107540</a>].
It also further limits the definition of a "local file URI" by
excluding any file URI with a path that encodes a UNC string.
<span class="grey">Kerwin Standards Track [Page 16]</span><span id="page-17" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
<span class="h3"><a class="selflink" id="appendix-E.4" href="#appendix-E.4">E.4</a>. Backslash as Separator</span>
Historically, some usages have copied entire file paths into the path
components of file URIs. Where DOS or Windows file paths were thus
copied, the resulting URI strings contained unencoded backslash "\"
characters, which are forbidden by both [<a href="./rfc1738" title=""Uniform Resource Locators (URL)"">RFC1738</a>] and [<a href="./rfc3986" title=""Uniform Resource Identifier (URI): Generic Syntax"">RFC3986</a>].
It may be possible to translate or update such an invalid file URI by
replacing all backslashes "\" with slashes "/" if it can be
determined with reasonable certainty that the backslashes are
intended as path separators.
<span class="h2"><a class="selflink" id="appendix-F" href="#appendix-F">Appendix F</a>. Collected Nonstandard Rules</span>
Here are the collected syntax rules for all optional appendices,
presented for convenience. This collected syntax is not normative.
file-URI = file-scheme ":" file-hier-part
file-scheme = "file"
file-hier-part = ( "//" auth-path )
/ local-path
auth-path = [ file-auth ] path-absolute
/ [ file-auth ] file-absolute
/ unc-authority path-absolute
local-path = [ drive-letter ] path-absolute
/ file-absolute
file-auth = "localhost"
/ [ userinfo "@" ] host
unc-authority = 2*3"/" file-host
file-host = inline-IP / IPv4address / reg-name
inline-IP = "%5B" ( IPv6address / IPvFuture ) "%5D"
file-absolute = "/" drive-letter path-absolute
drive-letter = ALPHA ":"
/ ALPHA "|"
<span class="grey">Kerwin Standards Track [Page 17]</span><span id="page-18" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
This collected syntax is intended to support file URIs that take the
following forms:
Local files:
o A traditional file URI for a local file with an empty authority.
For example:
* "file:///path/to/file"
o The minimal representation of a local file with no authority field
and an absolute path that begins with a slash "/". For example:
* "file:/path/to/file"
o The minimal representation of a local file in a DOS- or Windows-
based environment with no authority field and an absolute path
that begins with a drive letter. For example:
* "file:c:/path/to/file"
o Regular DOS or Windows file URIs with vertical line characters in
the drive letter construct. For example:
* "file:///c|/path/to/file"
* "file:/c|/path/to/file"
* "file:c|/path/to/file"
Non-local files:
o The representation of a non-local file with an explicit authority.
For example:
* "file://host.example.com/path/to/file"
o The "traditional" representation of a non-local file with an empty
authority and a complete (transformed) UNC string in the path.
For example:
* "file:////host.example.com/path/to/file"
o As above, with an extra slash between the empty authority and the
transformed UNC string. For example:
* "file://///host.example.com/path/to/file"
<span class="grey">Kerwin Standards Track [Page 18]</span><span id="page-19" ></span>
<span class="grey"><a href="./rfc8089">RFC 8089</a> "file" Scheme February 2017</span>
Acknowledgements
Contributions from many members of the IETF and W3C communities --
notably Dave Crocker, Graham Klyne, Tom Petch, and John Klensin --
are greatly appreciated.
Additional thanks to Dave Risney, author of the informative IEBlog
article <<a href="http://blogs.msdn.com/b/ie/archive/2006/12/06/file-uris-in-windows.aspx">http://blogs.msdn.com/b/ie/archive/2006/12/06/file-uris-in-</a>
<a href="http://blogs.msdn.com/b/ie/archive/2006/12/06/file-uris-in-windows.aspx">windows.aspx</a>>, and Dave Thaler for their early comments and
suggestions; and to Paul Hoffman, whose earlier work served as an
inspiration for this undertaking.
Author's Address
Matthew Kerwin
Queensland University of Technology
Victoria Park Road
Kelvin Grove, QLD 4059
Australia
Email: [email protected]
Kerwin Standards Track [Page 19]
Annotations
Select text to annotate