gcc: Common Function Attributes
1
1 6.31.1 Common Function Attributes
1 ---------------------------------
1
1 The following attributes are supported on most targets.
1
1 'alias ("TARGET")'
1 The 'alias' attribute causes the declaration to be emitted as an
1 alias for another symbol, which must be specified. For instance,
1
1 void __f () { /* Do something. */; }
1 void f () __attribute__ ((weak, alias ("__f")));
1
1 defines 'f' to be a weak alias for '__f'. In C++, the mangled name
1 for the target must be used. It is an error if '__f' is not
1 defined in the same translation unit.
1
1 This attribute requires assembler and object file support, and may
1 not be available on all targets.
1
1 'aligned (ALIGNMENT)'
1 This attribute specifies a minimum alignment for the function,
1 measured in bytes.
1
1 You cannot use this attribute to decrease the alignment of a
1 function, only to increase it. However, when you explicitly
1 specify a function alignment this overrides the effect of the
1 '-falign-functions' (⇒Optimize Options) option for this
1 function.
1
1 Note that the effectiveness of 'aligned' attributes may be limited
1 by inherent limitations in your linker. On many systems, the
1 linker is only able to arrange for functions to be aligned up to a
1 certain maximum alignment. (For some linkers, the maximum
1 supported alignment may be very very small.) See your linker
1 documentation for further information.
1
1 The 'aligned' attribute can also be used for variables and fields
1 (⇒Variable Attributes.)
1
1 'alloc_align'
1 The 'alloc_align' attribute is used to tell the compiler that the
1 function return value points to memory, where the returned pointer
1 minimum alignment is given by one of the functions parameters. GCC
1 uses this information to improve pointer alignment analysis.
1
1 The function parameter denoting the allocated alignment is
1 specified by one integer argument, whose number is the argument of
1 the attribute. Argument numbering starts at one.
1
1 For instance,
1
1 void* my_memalign(size_t, size_t) __attribute__((alloc_align(1)))
1
1 declares that 'my_memalign' returns memory with minimum alignment
1 given by parameter 1.
1
1 'alloc_size'
1 The 'alloc_size' attribute is used to tell the compiler that the
1 function return value points to memory, where the size is given by
1 one or two of the functions parameters. GCC uses this information
1 to improve the correctness of '__builtin_object_size'.
1
1 The function parameter(s) denoting the allocated size are specified
1 by one or two integer arguments supplied to the attribute. The
1 allocated size is either the value of the single function argument
1 specified or the product of the two function arguments specified.
1 Argument numbering starts at one.
1
1 For instance,
1
1 void* my_calloc(size_t, size_t) __attribute__((alloc_size(1,2)))
1 void* my_realloc(void*, size_t) __attribute__((alloc_size(2)))
1
1 declares that 'my_calloc' returns memory of the size given by the
1 product of parameter 1 and 2 and that 'my_realloc' returns memory
1 of the size given by parameter 2.
1
1 'always_inline'
1 Generally, functions are not inlined unless optimization is
1 specified. For functions declared inline, this attribute inlines
1 the function independent of any restrictions that otherwise apply
1 to inlining. Failure to inline such a function is diagnosed as an
1 error. Note that if such a function is called indirectly the
1 compiler may or may not inline it depending on optimization level
1 and a failure to inline an indirect call may or may not be
1 diagnosed.
1
1 'artificial'
1 This attribute is useful for small inline wrappers that if possible
1 should appear during debugging as a unit. Depending on the debug
1 info format it either means marking the function as artificial or
1 using the caller location for all instructions within the inlined
1 body.
1
1 'assume_aligned'
1 The 'assume_aligned' attribute is used to tell the compiler that
1 the function return value points to memory, where the returned
1 pointer minimum alignment is given by the first argument. If the
1 attribute has two arguments, the second argument is misalignment
1 offset.
1
1 For instance
1
1 void* my_alloc1(size_t) __attribute__((assume_aligned(16)))
1 void* my_alloc2(size_t) __attribute__((assume_aligned(32, 8)))
1
1 declares that 'my_alloc1' returns 16-byte aligned pointer and that
1 'my_alloc2' returns a pointer whose value modulo 32 is equal to 8.
1
1 'bnd_instrument'
1 The 'bnd_instrument' attribute on functions is used to inform the
1 compiler that the function should be instrumented when compiled
1 with the '-fchkp-instrument-marked-only' option.
1
1 'bnd_legacy'
1 The 'bnd_legacy' attribute on functions is used to inform the
1 compiler that the function should not be instrumented when compiled
1 with the '-fcheck-pointer-bounds' option.
1
1 'cold'
1 The 'cold' attribute on functions is used to inform the compiler
1 that the function is unlikely to be executed. The function is
1 optimized for size rather than speed and on many targets it is
1 placed into a special subsection of the text section so all cold
1 functions appear close together, improving code locality of
1 non-cold parts of program. The paths leading to calls of cold
1 functions within code are marked as unlikely by the branch
1 prediction mechanism. It is thus useful to mark functions used to
1 handle unlikely conditions, such as 'perror', as cold to improve
1 optimization of hot functions that do call marked functions in rare
1 occasions.
1
1 When profile feedback is available, via '-fprofile-use', cold
1 functions are automatically detected and this attribute is ignored.
1
1 'const'
1 Many functions do not examine any values except their arguments,
1 and have no effects except to return a value. Calls to such
1 functions lend themselves to optimization such as common
1 subexpression elimination. The 'const' attribute imposes greater
1 restrictions on a function's definition than the similar 'pure'
1 attribute below because it prohibits the function from reading
1 global variables. Consequently, the presence of the attribute on a
1 function declaration allows GCC to emit more efficient code for
1 some calls to the function. Decorating the same function with both
1 the 'const' and the 'pure' attribute is diagnosed.
1
1 Note that a function that has pointer arguments and examines the
1 data pointed to must _not_ be declared 'const'. Likewise, a
1 function that calls a non-'const' function usually must not be
1 'const'. Because a 'const' function cannot have any side effects
1 it does not make sense for such a function to return 'void'.
1 Declaring such a function is diagnosed.
1
1 'constructor'
1 'destructor'
1 'constructor (PRIORITY)'
1 'destructor (PRIORITY)'
1 The 'constructor' attribute causes the function to be called
1 automatically before execution enters 'main ()'. Similarly, the
1 'destructor' attribute causes the function to be called
1 automatically after 'main ()' completes or 'exit ()' is called.
1 Functions with these attributes are useful for initializing data
1 that is used implicitly during the execution of the program.
1
1 You may provide an optional integer priority to control the order
1 in which constructor and destructor functions are run. A
1 constructor with a smaller priority number runs before a
1 constructor with a larger priority number; the opposite
1 relationship holds for destructors. So, if you have a constructor
1 that allocates a resource and a destructor that deallocates the
1 same resource, both functions typically have the same priority.
1 The priorities for constructor and destructor functions are the
11 same as those specified for namespace-scope C++ objects (⇒C++
Attributes). However, at present, the order in which
1 constructors for C++ objects with static storage duration and
1 functions decorated with attribute 'constructor' are invoked is
1 unspecified. In mixed declarations, attribute 'init_priority' can
1 be used to impose a specific ordering.
1
1 'deprecated'
1 'deprecated (MSG)'
1 The 'deprecated' attribute results in a warning if the function is
1 used anywhere in the source file. This is useful when identifying
1 functions that are expected to be removed in a future version of a
1 program. The warning also includes the location of the declaration
1 of the deprecated function, to enable users to easily find further
1 information about why the function is deprecated, or what they
1 should do instead. Note that the warnings only occurs for uses:
1
1 int old_fn () __attribute__ ((deprecated));
1 int old_fn ();
1 int (*fn_ptr)() = old_fn;
1
1 results in a warning on line 3 but not line 2. The optional MSG
1 argument, which must be a string, is printed in the warning if
1 present.
1
1 The 'deprecated' attribute can also be used for variables and types
1 (⇒Variable Attributes, ⇒Type Attributes.)
1
1 'error ("MESSAGE")'
1 'warning ("MESSAGE")'
1 If the 'error' or 'warning' attribute is used on a function
1 declaration and a call to such a function is not eliminated through
1 dead code elimination or other optimizations, an error or warning
1 (respectively) that includes MESSAGE is diagnosed. This is useful
1 for compile-time checking, especially together with
1 '__builtin_constant_p' and inline functions where checking the
1 inline function arguments is not possible through 'extern char
1 [(condition) ? 1 : -1];' tricks.
1
1 While it is possible to leave the function undefined and thus
1 invoke a link failure (to define the function with a message in
1 '.gnu.warning*' section), when using these attributes the problem
1 is diagnosed earlier and with exact location of the call even in
1 presence of inline functions or when not emitting debugging
1 information.
1
1 'externally_visible'
1 This attribute, attached to a global variable or function,
1 nullifies the effect of the '-fwhole-program' command-line option,
1 so the object remains visible outside the current compilation unit.
1
1 If '-fwhole-program' is used together with '-flto' and 'gold' is
1 used as the linker plugin, 'externally_visible' attributes are
1 automatically added to functions (not variable yet due to a current
1 'gold' issue) that are accessed outside of LTO objects according to
1 resolution file produced by 'gold'. For other linkers that cannot
1 generate resolution file, explicit 'externally_visible' attributes
1 are still necessary.
1
1 'flatten'
1 Generally, inlining into a function is limited. For a function
1 marked with this attribute, every call inside this function is
1 inlined, if possible. Whether the function itself is considered
1 for inlining depends on its size and the current inlining
1 parameters.
1
1 'format (ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)'
1 The 'format' attribute specifies that a function takes 'printf',
1 'scanf', 'strftime' or 'strfmon' style arguments that should be
1 type-checked against a format string. For example, the
1 declaration:
1
1 extern int
1 my_printf (void *my_object, const char *my_format, ...)
1 __attribute__ ((format (printf, 2, 3)));
1
1 causes the compiler to check the arguments in calls to 'my_printf'
1 for consistency with the 'printf' style format string argument
1 'my_format'.
1
1 The parameter ARCHETYPE determines how the format string is
1 interpreted, and should be 'printf', 'scanf', 'strftime',
1 'gnu_printf', 'gnu_scanf', 'gnu_strftime' or 'strfmon'. (You can
1 also use '__printf__', '__scanf__', '__strftime__' or
1 '__strfmon__'.) On MinGW targets, 'ms_printf', 'ms_scanf', and
1 'ms_strftime' are also present. ARCHETYPE values such as 'printf'
1 refer to the formats accepted by the system's C runtime library,
1 while values prefixed with 'gnu_' always refer to the formats
1 accepted by the GNU C Library. On Microsoft Windows targets,
1 values prefixed with 'ms_' refer to the formats accepted by the
1 'msvcrt.dll' library. The parameter STRING-INDEX specifies which
1 argument is the format string argument (starting from 1), while
1 FIRST-TO-CHECK is the number of the first argument to check against
1 the format string. For functions where the arguments are not
1 available to be checked (such as 'vprintf'), specify the third
1 parameter as zero. In this case the compiler only checks the
1 format string for consistency. For 'strftime' formats, the third
1 parameter is required to be zero. Since non-static C++ methods
1 have an implicit 'this' argument, the arguments of such methods
1 should be counted from two, not one, when giving values for
1 STRING-INDEX and FIRST-TO-CHECK.
1
1 In the example above, the format string ('my_format') is the second
1 argument of the function 'my_print', and the arguments to check
1 start with the third argument, so the correct parameters for the
1 format attribute are 2 and 3.
1
1 The 'format' attribute allows you to identify your own functions
1 that take format strings as arguments, so that GCC can check the
1 calls to these functions for errors. The compiler always (unless
1 '-ffreestanding' or '-fno-builtin' is used) checks formats for the
1 standard library functions 'printf', 'fprintf', 'sprintf', 'scanf',
1 'fscanf', 'sscanf', 'strftime', 'vprintf', 'vfprintf' and
1 'vsprintf' whenever such warnings are requested (using '-Wformat'),
1 so there is no need to modify the header file 'stdio.h'. In C99
1 mode, the functions 'snprintf', 'vsnprintf', 'vscanf', 'vfscanf'
1 and 'vsscanf' are also checked. Except in strictly conforming C
1 standard modes, the X/Open function 'strfmon' is also checked as
11 are 'printf_unlocked' and 'fprintf_unlocked'. ⇒Options
Controlling C Dialect C Dialect Options.
1
1 For Objective-C dialects, 'NSString' (or '__NSString__') is
1 recognized in the same context. Declarations including these
1 format attributes are parsed for correct syntax, however the result
1 of checking of such format strings is not yet defined, and is not
1 carried out by this version of the compiler.
1
1 The target may also provide additional types of format checks.
11 ⇒Format Checks Specific to Particular Target Machines Target
Format Checks.
1
1 'format_arg (STRING-INDEX)'
1 The 'format_arg' attribute specifies that a function takes a format
1 string for a 'printf', 'scanf', 'strftime' or 'strfmon' style
1 function and modifies it (for example, to translate it into another
1 language), so the result can be passed to a 'printf', 'scanf',
1 'strftime' or 'strfmon' style function (with the remaining
1 arguments to the format function the same as they would have been
1 for the unmodified string). For example, the declaration:
1
1 extern char *
1 my_dgettext (char *my_domain, const char *my_format)
1 __attribute__ ((format_arg (2)));
1
1 causes the compiler to check the arguments in calls to a 'printf',
1 'scanf', 'strftime' or 'strfmon' type function, whose format string
1 argument is a call to the 'my_dgettext' function, for consistency
1 with the format string argument 'my_format'. If the 'format_arg'
1 attribute had not been specified, all the compiler could tell in
1 such calls to format functions would be that the format string
1 argument is not constant; this would generate a warning when
1 '-Wformat-nonliteral' is used, but the calls could not be checked
1 without the attribute.
1
1 The parameter STRING-INDEX specifies which argument is the format
1 string argument (starting from one). Since non-static C++ methods
1 have an implicit 'this' argument, the arguments of such methods
1 should be counted from two.
1
1 The 'format_arg' attribute allows you to identify your own
1 functions that modify format strings, so that GCC can check the
1 calls to 'printf', 'scanf', 'strftime' or 'strfmon' type function
1 whose operands are a call to one of your own function. The
1 compiler always treats 'gettext', 'dgettext', and 'dcgettext' in
1 this manner except when strict ISO C support is requested by
1 '-ansi' or an appropriate '-std' option, or '-ffreestanding' or
11 '-fno-builtin' is used. ⇒Options Controlling C Dialect C
Dialect Options.
1
1 For Objective-C dialects, the 'format-arg' attribute may refer to
1 an 'NSString' reference for compatibility with the 'format'
1 attribute above.
1
1 The target may also allow additional types in 'format-arg'
11 attributes. ⇒Format Checks Specific to Particular Target
Machines Target Format Checks.
1
1 'gnu_inline'
1 This attribute should be used with a function that is also declared
1 with the 'inline' keyword. It directs GCC to treat the function as
1 if it were defined in gnu90 mode even when compiling in C99 or
1 gnu99 mode.
1
1 If the function is declared 'extern', then this definition of the
1 function is used only for inlining. In no case is the function
1 compiled as a standalone function, not even if you take its address
1 explicitly. Such an address becomes an external reference, as if
1 you had only declared the function, and had not defined it. This
1 has almost the effect of a macro. The way to use this is to put a
1 function definition in a header file with this attribute, and put
1 another copy of the function, without 'extern', in a library file.
1 The definition in the header file causes most calls to the function
1 to be inlined. If any uses of the function remain, they refer to
1 the single copy in the library. Note that the two definitions of
1 the functions need not be precisely the same, although if they do
1 not have the same effect your program may behave oddly.
1
1 In C, if the function is neither 'extern' nor 'static', then the
1 function is compiled as a standalone function, as well as being
1 inlined where possible.
1
1 This is how GCC traditionally handled functions declared 'inline'.
1 Since ISO C99 specifies a different semantics for 'inline', this
1 function attribute is provided as a transition measure and as a
1 useful feature in its own right. This attribute is available in
1 GCC 4.1.3 and later. It is available if either of the preprocessor
1 macros '__GNUC_GNU_INLINE__' or '__GNUC_STDC_INLINE__' are defined.
1 ⇒An Inline Function is As Fast As a Macro Inline.
1
1 In C++, this attribute does not depend on 'extern' in any way, but
1 it still requires the 'inline' keyword to enable its special
1 behavior.
1
1 'hot'
1 The 'hot' attribute on a function is used to inform the compiler
1 that the function is a hot spot of the compiled program. The
1 function is optimized more aggressively and on many targets it is
1 placed into a special subsection of the text section so all hot
1 functions appear close together, improving locality.
1
1 When profile feedback is available, via '-fprofile-use', hot
1 functions are automatically detected and this attribute is ignored.
1
1 'ifunc ("RESOLVER")'
1 The 'ifunc' attribute is used to mark a function as an indirect
1 function using the STT_GNU_IFUNC symbol type extension to the ELF
1 standard. This allows the resolution of the symbol value to be
1 determined dynamically at load time, and an optimized version of
1 the routine to be selected for the particular processor or other
1 system characteristics determined then. To use this attribute,
1 first define the implementation functions available, and a resolver
1 function that returns a pointer to the selected implementation
1 function. The implementation functions' declarations must match
1 the API of the function being implemented. The resolver should be
1 declared to be a function taking no arguments and returning a
1 pointer to a function of the same type as the implementation. For
1 example:
1
1 void *my_memcpy (void *dst, const void *src, size_t len)
1 {
1 ...
1 return dst;
1 }
1
1 static void * (*resolve_memcpy (void))(void *, const void *, size_t)
1 {
1 return my_memcpy; // we will just always select this routine
1 }
1
1 The exported header file declaring the function the user calls
1 would contain:
1
1 extern void *memcpy (void *, const void *, size_t);
1
1 allowing the user to call 'memcpy' as a regular function, unaware
1 of the actual implementation. Finally, the indirect function needs
1 to be defined in the same translation unit as the resolver
1 function:
1
1 void *memcpy (void *, const void *, size_t)
1 __attribute__ ((ifunc ("resolve_memcpy")));
1
1 In C++, the 'ifunc' attribute takes a string that is the mangled
1 name of the resolver function. A C++ resolver for a non-static
1 member function of class 'C' should be declared to return a pointer
1 to a non-member function taking pointer to 'C' as the first
1 argument, followed by the same arguments as of the implementation
1 function. G++ checks the signatures of the two functions and
1 issues a '-Wattribute-alias' warning for mismatches. To suppress a
1 warning for the necessary cast from a pointer to the implementation
1 member function to the type of the corresponding non-member
1 function use the '-Wno-pmf-conversions' option. For example:
1
1 class S
1 {
1 private:
1 int debug_impl (int);
1 int optimized_impl (int);
1
1 typedef int Func (S*, int);
1
1 static Func* resolver ();
1 public:
1
1 int interface (int);
1 };
1
1 int S::debug_impl (int) { /* ... */ }
1 int S::optimized_impl (int) { /* ... */ }
1
1 S::Func* S::resolver ()
1 {
1 int (S::*pimpl) (int)
1 = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl;
1
1 // Cast triggers -Wno-pmf-conversions.
1 return reinterpret_cast<Func*>(pimpl);
1 }
1
1 int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv")));
1
1 Indirect functions cannot be weak. Binutils version 2.20.1 or
1 higher and GNU C Library version 2.11.1 are required to use this
1 feature.
1
1 'interrupt'
1 'interrupt_handler'
1 Many GCC back ends support attributes to indicate that a function
1 is an interrupt handler, which tells the compiler to generate
1 function entry and exit sequences that differ from those from
1 regular functions. The exact syntax and behavior are
1 target-specific; refer to the following subsections for details.
1
1 'leaf'
1 Calls to external functions with this attribute must return to the
1 current compilation unit only by return or by exception handling.
1 In particular, a leaf function is not allowed to invoke callback
1 functions passed to it from the current compilation unit, directly
1 call functions exported by the unit, or 'longjmp' into the unit.
1 Leaf functions might still call functions from other compilation
1 units and thus they are not necessarily leaf in the sense that they
1 contain no function calls at all.
1
1 The attribute is intended for library functions to improve dataflow
1 analysis. The compiler takes the hint that any data not escaping
1 the current compilation unit cannot be used or modified by the leaf
1 function. For example, the 'sin' function is a leaf function, but
1 'qsort' is not.
1
1 Note that leaf functions might indirectly run a signal handler
1 defined in the current compilation unit that uses static variables.
1 Similarly, when lazy symbol resolution is in effect, leaf functions
1 might invoke indirect functions whose resolver function or
1 implementation function is defined in the current compilation unit
1 and uses static variables. There is no standard-compliant way to
1 write such a signal handler, resolver function, or implementation
1 function, and the best that you can do is to remove the 'leaf'
1 attribute or mark all such static variables 'volatile'. Lastly,
1 for ELF-based systems that support symbol interposition, care
1 should be taken that functions defined in the current compilation
1 unit do not unexpectedly interpose other symbols based on the
1 defined standards mode and defined feature test macros; otherwise
1 an inadvertent callback would be added.
1
1 The attribute has no effect on functions defined within the current
1 compilation unit. This is to allow easy merging of multiple
1 compilation units into one, for example, by using the link-time
1 optimization. For this reason the attribute is not allowed on
1 types to annotate indirect calls.
1
1 'malloc'
1 This tells the compiler that a function is 'malloc'-like, i.e.,
1 that the pointer P returned by the function cannot alias any other
1 pointer valid when the function returns, and moreover no pointers
1 to valid objects occur in any storage addressed by P.
1
1 Using this attribute can improve optimization. Functions like
1 'malloc' and 'calloc' have this property because they return a
1 pointer to uninitialized or zeroed-out storage. However, functions
1 like 'realloc' do not have this property, as they can return a
1 pointer to storage containing pointers.
1
1 'no_icf'
1 This function attribute prevents a functions from being merged with
1 another semantically equivalent function.
1
1 'no_instrument_function'
1 If '-finstrument-functions' is given, profiling function calls are
1 generated at entry and exit of most user-compiled functions.
1 Functions with this attribute are not so instrumented.
1
1 'no_profile_instrument_function'
1 The 'no_profile_instrument_function' attribute on functions is used
1 to inform the compiler that it should not process any profile
1 feedback based optimization code instrumentation.
1
1 'no_reorder'
1 Do not reorder functions or variables marked 'no_reorder' against
1 each other or top level assembler statements the executable. The
1 actual order in the program will depend on the linker command line.
1 Static variables marked like this are also not removed. This has a
1 similar effect as the '-fno-toplevel-reorder' option, but only
1 applies to the marked symbols.
1
1 'no_sanitize ("SANITIZE_OPTION")'
1 The 'no_sanitize' attribute on functions is used to inform the
1 compiler that it should not do sanitization of all options
1 mentioned in SANITIZE_OPTION. A list of values acceptable by
1 '-fsanitize' option can be provided.
1
1 void __attribute__ ((no_sanitize ("alignment", "object-size")))
1 f () { /* Do something. */; }
1 void __attribute__ ((no_sanitize ("alignment,object-size")))
1 g () { /* Do something. */; }
1
1 'no_sanitize_address'
1 'no_address_safety_analysis'
1 The 'no_sanitize_address' attribute on functions is used to inform
1 the compiler that it should not instrument memory accesses in the
1 function when compiling with the '-fsanitize=address' option. The
1 'no_address_safety_analysis' is a deprecated alias of the
1 'no_sanitize_address' attribute, new code should use
1 'no_sanitize_address'.
1
1 'no_sanitize_thread'
1 The 'no_sanitize_thread' attribute on functions is used to inform
1 the compiler that it should not instrument memory accesses in the
1 function when compiling with the '-fsanitize=thread' option.
1
1 'no_sanitize_undefined'
1 The 'no_sanitize_undefined' attribute on functions is used to
1 inform the compiler that it should not check for undefined behavior
1 in the function when compiling with the '-fsanitize=undefined'
1 option.
1
1 'no_split_stack'
1 If '-fsplit-stack' is given, functions have a small prologue which
1 decides whether to split the stack. Functions with the
1 'no_split_stack' attribute do not have that prologue, and thus may
1 run with only a small amount of stack space available.
1
1 'no_stack_limit'
1 This attribute locally overrides the '-fstack-limit-register' and
1 '-fstack-limit-symbol' command-line options; it has the effect of
1 disabling stack limit checking in the function it applies to.
1
1 'noclone'
1 This function attribute prevents a function from being considered
1 for cloning--a mechanism that produces specialized copies of
1 functions and which is (currently) performed by interprocedural
1 constant propagation.
1
1 'noinline'
1 This function attribute prevents a function from being considered
1 for inlining. If the function does not have side effects, there
1 are optimizations other than inlining that cause function calls to
1 be optimized away, although the function call is live. To keep
1 such calls from being optimized away, put
1 asm ("");
1
1 (⇒Extended Asm) in the called function, to serve as a
1 special side effect.
1
1 'noipa'
1 Disable interprocedural optimizations between the function with
1 this attribute and its callers, as if the body of the function is
1 not available when optimizing callers and the callers are
1 unavailable when optimizing the body. This attribute implies
1 'noinline', 'noclone' and 'no_icf' attributes. However, this
1 attribute is not equivalent to a combination of other attributes,
1 because its purpose is to suppress existing and future
1 optimizations employing interprocedural analysis, including those
1 that do not have an attribute suitable for disabling them
1 individually. This attribute is supported mainly for the purpose
1 of testing the compiler.
1
1 'nonnull (ARG-INDEX, ...)'
1 The 'nonnull' attribute specifies that some function parameters
1 should be non-null pointers. For instance, the declaration:
1
1 extern void *
1 my_memcpy (void *dest, const void *src, size_t len)
1 __attribute__((nonnull (1, 2)));
1
1 causes the compiler to check that, in calls to 'my_memcpy',
1 arguments DEST and SRC are non-null. If the compiler determines
1 that a null pointer is passed in an argument slot marked as
1 non-null, and the '-Wnonnull' option is enabled, a warning is
1 issued. The compiler may also choose to make optimizations based
1 on the knowledge that certain function arguments will never be
1 null.
1
1 If no argument index list is given to the 'nonnull' attribute, all
1 pointer arguments are marked as non-null. To illustrate, the
1 following declaration is equivalent to the previous example:
1
1 extern void *
1 my_memcpy (void *dest, const void *src, size_t len)
1 __attribute__((nonnull));
1
1 'noplt'
1 The 'noplt' attribute is the counterpart to option '-fno-plt'.
1 Calls to functions marked with this attribute in
1 position-independent code do not use the PLT.
1
1 /* Externally defined function foo. */
1 int foo () __attribute__ ((noplt));
1
1 int
1 main (/* ... */)
1 {
1 /* ... */
1 foo ();
1 /* ... */
1 }
1
1 The 'noplt' attribute on function 'foo' tells the compiler to
1 assume that the function 'foo' is externally defined and that the
1 call to 'foo' must avoid the PLT in position-independent code.
1
1 In position-dependent code, a few targets also convert calls to
1 functions that are marked to not use the PLT to use the GOT
1 instead.
1
1 'noreturn'
1 A few standard library functions, such as 'abort' and 'exit',
1 cannot return. GCC knows this automatically. Some programs define
1 their own functions that never return. You can declare them
1 'noreturn' to tell the compiler this fact. For example,
1
1 void fatal () __attribute__ ((noreturn));
1
1 void
1 fatal (/* ... */)
1 {
1 /* ... */ /* Print error message. */ /* ... */
1 exit (1);
1 }
1
1 The 'noreturn' keyword tells the compiler to assume that 'fatal'
1 cannot return. It can then optimize without regard to what would
1 happen if 'fatal' ever did return. This makes slightly better
1 code. More importantly, it helps avoid spurious warnings of
1 uninitialized variables.
1
1 The 'noreturn' keyword does not affect the exceptional path when
1 that applies: a 'noreturn'-marked function may still return to the
1 caller by throwing an exception or calling 'longjmp'.
1
1 Do not assume that registers saved by the calling function are
1 restored before calling the 'noreturn' function.
1
1 It does not make sense for a 'noreturn' function to have a return
1 type other than 'void'.
1
1 'nothrow'
1 The 'nothrow' attribute is used to inform the compiler that a
1 function cannot throw an exception. For example, most functions in
1 the standard C library can be guaranteed not to throw an exception
1 with the notable exceptions of 'qsort' and 'bsearch' that take
1 function pointer arguments.
1
1 'optimize'
1 The 'optimize' attribute is used to specify that a function is to
1 be compiled with different optimization options than specified on
1 the command line. Arguments can either be numbers or strings.
1 Numbers are assumed to be an optimization level. Strings that
1 begin with 'O' are assumed to be an optimization option, while
1 other options are assumed to be used with a '-f' prefix. You can
1 also use the '#pragma GCC optimize' pragma to set the optimization
11 options that affect more than one function. ⇒Function
Specific Option Pragmas, for details about the '#pragma GCC
1 optimize' pragma.
1
1 This attribute should be used for debugging purposes only. It is
1 not suitable in production code.
1
1 'patchable_function_entry'
1 In case the target's text segment can be made writable at run time
1 by any means, padding the function entry with a number of NOPs can
1 be used to provide a universal tool for instrumentation.
1
1 The 'patchable_function_entry' function attribute can be used to
1 change the number of NOPs to any desired value. The two-value
1 syntax is the same as for the command-line switch
1 '-fpatchable-function-entry=N,M', generating N NOPs, with the
1 function entry point before the Mth NOP instruction. M defaults to
1 0 if omitted e.g. function entry point is before the first NOP.
1
1 If patchable function entries are enabled globally using the
1 command-line option '-fpatchable-function-entry=N,M', then you must
1 disable instrumentation on all functions that are part of the
1 instrumentation framework with the attribute
1 'patchable_function_entry (0)' to prevent recursion.
1
1 'pure'
1 Many functions have no effects except the return value and their
1 return value depends only on the parameters and/or global
1 variables. Calls to such functions can be subject to common
1 subexpression elimination and loop optimization just as an
1 arithmetic operator would be. These functions should be declared
1 with the attribute 'pure'. For example,
1
1 int square (int) __attribute__ ((pure));
1
1 says that the hypothetical function 'square' is safe to call fewer
1 times than the program says.
1
1 Some common examples of pure functions are 'strlen' or 'memcmp'.
1 Interesting non-pure functions are functions with infinite loops or
1 those depending on volatile memory or other system resource, that
1 may change between two consecutive calls (such as 'feof' in a
1 multithreading environment).
1
1 The 'pure' attribute imposes similar but looser restrictions on a
1 function's defintion than the 'const' attribute: it allows the
1 function to read global variables. Decorating the same function
1 with both the 'pure' and the 'const' attribute is diagnosed.
1 Because a 'pure' function cannot have any side effects it does not
1 make sense for such a function to return 'void'. Declaring such a
1 function is diagnosed.
1
1 'returns_nonnull'
1 The 'returns_nonnull' attribute specifies that the function return
1 value should be a non-null pointer. For instance, the declaration:
1
1 extern void *
1 mymalloc (size_t len) __attribute__((returns_nonnull));
1
1 lets the compiler optimize callers based on the knowledge that the
1 return value will never be null.
1
1 'returns_twice'
1 The 'returns_twice' attribute tells the compiler that a function
1 may return more than one time. The compiler ensures that all
1 registers are dead before calling such a function and emits a
1 warning about the variables that may be clobbered after the second
1 return from the function. Examples of such functions are 'setjmp'
1 and 'vfork'. The 'longjmp'-like counterpart of such function, if
1 any, might need to be marked with the 'noreturn' attribute.
1
1 'section ("SECTION-NAME")'
1 Normally, the compiler places the code it generates in the 'text'
1 section. Sometimes, however, you need additional sections, or you
1 need certain particular functions to appear in special sections.
1 The 'section' attribute specifies that a function lives in a
1 particular section. For example, the declaration:
1
1 extern void foobar (void) __attribute__ ((section ("bar")));
1
1 puts the function 'foobar' in the 'bar' section.
1
1 Some file formats do not support arbitrary sections so the
1 'section' attribute is not available on all platforms. If you need
1 to map the entire contents of a module to a particular section,
1 consider using the facilities of the linker instead.
1
1 'sentinel'
1 This function attribute ensures that a parameter in a function call
1 is an explicit 'NULL'. The attribute is only valid on variadic
1 functions. By default, the sentinel is located at position zero,
1 the last parameter of the function call. If an optional integer
1 position argument P is supplied to the attribute, the sentinel must
1 be located at position P counting backwards from the end of the
1 argument list.
1
1 __attribute__ ((sentinel))
1 is equivalent to
1 __attribute__ ((sentinel(0)))
1
1 The attribute is automatically set with a position of 0 for the
1 built-in functions 'execl' and 'execlp'. The built-in function
1 'execle' has the attribute set with a position of 1.
1
1 A valid 'NULL' in this context is defined as zero with any pointer
1 type. If your system defines the 'NULL' macro with an integer type
1 then you need to add an explicit cast. GCC replaces 'stddef.h'
1 with a copy that redefines NULL appropriately.
1
1 The warnings for missing or incorrect sentinels are enabled with
1 '-Wformat'.
1
1 'simd'
1 'simd("MASK")'
1 This attribute enables creation of one or more function versions
1 that can process multiple arguments using SIMD instructions from a
1 single invocation. Specifying this attribute allows compiler to
1 assume that such versions are available at link time (provided in
1 the same or another translation unit). Generated versions are
1 target-dependent and described in the corresponding Vector ABI
1 document. For x86_64 target this document can be found
1 here (https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt).
1
1 The optional argument MASK may have the value 'notinbranch' or
1 'inbranch', and instructs the compiler to generate non-masked or
1 masked clones correspondingly. By default, all clones are
1 generated.
1
1 If the attribute is specified and '#pragma omp declare simd' is
1 present on a declaration and the '-fopenmp' or '-fopenmp-simd'
1 switch is specified, then the attribute is ignored.
1
1 'stack_protect'
1 This attribute adds stack protection code to the function if flags
1 '-fstack-protector', '-fstack-protector-strong' or
1 '-fstack-protector-explicit' are set.
1
1 'target (OPTIONS)'
1 Multiple target back ends implement the 'target' attribute to
1 specify that a function is to be compiled with different target
1 options than specified on the command line. This can be used for
1 instance to have functions compiled with a different ISA
1 (instruction set architecture) than the default. You can also use
1 the '#pragma GCC target' pragma to set more than one function to be
11 compiled with specific target options. ⇒Function Specific
Option Pragmas, for details about the '#pragma GCC target'
1 pragma.
1
1 For instance, on an x86, you could declare one function with the
1 'target("sse4.1,arch=core2")' attribute and another with
1 'target("sse4a,arch=amdfam10")'. This is equivalent to compiling
1 the first function with '-msse4.1' and '-march=core2' options, and
1 the second function with '-msse4a' and '-march=amdfam10' options.
1 It is up to you to make sure that a function is only invoked on a
1 machine that supports the particular ISA it is compiled for (for
1 example by using 'cpuid' on x86 to determine what feature bits and
1 architecture family are used).
1
1 int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
1 int sse3_func (void) __attribute__ ((__target__ ("sse3")));
1
1 You can either use multiple strings separated by commas to specify
1 multiple options, or separate the options with a comma (',') within
1 a single string.
1
11 The options supported are specific to each target; refer to ⇒
x86 Function Attributes, ⇒PowerPC Function Attributes,
DONTPRINTYET 1 ⇒ARM Function Attributes, *noteAArch64 Function
DONTPRINTYET 1DONTPRINTYET 1 ⇒ARM Function Attributes, ⇒AArch64 Function
Attributes, ⇒Nios II Function Attributes, and *noteS/390
1DONTPRINTYET 1DONTPRINTYET 1 ⇒ARM Function Attributes, ⇒AArch64 Function
Attributes, ⇒Nios II Function Attributes, and ⇒S/390
Function Attributes for details.
1
1 'target_clones (OPTIONS)'
1 The 'target_clones' attribute is used to specify that a function be
1 cloned into multiple versions compiled with different target
1 options than specified on the command line. The supported options
1 and restrictions are the same as for 'target' attribute.
1
1 For instance, on an x86, you could compile a function with
1 'target_clones("sse4.1,avx")'. GCC creates two function clones,
1 one compiled with '-msse4.1' and another with '-mavx'.
1
1 On a PowerPC, you can compile a function with
1 'target_clones("cpu=power9,default")'. GCC will create two
1 function clones, one compiled with '-mcpu=power9' and another with
1 the default options. GCC must be configured to use GLIBC 2.23 or
1 newer in order to use the 'target_clones' attribute.
1
1 It also creates a resolver function (see the 'ifunc' attribute
1 above) that dynamically selects a clone suitable for current
1 architecture. The resolver is created only if there is a usage of
1 a function with 'target_clones' attribute.
1
1 'unused'
1 This attribute, attached to a function, means that the function is
1 meant to be possibly unused. GCC does not produce a warning for
1 this function.
1
1 'used'
1 This attribute, attached to a function, means that code must be
1 emitted for the function even if it appears that the function is
1 not referenced. This is useful, for example, when the function is
1 referenced only in inline assembly.
1
1 When applied to a member function of a C++ class template, the
1 attribute also means that the function is instantiated if the class
1 itself is instantiated.
1
1 'visibility ("VISIBILITY_TYPE")'
1 This attribute affects the linkage of the declaration to which it
1 Attributes::) and types (⇒Common Type Attributes) as well as
1 functions.
1
1 There are four supported VISIBILITY_TYPE values: default, hidden,
1 protected or internal visibility.
1
1 void __attribute__ ((visibility ("protected")))
1 f () { /* Do something. */; }
1 int i __attribute__ ((visibility ("hidden")));
1
1 The possible values of VISIBILITY_TYPE correspond to the visibility
1 settings in the ELF gABI.
1
1 'default'
1 Default visibility is the normal case for the object file
1 format. This value is available for the visibility attribute
1 to override other options that may change the assumed
1 visibility of entities.
1
1 On ELF, default visibility means that the declaration is
1 visible to other modules and, in shared libraries, means that
1 the declared entity may be overridden.
1
1 On Darwin, default visibility means that the declaration is
1 visible to other modules.
1
1 Default visibility corresponds to "external linkage" in the
1 language.
1
1 'hidden'
1 Hidden visibility indicates that the entity declared has a new
1 form of linkage, which we call "hidden linkage". Two
1 declarations of an object with hidden linkage refer to the
1 same object if they are in the same shared object.
1
1 'internal'
1 Internal visibility is like hidden visibility, but with
1 additional processor specific semantics. Unless otherwise
1 specified by the psABI, GCC defines internal visibility to
1 mean that a function is _never_ called from another module.
1 Compare this with hidden functions which, while they cannot be
1 referenced directly by other modules, can be referenced
1 indirectly via function pointers. By indicating that a
1 function cannot be called from outside the module, GCC may for
1 instance omit the load of a PIC register since it is known
1 that the calling function loaded the correct value.
1
1 'protected'
1 Protected visibility is like default visibility except that it
1 indicates that references within the defining module bind to
1 the definition in that module. That is, the declared entity
1 cannot be overridden by another module.
1
1 All visibilities are supported on many, but not all, ELF targets
1 (supported when the assembler supports the '.visibility'
1 pseudo-op). Default visibility is supported everywhere. Hidden
1 visibility is supported on Darwin targets.
1
1 The visibility attribute should be applied only to declarations
1 that would otherwise have external linkage. The attribute should
1 be applied consistently, so that the same entity should not be
1 declared with different settings of the attribute.
1
1 In C++, the visibility attribute applies to types as well as
1 functions and objects, because in C++ types have linkage. A class
1 must not have greater visibility than its non-static data member
1 types and bases, and class members default to the visibility of
1 their class. Also, a declaration without explicit visibility is
1 limited to the visibility of its type.
1
1 In C++, you can mark member functions and static member variables
1 of a class with the visibility attribute. This is useful if you
1 know a particular method or static member variable should only be
1 used from one shared object; then you can mark it hidden while the
1 rest of the class has default visibility. Care must be taken to
1 avoid breaking the One Definition Rule; for example, it is usually
1 not useful to mark an inline method as hidden without marking the
1 whole class as hidden.
1
1 A C++ namespace declaration can also have the visibility attribute.
1
1 namespace nspace1 __attribute__ ((visibility ("protected")))
1 { /* Do something. */; }
1
1 This attribute applies only to the particular namespace body, not
1 to other definitions of the same namespace; it is equivalent to
1 using '#pragma GCC visibility' before and after the namespace
1 definition (⇒Visibility Pragmas).
1
1 In C++, if a template argument has limited visibility, this
1 restriction is implicitly propagated to the template instantiation.
1 Otherwise, template instantiations and specializations default to
1 the visibility of their template.
1
1 If both the template and enclosing class have explicit visibility,
1 the visibility from the template is used.
1
1 'warn_unused_result'
1 The 'warn_unused_result' attribute causes a warning to be emitted
1 if a caller of the function with this attribute does not use its
1 return value. This is useful for functions where not checking the
1 result is either a security problem or always a bug, such as
1 'realloc'.
1
1 int fn () __attribute__ ((warn_unused_result));
1 int foo ()
1 {
1 if (fn () < 0) return -1;
1 fn ();
1 return 0;
1 }
1
1 results in warning on line 5.
1
1 'weak'
1 The 'weak' attribute causes the declaration to be emitted as a weak
1 symbol rather than a global. This is primarily useful in defining
1 library functions that can be overridden in user code, though it
1 can also be used with non-function declarations. Weak symbols are
1 supported for ELF targets, and also for a.out targets when using
1 the GNU assembler and linker.
1
1 'weakref'
1 'weakref ("TARGET")'
1 The 'weakref' attribute marks a declaration as a weak reference.
1 Without arguments, it should be accompanied by an 'alias' attribute
1 naming the target symbol. Optionally, the TARGET may be given as
1 an argument to 'weakref' itself. In either case, 'weakref'
1 implicitly marks the declaration as 'weak'. Without a TARGET,
1 given as an argument to 'weakref' or to 'alias', 'weakref' is
1 equivalent to 'weak'.
1
1 static int x() __attribute__ ((weakref ("y")));
1 /* is equivalent to... */
1 static int x() __attribute__ ((weak, weakref, alias ("y")));
1 /* and to... */
1 static int x() __attribute__ ((weakref));
1 static int x() __attribute__ ((alias ("y")));
1
1 A weak reference is an alias that does not by itself require a
1 definition to be given for the target symbol. If the target symbol
1 is only referenced through weak references, then it becomes a
1 'weak' undefined symbol. If it is directly referenced, however,
1 then such strong references prevail, and a definition is required
1 for the symbol, not necessarily in the same translation unit.
1
1 The effect is equivalent to moving all references to the alias to a
1 separate translation unit, renaming the alias to the aliased
1 symbol, declaring it as weak, compiling the two separate
1 translation units and performing a reloadable link on them.
1
1 At present, a declaration to which 'weakref' is attached can only
1 be 'static'.
1