1beam_lib(3)                Erlang Module Definition                beam_lib(3)
2
3
4

NAME

6       beam_lib - An interface to the BEAM file format.
7

DESCRIPTION

9       This module provides an interface to files created by the BEAM Compiler
10       ("BEAM files"). The format used, a variant of "EA  IFF  1985"  Standard
11       for Interchange Format Files, divides data into chunks.
12
13       Chunk  data  can be returned as binaries or as compound terms. Compound
14       terms are returned when chunks are referenced by names  (atoms)  rather
15       than  identifiers (strings). The recognized names and the corresponding
16       identifiers are as follows:
17
18         * atoms ("Atom")
19
20         * attributes ("Attr")
21
22         * compile_info ("CInf")
23
24         * debug_info ("Dbgi")
25
26         * exports ("ExpT")
27
28         * imports ("ImpT")
29
30         * indexed_imports ("ImpT")
31
32         * labeled_exports ("ExpT")
33
34         * labeled_locals ("LocT")
35
36         * locals ("LocT")
37

DEBUG INFORMATION/ABSTRACT CODE

39       Option debug_info can be specified to the Compiler (see compile(3))  to
40       have  debug  information, such as Erlang Abstract Format, stored in the
41       debug_info chunk. Tools such as Debugger and Xref require the debug in‐
42       formation to be included.
43
44   Warning:
45       Source code can be reconstructed from the debug information. To prevent
46       this, use encrypted debug information (see below).
47
48
49       The debug information  can  also  be  removed  from  BEAM  files  using
50       strip/1, strip_files/1, and/or strip_release/1.
51

RECONSTRUCT SOURCE CODE

53       The  following example shows how to reconstruct Erlang source code from
54       the debug information in a BEAM file Beam:
55
56       {ok,{_,[{abstract_code,{_,AC}}]}} = beam_lib:chunks(Beam,[abstract_code]).
57       io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).
58

ENCRYPTED DEBUG INFORMATION

60       The debug information can be encrypted to keep the source code  secret,
61       but still be able to use tools such as Debugger or Xref.
62
63       To  use encrypted debug information, a key must be provided to the com‐
64       piler and beam_lib. The key is specified as a string. It is recommended
65       that the string contains at least 32 characters and that both upper and
66       lower case letters as well as digits and special characters are used.
67
68       The default type (and currently the only type) of crypto  algorithm  is
69       des3_cbc,  three  rounds  of DES. The key string is scrambled using er‐
70       lang:md5/1 to generate the keys used for des3_cbc.
71
72   Note:
73       As far as we know by the time of writing, it  is  infeasible  to  break
74       des3_cbc  encryption  without  any  knowledge of the key. Therefore, as
75       long as the key is kept safe and is unguessable,  the  encrypted  debug
76       information should be safe from intruders.
77
78
79       The key can be provided in the following two ways:
80
81         * Use  Compiler option {debug_info_key,Key}, see compile(3) and func‐
82           tion crypto_key_fun/1 to register a fun that returns the key  when‐
83           ever beam_lib must decrypt the debug information.
84
85           If no such fun is registered, beam_lib instead searches for an .er‐
86           lang.crypt file, see the next section.
87
88         * Store the key in a text file named .erlang.crypt.
89
90           In this case, Compiler option encrypt_debug_info can be  used,  see
91           compile(3).
92

.ERLANG.CRYPT

94       beam_lib  searches  for .erlang.crypt in the current directory and then
95       the home directory for the current user. If the file is found and  con‐
96       tains a key, beam_lib implicitly creates a crypto key fun and registers
97       it.
98
99       File .erlang.crypt is to contain a single list of tuples:
100
101       {debug_info, Mode, Module, Key}
102
103       Mode is the type of crypto algorithm; currently, the only allowed value
104       is  des3_cbc.  Module is either an atom, in which case Key is only used
105       for the module Module, or [], in which case Key is used  for  all  mod‐
106       ules. Key is the non-empty key string.
107
108       Key in the first tuple where both Mode and Module match is used.
109
110       The  following  is an example of an .erlang.crypt file that returns the
111       same key for all modules:
112
113       [{debug_info, des3_cbc, [], "%>7}|pc/DM6Cga*68$Mw]L#&_Gejr]G^"}].
114
115       The following is  a  slightly  more  complicated  example  of  an  .er‐
116       lang.crypt providing one key for module t and another key for all other
117       modules:
118
119       [{debug_info, des3_cbc, t, "My KEY"},
120        {debug_info, des3_cbc, [], "%>7}|pc/DM6Cga*68$Mw]L#&_Gejr]G^"}].
121
122   Note:
123       Do not use any of the keys in these examples. Use your own keys.
124
125

