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

NAME

6       xref  - A Cross Reference Tool for analyzing dependencies between func‐
7       tions, modules, applications and releases.
8

DESCRIPTION

10       Xref is a cross reference tool that can be used for  finding  dependen‐
11       cies between functions, modules, applications and releases.
12
13       Calls  between  functions  are either local calls like f(), or external
14       calls like m:f(). Module data, which are  extracted  from  BEAM  files,
15       include  local  functions, exported functions, local calls and external
16       calls. By default, calls to built-in functions () are ignored,  but  if
17       the  option  builtins,  accepted by some of this module's functions, is
18       set to true, calls to BIFs are included as well. It  is  the  analyzing
19       OTP  version  that  decides what functions are BIFs. Functional objects
20       are assumed to be called where they are  created  (and  nowhere  else).
21       Unresolved  calls  are  calls  to  apply or spawn with variable module,
22       variable function, or variable arguments. Examples are M:F(a), apply(M,
23       f,  [a]),  and spawn(m, f(), Args). Unresolved calls are represented by
24       calls  where  variable  modules  have  been  replaced  with  the   atom
25       '$M_EXPR',   variable  functions  have  been  replaced  with  the  atom
26       '$F_EXPR', and variable number of arguments have been replaced with the
27       number  -1.  The  above  mentioned examples are represented by calls to
28       '$M_EXPR':'$F_EXPR'/1, '$M_EXPR':f/1,  and  m:'$F_EXPR'/-1.  The  unre‐
29       solved calls are a subset of the external calls.
30
31   Warning:
32       Unresolved  calls  make  module data incomplete, which implies that the
33       results of analyses may be invalid.
34
35
36       Applications are collections of modules. The modules'  BEAM  files  are
37       located in the ebin subdirectory of the application directory. The name
38       of the application directory determines the name  and  version  of  the
39       application.  Releases  are  collections of applications located in the
40       lib subdirectory of the release directory. There is more to read  about
41       applications and releases in the Design Principles book.
42
43       Xref  servers  are  identified  by  names,  supplied  when creating new
44       servers. Each Xref server holds a set of releases, a  set  of  applica‐
45       tions, and a set of modules with module data. Xref servers are indepen‐
46       dent of each other, and all analyses are evaluated in  the  context  of
47       one  single Xref server (exceptions are the functions m/1 and d/1 which
48       do not use servers at all). The mode of an Xref server determines  what
49       module  data  are extracted from BEAM files as modules are added to the
50       server.  Starting  with  R7,  BEAM  files  compiled  with  the   option
51       debug_info  contain  so  called debug information, which is an abstract
52       representation of the code. In functions mode,  which  is  the  default
53       mode, function calls and line numbers are extracted from debug informa‐
54       tion. In modules mode, debug information is  ignored  if  present,  but
55       dependencies between modules are extracted from other parts of the BEAM
56       files. The modules mode is significantly less time and space  consuming
57       than the functions mode, but the analyses that can be done are limited.
58
59       An  analyzed  module  is a module that has been added to an Xref server
60       together with its module data. A library module is a module located  in
61       some  directory mentioned in the library path. A library module is said
62       to be used if some of its exported functions are used by some  analyzed
63       module.  An unknown module is a module that is neither an analyzed mod‐
64       ule nor a library module, but whose exported functions are used by some
65       analyzed module. An unknown function is a used function that is neither
66       local or exported by any analyzed module nor exported  by  any  library
67       module.  An  undefined  function is an externally used function that is
68       not exported by any  analyzed  module  or  library  module.  With  this
69       notion,  a local function can be an undefined function, namely if it is
70       externally used from some module. All unknown functions are also  unde‐
71       fined functions; there is a figure in the User's Guide that illustrates
72       this relationship.
73
74       Starting with R9C, the module attribute tag deprecated can be  used  to
75       inform  Xref  about  deprecated functions and optionally when functions
76       are planned to be removed. A few examples show the idea:
77
78         -deprecated({f,1}).:
79           The exported function f/1 is deprecated. Nothing  is  said  whether
80           f/1 will be removed or not.
81
82         -deprecated({f,'_'}).:
83           All exported functions f/0, f/1 and so on are deprecated.
84
85         -deprecated(module).:
86           All  exported functions in the module are deprecated. Equivalent to
87           -deprecated({'_','_'})..
88
89         -deprecated([{g,1,next_version}]).:
90           The function g/1 is deprecated and will be removed in next version.
91
92         -deprecated([{g,2,next_major_release}]).:
93           The function g/2 is deprecated and will be removed  in  next  major
94           release.
95
96         -deprecated([{g,3,eventually}]).:
97           The function g/3 is deprecated and will eventually be removed.
98
99         -deprecated({'_','_',eventually}).:
100           All  exported functions in the module are deprecated and will even‐
101           tually be removed.
102
103       Before any analysis can take place, module data must  be  set  up.  For
104       instance,  the  cross  reference and the unknown functions are computed
105       when all module data are known. The functions that need  complete  data
106       (analyze,  q,  variables)  take  care of setting up data automatically.
107       Module data need to be set up (again) after calls to any  of  the  add,
108       replace, remove, set_library_path or update functions.
109
110       The  result  of  setting up module data is the Call Graph. A (directed)
111       graph consists of a set of vertices and a set of (directed) edges.  The
112       edges  represent  calls (From, To) between functions, modules, applica‐
113       tions or releases. From is said to call To, and To is said to  be  used
114       by From. The vertices of the Call Graph are the functions of all module
115       data: local and exported functions of analyzed modules; used BIFs; used
116       exported functions of library modules; and unknown functions. The func‐
117       tions module_info/0,1 added by the  compiler  are  included  among  the
118       exported  functions,  but  only when called from some module. The edges
119       are the function calls of all module data. A consequence of  the  edges
120       being  a set is that there is only one edge if a function is locally or
121       externally used several times on one and the same line of code.
122
123       The Call Graph is represented by Erlang terms  (the  sets  are  lists),
124       which  is  suitable  for  many  analyses. But for analyses that look at
125       chains of calls, a list representation is much too  slow.  Instead  the
126       representation  offered  by the digraph module is used. The translation
127       of the list representation of the Call Graph - or a subgraph thereof  -
128       to  the  digraph representation does not come for free, so the language
129       used for expressing queries to be described below has a special  opera‐
130       tor  for this task and a possibility to save the digraph representation
131       for subsequent analyses.
132
133       In addition to the Call Graph there is a graph called  the  Inter  Call
134       Graph.  This  is a graph of calls (From, To) such that there is a chain
135       of calls from From to To in the Call Graph, and every From and To is an
136       exported  function  or  an  unused local function. The vertices are the
137       same as for the Call Graph.
138
139       Calls between modules, applications  and  releases  are  also  directed
140       graphs.  The types of the vertices and edges of these graphs are (rang‐
141       ing from the most special to the most general): Fun for functions;  Mod
142       for  modules; App for applications; and Rel for releases. The following
143       paragraphs will describe the different constructs of the language  used
144       for  selecting  and  analyzing  parts of the graphs, beginning with the
145       constants:
146
147         * Expression ::= Constants
148
149         * Constants ::= Consts | Consts : Type | RegExpr
150
151         * Consts ::= Constant | [Constant, ...] | {Constant, ...}
152
153         * Constant ::= Call | Const
154
155         * Call ::= FunSpec -> FunSpec | {MFA, MFA} | AtomConst -> AtomConst |
156           {AtomConst, AtomConst}
157
158         * Const ::= AtomConst | FunSpec | MFA
159
160         * AtomConst ::= Application | Module | Release
161
162         * FunSpec ::= Module : Function / Arity
163
164         * MFA ::= {Module, Function, Arity}
165
166         * RegExpr ::= RegString : Type | RegFunc | RegFunc : Type
167
168         * RegFunc ::= RegModule : RegFunction / RegArity
169
170         * RegModule ::= RegAtom
171
172         * RegFunction ::= RegAtom
173
174         * RegArity ::= RegString | Number | _ | -1
175
176         * RegAtom ::= RegString | Atom | _
177
178         * RegString  ::=  - a regular expression, as described in the re mod‐
179           ule, enclosed in double quotes -
180
181         * Type ::= Fun | Mod | App | Rel
182
183         * Function ::= Atom
184
185         * Application ::= Atom
186
187         * Module ::= Atom
188
189         * Release ::= Atom
190
191         * Arity ::= Number | -1
192
193         * Atom ::= - same as Erlang atoms -
194
195         * Number ::= - same as non-negative Erlang integers -
196
197       Examples of constants are: kernel, kernel->stdlib, [kernel, sasl],  [pg
198       ->  mnesia, {tv, mnesia}] : Mod. It is an error if an instance of Const
199       does not match any vertex of any graph. If there are more than one ver‐
200       tex matching an untyped instance of AtomConst, then the one of the most
201       general type is chosen. A list of constants is interpreted as a set  of
202       constants,  all  of  the  same  type. A tuple of constants constitute a
203       chain of calls (which may, but does  not  have  to,  correspond  to  an
204       actual  chain  of  calls  of some graph). Assigning a type to a list or
205       tuple of Constant is equivalent to assigning the type to each Constant.
206
207       Regular expressions are used as a means to select some of the  vertices
208       of a graph. A RegExpr consisting of a RegString and a type - an example
209       is "xref_.*" : Mod - is interpreted as those modules  (or  applications
210       or  releases,  depending  on the type) that match the expression. Simi‐
211       larly, a RegFunc is interpreted as those vertices  of  the  Call  Graph
212       that  match  the  expression. An example is "xref_.*":"add_.*"/"(2|3)",
213       which matches all add functions of arity two or three  of  any  of  the
214       xref  modules. Another example, one that matches all functions of arity
215       10 or more: _:_/"[1-9].+". Here _ is an abbreviation for ".*", that is,
216       the regular expression that matches anything.
217
218       The syntax of variables is simple:
219
220         * Expression ::= Variable
221
222         * Variable ::= - same as Erlang variables -
223
224       There  are  two kinds of variables: predefined variables and user vari‐
225       ables. Predefined variables hold set up  module  data,  and  cannot  be
226       assigned  to but only used in queries. User variables on the other hand
227       can be assigned to, and are typically used for temporary results  while
228       evaluating  a query, and for keeping results of queries for use in sub‐
229       sequent queries. The predefined variables are  (variables  marked  with
230       (*) are available in functions mode only):
231
232         E:
233           Call Graph Edges (*).
234
235         V:
236           Call Graph Vertices (*).
237
238         M:
239           Modules.  All  modules: analyzed modules, used library modules, and
240           unknown modules.
241
242         A:
243           Applications.
244
245         R:
246           Releases.
247
248         ME:
249           Module Edges. All module calls.
250
251         AE:
252           Application Edges. All application calls.
253
254         RE:
255           Release Edges. All release calls.
256
257         L:
258           Local Functions (*). All local functions of analyzed modules.
259
260         X:
261           Exported Functions. All exported functions of analyzed modules  and
262           all used exported functions of library modules.
263
264         F:
265           Functions (*).
266
267         B:
268           Used  BIFs.  B  is empty if builtins is false for all analyzed mod‐
269           ules.
270
271         U:
272           Unknown Functions.
273
274         UU:
275           Unused Functions (*). All local and exported functions of  analyzed
276           modules that have not been used.
277
278         XU:
279           Externally  Used  Functions.  Functions  of all modules - including
280           local functions - that have been used in some external call.
281
282         LU:
283           Locally Used Functions (*). Functions of all modules that have been
284           used in some local call.
285
286         OL:
287           Functions with an attribute tag on_load (*).
288
289         LC:
290           Local Calls (*).
291
292         XC:
293           External Calls (*).
294
295         AM:
296           Analyzed Modules.
297
298         UM:
299           Unknown Modules.
300
301         LM:
302           Used Library Modules.
303
304         UC:
305           Unresolved Calls. Empty in modules mode.
306
307         EE:
308           Inter Call Graph Edges (*).
309
310         DF:
311           Deprecated  Functions.  All  deprecated  exported functions and all
312           used deprecated BIFs.
313
314         DF_1:
315           Deprecated Functions. All deprecated functions  to  be  removed  in
316           next version.
317
318         DF_2:
319           Deprecated  Functions.  All  deprecated  functions to be removed in
320           next version or next major release.
321
322         DF_3:
323           Deprecated Functions. All deprecated functions  to  be  removed  in
324           next version, next major release, or later.
325
326       These are a few facts about the predefined variables (the set operators
327       + (union) and - (difference) as well as the cast  operator  (Type)  are
328       described below):
329
330         * F is equal to L + X.
331
332         * V  is equal to X + L + B + U, where X, L, B and U are pairwise dis‐
333           joint (that is, have no elements in common).
334
335         * UU is equal to V - (XU + LU), where LU and XU may have elements  in
336           common. Put in another way:
337
338         * V is equal to UU + XU + LU.
339
340         * OL is a subset of F.
341
342         * E  is  equal  to  LC + XC. Note that LC and XC may have elements in
343           common, namely if some function is locally and externally used from
344           one and the same function.
345
346         * U is a subset of XU.
347
348         * B is a subset of XU.
349
350         * LU is equal to range LC.
351
352         * XU is equal to range XC.
353
354         * LU is a subset of F.
355
356         * UU is a subset of F.
357
358         * range UC is a subset of U.
359
360         * M  is  equal to AM + LM + UM, where AM, LM and UM are pairwise dis‐
361           joint.
362
363         * ME is equal to (Mod) E.
364
365         * AE is equal to (App) E.
366
367         * RE is equal to (Rel) E.
368
369         * (Mod) V is a subset of M. Equality holds if  all  analyzed  modules
370           have some local, exported, or unknown function.
371
372         * (App)  M  is a subset of A. Equality holds if all applications have
373           some module.
374
375         * (Rel) A is a subset of R. Equality holds if all releases have  some
376           application.
377
378         * DF_1 is a subset of DF_2.
379
380         * DF_2 is a subset of DF_3.
381
382         * DF_3 is a subset of DF.
383
384         * DF is a subset of X + B.
385
386       An important notion is that of conversion of expressions. The syntax of
387       a cast expression is:
388
389         * Expression ::= ( Type ) Expression
390
391       The interpretation of the cast operator depends on the named type Type,
392       the type of Expression, and the structure of the elements of the inter‐
393       pretation of Expression. If the named type is equal to  the  expression
394       type, no conversion is done. Otherwise, the conversion is done one step
395       at a time; (Fun) (App) RE, for instance, is equivalent to  (Fun)  (Mod)
396       (App)  RE. Now assume that the interpretation of Expression is a set of
397       constants (functions, modules, applications or releases). If the  named
398       type  is more general than the expression type, say Mod and Fun respec‐
399       tively, then the interpretation of the cast expression is  the  set  of
400       modules  that  have  at  least  one of their functions mentioned in the
401       interpretation of the expression. If the named  type  is  more  special
402       than  the  expression type, say Fun and Mod, then the interpretation is
403       the set of all the functions of the modules (in modules mode, the  con‐
404       version  is  partial since the local functions are not known). The con‐
405       versions to and from applications and releases  work  analogously.  For
406       instance,  (App) "xref_.*" : Mod returns all applications containing at
407       least one module such that xref_ is a prefix of the module name.
408
409       Now assume that the interpretation of Expression is a set of calls.  If
410       the  named  type  is more general than the expression type, say Mod and
411       Fun respectively, then the interpretation of the cast expression is the
412       set  of  calls  (M1, M2) such that the interpretation of the expression
413       contains a call from some function of M1 to some function of M2. If the
414       named  type  is more special than the expression type, say Fun and Mod,
415       then the interpretation is the set of all function calls (F1, F2)  such
416       that  the interpretation of the expression contains a call (M1, M2) and
417       F1 is a function of M1 and F2 is a function of  M2  (in  modules  mode,
418       there  are  no functions calls, so a cast to Fun always yields an empty
419       set). Again, the conversions to and from applications and releases work
420       analogously.
421
422       The  interpretation of constants and variables are sets, and those sets
423       can be used as the basis for forming new sets by the application of set
424       operators. The syntax:
425
426         * Expression ::= Expression BinarySetOp Expression
427
428         * BinarySetOp ::= + | * | -
429
430       +,  *  and  -  are  interpreted  as  union, intersection and difference
431       respectively: the union of two sets contains the elements of both sets;
432       the intersection of two sets contains the elements common to both sets;
433       and the difference of two sets contains the elements of the  first  set
434       that  are  not  members of the second set. The elements of the two sets
435       must be of the same structure; for instance, a function call cannot  be
436       combined  with a function. But if a cast operator can make the elements
437       compatible, then the more general elements are converted  to  the  less
438       general element type. For instance, M + F is equivalent to (Fun) M + F,
439       and E - AE is equivalent to E - (Fun) AE. One more example: X * xref  :
440       Mod is interpreted as the set of functions exported by the module xref;
441       xref : Mod is converted to the more special type of X  (Fun,  that  is)
442       yielding  all functions of xref, and the intersection with X (all func‐
443       tions exported by analyzed modules and library modules) is  interpreted
444       as  those  functions  that are exported by some module and functions of
445       xref.
446
447       There are also unary set operators:
448
449         * Expression ::= UnarySetOp Expression
450
451         * UnarySetOp ::= domain | range | strict
452
453       Recall that a call is a pair (From, To). domain applied  to  a  set  of
454       calls  is interpreted as the set of all vertices From, and range as the
455       set of all vertices To. The interpretation of the  strict  operator  is
456       the operand with all calls on the form (A, A) removed.
457
458       The  interpretation  of  the  restriction  operators is a subset of the
459       first operand, a set of calls. The second operand, a set  of  vertices,
460       is  converted  to  the  type  of  the  first operand. The syntax of the
461       restriction operators:
462
463         * Expression ::= Expression RestrOp Expression
464
465         * RestrOp ::= |
466
467         * RestrOp ::= ||
468
469         * RestrOp ::= |||
470
471       The interpretation in some detail for the three operators:
472
473         |:
474           The subset of calls from any of the vertices.
475
476         ||:
477           The subset of calls to any of the vertices.
478
479         |||:
480           The subset of calls to and from any of the vertices. For  all  sets
481           of  calls  CS and all sets of vertices VS, CS ||| VS  is equivalent
482           to CS | VS * CS || VS.
483
484       Two functions (modules, applications,  releases)  belong  to  the  same
485       strongly  connected component if they call each other (in)directly. The
486       interpretation of the components operator is the set of  strongly  con‐
487       nected components of a set of calls. The condensation of a set of calls
488       is a new set of calls between the strongly  connected  components  such
489       that  there is an edge between two components if there is some constant
490       of the first component that calls some constant of  the  second  compo‐
491       nent.
492
493       The interpretation of the of operator is a chain of calls of the second
494       operand (a set of calls) that passes throw all of the vertices  of  the
495       first  operand  (a  tuple of constants), in the given order. The second
496       operand is converted to the type of the first  operand.  For  instance,
497       the  of  operator  can be used for finding out whether a function calls
498       another function indirectly, and the chain of calls  demonstrates  how.
499       The syntax of the graph analyzing operators:
500
501         * Expression ::= Expression BinaryGraphOp Expression
502
503         * Expression ::= UnaryGraphOp Expression
504
505         * UnaryGraphOp ::= components | condensation
506
507         * BinaryGraphOp ::= of
508
509       As was mentioned before, the graph analyses operate on the digraph rep‐
510       resentation of graphs. By default, the digraph representation  is  cre‐
511       ated  when needed (and deleted when no longer used), but it can also be
512       created explicitly by use of the closure operator:
513
514         * Expression ::= ClosureOp Expression
515
516         * ClosureOp ::= closure
517
518       The interpretation of the closure operator is the transitive closure of
519       the operand.
520
521       The restriction operators are defined for closures as well; closure E |
522       xref : Mod is interpreted as the direct or indirect function calls from
523       the  xref module, while the interpretation of E | xref : Mod is the set
524       of direct calls from xref. If some graph is to be used in several graph
525       analyses,  it  saves  time  to assign the digraph representation of the
526       graph to a user variable, and then make sure that every graph  analysis
527       operates  on  that  variable  instead of the list representation of the
528       graph.
529
530       The lines where functions are defined (more precisely: where the  first
531       clause  begins) and the lines where functions are used are available in
532       functions mode. The line numbers refer to the files where the functions
533       are  defined.  This holds also for files included with the -include and
534       -include_lib directives, which may result in functions  defined  appar‐
535       ently  in the same line. The line operators are used for assigning line
536       numbers to functions and for assigning sets of line numbers to function
537       calls. The syntax is similar to the one of the cast operator:
538
539         * Expression ::= ( LineOp) Expression
540
541         * Expression ::= ( XLineOp) Expression
542
543         * LineOp ::= Lin | ELin | LLin | XLin
544
545         * XLineOp ::= XXL
546
547       The  interpretation  of  the Lin operator applied to a set of functions
548       assigns to each function the line number where the function is defined.
549       Unknown  functions  and  functions  of library modules are assigned the
550       number 0.
551
552       The interpretation of some LineOp operator applied to a set of function
553       calls  assigns  to  each  call  the set of line numbers where the first
554       function calls the second function. Not all  calls  are  assigned  line
555       numbers by all operators:
556
557         * the Lin operator is defined for Call Graph Edges;
558
559         * the LLin operator is defined for Local Calls.
560
561         * the XLin operator is defined for External Calls.
562
563         * the ELin operator is defined for Inter Call Graph Edges.
564
565       The  Lin  (LLin,  XLin)  operator  assigns the lines where calls (local
566       calls, external calls) are made. The ELin operator assigns to each call
567       (From,  To), for which it is defined, every line L such that there is a
568       chain of calls from From to To beginning with a call on line L.
569
570       The XXL operator is defined for the interpretation of any of the LineOp
571       operators  applied  to  a  set of function calls. The result is that of
572       replacing the function call with a line numbered  function  call,  that
573       is,  each of the two functions of the call is replaced by a pair of the
574       function and the line where the function is defined. The effect of  the
575       XXL operator can be undone by the LineOp operators. For instance, (Lin)
576       (XXL) (Lin) E is equivalent to (Lin) E.
577
578       The +, -, * and # operators are defined for  line  number  expressions,
579       provided  the  operands  are  compatible. The LineOp operators are also
580       defined for modules, applications, and releases; the operand is implic‐
581       itly  converted  to  functions. Similarly, the cast operator is defined
582       for the interpretation of the LineOp operators.
583
584       The interpretation of the counting operator is the number  of  elements
585       of a set. The operator is undefined for closures. The +, - and * opera‐
586       tors are interpreted as the obvious arithmetical operators when applied
587       to numbers. The syntax of the counting operator:
588
589         * Expression ::= CountOp Expression
590
591         * CountOp ::= #
592
593       All  binary operators are left associative; for instance, A | B || C is
594       equivalent to (A | B) || C. The following is a list of  all  operators,
595       in increasing order of precedence:
596
597         * +, -
598
599         * *
600
601         * #
602
603         * |, ||, |||
604
605         * of
606
607         * (Type)
608
609         * closure, components, condensation, domain, range, strict
610
611       Parentheses  are  used  for grouping, either to make an expression more
612       readable or to override the default precedence of operators:
613
614         * Expression ::= ( Expression )
615
616       A query is a non-empty sequence of statements. A statement is either an
617       assignment of a user variable or an expression. The value of an assign‐
618       ment is the value of the right hand side expression. It makes no  sense
619       to put a plain expression anywhere else but last in queries. The syntax
620       of queries is summarized by these productions:
621
622         * Query ::= Statement, ...
623
624         * Statement ::= Assignment | Expression
625
626         * Assignment ::= Variable := Expression | Variable = Expression
627
628       A variable cannot be assigned a new value unless first  removed.  Vari‐
629       ables  assigned  to  by  the  =  operator are removed at the end of the
630       query, while variables assigned to by  the  :=  operator  can  only  be
631       removed  by  calls  to  forget. There are no user variables when module
632       data need to be set up again; if any of the functions that make it nec‐
633       essary  to  set  up module data again is called, all user variables are
634       forgotten.
635
636       Types
637
638       application() = atom()
639       arity() = int() | -1
640       bool() = true | false
641       call() = {atom(), atom()} | funcall()
642       constant() = mfa() | module() | application() | release()
643       directory() = string()
644       file() = string()
645       funcall() = {mfa(), mfa()}
646       function() = atom()
647       int() = integer() >= 0
648       library() = atom()
649       library_path() = path() | code_path
650       mfa() = {module(), function(), arity()}
651       mode() = functions | modules
652       module() = atom()
653       release() = atom()
654       string_position() = int() | at_end
655       variable() = atom()
656       xref() = atom() | pid()
657

