Module OS.File

null is Fpath.v "/dev/null" on POSIX and Fpath.v "NUL" on Windows. It represents a file on the OS that discards all writes and returns end of file on reads.

dash is Fpath.v "-". This value is used by input and output functions to respectively denote stdin and stdout.

Note. Representing stdin and stdout by this path is a widespread command line tool convention. However it is perfectly possible to have files that bear this name in the file system. If you need to operate on such path from the current directory you can simply specify them as Fpath.(cur_dir / "-") and so can your users on the command line by using "./-".

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

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

delete ~must_exist file deletes file file. If must_exist is true (defaults to false) an error is returned if file doesn't exist.

truncate p size truncates p to s.

is_executable p is true iff file p exists and is executable.

The type for file inputs. The function is called by the client to input more bytes. It returns Some (b, pos, len) if the bytes b can be read in the range [pos;pos+len]; this byte range is immutable until the next function call. None is returned at the end of input.

with_input ~bytes file f v provides contents of file with an input i using bytes to read the data and returns f i v. After the function returns (normally or via an exception) a call to i by the client raises Invalid_argument.

• raises Invalid_argument

  if the length of bytes is 0.

with_ic file f v opens file as a channel ic and returns Ok (f ic v). After the function returns (normally or via an exception), ic is ensured to be closed. If file is dash, ic is Stdlib.stdin and not closed when the function returns. End_of_file exceptions raised by f are turned it into an error message.

read file is file's content as a string.

read_lines file is file's content, split at each '\n' character.

fold_lines f acc file is like List.fold_left f acc (read_lines p).

The type for file outputs. The function is called by the client with Some (b, pos, len) to output the bytes of b in the range [pos;pos+len]. None is called to denote end of output.

with_output file f v writes the contents of file using an output o given to f and returns Ok (f o v). file is not written if f returns an error. After the function returns (normally or via an exception) a call to o by the client raises Invalid_argument.

with_oc file f v opens file as a channel oc and returns Ok (f oc v). After the function returns (normally or via an exception) oc is closed. file is not written if f returns an error. If file is dash, oc is Stdlib.stdout and not closed when the function returns.

write file content outputs content to file. If file is dash, writes to Stdlib.stdout. If an error is returned file is left untouched except if Stdlib.stdout is written.

write file fmt ... is like write file (Format.asprintf fmt ...).

write_lines file lines is like write file (String.concat ~sep:"\n" lines).

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

tmp mode dir pat is a new empty temporary file in dir (defaults to Dir.default_tmp) named according to pat and created with permissions mode (defaults to 0o600 only readable and writable by the user). The file is deleted at the end of program execution using a Stdlib.at_exit handler.

Warning. If you want to write to the file, using with_tmp_output or with_tmp_oc is more secure as it ensures that noone replaces the file, e.g. by a symbolic link, between the time you create the file and open it.

with_tmp_output dir pat f v is a new temporary file in dir (defaults to Dir.default_tmp) named according to pat and atomically created and opened with permissions mode (defaults to 0o600 only readable and writable by the user). Returns Ok (f file o v) with file the file path and o an output to write the file. After the function returns (normally or via an exception), calls to o raise Invalid_argument and file is deleted.

with_tmp_oc mode dir pat f v is a new temporary file in dir (defaults to Dir.default_tmp) named according to pat and atomically created and opened with permission mode (defaults to 0o600 only readable and writable by the user). Returns Ok (f file oc v) with file the file path and oc an output channel to write the file. After the function returns (normally or via an exception), oc is closed and file is deleted.