package octez-internal-libs

  1. Overview
  2. Docs
package octez-internal-libs
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Source file io_intf.ml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
(*
 * Copyright (c) 2022-2023 Tarides <contact@tarides.com>
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *)

open Import

module type S = sig
  (** Low level IO abstraction. A typical implementation is unix. This
      abstraction is meant to be dead simple. Not a lot of documentation is
      required.

      It is not resistant to race condictions. There should not be concurrent
      modifications of the files.

      These functions are essentially invoking the underlying functions from
      {!Unix} directly; there is no buffering for example. *)

  type t

  (** {1 Errors} *)

  type misc_error [@@deriving irmin]
  (** An abstract error type that contains the IO-backend specific errors. (e.g.
      [Unix.error]) *)

  type create_error = [ `Io_misc of misc_error | `File_exists of string ]

  type open_error =
    [ `Io_misc of misc_error
    | `No_such_file_or_directory of string
    | `Not_a_file ]

  type read_error =
    [ `Io_misc of misc_error
    | `Read_out_of_bounds
    | `Closed
    | `Invalid_argument ]

  type write_error = [ `Io_misc of misc_error | `Ro_not_allowed | `Closed ]
  type close_error = [ `Io_misc of misc_error | `Double_close ]

  type mkdir_error =
    [ `Io_misc of misc_error
    | `File_exists of string
    | `No_such_file_or_directory of string
    | `Invalid_parent_directory ]

  (** {1 Safe Functions}

      None of the functions in this section raise exceptions. They may however
      perform effects that are always continued.

      {2 Life Cycle} *)

  val create : path:string -> overwrite:bool -> (t, [> create_error ]) result
  val open_ : path:string -> readonly:bool -> (t, [> open_error ]) result
  val close : t -> (unit, [> close_error ]) result

  (** {2 Write Functions} *)

  val write_string : t -> off:int63 -> string -> (unit, [> write_error ]) result
  (** [write_string t ~off s] writes [s] at [offset] in [t]. *)

  val fsync : t -> (unit, [> write_error ]) result
  (** [fsync t] persists to the file system the effects of previous [create] or
      write. *)

  val move_file :
    src:string -> dst:string -> (unit, [> `Sys_error of string ]) result

  val copy_file :
    src:string -> dst:string -> (unit, [> `Sys_error of string ]) result

  val mkdir : string -> (unit, [> mkdir_error ]) result
  val unlink : string -> (unit, [> `Sys_error of string ]) result

  val unlink_dont_wait : on_exn:(exn -> unit) -> string -> unit
  (** [unlink_dont_wait file] attempts to unlink the named file but doesn't wait
      for the completion of the unlink operation.

      If unlink raises an exception it is passed to [on_exn]. *)

  (** {2 Read Functions} *)

  val read_to_string :
    t -> off:int63 -> len:int -> (string, [> read_error ]) result
  (** [read_to_string t ~off ~len] are the [len] bytes of [t] at [off]. *)

  val read_all_to_string :
    t -> (string, [> `Io_misc of misc_error | `Closed ]) result
  (** [read_to_string t] is the contents full contents of the file.

      The individual pages are not guaranteed to be read atomically. *)

  val read_size : t -> (int63, [> read_error ]) result
  (** [read_size t] is the number of bytes of the file handled by [t].

      This function is expensive in the unix implementation because it performs
      syscalls. *)

  val size_of_path :
    string ->
    ( int63,
      [> `Io_misc of misc_error
      | `No_such_file_or_directory of string
      | `Not_a_file ] )
    result

  val classify_path :
    string -> [> `File | `Directory | `No_such_file_or_directory | `Other ]

  (** {1 MISC.} *)

  val readonly : t -> bool
  val path : t -> string
  val page_size : int

  (** {1 Unsafe Functions}

      These functions are equivalents to exising safe ones, but using exceptions
      instead of the result monad for performances reasons. *)

  val read_exn : t -> off:int63 -> len:int -> bytes -> unit
  (** [read_exn t ~off ~len b] reads the [len] bytes of [t] at [off] to [b].

      Raises [Errors.Pack_error] and [Errors.RO_not_allowed].

      Also raises backend-specific exceptions (e.g. [Unix.Unix_error] for the
      unix backend). *)

  val write_exn : t -> off:int63 -> len:int -> string -> unit
  (** [write_exn t ~off ~len b] writes the first [len] bytes pf [b] to [t] at
      offset [off].

      Raises [Errors.Pack_error] and [Errors.RO_not_allowed].

      Also raises backend-specific exceptions (e.g. [Unix.Unix_error] for the
      unix backend). *)

  val raise_misc_error : misc_error -> 'a

  val catch_misc_error :
    (unit -> 'a) -> ('a, [> `Io_misc of misc_error ]) result
end

module type Sigs = sig
  module type S = S

  module Unix : S with type misc_error = Unix.error * string * string
end
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct