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.

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

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

Deleting and renaming

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

delete ~recurse p deletes p from the file system. If p is a symbolic link this only deletes the link, not the linked object. If recurse is true and p is a non-empty directory, no error occurs, its contents is recursively deleted. 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.

val rename : force:bool -> make_path:bool -> src:Fpath.t -> 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 and resolves all references to . and .. segments. The function errors if p does not exist.

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 ~make_path ~recurse ~src dst copies the file or file hierarchy rooted at src to dst. The function errors if dst exists. The semantics and arguments correspond to those of Copying, except this function also works if src is not a directory. Note that prune is never called on src itself FIXME is that a good idea ? also FIXME this should error if src is a directory and recurse is false.

See also Copying and Os.File.copy.

File mode and stat

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. 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 US-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 found. 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 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).