From 229d0d8ca88bc344bed89e46541b325c1d267996 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Fri, 6 May 2011 15:58:09 +0200 Subject: r Use Erlang specs and types for documentation --- lib/stdlib/doc/src/beam_lib.xml | 271 +++++++++++++++------------------------- 1 file changed, 98 insertions(+), 173 deletions(-) (limited to 'lib/stdlib/doc/src/beam_lib.xml') diff --git a/lib/stdlib/doc/src/beam_lib.xml b/lib/stdlib/doc/src/beam_lib.xml index adc411e272..013e94c393 100644 --- a/lib/stdlib/doc/src/beam_lib.xml +++ b/lib/stdlib/doc/src/beam_lib.xml @@ -4,7 +4,7 @@
- 20002010 + 20002011 Ericsson AB. All Rights Reserved. @@ -154,70 +154,78 @@ -
- DATA TYPES - -beam() -> Module | Filename | binary() - Module = atom() - Filename = string() | atom() -

Each of the functions described below accept either the module - name, the filename, or a binary containing the beam module.

- -chunkdata() = {ChunkId, DataB} | {ChunkName, DataT} - ChunkId = chunkid() - DataB = binary() - {ChunkName, DataT} = - {abstract_code, AbstractCode} - | {attributes, [{Attribute, [AttributeValue]}]} - | {compile_info, [{InfoKey, [InfoValue]}]} - | {exports, [{Function, Arity}]} - | {labeled_exports, [{Function, Arity, Label}]} - | {imports, [{Module, Function, Arity}]} - | {indexed_imports, [{Index, Module, Function, Arity}]} - | {locals, [{Function, Arity}]}]} - | {labeled_locals, [{Function, Arity, Label}]}]} - | {atoms, [{integer(), atom()}]} - AbstractCode = {AbstVersion, Forms} | no_abstract_code - AbstVersion = atom() - Attribute = atom() - AttributeValue = term() - Module = Function = atom() - Arity = int() - Label = int() -

It is not checked that the forms conform to the abstract format - indicated by AbstVersion. no_abstract_code means - that the "Abst" chunk is present, but empty.

-

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 in the file. The lists of functions - are also sorted.

- -chunkid() = "Abst" | "Attr" | "CInf" - | "ExpT" | "ImpT" | "LocT" - | "Atom" + + + + +

Each of the functions described below accept either the + module name, the filename, or a binary containing the beam + module.

+ + + + + +

The list of attributes is sorted on Attribute + (in attrib_entry()), and each + attribute name occurs once in the list. The attribute values + occur in the same order as in the file. The lists of functions + are also sorted.

+ + + + + +

"Abst" | "Attr" | "CInf" | "ExpT" | "ImpT" | "LocT" | "Atom"

+ + + + + + + + +

It is not checked that the forms conform to the abstract format + indicated by AbstVersion. no_abstract_code means + that the "Abst" chunk is present, but empty.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -chunkname() = abstract_code | attributes | compile_info - | exports | labeled_exports - | imports | indexed_imports - | locals | labeled_locals - | atoms - -chunkref() = chunkname() | chunkid() -
- chunks(Beam, [ChunkRef]) -> {ok, {Module, [ChunkData]}} | {error, beam_lib, Reason} + Read selected chunks from a BEAM file or binary - - Beam = beam() - ChunkRef = chunkref() - Module = atom() - ChunkData = chunkdata() - Reason = {unknown_chunk, Filename, atom()} -   | {key_missing_or_invalid, Filename, abstract_code} -   | Reason1 -- see info/1 -  Filename = string() -

Reads chunk data for selected chunks refs. The order of the returned list of chunk data is determined by the order @@ -225,43 +233,26 @@ chunkref() = chunkname() | chunkid() - chunks(Beam, [ChunkRef], [Option]) -> {ok, {Module, [ChunkResult]}} | {error, beam_lib, Reason} + Read selected chunks from a BEAM file or binary - - Beam = beam() - ChunkRef = chunkref() - Module = atom() - Option = allow_missing_chunks - ChunkResult = {chunkref(), ChunkContents} | {chunkref(), missing_chunk} - Reason = {missing_chunk, Filename, atom()} -   | {key_missing_or_invalid, Filename, abstract_code} -   | Reason1 -- see info/1 -  Filename = string() -

Reads chunk data for selected chunks refs. The order of the returned list of chunk data is determined by the order of the list of chunks references.

-

By default, if any requested chunk is missing in Beam, +

By default, if any requested chunk is missing in Beam, an error tuple is returned. However, if the option allow_missing_chunks has been given, a result will be returned even if chunks are missing. In the result list, any missing chunks will be represented as - {ChunkRef,missing_chunk}. + {ChunkRef,missing_chunk}. Note, however, that if the "Atom" chunk if missing, that is considered a fatal error and the return value will be an error tuple.

 - version(Beam) -> {ok, {Module, [Version]}} | {error, beam_lib, Reason} + Read the BEAM file's module version - - Beam = beam() - Module = atom() - Version = term() - Reason -- see chunks/2 -

Returns the module version(s). A version is defined by the module attribute -vsn(Vsn). If this attribute is @@ -282,51 +273,30 @@ chunkref() = chunkname() | chunkid() - md5(Beam) -> {ok, {Module, MD5}} | {error, beam_lib, Reason} + Read the BEAM file's module version - - Beam = beam() - Module = atom() - MD5 = binary() - Reason -- see chunks/2 -

