Note about diagnostics fine-tuning

Dec 15 2014

Author: Andrey Karpov

Settings
New settings syntax
V128 tweaking
V576 tweaking
Conclusion

Despite the fact that our analyzer is stated to be one of the simplest tools in installing and everyday usage (everything is working "out-of-the-box" and does not require any unintuitive tweaks), some users lacks flexibility of some of the diagnostic rules. Unfortunately, usability and flexibility is if not totally opposite, but sometimes those features conflict with each other. In this note, we shall be talking about additional mechanism of tuning some diagnostic rules, which can be useful for some of our valuable users.

Settings

It was already possible to manipulate the behavior of a few diagnostic rules using special comments. You can read about it from their description in documentation. For instance, //-V610_LEFT_SIGN_OFF for V610 rule.

However, all these settings was about false alarm suppression. New settings now allows users to hint analyzer where additional errors may be found.

New settings syntax

Syntax of new mechanism is as follows: to activate addition to diagnostic, user should use //+V comment. We have chosen this format because it is similar to the widely used comment to false alarm suppression: //+V. New format to make an addition to diagnostic is simple:

//+V<Number of rule>, <Key>:<Value>, ... , <Key>:<Value>

User can arrange parameters in any order in relation to each other. In a few diagnostics, there may be a possibility to add values with the same key, but with different values. In almost any diagnostic, some parameters in addition may be absent.

User may write an addition in:

The file that is included in the whole project (stdafx.h),
If they are related to some function or class method - near its prototype or realization in .h-file,
If addition should be related only to particular .cpp-file - anywhere inside it.

Restriction - user should write the rule in one line.

Examples:

//+V128,function:N128_write_it,non_memsize:2,class:N128_T

//+V576,function:foo,format_arg:1,ellipsis_arg:3,namespace:X,class:Y

At the time when article was written, we have implemented new additions for two diagnostic rules: V128 and V576. In future, there may be new additions to other rules.

V128 tweaking

V128 rule finds all the places where variable of memsize type is written into file or is read from file. Full description of rule is present in the link above. One user asked to extend V128 with addition of possibility of creating a warning on custom functions.

Addition format is as follows: just above function prototype (or near its realization, or in standard header file) user should add a special comment. Let us start with the usage example:

//+V128, function:write, non_memsize:2
void write(string name, char);
void write(string name, int32);
void write(string name, int64);
foo()
{
  write("zz", array.size()); // warning V128
}

Format:

"function" key represents name of the function to be checked by analyzer. This key is necessary - without this key addition, of course, would not work.
"class" key - non-necessary key that allows to enter class name to which this function belongs (i.e. class method). Without specifying it analyzer will check any function with given name, with specifying - only ones that belongs to the particular class.
"namespace" key - non-necessary key that allows to enter namespace name to which function belongs. Again, without specifying it analyzer will check any function with given name, with specifying - only ones that belongs to the particular namespace. Key will correctly work with the "class" key - analyzer then will check any class method with given name that belongs to particular namespace.
"non_memsize" key allows specifying number of argument that should not allow type, which size changes depending on architecture. Number counts from one, not from zero. There is a technical restriction - this number should not exceed 14. There may be multiple "non-memsize" keys if there is a need to check multiple function arguments.

Warning level in case of user functions is always first.

At last, here is full usage example:

//Warns when in method C of class B
//from A namespace memsize-type value
//is put as a second or third argument.
//+V128,namespace:A,class:B,function:C,non_memsize:3,non_memsize:2

V576 tweaking

V576 rule finds all the places where argument in printf()-like function is not corresponding with its desired type in format string. Potential user asked us to extend this diagnostic rule to the case of user-defined functions. He suggested that analyzer would print a warning message in case of somewhere an argument does not correspond with format string. It is assumed that formatting principle is equal to the one in printf() function.

Again, no sooner said than done.

Addition format is alike to the one of V128 diagnostics. User should write a comment of special kind near function prototype (or near its implementation, or in standard header file). Again, let us start with the usage example:

//+V576, function:Mylog, format_arg:1, ellipsis_arg:2
Mylog("%f", time(NULL)); // warning V576

Format:

"function", "class" and "namespace" keys determines function name, class name (if it's required to analyze only methods of some class) and namespace name (if it's required to analyze only functions or class members of some namespace).
"format_arg" key determines number of function argument that contains format string. This argument is necessary. Numbers counts from one, not from zero, and should not exceed 14.
"ellipsis_arg" key determines number of function argument with ellipsis (three dots). This number is bound by the same restrictions as the one given by format_arg key. In addition, ellipsis_arg number should be greater than format_arg (because ellipsis can only be the last argument). This key is also nessesary.

At last, here is full usage example:

//Warn when in C method of class B from A namespace
//arguments, counting from third one, does not
//correspond to the format line in the second argument 
//+V576,namespace:A,class:B,function:C,format_arg:2,ellipsis_arg:3

Conclusion

Our tool is constantly improving; it always gains new possibilities and other decisions features. I hope we also stressed that we love our clients and value their wishes. On PVS-Studio license purchase, you will also gain qualified support and realization of features that will allow you to gain maximum profit from static code analysis.