--- codesonar-3.7p0/codesonar/template.conf 2012-03-03 00:33:42.000000000 -0500 +++ codesonar-3.8p0/codesonar/template.conf 2012-11-01 23:30:03.000000000 -0400 @@ -1,601 +1,598 @@ -# For emacs: -*- Shell-script -*- -# +# For emacs: -*- Shell-script -*- +# ###################################################################### #################### CodeSonar Configuration File #################### ###################################################################### -# -# CodeSonar will use preferences defined in this file when running the -# analysis. -# -# The file must be placed at .conf, where is the -# project name. The general configuration file template is located at -# $CSONAR/codesonar/template.conf, where $CSONAR is the CodeSonar -# installation directory. -# -# -# The file format is a sequence of lines of the form: -# PREFERENCE = VALUE -# or -# PREFERENCE += VALUE -# -# - 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. -# - 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. -# -# A template configuration with default values for all preferences is -# located at $CSONAR/codesonar/template.conf, where $CSONAR is the -# CodeSonar installation. -# -# Preferences that come later in this file take precedence over -# preferences that come earlier. The += operator will treat its -# right-hand-side as a string, and append to the existing string value. -# 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 -# project preference file is treated as if it is concatenated onto the -# end of the template preference file. Any options occurring in the -# project preference file will take precedence over options specified -# in the template preference file. +# +# CodeSonar will use preferences defined in this file when running +# the analysis. +# +# The file must be placed at .conf, where is the +# project name. The general configuration file template is located +# at $CSONAR/codesonar/template.conf, where $CSONAR is the +# CodeSonar installation directory. +# +# +# The file format is a sequence of lines of the form: +# PREFERENCE = VALUE +# or +# PREFERENCE += VALUE +# +# - 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. +# - 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. +# +# A template configuration with default values for all preferences +# is located at $CSONAR/codesonar/template.conf, where $CSONAR is +# the CodeSonar installation. +# +# Preferences that come later in this file take precedence over +# preferences that come earlier. The += operator will treat its +# right-hand-side as a string, and append to the existing string +# value. 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 +# project preference file is treated as if it is concatenated onto +# the end of the template preference file. Any options occurring in +# the project preference file will take precedence over options +# specified in the template preference file. # Parameter CFLAGS_PREPEND # # Purpose -# Modify the CFLAGs being passed to the parser. +# Modify the CFLAGs being passed to the parser. +# +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis # # Type # a list of CFLAGS # # Behavior -# The parser will be passed the same CFLAGs as the real -# compiler, with these additional CFLAGs prepended. +# The parser will be passed the same CFLAGs as the real compiler, +# with these additional CFLAGs prepended. # # Notes -# Most compilers will implicitly define various preprocessor symbols -# and include directories. Unless you are using gcc (which can be -# queried for its definitions), specify those implicit definitions -# here to avoid parse errors. +# Most compilers will implicitly define various preprocessor +# symbols and include directories. Unless you are using gcc (which +# can be queried for its definitions), specify those implicit +# definitions here to avoid parse errors. # # Typically, the implicit definitions specify the CPU architecture, # the operating system, and the compiler's include directory. # # The += operator will actually prepend to this preference (in all -# other cases except \param EDG_FRONTEND_OPTIONS_PREPEND, the += -# operator appends). This means that if you have two \tt -# CFLAGS_PREPEND += statements in this file, the CFLAGS in the second -# statement will be prepended to the CFLAGS in the first statement. +# other cases except EDG_FRONTEND_OPTIONS_PREPEND, the += operator +# appends). This means that if you have two CFLAGS_PREPEND += +# statements in this file, the CFLAGS in the second statement will +# be prepended to the CFLAGS in the first statement. # CFLAGS_PREPEND += # Parameter CFLAGS_APPEND # # Purpose -# Modify the CFLAGs being passed to the parser. +# Modify the CFLAGs being passed to the parser. +# +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis # # Type # a list of CFLAGS # # Behavior -# The parser will be passed the same CFLAGs as the real -# compiler, with these additional CFLAGs appended. +# The parser will be passed the same CFLAGs as the real compiler, +# with these additional CFLAGs appended. # # Notes -# Most compilers will implicitly define various preprocessor symbols -# and include directories. If the real compiler cannot be automatically -# queried for its implicit definitions (this only works for gcc), then the -# user must specify them here to avoid parse errors. Typically, -# these flags specify the CPU architecture, the operating system, and -# the compiler's include directory. +# Most compilers will implicitly define various preprocessor +# symbols and include directories. If the real compiler cannot be +# automatically queried for its implicit definitions (this only +# works for gcc), then the user must specify them here to avoid +# parse errors. Typically, these flags specify the CPU +# architecture, the operating system, and the compiler's include +# directory. # CFLAGS_APPEND += # Parameter COMPILER_MODELS # +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis +# # Purpose -# Defines a map from compiler executable basenames to compiler models. +# 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. +# '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 +# Notes # On Windows, the file extension (which should be .exe or .com) for -# the domain is not optional. Some examples are given below. The +# 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 -# ../C_Module/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 += gcc-3.exe -> gcc -# COMPILER_MODELS += g++-3.exe -> gpp -# COMPILER_MODELS += gcc-4.exe -> gcc -# COMPILER_MODELS += g++-4.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 += ecom68.exe -> ecomppc -# COMPILER_MODELS += armcc.exe -> armcc -# COMPILER_MODELS += armcpp.exe -> armcpp -# COMPILER_MODELS += tcc.exe -> armcc -# COMPILER_MODELS += tcpp.exe -> armcpp -# COMPILER_MODELS += iccarm.exe -> iccarm -# COMPILER_MODELS += icc430.exe -> icc430 -# COMPILER_MODELS += iccm32c.exe -> iccm32c -# 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 += dcc.exe -> dcc -# COMPILER_MODELS += dplus.exe -> dcc -# 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 += ecom68 -> 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 += armcpp -> armcpp -# COMPILER_MODELS += tcc -> armcc -# COMPILER_MODELS += tcpp -> armcpp -# \endcode -# -# On Solaris, in addition to posix default models: -# \code -# COMPILER_MODELS += CC -> acpp -# \endcode +# appropriate Compilers Recognized +# [doc/html/C_Module/CompilerModels/CompilersRecognized.html] +# table. Users can also author new compiler models in Scheme, +# thereby expanding the range. +# +# Windows default models: +# 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 += gcc-3.exe -> gcc +# COMPILER_MODELS += g++-3.exe -> gpp +# COMPILER_MODELS += gcc-4.exe -> gcc +# COMPILER_MODELS += g++-4.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 += ecom68.exe -> ecomppc +# COMPILER_MODELS += armcc.exe -> armcc +# COMPILER_MODELS += armcpp.exe -> armcpp +# COMPILER_MODELS += tcc.exe -> armcc +# COMPILER_MODELS += tcpp.exe -> armcpp +# COMPILER_MODELS += iccarm.exe -> iccarm +# COMPILER_MODELS += icc430.exe -> icc430 +# COMPILER_MODELS += iccm32c.exe -> iccm32c +# 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 += dcc.exe -> dcc +# COMPILER_MODELS += dplus.exe -> dcc +# COMPILER_MODELS += null-cc.exe -> xcc +# +# Posix default models: +# 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 += ecom68 -> 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 += armcpp -> armcpp +# COMPILER_MODELS += tcc -> armcc +# COMPILER_MODELS += tcpp -> armcpp +# +# On Solaris, in addition to posix default models: +# COMPILER_MODELS += CC -> acpp # -# To activate the Hi-Tech compiler model for Linux, Solaris, and OS X: -# \code +# To activate the Hi-Tech compiler model for Linux, Solaris, and OS +# X: # COMPILER_MODELS += picc -> picc -# \endcode # -# To activate the IAR compiler models for Linux, Solaris, and OS X: -# \code +# To activate the IAR compiler models for Linux, Solaris, and OS X: # COMPILER_MODELS += iccarm -> iccarm # COMPILER_MODELS += iccm32c -> iccm32c # COMPILER_MODELS += icc430 -> icc430 -# \endcode # -# To activate the Ti CodeComposer compiler models for Linux, Solaris, -# and OS X: -# \code +# To activate the Ti CodeComposer compiler models for Linux, +# Solaris, and OS X: # COMPILER_MODELS += cl6x -> cl6x # COMPILER_MODELS += cl30 -> cl30x -# \endcode # -# To activate Wind River compilers, use the following. This will disable -# recognition of some Green Hills compilers because of an executable -# name conflict. +# To activate Wind River compilers, use the following. This will +# disable recognition of some Green Hills compilers because of an +# executable name conflict. # -# \code -# (Windows) +# (Windows) # COMPILER_MODELS += ccppc.exe -> ccppc # COMPILER_MODELS += c++ppc.exe -> c++ppc -# (other systems) +# (other systems) # COMPILER_MODELS += ccppc -> ccppc # COMPILER_MODELS += c++ppc -> c++ppc -# \endcode # # Parameter DISABLED_COMPILERS # -# Purpose +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis +# +# Purpose # Forces the project builder to ignore certain compilers that it # would, by default, notice. # # Type # Whitespace separated list of compiler basenames # -# Behavior -# Invocations of compilers listed here will be ignored by the project -# builder. -# -# Behavior is undefined if the same compiler executable appears in -# both the \param COMPILER_MODELS domain and the \tt -# DISABLED_COMPILERS set. +# Behavior +# Invocations of compilers listed here will be ignored by the +# project builder. +# +# Behavior is undefined if the same compiler executable appears in +# both the COMPILER_MODELS domain and the DISABLED_COMPILERS set. # # Notes # On Windows, always include the file extension of the executable # (which should be .exe or .com). # # A superset of the default compilers appears below. # -# Windows: -# \code -# DISABLED_COMPILERS += armcc.exe -# DISABLED_COMPILERS += armcpp.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 += dcc.exe -# DISABLED_COMPILERS += dplus.exe -# DISABLED_COMPILERS += ecom68.exe -# DISABLED_COMPILERS += ecom86.exe -# DISABLED_COMPILERS += ecomarm.exe -# DISABLED_COMPILERS += ecomppc.exe -# DISABLED_COMPILERS += ecomx86.exe -# DISABLED_COMPILERS += g++.exe -# DISABLED_COMPILERS += g++-3.exe -# DISABLED_COMPILERS += g++-4.exe -# DISABLED_COMPILERS += gcc.exe -# DISABLED_COMPILERS += gcc-3.exe -# DISABLED_COMPILERS += gcc-4.exe -# DISABLED_COMPILERS += gpp.exe -# DISABLED_COMPILERS += gxx.exe -# DISABLED_COMPILERS += iccarm.exe -# DISABLED_COMPILERS += icc430.exe -# DISABLED_COMPILERS += iccm32c.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 -# DISABLED_COMPILERS += tcpp.exe -# \endcode -# -# Posix: -# \code -# DISABLED_COMPILERS += armcc -# DISABLED_COMPILERS += armcpp -# DISABLED_COMPILERS += c++ -# DISABLED_COMPILERS += cc -# DISABLED_COMPILERS += ccppc -# DISABLED_COMPILERS += ch38 -# DISABLED_COMPILERS += c++ppc -# DISABLED_COMPILERS += dcc -# DISABLED_COMPILERS += dplus -# DISABLED_COMPILERS += ecomarm -# DISABLED_COMPILERS += ecom68 -# DISABLED_COMPILERS += ecom86 -# DISABLED_COMPILERS += ecomppc -# DISABLED_COMPILERS += ecomx86 -# DISABLED_COMPILERS += g++ -# DISABLED_COMPILERS += gcc -# DISABLED_COMPILERS += gpp -# DISABLED_COMPILERS += gxx -# DISABLED_COMPILERS += mcpcom -# DISABLED_COMPILERS += null-cc -# DISABLED_COMPILERS += shc -# DISABLED_COMPILERS += shcpp -# DISABLED_COMPILERS += armcc -# DISABLED_COMPILERS += tcc -# DISABLED_COMPILERS += tcpp -# -# \endcode +# Windows: +# DISABLED_COMPILERS += armcc.exe +# DISABLED_COMPILERS += armcpp.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 += dcc.exe +# DISABLED_COMPILERS += dplus.exe +# DISABLED_COMPILERS += ecom68.exe +# DISABLED_COMPILERS += ecom86.exe +# DISABLED_COMPILERS += ecomarm.exe +# DISABLED_COMPILERS += ecomppc.exe +# DISABLED_COMPILERS += ecomx86.exe +# DISABLED_COMPILERS += g++.exe +# DISABLED_COMPILERS += g++-3.exe +# DISABLED_COMPILERS += g++-4.exe +# DISABLED_COMPILERS += gcc.exe +# DISABLED_COMPILERS += gcc-3.exe +# DISABLED_COMPILERS += gcc-4.exe +# DISABLED_COMPILERS += gpp.exe +# DISABLED_COMPILERS += gxx.exe +# DISABLED_COMPILERS += iccarm.exe +# DISABLED_COMPILERS += icc430.exe +# DISABLED_COMPILERS += iccm32c.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 +# DISABLED_COMPILERS += tcpp.exe +# +# Posix: +# DISABLED_COMPILERS += armcc +# DISABLED_COMPILERS += armcpp +# DISABLED_COMPILERS += c++ +# DISABLED_COMPILERS += cc +# DISABLED_COMPILERS += ccppc +# DISABLED_COMPILERS += ch38 +# DISABLED_COMPILERS += c++ppc +# DISABLED_COMPILERS += dcc +# DISABLED_COMPILERS += dplus +# DISABLED_COMPILERS += ecomarm +# DISABLED_COMPILERS += ecom68 +# DISABLED_COMPILERS += ecom86 +# DISABLED_COMPILERS += ecomppc +# DISABLED_COMPILERS += ecomx86 +# DISABLED_COMPILERS += g++ +# DISABLED_COMPILERS += gcc +# DISABLED_COMPILERS += gpp +# DISABLED_COMPILERS += gxx +# DISABLED_COMPILERS += mcpcom +# DISABLED_COMPILERS += null-cc +# DISABLED_COMPILERS += shc +# DISABLED_COMPILERS += shcpp +# DISABLED_COMPILERS += armcc +# DISABLED_COMPILERS += tcc +# DISABLED_COMPILERS += tcpp +# # Parameter FORCE_ENVIRONMENT # # Purpose -# Specifies whether or not to prevent the software build system (for -# example, make) from writing over environment variables necessary -# for proper process hooking on POSIX systems. +# Specifies whether or not to prevent the software build system +# (for example, make) from writing over environment variables +# necessary for proper process hooking on POSIX systems. +# +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis # # Type # {Yes, No} # # Behavior -# Every time a process calls \tt exec, if the \tt CS_ENVIRON -# environment variable has not been written over, then any important -# environment variables (such as \tt LD_PRELOAD, \tt LD_LIBRARY_PATH) -# that have been written over will be repaired in the environment -# used to create the new process. +# Every time a process calls exec, if the CS_ENVIRON environment +# variable has not been written over, then any important +# environment variables (such as 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 +# 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 -# \tt LD_PRELOAD at some point. -# +# LD_PRELOAD at some point. +# # If your build system writes over the entire environment or the -# \tt CS_ENVIRON variable at some point, then in addition to setting -# \tt FORCE_ENVIRONMENT to "Yes", you will need to resurrect the -# \tt CS_ENVIRON environment variable to the value it had before it was +# 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 invocations to be missed. If you believe source files +# (compilation units) are missing from your project and # COMPILER_MODELS is set correctly, then setting this to "Yes" may -# help. It is slightly invasive and could conceivably cause +# help. It is slightly invasive and could conceivably cause # problems, although none have been observed. # -# The \tt CS_ENVIRON environment variable, if set, takes precedence over -# \tt FORCE_ENVIRONMENT. +# The CS_ENVIRON environment variable, if set, takes precedence +# over FORCE_ENVIRONMENT. # FORCE_ENVIRONMENT = No # Parameter UNIX_TEXT_MODE # # Purpose # Specifies whether or not to perform crlf -> lf translations on -# stdout and stderr and do the inverse on stdin. +# stdout and stderr and do the inverse on stdin. +# +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis # # Type # {Yes, No} # # Notes -# This parameter is ignored by the Windows project builder GUI and on -# non-Windows systems. +# This parameter is ignored by the Windows project builder GUI and +# on non-Windows systems. # # Setting this to "Yes" can be useful if running an interactive -# Cygwin shell inside a hook command. +# Cygwin shell inside a hook command. # -# For example: -# \code -# UNIX_TEXT_MODE = No -# \endcode - -# UNIX_TEXT_MODE = No +## UNIX_TEXT_MODE = No # Parameter INVOKE_COMPILER_FIRST # # Purpose # Specifies whether or not to invoke the real compiler before # invoking the CodeSurfer or CodeSonar parser. # +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis +# # Type # {Yes, No} # # 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 \tt #import directive. -# -# For example: -# \code -# INVOKE_COMPILER_FIRST = Yes -# \endcode - -# INVOKE_COMPILER_FIRST = Yes +# 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. +# +## INVOKE_COMPILER_FIRST = Yes # Parameter HOLD_STDIO # # Purpose # Specifies whether or not to hold the stdout, stderr, and stdin # streams open. # +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis +# # Type # {Yes, No} # # Behavior -# When this is set to "Yes", the stdout, stderr, and stdin streams -# will be kept open even after the real compiler closes them or -# exits. -# -# Notes -# Setting this to "Yes" can cause deadlock if closing one of these -# streams signals something to another process. -# -# Setting this to "Yes" can reduce the probability of exercising -# race conditions in the IAR Embedded Workbench IDE. If that IDE is -# producing the spurious and harmless error message "Error while -# running C/C++ Compiler" then setting this to "Yes" may prevent the -# message. It has also been observed that setting \param -# INVOKE_COMPILER_FIRST to "No" while running an expensive program -# in the background can prevent the error message. -# -# For example: -# \code -# HOLD_STDIO = Yes -# \endcode - -# HOLD_STDIO = No +# When this is set to "Yes", the stdout, stderr, and stdin streams +# will be kept open even after the real compiler closes them or +# exits. +# +# Notes +# Setting this to "Yes" can cause deadlock if closing one of these +# streams signals something to another process. +# +# Setting this to "Yes" can reduce the probability of exercising +# race conditions in the IAR Embedded Workbench IDE. If that IDE is +# producing the spurious and harmless error message "Error while +# running C/C++ Compiler" then setting this to "Yes" may prevent +# the message. It has also been observed that setting +# INVOKE_COMPILER_FIRST to "No" while running an expensive program +# in the background can prevent the error message. +# +## HOLD_STDIO = No # Parameter CODEWARRIOR_INSTALLS # # Purpose # Specifies CodeWarrior install directories so that compiler IDE # plug-ins can be identified for interception. # +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis +# # Type # Whitespace-separated list of directories # # Behavior # Invocations of all compiler IDE plug-ins of CodeWarrior install # directories in this list will be intercepted. # # Notes -# \link ../C_Module/CompilerModels/CompilerModelsCodeWarrior.html -# Set up CodeWarrior Support\endlink before basing a project on a -# CodeWarrior build. CodeWarrior is supported for Windows systems only. -# -# This parameter is ignored by the Windows project builder GUI and on -# non-Windows systems. -# -# To configure interception of some subset of the compiler plug-ins, -# use \param CODEWARRIOR_PLUGINS instead. If you are running from -# the command line and neither \tt CODEWARRIOR_INSTALLS nor \tt +# Set up CodeWarrior Support +# [doc/html/C_Module/CompilerModels/CompilerModelsCodeWarrior.html] +# before basing a project on a CodeWarrior build. CodeWarrior is +# supported for Windows systems only. +# +# This parameter is ignored by the Windows project builder GUI and +# on non-Windows systems. +# +# To configure interception of some subset of the compiler plug- +# ins, use CODEWARRIOR_PLUGINS instead. If you are running from the +# command line and neither CODEWARRIOR_INSTALLS nor # CODEWARRIOR_PLUGINS is specified in the template or project -# configuration file, then the settings specified at install time will -# be used. -# -# For example: -# \code -# CODEWARRIOR_INSTALLS += "C:\Program Files\Freescale\CodeWarrior for Microcontrollers V6.0" -# \endcode +# configuration file, then the settings specified at install time +# will be used. +# +# For example: +# CODEWARRIOR_INSTALLS += "C:\Program Files\Freescale\CodeWarrior for Microcontrollers V6.0" # Parameter CODEWARRIOR_PLUGINS # # Purpose -# Specifies individual CodeWarrior compiler IDE plug-ins for interception. +# Specifies individual CodeWarrior compiler IDE plug-ins for +# interception. +# +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis # # Type # Whitespace-separated list of directories # # Behavior -# Invocations of CodeWarrior compiler IDE plug-ins in this parameter -# will be intercepted. +# Invocations of CodeWarrior compiler IDE plug-ins in this +# parameter will be intercepted. # # Notes -# \link ../C_Module/CompilerModels/CompilerModelsCodeWarrior.html -# Set up CodeWarrior Support\endlink before basing a project on a -# CodeWarrior build. CodeWarrior is supported for Windows systems only. -# -# This parameter is ignored by the Windows project builder GUI and on -# non-Windows systems. -# -# To configure interception of all CodeWarrior IDE compiler plug-ins, -# 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 -# configuration file, then the settings specified at install time will -# be used. -# -# For example: -# \code -# CODEWARRIOR_PLUGINS += "C:\Program Files\Freescale\CodeWarrior for Microcontrollers V6.0\bin\plugins\compiler\MCFCCompiler.dll" -# \endcode +# Set up CodeWarrior Support +# [doc/html/C_Module/CompilerModels/CompilerModelsCodeWarrior.html] +# before basing a project on a CodeWarrior build. CodeWarrior is +# supported for Windows systems only. +# +# This parameter is ignored by the Windows project builder GUI and +# on non-Windows systems. +# +# To configure interception of all CodeWarrior IDE compiler plug- +# ins, use the CODEWARRIOR_INSTALLS parameter instead. If you are +# running from the command line and neither CODEWARRIOR_INSTALLS +# nor CODEWARRIOR_PLUGINS is specified in the template or project +# configuration file, then the settings specified at install time +# will be used. +# +# For example: +# CODEWARRIOR_PLUGINS += "C:\Program Files\Freescale\CodeWarrior for Microcontrollers V6.0\bin\plugins\compiler\MCFCCompiler.dll" # Parameter IGNORED_COMPILATIONS # # Purpose -# Specifies files whose compilations should be ignored. +# Specifies files whose compilations should be ignored. +# +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis # # Type -# A \link ../Asides/STkRegExp.html -# Scheme regular expression\endlink +# STk-style regular expression [doc/html/Asides/STkRegExp.html] # # Behavior # If a file in a compilation command has a path that matches the -# regular expression, that compilation will be ignored. +# regular expression, that compilation will be ignored. # # Notes # For example, -# \code -# IGNORED_COMPILATIONS += ^.*foo\.c$ -# \endcode +# IGNORED_COMPILATIONS += ^.*foo\.c$ # 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 \tt IGNORED_COMPILATIONS entries as you -# want. +# You can specify as many IGNORED_COMPILATIONS entries as you want. # # Note that backslashes used as directory separators need to be -# escaped, so a rule containing a Windows path will look (something) -# like the following: -# \code -# IGNORED_COMPILATIONS += bar\\foo\.c -# \endcode +# escaped, so a rule containing a Windows path will look +# (something) like the following: +# IGNORED_COMPILATIONS += bar\\foo\.c # # The forward slashes used as directory separators on other systems # do not require escaping: -# \code -# IGNORED_COMPILATIONS += bar/foo\.c -# \endcode +# IGNORED_COMPILATIONS += bar/foo\.c # # Parameter IGNORED_COMPILATION_COMMANDS # # Purpose # Specifies compilation commands that should be ignored. -# +# +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis +# # Type # string # # Behavior -# Ignore compilation command lines matching the specified string. +# Ignore compilation command lines matching the specified string. # # 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. +# This can be significantly faster than using IGNORED_COMPILATIONS, +# but is not as precise. IGNORED_COMPILATIONS could ignore foo.c +# and not bar.c in the command "gcc -c foo.c bar.c", but +# IGNORED_COMPILATION_COMMANDS must either accept the entire +# command or none of it. # # For example: -# \code -# IGNORED_COMPILATION_COMMANDS += gcc -c foo.c -# \endcode +# IGNORED_COMPILATION_COMMANDS += gcc -c foo.c # Parameter ERROR_LIMIT_PER_COMPILATION # # Purpose # Specifies the maximum number of parse errors allowed in a # compilation before the compilation is excluded from the analysis. # +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit +# # Type # integer # # Behavior -# If the percentage of project compilation units exceeding this limit -# is greater than \param MINIMUM_GOOD_COMPILATIONS, no analysis will +# If the percentage of project compilation units exceeding this +# limit is greater than MINIMUM_GOOD_COMPILATIONS, no analysis will # take place. # ERROR_LIMIT_PER_COMPILATION = 30 @@ -604,96 +601,140 @@ # # Purpose # At least this percentage of the project compilation units must be # "good compilations", meaning that they have no more parse errors -# than the limit specified by \param ERROR_LIMIT_PER_COMPILATION. -# -# Type -# integer between 0 and 100, inclusive +# than the limit specified by ERROR_LIMIT_PER_COMPILATION. +# +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit +# +# Type +# integer between 0 and 100, inclusive # # Behavior -# If the percentage of good compilations in the project is below this -# value, the analysis will not proceed. +# If the percentage of good compilations in the project is below +# this value, the analysis will not proceed. # MINIMUM_GOOD_COMPILATIONS = 80 # Parameter MALLOC_FAILURE_BEHAVIOR # -# Purpose +# Purpose # Specifies the treatment of allocators such as # malloc/calloc/alloca/realloc/new/new[] on failure. -# +# +# Tags +# - LANGUAGE_TREATMENT: Treatment of Language Constructs +# # Type # {RETURN_NULL, DOESNT_FAIL} # # Behavior -# - \tt RETURN_NULL : allocators are modeled as returning NULL on failure -# - \tt DOESNT_FAIL : allocators are assumed never to fail +# - RETURN_NULL : allocators are modeled as returning NULL on +# failure +# - DOESNT_FAIL : allocators are assumed never to fail.This setting +# is mainly useful for users who don't care what their software +# does when it runs out of memory. # # Notes -# This setting is mainly useful for users who don't care what their -# software does when it runs out of memory. -# +# We do not recommend changing the MALLOC_FAILURE_BEHAVIOR setting +# between incremental analyses because the different handling of +# allocators in the parent and child analyses is likely to confuse +# users: re-analyzed (and newly-analyzed) allocators will be +# handled as specified by the updated setting, but handling for any +# other allocators in the project will reflect the previous +# setting. + MALLOC_FAILURE_BEHAVIOR = RETURN_NULL -# MALLOC_FAILURE_BEHAVIOR = DOESNT_FAIL +## MALLOC_FAILURE_BEHAVIOR = DOESNT_FAIL # Parameter NEW_FAILURE_BEHAVIOR # -# Purpose +# Purpose # Specifies the treatment of new/new[] on failure. -# +# +# Tags +# - LANGUAGE_TREATMENT: Treatment of Language Constructs +# # Type # {EXCEPTION, RETURN_NULL, DOESNT_FAIL} # # Behavior -# - \tt EXCEPTION : new/new[] are modeled as throwing an exception on +# - EXCEPTION : new/new[] are modeled as throwing an exception on # failure -# - \tt RETURN_NULL : new/new[] are modeled as returning NULL on failure -# - \tt DOESNT_FAIL : new/new[] are assumed never to fail +# - RETURN_NULL : new/new[] are modeled as returning NULL on +# failure +# - DOESNT_FAIL : new/new[] are assumed never to fail # # Notes -# \param MALLOC_FAILURE_BEHAVIOR = \tt DOESNT_FAIL takes precedence -# over this parameter. +# MALLOC_FAILURE_BEHAVIOR = DOESNT_FAIL takes precedence over this +# parameter. # -# Different C++ runtimes have different behaviors. We recommend -# that you write a small test program to see what your compiler does. -# +# Different C++ runtimes have different behaviors. We recommend +# that you write a small test program to see what your compiler +# does. +# +# We do not recommend changing the NEW_FAILURE_BEHAVIOR setting +# between incremental analyses because the different handling of +# allocators in the parent and child analyses is likely to confuse +# users. Any new/new[] operators (or allocators modeled in terms of +# those operators) that are re-analyzed or newly-analyzed will be +# handled as specified by the updated setting, but the remainder +# will reflect the previous setting. + NEW_FAILURE_BEHAVIOR = EXCEPTION -# NEW_FAILURE_BEHAVIOR = RETURN_NULL -# NEW_FAILURE_BEHAVIOR = DOESNT_FAIL +## NEW_FAILURE_BEHAVIOR = RETURN_NULL +## NEW_FAILURE_BEHAVIOR = DOESNT_FAIL # Parameter MUTEX_FAILURE_BEHAVIOR # -# Purpose -# Specifies the treatment of lock acquisition and release functions such as -# pthread_mutex_lock on failure. -# +# Purpose +# Specifies the treatment of lock acquisition and release functions +# such as pthread_mutex_lock on failure. +# +# Tags +# - LANGUAGE_TREATMENT: Treatment of Language Constructs +# # Type # {RETURN_ERR, DOESNT_FAIL} # # Behavior -# - \tt RETURN_ERR : lock acquire/release functions are modeled as returning -# an error code on failure -# - \tt DOESNT_FAIL : lock acquire/release functions are assumed never to fail -# -# Notes -# It is dangerous to choose DOESNT_FAIL, when using an API (such as POSIX -# threads) that allows lock acquire/release functions to fail spuriously. -# +# - RETURN_ERR : lock acquire/release functions are modeled as +# returning an error code on failure +# - DOESNT_FAIL : lock acquire/release functions are assumed never +# to fail +# +# Notes +# It is dangerous to choose DOESNT_FAIL, when using an API (such as +# POSIX threads) that allows lock acquire/release functions to fail +# spuriously. +# +# We do not recommend changing the MUTEX_FAILURE_BEHAVIOR setting +# between incremental analyses because the different handling of +# lock operations in the parent and child analyses is likely to +# confuse users: any lock acquisition or release functions that are +# re-analyzed or newly-analyzed will be handled as specified by the +# updated setting, but the remainder will reflect the previous +# setting. + MUTEX_FAILURE_BEHAVIOR = RETURN_ERR -# MUTEX_FAILURE_BEHAVIOR = DOESNT_FAIL +## MUTEX_FAILURE_BEHAVIOR = DOESNT_FAIL # Parameter INITIALIZER_LIMIT # -# Purpose -# Specifies an upper bound on the number of elements in an initializer. -# +# Purpose +# Specifies an upper bound on the number of elements in an +# initializer. +# +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit +# # Type -# integer +# integer # # Behavior # Initializers containing more elements than this limit will be # ignored by the analysis. @@ -707,70 +748,98 @@ # Parameter AST_DEPTH_LIMIT # -# Purpose -# Specifies an upper bound on the depth of expression \link -# ../API/Descriptions/API_AST.html ASTs \endlink. -# +# Purpose +# Specifies an upper bound on the depth of expression ASTs +# [doc/html/API/Descriptions/API_AST.html]. +# +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit +# # Type -# integer +# integer # # Behavior # For every expression AST, the analysis will only consider those # parts of the AST that lie within this limit. # # A value of -1 means that there is no limit. # # Notes -# This is for preventing the front end or the analyzer from exhausting -# the stack when processing deeply nested expressions. For example, -# var + var2 + ... with 4000 additions. +# This is for preventing the front end or the analyzer from +# exhausting the stack when processing deeply nested expressions. +# For example, var + var2 + ... with 4000 additions. # -# Using "ulimit -s unlimited" in the shell from which the analysis +# Using "ulimit -s unlimited" in the shell from which the analysis # runs will make it possible to use higher values. AST_DEPTH_LIMIT = 256 # Parameter VERBOSITY # -# Purpose +# Purpose # Specifies status message verbosity # +# Tags +# - ANALYSIS_PROPERTY: Analysis Properties +# # Type # {0, 1, 2, 3, ..., 10} # -# Behavior -# The higher the \tt VERBOSITY value, the more status messages are +# Behavior +# The higher the 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. # +# When the value is 6 or higher the Native Compilation Details Log +# will include some trace output for source patching (from +# directories specified with SOURCE_PATCH_DIRECTORIES) and source +# replacement (as specified with SOURCE_REPLACE_COMMAND and +# SOURCE_PATTERN_REPLACEMENT rules). +# +# Notes +# In general, higher VERBOSITY values will result in longer running +# time; this effect is particularly marked in the analysis phase. +# If you are using higher settings to debug source patching or +# source replacement, we recommend doing the build and analysis in +# separate phases: +# - Set VERBOSITY to 6 and build the project with codesonar build +# [doc/html/C_Module/Building/HookCommands.html#build]. +# - Use the trace information in the Native Compilation Details Log +# to perform any necessary debugging, repeating the project build +# as necessary. +# - Once you are satisfied that the project has built correctly, +# set VERBOSITY to a lower value and analyze the project with +# codesonar analyze +# [doc/html/C_Module/Building/HookCommands.html#analyze]. + VERBOSITY = 2 # Parameter BUILD_OPTIONS # # Purpose # Specifies CodeSurfer builder options. -# +# +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis +# # Type # a list of build options # -# Behavior -# See the CodeSurfer manual, section \link [CSURF] -# ../../../../csurf/doc/codesurfer/CodeSurfer.html#OptionsPreferences/BuildOptionsSummary.html -# Build Options: Summary \endlink for a list of the available -# options. +# Behavior +# See the CodeSurfer manual, section Build Options: Summary +# [../csurf/doc/codesurfer/CodeSurfer.html#OptionsPreferences/BuildOptionsSummary.html] +# for a list of the available options. # # Notes -# CodeSonar users should usually not need to change this. +# CodeSonar users should usually not need to change this. # # To cause the builder to emit more status messages: -# \code -# BUILD_OPTIONS += -verbose 10 -# \endcode +# BUILD_OPTIONS += -verbose 10 # -BUILD_OPTIONS += +BUILD_OPTIONS += # Parameter EDG_FRONTEND_OPTIONS_PREPEND @@ -778,24 +847,25 @@ # Purpose # Specifies front end options to prepend to the front end command # line, in front of any CodeSurfer build options specified. # +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis +# # Type # a list of front-end options # # Behavior -# See section \link -# ../C_Module/CompilerModels/CsurfFrontEndOptions.html -# Front-End Options \endlink for descriptions of the available -# options. +# See section Front-End Options +# [doc/html/C_Module/CompilerModels/CsurfFrontEndOptions.html] for +# descriptions of the available options. # # Notes # The += operator will actually prepend to this preference (in all -# other cases except \param CFLAGS_PREPEND , the += operator -# appends). This means that if you have two \tt -# EDG_FRONTEND_OPTIONS_PREPEND += statements in this file, the -# options in the second statement will be prepended to the options in -# the first statement. +# other cases except CFLAGS_PREPEND , the += operator appends). +# This means that if you have two EDG_FRONTEND_OPTIONS_PREPEND += +# statements in this file, the options in the second statement will +# be prepended to the options in the first statement. # EDG_FRONTEND_OPTIONS_PREPEND += @@ -804,29 +874,27 @@ # Purpose # Specifies front end options to append to the front end command # line. # +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis +# # Type -# a list of front-end options +# a list of front-end options # # Behavior -# See section \link -# ../C_Module/CompilerModels/CsurfFrontEndOptions.html -# Front-End Options \endlink for descriptions of the available -# options. -# -# Notes -# To add mydir to the list of directories searched for -# include files: -# \code -# EDG_FRONTEND_OPTIONS_APPEND += -Imydir -# \endcode -# -# To set macro MYMACRO to the empty string (useful if you -# are getting a parser error complaining that MYMACRO is undefined): -# \code -# EDG_FRONTEND_OPTIONS_APPEND += -DMYMACRO= -# \endcode +# See section Front-End Options +# [doc/html/C_Module/CompilerModels/CsurfFrontEndOptions.html] for +# descriptions of the available options. +# +# Notes +# To add mydir to the list of directories searched for include +# files: +# EDG_FRONTEND_OPTIONS_APPEND += -Imydir +# +# To set macro MYMACRO to the empty string (useful if you are +# getting a parser error complaining that MYMACRO is undefined): +# EDG_FRONTEND_OPTIONS_APPEND += -DMYMACRO= # EDG_FRONTEND_OPTIONS_APPEND += @@ -835,61 +903,104 @@ # Purpose # Specifies the amount of memory (in Megabytes) to allocate for # managed IR objects. # +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit +# # Type # integer # # Behavior # When the intermediate representation (IR) of the program being -# analyzed occupies approximately this much virtual address space, a -# portion of the IR will be paged out. +# analyzed occupies approximately this much virtual address space, +# a portion of the IR will be paged out. +# +# A low value may cause thrashing. A high value may cause the tool +# to exhaust virtual address space. # -# A low value may cause thrashing. A high value may cause the tool -# to exhaust virtual address space. -# # Notes # Only a subset of the objects in memory are managed under this -# limit. CodeSonar has been observed to peak at approximately a -# gigabyte of additional address space on large programs, for default -# preferences. +# limit. CodeSonar has been observed to peak at approximately a +# gigabyte of additional address space on large programs, for +# default preferences. # MANAGED_OBJECTS_RESIDENT_LIMIT = 256 # Parameter MANAGED_OBJECTS_IO_BUFFER_CAPACITY # # Purpose -# Specifies the amount of memory (in Megabytes) to allocate for -# IO buffering. -# +# Specifies the amount of memory (in Megabytes) to allocate for IO +# buffering. +# +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit +# # Type # integer # # Notes -# A low value may cause thrashing. A high value may cause the tool -# to exhaust virtual address space. +# A low value may cause thrashing. A high value may cause the tool +# to exhaust virtual address space. # MANAGED_OBJECTS_IO_BUFFER_CAPACITY = 128 +# Parameter MANAGED_OBJECTS_IO_KERNEL_BUFFERING +# +# Purpose +# Specifies whether kernel page bufferring should be enabled for +# files that are buffered in userland (according to +# MANAGED_OBJECTS_IO_BUFFER_CAPACITY). +# +# Tags +# - ANALYSIS_PROPERTY: Analysis Properties +# +# Type +# {Yes, No} +# +# Notes +# In order to avoid the cost of context switches and OS overhead, +# I/O buffers for managed objects are stored in userland. Having +# the OS kernel ALSO buffer the data can be wasteful if the file in +# question is only being used by one long-running process, since +# the userland buffer will obviate the need for the kernel buffer. +# Therefore, it can be desirable to simply disable kernel +# bufferring in order that the OS's file system buffers can be used +# for other purposes. +# +# With short lived processes, parallel analysis, or machines with +# large amounts of physical memory, kernel bufferring is often +# beneficial. Kernel bufferring is always enabled for front end +# processes since they are short lived. +# +# Disabling kernel bufferring can make other processes on the same +# computer seem more responsive. +# +MANAGED_OBJECTS_IO_KERNEL_BUFFERING = Yes + + # Parameter ZFRAG_POOL_MINIMUM_CAPACITY # # Purpose -# Specifies the amount of memory (in Megabytes) to eagerly reserve for -# defragmentable allocations. -# +# Specifies the amount of memory (in Megabytes) to eagerly reserve +# for defragmentable allocations. +# +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit +# # Type # integer # # Notes -# It is not recommended that users alter this unless advised to do so -# by GrammaTech. +# It is not recommended that users alter this unless advised to do +# so by GrammaTech. # # Setting this to a large value can help avoid problems where large -# allocations are eventually unsatisfiable in long-running processes -# because of memory fragmentation. It interacts with other memory -# limits in the configuration file. +# allocations are eventually unsatisfiable in long-running +# processes because of memory fragmentation. It interacts with +# other memory limits in the configuration file. # ZFRAG_POOL_MINIMUM_CAPACITY = 256 @@ -898,18 +1009,21 @@ # Purpose # Specifies a lower bound on allocation size (in bytes) below which # degramentable memory will not be used. # +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit +# # Type # integer # # Behavior # Defragmentable memory will be used only for allocations greater # than or equal to this many bytes. # # Notes -# It is not recommended that users alter this unless advised to do so -# by GrammaTech. +# It is not recommended that users alter this unless advised to do +# so by GrammaTech. # # Defragmentable allocations have a space overhead of 32 bytes and # time overhead linear in the amount of space allocated. # @@ -918,12 +1032,16 @@ # Parameter MAX_MATCH_LENGTH # # Purpose -# When performing source replacement with \param -# SOURCE_PATTERN_REPLACEMENT, this is the size (in bytes) of the buffer -# used to hold the part of the source file currently undergoing -# matching. +# When performing source replacement with +# SOURCE_PATTERN_REPLACEMENT, this is the size (in bytes) of the +# buffer used to hold the part of the source file currently +# undergoing matching. +# +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit +# - PRE_PREPROC: Operations on Un-Preprocessed Files # # Type # integer # @@ -936,186 +1054,192 @@ # Parameter SOURCE_PATTERN_REPLACEMENT # # Purpose -# Specifies a regular expression based replacement to be carried out -# over the source code being analyzed (before preprocessing -# occurs). -# -# Type -# A string of the form -# \code -# s///+ -# \endcode +# Specifies a regular expression based replacement to be carried +# out over the source code being analyzed (before preprocessing +# occurs). +# +# Tags +# - PRE_PREPROC: Operations on Un-Preprocessed Files +# +# 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/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. +# +# - The delimiter '/' can be replaced by any character (except +# null). +# - is a Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] +# 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. +# 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/html/boost_regex/ref/syntax_option_type.html -# Boost regular expression syntax option\endlink correspondences: +# expression syntax option or flag as shown below. # -# \code -# -M no_mod_m -# -S no_mod_s -# A awk -# B basic -# C no_char_classes -# D sed -# E extended -# G grep -# H egrep -# I icase -# L literal -# N normal -# O collate -# P perl -# Q bk_plus_qm -# S mod_s -# T no_intervals -# X mod_x -# \endcode -# -# \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 -# c match_continuous -# d match_default -# e match_extra -# fa format_all -# fc format_no_copy -# fd format_default -# ff format_first_only -# fl format_literal -# fp format_perl -# fs format_sed -# m match_single_line -# n match_not_null -# z match_not_eob -# $ match_not_eol -# * match_any -# . match_not_dot_newline -# < match_not_bow -# > match_not_eow -# ^ match_not_bol -# \endcode +# Boost regular expression syntax_option_type [../third- +# party/boost/libs/regex/doc/html/boost_regex/ref/syntax_option_type.html] +# correspondences: +# +# -M no_mod_m +# -S no_mod_s +# A awk +# B basic +# C no_char_classes +# D sed +# E extended +# G grep +# H egrep +# I icase +# L literal +# N normal +# O collate +# P perl +# Q bk_plus_qm +# S mod_s +# T no_intervals +# X mod_x +# +# Boost regular expression match_flag_type [../third- +# party/boost/libs/regex/doc/html/boost_regex/ref/match_flag_type.html] +# correspondences: +# +# a match_not_bob +# c match_continuous +# d match_default +# e match_extra +# fa format_all +# fc format_no_copy +# fd format_default +# ff format_first_only +# fl format_literal +# fp format_perl +# fs format_sed +# m match_single_line +# n match_not_null +# z match_not_eob +# $ match_not_eol +# * match_any +# . match_not_dot_newline +# < match_not_bow +# > match_not_eow +# ^ match_not_bol +# +# Notes +# SOURCE_PATTERN_REPLACEMENT rules are typically used to improve +# analysis result quality by +# - removing code that CodeSonar has difficulty understanding, or +# - adding code that clarifies program behavior, or +# - both. # -# Notes # Matching and replacement is carried out within each source file, # before preprocessing occurs. # -# The updated text is saved in the store: the analysis back end never -# sees the original code. Note that this means that any error +# The updated text is saved in the store: the analysis back end +# never 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 \tt SOURCE_PATTERN_REPLACEMENT +# If no is specified for a 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 \param SOURCE_PATTERN, \param -# SOURCE_REPLACEMENT, and \param SOURCE_MODIFIERS to specify a -# regular expression based replacement as described below. +# 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 below. # # For example, -# \code -# SOURCE_PATTERN_REPLACEMENT=s/foo//I -# \endcode +# SOURCE_PATTERN_REPLACEMENT=s/foo//I # specifies that all occurrences of "foo" in the source code, # regardless of case, should be deleted. This is exactly equivalent -# to -# \code -# SOURCE_PATTERN_REPLACEMENT=s*foo**I -# \endcode +# to +# SOURCE_PATTERN_REPLACEMENT=s*foo**I # (the same expression with a different delimiter), and to -# \code -# SOURCE_PATTERN=foo -# SOURCE_REPLACEMENT= -# SOURCE_MODIFIERS=I -# \endcode +# SOURCE_PATTERN=foo +# SOURCE_REPLACEMENT= +# SOURCE_MODIFIERS=I # -# You can specify as many \tt SOURCE_PATTERN_REPLACEMENT entries as you +# You can specify as many SOURCE_PATTERN_REPLACEMENT entries as you # want: replacements will be carried out in the same order that the -# entries are specified. All \tt SOURCE_PATTERN_REPLACEMENTs will be -# carried out after all \tt SOURCE_REPLACE_COMMANDs. +# entries are specified. All SOURCE_PATTERN_REPLACEMENTs will be +# carried out after all SOURCE_REPLACE_COMMANDs. # # Parameter SOURCE_PATTERN # Parameter SOURCE_REPLACEMENT # Parameter SOURCE_MODIFIERS # # Purpose -# Provide an alternative to \param SOURCE_PATTERN_REPLACEMENT for -# specifying regular expression based replacements in the source -# code: -# - \tt SOURCE_PATTERN corresponds to the part of a -# \tt SOURCE_PATTERN_REPLACEMENT expression -# - \tt SOURCE_REPLACEMENT corresponds to the part of a -# \tt SOURCE_PATTERN_REPLACEMENT expression -# - \tt SOURCE_MODIFIERS corresponds to the + part of a -# \tt SOURCE_PATTERN_REPLACEMENT expression -# -# Type -# \tt SOURCE_PATTERN : \link -# ../../../../third-party/boost/libs/regex/doc/html/boost_regex/syntax.html -# Boost regular expression\endlink -# -# \tt SOURCE_REPLACEMENT : string -# -# \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 \param -# SOURCE_PATTERN_REPLACEMENT whose position in the -# execution order depends on the position of the following -# \tt SOURCE_PATTERN entry (or the end of the file, if there is no such -# following entry). -# -# A \tt SOURCE_REPLACEMENT entry is associated with the -# most-recently-seen \tt SOURCE_PATTERN not already associated with a -# \tt SOURCE_REPLACEMENT. -# -# A \tt SOURCE_REPLACEMENT or \tt SOURCE_MODIFIERS entry with which no -# \tt SOURCE_PATTERN can be associated is ignored with a warning. -# -# A \tt SOURCE_PATTERN with which no \tt SOURCE_REPLACEMENT can be -# associated will associated with the empty string as its source -# replacement +# An alternative to SOURCE_PATTERN_REPLACEMENT for specifying +# regular expression based replacements in the source code. +# +# Tags +# - PRE_PREPROC: Operations on Un-Preprocessed Files +# +# Type +# SOURCE_PATTERN : Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] +# +# SOURCE_REPLACEMENT : string +# +# SOURCE_MODIFIERS : one or modifiers as described in the entry for +# SOURCE_PATTERN_REPLACEMENT +# +# Behavior +# - SOURCE_PATTERN corresponds to the part of a +# SOURCE_PATTERN_REPLACEMENT expression +# - SOURCE_REPLACEMENT corresponds to the part of a +# SOURCE_PATTERN_REPLACEMENT expression +# - SOURCE_MODIFIERS corresponds to the + part of a +# SOURCE_PATTERN_REPLACEMENT expression # -# A \tt SOURCE_PATTERN with which no \tt SOURCE_MODIFIERS can be -# associated will asssumed to have no modifiers. # -# See the entry for \param SOURCE_PATTERN_REPLACEMENT for -# more information, including an example. +# Notes +# For the sake of execution order determination, a +# SOURCE_PATTERN/SOURCE_REPLACEMENT/SOURCE_MODIFIERS triple is +# treated as if it is a SOURCE_PATTERN_REPLACEMENT rule whose +# location is that of the next SOURCE_PATTERN rule, or at the end +# of the file if there is no such rule. +# +# A SOURCE_REPLACEMENT entry is associated with the most-recently- +# seen SOURCE_PATTERN not already associated with a +# SOURCE_REPLACEMENT. +# +# A SOURCE_REPLACEMENT or SOURCE_MODIFIERS entry with which no +# SOURCE_PATTERN can be associated is ignored with a warning. +# +# A SOURCE_PATTERN with which no 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 associated +# will assumed to have no modifiers. +# +# See the entry for SOURCE_PATTERN_REPLACEMENT for more +# information, including an example. # Parameter SOURCE_REPLACE_COMMAND # # Purpose # Specify a text-replacement command to be executed on each source # file being analyzed (before preprocessing occurs). -# +# +# Tags +# - PRE_PREPROC: Operations on Un-Preprocessed Files +# # Type # A string corresponding to a command that reads from stdin and # writes to stdout. # @@ -1123,273 +1247,336 @@ # Use this parameter to specify a substring replacement command to # execute on the source files before preprocessing occurs. # # For example, -# \code -# SOURCE_REPLACE_COMMAND=sed -e 's#@ *0x[0-9a-fA-F][0-9a-fA-F]*#/* CSURF: At removed */#' -# \endcode +# SOURCE_REPLACE_COMMAND=sed -e 's#@ *0x[0-9a-fA-F][0-9a-fA-F]*#/* CSURF: At removed */#' # 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 */" +# more spaces followed by a hexadecimal number should be replaced +# by a comment reading "/* CSURF: At removed */" # -# You can specify as many \tt SOURCE_REPLACE_COMMAND entries as you +# You can specify as many SOURCE_REPLACE_COMMAND entries as you # want: replacements will be carried out in the same order that the # entries are specified. # -# All replacements specified with \tt SOURCE_REPLACE_COMMAND will be -# carried out before any replacements specified with \param -# SOURCE_PATTERN_REPLACEMENT (or \param SOURCE_PATTERN, \param -# SOURCE_REPLACEMENT, \param SOURCE_MODIFIERS). +# All replacements specified with SOURCE_REPLACE_COMMAND will be +# carried out before any replacements specified with +# SOURCE_PATTERN_REPLACEMENT (or SOURCE_PATTERN, +# SOURCE_REPLACEMENT, SOURCE_MODIFIERS). # # Parameter PREPROCESS_IF_FAIL # # Purpose -# Specifies whether or not preprocessed versions of compilation -# units containing parse errors will be saved. +# Specifies whether or not preprocessed versions of compilation +# units containing parse errors will be saved. +# +# Tags +# - ANALYSIS_PROPERTY: Analysis Properties # # Type # {Yes, No} # # Notes -# If environment variable \tt CS_PREPROCESS_IF_FAIL is set, its -# value will override the setting of this parameter. +# If environment variable CS_PREPROCESS_IF_FAIL is set, its value +# will override the setting of this parameter. # PREPROCESS_IF_FAIL = Yes # Parameter PREPROCESS_ALWAYS # # Purpose -# Specifies whether or not preprocessed versions of all compilation units -# will be saved. +# Specifies whether or not preprocessed versions of all compilation +# units will be saved. +# +# Tags +# - ANALYSIS_PROPERTY: Analysis Properties # # Type # {Yes, No} # # Notes -# If environment variable \tt CS_PREPROCESS_ALWAYS is set, its value -# will override the setting of this parameter. +# If environment variable CS_PREPROCESS_ALWAYS is set, its value +# will override the setting of this parameter. # PREPROCESS_ALWAYS = No # Parameter HOOK_LOG # # Purpose -# Specifies a log file for hook* sub-commands. +# Specifies a log file for hook* sub-commands. +# +# Tags +# - BUILD_OUTPUT: Additional Outputs from the Build/Analysis # # Type -# file path +# file path # -# Behavior -# All process invocations inside a hook, hook-build, hook-html, -# or hook-start sub-command will be logged to the specified file. +# Behavior +# All process invocations inside a \c build, \c analyze, \c hook, +# \c hook-build, \c hook-html, or \c hook-start sub-command will be +# logged to the specified file. # # Notes # For example: -# \code # HOOK_LOG = /PATH/TO/log_file -# \endcode # # This parameter has no effect on Windows systems. # -# If environment variable \tt CS_HOOK_LOG is set, its value will +# If environment variable CS_HOOK_LOG is set, its value will # override the setting of this parameter. -# +# # Parameter BADFS_NOSLEEP # # Purpose -# Specifies whether or not to give users a chance to stop the build -# when we detect that the file system the project is being put on -# could cause reliability or performance problems. +# Specifies whether or not to give users a chance to stop the build +# when we detect that the file system the project is being put on +# could cause reliability or performance problems. +# +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis # # Type -# {Yes, No} +# {Yes, No} # # Notes -# If environment variable \tt GT_BADFS_NOSLEEP is set, its value will +# If environment variable GT_BADFS_NOSLEEP is set, its value will # override the setting of this parameter. BADFS_NOSLEEP = No # Parameter FATSTATS_DUMP_FILE # # Purpose -# Specifies an output file for certain diagnostic information. +# Specifies an output file for certain diagnostic information. +# +# Tags +# - BUILD_OUTPUT: Additional Outputs from the Build/Analysis # # Type -# file path +# file path # # Notes -# If environment variable \tt FATSTATS_DUMP_FILE is set, its value will -# override the setting of this parameter. +# If environment variable FATSTATS_DUMP_FILE is set, its value will +# override the setting of this parameter. # -# For example: -# \code -# FATSTATS_DUMP_FILE = /PATH/TO/dump_file -# \endcode +# For example: +# FATSTATS_DUMP_FILE = /PATH/TO/dump_file # Parameter MAX_CONCURRENT_PARSE_PROCESSES # +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit +# # Purpose -# Limits the number of concurrent parse processes. Note that -# concurrent parsing only occurs insofar as your normal build -# system invokes the compiler concurrently. +# Limits the number of concurrent parse processes. Note that +# concurrent parsing only occurs insofar as your normal build +# system invokes the compiler concurrently. # # Type -# integer +# integer # # Notes # This limit is necessary because each concurrent compilation # contributes to 5 files, and eventually the analysis needs to open # all files simultaneously (estimated at 50 + 5 * -# NUMBER_OF_CONCURRENT_PARSES). Most systems have various limits on -# the number of files a process can open. Typical file descriptor +# NUMBER_OF_CONCURRENT_PARSES). Most systems have various limits on +# the number of files a process can open. Typical file descriptor # limits for this platform are: -# - getrlimit(RLIMIT_NOFILE) = 1017 -# - stdio FILE* Limit = 1017 -# - GrammaTech-Internal Limit = 4096 -# - FD_SETSIZE = 1024 (of no consequence on Windows) -# +# - getrlimit(RLIMIT_NOFILE) = 1017 +# - GrammaTech-Internal Limit = 4096 +# # Increasing this value may cause the product to exhaust available -# file descriptors. Environments with low ulimits may need to -# decrease this value. 32-bit Solaris users may be able to increase -# this value if using LD_PRELOAD_32=extendedFILE.so.1. +# file descriptors. Environments with low ulimits may need to +# decrease this value. # MAX_CONCURRENT_PARSE_PROCESSES = 193 # Parameter PROCEDURE_METRIC_TIMEOUT # # Purpose -# Seconds spent computing a metric for a single procedure before the operation -# is aborted. +# Seconds spent computing a metric for a single procedure before +# the operation is aborted. # # Type # Integer # # Behavior -# A value of -1 disables the timeout. Values of 0 or greater specify the maximum -# number of seconds (elapsed time) to spend computing a single procedure -# metric value. If the timeout occurs for a given procedure and metric, no -# metric value will be reported for that procedure and metric. +# A value of -1 disables the timeout. Values of 0 or greater +# specify the maximum number of seconds (elapsed time) to spend +# computing a single procedure metric value. If the timeout occurs +# for a given procedure and metric, no metric value will be +# reported for that procedure and metric. # # Notes # Only applies to the following metrics: # - Module Design Complexity (ivG) # - Essential Complexity (evG) # PROCEDURE_METRIC_TIMEOUT = 60 -# Parameter INCREMENTAL_BUILD +# Parameter SOURCE_PATCH_DIRECTORIES # # Purpose -# Specifies whether or not the build/analysis will be incremental. +# Specifies directories under which patches to source are located. +# +# Tags +# - PRE_PREPROC: Operations on Un-Preprocessed Files # # Type -# {Yes, No} +# string # -# Behavior -# If set to "Yes", the build/analysis will be incremental. If set to -# "No", the entire project will be rebuilt and re-analyzed. +# Notes +# For every directory D specified with SOURCE_PATCH_DIRECTORIES, +# patch files in subdirectory D/fname.x/ are applied to the source +# file named fname.x, where fname.x is the source file name as +# specified in the build command or #include statements, before any +# redirection (such as symbolic link resolution). Note that +# fname.x/ must be a direct subdirectory of D - it cannot be more +# deeply nested. +# +# This process is independent of the names of the patch files +# themselves - only the subdirectory name matters. Similarly, any +# from-file and to-file filenames specified in a patch file are +# ignored. # -INCREMENTAL_BUILD = Yes +# If any part of a patch file fails, no part of that file is +# applied. +SOURCE_PATCH_DIRECTORIES += $GTHOME/codesonar/libmodels/header_patches -# Parameter DRY_RUN + +# Parameter INCREMENTAL_BUILD # # Purpose -# Dry runs are useful for counting lines and locating parse errors -# without running the CodeSonar analysis, and therefore without -# consuming licensed lines. +# Specifies whether or not the build/analysis will be incremental. +# +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis # # Type -# {Yes, No} +# {Yes, No} # # Behavior -# When set to "Yes", CodeSonar will perform a "dry run": it will -# count lines and report parse errors, but not perform the CodeSonar -# analysis. Because the analysis is not performed, no warnings are issued. -# -# When set to "No", CodeSonar will perform the full build/analysis -# based on the specified build command. -# -# Notes -# It can be useful to perform a dry run on a project before -# analyzing it to see whether it will exhaust your license (without -# actually exhausting your license). -# -# Dry run results are presented in an Analysis page in the Web -# GUI. See \link ../GUI/GUI_Analysis.html#dry_runs Analysis: Dry -# Runs\endlink in the GUI reference for more information. +# Let P be the name of the project. Then behavior is as follows. +# - Yes : Incrementality will be enabled for this build/analysis of +# P and all its descendant builds/analyses. If the project +# directory already contains a P.prj_files/ subdirectory, the +# current build/analysis will be an incremental child of the +# corresponding analysis, otherwise it will be a new base +# analysis. +# - No : Incrementality will not be enabled for this build/analysis +# - it will not have a parent, and cannot have any descendants. +# If the underlying software project is not being fully rebuilt, +# the CodeSonar project (and therefore any analysis of the +# project) will reflect only those parts that are being built. + +INCREMENTAL_BUILD = Yes + + +# Parameter DRY_RUN # -# CodeSonar does not require a license to perform a dry run. +# Purpose +# Dry runs are useful for counting lines and locating parse errors +# without running the CodeSonar analysis, and therefore without +# consuming licensed lines. +# +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis +# - INCREMENTAL_NOCHANGE: Do Not Change Between Incremental +# Analyses # -# Mixing dry runs and analysis runs for the same .prj_files -# directory (that is, the same project name) is not supported. +# Type +# {Yes, No} # -# Do not use \tt DRY_RUN if the hub is running version 3.5p1 or earlier: -# older hubs do not understand this parameter and will consume -# licensed lines regardless of its setting. +# Behavior +# - Yes : CodeSonar will perform a "dry run" - it will count lines +# and report parse errors, but not perform the CodeSonar +# analysis. Because the analysis is not performed, no warnings +# are issued. +# - No : CodeSonar will perform the full build/analysis based on +# the specified build command. +# +# Notes +# It can be useful to perform a dry run on a project before +# analyzing it to see whether it will exhaust your license (without +# actually exhausting your license). +# +# Dry run results are presented in an Analysis page in the Web GUI. +# See Analysis: Dry Runs [doc/html/GUI/GUI_Analysis.html#dry_runs] +# for more information. +# +# CodeSonar does not require a license to perform a dry run. +# +# Mixing dry runs and analysis runs for the same .prj_files +# directory (that is, the same project name) is not supported. +# +# Do not use DRY_RUN if the hub is running version 3.5p1 or +# earlier: older hubs do not understand this parameter and will +# consume licensed lines regardless of its setting. DRY_RUN = No -# Parameter HUB_ADDRESS +# Parameter HUB_ADDRESS # -# Purpose +# Purpose # Specifies the hub address CodeSonar should use. -# +# +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis +# # Type # String of the form : # # Behavior # CodeSonar will use the specified hub address. # - If an address is specified on the command line, then it takes -# precedence. -# - The \tt HUB_ADDRESS setting takes precedence over the -# \tt CODESONAR_HUB environment variable. -# - Setting \tt HUB_ADDRESS in template.conf affects the hub-start, -# hub-stop, hub-info, hook, and hook-html commands. Setting it in -# any other configuration file will affect only hook and hook-html +# precedence. +# - The HUB_ADDRESS setting takes precedence over the CODESONAR_HUB +# environment variable. +# - Setting HUB_ADDRESS in template.conf affects the hub-start, +# hub-stop, hub-info, build, and analyze commands. Setting it in +# any other configuration file will affect only build and analyze # commands using that file. # # Notes # For example: -# \code -# HUB_ADDRESS = 127.0.0.1:7340 -# \endcode +# HUB_ADDRESS = 127.0.0.1:7340 # # This parameter is ignored by the Windows project builder GUI. # -#HUB_ADDRESS = 127.0.0.1:7340 +## HUB_ADDRESS = 127.0.0.1:7340 -# Parameter ANALYSIS_NAME +# Parameter ANALYSIS_NAME # -# Purpose +# Purpose # Specifies a name for the analysis. -# +# +# Tags +# - ANALYSIS_PROPERTY: Analysis Properties +# # Type # string # # Behavior -# CodeSonar will label the analysis with the specified name. If a +# CodeSonar will label the analysis with the specified name. If a # name is specified on the command line, then it takes precedence. # Different analyses of the same project may have different names # (e.g., to distinguish different versions). # # Notes # For example: -# \code -# ANALYSIS_NAME = Bob's Project Revision 472 -# \endcode +# ANALYSIS_NAME = Bob's Project Revision 472 # -# CodeSonar will generate a name for the analysis if none is specified. +# CodeSonar will generate a name for the analysis if none is +# specified. # # Parameter USE_SERVICES @@ -1397,251 +1584,552 @@ # Purpose # [Windows only] Specifies whether or not the CodeSonar launch # daemon process will be created as a Windows service. # +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis +# # Type # {Yes, No} # -# Behavior -# If "Yes", any 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. +# Behavior +# - Yes : any launch daemon started by "codesonar analyze" will be +# created as a Windows service. +# +# - 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 +# Notes # This parameter is ignored by the Windows project builder GUI. # # This parameter has no effect on non-Windows systems. # # For example: -# \code -# USE_SERVICES = Yes -# \endcode +# USE_SERVICES = Yes -# USE_SERVICES = Yes +# USE_SERVICES = Yes # Parameter FOREGROUND # -# Purpose -# Specifies whether or not a "codesonar hook-html" command will run the -# analysis in the codesonar hook-html process itself. +# Purpose +# Specifies whether or not a "codesonar analyze" command will run +# the analysis in the codesonar analyze process itself. +# +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis # # 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. +# - Yes : the "codesonar analyze" command runs the analysis itself. +# - No : a separate background process runs the analysis after +# control returns to the shell. # -# Notes +# Notes # This parameter 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. +# when this is set to "Yes". Instead, the log will show up on the +# analyze 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 ANALYSIS_SLAVES # -# For example: -# \code -# FOREGROUND = No -# \endcode +# Purpose +# Specifies how many slave processes the CodeSonar analysis may +# start. The optimal number of slave processes depends on available +# system resources; each slave process uses CPU cycles and memory. +# +# Type +# {Auto, Serial} or integer +# +# Behavior +# - Serial : the analysis will take place in a single process. This +# will use the minimum amount of memory, but provides no +# parallelism or fault tolerance during analysis. It is useful on +# single-core systems and when resources are scarce. +# - Auto : CodeSonar will determine the appropriate maximum number +# of slaves based on the total number of logical cores (Cores) on +# the machine and the amount of free physical memory (Mem) using +# the following formula: min(Cores, (Mem / 512MB) - 1). If the +# result is less than or equal to 1, a serial analysis is +# performed. +# - integer: CodeSonar will spawn up to the specified number of +# slaves, in addition to the master process. Empirically, each +# process might use up to about 512MB of memory. +# +# Notes +# Use MASTER_LISTEN_INTERFACE to specify the address on which the +# master process will listen. +# +# Use DAEMON_SLAVES to specify how many slave processes CodeSonar +# may start to service web requests. +# +# For more information, see the manual section on Parallelism in +# CodeSonar [doc/html/Workings/Parallelism.html]. + +ANALYSIS_SLAVES = Auto + + +# Parameter MAX_ANALYSIS_SLAVES +# +# Purpose +# If set to a value greater than that of ANALYSIS_SLAVES, specifies +# an upper bound on the total number of CodeSonar analysis slaves. +# Otherwise the upper bound is the value of ANALYSIS_SLAVES - +# either the explicit value given by the user or the value computed +# for Auto. +# +# Type +# integer +# +# Behavior +# If the specified number of analysis slaves are running: +# - the CodeSonar analysis will not automatically start any new +# slaves, and +# - any attempt to manually start an analysis slave will fail. +# +# Notes +# This upper bound applies to all analysis slaves, whether started +# automatically by the CodeSonar analysis or manually by a user. +# +# If the analysis is running serially (either because +# ANALYSIS_SLAVES=Serial, or because ANALYSIS_SLAVES=Auto and +# CodeSonar determined that it should run serially), +# MAX_ANALYSIS_SLAVES has no effect. + +MAX_ANALYSIS_SLAVES = 62 + + +# Parameter DAEMON_SLAVES +# +# Purpose +# Specifies how many slave processes CodeSonar may start to service +# web requests. The optimal number of slave processes depends on +# available system resources; each slave process uses CPU cycles +# and memory. +# +# Type +# {Auto, Serial} or integer +# +# Behavior +# - Serial : web requests are serviced by a single process. +# - Auto : CodeSonar will determine the appropriate maximum number +# of slaves based on the total number of logical cores (Cores) on +# the machine and the amount of free physical memory (Mem) using +# the following formula: min(Cores, (Mem / 512MB) - 1). If the +# result is less than or equal to 1, web requests are serviced by +# a single process. +# - integer: CodeSonar will spawn up to the specified number of +# slaves, in addition to the master process. +# +# Notes +# Multiple daemon slaves will only start if multiple web requests +# are pending concurrently. +# +# This parameter is analogous to ANALYSIS_SLAVES, but determines +# the degree of parallelism for CodeSonar in daemon mode while +# ANALYSIS_SLAVES determines the degree of parallelism for the +# analysis. +# +# Use MASTER_LISTEN_INTERFACE to specify the address on which the +# master process will listen. +# +# For more information, see the manual section on Parallelism in +# CodeSonar [doc/html/Workings/Parallelism.html]. + +DAEMON_SLAVES = Auto + + +# Parameter MAX_DAEMON_SLAVES +# +# Purpose +# If set to a value greater than that of DAEMON_SLAVES, specifies +# an upper bound on the total number of CodeSonar analysis slaves. +# Otherwise the upper bound is the value of DAEMON_SLAVES - either +# the explicit value given by the user or the value computed for +# Auto. +# +# Type +# integer +# +# Behavior +# If the specified number of daemon slaves are running: +# - CodeSonarwill not automatically start any new slaves, and +# - any attempt to manually start a daemon slave will fail. +# +# Notes +# This upper bound applies to all daemon slaves, whether started +# automatically by CodeSonar or manually by a user. +# +# If the analysis is running serially in daemon mode (either +# because DAEMON_SLAVES=Serial, or because DAEMON_SLAVES=Auto and +# CodeSonar determined that it should run serially), +# MAX_DAEMON_SLAVES has no effect. + +MAX_DAEMON_SLAVES = 62 + + +# Parameter UNIT_OF_WORK_RETRIES +# +# Purpose +# Specifies how many times the analysis master should retry a +# failing unit of work before giving up on it and moving on. +# +# Type +# integer +# +# Behavior +# - negative N: keep retrying the unit of work forever. +# - zero: do not retry; move on after the first failure. +# - positive N: retry the unit of work N times before moving on. +# +# Notes +# When CodeSonar is running in parallel, slaves may experience +# various modes of failure, such as network socket disconnection or +# the slave process being killed by the user. Some of these modes +# of failure are intermittent and indepent of the particular unit +# of work being analyzed. Therefore, retrying a failed unit of work +# might be fruitful. On the other hand, if the slave is crashing +# due to the content of a particular unit of work, then repeated +# attempts on that unit of work will likely result in repeating +# crashes. +# +# By default, CodeSonar retries a failing unit of work up to three +# times before giving up on that unit of work and moving on. This +# strikes a balance between retrying forever and giving up +# immediately. +# +# For more information, see the manual sections on Parallelism in +# CodeSonar [doc/html/Workings/Parallelism.html] and the CodeSonar +# Plug-In API [doc/html/API/CodeSonarPlugins/PluginAPI.html]. -# FOREGROUND = No +UNIT_OF_WORK_RETRIES = 3 + + +# Parameter MASTER_LISTEN_INTERFACE +# +# Purpose +# Specifies the address on which the master process will listen, +# both in analysis mode and in daemon mode. +# +# Type +# String of the form or : +# +# Behavior +# - If is not specified, the analysis master will listen on +# the interface specified by , on a port allocated by the +# operating system. Inspect the analysis log to identify the port +# that is being used. +# - If is specified and available, the analysis master will +# listen on :. +# - If is specified but unavailable, the master will not +# run. If this occurs in analysis mode, the analysis will crash. +# If it occurs in daemon mode, the daemon will not start and +# requests will not be serviced. In both cases, there will be an +# error message in the Analysis Log +# [doc/html/GUI/GUI_Log_Analysis.html]. +# +# Notes +# Examples: +# MASTER_LISTEN_INTERFACE=0.0.0.0 +# MASTER_LISTEN_INTERFACE=0.0.0.0:1234 +# MASTER_LISTEN_INTERFACE=127.0.0.1 +# MASTER_LISTEN_INTERFACE=127.0.0.1:1234 +# MASTER_LISTEN_INTERFACE=mymachine +# MASTER_LISTEN_INTERFACE=mymachine:1234 +# + +MASTER_LISTEN_INTERFACE = 127.0.0.1 # Parameter WARNING_FILTER # # Purpose # Allows warnings to be modified before they are submitted to the # hub, or discarded entirely without being submitted. # +# Tags +# - ANALYSIS_FILTER: Analysis-Side Filtering +# # Type # Zero or more patterns, each consisting of an followed by -# one or more s. +# one or more s. # -# is one of: +# is one of: # - discard # - allow # - priority:= # - owner:= # # is one of: -# - class # - categories +# - class +# - compilation_unit # - file -# - procedure -# - procedure_typed +# - is_sysinclude +# - language # - line= # - path_listing -# - compilation_unit -# - language +# - procedure +# - procedure_typed # # and is one of: -# - : (substring match) -# - = (exact match) +# - : (substring match, type-insensitive) +# - = (exact match, type-insensitive) # # Behavior -# Depends on the : -# - \tt discard : warnings matching the rules will be discarded instead -# of being submitted to the hub. -# - \tt allow : warnings matching the rules will be submitted to the +# Depends on the and the s. +# +# is interpreted as follows. +# - 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" -# - \tt priority:= : warnings matching the rules will have +# - 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. -# - \tt owner:= : warnings matching the rules will have their +# 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. # -# Notes -# If there are two or more s in a pattern, the pattern -# will be applied to warnings that match ALL of the rules. +# Each specifies a condition that a warning must satisfy in +# order to match the rule. +# - is_sysinclude matches warnings that occur entirely within +# system include files (as designated by SYSTEM_INCLUDE_PATHS) +# with no user code involved. +# +# The remaining rule types specify constraints on various warning +# properties [doc/html/Elements/PROPERTIES_Warning.html]: +# - categories : Categories +# - class : Class +# - compilation_unit : Compilation Unit +# - file : the full path name of Warning File +# - language : Language +# - line= : Line +# - path_listing : Listing XML +# - procedure : Procedure +# - procedure_typed : depends on the warning Language. If C++, +# rules specify constraints on the fully typed rendering of the +# warning Procedure (including template instantiations, name +# qualification, and argument types). If C, specifies a +# constraint on the warning Procedure (so has the same behavior +# as a procedure rule). +# +# 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 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. +# +# Example 1: Discard all warnings belonging to any class with a +# LANG.MEM.* mnemonic +# [doc/html/WarningClasses/MnemonicHierarchy.html#LANG_MEM]. +# WARNING_FILTER = discard categories:LANG.MEM +# +# Example 2: Discard all warnings whose class is Buffer Overrun, +# Type Overrun, or any user-defined class with "underrun" in its +# name. +# WARNING_FILTER = discard class:underrun +# +# Example 3: Discard all warnings in the compilation unit +# [doc/html/Elements/PROPERTIES_File.html#compilation_unit_def] +# associated with mylib.cpp +# WARNING_FILTER = discard compilation_unit=mylib.cpp +# +# Example 4: Assign all warnings in file mylib.h to alex. If the +# hub has no user called alex, this rule has no effect. +# WARNING_FILTER = owner:=alex file=mylib.h +# +# Example 5: Assign all warnings in system include files to sandy. +# If the hub has no user called sandy, this rule has no effect. +# WARNING_FILTER = owner:=sandy is_sysinclude +# +# Example 6: Discard all warnings in C compilation units. +# WARNING_FILTER = discard language=c +# +# Example 7: Discard all warnings issued at line 47 (of any file). +# WARNING_FILTER = discard line=47 +# +# Example 8: Discard all warnings whose associated Listing XML +# contains substring 'callPrinter'. +# WARNING_FILTER = discard path_listing:callPrinter +# +# Example 9: For all warnings issued in procedure writeThis(), set +# Priority to "Maximum". For all warnings issued in any other +# procedure whose name contains substring 'write', set priority to +# "P0: High" +# - procedure writeThis() will match both rules, so the rule order +# is important. +# - if "Maximum" was not already a candidate Priority value on the +# hub, it will be added to the list of candidates once a warning +# with "Maximum" Priority is submitted. +# WARNING_FILTER = priority:="P0: High" procedure:write +# WARNING_FILTER += priority:="Incredible" procedure=writeThis +# +# Example 10: In C compilation units, discard all warnings issued +# in a procedure whose name contains substring 'gridproc'. In C++ +# compilation units, discard all warnings issued in a procedure +# such that the fully-qualified procedure name contains substring +# 'gridproc', or one of the argument type names contains substring +# gridproc. +# WARNING_FILTER = discard procedure_typed:gridproc +# +# Example 11: In C++ compilation units, discard all warnings issued +# in a procedure with exactly one, unsigned int, argument. In C +# compilation units, this rule will not match anything. +# WARNING_FILTER = discard procedure_typed:"(unsigned int)" +# +# The following checks are enabled by default. To discard warnings +# of a particular class, use the corresponding "discard" rule. +# WARNING_FILTER += discard class="Blocking in Critical Section" +# WARNING_FILTER += discard class="Buffer Overrun" +# WARNING_FILTER += discard class="Buffer Underrun" +# WARNING_FILTER += discard class="Cast Alters Value" +# WARNING_FILTER += discard class="Dangerous Function" +# WARNING_FILTER += discard class="Dangerous Function Cast" +# WARNING_FILTER += discard class="Deadlock" +# 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="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="Integer Overflow of Allocation Size" +# WARNING_FILTER += discard class="Leak" +# WARNING_FILTER += discard class="Misaligned Object" +# WARNING_FILTER += discard class="Missing Return Statement" +# WARNING_FILTER += discard class="Negative Character Value" +# WARNING_FILTER += discard class="Negative Shift Amount" +# WARNING_FILTER += discard class="Negative File Descriptor" +# WARNING_FILTER += discard class="No Space For Null Terminator" +# WARNING_FILTER += discard class="Null Pointer Dereference" +# WARNING_FILTER += discard class="Null Test After Dereference" +# WARNING_FILTER += discard class="Overlapping Memory Regions" +# 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="Shift Amount Exceeds Bit Width" +# WARNING_FILTER += discard class="Socket In Wrong State" +# 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="Uninitialized Variable" +# WARNING_FILTER += discard class="Unreachable Call" +# WARNING_FILTER += discard class="Unreachable Computation" +# WARNING_FILTER += discard class="Unreachable Conditional" +# WARNING_FILTER += discard class="Unreachable Control Flow" +# WARNING_FILTER += discard class="Unreachable Data Flow" +# WARNING_FILTER += discard class="Unreasonable Size Argument" +# WARNING_FILTER += discard class="Unused Value" +# WARNING_FILTER += discard class="Use After Close" +# WARNING_FILTER += discard class="Use After Free" +# WARNING_FILTER += discard class="Use of crypt" +# WARNING_FILTER += discard class="Use of gets" +# WARNING_FILTER += discard class="Use of getwd" +# WARNING_FILTER += discard class="Use of LoadModule" +# WARNING_FILTER += discard class="Use of mktemp" +# WARNING_FILTER += discard class="Use of realpath" +# WARNING_FILTER += discard class="Use of tmpfile" +# WARNING_FILTER += discard class="Use of tmpnam" +# WARNING_FILTER += discard class="Use of WinExec" +# WARNING_FILTER += discard class="Useless Assignment" +# WARNING_FILTER += discard class="Varargs Function Cast" +# +# The following checks are disabled by default. To enable checks +# for a particular class, use the corresponding "allow" rule. +# (Checks for some classes may require additional settings in order +# to work correctly. See the individual warning class documentation +# in the manual for full information.) +# WARNING_FILTER += allow class="Basic Numerical Type Used" +# WARNING_FILTER += allow class="Code Before #include" +# WARNING_FILTER += allow class="Condition Contains Side Effects" +# WARNING_FILTER += allow class="Conditional Compilation" +# WARNING_FILTER += allow class="Conflicting Lock Order" +# WARNING_FILTER += allow class="Data Race" +# WARNING_FILTER += allow class="Dynamic Allocation After Initialization" +# WARNING_FILTER += allow class="Excessive Stack Depth" +# WARNING_FILTER += allow class="Function Too Long" +# WARNING_FILTER += allow class="Function Pointer" +# WARNING_FILTER += allow class="Function Pointer Conversion" +# WARNING_FILTER += allow class="Goto Statement" +# WARNING_FILTER += allow class="High Risk Loop" +# WARNING_FILTER += allow class="Inconsistent Enumerator Initialization" +# WARNING_FILTER += allow class="Lock/Unlock Mismatch" +# WARNING_FILTER += allow class="Locked Twice" +# WARNING_FILTER += allow class="Macro Defined in Function Body" +# WARNING_FILTER += allow class="Macro Does Not End With ) or }" +# WARNING_FILTER += allow class="Macro Does Not Start With ( or {" +# WARNING_FILTER += allow class="Macro Undefined in Function Body" +# WARNING_FILTER += allow class="Macro Uses -> Operator" +# WARNING_FILTER += allow class="Macro Uses [] Operator" +# WARNING_FILTER += allow class="Macro Uses ## Operator" +# WARNING_FILTER += allow class="Macro Uses Unary * Operator" +# WARNING_FILTER += allow class="Missing Lock Acquisition" +# WARNING_FILTER += allow class="Missing Lock Release" +# WARNING_FILTER += allow class="Multiple Statements On Line" +# WARNING_FILTER += allow class="Multiple Declarations On Line" +# WARNING_FILTER += allow class="Nested Locks" +# WARNING_FILTER += allow class="No Matching #if" +# WARNING_FILTER += allow class="No Matching #endif" +# WARNING_FILTER += allow class="Not Enough Assertions" +# WARNING_FILTER += allow class="Pointer Before Beginning of Object" +# WARNING_FILTER += allow class="Pointer Past End of Object" +# WARNING_FILTER += allow class="Pointer Type Inside Typedef" +# WARNING_FILTER += allow class="Potential Unbounded Loop" +# WARNING_FILTER += allow class="Recursion" +# WARNING_FILTER += allow class="Recursive Macro" +# WARNING_FILTER += allow class="Scope Could Be File Static" +# WARNING_FILTER += allow class="Scope Could Be Local Static" +# WARNING_FILTER += allow class="Task Delay Function" +# WARNING_FILTER += allow class="Too Many Dereferences" +# WARNING_FILTER += allow class="Too Much Indirection in Declaration" +# WARNING_FILTER += allow class="Unbalanced Parenthesis" +# WARNING_FILTER += allow class="Unchecked Parameter Dereference" +# WARNING_FILTER += allow class="Too Many Parameters" +# WARNING_FILTER += allow class="Unknown Lock" +# WARNING_FILTER += allow class="Use of #undef" +# WARNING_FILTER += allow class="Use of longjmp" +# WARNING_FILTER += allow class="Use of setjmp" +# WARNING_FILTER += allow class="Variadic Macro" +# +# To enable all Power of Ten +# [doc/html/WarningClasses/Pow10Checks.html] checks: +# WARNING_FILTER += allow categories:POW10 +# BUILD_OPTIONS += -retain-unnormalized-c-ast yes # -# 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. -# -# The following checks are enabled by default. To discard warnings of -# a particular class, use the corresponding "discard" rule. -# \code -# WARNING_FILTER += discard class="Buffer Overrun" -# WARNING_FILTER += discard class="Buffer Underrun" -# WARNING_FILTER += discard class="Cast Alters Value" -# WARNING_FILTER += discard class="Dangerous Function" -# WARNING_FILTER += discard class="Dangerous Function Cast" -# WARNING_FILTER += discard class="Deadlock" -# 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="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="Integer Overflow of Allocation Size" -# WARNING_FILTER += discard class="Leak" -# WARNING_FILTER += discard class="Misaligned Object" -# WARNING_FILTER += discard class="Missing Return Statement" -# WARNING_FILTER += discard class="Negative Character Value" -# WARNING_FILTER += discard class="Negative Shift Amount" -# WARNING_FILTER += discard class="Negative File Descriptor" -# WARNING_FILTER += discard class="No Space For Null Terminator" -# WARNING_FILTER += discard class="Null Pointer Dereference" -# WARNING_FILTER += discard class="Null Test After Dereference" -# WARNING_FILTER += discard class="Overlapping Memory Regions" -# 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="Shift Amount Exceeds Bit Width" -# WARNING_FILTER += discard class="Socket In Wrong State" -# 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="Uninitialized Variable" -# WARNING_FILTER += discard class="Unreachable Call" -# WARNING_FILTER += discard class="Unreachable Computation" -# WARNING_FILTER += discard class="Unreachable Conditional" -# WARNING_FILTER += discard class="Unreachable Control Flow" -# WARNING_FILTER += discard class="Unreachable Data Flow" -# WARNING_FILTER += discard class="Unreasonable Size Argument" -# WARNING_FILTER += discard class="Unused Value" -# WARNING_FILTER += discard class="Use After Close" -# WARNING_FILTER += discard class="Use After Free" -# WARNING_FILTER += discard class="Use of crypt" -# WARNING_FILTER += discard class="Use of gets" -# WARNING_FILTER += discard class="Use of getwd" -# WARNING_FILTER += discard class="Use of LoadModule" -# WARNING_FILTER += discard class="Use of mktemp" -# WARNING_FILTER += discard class="Use of realpath" -# WARNING_FILTER += discard class="Use of tmpfile" -# WARNING_FILTER += discard class="Use of tmpnam" -# WARNING_FILTER += discard class="Use of WinExec" -# WARNING_FILTER += discard class="Useless Assignment" -# WARNING_FILTER += discard class="Varargs Function Cast" -# \endcode -# -# The following checks are disabled by default. To enable checks for a -# particular class, use the corresponding "allow" rule. (Checks for -# some classes may require additional settings in order to work -# correctly. See the individual warning class documentation in the -# manual for full information.) -# \code -# WARNING_FILTER += allow class="Basic Numerical Type Used" -# WARNING_FILTER += allow class="Code Before #include" -# WARNING_FILTER += allow class="Condition Contains Side Effects" -# WARNING_FILTER += allow class="Conditional Compilation" -# WARNING_FILTER += allow class="Conflicting Lock Order" -# WARNING_FILTER += allow class="Data Race" -# WARNING_FILTER += allow class="Dynamic Allocation After Initialization" -# WARNING_FILTER += allow class="Excessive Stack Depth" -# WARNING_FILTER += allow class="Function Too Long" -# WARNING_FILTER += allow class="Function Pointer" -# WARNING_FILTER += allow class="Function Pointer Conversion" -# WARNING_FILTER += allow class="Goto Statement" -# WARNING_FILTER += allow class="High Risk Loop" -# WARNING_FILTER += allow class="Inconsistent Enumerator Initialization" -# WARNING_FILTER += allow class="Lock/Unlock Mismatch" -# WARNING_FILTER += allow class="Locked Twice" -# WARNING_FILTER += allow class="Macro Defined in Function Body" -# WARNING_FILTER += allow class="Macro Does Not End With ) or }" -# WARNING_FILTER += allow class="Macro Does Not Start With ( or {" -# WARNING_FILTER += allow class="Macro Undefined in Function Body" -# WARNING_FILTER += allow class="Macro Uses -> Operator" -# WARNING_FILTER += allow class="Macro Uses [] Operator" -# WARNING_FILTER += allow class="Macro Uses ## Operator" -# WARNING_FILTER += allow class="Macro Uses Unary * Operator" -# WARNING_FILTER += allow class="Missing Lock Acquisition" -# WARNING_FILTER += allow class="Missing Lock Release" -# WARNING_FILTER += allow class="Multiple Statements On Line" -# WARNING_FILTER += allow class="Multiple Declarations On Line" -# WARNING_FILTER += allow class="Nested Locks" -# WARNING_FILTER += allow class="No Matching #if" -# WARNING_FILTER += allow class="No Matching #endif" -# WARNING_FILTER += allow class="Not Enough Assertions" -# WARNING_FILTER += allow class="Pointer Before Beginning of Object" -# WARNING_FILTER += allow class="Pointer Past End of Object" -# WARNING_FILTER += allow class="Pointer Type Inside Typedef" -# WARNING_FILTER += allow class="Potential Unbounded Loop" -# WARNING_FILTER += allow class="Recursion" -# WARNING_FILTER += allow class="Recursive Macro" -# WARNING_FILTER += allow class="Scope Could Be File Static" -# WARNING_FILTER += allow class="Scope Could Be Local Static" -# WARNING_FILTER += allow class="Task Delay Function" -# WARNING_FILTER += allow class="Too Many Dereferences" -# WARNING_FILTER += allow class="Too Much Indirection in Declaration" -# WARNING_FILTER += allow class="Unbalanced Parenthesis" -# WARNING_FILTER += allow class="Unchecked Parameter Dereference" -# WARNING_FILTER += allow class="Too Many Parameters" -# WARNING_FILTER += allow class="Unknown Lock" -# WARNING_FILTER += allow class="Use of #undef" -# WARNING_FILTER += allow class="Use of longjmp" -# WARNING_FILTER += allow class="Use of setjmp" -# WARNING_FILTER += allow class="Variadic Macro" -# \endcode -# -# To enable all \link ../WarningClasses/Pow10Checks.html Power of -# Ten\endlink checks: -# \code -# WARNING_FILTER += allow categories:POW10 -# BUILD_OPTIONS += -retain-unnormalized-c-ast yes -# \endcode +# To enable all JPL [doc/html/WarningClasses/JPLChecks.html] +# checks: +# WARNING_FILTER += allow categories:JPL +# BUILD_OPTIONS += -retain-unnormalized-c-ast yes +# +# To discard integer overflow warnings that occur entirely within +# system headers: +# WARNING_FILTER += discard class="Integer Overflow of Allocation Size" is_sysinclude + +WARNING_FILTER += discard class="Integer Overflow of Allocation Size" is_sysinclude # Parameter BAD_FUNCTION_REGEX # Parameter BAD_FUNCTION_MESSAGE @@ -1650,122 +2138,115 @@ # Parameter BAD_FUNCTION_INFO # Parameter BAD_FUNCTION_LINK # # Purpose -# Specifies functions that are prohibited. +# Use the BAD_FUNCTION_* family of parameters to define warning +# classes that indicate the use of specific (prohibited) functions. +# +# Tags +# - WARNING_SPECIAL_FUNCTIONS: Designates Specially-Treated +# Functions # # Type -# - \tt BAD_FUNCTION_REGEX: \link -# ../../../../third-party/boost/libs/regex/doc/html/boost_regex/syntax.html -# Boost regular expression\endlink -# - \tt BAD_FUNCTION_MESSAGE: string -# - \tt BAD_FUNCTION_CATEGORIES: string -# - \tt BAD_FUNCTION_RANK: number -# - \tt BAD_FUNCTION_INFO: string -# - \tt BAD_FUNCTION_LINK: string representing a URL +# - BAD_FUNCTION_REGEX: Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] +# - BAD_FUNCTION_MESSAGE: string +# - BAD_FUNCTION_CATEGORIES: string +# - BAD_FUNCTION_RANK: number +# - BAD_FUNCTION_INFO: string +# - BAD_FUNCTION_LINK: string representing a URL # # Behavior # These parameters are used together to specify bad functions to # check for and warnings to issue when those functions occur. -# - \tt BAD_FUNCTION_REGEX is a regular expression. If a reference -# to a function that matches this is found, then a warning -# is issued. -# - \tt BAD_FUNCTION_MESSAGE will be used as the warning class -# name. It defaults to "Bad Function". -# - \tt BAD_FUNCTION_CATEGORIES is the set of categories for the +# - BAD_FUNCTION_REGEX is a regular expression. If a reference to a +# function that matches this is found, then a warning is issued. +# - BAD_FUNCTION_MESSAGE will be used as the warning class name. It +# defaults to "Bad Function". +# - BAD_FUNCTION_CATEGORIES is the set of categories for the # warning, as a semicolon-separated list. This defaults to the # empty string. -# - \tt BAD_FUNCTION_RANK is the rank assigned to the warning, with +# - BAD_FUNCTION_RANK is the rank assigned to the warning, with # default 15.0. -# - \tt BAD_FUNCTION_INFO will be used in the \link -# ../GUI/GUI_Warning_Report.html#endbox warning description -# box\endlink sentence 'Use of [\tt funcname()] is not recommended -# because ...'. The default value is "it is correlated with -# security or safety problems." Use to -# delimit paragraphs. Use -# linktext to link "linktext" to linkURL. -# - \tt BAD_FUNCTION_LINK specifies a URL for further information. +# - BAD_FUNCTION_INFO will be used in the warning description box +# [doc/html/GUI/GUI_Warning_Report.html#endbox] sentence 'Use of +# [funcname()] is not recommended because ...'. The default value +# is "it is correlated with security or safety problems." Use +# to delimit paragraphs. Use linktext to link "linktext" to linkURL. +# - BAD_FUNCTION_LINK specifies a URL for further information. # Values beginning with "#' are interpreted relative to the # CodeSonar manual root. If a value is specified, CodeSonar will -# append 'See here for more information.' to the -# text in the \link ../GUI/GUI_Warning_Report.html#endbox warning -# description box\endlink. If no value is specified, and \tt -# BAD_FUNCTION_INFO is also not specified, CodeSonar will look for -# a category beginning with "BADFUNC" in the \tt -# BAD_FUNCTION_CATEGORIES list. If there is such a category, -# CodeSonar will add the "See here..." sentence with a link to the -# corresponding warning class page. -# -# Notes -# -# If two or more sets of \tt BAD_FUNCTION_* rules have the same \tt -# BAD_FUNCTION_MESSAGE value, the same warning class will be used to -# cover all cases. Therefore, sets of rules with the same \tt -# BAD_FUNCTION_MESSAGE should also have the same \tt -# BAD_FUNCTION_CATEGORIES and \tt BAD_FUNCTION_RANK values (that is, -# they should only differ in the \tt BAD_FUNCTION_REGEX setting). -# -# Similarly, if a set of \tt BAD_FUNCTION_* rules has a \tt -# BAD_FUNCTION_MESSAGE that is the same as the name of a standard -# CodeSonar warning class, the category and rank settings of the -# standard class will apply and any \tt BAD_FUNCTION_CATEGORIES or -# \tt BAD_FUNCTION_RANK specified in the set will not be used. +# append 'See here for more information.' to +# the text in the warning description box +# [doc/html/GUI/GUI_Warning_Report.html#endbox]. If no value is +# specified, and BAD_FUNCTION_INFO is also not specified, +# CodeSonar will look for a category beginning with "BADFUNC" in +# the BAD_FUNCTION_CATEGORIES list. If there is such a category, +# CodeSonar will add the "See here..." sentence with a link to +# the corresponding warning class page. +# +# Notes +# +# If two or more sets of BAD_FUNCTION_* rules have the same +# BAD_FUNCTION_MESSAGE value, the same warning class will be used +# to cover all cases. Therefore, sets of rules with the same +# BAD_FUNCTION_MESSAGE should also have the same +# BAD_FUNCTION_CATEGORIES and BAD_FUNCTION_RANK values (that is, +# they should only differ in the BAD_FUNCTION_REGEX setting). +# +# Similarly, if a set of BAD_FUNCTION_* rules has a +# BAD_FUNCTION_MESSAGE that is the same as the name of a standard +# CodeSonar warning class, the category and rank settings of the +# standard class will apply and any BAD_FUNCTION_CATEGORIES or +# BAD_FUNCTION_RANK specified in the set will not be used. # # Examples: -# \code -# BAD_FUNCTION_REGEX = ^gets$ -# BAD_FUNCTION_MESSAGE = Use of gets -# BAD_FUNCTION_CATEGORIES = BADFUNC.BO.GETS;CWE:242 -# BAD_FUNCTION_RANK = 1.0 -# \endcode +# BAD_FUNCTION_REGEX = ^gets$ +# BAD_FUNCTION_MESSAGE = Use of gets +# BAD_FUNCTION_CATEGORIES = BADFUNC.BO.GETS;CWE:242 +# BAD_FUNCTION_RANK = 1.0 # specifies that uses of the function "gets" should be flagged as # warnings. # # The following introduces a warning on use of the function # "memset" because some compilers may insecurely remove the call -# during optimization. See -# \link http://cwe.mitre.org/data/definitions/14.html CWE:14\endlink -# for details. -# \code -# BAD_FUNCTION_REGEX = ^memset$ -# BAD_FUNCTION_MESSAGE = Use of memset -# BAD_FUNCTION_CATEGORIES = BADFUNC.MEMSET;CWE:14 -# BAD_FUNCTION_RANK = 10.0 -# \endcode +# during optimization. See CWE:14 +# [http://cwe.mitre.org/data/definitions/14.html] for details. +# BAD_FUNCTION_REGEX = ^memset$ +# BAD_FUNCTION_MESSAGE = Use of memset +# BAD_FUNCTION_CATEGORIES = BADFUNC.MEMSET;CWE:14 +# BAD_FUNCTION_RANK = 10.0 # # For functions in C++ compilation units with C++ linkage, the # regular expression will be matched against the fully qualified -# function signature (including namespace and template -# components). For example, suppose we have function \tt myfunc() in -# such a compilation unit, where \tt myfunc() returns \tt int and has -# one int parameter. Then: -# \code -# BAD_FUNCTION_REGEX = ^int myfunc(int)$ -# \endcode -# will match a use of \tt myfunc(). If \tt myfunc() is overloaded, -# only uses with the corresponding type signature will match. We can -# remove the delimiters from the regular expression to widen the search: -# \code -# BAD_FUNCTION_REGEX = myfunc -# \endcode -# will match all uses of \tt myfunc(), regardless of type signature, -# but will also match uses of \tt myfunc_2(), \tt not_myfunc(), and -# so on. It is important to note that -# \code -# BAD_FUNCTION_REGEX = ^myfunc$ -# \endcode -# will not match ANY use of \tt myfunc() in this compilation unit. +# function signature (including namespace and template components). +# For example, suppose we have function myfunc() in such a +# compilation unit, where myfunc() returns int and has one int +# parameter. Then: +# BAD_FUNCTION_REGEX = ^int myfunc(int)$ +# will match a use of myfunc(). If myfunc() is overloaded, only +# uses with the corresponding type signature will match. We can +# remove the delimiters from the regular expression to widen the +# search: +# BAD_FUNCTION_REGEX = myfunc +# will match all uses of myfunc(), regardless of type signature, +# but will also match uses of myfunc_2(), not_myfunc(), and so on. +# It is important to note that +# BAD_FUNCTION_REGEX = ^myfunc$ +# will not match ANY use of myfunc() in this compilation unit. # # To inspect the function signature strings that CodeSonar will be -# matching \tt BAD_FUNCTION_REGEX expressions against, write a \link -# ../API/CodeSonarPlugins/PluginAPI.html CodeSonar plug-in\endlink +# matching BAD_FUNCTION_REGEX expressions against, use the +# CodeSonar Plug-In API +# [doc/html/API/CodeSonarPlugins/PluginAPI.html] to write a plug-in # that traverses the PDGs of the project, getting the function # ABS_LOC for each and then printing its name. # -# The \tt $str$Class_Name form used in some of the \tt -# BAD_FUNCTION_MESSAGE factory settings is for internal GrammaTech -# use. Do not imitate this format: specify plain class names as shown -# in the examples above. +# The $str$Class_Name form used in some of the BAD_FUNCTION_MESSAGE +# factory settings is for internal GrammaTech use. Do not imitate +# this format: specify plain class names as shown in the examples +# above. BAD_FUNCTION_REGEX = ^crypt$ BAD_FUNCTION_MESSAGE = $Insecure Randomness$Use of crypt BAD_FUNCTION_CATEGORIES = BADFUNC.CRYPT;BSI:CRYPT-01;BSI:CRYPT-02;CWE:326;CWE:330 @@ -1812,9 +2293,9 @@ BAD_FUNCTION_CATEGORIES = BADFUNC.TEMP.MKTEMP;BSI:MKTEMP;CWE:377 BAD_FUNCTION_RANK = 47.0 ## For "Task Delay Function" check. -## As with other JPL classes, this warning class is disabled by default.f +## As with other JPL classes, this warning class is disabled by default. BAD_FUNCTION_REGEX = ^sleep|usleep|taskDelay|nanosleep|clock_nanosleep$ BAD_FUNCTION_MESSAGE = Task Delay Function BAD_FUNCTION_INFO = it is considered to be a task delay function. The use of task delay functions for synchronization can cause problems such as race conditions. @@ -1828,75 +2309,74 @@ # Parameter PLUGINS # # Purpose -# Specifies filenames of Scheme API and C API plug-ins to load. +# Specifies filenames of Scheme and C plug-ins to load. +# +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis # # Type -# string +# string # # Behavior # The specified files will be loaded as plug-ins. # # Notes # For example: -# \code -# PLUGINS += /tmp/foo.stk -# PLUGINS += /tmp/foo.so -# PLUGINS += /tmp/foo.dll -# PLUGINS += /tmp/foo.bundle -# PLUGINS += c:\Documents and Settings\Bob\Desktop\foo.dll -# \endcode -# -# For more information about CodeSonar plug-ins, see \link -# ../API/CodeSonarPlugins/PluginAPI.html CodeSonar Plug-In API -# \endlink. +# PLUGINS += /tmp/fname.stk +# PLUGINS += /tmp/fname.so +# PLUGINS += /tmp/fname.dll +# PLUGINS += /tmp/fname.bundle +# PLUGINS += c:\Documents and Settings\Bob\Desktop\fname.dll +# +# For more information about CodeSonar plug-ins, see CodeSonar +# Plug-In API [doc/html/API/CodeSonarPlugins/PluginAPI.html]. # Parameter REPORT_IMPLIED_EQUALITY # # Purpose # Specifies whether or not implied unsafe behavior due to # equality/disequality is sufficient cause to issue warnings. # +# Tags +# - WARNING_TUNING: Fine Tuning for Warnings +# # 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. +# Behavior +# - No : 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 +# Notes # Setting this to "No" will decrease the false positive rate and -# increase the false negative rate. +# 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; -# \endcode +# if( p == NULL ) +# *p = 42; # # but this would not: # -# \code -# p = NULL; -# if( p == NULL ) -# *p = 42; -# \endcode +# p = NULL; +# if( p == NULL ) +# *p = 42; # # It may be difficult to find vulnerabilities in functions that are # 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 # test for equality unless they believe it can happen. # -# The warning classes affected by this parameter are the same as those for -# \param TIME_LIMIT_INTRA_CLASSIFY. +# The warning classes affected by this parameter are the same as +# those for TIME_LIMIT_INTRA_CLASSIFY. # REPORT_IMPLIED_EQUALITY = Yes @@ -1905,49 +2385,47 @@ # Purpose # Specifies whether or not implied unsafe behavior due to # inequality is sufficient cause to issue warnings. # +# Tags +# - WARNING_TUNING: Fine Tuning for Warnings +# # 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 inequality -# (<, <=, >, >=); satisfying assignments to the variables must also -# exist. +# Behavior +# - No : 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. # -# Notes +# Notes # Setting this to "No" will decrease the false positive rate and -# increase the false negative rate. +# 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 ) -# A[i] = 42; -# \endcode +# int A[10]; +# if( i < 0 ) +# A[i] = 42; # # but this would not: # -# \code -# int A[10]; -# i = -1; -# if( i < 0 ) -# A[i] = 42; -# \endcode +# int A[10]; +# i = -1; +# if( i < 0 ) +# A[i] = 42; # # It may be difficult to find vulnerabilities in functions that are # 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 -# that are always satisfied on the first iteration. +# This is set to "No" by default because loops often have +# conditions that are always satisfied on the first iteration. # -# The warning classes affected by this parameter are the same as those for -# \param TIME_LIMIT_INTRA_CLASSIFY. +# The warning classes affected by this parameter are the same as +# those for TIME_LIMIT_INTRA_CLASSIFY. # REPORT_IMPLIED_INEQUALITY = No @@ -1955,33 +2433,37 @@ # # Purpose # Seconds of inactivity before the analysis daemon shuts down to # conserve system resources. -# +# +# Tags +# - ANALYSIS_PROPERTY: Analysis Properties +# # Type # integer # # Behavior -# When the web application needs certain information (such as source -# file listings), it queries the analysis daemon. If the analysis -# daemon is not running, then the web application will attempt to -# start it. This can take a minute or more, so timing out quickly is -# often undesirable. -# +# When the web application needs certain information (such as +# source file listings), it queries the analysis daemon. If the +# analysis daemon is not running, then the web application will +# attempt to start it. This can take a minute or more, so timing +# out quickly is often undesirable. +# # A negative value prevents the analysis daemon from timing out at # all. -# +# # Notes # A low value can result in slow web queries if the time between -# applicable queries exceeds this value. A high value can result in +# applicable queries exceeds this value. A high value can result in # an extra process hanging around doing nothing on the analysis -# machine. The default setting is 30 minutes ( = 1800 seconds). +# machine. The default setting is 30 minutes ( = 1800 seconds). # -# The analysis log will not be finalized,and so the \link -# ../GUI/GUI_Log_Analysis.html Analysis Log page\endlink contents may -# continue to change, until the analysis daemon times out (or is -# properly shut down). +# The analysis log will not be finalized, and so the Analysis Log +# [doc/html/GUI/GUI_Log_Analysis.html] contents may continue to +# change, until the analysis daemon times out (or is properly shut +# down). # + DAEMON_TIMEOUT = 1800 # Parameter FOREGROUND_DAEMON_TIMEOUT @@ -1988,70 +2470,60 @@ # # Purpose # Seconds of inactivity when running in foreground mode before the # analysis daemon shuts down to conserve system resources. -# +# +# Tags +# - ANALYSIS_PROPERTY: Analysis Properties +# # Type # integer # # Behavior -# When the web application needs certain information (such as source -# file listings), it queries the analysis daemon. If the analysis -# daemon is not running, then the web application will attempt to -# start it. This can take a minute or more, so timing out quickly is -# often undesirable. -# +# When the web application needs certain information (such as +# source file listings), it queries the analysis daemon. If the +# analysis daemon is not running, then the web application will +# attempt to start it. This can take a minute or more, so timing +# out quickly is often undesirable. +# # A negative value prevents the analysis daemon from timing out at # all. -# +# # Notes -# Applicable when running with FOREGROUND = Yes or -foreground on the -# command line. +# Applicable when running with FOREGROUND=Yes (or -foreground on +# the command line). # # A low value can result in slow web queries if the time between -# applicable queries exceeds this value. A high value can result in +# applicable queries exceeds this value. A high value can result in # an extra process hanging around doing nothing on the analysis -# machine. The default setting is 30 minutes ( = 1800 seconds). +# machine. The default setting is 30 minutes ( = 1800 seconds). # -# The analysis log will not be finalized,and so the \link -# ../GUI/GUI_Log_Analysis.html Analysis Log page\endlink contents may -# continue to change, until the analysis daemon times out (or is -# properly shut down). +# The analysis log will not be finalized, and so the Analysis Log +# [doc/html/GUI/GUI_Log_Analysis.html] page contents may continue +# to change, until the analysis daemon times out (or is properly +# shut down). # FOREGROUND_DAEMON_TIMEOUT = 5 -# Parameter CONSTANT_CACHE_CAPACITY -# -# Purpose -# Megabytes of memory to allocate for values of constants, such as -# those found in static initializers of const variables. -# -# Type -# integer -# -# Notes -# A low value may cause the analysis to frequently recompute the -# values of local and static constants. -# -CONSTANT_CACHE_CAPACITY = 64 - - # Parameter TOLERATE_PARSE_ERRORS # -# Purpose +# Purpose # If errors were encountered in parsing the code, specifies whether # or not the analysis will run anyway # +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis +# # Type # {Yes, No} # -# Behavior -# 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 tiny or enormous. -# +# Behavior +# - No : 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 tiny or enormous. +# # Notes # A log of parse errors and compiler command lines can be found at # .prj_files/log.txt. # @@ -2060,65 +2532,70 @@ # Parameter NULL_POINTER_THRESHOLD # # Purpose -# Determines what qualifies as a \wclink LANG.MEM.NPD Null Pointer -# Dereference \endwclink. +# Determines what qualifies as a Null Pointer Dereference +# +# Tags +# - WARNING_THRESHOLD: Warning-Class-Specific Thresholds +# - WC_LANG.MEM.NPD: Used by Null Pointer Dereference # # Type # integer # # Behavior -# Any dereference of an address less than this value will be treated -# as a Null Pointer Dereference. Most machines will never allocate -# objects on the 0 page in user mode. +# Any dereference of an address less than this value will be +# treated as a Null Pointer Dereference. Most machines will never +# allocate objects on the 0 page in user mode. # # Notes # Non-zero values must be treated as Null Pointer Dereferences in # order to catch things such as: # -# \code # int *p = &s->f; /* this is ok, even if s is null */ -# *p = 42; /* this is where the program will -# * crash if s was null, because an -# * address such as '4' is being dereferenced -# * (assuming f is 4 bytes into s). */ -# \endcode +# *p = 42; /* this is where the program will +# * crash if s was null, because an +# * address such as '4' is being dereferenced +# * (assuming f is 4 bytes into s). */ # NULL_POINTER_THRESHOLD = 4096 # Parameter REPORT_TEMPLATE_UQ_WARNINGS # # Purpose -# Determines whether to report warnings in templated functions in -# warning classes for which something must hold on all paths. +# Determines whether warnings will be reported in templated +# functions when the warning class is one of those that requires +# some condition to hold on all paths. +# +# Tags +# - WARNING_TUNING: Fine Tuning for Warnings +# - WC_LANG.STRUCT.RC: Used by Redundant Condition +# - WC_LANG.STRUCT.UC: Used by Unreachable Code: 5 warning classes +# - WC_LANG.STRUCT.UVAL: Used by Unused Value +# - WC_LANG.STRUCT.UA: Used by Useless Assignment # # Type # {Yes, No} # -# Behavior +# Behavior # If set to "Yes", then warnings of classes requiring universal # quantification over paths will be reported in C++ templated -# functions. -# The affected warning classes are: -# - \wclink LANG.STRUCT.RC Redundant Condition \endwclink -# - The \wclink LANG.STRUCT.UC Unreachable Code \endwclink family: -# Unreachable Call, Unreachable Computation, Unreachable -# Conditional, Unreachable Control Flow, and Unreachable Data -# Flow -# - \wclink LANG.STRUCT.UVAL Unused Value \endwclink -# - \wclink LANG.STRUCT.UA Useless Assignment \endwclink +# functions. The affected warning classes are: +# - Redundant Condition +# - Unreachable Code: 5 warning classes +# - Unused Value +# - Useless Assignment # -# Notes +# Notes # Setting this to "Yes" will increase the false positive rate and # decrease the false negative rate for warning classes requiring # universal quantification over paths. # -# These warnings are often not very useful. For example, -# if( sizeof(T)==sizeof(int) ) is likely to cause some unreachable -# code in some template instantations, but this isn't interesting to -# most users. However, useful warnings in these functions will also +# These warnings are often not very useful. For example, if( +# sizeof(T)==sizeof(int) ) is likely to cause some unreachable code +# in some template instantations, but this isn't interesting to +# most users. However, useful warnings in these functions will also # be lost. # REPORT_TEMPLATE_UQ_WARNINGS = No @@ -2129,26 +2606,30 @@ # Determines whether exhaustive interprocedural exploration is # required before reporting warnings in classes for which something # must hold on all paths. # +# Tags +# - WARNING_TUNING: Fine Tuning for Warnings +# - WC_LANG.STRUCT.RC: Used by Redundant Condition +# - WC_LANG.STRUCT.UC: Used by Unreachable Code: 5 warning classes +# - WC_LANG.STRUCT.UVAL: Used by Unused Value +# - WC_LANG.STRUCT.UA: Used by Useless Assignment +# # Type # {Yes, No} # -# Behavior +# Behavior # 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: -# - \wclink LANG.STRUCT.RC Redundant Condition \endwclink -# - The \wclink LANG.STRUCT.UC Unreachable Code \endwclink family: -# Unreachable Call, Unreachable Computation, Unreachable -# Conditional, Unreachable Control Flow, and Unreachable Data -# Flow -# - \wclink LANG.STRUCT.UVAL Unused Value \endwclink -# - \wclink LANG.STRUCT.UA Useless Assignment \endwclink +# The default behavior is to suppress such warnings. The affected +# warning classes are: +# - Redundant Condition +# - Unreachable Code: 5 warning classes +# - Unused Value +# - Useless Assignment # -# Notes +# Notes # Setting this to "Yes" will increase the false positive rate and # decrease the false negative rate for warning classes requiring # universal quantification over paths. # @@ -2158,21 +2639,24 @@ # Parameter REPORT_PARTIAL_NTAD_WARNINGS # # Purpose # Determines whether exhaustive exploration is required before -# issuing a \wclink LANG.STRUCT.NTAD Null Test After Dereference -# \endwclink warning. +# issuing a Null Test After Dereference warning. +# +# Tags +# - WARNING_TUNING: Fine Tuning for Warnings +# - WC_LANG.STRUCT.NTAD: Used by Null Test After Dereference # # Type # {Yes, No} # -# Behavior -# 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 +# Behavior +# 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 +# Notes # Setting this to "Yes" will increase the false positive rate and # decrease the false negative rate for Null Test After Dereference # warnings. # @@ -2187,63 +2671,70 @@ # Purpose # Determines whether calls to undefined functions and function # pointer calls are considered exhaustively explored. # +# Tags +# - WARNING_TUNING: Fine Tuning for Warnings +# - WC_LANG.STRUCT.NTAD: Used by Null Test After Dereference +# - WC_LANG.STRUCT.RC: Used by Redundant Condition +# - WC_LANG.STRUCT.UC: Used by Unreachable Code: 5 warning classes +# - WC_LANG.STRUCT.UVAL: Used by Unused Value +# - WC_LANG.STRUCT.UA: Used by Useless Assignment +# # Type # {Yes, No} # -# Behavior +# Behavior # If set to "Yes", then warnings of classes requiring universal -# quantification over paths can be reported on statements preceded by -# calls to undefined functions or function pointer calls. The -# default behavior is to report such warnings. -# The affected warning classes are: -# - \wclink LANG.STRUCT.NTAD Null Test After Dereference \endwclink -# - \wclink LANG.STRUCT.RC Redundant Condition \endwclink -# - The \wclink LANG.STRUCT.UC Unreachable Code \endwclink family: -# Unreachable Call, Unreachable Computation, Unreachable -# Conditional, Unreachable Control Flow, and Unreachable Data -# Flow -# - \wclink LANG.STRUCT.UVAL Unused Value \endwclink -# - \wclink LANG.STRUCT.UA Useless Assignment \endwclink +# quantification over paths can be reported on statements preceded +# by calls to undefined functions or function pointer calls. The +# default behavior is to report such warnings. The affected warning +# classes are: +# - Null Test After Dereference +# - Redundant Condition +# - Unreachable Code: 5 warning classes +# - Unused Value +# - Useless Assignment # -# Notes +# Notes # Setting this to "Yes" will increase the false positive rate and # decrease the false negative rate for warning classes requiring -# universal quantification over paths. Using the setting "No" is +# universal quantification over paths. Using the setting "No" is # most useful if undefined functions and functions called using -# function pointers are modifying globals that are then tested by the -# calling function. +# function pointers are modifying globals that are then tested by +# the calling function. # UNDEF_FUNCS_EXHAUSTIVE = Yes # Parameter TIME_LIMIT_INTRA_EXPLORE # # Purpose -# Seconds the analysis may spend doing intraprocedural exploration in -# a single procedure. -# +# Seconds the analysis may spend doing intraprocedural exploration +# in a single procedure. +# +# Tags +# - TIME_LIMIT: Analysis Time Limits +# # Type # integer # # Behavior -# If this time limit expires, summaries for the procedure are rolled -# back and the analysis will treat call sites to the procedure as if -# the procedure is not defined in the project. +# If this time limit expires, summaries for the procedure are +# rolled back and the analysis will treat call sites to the +# procedure as if the procedure is not defined in the project. # # Notes # This specifies elapsed time. # -# This parameter affects checks for most warning classes. The classes -# NOT affected are: -# - \wclink LANG.CAST.FN Dangerous Function Cast \endwclink -# - \wclink LANG.STRUCT.EBS Empty {Branch, if, switch, while} -# Statement \endwclink -# - \wclink MISC.NOEFFECT Function Call Has No Effect \endwclink -# - \wclink MISC.NEGCHAR Negative Character Value \endwclink -# - \wclink LANG.CAST.VARARG Varargs Function Cast \endwclink -# +# 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 +# - Negative Character Value +# - Varargs Function Cast + TIME_LIMIT_INTRA_EXPLORE = 25 # Parameter TIME_LIMIT_INTRA_CLASSIFY @@ -2251,42 +2742,41 @@ # Purpose # Seconds the analysis may spend determining whether potential # intraprocedural vulnerabilities warrant further examination, per # procedure. -# +# +# Tags +# - TIME_LIMIT: Analysis Time Limits +# # Type # integer # # Behavior # Potential vulnerabilities nearer to the beginning of procedures -# receive preferential treatment. Once the time limit expires, +# receive preferential treatment. Once the time limit expires, # potential intraprocedural vulnerabilities starting in the current # procedure are ignored until the analysis moves on to the next # procedure. # # Notes -# This specifies elapsed time. The default limit is likely to be +# This specifies elapsed time. The default limit is likely to be # exceeded in large procedures. # -# This parameter affects checks for most warning classes. The classes -# NOT affected are: -# - \wclink LANG.CAST.FN Dangerous Function Cast \endwclink -# - \wclink LANG.STRUCT.EBS Empty {Branch, if, switch, while} -# Statement \endwclink -# - \wclink MISC.FMT Format String \endwclink -# - \wclink MISC.NOEFFECT Function Call Has No Effect \endwclink -# - \wclink LANG.FUNCS.IRV Ignored Return Value \endwclink -# - \wclink MISC.NEGCHAR Negative Character Value \endwclink -# - \wclink LANG.STRUCT.NTAD Null Test After Dereference \endwclink -# - \wclink LANG.STRUCT.ULOOP Potential Unbounded Loop \endwclink -# - \wclink LANG.STRUCT.RC Redundant Condition \endwclink -# - The \wclink LANG.STRUCT.UC Unreachable Code \endwclink family: -# Unreachable Call, Unreachable Computation, Unreachable -# Conditional, Unreachable Control Flow, and Unreachable Data -# Flow -# - \wclink LANG.STRUCT.UVAL Unused Value \endwclink -# - \wclink LANG.STRUCT.UA Useless Assignment \endwclink -# - \wclink LANG.CAST.VARARG Varargs Function Cast \endwclink +# 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 +# - Negative Character Value +# - Null Test After Dereference +# - Potential Unbounded Loop +# - Redundant Condition +# - Unreachable Code: 5 warning classes +# - Unused Value +# - Useless Assignment +# - Varargs Function Cast # TIME_LIMIT_INTRA_CLASSIFY = 8 @@ -2295,25 +2785,28 @@ # Purpose # Seconds the analysis may spend determining whether potential # interprocedural vulnerabilities warrant further examination, per # procedure. -# +# +# Tags +# - TIME_LIMIT: Analysis Time Limits +# # Type # integer # # Behavior # Potential vulnerabilities nearer to the beginning of procedures -# receive preferential treatment. Once the time limit expires, +# receive preferential treatment. Once the time limit expires, # potential interprocedural vulnerabilities starting in the current # procedure are ignored until the analysis moves on to the next # procedure. # # Notes -# This specifies elapsed time. The default limit is likely to be +# This specifies elapsed time. The default limit is likely to be # exceeded in large procedures. # -# The warning classes affected by this parameter are the same as those for -# \param TIME_LIMIT_INTRA_CLASSIFY. +# The warning classes affected by this parameter are the same as +# those for TIME_LIMIT_INTRA_CLASSIFY. # TIME_LIMIT_INTER_CLASSIFY = 8 @@ -2321,24 +2814,27 @@ # # Purpose # Seconds the analysis may spend resolving potential intra- and # interprocedural vulnerabilities, per procedure. -# +# # Type # integer # +# Tags +# - TIME_LIMIT: Analysis Time Limits +# # Behavior # Once likely vulnerabilities have been identified, an intermediate -# refinement step takes place. This preference limits the amount of +# refinement step takes place. This preference limits the amount of # time spent on the refinement step. # # Notes -# This specifies elapsed time. The default limit is extremely +# This specifies elapsed time. The default limit is extremely # unlikely to be exceeded 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. +# The warning classes affected by this parameter are the same as +# those for TIME_LIMIT_INTRA_CLASSIFY. # TIME_LIMIT_RESOLVE = 16 @@ -2346,49 +2842,52 @@ # # Purpose # Seconds the analysis may spend refining potential intra- and # interprocedural vulnerabilities, per procedure. -# +# +# Tags +# - TIME_LIMIT: Analysis Time Limits +# # Type # integer # # Behavior # Once likely vulnerabilities have been identified in the # 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 +# contained in the warning reports. If this limit expires, then # yet-to-be-refined likely vulnerabilities will be dropped. # # Notes # This specifies elapsed time. # -# The warning classes affected by this parameter are the same as those for -# \param TIME_LIMIT_INTRA_CLASSIFY. +# The warning classes affected by this parameter are the same as +# those for TIME_LIMIT_INTRA_CLASSIFY. # TIME_LIMIT_REFINE = 16 # Parameter TIME_LIMIT_RENDER # # Purpose -# Seconds the analysis may spend rendering intra- and interprocedural -# vulnerabilities, per procedure. -# +# Seconds the analysis may spend rendering intra- and +# interprocedural vulnerabilities, per procedure. +# # Type # integer # # Behavior -# Once a warning is identified, the analysis renders a warning report -# for presentation to the user. If the rendering phase takes longer -# than the limit specified here, the warning is discarded. -# -# Factors that can make rendering take a long time include extremely -# long lines of source code, deeply nested call stacks, and heavy use -# of the preprocessor. +# Once a warning is identified, the analysis renders a warning +# report for presentation to the user. If the rendering phase takes +# longer than the limit specified here, the warning is discarded. +# +# Factors that can make rendering take a long time include +# extremely long lines of source code, deeply nested call stacks, +# and heavy use of the preprocessor. # # Notes # The default limit is rarely exceeded and exists to guard against -# pathological constructs. +# pathological constructs. # # All warning classes can be affected by this limit. # TIME_LIMIT_RENDER = 60 @@ -2396,42 +2895,48 @@ # Parameter TIME_LIMIT_LEAK_CLASSIFY # # Purpose -# Seconds the analysis may spend determining whether potential -# \wclink ALLOC.LEAK Leaks\endwclink warrant further examination, per -# procedure. -# +# Seconds the analysis may spend determining whether potential Leak +# cases warrant further examination, per procedure. +# +# Tags +# - TIME_LIMIT: Analysis Time Limits +# - WC_ALLOC.LEAK: Used by Leak +# # Type # integer # # Behavior # Potential leaks nearer to the beginning of procedures receive # preferential treatment. # # Notes -# This specifies elapsed time. The default limit is -# not likely to be exceeded when the default value for \param -# SEARCH_BOUND is used. +# This specifies elapsed time. The default limit is not likely to +# be exceeded when the default value for SEARCH_BOUND is used. # TIME_LIMIT_LEAK_CLASSIFY = 20 # Parameter TIME_LIMIT_LEAK_REFINE # # Purpose -# Seconds the analysis may spend refining potential \wclink -# ALLOC.LEAK Leaks\endwclink, per procedure. -# +# Seconds the analysis may spend refining potential Leak cases, per +# procedure. +# +# Tags +# - TIME_LIMIT: Analysis Time Limits +# - WC_ALLOC.LEAK: Used by Leak +# # Type # integer # # Behavior -# Once likely leaks have been identified in the 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 leaks -# will be dropped. +# Once likely leaks have been identified in the 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 +# leaks will be dropped. # # Notes # This specifies elapsed time. # @@ -2442,45 +2947,50 @@ # # Purpose # Seconds the analysis may spend determining which parts of a # procedure have been exhaustively explored. -# +# +# Tags +# - TIME_LIMIT: Analysis Time Limits +# # Type # integer # # Behavior -# Some checks (such as those for the \wclink LANG.STRUCT.UC -# Unreachable Code \endwclink classes) can only be reported with -# respect to portions of procedures that have been exhaustively -# explored. Making this determination can sometimes be extremely -# expensive (typically in generated code). +# Some checks (such as those for Unreachable Code: 5 warning +# classes) can only be reported with respect to portions of +# procedures that have been exhaustively explored. Making this +# determination can sometimes be extremely expensive (typically in +# generated code). # # Notes -# This specifies elapsed time. The default limit is not -# likely to be exceeded: it exists to guard against pathological -# behavior. +# This specifies elapsed time. The default limit is not likely to +# be exceeded: it exists to guard against pathological behavior. # -# The warning classes affected by this parameter are the same as those for -# \param TIME_LIMIT_INTRA_CLASSIFY. +# The warning classes affected by this parameter are the same as +# those for TIME_LIMIT_INTRA_CLASSIFY. # TIME_LIMIT_PROP_EXHAUSTIVE = 60 + # Parameter TIME_LIMIT_DATA_RACE_PATH_SEARCH # # Purpose -# Seconds the analysis may spend searching for a feasible path for a -# particular pair of threads and a particular memory location. -# +# Seconds the analysis may spend searching for a feasible path for +# a particular pair of threads and a particular memory location. +# +# Tags +# - TIME_LIMIT: Analysis Time Limits +# # Type # integer # # Behavior -# If the time limit is exceeded, no \wclink CONCURRENCY.DATARACE Data -# Race\endwclink warnings will be reported for the relevant pair of -# threads and memory location. +# If the time limit is exceeded, no Data Race warnings will be +# reported for the relevant thread pair and memory location. # # Notes -# This specifies elapsed time. The default limit is unlikely to be +# This specifies elapsed time. The default limit is unlikely to be # exceeded and exists to guard against pathological behavior. # TIME_LIMIT_DATA_RACE_PATH_SEARCH = 600 @@ -2494,348 +3004,422 @@ # Type # non-negative integer # # Behavior -# If a procedure accesses more than this many shared variables, some -# variables will not be checked for data races. Raising this will result -# in a more thorough analysis, but will increase the time and memory -# used by the analysis. +# If a procedure accesses more than this many shared variables, +# some variables will not be checked for data races. Raising this +# will result in a more thorough analysis, but will increase the +# time and memory used by the analysis. # # Notes -# This only affects the analysis for \wclink CONCURRENCY.DATARACE -# Data Race\endwclink warnings. If this is set to a very high number -# (for example, more than 200,000) CodeSonar may behave unpredictably -# or crash. +# This only affects the analysis for Data Race warnings. If this is +# set to a very high number (for example, more than 200,000) +# CodeSonar may behave unpredictably or crash. # DATA_RACE_MAX_MEM_ACCESSES = 1000 # Parameter ROLLBACK_SUMMARIES_ON_ABORT # # Purpose -# Specifies whether or not function summaries will be rolled back if -# \param TIME_LIMIT_INTRA_EXPLORE expires. +# Specifies whether or not function summaries will be rolled back +# if TIME_LIMIT_INTRA_EXPLORE expires. +# +# Tags +# - ANALYSIS_PROPERTY: Analysis Properties # # Type # {Yes, No} # -# Behavior +# Behavior # If set to "Yes", 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. +# 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 -# and false negatives. +# Notes +# 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. # ROLLBACK_SUMMARIES_ON_ABORT = Yes # Parameter SEARCH_BOUND # -# Purpose +# Purpose # Number of paths under simultaneous consideration when exploring a # procedure. # +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit +# # Type # integer # -# Behavior +# Behavior # When the number is larger, more paths are searched, but more time # is used. # -# Notes +# Notes # This preference represents a trade-off between time and -# thoroughness. If this preference is raised, then \param +# thoroughness. If this preference is raised, then # TIME_LIMIT_INTRA_EXPLORE should usually also be raised. # SEARCH_BOUND = 100 +# Parameter EXPLORE_MORE_LOOP_PATHS +# +# Purpose +# Specifies whether or not the analysis should consider an extended +# set of loop execution scenarios. +# +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit +# +# Type +# {Yes, No} +# +# Behavior +# - No : The analysis will consider a standard set of loop +# repetition scenarios for each loop. +# - Yes : The analysis will consider several additional loop +# repetition scenarios along with the standard set. +# +# Notes +# Code may contain one or more defects that only manifest in one of +# the additional Yes scenarios, so analyzing with +# EXPLORE_MORE_LOOP_PATHS=Yes can reveal more true positives than +# analyzing with EXPLORE_MORE_LOOP_PATHS=No. +# +# Note, however, that path exploration is subject to various limits +# (including PATH_FINDING_EFFORT and SEARCH_BOUND), so setting this +# parameter to Yes does not guarantee that all the considered +# scenarios will ultimately be analyzed. + +EXPLORE_MORE_LOOP_PATHS = No + + # Parameter PATH_FINDING_EFFORT # -# Purpose -# Once a set of paths believed to contain at least one vulnerability -# is obtained, this many paths from the set will be searched before -# moving on. +# Purpose +# Once a set of paths believed to contain at least one +# vulnerability is obtained, this many paths from the set will be +# searched before moving on. +# +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit # # Type # integer # -# Behavior +# Behavior # A negative setting indicates that there is no limit. Too low a # (positive) setting can cause false negatives, but might save some # time in pathological cases. # -# Notes -# If this preference is raised, then \param TIME_LIMIT_RESOLVE should +# Notes +# If this preference is raised, then TIME_LIMIT_RESOLVE should # usually also be raised. # PATH_FINDING_EFFORT = 500 # Parameter PATH_SHORTENING_EFFORT # -# Purpose -# Once a set of paths believed to contain at least one vulnerability -# is obtained, and we have found a particular dangerous path within -# the set, this many total paths will be searched in an effort -# to find additional similar warnings within the set, or shorter -# versions of the same warning. Similar, in this context, is defined -# as a warning that violates the same (interprocedural) contract. +# Purpose +# Once a set of paths believed to contain at least one +# vulnerability is obtained, and we have found a particular +# dangerous path within the set, this many total paths will be +# searched in an effort to find additional similar warnings within +# the set, or shorter versions of the same warning. Similar, in +# this context, is defined as a warning that violates the same +# (interprocedural) contract. +# +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit # # Type # integer # -# Behavior +# Behavior # A negative setting indicates that there is no limit. Too low a # (positive) setting can cause false negatives, but might save some -# time. Setting this to 0 will prevent some warnings with similar +# time. Setting this to 0 will prevent some warnings with similar # causes to other warnings from being flagged. # # Notes -# If this preference is raised, then \param TIME_LIMIT_RESOLVE should +# If this preference is raised, then TIME_LIMIT_RESOLVE should # usually also be raised. # PATH_SHORTENING_EFFORT = 30 # Parameter REPORT_SIMILAR_WARNINGS # +# Purpose +# Specifies whether or not the analysis should report all members +# of each warning group +# [doc/html/Elements/PROPERTIES_Warning.html#group_def] detected +# (as opposed to a single representative instance +# [doc/html/Elements/PROPERTIES_Warning.html#representative_def] +# per group). +# +# Tags +# - WARNING_TUNING: Fine Tuning for Warnings +# # Type # {Yes, No} # -# Purpose -# Specifies whether or not the analysis should report all members of -# each \link ../Elements/PROPERTIES_Warning.html#group_def warning -# group\endlink detected (as opposed to a single \link -# ../Elements/PROPERTIES_Warning.html#representative_def -# representative instance\endlink per group). -# # Behavior -# If set to "Yes", the analysis will report all \link -# ../Elements/PROPERTIES_Warning.html#instance_def warning -# instances\endlink detected. -# -# If set to "No", the analysis will report one \link -# ../Elements/PROPERTIES_Warning.html#instance_def warning -# instance\endlink per warning group detected. +# - Yes : the analysis will report every warning instance +# [doc/html/Elements/PROPERTIES_Warning.html#instance_def] +# detected. +# - No : the analysis will report one warning instance +# [doc/html/Elements/PROPERTIES_Warning.html#instance_def] per +# warning group detected. # REPORT_SIMILAR_WARNINGS = Yes # Parameter MAX_SIMILAR_PATHS # -# Purpose -# Can influence the number of instances with similar paths that will -# be generated for a single warning. +# Purpose +# Can influence the number of instances with similar paths that +# will be generated for a single warning. +# +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit # # Type # integer # -# Notes -# "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 \wclink LANG.MEM.NPD Null Pointer Dereference \endwclink -# paths through both branches of the conditional statement, set \tt -# MAX_SIMILAR_PATHS to 2 (or higher). +# Notes +# "Similar paths" are paths with the same start and end points. For +# example, suppose you had the following code. +# int *p = 0; +# if( x ) +# x = 1; +# else +# x = 2; +# *p = 42; +# +# To see Null Pointer Dereference paths through both branches of +# the conditional statement, set MAX_SIMILAR_PATHS to 2 (or +# higher). # # Most users will never need a setting higher than 1 # -# This parameter does not significantly affect performance. +# This parameter does not significantly affect performance. # MAX_SIMILAR_PATHS = 1 # Parameter MAX_ATTEMPTED_SIMILAR_PATHS # -# Purpose +# Purpose # Bounds the number of potentially similar warnings that CodeSonar -# will attempt to refine. Both successfully refined warnings and +# will attempt to refine. Both successfully refined warnings and # dismissed warnings count against this limit. # +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit +# # Type # integer # -# Notes -# \param MAX_SIMILAR_PATHS is similar to this except that it bounds the -# number of reported warnings. \tt MAX_ATTEMPTED_SIMILAR_PATHS should -# always be at least as large as \tt MAX_SIMILAR_PATHS. +# Notes +# MAX_SIMILAR_PATHS is similar to this except that it bounds the +# number of reported warnings. MAX_ATTEMPTED_SIMILAR_PATHS should +# always be at least as large as MAX_SIMILAR_PATHS. # MAX_ATTEMPTED_SIMILAR_PATHS = 4 # Parameter MAX_CHECKED_INPUTS_PER_PROCEDURE # -# Purpose -# Specifies how many inputs to a procedure can be checked at call sites. +# Purpose +# Specifies how many inputs to a procedure can be checked at call +# sites. +# +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit # # Type # integer # -# Behavior +# Behavior # A negative value indicates no limit. Lower (positive) values will # conserve disk space and time, but can cause false negatives. # -# Notes -# This bound may be useful for projects containing millions of lines -# of code. +# Notes +# This bound may be useful for projects containing millions of +# lines of code. # -# Checks for code nearer to the beginning of procedures -# receive preferential treatment. +# Checks for code nearer to the beginning of procedures receive +# preferential treatment. # -# Both implicit and explicit inputs are counted. For example, both +# Both implicit and explicit inputs are counted. For example, both # the pointer passed to strlen() and the value pointed to by that -# pointer are counted as inputs to strlen(). Global variables -# transitively used by a procedure also qualify. +# pointer are counted as inputs to strlen(). Global variables +# transitively used by a procedure also qualify. # MAX_CHECKED_INPUTS_PER_PROCEDURE = 100 # Parameter MAX_CHECKS_PER_INPUT # -# Purpose -# Controls the maximum number of interprocedural checks that will be -# stored per input per procedure. When analyzing call sites to -# procedures, the tool examines whether these checks are satisfied in -# order to flag interprocedural vulnerabilities. +# Purpose +# Controls the maximum number of interprocedural checks that will +# be stored per input per procedure. When analyzing call sites to +# procedures, the tool examines whether these checks are satisfied +# in order to flag interprocedural vulnerabilities. +# +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit # # Type # integer # -# Behavior +# Behavior # A larger number means that more checks will be stored, with a # corresponding increase in disk and time usage. A smaller number -# will save on space and time, at the cost of potentially overlooking -# some positive results. +# will save on space and time, at the cost of potentially +# overlooking some positive results. # -# Notes +# Notes # In some (rare) cases, a larger bound will enable more # simplification to occur, improving performance and reducing false -# negatives. +# negatives. # MAX_CHECKS_PER_INPUT = 10 # Parameter MAX_GLOBAL_CHECK_AGE # -# Purpose -# Specifies how many levels up the call graph interprocedural checks -# on global variables can be propagated. +# Purpose +# Specifies how many levels up the call graph interprocedural +# checks on global variables can be propagated. +# +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit # # Type # integer # -# Behavior -# A negative value indicates no limit (this is usually best for small -# to medium sized projects). +# Behavior +# A negative value indicates no limit (this is usually best for +# small to medium sized projects). # -# Larger values will cause CodeSonar to perform a more thorough check -# at the expense of system resources. +# Larger values will cause CodeSonar to perform a more thorough +# check at the expense of system resources. # -# Notes +# Notes # Most interprocedural warnings tend to be caused by bad parameter -# values, not bad values in global variables. Many users will find +# 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 +# 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. # MAX_GLOBAL_CHECK_AGE = 0 # Parameter MAX_CHECK_COMPLEXITY # -# Purpose +# Purpose # Maximum complexity of an expression in an interprocedural check. # +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit +# # Type # integer # # Behavior # Checks on expressions whose complexity exceeds this limit are # discarded. # # Notes -# Expressions with more pointer dereferences and field/array accesses -# have a higher complexity. +# Expressions with more pointer dereferences and field/array +# accesses have a higher complexity. # MAX_CHECK_COMPLEXITY = 5 # Parameter MAX_EXPRESSION_COMPLEXITY # -# Purpose +# Purpose # A threshold for expression complexity. # +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit +# # Type # integer # # Behavior # Information about expressions whose complexity exceeds this limit # is discarded. # -# Notes -# Expressions with more pointer dereferences and field/array accesses -# have a higher complexity. +# Notes +# Expressions with more pointer dereferences and field/array +# accesses have a higher complexity. # MAX_EXPRESSION_COMPLEXITY = 12 # Parameter MAX_SUMMARIES_PER_PROCEDURE # -# Purpose -# Controls how many summaries per procedure will be stored in memory. +# Purpose +# Controls how many summaries per procedure will be stored in +# memory. +# +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit # # Type # integer # -# Behavior +# Behavior # Increasing the value for this preference may allow more precise # analysis, at the cost of longer analysis time and higher memory # usage. # # Notes -# Complex procedures with a large number of possible effects may have -# a correspondingly large number of summaries. If this number +# Complex procedures with a large number of possible effects may +# have a correspondingly large number of summaries. If this number # exceeds the per-procedure maximum, CodeSonar will generate a # smaller number of summaries designed to preserve as much -# information as possible from the original set. When the full set of -# original summaries is desired, change the value of this +# information as possible from the original set. When the full set +# of original summaries is desired, change the value of this # preference accordingly. # MAX_SUMMARIES_PER_PROCEDURE = 5 # Parameter MAX_MODIFIED_VALUES # -# Purpose +# Purpose # Specifies a per-procedure bound on the number of modified values -# (outputs) that CodeSonar will keep track of in procedure summaries. +# (outputs) that CodeSonar will keep track of in procedure +# summaries. +# +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit # # Type # integer # -# Behavior +# Behavior # If a procedure modifies more values than this maximum, CodeSonar -# will select values to discard from the summaries for the procedure -# to bring the total number of values tracked down to the +# will select values to discard from the summaries for the +# procedure to bring the total number of values tracked down to the # maximum. Increasing the value for this preference may allow more # precise analysis, at the cost of longer analysis time and higher # memory usage. # -# Notes +# Notes # The values modified by a procedure may include its return value, # parameters and values from its calling environment, and values # derived from these. # @@ -2843,37 +3427,43 @@ # Parameter RETURN_CHECKER_SAMPLE_SIZE # -# Purpose +# 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 an \wclink LANG.FUNCS.IRV Ignored Return Value \endwclink for -# that function. +# about an Ignored Return Value for that function. +# +# Tags +# - WARNING_THRESHOLD: Warning-Class-Specific Thresholds +# - WC_LANG.FUNCS.IRV: Used by Ignored Return Value # # Type # integer # -# Behavior +# Behavior # A smaller value will cause more warnings based on statistical -# decisions. Negative values are prohibited. +# decisions. Negative values are prohibited. # RETURN_CHECKER_SAMPLE_SIZE = 20 # Parameter RETURN_CHECKER_RATIO # -# Purpose -# Sets a threshold T. If the number of ignored call sites to a given -# function is at least T times the number of heeded call sites, no -# \wclink LANG.FUNCS.IRV Ignored Return Value \endwclink warnings -# will be produced. +# Purpose +# Sets a threshold T. If the number of ignored call sites to a +# given function is at least T times the number of heeded call +# sites, no Ignored Return Value warnings will be produced. +# +# Tags +# - WARNING_THRESHOLD: Warning-Class-Specific Thresholds +# - WC_LANG.FUNCS.IRV: Used by Ignored Return Value # # Type # Real number between 0 and 1 (inclusive) # -# Behavior -# Making this number larger will cause more warnings. A value of 0 +# Behavior +# Making this number larger will cause more warnings. A value of 0 # will effectively disable statistical warnings. # RETURN_CHECKER_RATIO = 0.04 @@ -2876,34 +3466,39 @@ # will effectively disable statistical warnings. # RETURN_CHECKER_RATIO = 0.04 + # Parameter RETURN_CHECKER_CHECKED_FUNCS # -# Purpose -# Used by \wclink LANG.FUNCS.IRV Ignored Return Value\endwclink to -# specify exceptions to the statistical analysis: functions whose -# return values will always trigger a warning if ignored. +# Purpose +# Used by Ignored Return Value to specify exceptions to the +# statistical analysis: functions whose return values will always +# trigger a warning if ignored. +# +# Tags +# - WARNING_SPECIAL_FUNCTIONS: Designates Specially-Treated +# Functions +# - WC_LANG.FUNCS.IRV: Used by Ignored Return Value # # Type -# \link -# ../../../../third-party/boost/libs/regex/doc/html/boost_regex/syntax.html -# Boost regular expression\endlink +# Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] # -# Behavior -# If the name of a called function matches a \tt +# Behavior +# If the name of a called function matches a # RETURN_CHECKER_CHECKED_FUNCS regular expression and the return # value from that function call is ignored, an Ignored Return Value -# warning will always be issued (regardless of the settings of \param -# RETURN_CHECKER_SAMPLE_SIZE and \param RETURN_CHECKER_RATIO). +# warning will always be issued (regardless of the settings of +# RETURN_CHECKER_SAMPLE_SIZE and RETURN_CHECKER_RATIO). # -# If the Ignored Return Value warning class is disabled, such as with -# a \param WARNING_FILTER rule, this parameter has no effect. +# If the Ignored Return Value warning class is disabled, such as +# with a WARNING_FILTER rule, this parameter has no effect. # # Notes # This parameter replaces the csonar_return_check() function -# previously available in the \link ../Extensions/Extensions.html -# Extension API\endlink. +# previously available in the Extension API +# [doc/html/Extensions/Extensions.html]. # RETURN_CHECKER_CHECKED_FUNCS += ^access$ RETURN_CHECKER_CHECKED_FUNCS += ^bind$ @@ -3043,137 +3638,151 @@ # Parameter RETURN_CHECKER_IGNORED_FUNCS # -# Purpose -# Used by \wclink LANG.FUNCS.IRV Ignored Return Value\endwclink to -# specify exceptions to the statistical analysis: functions whose -# return values can be ignored without triggering a warning. +# Purpose +# Used by Ignored Return Value to specify exceptions to the +# statistical analysis: functions whose return values can be +# ignored without triggering a warning. +# +# Tags +# - WARNING_SPECIAL_FUNCTIONS: Designates Specially-Treated +# Functions +# - WC_LANG.FUNCS.IRV: Used by Ignored Return Value # # Type -# \link -# ../../../../third-party/boost/libs/regex/doc/html/boost_regex/syntax.html -# Boost regular expression\endlink +# Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] # -# Behavior -# If the name of a called function matches a \tt +# Behavior +# If the name of a called function matches a # RETURN_CHECKER_IGNORED_FUNCS regular expression and the return # value from that function call is ignored, an Ignored Return Value -# warning will not be issued (regardless of the settings of \param -# RETURN_CHECKER_SAMPLE_SIZE and \param RETURN_CHECKER_RATIO). +# warning will not be issued (regardless of the settings of +# RETURN_CHECKER_SAMPLE_SIZE and RETURN_CHECKER_RATIO). # -# If the Ignored Return Value warning class is disabled, such as with -# a \param WARNING_FILTER rule, this parameter has no effect. +# If the Ignored Return Value warning class is disabled, such as +# with a WARNING_FILTER rule, this parameter has no effect. # # Notes # This parameter replaces the csonar_ignore_return() function -# previously available in the \link ../Extensions/Extensions.html -# Extension API\endlink. +# previously available in the Extension API +# [doc/html/Extensions/Extensions.html]. # RETURN_CHECKER_IGNORED_FUNCS += ^strchr$ RETURN_CHECKER_IGNORED_FUNCS += ^strlen$ RETURN_CHECKER_IGNORED_FUNCS += ^std::basic_ostream::operator<<()$ +RETURN_CHECKER_IGNORED_FUNCS += ^std::basic_string::_M_data$ +RETURN_CHECKER_IGNORED_FUNCS += ^std::basic_streambuf::eback()$ +RETURN_CHECKER_IGNORED_FUNCS += ^std::_Tree_val::_Right$ +RETURN_CHECKER_IGNORED_FUNCS += ^std::_Tree_val::_Left$ +RETURN_CHECKER_IGNORED_FUNCS += ^std::_Tree_val::_Parent$ +RETURN_CHECKER_IGNORED_FUNCS += ^std::_Tree::_Parent$ # Parameter FORMAT_STRING_CHECKER_SAMPLE_SIZE # -# Purpose +# 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 \wclink MISC.FMT -# Format String \endwclink problems. +# considered large enough to warn the user about Format String +# problems. +# +# Tags +# - WARNING_THRESHOLD: Warning-Class-Specific Thresholds +# - WC_MISC.FMT: Used by Format String # # Type # integer # -# Behavior +# Behavior # A smaller value will cause more warnings based on statistical -# decisions. Negative values are prohibited. +# decisions. Negative values are prohibited. # FORMAT_STRING_CHECKER_SAMPLE_SIZE = 20 # Parameter FORMAT_STRING_CHECKER_RATIO # -# Purpose +# Purpose # Sets a threshold T such that for fixed k, if the number of call # sites to a given function without a format string in the k'th -# argument position is at least T times the number of call sites with -# a format string in the k'th argument position, no \wclink MISC.FMT -# Format String \endwclink warnings will be produced for the -# function/position pair. +# argument position is at least T times the number of call sites +# with a format string in the k'th argument position, no Format +# String warnings will be produced for the function/position pair. +# +# Tags +# - WARNING_THRESHOLD: Warning-Class-Specific Thresholds +# - WC_MISC.FMT: Used by Format String # # Type # Real number between 0 and 1 (inclusive) # -# Behavior -# Making this number larger will cause more warnings. A value of 0 +# Behavior +# Making this number larger will cause more warnings. A value of 0 # will effectively disable statistical warnings. # FORMAT_STRING_CHECKER_RATIO = 0.4 # Parameter FORMAT_STRING_CHECKER_CHECKED_FUNCS # -# Purpose -# Used by \wclink MISC.FMT Format String\endwclink to specify -# exceptions to the statistical analysis: (position, regular -# expression) pairs such that calls to functions whose names match -# the specified regular expression must always have a format string -# argument in the specified position. +# Purpose +# Used by Format String to specify exceptions to the statistical +# analysis: (position, regular expression) pairs such that calls to +# functions whose names match the specified regular expression must +# always have a format string argument in the specified position. +# +# Tags +# - WARNING_SPECIAL_FUNCTIONS: Designates Specially-Treated +# Functions +# - WC_MISC.FMT: Used by Format String # # Type # A string of the form -# \code -# , -# \endcode +# , # where: -# - \tt is an argument position (counting from 1) -# - \tt is an \link ../Asides/STkRegExp.html STk-style regular -# expression\endlink -# -# Behavior -# Calling a function whose name matches \tt without a format -# string in the \tt 'th parameter position will always trigger a -# Format String warning, regardless of the settings of \param -# FORMAT_STRING_CHECKER_SAMPLE_SIZE and \param +# - is an argument position (counting from 1) +# - is a Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] +# +# Behavior +# Calling a function whose name matches without a format +# string in the 'th parameter position will always trigger a +# Format String warning, regardless of the settings of +# FORMAT_STRING_CHECKER_SAMPLE_SIZE and # FORMAT_STRING_CHECKER_RATIO. # -# If the Format String warning class is disabled, such as with -# a \param WARNING_FILTER rule, this parameter has no effect. +# If the Format String warning class is disabled, such as with a +# WARNING_FILTER rule, this parameter has no effect. # # Notes # This parameter replaces the csonar_format_string_check() function -# previously available in the \link ../Extensions/Extensions.html -# Extension API\endlink. +# previously available in the Extension API +# [doc/html/Extensions/Extensions.html]. # FORMAT_STRING_CHECKER_CHECKED_FUNCS += 1, ^__eprintf$ -FORMAT_STRING_CHECKER_CHECKED_FUNCS += 1, ^_[ct]printf$ -FORMAT_STRING_CHECKER_CHECKED_FUNCS += 1, ^_ftprintf$ -FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^_s[tw]printf$ -FORMAT_STRING_CHECKER_CHECKED_FUNCS += 3, ^_v?sn[tw]?printf$ -FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^_v?stprintf$ +FORMAT_STRING_CHECKER_CHECKED_FUNCS += 1, ^_cprintf$ +FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^_swprintf$ +FORMAT_STRING_CHECKER_CHECKED_FUNCS += 3, ^_v?snw?printf$ +FORMAT_STRING_CHECKER_CHECKED_FUNCS += 4, ^_v?snw?printf_s$ FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^fwprintf$ FORMAT_STRING_CHECKER_CHECKED_FUNCS += 3, ^sn?wprintf$ FORMAT_STRING_CHECKER_CHECKED_FUNCS += 1, ^v?w?printf$ FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^v?[fs]printf$ FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^vfwprintf$ FORMAT_STRING_CHECKER_CHECKED_FUNCS += 3, ^v?snprintf$ -FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^vstprintf$ FORMAT_STRING_CHECKER_CHECKED_FUNCS += 3, ^vswprintf$ -FORMAT_STRING_CHECKER_CHECKED_FUNCS += 3, ^wnsprintf[AW]?$ -FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^wsprintf[AW]?$ +FORMAT_STRING_CHECKER_CHECKED_FUNCS += 3, ^wnsprintf[AW]?$ +FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^wsprintf[AW]?$ FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^wvsprintf$ -FORMAT_STRING_CHECKER_CHECKED_FUNCS += 3, ^wvnsprintf[AW]?$ +FORMAT_STRING_CHECKER_CHECKED_FUNCS += 3, ^wvnsprintf[AW]?$ FORMAT_STRING_CHECKER_CHECKED_FUNCS += 1, ^(__isoc99_)?_cscanf$ -FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^(__isoc99_)?_[fs]tscanf$ -FORMAT_STRING_CHECKER_CHECKED_FUNCS += 1, ^(__isoc99_)?_tscanf$ -FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^(__isoc99_)?f[tw]?scanf$ +FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^(__isoc99_)?fw?scanf$ FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^(__isoc99_)?sw?scanf$ FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^(__isoc99_)?v?[fs]scanf$ -FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^(__isoc99_)?vftscanf$ FORMAT_STRING_CHECKER_CHECKED_FUNCS += 1, ^(__isoc99_)?[vw]?scanf$ FORMAT_STRING_CHECKER_CHECKED_FUNCS += 3, ^StringCchPrintf$ FORMAT_STRING_CHECKER_CHECKED_FUNCS += 2, ^v?syslog$ FORMAT_STRING_CHECKER_CHECKED_FUNCS += 1, ^CH?String::FormatV?$ @@ -3182,154 +3791,238 @@ # Parameter FORMAT_STRING_CHECKER_IGNORED_FUNCS # -# Purpose -# Used by \wclink MISC.FMT Format String\endwclink to specify -# exceptions to the statistical analysis: (position, regular -# expression) pairs such that calls to functions whose names match -# the specified regular expression are never required to have a -# format string argument in the specified position. +# Purpose +# Used by Format String to specify exceptions to the statistical +# analysis: (position, regular expression) pairs such that calls to +# functions whose names match the specified regular expression are +# never required to have a format string argument in the specified +# position. +# +# Tags +# - WARNING_SPECIAL_FUNCTIONS: Designates Specially-Treated +# Functions +# - WC_MISC.FMT: Used by Format String # # Type # A string of the form -# \code -# , -# \endcode +# , # where: -# - \tt is an argument position (counting from 1) -# - \tt is an \link ../Asides/STkRegExp.html STk-style regular -# expression\endlink -# -# Behavior -# Calling a function whose name matches \tt without a format -# string in the \tt 'th parameter position will not trigger a -# Format String warning, regardless of the settings of \param -# FORMAT_STRING_CHECKER_SAMPLE_SIZE and \param +# - is an argument position (counting from 1) +# - is a Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] +# +# Behavior +# Calling a function whose name matches without a format +# string in the 'th parameter position will not trigger a +# Format String warning, regardless of the settings of +# FORMAT_STRING_CHECKER_SAMPLE_SIZE and # FORMAT_STRING_CHECKER_RATIO. # -# If the Format String warning class is disabled, such as with -# a \param WARNING_FILTER rule, this parameter has no effect. +# If the Format String warning class is disabled, such as with a +# WARNING_FILTER rule, this parameter has no effect. # # Notes -# This parameter replaces the csonar_ignore_format_string() function -# previously available in the \link ../Extensions/Extensions.html -# Extension API\endlink. +# This parameter replaces the csonar_ignore_format_string() +# function previously available in the Extension API +# [doc/html/Extensions/Extensions.html]. # FORMAT_STRING_CHECKER_IGNORED_FUNCS += 3, ^strftime$ # Parameter MULTIPLE_THREADS_PER_ENTRY_PROCEDURE # # Purpose -# Specifies whether CodeSonar should assume every thread entry point is -# used to create multiple threads that run concurrently. +# Specifies whether CodeSonar should assume every thread entry +# point is used to create multiple threads that run concurrently. +# +# Tags +# - WC_CONCURRENCY.DATARACE: Used by Data Race # # Type # {Yes, No} # # Behavior -# If set to Yes, CodeSonar will report Data Race warnings in which both -# threads start at the same entry procedure/method. Normally, only -# warnings between threads that start at different points are reported. +# If set to Yes, CodeSonar will report Data Race warnings in which +# both threads start at the same entry procedure/method. Normally, +# only warnings between threads that start at different points are +# reported. # -# Note -# Setting this to Yes can result in a large number of false positive -# Data Race warnings, especially for applications that use many -# "singleton threads". +# Notes +# Setting this to Yes can result in a large number of false +# positive Data Race warnings, especially for applications that use +# many "singleton threads". # MULTIPLE_THREADS_PER_ENTRY_PROCEDURE = No + +# Parameter DATA_RACE_IGNORE_NAMES +# +# Purpose +# Sometimes certain variables or procedures should be ignored for +# the purpose of data race detection. The classic example is errno, +# which appears to be a normal global variable, but is made thread- +# local by all modern C/C++ implementations. DATA_RACE_IGNORE_NAMES +# provides a way to extend the set of variables and procedures that +# the data race analysis should ignore. +# +# Tags +# - WC_CONCURRENCY.DATARACE: Used by Data Race +# +# Type +# Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] +# +# Behavior +# The data race analysis checks all global variables and procedure +# names to see if they match one of the specified patterns. No data +# races will be reported on accesses to matching variables or +# inside of matching procedures. The general analysis engine will +# still track matching variables and procedures as usual. +# +# Notes +# +# Example rules: +# DATA_RACE_IGNORE_NAMES += ^errno$ +# DATA_RACE_IGNORE_NAMES += ^run$ +# + + +# Parameter FORCE_THREAD_ENTRY_NAMES +# +# Purpose +# Sometimes the analysis engine cannot find all the thread entry +# procedures/methods in a program. The most common cause of missing +# entry points is the use of closure-like wrappers around the +# "true" thread entry procedures. This parameter can be used to +# force the analysis engine to treat specific procedures as thread +# entry points. +# +# Tags +# - WC_CONCURRENCY.DATARACE: Used by Data Race +# +# Type +# Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] +# +# Behavior +# The analysis engine checks all procedures and methods to see if +# they match one of the specified patterns. Matching procedures are +# considered thread entry points, even if CodeSonar's regular +# thread entry discovery mechanisms cannot prove that. +# +# Notes +# +# Example rules: +# FORCE_THREAD_ENTRY_NAMES += ^f1$ +# FORCE_THREAD_ENTRY_NAMES += ^handler$ +# + + # Parameter THREAD_ENTRY_METHOD_NAMES # # Purpose -# For programs that use an object-oriented multithreading -# API. Specifies which method on an object should be considered the -# "entry method" when the object (or a reference to it) is specified -# as a thread entry point. +# For programs that use an object-oriented multithreading API. +# Specifies which method on an object should be considered the +# "entry method" when the object (or a reference to it) is +# specified as a thread entry point. +# +# Tags +# - WARNING_SPECIAL_FUNCTIONS: Designates Specially-Treated +# Functions +# - WC_CONCURRENCY.DATARACE: Used by Data Race # # Type -# \link ../Asides/STkRegExp.html STk-style regular expression\endlink +# Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] # # Behavior # If an object (or object reference) is used in a location where a # thread entry point procedure is expected, CodeSonar will scan the -# object's class hierarchy for a method whose name matches one of the -# specified patterns. +# object's class hierarchy for a method whose name matches one of +# the specified patterns. # - If such a method is found, it will be used as a thread entry # procedure. # - Otherwise, no thread entry point is discovered. If the thread -# contributed to a data race, the analysis will not be able to detect -# that race. +# contributed to a data race, the analysis will not be able to +# detect that race. # -# Note -# CodeSonar uses \tt THREAD_ENTRY_METHOD_NAMES settings to determine +# Notes +# CodeSonar uses THREAD_ENTRY_METHOD_NAMES settings to determine # which method on an object should be considered the "entry method" # when the object is specified as a thread entry point. This # parameter is only suitable for use with object-oriented # multithreading APIs. # -# To specify that an arbitrary function provides a thread -# entry point, you will need to write a model for that function. See -# the manual section on \link -# ../C_Module/LibraryModels/ConcurrencyModels.html concurrency -# models\endlink for details. +# To specify that an arbitrary function provides a thread entry +# point, you will need to write a model for that function. See the +# manual section on concurrency models +# [doc/html/C_Module/LibraryModels/ConcurrencyModels.html] for +# details. # # Example rule: -# \code # THREAD_ENTRY_METHOD_NAMES += ^Main$ -# \endcode THREAD_ENTRY_METHOD_NAMES += ^run$ # Parameter SEMOPEN_FUNCTIONS # # Purpose -# Used by the lock-related checks to identify the procedures used to -# open named semaphores +# Used by the lock-related checks to identify the procedures used +# to open named semaphores +# +# Tags +# - WARNING_SPECIAL_FUNCTIONS: Designates Specially-Treated +# Functions # # Type -# \link ../Asides/STkRegExp.html STk-style regular expression\endlink +# Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] # # Behavior # The analysis will treat all functions whose names match patterns -# in \tt SEMOPEN_FUNCTIONS as semaphore-opening functions. -# The analysis assumes that the first parameter is a string that -# represents the name of the semaphore. +# in SEMOPEN_FUNCTIONS as semaphore-opening functions. The analysis +# assumes that the first parameter is a string that represents the +# name of the semaphore. # # Notes # Functions that open named semaphores are expected to return the -# same semaphore address each time they are successfully called with -# the same name, until that semaphore is unlinked or -# closed. Identifying a function f() with SEMOPEN_FUNCTIONS ensures -# that the CodeSonar analysis correctly associates these properties -# with f(). -# -# For more information, see the manual section on \link -# ../C_Module/LibraryModels/ConcurrencyModels.html concurrency -# models\endlink. -# -# Example rule: -# \code -# SEMOPEN_FUNCTIONS += ^semOpen$ -# SEMOPEN_FUNCTIONS += ^sem_open$ -# \endcode +# same semaphore address each time they are successfully called +# with the same name, until that semaphore is unlinked or closed. +# Identifying a function f() with SEMOPEN_FUNCTIONS ensures that +# the CodeSonar analysis correctly associates these properties with +# f(). +# +# For more information, see the manual section on concurrency +# models [doc/html/C_Module/LibraryModels/ConcurrencyModels.html]. +# +# Example rules: +# SEMOPEN_FUNCTIONS += ^semOpen$ +# SEMOPEN_FUNCTIONS += ^sem_open$ # Parameter LOCK_FUNCTIONS # # Purpose -# Used by the \wclink CONCURRENCY.LOCK.NOLOCK Missing Lock -# Acquisition\endwclink and \wclink CONCURRENCY.LOCK.NOUNLOCK Missing -# Lock Release\endwclink checks to identify functions that should be -# treated as if they directly acquire locks. +# Used by the CONCURRENCY.LOCK.* checks +# [doc/html/WarningClasses/MnemonicHierarchy.html#CONCURRENCY_LOCK] +# to identify functions that should be treated as if they directly +# acquire locks. +# +# Tags +# - WARNING_SPECIAL_FUNCTIONS: Designates Specially-Treated +# Functions +# - WC_CONCURRENCY.LOCK.NOLOCK: Used by Missing Lock Acquisition +# - WC_CONCURRENCY.LOCK.NOUNLOCK: Used by Missing Lock Release # # Type -# \link ../Asides/STkRegExp.html STk-style regular expression\endlink +# Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] # # Behavior # The analysis will treat all functions whose names match patterns -# in \param LOCK_FUNCTIONS as lock-acquiring functions. The analysis +# in LOCK_FUNCTIONS as lock-acquiring functions. The analysis # assumes that the first parameter is a pointer to the lock object. # # Notes # Use this parameter to identify wrapper functions for lock @@ -3338,56 +4031,58 @@ # the bodies of the wrappers themselves. # # For example, suppose a project uses wrapper mylock(): # -# \code -# void mylock(GMutex *m){ -# /* ... */ -# g_mutex_lock(m); -# return; -# } -# -# void nounlock(GMutex *m){ -# mylock(m); -# } -# \endcode +# void mylock(GMutex *m){ +# /* ... */ +# g_mutex_lock(m); +# return; +# } +# +# void nounlock(GMutex *m){ +# mylock(m); +# } # # If we set LOCK_FUNCTIONS += ^mylock$, the analysis will issue a # "Missing Lock Release" in the body of function nounlock(). # # If we do not specify that mylock is a lock function with # LOCK_FUNCTIONS, the analysis will not issue a "Missing Lock -# Release" warning in the body of function nounlock(), but WILL issue -# a "Missing Lock Release" warning in the body of mylock(). +# Release" warning in the body of function nounlock(), but WILL +# issue a "Missing Lock Release" warning in the body of mylock(). +# +# Functions that have library models identifying them as lock +# acquirers do not need to be specified with LOCK_FUNCTIONS: they +# will automatically be treated correctly. # -# Functions that have library models identifying them as -# lock acquirers do not need to be specified with LOCK_FUNCTIONS: -# they will automatically be treated correctly. -# -# For more information, see the manual section on \link -# ../C_Module/LibraryModels/ConcurrencyModels.html concurrency -# models\endlink. +# For more information, see the manual section on concurrency +# models [doc/html/C_Module/LibraryModels/ConcurrencyModels.html]. # # Example rule: -# \code # LOCK_FUNCTIONS += ^my_lock_wrapper$ -# \endcode # Parameter UNLOCK_FUNCTIONS # # Purpose -# Used by the \wclink CONCURRENCY.LOCK.NOLOCK Missing Lock -# Acquisition\endwclink and \wclink CONCURRENCY.LOCK.NOUNLOCK Missing -# Lock Release\endwclink checks to identify functions that should be -# treated as if they directly acquire locks. +# Used by the CONCURRENCY.LOCK.* checks +# [doc/html/WarningClasses/MnemonicHierarchy.html#CONCURRENCY_LOCK] +# to identify functions that should be treated as if they directly +# release locks. +# +# Tags +# - WARNING_SPECIAL_FUNCTIONS: Designates Specially-Treated +# Functions +# - WC_CONCURRENCY.LOCK.NOLOCK: Used by Missing Lock Acquisition +# - WC_CONCURRENCY.LOCK.NOUNLOCK: Used by Missing Lock Release # # Type -# \link ../Asides/STkRegExp.html STk-style regular expression\endlink +# Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] # # Behavior # The analysis will treat all functions whose names match patterns -# in \param UNLOCK_FUNCTIONS as lock-releasing functions. The analysis +# in UNLOCK_FUNCTIONS as lock-releasing functions. The analysis # assumes that the first parameter is a pointer to the lock object. # # Notes # Use this parameter to identify wrapper functions for lock @@ -3396,123 +4091,160 @@ # the bodies of the wrappers themselves. # # For example, suppose a project uses wrapper myunlock(): # -# \code -# void myunlock(GMutex *m){ -# g_mutex_unlock(m); -# /* ... */ -# return; -# } -# -# void nolock(GMutex *m){ -# myunlock(m); -# } -# \endcode -# -# If we set UNLOCK_FUNCTIONS += ^myunlock$, the analysis will issue a -# "Missing Lock Acquisition" warning in the body of function nolock(). +# void myunlock(GMutex *m){ +# g_mutex_unlock(m); +# /* ... */ +# return; +# } +# +# void nolock(GMutex *m){ +# myunlock(m); +# } +# +# If we set UNLOCK_FUNCTIONS += ^myunlock$, the analysis will issue +# a "Missing Lock Acquisition" warning in the body of function +# nolock(). # # If we do not use LOCK_FUNCTIONS specify that myunlock is a unlock -# function, the analysis will not issue a "Missing Lock Acquisition" -# warning in the body of function nounlock(), but WILL issue a -# "Missing Lock Acquisition" warning in the body of myunlock(). -# -# Functions that have library models identifying them as -# lock releasers do not need to be specified with UNLOCK_FUNCTIONS: -# they will automatically be treated correctly. -# -# For more information, see the manual section on \link -# ../C_Module/LibraryModels/ConcurrencyModels.html concurrency -# models\endlink. +# function, the analysis will not issue a "Missing Lock +# Acquisition" warning in the body of function nounlock(), but WILL +# issue a "Missing Lock Acquisition" warning in the body of +# myunlock(). +# +# Functions that have library models identifying them as lock +# releasers do not need to be specified with UNLOCK_FUNCTIONS: they +# will automatically be treated correctly. +# +# For more information, see the manual section on concurrency +# models [doc/html/C_Module/LibraryModels/ConcurrencyModels.html]. # # Example rule: -# \code -# UNLOCK_FUNCTIONS += ^my_unlock_wrapper$ -# \endcode +# UNLOCK_FUNCTIONS += ^my_unlock_wrapper$ + + +# Parameter LOCK_MAX_PENDING_WARNINGS_PER_PROCEDURE +# +# Purpose +# Bounds the number of potential lock-related warnings that +# CodeSonar will consider during the analysis of any particular +# function. +# +# Type +# non-negative integer +# +# Behavior +# If during the analysis of a procedure, more than this many +# potential lock-related warnings are identified, some of the +# potential warnings will be dropped. Raising this may result in a +# more thorough analysis, but will increase the time and memory +# used by the analysis. +# +# Notes +# This only affects the analysis for CONCURRENCY.LOCK.* checks +# [doc/html/WarningClasses/MnemonicHierarchy.html#CONCURRENCY_LOCK]. +# It is quite unusual for this limit to be reached. However, if it +# is set to a very high number (for example, more than 200,000) +# CodeSonar may behave unpredictably or crash. +# +## LOCK_MAX_PENDING_WARNINGS_PER_PROCEDURE = 1000 # Parameter CALL_SITE_EXPANSIONS # -# Purpose +# Purpose # Specifies the extent to which the CodeSonar analysis will expand # call sites for full analysis instead of using summaries to # approximate the behavior of the call. # -# Type +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit +# +# Type # {None, Some, More, Most} # -# Behavior +# Behavior # A call site will only be expanded if it is on a path and is # especially relevant. -# +# # A higher value for this preference can reduce the number of false # positive results, but will make the analysis take longer. # -# Notes -# If a call site on some path is expanded in the CodeSonar analysis, -# the corresponding HTML warning report will allow navigation into -# the call site. This provides a more complete depiction of program -# behavior, but increases the size of the output. +# Notes +# If a call site on some path is expanded in the CodeSonar +# analysis, the corresponding HTML warning report will allow +# navigation into the call site. This provides a more complete +# depiction of program behavior, but increases the size of the +# output. # CALL_SITE_EXPANSIONS = Some -# CALL_SITE_EXPANSIONS = None -# CALL_SITE_EXPANSIONS = More -# CALL_SITE_EXPANSIONS = Most +## CALL_SITE_EXPANSIONS = None +## CALL_SITE_EXPANSIONS = More +## CALL_SITE_EXPANSIONS = Most # Parameter CALL_SITE_EXPANSION_BOUND # -# Purpose -# Places a bound on the nesting depth of call site expansions (nested -# "+" widgets in warning reports). +# Purpose +# Places a bound on the nesting depth of call site expansions +# (nested "+" widgets in warning reports). +# +# Tags +# - ANALYSIS_BOUND: Analysis time/effort limit # # Type # integer # -# Notes +# Notes # A limit that is too high may cause CodeSonar to have a stack # overflow. The default limit is only encountered in pathological # cases: only one program capable of inducing a stack overflow has # ever been found in the wild. -# +# CALL_SITE_EXPANSION_BOUND = 30 # Parameter ABRIDGE_HTML # -# Purpose -# Determines whether HTML warning reports may abridge procedure listings -# in order to show only the most relevant parts. +# Purpose +# Determines whether HTML warning reports may abridge procedure +# listings in order to show only the most relevant parts. +# +# Tags +# - HUB_BEHAVIOR: Hub and Web GUI # # Type # {Yes, No} # -# Behavior -# When set to "No": if a path includes any part of a procedure, the -# warning report will show all of the procedure. +# Behavior +# - No: if a path includes any part of a procedure, the warning +# report will show all of the procedure. # ABRIDGE_HTML = Yes -# Parameter MAX_FUNCTION_LENGTH +# Parameter MAX_FUNCTION_LENGTH # # Purpose -# Used by the \wclink LANG.FUNCS.TOOLONG Function Too Long\endwclink -# check: specifies the maximum allowable length of a function. +# Used by the Function Too Long check: specifies the maximum +# allowable length of a function. +# +# Tags +# - WARNING_THRESHOLD: Warning-Class-Specific Thresholds +# - WC_LANG.FUNCS.TOOLONG: Used by Function Too Long # # Type # non-negative integer # # Behavior -# CodeSonar will emit a \wclink LANG.FUNCS.TOOLONG Function Too Long -# \endwclink warning for functions whose \link -# ../Metrics/Metrics.html#LCode Lines With Code\endlink exceeds this -# value. -# Notes -# Note that the \wclink LANG.FUNCS.TOOLONG Function Too -# Long\endwclink check is disabled by default: use a \param -# WARNING_FILTER rule to enable it. +# CodeSonar will issue a Function Too Long warning for functions +# whose Lines With Code [doc/html/Metrics/Metrics.html#LCode] +# exceeds this value. +# +# Notes +# Note that the Function Too Long check is disabled by default: use +# a WARNING_FILTER rule to enable it. # MAX_FUNCTION_LENGTH = 60 @@ -3521,268 +4253,287 @@ # Purpose # Specifies the maximum allowable numbers of parameters a function # can have to comply with the Too Many Parameters check. # +# Tags +# - WARNING_THRESHOLD: Warning-Class-Specific Thresholds +# - WC_LANG.FUNCS.TMFP: Used by Too Many Parameters +# # Type # non-negative integer # # Behavior -# CodeSonar will emit a \wclink LANG.FUNCS.TMFP Too Many Paramaters -# \endwclink warning for functions that have more parameters -# than specified here. +# CodeSonar will emit a Too Many Parameters warning for functions +# that have more parameters than specified here. # # Notes -# Note that the \wclink LANG.FUNCS.TMFP Too Many Parameters -# \endwclink check is disabled by default: use a \param -# WARNING_FILTER rule to enable it. +# Note that the Too Many Parameters check is disabled by default: +# use a WARNING_FILTER rule to enable it. # MAX_NUM_PARAMS = 6 # Parameter MIN_ASSERTS # # Purpose -# Used by the \wclink LANG.FUNCS.ASSERTS Not Enough -# Assertions\endwclink check: specifies the minimum number of -# assertions each function must contain. +# Used by the Not Enough Assertions check: specifies the minimum +# number of assertions each function must contain. +# +# Tags +# - WARNING_THRESHOLD: Warning-Class-Specific Thresholds +# - WC_LANG.FUNCS.ASSERTS: Used by Not Enough Assertions # # Type # non-negative integer # # Behavior -# CodeSonar will emit a \wclink LANG.FUNCS.ASSERTS Not Enough -# Assertions\endwclink warning when it detects a function with fewer -# calls to a recognizable assert function, provided that the function -# length exceeds the \param MIN_ASSERTS_FUNCTION_LENGTH threshold. +# CodeSonar will emit a Not Enough Assertions warning when it +# detects a function with fewer calls to a recognizable assert +# function, provided that the function length exceeds the +# MIN_ASSERTS_FUNCTION_LENGTH threshold. # # Notes -# Note that the \wclink LANG.FUNCS.ASSERTS Not Enough -# Assertions\endwclink check is disabled by default: use a \param -# WARNING_FILTER rule to enable it. +# Note that the Not Enough Assertions check is disabled by default: +# use a WARNING_FILTER rule to enable it. # MIN_ASSERTS = 2 # Parameter MIN_ASSERTS_FUNCTION_LENGTH # # Purpose -# Used by the \wclink LANG.FUNCS.ASSERTS Not Enough -# Assertions\endwclink check: specifies the minimum length a -# function must have to be subject to the check. +# Used by the Not Enough Assertions check: specifies the minimum +# length a function must have to be subject to the check. # # Type # non-negative integer # +# Tags +# - WARNING_THRESHOLD: Warning-Class-Specific Thresholds +# - WC_LANG.FUNCS.ASSERTS: Used by Not Enough Assertions +# # Behavior # CodeSonar will only check the number of assertions in functions -# whose \link ../Metrics/Metrics.html#LCode Lines With Code\endlink +# whose Lines With Code [doc/html/Metrics/Metrics.html#LCode] # exceeds this value. # # Notes -# Note that the \wclink LANG.FUNCS.ASSERTS Not Enough -# Assertions\endwclink check is disabled by default: use a \param -# WARNING_FILTER rule to enable it. +# Note that the Not Enough Assertions check is disabled by default: +# use a WARNING_FILTER rule to enable it. # MIN_ASSERTS_FUNCTION_LENGTH = 0 # Parameter MAX_PERMITTED_DEREFS # # Purpose -# Used by the \wclink LANG.STRUCT.TMD Too Many Dereferences\endwclink -# check: specifies the maximum number of dereferencing levels -# permitted on a single item. +# Used by the Too Many Dereferences check: specifies the maximum +# number of dereferencing levels permitted on a single item. +# +# Tags +# - WARNING_THRESHOLD: Warning-Class-Specific Thresholds +# - WC_LANG.STRUCT.TMD: Used by Too Many Dereferences # # Type # non-negative integer # # Behavior # If an item is dereferenced by more levels than allowed by this -# parameter, CodeSonar will issue a \wclink LANG.STRUCT.TMD Too Many -# Dereferences\endwclink warning. +# parameter, CodeSonar will issue a Too Many Dereferences warning. # # Notes -# For example, -# - "*x" has a maximum of one dereference, +# For example, +# - "*x" has a maximum of one dereference, # - "*x = *y" also has a maximum of one dereference, -# - "*x[0] = *y" has a maximum of two dereferences. +# - "*x[0] = *y" has a maximum of two dereferences. # -# Note that the \wclink LANG.STRUCT.TMD Too Many -# Dereferences\endwclink check is disabled by default: use a \param -# WARNING_FILTER rule to enable it. +# Note that the Too Many Dereferences check is disabled by default: +# use a WARNING_FILTER rule to enable it. # MAX_PERMITTED_DEREFS = 1 # Parameter MAX_PERMITTED_INDIRECTION_IN_DECLARATION # # Purpose # Specifies the maximum levels of indirection allowed in a -# declaration to comply with the \wclink LANG.STRUCT.TMID Too Much -# Indirection in Declaration\endwclink check. +# declaration to comply with the Too Much Indirection in +# Declaration check. +# +# Tags +# - WARNING_THRESHOLD: Warning-Class-Specific Thresholds +# - WC_LANG.STRUCT.TMID: Used by Too Much Indirection in +# Declaration # # Type # non-negative integer # # Behavior -# CodeSonar will emit a \wclink LANG.STRUCT.TMID Too Much Indirection -# in Declaration\endwclink warning when it detects a number of -# indirections greater than this setting. +# CodeSonar will emit a Too Much Indirection in Declaration warning +# when it detects a number of indirections greater than this +# setting. # # Notes -# For example, the following declaration has two levels of indirection: -# \code +# For example, the following declaration has two levels of +# indirection: # int **x -# \endcode # -# Note that the \wclink LANG.STRUCT.TMID Too Much Indirection -# in Declaration\endwclink check is disabled by default: use a \param -# WARNING_FILTER rule to enable it. +# Note that the Too Much Indirection in Declaration check is +# disabled by default: use a WARNING_FILTER rule to enable it. +# MAX_PERMITTED_INDIRECTION_IN_DECLARATION = 2 # Parameter SCOPE_CHECK_SUGGESTS_LOCAL_STATIC # # Purpose -# Determines how the analysis will report variables that can -# be local static but are declared with file or global scope. +# Determines how the analysis will report variables that can be +# local static but are declared with file or global scope. +# +# Tags +# - WARNING_THRESHOLD: Warning-Class-Specific Thresholds +# - WC_LANG.STRUCT.SCOPE.LOCAL: Used by Scope Could Be Local Static +# - WC_LANG.STRUCT.SCOPE.FILE: Used by Scope Could Be File Static # # Type # {Yes, No} # # Behavior -# If "Yes", variables that are global or file static but could be -# local static will trigger \wclink LANG.STRUCT.SCOPE.LOCAL Scope -# Could Be Local Static\endwclink warnings. -# -# If "No", variables that are global but could be local static will -# trigger \wclink LANG.STRUCT.SCOPE.FILE Scope Could Be File -# Static\endwclink warnings; variables that are file static but could -# be local static do not trigger any scope warning. +# - Yes : variables that are global or file static but could be +# local static will trigger Scope Could Be Local Static warnings. +# - No : variables that are global but could be local static will +# trigger Scope Could Be File Static warnings; variables that are +# file static but could be local static do not trigger any scope +# warning. # # Notes -# Setting to "No" means that no warnings of class \wclink -# LANG.STRUCT.SCOPE.LOCAL Scope Could Be Local Static\endwclink will -# be issued by the analysis. +# Setting to "No" means that no warnings of class Scope Could Be +# Local Static will be issued by the analysis. # -# The \wclink LANG.STRUCT.SCOPE.FILE Scope Could Be File -# Static\endwclink check and the \wclink LANG.STRUCT.SCOPE.LOCAL -# Scope Could Be Local Static\endwclink check are disabled by -# default: use \param WARNING_FILTER rules to enable them. +# The Scope Could Be File Static check and the Scope Could Be Local +# Static check are disabled by default: use WARNING_FILTER rules to +# enable them. # -# SCOPE_CHECK_SUGGESTS_LOCAL_STATIC = Yes +## SCOPE_CHECK_SUGGESTS_LOCAL_STATIC = Yes # Parameter PTR_INSIDE_TYPEDEF_EXCEPTION # # Purpose -# Used by the \wclink LANG.STRUCT.PIT Pointer Type Inside -# Typedef\endwclink check: specifies types whose typedefs are allowed -# to contain pointer types. +# Used by the Pointer Type Inside Typedef check: specifies types +# whose typedefs are allowed to contain pointer types. +# +# Tags +# - WC_LANG.STRUCT.PIT: Used by Pointer Type Inside Typedef # # Type -# \link -# ../../../../third-party/boost/libs/regex/doc/html/boost_regex/syntax.html -# Boost regular expression\endlink +# Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] # # Behavior -# \wclink LANG.STRUCT.PIT Pointer Type Inside Typedef\endwclink -# warnings will not be issued for typedefs whose type name matches a -# regular expression in the \tt PTR_INSIDE_TYPEDEF_EXCEPTION set, -# even if the typedef contains a pointer type. +# Pointer Type Inside Typedef warnings will not be issued for +# typedefs whose type name matches a regular expression in the +# PTR_INSIDE_TYPEDEF_EXCEPTION set, even if the typedef contains a +# pointer type. # -# Notes +# Notes # For example, -# \code -# PTR_INSIDE_TYPEDEF_EXCEPTION += _ptr$ -# \endcode -# specifies that typedefs whose name end with _ptr are allowed to have -# pointers in their definitions. -# -# Note that the \wclink LANG.STRUCT.PIT Pointer Type Inside -# Typedef\endwclink check is disabled by default: use a \param -# WARNING_FILTER rule to enable it. +# PTR_INSIDE_TYPEDEF_EXCEPTION += _ptr$ +# specifies that typedefs whose name end with _ptr are allowed to +# have pointers in their definitions. +# +# Note that the Pointer Type Inside Typedef check is disabled by +# default: use a WARNING_FILTER rule to enable it. + PTR_INSIDE_TYPEDEF_EXCEPTION += _ptr$ # Parameter DFS_MAX_VISITED_COEFFICIENT # Parameter DFS_MAX_VISITED_CONSTANT # # Purpose -# Used by the \wclink LANG.FUNCS.RECURSION Recursion\endwclink and -# \wclink ALLOC.POSTINIT Dynamic Allocation After -# Initialization\endwclink checks to compute an upper bound on the -# number of procedures the depth-first search in these checks can -# visit in an incremental run. +# Used by the Recursion and Dynamic Allocation After Initialization +# checks to compute an upper bound on the number of procedures the +# depth-first search in these checks can visit in an incremental +# run. +# +# Tags +# - WARNING_TUNING: Fine Tuning for Warnings +# - WC_LANG.FUNCS.RECURSION: Used by Recursion +# - WC_ALLOC.POSTINIT: Used by Dynamic Allocation After +# Initialization # # Type -# \tt DFS_MAX_VISITED_COEFFICIENT : non-negative integer -# -# \tt DFS_MAX_VISITED_CONSTANT : non-negative integer +# - DFS_MAX_VISITED_COEFFICIENT : non-negative integer +# - DFS_MAX_VISITED_CONSTANT : non-negative integer # # Behavior -# The depth-first search used by the \wclink LANG.FUNCS.RECURSION -# Recursion\endwclink and \wclink ALLOC.POSTINIT Dynamic Allocation -# After Initialization\endwclink checks is bounded on incremental +# The depth-first search used by the Recursion and Dynamic +# Allocation After Initialization checks is bounded on incremental # analyses in proportion to the total number of procedures changed -# since the last analysis. +# since the last analysis. # -# Specifically, the depth-first search will terminate after visiting a number -# of procedures equal to: -# \tt DFS_MAX_VISITED_COEFFICIENT * (# of procedures changed) -# + \tt DFS_MAX_VISITED_CONSTANT +# Specifically, the depth-first search will terminate after +# visiting a number of procedures equal to: +# \tt DFS_MAX_VISITED_COEFFICIENT * (# of procedures changed) +# + \tt DFS_MAX_VISITED_CONSTANT # # Notes -# Note that the \wclink LANG.FUNCS.RECURSION Recursion\endwclink and -# \wclink ALLOC.POSTINIT Dynamic Allocation After -# Initialization\endwclink checks are disabled by default: use \param -# WARNING_FILTER rules to enable them. +# Note that the Recursion and Dynamic Allocation After +# Initialization checks are disabled by default: use WARNING_FILTER +# rules to enable them. # DFS_MAX_VISITED_COEFFICIENT = 8 DFS_MAX_VISITED_CONSTANT = 128 # Parameter DFS_MAX_LOCAL_VISITED # # Purpose -# Used by the \wclink LANG.FUNCS.RECURSION Recursion\endwclink and -# \wclink ALLOC.POSTINIT Dynamic Allocation After -# Initialization\endwclink checks: specifies a bound on the number -# of procedures visited by a single local depth-first search +# Used by the Recursion and Dynamic Allocation After Initialization +# checks: specifies a bound on the number of procedures visited by +# a single local depth-first search +# +# Tags +# - WARNING_TUNING: Fine Tuning for Warnings +# - WC_LANG.FUNCS.RECURSION: Used by Recursion +# - WC_ALLOC.POSTINIT: Used by Dynamic Allocation After +# Initialization # # Type # non-negative integer # # Behavior -# In incremental analyses, the depth-first search used by the \wclink -# LANG.FUNCS.RECURSION Recursion\endwclink and \wclink ALLOC.POSTINIT -# Dynamic Allocation After Initialization\endwclink checks descends -# from each procedure that changed since the last analysis. Each -# local depth-first search will visit at most \tt +# In incremental analyses, the depth-first search used by the +# Recursion and Dynamic Allocation After Initialization checks +# descends from each procedure that changed since the last +# analysis. Each local depth-first search will visit at most # DFS_MAX_LOCAL_VISITED procedures. # -# This works in conjunction with the \param -# DFS_MAX_VISITED_COEFFICIENT and \param DFS_MAX_VISITED_CONSTANT -# configuration options to bound the depth-first search: it prevents -# a single depth-first search from hitting the global bound and -# starving any subsequent searches. +# This works in conjunction with the DFS_MAX_VISITED_COEFFICIENT +# and DFS_MAX_VISITED_CONSTANT configuration options to bound the +# depth-first search: it prevents a single depth-first search from +# hitting the global bound and starving any subsequent searches. # # Notes -# Note that the \wclink LANG.FUNCS.RECURSION Recursion\endwclink and -# \wclink ALLOC.POSTINIT Dynamic Allocation After -# Initialization\endwclink checks are disabled by default: use -# \param WARNING_FILTER rules to enable them. +# Note that the Recursion and Dynamic Allocation After +# Initialization checks are disabled by default: use WARNING_FILTER +# rules to enable them. # DFS_MAX_LOCAL_VISITED = 16 # Parameter DATA_RACE_PATH_FINDING_EFFORT # # Purpose -# Used by the data race analysis to limit the amount of effort spent -# searching for a feasible path in a particular set of potential -# paths. +# Used by the Data Race analysis to limit the amount of effort +# spent searching for a feasible path in a particular set of +# potential paths. +# +# Tags +# - WARNING_TUNING: Fine Tuning for Warnings +# - WC_CONCURRENCY.DATARACE: Used by Data Race # # Type # non-negative integer # @@ -3791,46 +4542,50 @@ # explored in the search for a feasible path. # # Notes # The data race analysis builds up large sets of program paths that -# could be involved in data races. After the main code analysis +# could be involved in data races. After the main code analysis # completes, the data race detector must search through its -# (potentially quite large) sets of paths to find pairs of paths that -# represent a real race. Searching through these sets can be quite -# time consuming, so \tt DATA_RACE_PATH_FINDING_EFFORT gives a +# (potentially quite large) sets of paths to find pairs of paths +# that represent a real race. Searching through these sets can be +# quite time consuming, so DATA_RACE_PATH_FINDING_EFFORT gives a # mechanism to limit the amount of time spent on the search. # DATA_RACE_PATH_FINDING_EFFORT = 10000 # Parameter STACK_DEPTH_THRESHOLD # # Purpose -# Used by the \wclink LANG.STRUCT.CALLSTACK Excessive Stack -# Depth\endwclink check: specifies the maximum allowable depth of the -# call stack, in bytes. +# Used by the Excessive Stack Depth check: specifies the maximum +# allowable depth of the call stack, in bytes. +# +# Tags +# - WARNING_THRESHOLD: Warning-Class-Specific Thresholds +# - WC_LANG.STRUCT.CALLSTACK: Used by Excessive Stack Depth # # Type # integer # # Behavior -# If this threshold is exceeded, CodeSonar will issue a \wclink -# LANG.STRUCT.CALLSTACK Excessive Stack Depth\endwclink warning. +# If this threshold is exceeded, CodeSonar will issue a Excessive +# Stack Depth warning. # # Notes -# Note that the \wclink LANG.STRUCT.CALLSTACK Excessive Stack -# Depth\endwclink check is disabled by default: use a \param -# WARNING_FILTER rule to enable it. +# Note that the Excessive Stack Depth check is disabled by default: +# use a WARNING_FILTER rule to enable it. # STACK_DEPTH_THRESHOLD = 65536 # Parameter STACK_DEPTH_UNDEFINED_FUNCTION_SIZE # # Purpose -# Used by the \wclink LANG.STRUCT.CALLSTACK Excessive Stack -# Depth\endwclink check: estimates the activation record size for -# undefined functions. +# Used by the Excessive Stack Depth check: estimates the activation +# record size for undefined functions. +# +# Tags +# - WC_LANG.STRUCT.CALLSTACK: Used by Excessive Stack Depth # # Type # integer # @@ -3838,21 +4593,22 @@ # CodeSonar will treat calls to undefined functions as contributing # this many bytes to the call stack depth. # # Notes -# Note that the \wclink LANG.STRUCT.CALLSTACK Excessive Stack -# Depth\endwclink check is disabled by default: use a \param -# WARNING_FILTER rule to enable it. +# Note that the Excessive Stack Depth check is disabled by default: +# use a WARNING_FILTER rule to enable it. # STACK_DEPTH_UNDEFINED_FUNCTION_SIZE = 128 # Parameter STACK_DEPTH_COMPILER_PADDING # # Purpose -# Used by the \wclink LANG.STRUCT.CALLSTACK Excessive Stack -# Depth\endwclink check: estimates the word size to which a compiler -# will pad individual variables. +# Used by the Excessive Stack Depth check: estimates the word size +# to which a compiler will pad individual variables. +# +# Tags +# - WC_LANG.STRUCT.CALLSTACK: Used by Excessive Stack Depth # # Type # integer # @@ -3860,178 +4616,176 @@ # 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. +# 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. # # Notes -# Note that the \wclink LANG.STRUCT.CALLSTACK Excessive Stack -# Depth\endwclink check is disabled by default: use a \param -# WARNING_FILTER rule to enable it. +# Note that the Excessive Stack Depth check is disabled by default: +# use a WARNING_FILTER rule to enable it. # STACK_DEPTH_COMPILER_PADDING = 4 # Parameter STACK_DEPTH_ACTIVATION_RECORD_CONSTANTS # # Purpose -# Used by the \wclink LANG.STRUCT.CALLSTACK Excessive Stack -# Depth\endwclink check: estimates the the size of the constant -# elements the compiler pushes on the call stack for each activation -# record. +# Used by the Excessive Stack Depth check: estimates the the size +# of the constant elements the compiler pushes on the call stack +# for each activation record. +# +# Tags +# - WC_LANG.STRUCT.CALLSTACK: Used by Excessive Stack Depth # # Type # integer # # Behavior # 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. +# 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. +# For example, the return address is stored on the call stack for +# every activation record. # # Notes -# Note that the \wclink LANG.STRUCT.CALLSTACK Excessive Stack -# Depth\endwclink check is disabled by default: use a \param -# WARNING_FILTER rule to enable it. +# Note that the Excessive Stack Depth check is disabled by default: +# use a WARNING_FILTER rule to enable it. # STACK_DEPTH_ACTIVATION_RECORD_CONSTANTS = 12 + # Parameter STACK_DEPTH_MODULES # -# Purpose -# Used by \wclink LANG.STRUCT.CALLSTACK Excessive Stack Depth\endwclink -# to specify the entry point of a module and the maximum allowable depth -# of the call stack of this module, in bytes. +# Purpose +# Used by Excessive Stack Depth to specify the entry point of a +# module and the maximum allowable depth of the call stack of that +# module. +# +# Tags +# - WC_LANG.STRUCT.CALLSTACK: Used by Excessive Stack Depth # # Type # A string of the form -# \code -# , -# \endcode +# , # where: -# - \tt is the maximum allowable depth. -# - \tt is an \link -# ../../../../third-party/boost/libs/regex/doc/html/boost_regex/syntax.html -# Boost regular expression\endlink +# - is the maximum allowable depth, in bytes. +# - is a Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] # -# Behavior +# Behavior # If the stack depth of the module entry point exceeds the module's -# threshold, CodeSonar will issue a \wclink -# LANG.STRUCT.CALLSTACK Excessive Stack Depth\endwclink warning. +# threshold, CodeSonar will issue a Excessive Stack Depth warning. # # Notes -# If any STACK_DEPTH_MODULES is specified -- even if none of them -# match any function -- CodeSonar won't check for project wide -# stack depth violations. +# If any STACK_DEPTH_MODULES are specified - even if none of them +# match any function - CodeSonar won't check for project-wide stack +# depth violations. # -# STACK_DEPTH_MODULES += 65536, ^module_1_init$ +## STACK_DEPTH_MODULES += 65536, ^module_1_init$ + # Parameter STACK_DEPTH_TERMINATE_FUNCTIONS # -# Purpose -# Used by \wclink LANG.STRUCT.CALLSTACK Excessive Stack Depth\endwclink -# to specify functions whose callees should be ignored when computing -# the stack depth of the function. +# Purpose +# Used by Excessive Stack Depth to specify functions whose callees +# should be ignored when computing the stack depth of the function. +# +# Tags +# - WC_LANG.STRUCT.CALLSTACK: Used by Excessive Stack Depth # # Type # string # -# Behavior +# Behavior # If the name of a function equals to the string given, the stack # depth of the function will only be computed from its locals. # -# STACK_DEPTH_TERMINATE_FUNCTIONS += foo +## STACK_DEPTH_TERMINATE_FUNCTIONS += funcname -# Parameter UNDEFINED_FUNCTIONS_HAVE_SIDE_EFFECTS -# -# Purpose -# Specifies whether or not undefined functions should be considered as -# having side effects by \wclink Condition Contains Call\endwclink -# -# Type -# {Yes, No} -# -UNDEFINED_FUNCTIONS_HAVE_SIDE_EFFECTS = Yes -# Parameter CHECK_EMPTY_BRANCH +# Parameter UNDEFINED_FUNCTIONS_HAVE_SIDE_EFFECTS # # Purpose -# Specifies whether or not CodeSonar will check for conditional -# statements with empty bodies. +# Specifies whether or not undefined functions should be considered +# as having side effects by the Condition Contains Side Effects +# check. +# +# Tags +# - LANGUAGE_TREATMENT: Treatment of Language Constructs +# - WC_LANG.STRUCT.SIDEEFFECT: Used by Condition Contains Side +# Effects # # Type # {Yes, No} -# -# Behavior -# If "Yes", CodeSonar will carry out checks for the following warning classes: -# - \wclink LANG.STRUCT.EBS Empty Branch Statement \endwclink -# - \wclink LANG.STRUCT.EBS Empty if Statement \endwclink -# - \wclink LANG.STRUCT.EBS Empty switch Statement \endwclink -# - \wclink LANG.STRUCT.EBS Empty while Statement \endwclink -# -# If "No", these checks will not be carried out. # -CHECK_EMPTY_BRANCH = Yes +UNDEFINED_FUNCTIONS_HAVE_SIDE_EFFECTS = Yes # Parameter EMIT_PROCEDURE_SIDE_EFFECTS # # Purpose -# Specifies whether or not CodeSonar will output an xml file showing -# the variables modified by each procedure. +# Specifies whether or not CodeSonar will output an xml file +# showing the variables modified by each procedure. +# +# Tags +# - BUILD_OUTPUT: Additional Outputs from the Build/Analysis # # Type # {Yes, No} -# +# # Notes # Modifications are stated in terms of inputs to the procedure. # EMIT_PROCEDURE_SIDE_EFFECTS = No # Parameter REPORT_UNUSED_ASSIGNMENTS_FROM_CONSTANTS # -# Purpose -# Specifies whether or not CodeSonar will issue \wclink -# LANG.STRUCT.UVAL Unused Value \endwclink warnings for values that -# arise from constant assignments. +# Purpose +# Specifies whether or not CodeSonar will issue Unused Value +# warnings for values that arise from constant assignments. +# +# Tags +# - WC_LANG.STRUCT.UVAL: Used by Unused Value +# - WARNING_TUNING: Fine Tuning for Warnings # # Type # {Yes, No} # # Behavior -# If "Yes", CodeSonar will issue Unused Value warnings in cases like: -# \code -# x = 3; -# \endcode +# If "Yes", CodeSonar will issue Unused Value warnings in cases +# like: +# x = 3; # -# If "No", such cases will not trigger Unused Value warnings. +# If "No", such cases will not trigger Unused Value warnings. # REPORT_UNUSED_ASSIGNMENTS_FROM_CONSTANTS = No # Parameter REPORT_REDUNDANT_CONDITIONS_BASED_ON_CONSTANTS # -# Purpose -# Specifies whether or not CodeSonar will issue \wclink -# LANG.STRUCT.RC Redundant Condition \endwclink warnings for -# conditions testing constant values. +# Purpose +# Specifies whether or not CodeSonar will issue Redundant Condition +# warnings for conditions testing constant values. +# +# Tags +# - WC_LANG.STRUCT.RC: Used by Redundant Condition +# - WARNING_TUNING: Fine Tuning for Warnings # # Type # {Yes, No} # # Behavior -# If "Yes", CodeSonar will issue Redundant Condition warnings in cases like: -# \code -# if ( 0 ) -# ... -# \endcode +# If "Yes", CodeSonar will issue Redundant Condition warnings in +# cases like: +# if ( 0 ) +# ... # -# If "No", such cases will not trigger Redundant Condition warnings. +# If "No", such cases will not trigger Redundant Condition +# warnings. # REPORT_REDUNDANT_CONDITIONS_BASED_ON_CONSTANTS = No @@ -4044,11 +4798,11 @@ # String of the form "A -> B" where A and B are function names. # # Behavior # The value "A -> B" indicates that CodeSonar should treat calls to -# function A as calls to function B. This is equivalent to writing a -# stub using csonar_replace_A that calls B, but may be more -# convenient. +# function A as calls to function B. This is equivalent to writing +# a stub using csonar_replace_A that calls B, but may be more +# convenient. # # If A -> B and B -> C then A ->C # # The behavior is undefined if @@ -4057,32 +4811,27 @@ # - there are cycles in the function map. # # Notes # The most common use cases are: -# - Designating functions that end program execution. -# - Designating \tt malloc and \tt free workalikes. +# - Designating functions that end program execution. +# - Designating malloc and free workalikes. # -# For multiple mappings, use a separate \tt FUNCTION_MAP += statement +# For multiple mappings, use a separate FUNCTION_MAP += statement # for each mapping. # -# This feature cannot be used with C++ identifiers containing spaces. -# +# This feature cannot be used with C++ identifiers containing +# spaces. +# # Examples: # -# To specify that \tt fatal causes the program to abort: -# \code -# FUNCTION_MAP += fatal -> abort -# \endcode -# -# To specify that \tt pmalloc behaves like \tt malloc: -# \code -# FUNCTION_MAP += pmalloc -> malloc -# \endcode -# -# To specify that \tt pfree behaves like \tt free: -# \code -# FUNCTION_MAP += pfree -> free -# \endcode +# To specify that fatal causes the program to abort: +# FUNCTION_MAP += fatal -> abort +# +# To specify that pmalloc behaves like malloc: +# FUNCTION_MAP += pmalloc -> malloc +# +# To specify that pfree behaves like free: +# FUNCTION_MAP += pfree -> free # FUNCTION_MAP += @@ -4091,183 +4840,241 @@ # Purpose # Specifies whether or not the CodeSonar analysis should check C++ # compilation units. # +# Tags +# - LANGUAGE_TREATMENT: Treatment of Language Constructs +# # 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. +# - Yes : CodeSonar will ignore all C++ compilation units: C++ code +# will not be checked. +# - No : CodeSonar will check both C and C++ compilation units. # IGNORE_CPP_CODE = No # Parameter ERROR_SUBMISSION_LIMIT_PER_COMPILATION # # Purpose -# Specifies the maximum number of parse errors submitted to the hub -# for a compilation. +# Specifies the maximum number of parse errors submitted to the hub +# for a compilation. +# +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis # # Type -# integer. -1 means "no limit" +# integer. -1 means "no limit" # # Behavior -# No more than the specified number of errors will be submitted to -# the hub for any single compilation. If the number of errors for -# the compilation exceeds the specified number, a "There are more -# errors" entry is submitted. +# No more than the specified number of errors will be submitted to +# the hub for any single compilation. If the number of errors for +# the compilation exceeds the specified number, a "There are more +# errors" entry is submitted. # # Notes -# This parameter has no effect on whether or not a compilation is -# included in the analysis. +# This parameter has no effect on whether or not a compilation is +# included in the analysis. # ERROR_SUBMISSION_LIMIT_PER_COMPILATION = 30 # Parameter VOLATILE_TREATMENT # # Purpose -# Specifies whether reads through volatile types always result in -# unknown values. +# Specifies whether reads through volatile types always result in +# unknown values. +# +# Tags +# - LANGUAGE_TREATMENT: Treatment of Language Constructs # # Type # {UNKNOWABLE, ADVERSARIAL, IGNORE} # # Behavior -# If set to "UNKNOWABLE", any attempt to read through a volatile -# type will result in an unknown value that is not considered -# adversarial. -# -# If set to "ADVERSARIAL", any attempt to read through a volatile -# type will result in an adversarial value. -# -# If set to "IGNORE", CodeSonar ignores the \tt volatile keyword. -# -# Notes -# The following test case will produce a \wclink LANG.MEM.NPD Null -# Pointer Dereference\endwclink warning if this preference is set to -# "UNKNOWABLE" or "ADVERSARIAL". -# \code -# int *p = 0; -# volatile int i; -# i = 5; -# if( i != 5 ) -# *p; -# \endcode -# -# The following test case will produce a \wclink LANG.ARITH.DIVZERO -# Division By Zero \endwclink warning if this preference is set to -# "ADVERSARIAL". -# \code -# volatile int i; -# i = 5; -# 10 / i; -# \endcode -# -# The following test case will produce a \wclink -# LANG.ARITH.DIVZERO Division By Zero \endwclink warning if this -# preference is set to "ADVERSARIAL" or "IGNORE". -# \code -# volatile int i; -# i = 0; -# 10 / i; -# \endcode -# -# The following test case will produce an \wclink LANG.STRUCT.UC -# Unreachable Data Flow\endwclink warning if this preference is set -# to "IGNORE". -# \code -# int j; -# volatile int timer = 0; -# while( timer != 1000 ) -# ; -# j = 42; -# \endcode +# - UNKNOWABLE : any attempt to read through a volatile type will +# result in an unknown value that is not considered adversarial. +# - ADVERSARIAL : any attempt to read through a volatile type will +# result in an adversarial value. +# - IGNORE : CodeSonar ignores the volatile keyword. +# +# Notes +# The following test case will produce a Null Pointer Dereference +# warning if this preference is set to UNKNOWABLE or ADVERSARIAL. +# int *p = 0; +# volatile int i; +# i = 5; +# if( i != 5 ) +# *p; +# +# The following test case will produce a Division By Zero warning +# if this preference is set to ADVERSARIAL. +# volatile int i; +# i = 5; +# 10 / i; +# +# The following test case will produce a Division By Zero warning +# if this preference is set to ADVERSARIAL or IGNORE. +# volatile int i; +# i = 0; +# 10 / i; +# +# The following test case will produce an Unreachable Code: 5 +# warning classes warning if this preference is set to IGNORE. +# int j; +# volatile int timer = 0; +# while( timer != 1000 ) +# ; +# j = 42; # VOLATILE_TREATMENT = UNKNOWABLE # Parameter FLOAT_IS_ADVERSARIAL # # Purpose -# Specifies whether all floating point values should be considered -# adversarial. +# Specifies whether all floating point values should be considered +# adversarial. +# +# Tags +# - LANGUAGE_TREATMENT: Treatment of Language Constructs # # Type # {Yes, No} # # Behavior -# If set to "Yes", any attempt to convert a floating point to an -# integer will result in an adversarial value. +# - Yes : any attempt to convert a floating point to an integer +# will result in an adversarial value. +# - No : CodeSonar treats floating point values as unknown but not +# adversarial. # -# If set to "No", CodeSonar treats floating point values as unknown -# but not adversarial. -# -# Notes +# Notes # -# The following test case will produce two \wclink LANG.MEM.BO Buffer -# Overrun\endwclink warnings if this preference is set to "Yes". -# \code -# char A[10]; -# double d = 11.0; -# A[d] = 0; -# d = 5.0; -# A[d] = 0; -# \endcode +# The following test case will produce two Buffer Overrun warnings +# if this preference is set to "Yes". +# char A[10]; +# double d = 11.0; +# A[d] = 0; +# d = 5.0; +# A[d] = 0; # FLOAT_IS_ADVERSARIAL = No +# Parameter INFER_CONST +# +# Purpose +# Specifies whether to treat globals and statics as const if they +# are initialized (explicitly or implicitly) but never assigned to. +# +# Tags +# - LANGUAGE_TREATMENT: Treatment of Language Constructs +# +# Type +# {Yes, No} +# +# Behavior +# - Yes : assume these variables never change +# - No : assume these variables might change +# +# Notes +# +# In the following code example, bound is initialized to 100 and +# then never assigned to. +# - If the example is analyzed with INFER_CONST=Yes, CodeSonar will +# assume that the value of bound is always 100, and so will +# determine that the array access buf[i] will never overflow +# because it is adequately guarded by the test on the previous +# line. +# - If this example is analyzed with INFER_CONST=No, CodeSonar's +# analysis will allow for the possibility that the value of bound +# could be changed by separate code, and so issue a Buffer +# Overrun warning. +# int bound = 100; +# void foo(void) { +# char buf[100]; +# int i = getchar(); +# if( i >= bound || i < 0 ) return; +# buf[i] = 'c'; +# } +# +# The following test case will produce a Null Pointer Dereference +# warning if it is analyzed with INFER_CONST=Yes. +# int *ip; +# void foo(void) { +# *ip = 7; +# } +# This is because ip is implicitly zero-initialized, and no other +# value is ever assigned to ip. Therefore, CodeSonar assumes that +# ip must always be zero. To avoid the zero-initialization, you can +# change the declaration to +# extern int *ip; +# +# In some cases, analyzing code with INFER_CONST=Yes can lead to +# unexpected false positives and false negatives. +# - If you are analyzing only pieces of a larger code base, you may +# experience positives and false negatives arising from variables +# that are modified elsewhere in the program but not in the +# analyzed portion (because CodeSonar will assume that these +# variables are never modified). +# - Similarly, libraries and synthetic test cases often involve +# variables whose values do not change in the library/test +# itself, but may be changed by external code. +# +# In these cases, analyzing with INFER_CONST=No may provide better +# results. + +INFER_CONST = Yes + + # Parameter NULL_SENTINEL_CHAR_SIZE # # Purpose # Specifies the maximum sized integer that should be considered a # character type for the purpose of tracking the null-terminator -# position. +# position. # # Type # integer # # Notes -# Setting this to 2 may prove useful for projects using -# wide characters. However, some approximations that occur as a -# consequence of using this can backfire when a single memory region -# contains multiple zeroes. It is not recommended that users alter -# this unless advised to do so by GrammaTech. +# Setting this to 2 may prove useful for projects using wide +# characters. However, some approximations that occur as a +# consequence of using this can backfire when a single memory +# region contains multiple zeroes. It is not recommended that users +# alter this unless advised to do so by GrammaTech. # NULL_SENTINEL_CHAR_SIZE = 1 # Parameter WARN_POINTER_AT_END # # Purpose -# Specifies whether \wclink LANG.STRUCT.PPE Pointer Past End of -# Object \endwclink warnings should be issued for pointers that point -# to exactly the end of an object. +# Specifies whether Pointer Past End of Object warnings should be +# issued for pointers that point to exactly the end of an object. +# +# Tags +# - WC_LANG.STRUCT.PPE: Used by Pointer Past End of Object +# - WARNING_TUNING: Fine Tuning for Warnings # # Type # {Yes, No} # # Behavior -# If set to "Yes", Pointer Past End of Object warnings will be issued -# in cases like the following. -# \code -# int A[10]; -# int *p = &A[10]; -# \endcode +# If set to "Yes", Pointer Past End of Object warnings will be +# issued in cases like the following. +# int A[10]; +# int *p = &A[10]; # # Notes # This feature is turned off by default because many codebases may -# have cursor pointers that reach the end of an object but are never -# dereferenced, as in the following example. -# \code -# int A[10]; -# int *p; -# for( p = A; p < &A[10]; p++ ); -# \endcode +# have cursor pointers that reach the end of an object but are +# never dereferenced, as in the following example. +# int A[10]; +# int *p; +# for( p = A; p < &A[10]; p++ ); # WARN_POINTER_AT_END = No @@ -4277,15 +5084,19 @@ # Specifies whether the tracking of variable initialization in # loops is tuned to potentially report more Uninitialized Variable # warnings. # +# Tags +# - WC_LANG.MEM.UVAR: Used by Uninitialized Variable +# - WARNING_TUNING: Fine Tuning for Warnings +# # Type # {Yes, No} # # Behavior -# If set to "Yes", Uninitialized Variable warnings will be issued for -# variables that are initialized on some but not all paths through -# the loop. +# If set to "Yes", Uninitialized Variable warnings will be issued +# for variables that are initialized on some but not all paths +# through the loop. # # Notes # This feature is turned off by default because it is a frequent # source of false positive results when complex invariants in the @@ -4296,17 +5107,21 @@ # Parameter METRIC_FILTER # # Purpose -# Allows \link ../Metrics/Metrics.html metrics \endlink to be turned +# Allows metrics [doc/html/Metrics/Metrics.html] to be turned # on/off, either for an entire metric class or for specific files, # procedures, or compilation units. # +# Tags +# - METRIC: metric-related +# - ANALYSIS_FILTER: Analysis-Side Filtering +# # Type # Zero or more patterns, each consisting of an followed by -# one or more s. +# one or more s. # -# is one of: +# is one of: # - discard # - allow # # is one of: @@ -4322,42 +5137,36 @@ # - = (exact match) # # Behavior # Depends on the : -# - \tt discard : metrics matching the rules will be discarded instead -# of being submitted to the hub, and whenever possible will not be computed. -# - \tt allow : metrics matching the rules will be submitted to the +# - discard : metrics matching the rules will be discarded instead +# of being submitted to the hub, and whenever possible will not +# be computed. +# - allow : metrics matching the rules will be submitted to the # hub, even if they matched a previous "discard" # # Notes -# If there are two or more s in a pattern, the pattern -# will be applied to metrics that match ALL of the rules. +# If there are two or more s in a pattern, the pattern +# will be applied to metrics that match ALL of the rules. # -# \tt procedure rules match against the \link -# ../API/CAPI/cs__pdg_8h.html#func_cs_pdg_friendly_name -# cs_pdg_friendly_name()\endlink of a procedure; \tt procedure_typed -# rules match against the \link -# ../API/CAPI/cs__pdg_8h.html#func_cs_pdg_procedure_name -# cs_pdg_procedure_name()\endlink. -# -# If you want to compute any of the Halstead metrics (n1, N1, n2, N2, -# D, I, T, E, N, L, V), set -# \code +# procedure rules match against the cs_pdg_friendly_name() +# [doc/html/API/CAPI/cs__pdg_8h.html#func_cs_pdg_friendly_name]; +# procedure_typed rules match against the cs_pdg_procedure_name() +# [doc/html/API/CAPI/cs__pdg_8h.html#func_cs_pdg_procedure_name]. +# +# If you want to compute any of the Halstead metrics (n1, N1, n2, +# N2, D, I, T, E, N, L, V), set # BUILD_OPTIONS += -retain-unnormalized-c-ast yes -# \endcode # -# Metrics of an individual granularity can be allowed/discarded if the string -# pattern is of the form "name[granularity]". For example, to discard the -# "Total Lines" (TL) metric only for file granularity (not the analysis or -# procedure granularity metrics of the same name), the following rule will -# work: -# \code +# Metrics of an individual granularity can be allowed/discarded if +# the string pattern is of the form "name[granularity]". For +# example, to discard the "Total Lines" (TL) metric only for file +# granularity (not the analysis or procedure granularity metrics of +# the same name), the following rule will work: # METRIC_FILTER += discard metric="TL[FILE]" -# \endcode # -# The following metrics are enabled by default. To discard -# a particular metric class, use the corresponding "discard" rule. -# \code +# The following metrics are enabled by default. To discard a +# particular metric class, use the corresponding "discard" rule. # METRIC_FILTER += discard metric="LCodeOnly" # METRIC_FILTER += discard metric="LCode" # METRIC_FILTER += discard metric="LMCC" # METRIC_FILTER += discard metric="LComOnly" @@ -4367,14 +5176,12 @@ # METRIC_FILTER += discard metric="vG" # METRIC_FILTER += discard metric="mvG" # METRIC_FILTER += discard metric="Modules" # METRIC_FILTER += discard metric="TopLF" -# METRIC_FILTER += discard metric="InclF" -# \endcode +# METRIC_FILTER += discard metric="InclF" # -# The following metrics are disabled by default. To enable -# a particular metric class, use the corresponding "allow" rule. -# \code +# The following metrics are disabled by default. To enable a +# particular metric class, use the corresponding "allow" rule. # METRIC_FILTER += allow metric="n1" # METRIC_FILTER += allow metric="N1" # METRIC_FILTER += allow metric="n2" # METRIC_FILTER += allow metric="N2" @@ -4386,111 +5193,107 @@ # METRIC_FILTER += allow metric="L" # METRIC_FILTER += allow metric="V" # METRIC_FILTER += allow metric="evG" # METRIC_FILTER += allow metric="ivG" -# METRIC_FILTER += allow metric="S1" -# \endcode +# METRIC_FILTER += allow metric="S1" # Parameter METRIC_DERIVED_DEF # # Purpose -# Creates new derived \link ../Metrics/Metrics.html metrics \endlink, -# which are computed by mathematically manipulating values of already -# existing metrics. -# -# Type -# A string of the form -# , , , +# Creates new derived metrics [doc/html/Metrics/Metrics.html], +# which are computed by mathematically manipulating values of +# already existing metrics. +# +# Tags +# - METRIC: metric-related +# +# Type +# A string of the form , , +# , +# +# where: is the quoted short name to give the new +# metric, and must: +# - start with characters matching: [a-zA-Z] +# - only contain characters matching: [a-zA-Z][0-9] _- +# - have string length <= 15 characters +# - be unique (in combination with a granularity), case +# insensitively +# - not match any function name in the expression grammar +# +# is the quoted description to give the new +# metric, and must: +# - only contain characters matching: [a-zA-Z][0-9] _- +# - have string length <= 35 characters # -# where: -# is the quoted short name to give the new metric, and must: -# - start with characters matching: [a-zA-Z] -# - only contain characters matching: [a-zA-Z][0-9] _- -# - have string length <= 15 characters -# - be unique (in combination with a granularity), case insensitively -# - not match any \tt function name in the expression grammar -# -# is the quoted description to give the new metric, -# and must: -# - only contain characters matching: [a-zA-Z][0-9] _- -# - have string length <= 35 characters -# -# is the granularity of the new metric, and is one of +# is the granularity of the new metric, and is one of # {ANALYSIS, COMPUNIT, FILE, PROCEDURE} -# -# is an expression containing mathematical operators, functions, -# constant (floating point) values, and references to other metrics. +# +# is an expression containing mathematical operators, +# functions, constant (floating point) values, and references to +# other metrics. # # Expression grammar: -# \code -# S -> expr -# expr -> expr + expr | expr - expr | expr * expr | expr / expr | -# const | metric | function(expr, ...) -# function -> cos | sin | tan | acos | asin | atan | atan2 | cosh | sinh | -# tanh | exp | frexp | ldexp | log | log10 | pow | sqrt | -# ceil | fabs | floor | fmod | sum | prod | avg | min | max -# metric -> "[a-zA-Z0-9]+\[granularity\]" (must match existing metric, case-insensitive) -# granularity -> PROJECT | COMPUNIT | FILE | PROCEDURE -# \endcode -# -# - All \tt functions return a single floating point value. -# - All math operations are floating point. -# - Functions \tt sum, \tt prod, \tt avg, \tt min, and \tt max are -# summarizing functions they only take metrics as arguments, and -# only work when the derived metric has granularity greater than -# the referenced metric. See table below (\tt sum is used as example). -# -# \code -# +---------------------+-------------------+-----------------------------+ -# | derived metric gran | expression | description | -# +---------------------+-------------------+-----------------------------+ -# | FILE | sum(PROCEDURE) | Sums over all procedures in | -# | | | the file. | -# | | | | -# | COMPUNIT | sum(PROCEDURE) | Sums over all procedures in | -# | | | the compilation unit. | -# | | | | -# | PROJECT | sum(PROCEDURE) | Sums over all procedures in | -# | | | the project. | -# | | | | -# | COMPUNIT | sum(FILE) | Sums over all files in the | -# | | | compilation unit. | -# | ... etc | -# +-----------------------------------------------------------------------+ -# \endcode -# -# Behavior -# If a properly formed derived metric is specified, that metric will -# be computed and displayed for the next analysis unless it is -# discarded via \param METRIC_FILTER. -# -# If there is an error in the specification of \tt -# METRIC_DERIVED_DEF, CodeSonar will issue an \link -# ../GUI/GUI_Alerts.html alert\endlink that specifies the nature of -# the problem. +# S -> expr +# expr -> expr + expr | expr - expr | expr * expr | expr / expr | +# const | metric | function(expr, ...) +# function -> cos | sin | tan | acos | asin | atan | atan2 | cosh | sinh | +# tanh | exp | frexp | ldexp | log | log10 | pow | sqrt | +# ceil | fabs | floor | fmod | sum | prod | avg | min | max +# metric -> "[a-zA-Z0-9]+\[granularity\]" (must match existing metric, case-insensitive) +# granularity -> PROJECT | COMPUNIT | FILE | PROCEDURE +# +# - All functions return a single floating point value. +# - All math operations are floating point. +# - Functions sum, prod, avg, min, and max are summarizing +# functions they only take metrics as arguments, and only work +# when the derived metric has granularity greater than the +# referenced metric. See table below (sum is used as example). +# +# +---------------------+-------------------+-----------------------------+ +# | derived metric gran | expression | description | +# +---------------------+-------------------+-----------------------------+ +# | FILE | sum(PROCEDURE) | Sums over all procedures in | +# | | | the file. | +# | | | | +# | COMPUNIT | sum(PROCEDURE) | Sums over all procedures in | +# | | | the compilation unit. | +# | | | | +# | PROJECT | sum(PROCEDURE) | Sums over all procedures in | +# | | | the project. | +# | | | | +# | COMPUNIT | sum(FILE) | Sums over all files in the | +# | | | compilation unit. | +# | ... etc | +# +-----------------------------------------------------------------------+ +# +# Behavior +# If a properly formed derived metric is specified, that metric +# will be computed and displayed for the next analysis unless it is +# discarded via METRIC_FILTER. +# +# If there is an error in the specification of METRIC_DERIVED_DEF, +# CodeSonar will issue an alert [doc/html/GUI/GUI_Alerts.html] that +# specifies the nature of the problem. # # Notes # If a derived metric which is enabled refers to a metric which is # disabled, the derived metric will still be calculated. This will # cause the disabled metric to be calculated as well (though not -# reported). In this scenario, the performance gains from having the -# unreported metric disabled are lost. +# reported). In this scenario, the performance gains from having +# the unreported metric disabled are lost. # -# All \tt METRIC_DERIVED_DEF definitions are processed before any -# \param METRIC_FILTER settings. A derived metric can therefore be -# disabled by a \tt METRIC_FILTER rule that appears before the metric +# All METRIC_DERIVED_DEF definitions are processed before any +# METRIC_FILTER settings. A derived metric can therefore be +# disabled by a METRIC_FILTER rule that appears before the metric # definition in the configuration file. # -# If you want to compute any of the Halstead metrics (n1, N1, n2, N2, -# D, I, T, E, N, L, V), set -# \code +# If you want to compute any of the Halstead metrics (n1, N1, n2, +# N2, D, I, T, E, N, L, V), set # BUILD_OPTIONS += -retain-unnormalized-c-ast yes -# \endcode # -# The following are some examples defining file-granularity versions -# of the Halstead and McCabe metrics. -# \code +# The following are some examples defining file-granularity +# versions of the Halstead and McCabe metrics. # METRIC_DERIVED_DEF += "vG", "Cyclomatic Complexity", FILE, sum("vG[PROCEDURE]") # METRIC_DERIVED_DEF += "ivG", "Design Complexity", FILE, sum("ivG[PROCEDURE]") # METRIC_DERIVED_DEF += "evG", "Essential Complexity", FILE, sum("evG[PROCEDURE]") # METRIC_DERIVED_DEF += "n1", "Distinct Operators", FILE, sum("n1[PROCEDURE]") @@ -4503,57 +5306,57 @@ # METRIC_DERIVED_DEF += "E", "Halstead Programming Effort", FILE, sum("E[PROCEDURE]") # METRIC_DERIVED_DEF += "N", "Halstead Program Length", FILE, sum("N[PROCEDURE]") # METRIC_DERIVED_DEF += "L", "Halstead Program Level", FILE, sum("L[PROCEDURE]") # METRIC_DERIVED_DEF += "V", "Halstead Program Volume", FILE, sum("V[PROCEDURE]") -# \endcode # -# The following are more examples, this time slight variations on the basic -# McCabe metrics. -# \code +# The following are more examples, this time slight variations on +# the basic McCabe metrics. # METRIC_DERIVED_DEF += "vG-code", "Cyclomatic Density", PROCEDURE, "vG[PROCEDURE]" / "LCode[PROCEDURE]" # METRIC_DERIVED_DEF += "ivG-vG", "Design Density", PROCEDURE, "ivG[PROCEDURE]" / "vG[PROCEDURE]" # METRIC_DERIVED_DEF += "evG-vG", "Essential Density", PROCEDURE, ("evG[PROCEDURE]" - 1) / "vG[PROCEDURE]" -# \endcode # + # Parameter METHOD_INVOCATION_DEREFERENCE_BEHAVIOR # -# Purpose +# Purpose # Specifies whether C++ method invocations should always be treated -# as if they dereference \tt this at the method invocation site. +# as if they dereference this at the method invocation site. +# +# Tags +# - LANGUAGE_TREATMENT: Treatment of Language Constructs # -# Type +# Type # {All, Undefined, None} # -# Behavior -# The C++ method invocation p->m() will not actually dereference the -# pointer p unless the body of m accesses a data member of p. +# Behavior +# The C++ method invocation p->m() will not actually dereference +# the pointer p unless the body of m accesses a data member of p. # However, sometimes it is useful to treat method invocations as if # they always dereference their objects - either because the source -# code implementing m() is unavailable or to reduce the complexity of -# warnings. -# -# - "All": All method invocations are treated as if they dereference -# their \tt this pointer. Additionally, \tt this is -# assumed to never have a value below \param -# NULL_POINTER_THRESHOLD. -# - "Undefined": All invocations of undefined methods (methods for which no -# source code is available) are treated as if they -# dereference their \tt this pointers, which are -# assumed to never have a value below \param -# NULL_POINTER_THRESHOLD. No assumptions are made -# about defined methods. -# - "None": No assumptions are made about any methods. In practice, -# this means that invocations of undefined methods are never -# considered to dereference \tt this. +# code implementing m() is unavailable or to reduce the complexity +# of warnings. # -# Notes -# With the "All" setting, method invocations on unconditionally null -# pointers will result in unreachable code after the method returns. +# - All : All method invocations are treated as if they dereference +# their this pointer. Additionally, this is assumed to never have +# a value below NULL_POINTER_THRESHOLD. +# - Undefined : All invocations of undefined methods (methods for +# which no source code is available) are treated as if they +# dereference their this pointers, which are assumed to never +# have a value below NULL_POINTER_THRESHOLD. No assumptions are +# made about defined methods. +# - None : No assumptions are made about any methods. In practice, +# this means that invocations of undefined methods are never +# considered to dereference this. +# +# Notes +# With the All setting, method invocations on unconditionally null +# pointers will result in unreachable code after the method +# returns. # METHOD_INVOCATION_DEREFERENCE_BEHAVIOR = None -# METHOD_INVOCATION_DEREFERENCE_BEHAVIOR = Undefined -# METHOD_INVOCATION_DEREFERENCE_BEHAVIOR = All +# METHOD_INVOCATION_DEREFERENCE_BEHAVIOR = Undefined +# METHOD_INVOCATION_DEREFERENCE_BEHAVIOR = All # Parameter METRIC_WARNING_CONDITION # Parameter METRIC_WARNING_CLASS_NAME @@ -4563,145 +5366,156 @@ # Purpose # Specifies a warning condition for a metric; if that condition is # met, a warning is reported. # -# Type -# - \tt METRIC_WARNING_CONDITION: metric number -# where the metric is specified by name[granularity], and is -# one of >, <, >=, <= -# - \tt METRIC_WARNING_CLASS_NAME: string -# - \tt METRIC_WARNING_CATEGORIES: string -# - \tt METRIC_WARNING_RANK: number -# -# Behavior -# These parameters are used together to specify conditions on metric -# values, and warnings to issue when values meet those conditions. -# -# - \tt METRIC_WARNING_CONDITION specifies a metric and a condition on -# that metric. A warning will be issued if the metric's value meets the -# condition. The metric must be enabled with a \param METRIC_FILTER -# \tt allow rule. Both built-in metrics and derived metrics can be used. -# - \tt METRIC_WARNING_CLASS_NAME is the warning class name. -# - \tt METRIC_WARNING_CATEGORIES is the set of categories for the -# warning, as a semicolon-separated list. This defaults to +# Tags +# - METRIC: metric-related +# - WC_METRIC.CUSTOM: Used by Custom Metric-Based Warning Classes +# +# Type +# - METRIC_WARNING_CONDITION: metric number where the metric +# is specified by name[granularity], and is one of >, <, >=, +# <= +# - METRIC_WARNING_CLASS_NAME: string +# - METRIC_WARNING_CATEGORIES: string +# - METRIC_WARNING_RANK: number +# +# Behavior +# These parameters are used together to specify conditions on +# metric values, and warnings to issue when values meet those +# conditions. +# +# - METRIC_WARNING_CONDITION specifies a metric and a condition on +# that metric. A warning will be issued if the metric's value +# meets the condition. The metric must be enabled with a +# METRIC_FILTER allow rule. Both built-in metrics and derived +# metrics can be used. +# - METRIC_WARNING_CLASS_NAME is the warning class name. +# - METRIC_WARNING_CATEGORIES is the set of categories for the +# warning, as a semicolon-separated list. This defaults to # "METRIC.CUSTOM". -# - \tt METRIC_WARNING_RANK is the rank assigned to the warning, with +# - METRIC_WARNING_RANK is the rank assigned to the warning, with # default 25.0. # -# Notes +# Notes # -# The \tt METRIC_WARNING_CATEGORIES and \tt METRIC_WARNING_RANK -# settings are optional, but both \tt METRIC_WARNING_CONDITION and -# \tt METRIC_WARNING_CLASS_NAME must be fully specified. The \tt -# METRIC_WARNING_CONDITION message must come first, and the \tt +# The METRIC_WARNING_CATEGORIES and METRIC_WARNING_RANK settings +# are optional, but both METRIC_WARNING_CONDITION and +# METRIC_WARNING_CLASS_NAME must be fully specified. The +# METRIC_WARNING_CONDITION message must come first, and the # METRIC_WARNING_CLASS_NAME second. -# -# If two or more sets of \tt METRIC_WARNING_* rules have the same \tt +# +# If two or more sets of METRIC_WARNING_* rules have the same # METRIC_WARNING_CLASS_NAME value, the same warning class will be -# used to cover all cases. Therefore, sets of rules with the same \tt -# METRIC_WARNING_CLASS_NAME should also have the same \tt -# METRIC_WARNING_CATEGORIES and \tt METRIC_WARNING_RANK values (that -# is, they should only differ in the \tt METRIC_WARNING_CONDITION +# used to cover all cases. Therefore, sets of rules with the same +# METRIC_WARNING_CLASS_NAME should also have the same +# METRIC_WARNING_CATEGORIES and METRIC_WARNING_RANK values (that +# is, they should only differ in the METRIC_WARNING_CONDITION # setting). # -# Similarly, if a set of \tt METRIC_WARNING_* rules has a \tt -# METRIC_WARNING_CLASS_NAME that is the same as the name of a standard -# CodeSonar warning class, the category and rank settings of the -# standard class will apply and any \tt METRIC_WARNING_CATEGORIES or -# \tt METRIC_WARNING_RANK specified in the set will not be used. +# Similarly, if a set of METRIC_WARNING_* rules has a +# METRIC_WARNING_CLASS_NAME that is the same as the name of a +# standard CodeSonar warning class, the category and rank settings +# of the standard class will apply and any +# METRIC_WARNING_CATEGORIES or METRIC_WARNING_RANK specified in the +# set will not be used. # # Examples: # # Instruct CodeSonar to issue a warning of class "High Cyclomatic -# Complexity" for any function with a cyclomatic complexity of 20 or -# more. -# \code -# METRIC_WARNING_CONDITION = vG[PROCEDURE] >= 20 -# METRIC_WARNING_CLASS_NAME = High Cyclomatic Complexity -# METRIC_WARNING_CATEGORIES = METRIC.VG -# METRIC_WARNING_RANK = 5.0 -# \endcode +# Complexity" for any function with a cyclomatic complexity of 20 +# or more. +# METRIC_WARNING_CONDITION = vG[PROCEDURE] >= 20 +# METRIC_WARNING_CLASS_NAME = High Cyclomatic Complexity +# METRIC_WARNING_CATEGORIES = METRIC.VG +# METRIC_WARNING_RANK = 5.0 # # Instruct CodeSonar to issue a warning of class "Large procedure" # for any function containing more than 100 lines with code: -# \code -# METRIC_WARNING_CONDITION = LCode[PROCEDURE] > 100 -# METRIC_WARNING_CLASS_NAME = Large procedure -# METRIC_WARNING_CATEGORIES = METRIC.LCODE -# METRIC_WARNING_RANK = 1.0 -# \endcode -# +# METRIC_WARNING_CONDITION = LCode[PROCEDURE] > 100 +# METRIC_WARNING_CLASS_NAME = Large procedure +# METRIC_WARNING_CATEGORIES = METRIC.LCODE +# METRIC_WARNING_RANK = 1.0 +# # Instruct CodeSonar to issue a warning of class "Too few comments" # for any insufficiently commented function (defined here as a # function containing fewer than 5 lines with comments). -# \code -# METRIC_WARNING_CONDITION = LCom[PROCEDURE] < 5 -# METRIC_WARNING_CLASS_NAME = Too few comments -# METRIC_WARNING_CATEGORIES = METRIC.LCOM -# METRIC_WARNING_RANK = 2.0 -# \endcode +# METRIC_WARNING_CONDITION = LCom[PROCEDURE] < 5 +# METRIC_WARNING_CLASS_NAME = Too few comments +# METRIC_WARNING_CATEGORIES = METRIC.LCOM +# METRIC_WARNING_RANK = 2.0 # # Note that the categories in these examples are arbitrary text. # # Parameter SCHEME_WEB_CONSOLE # # Purpose -# Specifies whether the \link ../GUI/GUI_Analysis.html#dry_runs -# Analysis: Dry Runs\endlink Scheme Console will be made available -# with the analysis. +# Specifies whether the Scheme Console will be made available with +# the analysis. +# +# Tags +# - HUB_BEHAVIOR: Hub and Web GUI # # Type # {Yes, No} # # Behavior -# If set to "Yes", the Scheme Console will be available and -# functional for this analysis. Warning: this poses a grave security -# risk. Anyone with access to the hub can execute arbitrary code in -# the analysis process. +# - Yes : the Scheme Console will be available and functional for +# this analysis. Warning: this poses a grave security risk. +# Anyone with access to the hub can execute arbitrary code in the +# analysis process. +# - No : the Scheme Console will not be available for this +# analysis. # # Notes # This feature can be useful for experimenting with the Scheme API. -# It can also be useful for debugging analysis plug-ins. +# It can also be useful for debugging analysis plug-ins. # -# Code will have full access to the program representations generated -# by CodeSonar and will run with the credentials of whoever started -# the analysis process. There is no sandboxing of any kind. +# Code will have full access to the program representations +# generated by CodeSonar and will run with the credentials of +# whoever started the analysis process. There is no sandboxing of +# any kind. SCHEME_WEB_CONSOLE = No # Parameter COLLAPSE_PROCEDURES # # Purpose -# Specifies whether multiple instances of the same procedure should be -# collapsed into a single instance for viewing purposes. This primarily -# affects templated functions which are instantiated with multiple template -# arguments, and also static inline functions. +# Specifies whether multiple instances of the same procedure should +# be collapsed into a single instance for viewing purposes. This +# primarily affects templated functions which are instantiated with +# multiple template arguments, and also static inline functions. +# +# Tags +# - INCREMENTAL_NOCHANGE: Do Not Change Between Incremental +# Analyses +# - HUB_BEHAVIOR: Hub and Web GUI # # Type # {Yes, No} # # Behavior -# If set to "Yes", the hub will only display one procedure in cases where -# multiple PDGs are instances of the same procedure. +# If set to "Yes", the hub will only display one procedure in cases +# where multiple PDGs are instances of the same procedure. # # Notes -# The choice of representative procedure instance is -# arbitrary. Multiple procedures defined at the same source file/line -# may also be collapsed. Do not change the setting of this parameter between +# The choice of representative procedure instance is arbitrary. +# Multiple procedures defined at the same source file/line may also +# be collapsed. Do not change the setting of this parameter between # incremental builds. # -# For example, suppose foo(void) has two instances: foo(void) -# and foo(void). -# - With COLLAPSE_PROCEDURES=Yes, foo will have only a single line in -# tables of procedures and procedure-granularity metrics, describing -# one of the two instances. Only this instance will be shown in -# charts. -# - With COLLAPSE_PROCEDURES=No, foo will have two lines in tables of -# procedures and procedures-granularity metrics - one for each -# instance. Both instances will be shown in charts. +# For example, suppose foo(void) has two instances: +# foo(void) and foo(void). +# - With COLLAPSE_PROCEDURES=Yes, foo will have only a single line +# in tables of procedures and procedure-granularity metrics, +# describing one of the two instances. Only this instance will be +# shown in charts. +# - With COLLAPSE_PROCEDURES=No, foo will have two lines in tables +# of procedures and procedures-granularity metrics - one for each +# instance. Both instances will be shown in charts. # # Procedure and line counts are not affected by the setting of this # parameter. Metrics warnings on procedures are also not affected. # @@ -4711,192 +5525,224 @@ # Parameter WARN_MORE_LOOP_LEAKS # # Purpose # Normally, leak warnings on paths that iterate around a loop -# multiple times are suppressed. Setting to "Yes" will disable the +# multiple times are suppressed. Setting to "Yes" will disable the # suppression. # +# Tags +# - WC_ALLOC.LEAK: Used by Leak +# - WARNING_TUNING: Fine Tuning for Warnings +# # Type # {Yes, No} # # Behavior # If set to "Yes", leaks will be reported on paths that iterate -# around loops multiple times. These leaks are often false +# around loops multiple times. These leaks are often false # positives. # # Notes # This is an experimental feature and more work is necessary on -# GrammaTech's part to eliminate false positives in this area. The -# natural language explanation of existing warnings may also degrade -# as a consequence of enabling this setting. +# GrammaTech's part to eliminate false positives in this area. The +# natural language explanation of existing warnings may also +# degrade as a consequence of enabling this setting. # WARN_MORE_LOOP_LEAKS = No + +# Parameter REFINE_LEAKS_THOROUGHLY +# +# Purpose +# Setting to "No" will prevent CodeSonar from dismissing likely +# leak false positives. +# +# Tags +# - WC_ALLOC.LEAK: Used by Leak +# - WARNING_TUNING: Fine Tuning for Warnings +# +# Type +# {Yes, No} +# +# Behavior +# If set to "No", leaks will be reported significantly more +# frequently. Many of the resulting reports will be false +# positives, but some may be true positives. +# +REFINE_LEAKS_THOROUGHLY = Yes + + # Parameter FILE_LISTING_UNDEF_PROCS # # Purpose -# Specifies whether file listings (not warning report listings) should show -# events for calls to undefined functions that occur in the listing. Warning -# report listings will always show events for undefined function calls that -# occur on the warning path. +# For Source Listing pages: specifies whether calls to undefined +# functions should be specially marked. +# +# Tags +# - HUB_BEHAVIOR: Hub and Web GUI +# - ANALYSIS_PROPERTY: Analysis Properties # # Type # {Yes, No} # # Behavior -# If set to "Yes", undefined functions will be marked with events when viewing -# a file's contents from the hub. +# If set to "Yes", undefined functions will be marked with events +# when viewing a file's contents from the hub. # # Notes -# Turning this on could have a negative performance impact on the file listing -# view in the hub. +# Turning this on could have a negative performance impact on the +# file listing view in the hub. +# +# This parameter does not affect Warning Report pages, which will +# always show events for undefined function calls that occur on the +# warning path. # FILE_LISTING_UNDEF_PROCS = No # Parameter XML_DUMP_MODE # # Purpose -# Specifies whether analysis daemon should write the content of a warning -# to an XML file when it sends the warning to the hub. +# Specifies whether analysis daemon should write the content of a +# warning to an XML file when it sends the warning to the hub. +# +# Tags +# - ANALYSIS_PROPERTY: Analysis Properties # # Type # {FULL, NO_LISTING, No} # # Behavior -# - \tt FULL: the full warning report will be written out for each +# - FULL: the full warning report will be written out for each # warning. -# - \tt NO_LISTING: the warning report for each warning will be -# written out with the path listing omitted. -# - \tt No: no XML files are generated. +# - NO_LISTING: the warning report for each warning will be written +# out with the path listing omitted. +# - No: no XML files are generated. # # Notes -# Set this parameter to \tt FULL or \tt NO_LISTING if you want the analysis -# to generate XML files for all warnings sent to the hub. There will -# be one XML file per warning. +# Set this parameter to FULL or NO_LISTING if you want the analysis +# to generate XML files for all warnings sent to the hub. There +# will be one XML file per warning. # -# - XML files for warnings issued in source file \tt / -# will be output at \tt +# - XML files for warnings issued in source file / +# will be output at # .xml/analysis_//. -# - XML files for warnings not associated with a source file will be -# output at \tt +# - XML files for warnings not associated with a source file will +# be output at # .xml/analysis_/NONAME_0000000>/. # XML_DUMP_MODE = No # Parameter NON_TERMINATING_LOOP_MARK # # Purpose -# Specifies loops for which \wclink LANG.STRUCT.ULOOP Potential -# Unbounded Loop \endwclink should not issue warnings. +# Specifies loops for which Potential Unbounded Loop warnings +# should not be issued. +# +# Tags +# - WC_LANG.STRUCT.ULOOP: Used by Potential Unbounded Loop # # Type -# \link -# ../../../../third-party/boost/libs/regex/doc/html/boost_regex/syntax.html -# Boost regular expression\endlink +# Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] # # Behavior -# If the line the loop condition is at matches this regular expression, -# a \wclink LANG.STRUCT.ULOOP Potential Unbounded Loop \endwclink -# warning will not be issued. +# If the line the loop condition is at matches this regular +# expression, a Potential Unbounded Loop warning will not be +# issued. # -# Notes +# Notes # For example, -# \code -# NON_TERMINATING_LOOP_MARK += /[*] @non-terminating@ [*]/ -# \endcode -# specifies that \wclink LANG.STRUCT.ULOOP Potential Unbounded Loop -# \endwclink warnings will not be triggered by any loop whose condition -# line contains the comment /* @non-terminating@ */. -# -# Don't issue warnings for loops whose condition looks like \tt for(;;) : -# \code -# NON_TERMINATING_LOOP_MARK += for *[(] *; *; *[)] -# \endcode -# -# Don't issue warnings for loops whose condition looks like \tt while(1) : -# \code -# NON_TERMINATING_LOOP_MARK += while *[(] *1 *[)] -# \endcode -# -# Note that the \wclink LANG.STRUCT.ULOOP Potential Unbounded Loop -# \endwclink check is disabled by default: use a \param -# WARNING_FILTER rule to enable it. +# NON_TERMINATING_LOOP_MARK += /[*] @non-terminating@ [*]/ +# specifies that Potential Unbounded Loop warnings will not be +# triggered by any loop whose condition line contains the comment +# /* @non-terminating@ */. +# +# Don't issue warnings for loops whose condition looks like for(;;) +# : +# NON_TERMINATING_LOOP_MARK += for *[(] *; *; *[)] +# +# Don't issue warnings for loops whose condition looks like +# while(1) : +# NON_TERMINATING_LOOP_MARK += while *[(] *1 *[)] +# +# Note that the Potential Unbounded Loop check is disabled by +# default: use a WARNING_FILTER rule to enable it. NON_TERMINATING_LOOP_MARK += for *[(] *; *; *[)] NON_TERMINATING_LOOP_MARK += while *[(] *1 *[)] # Parameter PROGRAM_ENTRY_POINTS # # Purpose -# Specifies additional functions that should be considered as program -# entry points. Currently only the \wclink ALLOC.POSTINIT -# Dynamic Allocation After Initialization \endwclink check uses this -# parameter. +# Specifies additional functions that should be considered as +# program entry points. Currently only the Dynamic Allocation After +# Initialization check uses this parameter. +# +# Tags +# - WARNING_SPECIAL_FUNCTIONS: Designates Specially-Treated +# Functions +# - WC_ALLOC.POSTINIT: Used by Dynamic Allocation After +# Initialization # # Type -# \link -# ../../../../third-party/boost/libs/regex/doc/html/boost_regex/syntax.html -# Boost regular expression\endlink +# Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] # # Behavior -# The \wclink ALLOC.POSTINIT Dynamic Allocation After -# Initialization \endwclink check will trigger a warning if there is -# a call chain from a program entry point to an allocator call that -# does not go through a function specified with \param +# The Dynamic Allocation After Initialization check will trigger a +# warning if there is a call chain from a program entry point to an +# allocator call that does not go through a function specified with # DYN_INIT_FUNCTIONS. # # Notes # For example, -# \code -# PROGRAM_ENTRY_POINTS += ^init$ -# \endcode +# PROGRAM_ENTRY_POINTS += ^init$ # specifies that the check should start at function(s) named init. # -# Note that the \wclink ALLOC.POSTINIT Dynamic Allocation After -# Initialization\endwclink check is disabled by default: use a \param -# WARNING_FILTER rule to enable it. +# Note that the Dynamic Allocation After Initialization check is +# disabled by default: use a WARNING_FILTER rule to enable it. + +## #System_Initialization is the true 'main' procedure in a CodeSonar +## project. -# #System_Initialization is the true 'main' procedure in a CodeSonar -# project. PROGRAM_ENTRY_POINTS += ^#System_Initialization$ PROGRAM_ENTRY_POINTS += ^init$ # Parameter ALLOCATOR_FUNCTIONS # # Purpose -# Specifies allocator functions. -# Currently only used by -# \wclink ALLOC.POSTINIT Dynamic Allocation After Initialization -# \endwclink check. -# -# Type -# \link -# ../../../../third-party/boost/libs/regex/doc/html/boost_regex/syntax.html -# Boost regular expression\endlink -# -# Behavior -# For \wclink ALLOC.POSTINIT Dynamic Allocation After Initialization -# \endwclink check: calls to functions matching this regular -# expression are reported unless: -# - they are directly or transitively called by a function specified with -# \param DYN_INIT_FUNCTIONS, or -# - they are not reachable from a program entry point (see \param -# PROGRAM_ENTRY_POINTS). +# Specifies allocator functions. Currently only used by the Dynamic +# Allocation After Initialization check. +# +# Tags +# - WARNING_SPECIAL_FUNCTIONS: Designates Specially-Treated +# Functions +# - WC_ALLOC.POSTINIT: Used by Dynamic Allocation After +# Initialization +# +# Type +# Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] +# +# Behavior +# For the Dynamic Allocation After Initialization check, calls to +# functions matching this regular expression are reported unless: +# - they are directly or transitively called by a function +# specified with DYN_INIT_FUNCTIONS, or +# - they are not reachable from a program entry point (see +# PROGRAM_ENTRY_POINTS). # # Notes # For example, -# \code -# ALLOCATOR_FUNCTIONS += ^mmap$ -# \endcode -# specifies that \tt mmap() should be considered an allocator -# -# Note that the \wclink ALLOC.POSTINIT Dynamic Allocation After -# Initialization\endwclink check is disabled by default: use a \param -# WARNING_FILTER rule to enable it. +# ALLOCATOR_FUNCTIONS += ^mmap$ +# specifies that mmap() should be considered an allocator +# +# Note that the Dynamic Allocation After Initialization check is +# disabled by default: use a WARNING_FILTER rule to enable it. ALLOCATOR_FUNCTIONS += ^(csonar_allocate_heap)$ ALLOCATOR_FUNCTIONS += ^(malloc|alloca|realloc)$ ALLOCATOR_FUNCTIONS += ^(sbrk|brk|mmap)$ @@ -4906,66 +5752,68 @@ # Parameter DYN_INIT_FUNCTION # # Purpose # Specifies functions that may directly or transitively call -# allocator functions without triggering a \wclink -# ALLOC.POSTINIT Dynamic Allocation After Initialization -# \endwclink warning. +# allocator functions without triggering a Dynamic Allocation After +# Initialization warning. +# +# Tags +# - WARNING_SPECIAL_FUNCTIONS: Designates Specially-Treated +# Functions +# - WC_ALLOC.POSTINIT: Used by Dynamic Allocation After +# Initialization # # Type -# \link -# ../../../../third-party/boost/libs/regex/doc/html/boost_regex/syntax.html -# Boost regular expression\endlink +# Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] # # Behavior -# No \wclink ALLOC.POSTINIT Dynamic Allocation After -# Initialization \endwclink warnings are issued for allocators (as -# specified by \param ALLOCATOR_FUNCTIONS) called directly or -# transitively by a function whose name matches this regular -# expression. +# No Dynamic Allocation After Initialization warnings are issued +# for allocators (as specified by ALLOCATOR_FUNCTIONS) called +# directly or transitively by a function whose name matches this +# regular expression. # # Notes # For example, -# \code -# DYN_INIT_FUNCTIONS += ^dyn_init$ -# \endcode -# specifies that function(s) \tt dyn_init() can directly or -# transitively call allocator functions without triggering a warning. -# -# Note that the \wclink ALLOC.POSTINIT Dynamic Allocation After -# Initialization\endwclink check is disabled by default: use a \param -# WARNING_FILTER rule to enable it. +# DYN_INIT_FUNCTIONS += ^dyn_init$ +# specifies that function(s) dyn_init() can directly or +# transitively call allocator functions without triggering a +# warning. +# +# Note that the Dynamic Allocation After Initialization check is +# disabled by default: use a WARNING_FILTER rule to enable it. DYN_INIT_FUNCTIONS += ^dyn_init$ # Parameter ASSERT_FAIL_FUNCTIONS # # Purpose -# Specifies functions that will be treated as assertions by the \wclink -# LANG.FUNCS.ASSERTS Not Enough Assertions \endwclink check +# Specifies functions that will be treated as assertions by the Not +# Enough Assertions check +# +# Tags +# - WARNING_SPECIAL_FUNCTIONS: Designates Specially-Treated +# Functions +# - WC_LANG.FUNCS.ASSERTS: Used by Not Enough Assertions # # Type -# \link -# ../../../../third-party/boost/libs/regex/doc/html/boost_regex/syntax.html -# Boost regular expression\endlink +# Boost regular expression [../third- +# party/boost/libs/regex/doc/html/boost_regex/syntax.html] # # Behavior # Calls to functions matching this regular expression are counted # as assertions. # # Notes # For example, -# \code -# ASSERT_FAIL_FUNCTIONS += ^__assert_fail$ -# \endcode -# specifies that calls to \tt __assert_fail() should be considered -# assertions. Some systems implement the \tt assert macro using \tt +# ASSERT_FAIL_FUNCTIONS += ^__assert_fail$ +# specifies that calls to __assert_fail() should be considered +# assertions. Some systems implement the assert macro using # __assert_fail(). # -# Note that the \wclink LANG.FUNCS.ASSERTS Not Enough Assertions -# \endwclink check is disabled by default: use a \param -# WARNING_FILTER rule to enable it. +# Note that the Not Enough Assertions check is disabled by default: +# use a WARNING_FILTER rule to enable it. ASSERT_FAIL_FUNCTIONS += ^__assert_fail$ ASSERT_FAIL_FUNCTIONS += ^__assert$ ASSERT_FAIL_FUNCTIONS += ^_assert$ @@ -4975,22 +5823,29 @@ # Parameter SYSTEM_INCLUDE_PATHS # # Purpose -# Specifies file system paths which contain system include headers. +# Specifies file system paths which contain system include headers. +# +# Tags +# - BUILD_BEHAVIOR: Governs the Build/Analysis # # Type # string # # Behavior -# Any file matching the paths added via SYSTEM_INCLUDE_PATHS are excluded -# from computation of metrics and certain warning classes. Substring match is -# used to match files to the specified system include paths. -# -# NOTE: Any line ending with a "\" is treated as a continuation - meaning that -# the subsequent line will be concatenated with the current line. To avoid -# this situation (e.g. for paths that actually end in "\"), add whitespace -# after the "\" before the newline character. +# Any file matching the paths added via SYSTEM_INCLUDE_PATHS are +# excluded from computation of metrics and certain warning classes. +# Substring match is used to match files to the specified system +# include paths. +# +# NOTE: Any line ending with a "\" is treated as a continuation - +# meaning that the subsequent line will be concatenated with the +# current line. To avoid this situation (e.g. for paths that +# actually end in "\"), add whitespace after the "\" before the +# newline character. +# + SYSTEM_INCLUDE_PATHS += /codesonar/smel/ SYSTEM_INCLUDE_PATHS += /codesonar/libmodels/ SYSTEM_INCLUDE_PATHS += /csurf/csinclude/ @@ -5006,8 +5861,9 @@ SYSTEM_INCLUDE_PATHS += /opt/sfw/lib/ SYSTEM_INCLUDE_PATHS += /cygwin/lib/ SYSTEM_INCLUDE_PATHS += /cygwin/local/lib/ SYSTEM_INCLUDE_PATHS += :\Program Files\Microsoft +SYSTEM_INCLUDE_PATHS += :\Program Files\Windows SYSTEM_INCLUDE_PATHS += :\Program Files\Freescale SYSTEM_INCLUDE_PATHS += :\Program Files\Metrowerks SYSTEM_INCLUDE_PATHS += :\Program Files\Intel SYSTEM_INCLUDE_PATHS += :\Program Files\ARM @@ -5028,8 +5884,9 @@ SYSTEM_INCLUDE_PATHS += \csurf\csinclude\ SYSTEM_INCLUDE_PATHS += \codesonar\smel\ SYSTEM_INCLUDE_PATHS += \codesonar\libmodels\ SYSTEM_INCLUDE_PATHS += :\Program Files (x86)\Microsoft +SYSTEM_INCLUDE_PATHS += :\Program Files (x86)\Windows SYSTEM_INCLUDE_PATHS += :\Program Files (x86)\Freescale SYSTEM_INCLUDE_PATHS += :\Program Files (x86)\Metrowerks SYSTEM_INCLUDE_PATHS += :\Program Files (x86)\Intel SYSTEM_INCLUDE_PATHS += :\Program Files (x86)\ARM @@ -5042,37 +5899,175 @@ SYSTEM_INCLUDE_PATHS += /Library/Frameworks/ SYSTEM_INCLUDE_PATHS += /System/Library/ SYSTEM_INCLUDE_PATHS += /opt/local/include/ SYSTEM_INCLUDE_PATHS += /sw/include/ +SYSTEM_INCLUDE_PATHS += /usr/llvm-gcc- + +# Parameter VISUALIZATION +# +# Purpose +# Specifies whether to generate a call graph for visualization. +# +# Type +# {Yes, No} +# +# Behavior +# - Yes : the CodeSonar analysis generates additional data in +# support of visualization and sends it to the hub. Visualization +# functionality for this analysis of the project is enabled on +# the hub. +# - No : additional data is not generated, and visualization is not +# enabled for this analysis of the project. + +VISUALIZATION = Yes + + +# Parameter ASSUME_UNDEFINED_PARAMETERS_MAYBE_FREED +# Parameter ASSUME_UNDEFINED_PARAMETERS_MAYBE_INITIALIZED +# Parameter ASSUME_UNDEFINED_PARAMETERS_MAYBE_MODIFIED +# Parameter ASSUME_FUNCPTR_PARAMETERS_MAYBE_FREED +# Parameter ASSUME_FUNCPTR_PARAMETERS_MAYBE_INITIALIZED +# Parameter ASSUME_FUNCPTR_PARAMETERS_MAYBE_MODIFIED +# Parameter ASSUME_VARARG_PARAMETERS_MAYBE_FREED +# Parameter ASSUME_VARARG_PARAMETERS_MAYBE_INITIALIZED +# Parameter ASSUME_VARARG_PARAMETERS_MAYBE_MODIFIED +# Parameter ASSUME_OTHER_PARAMETERS_MAYBE_FREED +# Parameter ASSUME_OTHER_PARAMETERS_MAYBE_INITIALIZED +# Parameter ASSUME_OTHER_PARAMETERS_MAYBE_MODIFIED +# +# Purpose +# For cases where CodeSonar cannot determine this directly, these +# parameters specify the effects that certain called functions may +# be assumed to have on their parameters and memory locations that +# are transitively reachable from those parameters (pointer +# targets, structure fields, and so on). +# +# Type +# {Yes, No} +# +# Tags +# - LANGUAGE_TREATMENT: Treatment of Language Constructs +# - WC_ALLOC.LEAK: Used by Leak +# - WC_LANG.MEM.UVAR: Used by Uninitialized Variable +# +# Behavior +# Each parameter specifies, for a single kind of function call, +# whether CodeSonar can treat that call as if it may {free, +# initialize, modify} one or more of its parameters {P} or the +# memory locations transitively reachable from {P}. +# +# The function call kinds are as follows. +# - _UNDEFINED_ : a call to a function whose definition does not +# appear in the analyzed project. +# - _FUNCPTR_ : a call through a function pointer. +# - _VARARG_ : a call to a variadic function. Note: the +# ASSUME_VARARG_PARAMETERS_MAYBE_* rules control the treatment of +# variadic arguments (those designated by '...' in the header) +# only. +# - _OTHER_ : other special cases. This designation includes +# recursive calls and certain calls to functions whose analysis +# was incomplete. +# +# The effects are as follows, where {f} denotes all functions of +# the kind under consideration and {T} denotes the set of arguments +# to a function call along with all transitively reachable memory +# locations. +# - _MAYBE_FREED : if set to Yes, CodeSonar will treat all calls to +# {f} as if they may free one or more of {T}. This can reduce the +# incidence of Leak warnings. If set to No, CodeSonar will treat +# all calls to {f} as if they do not free any of {T}. +# - _MAYBE_INITIALIZED : if set to Yes, CodeSonar will treat all +# calls to {f} as if they may initialize one or more of {T}. This +# can reduce the incidence of Uninitialized Variable warnings. If +# set to No, CodeSonar will treat all calls to {f} as if they do +# not initialize any of {T}. +# - _MAYBE_MODIFIED : if set to Yes, CodeSonar will treat all calls +# to {f} as if they may modify one or more of {T}. This can +# reduce the incidence of warnings from path-sensitive warning +# classes such as Buffer Overrun, Division By Zero, and +# Unreachable Code: 5 warning classes. If set to No, CodeSonar +# will treat all calls to {f} as if they do not modify any of +# {T}. +# +# Notes +# For Yes settings, CodeSonar will make the associated assumptions +# only when doing so allows it to avoid issuing a warning. +# +# For example, suppose we have undefined function g() and are +# analyzing the following code. +# int funcA(){ +# char *p = malloc(5); +# if (p) {g(p);} +# return 1; +# } +# +# int funcB(){ +# char *p = malloc(5); +# if (p) { +# g(p); +# p++; +# } +# return 2; +# } +# +# With ASSUME_UNDEFINED_PARAMETERS_MAYBE_FREED=Yes, CodeSonar +# assumes that... +# - ...the call to g(p) in funcA frees p : no Leak warning, +# - ...the call to g(p) in funcB does not free p : no Use After +# Free warning, +# +# With ASSUME_UNDEFINED_PARAMETERS_MAYBE_FREED=No, CodeSonar must +# treat both calls to g(p) as if they do not free p. +# - funcA has a Leak warning, +# - funcB does not have a Use After Free warning. +# +# In general, Yes settings are likely to reduce the number of false +# positive warnings, but may also cause true defects to be +# overlooked. +# + +ASSUME_UNDEFINED_PARAMETERS_MAYBE_FREED = Yes +ASSUME_UNDEFINED_PARAMETERS_MAYBE_INITIALIZED = Yes +ASSUME_UNDEFINED_PARAMETERS_MAYBE_MODIFIED = Yes + +ASSUME_FUNCPTR_PARAMETERS_MAYBE_FREED = Yes +ASSUME_FUNCPTR_PARAMETERS_MAYBE_INITIALIZED = Yes +ASSUME_FUNCPTR_PARAMETERS_MAYBE_MODIFIED = Yes + +ASSUME_VARARG_PARAMETERS_MAYBE_FREED = Yes +ASSUME_VARARG_PARAMETERS_MAYBE_INITIALIZED = Yes +ASSUME_VARARG_PARAMETERS_MAYBE_MODIFIED = Yes + +ASSUME_OTHER_PARAMETERS_MAYBE_FREED = Yes +ASSUME_OTHER_PARAMETERS_MAYBE_INITIALIZED = Yes +ASSUME_OTHER_PARAMETERS_MAYBE_MODIFIED = Yes # Parameter EXTRA_COMPILATION_UNITS # -# Purpose +# Purpose # Specifies extra compilation units to be added to every CodeSonar -# project. In particular, use this parameter to include custom checks -# written with the \link ../Extensions/Extensions.html extension -# API\endlink. +# project. In particular, use this parameter to include custom +# checks written with the Extension API +# [doc/html/Extensions/Extensions.html]. # # Type -# Space-separated list of strings, each representing the full path to -# a .c file. +# Space-separated list of strings, each representing the full path +# to a .c file. # # Behavior # For each file listed, CodeSonar will obtain the corresponding IR -# from the file's sibling CSURF.FILES directory and include it in the -# project. +# from the file's sibling CSURF.FILES directory and include it in +# the project. # # Notes # If a path contains spaces, it should be quoted "". # -# Every file listed should be a C or C++ source file that has -# previously been compiled in the file's directory with -# \code -# (Windows) -# codesonar -w xcc "-I/codesonar/libmodels" -c -# -# (Otherwise) -# codesonar -w xcc -I/codesonar/libmodels -c -# \endcode +# Every file listed should be a C or C++ source file that +# has previously been compiled in the file's directory with +# (Windows) +# codesonar -w xcc "-I/codesonar/libmodels" -c +# +# (Otherwise) +# codesonar -w xcc -I/codesonar/libmodels -c