================ @@ -0,0 +1,600 @@ +======================== +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 exclusivity enforcement (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. 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. + +.. note:: + This analysis is designed for bug finding, not verification. It may miss some + lifetime issues and can produce false positives. It does not guarantee the + +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``. The lifetime of ``s`` ends at the end of +the inner block, causing ``v`` to become 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. + +.. code-block:: bash + + clang -c -Wlifetime-safety-permissive example.cpp + +This flag enables a core set of lifetime safety checks. For more fine-grained +control over warnings, see :ref:`warning_flags`. + +Lifetime Annotations +==================== + +While lifetime analysis can detect many issues without annotations, its +precision increases significantly when types and functions are annotated with +lifetime contracts. These annotations clarify ownership semantics and lifetime +dependencies, enabling the analysis to reason more accurately about pointer +validity across function calls. + +Owner and Pointer Types +----------------------- + +Lifetime analysis distinguishes between types that own the data they point to +(Owners) and types that are non-owning views or references to data owned by +others (Pointers). This distinction is made using GSL-style attributes: + +* ``[[gsl::Owner]]``: For types that manage the lifetime of a resource, + like ``std::string``, ``std::vector``, ``std::unique_ptr``. +* ``[[gsl::Pointer]]``: For non-owning types that borrow resources, + like ``std::string_view``, or raw pointers (which are + implicitly treated as pointers). + +Many common STL types, such as ``std::string_view`` and container iterators, ---------------- Xazax-hun wrote:
I think one guidance people might want/need is how to annotate types that are mixed, e.g., own some data and also behave as views for some other members. Also what to do about types when they have multiple view fields with different lifetimes. I wonder if we should just say that we do not recommend annotating those types for now? Maybe mention named lifetimes as a potential future direction? https://github.com/llvm/llvm-project/pull/183058 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
