https://github.com/steakhal updated https://github.com/llvm/llvm-project/pull/191005
From 07dc9e9666cd3bbf78401c751509adfbff2ceac8 Mon Sep 17 00:00:00 2001 From: Balazs Benics <[email protected]> Date: Wed, 8 Apr 2026 17:17:23 +0100 Subject: [PATCH 1/4] [clang][docs] Improve documentation of [[ownership_returns]] attribute The 2 parameter use of this attribute wasn't documented. --- clang/docs/analyzer/user-docs/Annotations.rst | 11 ++++++++++- clang/include/clang/Basic/AttrDocs.td | 14 ++++++++++++-- 2 files changed, 22 insertions(+), 3 deletions(-) diff --git a/clang/docs/analyzer/user-docs/Annotations.rst b/clang/docs/analyzer/user-docs/Annotations.rst index 11f15939ecfaf..5439aeba2c1d4 100644 --- a/clang/docs/analyzer/user-docs/Annotations.rst +++ b/clang/docs/analyzer/user-docs/Annotations.rst @@ -174,12 +174,21 @@ If a project uses custom functions for dynamic memory management (that e.g. act Attribute 'ownership_returns' (Clang-specific) ---------------------------------------------- -Use this attribute to mark functions that return dynamically allocated memory. Takes a single argument, the type of the allocation (e.g. ``malloc`` or ``new``). +Use this attribute to mark functions that return dynamically allocated memory. +The first argument is the type of the allocation (e.g. ``malloc``, ``new``, or any other identifier). +An optional second argument is the 1-based index of the function parameter that specifies the allocation size in bytes. +The referenced parameter must have an integral type. + +This attribute may appear at most once per function declaration. .. code-block:: c + // Without size parameter: void __attribute((ownership_returns(malloc))) *my_malloc(size_t); + // With size parameter (parameter 1 is the allocation size in bytes): + void __attribute((ownership_returns(malloc, 1))) *my_sized_malloc(size_t sz); + Attribute 'ownership_takes' (Clang-specific) -------------------------------------------- diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td index 2ffbecfc2366b..3e6db7ca99eb2 100644 --- a/clang/include/clang/Basic/AttrDocs.td +++ b/clang/include/clang/Basic/AttrDocs.td @@ -1639,8 +1639,15 @@ the Clang Static Analyzer makes sure that allocating functions annotated with ``malloc`` are treated like they used the standard ``malloc()``, and can be safely deallocated with the standard ``free()``. -* Use ``ownership_returns`` to mark a function as an allocating function. Takes - 1 parameter to denote the allocation type. +* Use ``ownership_returns`` to mark a function as an allocating function. + It takes 1 or 2 parameters. + The first parameter is a user-provided identifier representing the "kind" of the allocation. + This is basically what is enforced when checking the deallocation. + The second parameter is optional. + It represents the index of the parameter that represents the allocation size in bytes (counting from 1). + The referenced parameter must have some integral type. + This attribute may appear at most once per declaration; + If forward declarations have this attribute, those must have the same parameters. * Use ``ownership_takes`` to mark a function as a deallocating function. Takes 2 parameters: the allocation type, and the index of the parameter that is being deallocated (counting from 1). @@ -1662,6 +1669,9 @@ Example: // memory using malloc(). void __attribute((ownership_returns(malloc))) *my_malloc(size_t); + // 'sz' (parameter 1) is the allocation size. + void __attribute((ownership_returns(malloc, 1))) *my_sized_malloc(size_t sz); + // Denotes that my_free will deallocate its parameter using free(). void __attribute((ownership_takes(malloc, 1))) my_free(void *); From 753270be8cf90672af4e9b3256aa16153c66bed5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Benics?= <[email protected]> Date: Wed, 8 Apr 2026 17:59:03 +0100 Subject: [PATCH 2/4] Add param name in example --- clang/docs/analyzer/user-docs/Annotations.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/clang/docs/analyzer/user-docs/Annotations.rst b/clang/docs/analyzer/user-docs/Annotations.rst index 5439aeba2c1d4..47abbe48bc7ab 100644 --- a/clang/docs/analyzer/user-docs/Annotations.rst +++ b/clang/docs/analyzer/user-docs/Annotations.rst @@ -184,7 +184,7 @@ This attribute may appear at most once per function declaration. .. code-block:: c // Without size parameter: - void __attribute((ownership_returns(malloc))) *my_malloc(size_t); + void __attribute((ownership_returns(malloc))) *my_malloc(size_t sz); // With size parameter (parameter 1 is the allocation size in bytes): void __attribute((ownership_returns(malloc, 1))) *my_sized_malloc(size_t sz); From bb6cf3944938e5638f92c1570a6c8aa1ac0c91f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Benics?= <[email protected]> Date: Wed, 8 Apr 2026 18:00:06 +0100 Subject: [PATCH 3/4] Use full-stop instead of semicolon MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Donát Nagy <[email protected]> --- clang/include/clang/Basic/AttrDocs.td | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td index 3e6db7ca99eb2..65db3e59fb24d 100644 --- a/clang/include/clang/Basic/AttrDocs.td +++ b/clang/include/clang/Basic/AttrDocs.td @@ -1646,7 +1646,7 @@ safely deallocated with the standard ``free()``. The second parameter is optional. It represents the index of the parameter that represents the allocation size in bytes (counting from 1). The referenced parameter must have some integral type. - This attribute may appear at most once per declaration; + This attribute may appear at most once per declaration. If forward declarations have this attribute, those must have the same parameters. * Use ``ownership_takes`` to mark a function as a deallocating function. Takes 2 parameters: the allocation type, and the index of the parameter that is being From b13e25327e143eafb934d89083a3253e43b436c1 Mon Sep 17 00:00:00 2001 From: Balazs Benics <[email protected]> Date: Wed, 8 Apr 2026 19:53:31 +0100 Subject: [PATCH 4/4] Add remaining param name in docs --- clang/include/clang/Basic/AttrDocs.td | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td index 65db3e59fb24d..3e93142186750 100644 --- a/clang/include/clang/Basic/AttrDocs.td +++ b/clang/include/clang/Basic/AttrDocs.td @@ -1667,7 +1667,7 @@ Example: // Denotes that my_malloc will return with a dynamically allocated piece of // memory using malloc(). - void __attribute((ownership_returns(malloc))) *my_malloc(size_t); + void __attribute((ownership_returns(malloc))) *my_malloc(size_t sz); // 'sz' (parameter 1) is the allocation size. void __attribute((ownership_returns(malloc, 1))) *my_sized_malloc(size_t sz); _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
