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 positions of declarations, definition and all usages.  Out-       put is written to the file specified by the -refs option. Xref’s       cross references are destinated 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 finally all other suffixes  are  in-       terpreted as C input files.       When  invoked  with  the -html option xref  does not produce the       cross reference file. Instead it reads an existing cross  refer-       ence  file  and  then it converts 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       hierarchy specified by the -htmlroot option.WILD CHARACTERS       Following wild characters can  be  used  when  specifying  input       files:  ’*’  expands to any (possibly empty) string; ’?’ expands       to any single character and ’[...]’ pair expands to one  of  en-       closed  characters. Ranges of characters can be included between       [ and ], so for example [a-z] matches  any  lower  case  letter,       [0-9]  matches  any  digit, as it is usual in standard shell ex-       pressions. 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,  -sourcepath       and  -javadocpath  also accept wild characters. 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 standard way of passing options to xref       is configuration file named .xrefrc placed in user’s home direc-       tory.  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 invoked from Emacs.       Order of options on command line is important. Options are  pro-       cessed 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 op-              tions from the section project of the .xrefrc  configura-              tion  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 directory is entered as infile              then all files from the directory having the suffix  ’.c’              or ’.java’ are processed (note that it is useless to pro-              cess the ’.h’ suffixes as they are processed when includ-              ed  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  absolute path, or a ’:’ (’;’ under MS-Windows)              separated   list   of   both.    For    example    -prune              CVS:/project/backup will forbids scanning of the directo-              ry /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 considered 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 include directo-              ry  list  (including the default include directories like              /usr/include).  This option should be used before any  -I              option.       -cacheincludes              This  option  causes  that xref task will keep readed in-              clude files in memory and reuse them when processing next              files.   This  can  improve  time  performance  when many              source files are using common header files. Especially if              those  header  files are read over network or from a slow              drive. It will increase 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 vari-              ables. Otherwise you will need to specify  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 en-              vironment  variable  CLASSPATH.  See also the ’-jdkclass-              path’ and ’-sourcepath’ option.       -sourcepath paths              This option specifies paths where sources of  Java  pack-              ages  and classes are searched. This option overrides the              value of the environment  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 modification 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 -javadocpath, if not found and the              package documentation is available (-javadocavailable op-              tion) the URL specified by -javadocurl is taken.  See al-              so -javadocurl, -javadocavailable and -htmlgenjavadoclink              options.       -packages              This  option allows to enter package names instead of in-              put 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  ver-              sion  automatically  from  Java  runtime library. Version              "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 instead.  With this              option sources are considered to be written in Java  ver-              sion 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-reference files              are stored.       -refnum=<number>              This option specifies how many cross reference files will              be  generated.  When <number> == 1, the name specified by              the ’-refs’ option is directly the name of the cross ref-              erence  file.   When <number> > 1 then the name specified              by the ’-refs’ option is interpreted 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 generat-              ing HTML form, because it makes easy to find cross refer-              ences  for given symbol name.  This option excludes using              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              references  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  func-              tions  have).  This creates a problem how ’xref’ can link              together (for example) structures of the same  name  used              in different compilation units.  If the -exactpositionre-              solve option is present 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 ’-exactposi-              tionresolve’ 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  oc-              curs.  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 infor-              mation about position of the macro definition).  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 active de-              velopment.       -noincluderefresh              This is a particular option importing only when xref task              is used from Emacs. It causes that xref task does not up-              date include references 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 windows 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              existing cross-reference file are checked and only  those              having newer modification time than existing cross-refer-              ence file are scheduled to be processed. Also  all  files              which  includes  (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 updat-              ed.       -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              depending 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 enclos-              ing the name in ${ }.              If an option contains name of previously defined variable              enclosed  in  ${  and }, then the name (together with en-              colsing ${}) is  replaced  by  the  corresponding  value.              Variables  can  be hence used to abbreviate options or to              predefine repeated parts of  options.   Following  prede-              fined  variables  can be used in order to introduce prob-              lematic characters into options: ’nl’ for  newline;  ’pc’              for  percent; ’dl’ for dollar and ’dq’ for double-quotes.              Also all environment variables taken from operating  sys-              tem  (like  PATH,  HOME,  ...) are ’inherited’ and can be