package clang.tidy.nullability

Get desktop application:
View/edit binary Protocol Buffers messages

Used in: NullabilityBehaviorSummary

• optional FormulaProto first_is_null = 1

• optional string first_loc = 2

• optional FormulaProto second_is_null = 3

• optional string second_loc = 4

Encodes properties of an assignment relevant to collecting evidence for the assignment's LHS; that is, the assignee.

Used in: NullabilityBehaviorSummary

• optional PointerTypeNullabilityProto lhs_type_nullability = 1

• optional PointerNullStateProto rhs_null_state = 2

  Genuinely optional: not populated when RHS is a nullptr literal.

• optional string rhs_loc = 3

• optional Evidence.Kind evidence_kind = 4

Covers argument binding and "binding" to the returned value.

Used in: NullabilityBehaviorSummary

• optional Symbol function_symbol = 1

• optional uint32 slot = 2

• optional bool type_is_lvalue_ref = 3

  Whether the type is: a) a reference, and ...

• optional bool type_is_const = 4

  b) const, after stripping any reference qualifier.

• optional PointerNullStateProto null_state = 5

  Genuinely optional: not populated when the value is a nullptr literal.

• optional string location = 6

Summarizes Nullability-relevant "behaviors" and relevant context from a CFG.

Used in: TUSummary

• repeated InferableSlotProto inferable_slots = 1

• optional LogicalContext logical_context = 2

• repeated NullabilityBehaviorSummary behavior_summaries = 3

An observation of nullability based on local analysis (e.g. a function body). Evidence from across different functions/TUs is combined to form conclusions.

Used in: SlotInference, SlotPartial.SampleEvidence

• optional Symbol symbol = 1

• optional uint32 slot = 2

• optional Evidence.Kind kind = 3

• optional string location = 4

  Source location: file:line:col. Optional, for debugging only.

• optional Symbol propagated_from = 5

  If set, this evidence was originally collected from the virtual or override function identified by this symbol and propagated to `symbol`.

A pattern in the code that might help us determine nullability.

Used in: AssignmentFromValueSummary, Evidence, RequiresAnnotationSummary

• ANNOTATED_UNKNOWN = 0

  The declaration was annotated with _Null_unspecified or similar.

• ANNOTATED_NULLABLE = 1

  The declaration was annotated with _Nullable or similar.

• ANNOTATED_NONNULL = 2

  The declaration was annotated with _Nonnull or similar.

• UNCHECKED_DEREFERENCE = 3

  A pointer was dereferenced without being checked for null first.

• NULLABLE_ARGUMENT = 4

  A Nullable value was passed as an argument.

• NONNULL_ARGUMENT = 5

  A Nonnull value was passed as an argument.

• UNKNOWN_ARGUMENT = 6

  A value with Unknown nullability was passed as an argument.

• NULLABLE_RETURN = 7

  A Nullable value was returned.

• NONNULL_RETURN = 8

  A Nonnull value was returned.

• UNKNOWN_RETURN = 9

  A value with Unknown nullability was returned.

• ASSIGNED_TO_NONNULL = 10

  A value was assigned to a Nonnull declaration. e.g. evidence for `p` from `int* _Nonnull q = p;`.

• ASSIGNED_TO_MUTABLE_NULLABLE = 11

  A value was assigned to a declaration that is a reference to a mutable nullable pointer, e.g. evidence for `p` from `int* _Nullable& q = p;`.

• ABORT_IF_NULL = 12

  The program aborts if a value is null.

• ASSIGNED_FROM_NULLABLE = 13

  A nullable value was assigned. e.g. evidence for `p` from `int* p = nullptr;`.

• ARITHMETIC = 14

  A pointer was used with an arithmetic operator without being checked for null first.

• NULLPTR_DEFAULT_MEMBER_INITIALIZER = 15

  A non-static member variable has a default initializer that is a literal nullptr or is simply constructed from a literal nullptr. This is considered to be a weaker signal than other assignments to nullable, due to the common use of nullptr as a default value to avoid quieter uninitialized memory errors in favor of loud segfaults, so we differentiate the evidence. Default initializers that are nullable but not using literal nullptrs use the stronger evidence ASSIGNED_TO_NULLABLE, as they likely indicate more explicit Nullable intent.

• GCC_NONNULL_ATTRIBUTE = 16

  __attribute((nonnull[(optional_param_indices)])) was applied to a function or parameter declaration or __attribute((returns_nonnull)) was applied to a function declaration.

• NULLABLE_REFERENCE_RETURN = 17

  A Nullable value was returned as a reference.

• NONNULL_REFERENCE_RETURN = 18

  A Nonnull value was returned as a mutable reference.

• UNKNOWN_REFERENCE_RETURN = 19

  A value with Unknown nullability was returned as a reference.

• NULLABLE_REFERENCE_ARGUMENT = 20

  A Nullable value was passed as a reference argument.

• NONNULL_REFERENCE_ARGUMENT = 21

  A Nonnull value was passed as a mutable reference argument.

• UNKNOWN_REFERENCE_ARGUMENT = 22

  A value with Unknown nullability was passed as a reference argument.

