File: beam_lib.html

package info (click to toggle)
erlang-doc-html 1%3A10.b.1a-1
links: PTS
area: main
in suites: sarge
size: 22,488 kB
ctags: 9,933
sloc: erlang: 505; ansic: 323; perl: 61; sh: 45; makefile: 39
file content (433 lines) | stat: -rw-r--r-- 12,122 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.2 -->
<HTML>
<HEAD>
  <TITLE>beam_lib</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>beam_lib</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
beam_lib
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
An interface to the BEAM file format
</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P><CODE>beam_lib</CODE> provides an interface to files 
created by the BEAM compiler (&#34;BEAM files&#34;). The format used,
a variant of &#34;EA IFF 1985&#34; Standard for Interchange Format Files,
divides data into chunks.


<P>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 <CODE>abstract_code</CODE>
(&#34;Abst&#34;), <CODE>attributes</CODE> (&#34;Attr&#34;), <CODE>exports</CODE> (&#34;ExpT&#34;),
<CODE>labeled_exports</CODE> (&#34;ExpT&#34;), <CODE>imports</CODE> (&#34;ImpT&#34;),
<CODE>locals</CODE> (&#34;LocT&#34;), <CODE>labeled_locals</CODE> (&#34;LocT&#34;), and
<CODE>atoms</CODE> (&#34;Atom&#34;).


<P>The syntax of the compound term (<CODE>ChunkData</CODE>) is as follows:

<P>
<UL>

<LI>
<CODE>ChunkData = {ChunkId, binary()}
         | {abstract_code, AbstractCode}
         | {attributes, [{Attribute, [AttributeValue]}]}
         | {exports, [{Function, Arity}]}
         | {labeled_exports, [{Function, Arity, Label}]}
         | {imports, [{Module, Function, Arity}]}
         | {locals, [{Function, Arity}]}]}
         | {labeled_locals, [{Function, Arity, Label}]}]}
         | {atoms, [{integer(), atom()}]}</CODE>
<BR>

</LI>


<LI>
<CODE>ChunkRef = ChunkId | ChunkName</CODE>
         <BR>

</LI>


<LI>
<CODE>ChunkName = abstract_code | attributes | exports 
         | labeled_exports | imports | locals | labeled_locals
         | atoms</CODE>
         <BR>

</LI>


<LI>
<CODE>ChunkId = string()</CODE>
         <BR>

</LI>


<LI>
<CODE>AbstractCode = {AbstVersion, forms()}
         | no_abstract_code</CODE>
         <BR>

</LI>


<LI>
<CODE>AbstVersion = atom()</CODE>
         <BR>

</LI>


<LI>
<CODE>Attribute = atom()</CODE>
         <BR>

</LI>


<LI>
<CODE>AttributeValue = term()</CODE>
         <BR>

</LI>


<LI>
<CODE>Module = Function = atom()</CODE>
         <BR>

</LI>


<LI>
<CODE>Arity = integer() &#62;= 0</CODE>
         <BR>

</LI>


<LI>
<CODE>Label = integer() &#62;= 0</CODE>
<BR>

</LI>


</UL>

<P>The list of attributes is sorted on <CODE>Attribute</CODE>, 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 <CODE>AbstVersion</CODE>.


<P><CODE>no_abstract_code</CODE> means that the &#34;Abst&#34; chunk is present,
but empty.


<P>Each of the functions described below accept either
a filename or a binary containing a beam module.


</DIV>

<H3>EXPORTS</H3>

<P><A NAME="chunks/2"><STRONG><CODE>chunks(FileNameOrBinary, [ChunkRef]) -&#62; 
{ok, {Module, [ChunkData]}} | {error, Module, Reason}
</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>FileNameOrBinary = string() | atom() | binary()</CODE></STRONG><BR>
<STRONG><CODE>Reason = {unknown_chunk, FileName, atom()}
         | -see info/1-
        </CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <CODE>chunks/2</CODE> 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.


</DIV>

<P><A NAME="version/1"><STRONG><CODE>version(FileNameOrBinary) -&#62; 
{ok, {Module, Version}} | {error, Module, Reason}
</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>FileNameOrBinary = string() | atom() | binary()</CODE></STRONG><BR>
<STRONG><CODE>Version = [term()]</CODE></STRONG><BR>
<STRONG><CODE>Reason = -see chunks/2-
</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <CODE>version/1</CODE> function returns the module version(s)
         found in a BEAM file.

</DIV>

<P><A NAME="info/1"><STRONG><CODE>info(FileNameOrBinary) -&#62; 
[SourceRef, {module, Module}, {chunks, [ChunkInfo]}]
         | {error, Module, Reason}
</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>FileName = string() | atom()</CODE></STRONG><BR>
<STRONG><CODE>FileNameOrBinary = FileName | binary()</CODE></STRONG><BR>
<STRONG><CODE>SourceRef = {file, FileName} | {binary, binary()}</CODE></STRONG><BR>
<STRONG><CODE>ChunkInfo = {ChunkId, StartPosition, Size}</CODE></STRONG><BR>
<STRONG><CODE>StartPosition = integer() &#62; 0</CODE></STRONG><BR>
<STRONG><CODE>Size = integer() &#62;= 0</CODE></STRONG><BR>
<STRONG><CODE>Reason = {chunk_too_big, FileName, ChunkId, ChunkSize, FileSize}
| {invalid_beam_file, FileName, FilePosition}
| {invalid_chunk, FileName, ChunkId}
| {missing_chunk, FileName, ChunkId}
| {not_a_beam_file, FileName} 
         | {file_error, FileName, FileError}
        </CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <CODE>info/1</CODE> 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.

</DIV>

<P><A NAME="cmp/2"><STRONG><CODE>cmp(FileNameOrBinary, FileNameOrBinary) -&#62; 
         ok | {error, Module, Reason}
</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>FileName = string() | atom()</CODE></STRONG><BR>
<STRONG><CODE>FileNameOrBinary = FileName | binary()</CODE></STRONG><BR>
<STRONG><CODE>Reason = {modules_different, Module, Module}
| {chunks_different, ChunkId}
         | -see info/1-
        </CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <CODE>cmp/2</CODE> function compares the contents of two BEAM
         files. If the module names are the same, and the chunks with
         the identifiers &#34;Code&#34;, &#34;ExpT&#34;, &#34;ImpT&#34;, &#34;StrT&#34;, and &#34;Atom&#34;
         have the same contents in both files, <CODE>ok</CODE> is
         returned. Otherwise an error message is returned.

</DIV>

<P><A NAME="cmp_dirs/2"><STRONG><CODE>cmp_dirs(Directory1, Directory2) -&#62; 
{Only1, Only2, Different} | {error, Module, Reason}
</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Directory1 = Directory2 = string() | atom()</CODE></STRONG><BR>
<STRONG><CODE>Different = [{FileName1, FileName2}]</CODE></STRONG><BR>
<STRONG><CODE>Only1 = Only2 = [FileName]</CODE></STRONG><BR>
<STRONG><CODE>FileName = FileName1 = FileName2 = string()</CODE></STRONG><BR>
<STRONG><CODE>Reason = -see info/1-</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <CODE>cmp_dirs/2</CODE> function compares the BEAM files in
         two directories. Only files with extension &#34;.beam&#34; are
         compared. BEAM files that exist in directory
         <CODE>Directory1</CODE> (<CODE>Directory2</CODE>) only are returned in
         <CODE>Only1</CODE> (<CODE>Only2</CODE>). BEAM files that exist on both
         directories but are considered different by <CODE>cmp/2</CODE> are
         returned as pairs {<CODE>FileName1</CODE>, <CODE>FileName2</CODE>} where
         <CODE>FileName1</CODE> (<CODE>FileName2</CODE>) exists in directory
         <CODE>Directory1</CODE> (<CODE>Directory2</CODE>).

</DIV>

<P><A NAME="diff_dirs/2"><STRONG><CODE>diff_dirs(Directory1, Directory2) -&#62; 
ok | {error, Module, Reason}
</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Directory1 = Directory2 = string() | atom()</CODE></STRONG><BR>
<STRONG><CODE>Reason = -see info/1-</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

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

</DIV>

<P><A NAME="strip/1"><STRONG><CODE>strip(FileNameOrBinary) -&#62; 
{ok, {Module, FileNameOrBinary}} | {error, Module, Reason}
</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>FileName = string() | atom()</CODE></STRONG><BR>
<STRONG><CODE>FileNameOrBinary = FileName | binary()</CODE></STRONG><BR>
<STRONG><CODE>Reason = -see info/1-
        </CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <CODE>strip/1</CODE> function removes all chunks from a BEAM
         file except those needed by the loader. In particular, the
         abstract code is removed. The module name found in the file
         and the file name, possibly with the &#34;.beam&#34; extension
         added, are returned.

</DIV>

<P><A NAME="strip_files/1"><STRONG><CODE>strip_files(Files) -&#62; 
{ok, [{Module, FileNameOrBinary]}} | {error, Module, Reason}
</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Files = [FileNameOrBinary]</CODE></STRONG><BR>
<STRONG><CODE>FileName = string() | atom()</CODE></STRONG><BR>
<STRONG><CODE>FileNameOrBinary = FileName | binary()</CODE></STRONG><BR>
<STRONG><CODE>Reason = -see info/1-
        </CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <CODE>strip_files/1</CODE> function removes all chunks except
         those needed by the loader from BEAM files. In particular,
         the abstract code is removed. The returned list contains one
         element for each given file name, ordered as the given
         list. The list element is a pair of the module name found in
         the file and the file name, the latter possibly with the
         &#34;.beam&#34; extension added.

</DIV>

<P><A NAME="strip_release/1"><STRONG><CODE>strip_release(Directory) -&#62; 
{ok, [{Module, FileName]}} | {error, Module, Reason}
</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Directory = string() | atom()</CODE></STRONG><BR>
<STRONG><CODE>FileName = string()</CODE></STRONG><BR>
<STRONG><CODE>Reason = -see info/1-
        </CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>The <CODE>strip_release/1</CODE> function removes all chunks
         except those needed by the loader from the BEAM files of a
         release. <CODE>Directory</CODE> should be the installation root
         directory. For example, the current OTP release can be
         stripped with the call
         <CODE>beam_lib:strip_release(code:root_dir())</CODE>. The returned
         list contains module names and file names of stripped files.

</DIV>

<P><A NAME="format_error/1"><STRONG><CODE>format_error(Error) -&#62; character_list()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Given the error returned by any function in this module, 
         the function <CODE>format_error</CODE> returns a descriptive string
         of the error in English. For file errors, the function 
         <CODE>format_error/1</CODE> in the <CODE>file</CODE> module is called.

</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Hans Bolinder - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>stdlib 1.13.2<BR>
Copyright &copy; 1991-2004
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>