Module Os.Path

File system path operations.

These functions operate on files and directories equally. Specific function operating on either kind of path are in the File and Dir modules.

Existence

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

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

See also exists_stat, File.exists, Dir.exists.

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

must_exist p is Ok () if p exists in the file system and an error that mentions p otherwise. Symbolic links are followed.

See also File.must_exist, Dir.must_exist.

Deleting and renaming

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

delete ~recurse p deletes path p from the file system. If:

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

The result is:

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

See also File.delete, Deleting and Dir.delete_contents.

val rename : force:bool -> make_path:bool -> Fpath.t -> dst:Fpath.t -> (unit, string) Stdlib.result

rename ~force ~make_path src ~dst renames src to dst.

  • If force is true and dst exists it tries to delete it using File.delete dst. If force is false and dst exists the function errors.
  • 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).

Resolving

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

realpath p expands all symbolic links, resolves all references to . and .. segments and returns an absolute path on the file system that corresponds to p. The function errors with an error message that mentions p if p does not exist.

Copying

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

copy ~force ~make_path ~recurse src ~dst copies the file or file hierarchy rooted at src to dst. If:

  • src or dst are symbolic link, the link are resolved and (conceptually) the function is called again with the result. Dangling links result in errors.
  • src or dst are Fpath.dash they are (conceptually) resolved to the files /dev/stdin and /dev/stdout and the function is called again.
  • src is a regular file and dst is a regular file or does not exist. src is copied to dst with Os.File.copy.
  • src is a file and dst is a directory. src is copied to Fpath.(dst / basename src) with Os.File.copy.
  • src is a directory, dst does not exist and recurse is true, src is copied to dst like Os.Dir.copy does.
  • src is a directory and dst is a directory. src is copied to Fpath.(dst / basename src) like Os.Dir.copy does.
  • Otherwise the function errors

All applicable named arguments are given to the underlying copy function.

See also Os.File.copy, Os.Dir.copy.

File mode, stat and mounts

See also File.is_executable.

val get_mode : Fpath.t -> (int, string) Stdlib.result

get_mode p is the file mode of p. Symbolic links are followed.

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

set_mode file p sets the file mode of file to p. Symbolic links are followed.

val stat : Fpath.t -> (Unix.stats, string) Stdlib.result

stat p is p's file information if p exists in the file system and error the mentions p otherwise. Symbolic links are followed.

See also exists_stat and symlink_stat.

val exists_stat : Fpath.t -> (Unix.stats option, string) Stdlib.result

exist_stat p is p's file information or None if p does not exist. Symbolic links are followed.

See also stat and symlink_stat.

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

is_mount_point p is true if p looks like a mount point. The criterion is if p and p/..'s stat have a differing Unix.stat.std_dev field. Symbolic links are followed.

For hard links see Hard links.

symlink ~force ~src p symbolically links src to p.

  • If force is true and p exists it tries to delete it using File.delete p. If force is false and p exists the function errors.
  • If make_path is true and the parent directory of file 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).

symlink_link p is Ok l if p is a symbolic link to l.

symlink_stat p is like stat but if p is a symlink returns information about the link itself. If p is not a symlink then this is stat.

Temporary paths

type tmp_name = (string -> string, unit, string) Stdlib.format

The type for temporary file name patterns. The string format is replaced by random hexadecimal ASCII characters.

val tmp : ?make_path:bool -> ?dir:Fpath.t -> ?name:tmp_name -> unit -> (Fpath.t, string) Stdlib.result

tmp ~make_path ~dir name () is a file system path in dir that did not exist when the name was devised. It may exist once the function returns though, prefer temporary files and directories creation functions to guarantee the creation of the temporary objects.

  • name is used to construct the filename of the file, see 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 does not exist the whole path to it is created as needed with permission 0o755 (readable and traversable by everyone, writable by the user).