cov-analyze

cov-analyze

cov-analyze — Analyze an intermediate directory for defects.

Synopsis

cov-analyze --dir <intermediate_directory> [--cxx] [OPTIONS]

Description

The cov-analyze command analyzes the code previously parsed and emitted into an intermediate directory. The result is a set of XML files in the <intermediate_directory>/c/output directory that contain a description of the defects. The cov-analyze command also stores analysis information in the intermediate directory, which speeds up future runs.

A log file with information about the checkers used in the analysis, including notices of crashes, is created at <intermediate_directory>/c/output/analysis-log.txt.gz.

Note that behind the scenes, cov-analyze actually calls cov-internal-analyze-c to run the analysis. If you look at running processes, both cov-analyze and cov-internal-analyze-c are listed. During an analysis, cov-analyze monitors cov-internal-analyze-c, and can seamlessly restart the analysis in case of failure.

When analysis completes, you might see a message similar to:

    The analysis was restarted <N> times.

Where < N> is the number of times that  cov-analyze restarted  cov-internal-analyze-c to complete the analysis.

Options

--aggressiveness-level <level>

Enables a set of checker flags and cov-analyze options that cause Prevent to make more aggressive assumptions during analysis. As the level increases, more defects are reported (both as true defects and as false positives), and analysis time increases. Values forlevel are low, medium, or high. Default is low.

The aggregate false positive rate for all checkers except parse warnings will be on the order of 50% higher with --aggressiveness-level medium, and 70% higher with --aggressiveness-level high. For the parse warning checkers, the false positive rate does not change with different levels, but the issues being reported are of decreased severity.

The level value sets the following options.

• For low, uses the default status for all checker options.

• For medium, sets all options used at the low level, as well as the following options:

      --enable-parse-warnings   
      BAD_ALLOC_STRLEN:report_plus_any
      CHECKED_RETURN:error_on_use
      CHECKED_RETURN:stat_threshold:55
      CONSTANT_EXPRESSION_RESULT:report_bit_and_with_zero
      CONSTANT_EXPRESSION_RESULT:report_constant_logical_operands
      FORWARD_NULL:deref_zero_errors
      FORWARD_NULL:track_macro_nulls
      INFINITE_LOOP:allow_asm
      INFINITE_LOOP:allow_pointer_derefs
      INFINITE_LOOP:report_no_escape
      NO_EFFECT:self_assign_to_local
      NO_EFFECT:unsigned_enums
      NULL_RETURNS:allow_unimpl
      NULL_RETURNS:stat_bias:10 
      NULL_RETURNS:stat_threshold:50
      RESOURCE_LEAK:allow_cast_to_int
      RESOURCE_LEAK:allow_main
      RESOURCE_LEAK:allow_overwrite_model
      RESOURCE_LEAK:allow_unimpl
      RESOURCE_LEAK:track_fields
      SYMBIAN.CLEANUP_STACK:bad_pop
      SYMBIAN.CLEANUP_STACK:multiple_pushes
      SYMBIAN.CLEANUP_STACK:infer_allocs
      SYMBIAN.NAMING:report_LC_errors
      PW.DECLARED_BUT_NOT_REFERENCED
      UNINIT:check_arguments
      UNINIT:check_mayreads
      UNINIT:enable_deep_read_models
      UNINIT:enable_parm_context_reads
      UNINIT:enable_write_context

