Provided by: oxref_1.00.06-2_amd64 
NAME
oxref - cross reference utility for multiple 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 a cross reference listing of symbols defined in non-stripped object files
and/or libraries.
A cross reference listing shows the functions using certain symbols (functions, data). This is useful
information during program development and debugging phases. 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.
The generated cross reference listing 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 V0.90.00 2011
CREATED Wed, 16 Feb 2011 15:21:03 +0000
CROSS REFERENCE FOR: --select define liboxref.a
----------------------------------------------------------------------
RETURN VALUE
Oxref returns 0 to the operating system unless an error occurs or oxref’s version or usage info is shown
or requested. In those cases 1 is returned
OPTIONS
If 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.
o --arg=mode (-a)
Mode specifies the way the output is abbreviated:
count - function parameters are suppressed; instead the number of arguments required by a function
is shown in its parameter list. Example:
usage(1)
instead of
usage(std::string const&)
first - only show the first word of parameters. Example:
insertDefined(unsigned, std::ostream&, std::vector&)
instead of
insertDefined(unsigned int, std::ostream&, std::vector<XrefData,
std::allocator<XrefData> > const&)
<len> - where <len> is a positive integral number (5 is used if <len> is less than 5). <len>
specifies the maximum length of parameter names. If parameter names need to be truncated, an
ellipsis replaces the truncated characters. Example using -a 12:
insertDefined(unsigned int, std::ostream&, std::vect...&)
instead of
insertDefined(unsigned int, std::ostream&, std::vector<XrefData,
std::allocator<XrefData> > const&)
o --full-symbol -f
The full names of the symbols are shown, in addition to the plain symbol names. Full names include
class names and/or namespace identifiers. Example:
insertDefined(unsigned int, std::ostream&, std::vector<XrefData,
std::allocator<XrefData> > const&)
Full name: Store::insertDefined(unsigned int, std::ostream&,
std::vector<XrefData, std::allocator<XrefData> > const&)
o --help (-h)
Basic usage information is written to the standard error stream.
o --object-files (-o)
Include the name of object files containing the symbols in the cross reference listing
o --select=name
Only display the cross-reference of name, where name is the (case sensitive) initial substring of
a symbol
o --select-pattern=regex
Only display the cross-reference of symbols matching the regular expression regex, where regex is
a regular expression matching the regex(7) specification, including the extensions offered by the
pattern(3bobcat) Pattern class. Case sensitive matching is used here, too.
o --source-files (-s)
Include the name of source files containing the symbols in the cross reference listing
o --xref-source-files (-x)
Include the name of source files containing the used symbols in the cross reference listing
o --version (-v)
Oxref’s version number is written to the standard error stream.
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
This is the initial release version of oxref.
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).