diff options
| author | alk3pInjection <webmaster@raspii.tech> | 2024-02-04 16:16:35 +0800 |
|---|---|---|
| committer | alk3pInjection <webmaster@raspii.tech> | 2024-02-04 16:16:35 +0800 |
| commit | abdaadbcae30fe0c9a66c7516798279fdfd97750 (patch) | |
| tree | 00a54a6e25601e43876d03c1a4a12a749d4a914c /share/doc/gcc/Common-Variable-Attributes.html | |
https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads
Change-Id: I7303388733328cd98ab9aa3c30236db67f2e9e9c
Diffstat (limited to 'share/doc/gcc/Common-Variable-Attributes.html')
| -rw-r--r-- | share/doc/gcc/Common-Variable-Attributes.html | 666 |
1 files changed, 666 insertions, 0 deletions
diff --git a/share/doc/gcc/Common-Variable-Attributes.html b/share/doc/gcc/Common-Variable-Attributes.html new file mode 100644 index 0000000..65b9ea3 --- /dev/null +++ b/share/doc/gcc/Common-Variable-Attributes.html @@ -0,0 +1,666 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- This file documents the use of the GNU compilers. + +Copyright (C) 1988-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Funding Free Software", the Front-Cover +Texts being (a) (see below), and with the Back-Cover Texts being (b) +(see below). A copy of the license is included in the section entitled +"GNU Free Documentation License". + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>Using the GNU Compiler Collection (GCC): Common Variable Attributes</title> + +<meta name="description" content="Using the GNU Compiler Collection (GCC): Common Variable Attributes"> +<meta name="keywords" content="Using the GNU Compiler Collection (GCC): Common Variable Attributes"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Indices.html#Indices" rel="index" title="Indices"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Variable-Attributes.html#Variable-Attributes" rel="up" title="Variable Attributes"> +<link href="ARC-Variable-Attributes.html#ARC-Variable-Attributes" rel="next" title="ARC Variable Attributes"> +<link href="Variable-Attributes.html#Variable-Attributes" rel="previous" title="Variable Attributes"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en_US" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Common-Variable-Attributes"></a> +<div class="header"> +<p> +Next: <a href="ARC-Variable-Attributes.html#ARC-Variable-Attributes" accesskey="n" rel="next">ARC Variable Attributes</a>, Up: <a href="Variable-Attributes.html#Variable-Attributes" accesskey="u" rel="up">Variable Attributes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html#Indices" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Common-Variable-Attributes-1"></a> +<h4 class="subsection">6.34.1 Common Variable Attributes</h4> + +<p>The following attributes are supported on most targets. +</p> +<dl compact="compact"> +<dd> +<a name="index-alias-variable-attribute"></a> +</dd> +<dt><code>alias ("<var>target</var>")</code></dt> +<dd><p>The <code>alias</code> variable attribute causes the declaration to be emitted +as an alias for another symbol known as an <em>alias target</em>. Except +for top-level qualifiers the alias target must have the same type as +the alias. For instance, the following +</p> +<div class="smallexample"> +<pre class="smallexample">int var_target; +extern int __attribute__ ((alias ("var_target"))) var_alias; +</pre></div> + +<p>defines <code>var_alias</code> to be an alias for the <code>var_target</code> variable. +</p> +<p>It is an error if the alias target is not defined in the same translation +unit as the alias. +</p> +<p>Note that in the absence of the attribute GCC assumes that distinct +declarations with external linkage denote distinct objects. Using both +the alias and the alias target to access the same object is undefined +in a translation unit without a declaration of the alias with the attribute. +</p> +<p>This attribute requires assembler and object file support, and may not be +available on all targets. +</p> +<a name="index-aligned-variable-attribute"></a> +</dd> +<dt><code>aligned</code></dt> +<dt><code>aligned (<var>alignment</var>)</code></dt> +<dd><p>The <code>aligned</code> attribute specifies a minimum alignment for the variable +or structure field, measured in bytes. When specified, <var>alignment</var> must +be an integer constant power of 2. Specifying no <var>alignment</var> argument +implies the maximum alignment for the target, which is often, but by no +means always, 8 or 16 bytes. +</p> +<p>For example, the declaration: +</p> +<div class="smallexample"> +<pre class="smallexample">int x __attribute__ ((aligned (16))) = 0; +</pre></div> + +<p>causes the compiler to allocate the global variable <code>x</code> on a +16-byte boundary. On a 68040, this could be used in conjunction with +an <code>asm</code> expression to access the <code>move16</code> instruction which +requires 16-byte aligned operands. +</p> +<p>You can also specify the alignment of structure fields. For example, to +create a double-word aligned <code>int</code> pair, you could write: +</p> +<div class="smallexample"> +<pre class="smallexample">struct foo { int x[2] __attribute__ ((aligned (8))); }; +</pre></div> + +<p>This is an alternative to creating a union with a <code>double</code> member, +which forces the union to be double-word aligned. +</p> +<p>As in the preceding examples, you can explicitly specify the alignment +(in bytes) that you wish the compiler to use for a given variable or +structure field. Alternatively, you can leave out the alignment factor +and just ask the compiler to align a variable or field to the +default alignment for the target architecture you are compiling for. +The default alignment is sufficient for all scalar types, but may not be +enough for all vector types on a target that supports vector operations. +The default alignment is fixed for a particular target ABI. +</p> +<p>GCC also provides a target specific macro <code>__BIGGEST_ALIGNMENT__</code>, +which is the largest alignment ever used for any data type on the +target machine you are compiling for. For example, you could write: +</p> +<div class="smallexample"> +<pre class="smallexample">short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__))); +</pre></div> + +<p>The compiler automatically sets the alignment for the declared +variable or field to <code>__BIGGEST_ALIGNMENT__</code>. Doing this can +often make copy operations more efficient, because the compiler can +use whatever instructions copy the biggest chunks of memory when +performing copies to or from the variables or fields that you have +aligned this way. Note that the value of <code>__BIGGEST_ALIGNMENT__</code> +may change depending on command-line options. +</p> +<p>When used on a struct, or struct member, the <code>aligned</code> attribute can +only increase the alignment; in order to decrease it, the <code>packed</code> +attribute must be specified as well. When used as part of a typedef, the +<code>aligned</code> attribute can both increase and decrease alignment, and +specifying the <code>packed</code> attribute generates a warning. +</p> +<p>Note that the effectiveness of <code>aligned</code> attributes for static +variables may be limited by inherent limitations in the system linker +and/or object file format. On some systems, the linker is +only able to arrange for variables to be aligned up to a certain maximum +alignment. (For some linkers, the maximum supported alignment may +be very very small.) If your linker is only able to align variables +up to a maximum of 8-byte alignment, then specifying <code>aligned(16)</code> +in an <code>__attribute__</code> still only provides you with 8-byte +alignment. See your linker documentation for further information. +</p> +<p>Stack variables are not affected by linker restrictions; GCC can properly +align them on any target. +</p> +<p>The <code>aligned</code> attribute can also be used for functions +(see <a href="Common-Function-Attributes.html#Common-Function-Attributes">Common Function Attributes</a>.) +</p> +<a name="index-warn_005fif_005fnot_005faligned-variable-attribute"></a> +</dd> +<dt><code>warn_if_not_aligned (<var>alignment</var>)</code></dt> +<dd><p>This attribute specifies a threshold for the structure field, measured +in bytes. If the structure field is aligned below the threshold, a +warning will be issued. For example, the declaration: +</p> +<div class="smallexample"> +<pre class="smallexample">struct foo +{ + int i1; + int i2; + unsigned long long x __attribute__ ((warn_if_not_aligned (16))); +}; +</pre></div> + +<p>causes the compiler to issue an warning on <code>struct foo</code>, like +‘<samp>warning: alignment 8 of 'struct foo' is less than 16</samp>’. +The compiler also issues a warning, like ‘<samp>warning: 'x' offset +8 in 'struct foo' isn't aligned to 16</samp>’, when the structure field has +the misaligned offset: +</p> +<div class="smallexample"> +<pre class="smallexample">struct __attribute__ ((aligned (16))) foo +{ + int i1; + int i2; + unsigned long long x __attribute__ ((warn_if_not_aligned (16))); +}; +</pre></div> + +<p>This warning can be disabled by <samp>-Wno-if-not-aligned</samp>. +The <code>warn_if_not_aligned</code> attribute can also be used for types +(see <a href="Common-Type-Attributes.html#Common-Type-Attributes">Common Type Attributes</a>.) +</p> +<a name="index-strict_005fflex_005farray-variable-attribute"></a> +</dd> +<dt><code>strict_flex_array (<var>level</var>)</code></dt> +<dd><p>The <code>strict_flex_array</code> attribute should be attached to the trailing +array field of a structure. It controls when to treat the trailing array +field of a structure as a flexible array member for the purposes of accessing +the elements of such an array. +<var>level</var> must be an integer betwen 0 to 3. +</p> +<p><var>level</var>=0 is the least strict level, all trailing arrays of structures +are treated as flexible array members. <var>level</var>=3 is the strictest level, +only when the trailing array is declared as a flexible array member per C99 +standard onwards (‘<samp>[]</samp>’), it is treated as a flexible array member. +</p> +<p>There are two more levels in between 0 and 3, which are provided to support +older codes that use GCC zero-length array extension (‘<samp>[0]</samp>’) or one-element +array as flexible array members (‘<samp>[1]</samp>’): +When <var>level</var> is 1, the trailing array is treated as a flexible array member +when it is declared as either ‘<samp>[]</samp>’, ‘<samp>[0]</samp>’, or ‘<samp>[1]</samp>’; +When <var>level</var> is 2, the trailing array is treated as a flexible array member +when it is declared as either ‘<samp>[]</samp>’, or ‘<samp>[0]</samp>’. +</p> +<p>This attribute can be used with or without the <samp>-fstrict-flex-arrays</samp>. +When both the attribute and the option present at the same time, the level of +the strictness for the specific trailing array field is determined by the +attribute. +</p> +<a name="index-alloc_005fsize-variable-attribute"></a> +</dd> +<dt><code>alloc_size (<var>position</var>)</code></dt> +<dt><code>alloc_size (<var>position-1</var>, <var>position-2</var>)</code></dt> +<dd><p>The <code>alloc_size</code> variable attribute may be applied to the declaration +of a pointer to a function that returns a pointer and takes at least one +argument of an integer type. It indicates that the returned pointer points +to an object whose size is given by the function argument at <var>position</var>, +or by the product of the arguments at <var>position-1</var> and <var>position-2</var>. +Meaningful sizes are positive values less than <code>PTRDIFF_MAX</code>. Other +sizes are diagnosed when detected. GCC uses this information to improve +the results of <code>__builtin_object_size</code>. +</p> +<p>For instance, the following declarations +</p> +<div class="smallexample"> +<pre class="smallexample">typedef __attribute__ ((alloc_size (1, 2))) void* + (*calloc_ptr) (size_t, size_t); +typedef __attribute__ ((alloc_size (1))) void* + (*malloc_ptr) (size_t); +</pre></div> + +<p>specify that <code>calloc_ptr</code> is a pointer of a function that, like +the standard C function <code>calloc</code>, returns an object whose size +is given by the product of arguments 1 and 2, and similarly, that +<code>malloc_ptr</code>, like the standard C function <code>malloc</code>, +returns an object whose size is given by argument 1 to the function. +</p> +<a name="index-cleanup-variable-attribute"></a> +</dd> +<dt><code>cleanup (<var>cleanup_function</var>)</code></dt> +<dd><p>The <code>cleanup</code> attribute runs a function when the variable goes +out of scope. This attribute can only be applied to auto function +scope variables; it may not be applied to parameters or variables +with static storage duration. The function must take one parameter, +a pointer to a type compatible with the variable. The return value +of the function (if any) is ignored. +</p> +<p>If <samp>-fexceptions</samp> is enabled, then <var>cleanup_function</var> +is run during the stack unwinding that happens during the +processing of the exception. Note that the <code>cleanup</code> attribute +does not allow the exception to be caught, only to perform an action. +It is undefined what happens if <var>cleanup_function</var> does not +return normally. +</p> +<a name="index-common-variable-attribute"></a> +<a name="index-nocommon-variable-attribute"></a> +<a name="index-fcommon-1"></a> +<a name="index-fno_002dcommon-1"></a> +</dd> +<dt><code>common</code></dt> +<dt><code>nocommon</code></dt> +<dd><p>The <code>common</code> attribute requests GCC to place a variable in +“common” storage. The <code>nocommon</code> attribute requests the +opposite—to allocate space for it directly. +</p> +<p>These attributes override the default chosen by the +<samp>-fno-common</samp> and <samp>-fcommon</samp> flags respectively. +</p> +<a name="index-copy-variable-attribute"></a> +</dd> +<dt><code>copy</code></dt> +<dt><code>copy (<var>variable</var>)</code></dt> +<dd><p>The <code>copy</code> attribute applies the set of attributes with which +<var>variable</var> has been declared to the declaration of the variable +to which the attribute is applied. The attribute is designed for +libraries that define aliases that are expected to specify the same +set of attributes as the aliased symbols. The <code>copy</code> attribute +can be used with variables, functions or types. However, the kind +of symbol to which the attribute is applied (either varible or +function) must match the kind of symbol to which the argument refers. +The <code>copy</code> attribute copies only syntactic and semantic attributes +but not attributes that affect a symbol’s linkage or visibility such as +<code>alias</code>, <code>visibility</code>, or <code>weak</code>. The <code>deprecated</code> +attribute is also not copied. See <a href="Common-Function-Attributes.html#Common-Function-Attributes">Common Function Attributes</a>. +See <a href="Common-Type-Attributes.html#Common-Type-Attributes">Common Type Attributes</a>. +</p> +<a name="index-deprecated-variable-attribute"></a> +</dd> +<dt><code>deprecated</code></dt> +<dt><code>deprecated (<var>msg</var>)</code></dt> +<dd><p>The <code>deprecated</code> attribute results in a warning if the variable +is used anywhere in the source file. This is useful when identifying +variables that are expected to be removed in a future version of a +program. The warning also includes the location of the declaration +of the deprecated variable, to enable users to easily find further +information about why the variable is deprecated, or what they should +do instead. Note that the warning only occurs for uses: +</p> +<div class="smallexample"> +<pre class="smallexample">extern int old_var __attribute__ ((deprecated)); +extern int old_var; +int new_fn () { return old_var; } +</pre></div> + +<p>results in a warning on line 3 but not line 2. The optional <var>msg</var> +argument, which must be a string, is printed in the warning if +present. +</p> +<p>The <code>deprecated</code> attribute can also be used for functions and +types (see <a href="Common-Function-Attributes.html#Common-Function-Attributes">Common Function Attributes</a>, +see <a href="Common-Type-Attributes.html#Common-Type-Attributes">Common Type Attributes</a>). +</p> +<p>The message attached to the attribute is affected by the setting of +the <samp>-fmessage-length</samp> option. +</p> +<a name="index-unavailable-variable-attribute"></a> +</dd> +<dt><code>unavailable</code></dt> +<dt><code>unavailable (<var>msg</var>)</code></dt> +<dd><p>The <code>unavailable</code> attribute indicates that the variable so marked +is not available, if it is used anywhere in the source file. It behaves +in the same manner as the <code>deprecated</code> attribute except that the +compiler will emit an error rather than a warning. +</p> +<p>It is expected that items marked as <code>deprecated</code> will eventually be +withdrawn from interfaces, and then become unavailable. This attribute +allows for marking them appropriately. +</p> +<p>The <code>unavailable</code> attribute can also be used for functions and +types (see <a href="Common-Function-Attributes.html#Common-Function-Attributes">Common Function Attributes</a>, +see <a href="Common-Type-Attributes.html#Common-Type-Attributes">Common Type Attributes</a>). +</p> +<a name="index-mode-variable-attribute"></a> +</dd> +<dt><code>mode (<var>mode</var>)</code></dt> +<dd><p>This attribute specifies the data type for the declaration—whichever +type corresponds to the mode <var>mode</var>. This in effect lets you +request an integer or floating-point type according to its width. +</p> +<p>See <a href="http://gcc.gnu.org/onlinedocs/gccint/Machine-Modes.html#Machine-Modes">Machine Modes</a> in <cite>GNU Compiler Collection (GCC) Internals</cite>, +for a list of the possible keywords for <var>mode</var>. +You may also specify a mode of <code>byte</code> or <code>__byte__</code> to +indicate the mode corresponding to a one-byte integer, <code>word</code> or +<code>__word__</code> for the mode of a one-word integer, and <code>pointer</code> +or <code>__pointer__</code> for the mode used to represent pointers. +</p> +<a name="index-nonstring-variable-attribute"></a> +</dd> +<dt><code>nonstring</code></dt> +<dd><p>The <code>nonstring</code> variable attribute specifies that an object or member +declaration with type array of <code>char</code>, <code>signed char</code>, or +<code>unsigned char</code>, or pointer to such a type is intended to store +character arrays that do not necessarily contain a terminating <code>NUL</code>. +This is useful in detecting uses of such arrays or pointers with functions +that expect <code>NUL</code>-terminated strings, and to avoid warnings when such +an array or pointer is used as an argument to a bounded string manipulation +function such as <code>strncpy</code>. For example, without the attribute, GCC +will issue a warning for the <code>strncpy</code> call below because it may +truncate the copy without appending the terminating <code>NUL</code> character. +Using the attribute makes it possible to suppress the warning. However, +when the array is declared with the attribute the call to <code>strlen</code> is +diagnosed because when the array doesn’t contain a <code>NUL</code>-terminated +string the call is undefined. To copy, compare, of search non-string +character arrays use the <code>memcpy</code>, <code>memcmp</code>, <code>memchr</code>, +and other functions that operate on arrays of bytes. In addition, +calling <code>strnlen</code> and <code>strndup</code> with such arrays is safe +provided a suitable bound is specified, and not diagnosed. +</p> +<div class="smallexample"> +<pre class="smallexample">struct Data +{ + char name [32] __attribute__ ((nonstring)); +}; + +int f (struct Data *pd, const char *s) +{ + strncpy (pd->name, s, sizeof pd->name); + … + return strlen (pd->name); // unsafe, gets a warning +} +</pre></div> + +<a name="index-packed-variable-attribute"></a> +</dd> +<dt><code>packed</code></dt> +<dd><p>The <code>packed</code> attribute specifies that a structure member should have +the smallest possible alignment—one bit for a bit-field and one byte +otherwise, unless a larger value is specified with the <code>aligned</code> +attribute. The attribute does not apply to non-member objects. +</p> +<p>For example in the structure below, the member array <code>x</code> is packed +so that it immediately follows <code>a</code> with no intervening padding: +</p> +<div class="smallexample"> +<pre class="smallexample">struct foo +{ + char a; + int x[2] __attribute__ ((packed)); +}; +</pre></div> + +<p><em>Note:</em> The 4.1, 4.2 and 4.3 series of GCC ignore the +<code>packed</code> attribute on bit-fields of type <code>char</code>. This has +been fixed in GCC 4.4 but the change can lead to differences in the +structure layout. See the documentation of +<samp>-Wpacked-bitfield-compat</samp> for more information. +</p> +<a name="index-section-variable-attribute"></a> +</dd> +<dt><code>section ("<var>section-name</var>")</code></dt> +<dd><p>Normally, the compiler places the objects it generates in sections like +<code>data</code> and <code>bss</code>. Sometimes, however, you need additional sections, +or you need certain particular variables to appear in special sections, +for example to map to special hardware. The <code>section</code> +attribute specifies that a variable (or function) lives in a particular +section. For example, this small program uses several specific section names: +</p> +<div class="smallexample"> +<pre class="smallexample">struct duart a __attribute__ ((section ("DUART_A"))) = { 0 }; +struct duart b __attribute__ ((section ("DUART_B"))) = { 0 }; +char stack[10000] __attribute__ ((section ("STACK"))) = { 0 }; +int init_data __attribute__ ((section ("INITDATA"))); + +main() +{ + /* <span class="roman">Initialize stack pointer</span> */ + init_sp (stack + sizeof (stack)); + + /* <span class="roman">Initialize initialized data</span> */ + memcpy (&init_data, &data, &edata - &data); + + /* <span class="roman">Turn on the serial ports</span> */ + init_duart (&a); + init_duart (&b); +} +</pre></div> + +<p>Use the <code>section</code> attribute with +<em>global</em> variables and not <em>local</em> variables, +as shown in the example. +</p> +<p>You may use the <code>section</code> attribute with initialized or +uninitialized global variables but the linker requires +each object be defined once, with the exception that uninitialized +variables tentatively go in the <code>common</code> (or <code>bss</code>) section +and can be multiply “defined”. Using the <code>section</code> attribute +changes what section the variable goes into and may cause the +linker to issue an error if an uninitialized variable has multiple +definitions. You can force a variable to be initialized with the +<samp>-fno-common</samp> flag or the <code>nocommon</code> attribute. +</p> +<p>Some file formats do not support arbitrary sections so the <code>section</code> +attribute is not available on all platforms. +If you need to map the entire contents of a module to a particular +section, consider using the facilities of the linker instead. +</p> +<a name="index-tls_005fmodel-variable-attribute"></a> +</dd> +<dt><code>tls_model ("<var>tls_model</var>")</code></dt> +<dd><p>The <code>tls_model</code> attribute sets thread-local storage model +(see <a href="Thread_002dLocal.html#Thread_002dLocal">Thread-Local</a>) of a particular <code>__thread</code> variable, +overriding <samp>-ftls-model=</samp> command-line switch on a per-variable +basis. +The <var>tls_model</var> argument should be one of <code>global-dynamic</code>, +<code>local-dynamic</code>, <code>initial-exec</code> or <code>local-exec</code>. +</p> +<p>Not all targets support this attribute. +</p> +<a name="index-unused-variable-attribute"></a> +</dd> +<dt><code>unused</code></dt> +<dd><p>This attribute, attached to a variable or structure field, means that +the variable or field is meant to be possibly unused. GCC does not +produce a warning for this variable or field. +</p> +<a name="index-used-variable-attribute"></a> +</dd> +<dt><code>used</code></dt> +<dd><p>This attribute, attached to a variable with static storage, means that +the variable must be emitted even if it appears that the variable is not +referenced. +</p> +<p>When applied to a static data member of a C++ class template, the +attribute also means that the member is instantiated if the +class itself is instantiated. +</p> +<a name="index-retain-variable-attribute"></a> +</dd> +<dt><code>retain</code></dt> +<dd><p>For ELF targets that support the GNU or FreeBSD OSABIs, this attribute +will save the variable from linker garbage collection. To support +this behavior, variables that have not been placed in specific sections +(e.g. by the <code>section</code> attribute, or the <code>-fdata-sections</code> option), +will be placed in new, unique sections. +</p> +<p>This additional functionality requires Binutils version 2.36 or later. +</p> +<a name="index-uninitialized-variable-attribute"></a> +</dd> +<dt><code>uninitialized</code></dt> +<dd><p>This attribute, attached to a variable with automatic storage, means that +the variable should not be automatically initialized by the compiler when +the option <code>-ftrivial-auto-var-init</code> presents. +</p> +<p>With the option <code>-ftrivial-auto-var-init</code>, all the automatic variables +that do not have explicit initializers will be initialized by the compiler. +These additional compiler initializations might incur run-time overhead, +sometimes dramatically. This attribute can be used to mark some variables +to be excluded from such automatical initialization in order to reduce runtime +overhead. +</p> +<p>This attribute has no effect when the option <code>-ftrivial-auto-var-init</code> +does not present. +</p> +<a name="index-vector_005fsize-variable-attribute"></a> +</dd> +<dt><code>vector_size (<var>bytes</var>)</code></dt> +<dd><p>This attribute specifies the vector size for the type of the declared +variable, measured in bytes. The type to which it applies is known as +the <em>base type</em>. The <var>bytes</var> argument must be a positive +power-of-two multiple of the base type size. For example, the declaration: +</p> +<div class="smallexample"> +<pre class="smallexample">int foo __attribute__ ((vector_size (16))); +</pre></div> + +<p>causes the compiler to set the mode for <code>foo</code>, to be 16 bytes, +divided into <code>int</code> sized units. Assuming a 32-bit <code>int</code>, +<code>foo</code>’s type is a vector of four units of four bytes each, and +the corresponding mode of <code>foo</code> is <code>V4SI</code>. +See <a href="Vector-Extensions.html#Vector-Extensions">Vector Extensions</a>, for details of manipulating vector variables. +</p> +<p>This attribute is only applicable to integral and floating scalars, +although arrays, pointers, and function return values are allowed in +conjunction with this construct. +</p> +<p>Aggregates with this attribute are invalid, even if they are of the same +size as a corresponding scalar. For example, the declaration: +</p> +<div class="smallexample"> +<pre class="smallexample">struct S { int a; }; +struct S __attribute__ ((vector_size (16))) foo; +</pre></div> + +<p>is invalid even if the size of the structure is the same as the size of +the <code>int</code>. +</p> +<a name="index-visibility-variable-attribute"></a> +</dd> +<dt><code>visibility ("<var>visibility_type</var>")</code></dt> +<dd><p>This attribute affects the linkage of the declaration to which it is attached. +The <code>visibility</code> attribute is described in +<a href="Common-Function-Attributes.html#Common-Function-Attributes">Common Function Attributes</a>. +</p> +<a name="index-weak-variable-attribute"></a> +</dd> +<dt><code>weak</code></dt> +<dd><p>The <code>weak</code> attribute is described in +<a href="Common-Function-Attributes.html#Common-Function-Attributes">Common Function Attributes</a>. +</p> +<a name="index-noinit-variable-attribute"></a> +</dd> +<dt><code>noinit</code></dt> +<dd><p>Any data with the <code>noinit</code> attribute will not be initialized by +the C runtime startup code, or the program loader. Not initializing +data in this way can reduce program startup times. +</p> +<p>This attribute is specific to ELF targets and relies on the linker +script to place sections with the <code>.noinit</code> prefix in the right +location. +</p> +<a name="index-persistent-variable-attribute"></a> +</dd> +<dt><code>persistent</code></dt> +<dd><p>Any data with the <code>persistent</code> attribute will not be initialized by +the C runtime startup code, but will be initialized by the program +loader. This enables the value of the variable to ‘<samp>persist</samp>’ +between processor resets. +</p> +<p>This attribute is specific to ELF targets and relies on the linker +script to place the sections with the <code>.persistent</code> prefix in the +right location. Specifically, some type of non-volatile, writeable +memory is required. +</p> +<a name="index-objc_005fnullability-variable-attribute"></a> +</dd> +<dt><code>objc_nullability (<var>nullability kind</var>) <span class="roman">(Objective-C and Objective-C++ only)</span></code></dt> +<dd><p>This attribute applies to pointer variables only. It allows marking the +pointer with one of four possible values describing the conditions under +which the pointer might have a <code>nil</code> value. In most cases, the +attribute is intended to be an internal representation for property and +method nullability (specified by language keywords); it is not recommended +to use it directly. +</p> +<p>When <var>nullability kind</var> is <code>"unspecified"</code> or <code>0</code>, nothing is +known about the conditions in which the pointer might be <code>nil</code>. Making +this state specific serves to avoid false positives in diagnostics. +</p> +<p>When <var>nullability kind</var> is <code>"nonnull"</code> or <code>1</code>, the pointer has +no meaning if it is <code>nil</code> and thus the compiler is free to emit +diagnostics if it can be determined that the value will be <code>nil</code>. +</p> +<p>When <var>nullability kind</var> is <code>"nullable"</code> or <code>2</code>, the pointer might +be <code>nil</code> and carry meaning as such. +</p> +<p>When <var>nullability kind</var> is <code>"resettable"</code> or <code>3</code> (used only in +the context of property attribute lists) this describes the case in which a +property setter may take the value <code>nil</code> (which perhaps causes the +property to be reset in some manner to a default) but for which the property +getter will never validly return <code>nil</code>. +</p> +</dd> +</dl> + +<hr> +<div class="header"> +<p> +Next: <a href="ARC-Variable-Attributes.html#ARC-Variable-Attributes" accesskey="n" rel="next">ARC Variable Attributes</a>, Up: <a href="Variable-Attributes.html#Variable-Attributes" accesskey="u" rel="up">Variable Attributes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html#Indices" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |