[llvm-branch-commits] [clang] [analyzer][docs] Add documentation for the UseAfterLifetimeEnd checker (PR #218272)

[via llvm-branch-commits]

llvmorg-github-actions[bot] wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-clang

Author: Benedek Kaibas (benedekaibas)

<details>
<summary>Changes</summary>

In order to move the UseAfterLifetimeEnd checker out of alpha it needs a documentation the user can get information from. This PR added the documentation for the checker. Currently the documentation sits in the alpha.core category, but once we move the checker out of alpha stage it should be changed as well.

This PR is stacked on #<!-- -->216739.

---

<sub>Stack created with <a href="https://github.com/github/gh-stack">GitHub Stacks CLI</a> • <a href="https://gh.io/stacks-feedback">Give Feedback 💬</a></sub>

---
Full diff: https://github.com/llvm/llvm-project/pull/218272.diff


1 Files Affected:

- (modified) clang/docs/analyzer/checkers.md (+59) 


``````````diff
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++)

``````````

</details>


https://github.com/llvm/llvm-project/pull/218272