.TH "oxref" "1" "2012\-2023" "oxref\&.2\&.01\&.00" "oxref \- cross reference utility" .PP .SH "NAME" oxref \- cross reference utility for various languages .PP .SH "SYNOPSIS" \fBoxref\fP [OPTIONS] \fIarguments\fP .br [OPTIONS] \- see the \fBOPTIONS\fP section below .br arguments \- object files and/or libraries to process .br .PP The cross reference listing is written to the standard output stram\&. .PP .SH "DESCRIPTION" .PP The program \fBoxref\fP 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\&. .PP 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\&. .PP Call\-trees show the (nested) tree of functions directly or indirectly called from the top\-level (main program) function\&. .PP Called\-by overviews start from a specified function name, and (recursively) show the functions calling the specified function\&. .PP Brief examples of these three modes of operation are shown below\&. .PP Especially the \(cq\&called\-by\(cq\& 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\&. .PP 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\&. .PP \fBOxref\fP\(cq\&s output starts with a header showing information about the program, a time stamp and the arguments passed to \fIoxref\fP\&. E\&.g\&., .PP .nf 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 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- .fi .PP The header is (depending on the specified options) followed by the cross reference information, the call tree and/or the called\-by overview\&. .PP \fBCross reference listings\fP 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: .nf 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&) .fi .PP \fBCall trees\fP show the names of all entities used or called from a certain starting point\&. For \fBC\fP and \fBC++\fP programs the starting point \fImain\fP produces the program\(cq\&s full call tree\&. A (partially shown) call tree might look like this: .nf 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 .fi Calling levels are indented using +\- indicators, continuation at identical levels are indicated by vertical lines, using | characters\&. In the shown call tree \fImain\fP calls \fIusage\fP, the \fIStorage\fP constructor and the \fIStorage::tree()\fP member\&. Likewise, the \fIStorage\fP constructor calls the \fIStore\fP constructor and the member \fIStorage::patternFile\fP\&. Recursively called functions appear in the overview where their names are followed by \fI==> nr\fP arrows where \fInr\fP refers to the call\-level where the function is defined\&. The top level (e\&.g\&. \fImain\fP) is referred to as level 0\&. Here is an example showing recursion in the call\-tree of the \fIbisonc++\fP program: .nf main \&.\&.\&. +\-Grammar::deriveSentence() | +\-Rules::s_startSymbol | +\-Grammar::derivable(Symbol const*) | +\-Grammar::becomesDerivable(Production const*) | | +\-Grammar::derivable(Symbol const*) ==> 2 | +\-Grammar::isDerivable(Production const*) \&.\&.\&. .fi Indirect recursion is shown this way as well\&. .PP Caveat: in order to produce the program\(cq\&s call tree the object file containing the program\(cq\&s starting point (e\&.g\&., \fImain\fP) must be available to \fIoxref\fP\&. If \fImain\&.o\fP is the object file of the function \fImain\fP then \fImain\&.o\fP must explicitly be specified as \fIoxref\(cq\&s\fP command\-line argument (see, e\&.g\&., the command specification shown above in the header line of \fIoxref\(cq\&s\fP output)\&. .PP \fBCalled\-by listings\fP start from a specified function (specified as a regular expression but usually simply specified as \fIClassName::memberFunction\fP, showing (recursively) the functions calling the specified function (see option \fI\-\-called\-by\fP below): .nf 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) .fi .PP .SH "RETURN VALUE" .PP \fBOxref\fP returns 1 to the operating system if an error occurs or if \fBoxref\fP automatically shows its usage info\&. .PP \fBOxref\fP returns 0 if the requested action was successfully completed, or if the \fI\-\-version\fP or \fI\-\-help\fP options are specified\&. .PP .SH "OPTIONS" .PP 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\&. .PP .IP o \fB\-\-arg\fP=\fImode\fP (\fB\-a\fP) .br Mode specifies the way the output is abbreviated: .br .IP \fBcount\fP \- function parameters are suppressed; instead the number of arguments required by a function is shown in its parameter list\&. Example: .nf usage(1) .fi instead of .nf usage(std::string const&) .fi .IP \fBfirst\fP \- only show the first word of parameters\&. Example: .nf insertDefined(unsigned, std::ostream&, std::vector&) .fi instead of .nf insertDefined(unsigned int, std::ostream&, std::vector > const&) .fi .IP \fBlen\fP \- where \fIlen\fP is a positive integral number (5 is used if \fIlen\fP is less than 5)\&. The value \fIlen\fP specifies the maximum length of parameter names\&. If parameter names need to be truncated, an ellipsis replaces the truncated characters\&. Example using \fI\-a 12\fP: .nf insertDefined(unsigned int, std::ostream&, std::vect\&.\&.\&.&) .fi instead of .nf insertDefined(unsigned int, std::ostream&, std::vector > const&) .fi .IP .IP o \fB\-\-called\-by\fP=\fIspec\fP (\fB\-c\fP) .br \fIspec\fP is a regular expression showing (recursively) the function(s) and the functions calling those functions\&. Although \fIspec\fP can refer to multiple functions, a single function can be specified as, e\&.g\&., its name, prefixed by the function\(cq\&s class\&. E\&.g\&., \fIStore::define\fP (which is a member function of \fBoxref\fP\(cq\&s \fIStore\fP class, see the \fBDESCRIPTION\fP section)\&. .IP When specifying the \fI\-\-called\-by\fP option the \fI\-f\fP and \fI\-s\fP options do not have to be specified\&. If only the called\-by hierarchy is requested the \fI\-\-no\-xref\fP option can be specified to prevent writing the cross\-reference listing to the standard output stream\&. .IP As an example: to generated the \fIcalled\-by\fP listing for \fBoxref\fP\(cq\&s \fIStore::define\fP function the following command was issued: .nf oxref \-Xc Store::define \-r replacements tmp/main\&.o tmp/libmodules\&.a .fi (with \fIreplacements\fP being the file containing \fBoxref\fP\(cq\&s type replacements, see option \fI\-\-replace\-file\fP below)\&. .IP .IP o \fB\-\-full\-symbol\fP \fB\-f\fP .br The full names of the symbols are shown, in addition to the plain symbol names (see also options \fIobject\-files, source\-files\fP and \fIxref\-source\-files\fP)\&. .br Full names include class names and/or namespace identifiers\&. Example: .nf insertDefined(unsigned int, std::ostream&, std::vector > const&) Full name: Store::insertDefined(unsigned int, std::ostream&, std::vector > const&) .fi .IP .IP o \fB\-\-help\fP (\fB\-h\fP) .br Basic usage information is written to the standard error stream\&. .IP .IP o \fB\-\-no\-xref\fP (\fB\-X\fP) .br The \fIno\-xref\fP option prevents the cross\-reference information from being written to the standard output stream\&. It can be useful in situations where you\(cq\&re only interested in the program\(cq\&s call\-tree (cf\&. option \fI\-\-tree\fP)\&. .IP .IP o \fB\-\-objdump\fP=\fIcommand\fP .br The \fIcommand\fP option value specifies how the object\-dumping program is called\&. By default it is called as \fI/usr/bin/objdump \-C \-t\fP\&. In practice there\(cq\&s probably no reason for using this option\&. .IP .IP o \fB\-\-object\-files\fP (\fB\-o\fP) .br Include in the cross reference listing the name of object files in which symbols (data, functions) are defined (see also options \fIfull\-symbol, source\-files\fP and \fIxref\-source\-files\fP) .IP .IP o \fB\-\-replace\fP=\fIspec\fP (\fB\-R\fP) .br Output generated by \fIobjdump\fP may show the compiler\(cq\&s ideas of what, e\&.g\&., a \fBC++\fP \fIstd::string\fP is\&. Thus, instead of a parameter \fIstd::sting const &\fP it may show .nf std::__cxx11::basic_string const & .fi \fIR\fP options are used to specify text replacements of the form .nf #find#replace# .fi where \fI#\fP can be any character not used in either the \fIfind\fP text or the \fIreplace\fP text\&. For example: .nf #std::__cxx11::basic_string#std::string# .fi Multiple \fIR\fP options may be specified, which are applied in sequence line\-by\-line to all output lines of \fIobjdump\fP\&. E\&.g, after replacing the above long definition of a string into \fIstd::string\fP subsequent replacements should use \fIstd::string\fP rather than the original long definition provided by the compiler\&. .IP In practice replacement specifications are specified after initially running \fIoxref\fP without any specifications\&. The required replacements are then derived from the obtained output .IP .IP o \fB\-\-replace\-file\fP=\fIfname\fP (\fB\-r\fP) .br Replacement specifications can also be stored in a file\&. Specifications read from file are handled like those obtained from \fIreplace\fP options with the \fIreplace\fP options being processed before the replacement specifications read from the file specified with the \fIreplace_file\fP are processed\&. .IP .IP o \fB\-\-select\fP=\fIname\fP .br Only display the cross\-reference of \fIname\fP, where \fIname\fP is the (case sensitive) initial substring of a symbol .IP .IP o \fB\-\-select\-pattern\fP=\fIregex\fP .br Only display the cross\-reference of symbols matching the regular expression \fIregex\fP, where \fIregex\fP is a regular expression matching the \fBregex\fP(7) specification, including the extensions offered by the \fBpattern\fP(3bobcat) \fBPattern\fP class\&. Case sensitive matching is used here, too\&. .IP .IP o \fB\-\-source\-files\fP (\fB\-s\fP) .br Include in the cross reference listing the names of the source files in which symbols are defined (see also options \fIfull\-symbol, object\-files\fP and \fIxref\-source\-files\fP) .IP .IP o \fB\-\-tree\fP=\fIfname\fP (\fB\-t\fP) .br The \fItree\fP option generates a call tree for function \fIfname\fP\&. The argument \fIfname\fP defines the starting point of the call tree\&. Note that the program\(cq\&s starting point (usually \fImain\fP) does not normally appear in a cross\-reference listing, as it is not used by other parts of the program\&. To obtain the call tree for the program\(cq\&s starting function in these cases specify \fI\-\-tree main\fP\&. Otherwise, if the call tree of another function is requested its `Full name\(cq\& specification as used in the cross\-reference listing must be used\&. .IP .IP o \fB\-\-xref\-source\-files\fP (\fB\-x\fP) .br Include in the cross reference listing the name of source files in which used symbols are defined (see also options \fIfull\-symbol, object\-files\fP and \fIsource\-files\fP) .IP .IP o \fB\-\-version\fP (\fB\-v\fP) .br \fIOxref\fP\(cq\&s version number is written to the standard error stream\&. .PP .SH "EXAMPLES" .PP The examples show how \fIoxref\fP was called, followed by a representative example of a cross\-reference listing for a symbol\&. \fIOxref\fP\(cq\&s own cross reference listing was used: .nf 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&) .fi .PP .SH "BUGS" .PP No bugs reported .PP .SH "ABOUT" .PP 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 \fBC++\fP this is a difficult hurdle to pass\&. .PP Looking for `cross reference programs\(cq\& 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\&. .PP 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? .PP 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\&. .PP Programs like \fBnm\fP(1) and \fBobjdump\fP(1) can be used to produce human readable output from the information embedded in object files\&. \fIOxref\fP reads this information and organizes it, creating a cross reference listing\&. .PP Since all compilable program languages generate identically organized object files (or maybe better: generate object files that can be interpreted by \fBobjdump\fP(1)), \fIoxref\fP can broadly be applied\&. As long as \fBobjdump\fP(1) produces sensible output \fIoxref\fP should be able to generate a cross reference listing\&. .PP \fIOxref\fP\(cq\&s name consists of two syllables: \fIo\fP and \fIxref\fP\&. The \fIo\fP represents the program \fBobjdump\fP(1), called from \fIoxref\fP as a child program\&. The important part is of course the cross\-referencing of symbols\&. Like the common abbreviation of \fIrail\-road crossing\fP, \fIrail\-road xing\fP, cross referencing is abbreviated to \fIxref\fP\&. Hence \fIoxref\fP\&. .PP Of course, nearly everybody will read \fIoxref\fP as \fIox\-ref\fP\&. Fortunately, here too we\(cq\&re on familiar ground: Bison, Cow, Gnu, Yacc: all are bovine animals\&. To that important list \fIoxref\fP adds the Ox\&. .PP .SH "FILES" .PP An example of \fIoxref\fP\(cq\&s own cross reference listing is provided (on Debian systems) in the file .nf /usr/share/doc/oxref/oxref\&.xref\&.gz .fi .PP .SH "SEE ALSO" .PP \fBnm\fP(1), \fBobjdump\fP(1), \fBpattern\fP(3bobcat), \fBregex\fP(7) .PP .SH "AUTHOR" .PP Frank B\&. Brokken (f\&.b\&.brokken@rug\&.nl)\&.