Module Os.File

Regular file operations.

This module operates on regular files, most functions error if they are applied to other file kinds.

Famous file paths

val null : Fpath.t

null represents a file on the OS that discards all writes and returns end of file on reads.

val dash : Fpath.t

dash is "-". This value is used by read and write to respectively denote stdin and stdout.

Existence

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

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

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

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

val is_executable : Fpath.t -> bool

is_executable file is true iff file exists and is executable.

Deleting and truncating

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

delete file deletes file file from the file system. If file is a symbolic link this only deletes the link, not the linked file. The result is:

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

See also Path.delete.

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

trunacte file size truncates file to size.

For symbolic links see Symbolic links.

link ~force ~src p hard links file path p to the file src.

  • If force is true and p exists an attempt to delete it is performed with File.delete p. If force is false and p exists the function errors.
  • 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).

Reading

val read_with_fd : Fpath.t -> (Unix.file_descr -> 'b) -> ('b, string) Stdlib.result

read_with_ic file f opens file as a file descriptor fdi and returns Ok (f ic). If file is dash, ic is stdin. After the function returns (normally or via an exception raised by f), ic is ensured to be closed, except if it is stdin. The function errors if opening file fails. Errors have the form Fmt.str "%s: %s" file err.

val read_with_ic : Fpath.t -> (Stdlib.in_channel -> 'b) -> ('b, string) Stdlib.result

read_with_ic file f is exactly like read_with_fd but opens an OCaml input channel.

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

read file is file's content as a string. If file is dash the contents of stdin is read. Warning. The signature of this function limits files to be at most Sys.max_string_length in size. On 32-bit platforms this is only around 16MB. Errors have the form Fmt.str "%s: %s" file err.

Writing and copying

val write_with_fd : ?⁠atomic:bool -> ?⁠mode:int -> force:bool -> make_path:bool -> Fpath.t -> (Unix.file_descr -> ('a'b) Stdlib.result) -> (('a'b) Stdlib.result, string) Stdlib.result

write_with_fd ~atomic ~mode ~force ~make_path file f opens an output file descriptor fdo to write to file and returns Ok (f fdo). If file is dash, fdo is Unix.stdout. After the function returns (normally or via an exception) fdo is ensured to be closed except if it is Unix.stdout.

  • 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).
  • If force is true and file exists at call time as a regular file it tries to overwrite it, in all other cases the function errors if file exists.
  • mode are the permissions of the written file; they default to 0o644, readable by everyone, writable by the user.
  • If atomic is true (default) and the function or f errors file is left untouched. To write atomically, a temporary file t in the parent directory of file is created. On write success t is renamed to file; an operation which is more or less atomic. On error t is deleted and file left intact. This means the user needs write permissions in the parent directory of file, in practice this is almost always the case but fails for some directories (e.g. writing to /sys on Linux®). XXX An improvement would be to automatically disable atomic on non Unix.S_REG files at the cost of a stat(2).
val write_with_oc : ?⁠atomic:bool -> ?⁠mode:int -> force:bool -> make_path:bool -> Fpath.t -> (Stdlib.out_channel -> ('a'b) Stdlib.result) -> (('a'b) Stdlib.result, string) Stdlib.result

write_with_oc ~atomic ~mode ~force ~make_path file f operates like write_with_fd but opens an OCaml channel.

val write : ?⁠atomic:bool -> ?⁠mode:int -> force:bool -> make_path:bool -> Fpath.t -> string -> (unit, string) Stdlib.result

write ~atomic ~mode ~force ~make_path file s operates like write_with_fd but directly writes s to file.

val copy : ?⁠atomic:bool -> ?⁠mode:int -> force:bool -> make_path:bool -> src:Fpath.t -> Fpath.t -> (unit, string) Stdlib.result

copy ~atomic ~mode ~force ~path ~make_path ~src file operates like write_with_fd but directly writes the content of src (or stdin if src is dash) to file. mode defaults to the permissions of src if available and 0o644 otherwise.

Temporary files

val with_tmp_fd : ?⁠flags:Unix.open_flag list -> ?⁠mode:int -> ?⁠make_path:bool -> ?⁠dir:Fpath.t -> ?⁠name:Path.tmp_name -> (Fpath.t -> Unix.file_descr -> 'b) -> ('b, string) Stdlib.result

with_tmp_fd ~flags ~mode ~make_path ~dir ~name f opens an output file descriptor fdo to a temporary file and returns Ok (f fdo). After the function returns (normally or via an exception) fdo is ensured to be closed and the temporary file is deleted.

  • 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 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 written file; they default to 0o600, only readable and writeable by the user
  • flags are the flags used to open the file. They default to Unix.[O_WRONLY; O_CREAT; O_EXCL; O_SHARE_DELETE; O_CLOEXEC]
val open_tmp_fd : ?⁠flags:Unix.open_flag list -> ?⁠mode:int -> ?⁠make_path:bool -> ?⁠dir:Fpath.t -> ?⁠name:Path.tmp_name -> unit -> (Fpath.t * Unix.file_descr, string) Stdlib.result

open_tmp_fd is like with_tmp_fd except it is the client's duty to close the file descriptor and delete the file (if the file is not deleted it will be when the program exits).

val with_tmp_oc : ?⁠flags:Unix.open_flag list -> ?⁠mode:int -> ?⁠make_path:bool -> ?⁠dir:Fpath.t -> ?⁠name:Path.tmp_name -> (Fpath.t -> Stdlib.out_channel -> 'b) -> ('b, string) Stdlib.result

with_tmp_oc is like with_tmp_fd but uses an OCaml output channel instead of a file decriptor.