Module Bos.OS.File

module File: sig .. end
File operations.


Famous file paths


val null : Fpath.t
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.
val dash : Fpath.t
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 "./-".


Existence and deletion


val exists : Fpath.t -> (bool, [> Rresult.R.msg ]) Bos.OS.result
exists file is true if file is a regular file in the file system and false otherwise. Symbolic links are followed.
val must_exist : Fpath.t -> (Fpath.t, [> Rresult.R.msg ]) Bos.OS.result
must_exist file is Ok file if file is a regular file in the file system and an error otherwise. Symbolic links are followed.
val delete : ?must_exist:bool -> Fpath.t -> (unit, [> Rresult.R.msg ]) Bos.OS.result
delete ~must_exist file deletes file file. If must_exist is true (defaults to false) an error is returned if file doesn't exist.
val truncate : Fpath.t -> int -> (unit, [> Rresult.R.msg ]) Bos.OS.result
truncate p size truncates p to s.

Input

Stdin. In the following functions if the path is Bos.OS.File.dash, bytes are read from stdin.

type input = unit -> (Bytes.t * int * int) option 
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.
val with_input : Fpath.t ->
(input -> 'a -> 'b) ->
'a -> ('b, [> Rresult.R.msg ]) Bos.OS.result
with_input file f v provides contents of file with an input i and returns f i v. After the function returns (normally or via an exception) a call to i by the client raises Invalid_argument.
val with_ic : Fpath.t ->
(Pervasives.in_channel -> 'a -> 'b) ->
'a -> ('b, [> Rresult.R.msg ]) Bos.OS.result
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 Bos.OS.File.dash, ic is Pervasives.stdin and not closed when the function returns. End_of_file exceptions raised by f are turned it into an error message.
val read : Fpath.t -> (string, [> Rresult.R.msg ]) Bos.OS.result
read file is file's content as a string.
val read_lines : Fpath.t -> (string list, [> Rresult.R.msg ]) Bos.OS.result
read_lines file is file's content, split at each '\n' character.
val fold_lines : ('a -> string -> 'a) ->
'a -> Fpath.t -> ('a, [> Rresult.R.msg ]) Bos.OS.result
fold_lines f acc file is like List.fold_left f acc (read_lines p).

Output

The following applies to every function in this section.

Stdout. If the path is Bos.OS.File.dash, bytes are written to stdout.

Default permission mode. The optional mode argument specifies the permissions of the created file. It defaults to 0o644 (readable by everyone writeable by the user).

Atomic writes. Files are written atomically by the functions. They create a temporary file t in the directory of the file f to write, write the contents to t and renames it to f on success. In case of error t is deleted and f left intact.

type output = (Bytes.t * int * int) option -> unit 
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.
val with_output : ?mode:int ->
Fpath.t ->
(output -> 'a -> ('c, 'd) Result.result) ->
'a -> (('c, 'd) Result.result, [> Rresult.R.msg ]) Bos.OS.result
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.
val with_oc : ?mode:int ->
Fpath.t ->
(Pervasives.out_channel -> 'a -> ('c, 'd) Result.result) ->
'a -> (('c, 'd) Result.result, [> Rresult.R.msg ]) Bos.OS.result
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 Bos.OS.File.dash, oc is Pervasives.stdout and not closed when the function returns.
val write : ?mode:int -> Fpath.t -> string -> (unit, [> Rresult.R.msg ]) Bos.OS.result
write file content outputs content to file. If file is Bos.OS.File.dash, writes to Pervasives.stdout. If an error is returned file is left untouched except if Pervasives.stdout is written.
val writef : ?mode:int ->
Fpath.t ->
('a, Format.formatter, unit, (unit, [> Rresult.R.msg ]) Bos.OS.result)
Pervasives.format4 -> 'a
write file fmt ... is like write file (Format.asprintf fmt ...).
val write_lines : ?mode:int ->
Fpath.t -> string list -> (unit, [> Rresult.R.msg ]) Bos.OS.result
write_lines file lines is like write file (String.concat ~sep:"\n" lines).

Temporary files


type tmp_name_pat = (string -> string, Format.formatter, unit, string) Pervasives.format4 
The type for temporary file name patterns. The string format is replaced by random characters.
val tmp : ?mode:int ->
?dir:Fpath.t ->
tmp_name_pat -> (Fpath.t, [> Rresult.R.msg ]) Bos.OS.result
tmp mode dir pat is a new empty temporary file in dir (defaults to Bos.OS.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 Pervasives.at_exit handler.

Warning. If you want to write to the file, using Bos.OS.File.with_tmp_output or Bos.OS.File.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.

val with_tmp_output : ?mode:int ->
?dir:Fpath.t ->
tmp_name_pat ->
(Fpath.t -> output -> 'a -> 'b) ->
'a -> ('b, [> Rresult.R.msg ]) Bos.OS.result
with_tmp_output dir pat f v is a new temporary file in dir (defaults to Bos.OS.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.
val with_tmp_oc : ?mode:int ->
?dir:Fpath.t ->
tmp_name_pat ->
(Fpath.t -> Pervasives.out_channel -> 'a -> 'b) ->
'a -> ('b, [> Rresult.R.msg ]) Bos.OS.result
with_tmp_oc mode dir pat f v is a new temporary file in dir (defaults to Bos.OS.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.