1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
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>
|
