https://gcc.gnu.org/g:cf6a4fbbaf9ff2402d6b3bd4d81b58c98dcdaa88
commit r16-7851-gcf6a4fbbaf9ff2402d6b3bd4d81b58c98dcdaa88 Author: Sandra Loosemore <[email protected]> Date: Mon Mar 2 20:16:28 2026 +0000 doc: Switch some attribute examples to using standard syntax [PR102397] To finish up PR102397, I've switched some of the attribute examples to use the new standard syntax (in addition to the few examples that were already there). Because the old syntax is so common in existing code, I don't think we want to switch all of the examples -- although when folks add new attributes going forward, I'd recommend using the standard syntax in the documentation. I tested that all the modified examples are accepted by GCC. There are relatively few examples of target-specific attributes for the targets I have existing builds for or can build easily to use for such testing, so I decided to just to leave all the target-specific examples alone and focus on the common attributes. gcc/ChangeLog PR c++/102397 * doc/extend.texi (Attributes): Explicitly say that all attributes work in both syntaxes and examples may show either form. (Common Attributes): Convert some examples to use the new syntax. Diff: --- gcc/doc/extend.texi | 144 ++++++++++++++++++++++++++++------------------------ 1 file changed, 79 insertions(+), 65 deletions(-) diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index ac9fb458f0b2..eb057fb7c406 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -1766,6 +1766,10 @@ __attribute__ ((section ("bar"))) __attribute__ ((weak)) void g4 (void) @{ f2 (); @} @end smallexample +In the sections that follow, either or both syntaxes may appear in code +examples. All attributes can be used with both syntaxes even if only one +is used in the examples for a given attribute. + Compatible attribute specifications on distinct declarations of the same entity are merged. An attribute specification that is not compatible with attributes already applied to a declaration of the same @@ -1866,10 +1870,10 @@ the @code{puts} function, or the second argument to the @code{memcpy} function. @smallexample -__attribute__ ((access (read_only, 1))) +[[gnu::access (read_only, 1)]] int puts (const char*); -__attribute__ ((access (read_only, 2, 3))) +[[gnu::access (read_only, 2, 3)]] void* memcpy (void*, const void*, size_t); @end smallexample @@ -1882,7 +1886,7 @@ of the use of the @code{read_write} access mode is the first argument to the @code{strcat} function. @smallexample -__attribute__ ((access (read_write, 1), access (read_only, 2))) +[[gnu::access (read_write, 1), gnu::access (read_only, 2)]] char* strcat (char*, const char*); @end smallexample @@ -1934,7 +1938,7 @@ For instance, the following @smallexample int var_target; -extern int __attribute__ ((alias ("var_target"))) var_alias; +extern int var_alias [[gnu::alias ("var_target")]]; @end smallexample @noindent @@ -1977,7 +1981,7 @@ When specified, @var{alignment} must be an integer constant power of 2. For example, the declaration: @smallexample -int x __attribute__ ((aligned (16))) = 0; +int x [[gnu::aligned (16)]] = 0; @end smallexample @noindent @@ -2030,7 +2034,7 @@ which is the largest alignment ever used for any data type on the target machine you are compiling for. For example, you could write: @smallexample -short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__))); +short array[3] [[gnu::aligned (__BIGGEST_ALIGNMENT__)]]; @end smallexample @noindent @@ -2190,8 +2194,8 @@ both C and C++. int foo (int x, int y) @{ - __attribute__((assume(x == 42))); - __attribute__((assume(++y == 43))); + [[gnu::assume(x == 42)]]; + [[gnu::assume(++y == 43)]]; return x + y; @} @end smallexample @@ -2252,7 +2256,7 @@ guaranteed to maintain the order of attributes in the source code. For example: @smallexample -int *foo __attribute__ ((btf_decl_tag ("__percpu"))); +int *foo [[gnu::btf_decl_tag ("__percpu")]]; @end smallexample @noindent @@ -2287,7 +2291,7 @@ maintain the order of attributes in the source code. For example the following code: @smallexample -int * __attribute__ ((btf_type_tag ("__user"))) foo; +int * [[gnu::btf_type_tag ("__user")]] foo; @end smallexample @noindent @@ -2400,7 +2404,7 @@ values. For example, @smallexample -int square (int) __attribute__ ((const)); +[[gnu::const]] int square (int); @end smallexample @noindent @@ -2549,7 +2553,7 @@ For instance, the following code: struct P @{ size_t count; char other; - char array[] __attribute__ ((counted_by (count))); + [[gnu::counted_by (count)]] char array[]; @} *p; @end smallexample @@ -2561,7 +2565,7 @@ of elements is given by the field @code{count} in the same structure. struct PP @{ size_t count2; char other1; - char *array2 __attribute__ ((counted_by (count2))); + [[gnu::counted_by (count2)]] char *array2; int other2; @} *pp; @end smallexample @@ -2878,9 +2882,9 @@ should be type-checked against a format string. For example, the declaration: @smallexample +[[gnu::format (printf, 2, 3)]] extern int -my_printf (void *my_object, const char *my_format, ...) - __attribute__ ((format (printf, 2, 3))); +my_printf (void *my_object, const char *my_format, ...); @end smallexample @noindent @@ -3287,8 +3291,8 @@ calls. @atindex @code{malloc} @cindex functions that behave like malloc @item malloc -@item malloc (@var{deallocator}) -@item malloc (@var{deallocator}, @var{ptr-index}) +@itemx malloc (@var{deallocator}) +@itemx malloc (@var{deallocator}, @var{ptr-index}) This attribute applies to functions. Attribute @code{malloc} indicates that a function is @code{malloc}-like, @@ -3338,15 +3342,15 @@ be declared before they can be referenced in the attribute. int fclose (FILE*); int pclose (FILE*); -__attribute__ ((malloc, malloc (fclose, 1))) +[[gnu::malloc, gnu::malloc (fclose, 1)]] FILE* fdopen (int, const char*); -__attribute__ ((malloc, malloc (fclose, 1))) +[[gnu::malloc, gnu::malloc (fclose, 1)]] FILE* fopen (const char*, const char*); -__attribute__ ((malloc, malloc (fclose, 1))) +[[gnu::malloc, gnu::malloc (fclose, 1)]] FILE* fmemopen(void *, size_t, const char *); -__attribute__ ((malloc, malloc (pclose, 1))) +[[gnu::malloc, gnu::malloc (fclose, 1)]] FILE* popen (const char*, const char*); -__attribute__ ((malloc, malloc (fclose, 1))) +[[gnu::malloc, gnu::malloc (fclose, 1)]] FILE* tmpfile (void); @end smallexample @@ -3842,17 +3846,19 @@ arguments are zero and if both are non-zero, the pointer argument must not be null. @smallexample +[[gnu::nonnull (1, 2)]] extern void * -my_memcpy (void *dest, const void *src, size_t len) - __attribute__((nonnull (1, 2))); +my_memcpy (void *dest, const void *src, size_t len); + +[[gnu::nonnull_if_nonzero (1, 3), + gnu::nonnull_if_nonzero (2, 3)]] extern void * -my_memcpy2 (void *dest, const void *src, size_t len) - __attribute__((nonnull_if_nonzero (1, 3), - nonnull_if_nonzero (2, 3))); +my_memcpy2 (void *dest, const void *src, size_t len); + +[[gnu::nonnull (4), + gnu::nonnull_if_nonzero (1, 2, 3)]] extern size_t -my_fread (void *buf, size_t size, size_t count, FILE *stream) - __attribute__((nonnull (4), - nonnull_if_nonzero (1, 2, 3))); +my_fread (void *buf, size_t size, size_t count, FILE *stream); @end smallexample With these declarations, it is invalid to call @@ -3918,7 +3924,7 @@ do not use the PLT. @smallexample @group /* Externally defined function foo. */ -int foo () __attribute__ ((noplt)); +[[gnu::noplt]] int foo (); int main (/* @r{@dots{}} */) @@ -4042,10 +4048,10 @@ referring to a size argument, this expresses the maximum size of the access. For example, given: @smallexample -extern char *example_fn (const char *p, size_t n) - __attribute__((null_terminated_string_arg (1), - access (read_only, 1, 2), - nonnull (1))); +[[gnu::null_terminated_string_arg (1), + gnu::access (read_only, 1, 2), + gnu::nonnull (1)]] +extern char *example_fn (const char *p, size_t n); @end smallexample @noindent @@ -4167,16 +4173,16 @@ be packed too. @smallexample struct my_unpacked_struct - @{ - char c; - int i; - @}; +@{ + char c; + int i; +@}; -struct __attribute__ ((__packed__)) my_packed_struct - @{ - char c; - int i; - struct my_unpacked_struct s; +struct [[gnu::__packed__]] my_packed_struct +@{ + char c; + int i; + struct my_unpacked_struct s; @}; @end smallexample @@ -4335,8 +4341,8 @@ The @code{returns_nonnull} attribute specifies that the function return value should be a non-null pointer. For instance, the declaration: @smallexample -extern void * -mymalloc (size_t len) __attribute__((returns_nonnull)); +[[gnu::returns_nonnull]] +extern void *mymalloc (size_t len); @end smallexample @noindent @@ -4480,11 +4486,7 @@ argument of the function call. If the optional @var{position} argument is specified to the attribute, the sentinel must be located at @var{position} counting backwards from the end of the argument list. -@smallexample -__attribute__ ((sentinel)) -is equivalent to -__attribute__ ((sentinel(0))) -@end smallexample +@samp{[[gnu::sentinel]]} is equivalent to @samp{[[gnu::sentinel(0)]]}. The attribute is automatically set with a position of 0 for the built-in functions @code{execl} and @code{execlp}. The built-in function @@ -4690,12 +4692,13 @@ with @option{-fstrub=strict}, that causes @code{strub} mode to default to @code{disabled}. @smallexample -extern int __attribute__ ((strub ("callable"))) bac (void); -extern int __attribute__ ((strub ("disabled"))) bad (void); +[[gnu::strub("callable")]] extern int bac (void); +[[gnu::strub("disabled")]] extern int bad (void); /* Implicitly disabled with -fstrub=strict, otherwise callable. */ extern int bah (void); -int __attribute__ ((strub)) +[[gnu::strub]] +int bal (void) @{ /* Not allowed, bad is not strub-callable. */ @@ -4853,7 +4856,7 @@ This example produces a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler output.: @smallexample -__attribute__ ((__symver__ ("foo@@VERS_1"))) int +[[gnu::__symver__ ("foo@@VERS_1")]] int foo_v1 (void) @{ @} @@ -4863,7 +4866,7 @@ You can also define multiple versions for a given symbol (starting from binutils 2.35): @smallexample -__attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3"))) +[[gnu::__symver__ ("foo@@VERS_2"), gnu::__symver__ ("foo@@VERS_3")]] int symver_foo_v1 (void) @{ @} @@ -5237,7 +5240,7 @@ return type. This attribute specifies the vector size for the type, measured in bytes. The type to which it applies is known as the @dfn{base type}. The @var{bytes} argument must be a positive power-of-two multiple of the base type size. For -example, the following declarations: +example, the following declarations using the legacy attribute syntax: @smallexample typedef __attribute__ ((vector_size (32))) int int_vec32_t ; @@ -5246,6 +5249,16 @@ typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3]; @end smallexample @noindent +or, alternatively, these declarations using the standard syntax: + +@smallexample +typedef int int_vec32_t [[gnu::vector_size (32)]]; +typedef int * int_vec32_ptr_t [[gnu::vector_size (32)]]; +typedef int int_vec32_arr3_t[3] [[gnu::vector_size (32)]]; +@end smallexample + +@noindent +both define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int} sized units. With @code{int} having a size of 4 bytes, the type defines a vector of eight units, four bytes each. The mode of variables of type @@ -5264,7 +5277,7 @@ a 16-byte vector with the base type @code{float}. This example: @smallexample -int foo __attribute__ ((vector_size (16))); +int foo [[gnu::vector_size (16)]]; @end smallexample @noindent @@ -5302,9 +5315,10 @@ There are four supported @var{visibility_type} values: @code{default}, @code{hidden}, @code{protected}, or @code{internal} visibility. @smallexample -void __attribute__ ((visibility ("protected"))) -f () @{ /* @r{Do something.} */; @} -int i __attribute__ ((visibility ("hidden"))); +[[gnu::visibility ("protected")]] +void f () @{ /* @r{Do something.} */; @} + +int i [[gnu::visibility ("hidden")]]; @end smallexample The possible values of @var{visibility_type} correspond to the @@ -5452,7 +5466,7 @@ For example, this code: @smallexample typedef unsigned long long __u64 - __attribute__((aligned (4), warn_if_not_aligned (8))); + [[gnu::aligned (4), gnu::warn_if_not_aligned (8)]]; struct foo @{ @@ -5480,8 +5494,8 @@ the result is either a security problem or always a bug, such as @code{realloc}. @smallexample -int fn () __attribute__ ((warn_unused_result)); -int foo () +[[gnu::warn_unused_result]] int fn (void); +int foo (void) @{ if (fn () < 0) return -1; fn (); @@ -5490,7 +5504,7 @@ int foo () @end smallexample @noindent -results in warning on line 5. +results in a warning on line 5. @atindex @code{weak} @cindex weak symbols
