.TH "oxref" "1" "2012\-2018" "oxref\&.1\&.00\&.07\&.tar\&.gz" "oxref \- cross reference utility" .PP .SH "NAME" oxref \- cross reference utility for multiple 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 a cross reference listing of symbols defined in non\-stripped object files and/or libraries\&. .PP 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\&. .PP The generated cross reference listing 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 V0\&.90\&.00 2011 CREATED Wed, 16 Feb 2011 15:21:03 +0000 CROSS REFERENCE FOR: \-\-select define liboxref\&.a \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- .fi .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 \fB\fP \- where \fI\fP is a positive integral number (5 is used if \fI\fP is less than 5)\&. \fI\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\&. 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\-\-object\-files\fP (\fB\-o\fP) .br Include the name of object files containing the symbols in the cross reference listing .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 the name of source files containing the symbols in the cross reference listing .IP .IP o \fB\-\-xref\-source\-files\fP (\fB\-x\fP) .br Include the name of source files containing the used symbols in the cross reference listing .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 This is the initial release version of \fIoxref\fP\&. .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)\&.