Unix/Linux Go Back    


Linux 2.6 - man page for xref (linux section 3erl)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


xref(3erl)			     Erlang Module Definition			       xref(3erl)

NAME
       xref  -	A  Cross  Reference  Tool  for analyzing dependencies between functions, modules,
       applications and releases.

DESCRIPTION
       Xref is a cross reference tool that can be used for  finding  dependencies  between  func-
       tions, modules, applications and releases.

       Calls  between  functions are either local calls like f() , or external calls like m:f() .
       Module data , which are extracted from BEAM files, include local functions, exported func-
       tions,  local  calls  and  external calls. By default, calls to built-in functions ( ) are
       ignored, but if the option builtins , accepted by some of this module's functions, is  set
       to true , calls to BIFs are included as well. It is the analyzing OTP version that decides
       what functions are BIFs. Functional objects are assumed to be called where they	are  cre-
       ated  (and  nowhere else). Unresolved calls are calls to apply or spawn with variable mod-
       ule, variable function, or variable arguments. Examples are M:F(a) , apply(M,  f,  [a])	,
       and spawn(m, f(), Args) . Unresolved calls are represented by calls where variable modules
       have been replaced with the atom '$M_EXPR' , variable functions have  been  replaced  with
       the  atom  '$F_EXPR' , and variable number of arguments have been replaced with the number
       -1 . The above mentioned examples are represented  by  calls  to  '$M_EXPR':'$F_EXPR'/1	,
       '$M_EXPR':f/1  ,  and  m:'$F_EXPR'/-1  . The unresolved calls are a subset of the external
       calls.

   Warning:
       Unresolved calls make module data incomplete, which implies that the results  of  analyses
       may be invalid.

       Applications  are  collections of modules. The modules' BEAM files are located in the ebin
       subdirectory of the application directory. The name of the  application	directory  deter-
       mines  the  name  and version of the application. Releases are collections of applications
       located in the lib subdirectory of the release directory. There	is  more  to  read  about
       applications and releases in the Design Principles book.

       Xref servers are identified by names, supplied when creating new servers. Each Xref server
       holds a set of releases, a set of applications, and a set of  modules  with  module  data.
       Xref  servers are independent of each other, and all analyses are evaluated in the context
       of one single Xref server (exceptions are the functions m/1  and  d/1  which  do  not  use
       servers at all). The mode of an Xref server determines what module data are extracted from
       BEAM files as modules are added to the server. Starting with R7, BEAM files compiled  with
       the  option debug_info contain so called debug information, which is an abstract represen-
       tation of the code. In functions mode, which is the default mode, function calls and  line
       numbers	are  extracted	from  debug  information.  In  modules mode, debug information is
       ignored if present, but dependencies between modules are extracted from other parts of the
       BEAM files. The modules mode is significantly less time and space consuming than the func-
       tions mode, but the analyses that can be done are limited.

       An analyzed module is a module that has been added to an Xref  server  together	with  its
       module  data.  A  library  module  is  a module located in some directory mentioned in the
       library path . A library module is said to be used if some of its exported  functions  are
       used  by  some  analyzed module. An unknown module is a module that is neither an analyzed
       module nor a library module, but whose exported functions are used by some  analyzed  mod-
       ule.  An unknown function is a used function that is neither local or exported by any ana-
       lyzed module nor exported by any library module. An undefined function  is  an  externally
       used  function  that  is  not exported by any analyzed module or library module. With this
       notion, a local function can be an undefined function, namely if  it  is  externally  used
       from some module. All unknown functions are also undefined functions; there is a figure in
       the User's Guide that illustrates this relationship.

       Starting with R9C, the module attribute tag deprecated can be used to  inform  Xref  about
       deprecated  functions and optionally when functions are planned to be removed. A few exam-
       ples show the idea:

	 -deprecated({f,1}). :
	   The exported function f/1 is deprecated. Nothing is said whether f/1 will  be  removed
	   or not.

	 -deprecated({f,'_'}). :
	   All exported functions f/0 , f/1 and so on are deprecated.

	 -deprecated(module). :
	   All	 exported   functions  in  the	module	are  deprecated.  Equivalent  to  -depre-
	   cated({'_','_'}). .

	 -deprecated([{g,1,next_version}]). :
	   The function g/1 is deprecated and will be removed in next version.

	 -deprecated([{g,2,next_major_release}]). :
	   The function g/2 is deprecated and will be removed in next major release.

	 -deprecated([{g,3,eventually}]). :
	   The function g/3 is deprecated and will eventually be removed.

	 -deprecated({'_','_',eventually}). :
	   All exported functions in the module are deprecated and will eventually be removed.

       Before any analysis can take place, module data must be set up . For instance,  the  cross
       reference and the unknown functions are computed when all module data are known. The func-
       tions that need complete data ( analyze , q , variables ) take care  of	setting  up  data
       automatically.  Module  data  need  to  be  set up (again) after calls to any of the add ,
       replace , remove , set_library_path or update functions.

       The result of setting up module data is the Call Graph . A (directed) graph consists of	a
       set  of	vertices  and  a  set  of  (directed) edges. The edges represent calls (From, To)
       between functions, modules, applications or releases. From is said to call To, and  To  is
       said  to  be  used by From. The vertices of the Call Graph are the functions of all module
       data: local and exported functions of analyzed modules; used BIFs; used exported functions
       of library modules; and unknown functions. The functions module_info/0,1 added by the com-
       piler are included among the exported functions, but only when called  from  some  module.
       The  edges  are	the function calls of all module data. A consequence of the edges being a
       set is that there is only one edge if a function is locally  or	externally  used  several
       times on one and the same line of code.

       The  Call Graph is represented by Erlang terms (the sets are lists), which is suitable for
       many analyses. But for analyses that look at chains of calls,  a  list  representation  is
       much  too  slow.  Instead  the  representation  offered by the digraph module is used. The
       translation of the list representation of the Call Graph - or a subgraph thereof - to  the
       digraph representation does not come for free, so the language used for expressing queries
       to be described below has a special operator for this task and a possibility to	save  the
       digraph representation for subsequent analyses.

       In  addition  to  the  Call Graph there is a graph called the Inter Call Graph . This is a
       graph of calls (From, To) such that there is a chain of calls from From to To in the  Call
       Graph, and every From and To is an exported function or an unused local function. The ver-
       tices are the same as for the Call Graph.

       Calls between modules, applications and releases are also directed graphs.  The	types  of
       the vertices and edges of these graphs are (ranging from the most special to the most gen-
       eral): Fun for functions; Mod for modules; App for applications; and Rel for releases. The
       following  paragraphs  will  describe  the  different  constructs of the language used for
       selecting and analyzing parts of the graphs, beginning with the constants :

	 * Expression ::= Constants

	 * Constants ::= Consts | Consts : Type | RegExpr

	 * Consts ::= Constant | [ Constant , ... ] | { Constant , ... }

	 * Constant ::= Call | Const

	 * Call ::= FunSpec -> FunSpec | { MFA , MFA } | AtomConst -> AtomConst | {  AtomConst	,
	   AtomConst }

	 * Const ::= AtomConst | FunSpec | MFA

	 * AtomConst ::= Application | Module | Release

	 * FunSpec ::= Module : Function / Arity

	 * MFA ::= { Module , Function , Arity }

	 * RegExpr ::= RegString : Type | RegFunc | RegFunc : Type

	 * RegFunc ::= RegModule : RegFunction / RegArity

	 * RegModule ::= RegAtom

	 * RegFunction ::= RegAtom

	 * RegArity ::= RegString | Number | _ | -1

	 * RegAtom ::= RegString | Atom | _

	 * RegString  ::= - a regular expression, as described in the re module, enclosed in dou-
	   ble quotes -

	 * Type ::= Fun | Mod | App | Rel

	 * Function ::= Atom

	 * Application ::= Atom

	 * Module ::= Atom

	 * Release ::= Atom

	 * Arity ::= Number | -1

	 * Atom ::= - same as Erlang atoms -

	 * Number ::= - same as non-negative Erlang integers -

       Examples of constants are: kernel , kernel->stdlib , [kernel, sasl] , [pg -> mnesia,  {tv,
       mnesia}]  :  Mod . It is an error if an instance of Const does not match any vertex of any
       graph. If there are more than one vertex matching an untyped instance of AtomConst ,  then
       the one of the most general type is chosen. A list of constants is interpreted as a set of
       constants, all of the same type. A tuple of constants constitute a chain of  calls  (which
       may,  but does not have to, correspond to an actual chain of calls of some graph). Assign-
       ing a type to a list or tuple of Constant is equivalent to assigning the type to each Con-
       stant .

       Regular	expressions are used as a means to select some of the vertices of a graph. A Reg-
       Expr consisting of a RegString and a type - an example is "xref_.*" : Mod - is interpreted
       as  those  modules  (or	applications  or  releases, depending on the type) that match the
       expression. Similarly, a RegFunc is interpreted as those vertices of the Call  Graph  that
       match  the  expression.	An  example is "xref_.*":"add_.*"/"(2|3)" , which matches all add
       functions of arity two or three of any of the xref  modules.  Another  example,	one  that
       matches	all  functions of arity 10 or more: _:_/"[1-9].+" . Here _ is an abbreviation for
       ".*" , that is, the regular expression that matches anything.

       The syntax of variables is simple:

	 * Expression ::= Variable

	 * Variable ::= - same as Erlang variables -

       There are two kinds of variables: predefined  variables	and  user  variables.  Predefined
       variables  hold	set  up  module data, and cannot be assigned to but only used in queries.
       User variables on the other hand can be assigned to, and are typically used for	temporary
       results while evaluating a query, and for keeping results of queries for use in subsequent
       queries. The predefined variables are (variables marked with (*) are  available	in  func-
       tions mode only):

	 E :
	   Call Graph Edges (*).

	 V :
	   Call Graph Vertices (*).

	 M :
	   Modules. All modules: analyzed modules, used library modules, and unknown modules.

	 A :
	   Applications.

	 R :
	   Releases.

	 ME :
	   Module Edges. All module calls.

	 AE :
	   Application Edges. All application calls.

	 RE :
	   Release Edges. All release calls.

	 L :
	   Local Functions (*). All local functions of analyzed modules.

	 X :
	   Exported  Functions.  All exported functions of analyzed modules and all used exported
	   functions of library modules.

	 F :
	   Functions (*).

	 B :
	   Used BIFs. B is empty if builtins is false for all analyzed modules.

	 U :
	   Unknown Functions.

	 UU :
	   Unused Functions (*). All local and exported functions of analyzed modules  that  have
	   not been used.

	 XU :
	   Externally Used Functions. Functions of all modules - including local functions - that
	   have been used in some external call.

	 LU :
	   Locally Used Functions (*). Functions of all modules that have been used in some local
	   call.

	 LC :
	   Local Calls (*).

	 XC :
	   External Calls (*).

	 AM :
	   Analyzed Modules.

	 UM :
	   Unknown Modules.

	 LM :
	   Used Library Modules.

	 UC :
	   Unresolved Calls. Empty in modules mode.

	 EE :
	   Inter Call Graph Edges (*).

	 DF :
	   Deprecated Functions. All deprecated exported functions and all used deprecated BIFs.

	 DF_1 :
	   Deprecated Functions. All deprecated functions to be removed in next version.

	 DF_2 :
	   Deprecated  Functions.  All deprecated functions to be removed in next version or next
	   major release.

	 DF_3 :
	   Deprecated Functions. All deprecated functions to be removed  in  next  version,  next
	   major release, or later.

       These  are  a  few facts about the predefined variables (the set operators + (union) and -
       (difference) as well as the cast operator ( Type ) are described below):

	 * F is equal to L + X .

	 * V is equal to X + L + B + U , where X , L , B and U are pairwise  disjoint  (that  is,
	   have no elements in common).

	 * UU  is  equal  to  V - (XU + LU) , where LU and XU may have elements in common. Put in
	   another way:

	 * V is equal to UU + XU + LU .

	 * E is equal to LC + XC . Note that LC and XC may have elements  in  common,  namely  if
	   some function is locally and externally used from one and the same function.

	 * U is a subset of XU .

	 * B is a subset of XU .

	 * LU is equal to range LC .

	 * XU is equal to range XC .

	 * LU is a subset of F .

	 * UU is a subset of F .

	 * range UC is a subset of U .

	 * M is equal to AM + LM + UM , where AM , LM and UM are pairwise disjoint.

	 * ME is equal to (Mod) E .

	 * AE is equal to (App) E .

	 * RE is equal to (Rel) E .

	 * (Mod)  V  is  a  subset of M . Equality holds if all analyzed modules have some local,
	   exported, or unknown function.

	 * (App) M is a subset of A . Equality holds if all applications have some module.

	 * (Rel) A is a subset of R . Equality holds if all releases have some application.

	 * DF_1 is a subset of DF_2 .

	 * DF_2 is a subset of DF_3 .

	 * DF_3 is a subset of DF .

	 * DF is a subset of X + B .

       An important notion is that of conversion of expressions. The syntax of a cast  expression
       is:

	 * Expression ::= ( Type ) Expression

       The  interpretation  of	the  cast  operator  depends on the named type Type , the type of
       Expression , and the structure of the elements of the interpretation of	Expression  .  If
       the named type is equal to the expression type, no conversion is done. Otherwise, the con-
       version is done one step at a time; (Fun) (App) RE , for instance, is equivalent to  (Fun)
       (Mod)  (App)  RE  . Now assume that the interpretation of Expression is a set of constants
       (functions, modules, applications or releases). If the named type is more general than the
       expression type, say Mod and Fun respectively, then the interpretation of the cast expres-
       sion is the set of modules that have at least one of  their  functions  mentioned  in  the
       interpretation  of  the	expression. If the named type is more special than the expression
       type, say Fun and Mod , then the interpretation is the set of all  the  functions  of  the
       modules	(in  modules  mode,  the  conversion is partial since the local functions are not
       known). The conversions to and  from  applications  and	releases  work	analogously.  For
       instance,  (App)  "xref_.*"  : Mod returns all applications containing at least one module
       such that xref_ is a prefix of the module name.

       Now assume that the interpretation of Expression is a set of calls. If the named  type  is
       more  general than the expression type, say Mod and Fun respectively, then the interpreta-
       tion of the cast expression is the set of calls (M1, M2) such that the  interpretation  of
       the  expression	contains  a  call from some function of M1 to some function of M2. If the
       named type is more special than the expression type, say Fun and Mod , then the	interpre-
       tation  is  the	set  of  all  function calls (F1, F2) such that the interpretation of the
       expression contains a call (M1, M2) and F1 is a function of M1 and F2 is a function of  M2
       (in  modules  mode,  there are no functions calls, so a cast to Fun always yields an empty
       set). Again, the conversions to and from applications and releases work analogously.

       The interpretation of constants and variables are sets, and those sets can be used as  the
       basis for forming new sets by the application of set operators . The syntax:

	 * Expression ::= Expression BinarySetOp Expression

	 * BinarySetOp ::= + | * | -

       +  , * and - are interpreted as union, intersection and difference respectively: the union
       of two sets contains the elements of both sets; the intersection of two sets contains  the
       elements  common to both sets; and the difference of two sets contains the elements of the
       first set that are not members of the second set. The elements of the two sets must be  of
       the  same structure; for instance, a function call cannot be combined with a function. But
       if a cast operator can make the elements compatible, then the more  general  elements  are
       converted to the less general element type. For instance, M + F is equivalent to (Fun) M +
       F , and E - AE is equivalent to E - (Fun) AE . One more example: X * xref : Mod is  inter-
       preted  as  the	set of functions exported by the module xref ; xref : Mod is converted to
       the more special type of X ( Fun , that is) yielding all  functions  of	xref  ,  and  the
       intersection  with  X  (all functions exported by analyzed modules and library modules) is
       interpreted as those functions that are exported by some module and functions of xref .

       There are also unary set operators:

	 * Expression ::= UnarySetOp Expression

	 * UnarySetOp ::= domain | range | strict

       Recall that a call is a pair (From, To). domain applied to a set of calls  is  interpreted
       as  the set of all vertices From, and range as the set of all vertices To. The interpreta-
       tion of the strict operator is the operand with all calls on the form (A, A) removed.

       The interpretation of the restriction operators is a subset of the first operand, a set of
       calls.  The second operand, a set of vertices, is converted to the type of the first oper-
       and. The syntax of the restriction operators:

	 * Expression ::= Expression RestrOp Expression

	 * RestrOp ::= |

	 * RestrOp ::= ||

	 * RestrOp ::= |||

       The interpretation in some detail for the three operators:

	 | :
	   The subset of calls from any of the vertices.

	 || :
	   The subset of calls to any of the vertices.

	 ||| :
	   The subset of calls to and from any of the vertices. For all sets of calls CS and  all
	   sets of vertices VS , CS ||| VS is equivalent to CS | VS * CS || VS .

       Two functions (modules, applications, releases) belong to the same strongly connected com-
       ponent if they call each other (in)directly. The interpretation of the components operator
       is  the	set of strongly connected components of a set of calls. The condensation of a set
       of calls is a new set of calls between the strongly connected components such  that  there
       is  an  edge  between two components if there is some constant of the first component that
       calls some constant of the second component.

       The interpretation of the of operator is a chain of calls of the second operand (a set  of
       calls)  that passes throw all of the vertices of the first operand (a tuple of constants),
       in the given order. The second operand is converted to the type of the first operand.  For
       instance,  the  of  operator  can be used for finding out whether a function calls another
       function indirectly, and the chain of calls demonstrates how. The syntax of the graph ana-
       lyzing operators:

	 * Expression ::= Expression GraphOp Expression

	 * GraphOp ::= components | condensation | of

       As  was	mentioned  before,  the  graph	analyses operate on the digraph representation of
       graphs. By default, the digraph representation is created when needed (and deleted when no
       longer used), but it can also be created explicitly by use of the closure operator:

	 * Expression ::= ClosureOp Expression

	 * ClosureOp ::= closure

       The interpretation of the closure operator is the transitive closure of the operand.

       The  restriction  operators  are  defined  for closures as well; closure E | xref : Mod is
       interpreted as the direct or indirect function calls  from  the	xref  module,  while  the
       interpretation  of  E | xref : Mod is the set of direct calls from xref . If some graph is
       to be used in several graph analyses, it saves time to assign the  digraph  representation
       of  the graph to a user variable, and then make sure that every graph analysis operates on
       that variable instead of the list representation of the graph.

       The lines where functions are defined (more precisely: where the first clause begins)  and
       the lines where functions are used are available in functions mode. The line numbers refer
       to the files where the functions are defined. This holds also for files included with  the
       -include  and -include_lib directives, which may result in functions defined apparently in
       the same line. The line operators are used for assigning line numbers to functions and for
       assigning  sets of line numbers to function calls. The syntax is similar to the one of the
       cast operator:

	 * Expression ::= ( LineOp ) Expression

	 * Expression ::= ( XLineOp ) Expression

	 * LineOp ::= Lin | ELin | LLin | XLin

	 * XLineOp ::= XXL

       The interpretation of the Lin operator applied to a set of functions assigns to each func-
       tion  the  line	number	where the function is defined. Unknown functions and functions of
       library modules are assigned the number 0.

       The interpretation of some LineOp operator applied to a set of function calls  assigns  to
       each  call the set of line numbers where the first function calls the second function. Not
       all calls are assigned line numbers by all operators:

	 * the Lin operator is defined for Call Graph Edges;

	 * the LLin operator is defined for Local Calls.

	 * the XLin operator is defined for External Calls.

	 * the ELin operator is defined for Inter Call Graph Edges.

       The Lin ( LLin , XLin ) operator assigns the lines  where  calls  (local  calls,  external
       calls)  are  made.  The	ELin  operator	assigns  to each call (From, To), for which it is
       defined, every line L such that there is a chain of calls from From to To beginning with a
       call on line L.

       The  XXL operator is defined for the interpretation of any of the LineOp operators applied
       to a set of function calls. The result is that of replacing the function call with a  line
       numbered  function  call,  that is, each of the two functions of the call is replaced by a
       pair of the function and the line where the function is defined. The  effect  of  the  XXL
       operator  can  be  undone  by  the  LineOp operators. For instance, (Lin) (XXL) (Lin) E is
       equivalent to (Lin) E .

       The + , - , * and # operators are defined for line number expressions, provided the  oper-
       ands  are compatible. The LineOp operators are also defined for modules, applications, and
       releases; the operand is implicitly converted to functions. Similarly, the  cast  operator
       is defined for the interpretation of the LineOp operators.

       The interpretation of the counting operator is the number of elements of a set. The opera-
       tor is undefined for closures. The + , - and * operators are interpreted  as  the  obvious
       arithmetical operators when applied to numbers. The syntax of the counting operator:

	 * Expression ::= CountOp Expression

	 * CountOp ::= #

       All  binary operators are left associative; for instance, A | B || C is equivalent to (A |
       B) || C . The following is a list of all operators, in increasing order of precedence :

	 * + , -

	 * *

	 * #

	 * | , || , |||

	 * of

	 * ( Type )

	 * closure , components , condensation , domain , range , strict

       Parentheses are used for grouping, either to make an expression more readable or to  over-
       ride the default precedence of operators:

	 * Expression ::= ( Expression )

       A  query  is  a non-empty sequence of statements. A statement is either an assignment of a
       user variable or an expression. The value of an assignment is the value of the right  hand
       side  expression.  It  makes  no sense to put a plain expression anywhere else but last in
       queries. The syntax of queries is summarized by these productions:

	 * Query ::= Statement , ...

	 * Statement ::= Assignment | Expression

	 * Assignment ::= Variable := Expression | Variable = Expression

       A variable cannot be assigned a new value unless first removed. Variables assigned  to  by
       the  = operator are removed at the end of the query, while variables assigned to by the :=
       operator can only be removed by calls to forget . There are no user variables when  module
       data  need  to  be  set up again; if any of the functions that make it necessary to set up
       module data again is called, all user variables are forgotten.

       Types

       application() = atom()
       arity() = int() | -1
       bool() = true | false
       call() = {atom(), atom()} | funcall()
       constant() = mfa() | module() | application() | release()
       directory() = string()
       file() = string()
       funcall() = {mfa(), mfa()}
       function() = atom()
       int() = integer() >= 0
       library() = atom()
       library_path() = path() | code_path
       mfa() = {module(), function(), arity()}
       mode() = functions | modules
       module() = atom()
       release() = atom()
       string_position() = int() | at_end
       variable() = atom()
       xref() = atom() | pid()

