================ @@ -0,0 +1,598 @@ +======================== +Lifetime Safety Analysis +======================== + +.. contents:: + :local: + +Introduction +============ + +Clang Lifetime Safety Analysis is a C++ language extension which warns about +potential dangling pointer defects in code. The analysis aims to detect +when a pointer, reference or view type (such as ``std::string_view``) refers to an object +that is no longer alive, a condition that leads to use-after-free bugs and +security vulnerabilities. Common examples include pointers to stack variables +that have gone out of scope, fields holding views to stack-allocated objects +(dangling-field), returning pointers/references to stack variables +(return stack address) or iterators into container elements invalidated by +container operations (e.g., ``std::vector::push_back``) + +The analysis design is inspired by `Polonius, the Rust borrow checker <https://github.com/rust-lang/polonius>`_, +but adapted to C++ idioms and constraints, such as the lack of borrow checker exclusivity (alias-xor-mutability). +Further details on the analysis method can be found in the `RFC on Discourse <https://discourse.llvm.org/t/rfc-intra-procedural-lifetime-analysis-in-clang/86291/>`_. + +This is compile-time analysis; there is no run-time overhead. +It tracks pointer validity through intra-procedural data-flow analysis. While it does +not require lifetime annotations to get started, in their absence, the analysis +treats function calls optimistically, assuming no lifetime effects, thereby potentially missing dangling pointer issues or producing false positives. As more functions are annotated +with attributes like `clang::lifetimebound <https://clang.llvm.org/docs/AttributeReference.html#lifetimebound>`_, `gsl::Owner <https://clang.llvm.org/docs/AttributeReference.html#gsl-owner>`_, and +`gsl::Pointer <https://clang.llvm.org/docs/AttributeReference.html#gsl-pointer>`_, the analysis can see through these lifetime contracts and enforce +lifetime safety at call sites with higher accuracy. This approach supports +gradual adoption in existing codebases. It is still very much under active development, +but it is mature enough to be used in production codebases. + +Getting Started +---------------- + +.. code-block:: c++ + + #include <string> + #include <string_view> + + void simple_dangle() { + std::string_view v; + { + std::string s = "hello"; + v = s; // warning: object whose reference is captured does not live long enough + } // note: destroyed here + std::cout << v; // note: later used here + } + +This example demonstrates +a basic use-after-scope bug. The ``std::string_view`` object ``v`` holds a +reference to ``s``, a ``std::string``. When ``s`` goes out of +scope at the end of the inner block, ``v`` becomes a dangling reference. +The analysis flags the assignment ``v = s`` as defective because ``s`` is +destroyed while ``v`` is still alive and points to ``s``, and adds a note +to where ``v`` is used after ``s`` has been destroyed. + +Running The Analysis +-------------------- + +To run the analysis, compile with the ``-Wlifetime-safety-permissive`` flag, e.g. ---------------- Xazax-hun wrote:
I think this decision should not block this PR, we can always revisit this. I like it when the recommended flag is the shortest and simplest but I do not insist. Especially since recommendations might change over time and maybe the strict version will be more desirable in the future. https://github.com/llvm/llvm-project/pull/183058 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
