1Misc.Magic_number(3)             OCaml library            Misc.Magic_number(3)
2
3
4

NAME

6       Misc.Magic_number - no description
7

Module

9       Module   Misc.Magic_number
10

Documentation

12       Module Magic_number
13        : sig end
14
15
16
17
18
19
20
21
22
23       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
28       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 ob‐
30       tain the byte sequence that should be a magic number. Typical user code
31       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
40
41       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
47       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
57
58       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
63       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
67       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
71       type native_obj_config = {
72        flambda : bool ;
73        }
74
75
76       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
80
81
82       val native_obj_config : native_obj_config
83
84       the native object file configuration of the active/configured compiler.
85
86
87       type version = int
88
89
90
91
92       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
104
105
106
107       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
117
118
119
120       type raw = string
121
122
123       the  type  of  raw  magic  numbers, such as "Caml1999A027" for the .cma
124       files of OCaml 4.10
125
126
127
128
129   Parsing magic numbers
130       type parse_error =
131        | Truncated of string
132        | Not_a_magic_number of string
133
134
135
136
137
138       val explain_parse_error : kind option -> parse_error -> string
139
140       Produces an explanation for a parse error. If no kind is  provided,  we
141       use an unspecific formulation suggesting that any compiler-produced ob‐
142       ject file would have been satisfying.
143
144
145
146       val parse : raw -> (info, parse_error) result
147
148       Parses a raw magic number
149
150
151
152       val read_info : in_channel -> (info, parse_error) result
153
154       Read a raw magic number from an input channel.
155
156       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
160       If parsing succeeds with an  Ok  info  result,  we  know  that  exactly
161       magic_length bytes have been consumed from the input_channel.
162
163       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
166
167
168       val magic_length : int
169
170       all magic numbers take the same number of bytes
171
172
173
174
175   Checking that magic numbers are current
176       type 'a unexpected = {
177        expected : 'a ;
178        actual : 'a ;
179        }
180
181
182
183
184       type unexpected_error =
185        | Kind of kind unexpected
186        | Version of kind * version unexpected
187
188
189
190
191
192       val check_current : kind -> info -> (unit, unexpected_error) result
193
194
195       check_current kind info checks that the provided magic info is the cur‐
196       rent version of kind 's magic header.
197
198
199
200       val explain_unexpected_error : unexpected_error -> string
201
202       Provides an explanation of the unexpected_error .
203
204
205       type error =
206        | Parse_error of parse_error
207        | Unexpected_error of unexpected_error
208
209
210
211
212
213       val  read_current_info  :  expected_kind:kind  option  -> in_channel ->
214       (info, error) result
215
216       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
220
221
222
223   Information on magic numbers
224       val string_of_kind : kind -> string
225
226       a user-printable string for a kind, eg. "exec" or "cmo", to use in  er‐
227       ror messages.
228
229
230
231       val human_name_of_kind : kind -> string
232
233       a  user-meaningful  name for a kind, eg. "executable file" or "bytecode
234       object file", to use in error messages.
235
236
237
238       val current_raw : kind -> raw
239
240       the current magic number of each kind
241
242
243
244       val current_version : kind -> version
245
246       the current version of each kind
247
248
249
250
251   Raw representations
252       Mainly for internal usage and testing.
253
254       type raw_kind = string
255
256
257       the type of raw magic numbers kinds, such as "Caml1999A" for .cma files
258
259
260
261       val parse_kind : raw_kind -> kind option
262
263       parse a raw kind into a kind
264
265
266
267       val raw_kind : kind -> raw_kind
268
269       the current raw representation of a kind.
270
271       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
276
277
278       val raw : info -> raw
279
280       A valid raw representation of the magic number.
281
282       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.
287
288
289
290
291
292OCamldoc                          2023-07-20              Misc.Magic_number(3)
Impressum