package eio

Build not yet checked
  1. Overview
  2. Docs
Effect-based direct-style IO API for OCaml

Install

dune-project
 Dependency

Authors

Maintainers

Sources

eio-1.7.tbz
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:a is relative to drive C's current directory. Only the current drive's is known here, so for other drives we use the root.
  • Reserved names such as NUL and COM1 name devices in any Win32 directory. to_win32 keeps paths using them verbatim.
  • Names are case-insensitive, but beneath only 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 step appends step to dir using "\\" as the directory separator, unless dir already 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.
include Eio.Fs.Pi.PATH
Sourceval split : Eio.Fs.path -> (Eio.Fs.path * string) option

The implementation of Eio.Path.split.

The implementation of Eio.Path.(/).

Sourcetype kind = [
  1. | `Relative
    (*

    a\b, relative to the current directory.

    *)
  2. | `Rooted
    (*

    \a, relative to the root of the current drive.

    *)
  3. | `Drive_relative
    (*

    C:a, relative to drive C's current directory.

    *)
  4. | `Absolute
    (*

    C:\a, a fully qualified DOS path.

    *)
  5. | `Unc
    (*

    \\server\share\a.

    *)
  6. | `Device
    (*

    \\.\pipe\a, a device path, which is normalised.

    *)
  7. | `Verbatim
    (*

    \\?\C:\a or \??\C:\a, which is not normalised. Only these exact prefixes are verbatim: //?/C:/a is a device path.

    *)
]

The type of a path, identified from its prefix as described in Identify the path.

Sourceval pp_kind : kind Fmt.t
Sourceval classify : string -> kind

classify p is the type of path p.

Sourceval is_relative : string -> bool

is_relative p is classify p = `Relative.

Sourceval dirname : string -> string

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

Sourceval basename : string -> string

basename p is the final component of p. It is p itself when p has no directory part, and "." when p is empty.

Sourceval to_nt : cwd:string -> string -> string

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.

Sourceval to_win32 : string -> string

to_win32 p is the verbatim path p without its prefix.

Sourceval relative : string -> string option

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.

Sourceval beneath : root:string -> string -> string option

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.