Module Os.Dir

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

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

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.

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.

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

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

path_list is a folding function to get a (reverse w.r.t. folding order) list of paths.

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.
• allow_hardlinks if true, tries to hard link files from src at the destination, falling back to copying if that's not possible. Defaults to false.
• 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.

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

set_cwd dir sets the current working directory to dir.

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

set_default_tmp p sets the value returned by default_tmp to p.

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

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.

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 or on Windows falls back to parse a path from the HOME environment variables.

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 %LOCALAPPDATA%.
3. If user () is Ok home, Fpath.(home / ".config").

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 %LOCALAPPDATA%.
3. If user () is Ok home, Fpath.(home / ".local" / "share").

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")

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.