Calculates an MD5 redundancy check for the code of the module (compilation date and other attributes are not included).

 - info(Beam) -> [{Item, Info}] | {error, beam_lib, Reason1} + Information about a BEAM file - - Beam = beam() - Item, Info -- see below - Reason1 = {chunk_too_big, Filename, ChunkId, ChunkSize, FileSize} -   | {invalid_beam_file, Filename, Pos} -   | {invalid_chunk, Filename, ChunkId} -   | {missing_chunk, Filename, ChunkId} -   | {not_a_beam_file, Filename} -   | {file_error, Filename, Posix} -  Filename = string() -  ChunkId = chunkid() -  ChunkSize = FileSize = int() -  Pos = int() -  Posix = posix() -- see file(3) -

Returns a list containing some information about a BEAM file as tuples {Item, Info}:

- {file, Filename} | {binary, Binary} + {file, Filename} | {binary, Binary}

The name (string) of the BEAM file, or the binary from which the information was extracted.

 - {module, Module} + {module, Module}

The name (atom) of the module.

 - {chunks, [{ChunkId, Pos, Size}]} + {chunks, [{ChunkId, Pos, Size}]}

For each chunk, the identifier (string) and the position and size of the chunk data, in bytes.

@@ -335,17 +305,9 @@ chunkref() = chunkname() | chunkid() - cmp(Beam1, Beam2) -> ok | {error, beam_lib, Reason} + Compare two BEAM files - - Beam1 = Beam2 = beam() - Reason = {modules_different, Module1, Module2} -   | {chunks_different, ChunkId} -   | different_chunks -   | Reason1 -- see info/1 -  Module1 = Module2 = atom() -  ChunkId = chunkid() - +

Compares the contents of two BEAM files. If the module names are the same, and all chunks except for the "CInf" chunk @@ -356,34 +318,23 @@ chunkref() = chunkname() | chunkid() - cmp_dirs(Dir1, Dir2) -> {Only1, Only2, Different} | {error, beam_lib, Reason1} + Compare the BEAM files in two directories - - Dir1 = Dir2 = string() | atom() - Different = [{Filename1, Filename2}] - Only1 = Only2 = [Filename] - Filename = Filename1 = Filename2 = string() - Reason1 = {not_a_directory, term()} | -- see info/1 -

The cmp_dirs/2 function compares the BEAM files in two directories. Only files with extension ".beam" are - compared. BEAM files that exist in directory Dir1 - (Dir2) only are returned in Only1 - (Only2). BEAM files that exist on both directories but + compared. BEAM files that exist in directory Dir1 + (Dir2) only are returned in Only1 + (Only2). BEAM files that exist on both directories but are considered different by cmp/2 are returned as - pairs {Filename1, Filename2} where - Filename1 (Filename2) exists in directory - Dir1 (Dir2).

+ pairs {Filename1, Filename2} where + Filename1 (Filename2) exists in directory + Dir1 (Dir2).

 - diff_dirs(Dir1, Dir2) -> ok | {error, beam_lib, Reason1} + Compare the BEAM files in two directories - - Dir1 = Dir2 = string() | atom() - Reason1 = {not_a_directory, term()} | -- see info/1 -

The diff_dirs/2 function compares the BEAM files in two directories the way cmp_dirs/2 does, but names of @@ -392,13 +343,8 @@ chunkref() = chunkname() | chunkid() - strip(Beam1) -> {ok, {Module, Beam2}} | {error, beam_lib, Reason1} + Removes chunks not needed by the loader from a BEAM file - - Beam1 = Beam2 = beam() - Module = atom() - Reason1 -- see info/1 -

The strip/1 function removes all chunks from a BEAM file except those needed by the loader. In particular, @@ -406,15 +352,8 @@ chunkref() = chunkname() | chunkid() - strip_files(Files) -> {ok, [{Module, Beam2}]} | {error, beam_lib, Reason1} + Removes chunks not needed by the loader from BEAM files - - Files = [Beam1] -  Beam1 = beam() - Module = atom() - Beam2 = beam() - Reason1 -- see info/1 -

The strip_files/1 function removes all chunks except those needed by the loader from BEAM files. In particular, @@ -424,30 +363,20 @@ chunkref() = chunkname() | chunkid() - strip_release(Dir) -> {ok, [{Module, Filename]}} | {error, beam_lib, Reason1} + Removes chunks not needed by the loader from all BEAM files of a release - - Dir = string() | atom() - Module = atom() - Filename = string() - Reason1 = {not_a_directory, term()} | -- see info/1 -

The strip_release/1 function removes all chunks except those needed by the loader from the BEAM files of a - release. Dir should be the installation root + release. Dir should be the installation root directory. For example, the current OTP release can be stripped with the call beam_lib:strip_release(code:root_dir()).

 - format_error(Reason) -> Chars + Return an English description of a BEAM read error reply - - Reason -- see other functions - Chars = [char() | Chars] -

Given the error returned by any function in this module, the function format_error returns a descriptive string @@ -456,12 +385,11 @@ chunkref() = chunkname() | chunkid() - crypto_key_fun(CryptoKeyFun) -> ok | {error, Reason} + Register a fun that provides a crypto key - - CryptoKeyFun = fun() -- see below - Reason = badfun | exists | term() - + + +

The crypto_key_fun/1 function registers a unary fun that will be called if beam_lib needs to read an @@ -495,11 +423,8 @@ chunkref() = chunkname() | chunkid() - clear_crypto_key_fun() -> {ok, Result} + Unregister the current crypto key fun - - Result = undefined | term() -

Unregisters the crypto key fun and terminates the process holding it, started by crypto_key_fun/1.

-- cgit v1.2.3