Module Misc.Magic_number

module Magic_number: sig .. end

---

a typical magic number is "Caml1999I011"; it is formed of an alphanumeric prefix, here Caml1990I, followed by a version, here 011. The prefix identifies the kind of the versioned data: here the I indicates that it is the magic number for .cmi files.

All magic numbers have the same byte length, magic_length, and this is important for users as it gives them the number of bytes to read to obtain the byte sequence that should be a magic number. Typical user code will look like:

        let ic = open_in_bin path in
        let magic =
          try really_input_string ic Magic_number.magic_length
          with End_of_file -> ... in
        match Magic_number.parse magic with
        | Error parse_error -> ...
        | Ok info -> ...
      

A given compiler version expects one specific version for each kind of object file, and will fail if given an unsupported version. Because versions grow monotonically, you can compare the parsed version with the expected "current version" for a kind, to tell whether the wrong-magic object file comes from the past or from the future.

An example of code block that expects the "currently supported version" of a given kind of magic numbers, here Cmxa, is as follows:

        let ic = open_in_bin path in
        begin
          try Magic_number.(expect_current Cmxa (get_info ic)) with
          | Parse_error error -> ...
          | Unexpected error -> ...
        end;
        ...
      

Parse errors distinguish inputs that are Not_a_magic_number str, which are likely to come from the file being completely different, and Truncated str, raised by headers that are the (possibly empty) prefix of a valid magic number.

Unexpected errors correspond to valid magic numbers that are not the one expected, either because it corresponds to a different kind, or to a newer or older version.

The helper functions explain_parse_error and explain_unexpected_error will generate a textual explanation of each error, for use in error messages.

type native_obj_config = {

flambda : bool;

}

val native_obj_config : native_obj_config

type version = int 

type kind = 

|	Exec
|	Cmi
|	Cmo
|	Cma
|	Cmx of native_obj_config
|	Cmxa of native_obj_config
|	Cmxs
|	Cmt
|	Ast_impl
|	Ast_intf

type info = {

	kind : kind;
	version : version;	(*	Note: some versions of the compiler use the same version suffix for all kinds, but others use different versions counters for different kinds. We may only assume that versions are growing monotonically (not necessarily always by one) between compiler versions.	*)

}

type raw = string 

Parsing magic numbers

type parse_error = 

|	Truncated of string
|	Not_a_magic_number of string

val explain_parse_error : kind option -> parse_error -> string

val parse : raw ->
       (info, parse_error) result

val read_info : in_channel ->
       (info, parse_error) result

val magic_length : int

Checking that magic numbers are current

type 'a unexpected = {

	expected : 'a;
	actual : 'a;

}

type unexpected_error = 

|	Kind of kind unexpected
|	Version of kind * version unexpected

val check_current : kind ->
       info ->
       (unit, unexpected_error) result

val explain_unexpected_error : unexpected_error -> string

type error = 

|	Parse_error of parse_error
|	Unexpected_error of unexpected_error

val read_current_info : expected_kind:kind option ->
       in_channel ->
       (info, error) result

Information on magic numbers

val string_of_kind : kind -> string

val human_name_of_kind : kind -> string

val current_raw : kind -> raw

val current_version : kind -> version

Raw representations

Mainly for internal usage and testing.

type raw_kind = string 

val parse_kind : raw_kind -> kind option

val raw_kind : kind -> raw_kind

val raw : info -> raw

val all_kinds : kind list