xref(1)
NAME
xref − Cross-reference analysis tool
SYNOPSIS
xref [ −info ] [ −lint ] [ −A ] [ −s name ] [ −N ] [ −a name ] [ −o filename ] [ files ]
DESCRIPTION
The xref(1) tool is a general purpose cross-reference listing generator and interface analysis tool. Currently only the hf77(1) compiler is supported.
Cross-reference listings are not generated directly by the compiler. Rather, the compiler generates a source description file or SDF containing detailed information for specific source file features. The xref tool constructs from the SDF an internal database representing the source. An SDF for a single source file contains all information necessary for xref to generate a cross-reference listing describing source entities’ qualities and occurrences. Multiple SDFs are accepted, allowing comprehensive cross-reference listings and verification of user subprogram and global block interfaces even if the definition and references are spread across many source files. The contents of an SDF are internally order-dependent but self-contained so that multiple SDFs may be concatenated into a single file for simplicity.
With the -xref,interface option the hf77 compiler will generate interface descriptions rather than a detailed SDF. An interface description describes the call interface for a subroutine, function, or entry point and is conceptually similar to a C function prototype. When verifying interfaces, xref will accept an interface description in place of a full subprogram description. If both are present for a particular subprogram the full description is used. An interface description may describe an external subprogram such as a library routine, say, which may be called by but is not compiled with a program. The file /usr/lib/libf77.x contains interface descriptions for the external routines defined in the libraries released with the Hf77 Fortran compiler: libhF77.a, libhI77.a and libhU77.a.
An unnamed main program has the name "∗MAIN∗", unnamed BLOCKDATA "∗BLOCKDATA∗", and the blank COMMON block "∗BLANK_COMMON∗".
The hf77 compiler driver provides options to generate SDF files and xref output in one step. See the hf77(1) man page for details.
The xref tool generates output according to the following options:
−info (Default) Create cross-reference listing. Among the FORTRAN program entities displayed are subprograms, entries, common blocks, datapools, variables, equivalence classes, labels, and exit points. Source files are listed in the order encountered, subprograms are listed according to their order within each source file, with subprogram alphanumerics displayed sorted by name, followed by equivalence classes, subprogram labels, and subprogram exit points.
−lint Verify interfaces. This checks subprogram definition and invocation argument lists, common block declarations, and datapool declarations and references for inconsistencies.
Further options recognized by xref:
−A (Default) Include all subprograms in −info and −lint reports. The −s option may be used to subtract subprograms from the working set.
−s name Subtract subprogram name from the set of subprograms considered for −info and −lint reports. The −A option is implied if none was provided. Multiple −s options may be used.
−N Exclude all subprograms in −info and −lint reports. The −a option may be used to add subprograms to the working set.
−a name Add subprogram name to the set of subprograms considered for −info and −list reports. The −N option is implied if none was provided. Multiple −a options may be used.
−lower Translate all names to lowercase. Normally FORTRAN names are printed in uppercase.
−o filename
Generate output to filename rather than stdout.
files Source description files. If none are provided on the command line, xref reads input from stdin.
FILES
file.x default xref SDF name for source file file.f
/usr/bin/xref xref(1) executable
/usr/lib/libf77.x interface descriptions for /usr/lib/libh{F,I,U}77.a
SEE ALSO
DIAGNOSTICS
Error messages are intended to be self-explanatory.
If xref issues an "Internal Error" message, report the error to the Harris Software Support Center (800-245-6453, hours Monday through Friday, 8 a.m. to 7 p.m. EST.)
FORTHCOMING FEATURES
A static call graph report will be available.
Equivalence class and common block cross-reference entries will include members’ offsets within the class or block.
Source file entries will include number of total lines, comment lines, etc.
Array and character variable entries will include dimension and size information.
Use of INCLUDE files will be more thoroughly tracked. Currently, all information gathered from an included file is given the line number of the INCLUDE statement, with no further indication of its origin.
BUGS
xref may not note all appearances of a name within non-executable statements, that is, within declarations, if multiple statements are used to describe type, dimension, etc. However, xref will always indicate the first appearance of a name, and all name references within executable statements.
Label references within I/O statements may not be reported.
Line numbers may occasionally be incorrect by a few lines. A line number may refer to a blank or comment line; the nearest preceding executable statement is the correct line. The line number of multi-line statements is the line number of the final continuation line.
If an entire common block is declared volatile, the member variables show the volatile attribute but the common block name itself does not indicate such.
For common blocks the SAVE attribute is not reported.
Equivalence classes are always reported with a ’0’ line number.
Interface verification may report datatype mismatch errors for subroutines passed as actual arguments; so long as the argument is a subroutine (not a function) such errors may be safely ignored.
Intrinsic routines are not included in the interface verification report.