You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
|`malloc`| GCC 2.95.3<br/>Clang 13 | Function |Allocator that returns a non-aliased (possibly NULL) pointer. |
32
-
|`malloc (dealloc)`| GCC 11 | Function |Same as above but also associate `dealloc` as the deallocator for this function |
31
+
|`malloc`| GCC 2.95.3<br/>Clang 13 | Function |Mark custom allocation functions that return non-aliased (possibly NULL) pointers.|
32
+
|`malloc (`_`deallocator`_`)`| GCC 11.0.0| Function |Associates _`deallocator`_ as the valid deallocator for the storage allocated by marked function.|
33
33
|`alloc_size(pos)`<br/>`alloc_size(pos-1, pos-2)`| GCC 2.95.3<br/>Clang 4 | Function | Size of the object that the returned pointer points to is at argument `pos` of the function or product of arguments at `pos-1` and `pos-2`. |
34
34
|`access(mode, ref-pos)`<br/>`access(mode, ref-pos, size-pos)`| GCC 10 | Function | Indicate how the function uses argument at `ref-pos`. `mode` could be `read_only`, `read_write`, `write_only` or `none`. `size-pos`, if mentioned, is the argument indicating the size of object at `ref-pos`. |
35
35
|`fd_arg(N)`| GCC 13 | Function | Argument N is an open file descriptor. |
@@ -45,3 +45,42 @@ Attributes influence not only diagnostics generated by the compiler but also the
[^CPP11]: ISO/IEC, [Programming languages — C++ ("C++11")](https://web.archive.org/web/20240112105643/https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3797.pdf), ISO/IEC 14882, 2011. Note: The official ISO/IEC specification is paywalled and therefore not publicly available. The final specification draft is publicly available.
47
47
[^C23]: ISO/IEC, [Programming languages — C ("C23")](https://web.archive.org/web/20240105084047/https://open-std.org/JTC1/SC22/WG14/www/docs/n3096.pdf), ISO/IEC 9899:2023, 2023. Note: The official ISO/IEC specification is not available.
48
+
49
+
---
50
+
51
+
### Mark custom allocation and deallocation functions
52
+
53
+
| Attribute | Supported since | Type | Description |
| <spanid="malloc">`malloc`</span> | GCC 2.95.3<br/>Clang 13.0.0 | Function | Mark custom allocation functions that return non-aliased (possibly NULL) pointers. |
56
+
| <spanid="malloc (dealloc)">`malloc (`_`deallocator`_`)`</span> | GCC 11.0.0 | Function | Associates _`deallocator`_ as the valid deallocator for the storage allocated by marked function. |
57
+
| <spanid="malloc (dealloc, ptr-index)">`malloc (`_`deallocator`_`,`_`ptr-index`_`)`</span> | GCC 11.0.0 | Function | Same as above but also denotes the positional argument here the pointer must be passed. |
58
+
59
+
The `malloc` attribute in GCC and Clang indicates that the function acts like a memory allocation function, meaning it returns a pointer to allocated storage that is disjoint (non-aliased) from the storage for any other object accessible to the caller.
60
+
61
+
Using the attribute with no arguments is designed to allow the compiler to rely on that the returned pointer does not alias any other valid pointers at the time of return and does not contain pointers to existing objects for program optimization. Functions like `malloc` and `calloc` have this property because they return a pointer to uninitialized or zeroed-out, newly obtained storage. However, functions like `realloc` do not have this property, as they may return pointers to storage containing pointers to existing objects. Additionally, GCC uses the `malloc` attribute to infer that the marked function returns null only infrequently, allowing callers to be optimized based on that assumption.
62
+
63
+
In GCC, the `malloc (`_`deallocator`_`)` and `malloc (`_`deallocator`_`,`_`ptr-index`_`)` forms associate the pointer returned by the marked function with the specified _`deallocator`_ function. Here, _`deallocator`_ is a function name that must have been declared before it can be referenced in the attribute and _`ptr-index`_ denotes the positional argument to _`deallocator`_ where the pointer must be passed in order to deallocate the storage. Using these forms of the `malloc` attribute interact with GCC’s static analyzer (`-fanalyzer`) to allow it to catch:
64
+
65
+
-**Mismatched deallocation** (`-Wanalyzer-mismatching-deallocation`) if there is an execution path in which the result of an allocation call is passed to a different _`deallocator`_.
66
+
-**Double free** (`-Wanalyzer-double-free`) if there is an execution path in which a value is passed more than once to a deallocation call.
67
+
-**Null pointer dereference** (`-Wanalyzer-possible-null-dereference`) if there are execution paths in which an unchecked result of an allocation call is dereferenced or passed to a function requiring a non-null argument.
68
+
-**Use-after-free** (`-Wanalyzer-use-after-free`) if there is an execution path in which the memory passed by pointer to a deallocation call is used after the deallocation.
69
+
-**Memory leaks** (`-Wanalyzer-malloc-leak`) if if there is an execution path in which the result of an allocation call goes out of scope without being passed to the deallocation function.
70
+
-**Invalid free** (`-Wanalyzer-free-of-non-heap`) if a deallocation function is used on a global or on-stack variable.
71
+
72
+
#### Example usage
73
+
74
+
GCC `malloc`, `malloc (`_`deallocator`_`)`, and `malloc (`_`deallocator`_, _`ptr-index`_`)`:
75
+
76
+
~~~c
77
+
voidmy_free(void *);
78
+
79
+
// Denotes that my_malloc will return with a dynamically allocated piece of memory which must be freed using my_free.
80
+
__attribute__ ((malloc, malloc (my_free, 1)))
81
+
void *my_malloc(size_t);
82
+
~~~
83
+
84
+
Note that to benefit both from the associated optimizations and improved detection of memory errors functions should be marked with _both_ the form of the attribute without arguments and the form of the attribute with one or two arguments.
0 commit comments