DATA TYPES

127       beam() = file:filename() | binary()
128
129              Each of the functions described below accept either the filename
130              (as a string) or a binary containing the BEAM module.
131
132       chunkdata() =
133           {chunkid(), dataB()} |
134           {abstract_code, abst_code()} |
135           {debug_info, debug_info()} |
136           {attributes, [attrib_entry()]} |
137           {compile_info, [compinfo_entry()]} |
138           {exports, [{atom(), arity()}]} |
139           {labeled_exports, [labeled_entry()]} |
140           {imports, [mfa()]} |
141           {indexed_imports,
142            [{index(), module(), Function :: atom(), arity()}]} |
143           {locals, [{atom(), arity()}]} |
144           {labeled_locals, [labeled_entry()]} |
145           {atoms, [{integer(), atom()}]}
146
147              The  list  of  attributes  is sorted on Attribute (in attrib_en‐
148              try()) and each attribute name occurs once in the list. The  at‐
149              tribute values occur in the same order as in the file. The lists
150              of functions are also sorted.
151
152       chunkid() = nonempty_string()
153
154              "Attr" | "CInf" | "Dbgi" | "ExpT" | "ImpT" | "LocT" | "AtU8"
155
156       dataB() = binary()
157
158       debug_info() =
159           {DbgiVersion :: atom(), Backend :: module(), Data :: term()} |
160           no_debug_info
161
162              The format stored in the debug_info chunk. To retrieve  particu‐
163              lar   code   representation   from   the   backend,  Backend:de‐
164              bug_info(Format, Module, Data, Opts) must be invoked. Format  is
165              an  atom,  such  as  erlang_v1 for the Erlang Abstract Format or
166              core_v1 for Core Erlang. Module is the module represented by the
167              beam  file and Data is the value stored in the debug info chunk.
168              Opts is any list of values supported by the Backend. Backend:de‐
169              bug_info/4 must return {ok, Code} or {error, Term}.
170
171              Developers  must  always  invoke  the  debug_info/4 function and
172              never rely on the Data stored in the debug_info chunk, as it  is
173              opaque  and  may  change at any moment. no_debug_info means that
174              chunk "Dbgi" is present, but empty.
175
176       abst_code() =
177           {AbstVersion :: atom(), forms()} | no_abstract_code
178
179              It is not checked that the forms conform to the abstract  format
180              indicated  by  AbstVersion.  no_abstract_code  means  that chunk
181              "Abst" is present, but empty.
182
183              For modules compiled with OTP 20 onwards, the abst_code chunk is
184              automatically computed from the debug_info chunk.
185
186       forms() = [erl_parse:abstract_form() | erl_parse:form_info()]
187
188       compinfo_entry() = {InfoKey :: atom(), term()}
189
190       attrib_entry() =
191           {Attribute :: atom(), [AttributeValue :: term()]}
192
193       labeled_entry() = {Function :: atom(), arity(), label()}
194
195       index() = integer() >= 0
196
197       label() = integer()
198
199       chunkref() = chunkname() | chunkid()
200
201       chunkname() =
202           abstract_code | debug_info | attributes | compile_info |
203           exports | labeled_exports | imports | indexed_imports |
204           locals | labeled_locals | atoms
205
206       chnk_rsn() =
207           {unknown_chunk, file:filename(), atom()} |
208           {key_missing_or_invalid,
209            file:filename(),
210            abstract_code | debug_info} |
211           {missing_backend, file:filename(), module()} |
212           info_rsn()
213
214       info_rsn() =
215           {chunk_too_big,
216            file:filename(),
217            chunkid(),
218            ChunkSize :: integer() >= 0,
219            FileSize :: integer() >= 0} |
220           {invalid_beam_file,
221            file:filename(),
222            Position :: integer() >= 0} |
223           {invalid_chunk, file:filename(), chunkid()} |
224           {missing_chunk, file:filename(), chunkid()} |
225           {not_a_beam_file, file:filename()} |
226           {file_error, file:filename(), file:posix()}
227

