1Misc.Magic_number(3) OCaml library Misc.Magic_number(3)
2
6 Misc.Magic_number - no description
7
9 Module Misc.Magic_number
10
12 Module Magic_number
13 : sig end
14 a typical magic number is "Caml1999I011"; it is formed of an alphanu‐
24 meric prefix, here Caml1990I, followed by a version, here 011. The pre‐
25 fix identifies the kind of the versioned data: here the I indicates
26 that it is the magic number for .cmi files.
27 All magic numbers have the same byte length, magic_length , and this is
29 important for users as it gives them the number of bytes to read to
30 obtain the byte sequence that should be a magic number. Typical user
31 code will look like:
32 let ic = open_in_bin path in
33 let magic =
34 try really_input_string ic Magic_number.magic_length
35 with End_of_file -> ... in
36 match Magic_number.parse magic with
37 | Error parse_error -> ...
38 | Ok info -> ...
39 A given compiler version expects one specific version for each kind of
42 object file, and will fail if given an unsupported version. Because
43 versions grow monotonically, you can compare the parsed version with
44 the expected "current version" for a kind, to tell whether the
45 wrong-magic object file comes from the past or from the future.
46 An example of code block that expects the "currently supported version"
48 of a given kind of magic numbers, here Cmxa , is as follows:
49 let ic = open_in_bin path in
50 begin
51 try Magic_number.(expect_current Cmxa (get_info ic)) with
52 | Parse_error error -> ...
53 | Unexpected error -> ...
54 end;
55 ...
56 Parse errors distinguish inputs that are Not_a_magic_number str , which
59 are likely to come from the file being completely different, and Trun‐
60 cated str , raised by headers that are the (possibly empty) prefix of a
61 valid magic number.
62 Unexpected errors correspond to valid magic numbers that are not the
64 one expected, either because it corresponds to a different kind, or to
65 a newer or older version.
66 The helper functions explain_parse_error and explain_unexpected_error
68 will generate a textual explanation of each error, for use in error
69 messages.
70 type native_obj_config = {
72 flambda : bool ;
73 }
74 native object files have a format and magic number that depend on cer‐
77 tain native-compiler configuration parameters. This configuration space
78 is expressed by the native_obj_config type.
79 val native_obj_config : native_obj_config
83 the native object file configuration of the active/configured compiler.
85 type version = int
88 type kind =
93 | Exec
94 | Cmi
95 | Cmo
96 | Cma
97 | Cmx of native_obj_config
98 | Cmxa of native_obj_config
99 | Cmxs
100 | Cmt
101 | Ast_impl
102 | Ast_intf
103 type info = {
108 kind : kind ;
109 version : version ; (* Note: some versions of the compiler use the
110 same version suffix for all kinds, but others use different versions
111 counters for different kinds. We may only assume that versions are
112 growing monotonically (not necessarily always by one) between compiler
113 versions.
114 *)
115 }
116 type raw = string
121 the type of raw magic numbers, such as "Caml1999A027" for the .cma
124 files of OCaml 4.10
125 Parsing magic numbers
130 type parse_error =
131 | Truncated of string
132 | Not_a_magic_number of string
133 val explain_parse_error : kind option -> parse_error -> string
139 Produces an explanation for a parse error. If no kind is provided, we
141 use an unspecific formulation suggesting that any compiler-produced
142 object file would have been satisfying.
143 val parse : raw -> (info, parse_error) result
147 Parses a raw magic number
149 val read_info : in_channel -> (info, parse_error) result
153 Read a raw magic number from an input channel.
155 If the data read str is not a valid magic number, it can be recovered
157 from the Truncated str | Not_a_magic_number str payload of the Error
158 parse_error case.
159 If parsing succeeds with an Ok info result, we know that exactly
161 magic_length bytes have been consumed from the input_channel.
162 If you also wish to enforce that the magic number is at the current
164 version, see Misc.Magic_number.read_current_info below.
165 val magic_length : int
169 all magic numbers take the same number of bytes
171 Checking that magic numbers are current
176 type 'a unexpected = {
177 expected : 'a ;
178 actual : 'a ;
179 }
180 type unexpected_error =
185 | Kind of kind unexpected
186 | Version of kind * version unexpected
187 val check_current : kind -> info -> (unit, unexpected_error) result
193 check_current kind info checks that the provided magic info is the cur‐
196 rent version of kind 's magic header.
197 val explain_unexpected_error : unexpected_error -> string
201 Provides an explanation of the unexpected_error .
203 type error =
206 | Parse_error of parse_error
207 | Unexpected_error of unexpected_error
208 val read_current_info : expected_kind:kind option -> in_channel ->
214 (info, error) result
215 Read a magic number as read_info , and check that it is the current
217 version as its kind. If the expected_kind argument is None , any kind
218 is accepted.
219 Information on magic numbers
224 val string_of_kind : kind -> string
225 a user-printable string for a kind, eg. "exec" or "cmo", to use in
227 error messages.
228 val human_name_of_kind : kind -> string
232 a user-meaningful name for a kind, eg. "executable file" or "bytecode
234 object file", to use in error messages.
235 val current_raw : kind -> raw
239 the current magic number of each kind
241 val current_version : kind -> version
245 the current version of each kind
247 Raw representations
252 Mainly for internal usage and testing.
253 type raw_kind = string
255 the type of raw magic numbers kinds, such as "Caml1999A" for .cma files
258 val parse_kind : raw_kind -> kind option
262 parse a raw kind into a kind
264 val raw_kind : kind -> raw_kind
268 the current raw representation of a kind.
270 In some cases the raw representation of a kind has changed over com‐
272 piler versions, so other files of the same kind may have different raw
273 kinds. Note that all currently known cases are parsed correctly by
274 parse_kind .
275 val raw : info -> raw
279 A valid raw representation of the magic number.
281 Due to past and future changes in the string representation of magic
283 numbers, we cannot guarantee that the raw strings returned for past and
284 future versions actually match the expectations of those compilers. The
285 representation is accurate for current versions, and it is correctly
286 parsed back into the desired version by the parsing functions above.
287OCamldoc 2020-09-01 Misc.Magic_number(3)