.TH "oxref" "1" "2012\-2021" "oxref\&.2\&.00\&.01" "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 of symbols defined in non\-stripped object files and/or libraries as well as program or function call\-trees\&. .PP Cross reference listings show 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\&. .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 V2\&.00\&.00 2012\-2019 CREATED Mon, 11 Mar 2019 05:35:47 +0000 CROSS REFERENCE FOR: \-t main \-r replace \-fxs tmp/main\&.o tmp/libmodules\&.a \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- .fi .PP The header is followed by the cross reference information and the call tree\&. Both the cross reference information and the call tree can be omitted\&. .PP The cross reference listing shows 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 The call tree shows 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 .SH "RETURN VALUE" .PP \fBOxref\fP returns 0 to the operating system unless an error occurs or \fBoxref\fP\(cq\&s version or usage info is shown or requested\&. In those cases 1 is returned .PP .SH "OPTIONS" .PP 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\&. .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\-\-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)\&.