Contents
Filtering and handling the analyzer output through diagnostic configuration files (.pvsconfig)
- How to add/use configuration files in IDE and other analysis tools
- General functionality of configuration files
- Additional features of the C++ analyzer
A configuration file is used to display and filter analyzer messages. The configuration file also allows you to set additional parameters for the analysis. You can use configuration files only for projects written in C, C++ or C#.
Plugins for the following IDEs support configuration files:
- Visual Studio;
- Rider.
Utilities that support configuration files:
- PVS-Studio_Cmd.exe;
- CLMonitor.exe (only in analyze or analyzeFromDump mode);
- C and C++ Compiler Monitoring UI (Standalone.exe);
- CompileCommandsAnalyzer.exe (in analyze mode).
How to add/use configuration files in IDE and other analysis tools
.pvsconfig in Visual Studio
To use a configuration file in Visual Studio, add the file at the project or solution level. Choose the necessary project or solution in the Solution Explorer window inside Visual Studio IDE. Select the 'Add New Item...' context menu item. In the window that appears, select the 'PVS-Studio Filters File' file type.
If there is no file template, you can add a simple text file with the ".pvsconfig" extension to the project or solution.
You can add multiple configuration files for each project/solution.
Configuration files added at the project level apply to all files in a given project. Configuration files added at the solution level apply to all files of all projects in a given solution.
.pvsconfig in Rider
There is no special template for adding a configuration file for Rider.
You can add a configuration file for Rider only at the project level. To use the diagnostics configuration file in Rider, add a new file with the '.pvsconfig' extension to the project via Solution Explorer.
.pvsconfig in PVS-Studio_Cmd.exe and pvs-studio-dotnet
When you run analysis through PVS-Studio_Cmd.exe or pvs-studio-dotnet, the configuration files from the project or solution being analyzed are automatically used. You can also specify the path to the additional .pvsconfig file using the --rulesConfig (-C) parameter:
PVS-Studio_Cmd.exe -t ProjName.sln -C \path\to\.pvsconfig
pvs-studio-dotnet -t ProjName.sln -C /path/to/.pvsconfigIn this case, the settings both from the files in the project/solution and the file passed as an argument are taken into account in the analysis.
.pvsconfig in CLMonitor.exe
You can specify the path to the configuration file as a command-line argument (the -c parameter):
CLMonitor.exe analyzeFromDump -d /path/to/compileDump.gz -c /path/to/.pvsconfig.pvsconfig in CompilerCommandsAnalyzer.exe
If you use the CompilerCommandsAnalyzer.exe utility, you can specify the path to the .pvsconfig file via the -R parameter:
CompilerCommandsAnalyzer.exe analyze ... -R /path/to/.pvsconfig.pvsconfig in Standalone.exe
In Standalone.exe, you can specify the path to the file when you start monitoring.
The use of the global .pvsconfig file
The global diagnostics configuration file is used during all project checks. There can be several global .pvsconfig configuration files and the PVS-Studio tools will use them all.
To add a global configuration file, create a file with the pvsconfig extension in the folder:
- For Windows – '%APPDATA%\PVS-Studio';
- For Linux and macOS – '~/.config/PVS-Studio'.
General functionality of configuration files
Adding entries to the configuration file
To set the settings in the configuration files use special directives that start with the '//' characters. Each directive is written on a new line.
Example:
//-V::122
//-V::123You can add comments — write the '#' character at the beginning of the line.
Example:
# I am a commentFiltering the analyzer messages
Complete warning disabling
To completely disable a certain diagnostic, use the following syntax pattern:
//-V::number'number' is the number of the diagnostic you want to turn off (for example, 3022).
Example:
//-V::3022In this case, the V3022 diagnostic warnings will be ignored.
To disable a number of diagnostics, you can list their numbers separating them by commas:
//-V::number1,number2,...,numberNExample:
//-V::3022,3080This use of this directive will completely disable V3022 and V3080 diagnostics.
Disabling a group of diagnostics
To disable diagnostics of a certain group, use the following directives:
//-V::GA
//-V::X64
//-V::OP
//-V::CS
//-V::MISRA
//-V::OWASPDefinition for each of the group:
- GA (General Analysis) — general analysis rule set. The main set of PVS-Studio diagnostic rules;
- OP (Optimization) — diagnostics of optimization. These are tips to improve the code efficiency;
- X64 (64-bit) — diagnostics that allow you to identify specific errors related to the development of 64-bit applications and migrating the code from a 32-bit platform to a 64-bit one;
- CS (Customers' Specific) — highly specialized diagnostics, developed by user requests. By default, this set of diagnostics is disabled;
- MISRA — the set of diagnostics, developed according to the MISRA standard (Motor Industry Software Reliability Association). By default, this set of diagnostics is disabled;
- OWASP — the set of diagnostics that allow you to find security issues and check code for compliance with OWASP ASVS standard. By default, this set of diagnostics is disabled.
You can disable several groups of diagnostics — list them separating by commas.
For example:
//-V::GA,MISRADisabling all C++ or C# diagnostics
To turn off all diagnostics of C++ or C# analyzer use the following directives:
//-V::C++
//-V::C#Excluding warnings for certain diagnostics at specific levels
If you need to turn off warnings of a certain level, use the following syntax pattern:
//-V::number1,number2,...,numberN:level- 'number1', 'number2', etc. — the numbers of diagnostics that need to be excluded from the analysis results (for example, 3022).
- 'level' — the warning level (1, 2 or 3).
The number 1 corresponds to warnings of 'High' level, the number 2 — to 'Medium' level warnings, the number 3 — to 'Low' level warnings.
You can filter out warnings of several levels at once. To do this, list the levels and separate them by commas.
Example:
//-V::3022,5623:1,3This directive will filter out the warnings of V3022 and V5623 diagnostics of 'High' and 'Low' levels.
Excluding warnings by the substring in a message
The analyzer supports the ability to exclude warnings by the diagnostic number and substring contained in a message.
The syntax pattern is as follows:
//-V::number::{substring}- 'number' is the number of diagnostic which message needs to be suppressed (for example, 3080);
- 'substring' is a substring contained in the analyzer's message.
The syntax pattern to suppress warnings by the substring:
//-V::3022::{always true}In this case, the V3022 warnings with the 'always true' substring in the message will be suppressed.
Excluding warnings by the certainty level and the substring
You can filter warnings by the certainty level and the substring simultaneously. The syntax pattern is the following:
//-V::number1,number2,...,numberN:level:{substring}- 'number1', 'number2', etc. — the numbers of diagnostics that need to be excluded from the analysis results (for example, 3022);
- 'level' — the warning's level (1, 2 or 3);
- 'substring' is a substring contained in the analyzer's message.
The number 1 corresponds to warnings of 'High' level, the number 2 is the 'Medium' level warnings, and the number 3 is the 'Low' level warnings.
You can filter out warnings of several levels at once. To do this, list the levels and separate them by commas.
Example:
//-V::3022,5623:1:{always true}This directive will filter out the warnings of V3022 and V5623 diagnostics of 'High' and 'Low' levels with the 'always true' substring in the message.
Marking warnings issued for code fragment that includes the specified fragment as False Alarm
You can mark warnings issued for certain string that includes the specified fragment as False Alarm. Use the following directive:
//-V:substring:number- 'substring' is the substring in the string indicated by the analyzer;
- 'number' is the number of diagnostic which message needs to be suppressed (for example, 3080).
Note 1. The substring you are looking for ('substring') must not contain spaces.
Note 2. Messages filtered in this way will still appear in the report. They will be marked as False Alarm (FA).
Example:
public string GetNull()
{
return null;
}
public void Foo()
{
string nullStr = GetNull();
Console.WriteLine(nullStr.Length);
}For this code, the analyzer will issue a warning: "V3080 Possible null dereference. Consider inspecting 'nullStr'.".
Use the following directive in .pvsconfig to add the FA mark for warnings issued on such code:
//-V:Console:3080This directive adds a False Alarm mark to all V3080 warnings issued on the code lines containing 'Console'.
You can also add the False Alarm mark to multiple diagnostic warnings at once. To do this, list their numbers separated by commas:
//-V:substring:number1,number2,...,numberExample:
//-V:str:3080,3022,3175The V3080, V3082, V3175 diagnostic messages will be marked as False Alarm if there is the 'str' substring in the code line indicated by the analyzer.
Excluding files from the analysis
To exclude a file or a group of files from analysis, use the directive:
//V_EXCLUDE_PATH fileMaskSeveral examples of masks:
//V_EXCLUDE_PATH C:\TheBestProject\thirdParty
//V_EXCLUDE_PATH *\UE4\Engine\*
//V_EXCLUDE_PATH *.autogen.csThe process of how the masks are specified is described in the documentation.
Ignoring global configuration files
Before running the analysis, 'PVS-Studio_Cmd' generates the configuration of diagnostic rules from:
- global configuration files (in the '%AppData%\PVS-Studio\' folder for Windows and in the '~/.config/PVS-Studio' folder for Linux or macOS);
- the file passed through the --rulesConfig (-C) option;
- files added to the solution;
- files added to the project.
There may be a situation when the global configuration should not be applied during analysis of some projects or solutions. If you need to ignore global configuration files, add the following flag to the corresponding '.pvsconfig' file:
//IGNORE_GLOBAL_PVSCONFIGSpecifying the file analysis timeout for a project/solution/system
If you run the analysis with the plugin interface (Visual Studio, Rider and CLion) or in the C and C++ Compiler Monitoring UI (Standalone.exe) you can specify a timeout after which the file analysis is terminated. If the analysis timeout is exceeded, the V009 warning is added to the analysis results. The warning contains information about the file that exceeded the timeout.
You can specify the file analysis timeout in .pvsconfig. For example, you can set a 10-minute (600-second) timeout with the following line:
//V_ANALYSIS_TIMEOUT 600If the timeout value specified in the .pvsconfig file is 0, the files are analyzed with no time limit.
You can limit file analysis time in certain projects/solutions/systems by specifying a timeout in .pvsconfig files of different levels:
- use the --rulesConfig (-c) parameter in PVS-Studio_Cmd.exe (to redefine the file analysis timeout for the current solution/project analysis);
- system (%AppData% in Windows, ~/.config in Linux, macOS);
- solution (.sln);
- project level (.csproj, .vcxproj).
Changing the diagnostic warning level
To change the level, use the following directive:
//V_LEVEL_1::number'number' is the number of the diagnostic (for example, 3022).
To change the warning level for the V3176 diagnostic to the third level, use this entry:
//V_LEVEL_3::3176Directives that change the level:
- The '//V_LEVEL_1' changes the warning level to 'High';
- The '//V_LEVEL_2' changes the warning level to 'Medium';
- The '//V_LEVEL_3' changes the warning level to 'Low'.
Changing the text of the analyzer messages
To change the substring in the analyzer message, use the following directive:
//+diagnosticName:RENAME:{originalString:replacementString}, ...- 'diagnosticName' is the name of the diagnostic whose message needs to be modified (for example, V624);
- 'OriginalString' – the original substring;
- 'replacementString' – the string to be replaced with.
Let's look at how the directives works. The V624 diagnostic when it encounters the 3.1415 number in code, suggests replacing it with 'M_PI' from the '<math.h>' library. But the project uses a special mathematical library, and it is necessary to use mathematical constants from it. For the analyzer to work correctly, add the directive to the configuration file.
The directive looks as follows:
//+V624:RENAME:{M_PI:OUR_PI},{<math.h>:"math/MMath.h"}Now the analyzer will tell you that you need to use the 'OUR_PI' constant from the 'math/MMath.h' header file.
It is possible to add a line to the message.
The directive that allows you to do this has the following form:
//+diagnosticName:ADD:{message}- 'diagnosticName' – the name of the diagnostic whose message needs to be modified (for example, V2003);
- 'message' – the string you need to add.
Here's the example. Let's look at the V2003 diagnostic message: "Explicit conversion from 'float/double' type to signed integer type.".
To add additional information to this message, you need to use the following directive:
//+V2003:ADD:{ Consider using boost::numeric_cast instead.}Now the analyzer will output the modified message: "Explicit conversion from 'float/double' type to signed integer type. Consider using boost::numeric_cast instead.".
Additional features of the C++ analyzer
This section provides information about features of the C++ analyzer only. If you are analyzing projects written in other languages, the directives described here will be ignored.
Telling the analyzer that the function returns or does not return nullptr
There are many system functions that return a null pointer under certain conditions. Examples of such functions are 'malloc', 'realloc', 'calloc'. They return 'NULL' when a memory buffer of the specified size cannot be allocated.
You might want to change the behaviour of the analyzer and make it assume that, for example, the 'malloc' function cannot return 'NULL'. For example, the user can use system libraries which handle memory shortage situations in a special way.
The opposite situation is also possible. The user can tell the analyzer that a certain system or their function can return a null pointer.
If the function does not return 'nullptr', the directive has the following format:
//V_RET_NOT_NULL, namespace: n, class:c, function:fTo tell the analyzer that the function returns 'nullptr', add the following directive:
//V_RET_NULL, namespace: n, class: c, function: fFor both cases:
- The 'namespace' option is the namespace name: optional;
- The 'class' option is the name of the class: optional;
- The 'function' option – specifies the name of the function that can/cannot return a null pointer.
Let's look at examples.
The function does not return a null pointer:
//V_RET_NOT_NULL, function:mallocNow the analyzer knows that the result of executing the 'malloc' function does not return 'nullptr'.
The function returns a null pointer:
//V_RET_NULL, namesapce:Memory, function:QuickAllocThe analyzer will take into account that the 'QuickAlloc' function located in the 'Memory' namespace can return 'nullptr'.
Configurating the assert() macro handling
By default, the analyzer equally checks the code where the assert() macro is presented regardless of the configuration of the project. Namely, the analyzer specifically doesn't take into account that the execution of the code is interrupted if the macro has the false condition. To set another analyzer behavior, use the following directive:
//V_ASSERT_CONTRACTNote that in this mode the analysis results may vary depending on how the macro is expanded in the project configuration being checked.
Let's look at the example to make it clear:
MyClass *p = dynamic_cast<MyClass *>(x);
assert(p);
p->foo();The 'dynamic_cast' operator can return the 'nullptr' value. Thus, in the standard mode the analyzer will issue the warning that a null pointer dereferencing may occur when calling the 'foo' function.
But if we use the directive, the warning will be gone.
You can specify the macro name that the analyzer will handle in the same way it handles 'assert'. To do this, use the following directive:
//V_ASSERT_CONTRACT, assertMacro:macroNameThe 'assetMacro' option is the name of the macro that the analyzer will process as 'assert';
Example:
//V_ASSERT_CONTRACT, assertMacro:MY_CUSTOM_MACRO_NAMENow the analyzer will process the 'MY_CUSTOM_MACRO_NAME' macro as 'assert'.
If you need to specify multiple macro names, add a separate 'V_ASSERT_CONTRACT' directive for each of them.
Specifying an alias for a system function
Some projects may use custom implementations of various system functions, for example, 'memcpy', 'malloc', etc. In this case, the analyzer does not understand that such functions behave in the same way as their standard analogues. You can specify which custom functions correspond to which system ones.
The directive format:
//V_FUNC_ALIAS, implementation:imp, function:f, namespace:n, class:c- The 'implementation' option is the name of the standard function for which you need to specify an alias;
- The 'function' option is the alias name. The signature of the function whose name is specified in this option must match the signature of the function specified in the 'implementation' option;
- The 'class' option is the name of the class: optional;
- The 'namespace' option is the namespace name: optional.
Example:
//V_FUNC_ALIAS, implementation:memcpy, function:MyMemCpyNow, the analyzer will process calls to the 'MyMemCpy' function in the same way it processes calls of 'memcpy'.