cppcheck/man/writing-addons.md

12 KiB

title subtitle author lang documentclass
Writing addons Version 2.11 Cppcheck team en report

Introduction

This document provides an overview about writing Cppcheck addons.

Overview of data

Tokens

See class Token in cppcheckdata.py

Cppcheck splits up the code in tokens. Operators, numbers, identifiers, etc.

Example C code:

ab = a + b;

Addon code:

import cppcheck

@cppcheck.checker
def func(cfg, data):
    for token in cfg.tokenlist:
        print(token.str)

Output:

$ cppcheck --dump test.c
$ python3 runaddon.py myaddon.py test.c.dump
Checking 1.c.dump...
Checking 1.c.dump, config ...
ab
=
a
+
b
;

The cfg.tokenlist does not always match the raw input code exactly. For instance:

  • The cfg.tokenlist is preprocessed.
  • There is no typedefs in cfg.tokenlist.
  • C++ templates are instantiated when possible in cfg.tokenlist.
  • Variable declarations are sometimes splitted up.
  • If you don't write {} around the body for a if/else/while/for etc then those are inserted in the cfg.tokenlist.
  • ...

There are various properties in the Token class and some of those will be discussed below.

AST - Abstract syntax tree

Cppcheck creates a syntax tree for every expression.

Example C code:

ab = a + b;

Addon code:

import cppcheck

@cppcheck.checker
def func(cfg, data):
    for token in cfg.tokenlist:
        out = token.str
        if token.astParent:
            out += f' parent:"{token.astParent.str}"'
        if token.astOperand1:
            out += f' astOperand1:"{token.astOperand1.str}"'
        if token.astOperand2:
            out += f' astOperand2:"{token.astOperand2.str}"'
        print(out)

Output:

$ cppcheck --dump test.c
$ python3 runaddon.py myaddon.py test.c.dump
Checking 1.c.dump...
Checking 1.c.dump, config ...
ab parent:"="
= astOperand1:"ab" astOperand2:"+"
a parent:"+"
+ parent:"=" astOperand1:"a" astOperand2:"b"
b parent:"+"
;

ValueType

Data type of expressions are provided by class ValueType in cppcheckdata.py.

Example C code:

short a;
a = a + 10;

Addon code:

import cppcheck

@cppcheck.checker
def func(cfg, data):
    for token in cfg.tokenlist:
        print(f'{token.str} : {token.valueType}')

Output:

$ cppcheck --dump test.c
$ python3 runaddon.py myaddon.py test.c.dump
Checking 1.c.dump...
Checking 1.c.dump, config ...
short : None
a : ValueType(type='short', sign='signed', bits=0, typeScopeId=None, originalTypeName=None, constness=0, pointer=0)
; : None
a : ValueType(type='short', sign='signed', bits=0, typeScopeId=None, originalTypeName=None, constness=0, pointer=0)
= : ValueType(type='short', sign='signed', bits=0, typeScopeId=None, originalTypeName=None, constness=0, pointer=0)
a : ValueType(type='short', sign='signed', bits=0, typeScopeId=None, originalTypeName=None, constness=0, pointer=0)
+ : ValueType(type='int', sign='signed', bits=0, typeScopeId=None, originalTypeName=None, constness=0, pointer=0)
10 : ValueType(type='int', sign='signed', bits=0, typeScopeId=None, originalTypeName=None, constness=0, pointer=0)
; : None

The pointer property is a simple counter.

int p    =>  pointer=0
int *p   =>  pointer=1
int **p  =>  pointer=2

The constness property is a bitmask.

int * *                     =>  constness=0
const int * *               =>  constness=1
int * const *               =>  constness=2
int * * const               =>  constness=4
const int * const *         =>  constness=3
const int * const * const   =>  constness=7

Variable

Information about a variable is provided by class Variable in cppcheckdata.py.

Example code:

short a[10];
a[0] = 0;

Addon code:

import cppcheck

