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).