cvstatic(1)cvstatic(1) NAME cvstatic - Invokes the WorkShop Static Analyzer SYNOPSIS cvstatic [-batch] [-fileset filename] [-readonly] [-preprocess] [-noindex] [-preprocess] [-executable filename] [-mode SCANNER] [-mode PARSER] IMPLEMENTATION IRIX systems DESCRIPTION The Static Analyzer is the WorkShop source code analyzer designed to help you understand the structure of a program. The Static Analyzer allows you to ask questions about the organization and structure of a collection of files. The Static Analyzer supports Ada, C, C++, Fortran 77 code and provides limited support for Fortran 90 codes. The Static Analyzer provides numerous ways to look at program structure both graphically and through textual results of queries. The Analyzer operates in two modes: scanner mode and parser mode. Scanner mode is the default mode and the method of building a static analysis database. Scanner mode is fast and runs on code that does not compile, but it is not sensitive to the characteristics of specific programming languages. Parser mode provides a more detailed, language-specific analysis that uses the compiler front-end to analyze code. This mode works only on source code that does compile. You must provide the Analyzer with a set of files on which to work. These files must exist in a fileset, which is a file that contains a list of files, one file name per line. By default, the analyzer creates a fileset with the following file naming convention: filename.[C|f], which matches C, C++ or Fortran 77 programs in the current directory. You can specify any name for a fileset file but, by default, the Analyzer looks for a file named cvstatic.fileset. For additional information about filesets, refer to the Fileset Files section of this man page. The cvstatic command supports the following options: Option Description -batch Runs the Static Analyzer in batch mode, which always forces a complete build of the database. Batch mode is useful if you want to build a database for a very large program and do not want to wait while the database builds. Batch mode works only if the fileset already exists. No output is displayed when the Analyzer is run in batch mode. After the database is built, the Analyzer exits. -fileset filename Instructs the Analyzer to use the specified file as the fileset file instead of the default cvstatic.fileset file. If you do not specify a fileset name, the name defaults to cvstatic.fileset. The -fileset option is used only when the default fileset is not being used. -readonly Runs the Analyzer using the current database files; database files are not updated. -preprocess Specifies that preprocessing be performed when running the Analyzer in scanner mode. By default, files are not preprocessed when running in scanner mode because preprocessing destroys useful information and alters the user's view of the program. Therefore, the Analyzer generally works on unaltered source files. However, for code with many if/def statements, it is sometimes useful to preprocess these statements. If you specify the -preprocess option, the Analyzer runs a special preprocessor before scanning the code. This preprocessor handles only if/def and define statements. It does not perform macro expansion or insert included code. It does read include files to look for define statements that might affect if/def statements. Preprocessing adds significantly to the time required to generate a scanner-mode database file. -noindex Suppresses generation of the cvstatic.xref, cvstatic.index, and cvstatic.posting files. By default, the Analyzer creates three database files in scanner mode: the cvstatic.xref file that contains cross-reference listings and the cvstatic.index and cvstatic.posting files both of which help in finding items in the cvstatic.xref file. If the -noindex option is specified, the cvstatic.index and the cvstatic.posting files will not be created and the Analyzer will run more slowly. The default mode is significantly faster, particularly on large databases. However, it takes time to generate the cvstatic.index and the cvstatic.posting files and it requires approximately twice as much disk space as when the -noindex option is used. -executable filename Specifies that the Analyzer generate a fileset by extracting the filenames used to build the named executable file. The executable file must be unstripped. Although this option provides an easy method of creating a fileset file, the resulting fileset file may need to be edited because it includes all files in the program, including system libraries and other files that are often outside the fileset of interest. -mode SCANNER Starts the Analyzer in scanner mode. Files in the parser-mode fileset are ignored and queries supported only in parser mode will be unavailable. A parser-mode database is not produced. -mode PARSER Starts the Analyzer in parser mode. Files in the scanner-mode fileset are ignored and queries supported only in scanner mode will be unavailable. The cvstatic.xref, cvstatic.posting, and cvstatic.index files are not produced. Fileset Files If the default cvstatic.fileset fileset does not meet your needs, you can modify the file as needed by editing the file with a text editor. If you have many subdirectories in your program, you can use the find(1) command to create a fileset file. For example, the following command can be used to generate a fileset file containing all C files in the current directory and all subdirectories: find . -name *.c -print > cvstatic.fileset All fileset files must have -cvstatic as the first line. If you do not use the default cvstatic.fileset file, you must edit your fileset file to add this line at the beginning of the file. If this line is missing, the Analyzer will not recognize the file as a valid fileset. You need not list header files in a fileset file because the Static Analyzer determines which headers are used as it reads the source files. By default, the Analyzer looks in the current directory and then looks in the /usr/include directory for all header files. To look elsewhere, add the following command at the end of the fileset file: -I/usr/local/include You also can direct the Analyzer to extract a fileset from an executable file by specifying -executable filename on the command line or by using the Analyzer's fileset editor to build a list. Database Files In scanner mode, the Analyzer creates several database files from the source files listed in the fileset file. The names of these files are based on the name of the fileset file. By default, these files are named cvstatic.xref, cvstatic.index, and cvstatic.posting. These files are non-ASCII database files used by the analyzer to look up information quickly in response to queries. In parser mode, the Analyzer creates a number of files beginning with cvdb that compose a database of a different format from that produced in scanner mode. The Analyzer can analyze files in either mode and will produce both kinds of database files. By default, the dates of all files in a fileset are checked upon starting the Analyzer. If any files are newer than the database files, the database is updated with the newer files. You can change this behavior in the following ways: * Start the Analyzer in read-only mode by specifying the -readonly option on the cvstatic command line * Change to read-only mode interactively by selecting the Read Only option from the General Options dialog box available through the Admin menu * Force the database to be completely rebuilt at any time by choosing the Force Scan option from the Admin menu Read-only mode is useful for viewing files mounted on read-only file systems. For example, a large project might build a database overnight on a fileserver. Then an individual user could view the database by starting the Analyzer in read-only mode, without having to rebuild the database. For large filesets, using read-only mode can reduce startup time significantly because the Analyzer will not check the time stamps on every file. You should note, however, that using an out-of-date database may generate results that do not match the files. Getting Started To start a static analysis session, change to the directory containing the source file you wish to examine and type cvstatic. After the Static Analyzer window is displayed, you can begin making queries by selecting options from the Queries menu. Query Options The Static Analyzer supports many types of queries. You can make queries by selecting options from the Queries menu. Some queries are always available, while other queries require that you supply an argument. For example, the List All Functions option does not require an argument but the Who Calls option does. To specify an argument to an option, enter the argument in the Query Target text field located below the menu bar on the main Static Analyzer window. Query results are displayed in the current window and also are recorded in the history list to allow you to reexamine the results of previous queries. Views The Static Analyzer offers several ways to view the results of a query. The default view is the Text View. Graphical views include the Call Tree View, the Class Tree View, and the File Dependency Views. Text View Text View is the default view. This view displays the results of each query as a list. Each item in the list represents one result of the query. For example, if you select the Who Is Called By option from the Queries menu and specify main as the argument, you will see a list of all functions called by main, the name of the file in which the call occurred, the line number of the call, and a short code segment. Clicking the mouse on a line in the Text View area selects an item from the output. The selected item is placed in the Query Target text field for use as the next query target. You also can double click on any line to bring up an editor to view the source indicated by the line. Call Tree View The Call Tree View displays a call graph of functions in a fileset. By default, the call tree displays only those functions that are the results of a query. For example, the query Who Is Called By with a specified argument of main is displayed graphically as a tree one level deep with the function main shown as the root of the tree. If you make a query such as Who References with a specified argument of varx, all functions that reference the varx variable are displayed. However, if any of these functions have caller/callee relationships, these relationships are also displayed. The Call Tree View supports the following display modes: * Incremental mode, in which results of previous queries remain on the screen when new queries are made. This allows you to build an incremental call tree of portions of code. * All Defined mode, in which all functions in the fileset remain on the screen at all times. The results of various queries are shown by annotating the appropriate nodes of the tree in color. This mode is only appropriate for small filesets. For large filesets with many functions, the tree quickly becomes unmanageable. * Complete Tree mode, in which the entire tree is shown at all times. This mode is similar to the All Defined mode, but displays not only all functions defined in the fileset but also all known functions referenced within the fileset, including library routines, system calls, and so on. Class Tree View The Class Tree View is used for C++ programs and allows you to see superclass/subclass relationships between classes defined within the fileset. The Class Tree View functions similarly to the Call Tree View. File Dependency View The File Dependency View displays include relationships between files. This view is useful for determining how include files are used, but it also can be used to provide a global view of the code. For example, displaying the File Dependency View and selecting the Who References option with an argument of varx displays all files that contain references to the varx variable. NOTES Information about using and customizing graphical displays can be found in the ProDev WorkShop: Overview. CAUTIONS The Analyzer is intended for use with a single program. Attempting to analyze filesets that represent multiple programs will produce unpredictable results in the graphical views. The Analyzer performs static analysis. Therefore, it cannot handle C++ virtual functions or other indirect techniques for calling functions. C++ has no standard suffix conventions. Therefore, the fileset naming convention used by the Analyzer may not match C++ conventions used at your site. ENVIRONMENT VARIABLES The Static Analyzer uses the following environment variable: Variable Description USER User's login name. FILES The Static Analyzer uses the following files: File Description cvstatic.fileset Default fileset file used by the Static Analyzer cvstatic.xref Non-ASCII database file created and used by the Static Analyzer to find information in response to user queries cvstatic.index Non-ASCII database file created and used by the Static Analyzer to find information in response to user queries cvstatic.posting Non-ASCII database file created and used by the Static Analyzer to find information in response to user queries cvdb*. Parser mode database files SEE ALSO cvd(1), cvhang(1), cvperf(1), cvxhang(1) ProDev WorkShop: Debugger User's Guide ProDev WorkShop: Performance Analyzer User's Guide ProDev WorkShop: Overview ProDev WorkShop: Static Analyzer User's Guide Online information is available through the Help manu of the Static Analyzer tool.