Module Os.Dir

Directory operations.

This module operates on directories, most functions error if they are applied to other file kinds.

Existence

val exists : Fpath.t -> (bool, string) Stdlib.result

exists dir is Ok true if dir is a directory in the file system and Ok false otherwise. Symbolic links are followed.

val must_exist : Fpath.t -> (unit, string) Stdlib.result

must_exist dir is Ok () if dir is a directory in the file system and an error otherwise. Symbolic links are followed.

Creating

val create : ?⁠mode:int -> make_path:bool -> Fpath.t -> (bool, string) Stdlib.result

create ~mode ~make_path dir creates the directory dir.

  • mode are the file permission of dir. They default to 0o755 (readable and traversable by everyone, writeable by the user).
  • If make_path is true and the parent directory of p does not exist the whole path to the parent is created as needed with permission 0o755 (readable and traversable by everyone, writable by the user)

The result is:

  • Ok true if dir did not exist and was created.
  • Ok false if dir did exist as (possibly a symlink to) a directory. In this case the mode of dir and any other directory is kept unchanged.
  • Error _ otherwise and in particular if dir exists as a non-directory.

Contents

val fold : ?⁠rel:bool -> ?⁠dotfiles:bool -> ?⁠follow_symlinks:bool -> ?⁠prune:(Unix.stats -> string -> Fpath.t -> bool) -> recurse:bool -> (Unix.stats -> string -> Fpath.t -> 'a -> 'a) -> Fpath.t -> 'a -> ('a, string) Stdlib.result

fold ~rel ~dotfiles ~follow_symlinks ~prune ~recurse f dir acc folds f over the contents of dir starting with acc. If dir does not exist the function errors.

  • f st name p acc is called with each path p folded over with st its stat information, name its filename and acc the accumulator.
  • If recurse is true sub-directories dir are folded over recursively modulo prune (see below). If recurse is false only the direct contents of dir is folded over.
  • prune is called only when recurse is true as prune st d with d any sub-directory to be folded over and st its stat information. If the result is true d and its contents are not folded over. Defaults to fun _ _ _ -> false
  • follow_symlinks if true (default), symbolic links are followed. If false symbolic links are not followed and the stat information given to prune and f is given by Path.symlink_stat.
  • If dotfiles is false (default) elements whose filename start with a . are not folded over
  • If rel is false (default) the paths given to f and prune have dir prepended, if true they are relative to dir.

Fold order. The fold order is generally undefined. The only guarantee is that directory paths are folded over before their content.

Warning. Given the raciness of the POSIX file API it cannot be guaranteed that really all existing files will be folded over in presence of other processes.

val fold_files : ?⁠rel:bool -> ?⁠dotfiles:bool -> ?⁠follow_symlinks:bool -> ?⁠prune:(Unix.stats -> string -> Fpath.t -> bool) -> recurse:bool -> (Unix.stats -> string -> Fpath.t -> 'a -> 'a) -> Fpath.t -> 'a -> ('a, string) Stdlib.result

fold_files is like fold but f is only applied to non-directory files.

val fold_dirs : ?⁠rel:bool -> ?⁠dotfiles:bool -> ?⁠follow_symlinks:bool -> ?⁠prune:(Unix.stats -> string -> Fpath.t -> bool) -> recurse:bool -> (Unix.stats -> string -> Fpath.t -> 'a -> 'a) -> Fpath.t -> 'a -> ('a, string) Stdlib.result

fold_dirs is like fold but f is only applied to directory files.

val path_list : Unix.stats -> string -> Fpath.t -> Fpath.t list -> Fpath.t list

