Previous Next Contents Index Doc Set Home


Program Analysis and Debugging

5

This chapter presents a number of Sun Fortran compiler features that facilitate program analysis and debugging.

Global Program Checking (f77 Only)

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.

Note - Although a subset of -Xlist options are available with this release (1.2) of f90, a conventional cross-reference map is produced but global program checking is not performed; full checking will appear in a subsequent release of the f90 compiler.

GPC Overview

Global program checking (GPC), invoked by the -Xlistx option, does the following:

In particular, global-cross checking reports problems such as:

How to Invoke Global Program Checking

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:

Screen Output

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.

Example: Display to terminal:

demo% f77 -Xlisto /dev/tty  any1.f

Default Output Features

The -Xlist option provides a combination of features available for output. With no other -Xlist options, you get the following by default:

File Types

The checking process recognizes all the files in the compiler command line that end in .f, .f90, .for, .F, .o, or .s. The .o and .s files supply the process with information regarding global names only, such as subroutine and function names.

Analysis Files (.fln Files)

The compiler saves individual source file analysis results into files with a .fln suffix. It usually uses the source directory. You can specify an alternate directory to receive these files with the -Xlistflndir option.

demo% f77 -Xlistfln/tmp *.f

Libraries compiled with -Xlist options have their analysis files built into the binary files automatically, enabling GPC over programs that link these libraries.

Some Examples of -Xlist and Global Program Checking

Source code used in the following examples, Repeat.f: 

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 23 10:40:32 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%







 










Compiling the same program with -Xlist also produces a cross-reference table:



Output File: f77 -Xlist Repeat.f  







         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 file: 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:





 Suboptions for Global Checking Across Routines




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.



Described below are options for producing the listing, errors, and cross- reference table. Multiple suboptions may appear on the command line.




 Suboption Syntax




Add suboptions according to the following rules:





 Combination Special and A La Carte Suboptions




Combine suboptions according to the following rules:




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 combination special or a la carte suboptions, with no other 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





 










Here is a summary of all -Xlist suboptions:






Option



Action






-Xlist  (no suboption)




Show errors, listing, and cross-reference table





-Xlistc




Show call graphs and errors





-XlistE




Show errors





-Xlisterr[nnn]




Suppress error nnn in the verification report





-Xlistf




Produce fast output





-Xlistflndir




Put the .fln files in dir





-Xlisth




Errors from cross-checking stop compilation





-XlistI




List and cross-check include files





-XlistL




Show the listing and errors





-Xlistln




Set page breaks





-Xlisto name




Rename the -Xlist output report file





-Xlists




Unreferenced symbols suppressed from the cross-reference





-Xlistvn




Show different amounts of semantic information





-Xlistw[nnn]




Set the width of output lines





-Xlistwar[nnn]




Suppress warning nnn in the report





-XlistX




Show the cross-reference table and errors





 











 -Xlist Suboption Reference





	-Xlistc



Show call graphs (and cross-routine errors). 



This suboption by itself 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.




	-XlistE



Show cross-routine errors. 



This suboption by itself does not show a listing or a cross-reference.




	-Xlisterr[nnn]



Suppress error nnn in the verification report. 



This option is useful if you want a listing or cross-reference without the error messages. It is also useful if you do not consider certain practices to be real errors.



To suppress more than one error, use this option repeatedly. For example: -Xlisterr338 suppresses error message 338. If nnn is not specified, all error messages are suppressed. 




	-Xlistf



For faster output, produce source file listings and cross-checking and verify 
sources, but do not generate object files. 



The default without this option is to generate object files.




	-Xlistflndir



Put the .fln files into the dir directory, which must already exist. 



The default is the source directory.




	-Xlisth



Halt the compilation if errors are detected while cross-checking the program. In 
this case, the report is redirected to stdout instead of the *.lst file.




	-XlistI



List and cross-check include files.



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






The default is not to show include files.






	-XlistL



Show listing and cross-routine errors. 



This suboption by itself does not show a cross reference. The default is to show the listing and cross-reference.




	-Xlistln



Set the page length for pagination to n lines. 



The suboption is the letter ell for length, not the digit one. 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. 




	-Xlisto name



Rename the -Xlist output report file. The space between o and name is 
required. Output is then to the name.lst file.



To display directly to the screen, use the command: -Xlisto /dev/tty




	-Xlists



Suppress unreferenced identifiers from the cross-reference table.



If the identifiers are defined in the include files but not referenced in the source files, then they are not shown in the cross-reference table.



This suboption has no effect if the suboption -XlistI is used.



The default is not to show the occurrences in #include or INCLUDE files.




	-Xlistvn



 Set level of checking strictness; n is 1,2, 3, or 4. The default is 2 (-Xlistv2).






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








Show cross-checked information with summaries and line numbers. This is the normal level of checking strictness and includes argument inconsistency errors and variable usage errors.








Show cross-checking with summaries, line numbers, and show 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.








Show cross-checking with summaries, line numbers, and show common block maps, and equivalence block maps. This is the top level of checking strictness with maximum error detection.






	-Xlistw[nnn]



Set width of output line to n columns. 



