From 68d53c01b0b8e9a007a6a30158c19e34b2d2a34e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Wed, 18 May 2016 15:53:35 +0200 Subject: Update STDLIB documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder. --- lib/stdlib/doc/src/beam_lib.xml | 528 ++++++++++++++++++++++------------------ 1 file changed, 288 insertions(+), 240 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 7c89c8b43e..d5ec90b060 100644 --- a/lib/stdlib/doc/src/beam_lib.xml +++ b/lib/stdlib/doc/src/beam_lib.xml @@ -4,7 +4,7 @@
- 20002015 + 20002016 Ericsson AB. All Rights Reserved. @@ -29,137 +29,159 @@ PA1
beam_lib - An Interface To the BEAM File Format + An interface to the BEAM file format. -

beam_lib provides an interface to files created by - the BEAM compiler ("BEAM files"). The format used, a variant of +

This module 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:

+ (atoms) rather than identifiers (strings). The recognized names + and the corresponding identifiers are as follows:

+ abstract_code ("Abst") + atoms ("Atom") attributes ("Attr") compile_info ("CInf") exports ("ExpT") - labeled_exports ("ExpT") imports ("ImpT") indexed_imports ("ImpT") - locals ("LocT") + labeled_exports ("ExpT") labeled_locals ("LocT") - atoms ("Atom") + locals ("LocT")
Debug Information/Abstract Code -

The option debug_info can be given to the compiler (see - compile(3)) - in order to have debug information in the form of abstract code - (see The Abstract Format - in ERTS User's Guide) stored in the abstract_code chunk. +

Option debug_info can be specified to the Compiler (see + compile(3)) + to have debug information in the form of abstract code (see section + The Abstract Format in the + ERTS User's Guide) stored in the abstract_code chunk. Tools such as Debugger and Xref require the debug information to be included.

+

Source code can be reconstructed from the debug information. - Use encrypted debug information (see below) to prevent this.

+ To prevent this, use encrypted debug information (see below).

 +

The debug information can also be removed from BEAM files - using strip/1, - strip_files/1 and/or - strip_release/1.

+ using strip/1, + strip_files/1, and/or + strip_release/1.

-
- Reconstructing source code -

Here is an example of how to reconstruct source code from - the debug information in a BEAM file Beam:

- - {ok,{_,[{abstract_code,{_,AC}}]}} = beam_lib:chunks(Beam,[abstract_code]). - io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]). -
-
- Encrypted debug information -

The debug information can be encrypted in order to keep - the source code secret, but still being able to use tools such as - Xref or Debugger.

-

To use encrypted debug information, a key must be provided to - the compiler and beam_lib. The key is given as a string and - it is recommended that it contains at least 32 characters and - that both upper and lower case letters as well as digits and - special characters are used.

-

The default type -- and currently the only type -- of crypto - algorithm is des3_cbc, three rounds of DES. The key string - will be scrambled using erlang:md5/1 to generate - the actual keys used for des3_cbc.

- -

As far as we know by the time of writing, it is - infeasible to break des3_cbc encryption without any - knowledge of the key. Therefore, as long as the key is kept - safe and is unguessable, the encrypted debug information - should be safe from intruders.

- -

There are two ways to provide the key:

- - -

Use the compiler option {debug_info,Key}, see - compile(3), - and the function - crypto_key_fun/1 - to register a fun which returns the key whenever - beam_lib needs to decrypt the debug information.

-

If no such fun is registered, beam_lib will instead - search for a .erlang.crypt file, see below.

- - -

Store the key in a text file named .erlang.crypt.

-

In this case, the compiler option encrypt_debug_info - can be used, see - compile(3).

- - + +
+ Reconstruct Source Code +

The following example shows how to reconstruct source code from + the debug information in a BEAM file Beam:

+ + +{ok,{_,[{abstract_code,{_,AC}}]}} = beam_lib:chunks(Beam,[abstract_code]). +io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).
-
- .erlang.crypt -