EXPORTS

229       all_chunks(File :: beam()) ->
230                     {ok, beam_lib, [{chunkid(), dataB()}]} |
231                     {error, beam_lib, info_rsn()}
232
233              Reads chunk data for all chunks.
234
235       build_module(Chunks) -> {ok, Binary}
236
237              Types:
238
239                 Chunks = [{chunkid(), dataB()}]
240                 Binary = binary()
241
242              Builds a BEAM module (as a binary) from a list of chunks.
243
244       chunks(Beam, ChunkRefs) ->
245                 {ok, {module(), [chunkdata()]}} |
246                 {error, beam_lib, chnk_rsn()}
247
248              Types:
249
250                 Beam = beam()
251                 ChunkRefs = [chunkref()]
252
253              Reads  chunk  data  for selected chunks references. The order of
254              the returned list of chunk data is determined by  the  order  of
255              the list of chunks references.
256
257       chunks(Beam, ChunkRefs, Options) ->
258                 {ok, {module(), [ChunkResult]}} |
259                 {error, beam_lib, chnk_rsn()}
260
261              Types:
262
263                 Beam = beam()
264                 ChunkRefs = [chunkref()]
265                 Options = [allow_missing_chunks]
266                 ChunkResult =
267                     chunkdata() | {ChunkRef :: chunkref(), missing_chunk}
268
269              Reads  chunk  data  for selected chunks references. The order of
270              the returned list of chunk data is determined by  the  order  of
271              the list of chunks references.
272
273              By  default, if any requested chunk is missing in Beam, an error
274              tuple is returned. However, if  option  allow_missing_chunks  is
275              specified,  a  result is returned even if chunks are missing. In
276              the  result  list,  any  missing  chunks  are   represented   as
277              {ChunkRef,missing_chunk}. Notice however that if chunk "Atom" is
278              missing, that is considered a fatal error and the  return  value
279              is an error tuple.
280
281       clear_crypto_key_fun() -> undefined | {ok, Result}
282
283              Types:
284
285                 Result = undefined | term()
286
287              Unregisters  the crypto key fun and terminates the process hold‐
288              ing it, started by crypto_key_fun/1.
289
290              Returns either {ok, undefined} if no crypto key  fun  is  regis‐
291              tered,  or {ok, Term}, where Term is the return value from Cryp‐
292              toKeyFun(clear), see crypto_key_fun/1.
293
294       cmp(Beam1, Beam2) -> ok | {error, beam_lib, cmp_rsn()}
295
296              Types:
297
298                 Beam1 = Beam2 = beam()
299                 cmp_rsn() =
300                     {modules_different, module(), module()} |
301                     {chunks_different, chunkid()} |
302                     different_chunks |
303                     info_rsn()
304
305              Compares the contents of two BEAM files. If the module names are
306              the same, and all chunks except for chunk "CInf" (the chunk con‐
307              taining the compilation information that  is  returned  by  Mod‐
308              ule:module_info(compile))  have the same contents in both files,
309              ok is returned. Otherwise an error message is returned.
310
311       cmp_dirs(Dir1, Dir2) ->
312                   {Only1, Only2, Different} | {error, beam_lib, Reason}
313
314              Types:
315
316                 Dir1 = Dir2 = atom() | file:filename()
317                 Only1 = Only2 = [file:filename()]
318                 Different =
319                     [{Filename1 :: file:filename(), Filename2  ::  file:file‐
320                 name()}]
321                 Reason = {not_a_directory, term()} | info_rsn()
322
323              Compares  the BEAM files in two directories. Only files with ex‐
324              tension ".beam" are compared. BEAM files that exist only in  di‐
325              rectory  Dir1  (Dir2)  are returned in Only1 (Only2). BEAM files
326              that exist in both directories but are considered  different  by
327              cmp/2  are returned as pairs {Filename1, Filename2}, where File‐
328              name1 (Filename2) exists in directory Dir1 (Dir2).
329
330       crypto_key_fun(CryptoKeyFun) -> ok | {error, Reason}
331
332              Types:
333
334                 CryptoKeyFun = crypto_fun()
335                 Reason = badfun | exists | term()
336                 crypto_fun() = fun((crypto_fun_arg()) -> term())
337                 crypto_fun_arg() =
338                     init | clear | {debug_info, mode(), module(), file:filename()}
339                 mode() = des3_cbc
340
341              Registers an unary fun that is called if beam_lib must  read  an
342              debug_info  chunk  that has been encrypted. The fun is held in a
343              process that is started by the function.
344
345              If a fun is already registered when  attempting  to  register  a
346              fun, {error, exists} is returned.
347
348              The fun must handle the following arguments:
349
350              CryptoKeyFun(init) -> ok | {ok, NewCryptoKeyFun} | {error, Term}
351
352              Called when the fun is registered, in the process that holds the
353              fun. Here the crypto key fun can do  any  necessary  initializa‐
354              tions.  If {ok, NewCryptoKeyFun} is returned, NewCryptoKeyFun is
355              registered instead of CryptoKeyFun.  If  {error,  Term}  is  re‐
356              turned,  the  registration  is aborted and crypto_key_fun/1 also
357              returns {error, Term}.
358
359              CryptoKeyFun({debug_info, Mode, Module, Filename}) -> Key
360
361              Called when the key is needed for  module  Module  in  the  file
362              named Filename. Mode is the type of crypto algorithm; currently,
363              the only possible value is des3_cbc. The call is to fail  (raise
364              an exception) if no key is available.
365
366              CryptoKeyFun(clear) -> term()
367
368              Called  before the fun is unregistered. Here any cleaning up can
369              be done. The return value is not important, but is  passed  back
370              to  the  caller  of clear_crypto_key_fun/0 as part of its return
371              value.
372
373       diff_dirs(Dir1, Dir2) -> ok | {error, beam_lib, Reason}
374
375              Types:
376
377                 Dir1 = Dir2 = atom() | file:filename()
378                 Reason = {not_a_directory, term()} | info_rsn()
379
380              Compares the BEAM files in two directories  as  cmp_dirs/2,  but
381              the  names of files that exist in only one directory or are dif‐
382              ferent are presented on standard output.
383
384       format_error(Reason) -> io_lib:chars()
385
386              Types:
387
388                 Reason = term()
389
390              For a specified error returned by any function in  this  module,
391              this  function returns a descriptive string of the error in Eng‐
392              lish. For file errors, function file:format_error(Posix)  is  to
393              be called.
394
395       info(Beam) -> [InfoPair] | {error, beam_lib, info_rsn()}
396
397              Types:
398
399                 Beam = beam()
400                 InfoPair =
401                     {file, Filename :: file:filename()} |
402                     {binary, Binary :: binary()} |
403                     {module, Module :: module()} |
404                     {chunks,
405                      [{ChunkId :: chunkid(),
406                        Pos :: integer() >= 0,
407                        Size :: integer() >= 0}]}
408
409              Returns  a list containing some information about a BEAM file as
410              tuples {Item, Info}:
411
412                {file, Filename} | {binary, Binary}:
413                  The name (string) of the BEAM file, or the binary from which
414                  the information was extracted.
415
416                {module, Module}:
417                  The name (atom) of the module.
418
419                {chunks, [{ChunkId, Pos, Size}]}:
420                  For each chunk, the identifier (string) and the position and
421                  size of the chunk data, in bytes.
422
423       md5(Beam) -> {ok, {module(), MD5}} | {error, beam_lib, chnk_rsn()}
424
425              Types:
426
427                 Beam = beam()
428                 MD5 = binary()
429
430              Calculates an MD5 redundancy check for the code  of  the  module
431              (compilation date and other attributes are not included).
432
433       strip(Beam1) ->
434                {ok, {module(), Beam2}} | {error, beam_lib, info_rsn()}
435
436              Types:
437
438                 Beam1 = Beam2 = beam()
439
440              Removes  all  chunks from a BEAM file except those needed by the
441              loader. In particular, the debug information  (chunk  debug_info
442              and abstract_code) is removed.
443
444       strip(Beam1, AdditionalChunks) ->
445                {ok, {module(), Beam2}} | {error, beam_lib, info_rsn()}
446
447              Types:
448
449                 Beam1 = beam()
450                 AdditionalChunks = [chunkid()]
451                 Beam2 = beam()
452
453              Removes  all  chunks from a BEAM file except those needed by the
454              loader or passed in. In particular, the debug information (chunk
455              debug_info and abstract_code) is removed.
456
457       strip_files(Files) ->
458                      {ok, [{module(), Beam}]} |
459                      {error, beam_lib, info_rsn()}
460
461              Types:
462
463                 Files = [beam()]
464                 Beam = beam()
465
466              Removes  all  chunks except those needed by the loader from BEAM
467              files. In particular, the debug  information  (chunk  debug_info
468              and  abstract_code)  is  removed. The returned list contains one
469              element for each specified filename, in the  same  order  as  in
470              Files.
471
472       strip_files(Files, AdditionalChunks) ->
473                      {ok, [{module(), Beam}]} |
474                      {error, beam_lib, info_rsn()}
475
476              Types:
477
478                 Files = [beam()]
479                 AdditionalChunks = [chunkid()]
480                 Beam = beam()
481
482              Removes  all  chunks except those needed by the loader or passed
483              in from BEAM files. In particular, the debug information  (chunk
484              debug_info and abstract_code) is removed. The returned list con‐
485              tains one element for each specified filename, in the same order
486              as in Files.
487
488       strip_release(Dir) ->
489                        {ok, [{module(), file:filename()}]} |
490                        {error, beam_lib, Reason}
491
492              Types:
493
494                 Dir = atom() | file:filename()
495                 Reason = {not_a_directory, term()} | info_rsn()
496
497              Removes  all  chunks  except those needed by the loader from the
498              BEAM files of a release. Dir is to be the installation root  di‐
499              rectory.  For  example,  the current OTP release can be stripped
500              with the call beam_lib:strip_release(code:root_dir()).
501
502       strip_release(Dir, AdditionalChunks) ->
503                        {ok, [{module(), file:filename()}]} |
504                        {error, beam_lib, Reason}
505
506              Types:
507
508                 Dir = atom() | file:filename()
509                 AdditionalChunks = [chunkid()]
510                 Reason = {not_a_directory, term()} | info_rsn()
511
512              Removes all chunks except those needed by the loader  or  passed
513              in  from the BEAM files of a release. Dir is to be the installa‐
514              tion root directory. For example, the current OTP release can be
515              stripped with the call beam_lib:strip_release(code:root_dir()).
516
517       version(Beam) ->
518                  {ok, {module(), [Version :: term()]}} |
519                  {error, beam_lib, chnk_rsn()}
520
521              Types:
522
523                 Beam = beam()
524
525              Returns  the module version or versions. A version is defined by
526              module attribute -vsn(Vsn). If this attribute is not  specified,
527              the  version defaults to the checksum of the module. Notice that
528              if version Vsn is not a list, it  is  made  into  one,  that  is
529              {ok,{Module,[Vsn]}}  is  returned. If there are many -vsn module
530              attributes, the result is the concatenated list of versions.
531
532              Examples:
533
534              1> beam_lib:version(a). % -vsn(1).
535              {ok,{a,[1]}}
536              2> beam_lib:version(b). % -vsn([1]).
537              {ok,{b,[1]}}
538              3> beam_lib:version(c). % -vsn([1]). -vsn(2).
539              {ok,{c,[1,2]}}
540              4> beam_lib:version(d). % no -vsn attribute
541              {ok,{d,[275613208176997377698094100858909383631]}}
542
543
544
545Ericsson AB                      stdlib 3.16.1                     beam_lib(3)
Impressum