• For high, sets all options used at the medium level, as well as the following:

      CONSTANT_EXPRESSION_RESULT:report_bit_and_with_zero_in_macros
      CONSTANT_EXPRESSION_RESULT:report_constant_logical_operands_in_macros
      CONSTANT_EXPRESSION_RESULT:report_contradictory_bit_and
      INFINITE_LOOP:suppress_in_macro:false
      INTEGER_OVERFLOW:enable_all_overflow_ops
      INTEGER_OVERFLOW:enable_deref_sink
      NO_EFFECT:self_assign_in_macro
      NULL_RETURNS:stat_threshold:0
      PW.ALREADY_DEFINED
      PW.BAD_INITIALIZER_TYPE
      PW.BAD_RETURN_VALUE_TYPE
      PW.CLASS_WITH_OP_DELETE_BUT_NO_OP_NEW
      PW.CLASS_WITH_OP_NEW_BUT_NO_OP_DELETE
      PW.ILP64_WILL_NARROW
      PW.INCOMPATIBLE_ASSIGNMENT_OPERANDS
      PW.INCOMPATIBLE_OPERANDS
      PW.INCOMPATIBLE_PARAM
      PW.INTEGER_TRUNCATED
      PW.MIXED_ENUM_TYPE
      PW.NESTED_COMMENT
      PW.NO_CORRESPONDING_DELETE
      PW.NO_CORRESPONDING_MEMBER_DELETE
      PW.NO_CTOR_BUT_CONST_OR_REF_MEMBER
      PW.NON_CONST_PRINTF_FORMAT_STRING
      PW.NONSTD_VOID_PARAM_LIST
      PW.NOT_COMPATIBLE_WITH_PREVIOUS_DECL
      PW.POINTER_CONVERSION_LOSES_BITS
      PW.SET_BUT_NOT_USED
      SYMBIAN.CLEANUP_STACK:aliases_as_free
      TAINTED_STRING:paranoid_format
      RESOURCE_LEAK:allow_address_taken
      RESOURCE_LEAK:allow_constructor
      RESOURCE_LEAK:allow_template
      RESOURCE_LEAK:allow_virtual
      UNCAUGHT_EXCEPT:report_all_except
      UNCAUGHT_EXCEPT:report_all_fun
      UNINIT:allow_unimpl
      UNINIT:check_malloc_wrappers
      UNREACHABLE:report_unreachable_in_macro

--all

Enable all Prevent checkers including all preview checkers. Equivalent to the options --cxx --security --concurrency --enable-parse-warnings and enabling all other checkers that are not enabled by default.

--allow-duplicate-files

If the same file has been compiled several times with different options, the analysis fails. Usually this means that the resulting objects will be linked into separate binaries (for example, different architectures), and you should use cov-link to separate the duplicate function calls into different emit repositories. If the objects are part of the same binary, you can use this option and cov-analyze will complete the analysis. Note that if two compilations exported the same symbols (function names), then cov-analyze will arbitrarily choose one of the two when resolving function calls.

--allow-unmerged-emits

By default, the analysis fails if an intermediate directory contains emits from multiple hosts. Specify this option to permit the analysis to continue in these cases. If you use cov-manage-emit add-other-hosts to associate all emit repositories in the current intermediate directory with the current host, then --allow-unmerged-emits is not needed to continue the analysis.

--append

Append to the defects from the last run of cov-analyze.

--checker-option <chk>:<opt>[:<val>],  -co <chk>:<opt>[:<val>]

Pass option <opt> (with optional value <val>) to a specific checker <chk>. See, for example, the STACK_USE checker.

--command <checker_pathname>

Use an Extend checker at the specified path name.

--concurrency

Turn on concurrency-related checkers such as LOCK and ORDER_REVERSAL.

	For best results, Coverity highly recommends training for the concurrency checkers. To find out more about training, please contact your Coverity representative or [email protected].

--cxx

Turn on C++ specific checkers.

--debug,  -g

Turn on basic debugging output.

--derived-model-file <derived_file.xmldb>

Use the function models in <derived_file.xmldb> when no implementation or user model is found for a function. This option can be specified multiple times. See cov-help cov-collect-models.

--dir <intermediate_directory>

Pathname to an intermediate directory that is used to store the emit repository and output directory. Uses an emit repository at <intermediate_directory>/c|java|cs/emit and an output directory at <intermediate_directory>/c|java|cs/output. If you specify ".", usesc|java|cs/emit and c|java|cs/output in the current directory.

--disable <checker>,  -n <checker>

Disable <checker>. This can be specified multiple times. See also --list-checkers and --disable-default.

--disable-default