• ASSIGNED_FROM_NONNULL = 23

  A nonnull value was assigned. e.g. evidence for `p` from `int a; int* p = &a;`.

• ASSIGNED_FROM_UNKNOWN = 24

  An unknown value was assigned. e.g. evidence for `p` from `int* p = getUnknownPtr();`.

• ASSIGNED_TO_NONNULL_REFERENCE = 26

  A value was bound to a reference to a nonnull pointer, regardless of whether the pointer can be mutated through the reference. If any Nonnull reference exists, the pointer must be declared Nonnull to prevent the pointer from being directly, or through a different reference, assigned to null and then accessed through the Nonnull reference unsafely. e.g. evidence for `p` from `int* _Nonnull&q = p;`.

• NONNULL_REFERENCE_RETURN_AS_CONST = 27

  A reference to a nonnull value was returned as a reference to a const value. This is distinct from NONNULL_REFERENCE_RETURN because it does not require that the return type is Nonnull, the way returning a reference to a mutable nonnull value does.

• NONNULL_REFERENCE_ARGUMENT_AS_CONST = 28

  A reference to a nonnull value was passed as an argument to a const reference parameter. This is distinct from NONNULL_REFERENCE_ARGUMENT because it does not require that the argument type is Nonnull, the way passing a reference to a mutable nonnull value does.

• WELL_KNOWN_NONNULL = 29

  A decl that is defined by the standard or strong convention to be Nonnull.

• WELL_KNOWN_NULLABLE = 30

  A decl that is defined by the standard or strong convention to be Nullable.

• ARRAY_SUBSCRIPT = 31

  A pointer was used with an array subscript operator without being checked for null first.

• LEFT_NOT_NULLABLE_BY_LATE_INITIALIZER = 32

  A smart pointer field was left not-nullable in the exit block of a supported late initializer method.

• LEFT_NULLABLE_BY_CONSTRUCTOR = 33

  A smart pointer field was left default-initialized (to null) or initialized to a nullable value in the exit block of a constructor.

Covers behaviors learned specifically from particular function exit blocks -- constructors and (late) initializers.

Used in: NullabilityBehaviorSummary

• repeated InitOnExitSummary ctor_inits_on_exit = 2

• repeated InitOnExitSummary late_inits_on_exit = 3

Encodes type Formula.

Used in: AbortIfEqualSummary, LogicalContext, PointerNullStateProto, RequiresAnnotationSummary

• optional string serialized = 1

  A compact serialization of a formula. Serialization and deserialization (parsing) is handled by the dataflow framework. The grammar is: bool ::= "F" (false) | "T" (true) atom ::= "V" n (n is a positive integer) op ::= "&" (and) | "|" (or) | ">" (implication) | "=" (equality) F ::= bool | atom | "!" F | op F1 F2 The corresponding serialization/deserialization API is https://github.com/llvm/llvm-project/blob/main/clang/include/clang/Analysis/FlowSensitive/FormulaSerialization.h

Used in: CFGSummary

• optional uint32 nonnull_atom = 1

• optional uint32 nullable_atom = 2

• optional uint32 slot = 3

• optional Symbol symbol = 4

For initialization functions -- constructors and "late" initializers -- we collect the state of fields at function exit. We may judge the nullability of the field based on this exit state rather than strictly on initial state.

Used in: ExitBlockSummary

• optional Symbol field = 1

• optional PointerNullStateProto null_state = 2

• optional string location = 3

The logical context for a function definition.

Used in: CFGSummary

• optional FormulaProto invariant = 1

  optional, string-encoded formula providing an invariant across all formulas represented in this logical context.

• map<uint32, FormulaProto> atom_defs = 2

  Int-encoded atoms and their definitions as formulas.

• map<uint32, LogicalContext.AtomSet> atom_deps = 3

  The dependencies of the atoms used in the function. The key is the atom, and the value is the set of atoms that the key atom depends on.

Used in: LogicalContext

• repeated uint32 atoms = 1

Used in: PointerTypeNullabilityProto, RequiresAnnotationSummary, SlotInference, SlotRange

• UNKNOWN = 0

• NONNULL = 1

• NULLABLE = 2

Used in: CFGSummary

• optional uint32 block_atom = 8

  The numerical ID of the atom representing the flow condition (aka. flow condition token) of the block from which this behavior was summarized.

• oneof behavior

  • RequiresAnnotationSummary requires_annotation = 1

  • ValueAssignedToTypeSummary value_assigned = 2

  • AssignmentFromValueSummary assignment_from_value = 3

  • BindingSummary argument_binding = 4

  • AbortIfEqualSummary abort_if_equal = 5

  • BindingSummary returned = 6

  • ExitBlockSummary on_exit = 7

Encodes type PointerNullState.

Used in: AssignmentFromValueSummary, BindingSummary, InitOnExitSummary, ValueAssignedToTypeSummary

• optional FormulaProto from_nullable = 1

  Both fields are optional.

• optional FormulaProto is_null = 2

Encodes type PointerTypeNullability.

Used in: AssignmentFromValueSummary, ValueAssignedToTypeSummary

