Module Magic_number
: sigend
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:
letic=open_in_binpathinletmagic=tryreally_input_stringicMagic_number.magic_lengthwithEnd_of_file->...inmatchMagic_number.parsemagicwith|Errorparse_error->...|Okinfo->...
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:
letic=open_in_binpathinbegintryMagic_number.(expect_currentCmxa(get_infoic))with|Parse_errorerror->...|Unexpectederror->...end;...
Parse errors distinguish inputs that are Not_a_magic_numberstr , which are likely to come from the file
being completely different, and Truncatedstr , 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.
typenative_obj_config = {
flambda : bool ;
}
native object files have a format and magic number that depend on certain native-compiler configuration
parameters. This configuration space is expressed by the native_obj_config type.
valnative_obj_config : native_obj_config
the native object file configuration of the active/configured compiler.
typeversion = inttypekind =
| Exec
| Cmi
| Cmo
| Cma
| Cmx ofnative_obj_config
| Cmxa ofnative_obj_config
| Cmxs
| Cmt
| Ast_impl
| Ast_intf
typeinfo = {
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.
*)
}
typeraw = string
the type of raw magic numbers, such as "Caml1999A027" for the .cma files of OCaml 4.10
Parsingmagicnumberstypeparse_error =
| Truncated ofstring
| Not_a_magic_number ofstringvalexplain_parse_error : kindoption->parse_error->string
Produces an explanation for a parse error. If no kind is provided, we use an unspecific formulation
suggesting that any compiler-produced object file would have been satisfying.
valparse : raw->(info,parse_error)result
Parses a raw magic number
valread_info : in_channel->(info,parse_error)result
Read a raw magic number from an input channel.
If the data read str is not a valid magic number, it can be recovered from the Truncatedstr|Not_a_magic_numberstr payload of the Errorparse_error case.
If parsing succeeds with an Okinfo result, we know that exactly magic_length bytes have been consumed
from the input_channel.
If you also wish to enforce that the magic number is at the current version, see
Misc.Magic_number.read_current_info below.
valmagic_length : int
all magic numbers take the same number of bytes
Checkingthatmagicnumbersarecurrenttype'aunexpected = {
expected : 'a ;
actual : 'a ;
}
typeunexpected_error =
| Kind ofkindunexpected
| Version ofkind*versionunexpectedvalcheck_current : kind->info->(unit,unexpected_error)resultcheck_currentkindinfo checks that the provided magic info is the current version of kind 's magic
header.
valexplain_unexpected_error : unexpected_error->string
Provides an explanation of the unexpected_error .
typeerror =
| Parse_error ofparse_error
| Unexpected_error ofunexpected_errorvalread_current_info : expected_kind:kindoption->in_channel->(info,error)result
Read a magic number as read_info , and check that it is the current version as its kind. If the
expected_kind argument is None , any kind is accepted.
Informationonmagicnumbersvalstring_of_kind : kind->string
a user-printable string for a kind, eg. "exec" or "cmo", to use in error messages.
valhuman_name_of_kind : kind->string
a user-meaningful name for a kind, eg. "executable file" or "bytecode object file", to use in error
messages.
valcurrent_raw : kind->raw
the current magic number of each kind
valcurrent_version : kind->version
the current version of each kind
Rawrepresentations
Mainly for internal usage and testing.
typeraw_kind = string
the type of raw magic numbers kinds, such as "Caml1999A" for .cma files
valparse_kind : raw_kind->kindoption
parse a raw kind into a kind
valraw_kind : kind->raw_kind
the current raw representation of a kind.
In some cases the raw representation of a kind has changed over compiler versions, so other files of the
same kind may have different raw kinds. Note that all currently known cases are parsed correctly by
parse_kind .
valraw : info->raw
A valid raw representation of the magic number.
Due to past and future changes in the string representation of magic numbers, we cannot guarantee that
the raw strings returned for past and future versions actually match the expectations of those compilers.
The representation is accurate for current versions, and it is correctly parsed back into the desired
version by the parsing functions above.
valall_kinds : kindlist
OCamldoc 2025-06-12 Misc.Magic_number(3o)
Install Now
PNG Icons
