Use of a forbidden function

Function appears in a blacklist of forbidden functions

Description

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

• 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="FORBIDDEN_FUNC"/>

  where funcname is the name of the function you want to blacklist.

• Specify this XML file as argument for the option -code-behavior-specifications.

Even if you enable this checker using the option Find defects (-checkers), unless you specify a blacklist of functions, this checker stays disabled.

Risk

A function might be blacklisted 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 blacklist 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 blacklisted function with an approved function.

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

Examples

Use of Blacklisted Function

#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:

<function name="std::signal" behavior="FORBIDDEN_FUNC"/>

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.

Blacklisting C++ Overloaded Operators

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:

   <function name="orderedPair::operator=" behavior="FORBIDDEN_FUNC"/>
    <function name="orderedPair::operator+" behavior="FORBIDDEN_FUNC"/>

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