oxref(1)

oxref - cross reference utility
(oxref.2.01.00)

2012-2023

NAME

oxref - cross reference utility for various languages

SYNOPSIS

oxref [OPTIONS] arguments
[OPTIONS] - see the OPTIONS section below
arguments - object files and/or libraries to process

The cross reference listing is written to the standard output stram.

DESCRIPTION

The program oxref generates cross reference listings, program or function call-trees, and/or (recursive) called-by overviews of specified functions using non-stripped object files and/or libraries.

Cross reference listings contain the names and source files of functions defined in the specified object files and/or libraries, as well as an overview of the functions calling these functions.

Call-trees show the (nested) tree of functions directly or indirectly called from the top-level (main program) function.

Called-by overviews start from a specified function name, and (recursively) show the functions calling the specified function.

Brief examples of these three modes of operation are shown below.

Especially the 'called-by' overview is useful information during program development and debugging phases, as it immediately provides the hierarchy of functions directly or indirectly calling the specified function name.

E.g., assuming that the signature; the pre-conditions or the post-conditions of a function must be changed it is important to know from what function(s) the function-to-modify is called to verify that the changes to the modified function do not break its calling functions.

Oxref's output starts with a header showing information about the program, a time stamp and the arguments passed to oxref. E.g.,


oxref by Frank B. Brokken (f.b.brokken@rug.nl)
oxref V 2.01.00 2012-2023

CREATED Wed, 25 Oct 2023 11:56:44 +0000
OXREF ARGUMENTS: -t main -r replace -fxs tmp/main.o tmp/libmodules.a 
----------------------------------------------------------------------

The header is (depending on the specified options) followed by the cross reference information, the call tree and/or the called-by overview.

Cross reference listings show the symbols, as well as (optionally) their full names (e.g., prefixed by class-names), source files and the source files and names of functions using the symbols. The cross reference listings of a global variable and a function looks like this:


    author
      Full name: Icmbuild::author
      Source:    version.cc 
      Used By:
        header.cc: header(int, char**)
        usage.cc: usage(std::string const&)
    
    calledFrom(unsigned long)
      Full name: XrefData::calledFrom(unsigned long)
      Source:    calledfrom.cc 
      Used By:
        undefined.cc: Store::undefined(std::string const&)
    

Call trees show the names of all entities used or called from a certain starting point. For C and C++ programs the starting point main produces the program's full call tree. A (partially shown) call tree might look like this:


    CALL TREE FOR: main
    
    main
    +-usage(std::string const&)
    | +-Icmbuild::version
    +-Storage::Storage()
    | +-Store::Store()
    | +-Storage::patternFile(std::string const&)
    +-Storage::tree() const
      +-Store::tree(std::string const&) const
        +-Tree::print(unsigned long, unsigned long)
          +-Tree::calls(unsigned long, unsigned long)
          | +-Tree::calls(unsigned long, XrefData const&)
          +-Tree::indent(unsigned long) const
        
Calling levels are indented using +- indicators, continuation at identical levels are indicated by vertical lines, using | characters. In the shown call tree main calls usage, the Storage constructor and the Storage::tree() member. Likewise, the Storage constructor calls the Store constructor and the member Storage::patternFile. Recursively called functions appear in the overview where their names are followed by ==> nr arrows where nr refers to the call-level where the function is defined. The top level (e.g. main) is referred to as level 0. Here is an example showing recursion in the call-tree of the bisonc++ program:

    main
    ...
    +-Grammar::deriveSentence()
    | +-Rules::s_startSymbol
    | +-Grammar::derivable(Symbol const*)
    |   +-Grammar::becomesDerivable(Production const*)
    |   | +-Grammar::derivable(Symbol const*) ==> 2
    |   +-Grammar::isDerivable(Production const*)
    ...
        
Indirect recursion is shown this way as well.

Caveat: in order to produce the program's call tree the object file containing the program's starting point (e.g., main) must be available to oxref. If main.o is the object file of the function main then main.o must explicitly be specified as oxref's command-line argument (see, e.g., the command specification shown above in the header line of oxref's output).

