https://gcc.gnu.org/g:f42fea07282b49066b49ee600c65bac2ea746698
commit r17-3898-gf42fea07282b49066b49ee600c65bac2ea746698 Author: Josef Melcr <[email protected]> Date: Thu Sep 3 14:42:15 2026 +0200 Reformat callback_only attribute docs This patch reformats the paragraphs describing the callback_only function attribute to fit in with the rest of the file. Commiting as obvious. gcc/ChangeLog: * doc/extend.texi: Reformat callback_only attrbute docs. Signed-off-by: Josef Melcr <[email protected]> Diff: --- gcc/doc/extend.texi | 53 ++++++++++++++++++++++++++++------------------------- 1 file changed, 28 insertions(+), 25 deletions(-) diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index a9e4dfd5616d..88213d25a899 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -2357,33 +2357,36 @@ may be silently skipped when generating BTF. @atindex @code{callback_only} @cindex functions with callbacks @item callback_only -The @code{callback_only} attribute specifies that the annotated function may -call the specified callback function. The first parameter identifies the index -of the callback function, the rest of the arguments specify the indices of the -arguments of the indirect call. All indices start from 1. If the function takes -the implicit @code{this} pointer, it is referred to by the index 1, with the -rest of the arguments starting at index 2. The index 0 marks an argument not -present in the arguments of the annotated function, an argument which is -modified before calling the callback function. The annotated function must pass -the specified arguments in the specified order to the callback function, which -must be callable with the number, order and type of the arguments. The -specified pointer to the callback may not escape the translation unit of the -annotated function and it may not be captured. The annotated function is -required to pass the arguments through, it may not change or dereference them. -The arguments also may not escape. The attribute may be used multiple times per -function, though only one @code{callback_only} attribute may be used per -function parameter. Neither the dispatching function nor the callback function -may be variadic. +The @code{callback_only} attribute specifies that the annotated +function may call the specified callback function. The first parameter +identifies the index of the callback function, the rest of the arguments +specify the indices of the arguments of the indirect call. All indices +start from 1. If the function takes the implicit @code{this} pointer, +it is referred to by the index 1, with the rest of the arguments +starting at index 2. The index 0 marks an argument not present in the +arguments of the annotated function, an argument which is modified +before calling the callback function. The annotated function must +pass the specified arguments in the specified order to the callback +function, which must be callable with the number, order and type of +the arguments. The specified pointer to the callback may not escape the +translation unit of the annotated function and it may not be captured. +The annotated function is required to pass the arguments through, it +may not change or dereference them. The arguments also may not escape. +The attribute may be used multiple times per function, though only one +@code{callback_only} attribute may be used per function parameter. +Neither the dispatching function nor the callback function may be +variadic. The attribute exposes the potentially hidden callsite in the annotated -function, enabling interprocedural optimizations which may not be possible -without the attribute. It is most useful for annotating functions from -dynamically linked libraries, as their bodies are not available during -compilation. - -This attribute is similar to the clang @code{callback} attribute but it is not -compatible with it. The clang implementation allows identifiers as arguments, -marks an unknown argument with -1 and the @code{this} pointer with the index 0. +function, enabling interprocedural optimizations which may not be +possible without the attribute. It is most useful for annotating +functions from dynamically linked libraries, as their bodies are not +available during compilation. + +This attribute is similar to the clang @code{callback} attribute +but it is not compatible with it. The clang implementation allows +identifiers as arguments, marks an unknown argument with -1 and the +@code{this} pointer with the index 0. An example usage:
