1//===- EnumCastOutOfRangeChecker.cpp ---------------------------*- C++ -*--===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// The EnumCastOutOfRangeChecker is responsible for checking integer to
10// enumeration casts that could result in undefined values. This could happen
11// if the value that we cast from is out of the value range of the enumeration.
12// Reference:
13// [ISO/IEC 14882-2014] ISO/IEC 14882-2014.
14// Programming Languages — C++, Fourth Edition. 2014.
15// C++ Standard, [dcl.enum], in paragraph 8, which defines the range of an enum
16// C++ Standard, [expr.static.cast], paragraph 10, which defines the behaviour
17// of casting an integer value that is out of range
18// SEI CERT C++ Coding Standard, INT50-CPP. Do not cast to an out-of-range
19// enumeration value
20//===----------------------------------------------------------------------===//
21
22#include "clang/StaticAnalyzer/Checkers/BuiltinCheckerRegistration.h"
23#include "clang/StaticAnalyzer/Core/BugReporter/BugType.h"
24#include "clang/StaticAnalyzer/Core/PathSensitive/CheckerContext.h"
25#include "llvm/Support/FormatVariadic.h"
26#include <optional>
27
28using namespace clang;
29using namespace ento;
30using llvm::formatv;
31
32namespace {
33// This evaluator checks two SVals for equality. The first SVal is provided via
34// the constructor, the second is the parameter of the overloaded () operator.
35// It uses the in-built ConstraintManager to resolve the equlity to possible or
36// not possible ProgramStates.
37class ConstraintBasedEQEvaluator {
38 const DefinedOrUnknownSVal CompareValue;
39 const ProgramStateRef PS;
40 SValBuilder &SVB;
41
42public:
43 ConstraintBasedEQEvaluator(CheckerContext &C,
44 const DefinedOrUnknownSVal CompareValue)
45 : CompareValue(CompareValue), PS(C.getState()), SVB(C.getSValBuilder()) {}
46
47 bool operator()(const llvm::APSInt &EnumDeclInitValue) {
48 DefinedOrUnknownSVal EnumDeclValue = SVB.makeIntVal(integer: EnumDeclInitValue);
49 DefinedOrUnknownSVal ElemEqualsValueToCast =
50 SVB.evalEQ(state: PS, lhs: EnumDeclValue, rhs: CompareValue);
51
52 return static_cast<bool>(PS->assume(Cond: ElemEqualsValueToCast, Assumption: true));
53 }
54};
55
56// This checker checks CastExpr statements.
57// If the value provided to the cast is one of the values the enumeration can
58// represent, the said value matches the enumeration. If the checker can
59// establish the impossibility of matching it gives a warning.
60// Being conservative, it does not warn if there is slight possibility the
61// value can be matching.
62class EnumCastOutOfRangeChecker : public Checker<check::PreStmt<CastExpr>> {
63 const BugType EnumValueCastOutOfRange{this, "Enum cast out of range"};
64 void reportWarning(CheckerContext &C, const CastExpr *CE,
65 const EnumDecl *E) const;
66
67public:
68 void checkPreStmt(const CastExpr *CE, CheckerContext &C) const;
69};
70
71using EnumValueVector = llvm::SmallVector<llvm::APSInt, 6>;
72
73// Collects all of the values an enum can represent (as SVals).
74EnumValueVector getDeclValuesForEnum(const EnumDecl *ED) {
75 EnumValueVector DeclValues(
76 std::distance(first: ED->enumerator_begin(), last: ED->enumerator_end()));
77 llvm::transform(Range: ED->enumerators(), d_first: DeclValues.begin(),
78 F: [](const EnumConstantDecl *D) { return D->getInitVal(); });
79 return DeclValues;
80}
81} // namespace
82
83void EnumCastOutOfRangeChecker::reportWarning(CheckerContext &C,
84 const CastExpr *CE,
85 const EnumDecl *E) const {
86 assert(E && "valid EnumDecl* is expected");
87 if (const ExplodedNode *N = C.generateNonFatalErrorNode()) {
88 std::string ValueStr = "", NameStr = "the enum";
89
90 // Try to add details to the message:
91 const auto ConcreteValue =
92 C.getSVal(S: CE->getSubExpr()).getAs<nonloc::ConcreteInt>();
93 if (ConcreteValue) {
94 ValueStr = formatv(Fmt: " '{0}'", Vals: ConcreteValue->getValue());
95 }
96 if (StringRef EnumName{E->getName()}; !EnumName.empty()) {
97 NameStr = formatv(Fmt: "'{0}'", Vals&: EnumName);
98 }
99
100 std::string Msg = formatv(Fmt: "The value{0} provided to the cast expression is "
101 "not in the valid range of values for {1}",
102 Vals&: ValueStr, Vals&: NameStr);
103
104 auto BR = std::make_unique<PathSensitiveBugReport>(args: EnumValueCastOutOfRange,
105 args&: Msg, args&: N);
106 bugreporter::trackExpressionValue(N, E: CE->getSubExpr(), R&: *BR);
107 BR->addNote(Msg: "enum declared here",
108 Pos: PathDiagnosticLocation::create(D: E, SM: C.getSourceManager()),
109 Ranges: {E->getSourceRange()});
110 C.emitReport(R: std::move(BR));
111 }
112}
113
114void EnumCastOutOfRangeChecker::checkPreStmt(const CastExpr *CE,
115 CheckerContext &C) const {
116
117 // Only perform enum range check on casts where such checks are valid. For
118 // all other cast kinds (where enum range checks are unnecessary or invalid),
119 // just return immediately. TODO: The set of casts allowed for enum range
120 // checking may be incomplete. Better to add a missing cast kind to enable a
121 // missing check than to generate false negatives and have to remove those
122 // later.
123 switch (CE->getCastKind()) {
124 case CK_IntegralCast:
125 break;
126
127 default:
128 return;
129 break;
130 }
131
132 // Get the value of the expression to cast.
133 const std::optional<DefinedOrUnknownSVal> ValueToCast =
134 C.getSVal(S: CE->getSubExpr()).getAs<DefinedOrUnknownSVal>();
135
136 // If the value cannot be reasoned about (not even a DefinedOrUnknownSVal),
137 // don't analyze further.
138 if (!ValueToCast)
139 return;
140
141 const QualType T = CE->getType();
142 // Check whether the cast type is an enum.
143 if (!T->isEnumeralType())
144 return;
145
146 // If the cast is an enum, get its declaration.
147 // If the isEnumeralType() returned true, then the declaration must exist
148 // even if it is a stub declaration. It is up to the getDeclValuesForEnum()
149 // function to handle this.
150 const EnumDecl *ED = T->castAs<EnumType>()->getDecl();
151
152 EnumValueVector DeclValues = getDeclValuesForEnum(ED);
153
154 // If the declarator list is empty, bail out.
155 // Every initialization an enum with a fixed underlying type but without any
156 // enumerators would produce a warning if we were to continue at this point.
157 // The most notable example is std::byte in the C++17 standard library.
158 // TODO: Create heuristics to bail out when the enum type is intended to be
159 // used to store combinations of flag values (to mitigate the limitation
160 // described in the docs).
161 if (DeclValues.size() == 0)
162 return;
163
164 // Check if any of the enum values possibly match.
165 bool PossibleValueMatch =
166 llvm::any_of(Range&: DeclValues, P: ConstraintBasedEQEvaluator(C, *ValueToCast));
167
168 // If there is no value that can possibly match any of the enum values, then
169 // warn.
170 if (!PossibleValueMatch)
171 reportWarning(C, CE, E: ED);
172}
173
174void ento::registerEnumCastOutOfRangeChecker(CheckerManager &mgr) {
175 mgr.registerChecker<EnumCastOutOfRangeChecker>();
176}
177
178bool ento::shouldRegisterEnumCastOutOfRangeChecker(const CheckerManager &mgr) {
179 return true;
180}
181