--- codesonar-3.2p0/i686-pc-linux/codesonar-3.2p0/codesonar/template.conf 2008-09-02 13:28:45.000000000 -0400 +++ codesonar-3.3p0/i686-pc-linux/codesonar-3.3p0/codesonar/template.conf 2008-11-06 23:38:58.000000000 -0500 @@ -21,9 +21,9 @@ # - Backslash can be used at the end of a line to continue a line. # - A comment is a line where the first non-whitespace character is a # hash mark. # - Empty lines have no effect. -# - Nothing is case sensitive. +# - Variable names and boolean values (Yes/No) are case insensitive. # # The tool will issue warnings if there are syntax errors in this # file, but continue running. # @@ -34,8 +34,14 @@ # Preferences that come later in this file take precedence over # preferences that come earlier. The += operator will append to a # preference. If the first occurrence of a preference uses the += # operator, then it is treated as an = operator. +# +# If a command line flag contradicts a conf file setting (even in the +# template conf file), then behavior is undefined. GrammaTech +# strongly encourages users to use conf files to encode settings +# rather than command line flags, and is in the process of deprecating +# use of command line flags in some contexts. # # CodeSonar reads both the template preference file and the project # preference file. To modify default preferences in a system-wide # fashion, a user should modify the template preference file. The @@ -63,9 +69,9 @@ # the compiler's include directory. # # The += operator will actually prepend to this preference (in all # other cases, the += operator appends). This means that if you have -# two CFLAGS_PREPEND += statements in this file, the CFLAGS in the +# two \tt CFLAGS_PREPEND += statements in this file, the CFLAGS in the # second statement will be prepended to the CFLAGS in the first # statement. # # Type @@ -93,8 +100,310 @@ # a list of CFLAGS # CFLAGS_APPEND += + +# Parameter COMPILER_MODELS +# +# Behavior +# Defines a map from compiler executable basenames to compiler models. +# +# If your compiler executable has a basename not listed below as a +# 'default', then you should add an entry mapping it to the compiler +# model it is most similar to. +# +# Type +# Whitespace-separated list of rules of the form +# \code +# executable-basename -> model +# \endcode +# +# Notes +# On Windows, the file extension (which should be .exe or .com) for +# the domain is not optional. Some examples are given below. The +# range of the map is the list of 'model used' entries in the +# appropriate \link ../CompilerModels/CompilersRecognized.html +# Compilers Recognized\endlink table. Users can also author new +# compiler models in Scheme, thereby expanding the range. +# +# Windows default models: +# \code +# COMPILER_MODELS += cl.exe -> cl +# COMPILER_MODELS += cl30.exe -> cl30 +# COMPILER_MODELS += cl6x.exe -> cl6x +# COMPILER_MODELS += clarm.exe -> cl +# COMPILER_MODELS += clmips.exe -> cl +# COMPILER_MODELS += clsh.exe -> cl +# COMPILER_MODELS += clthumb.exe -> cl +# COMPILER_MODELS += gcc.exe -> gcc +# COMPILER_MODELS += g++.exe -> gpp +# COMPILER_MODELS += gpp.exe -> gpp +# COMPILER_MODELS += gxx.exe -> gpp +# COMPILER_MODELS += ecomppc.exe -> ecomppc +# COMPILER_MODELS += ecomx86.exe -> ecomppc +# COMPILER_MODELS += ecomarm.exe -> ecomppc +# COMPILER_MODELS += ecom86.exe -> ecomppc +# COMPILER_MODELS += armcc.exe -> armcc +# COMPILER_MODELS += tcc.exe -> armcc +# COMPILER_MODELS += mcpcom.exe -> mcpcom +# COMPILER_MODELS += cw-cc.exe -> xcc +# COMPILER_MODELS += picc.exe -> picc +# COMPILER_MODELS += shc.exe -> shc +# COMPILER_MODELS += shcpp.exe -> shcpp +# COMPILER_MODELS += ch38.exe -> ch38 +# COMPILER_MODELS += null-cc.exe -> xcc +# \endcode +# +# Posix default models: +# \code +# COMPILER_MODELS += gcc -> gcc +# COMPILER_MODELS += gxx -> gpp +# COMPILER_MODELS += g++ -> gpp +# COMPILER_MODELS += gpp -> gpp +# COMPILER_MODELS += c++ -> gpp +# COMPILER_MODELS += cc -> cc +# COMPILER_MODELS += null-cc -> xcc +# COMPILER_MODELS += dcc -> dcc +# COMPILER_MODELS += dplus -> dcc +# COMPILER_MODELS += ecomppc -> ecomppc +# COMPILER_MODELS += ecomx86 -> ecomppc +# COMPILER_MODELS += ecom86 -> ecomppc +# COMPILER_MODELS += ecomarm -> ecomppc +# COMPILER_MODELS += mcpcom -> mcpcom +# COMPILER_MODELS += shc -> shc +# COMPILER_MODELS += shcpp -> shcpp +# COMPILER_MODELS += ch38 -> ch38 +# COMPILER_MODELS += armcc -> armcc +# COMPILER_MODELS += tcc -> armcc +# \endcode +# +# To activate the Hi-Tech compiler model for command-line builds: +# \code +# (Windows) +# COMPILER_MODELS += picc.exe -> picc +# (other systems) +# COMPILER_MODELS += picc -> picc +# \endcode +# +# To activate the Ti CodeComposer compiler models for command-line +# builds on Windows: +# \code +# (Windows) +# COMPILER_MODELS += cl6x.exe -> cl6x +# COMPILER_MODELS += cl30.exe -> cl30x +# (other systems) +# COMPILER_MODELS += cl6x -> cl6x +# COMPILER_MODELS += cl30 -> cl30x +# \endcode +# +# To activate WindRiver compilers, use the following. This will disable +# recognition of some Green Hills compilers because of an executable +# name conflict. +# \code +# (Windows) +# COMPILER_MODELS += ccppc.exe -> ccppc +# COMPILER_MODELS += c++ppc.exe -> c++ppc +# (other systems) +# COMPILER_MODELS += ccppc -> ccppc +# COMPILER_MODELS += c++ppc -> c++ppc +# \endcode + + +# Parameter DISABLED_COMPILERS +# +# Behavior +# Invocations of compilers listed here will be ignored by the project +# builder. Use this parameter to force the project builder to ignore +# certain compilers that it would, by default, notice. +# +# Notes +# On Windows, you may not omit the file extension of the executable +# (which should always be .exe or .com). A superset of the default +# compilers is commented out below. Behavior is undefined if the +# same compiler executable appears in both the \param COMPILER_MODELS +# domain and in the \tt DISABLED_COMPILERS set. +# +# Type +# Whitespace separated list of compiler basenames + +# Windows: +# DISABLED_COMPILERS += armcc.exe +# DISABLED_COMPILERS += ch38.exe +# DISABLED_COMPILERS += cl.exe +# DISABLED_COMPILERS += cl30.exe +# DISABLED_COMPILERS += cl6x.exe +# DISABLED_COMPILERS += clarm.exe +# DISABLED_COMPILERS += clmips.exe +# DISABLED_COMPILERS += clsh.exe +# DISABLED_COMPILERS += clthumb.exe +# DISABLED_COMPILERS += cw-cc.exe +# DISABLED_COMPILERS += ecom86.exe +# DISABLED_COMPILERS += ecomarm.exe +# DISABLED_COMPILERS += ecomppc.exe +# DISABLED_COMPILERS += ecomx86.exe +# DISABLED_COMPILERS += g++.exe +# DISABLED_COMPILERS += gcc.exe +# DISABLED_COMPILERS += gpp.exe +# DISABLED_COMPILERS += gxx.exe +# DISABLED_COMPILERS += mcpcom.exe +# DISABLED_COMPILERS += null-cc.exe +# DISABLED_COMPILERS += picc.exe +# DISABLED_COMPILERS += shc.exe +# DISABLED_COMPILERS += shcpp.exe +# DISABLED_COMPILERS += tcc.exe +# Posix: +# DISABLED_COMPILERS += gcc +# DISABLED_COMPILERS += gxx +# DISABLED_COMPILERS += g++ +# DISABLED_COMPILERS += gpp +# DISABLED_COMPILERS += c++ +# DISABLED_COMPILERS += cc +# DISABLED_COMPILERS += null-cc +# DISABLED_COMPILERS += dcc +# DISABLED_COMPILERS += dplus +# DISABLED_COMPILERS += ccppc +# DISABLED_COMPILERS += c++ppc +# DISABLED_COMPILERS += ecomppc +# DISABLED_COMPILERS += ecomx86 +# DISABLED_COMPILERS += ecom86 +# DISABLED_COMPILERS += ecomarm +# DISABLED_COMPILERS += mcpcom +# DISABLED_COMPILERS += shc +# DISABLED_COMPILERS += shcpp +# DISABLED_COMPILERS += ch38 +# DISABLED_COMPILERS += armcc +# DISABLED_COMPILERS += tcc + + +# Purpose +# Prevent the software build system (e.g., make) from writing over +# environment variables necessary for proper process hooking on POSIX +# systems. +# +# Behavior +# Every time a process calls exec, if the CS_ENVIRON environment +# variable has not been written over, then any important environment +# variables (e.g., LD_PRELOAD, LD_LIBRARY_PATH) that have been +# written over will be repaired in the environment used to create the +# new process. +# +# Notes +# This parameter has no effect on Windows systems. +# +# Most build systems do not need this to be set. The most common +# cause for setting this to "Yes" is a build system that overwrites +# LD_PRELOAD at some point. +# +# If your build system writes over the entire environment or the +# CS_ENVIRON variable at some point, then in addition to setting +# FORCE_ENVIRONMENT to "Yes", you will need to resurrect the +# CS_ENVIRON environment variable to the value it had before it was +# written over. +# +# Setting this to "Yes" can prevent build systems from causing +# compiler invocations to be missed. If you believe source files +# (compilation units) are missing from your project and \param +# COMPILER_MODELS is set correctly, then setting this to "Yes" may +# help. It is slightly invasive and could conceivably cause +# problems, although that hasn't been observed yet. +# +# The CS_ENVIRON environment variable takes precedence over this +# configuration file variable, if it is set when the hook command +# runs. +# +# Type +# {Yes, No} +# +FORCE_ENVIRONMENT = No + + +# Parameter UNIX_TEXT_MODE +# +# Purpose +# Perform crlf -> lf translations on stdout and stderr. Do the +# inverse on stdin. +# +# Notes +# This variable is ignored by the Windows project builder GUI. +# +# This parameter is ignored on non-windows systems. This can be +# useful if running an interactive Cygwin shell inside a hook +# command. +# +# Type +# {Yes, No} + +# UNIX_TEXT_MODE = No + + +# Parameter INVOKE_COMPILER_FIRST +# +# Purpose +# Invoke the real compiler before invoking the CodeSurfer or +# CodeSonar parser. +# +# Notes +# This parameter is ignored on non-Windows systems. Its only known +# use is to make sure the parser has access to output files produced +# by the compiler when using Microsoft's #import directive. +# +# Type +# {Yes, No} + +# INVOKE_COMPILER_FIRST = No + + +# Parameter CODEWARRIOR_INSTALLS +# +# Purpose +# Invocations of all compiler IDE plugins of CodeWarrior install +# directories in this list will be intercepted. +# +# Notes +# This variable is ignored by the Windows project builder GUI. +# CodeWarrior integration must be configured through the GUI. +# +# To configure interception of some subset of the compiler plugins, +# use the \param CODEWARRIOR_PLUGINS parameter instead. If you are +# running from the command line and neither \tt CODEWARRIOR_INSTALLS nor +# \tt CODEWARRIOR_PLUGINS is specified in the template or project +# configuration file, then the settings selected at install time will +# be used. +# +# Type +# Whitespace-separated list of directories +# +# For example: +# \code +# CODEWARRIOR_INSTALLS += "C:\Program Files\Freescale\CodeWarrior for Microcontrollers V6.0" +# \endcode + + +# Parameter CODEWARRIOR_PLUGINS +# +# Purpose +# Invocations of CodeWarrior compiler IDE plugins in this parameter +# will be intercepted. +# +# Notes +# This variable is ignored by the Windows project builder GUI. +# CodeWarrior integration must be configured through the GUI. +# +# To configure interception of all CodeWarrior IDE compiler plugins, +# use the \param CODEWARRIOR_INSTALLS parameter instead. If you are +# running from the command line and neither \tt CODEWARRIOR_INSTALLS nor +# \tt CODEWARRIOR_PLUGINS is specified in the template or project conf +# file, then the settings selected at install time will be used. +# +# Type +# Whitespace-separated list of directories +# +# For example: +# \code +# CODEWARRIOR_PLUGINS += "C:\Program Files\Freescale\CodeWarrior for Microcontrollers V6.0\bin\plugins\compiler\MCFCCompiler.dll" +# \endcode + + # Parameter IGNORED_COMPILATIONS # # Type # A \link ../Asides/STkRegExp.html @@ -116,16 +424,41 @@ # specifies that compilations of files whose paths end in "foo.c" # should be ignored. This includes compilations of "foo.c", # "/usr/local/foo.c", and "mydir/myfoo.c", but not "foo.cpp". # -# You can specify as many IGNORED_COMPILATIONS entries as you +# You can specify as many \tt IGNORED_COMPILATIONS entries as you # want. + +# Parameter IGNORED_COMPILATION_COMMANDS +# +# Type +# string +# # Purpose -# Maximum number of parse errors allowed in a compilation before the -# compilation is excluded from the analysis. If the percentage of -# project compilation units exceeding this limit is greater than -# MINIMUM_GOOD_COMPILATIONS, no analysis will take place. +# Ignore compilation command lines matching this option. +# +# Notes +# This can be significantly faster than using \param +# IGNORED_COMPILATIONS, but is not as precise. \tt IGNORED_COMPILATIONS +# could ignore foo.c and not bar.c in the command "gcc -c foo.c +# bar.c", but \tt IGNORED_COMPILATION_COMMANDS must either accept the +# entire command or none of it. +# +# For example: +# \code +# IGNORED_COMPILATION_COMMANDS += gcc -c foo.c +# \endcode + + +# Purpose +# Specifies the maximum number of parse errors allowed in a +# compilation before the compilation is excluded from the analysis. +# +# Behavior +# If the percentage of project compilation units exceeding this limit +# is greater than \param MINIMUM_GOOD_COMPILATIONS, no analysis will +# take place. # # Type # integer # @@ -130,13 +463,17 @@ # integer # ERROR_LIMIT_PER_COMPILATION = 30 + # Purpose -# Minimum percentage of the compilations that have to be included for -# the analysis to proceed. A good compilation is defined as a -# compilation unit for which the number of parse errors is less than -# ERROR_LIMIT_PER_COMPILATION. +# Specifies the minimum percentage of the compilations that have to +# be included for the analysis to proceed. +# +# Notes +# A good compilation is defined as a compilation unit for which the +# number of parse errors is less than \param +# ERROR_LIMIT_PER_COMPILATION. # # Type # integer between 0 and 100 # @@ -146,10 +484,10 @@ # Do malloc/calloc/alloca/realloc/new/new[] return NULL on failure? # # Notes # This setting is mainly useful for users who don't care what their -# software does when it runs out of memory. -# +# software does when it runs out of memory. +# # Type # {RETURN_NULL, DOESNT_FAIL} # MALLOC_FAILURE_BEHAVIOR = RETURN_NULL @@ -161,10 +500,11 @@ # Notes # Different C++ runtimes have different behaviors. It is recommended # that you write a small test program to see what your compiler does. # -# If MALLOC_FAILURE_BEHAVIOR is set to DOESNT_FAIL, then this -# variable will always behave as if it is set to DOESNT_FAIL. +# If \param MALLOC_FAILURE_BEHAVIOR is set to DOESNT_FAIL, +# then this variable will always behave as if it is set to +# DOESNT_FAIL. # # Type # {STANDARD, EXCEPTION, RETURN_NULL, DOESNT_FAIL} # @@ -176,10 +516,11 @@ # Purpose # Ignore initializers that are sufficiently large to bog down the # analysis. # -# -1 means unlimited, a nonnegative integer places a bound on the -# number of initializer elements. +# Behavior +# Setting to a nonnegative integer places a bound on the +# number of initializer elements, -1 means unlimited. # # Type # integer # @@ -189,9 +530,9 @@ # Purpose # Specifies status message verbosity # # Behavior -# The higher the VERBOSITY value, the more status messages are +# The higher the \tt VERBOSITY value, the more status messages are # issued. If the value is 0 or 1, messages will only be issued for # fatal and near-fatal errors. # # Type @@ -209,9 +550,9 @@ # Build Options: Summary \endlink for a list of the available # options. # # Notes -# CodeSonar users should usually not need to change this. The +# CodeSonar users should usually not need to change this. The # "-verbose 10" setting will cause the builder to emit more status # messages. # # Type @@ -250,12 +592,13 @@ # Notes # One useful option is the ability to add a preinclude file. # # Type -# a list of front-end options +# a list of front-end options # EDG_FRONTEND_OPTIONS_APPEND += + # Purpose # Megabytes of memory to allocate for managed IR objects. # # Behavior @@ -316,12 +662,14 @@ # integer # ZFRAG_POOL_SMALL_THRESHOLD = 4096 + # Purpose -# When performing source replacement with SOURCE_PATTERN_REPLACEMENT, -# this is the size of the buffer used to hold the part of the source -# file currently undergoing matching. +# When performing source replacement with \param +# SOURCE_PATTERN_REPLACEMENT, this is the size of the buffer +# used to hold the part of the source file currently undergoing +# matching. # # Notes # File substrings whose length exceeds this value will never be # matched, but too high a value can cause performance problems. @@ -347,25 +695,24 @@ # sees the original code. Note that this means that any error # reporting will involve line numbers and text from the updated # files. # -# If no is specified for a SOURCE_PATTERN_REPLACEMENT +# If no is specified for a \tt SOURCE_PATTERN_REPLACEMENT # entry, the entry will be ignored with a warning. # # The '/' character is the standard delimiter, but you can use a # different delimiter if necessary. Occurrences of the delimiter # inside and must be escaped. # # If you don't wish to use the delimited expression form at all, you -# can use the combination of SOURCE_PATTERN, SOURCE_REPLACEMENT, and -# SOURCE_MODIFIERS to specify a regular expression based replacement -# as described \link #SOURCE_PATTERN -# below\endlink. +# can use the combination of \param SOURCE_PATTERN, \param +# SOURCE_REPLACEMENT, and \param SOURCE_MODIFIERS to specify a +# regular expression based replacement as described below. # # For example, # \code # SOURCE_PATTERN_REPLACEMENT=s/foo//I -# \endcode +# \endcode # specifies that all occurrences of "foo" in the source code, # regardless of case, should be deleted. This is exactly equivalent # to # \code @@ -377,35 +724,36 @@ # SOURCE_REPLACEMENT= # SOURCE_MODIFIERS=I # \endcode # -# You can specify as many SOURCE_PATTERN_REPLACEMENT entries as you +# You can specify as many \tt SOURCE_PATTERN_REPLACEMENT entries as you # want: replacements will be carried out in the same order that the -# entries are specified. All SOURCE_PATTERN_REPLACEMENTs will be -# carried out after all \link #SOURCE_REPLACE_COMMAND -# SOURCE_REPLACE_COMMANDs\endlink. +# entries are specified. All \tt SOURCE_PATTERN_REPLACEMENTs will be +# carried out after all \tt SOURCE_REPLACE_COMMANDs. # # Type -# A string of the form s///+, where: -# -# The delimiter '/' can be replaced by any character (except null). -# -# is a \link -# ../../../../third-party/boost/libs/regex/doc/syntax.html -# Boost regular expression\endlink describing a pattern that could -# occur in the source code. The pattern can match multiple-line -# substrings in the source file. Double-quote if you want -# it to include leading or trailing spaces. -# -# is the string that should replace source code -# substrings that march . This can be a multiple-line -# string. Double-quote if you want it to include -# leading or trailing spaces. +# A string of the form +# \code +# s///+ +# \endcode # -# is a process modifier, corresponding to a Boost regular -# expression syntax option or flag as shown below. +# where: +# +# - The delimiter '/' can be replaced by any character (except null). +# - is a \link +# ../../../../third-party/boost/libs/regex/doc/html/boost_regex/syntax.html +# Boost regular expression\endlink describing a pattern that +# could occur in the source code. The pattern can match +# multiple-line substrings in the source file. Double-quote +# if you want it to include leading or trailing spaces. +# - is the string that should replace source code +# substrings that match . This can be a multiple-line +# string. Double-quote if you want it to include +# leading or trailing spaces. +# - is a process modifier, corresponding to a Boost regular +# expression syntax option or flag as shown below. # -# \link ../../../../third-party/boost/libs/regex/doc/syntax_option_type.html +# \link ../../../../third-party/boost/libs/regex/doc/html/boost_regex/ref/syntax_option_type.html # Boost regular expression syntax option\endlink correspondences: # # \code # -M no_mod_m @@ -427,9 +775,9 @@ # T no_intervals # X mod_x # \endcode # -# \link ../../../../third-party/boost/libs/regex/doc/match_flag_type.html +# \link ../../../../third-party/boost/libs/regex/doc/html/boost_regex/ref/match_flag_type.html # Boost regular expression match flag\endlink correspondences: # # \code # a match_not_bob @@ -460,60 +807,55 @@ # Parameter SOURCE_REPLACEMENT # Parameter SOURCE_MODIFIERS # # Purpose -# Provide an alternative to \link #SOURCE_PATTERN_REPLACEMENT -# SOURCE_PATTERN_REPLACEMENT\endlink for specifying regular -# expression based replacements in the source code: +# Provide an alternative to \param SOURCE_PATTERN_REPLACEMENT for +# specifying regular expression based replacements in the source +# code: # -# SOURCE_PATTERN corresponds to the part of a -# SOURCE_PATTERN_REPLACEMENT expression +# \tt SOURCE_PATTERN corresponds to the part of a +# \tt SOURCE_PATTERN_REPLACEMENT expression # -# SOURCE_REPLACEMENT corresponds to the part of a -# SOURCE_PATTERN_REPLACEMENT expression +# \tt SOURCE_REPLACEMENT corresponds to the part of a +# \tt SOURCE_PATTERN_REPLACEMENT expression # -# SOURCE_MODIFIERS corresponds to the + part of a -# SOURCE_PATTERN_REPLACEMENT expression +# \tt SOURCE_MODIFIERS corresponds to the + part of a +# \tt SOURCE_PATTERN_REPLACEMENT expression # # Type -# SOURCE_PATTERN : \link -# ../../../../third-party/boost/libs/regex/doc/syntax.html +# \tt SOURCE_PATTERN : \link +# ../../../../third-party/boost/libs/regex/doc/html/boost_regex/syntax.html # Boost regular expression\endlink # -# SOURCE_REPLACEMENT : string +# \tt SOURCE_REPLACEMENT : string # -# SOURCE_MODIFIERS : one or modifiers as described in the entry for -# \link #SOURCE_PATTERN_REPLACEMENT -# SOURCE_PATTERN_REPLACEMENT\endlink. +# \tt SOURCE_MODIFIERS : one or modifiers as described in the entry for +# \param SOURCE_PATTERN_REPLACEMENT. # # Notes # For the sake of execution order, a replacement specified with -# these parameters is treated as a \link -# #SOURCE_PATTERN_REPLACEMENT -# SOURCE_PATTERN_REPLACEMENT\endlink whose position in the +# these parameters is treated as a \param +# SOURCE_PATTERN_REPLACEMENT whose position in the # execution order depends on the position of the following -# SOURCE_PATTERN entry (or the end of the file, if there is no such +# \tt SOURCE_PATTERN entry (or the end of the file, if there is no such # following entry). # -# A SOURCE_REPLACEMENT entry is associated with the -# most-recently-seen SOURCE_PATTERN not already associated with a -# SOURCE_REPLACEMENT. +# A \tt SOURCE_REPLACEMENT entry is associated with the +# most-recently-seen \tt SOURCE_PATTERN not already associated with a +# \tt SOURCE_REPLACEMENT. # -# A SOURCE_REPLACEMENT or SOURCE_MODIFIERS entry with which no -# SOURCE_PATTERN can be associated is ignored with a warning. +# A \tt SOURCE_REPLACEMENT or \tt SOURCE_MODIFIERS entry with which no +# \tt SOURCE_PATTERN can be associated is ignored with a warning. # -# A SOURCE_PATTERN with which no SOURCE_REPLACEMENT can be +# A \tt SOURCE_PATTERN with which no \tt SOURCE_REPLACEMENT can be # associated will associated with the empty string as its source # replacement # -# A SOURCE_PATTERN with which no SOURCE_MODIFIERS can be +# A \tt SOURCE_PATTERN with which no \tt SOURCE_MODIFIERS can be # associated will asssumed to have no modifiers. # -# See the entry for \link #SOURCE_PATTERN_REPLACEMENT -# SOURCE_PATTERN_REPLACEMENT\endlink for more information, including -# an example. - - +# See the entry for \param SOURCE_PATTERN_REPLACEMENT for +# more information, including an example. # Parameter SOURCE_REPLACE_COMMAND # @@ -532,15 +874,14 @@ # specifies that all strings consisting of "@" followed by zero or # more spaces followed by a hexadecimal number should be replaced by a # comment reading "/* CSURF: At removed */" # -# You can specify as many SOURCE_REPLACE_COMMAND entries as you +# You can specify as many \tt SOURCE_REPLACE_COMMAND entries as you # want: replacements will be carried out in the same order that the # entries are specified. # -# All SOURCE_REPLACE_COMMANDs will be carried out before all \link -# #SOURCE_PATTERN_REPLACEMENT -# SOURCE_PATTERN_REPLACEMENTs\endlink. +# All \tt SOURCE_REPLACE_COMMANDs will be carried out before all \param +# SOURCE_PATTERN_REPLACEMENT. # # Type # A string corresponding to a command that reads from stdin and # writes to stdout. @@ -548,9 +890,9 @@ # Purpose # Specifies whether or not preprocessed versions of compilation # units containing parse errors will be saved. # -# Note +# Notes # If environment variable CS_PREPROCESS_IF_FAIL is set, its value will # override the setting of this parameter. PREPROCESS_IF_FAIL = No @@ -557,36 +900,289 @@ # Purpose # Specifies whether or not preprocessed versions of all compilation units # will be saved. # -# Note +# Notes # If environment variable CS_PREPROCESS_ALWAYS is set, its value will # override the setting of this parameter. PREPROCESS_ALWAYS = No + +# Parameter HOOK_LOG +# +# Purpose +# Log all process invocations inside a hook, hook-build, hook-html, +# or hook-start sub-command. A (very) poor man's strace/truss. +# +# Notes +# This parameter has no effect on Windows. +# +# If environment variable CS_HOOK_LOG is set, its value will +# override the setting of this parameter. +# +# For example: +# \code +# HOOK_LOG = /PATH/TO/log_file +# \endcode + + # Parameter FATSTATS_DUMP_FILE # # Purpose # Specifies an output file for certain diagnostic information. # -# Note +# Notes # If environment variable FATSTATS_DUMP_FILE is set, its value will # override the setting of this parameter. -# -# FATSTATS_DUMP_FILE = /PATH/TO/dump_file +# +# For example: +# \code +# FATSTATS_DUMP_FILE = /PATH/TO/dump_file +# \endcode +# Parameter HUB_ADDRESS +# +# Behavior +# Specifies the hub address CodeSonar should use. +# +# Notes +# This is ignored by the Windows project builder GUI. +# +# If an address is specified on the command line, then it takes +# precedence. Setting this in template.conf affects the hub-start, +# hub-stop, hub-info, hook, and hook-html commands. Setting this in +# any other conf file will affect only hook and hook-html commands +# using that conf file. A conf file setting will take precedence +# over the CODESONAR_HUB environment variable. +# +# For example: +# \code +# HUB_ADDRESS = 127.0.0.1:7340 +# \endcode +# +# Type +# String of the form : + +# Parameter USE_SERVICES +# +# Purpose +# [Windows only] Specifies whether or not CodeSonar hub and launch +# daemon processes will be created as Windows services. +# # Behavior -# If set to No, then warnings will not be produced just because +# If "Yes", any new hub or launch daemon started by "codesonar hook" +# or "codesonar hook-html" will be created as a Windows service. +# +# If "No", Windows will kill hub processes and launch daemons when +# the user logs out, unless the processes are started from the Scheduled +# Tasks panel or by another windows service. +# +# Notes +# This variable is ignored by the Windows project builder GUI. +# +# This variable has no effect on non-windows systems. +# +# Type +# {Yes, No} +# + +# USE_SERVICES = Yes + + +# Parameter SPAWN_HUB +# +# Purpose +# Specifies whether or not "codesonar hook" or "codesonar hook-html" +# will create a new hub if the hub is not already running. +# +# Notes +# This variable is ignored by the Windows project builder GUI. +# +# If unspecified, then CodeSonar will be willing to spawn a hub only +# if no hub address is specified on the command line or through the +# CODESONAR_HUB environment variable. This default behavior was +# selected for backwards compatibility with CodeSonar 2.0. +# +# Type +# {Yes, No} +# + +# SPAWN_HUB = No + + +# Parameter FOREGROUND +# +# Purpose +# Specifies whether or not a "codesonar hook-html" command will run the +# analysis in the codesonar hook-html process itself. +# +# Type +# {Yes, No} +# +# Behavior +# If "Yes", the "codesonar hook-html" command runs the analysis itself. +# +# If "No", a separate background process runs the analysis after control +# returns to the shell. +# +# Notes +# This variable is ignored by the Windows project builder GUI. +# +# The "CodeSonar Analysis Log" in the web GUI will not be populated +# when this is set to Yes. Instead, the log will show up on the +# hook-html command's stdout and stderr. By default, analysis +# processes run in the background and can continue running after the +# user has logged out. +# + +# FOREGROUND = No + + +# Parameter WARNING_FILTER +# +# Behavior +# Allows warnings to be modified before they are submitted to the +# hub, or discarded entirely without being submitted. +# +# Type +# Zero or more patterns, each consisting of an followed by +# one or more s. +# +# is one of: +# - discard (warnings matching the rules will be discarded instead of +# being submitted to the hub). +# - allow (warnings matching the rules will be submitted to the hub, +# even if they matched a previous "discard") +# - priority:= (warnings matching the rules will have their +# Priority set to before being submitted to the hub. If +# is not a legal priority value on the hub, the hub will +# be updated to add to the list of priority values.) +# - owner:= (warnings matching the rules will have their Owner set +# to before being submitted to the hub. If is not +# an active user on the hub, the pattern has no effect) +# +# is one of: +# - class +# - categories +# - file +# - rank= +# - procedure +# - procedure_typed +# - line= +# - path_listing +# - preconditions +# - postconditions +# - compilation_unit +# - language +# +# and is one of: +# - : (substring match) +# - = (exact match) +# +# Notes +# If there are two or more s in a pattern, the pattern +# will be applied to warnings that match ALL of the rules. +# +# If \tt WARNING_FILTER settings specify that all warnings of a specific +# class should be discarded (with no exceptions from subsequent +# "allow" patterns"), CodeSonar will not even carry out checks for +# that class. This will generally lead to time savings. +# +# For example: +# \code +# WARNING_FILTER += discard class="Accept on socket in wrong state" +# WARNING_FILTER += discard class="Bind on socket in wrong state" +# WARNING_FILTER += discard class="Buffer Overrun" +# WARNING_FILTER += discard class="Buffer Underrun" +# WARNING_FILTER += discard class="Cast Alters Value" +# WARNING_FILTER += discard class="Connect on socket in wrong state" +# WARNING_FILTER += discard class="Dangerous Function Cast" +# WARNING_FILTER += discard class="Division By Zero" +# WARNING_FILTER += discard class="Double Close" +# WARNING_FILTER += discard class="Double Free" +# WARNING_FILTER += discard class="Double Lock" +# WARNING_FILTER += discard class="Double Unlock" +# WARNING_FILTER += discard class="Empty Branch Statement" +# WARNING_FILTER += discard class="Empty if Statement" +# WARNING_FILTER += discard class="Empty switch Statement" +# WARNING_FILTER += discard class="Empty while Statement" +# WARNING_FILTER += discard class="Excessive Stack Depth" +# WARNING_FILTER += discard class="File System Race Condition" +# WARNING_FILTER += discard class="Format String" +# WARNING_FILTER += discard class="Free Non-Heap Variable" +# WARNING_FILTER += discard class="Free Null Pointer" +# WARNING_FILTER += discard class="Function Call Has No Effect" +# WARNING_FILTER += discard class="Ignored Return Value" +# WARNING_FILTER += discard class="Leak" +# WARNING_FILTER += discard class="Listen on socket in wrong state" +# WARNING_FILTER += discard class="Missing Return Statement" +# WARNING_FILTER += discard class="Negative Shift Amount" +# WARNING_FILTER += discard class="Negative file descriptor" +# WARNING_FILTER += discard class="Null Pointer Dereference" +# WARNING_FILTER += discard class="Null Test After Dereference" +# WARNING_FILTER += discard class="Potential Unbounded Loop" +# WARNING_FILTER += discard class="Recv on socket in wrong state" +# WARNING_FILTER += discard class="Recv_from on socket in wrong state" +# WARNING_FILTER += discard class="Recvmsg on socket in wrong state" +# WARNING_FILTER += discard class="Redundant Condition" +# WARNING_FILTER += discard class="Return Pointer to Freed" +# WARNING_FILTER += discard class="Return Pointer to Local" +# WARNING_FILTER += discard class="Scope Could Be File Static" +# WARNING_FILTER += discard class="Scope Could Be Local Static" +# WARNING_FILTER += discard class="Send on socket in wrong state" +# WARNING_FILTER += discard class="Shift Amount Exceeds Bit Width" +# WARNING_FILTER += discard class="Try-lock that will never succeed" +# WARNING_FILTER += discard class="Type Overrun" +# WARNING_FILTER += discard class="Type Underrun" +# WARNING_FILTER += discard class="Unchecked Parameter Dereference" +# WARNING_FILTER += discard class="Uninitialized Variable" +# WARNING_FILTER += discard class="Unreachable Code" +# WARNING_FILTER += discard class="Unused Value" +# WARNING_FILTER += discard class="Use After Free" +# WARNING_FILTER += discard class="Useless Assignment" +# WARNING_FILTER += discard class="Varargs Function Cast" +# WARNING_FILTER += discard class="access After Open" +# WARNING_FILTER += discard class="alloca Buffer Length Unreasonable" +# WARNING_FILTER += discard class="bcopy Length Unreasonable" +# WARNING_FILTER += discard class="calloc Object Length Unreasonable" +# WARNING_FILTER += discard class="chmod After Open" +# WARNING_FILTER += discard class="chown After Open" +# WARNING_FILTER += discard class="delete Object Created by malloc" +# WARNING_FILTER += discard class="delete Object Created by new[]" +# WARNING_FILTER += discard class="delete[] Object Created by malloc" +# WARNING_FILTER += discard class="delete[] Object Created by new" +# WARNING_FILTER += discard class="free Object Created by new" +# WARNING_FILTER += discard class="free Object Created by new[]" +# WARNING_FILTER += discard class="malloc Buffer Length Unreasonable" +# WARNING_FILTER += discard class="memccpy Length Unreasonable" +# WARNING_FILTER += discard class="memccpy With Overlapping Regions" +# WARNING_FILTER += discard class="memcpy Length Unreasonable" +# WARNING_FILTER += discard class="memcpy With Overlapping Regions" +# WARNING_FILTER += discard class="realloc Buffer Length Unreasonable" +# WARNING_FILTER += discard class="stat After Open" +# WARNING_FILTER += discard class="strcpy With Overlapping Regions" +# WARNING_FILTER += discard class="strncpy Does Not Null-terminate" +# WARNING_FILTER += discard class="strncpy Length Unreasonable" +# WARNING_FILTER += discard class="strncpy With Overlapping Regions" +# \endcode + + +# Type +# {Yes, No} +# +# Behavior +# If set to "No", then warnings will not be produced just because # conditionals along a path imply unsafe behavior due to equality # (==) or disequality (!=); satisfying assignments to the variables # must also exist. # # Notes -# Setting this to No will decrease the false positive rate and -# increase the false negative rate. If set to "No", then the following -# would be suppressed (assuming CodeSonar does not find a place where -# p is assigned NULL): +# Setting this to "No" will decrease the false positive rate and +# increase the false negative rate. +# +# If set to "No", then the following would be suppressed (assuming +# CodeSonar does not find a place where p is assigned NULL): # # \code # if( p == NULL ) # *p = 42; @@ -600,30 +1196,36 @@ # *p = 42; # \endcode # # It may be difficult to find vulnerabilities in functions that are -# never called when this is set to No, since the values of the +# never called when this is set to "No", since the values of the # procedure inputs are never assigned. # -# This is set to Yes by default because most programmers will not +# This is set to "Yes" by default because most programmers will not # test for equality unless they believe it can happen. # -# Type -# {Yes, No} +# The warning classes affected by this parameter are the same as those for +# \param TIME_LIMIT_INTRA_CLASSIFY. # REPORT_IMPLIED_EQUALITY = Yes + # Behavior -# If set to No, then warnings will not be produced just because +# If set to "No", then warnings will not be produced just because # conditionals along a path imply unsafe behavior due to inequality # (<, <=, >, >=); satisfying assignments to the variables must also # exist. # +# Type +# {Yes, No} +# # Notes -# Setting this to No will decrease the false positive rate and -# increase the false negative rate. If set to No, then the following -# would be suppressed (assuming CodeSonar does not find a place where -# i is assigned a negative value): +# Setting this to "No" will decrease the false positive rate and +# increase the false negative rate. +# +# If set to "No", then the following would be suppressed (assuming +# CodeSonar does not find a place where i is assigned a negative +# value): # # \code # int A[10]; # if( i < 0 ) @@ -639,19 +1241,20 @@ # A[i] = 42; # \endcode # # It may be difficult to find vulnerabilitiess in functions that are -# never called when this is set to No, since the values of the +# never called when this is set to "No", since the values of the # procedure inputs are never assigned. # -# This is set to No by default because loops often have conditions +# This is set to "No" by default because loops often have conditions # that are always satisfied on the first iteration. # -# Type -# {Yes, No} +# The warning classes affected by this parameter are the same as those for +# \param TIME_LIMIT_INTRA_CLASSIFY. # REPORT_IMPLIED_INEQUALITY = No + # Purpose # Seconds of inactivity before the analysis daemon shuts down to # conserve system resources. # @@ -688,12 +1292,14 @@ # integer # CONSTANT_CACHE_CAPACITY = 16 + # Purpose # Megabytes of memory to allocate for hotlinkable tokens when # rendering source code. This is a hard limit that will not be -# exceeded wheras TOKEN_RENDERER_BACKOFF_CAPACITY may be exceeded. +# exceeded wheras \param TOKEN_RENDERER_BACKOFF_CAPACITY may be +# exceeded. # # Type # integer # @@ -698,11 +1304,12 @@ # integer # TOKEN_RENDERER_CAPACITY = 64 + # Purpose # Megabytes of memory to allocate for hotlinkable tokens before -# enforcing the TOKENS_PER_LINE limit. +# enforcing the \param TOKENS_PER_LINE limit. # # Notes # Exceeding this limit may result in unlinked tokens. Using two # limits prevents a single pathological line from obliterating all @@ -712,12 +1319,13 @@ # integer # TOKEN_RENDERER_BACKOFF_CAPACITY = 32 + # Purpose -# Once TOKEN_RENDERER_BACKOFF_CAPACITY is exceeded, the number of -# hotlinkable tokens for a single line will not be allowed to exceed -# this value. +# Once \param TOKEN_RENDERER_BACKOFF_CAPACITY is exceeded, the number +# of hotlinkable tokens for a single line will not be allowed to +# exceed this value. # # Type # integer # @@ -727,12 +1336,12 @@ # Whether the analysis will run anyway if there were errors parsing # the code. # # Behavior -# If set to No, then the analysis will refuse to run on a project +# If set to "No", then the analysis will refuse to run on a project # that contains parse errors. Analyzing code that contains parse # errors produces suboptimal results. Depending on the nature of the -# parse errors, the impact could be negligable or earth-shattering. +# parse errors, the impact could be tiny or enormous. # # Notes # A log of parse errors and compiler command lines can be found at # .prj_files/log.txt. @@ -772,16 +1383,21 @@ # required before reporting warnings in classes for which something # must hold on all paths. # # Behavior -# If set to Yes, then unreachable code, redundant condition, null test -# after dereference, and other warning classes requiring universal +# If set to "Yes", then warnings of classes requiring universal # quantification over paths will be reported on statements preceded # by calls to functions that have not been exhaustively explored. # The default behavior is to suppress such warnings. +# The affected warning classes are: +# - Null Test After Dereference +# - Redundant Condition +# - Unreachable Code +# - Unused Value +# - Useless Assignment # # Notes -# Setting this to Yes will increase the false positive rate and +# Setting this to "Yes" will increase the false positive rate and # decrease the false negative rate for warning classes requiring # universal quantification over paths. # # Type @@ -788,24 +1404,25 @@ # {Yes, No} # REPORT_INTER_PARTIAL_UQ_WARNINGS = No + # Purpose # Determines whether exhaustive exploration is required before -# issuing a `null test after dereference' warning. +# issuing a "Null Test After Dereference" warning. # # Behavior -# If set to Yes, then Null Test After Dereference warnings will be +# If set to "Yes", then Null Test After Dereference warnings will be # issued even if all paths leading to the test have not been # explored. Null Test After Dereference are only an anomaly if all # paths leading to the test have dereferenced the pointer. # # Notes -# Setting this to Yes will increase the false positive rate and +# Setting this to "Yes" will increase the false positive rate and # decrease the false negative rate for Null Test After Dereference # warnings. # -# In practice, setting this to Yes usually reveals more true +# In practice, setting this to "Yes" usually reveals more true # positives than false positives. # # Type # {Yes, No} @@ -823,10 +1441,16 @@ # # Notes # On Windows, this specifies elapsed time. On unix and linux, this # specifies a limit on user+system time. The default limit is -# unlikely to expire using the default value for SEARCH_BOUND. +# unlikely to expire using the default value for \param SEARCH_BOUND. # +# This parameter affects checks for most warning classes. The classes +# NOT affected are: +# - Dangerous Function Cast +# - Empty {Branch, if, switch, while} Statement +# - Function Call Has No Effect +# - Varargs Function Cast # Type # integer # TIME_LIMIT_INTRA_EXPLORE = 25 @@ -847,8 +1472,24 @@ # On Windows, this specifies elapsed time. On unix and linux, this # specifies a limit on user+system time. The default value for this # preference is likely to expire in large procedures. # +# This parameter affects checks for most warning classes. The classes +# NOT affected are: +# - Dangerous Function Cast +# - Empty {Branch, if, switch, while} Statement +# - Format String +# - Function Call Has No Effect +# - Ignored Return Value +# - Leak +# - Null Test After Dereference +# - Potential Unbounded Loop +# - Redundant Condition +# - Unreachable Code +# - Unused Value +# - Useless Assignment +# - Varargs Function Cast +# # Type # integer # TIME_LIMIT_INTRA_CLASSIFY = 8 @@ -869,8 +1511,11 @@ # On Windows, this specifies elapsed time. On unix and linux, this # specifies a limit on user+system time. The default value for this # preference is very likely to expire in large procedures. # +# The warning classes affected by this parameter are the same as those for +# \param TIME_LIMIT_INTRA_CLASSIFY. +# # Type # integer # TIME_LIMIT_INTER_CLASSIFY = 8 @@ -889,20 +1535,24 @@ # specifies a limit on user+system time. The default limit is # extremely unlikely to expire and exists to guard against # pathological behavior. # +# The warning classes affected by this parameter are the same as those for +# \param TIME_LIMIT_INTRA_CLASSIFY. +# # Type # integer # -TIME_LIMIT_RESOLVE = 60 +TIME_LIMIT_RESOLVE = 16 + # Purpose # Seconds the analysis may spend refining potential intra- and # interprocedural vulnerabilities, per procedure. # # Behavior # Once likely vulnerabilities have been identified in the -# classificition phase, the analysis applies a refinement step both +# classification phase, the analysis applies a refinement step both # to eliminate false positives and to enhance the information # contained in the warning reports. If this limit expires, then # yet-to-be-refined likely vulnerabilities will be dropped. # @@ -911,12 +1561,16 @@ # specifies a limit on user+system time. The default limit is # unlikely to expire and exists to guard against pathological # behavior. # +# The warning classes affected by this parameter are the same as those for +# \param TIME_LIMIT_INTRA_CLASSIFY. +# # Type # integer # -TIME_LIMIT_REFINE = 60 +TIME_LIMIT_REFINE = 16 + # Purpose # Seconds the analysis may spend determining whether potential # leaks warrant further examination, per procedure. @@ -927,9 +1581,9 @@ # # Notes # On Windows, this specifies elapsed time. On unix and linux, this # specifies a limit on user+system time. The default limit is -# unlikely to expire using the default value for SEARCH_BOUND. +# unlikely to expire using the default value for \param SEARCH_BOUND. # # Type # integer # @@ -956,16 +1611,18 @@ # integer # TIME_LIMIT_LEAK_REFINE = 60 + # Behavior -# If set to Yes, then summaries for a function will be rolled back -# if TIME_LIMIT_INTRA_EXPLORE expires. If this happens, call sites -# to the function will be treated like any other undefined function. +# If set to "Yes", then summaries for a function will be rolled back if +# \param TIME_LIMIT_INTRA_EXPLORE expires. If this happens, call +# sites to the function will be treated like any other undefined +# function. # # Notes -# Setting this to No can cause false positives and false negatives. -# Setting this to Yes can cause (a different set of) false positives +# Setting this to "No" can cause false positives and false negatives. +# Setting this to "Yes" can cause (a different set of) false positives # and false negatives. # # Type # {Yes, No} @@ -1019,15 +1679,30 @@ # {Yes, No} # REPORT_SIMILAR_WARNINGS = Yes + # Purpose -# Controls the number of similar paths (paths with the same start and -# end points) the CodeSonar window will display. +# Can influence the number of instances with similar paths that will +# be generated for a single warning. # # Notes -# Does not affect performance significantly. See also: -# CLUSTER_WARNINGS_ONLY_BY_ENDPOINT +# "Similar paths" are paths with the same start and end points. +# For example, suppose you had the following code. +# \code +# int *p = 0; +# if( x ) +# x = 1; +# else +# x = 2; +# *p = 42; +# \endcode +# To see Null Pointer Dereference paths through both branches of the +# conditional statement, set \tt MAX_SIMILAR_PATHS to 2 (or higher). +# +# Most users will never need a setting higher than 1 +# +# This parameter does not significantly affect performance. # # Type # integer # @@ -1087,16 +1765,20 @@ # specifies how many levels up the call graph interprocedural checks # on global variables can be propagated. # # Notes -# A value of 2 is recommended for large projects (hundreds of -# thousands of lines, or a large number of global and static -# variables). +# Most interprocedural warnings tend to be caused by bad parameter +# values, not bad values in global variables. Many users will find +# that setting this to 0 will have little or no effect on their +# results and a appreciable effect on analysis performance. A value +# of 2 is recommended for users who want to check for bad values in +# global variables crossing procedure boundaries. # # Type # integer # -MAX_GLOBAL_CHECK_AGE = 2 +MAX_GLOBAL_CHECK_AGE = 0 + # Purpose # Maximal complexity of an expression in an interprocedural check. # @@ -1173,12 +1858,13 @@ # integer # MAX_MODIFIED_VALUES = 100 + # Purpose # At least this many heeded calls to a given function must be seen # before the sample is considered large enough to warn the user -# about. +# about an Ignored Return Value for that function. # # Behavior # A smaller positive value will cause more warnings. A nonpositive # value disables the checking of sample sizes, with the effect that @@ -1205,12 +1892,13 @@ # real number # RETURN_CHECKER_RATIO = 0.04 + # Purpose # At least this many calls to a given function with a format string # in some fixed argument position must be seen before the sample is -# considered large enough to warn the user about. +# considered large enough to warn the user about Format String problems. # # Behavior # A smaller positive value will cause more warnings. A nonpositive # value disables the checking of sample sizes, with the effect that @@ -1289,83 +1981,74 @@ # {Yes, No} # ABRIDGE_HTML = Yes -# Purpose -# Determines how many instances of each included file will be present -# in the HTML output. -# -# Behavior -# If Yes: the HTML output will include one copy of each .h file in -# the project, no matter how many times it may be included by other -# project files. -# -# If No: the HTML output will include a separate copy of filename.h -# for each #include filename.h directive in the project, making the -# size of the output quadratic instead of linear. This preference -# should only be set to 'no' on the smallest of projects (1000 -# lines). CodeSonar will run out of memory if this is set to 'no' on -# a project of significant size. -# -# Notes -# This preference only affects the HTML output, not the CodeSonar -# analysis. There are two issues to consider: -# -# If the same text is included each time the same file is included, -# this preference should always be set to Yes. -# -# On the other hand, if constructs such as #IFDEF...#ENDIF are used -# to cause one set of definitions to be included in one place and a -# different set in a second place, the HTML output may be easier to -# interpret if this preference is set to No. If it is set to Yes in -# this situation, only one of the include file instances and its -# definitions will be selected for inclusion in the HTML output; this -# means locations that use items from a different instance may not be -# linked to the correct definitions, and syntax coloring may not be -# correct. -# -# The same CodeSonar analysis takes place in either case. -# -# Type -# {Yes, No} -# -COLLAPSE_SOURCE = Yes # Purpose -# Causes CodeSonar to detect globals that could be file/local statics -# and file statics that could be local statics. +# Specifies whether or not CodeSonar will perform checks for the +# "Scope Could Be Local Static" and "Scope Could Be File Static" +# warning classes. # # Type # {Yes, No} # +# Behavior +# When set to "Yes", CodeSonar will issue "Scope Could Be Local +# Static" warnings when it detects global or file static variables +# that could be local static, and "Scope Could Be File Static" +# warnings hen it detects global variables that could be file +# static. +# +# When set to "No", CodeSonar will not carry out these checks. +# CHECK_MINSCOPE = No + # Purpose -# Check that stack depth does not exceed STACK_DEPTH_THRESHOLD. -# +# Specifies whether or not CodeSonar will perform checks for the +# "Excessive Stack Depth" warning class. +# # Type # {Yes, No} # +# Behavior +# When set to "Yes", CodeSonar will issue "Excessive Stack Depth" +# warnings when the call stack depth exceeds the value specified by +# \param STACK_DEPTH_THRESHOLD. +# +# When set to "No", CodeSonar will not issue any "Excessive Stack +# Depth" warnings. CHECK_STACK_DEPTH = No + # Purpose -# Generate a warning report if the maximum stack depth exceeds this -# threshold. +# Specifies the call stack depth, in bytes, beyond which an "Excessive Stack +# Depth" warning will be issued. # # Type # integer # +# Behavior +# When \param CHECK_STACK_DEPTH is set to "Yes", CodeSonar will issue +# a warning report if the maximum call stack depth exceeds this +# threshold. Otherwise, this parameter has no effect. STACK_DEPTH_THRESHOLD = 65536 + # Purpose # Estimate the activation record size for undefined functions for -# the purpose of measuring the stack depth. +# the purpose of measuring the call stack depth. # # Type # integer # +# Behavior +# When \param CHECK_STACK_DEPTH is set to "Yes", CodeSonar will treat +# calls to undefined functions as contributing this many bytes to the +# call stack depth. Otherwise, this parameter has no effect. STACK_DEPTH_UNDEFINED_FUNCTION_SIZE = 128 + # Purpose # Estimate the word size to which a compiler will pad individual # variables. # @@ -1368,51 +2051,92 @@ # Purpose # Estimate the word size to which a compiler will pad individual # variables. # +# Type +# integer +# +# Behavior +# When \param CHECK_STACK_DEPTH is set to "Yes", CodeSonar will treat +# variables as being padded to a multiple of this many bytes when +# determining their contribution to the call stack depth. +# # For example, on a 4-byte word-aligned system, four bytes will # be allocated by the declaration 'char c', even though only one # byte is used. # -# Type -# integer -# +# When \param CHECK_STACK_DEPTH is set to "No", this parameter has no +# effect. STACK_DEPTH_COMPILER_PADDING = 4 + # Purpose -# Estimate the constant elements the compiler pushes on the stack +# Estimate the constant elements the compiler pushes on the call stack # for each activation record. # -# For example, the return address is stored on the stack for every -# activation record. -# # Type # integer # +# Behavior +# When \param CHECK_STACK_DEPTH is set to "Yes", CodeSonar will treat +# every activation record pushed on the call stack as if it +# contributes this many bytes of constant elements to the call stack +# depth. +# +# For example, the return address is stored on the call stack for every +# activation record. +# +# When \param CHECK_STACK_DEPTH is set to "No", this parameter has no +# effect. STACK_DEPTH_ACTIVATION_RECORD_CONSTANTS = 12 + # Purpose -# Loops without obvious bounds will be flagged. This is useful for -# embedded systems where infinite loops are extremely dangerous. +# Specifies whether or not CodeSonar will perform checks for the +# "Potential Unbounded Loop" warning class. # # Type # integer -# +# +# Behavior +# When set to "Yes", CodeSonar will issue "Potential Unbounded Loop" +# warnings when it cannot identify loop bounds. This is useful for +# embedded systems where infinite loops can be extremely dangerous. +# +# When set to "No", CodeSonar will not issue any "Potential +# Unbounded Loop" warnings. CHECK_UNBOUNDED_LOOPS = No + # Purpose -# Function parameters that are dereferenced without first being -# checked for nullness will be flagged if this is set to yes. +# Specifies whether or not CodeSonar will perform checks for the +# "Unchecked Parameter Dereference" warning class. # # Type # {Yes, No} # +# Behavior +# When set to "Yes", CodeSonar will issue "Unchecked Parameter +# Dereference" warnings when function parameters are dereferenced +# without first being checked for nullness. +# +# When set to "No", CodeSonar will not issue any "Unchecked Parameter +# Dereference" warnings. CHECK_PARAM_DEREFS = No + # Purpose -# Conditional statements with empty bodies will be detected if this -# option is set to Yes. This check will be disabled if it is set -# to No +# Specifies whether or not CodeSonar will check for conditional +# statements with empty bodies. +# +# Behavior +# If "Yes", CodeSonar will carry out checks for the following warning classes: +# - Empty Branch Statement +# - Empty if Statement +# - Empty switch Statement +# - Empty while Statement +# +# If "No", these checks will not be carried out. # # Type # {Yes, No} # @@ -1426,70 +2151,45 @@ # {Yes, No} # EMIT_PROCEDURE_SIDE_EFFECTS = No + # Purpose -# Indicates whether unused values of the form +# Specifies whether or not CodeSonar will issue "Unused Value" warnings +# for values that arise from constant assignments. +# +# Type +# {Yes, No} +# +# Behavior +# If "Yes", CodeSonar will issue "Unused Value" warnings in cases like: # \code # x = 3; # \endcode -# should be reported as Unused Value. # -# Type -# {Yes, No} +# If "No", such cases will not trigger "Unused Value" warnings. # REPORT_UNUSED_ASSIGNMENTS_FROM_CONSTANTS = No + # Purpose -# Indicates whether conditions testing constant values should be -# reported as Redundant Conditions. Example: -# +# Specifies whether or not CodeSonar will issue "Redundant Condition" +# warnings for conditions testing constant values. +# +# Type +# {Yes, No} +# +# Behavior +# If "Yes", CodeSonar will issue "Redundant Condition" warnings in cases like: # \code # if ( 0 ) # ... # \endcode # -# Type -# {Yes, No} +# If "No", such cases will not trigger "Redundant Condition" warnings. # REPORT_REDUNDANT_CONDITIONS_BASED_ON_CONSTANTS = No -# Purpose -# When set to No, paths are clustered together in the HTML index if -# they have the same endpoint. Setting this to Yes raises the -# clustering criteria to both the same endpoint and the same starting -# point. Warnings with the same endpoint but different starting -# points will occupy different rows in the HTML index page instead of -# the same row when this is set to Yes. They will share a row when -# this is set to No. -# -# Notes -# Setting this to Yes can make it easier to see warnings with -# different starting points in the index. Consider the following -# example: -# -# \code -# void f( int *p ){ *p = 42; } -# void g( void ){ f( NULL ); } -# void h( void ){ f( NULL ); } -# \endcode -# -# If this were set to Yes, then both call sites to f would be -# reported as individual rows. If this is set to No, then -# CodeSonar will arbitrarily choose one call site to represent the -# row, but the other will still be accessible. Both warnings here -# have the same endpoint: *p = 42;. -# -# The summary and textual results are not affected by this variable. -# -# This is set to Yes by default because many users would never -# notice the additional entries in the "Path Length(s)" column if it -# were set to No. -# -# Type -# {Yes, No} -# -CLUSTER_WARNINGS_BY_STARTPOINT = Yes # Purpose # Tells CodeSonar that function A works like function B. # @@ -1506,9 +2206,9 @@ # is also a common task. This feature cannot be used with C++ # identifiers containing spaces. If A -> B and B -> C then A -> C. # Behavior is undefined in the presence of cycles in the map. # -# For multiple mappings, use a separate FUNCTION_MAP += statement +# For multiple mappings, use a separate \tt FUNCTION_MAP += statement # for each mapping. # # Examples # If 'fatal' caused the program to end execution, then you would do @@ -1531,15 +2231,25 @@ # String of the form "A -> B" where A and B are function names. # FUNCTION_MAP += + # Purpose -# Ignore all C++ compilation units. C++ code will not be checked. +# Specifies whether or not the CodeSonar analysis should check C++ +# compilation units. # # Type # {Yes, No} +# +# Behavior +# If "Yes", CodeSonar will ignore all C++ compilation units: C++ code +# will not be checked. +# +# If "No", CodeSonar will check both C and C++ compilation units. +# IGNORE_CPP_CODE = No + # Purpose # Specifies the maximum number of parse errors submitted to the hub # for a compilation. # @@ -1995,11 +2752,11 @@ # # Behavior # If "Yes", enum bit fields are always unsigned. # -# If "No", signedness depends on the signedness and size of -# the values of the enum and defaults to the signedness -# indicated by TARG_NONNEGATIVE_ENUM_BIT_FIELD_IS_UNSIGNED. +# If "No", signedness depends on the signedness and size of the +# values of the enum and defaults to the signedness indicated by +# \param CS_TARG_NONNEGATIVE_ENUM_BIT_FIELD_IS_UNSIGNED. # # Notes # This parameter needs to be set to "No" to allow fully-standard C++. # @@ -2013,10 +2771,10 @@ # enumerators that could all fit in the nonnegative range of the bit # field if it were signed. # # Notes -# This setting is ignored if TARG_ENUM_BIT_FIELDS_ARE_ALWAYS_UNSIGNED -# is set to "Yes".) +# This setting is ignored if \param +# CS_TARG_ENUM_BIT_FIELDS_ARE_ALWAYS_UNSIGNED is set to "Yes".) # # Type # {Yes, No} #