Called-by listings start from a specified function (specified as a regular expression but usually simply specified as ClassName::memberFunction, showing (recursively) the functions calling the specified function (see option --called-by below):


    CALLED-BY LISTING:
    
    Store::define(std::string const&, bool) (define.cc): called by
        Store::setFunction(std::string const&) (setfunction.cc)
        Store::setObject(std::string const&) (setobject.cc)
        Store::setSource(std::string const&) (setsource.cc)
    
    Store::setFunction(std::string const&) (setfunction.cc): called by
        Storage::function(std::string const&) (function.cc)
    
    Store::setObject(std::string const&) (setobject.cc): called by
        Storage::object(std::string const&) (object.cc)
    
    Store::setSource(std::string const&) (setsource.cc): called by
        Storage::sourceFile(std::string const&) (sourcefile.cc)
    
    Storage::function(std::string const&) (function.cc): called by
        Storage::push_back(std::string) (pushback.cc)
    
    Storage::object(std::string const&) (object.cc): called by
        Storage::push_back(std::string) (pushback.cc)
    
    Storage::sourceFile(std::string const&) (sourcefile.cc): called by
        Storage::push_back(std::string) (pushback.cc)
    
    Storage::push_back(std::string) (pushback.cc): called by
        main (main.cc)

RETURN VALUE

Oxref returns 1 to the operating system if an error occurs or if oxref automatically shows its usage info.

Oxref returns 0 if the requested action was successfully completed, or if the --version or --help options are specified.

OPTIONS

Where available, single letter options are listed between parentheses following their associated long-option variants. Single letter options require arguments if their associated long options require arguments as well.

EXAMPLES

The examples show how oxref was called, followed by a representative example of a cross-reference listing for a symbol. Oxref's own cross reference listing was used:


called as: oxref liboxref

define(std::string const&, bool)
  Used By:
    Store::setFunction(std::string const&)
    Store::setObject(std::string const&)
    Store::setSource(std::string const&)

--------------------

called as: oxref -foxs liboxref

define(std::string const&, bool)
  Full name: Store::define(std::string const&, bool)
  Source:    define.cc (1define.o)
  Used By:
    setfunction.cc: Store::setFunction(std::string const&)
    setobject.cc: Store::setObject(std::string const&)
    setsource.cc: Store::setSource(std::string const&)
    

BUGS

No bugs reported

ABOUT

In theory, creating cross reference listings is a complex matter as it requires a full syntax analysis of the sources defining a program. Especially with complex languages like C++ this is a difficult hurdle to pass.

Looking for `cross reference programs' using a search engine returns remarkably few hits. LXR is a promising cross referencing program (see http://lxr.linux.no/), but it requires the use of data base packages, making it somewhat complex to use. Other links refer to cross-reference programs for textual documents, not programs.

The complexity of developing a program generating a cross reference listing has baffled me for a long time. Eventually I realized that in practice the essential information has already been generated by the compiler, when it compiles our source files. So why do it all again?

Once a program has been compiled one or (usually) more object files are available. The linker uses tables of defined and external symbols embedded in the object files to connect the various functions. If all requirements can be satisfied the linker is able to create a running program.

Programs like nm(1) and objdump(1) can be used to produce human readable output from the information embedded in object files. Oxref reads this information and organizes it, creating a cross reference listing.

Since all compilable program languages generate identically organized object files (or maybe better: generate object files that can be interpreted by objdump(1)), oxref can broadly be applied. As long as objdump(1) produces sensible output oxref should be able to generate a cross reference listing.

Oxref's name consists of two syllables: o and xref. The o represents the program objdump(1), called from oxref as a child program. The important part is of course the cross-referencing of symbols. Like the common abbreviation of rail-road crossing, rail-road xing, cross referencing is abbreviated to xref. Hence oxref.

Of course, nearly everybody will read oxref as ox-ref. Fortunately, here too we're on familiar ground: Bison, Cow, Gnu, Yacc: all are bovine animals. To that important list oxref adds the Ox.

FILES

An example of oxref's own cross reference listing is provided (on Debian systems) in the file


    /usr/share/doc/oxref/oxref.xref.gz
        

SEE ALSO

nm(1), objdump(1), pattern(3bobcat), regex(7)

AUTHOR

Frank B. Brokken (f.b.brokken@rug.nl).