The f77 compiler's -Xlistx options provide a valuable way to analyze a source program for inconsistencies and possible runtime problems. The analysis performed by the compiler is global, across subprograms.
-Xlistx reports errors in alignment, agreement in number and type for subprogram arguments, common block, parameter, and various other kinds of errors.
-Xlistx also can be used to make detailed source code listings and cross-reference tables.
The f90 compiler provides only a subset of the --Xlist options described here. A conventional cross-reference map is produced, but complete global program checking is not performed.
Global program checking (GPC), invoked by the -Xlistx option, does the following:
Enforces type-checking rules of Fortran more stringently than usual, especially between separately compiled routines
Enforces some portability restrictions needed to move programs between different machines or operating systems
Detects legal constructions that nevertheless might be suboptimal or error-prone
Reveals other potential bugs and obscurities
In particular, global checking reports problems such as:
Interface problems
Conflicts in number and type of dummy and actual arguments
Wrong types of function values
Possible conflicts due to data type mismatches in common blocks between different subprograms
Usage problems
Function used as a subroutine or subroutine used as a function
Declared but unused functions, subroutines, variables, and labels
Referenced but not declared functions, subroutines, variables, and labels
Usage of unset variables
Unreachable statements
Implicit type variables
Inconsistency of the named common block lengths, names, and layouts
The -Xlist option on the command line invokes the compiler's global program analyzer. There are a number of -Xlistx suboptions, as described in the sections that follow.
Example: Compile three files for basic global program checking:
demo% f77 -Xlist any1.f any2.f any3.f
In the preceding example, the compiler:
Produces output listings in the file any1.lst
Compiles and links the program if there are no errors
Normally, output listings produced by -Xlistx are written to a file. To display directly to the screen, use -Xlisto to write the output file to /dev/tty.
demo% f77 -Xlisto /dev/tty any1.f
The -Xlist option provides a combination of features available for output. With no other -Xlist options, you get the following by default:
The listing file name is taken from the first input source or object file that appears, with the extension replaced by .lst
A line-numbered source listing
Error messages (embedded in listing) for inconsistencies across routines
Cross-reference table of the identifiers
Pagination at 66 lines per page and 79 columns per line
No call graph
No expansion of include files
The checking process recognizes all the files in the compiler command line that end in .f, .f90, .for, .F, or .o. The .o files supply the process with information regarding only global names, such as subroutine and function names.
Programs compiled with --Xlist options have their analysis data built into the binary files automatically. This enables global program checking over programs in libraries.
Alternatively, the compiler will save individual source file analysis results into files with a .fln suffix if the -Xlistflndir option is also specified. dir indicates the directory to receive these files.
demo% f77 -Xlistfln/tmp *.f
Here is a listing of the Repeat.f source code used in the following examples:
demo% cat Repeat.f PROGRAM repeat pn1 = REAL( LOC ( rp1 ) ) CALL subr1 ( pn1 ) CALL nwfrk ( pn1 ) PRINT *, pn1 END ! PROGRAM repeat SUBROUTINE subr1 ( x ) IF ( x .GT. 1.0 ) THEN CALL subr1 ( x * 0.5 ) END IF END SUBROUTINE nwfrk( ix ) EXTERNAL fork INTEGER prnok, fork PRINT *, prnok ( ix ), fork ( ) END INTEGER FUNCTION prnok ( x ) prnok = INT ( x ) + LOC(x) END SUBROUTINE unreach_sub() CALL sleep(1) END
Example: Use -XlistE to show errors and warnings:
demo% f77 -XlistE -silent Repeat.f demo% cat Repeat.lst FILE "Repeat.f" program repeat 4 CALL nwfrk ( pn1 ) ^ **** ERR #418: argument "pn1" is real, but dummy argument is integer*4 See: "Repeat.f" line #14 4 CALL nwfrk ( pn1 ) ^ **** ERR #317: variable "pn1" referenced as integer*4 across repeat/nwfrk//prnok in line #21 but set as real by repeat in line #2 subroutine subr1 10 CALL subr1 ( x * 0.5 ) ^ **** WAR #348: recursive call for "subr1". See dynamic calls: "Repeat.f" line #3 subroutine nwfrk 17 PRINT *, prnok ( ix ), fork ( ) ^ **** ERR #418: argument "ix" is integer*4, but dummy argument is real See: "Repeat.f" line #20 subroutine unreach_sub 24 SUBROUTINE unreach_sub() ^ **** WAR #338: subroutine "unreach_sub" isn't called from program Date: Wed Feb 24 10:40:32 1999 Files: 2 (Sources: 1; libraries: 1) Lines: 26 (Sources: 26; Library subprograms:2) Routines: 5 (MAIN: 1; Subroutines: 3; Functions: 1) Messages: 5 (Errors: 3; Warnings: 2) demo%
Compiling the same program with --Xlist also produces a cross-reference table on standard output:
C R O S S R E F E R E N C E T A B L E Source file: Repeat.f Legend: D Definition/Declaration U Simple use M Modified occurrence A Actual argument C Subroutine/Function call I Initialization: DATA or extended declaration E Occurrence in EQUIVALENCE N Occurrence in NAMELIST P R O G R A M F O R M Program ------- repeat <repeat> D 1:D Functions and Subroutines ------------------------- fork int*4 <nwfrk> DC 15:D 16:D 17:C int intrinsic <prnok> C 21:C loc intrinsic <repeat> C 2:C <prnok> C 21:C nwfrk <repeat> C 4:C <nwfrk> D 14:D prnok int*4 <nwfrk> DC 16:D 17:C <prnok> DM 20:D 21:M real intrinsic <repeat> C 2:C sleep <unreach_sub> C 25:C subr1 <repeat> C 3:C <subr1> DC 8:D 10:C unreach_sub <unreach_sub> D 24:D
Output from compiling f77 -Xlist Repeat.f (Continued)
Variables and Arrays -------------------- ix int*4 dummy <nwfrk> DA 14:D 17:A pn1 real*4 <repeat> UMA 2:M 3:A 4:A 5:U rp1 real*4 <repeat> A 2:A x real*4 dummy <subr1> DU 8:D 9:U 10:U <prnok> DUA 20:D 21:A 21:U ---------------------------------------------------------------------- Date: Tue Feb 22 13:15:39 1995 Files: 2 (Sources: 1; libraries: 1) Lines: 26 (Sources: 26; Library subprograms:2) Routines: 5 (MAIN: 1; Subroutines: 3; Functions: 1) Messages: 5 (Errors: 3; Warnings: 2) demo%
In the cross-reference table in the preceding example:
ix is a 4-byte integer:
Used as an argument in the routine nwfrk
At line 14, used as a declaration of argument
At line 17, used as an actual argument
pn1 is a 4-byte real in the routine repeat:
At line 2, modified
At line 3, argument
At line 4, argument
At line 5, used
rp1 is a 4-byte real in the routine, repeat. At line 2, it is an argument.
x is a 4-byte real in the routines subr1 and prnok:
In subr1, at line 8, defined; used at lines 9 and 10
In prnok, at line 20, defined; at line 21, used as an argument
The basic global cross-checking option is -Xlist with no suboption. It is a combination of suboptions, each of which could have been specified separately.
The following sections describe options for producing the listing, errors, and cross-reference table. Multiple suboptions may appear on the command line.
Add suboptions according to the following rules:
Append the suboption to -Xlist.
Put no space between the -Xlist and the suboption.
Use only one suboption per -Xlist.
Combine suboptions according to the following rules:
The most general option is -Xlist (listing, errors, cross-reference table).
Specific features can be combined using -Xlistc, -XlistE, -XlistL, or -XlistX.
Other suboptions specify further details.
Example: Each of these two command lines performs the same task:
demo% f77 -Xlistc -Xlist any.f
demo% f77 -Xlistc any.f
The following table shows the reports generated by these basic --Xlist suboptions alone:
Table 5-1 Xlist Suboptions
Generated Report |
Option |
---|---|
Errors, listing, cross-reference |
-Xlist |
Errors only |
-XlistE |
Errors and source listing only |
-XlistL |
Errors and cross-reference table only |
-XlistX |
Errors and call graph only |
-Xlistc |
The following table summarizes all -Xlist suboptions.
Table 5-2 Summary of --Xlist Suboptions
Option |
Action |
-Xlist (no suboption) |
Shows errors, listing, and cross-reference table |
-Xlistc |
Shows call graphs and errors (f77 only) |
-XlistE |
Shows errors |
-Xlisterr[nnn] |
Suppresses error nnn in the verification report |
-Xlistf |
Produces fast output (f77 only) |
-Xlistflndir |
Puts the .fln files in dir (f77 only) |
-Xlisth |
Shows errors from cross-checking stop compilation (f77 only) |
-XlistI |
Lists and cross-checks include files |
-XlistL |
Shows the listing and errors |
-Xlistln |
Sets page breaks |
-Xlisto name |
Renames the -Xlist output report file |
-Xlists |
Suppresses unreferenced symbols from cross-reference (f77 only) |
-Xlistvn |
Sets checking "strictness" level (f77 only) |
-Xlistw[nnn] |
Sets the width of output lines |
-Xlistwar[nnn] |
Suppresses warning nnn in the report |
-XlistX |
Shows just the cross-reference table and errors |
This section describes the --Xlist suboptions. As noted, some are only available with f77.
Used alone, --Xlistc does not show a listing or cross-reference. It produces the call graph in a tree form, using printable characters. If some subroutines are not called from MAIN, more than one graph is shown. Each BLOCKDATA is printed separately with no connection to MAIN.
The default is not to show the call graph.
Used alone, --XlistE shows only cross-routine errors and does not show a listing or a cross-reference.
Use --Xlisterr to suppress a numbered error message from the listing or cross-reference.
For example: -Xlisterr338 suppresses error message 338. If nnn is not specified, all error messages are suppressed. To suppress additional specific errors, use this option repeatedly.
Use --Xlistf to produce source file listings and a cross-checking report and to verify sources, but without generating object files.
The default without this option is to generate object files.
Use --Xlistfln to specify the directory to receive .fln source analysis files. The directory specified (dir) must already exist. The default is to include the source analysis information directly within the object .o files (and not generate .fln files).
With --Xlisth, compilation stops if errors are detected while cross-checking the program. In this case, the report is redirected to stdout instead of the *.lst file.
If -XlistI is the only suboption used, include files are shown or scanned along with the standard -Xlist output (line numbered listing, error messages, and a cross-reference table).
Listing--If the listing is not suppressed, then the include files are listed in place. Files are listed as often as they are included. The files are:
Source files
#include files
INCLUDE files
Cross-Reference Table--If the cross reference table is not suppressed, the following files are all scanned while the cross reference table is generated:
Source files
#include files
INCLUDE files
The default is not to show include files.
Use --XlistL to produce only a listing and a list of cross routine errors. This suboption by itself does not show a cross reference table. The default is to show the listing and cross reference table.
Use --Xlistl to set the page length to something other than the default page size. For example, -Xlistl45 sets the page length to 45 lines. The default is 66.
With n=0 (-Xlistl0) this option shows listings and cross-references with no page breaks for easier on-screen viewing.
Use --Xlisto to rename the generated report output file. (A space between o and name is required.) With --Xlisto name, the output is to name.lst .
To display directly to the screen, use the command: -Xlisto /dev/tty
Use --Xlists to suppress from the cross reference table any identifiers defined in the include files but not referenced in the source files.
This suboption has no effect if the suboption -XlistI is used.
The default is not to show the occurrences in #include or INCLUDE files.
n is 1,2, 3, or 4. The default is 2 (-Xlistv2):
-Xlistv1
Shows the cross-checked information of all names in summary form only, with no line numbers. This is the lowest level of checking strictness--syntax errors only.
-Xlistv2
Shows cross-checked information with summaries and line numbers. This is the default level of checking strictness and includes argument inconsistency errors and variable usage errors.
-Xlistv3
Shows cross-checking with summaries, line numbers, and common block maps. This is a high level of checking strictness and includes errors caused by incorrect usage of data types in common blocks in different subprograms.
-Xlistv4
Shows cross-checking with summaries, line numbers, common block maps, and equivalence block maps. This is the strictest level of checking with maximum error detection.
Use --Xlistw to set the width of the output line. For example, -Xlistw132 sets the page width to 132 columns. The default is 79.
Use --Xlistwar to suppress a specific warning message from the output reports. If nnn is not specified, then all warning messages are suppressed from printing. For example, -Xlistwar338 suppresses warning message number 338. To suppress more than one, but not all warnings, use this option repeatedly.
--XlistX produces a cross reference table and cross routine error list but no source listing.
Example: Use -Xlistwarnnn to suppress two warnings from a preceding example:
demo% f77 -Xlistwar338 -Xlistwar348 -XlistE -silent Repeat.f demo% cat Repeat.lst FILE "Repeat.f" program repeat 4 CALL nwfrk ( pn1 ) ^ **** ERR #418: argument "pn1" is real, but dummy argument is integer*4 See: "Repeat.f" line #14 4 CALL nwfrk ( pn1 ) ^ **** ERR #317: variable "pn1" referenced as integer*4 across repeat/nwfrk//prnok in line #21 but set as real by repeat in line #2 subroutine nwfrk 17 PRINT *, prnok ( ix ), fork ( ) ^ **** ERR #418: argument "ix" is integer*4, but dummy argument is real See: "Repeat.f" line #20 Date: Wed Feb 24 10:40:32 1999 Files: 2 (Sources: 1; libraries: 1) Lines: 26 (Sources: 26; Library subprograms:2) Routines: 5 (MAIN: 1; Subroutines: 3; Functions: 1) Messages: 5 (Errors: 3; Warnings: 2) demo%
Example: Explain a message and find a type mismatch in program ShoGetc.f:
demo% cat ShoGetc.f CHARACTER*1 c i = getc(c) END demo% f77 -silent ShoGetc.f Compile program demo% a.out Program waits for input... Z Type "Z" on keyboard. This causes run-time message. Why? Note: IEEE floating-point exception flags raised: Invalid Operation; See the Numerical Computation Guide, ieee_flags(3M) demo% f77 -XlistE -silent ShoGetc.f Compile with Global Program Checking demo% cat ShoGetc.lst and view listing FILE "ShoGetc.f" program MAIN 2 i = getc(c) ^ **** WAR #320: variable "i" set but never referenced 2 i = getc(c) ^ **** ERR #412: function "getc" used as real but declared as integer*4 Here is the error - function must be declared INTEGER. 2 i = getc(c) ^ **** WAR #320: variable "c" set but never referenced demo% cat ShoGetc.f Modify program to declare getc INTEGER and run again. CHARACTER*1 c INTEGER getc i = getc(c) END demo% f77 -silent ShoGetc.f demo% a.out Z Type "Z" on keyboard demo% Now no error.