For example, -Xlistw132 sets the page width to 132 columns. The default is 79.




	-Xlistwar[nnn]



Suppress warning nnn in the report. 



If nnn is not specified, then all warning messages are suppressed from printing. To suppress more than one, but not all warnings, use this option repeatedly. For example, -Xlistwar338 suppresses  warning message number 338.




	-XlistX



Show cross-reference table and cross-routine errors. This suboption by itself 
does not show a listing.



The cross-reference table answers the following questions about each identifier: 













 Some Examples Using Suboptions




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 23 10:40:32 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%







 










Example: Explain a message and find a type mismatch:

















Program waits for  input





Type Z on keyboard  





demo% cat ShoGetc.f





	CHARACTER*1 c





	i = getc(c)





	END





demo% f77 -silent ShoGetc.f





demo% a.out         





Z







The problem:





     Why this message?    





 Note: IEEE floating-point exception flags raised: 





    Invalid Operation; 





 See the Numerical Computation Guide, ieee_flags(3M) 







Compile with -Xlist





       List the output.









































 





 Here is the error.       





     





The default typing of 
getc is not consistent 
with the Fortran 
library.





f77 has information 
about the Fortran 
library -- in particular, 
that getc is integer.





demo% f77 -XlistE -silent ShoGetc.f





demo% cat ShoGetc.lst





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 





     2          i = getc(c)





                         ^





**** WAR  #320:  variable "c" set but never referenced














 








The solution:                   





   Declare getc  an 
integer.

















 





No error message.





demo% cat ShoGetc.f





	CHARACTER*1 c





	INTEGER getc





	i = getc(c)





	END





demo% f77 -silent ShoGetc.f





demo% a.out





Z





demo%







 













 Special Compiler Options 




Some compiler options are useful for debugging. They check subscripts, spot undeclared variables, show stages of the compile-link sequence, display versions of software, and so on. 



With Solaris 2.3 and later, there are new linker debugging aids. See ld(1), or run   ld -Dhelp   to see online documentation.




 Subscript Bounds (-C)




The -C option adds checks for out-of-bounds array subscripts.



If you compile with -C, the compiler adds checks at runtime for out-of-bounds references on each array subscript. This action helps catch some situations that cause segmentation faults. 



Example: Index out of range:







demo% cat indrange.f





	REAL a(10,10)





	k = 11





	a(k,2) = 1.0





	END





demo% f77 -C -silent indrange.f





demo% a.out





 Subscript out of range on file indrange.f, line 3, procedure 
MAIN. 





 Subscript number 1 has value 11 in array a. 





 Abort (core dumped) 





demo%







 











 Undeclared Variable Types (-u)




The -u option checks for any undeclared variables.



The -u option causes all variables to be initially identified as undeclared, so that all variables that are not explicitly declared are flagged with an error. The -u flag is useful for discovering mistyped variables. If -u is set, all variables are treated as undeclared until explicitly declared. Use of an undeclared variable is accompanied by an error message.




 Version Checking (-V)




The -V option causes the name and version ID of each phase of the compiler to be displayed. This option can be useful in tracking the origin of ambiguous error messages and in reporting compiler failures, and to verify the level of installed compiler patches. 






 Interactive Debugging With dbx and The WorkShop




The Sun WorkShop provides a tightly integrated development environment for building and browsing, as well as debugging applications written in Fortran, C, C++, and Pascal.



The WorkShop debugging facility is a window-based interface to dbx, while dbx itself is an interactive, line-oriented, source-level symbolic debugger. Either can be used to determine where a program crashed, to view or trace the values of variables and expressions in a running code, and to set breakpoints. 



The WorkShop adds a sophisticated graphical environment to the debugging process that is integrated with tools for editing, building, and source code version control. It includes a data visualization capability to display and explore large and complex datasets, simulate results, and interactively steer computations. 



For details, see the Sun manuals WorkShop: Getting Started and WorkShop: Command-Line Utilities, and the dbx(1) man pages.



The dbx program provides event management, process control, and data inspection. You can watch what is happening during program execution, and perform the following tasks:





 Debugging Optimized Programs




To debug optimized programs, use the dbx fix command to recompile the routines you want to debug:




Some optimizations may be inhibited by the presence of -g on the compilation command. For example, -g suppresses the automatic inlining usually obtained with -O4. -g cancels any parallelization option (-autopar, -explicitpar, 
-parallel), as well as -depend and -reduction. Debugging is facilitated by specifying -g without any optimization options. See the dbx documentation for details.






 Viewing Compiler Listing Diagnostics




The error utility program can be used to view compiler diagnostics merged with the source code. error inserts compiler diagnostics above the relevant line in the source file. The diagnostics include the standard compiler error and warning messages, but not the -Xlist error and warning messages.




Warning - This utility rewrites your source files and does not work if the source files are read-only, or in a read-only directory. 



error(1) is available if the operating system was installed with a developer install, rather than an end-user install; it can also be installed from the package, SUNWbtool. 



Facilities also exist in the Sun WorkShop for viewing compiler diagnostics. Refer to the Sun WorkShop: Getting Started guide.









 



Previous


Next

Contents

Index

Doc Set

Home