• oneof nullability

  • Nullability concrete = 1

  • PointerTypeNullabilityProto.SymbolicNullability symbolic = 2

Used in: PointerTypeNullabilityProto

• optional uint32 nonnull_atom = 1

• optional uint32 nullable_atom = 2

A generic serialization format for a relation between symbols. Currently, used as for the `RelatedVirtualMethodsMap` type. TODO: b/440317964 - design a compact representation. For example, we could represent Symbols by integers, and separately maintain a map from integers to USRs.

Used in: TUSummary

• map<string, RelatedSymbols.SymbolSet> related_symbols = 1

  Since map keys cannot be message fields, we use strings directly for the key. These must be USRs.

Used in: RelatedSymbols

• repeated Symbol symbols = 1

A half-open source range to be removed: [begin, end).

Used in: SlotRange

• optional uint64 begin = 1

• optional uint64 end = 2

Encodes a potential requirement for an annotation, specifically -- when `formula` is true in the surrounding context.

Used in: NullabilityBehaviorSummary

• optional Nullability required_annotation = 1

  In practice, only Nonnull or Nullable make sense for this field.

• optional FormulaProto formula = 2

• optional string location = 3

• optional Evidence.Kind evidence_kind = 4

A "slot" identifies a position in a symbol's type that may have nullability. We use uint32 rather than the Slot type to represent slot numbers in protos. (A symbol may have any number of slots, and proto2 enums are closed). The Slot enum only defines well-known slot values for functions. Fields and global variables use Slot numbers aligned with the indices of their nullability vectors.

• SLOT_RETURN_TYPE = 0

  The slot number for a function's return type.

• SLOT_PARAM = 1

  The slot number for a function's first parameter. The second param is SLOT_PARAM + 1, etc.

A conclusion about nullability based on global analysis (e.g. all TUs).

• optional Nullability nullability = 1

• optional bool conflict = 2

  Indicates that not we could not reconcile all evidence into a conclusion. e.g. a decl that was both unconditionally dereferenced and assigned null.

• repeated Evidence sample_evidence = 3

  Examples of evidence that contributed. Optional, for debugging only.

• optional bool trivial = 4

  Indicates that this inference does not represent new information beyond what is explicitly written in the source code, and so does not need to be separately propagated from one round of inference into the next. e.g. an inference gathered from ANNOTATED_NONNULL Evidence.

• repeated string slot_id = 5

  Slot identifiers for which this inference is applicable. Used only for debugging information.

Summary of an incomplete set of Evidence for a slot. Once all evidence has been incorporated, can be finalized into SlotInference. This type should be treated as opaque, and its serialization is not stable.

• map<uint32, uint32> kind_count = 1

• map<uint32, SlotPartial.SampleEvidence> kind_samples = 2

• repeated string slot_id = 3

  Slot identifiers for which this partial is relevant. Used only for debugging information.

Used in: SlotPartial

• repeated Evidence evidence = 1

  A bounded number of evidence pieces are stored.

Nullability information for a pointer-type source range. Does not include the full source range for the type, as that isn't needed for adding/removing nullability annotations.

• optional string path = 1

  Path of the file containing this range.

• optional Nullability pragma_nullability = 2

  The nullability default set by the pragma affecting `path`, if one exists.

• optional uint64 qualifier_annotation_insertion_offset = 3

  The offset at which a qualifier-position annotation should be inserted. For a named pointer type not ending with `*`, including smart pointers and aliases to raw pointers, this precedes the type but follows any cv-qualifiers. For other pointers, this follows the `*` but precedes any cv-qualifiers. This field uniquely identifies a pointer-type slot range within a file, as no two pointer ranges can be annotated with a qualifier-positioned annotation in the same location.

• optional Nullability existing_annotation = 4

• repeated RemovalRange existing_annotation_removal_range = 5

  The source ranges of existing annotations to be removed if modifying the annotation for this range.

A symbol whose nullability should potentially be inferred.

Used in: BindingSummary, Evidence, InferableSlotProto, InitOnExitSummary, RelatedSymbols.SymbolSet

• optional string usr = 1

  Clang "Unified Symbol Resolution" identifier for the symbol.

A summary for a whole translation unit.

• repeated CFGSummary cfg_summaries = 1

• optional RelatedSymbols overrides_to_bases = 2

• optional string path = 3

  Information about the TU that could be useful for debug logs.

Encodes properties of an assignment relevant to collecting evidence for the assignment's RHS.

Used in: NullabilityBehaviorSummary

• optional bool lhs_is_non_reference_const = 1

• optional PointerTypeNullabilityProto lhs_type_nullability = 2

• optional uint64 lhs_decl_fingerprint = 3

  optional. When a decl is available for the LHS, lhs_type_nullability may be overridden during inference. `fingerprint` identifies this decl. When populated, the fingerprint should be checked for an override.

• optional PointerTypeNullabilityProto rhs_type_nullability = 4

  This field is genuinely optional and should be provided only if the LHS has reference type.

• optional PointerNullStateProto rhs_value_nullability = 5

• optional string rhs_loc = 6