[llvm-branch-commits] [clang] [analyzer][docs] Add documentation for the UseAfterLifetimeEnd checker (PR #218272)
Benedek Kaibas via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Wed Aug 26 07:12:17 PDT 2026
https://github.com/benedekaibas updated https://github.com/llvm/llvm-project/pull/218272
>From c9358498e5712cc5d911f5bb50dc5c43167961ee Mon Sep 17 00:00:00 2001
From: benedekaibas <kaibas01 at allegheny.edu>
Date: Sun, 23 Aug 2026 20:22:33 +0200
Subject: [PATCH 1/4] [analyzer][docs] Add documentation for the
UseAfterLifetimeEnd checker
---
clang/docs/analyzer/checkers.md | 59 +++++++++++++++++++++++++++++++++
1 file changed, 59 insertions(+)
diff --git a/clang/docs/analyzer/checkers.md b/clang/docs/analyzer/checkers.md
index 70ceae122f959..7ecb1949233f5 100644
--- a/clang/docs/analyzer/checkers.md
+++ b/clang/docs/analyzer/checkers.md
@@ -3348,6 +3348,65 @@ void test(int x) {
}
```
+(alpha-core-useafterlifetimeend)=
+
+#### alpha.core.UseAfterLifetimeEnd (C, C++)
+
+Check for returned pointers and references that are bound to an object whose
+lifetime ends when the function returns. The checker only analyzes code that
+is annotated with the `[[clang::lifetimebound]]` attribute. The annotation
+tells the checker which object the returned value is bound to.
+
+```cpp
+int *bound(int *p [[clang::lifetimebound]]);
+
+int *direct_return() {
+ int i = 5; // note: 'i' initialized here
+ return bound(&i); // warn: returning value bound to 'i' that will go
+ // out of scope
+}
+```
+
+The attribute states that the returned value may refer to the annotated
+parameter or to the object the function is called on. These are the two
+places where the attribute can be applied.
+
+```cpp
+struct Wrapper {
+ int value;
+ int &get() [[clang::lifetimebound]] { return value; }
+};
+
+int &method_return() {
+ Wrapper w;
+ return w.get(); // warn: returning value bound to 'w' that will go out
+ // of scope
+}
+```
+
+{ref}`core-stackaddressescape` reports returning the address of a local object
+directly. This checker extends that detection through functions that are
+annotated with `[[clang::lifetimebound]]`.
+
+{ref}`alpha-core-danglingptrderef` reports the use of a dangling pointer inside
+a function while this checker reports the returned value at the point where the
+function returns.
+
+{ref}`cplusplus-innerpointer` reports similar errors for inner pointers of C++
+containers that are used after re/deallocation without relying on annotations.
+
+**Limitations**
+
+The checker trusts the annotation, so any incorrect annotation can cause false
+positives.
+
+A dangling pointer that is held by a compound object (a struct field) is not
+tracked, so returning such an object is not reported.
+
+Only objects whose memory region is on the stack are tracked. A returned value
+that is bound to heap-allocated memory is not reported. Interoperability
+between this checker and {ref}`unix-malloc` would address this limitation.
+
(alpha-core-storetoimmutable)=
#### alpha.core.StoreToImmutable (C, C++)
>From d99278ba1be14394bc61c2c482fd9939928aca27 Mon Sep 17 00:00:00 2001
From: benedekaibas <kaibas01 at allegheny.edu>
Date: Sun, 23 Aug 2026 21:12:59 +0200
Subject: [PATCH 2/4] Resolve nits from superseeded PR review.
---
clang/docs/analyzer/checkers.md | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/clang/docs/analyzer/checkers.md b/clang/docs/analyzer/checkers.md
index 7ecb1949233f5..f6e72c776e3fe 100644
--- a/clang/docs/analyzer/checkers.md
+++ b/clang/docs/analyzer/checkers.md
@@ -3367,9 +3367,10 @@ int *direct_return() {
}
```
-The attribute states that the returned value may refer to the annotated
-parameter or to the object the function is called on. These are the two
-places where the attribute can be applied.
+The attribute states that the returned value is dangling after the lifetime
+of the annotated parameter, or of the implicit object argument, has ended.
+Refer to the [documentation](https://clang.llvm.org/docs/AttributeReference.html#lifetimebound)
+of this Clang attribute.
```cpp
struct Wrapper {
@@ -3404,8 +3405,7 @@ A dangling pointer that is held by a compound object (a struct field) is not
tracked, so returning such an object is not reported.
Only objects whose memory region is on the stack are tracked. A returned value
-that is bound to heap-allocated memory is not reported. Interoperability
-between this checker and {ref}`unix-malloc` would address this limitation.
+that is bound to heap-allocated memory is not reported.
(alpha-core-storetoimmutable)=
>From 1341c9dfa315e0c320db168f6963e385c9ffc64b Mon Sep 17 00:00:00 2001
From: Benedek Kaibas <82393336+benedekaibas at users.noreply.github.com>
Date: Wed, 26 Aug 2026 13:57:22 +0200
Subject: [PATCH 3/4] Update clang/docs/analyzer/checkers.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Co-authored-by: Balázs Benics <benicsbalazs at gmail.com>
---
clang/docs/analyzer/checkers.md | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/clang/docs/analyzer/checkers.md b/clang/docs/analyzer/checkers.md
index f6e72c776e3fe..67a05cbafc757 100644
--- a/clang/docs/analyzer/checkers.md
+++ b/clang/docs/analyzer/checkers.md
@@ -3380,8 +3380,7 @@ struct Wrapper {
int &method_return() {
Wrapper w;
- return w.get(); // warn: returning value bound to 'w' that will go out
- // of scope
+ return w.get(); // warn: returning value bound to 'w' that will go out of scope
}
```
>From aff169f255ec2fbe2896a0d523db63994285218d Mon Sep 17 00:00:00 2001
From: benedekaibas <kaibas01 at allegheny.edu>
Date: Wed, 26 Aug 2026 16:08:30 +0200
Subject: [PATCH 4/4] Address review comments
---
clang/docs/analyzer/checkers.md | 29 +++++++++++++++++++++--------
1 file changed, 21 insertions(+), 8 deletions(-)
diff --git a/clang/docs/analyzer/checkers.md b/clang/docs/analyzer/checkers.md
index 67a05cbafc757..b776732ff5ff6 100644
--- a/clang/docs/analyzer/checkers.md
+++ b/clang/docs/analyzer/checkers.md
@@ -3362,8 +3362,7 @@ int *bound(int *p [[clang::lifetimebound]]);
int *direct_return() {
int i = 5; // note: 'i' initialized here
- return bound(&i); // warn: returning value bound to 'i' that will go
- // out of scope
+ return bound(&i); // warn: returning value bound to 'i' that will go out of scope
}
```
@@ -3375,7 +3374,7 @@ of this Clang attribute.
```cpp
struct Wrapper {
int value;
- int &get() [[clang::lifetimebound]] { return value; }
+ int &get() [[clang::lifetimebound]];
};
int &method_return() {
@@ -3384,24 +3383,38 @@ int &method_return() {
}
```
+**Related Checkers**
+
{ref}`core-stackaddressescape` reports returning the address of a local object
directly. This checker extends that detection through functions that are
annotated with `[[clang::lifetimebound]]`.
-{ref}`alpha-core-danglingptrderef` reports the use of a dangling pointer inside
-a function while this checker reports the returned value at the point where the
-function returns.
+{ref}`alpha-core-danglingptrderef` reports use-after-scope errors anywhere in
+the function and does not rely on annotations. This checker reports the value
+that is returned from the function.
{ref}`cplusplus-innerpointer` reports similar errors for inner pointers of C++
containers that are used after re/deallocation without relying on annotations.
+```cpp
+void consume(std::string);
+
+void deref_inner_pointer() {
+ std::string s = "some string";
+ const char *c = s.data();
+ s = "a new string";
+ consume(c); // warn: Inner pointer of container used after re/deallocation
+}
+```
+
**Limitations**
The checker trusts the annotation, so any incorrect annotation can cause false
positives.
-A dangling pointer that is held by a compound object (a struct field) is not
-tracked, so returning such an object is not reported.
+A dangling pointer that is stored in a compound value is never reported
+regardless of how the value is used. This includes struct fields and arrays of
+pointers.
Only objects whose memory region is on the stack are tracked. A returned value
that is bound to heap-allocated memory is not reported.
More information about the llvm-branch-commits
mailing list