EXPORTS
       add_application(Xref, Directory [, Options]) -> {ok, application()} | Error

	      Types  Directory = directory()
		     Error = {error, module(), Reason}
		     Options = [Option] | Option
		     Option = {builtins, bool()} | {name, application()} |  {verbose,  bool()}	|
		     {warnings, bool()}
		     Reason  =	{application_clash,  {application(), directory(), directory()}} |
		     {file_error,   file(),   error()}	  |    {invalid_filename,    term()}	|
		     {invalid_options, term()} | - see also add_directory -
		     Xref = xref()

	      Adds  an application, the modules of the application and module data of the modules
	      to an Xref server . The modules will be members of the application. The default  is
	      to use the base name of the directory with the version removed as application name,
	      but this can be overridden by the name option. Returns the name of the application.

	      If the given directory has a subdirectory named ebin ,  modules  (BEAM  files)  are
	      searched	for  in  that  directory, otherwise modules are searched for in the given
	      directory.

	      If the mode of the Xref server is functions , BEAM  files  that  contain	no  debug
	      information are ignored.

       add_directory(Xref, Directory [, Options]) -> {ok, Modules} | Error

	      Types  Directory = directory()
		     Error = {error, module(), Reason}
		     Modules = [module()]
		     Options = [Option] | Option
		     Option = {builtins, bool()} | {recurse, bool()} | {verbose, bool()} | {warn-
		     ings, bool()}
		     Reason =  {file_error,  file(),  error()}	|  {invalid_filename,  term()}	|
		     {invalid_options,	term()}  |  {unrecognized_file,  file()}  |  - error from
		     beam_lib:chunks/2 -
		     Xref = xref()

	      Adds the modules found in the given directory and the  modules'  data  to  an  Xref
	      server  .  The  default is not to examine subdirectories, but if the option recurse
	      has the value true , modules are searched for in subdirectories on  all  levels  as
	      well  as	in  the  given directory. Returns a sorted list of the names of the added
	      modules.

	      The modules added will not be members of any applications.

	      If the mode of the Xref server is functions , BEAM  files  that  contain	no  debug
	      information are ignored.

       add_module(Xref, File [, Options]) -> {ok, module()} | Error

	      Types  Error = {error, module(), Reason}
		     File = file()
		     Options = [Option] | Option
		     Option = {builtins, bool()} | {verbose, bool()} | {warnings, bool()}
		     Reason  =	{file_error,  file(),  error()}  |  {invalid_filename,	term()} |
		     {invalid_options, term()} | {module_clash,  {module(),  file(),  file()}}	|
		     {no_debug_info, file()} | - error from beam_lib:chunks/2 -
		     Xref = xref()

	      Adds a module and its module data to an Xref server . The module will not be member
	      of any application. Returns the name of the module.

	      If the mode of the Xref server is functions , and the BEAM file contains	no  debug
	      information , the error message no_debug_info is returned.

       add_release(Xref, Directory [, Options]) -> {ok, release()} | Error

	      Types  Directory = directory()
		     Error = {error, module(), Reason}
		     Options = [Option] | Option
		     Option = {builtins, bool()} | {name, release()} | {verbose, bool()} | {warn-
		     ings, bool()}
		     Reason = {application_clash, {application(),  directory(),  directory()}}	|
		     {file_error,    file(),	error()}    |	 {invalid_filename,   term()}	|
		     {invalid_options, term()} | {release_clash, {release(), directory(),  direc-
		     tory()}} | - see also add_directory -
		     Xref = xref()

	      Adds  a  release, the applications of the release, the modules of the applications,
	      and module data of the modules to an Xref server . The applications will be members
	      of the release, and the modules will be members of the applications. The default is
	      to use the base name of the directory as release name, but this can  be  overridden
	      by the name option. Returns the name of the release.

	      If  the  given  directory  has  a  subdirectory named lib , the directories in that
	      directory are assumed to be application directories, otherwise  all  subdirectories
	      of the given directory are assumed to be application directories. If there are sev-
	      eral versions of some application, the one with the highest version is chosen.

	      If the mode of the Xref server is functions , BEAM  files  that  contain	no  debug
	      information are ignored.

       analyze(Xref, Analysis [, Options]) -> {ok, Answer} | Error

	      Types  Analysis  = undefined_function_calls | undefined_functions | locals_not_used
		     | exports_not_used | deprecated_function_calls | {deprecated_function_calls,
		     DeprFlag} | deprecated_functions | {deprecated_functions, DeprFlag} | {call,
		     FuncSpec} | {use, FuncSpec} | {module_call, ModSpec} | {module_use, ModSpec}
		     |	{application_call, AppSpec} | {application_use, AppSpec} | {release_call,
		     RelSpec} | {release_use, RelSpec}
		     Answer = [term()]
		     AppSpec = application() | [application()]
		     DeprFlag = next_version | next_major_release | eventually
		     Error = {error, module(), Reason}
		     FuncSpec = mfa() | [mfa()]
		     ModSpec = module() | [module()]
		     Options = [Option] | Option
		     Option = {verbose, bool()}
		     RelSpec = release() | [release()]
		     Reason  =	{invalid_options,  term()}  |  {parse_error,   string_position(),
		     term()}  |  {unavailable_analysis,  term()}  |  {unknown_analysis, term()} |
		     {unknown_constant, string()} | {unknown_variable, variable()}
		     Xref = xref()

	      Evaluates a predefined analysis. Returns a sorted list without duplicates of call()
	      or  constant()  ,  depending on the chosen analysis. The predefined analyses, which
	      operate on all analyzed modules , are (analyses marked with (*)  are  available  in
	      functions mode only):

		undefined_function_calls (*) :
		  Returns a list of calls to undefined functions .

		undefined_functions :
		  Returns a list of undefined functions .

		locals_not_used (*) :
		  Returns a list of local functions that have not been locally used.

		exports_not_used :
		  Returns a list of exported functions that have not been externally used.

		deprecated_function_calls (*) :
		  Returns a list of external calls to deprecated functions .

		{deprecated_function_calls, DeprFlag} (*) :
		  Returns  a list of external calls to deprecated functions. If DeprFlag is equal
		  to next_version , calls  to  functions  to  be  removed  in  next  version  are
		  returned. If DeprFlag is equal to next_major_release , calls to functions to be
		  removed in next major release are returned as well as calls to functions to  be
		  removed  in  next  version.  Finally,  if DeprFlag is equal to eventually , all
		  calls to functions to be removed are returned, including calls to functions  to
		  be removed in next version or next major release.

		deprecated_functions :
		  Returns a list of externally used deprecated functions.

		{deprecated_functions, DeprFlag} :
		  Returns a list of externally used deprecated functions. If DeprFlag is equal to
		  next_version , functions to  be  removed  in	next  version  are  returned.  If
		  DeprFlag is equal to next_major_release , functions to be removed in next major
		  release are returned as well as  functions  to  be  removed  in  next  version.
		  Finally,  if	DeprFlag is equal to eventually , all functions to be removed are
		  returned, including functions to be removed  in  next  version  or  next  major
		  release.

		{call, FuncSpec} (*) :
		  Returns a list of functions called by some of the given functions.

		{use, FuncSpec} (*) :
		  Returns a list of functions that use some of the given functions.

		{module_call, ModSpec} :
		  Returns a list of modules called by some of the given modules.

		{module_use, ModSpec} :
		  Returns a list of modules that use some of the given modules.

		{application_call, AppSpec} :
		  Returns a list of applications called by some of the given applications.

		{application_use, AppSpec} :
		  Returns a list of applications that use some of the given applications.

		{release_call, RelSpec} :
		  Returns a list of releases called by some of the given releases.

		{release_use, RelSpec} :
		  Returns a list of releases that use some of the given releases.

       d(Directory) -> [DebugInfoResult] | [NoDebugInfoResult] | Error

	      Types  Directory = directory()
		     DebugInfoResult  =  {deprecated,  [funcall()]}  | {undefined, [funcall()]} |
		     {unused, [mfa()]}
		     Error = {error, module(), Reason}
		     NoDebugInfoResult = {deprecated, [mfa()]} | {undefined, [mfa()]}
		     Reason =  {file_error,  file(),  error()}	|  {invalid_filename,  term()}	|
		     {unrecognized_file, file()} | - error from beam_lib:chunks/2 -

	      The  modules found in the given directory are checked for calls to deprecated func-
	      tions , calls to undefined functions , and for unused  local  functions.	The  code
	      path is used as library path .

	      If  some of the found BEAM files contain debug information , then those modules are
	      checked and a list of tuples is returned. The first element of each  tuple  is  one
	      of:

		* deprecated  ,  the second element is a sorted list of calls to deprecated func-
		  tions;

		* undefined , the second element is a sorted list of  calls  to  undefined  func-
		  tions;

		* unused , the second element is a sorted list of unused local functions.

	      If  no BEAM file contains debug information, then a list of tuples is returned. The
	      first element of each tuple is one of:

		* deprecated , the second element is a sorted list of externally used  deprecated
		  functions;

		* undefined , the second element is a sorted list of undefined functions.

       forget(Xref) -> ok
       forget(Xref, Variables) -> ok | Error

	      Types  Error = {error, module(), Reason}
		     Reason = {not_user_variable, term()}
		     Variables = [variable()] | variable()
		     Xref = xref()

	      forget/1 and forget/2 remove all or some of the user variables of an xref server .

       format_error(Error) -> Chars

	      Types  Error = {error, module(), term()}
		     Chars = [char() | Chars]

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

       get_default(Xref) -> [{Option, Value}]
       get_default(Xref, Option) -> {ok, Value} | Error

	      Types  Error = {error, module(), Reason}
		     Option = builtins | recurse | verbose | warnings
		     Reason = {invalid_options, term()}
		     Value = bool()
		     Xref = xref()

	      Returns the default values of one or more options.

       get_library_path(Xref) -> {ok, LibraryPath}

	      Types  LibraryPath = library_path()
		     Xref = xref()

	      Returns the library path .

       info(Xref) -> [Info]
       info(Xref, Category) -> [{Item, [Info]}]
       info(Xref, Category, Items) -> [{Item, [Info]}]

	      Types  Application = [] | [application()]
		     Category = modules | applications | releases | libraries
		     Info  = {application, Application} | {builtins, bool()} | {directory, direc-
		     tory()}  |  {library_path,  library_path()}  |  {mode,  mode()}  |  {no_ana-
		     lyzed_modules,  int()}  | {no_applications, int()} | {no_calls, {NoResolved,
		     NoUnresolved}} | {no_function_calls, {NoLocal,  NoResolvedExternal,  NoUnre-
		     solved}} | {no_functions, {NoLocal, NoExternal}} | {no_inter_function_calls,
		     int()} | {no_releases, int()} | {release, Release} | {version, Version}
		     Item = module() | application() | release() | library()
		     Items = Item | [Item]
		     NoLocal = NoExternal = NoResolvedExternal, NoResolved = NoUnresolved = int()
		     Release = [] | [release()]
		     Version = [int()]
		     Xref = xref()

	      The info functions return information as a list of  pairs  {Tag,	term()}  in  some
	      order about the state and the module data of an Xref server .

	      info/1 returns information with the following tags (tags marked with (*) are avail-
	      able in functions mode only):

		* library_path , the library path ;

		* mode , the mode ;

		* no_releases , number of releases;

		* no_applications , total number of applications (of all releases);

		* no_analyzed_modules , total number of analyzed modules ;

		* no_calls (*), total number of calls (in all modules),  regarding  instances  of
		  one function call in different lines as separate calls;

		* no_function_calls  (*),  total  number of local calls , resolved external calls
		  and unresolved calls ;

		* no_functions (*), total number of local and exported functions;

		* no_inter_function_calls (*), total number of calls of the Inter Call Graph .

	      info/2 and info/3 return information about all or some  of  the  analyzed  modules,
	      applications, releases or library modules of an Xref server. The following informa-
	      tion is returned for every analyzed module:

		* application , an empty list if the module does not belong to	any  application,
		  otherwise a list of the application name;

		* builtins , whether calls to BIFs are included in the module's data;

		* directory , the directory where the module's BEAM file is located;

		* no_calls (*), number of calls, regarding instances of one function call in dif-
		  ferent lines as separate calls;

		* no_function_calls (*), number of local calls, resolved external calls and unre-
		  solved calls;

		* no_functions (*), number of local and exported functions;

		* no_inter_function_calls (*), number of calls of the Inter Call Graph;

	      The following information is returned for every application:

		* directory , the directory where the modules' BEAM files are located;

		* no_analyzed_modules , number of analyzed modules;

		* no_calls (*), number of calls of the application's modules, regarding instances
		  of one function call in different lines as separate calls;

		* no_function_calls (*), number of local calls, resolved external calls and unre-
		  solved calls of the application's modules;

		* no_functions	(*),  number of local and exported functions of the application's
		  modules;

		* no_inter_function_calls (*), number of calls of the Inter  Call  Graph  of  the
		  application's modules;

		* release , an empty list if the application does not belong to any release, oth-
		  erwise a list of the release name;

		* version , the application's version as a list of  numbers.  For  instance,  the
		  directory  "kernel-2.6" results in the application name kernel and the applica-
		  tion version [2,6]; "kernel" yields the name kernel and the version [].

	      The following information is returned for every release:

		* directory , the release directory;

		* no_analyzed_modules , number of analyzed modules;

		* no_applications , number of applications;

		* no_calls (*), number of calls of the release's modules, regarding instances  of
		  one function call in different lines as separate calls;

		* no_function_calls (*), number of local calls, resolved external calls and unre-
		  solved calls of the release's modules;

		* no_functions (*), number of local and exported functions of the release's  mod-
		  ules;

		* no_inter_function_calls  (*),  number  of  calls of the Inter Call Graph of the
		  release's modules.

	      The following information is returned for every library module:

		* directory , the directory where the library module's BEAM file is located.

	      For every number of calls, functions etc. returned by the  no_  tags,  there  is	a
	      query returning the same number. Listed below are examples of such queries. Some of
	      the queries return the sum of a two or more of the no_ tags numbers. mod	(  app	,
	      rel ) refers to any module (application, release).

		* no_analyzed_modules

		  * "# AM" (info/1)

		  * "# (Mod) app:App" (application)

		  * "# (Mod) rel:Rel" (release)

		* no_applications

		  * "# A" (info/1)

		* no_calls . The sum of the number of resolved and unresolved calls:

		  * "# (XLin) E + # (LLin) E" (info/1)

		  * "T = E | mod:Mod, # (LLin) T + # (XLin) T" (module)

		  * "T = E | app:App, # (LLin) T + # (XLin) T" (application)

		  * "T = E | rel:Rel, # (LLin) T + # (XLin) T" (release)

		* no_functions	.  Functions in library modules and the functions module_info/0,1
		  are not counted by info . Assuming that "Extra := _:module_info/\"(0|1)\" + LM"
		  has been evaluated, the sum of the number of local and exported functions are:

		  * "# (F - Extra)" (info/1)

		  * "# (F * mod:Mod - Extra)" (module)

		  * "# (F * app:App - Extra)" (application)

		  * "# (F * rel:Rel - Extra)" (release)

		* no_function_calls  .	The  sum  of the number of local calls, resolved external
		  calls and unresolved calls:

		  * "# LC + # XC" (info/1)

		  * "# LC | mod:Mod + # XC | mod:Mod" (module)

		  * "# LC | app:App + # XC | app:App" (application)

		  * "# LC | rel:Rel + # XC | mod:Rel" (release)

		* no_inter_function_calls

		  * "# EE" (info/1)

		  * "# EE | mod:Mod" (module)

		  * "# EE | app:App" (application)

		  * "# EE | rel:Rel" (release)

		* no_releases

		  * "# R" (info/1)

       m(Module) -> [DebugInfoResult] | [NoDebugInfoResult] | Error
       m(File) -> [DebugInfoResult] | [NoDebugInfoResult] | Error

	      Types  DebugInfoResult = {deprecated, [funcall()]}  |  {undefined,  [funcall()]}	|
		     {unused, [mfa()]}
		     Error = {error, module(), Reason}
		     File = file()
		     Module = module()
		     NoDebugInfoResult = {deprecated, [mfa()]} | {undefined, [mfa()]}
		     Reason   =   {file_error,	file(),  error()}  |  {interpreted,  module()}	|
		     {invalid_filename, term()} | {cover_compiled, module()}  |  {no_such_module,
		     module()} | - error from beam_lib:chunks/2 -

	      The  given  BEAM	file  (with  or without the .beam extension) or the file found by
	      calling code:which(Module) is checked for calls to deprecated functions , calls  to
	      undefined  functions  ,  and  for  unused local functions. The code path is used as
	      library path .

	      If the BEAM file contains debug information , then a list of  tuples  is	returned.
	      The first element of each tuple is one of:

		* deprecated  ,  the second element is a sorted list of calls to deprecated func-
		  tions;

		* undefined , the second element is a sorted list of  calls  to  undefined  func-
		  tions;

		* unused , the second element is a sorted list of unused local functions.

	      If  the  BEAM  file  does  not  contain debug information, then a list of tuples is
	      returned. The first element of each tuple is one of:

		* deprecated , the second element is a sorted list of externally used  deprecated
		  functions;

		* undefined , the second element is a sorted list of undefined functions.

       q(Xref, Query [, Options]) -> {ok, Answer} | Error

	      Types  Answer  = false | [constant()] | [Call] | [Component] | int() | [DefineAt] |
		     [CallAt] | [AllLines]
		     Call = call() | ComponentCall
		     ComponentCall = {Component, Component}
		     Component = [constant()]
		     DefineAt = {mfa(), LineNumber}
		     CallAt = {funcall(), LineNumbers}
		     AllLines = {{DefineAt, DefineAt}, LineNumbers}
		     Error = {error, module(), Reason}
		     LineNumbers = [LineNumber]
		     LineNumber = int()
		     Options = [Option] | Option
		     Option = {verbose, bool()}
		     Query = string() | atom()
		     Reason  =	{invalid_options,  term()}  |  {parse_error,   string_position(),
		     term()}  |  {type_error,  string()}  | {type_mismatch, string(), string()} |
		     {unknown_analysis, term()} | {unknown_constant, string()}	|  {unknown_vari-
		     able, variable()} | {variable_reassigned, string()}
		     Xref = xref()

	      Evaluates  a  query in the context of an Xref server , and returns the value of the
	      last statement. The syntax of the value depends on the expression:

		* A set of calls is represented by a sorted list without duplicates of call() .

		* A set of constants is represented by a sorted list without duplicates  of  con-
		  stant() .

		* A  set  of strongly connected components is a sorted list without duplicates of
		  Component .

		* A set of calls between strongly connected components is a sorted  list  without
		  duplicates of ComponentCall .

		* A chain of calls is represented by a list of constant() . The list contains the
		  From vertex of every call and the To vertex of the last call.

		* The of operator returns false if no chain of calls between the given	constants
		  can be found.

		* The  value  of the closure operator (the digraph representation) is represented
		  by the atom 'closure()' .

		* A set of line numbered functions is represented by a sorted list without dupli-
		  cates of DefineAt .

		* A  set  of line numbered function calls is represented by a sorted list without
		  duplicates of CallAt .

		* A set of line numbered functions and function calls is represented by a  sorted
		  list without duplicates of AllLines .

	      For  both  CallAt  and AllLines it holds that for no list element is LineNumbers an
	      empty list; such elements have been removed. The constants  of  component  and  the
	      integers of LineNumbers are sorted and without duplicates.

       remove_application(Xref, Applications) -> ok | Error

	      Types  Applications = application() | [application()]
		     Error = {error, module(), Reason}
		     Reason = {no_such_application, application()}
		     Xref = xref()

	      Removes applications and their modules and module data from an Xref server .

       remove_module(Xref, Modules) -> ok | Error

	      Types  Error = {error, module(), Reason}
		     Modules = module() | [module()]
		     Reason = {no_such_module, module()}
		     Xref = xref()

	      Removes analyzed modules and module data from an Xref server .

       remove_release(Xref, Releases) -> ok | Error

	      Types  Error = {error, module(), Reason}
		     Reason = {no_such_release, release()}
		     Releases = release() | [release()]
		     Xref = xref()

	      Removes  releases  and  their  applications,  modules  and module data from an Xref
	      server .

       replace_application(Xref, Application, Directory [, Options])  ->  {ok,	application()}	|
       Error

	      Types  Application = application()
		     Directory = directory()
		     Error = {error, module(), Reason}
		     Options = [Option] | Option
		     Option = {builtins, bool()} | {verbose, bool()} | {warnings, bool()}
		     Reason = {no_such_application, application()} | - see also add_application -
		     Xref = xref()

	      Replaces	the modules of an application with other modules read from an application
	      directory. Release membership of the application is retained. Note that the name of
	      the application is kept; the name of the given directory is not used.

       replace_module(Xref, Module, File [, Options]) -> {ok, module()} | Error

	      Types  Error = {error, module(), Reason}
		     File = file()
		     Module = module()
		     Options = [Option] | Option
		     Option = {verbose, bool()} | {warnings, bool()}
		     ReadModule = module()
		     Reason  =	{module_mismatch,  module(),  ReadModule} | {no_such_module, mod-
		     ule()} | - see also add_module -
		     Xref = xref()

	      Replaces module data of an analyzed module with data read from a BEAM file.  Appli-
	      cation  membership  of  the module is retained, and so is the value of the builtins
	      option of the module. An error is returned if the name of the read  module  differs
	      from the given module.

	      The  update  function is an alternative for updating module data of recompiled mod-
	      ules.

       set_default(Xref, Option, Value) -> {ok, OldValue} | Error
       set_default(Xref, OptionValues) -> ok | Error

	      Types  Error = {error, module(), Reason}
		     OptionValues = [OptionValue] | OptionValue
		     OptionValue = {Option, Value}
		     Option = builtins | recurse | verbose | warnings
		     Reason = {invalid_options, term()}
		     Value = bool()
		     Xref = xref()

	      Sets the default value of one or more options. The options that can be set this way
	      are:

		* builtins , with initial default value false ;

		* recurse , with initial default value false ;

		* verbose , with initial default value false ;

		* warnings , with initial default value true .

	      The initial default values are set when creating an Xref server .

       set_library_path(Xref, LibraryPath [, Options]) -> ok | Error

	      Types  Error = {error, module(), Reason}
		     LibraryPath = library_path()
		     Options = [Option] | Option
		     Option = {verbose, bool()}
		     Reason = {invalid_options, term()} | {invalid_path, term()}
		     Xref = xref()

	      Sets  the  library  path	.  If the given path is a list of directories, the set of
	      library modules is determined  by  choosing  the	first  module  encountered  while
	      traversing the directories in the given order, for those modules that occur in more
	      than one directory. By default, the library path is an empty list.

	      The library path code_path is used by the functions m/1 and d/1 , but can  also  be
	      set  explicitly.	Note  however  that the code path will be traversed once for each
	      used library module while setting up module data. On the other hand, if  there  are
	      only  a  few  modules  that are used by not analyzed, using code_path may be faster
	      than setting the library path to code:get_path() .

	      If the library path is set to code_path , the set of library modules is not  deter-
	      mined, and the info functions will return empty lists of library modules.

       start(NameOrOptions) -> Return

	      Types  Name = atom()()
		     XrefOrOptions = Xref | Options
		     Options = [Option] | Option
		     Option = {xref_mode, mode()} | term()
		     Return = {ok, pid()} | {error, {already_started, pid()}}

	      Creates  an  Xref  server . The process may optionally be given a name. The default
	      mode is functions . Options that are not	recognized  by	Xref  are  passed  on  to
	      gen_server:start/4 .

       start(Name, Options) -> Return

	      Types  Name = atom()()
		     Options = [Option] | Option
		     Option = {xref_mode, mode()} | term()
		     Return = {ok, pid()} | {error, {already_started, pid()}}

	      Creates  an  Xref server with a given name. The default mode is functions . Options
	      that are not recognized by Xref are passed on to gen_server:start/4 .

       stop(Xref)

	      Types  Xref = xref()

	      Stops an Xref server .

       update(Xref [, Options]) -> {ok, Modules} | Error

	      Types  Error = {error, module(), Reason}
		     Modules = [module()]
		     Options = [Option] | Option
		     Option = {verbose, bool()} | {warnings, bool()}
		     Reason = {invalid_options, term()} | {module_mismatch, module(), ReadModule}
		     | - see also add_module -
		     Xref = xref()

	      Replaces	the module data of all analyzed modules the BEAM files of which have been
	      modified since last read by an add function or update . Application  membership  of
	      the  modules  is	retained,  and	so is the value of the builtins option. Returns a
	      sorted list of the names of the replaced modules.

       variables(Xref [, Options]) -> {ok, [VariableInfo]}

	      Types  Options = [Option] | Option
		     Option = predefined | user | {verbose, bool()}
		     Reason = {invalid_options, term()}
		     VariableInfo = {predefined, [variable()]} | {user, [variable()]}
		     Xref = xref()

	      Returns a sorted lists of the names of the  variables  of  an  Xref  server  .  The
	      default is to return the user variables only.

SEE ALSO
       beam_lib(3erl) , digraph(3erl) , digraph_utils(3erl) , re(3erl) , TOOLS User's Guide

Ericsson AB				  tools 2.6.6.3 			       xref(3erl)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 12:09 PM.