Disable all checkers. This option is useful if you want to disable all default checkers and then enable only a few with the --enable option.

--disable-parse-warnings

Disable all parse warnings, and override other arguments that might have enabled them, such as --all or --enable-parse-warnings. The order of command-line options is irrelevant; the --disable-parse-warnings option takes precedence.

--dtd <directory>

This option is now deprecated. Use the --prevent-root option instead.

--enable <checker>,  -en <checker>

Enable <checker>. The checker name is case insensitive. This can be specified multiple times. See also --list-checkers and --disable-default.

--enable-callgraph-metrics

Create a file, <intermediate_directory>/c/output/callgraph-metrics.txt, that has information about which functions are analyzed. The file lists whether a function is implemented, which means it is analyzed, or unimplemented, which means that it is not analyzed, although a model, if available, is used. The file also shows the number of callers for each function.

--enable-constraint-fpp

Enable additional filtering of potential defects by using an additional false-path pruner (FPP). This option can increase the analysis time up to 20% (normally much less), but decrease the number of false positives that occur along infeasible paths. Because this FPP uses a different method for pruning false positives, it is possible that a very small number of true positives will be pruned as well.

--enable-fnptr

Enable analysis of calls to function pointers for defects. By default, calls to function pointers are not analyzed.

Including calls to function pointers in the analysis with this option increases the false positive rate by approximately 10-20%.

This is a preview option.

--enable-parse-warnings

Enable parse warnings, recovery warnings, and semantic warnings that are produced by the cov-build command so that they appear as defects in the Defect Manager. See also --parse-warnings-config.

--enable-single-virtual

Enable single virtual call resolution, which has no effect on C code. On C++ code, the analysis can take longer than the default because the analysis engines looks at implementations of virtual functions, which can result in more defect reports. By default, the analysis engine assumes that all virtual functions are unimplemented. When this option is enabled, interprocedural analysis across virtual calls happens when the analysis engines finds only one implementation of a virtual function. When the analysis engine finds more than one implementation, it assumes that the virtual function is unimplemented. Do not specify this option if you specify the --enable-virtual option.

--enable-virtual

Enable full virtual call resolution, which has no effect on C code. On C++ code, the analysis can take significantly longer than the default or when the --enable-single-virtual option is enabled because the analysis engines looks at all implementations of virtual functions, which can result in more defect reports. By default, the analysis engine assumes that all virtual functions are unimplemented. Do not use this option if you specify the --enable-single-virtual option.

--fnptr-models

You can enable analysis of calls to function pointers (without requiring explicit models) using the --enable-fnptr option.

If the analysis fails to analyze certain function pointers calls, you can also enable function pointer models with --fnptr-models. See Modeling function pointers in the Checker Reference for more information, including examples.

--force

Do not use previously cached results to speed up the analysis. This effectively turns off incremental analysis.

--function <funcname>

Only analyze the function <funcname>. For C++, the name should be mangled.

--hfa

Reports unnecessary header file includes. An unnecessary header file include can occur when the header file prototypes functions and data structures that are not needed in that source file.

Including unnecessary header files does not cause problems with the analysis, but can slow build performance by requiring the compiler to perform additional work. Use this option to identify these unneeded headers, and then manually eliminate the includes to speed up future builds.

Unnecessary header files are reported as defects found by the HFA checker. This checker works only on C (not C++) code.

Note that the -all option does not enable this checker.

-j <processes>

Specifies the number of processes for parallel-by-checker analysis. For best results, run a manual parallel-by-checker analysis.

When specified, the -j option only performs analyses on the machine on which you run cov-analyze. It will not perform analyses on clustered machines. Note that defect results may differ a small amount (a few percent churn) from sequential analysis results.

An output directory is created in the intermediate directory for each process. You must specify all of these directories when you commit the defects to the Defect Manager with the cov-commit-defects command. When you use this option, all other command options are ignored except for the following: --dir, --enable, --concurrency, --cxx, --disable, and --security.

The default value is 1 and the value must be less or equal to 4. Make sure that you have 1.5GB of free memory for each <processes> value unit you specify. For example, if you specify <processes> as 3, you should have 4.5GB of free memory.

