================
@@ -9895,13 +9895,77 @@ Example:
def CountedByDocs : Documentation {
let Category = DocCatField;
- let Content = [{
-Clang supports the ``counted_by`` attribute on the flexible array member of a
-structure in C. The argument for the attribute is the name of a field member
-holding the count of elements in the flexible array. This information can be
-used to improve the results of the array bound sanitizer and the
-``__builtin_dynamic_object_size`` builtin. The ``count`` field member must be
-within the same non-anonymous, enclosing struct as the flexible array member.
+ let Heading = "counted_by";
+ let Content = [{
+The ``counted_by`` attribute is applied to a pointer or flexible array member
to
+indicate that the pointer points to (or the flexible array member contains) at
+least the number of *elements* given by the attribute's argument.
+
+This attribute is used by `-fbounds-safety <BoundsSafety.html>`__ to propagate
+bounds information on API surfaces without any ABI changes. This attribute is
+also used to improve the results of the array bound sanitizer and the
+``__builtin_dynamic_object_size`` builtin.
+
+Because the size of the pointee type must be known to compute the pointer's
+bounds, such a pointer must not be used while its pointee type is incomplete; a
+pointer to a forward-declared type is accepted on fields annotated with
+``counted_by``, but the type must be completed before the pointer is used. If
+the pointee type can never be completed, ``counted_by`` is rejected and
+``sized_by`` should be used instead. ``void *`` is a special case: as a GNU
+extension (diagnosed by ``-Wgnu-pointer-arith``), ``counted_by`` is accepted on
+it, where it behaves like ``sized_by`` (the argument is treated as a byte
count,
+``void`` having an assumed size of one byte).
+
+A pointer annotated with ``counted_by`` must have a count of zero when it is
+null. This requirement is currently only enforced when compiling with
----------------
rapidsna wrote:
Since -fbounds-safety isn't yet available in llvm/llvm-project, this
enforcement doesn't actually apply upstream today. I think writing the docs as
if -fbounds-safety were available is fine, but should we add a clarifying note
somewhere nearby so readers who land here directly aren't confused?
https://github.com/llvm/llvm-project/pull/212877
_______________________________________________
cfe-commits mailing list
[email protected]
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
