User annotations are special comments that can be specified in the source code for additional diagnostic rules configuration. An annotation can be found at one of the following locations:
User annotations that change the behavior of diagnostic rules are listed below. This functionality is available only for the C and C++ analyzer. User annotations given in this section are omitted when analyzing projects written in other programming languages.
Note. By default, user annotations are not applied to virtual functions. Here you can learn how to enable it.
When you check the project based on Unreal Engine, the analyzer applies diagnostic rules (for example, V1100 and V1102) that detect errors typical for UE projects. PVS-Studio applies the diagnostic rules only when it detects header files from the directory containing UE source code.
If a project contains compilable files that do not have such header files, the diagnostic rules are not applied, even if they are enabled. This way, the analyzer avoids generating irrelevant warnings for projects that do not use UE.
If you want to enforce a set of diagnostic rules on an arbitrary compilable file or a group of files, add the following comment:
//V_TREAT_AS_UNREAL_ENGINE_FILEThere are many system functions that can return a null pointer under certain conditions. Functions like 'malloc', 'realloc', and 'calloc' are good examples. These functions return 'NULL' when they fail to allocate a buffer of the specified size.
Sometimes you may want to change the analyzer's behavior and make it think, for example, that 'malloc' cannot return a null pointer. For example, this might be handy if the user employs system libraries that handle out-of-memory errors in a specific way.
An opposite scenario is also possible. The user may help the analyzer and specify that a certain system or user-declared function can return a null pointer.
With user annotations, you can specify whether a function can or cannot return a null pointer.
Annotation format:
//V_RET_[NOT]_NULL, function: [namespace::][class::]functionNameFor example, the user wants to specify to the analyzer that the 'Foo' function of the 'Bar' class within the 'Space' namespace cannot return a null pointer. Then the annotation looks like this:
//V_RET_NOT_NULL, function: Space::Bar::FooUser annotations support nested namespaces and nested classes. Suppose the 'Space2' namespace is within the 'Space1' namespace. The 'Bar1' class is within the 'Space2' namespace. The 'Bar2' class is within the 'Bar1' class. The 'Bar2' class has the 'Foo' member function, which can't return a null pointer. Then you can annotate this function the following way:
//V_RET_NOT_NULL, function: Space1::Space2::Bar1::Bar2::FooFor system functions, the annotation can be located at the global header file (for example, at the precompiled header), or at the diagnostic rules configuration file.
For clarity, let's look at two examples of system function annotations.
The function does not return a null pointer:
//V_RET_NOT_NULL, function:mallocNow the analyzer thinks that the 'malloc' function cannot return a null pointer and, therefore, will not issue the V522 warning for the following code:
int *p = (int *)malloc(sizeof(int) * 100);
p[0] = 12345; // okThe function returns a pointer that can be null:
//V_RET_NULL, function: Memory::QuickAllocWith this comment, the analyzer starts issuing a warning for the following code:
char *p = Memory::QuickAlloc(strlen(src) + 1);
strcpy(p, src); // Warning!In projects with special quality requirements, you may need to find all functions that return a pointer. For this purpose, use the following comment:
//V_RET_NULL_ALLWe don't recommend using this annotation as it causes too many warnings to be issued. However, if you require this for your project, you can add the return pointer check for all such functions in your code using this specific comment.
By default, the analyzer equally checks the code where the 'assert' macro is present regardless of the project's configuration (Debug, Release, ...). So, the analyzer does not take into account that code execution is interrupted if there is a false condition.
To set another analyzer behavior, use the following comment:
//V_ASSERT_CONTRACTPlease note that in this mode, the analysis results may differ depending on the way the macro is expanded in the project configuration being checked.
Let's look at this 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 issues a warning on the possible null pointer dereference when calling the 'foo' function.
But if you add the '//V_ASSERT_CONTRACT' comment, the warning will be gone.
You can also specify the name of the macro which the analyzer will handle in the same way it handles 'assert'. To do this, use the following annotation:
//V_ASSERT_CONTRACT, assertMacro:[MACRO_NAME]The 'assetMacro' key is the name of the macro that the analyzer handles similarly to 'assert'. Instead of '[MACRO_NAME]', insert the name of the annotated macro.
Example:
//V_ASSERT_CONTRACT, assertMacro:MY_CUSTOM_MACRO_NAMENow the analyzer processes the 'MY_CUSTOM_MACRO_NAME' macro as 'assert'.
If you need to specify multiple macro names, add the separate '//V_ASSERT_CONTRACT' directive for each of them.
Some projects use custom implementations of various system functions, such as 'memcpy', 'malloc', and so on. In this case, the analyzer is unaware that such functions behave similarly to their standard implementations. You can specify which custom functions correspond to system functions.
Annotation format:
//V_FUNC_ALIAS, implementation:imp, function:f, namespace:n, class:cUsage example:
//V_FUNC_ALIAS, implementation:memcpy, function:MyMemCpyNow, the analyzer will process calls to the 'MyMemCpy' function in the same way it processes calls to 'memcpy'.
You can specify the names of your own functions that should be format validated. It's assumed that the principle of string formatting corresponds to the 'printf' function.
You will need the user annotation for this. Here is the usage example:
//V_FORMATTED_IO_FUNC,function:Log,format_arg:1,ellipsis_arg:2
void Log(const char *fmt, ...);
Log("%f", time(NULL)); // <= V576Annotation format:
The most complete usage example:
namespace A
{
class B
{
void C(int, const char *fmt, ...);
};
}
//V_FORMATTED_IO_FUNC, function:A::B::C, format_arg:2, ellipsis_arg:3