CertC++-CTR54

Do not subtract iterators that do not refer to the same container

Required inputs: IR, StaticSemanticAnalysis

When two pointers are subtracted, both must point to elements of the same array object or to one past the last element of the array object; the result is the difference of the subscripts of the two array elements. Similarly, when two iterators are subtracted (including via std::distance()), both iterators must refer to the same container object or must be obtained via a call to  end() (or  cend()) on the same container object.

If two unrelated iterators (including pointers) are subtracted, the operation results in undefined behavior [ ISO/IEC 14882-2014]. Do not subtract two iterators (including pointers) unless both point into the same container or one past the end of the same container.

Noncompliant Code Example

This noncompliant code example attempts to determine whether the pointer  test is within the range  [r, r + n]. However, when  test does not point within the given range, as in this example, the subtraction produces undefined behavior. 

#include <cstddef>
#include <iostream>

template <typename Ty>
bool in_range(const Ty *test, const Ty *r, size_t n) {
  return 0 < (test - r) && (test - r) < (std::ptrdiff_t)n;
}

void f() {
  double foo[10];
  double *x = &foo[0];
  double bar;
  std::cout << std::boolalpha << in_range(&bar, x, 10);
}
Noncompliant Code Example

In this noncompliant code example, the  in_range() function is implemented using a comparison expression instead of subtraction. The C++ Standard, [expr.rel], paragraph 4 [ ISO/IEC 14882-2014], states the following:

If two operands p and q compare equal, p<=q and p>=q both yield true and p<q and p>q both yield  false. Otherwise, if a pointer p compares greater than a pointer q, p>=q, p>q, q<=p, and q<p all yield true and p<=q, p<q, q>=p, and q>p all yield false. Otherwise, the result of each of the operators is unspecified.

Thus, comparing two pointers that do not point into the same container or one past the end of the container results in unspecified behavior. Although the following example is an improvement over the previous noncompliant code example, it does not result in portable code and may fail when executed on a segmented memory architecture (such as some antiquated x86 variants). Consequently, it is noncompliant. 

#include <iostream>

template <typename Ty>
bool in_range(const Ty *test, const Ty *r, size_t n) {
  return test >= r && test < (r + n);
}

void f() {
  double foo[10];
  double *x = &foo[0];
  double bar;
  std::cout << std::boolalpha << in_range(&bar, x, 10);
}
Noncompliant Code Example

This noncompliant code example is roughly equivalent to the previous example, except that it uses iterators in place of raw pointers. As with the previous example, the  in_range_impl() function exhibits  unspecified behavior when the iterators do not refer into the same container because the operational semantics of  a < b on a random access iterator are b - a > 0, and  >= is implemented in terms of  <. 

#include <iostream>
#include <iterator>
#include <vector>

template <typename RandIter>
bool in_range_impl(RandIter test, RandIter r_begin, RandIter r_end, std::random_access_iterator_tag) {
  return test >= r_begin && test < r_end;
}

template <typename Iter>
bool in_range(Iter test, Iter r_begin, Iter r_end) {
  typename std::iterator_traits<Iter>::iterator_category cat;
  return in_range_impl(test, r_begin, r_end, cat);
}

void f() {
  std::vector<double> foo(10);
  std::vector<double> bar(1);
  std::cout << std::boolalpha << in_range(bar.begin(), foo.begin(), foo.end());
}
Noncompliant Code Example

In this noncompliant code example,  std::less<> is used in place of the  < operator. The C++ Standard, [comparisons], paragraph 14 [ ISO/IEC 14882-2014], states the following:

For templates greater, less, greater_equal, and less_equal, the specializations for any pointer type yield a total order, even if the built-in operators <, >, <=, >= do not.

Although this approach yields a total ordering, the definition of that total ordering is still unspecified by the implementation. For instance, the following statement could result in the assertion triggering for a given, unrelated pair of pointers, a and b: assert(std::less<T *>()(a, b) == std::greater<T *>()(a, b));. Consequently, this noncompliant code example is still nonportable and, on common implementations of  std::less<>, may even result in undefined behavior when the  < operator is invoked. 

#include <functional>
#include <iostream>

template <typename Ty>
bool in_range(const Ty *test, const Ty *r, size_t n) {
  std::less<const Ty *> less;
  return !less(test, r) && less(test, r + n);
}

void f() {
  double foo[10];
  double *x = &foo[0];
  double bar;
  std::cout << std::boolalpha << in_range(&bar, x, 10);
}
Compliant Solution

This compliant solution demonstrates a fully portable, but likely inefficient, implementation of in_range() that compares  test against each possible address in the range  [r, n]. A compliant solution that is both efficient and fully portable is currently unknown. 

#include <iostream>

template <typename Ty>
bool in_range(const Ty *test, const Ty *r, size_t n) {
  auto *cur = reinterpret_cast<const unsigned char *>(r);
  auto *end = reinterpret_cast<const unsigned char *>(r + n);
  auto *testPtr = reinterpret_cast<const unsigned char *>(test);

  for (; cur != end; ++cur) {
    if (cur == testPtr) {
      return true;
    }
  }
  return false;
}

void f() {
  double foo[10];
  double *x = &foo[0];
  double bar;
  std::cout << std::boolalpha << in_range(&bar, x, 10);
}
Risk Assessment
Rule Severity Likelihood Remediation Cost Priority Level
CTR54-CPP Medium Probable Medium P8 L2
Related Guidelines
SEI CERT C Coding Standard ARR36-C. Do not subtract or compare two pointers that do not refer to the same array
MITRE CWE CWE-469, Use of Pointer Subtraction to Determine Size
Bibliography
[ Banahan 2003] Section 5.3, "Pointers"
Section 5.7, "Expressions Involving Pointers" 
[ ISO/IEC 14882-2014] Subclause 5.7, "Additive Operators"
Subclause 5.9, "Relational Operators"
Subclause 20.9.5, "Comparisons"
Excerpt from SEI CERT C++ Coding Standard [https://cmu-sei.github.io/secure-coding-standards/sei-cert-cpp-coding-standard/rules/containers-ctr/ctr54-cpp], Copyright (C) 1995-2026 Carnegie Mellon University. See section 9.4. "3rd-Party Licenses" in the documentation for full details.

Possible Messages

Key

Text

Severity

Disabled

possible_unrelated_ptr_comparison

Comparing possibly unrelated pointers

None

False

possible_unrelated_ptr_subtraction

Subtracting possibly unrelated pointers

None

False

unrelated_iterators_comparing_unrelated_iterators

{} unrelated iterators ‘{}’ [{}] ‘{}’.

None

False

unrelated_iterators_iterator_not_initialized

Comparing with an uninitialized iterator ({}) ‘{}’.

None

False

unrelated_ptr_comparison

Comparing unrelated pointers

None

False

unrelated_ptr_subtraction

Subtracting unrelated pointers

None

False

Options

check_non_array_pointers

check_non_array_pointers : bool = False

Whether the check should also consider pointers to non-arrays (e.g., comparison of pointers to different fields). If enabled, a pointer to an object that is not an array is treated as if it were a pointer to the first element of an array with a single element.
 

entry_points

entry_points : set[bauhaus.analysis.config.QualifiedName] = {'main'}

Functions from where the interprocedural scanning starts.
 

max_call_depth

max_call_depth : int = 128

Maximum depth in scanning routines.
 

report_empty_points_to_sets

report_empty_points_to_sets : bool = False

Report cases where one of the pointers involved in the comparison does not point to any value. This can occur e.g. if parameters of entry functions are analyzed, for which no values are known.