package eio
Build not yet checkedInstall
dune-project
Dependency
Authors
Maintainers
Sources
sha256=a9771c0d7f4d9d9fe17badd3d147c96e85f34410ab252119ade2a407ab41ccb5
sha512=a6e0bfdc7d48886b613ba70004a46309e4162f6109d9603fbe9d70dafcc4fad3cd2382998685b1db4bb8e5bf0bbc89371b9023644d3bfaa80757e5e6939c6d8e
doc/eio.utils/Eio_utils/Nt_path/index.html
Module Eio_utils.Nt_pathSource
Windows path syntax.
In Windows, programs usually use Win32 paths, which the userspace maps to NT object-manager paths for kernel (e.g. C:\a becomes \??\C:\a). For sandboxing purposes, Eio opens files using NtCreateFile and handles the mapping itself, following Microsoft docs on Naming Files, Paths, and Namespaces and Microsoft file path formats on Windows systems, except where noted:
- Both backslash and slash are separators, except in verbatim paths (
\\?\...or\??\...).
.and..are resolved, and trailing dots and spaces trimmed, as in Win32. So, as in Win32, a name ending in a dot or space (such as...) can only be reached with a verbatim path. Unlike Win32, a trailing separator is dropped.
- A path such as
C:ais relative to driveC's current directory. Only the current drive's is known here, so for other drives we use the root.
- Reserved names such as
NULandCOM1name devices in any Win32 directory.to_win32keeps paths using them verbatim.
- Names are case-insensitive, but
beneathonly ignores ASCII case and doesn't understand short (8.3) names yet. Unknown ones are rejected though, so this should be safe for sandboxing purposes.
- Paths may be longer than
MAX_PATH. For Win32 paths we assume the application enables long paths.
- Reserved characters (such as
*,?and control characters) are left for the file system to reject. A:may also name an alternate data stream.
For Eio.Path:
join dir stepappendssteptodirusing"\\"as the directory separator, unlessdiralready ends in a separator. After a bare drive (C:) no separator is added, to keep the path drive-relative.
split: Volume prefixes (C:,\\server\share,\\?\...,\??\...) are never split.
type kind = [ | `Relative(*
*)a\b, relative to the current directory.| `Rooted(*
*)\a, relative to the root of the current drive.| `Drive_relative(*
*)C:a, relative to driveC's current directory.| `Absolute(*
*)C:\a, a fully qualified DOS path.| `Unc(*
*)\\server\share\a.| `Device(*
*)\\.\pipe\a, a device path, which is normalised.| `Verbatim(*
*)\\?\C:\aor\??\C:\a, which is not normalised. Only these exact prefixes are verbatim://?/C:/ais a device path.
]The type of a path, identified from its prefix as described in Identify the path.
is_relative p is classify p = `Relative.
dirname p is the directory part of p. It is "." when p names something in the current directory, and also when p has no parent to name (e.g. an empty path, a bare volume (C:) and a root (\\server\share)).
basename p is the final component of p. It is p itself when p has no directory part, and "." when p is empty.
to_nt ~cwd path is the NT object-manager form of the Win32 path path, resolved against cwd and normalised as described above. Verbatim paths are passed through unchanged.
to_win32 p is the verbatim path p without its prefix.
Normalise a handle-relative path, preserving literal names (including dots and spaces). Resolve . and .., but reject absolute paths and any .. that would leave the starting directory, even temporarily.
Convert a caller's Win32 link target to NT form, preserving relative and rooted names literally. Other paths are converted using to_nt.
Resolve a raw link target against its parent. Relative targets preserve literal names and resolve dot navigation; invalid targets return None. A relative parent also prevents climbing above its starting directory. With root, return a relative path beneath that real directory, checking absolute targets with beneath. A rooted target uses root's volume when parent is relative. Without root, absolute NT targets are unchanged. Relative targets ending in names made only of dots and spaces (other than . and ..) are refused, as Windows interprets them differently for file and directory links.
beneath ~root p compares absolute NT paths and returns the literal suffix below root, or None if it is outside or contains dot navigation. This does no Win32 normalisation. root must be the directory's real path.