https://github.com/steakhal created https://github.com/llvm/llvm-project/pull/191005
The 2 parameter use of this attribute wasn't documented. This clarification is based of the following two commits: - https://github.com/llvm/llvm-project/commit/d21139a34f51 - https://github.com/llvm/llvm-project/commit/893a303962608 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] [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 *); _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
