Module Eio_fs_memSource

In-memory Eio.Fs filesystem.

For hermetic tests: code reads and writes files through Eio.Path without touching the host's disk. Each call to v, load, Crunch.load or run makes a filesystem of its own: two of them share no file. The library eio-fs.chaos tests programs and filesystems with it.

Where Linux, macOS and Windows differ, the filesystem follows one, chosen by ?os: `Linux, the default, `Macos or `Windows. The choice comes from the argument, never from the host, so a test sees the same filesystem on every machine. macOS and Windows list what `Macos and `Windows change. Its answers are those recorded on Linux and macOS through the kernel and eio_posix, and on Windows through eio_windows, and Eio_fs_chaos.conformance checks them.

An entry's stat carries what Linux gives on tmpfs. Its times come from the clock given to v, and stay at 0. without one; under Eio_fs_chaos.run they come from the run's clock. A write, a truncation and an open that truncates move a file's mtime and ctime. A chmod, a chown and a rename move the entry's ctime. Making, removing or renaming an entry moves its directory's mtime and ctime. atime follows relatime, Linux's default: a read, a listing or a link read moves it when it is not past mtime or ctime, or a day after it last moved. dev is the filesystem's own, shared with no other filesystem and no host device. nlink is 2 plus the number of subdirectories for a directory, 1 for anything else, and 0 once its last name is gone. blocks counts the 512-byte blocks of the 4096-byte pages writes put bytes in: a hole, a directory and a link hold none.

A file's bytes live in memory, holes included, and a file holds at most 4 GiB: a write or a truncation past that raises Eio.Fs.error.File_too_large.

Where POSIX systems differ, the filesystem answers under `Linux as Linux does: Eio.Path.unlink of a directory raises the error EISDIR names, not Permission_denied, a positioned write to a file opened to append lands at its end, Eio.Path.chmod ~follow:false on a symbolic link raises the error EOPNOTSUPP names, and a symbolic link to the empty path is refused with Not_found. Under `Macos it answers as macOS does: see macOS. A write of no bytes returns 0 under either, where eio_posix on macOS raises the error EINVAL names from writev(2). Its paths have no native spelling (Eio.Path.native is None). The root v returns stands for Eio.Stdenv.fs: an absolute path or link target resolves from it, as eio_posix resolves one from / through fs. One filesystem may be used from several domains at once.

A path resolves one component at a time, as path_resolution(7) describes: a ".." climbs from the directory the walk has reached, a link's target included, never from a lexical rewrite of the path. A directory opened from the filesystem is confined as eio_posix confines one: an absolute path, an absolute link target and a ".." above that directory are refused with Eio.Fs.Permission_denied, whose message names the path asked for and not where the directory sits.

eio_posix. The filesystem answers as the kernel does, and eio_posix differs from the kernel on a few paths. Code that runs on both should not depend on them:

Permissions. Each operation runs as a user and meets the POSIX rules:

Errors

An error Eio classifies raises the Eio.Fs error of its class: Not_found, Already_exists, Permission_denied, File_too_large, and Symlink for a path through too many links. Every other error is an Eio.Io error of no class, as eio_posix raises it. Each carries Eio_fs, but Symlink, which carries nothing, and the Permission_denied of a confined directory, whose code names the path asked for. Below, "the error EISDIR names" is the one whose Eio_fs names EISDIR's error, "is a directory", and likewise for each errno.

Sourcetype Eio.Exn.Backend.t +=
  1. | Eio_fs of string
    (*

    The backend code of the filesystem's errors: the operation, the error and the path, as "rmdir: directory not empty: /d".

    *)

Users

Sourcetype user = {
  1. uid : int64;
    (*

    The user id, as Eio.File.Stat.t carries it.

    *)
  2. gid : int64;
    (*

    The primary group id.

    *)
  3. groups : int64 list;
    (*

    The supplementary group ids.

    *)
  4. umask : int;
    (*

    The mode bits a new file or directory loses.

    *)
}

The type for the user an in-memory filesystem's operations run as.

Sourceval root : user

root is uid 0, gid 0, no supplementary group and umask 0o022.

Filesystems

Sourceval v : ?os:[< `Linux | `Macos | `Windows ] -> ?user:user -> ?clock:_ Eio.Time.clock -> ?drives:char list -> unit -> [ `Close | Eio.Fs.dir_ty ] Eio.Path.t

v ~os ~user ~clock ~drives () is the root of a fresh, empty filesystem following the kernel os (defaults to `Linux), whose operations run as user (defaults to root), who owns its root directory. Its times are read from clock; without one, they stay at 0.. Under `Windows it has the drives drives (defaults to ['C']), and the root is the first one's, "C:\\"; see Windows. Closing the capability ends the filesystem, as the end of sw ends a network of Eio_net_mem.v: no operation goes through it or its aliases after, and only the directories already opened from it keep their own lifetimes.

Sourceval as_user : user -> 'a Eio.Path.t -> [ `Close | Eio.Fs.dir_ty ] Eio.Path.t

