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 <
-
Enables a set of checker flags and
cov-analyze
options that cause Prevent to make more aggressive assumptions during analysis. As thelevel
increases, more defects are reported (both as true defects and as false positives), and analysis time increases. Values forlevel
arelow
,medium
, orhigh
. Default islow
.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 thelow
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 themedium
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 andcov-analyze
will complete the analysis. Note that if two compilations exported the same symbols (function names), thencov-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 < -
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
support@coverity.com
.
--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
andc|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 < -
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 runcov-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
. Seeconfig/parse_warnings.conf.sample
for an example. See also--enable-parse-warnings
.
--path-log-threshold < -
If a function has more than <
number
> paths, this count is output to the log file.
--paths < -
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
support@coverity.com
.
--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, orlicense.dat
in the same directory ascov-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 ifcov-analyze
does not use a floating-node license.
level
>
checker_pathname
>
processes
>
number
>
number
>
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.