https://github.com/NagyDonat created https://github.com/llvm/llvm-project/pull/122749
This commit fixes three issues within the documentation file `Annotations.rst` which was recently created by my earlier commit https://github.com/llvm/llvm-project/pull/122246 . (1) The section title "Annotations to Enhance Generic Checks" is changed to "General Purpose Annotations" because it was a bit too verbose and it used the obsolete name "checks" for what we now call "checkers" in the static analyzer. (2) Several code blocks were missing from the generated html because I accidentally used `.. code-block: c` instead of `.. code-block:: c` and so Sphinx parsed them as comment blocks. (Without printing any error or warning...) (3) The `ownership_*` attributes (which are used by `MallocChecker`) were missing from this document, so I wrote a section that briefly describes them and links to their full documentation. From 098e884885cc3f82eac66b735203610a6e2af01a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Don=C3=A1t=20Nagy?= <donat.n...@ericsson.com> Date: Mon, 13 Jan 2025 18:20:06 +0100 Subject: [PATCH] [NFC][analyzer][docs] Improve Annotations.rst This commit fixes three issues within the documentation file `Annotations.rst` which was recently created by my earlier commit https://github.com/llvm/llvm-project/pull/122246 . (1) The section title "Annotations to Enhance Generic Checks" is changed to "General Purpose Annotations" because it was a bit too verbose and it used the obsolete name "checks" for what we now call "checkers" in the static analyzer. (2) Several code blocks were missing from the generated html because I accidentally used `.. code-block: c` instead of `.. code-block:: c` and so Sphinx parsed them as comment blocks. (Without printing any error or warning...) (3) The `ownership_*` attributes (which are used by `MallocChecker`) were missing from this document, so I wrote a section that briefly describes them and links to their full documentation. --- clang/docs/analyzer/user-docs/Annotations.rst | 51 ++++++++++++++++--- 1 file changed, 43 insertions(+), 8 deletions(-) diff --git a/clang/docs/analyzer/user-docs/Annotations.rst b/clang/docs/analyzer/user-docs/Annotations.rst index d87e8f4df99c31..2ed609d3594c4f 100644 --- a/clang/docs/analyzer/user-docs/Annotations.rst +++ b/clang/docs/analyzer/user-docs/Annotations.rst @@ -23,8 +23,8 @@ recognized by GCC. Their use can be conditioned using preprocessor macros .. contents:: :local: -Annotations to Enhance Generic Checks -_____________________________________ +General Purpose Annotations +___________________________ Null Pointer Checking ##################### @@ -79,7 +79,7 @@ implemented with a macro, with the macro performing a check for the assertion condition and, when the check fails, calling an assertion handler. For example, consider the following code fragment: -.. code-block: c +.. code-block:: c void foo(int *p) { assert(p != NULL); @@ -87,7 +87,7 @@ example, consider the following code fragment: When this code is preprocessed on Mac OS X it expands to the following: -.. code-block: c +.. code-block:: c void foo(int *p) { (__builtin_expect(!(p != NULL), 0) ? __assert_rtn(__func__, "t.c", 4, "p != NULL") : (void)0); @@ -131,7 +131,7 @@ return. On Mac OS X, the function prototype for ``__assert_rtn`` (declared in ``assert.h``) is specifically annotated with the 'noreturn' attribute: -.. code-block: c +.. code-block:: c void __assert_rtn(const char *, const char *, int, const char *) __attribute__((__noreturn__)); @@ -151,7 +151,7 @@ the use of preprocessor macros. **Example** -.. code-block: c +.. code-block:: c #ifndef CLANG_ANALYZER_NORETURN #if __has_feature(attribute_analyzer_noreturn) @@ -163,6 +163,42 @@ the use of preprocessor macros. void my_assert_rtn(const char *, const char *, int, const char *) CLANG_ANALYZER_NORETURN; +Dynamic Memory Modeling Annotations +################################### + +If a project uses custom functions for dynamic memory management (that e.g. act as wrappers around ``malloc``/``free`` or ``new``/``delete`` in C++) and the analyzer cannot "see" the _definitions_ of these functions, it's possible to annotate their declarations to let the analyzer model their behavior. (Otherwise the analyzer cannot know that the opaque ``my_free()`` is basically equivalent to a standard ``free()`` call.) + +**This page only provides a brief list of these annotations.** For a full documentation, see the main `Attributes in Clang <../../AttributeReference.html#ownership-holds-ownership-returns-ownership-takes-clang-static-analyzer>`_ page. + +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``). + +.. code-block:: c + + void __attribute((ownership_returns(malloc))) *my_malloc(size_t); + +Attribute 'ownership_takes' (Clang-specific) +-------------------------------------------- + +Use this attribute to mark functions that deallocate memory. Takes two arguments: the type of the allocation (e.g. ``malloc`` or ``new``) and the index of the parameter that is being deallocated (counting from 1). + +.. code-block:: c + + void __attribute((ownership_takes(malloc, 1))) my_free(void *); + +Attribute 'ownership_holds' (Clang-specific) +-------------------------------------------- + +Use this attribute to mark functions that take ownership of memory and will deallocate it at some unspecified point in the future. Takes two arguments: the type of the allocation (e.g. ``malloc`` or ``new``) and the index of the parameter that is being held (counting from 1). + +.. code-block:: c + + void __attribute((ownership_holds(malloc, 2))) store_in_table(int key, record_t *val); + +The annotations ``ownership_takes`` and ``ownership_holds`` both prevent memory leak reports (concerning the specified argument); the difference between them is that using taken memory is a use-after-free error, while using held memory is assumed to be legitimate. + Mac OS X API Annotations ________________________ @@ -207,7 +243,7 @@ functions allows the analyzer to perform extra checking. **Example** -.. code-block: objc +.. code-block:: objc #import <Foundation/Foundation.h>; @@ -597,7 +633,6 @@ returned object. LIBKERN_RETURNS_NOT_RETAINED OSObject *myFieldGetter(); } - // Note that the annotation only has to be applied to the function declaration. OSObject * MyClass::myFieldGetter() { return f; _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