as_user user path is path, an in-memory directory, with its operations run as user. A test sets a tree up as root and runs the code under test as a user. A directory opened from the result shares its descriptor with path's. A wrapper of Eio_fs_chaos over an in-memory directory, such as a run's env#fs, stays the same wrapper, over the directory as user.

  • raises Invalid_argument

    if path is neither an in-memory directory nor such a wrapper.

Sourceval load : ?os:[< `Linux | `Macos | `Windows ] -> ?clock:_ Eio.Time.clock -> ?filter:('a Eio.Path.t -> bool) -> 'a Eio.Path.t -> [ `Close | Eio.Fs.dir_ty ] Eio.Path.t

load ~os ~clock ~filter path is the root of a new in-memory filesystem that answers as os (defaults to `Linux) does, holding a copy of the directory tree at path, at the same path from its root: load (dir / "a/b") holds /a/b. path is followed if it is a symbolic link; the entries below it are copied as they are, a link kept a link. filter (defaults to fun _ -> true) is called on path, then on every path below it, before anything of it is copied: a path for which it is false is not copied, nor anything under it, so a refused path is an empty filesystem. path can be on any filesystem, an in-memory one included. Its times are read from clock, as v reads them: a copy is a new file, made now.

An entry that is neither a regular file, a directory nor a symbolic link is not copied; it is traced with Eio.traceln.

  • raises Eio.Io

    if path is not a directory, if it or an entry under it cannot be read, or if a regular file is replaced between the stat that found it and the open that copies it: that open does not follow a link.

Sourcemodule Crunch : sig ... end

Directory trees embedded in an executable, loaded as load loads a copy.

The type for the standard environment run passes on: an in-memory filesystem and current directory.

Sourceval run : ?os:[< `Linux | `Macos | `Windows ] -> ?user:user -> ?clock:_ Eio.Time.clock -> ?drives:char list -> ?cwd:string -> (stdenv -> 'a) -> 'a

run ~os ~user ~clock ~drives ~cwd fn calls fn with a new in-memory filesystem in place of the host's, that answers as os (defaults to `Linux) does, with drives as v takes them, whose times are read from clock, as v reads them. Unlike Eio_main.run, it starts no event loop and installs no effect handler: call it inside one, such as Eio_main.run or Eio_mock.Backend.run. fn's argument holds the root and the current directory of the new filesystem. The current directory is the directory at the absolute path cwd (defaults to "/", or the first drive's root under `Windows), made with its missing ancestors, mode 0o755, before fn runs. Like a process's, it follows that directory through a rename. Both run as user (defaults to root). Root owns the tree and gives user the current directory.

macOS

Under `Macos the filesystem answers as macOS does on its default APFS volume, where it differs from Linux:

Windows

Under `Windows the filesystem answers as a program meets Windows through eio_windows 1.7, on NTFS, where it differs from Linux. Its paths are Win32 paths, which Eio_utils.Nt_path resolves, as eio_windows resolves them, and Eio.Path.( / ), split and native are Nt_path's too:

Not modelled: NTFS's own semantics beyond what eio_windows shows (short 8.3 names, alternate data streams, attributes such as read-only or hidden, junctions, which Eio cannot make, and Developer Mode), UNC and device paths, which raise Permission_denied, each drive's own current directory, which Nt_path does not know either, and the durability of a directory on a power cut: a power cut under `Windows loses what it loses under `Linux, which only a power-cut test on real Windows could check.