Module Eio.Path

Accessing paths on a file-system.

A _ Path.t represents a particular location in some filesystem. It is a pair of a base directory and a relative path from there.

Eio.Stdenv.cwd provides access to the current working directory. For example:

let ( / ) = Eio.Path.( / )

let run dir =
  Eio.Path.save ~create:(`Exclusive 0o600)
    (dir / "output.txt") "the data"

let () =
  Eio_main.run @@ fun env ->
  run (Eio.Stdenv.cwd env)

It is normally not permitted to access anything above the base directory, even by following a symlink. The exception is Stdenv.fs, which provides access to the whole file-system:

Eio.Path.load (fs / "/etc/passwd")
type 'a t = Fs.dir as 'a * Fs.path

An OS directory FD and a path relative to it, for use with e.g. openat(2).

val (/) : 'a t -> string -> 'a t

t / step is t with step appended to t's path, or replacing t's path if step is absolute:

  • (fd, "foo") / "bar" = (fd, "foo/bar")
  • (fd, "foo") / "/bar" = (fd, "/bar")
val pp : _ t Fmt.t

pp formats a _ t as "<label:path>", suitable for logging.

Reading files

val load : _ t -> string

load t returns the contents of the given file.

This is a convenience wrapper around with_open_in.

val open_in : sw:Switch.t -> _ t -> < File.ro ; Flow.close >

open_in ~sw t opens t for reading.

Note: files are always opened in binary mode.

val with_open_in : _ t -> (< File.ro ; Flow.close > -> 'a) -> 'a

with_open_in is like open_in, but calls fn flow with the new flow and closes it automatically when fn returns (if it hasn't already been closed by then).

val with_lines : _ t -> (string Stdlib.Seq.t -> 'a) -> 'a

with_lines t fn is a convenience function for streaming the lines of the file.

It uses Buf_read.lines.

Writing files

val save : ?append:bool -> create:Fs.create -> _ t -> string -> unit

save t data ~create writes data to t.

This is a convenience wrapper around with_open_out.

val open_out : sw:Switch.t -> ?append:bool -> create:Fs.create -> _ t -> < File.rw ; Flow.close >

open_out ~sw t opens t for reading and writing.

Note: files are always opened in binary mode.

  • parameter append

    Open for appending: always write at end of file.

  • parameter create

    Controls whether to create the file, and what permissions to give it if so.

val with_open_out : ?append:bool -> create:Fs.create -> _ t -> (< File.rw ; Flow.close > -> 'a) -> 'a

with_open_out is like open_out, but calls fn flow with the new flow and closes it automatically when fn returns (if it hasn't already been closed by then).

Directories

val mkdir : perm:File.Unix_perm.t -> _ t -> unit

mkdir ~perm t creates a new directory t with permissions perm.

val open_dir : sw:Switch.t -> _ t -> < Fs.dir ; Flow.close > t

open_dir ~sw t opens t.

This can be passed to functions to grant access only to the subtree t.

val with_open_dir : _ t -> (< Fs.dir ; Flow.close > t -> 'a) -> 'a

with_open_dir is like open_dir, but calls fn dir with the new directory and closes it automatically when fn returns (if it hasn't already been closed by then).

val read_dir : _ t -> string list

read_dir t reads directory entries for t.

The entries are sorted using String.compare.

Note: The special Unix entries "." and ".." are not included in the results.

Other

unlink t removes directory entry t.

Note: this cannot be used to unlink directories. Use rmdir for directories.

val rmdir : _ t -> unit

rmdir t removes directory entry t. This only works when the entry is itself a directory.

Note: this usually requires the directory to be empty.

val rename : _ t -> _ t -> unit

rename old_t new_t atomically unlinks old_t and links it as new_t.

If new_t already exists, it is atomically replaced.