14.1.4 Windows Path Conventions

In general, a Windows pathname consists of an optional drive specifier and a drive-specific path. A Windows path can be absolute but still relative to the current drive; such paths start with a / or \ separator and are not UNC paths or paths that start with \\?\.

A path that starts with a drive specification is complete. Roughly, a drive specification is either a Roman letter followed by a colon, a UNC path of the form \\machine\volume›, or a \\?\ form followed by something other than REL\element›, or RED\element›. (Variants of \\?\ paths are described further below.)

Racket fails to implement the usual Windows path syntax in one way. Outside of Racket, a pathname "C:rant.txt" can be a drive-specific relative path. That is, it names a file "rant.txt" on drive "C:", but the complete path to the file is determined by the current working directory for drive "C:". Racket does not support drive-specific working directories (only a working directory across all drives, as reflected by the current-directory parameter). Consequently, Racket implicitly converts a path like "C:rant.txt" into "C:\rant.txt".

Otherwise, Racket follows standard Windows path conventions, but also adds \\?\REL and \\?\RED conventions to deal with paths inexpressible in the standard convention, plus conventions to deal with excessive \s in \\?\ paths.

In the following, ‹letter› stands for a Roman letter (case does not matter), ‹machine› stands for any sequence of characters that does not include \ or / and is not ?, ‹volume› stands for any sequence of characters that does not include \ or / , and ‹element› stands for any sequence of characters that does not include \.

Three additional Racket-specific rules provide meanings to character sequences that are otherwise ill-formed as Windows paths:

Outside of Racket, except for \\?\ paths, pathnames are typically limited to 259 characters. Racket internally converts pathnames to \\?\ form as needed to avoid this limit. The operating system cannot access files through \\?\ paths that are longer than 32,000 characters or so.

Where the above descriptions says “character,” substitute “byte” for interpreting byte strings as paths. The encoding of Windows paths into bytes preserves ASCII characters, and all special characters mentioned above are ASCII, so all of the rules are the same.

Beware that the \ path separator is an escape character in Racket strings. Thus, the path \\?\REL\..\\.. as a string must be written "\\\\?\\REL\\..\\\\..".

A path that ends with a directory separator syntactically refers to a directory. In addition, a path syntactcially refers to a directory if its last element is a same-directory or up-directory indicator (not quoted by a \\?\ form), or if it refers to a root.

Windows paths are cleansed as follows: In paths that start \\?\, redundant \s are removed, an extra \ is added in a \\?\REL if an extra one is not already present to separate up-directory indicators from literal path elements, and an extra \ is similarly added after \\?\RED if an extra one is not already present. When \\?\ acts as the root and the path contains, to additional /s (which might otherwise be redundant) are included after the root. For other paths, multiple /s are converted to single /s (except at the beginning of a shared folder name), a / is inserted after the colon in a drive specification if it is missing.

For (bytes->path-element bstr), /s, colons, trailing dots, trailing whitespace, and special device names (e.g., “aux”) in bstr are encoded as a literal part of the path element by using a \\?\REL prefix. The bstr argument must not contain a \, otherwise the exn:fail:contract exception is raised.

For (path-element->bytes path) or (path-element->string path), if the byte-string form of path starts with a \\?\REL, the prefix is not included in the result.

For (build-path base-path sub-path ...), trailing spaces and periods are removed from the last element of base-path and all but the last sub-path (unless the element consists of only spaces and peroids), except for those that start with \\?\. If base-path starts \\?\, then after each non-\\?\REL\ and non-\\?\RED\ sub-path is added, all /s in the addition are converted to \s, multiple consecutive \s are converted to a single \, added . elements are removed, and added .. elements are removed along with the preceding element; these conversions are not performed on the original base-path part of the result or on any \\?\REL\ or \\?\RED\ or sub-path. If a \\?\REL\ or \\?\RED\ sub-path is added to a non-\\?\ base-path, the base-path (with any additions up to the \\?\REL\ or \\?\RED\ sub-path) is simplified and converted to a \\?\ path. In other cases, a \ may be added or removed before combining paths to avoid changing the root meaning of the path (e.g., combining //x and y produces /x/y, because //x/y would be a UNC path instead of a drive-relative path).

For (simplify-path path use-filesystem?), path is expanded, and if path does not start with \\?\, trailing spaces and periods are removed, a / is inserted after the colon in a drive specification if it is missing, and a \ is inserted after \\?\ as a root if there are elements and no extra \ already. Otherwise, if no indicators or redundant separators are in path, then path is returned.

For (split-path path) producing base, name, and must-be-dir?, splitting a path that does not start with \\?\ can produce parts that start with \\?\. For example, splitting C:/x~/aux/ produces \\?\C:\x~\ and \\?\REL\\aux; the \\?\ is needed in these cases to preserve a trailing space after x and to avoid referring to the AUX device instead of an "aux" file.