Main Content

Use of a forbidden function

Use of function that appears in a blocklist of forbidden functions

Since R2020a

expand all in page

Description

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

  • List functions 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 function in the file using the following syntax after existing similar entries:

    <function name="funcname">
   <behavior name="FORBIDDEN_FUNC"/>
</function>
    where funcname is the name of the function 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 function might be blocked for one of these reasons:

  • The function can lead to many situations where the behavior is undefined leading to security vulnerabilities, and a more secure function exists.

    You can forbid functions that are not explicitly checked by existing checkers such as Use of dangerous standard function or Use of obsolete standard function.

  • The function is being deprecated as part of a migration, for instance, from C++98 to C++11.

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

Fix

Replace the blocked function with an allowed function.

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

Extend Checker

This defect checker requires a blocklist of functions 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

#include <csignal>
#include <iostream>

namespace
{
  volatile std::sig_atomic_t gSignalStatus;
}

void signal_handler(int signal)
{
  gSignalStatus = signal;
}

int main()
{
  // Install a signal handler
  std::signal(SIGINT, signal_handler);

  std::cout << "SignalValue: " << gSignalStatus << '\n';
  std::cout << "Sending signal " << SIGINT << '\n';
  std::raise(SIGINT);
  std::cout << "SignalValue: " << gSignalStatus << '\n';
}

Suppose you want to deprecate the std::signal function. 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">
  <functions>
     <function name="std::signal">
        <behavior name="FORBIDDEN_FUNC"/>
     </function>
   </functions>
</specifications>
and specify the XML file with the option -code-behavior-specifications.

In the analysis results, all uses of the std::signal function are flagged by this checker.

class orderedPair {
        int var1;
        int var2;
    public:
        orderedPair() {
            var1 = 0;
            var2 = 0;
        }
        orderedPair(int arg1, int arg2) {
            var1 = arg1;
            var2 = arg2;
        }
        orderedPair& operator=(const orderedPair& rhs) {
            var1 = rhs.var1;
            var2 = rhs.var2;
            return *this;
        } 
        orderedPair& operator+(orderedPair& rhs) {
            var1 += rhs.var1;
            var2 += rhs.var2;
            return *this;
        }  
};

void main() {
    int one=1, zero=0, sum;
    orderedPair firstOrderedPair(one, one);
    orderedPair secondOrderedPair(zero, one);
    orderedPair sumPair;
    
    sum = zero + one;
    sumPair = firstOrderedPair + secondOrderedPair;    
}

Suppose you want to identify all the locations where operator overloads in the orderedPair class are used. Add the overloaded operators to the template XML file:

<?xml version="1.0" encoding="UTF-8"?>
<specifications xmlns="http://www.mathworks.com/PolyspaceCodeBehaviorSpecifications">
  <functions>
     <function name="orderedPair::operator=">
        <behavior name="FORBIDDEN_FUNC"/>
     </function>
     <function name="orderedPair::operator+">
        <behavior name="FORBIDDEN_FUNC"/>
     </function>
   </functions>
</specifications>
and specify the XML file with the option -code-behavior-specifications.

The analysis identifies all calls to the overloaded operators and flags their use. Using this method, you can distinguish specific overloads of an operator instead of searching for and browsing through all instances of the operator.

Result Information

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

Version History

Introduced in R2020a

See Also

|

Topics