Provided by: oxref_1.00.01-1_amd64 bug

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