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 that mentions dir 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.

delete ~recurse dir delete the directory dir from the file system. If:

• dir does not exist on the file system, nothing happens.
• dir is an empty directory, the directory is deleted.
• dir is a non-empty directory and recurse is true, the directory and all its contents is deleted. Symbolic links are not followed.
• dir is a symbolic link to a directory, the link is deleted, not the linked directory.
• dir is a dangling symbolic link, the link is deleted.
• Otherwise the function errors.

The result is:

• Ok true, if dir existed and was deleted.
• Ok false, if the path dir did not exist on the file system.
• Error _ in case of error. In particular if dir is a non-empty directory and recurse is false or if dir is a file or a symlink to a file.

See also Dir.delete_contents, Path.delete, File.delete.

delete_contents ~recurse dir deletes the contents of the existing directory dir. If:

• dir does not exist on the file system, nothing happens.
• dir is a directory, it's files are deleted, empty directories are deleted and non-empty directories are deleted iff recurse is true.
• dir is a symbolic link to a directory, all the contents of the linked directory is deleted.
• Otherwise the function errors

The result is:

• Ok true, if dir was non empty.
• Ok false, if dir was empty.
• Error _ in case of error. In particular if dir does not exist or points to a file.

See also Deleting, Path.delete, File.delete.

fold ~recurse f dir acc folds f over the contents of dir starting with acc. If dir does not exist as (possibly a symlink to) a directory, the function errors. Paths given to f, prune_dir and stat_error do not have a trailing /. The arguments are as follows:

• 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_dir (see below). If recurse is false only the direct contents of dir is folded over.
• prune_dir 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 warn_and_prune_denied.
• stat_error is called if Unix.stat or Unix.lstat errors on a path. The default is warn_stat_error.
• 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 Unix.lstat.
• 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,prune_dir and stat_error 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.

contents uses path_list with:

• fold if kind is `All (default)
• fold_files if kind is `Files.
• fold_dirs if kind is `Dirs

path_list is a folding function to get a (reverse w.r.t. list of paths). Paths in the result that correspond to directories satisfy Fpath.is_syntactic_dir.

warn_and_prune_denied ~dir n rel root is a prune_dir function for fold to warn about and skip directories for which the user has no R_OK and X_OK permissions. dir is the directory given to fold and rel the argument given to fold.

warn_stat_error is a function that warns about stat errors.

copy ~make_path src ~dst copies the directory src to dst. If:

• src is a symbolic link it is resolved and (conceptually) the functino is called again with the result. A dangling link results in an error
• src is a directory and dst does not exist. The recursive contents of src is copied to the directory dst. File modes are preserved.
• Otherwise the function errors.

Other than that:

• 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 false (default), symbolic links are not followed, the actual symlinks are copied and the stat information given to prune is given by Os.Path.symlink_stat. If true symbolic links are followed.
• atomic if atomic is true (default) and the function errors then dst does not exist once the call returns. 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 inexistent. 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.
• stat_error is called if Unix.stat or Unix.lstat error on a path. The default is warn_stat_error.
• File timestamps of src are not preserved in dst
• The function always error if dst is a directory. If you would like to copy a directory to a directory use Path.copy with recurse:true

See also Path.copy and File.copy.

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 More.Os.Path.tmp_name for details. It defaults to "tmp-%s".
• dir is the directory in which the temporary file is created. It defaults to More.Os.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 id of the SUDO_UID env var or of the process. If this fails falls back to parse a path from the HOME environment variables. On Windows no special fallback is implemented.

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

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

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_DIR.
2. The value of default_tmp.

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