path_list is a folding function to get a (reverse w.r.t. list of paths. Paths which are directories satisfy Fpath.is_dir_path.

Copying

val copy : ?⁠rel:bool -> ?⁠atomic:bool -> ?⁠follow_symlinks:bool -> ?⁠prune:(Unix.stats -> string -> Fpath.t -> bool) -> make_path:bool -> recurse:bool -> src:Fpath.t -> Fpath.t -> (unit, string) Stdlib.result

copy ~rel ~atomic ~prune ~follow_symlinks ~make_path ~recurse ~src dst copies the directory src to dst. File modes of src and its contents are preserved in dst. The function errors if dst exists.

  • If recurse is true sub-directories of dir are also copied recursively, unless they are pruned (see below). If false only the files of src are copied modulo prune. FIXME I think this is weird
  • If make_path is true and the parent directory of dst does not exist the whole path to the parent is created as needed with permission 0o755 (readable and traversable by everyone, writable by the user).
  • prune st name p is called on each path p to copy with st its stat information and name its filename. If the function returns true the directory or file is not copied over. Defaults to fun _ _ _ -> false.
  • If follow_symlinks is true (default), symlinks are followed. If false symbolic links are not followed, the actual symlinks are copied and the stat information given to prune is given by Os.Path.symlink_stat.
  • atomic if atomic is true and the function errors then dst should not exist. To write atomically, a temporary directory t in the parent directory of dst is created. On copy success t is renamed to dst. On error t is deleted and dst left intact. This means the user needs write permissions in the parent directory of dst, in practice this is almost always the case but fails for some directories (e.g. writing in /sys on Linux®).
  • If rel is false (default) the paths given to prune have src prepended. If true they are relative to src.

Current working directory (cwd)

val cwd : unit -> (Fpath.t, string) Stdlib.result

cwd () is the current working directory. The resulting path is guaranteed to be absolute.

val set_cwd : Fpath.t -> (unit, string) Stdlib.result

set_cwd dir sets the current working directory to dir.

val with_cwd : Fpath.t -> (unit -> 'a) -> ('a, string) Stdlib.result

with_cwd dir f is f () with the current working directory bound to dir. After the function returns the current working directory is back to its initial value.

Default temporary directory

val default_tmp : unit -> Fpath.t

default_tmp () is a default directory that can be used as a default directory for creating temporary files and directories. If set_default_tmp hasn't been called this is:

  • On POSIX, the value of the TMPDIR environment variable or Fpath.v "/tmp" if the variable is not set or empty.
  • On Windows, the value of the TEMP environment variable or Fpath.v "." if it is not set or empty.
val set_default_tmp : Fpath.t -> unit

set_default_tmp p sets the value returned by default_tmp to p.

Temporary directories

val with_tmp : ?⁠mode:int -> ?⁠make_path:bool -> ?⁠dir:Fpath.t -> ?⁠name:Path.tmp_name -> (Fpath.t -> 'a) -> ('a, string) Stdlib.result

with_tmp ~mode ~make_path ~dir ~name f creates a temporary empty directory t and returns Ok (f t). After the function returns (normally or via an exception) t and its content are deleted.

  • name is used to construct the filename of the directory, see File.tmp_name for details. It defaults to "tmp-%s".
  • dir is the directory in which the temporary file is created. It defaults to Dir.default_tmp ().
  • If make_path is true (default) and dir doesn't exist the whole path to it is created as needed with permission 0o755 (readable and traversable by everyone, writable by the user).
  • mode are the permissions of the temporary directory; they default to 0o700, only readable, writeable and traversable by the user
val tmp : ?⁠mode:int -> ?⁠make_path:bool -> ?⁠dir:Fpath.t -> ?⁠name:Path.tmp_name -> unit -> (Fpath.t, string) Stdlib.result

tmp is like with_tmp except the directory and its content is only deleted at the end of program execution if the client doesn't do it before.

Base directories

The directories returned by these functions are not guaranteed to exist.

val user : unit -> (Fpath.t, string) Stdlib.result

user () is the home directory of the user executing the process. Determined by consulting passwd database with the user if of the process. If this fails falls back to parse a path from the HOME environment variables. On Windows no special fallback is implemented.

val config : unit -> (Fpath.t, string) Stdlib.result

config () is the directory used to store user-specific program configurations. This is in order:

  1. If set the value of XDG_CONFIG_HOME.
  2. If set and on Windows® the value of APPDATA.
  3. If user () is Ok home, Fpath.(home / ".config").
val data : unit -> (Fpath.t, string) Stdlib.result

data () is the directory used to store user-specific program data. This is in order:

  1. If set the value of XDG_DATA_HOME.
  2. If set and on Windows® the value of APPDATA.
  3. If user () is Ok home, Fpath.(home / ".local" / "share").
val cache : unit -> (Fpath.t, string) Stdlib.result

cache () is the directory used to store user-specific non-essential data. This is in order:

  1. If set the value of XDG_CACHE_HOME.
  2. If set and on Windows® the value of %TEMP%
  3. If user () is Ok home, Fpath.(home / ".cache")
val runtime : unit -> (Fpath.t, string) Stdlib.result

runtime () is the directory used to store user-specific runtime files. This is in order:

  1. If set the value of XDG_RUNTIME_HOME.
  2. The value of default_tmp.