CERT C++: OOP56-CPP

Honor replacement handler requirements

Since R2023b

expand all in page

Description

Rule Definition

Honor replacement handler requirements.¹

Polyspace Implementation

The rule checker checks for the issue Replacement handler function does not meet requirements

Examples

expand all

Replacement Handler Function Does Not Meet Requirements

Issue

This issue occurs when these conditions are true:

You replace one of these handler functions by using a custom implementation:
- new_handler
- terminate_handler
- unexpected_handler
The custom implementation does not meet the requirement specified by the C++ standards. The C++ standard specifies that the replacement handler functions must meet these requirements:
- new_handler must :
  - Make more storage available for allocation before returning to the caller
  - Throw exceptions of class bad_alloc or a class derived from bad_alloc.
  - Terminate execution of a program without returning to the caller
  For the intended purpose of a new_handler replacement, see std::set_new_handler.
- terminate_handler: This handler function must terminate execution of the program without returning to the caller. See std::terminate_handler.
- unexpected_handler: This handler function must not return to the caller. See std::unexpected_handler.

Risk

The C++ standard library behaves as expected only if the functions in your code meet the requirements imposed by the standard. If your handler functions do not meet the requirements specified by the standard, the behavior of your code is undefined.

Fix

To fix this issue, do one of the following:

Use the default set of handler functions.
Rewrite the replacement handler functions to meet the imposed requirements.

Example — Custom Handler Functions Do Not Behave as Required

This example implements three user-defined handler functions.

If the user-defined new_handler function cannot allocate sufficient memory, the C++ standard requires that the function raise an exception of class bad_alloc or a class derived from bad_alloc. Because the user defined handler function custom_new_handler does not raise exceptions when there is insufficient memory, Polyspace^® reports a violation.
The C++ standard requires that the user-defined terminate_handler function terminate the program execution. Because the user-defined handler function custom_terminate_handler raises an exception instead of terminating the execution, Polyspace reports a violation.
The C++ standard requires that the user-defined unexpected_handler function does not return to caller. Because the user-defined handler custom_unexpected_handler returns to caller, Polyspace reports a violation.

#include <new>
  
void custom_new_handler() { //Noncompliant
  // Returns number of bytes freed.
  extern std::size_t reclaim_resources();
  reclaim_resources();
}
  
void custom_terminate_handler() { //Noncompliant
  // ...
  throw 0;
}

void custom_unexpected_handler () { //Noncompliant
  // ...
  
}

// Set custom handlers
int main() {
  std::set_new_handler(custom_new_handler);
  std::set_terminate(custom_terminate_handler);
  std::set_unexpected(custom_unexpected_handler);
  // ...
}

Correction — Rewrite Handler Functions to Meet Standard Requirements

To fix these violations:

Raise an std::bad_alloc exception in custom_new_handler() when there is insufficient memory.
Terminate the execution by calling std::abort() in custom_terminate_handler().
Raise an exception instead of returning to caller in custom_unexpected_handler().

#include <new>
  
void custom_new_handler() { //Compliant
  // Returns number of bytes freed.
  extern std::size_t reclaim_resources();
  if(0==reclaim_resources()){
	  throw std::bad_alloc();
  }
  
}
  
void custom_terminate_handler() { //Compliant
  // terminating execution
  std::abort();
}

void custom_unexpected_handler () { //Compliant
  // throwing an exception
  throw 0;
}

// Set custom handlers
int main() {
  std::set_new_handler(custom_new_handler);
  std::set_terminate(custom_terminate_handler);
  std::set_unexpected(custom_unexpected_handler);
  // ...
}

Check Information

Group: Rule 09. Object Oriented Programming (OOP)

Version History

Introduced in R2023b

¹ This software has been created by MathWorks incorporating portions of: the “SEI CERT-C Website,” © 2017 Carnegie Mellon University, the SEI CERT-C++ Web site © 2017 Carnegie Mellon University, ”SEI CERT C Coding Standard – Rules for Developing safe, Reliable and Secure systems – 2016 Edition,” © 2016 Carnegie Mellon University, and “SEI CERT C++ Coding Standard – Rules for Developing safe, Reliable and Secure systems in C++ – 2016 Edition” © 2016 Carnegie Mellon University, with special permission from its Software Engineering Institute.

ANY MATERIAL OF CARNEGIE MELLON UNIVERSITY AND/OR ITS SOFTWARE ENGINEERING INSTITUTE CONTAINED HEREIN IS FURNISHED ON AN "AS-IS" BASIS. CARNEGIE MELLON UNIVERSITY MAKES NO WARRANTIES OF ANY KIND, EITHER EXPRESSED OR IMPLIED, AS TO ANY MATTER INCLUDING, BUT NOT LIMITED TO, WARRANTY OF FITNESS FOR PURPOSE OR MERCHANTABILITY, EXCLUSIVITY, OR RESULTS OBTAINED FROM USE OF THE MATERIAL. CARNEGIE MELLON UNIVERSITY DOES NOT MAKE ANY WARRANTY OF ANY KIND WITH RESPECT TO FREEDOM FROM PATENT, TRADEMARK, OR COPYRIGHT INFRINGEMENT.

This software and associated documentation has not been reviewed nor is it endorsed by Carnegie Mellon University or its Software Engineering Institute.