Module OS.Dir

Directory operations.

Existence, creation, deletion and contents

val exists : Fpath.t -> (bool, 'e) result

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

val must_exist : Fpath.t -> (Fpath.t, 'e) result

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

val create : ?path:bool -> ?mode:int -> Fpath.t -> (bool, 'e) result

create ~path ~mode dir creates, if needed, the directory dir with file permission mode (defaults 0o755 readable and traversable by everyone, writeable by the user). If path is true (default) intermediate directories are created with the same mode, otherwise missing intermediate directories lead to an error. 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
val delete : ?must_exist:bool -> ?recurse:bool -> Fpath.t -> (unit, 'e) result

delete ~must_exist ~recurse dir deletes the directory dir. If must_exist is true (defaults to false) an error is returned if dir doesn't exist. If recurse is true (default to false) no error occurs if the directory is non-empty: its contents is recursively deleted first.

val contents : ?dotfiles:bool -> ?rel:bool -> Fpath.t -> (Fpath.t list, 'e) result

contents ~dotfiles ~rel dir is the list of directories and files in dir. If rel is true (defaults to false) the resulting paths are relative to dir, otherwise they have dir prepended. See also fold_contents. If dotfiles is false (default) elements that start with a . are omitted.

val fold_contents : ?err:'b Path.fold_error -> ?dotfiles:bool -> ?elements:Path.elements -> ?traverse:Path.traverse -> (Fpath.t -> 'a -> 'a) -> 'a -> Fpath.t -> ('a, 'e) result

fold_contents err dotfiles elements traverse f acc d is:

contents d >>= Path.fold err dotfiles elements traverse f acc

For more details see Folding over file system hierarchies.

Current working directory (cwd)

val current : unit -> (Fpath.t, 'e) result

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

val set_current : Fpath.t -> (unit, 'e) result

set_current dir sets the current working directory to dir.

val with_current : Fpath.t -> ('a -> 'b) -> 'a -> ('b, 'e) result

with_current dir f v is f v with the current working directory bound to dir. After the function returns the current working directory is back to its initial value.

Base directories

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

val expand_tilde : Fpath.t -> (Fpath.t, 'e) result

expand_tilde p expands a tilde-prefixed path p according to the POSIX standard, for example expanding ~ to the result of user (). It returns p unchanged if p is not tilde-prefixed.

On Windows with MSVC++ or MinGW, ~ will still be expanded using the result of user () (which would be the value of USERPROFILE), but ~user is unsupported and will lead to an error.

val user : unit -> (Fpath.t, 'e) result

user () is the home directory of the user executing the process. On Windows with MSVC++ or MinGW, USERPROFILE is consulted. On other operating systems and Windows with Cygwin, HOME is consulted first, and then the passwd database is looked up with the user ID of the process.

val config : unit -> (Fpath.t, 'e) 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, 'e) 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, 'e) 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, 'e) result

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

  1. If set the value of XDG_RUNTIME_DIR.
  2. The value of default_tmp.
val state : unit -> (Fpath.t, 'e) result

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

  1. If set the value of XDG_STATE_DIR.
  2. If user () is Ok home, Fpath.(home / ".local" / "state")

Temporary directories

type tmp_name_pat = (string -> string, Stdlib.Format.formatter, unit, string) Stdlib.format4

The type for temporary directory name patterns. The string format is replaced by random characters.

val tmp : ?mode:int -> ?dir:Fpath.t -> tmp_name_pat -> (Fpath.t, 'e) result

tmp mode dir pat is a new empty directory in dir (defaults to Dir.default_tmp) named according to pat and created with permissions mode (defaults to 0o700 only readable and writable by the user). The directory path and its content is deleted at the end of program execution using a Stdlib.at_exit handler.

val with_tmp : ?mode:int -> ?dir:Fpath.t -> tmp_name_pat -> (Fpath.t -> 'a -> 'b) -> 'a -> ('b, 'e) result

with_tmp mode dir pat f v is a new empty directory in dir (defaults to Dir.default_tmp) named according to pat and created with permissions mode (defaults to 0o700 only readable and writable by the user). Returns the value of f tmpdir v with tmpdir the directory path. After the function returns the directory path tmpdir and its content is deleted.

Default temporary directory

val default_tmp : unit -> Fpath.t

default_tmp () is the directory used as a default value 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.cur_dir 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.