llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT--> @llvm/pr-subscribers-clang Author: Balázs Benics (steakhal) <details> <summary>Changes</summary> 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 --- Full diff: https://github.com/llvm/llvm-project/pull/191005.diff 2 Files Affected: - (modified) clang/docs/analyzer/user-docs/Annotations.rst (+10-1) - (modified) clang/include/clang/Basic/AttrDocs.td (+12-2) ``````````diff 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 *); `````````` </details> https://github.com/llvm/llvm-project/pull/191005 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
