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;

}

let 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

let explain_parse_error: (option(kind), parse_error) => string;

let parse: raw => result(info, parse_error);

let read_info: in_channel => result(info, parse_error);

let 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

let check_current: (kind, info) => result(unit, unexpected_error);

let explain_unexpected_error: unexpected_error => string;

type error = 

|	Parse_error of parse_error
|	Unexpected_error of unexpected_error

let read_current_info:
  (~expected_kind: option(kind), in_channel) => result(info, error);

Information on magic numbers

let string_of_kind: kind => string;

let human_name_of_kind: kind => string;

let current_raw: kind => raw;

let current_version: kind => version;

Raw representations

Mainly for internal usage and testing.

type raw_kind = string;

let parse_kind: raw_kind => option(kind);

let raw_kind: kind => raw_kind;

let raw: info => raw;