XREF(1)                                                   XREF(1)



NAME
       xref - A cross referencing tool for C and Java.

SYNOPSIS
       xref   [options] infile [... infile]

TYPICAL INVOCATION FORMS
       xref   -p <project>

       xref   -update -p <project>

       xref   -html -p <project>

       xref   -update -html -p <project>


       xref   <srcdir>

       xref   -html <srcdir>

DESCRIPTION
       Xref  is  a  C and Java cross-referencing tool.  It
       parses input files noting all symbol's  definitions
       and  usages.  If  not invoked with the -html option
       its output is a list of symbols, together with  po
       sitions of declarations, definition and all usages.
       Output is written to  the  file  specified  by  the
       -refs option. Xref's cross references are destinat
       ed to be read by xref itself or by on-line  editing
       macros. Programming language in which an input file
       is written is inferred from file suffix as follows:
       .java  for a Java language file, .y for a YACC (and
       C) input file, .jar for a Java archive file and fi
       nally all other suffixes are interpreted as C input
       files.

       When invoked with the -html option xref   does  not
       produce  the cross reference file. Instead it reads
       an existing cross reference file and then  it  con
       verts  input  files into a HTML format browsable by
       standard Internet browsers.  In  those  files  each
       symbol  is  linked  to  its definition.  If options
       '-htmlgxlist' and  '-htmllxlist'  is  present  then
       each  definition  is linked to a list of all symbol
       usages.  HTML files are written in directory  hier
       archy specified by the -htmlroot option.


