package eio

  1. Overview
  2. Docs
Effect-based direct-style IO API for OCaml

Install 

dune-project
 Dependency

github.com Readme Changelog ISC License Edit opam file Versions (19)

Authors

  1. A
    Anil Madhavapeddy
  2. T
    Thomas Leonard

Maintainers

  1. A
    anil@recoil.org

Sources

eio-0.11.tbz
sha256=0c33742074562631677886f4fe4a02f9672cec94297ff85c2ed854db5baa71aa
sha512=590843cb5fb3906fd5ab9911d29206172d164a53c48e635871a23c95d4cdce8ae0999480471187fdddee8c9c523148911ca140feabde6a826c317671a3b33090

doc/eio/Eio/Path/index.html

Module Eio.PathSource

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")
Sourcetype '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).

Sourceval (/) : '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")
Sourceval pp : _ t Fmt.t

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

Reading files

Sourceval load : _ t -> string

load t returns the contents of the given file.

This is a convenience wrapper around with_open_in.

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

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

Sourceval with_lines : _ t -> (string 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

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

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

Sourceval 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

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

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

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

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

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

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

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