EXPORTS

659       add_application(Xref, Directory [, Options]) -> {ok,  application()}  |
660       Error
661
662              Types:
663
664                 Directory = directory()
665                 Error = {error, module(), Reason}
666                 Options = [Option] | Option
667                 Option  =  {builtins, bool()} | {name, application()} | {ver‐
668                 bose, bool()} | {warnings, bool()}
669                 Reason  =  {application_clash,  {application(),  directory(),
670                 directory()}}    |    {file_error,    file(),    error()}   |
671                 {invalid_filename, term()} | {invalid_options,  term()}  |  -
672                 see also add_directory -
673                 Xref = xref()
674
675              Adds  an  application, the modules of the application and module
676              data of the modules to an Xref server. The modules will be  mem‐
677              bers  of the application. The default is to use the base name of
678              the directory with the version removed as application name,  but
679              this  can  be overridden by the name option. Returns the name of
680              the application.
681
682              If the given directory has a subdirectory  named  ebin,  modules
683              (BEAM  files) are searched for in that directory, otherwise mod‐
684              ules are searched for in the given directory.
685
686              If the mode of the Xref server is  functions,  BEAM  files  that
687              contain no debug information are ignored.
688
689       add_directory(Xref, Directory [, Options]) -> {ok, Modules} | Error
690
691              Types:
692
693                 Directory = directory()
694                 Error = {error, module(), Reason}
695                 Modules = [module()]
696                 Options = [Option] | Option
697                 Option  =  {builtins, bool()} | {recurse, bool()} | {verbose,
698                 bool()} | {warnings, bool()}
699                 Reason = {file_error, file(), error()}  |  {invalid_filename,
700                 term()}  |  {invalid_options,  term()}  | {unrecognized_file,
701                 file()} | - error from beam_lib:chunks/2 -
702                 Xref = xref()
703
704              Adds the modules found in the given directory and  the  modules'
705              data  to an Xref server. The default is not to examine subdirec‐
706              tories, but if the option recurse has the  value  true,  modules
707              are  searched  for in subdirectories on all levels as well as in
708              the given directory. Returns a sorted list of the names  of  the
709              added modules.
710
711              The modules added will not be members of any applications.
712
713              If  the  mode  of  the Xref server is functions, BEAM files that
714              contain no debug information are ignored.
715
716       add_module(Xref, File [, Options]) -> {ok, module()} | Error
717
718              Types:
719
720                 Error = {error, module(), Reason}
721                 File = file()
722                 Options = [Option] | Option
723                 Option = {builtins, bool()} | {verbose, bool()} |  {warnings,
724                 bool()}
725                 Reason  =  {file_error, file(), error()} | {invalid_filename,
726                 term()} | {invalid_options, term()}  |  {module_clash,  {mod‐
727                 ule(),  file(),  file()}} | {no_debug_info, file()} | - error
728                 from beam_lib:chunks/2 -
729                 Xref = xref()
730
731              Adds a module and its module data to an Xref server. The  module
732              will  not  be member of any application. Returns the name of the
733              module.
734
735              If the mode of the Xref server is functions, and the  BEAM  file
736              contains  no  debug information, the error message no_debug_info
737              is returned.
738
739       add_release(Xref, Directory [, Options]) -> {ok, release()} | Error
740
741              Types:
742
743                 Directory = directory()
744                 Error = {error, module(), Reason}
745                 Options = [Option] | Option
746                 Option = {builtins, bool()} | {name, release()}  |  {verbose,
747                 bool()} | {warnings, bool()}
748                 Reason  =  {application_clash,  {application(),  directory(),
749                 directory()}}   |    {file_error,    file(),    error()}    |
750                 {invalid_filename,  term()}  |  {invalid_options,  term()}  |
751                 {release_clash, {release(), directory(),  directory()}}  |  -
752                 see also add_directory -
753                 Xref = xref()
754
755              Adds  a release, the applications of the release, the modules of
756              the applications, and module data of  the  modules  to  an  Xref
757              server. The applications will be members of the release, and the
758              modules will be members of the applications. The default  is  to
759              use the base name of the directory as release name, but this can
760              be overridden by the  name  option.  Returns  the  name  of  the
761              release.
762
763              If  the given directory has a subdirectory named lib, the direc‐
764              tories in that directory are assumed to be application  directo‐
765              ries,  otherwise  all  subdirectories of the given directory are
766              assumed to be application directories. If there are several ver‐
767              sions  of  some application, the one with the highest version is
768              chosen.
769
770              If the mode of the Xref server is  functions,  BEAM  files  that
771              contain no debug information are ignored.
772
773       analyze(Xref, Analysis [, Options]) -> {ok, Answer} | Error
774
775              Types:
776
777                 Analysis  =  undefined_function_calls | undefined_functions |
778                 locals_not_used   |   exports_not_used   |   deprecated_func‐
779                 tion_calls  |  {deprecated_function_calls, DeprFlag} | depre‐
780                 cated_functions | {deprecated_functions, DeprFlag}  |  {call,
781                 FuncSpec}  | {use, FuncSpec} | {module_call, ModSpec} | {mod‐
782                 ule_use, ModSpec} | {application_call, AppSpec}  |  {applica‐
783                 tion_use,  AppSpec} | {release_call, RelSpec} | {release_use,
784                 RelSpec}
785                 Answer = [term()]
786                 AppSpec = application() | [application()]
787                 DeprFlag = next_version | next_major_release | eventually
788                 Error = {error, module(), Reason}
789                 FuncSpec = mfa() | [mfa()]
790                 ModSpec = module() | [module()]
791                 Options = [Option] | Option
792                 Option = {verbose, bool()}
793                 RelSpec = release() | [release()]
794                 Reason   =   {invalid_options,   term()}   |    {parse_error,
795                 string_position(), term()} | {unavailable_analysis, term()} |
796                 {unknown_analysis, term()} | {unknown_constant,  string()}  |
797                 {unknown_variable, variable()}
798                 Xref = xref()
799
800              Evaluates  a  predefined analysis. Returns a sorted list without
801              duplicates of call() or  constant(),  depending  on  the  chosen
802              analysis. The predefined analyses, which operate on all analyzed
803              modules, are (analyses marked with (*) are  available  in  func‐
804              tionsmode only):
805
806                undefined_function_calls(*):
807                  Returns a list of calls to undefined functions.
808
809                undefined_functions:
810                  Returns a list of undefined functions.
811
812                locals_not_used(*):
813                  Returns a list of local functions that have not been locally
814                  used.
815
816                exports_not_used:
817                  Returns a list of exported  functions  that  have  not  been
818                  externally used.
819
820                deprecated_function_calls(*):
821                  Returns a list of external calls to deprecated functions.
822
823                {deprecated_function_calls, DeprFlag}(*):
824                  Returns a list of external calls to deprecated functions. If
825                  DeprFlag is equal to next_version, calls to functions to  be
826                  removed  in  next version are returned. If DeprFlag is equal
827                  to next_major_release, calls to functions to be  removed  in
828                  next  major  release  are returned as well as calls to func‐
829                  tions to be removed in next version. Finally, if DeprFlag is
830                  equal  to  eventually,  all calls to functions to be removed
831                  are returned, including calls to functions to be removed  in
832                  next version or next major release.
833
834                deprecated_functions:
835                  Returns a list of externally used deprecated functions.
836
837                {deprecated_functions, DeprFlag}:
838                  Returns  a  list of externally used deprecated functions. If
839                  DeprFlag is equal to next_version, functions to  be  removed
840                  in  next  version  are  returned.  If  DeprFlag  is equal to
841                  next_major_release, functions to be removed  in  next  major
842                  release  are  returned as well as functions to be removed in
843                  next version. Finally, if DeprFlag is equal  to  eventually,
844                  all  functions  to  be removed are returned, including func‐
845                  tions to be removed in next version or next major release.
846
847                {call, FuncSpec}(*):
848                  Returns a list of functions called  by  some  of  the  given
849                  functions.
850
851                {use, FuncSpec}(*):
852                  Returns a list of functions that use some of the given func‐
853                  tions.
854
855                {module_call, ModSpec}:
856                  Returns a list of modules called by some of the  given  mod‐
857                  ules.
858
859                {module_use, ModSpec}:
860                  Returns  a  list  of modules that use some of the given mod‐
861                  ules.
862
863                {application_call, AppSpec}:
864                  Returns a list of applications called by some of  the  given
865                  applications.
866
867                {application_use, AppSpec}:
868                  Returns  a  list  of applications that use some of the given
869                  applications.
870
871                {release_call, RelSpec}:
872                  Returns a list of releases  called  by  some  of  the  given
873                  releases.
874
875                {release_use, RelSpec}:
876                  Returns  a  list  of  releases  that  use  some of the given
877                  releases.
878
879       d(Directory) -> [DebugInfoResult] | [NoDebugInfoResult] | Error
880
881              Types:
882
883                 Directory = directory()
884                 DebugInfoResult =  {deprecated,  [funcall()]}  |  {undefined,
885                 [funcall()]} | {unused, [mfa()]}
886                 Error = {error, module(), Reason}
887                 NoDebugInfoResult   =  {deprecated,  [mfa()]}  |  {undefined,
888                 [mfa()]}
889                 Reason = {file_error, file(), error()}  |  {invalid_filename,
890                 term()}   |   {unrecognized_file,  file()}  |  -  error  from
891                 beam_lib:chunks/2 -
892
893              The modules found in the given directory are checked  for  calls
894              to  deprecated  functions, calls to undefined functions, and for
895              unused local functions. The code path is used as library path.
896
897              If some of the found BEAM files contain debug information,  then
898              those  modules are checked and a list of tuples is returned. The
899              first element of each tuple is one of:
900
901                * deprecated, the second element is a sorted list of calls  to
902                  deprecated functions;
903
904                * undefined,  the  second element is a sorted list of calls to
905                  undefined functions;
906
907                * unused, the second element is a sorted list of unused  local
908                  functions.
909
910              If  no  BEAM  file  contains  debug  information, then a list of
911              tuples is returned. The first element of each tuple is one of:
912
913                * deprecated, the second element is a sorted  list  of  exter‐
914                  nally used deprecated functions;
915
916                * undefined,  the second element is a sorted list of undefined
917                  functions.
918
919       forget(Xref) -> ok
920       forget(Xref, Variables) -> ok | Error
921
922              Types:
923
924                 Error = {error, module(), Reason}
925                 Reason = {not_user_variable, term()}
926                 Variables = [variable()] | variable()
927                 Xref = xref()
928
929              forget/1 and forget/2 remove all or some of the  user  variables
930              of an xref server.
931
932       format_error(Error) -> Chars
933
934              Types:
935
936                 Error = {error, module(), term()}
937                 Chars = [char() | Chars]
938
939              Given  the  error  returned  by any function of this module, the
940              function format_error returns a descriptive string of the  error
941              in  English. For file errors, the function format_error/1 in the
942              file module is called.
943
944       get_default(Xref) -> [{Option, Value}]
945       get_default(Xref, Option) -> {ok, Value} | Error
946
947              Types:
948
949                 Error = {error, module(), Reason}
950                 Option = builtins | recurse | verbose | warnings
951                 Reason = {invalid_options, term()}
952                 Value = bool()
953                 Xref = xref()
954
955              Returns the default values of one or more options.
956
957       get_library_path(Xref) -> {ok, LibraryPath}
958
959              Types:
960
961                 LibraryPath = library_path()
962                 Xref = xref()
963
964              Returns the library path.
965
966       info(Xref) -> [Info]
967       info(Xref, Category) -> [{Item, [Info]}]
968       info(Xref, Category, Items) -> [{Item, [Info]}]
969
970              Types:
971
972                 Application = [] | [application()]
973                 Category = modules | applications | releases | libraries
974                 Info = {application,  Application}  |  {builtins,  bool()}  |
975                 {directory,  directory()}  | {library_path, library_path()} |
976                 {mode, mode()} | {no_analyzed_modules, int()} |  {no_applica‐
977                 tions,  int()}  |  {no_calls,  {NoResolved,  NoUnresolved}} |
978                 {no_function_calls,  {NoLocal,  NoResolvedExternal,   NoUnre‐
979                 solved}}    |   {no_functions,   {NoLocal,   NoExternal}}   |
980                 {no_inter_function_calls, int()}  |  {no_releases,  int()}  |
981                 {release, Release} | {version, Version}
982                 Item = module() | application() | release() | library()
983                 Items = Item | [Item]
984                 NoLocal = NoExternal = NoResolvedExternal, NoResolved = NoUn‐
985                 resolved = int()
986                 Release = [] | [release()]
987                 Version = [int()]
988                 Xref = xref()
989
990              The info functions return information as a list of  pairs  {Tag,
991              term()}  in some order about the state and the module data of an
992              Xref server.
993
994              info/1 returns information with the following tags (tags  marked
995              with (*) are available in functions mode only):
996
997                * library_path, the library path;
998
999                * mode, the mode;
1000
1001                * no_releases, number of releases;
1002
1003                * no_applications,   total  number  of  applications  (of  all
1004                  releases);
1005
1006                * no_analyzed_modules, total number of analyzed modules;
1007
1008                * no_calls (*),  total  number  of  calls  (in  all  modules),
1009                  regarding  instances of one function call in different lines
1010                  as separate calls;
1011
1012                * no_function_calls (*), total number of local calls, resolved
1013                  external calls and unresolved calls;
1014
1015                * no_functions  (*),  total number of local and exported func‐
1016                  tions;
1017
1018                * no_inter_function_calls (*), total number of  calls  of  the
1019                  Inter Call Graph.
1020
1021              info/2  and  info/3  return information about all or some of the
1022              analyzed modules, applications, releases or library  modules  of
1023              an  Xref server. The following information is returned for every
1024              analyzed module:
1025
1026                * application, an empty list if the module does not belong  to
1027                  any application, otherwise a list of the application name;
1028
1029                * builtins, whether calls to BIFs are included in the module's
1030                  data;
1031
1032                * directory, the directory where the  module's  BEAM  file  is
1033                  located;
1034
1035                * no_calls  (*),  number  of calls, regarding instances of one
1036                  function call in different lines as separate calls;
1037
1038                * no_function_calls  (*),  number  of  local  calls,  resolved
1039                  external calls and unresolved calls;
1040
1041                * no_functions (*), number of local and exported functions;
1042
1043                * no_inter_function_calls  (*),  number  of calls of the Inter
1044                  Call Graph;
1045
1046              The following information is returned for every application:
1047
1048                * directory, the directory where the modules' BEAM  files  are
1049                  located;
1050
1051                * no_analyzed_modules, number of analyzed modules;
1052
1053                * no_calls  (*), number of calls of the application's modules,
1054                  regarding instances of one function call in different  lines
1055                  as separate calls;
1056
1057                * no_function_calls  (*),  number  of  local  calls,  resolved
1058                  external calls and unresolved  calls  of  the  application's
1059                  modules;
1060
1061                * no_functions  (*), number of local and exported functions of
1062                  the application's modules;
1063
1064                * no_inter_function_calls (*), number of calls  of  the  Inter
1065                  Call Graph of the application's modules;
1066
1067                * release, an empty list if the application does not belong to
1068                  any release, otherwise a list of the release name;
1069
1070                * version, the application's version as a list of numbers. For
1071                  instance, the directory "kernel-2.6" results in the applica‐
1072                  tion name kernel and the application version [2,6]; "kernel"
1073                  yields the name kernel and the version [].
1074
1075              The following information is returned for every release:
1076
1077                * directory, the release directory;
1078
1079                * no_analyzed_modules, number of analyzed modules;
1080
1081                * no_applications, number of applications;
1082
1083                * no_calls  (*),  number  of  calls  of the release's modules,
1084                  regarding instances of one function call in different  lines
1085                  as separate calls;
1086
1087                * no_function_calls  (*),  number  of  local  calls,  resolved
1088                  external calls and unresolved calls of  the  release's  mod‐
1089                  ules;
1090
1091                * no_functions  (*), number of local and exported functions of
1092                  the release's modules;
1093
1094                * no_inter_function_calls (*), number of calls  of  the  Inter
1095                  Call Graph of the release's modules.
1096
1097              The following information is returned for every library module:
1098
1099                * directory,  the  directory  where  the library module's BEAM
1100                  file is located.
1101
1102              For every number of calls, functions etc. returned  by  the  no_
1103              tags,  there  is a query returning the same number. Listed below
1104              are examples of such queries. Some of the queries return the sum
1105              of  a two or more of the no_ tags numbers. mod (app, rel) refers
1106              to any module (application, release).
1107
1108                * no_analyzed_modules
1109
1110                  * "# AM" (info/1)
1111
1112                  * "# (Mod) app:App" (application)
1113
1114                  * "# (Mod) rel:Rel" (release)
1115
1116                * no_applications
1117
1118                  * "# A" (info/1)
1119
1120                * no_calls. The sum of the number of resolved  and  unresolved
1121                  calls:
1122
1123                  * "# (XLin) E + # (LLin) E" (info/1)
1124
1125                  * "T = E | mod:Mod, # (LLin) T + # (XLin) T" (module)
1126
1127                  * "T = E | app:App, # (LLin) T + # (XLin) T" (application)
1128
1129                  * "T = E | rel:Rel, # (LLin) T + # (XLin) T" (release)
1130
1131                * no_functions. Functions in library modules and the functions
1132                  module_info/0,1 are  not  counted  by  info.  Assuming  that
1133                  "Extra  := _:module_info/\"(0|1)\" + LM" has been evaluated,
1134                  the sum of the number of local and exported functions are:
1135
1136                  * "# (F - Extra)" (info/1)
1137
1138                  * "# (F * mod:Mod - Extra)" (module)
1139
1140                  * "# (F * app:App - Extra)" (application)
1141
1142                  * "# (F * rel:Rel - Extra)" (release)
1143
1144                * no_function_calls. The sum of the  number  of  local  calls,
1145                  resolved external calls and unresolved calls:
1146
1147                  * "# LC + # XC" (info/1)
1148
1149                  * "# LC | mod:Mod + # XC | mod:Mod" (module)
1150
1151                  * "# LC | app:App + # XC | app:App" (application)
1152
1153                  * "# LC | rel:Rel + # XC | mod:Rel" (release)
1154
1155                * no_inter_function_calls
1156
1157                  * "# EE" (info/1)
1158
1159                  * "# EE | mod:Mod" (module)
1160
1161                  * "# EE | app:App" (application)
1162
1163                  * "# EE | rel:Rel" (release)
1164
1165                * no_releases
1166
1167                  * "# R" (info/1)
1168
1169       m(Module) -> [DebugInfoResult] | [NoDebugInfoResult] | Error
1170       m(File) -> [DebugInfoResult] | [NoDebugInfoResult] | Error
1171
1172              Types:
1173
1174                 DebugInfoResult  =  {deprecated,  [funcall()]}  | {undefined,
1175                 [funcall()]} | {unused, [mfa()]}
1176                 Error = {error, module(), Reason}
1177                 File = file()
1178                 Module = module()
1179                 NoDebugInfoResult  =  {deprecated,  [mfa()]}  |   {undefined,
1180                 [mfa()]}
1181                 Reason  =  {file_error, file(), error()} | {interpreted, mod‐
1182                 ule()} | {invalid_filename, term()} |  {cover_compiled,  mod‐
1183                 ule()}   |   {no_such_module,   module()}   |  -  error  from
1184                 beam_lib:chunks/2 -
1185
1186              The given BEAM file (with or without the .beam extension) or the
1187              file found by calling code:which(Module) is checked for calls to
1188              deprecated functions, calls  to  undefined  functions,  and  for
1189              unused local functions. The code path is used as library path.
1190
1191              If  the  BEAM  file  contains  debug information, then a list of
1192              tuples is returned. The first element of each tuple is one of:
1193
1194                * deprecated, the second element is a sorted list of calls  to
1195                  deprecated functions;
1196
1197                * undefined,  the  second element is a sorted list of calls to
1198                  undefined functions;
1199
1200                * unused, the second element is a sorted list of unused  local
1201                  functions.
1202
1203              If the BEAM file does not contain debug information, then a list
1204              of tuples is returned. The first element of each  tuple  is  one
1205              of:
1206
1207                * deprecated,  the  second  element is a sorted list of exter‐
1208                  nally used deprecated functions;
1209
1210                * undefined, the second element is a sorted list of  undefined
1211                  functions.
1212
1213       q(Xref, Query [, Options]) -> {ok, Answer} | Error
1214
1215              Types:
1216
1217                 Answer  = false | [constant()] | [Call] | [Component] | int()
1218                 | [DefineAt] | [CallAt] | [AllLines]
1219                 Call = call() | ComponentCall
1220                 ComponentCall = {Component, Component}
1221                 Component = [constant()]
1222                 DefineAt = {mfa(), LineNumber}
1223                 CallAt = {funcall(), LineNumbers}
1224                 AllLines = {{DefineAt, DefineAt}, LineNumbers}
1225                 Error = {error, module(), Reason}
1226                 LineNumbers = [LineNumber]
1227                 LineNumber = int()
1228                 Options = [Option] | Option
1229                 Option = {verbose, bool()}
1230                 Query = string() | atom()
1231                 Reason   =   {invalid_options,   term()}   |    {parse_error,
1232                 string_position(),   term()}   |   {type_error,  string()}  |
1233                 {type_mismatch,  string(),  string()}  |   {unknown_analysis,
1234                 term()}  |  {unknown_constant, string()} | {unknown_variable,
1235                 variable()} | {variable_reassigned, string()}
1236                 Xref = xref()
1237
1238              Evaluates a query in the context of an Xref server, and  returns
1239              the value of the last statement. The syntax of the value depends
1240              on the expression:
1241
1242                * A set of calls is  represented  by  a  sorted  list  without
1243                  duplicates of call().
1244
1245                * A  set  of constants is represented by a sorted list without
1246                  duplicates of constant().
1247
1248                * A set of strongly connected  components  is  a  sorted  list
1249                  without duplicates of Component.
1250
1251                * A  set  of  calls between strongly connected components is a
1252                  sorted list without duplicates of ComponentCall.
1253
1254                * A chain of calls is represented by a list of constant(). The
1255                  list  contains the From vertex of every call and the To ver‐
1256                  tex of the last call.
1257
1258                * The of operator returns false if no chain of  calls  between
1259                  the given constants can be found.
1260
1261                * The  value  of the closure operator (the digraph representa‐
1262                  tion) is represented by the atom 'closure()'.
1263
1264                * A set of line numbered functions is represented by a  sorted
1265                  list without duplicates of DefineAt.
1266
1267                * A  set  of  line numbered function calls is represented by a
1268                  sorted list without duplicates of CallAt.
1269
1270                * A set of line numbered functions and function calls is  rep‐
1271                  resented by a sorted list without duplicates of AllLines.
1272
1273              For  both  CallAt and AllLines it holds that for no list element
1274              is LineNumbers an empty list; such elements have  been  removed.
1275              The  constants  of component and the integers of LineNumbers are
1276              sorted and without duplicates.
1277
1278       remove_application(Xref, Applications) -> ok | Error
1279
1280              Types:
1281
1282                 Applications = application() | [application()]
1283                 Error = {error, module(), Reason}
1284                 Reason = {no_such_application, application()}
1285                 Xref = xref()
1286
1287              Removes applications and their modules and module data  from  an
1288              Xref server.
1289
1290       remove_module(Xref, Modules) -> ok | Error
1291
1292              Types:
1293
1294                 Error = {error, module(), Reason}
1295                 Modules = module() | [module()]
1296                 Reason = {no_such_module, module()}
1297                 Xref = xref()
1298
1299              Removes analyzed modules and module data from an Xref server.
1300
1301       remove_release(Xref, Releases) -> ok | Error
1302
1303              Types:
1304
1305                 Error = {error, module(), Reason}
1306                 Reason = {no_such_release, release()}
1307                 Releases = release() | [release()]
1308                 Xref = xref()
1309
1310              Removes releases and their applications, modules and module data
1311              from an Xref server.
1312
1313       replace_application(Xref, Application, Directory [, Options])  ->  {ok,
1314       application()} | Error
1315
1316              Types:
1317
1318                 Application = application()
1319                 Directory = directory()
1320                 Error = {error, module(), Reason}
1321                 Options = [Option] | Option
1322                 Option  = {builtins, bool()} | {verbose, bool()} | {warnings,
1323                 bool()}
1324                 Reason = {no_such_application, application()} |  -  see  also
1325                 add_application -
1326                 Xref = xref()
1327
1328              Replaces  the  modules of an application with other modules read
1329              from an application directory. Release membership of the  appli‐
1330              cation  is  retained.  Note  that the name of the application is
1331              kept; the name of the given directory is not used.
1332
1333       replace_module(Xref, Module, File [,  Options])  ->  {ok,  module()}  |
1334       Error
1335
1336              Types:
1337
1338                 Error = {error, module(), Reason}
1339                 File = file()
1340                 Module = module()
1341                 Options = [Option] | Option
1342                 Option = {verbose, bool()} | {warnings, bool()}
1343                 ReadModule = module()
1344                 Reason    =   {module_mismatch,   module(),   ReadModule}   |
1345                 {no_such_module, module()} | - see also add_module -
1346                 Xref = xref()
1347
1348              Replaces module data of an analyzed module with data read from a
1349              BEAM file. Application membership of the module is retained, and
1350              so is the value of the builtins option of the module.  An  error
1351              is  returned  if  the  name  of the read module differs from the
1352              given module.
1353
1354              The update function is an alternative for updating  module  data
1355              of recompiled modules.
1356
1357       set_default(Xref, Option, Value) -> {ok, OldValue} | Error
1358       set_default(Xref, OptionValues) -> ok | Error
1359
1360              Types:
1361
1362                 Error = {error, module(), Reason}
1363                 OptionValues = [OptionValue] | OptionValue
1364                 OptionValue = {Option, Value}
1365                 Option = builtins | recurse | verbose | warnings
1366                 Reason = {invalid_options, term()}
1367                 Value = bool()
1368                 Xref = xref()
1369
1370              Sets  the default value of one or more options. The options that
1371              can be set this way are:
1372
1373                * builtins, with initial default value false;
1374
1375                * recurse, with initial default value false;
1376
1377                * verbose, with initial default value false;
1378
1379                * warnings, with initial default value true.
1380
1381              The initial default values are set when creating an Xref server.
1382
1383       set_library_path(Xref, LibraryPath [, Options]) -> ok | Error
1384
1385              Types:
1386
1387                 Error = {error, module(), Reason}
1388                 LibraryPath = library_path()
1389                 Options = [Option] | Option
1390                 Option = {verbose, bool()}
1391                 Reason = {invalid_options, term()} | {invalid_path, term()}
1392                 Xref = xref()
1393
1394              Sets the library path. If the given path is a list  of  directo‐
1395              ries,  the  set of library modules is determined by choosing the
1396              first module encountered while traversing the directories in the
1397              given  order,  for  those  modules  that  occur in more than one
1398              directory. By default, the library path is an empty list.
1399
1400              The library path code_path is used by the functions m/1 and d/1,
1401              but  can also be set explicitly. Note however that the code path
1402              will be traversed once for each used library module  while  set‐
1403              ting  up module data. On the other hand, if there are only a few
1404              modules that are used but not analyzed, using code_path  may  be
1405              faster than setting the library path to code:get_path().
1406
1407              If the library path is set to code_path, the set of library mod‐
1408              ules is not determined, and the info functions will return empty
1409              lists of library modules.
1410
1411       start(NameOrOptions) -> Return
1412
1413              Types:
1414
1415                 NameOrOptions = Name | Options
1416                 Name = atom()
1417                 Options = [Option] | Option
1418                 Option = {xref_mode, mode()} | term()
1419                 Return = {ok, pid()} | {error, {already_started, pid()}}
1420
1421              Creates  an  Xref  server. The process may optionally be given a
1422              name. The default mode is functions. Options that are not recog‐
1423              nized by Xref are passed on to gen_server:start/4.
1424
1425       start(Name, Options) -> Return
1426
1427              Types:
1428
1429                 Name = atom()
1430                 Options = [Option] | Option
1431                 Option = {xref_mode, mode()} | term()
1432                 Return = {ok, pid()} | {error, {already_started, pid()}}
1433
1434              Creates  an  Xref  server with a given name. The default mode is
1435              functions. Options that are not recognized by Xref are passed on
1436              to gen_server:start/4.
1437
1438       stop(Xref)
1439
1440              Types:
1441
1442                 Xref = xref()
1443
1444              Stops an Xref server.
1445
1446       update(Xref [, Options]) -> {ok, Modules} | Error
1447
1448              Types:
1449
1450                 Error = {error, module(), Reason}
1451                 Modules = [module()]
1452                 Options = [Option] | Option
1453                 Option = {verbose, bool()} | {warnings, bool()}
1454                 Reason  =  {invalid_options, term()} | {module_mismatch, mod‐
1455                 ule(), ReadModule} | - see also add_module -
1456                 Xref = xref()
1457
1458              Replaces the module data of all analyzed modules the BEAM  files
1459              of  which  have been modified since last read by an add function
1460              or update. Application membership of the  modules  is  retained,
1461              and  so  is  the  value of the builtins option. Returns a sorted
1462              list of the names of the replaced modules.
1463
1464       variables(Xref [, Options]) -> {ok, [VariableInfo]}
1465
1466              Types:
1467
1468                 Options = [Option] | Option
1469                 Option = predefined | user | {verbose, bool()}
1470                 Reason = {invalid_options, term()}
1471                 VariableInfo = {predefined,  [variable()]}  |  {user,  [vari‐
1472                 able()]}
1473                 Xref = xref()
1474
1475              Returns  a sorted lists of the names of the variables of an Xref
1476              server. The default is to return the user variables only.
1477

SEE ALSO

1479       beam_lib(3), digraph(3), digraph_utils(3), re(3), TOOLS User's Guide
1480
1481
1482
1483Ericsson AB                       tools 3.3.1                          xref(3)
Impressum