WILD CHARACTERS
       Following wild characters can be used when specify
       ing input files: '*' expands to any (possibly  emp
       ty) string; '?' expands to any single character and
       '[...]' pair expands to one of enclosed characters.
       Ranges  of characters can be included between [ and
       ], so for example [a-z] matches any lower case let
       ter,  [0-9]  matches  any  digit, as it is usual in
       standard shell expressions. If the first  character
       following  the [ is a ^ then the sense of expansion
       is inversed, for example [^0-9] expands to any non-
       digit  character.  Options  -I,  -classpath, -sour
       cepath and -javadocpath also  accept  wild  charac
       ters.  Be  carefull  when  using wild characters in
       those options as they can  considerably  slow  down
       the task.


NOTE
       Xref  accepts many options, however except the -p ,
       -update and -html options, it is not recommended to
       write them directly on the command line.  The stan
       dard way of passing options to xref  is  configura
       tion  file  named .xrefrc placed in user's home di
       rectory. Options stored in the ${HOME}/.xrefrc file
       are  read  at each xref invocation. Storing command
       line options into this file is the only way how you
       can pass project depending options to xref when in
       voked from Emacs.

       Order of options on command line is important.  Op
       tions  are  processed  in  order  in which they are
       written.


OPTIONS
       Here is the table of command  options  accepted  by
       xref.

       -p project
              At  the beginning of the execution, read and
              process options from the section project  of
              the  .xrefrc configuration file. This option
              is used to abstract  from  concrete  options
              and  file names when using xref from command
              line and from several IDEs.  For more  info,
              see the .xrefrc file documentation.

       -r     This  option  is  default now, so you do not
              need to enter it.  It causes that if  a  di
              rectory  is entered as infile then all files
              from the directory having the suffix '.c' or
              '.java'  are processed (note that it is use
              less to process the '.h'  suffixes  as  they
              are processed when included by a '.c' file).
              Subdirectories  are  recursively   searched.
              This option is obsolete now.

       --r    Do not process directories recursively. This
              is inverse option to -r option.

       -prune paths
              When recursively searching for  input  files
              do  not  enter  into  directories  in paths.
              Paths can be either a simple name, an  abso
              lute  path,  or a ':' (';' under MS-Windows)
              separated list of both. For  example  -prune
              CVS:/project/backup will forbids scanning of
              the directory /project/backup as well as all
              directories named CVS.

       -I dir Add  the directory dir to the end of list of
              directories inspected when  looking  for  an
              include  file.   If  specified more than one
              `-I' option, the directories are scanned  in
              left-to-right  order.  If  the  directory is
              specified using relative path, it is consid
              ered  relative  to the currently parsed file
              directory.

       -Dname  Predefine name as a macro, with  definition
              `1'.

       -Dname=definition
                Predefine name as a macro, with definition
              definition.

       -resetIncludeDirs
              This option removes all directories from in
              clude  directory list (including the default
              include  directories   like   /usr/include).
              This option should be used before any -I op
              tion.

       -cacheincludes
              This option causes that xref task will  keep
              readed  include  files  in  memory and reuse
              them when processing next files.   This  can
              improve  time  performance  when many source
              files are using common header  files.  Espe
              cially  if  those header files are read over
              network or from a slow drive.  It  will  in
              crease space requirements, however.

       -jdkclasspath paths
              This option defines path to standard runtime
              library (rt.jar) of your Java  installation.
              If  you are using JDK from Sun Microsystems,
              then xref task should be able to infer  this
              path  from  PATH  and  JAVA_HOME environment
              variables. Otherwise you will need to speci
              fy it explicitly using -jdkclasspath option.
              The syntax of paths is the same as  for  the
              -classpath  option.  For example you can use
              the         '-jdkclasspath          /usr/lo
              cal/jdk1.2.2/jre/lib/rt.jar'   settting  for
              most Java 1.2 installations.

       -classpath paths
              This option specifies the classpath used for
              finding  Java  .class  files.   This  option
              overrides the value of the environment vari
              able  CLASSPATH.   See  also the '-jdkclass
              path' and '-sourcepath' option.

       -sourcepath paths
              This option specifies paths where sources of
              Java packages and classes are searched. This
              option overrides the value of  the  environ
              ment  variable  SOURCEPATH.   If not present
              the current classpath is  used  as  default.
              The  'sourcepath'  value is used for finding
              source files in the same way as  'classpath'
              is  used  for finding .class compiled files.
              When loading a class having both source  and
              class  available then the time of last modi
              fication of both files is examined  and  the
              class is loaded from the newer file.

       -javadocpath=<path>
              Specifies  paths where Javadoc documentation
              is stored  in  local  file  system.  Several
              paths  can  be  specified, the syntax is the
              same as for classpath  value.  When  looking
              for a javadoc documentation, xref will first
              search files on paths specified by -javadoc
              path,  if not found and the package documen
              tation is available  (-javadocavailable  op
              tion)  the  URL  specified by -javadocurl is
              taken.  See also -javadocurl, -javadocavail
              able and -htmlgenjavadoclink options.

       -packages
              This  option  allows  to enter package names
              instead of input file names on command line.

       -source <version>
              Specifies  version  of Java in which sources
              are written. Currently available values are:
              "1.3", "1.4" and "auto". Version "auto" will
              cause that xref determines Java version  au
              tomatically  from Java runtime library. Ver
              sion "1.4" means that  'assert'  command  is
              allowed and 'assert' string is considered as
              keyword, so you can't  have  any  method  or
              variable  of  this  name.  Default  value is
              "1.3".

       -java1.4
              This option is  obsolete,  use  -source  in
              stead.  With this option sources are consid
              ered to be written in Java version  1.4  (or
              higher).

       -refs file
              This  option  specifies  the  file where the
              cross-references   are   stored.   If    the
              -refnum=n  option  is  present then the file
              indicates the directory  where  cross-refer
              ence files are stored.

       -refnum=<number>
              This  option specifies how many cross refer
              ence files will be generated.  When <number>
              ==  1, the name specified by the '-refs' op
              tion is directly the name of the cross  ref
              erence  file.   When  <number>  > 1 then the
              name specified by the '-refs' option is  in
              terpreted as directory where cross reference
              files are stored.  You  should  specify  the
              <number>  proportionally to the size of your
              project.  Do not forget to  delete  the  old
              cross-reference   file  if  you  change  the
              -refnum from 1 to a bigger value.

       -refalphahash
              Split references into 28 files depending  on
              the  first letter of the symbol. This option
              is useful when generating HTML form, because
              it  makes  easy to find cross references for
              given symbol name.  This option excludes us
              ing of the -refnum option.

       -refalpha2hash
              Split  references into 28*28 files depending
              on the first two letters of the symbol. This
              option  is useful when generating HTML form,
              because it makes easy to find  cross  refer
              ences  for  given  symbol name.  This option
              excludes using of the -refnum option.

       -exactpositionresolve
              This option controls how symbols  which  are
              local  to  a  compilation  unit, but usually
              used in several files, are linked  together.
              This   concerns   C  language  symbols  like
              macros, structures and their  records,  etc.
              Such  symbols  have  no link names passed to
              linker (like global functions  have).   This
              creates  a  problem  how 'xref' can link to
              gether (for example) structures of the  same
              name  used  in  different compilation units.
              If the -exactpositionresolve option is  pre
              sent  then such symbols are considered to be
              equals if their definitions  come  from  the
              same header file and they are defined at the
              same position in the file (in other words if
              this  is  a  single definition in the source
              code). Otherwise two symbols are linked  to
              gether  when  they  have the same name.  The
              '-exactpositionresolve'  is  very   powerful
              feature because it allows perfect resolution
              of browsed symbol and allows you  to  safely
              rename one of two symbols if a name conflict
              occurs.  However  this  option  also  causes
              that you will need to update cross reference
              file after each  modification  of  a  header
              file (as the cross-reference file stores in
              formation about position of the macro  defi
              nition).   Updating  may  be too annoying in
              normal use when you often edit header files.
              In  general, this option is recommended when
              browsing source code which is not under  ac
              tive development.


       -noincluderefresh
              This  is  a particular option importing only
              when xref task is used from Emacs. It causes
              that  xref task does not update include ref
              erences when used by an  Emacs  macro.  This
              avoids  memory overflow for huge projects or
              for projects  including  huge  header  files
              (for  example  when including Microsoft win
              dows API headers).


       -update
              This option represents standard way  of  how
              to  keep cross-reference file up to date. It
              causes that modification time of  all  input
              files  as well as those listed in the exist
              ing cross-reference file are checked and on
              ly those having newer modification time than
              existing cross-reference file are  scheduled
              to  be  processed.  Also all files which in
              cludes (by Cpp  pre-processor)  those  files
              are scheduled to be processed.

       -fastupdate
              The same as -update with the difference that
              files which include modified files  are  not
              scheduled  to  be  processed. Unless you are
              using  also  '-exactpositionresolve'  option
              this  is  enough  for  most references to be
              correctly updated.

       -fastupdate
              Fast update, force update  of  input  files.
              This  option is like the -update option with
              the difference that input files  entered  on
              command  line  are  always reparsed (not de
              pending on their modification time).

       -set <name> <value>
              The xref task provide a  simple  environment
              management.  The  -set option associates the
              string <name> to  the  string  <value>.  The
              value  can be then accessed by enclosing the
              name in ${ }.

              If an option contains name of previously de
              fined  variable  enclosed  in ${ and }, then
              the name (together with  encolsing  ${})  is
              replaced  by  the corresponding value. Vari
              ables can be hence used  to  abbreviate  op
              tions  or to predefine repeated parts of op
              tions.  Following predefined  variables  can
              be  used  in  order to introduce problematic
              characters into options: 'nl'  for  newline;
              'pc'  for  percent; 'dl' for dollar and 'dq'
              for  double-quotes.  Also  all   environment
              variables  taken from operating system (like
              PATH, HOME, ...) are 'inherited' and can  be
              used  when  enclosed  in  ${  }. For example
              ${PATH} string will be replaced by the value
              of PATH environment variable.

              Another  usage  of  -set option is to define
              project  depending  values  used  by   Emacs
              macros. Emacs can retrieve value of an envi
              ronmnet variable by  sending  '-get  <name>'
              request  to  xref  task.  Emacs is currently
              using following variables to get project de
              pending   settings:   "compilefile",   "com
              piledir", "compileproject", "run1",  "run2",
              ...  ,  "run5",  "runthis"  and "run". Those
              variables are used by 'Emacs IDE' macros  to
              retrieve  commands  for compilation and run
              ning of project program.  For example an op
              tion:   -set   run   "echo   will   run  now
              ${nl}a.out" will define run command to print
              'will  run  now'  message  and  then execute
              a.out command. When a command string is  en
              closed  in  quotas  it  can  contain newline
              characters to separate sequence of commands.
              For more info about compile and run commands
              see on-line Emacs help of the  corresponding
              Xrefactory macros.

       -brief The  output  of cross referencing will be in
              compact form, still  readable  by  xref  but
              rather  difficult for human reader. This op
              tion is default now.

       -nobrief
              The output of cross referencing will contain
              "comment" records for human readers.

       -no_enum
              Don't cross reference enumerators.

       -no_mac
              Don't cross reference macros.

       -no_type
              Don't cross-reference user defined types.

       -no_str
              Don't cross reference structure records.

       -no_local
              Don't cross reference function arguments and
              local variables.

       -no_cfrefs
              Don't get cross references from class files.
              This can decrease the size of your Tag file.
              However, because  informations  about  class
              hierarchy  are taken mainly from class files
              this option may causes that showed class hi
              erarchies will be incomplete.

       -html  Causes  xref to not produce the cross refer
              ence file. Instead  it  reads  a  previously
              generated cross reference file, then it pro
              ceeds input files creating  browsable  files
              in the HTML format.

       -htmlroot=dir
              Write output HTML files into directory hier
              archy starting by the dir.  This  option  is
              meaningful  only with combination with -html
              option.

       -d dir Equivalent to -htmlroot=dir.

       -htmltab=number
              When generating HTML files, set the  tabula
              tor to number.

       -htmllinenums
              When  converting source files into HTML for
              mat  generate  line  numbers  before  source
              code.

       -htmlnocolors
              When  converting source files into HTML for
              mat do not generate  color  highlighting  of
              keywords,  commentaries and preprocessor di
              rectives.

       -htmlgxlist
              When converting source files into HTML  for
              mat  generate  lists  of all usages for each
              global symbol.

       -htmllxlist
              When converting source files into HTML  for
              mat  generate  lists  of all usages for each
              local symbol.

       -htmldirectx
              When converting source files into HTML  for
              mat,  link  the  first character of a symbol
              directly to its cross references.

       -htmlfunseparate
              Causes that HTML files will contain horizon
              tal bar separating function definitions.

       -htmlcutpath=<path>
              This  option  causes  that  the output files
              from the path directory are not stored  with
              full  path  name  under -htmlroot directory.
              Rather the path is cut from  the  full  file
              name.  Xref  accepts  several '-htmlcutpath'
              options. On MS-DOS (QNX)  system,  the  path
              should be an absolute path but without drive
              (node) specification.

       -htmlcutcwd
              equals '-htmlcutpath=${CWD}' cutting current
              working directory path from html paths.

       -htmlcutsourcepaths
              cut  also  all  Java source paths defined by
              SOURCEPATH environment variable or by -sour
              cepath option.

       -htmlcutsuffix
              Cut language suffix from generated html file
              names. With this option xref  will  generate
              files  Class.html instead of Class.java.html
              (or file.html instead of file.c.html  for  C
              language).

       -htmllinenumlabel=<label>
              Set  the  label generated before line number
              in html documents. For example -htmllinenum
              label=line will generate line<n> labels com
              patible with links generated by javadoc ver
              sion 1.4.

       -htmllinkcolor=<color>
              This  option  specifies  the  color in which
              links of the HTML document will appear.  For
              example   '-htmllinkcolor=black'  or  '-htm
              llinkcolor=#000000' causes that  links  will
              be black.

       -htmllinenumcolor=<color>
              This option specifies the color of line num
              bers for generated HTML.  For example '-htm
              llinenumcolor=black'   or  '-htmllinenumcol
              or=#000000' causes that  line  numbers  will
              always  be  black. This option is meaningful
              only in combination with  -htmllinenums  op
              tion.

       -htmlnounderline
              This  option  causes  that links in the HTML
              document will not  be  underlined  (if  your
              browser support styles).

       -htmlgenjavadoclinks
              When   generating  html  generate  links  to
              Javadoc documentation  for  symbols  without
              definition reference.

       -encoding=<type>
              This option specifies international encoding
              of input files. Available values for  <type>
              are  'default',  'european',  'euc', 'sjis',
              'utf',  'utf-8',  'utf-16',  'utf-16le'  and
              'utf-16be'.  The  'default' value results in
              standard ASCII (and 'utf-8') characters.  If
              your files contain, for example, 8-bit euro
              pean characters,  then  you  should  include
              -encoding=european  into  your  project set
              ting.

       -javadocurl=<url> -htmljavadocpath=<url>
              Specifies  URL  where   existing   non-local
              Javadoc  documentation  is stored.  Both op
              tions are equivalent,  the  -htmljavadocpath
              is     obsolete.      The     default     is
              "-javadocurl=http://ja
              va.sun.com/j2se/1.3/docs/api".   It  is sup
              posed to contain  Javadoc  documentation  of
              packages  for  which  you do not have source
              code nor local  Javadoc  documentation,  but
              the documentation is available on the Inter
              net.  See also -javadocpath,  -javadocavail
              able and -htmlgenjavadoclink options.

       -javadocavailable=<packs>        -htmljavadocavail
       able=<packs>
              Both  options  are  equivalent,  the  -html
              javadocavailable is  obsolete.   The  option
              specifies packages having Javadoc documenta
              tion placed on  the  URL  specified  by  the
              -javadocurl option.  The <packs> string is a
              list of packages separated by ':' sign.  For
              example correct setting for standard jdk is:
              "-javadocavailable=java.applet:java.awt:ja
              va.beans:java.io:java.lang:java.math:ja
              va.net:java.rmi:java.security:java.sql:ja
              va.text:java.util:javax.accessibili
              ty:javax.swing:org.omg.CORBA:org.omg.CosNam
              ing".   See  also  -javadocpath, -javadocurl
              and -htmlgenjavadoclink options.

       -htmlzip=<command>
              This option causes that the command  command
              is  called  after  having  created  any HTML
              file. The character '!' included in the com
              mand  has special meaning and is replaced by
              the name of the last  generated  HTML  file.
              For  example  "-htmlzip=gzip  -f  !"  option
              causes that all generated HTML files will be
              zipped. See also '-htmllinksuffix' option.

       -htmllinksuffix=<suf>
              This option causes that whenever a hypertext
              link to a file xxx should be generated  then
              in  reality  a  link  to the file xxx.suf is
              generated. This option is meaningful  mainly
              with  the '-htmlzip' option. For example the
              combination  "-htmlzip=gzip  -f   !"   -htm
              llinksuffix=.gz  causes  that  all generated
              HTML files will be compressed and the  links
              are  correctly generated to those compressed
              files.

       -include file (or -stdop file)
              This option causes that the file  `file'  is
              read  and  scanned for further options. When
              used in an .xrefrc  file  this  options  in
              cludes options defined in file.  However, if
              the included file  is  modified  while  xref
              task is running then xref is unable to auto
              matically reload new options.   If  you  use
              -include (-stdop) option, and you modify in
              cluded file,  you  will  need  to  kill  and
              restart  xref  server  task  in  order  that
              changes take effect.

       -no_stdop
              This option forbids the search  of  standard
              option files '.xrefrc' and 'Xref.opt'.

       -mf<n> This  option  sets  the  memory  factor  for
              cross-references. The larger is  the  memory
              factor, the larger is the memory reserved to
              store cross-references and so xref does  not
              need to swap references on disk so frequent
              ly. The default value of n is 1. For example
              the  '-mf10'  option  causes that the memory
              used for cross-references will be  increased
              by the factor of 10. This option can be used
              only as command line option. If you  use  it
              inside  the ~/.xrefrc file it has no effect.

       -pass<n>
              Strictly speaking this is not  xref  option.
              It is used in the .xrefrc configuration file
              to describe how to process source  files  in
              multiple passes.  Multiple passes are neces
              sary if you need to process your  C  sources
              for several initial macro settings. For more
              informations  about  this  option  read  the
              'xrefrc' manual page.

       -keep_old
              This option is obsolete. It is kept for com
              patibility reasons only.  It is  recommended
              to use multiple passes options of the '.xre
              frc' file instead.  The  '-keep_old'  option
              causes  that the output of cross-referencing
              is added to  existing  references  from  the
              file  specified by the -refs option. All old
              references of the reference file are kept.

       -no_cpp_comment
              When scanning input files, do  not  consider
              the  string  `//'  as beginning of a comment
              ended by end of line.

       -csuffixes=<suffixes>
              This option defines list of suffixes  (sepa
              rated  by  ':'  character under Unix and ';'
              under MS-Windows) for C source files.  Files
              with  those  suffixes  will be inserted into
              Tag file  and  parsed  with  Xrefactory's  C
              parser. Suffixes should not start by the '.'
              dot character which is considered as  suffix
              separator automatically. For example suffix
              es "c:tc" mean that files ending by ".c"  or
              ".tc"  strings  are  considered  as  C input
              files.

       -javasuffixes=<suffixes>
              This option defines list of suffixes  (sepa
              rated  by  ':'  character under Unix and ';'
              under MS-Windows)  for  Java  source  files.
              Files  with  those suffixes will be inserted
              into Tag file and parsed  with  Xrefactory's
              Java  parser.  Suffixes  should not start by
              the '.'  dot character which is consider  as
              suffix  separator  automatically.  For exam
              ple, the default value under  MS-Windows  is
              -javasuffixes=java;JAV.

       -filescasesensitive -filescaseunsensitive
              This option controls whether xref is consid
              ering two file names differing only in cases
              as  the  same  file  or not. By default file
              names are considered as case sensitive. Set
              ting  names to be case unsensitive may avoid
              confusion in C #include directives under MS-
              Windows system.

       -errors
              Report all error messages.

       -noconversion -crconversion -crlfconversion
              Options  controling  end  of  line character
              conversions. By default  xref  automatically
              determines  which  character sequence should
              be considered as end-of-line. Those  options
              force xref to consider respectively linefeed
              (-noconversion), return (-crconversion),  or
              return  followed  by  linefeed (-crlfconver
              sion) as beginning of next line. Those cases
              corresponds respectively to Unix, Mac OS and
              Windows systems.

       -debug Produce debugging output  tracing  execution
              and  determining  possible source of errors.
              This option is very usefull  if  some  reac
              tions  of xref are inadequate on some input.
              In this case you can run xref with given in
              put  file and -debug option. In the produced
              output you can search for error messages and
              discover the origin of problems.


MORE INFO
       http://www.xref-tech.com

SEE ALSO
       xrefrc(5),



                                                          XREF(1)
