Main Content

Use of a forbidden macro

Use of macro that appears in a blocklist of forbidden macros

Since R2022b

expand all in page

Description

This defect occurs when you use a macro that appears in a blocklist of forbidden macros. To create the blocklist:

  • List macros in an XML file in a specific syntax.

    Copy the template file code-behavior-specifications-template.xml from the folder polyspaceroot\polyspace\verifier\cxx to a writable location and modify the file. Enter each macro in the file using the following syntax after existing similar entries:

    <token name="macroname" kind="macro">
      <behavior name="FORBIDDEN_MACRO"/>
</token>
    where macroname is the name of the macro you want to block.

  • Specify this XML file as argument for the option -code-behavior-specifications. See Flag Deprecated or Unsafe Functions, Keywords, or Macros Using Bug Finder Checkers.

Risk

A macro might be blocked for one of these reasons:

  • The macro is prone to misuse or makes the code difficult to maintain.

  • The macro is being deprecated as part of a migration. For instance, you might want to allow the boolean macros TRUE and FALSE only in their all-caps form, and forbid other forms such as true and false.

    As part of a migration, you can make a list of macros that need to be replaced and use this checker to identify their use.

Fix

Replace the blocked macro with an allowed macro.

When rolling out this checker to a group, project or organization, create a list of blocked macros and their replacements so that results reviewers can consult the list and make appropriate replacements.

Extend Checker

This defect checker requires a blocklist of macros to be specified. Even if you specify the checker using the option Find defects (-checkers), it is not enabled unless you also specify the blocklist. See Flag Deprecated or Unsafe Functions, Keywords, or Macros Using Bug Finder Checkers.

Examples

expand all

#define TRUE 1u
#define FALSE 0u
#define true 1u
#define false 0u

unsigned char isPositive(int num){
    if(num > 0)
        return TRUE;
    else
        return FALSE;
}

unsigned char isEven(int num){
    if(num%2 == 0)
        return true;
    else
        return false;
}

Suppose you want to allow the boolean macros TRUE and FALSE only in their all-caps form, and forbid other forms such as true and false. Add the following to the template XML file after similar existing entries:

<?xml version="1.0" encoding="UTF-8"?>
<specifications xmlns="http://www.mathworks.com/PolyspaceCodeBehaviorSpecifications">
  <tokens>
    <token name="true" kind="macro">
       <behavior name="FORBIDDEN_MACRO"/>
    </token>
    <token name="false" kind="macro">
       <behavior name="FORBIDDEN_MACRO"/>
    </token>
  </tokens>
</specifications>
and specify the XML file with the option -code-behavior-specifications.

In the analysis results, all uses of the true and false macros are flagged by this checker.

Result Information

Group: Good practice
Language: C | C++
Default: Off
Command-Line Syntax: FORBIDDEN_MACRO
Impact: Low

Version History

Introduced in R2022b

expand all

See Also

|

Topics