beam_lib searches for .erlang.crypt in the current - directory and then the home directory for the current user. If - the file is found and contains a key, beam_lib will - implicitly create a crypto key fun and register it.

-

The .erlang.crypt file should contain a single list of - tuples:

- - {debug_info, Mode, Module, Key} -

Mode is the type of crypto algorithm; currently, the only - allowed value thus is des3_cbc. Module is either an - atom, in which case Key will only be used for the module - Module, or [], in which case Key will be - used for all modules. Key is the non-empty key string.

-

The Key in the first tuple where both Mode and - Module matches will be used.

-

Here is an example of an .erlang.crypt file that returns - the same key for all modules:

- + Encrypted Debug Information +

The debug information can be encrypted to keep + the source code secret, but still be able to use tools such as + Debugger or Xref.

+ +

To use encrypted debug information, a key must be provided to + the compiler and beam_lib. The key is specified as a string. + It is recommended that the string contains at least 32 characters and + that both upper and lower case letters as well as digits and + special characters are used.

+ +

The default type (and currently the only type) of crypto + algorithm is des3_cbc, three rounds of DES. The key string + is scrambled using + erlang:md5/1 + to generate the keys used for des3_cbc.

+ + +

As far as we know by the time of writing, it is + infeasible to break des3_cbc encryption without any + knowledge of the key. Therefore, as long as the key is kept + safe and is unguessable, the encrypted debug information + should be safe from intruders.

+ + +

The key can be provided in the following two ways:

+ + + +

Use Compiler option {debug_info,Key}, see + compile(3) + and function + crypto_key_fun/1 + to register a fun that returns the key whenever + beam_lib must decrypt the debug information.

+

If no such fun is registered, beam_lib instead + searches for an .erlang.crypt file, see the next section.

+ + +

Store the key in a text file named .erlang.crypt.

+

In this case, Compiler option encrypt_debug_info + can be used, see + compile(3). +

+ + +
+ +
+ .erlang.crypt +

beam_lib searches for .erlang.crypt in the current + directory and then the home directory for the current user. If + the file is found and contains a key, beam_lib + implicitly creates a crypto key fun and registers it.

+ +

File .erlang.crypt is to contain a single list of tuples:

+ + +{debug_info, Mode, Module, Key} + +

Mode is the type of crypto algorithm; currently, the only + allowed value is des3_cbc. Module is either an + atom, in which case Key is only used for the module + Module, or [], in which case Key is + used for all modules. Key is the non-empty key string.

+ +

Key in the first tuple where both Mode and + Module match is used.

+ +

The following is an example of an .erlang.crypt file that returns + the same key for all modules:

+ + 7}|pc/DM6Cga*68$Mw]L#&_Gejr]G^"}].]]> -

And here is a slightly more complicated example of an - .erlang.crypt which provides one key for the module - t, and another key for all other modules:

- The following is a slightly more complicated example of an + .erlang.crypt providing one key for module + t and another key for all other modules:

+ + 7}|pc/DM6Cga*68$Mw]L#&_Gejr]G^"}].]]> - -

Do not use any of the keys in these examples. Use your own - keys.

- -
+ + +

Do not use any of the keys in these examples. Use your own keys.

+ +

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

 @@ -167,7 +189,7 @@

