![[Erlang Systems]](min_head.gif)
beam_lib provides an interface to files
created by the BEAM compiler ("BEAM files"). The format used,
a variant of "EA IFF 1985" Standard for Interchange Format Files,
divides data into chunks.
Chunk data can be returned as binaries or as compound terms.
Compound terms are returned when chunks are referenced by
names (atoms) rather than identifiers (strings).
The names recognized and the corresponding identifiers are
abstract_code ("Abst"), attributes ("Attr"),
exports ("ExpT"), imports ("ImpT"), and
locals ("LocT").
The syntas of the compound term (ChunkData) is as follows:
ChunkData = {ChunkId, binary()}
| {abstract_code, AbstractCode}
| {attributes, [{Attribute, [AttributeValue]}]}
| {exports, [{Function, Arity}]}
| {imports, [{Module, Function, Arity}]}
| {locals, [{Function, Arity}]}]}
ChunkRef = ChunkId | ChunkName
ChunkName = abstract_code | attributes | exports
| imports | locals
ChunkId = string()
AbstractCode = {AbstVersion, forms()}
| no_abstract_code
AbstVersion = atom()
Attribute = atom()
AttributeValue = term()
Module = Function = atom()
Arity = integer() >= 0
The list of attributes is sorted on Attribute, and
each attribute name occurs once in the list. The attribute
values occur in the same order as on the file. The lists of
functions are also sorted. It is not checked that the forms
conform to the abstract format indicated by AbstVersion.
chunks(FileName, [ChunkRef]) ->
{ok, {ModuleName, [ChunkData]}} | {error, Module, Reason}
FileName = string() | atom()ModuleName = string()Reason = {not_a_file_name, term()}
| {not_a_list, term()}
| {not_a_beam_file, FileName}
| {missing_chunk, FileName, "FOR1"}
| {form_not_beam, FileName}
| {form_too_big, FileName, FormSize, FileSize}
| {invalid_beam_file, FileName, FilePosition}
| {file_error, FileName, FileError}
| {invalid_chunk, FileName, "Atom"}
| {missing_chunk, FileName, ChunkId}
| {unknown_chunk, FileName, atom()}
| {chunk_too_big, FileName, ChunkId, ChunkSize, FileSize}
| {invalid_chunk, FileName, ChunkId}
| {file_error, FileName, FileError}
| {not_a_beam_handle, pid()}
The chunks/2 function reads chunk data for selected
chunks. The order of the returned list of chunk data is determined
by the order of the list of chunks references; if each
chunk data were replaced by the tag, the result would be the
given list.
version(FileName) ->
{ok, {ModuleName, Version}} | {error, Module, Reason}
FileName = string() | atom()ModuleName = string()Version = [term()]The version/1 function returns the module version(s)
found on a BEAM file.
See chunks/2 for possible error reasons.
FileName = string() | atom()ChunkInfo = {ChunkId, StartPosition, Size}StartPosition = Size = integer() > 0Reason = {not_a_file_name, term()}
| {not_a_beam_file, FileName}
| {missing_chunk, FileName, "FOR1"}
| {form_not_beam, FileName}
| {form_too_big, FileName, FormSize, FileSize}
| {invalid_beam_file, FileName, FilePosition}
| {file_error, FileName, FileError}
| {invalid_chunk, FileName, "Atom"}
The info/1 function extracts some information about
a BEAM file: the file name, the module name, and
for each chunk the identifier as well as the position and size
in bytes of the chunk data.
format_error(Error) -> character_list()
Given the error returned by any function in this module,
the function format_error returns a descriptive string
of the error in English. For file errors, the function
format_error/1 in the file module is called.