@cppcheck.checker
def func(cfg, data):
    for token in cfg.tokenlist:
        print(f'{token.str} : {token.variable}')

Output:

$ cppcheck --dump test.c
$ python3 runaddon.py myaddon.py test.c.dump
Checking 1.c.dump...
Checking 1.c.dump, config ...
a : Variable(Id='0x55f432fc1580', nameTokenId='0x55f432fe0850', typeStartTokenId='0x55f432fc0eb0', typeEndTokenId='0x55f432fc0eb0', access='Global', scopeId='0x55f432fe0360', isArgument=False, isArray=True, isClass=False, isConst=False, isGlobal=True, isExtern=False, isLocal=False, isPointer=False, isReference=False, isStatic=False, constness=0)
[ : None
10 : None
] : None
; : None
a : Variable(Id='0x55f432fc1580', nameTokenId='0x55f432fe0850', typeStartTokenId='0x55f432fc0eb0', typeEndTokenId='0x55f432fc0eb0', access='Global', scopeId='0x55f432fe0360', isArgument=False, isArray=True, isClass=False, isConst=False, isGlobal=True, isExtern=False, isLocal=False, isPointer=False, isReference=False, isStatic=False, constness=0)
[ : None
0 : None
] : None
= : None
0 : None
; : None

Scope

See class Scope in cppcheckdata.py.

Every token is in some scope.

If you see {} in the code then that is a scope of some kind. There is one scope that is not surrounded by {}; the global scope.

Example c code:

int x;
void foo()
{
    if (x)
    {
        x = 0;
    }
}

Example addon #1 (list all scopes):

import cppcheck

@cppcheck.checker
def func(cfg, data):
    for scope in cfg.scopes:
        print(scope.type)

Output:

$ cppcheck --dump test.c
$ python3 runaddon.py myaddon.py test.c.dump
Checking 1.c.dump...
Checking 1.c.dump, config ...
Global
Function
If

Example addon #2 (show scope for each token):

import cppcheck

@cppcheck.checker
def func(cfg, data):
    for token in cfg.tokenlist:
        print(f'{token.str} : {scope.type}')

Output:

$ cppcheck --dump test.c
$ python3 runaddon.py myaddon.py test.c.dump
Checking 1.c.dump...
Checking 1.c.dump, config ...
int : Global
x : Global
; : Global
void : Global
foo : Global
( : Global
) : Global
{ : Function
if : Function
( : Function
x : Function
) : Function
{ : If
x : If
= : If
0 : If
; : If
} : If
} : Function

Special tokenlist tweaks and else if

The cfg.tokenlist has some tweaks. In C/C++ code it is optional to use { and } around the if/else/for/while body, if the body is only a single statement. However Cppcheck adds "{" and "}" tokens if those are missing.

One more tweak is that in cfg.tokenlist there is no "else if" scope.

Example C code:

void foo(int x)
{
    if (x > 0)
        --x;
    else if (x < 0)
        ++x;
}

The tokens in the cfg.tokenlist will look like this:

void foo(int x)
{
    if (x > 0)
    {
        --x;
    }
    else
    {
        if (x < 0)
        {
            ++x;
        }
    }
}

And there are 2 "If" scopes here. And 1 "Else" scope.

Function

The class Function in cppcheckdata.py represents a function that is declared somewhere.

Example code:

void foo(int x);

void bar()
{
    foo(1);
}

Example addon #1:

import cppcheck

@cppcheck.checker
def func(cfg, data):
    for token in cfg.tokenlist:
        print(f'{token.str} : {token.function}')

Output:

void : None
foo : Function(Id='0x55c5f9330f60', tokenId='0', tokenDefId='0x55c5f93510d0', name='foo', type='Function', isVirtual=False, isImplicitlyVirtual=False, isInlineKeyword=False, isStatic=False, argumentId={1: '0x55c5f9351260'})
( : None
int : None
x : None
) : None
; : None
void : None
bar : Function(Id='0x55c5f9331040', tokenId='0x55c5f93314a0', tokenDefId='0x55c5f93314a0', name='bar', type='Function', isVirtual=False, isImplicitlyVirtual=False, isInlineKeyword=False, isStatic=False, argumentId={})
( : None
) : None
{ : None
foo : Function(Id='0x55c5f9330f60', tokenId='0', tokenDefId='0x55c5f93510d0', name='foo', type='Function', isVirtual=False, isImplicitlyVirtual=False, isInlineKeyword=False, isStatic=False, argumentId={1: '0x55c5f9351260'})
( : None
1 : None
) : None
; : None
} : None

Value flow

For Cppcheck, by default variables and expressions have "unknown" values. If the value is only constrained by the data type that is typically not enough information to write warnings with precision. Unless all the values possible in the data type are bad.

In Cppcheck terminology an expression will have a "possible" value if Cppcheck can determine that there will be a specific value in some control flow paths.

In Cppcheck terminology an expression will have a "known" value if Cppcheck can determine that there will be a specific value in all control flow paths.

An expression can have several "possible" values. But it can't have several "known" values.

Example code:

void foo(int x)  // <- values of x is only constrained by data type. there are no "possible" or "known" values here.
{
    a = x;  // <- assuming that condition below is not redundant, x can have value 2.
    if (x == 2)
    {
        b = x + 2;  // <- value of x is always 2 when this code is executed. It's "known".
    }
    else
    {
        c = x;
    }
    d = x + 10;  // <- value of x can be 2 when this code is executed. It's "possible".
}

Addon:

import cppcheck

@cppcheck.checker
def func(cfg, data):
    for token in cfg.tokenlist:
        if token.values:
            print(f'line {token.linenr} str="{token.str}"')
            for value in token.values:
                print(f'    {value}')

Output:

$ ../cppcheck --dump 1.c ; python3 runaddon.py myaddon.py 1.c.dump 
Checking 1.c ...
Checking 1.c.dump...
Checking 1.c.dump, config ...
line 3 str="="
    Value(intvalue=2, tokvalue=None, floatvalue=None, containerSize=None, condition=4, valueKind='possible', inconclusive=False)
line 3 str="x"
    Value(intvalue=2, tokvalue=None, floatvalue=None, containerSize=None, condition=4, valueKind='possible', inconclusive=False)
line 4 str="2"
    Value(intvalue=2, tokvalue=None, floatvalue=None, containerSize=None, condition=None, valueKind='known', inconclusive=False)
line 6 str="="
    Value(intvalue=4, tokvalue=None, floatvalue=None, containerSize=None, condition=4, valueKind='known', inconclusive=False)
line 6 str="x"
    Value(intvalue=2, tokvalue=None, floatvalue=None, containerSize=None, condition=4, valueKind='known', inconclusive=False)
line 6 str="+"
    Value(intvalue=4, tokvalue=None, floatvalue=None, containerSize=None, condition=4, valueKind='known', inconclusive=False)
line 6 str="2"
    Value(intvalue=2, tokvalue=None, floatvalue=None, containerSize=None, condition=None, valueKind='known', inconclusive=False)
line 12 str="="
    Value(intvalue=12, tokvalue=None, floatvalue=None, containerSize=None, condition=4, valueKind='possible', inconclusive=False)
line 12 str="x"
    Value(intvalue=2, tokvalue=None, floatvalue=None, containerSize=None, condition=4, valueKind='possible', inconclusive=False)
line 12 str="+"
    Value(intvalue=12, tokvalue=None, floatvalue=None, containerSize=None, condition=4, valueKind='possible', inconclusive=False)
line 12 str="10"
    Value(intvalue=10, tokvalue=None, floatvalue=None, containerSize=None, condition=None, valueKind='known', inconclusive=False)

If the value is determined from a condition then the attribute condition points out the line that has the condition.