The list of attributes is sorted on Attribute - (in attrib_entry()), and each + (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.

@@ -186,8 +208,8 @@

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.

+ indicated by AbstVersion. no_abstract_code + means that chunk "Abst" is present, but empty.

 @@ -230,78 +252,163 @@

Reads chunk data for all chunks.

 + + + + Create a BEAM module from a list of chunks. + +

Builds a BEAM module (as a binary) from a list of chunks.

+ + + - Read selected chunks from a BEAM file or binary + Read selected chunks from a BEAM file or binary. -

Reads chunk data for selected chunks refs. The order of +

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

 + - Read selected chunks from a BEAM file or binary + Read selected chunks from a BEAM file or binary. -

Reads chunk data for selected chunks refs. The order of +

Reads chunk data for selected chunks references. 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, - 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 +

By default, if any requested chunk is missing in + Beam, an error tuple is returned. + However, if option allow_missing_chunks is specified, + a result is returned even if chunks are missing. + In the result list, any missing chunks are represented as {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 + Notice however that if chunk "Atom" is missing, that is + considered a fatal error and the return value is an error tuple.

 + - - Creates a BEAM module from a list of chunks + + Unregister the current crypto key fun. -

Builds a BEAM module (as a binary) from a list of chunks.

+

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

+

Returns either {ok, undefined} if no crypto key fun is + registered, or {ok, Term}, where Term is + the return value from CryptoKeyFun(clear), see + crypto_key_fun/1.

 + - - Read the BEAM file's module version + + Compare two BEAM files. + -

Returns the module version(s). A version is defined by - the module attribute -vsn(Vsn). If this attribute is - not specified, the version defaults to the checksum of - the module. Note that if the version Vsn is not a list, - it is made into one, that is {ok,{Module,[Vsn]}} is - returned. If there are several -vsn module attributes, - the result is the concatenated list of versions. Examples:

- 
-1> beam_lib:version(a). % -vsn(1).
-{ok,{a,[1]}}
-2> beam_lib:version(b). % -vsn([1]).
-{ok,{b,[1]}}
-3> beam_lib:version(c). % -vsn([1]). -vsn(2).
-{ok,{c,[1,2]}}
-4> beam_lib:version(d). % no -vsn attribute
-{ok,{d,[275613208176997377698094100858909383631]}}
+

Compares the contents of two BEAM files. If the module names + are the same, and all chunks except for chunk "CInf" + (the chunk containing the compilation information that is + returned by Module:module_info(compile)) + have the same contents in both files, + ok is returned. Otherwise an error message is returned.

 + - - Read the BEAM file's module version + + Compare the BEAM files in two directories. -

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

+

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

 + + + + Register a fun that provides a crypto key. + + + + +

Registers an unary fun + that is called if beam_lib must read an + abstract_code chunk that has been encrypted. The fun + is held in a process that is started by the function.

+

If a fun is already registered when attempting to + register a fun, {error, exists} is returned.

+

The fun must handle the following arguments:

+ +CryptoKeyFun(init) -> ok | {ok, NewCryptoKeyFun} | {error, Term} +

Called when the fun is registered, in the process that holds + the fun. Here the crypto key fun can do any necessary + initializations. If {ok, NewCryptoKeyFun} is returned, + NewCryptoKeyFun is registered instead of + CryptoKeyFun. If {error, Term} is returned, + the registration is aborted and crypto_key_fun/1 + also returns {error, Term}.

+ +CryptoKeyFun({debug_info, Mode, Module, Filename}) -> Key +

Called when the key is needed for module Module + in the file named Filename. Mode is the type of + crypto algorithm; currently, the only possible value is + des3_cbc. The call is to fail (raise an exception) if + no key is available.

+ +CryptoKeyFun(clear) -> term() +

Called before the fun is unregistered. Here any cleaning up + can be done. The return value is not important, but is passed + back to the caller of clear_crypto_key_fun/0 as part + of its return value.

+ + + + + + Compare the BEAM files in two directories. + +

Compares the BEAM files in two directories as + cmp_dirs/2, but the + names of files that exist in only one directory or are different are + presented on standard output.

+ + + + + + Return an English description of a BEAM read error reply. + + +

For a specified error returned by any function in this module, + this function returns a descriptive string + of the error in English. For file errors, function + file:format_error(Posix) + is to be called.

+ + + - Information about a BEAM file + Information about a BEAM file.

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.

@@ -310,7 +417,8 @@

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.

@@ -318,135 +426,75 @@ + - - Compare two BEAM files - - -

Compares the contents of two BEAM files. If the module names - are the same, and all chunks except for the "CInf" chunk - (the chunk containing the compilation information which is - returned by Module:module_info(compile)) - have the same contents in both files, - ok is returned. Otherwise an error message is returned.

- - - - - Compare the BEAM files in two directories - -

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 - are considered different by cmp/2 are returned as - pairs {Filename1, Filename2} where - Filename1 (Filename2) exists in directory - Dir1 (Dir2).

- - - - - Compare the BEAM files in two directories + + Read the module version of the BEAM file. -

The diff_dirs/2 function compares the BEAM files in - two directories the way cmp_dirs/2 does, but names of - files that exist in only one directory or are different are - presented on standard output.

+

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

 + - Removes chunks not needed by the loader from a BEAM file + Remove chunks not needed by the loader from a BEAM file. + -

The strip/1 function removes all chunks from a BEAM +

Removes all chunks from a BEAM file except those needed by the loader. In particular, - the debug information (abstract_code chunk) is removed.

+ the debug information (chunk abstract_code) is removed.

 + - Removes chunks not needed by the loader from BEAM files + Removes chunks not needed by the loader from BEAM files. + -

The strip_files/1 function removes all chunks except +

Removes all chunks except those needed by the loader from BEAM files. In particular, - the debug information (abstract_code chunk) is removed. - The returned list contains one element for each given file - name, in the same order as in Files.

+ the debug information (chunk abstract_code) is removed. + The returned list contains one element for each specified filename, + in the same order as in Files.

 + - Removes chunks not needed by the loader from all BEAM files of a release + Remove chunks not needed by the loader from all BEAM files of + a release. -

The strip_release/1 function removes all chunks +

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

 + - - Return an English description of a BEAM read error reply - -

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 - file:format_error(Posix) should be called.

- - - - - Register a fun that provides a crypto key - - - - -

The crypto_key_fun/1 function registers a unary fun - that will be called if beam_lib needs to read an - abstract_code chunk that has been encrypted. The fun - is held in a process that is started by the function.

-

If there already is a fun registered when attempting to - register a fun, {error, exists} is returned.

-

The fun must handle the following arguments:

- - CryptoKeyFun(init) -> ok | {ok, NewCryptoKeyFun} | {error, Term} -

Called when the fun is registered, in the process that holds - the fun. Here the crypto key fun can do any necessary - initializations. If {ok, NewCryptoKeyFun} is returned - then NewCryptoKeyFun will be registered instead of - CryptoKeyFun. If {error, Term} is returned, - the registration is aborted and crypto_key_fun/1 - returns {error, Term} as well.

- - CryptoKeyFun({debug_info, Mode, Module, Filename}) -> Key -

Called when the key is needed for the module Module - in the file named Filename. Mode is the type of - crypto algorithm; currently, the only possible value thus is - des3_cbc. The call should fail (raise an exception) if - there is no key available.

- - CryptoKeyFun(clear) -> term() -

Called before the fun is unregistered. Here any cleaning up - can be done. The return value is not important, but is passed - back to the caller of clear_crypto_key_fun/0 as part - of its return value.

- - - - - Unregister the current crypto key fun + + Read the module version of the BEAM file. -

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

-

The clear_crypto_key_fun/1 either returns - {ok, undefined} if there was no crypto key fun - registered, or {ok, Term}, where Term is - the return value from CryptoKeyFun(clear), see - crypto_key_fun/1.

+

Returns the module version or versions. A version is defined by + module attribute -vsn(Vsn). If this attribute is + not specified, the version defaults to the checksum of + the module. Notice that if version Vsn is not a list, + it is made into one, that is {ok,{Module,[Vsn]}} is + returned. If there are many -vsn module attributes, + the result is the concatenated list of versions.

+

Examples:

+ 
+1> beam_lib:version(a). % -vsn(1).
+{ok,{a,[1]}}
+2> beam_lib:version(b). % -vsn([1]).
+{ok,{b,[1]}}
+3> beam_lib:version(c). % -vsn([1]). -vsn(2).
+{ok,{c,[1,2]}}
+4> beam_lib:version(d). % no -vsn attribute
+{ok,{d,[275613208176997377698094100858909383631]}}
 -- cgit v1.2.3