The --j <processes> option is supported for backward compatibility.

--list-checkers

Display a list of checkers that can be used with the --enable and --disable options.

--max-loop <num>

Limit the number of times loops can be traversed. The default is to traverse loops until a fixpoint is attained, which effectively exhausts all behaviors of the loop with respect to the abstraction being used in the analysis.

--max-mem <value>

Limit the amount of memory allowed for each function analyzed to <value> MB. Peak memory consumption might exceed this number significantly in rare cases. Defaults to 512.

--no-log

Disables logging.

--no-restart

In case of a crash during the analysis, do not restart the analysis. By default, the analysis restarts. This option can be useful for debugging.

For backwards compatibility, you can also specify this option as --no-watchdog.

--no-stats

Turn off the statistical derivation pass. This makes NULL_RETURNS ignore the number of times a function's return value is checked against NULL when reporting errors. This also turns off the CHECKED_RETURN checker.

--parse-warnings-config <filename>

Specify a configuration file that enables you to adjust which parse warnings pass through the warning filter in cov-analyze. See config/parse_warnings.conf.sample for an example. See also --enable-parse-warnings.

--path-log-threshold <number>

If a function has more than <number> paths, this count is output to the log file.

--paths <number>

Set the upper limit on the number of paths to traverse for each function. Default is 5000.

--prevent-root

When running an Extend checker, specifies the location of the Prevent installation directory:

--prevent-root /<install_dir>

--print-paths

For each analyzer, for each function analyzed, print the number of paths explored.

--security

Turns on security-related checkers such as TAINTED_DATA, TAINTED_STRING, STRING_SIZE, and STRING_NULL.

	For best results, Coverity highly recommends training for security-related checkers. To find out more about training, please contact your Coverity representative or [email protected].

--security-file <license file>,  -sf <license file>

Path to a valid Coverity Prevent license file. If not specified, this path is given by the <security_file> tag in the Coverity configuration, or license.dat in the same directory as cov-analyze. A valid license file is required to run the analysis.

--stats-only

Only run the statistical derivation pass, do not run any checkers.

--symbian

Enables the SYMBIAN.CLEANUP_STACK checker.

--ticker-mode <mode>

Set the mode of the progress bar ticker, from among:

none

No progress bar at all.

no-spin

Print stars only, without the spinning bar.

spin

(default) Stars with a spinning bar at the end. Each function analyzed corresponds to one step of spin.

--user-model-file <user_file.xmldb>

The function models in this file override any function models automatically derived from the implementation. Note that if the default file at <install_dir>/config/user_models.xmldb exists, it is used even without specifying this option. This option can be specified multiple times. See cov-help cov-make-library.

--wait-for-license

Indicate that if a license cannot be obtained from the license server, the cov-analyze command must wait until a license becomes available. After a license becomes available, cov-analyze acquires it and proceeds with the analysis. This option is ignored if cov-analyzedoes not use a floating-node license.

Common options

--config <coverity_config.xml>,  -c <coverity_config.xml>

Use the specified configuration file instead of the default configuration file located at <install_dir>/config/coverity_config.xml.

--debug,  -g

Turn on basic debugging output.

--ident

Display the version of Prevent and build number.

--info

Display certain internal information (useful for debugging), including the temporary directory, user name and host name, and process ID.

--tmpdir <tmp>,  -t <tmp>

Specify the temporary directory to use. On UNIX, the default is $TMPDIR, or /tmp if that variable does not exist. On Windows, the default is to use the temporary directory specified by the operating system.

--verbose <0, 1, 2, 3, 4>,  -V <0, 1, 2, 3, 4>

Set the detail level of command messages. Higher is more verbose (more messages). Defaults to 1. Use --verbose 0 to disable progress bars.

Examples

Analyze the intermediate directory at /nfs/foo/apache using only the DEADCODE checker:

> cov-analyze --dir /nfs/foo/apache --disable-default --enable DEADCODE