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

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

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

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

is_executable file is true iff file exists and is executable.

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.

trunacte file size truncates file to size.

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

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.

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

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.

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.file_kind.S_REG files at the cost of a stat(2).

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

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

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.

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]

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

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