Pragmas Accepted by GCC#
GCC supports several types of pragmas, primarily in order to compile code originally written for other compilers. Note that in general we do not recommend the use of pragmas; See Declaring Attributes of Functions, for further explanation.
The GNU C preprocessor recognizes several pragmas in addition to the compiler pragmas documented here. Refer to the CPP manual for more information.
AArch64 Pragmas#
The pragmas defined by the AArch64 target correspond to the AArch64 target function attributes. They can be specified as below:
#pragma GCC target("string")
where string
can be any string accepted as an AArch64 target
attribute. See AArch64 Function Attributes, for more details
on the permissible values of string
.
ARM Pragmas#
The ARM target defines pragmas for controlling the default addition of
long_call
and short_call
attributes to functions.
See Declaring Attributes of Functions, for information about the effects of these
attributes.
long_calls
Set all subsequent functions to have the
long_call
attribute.
no_long_calls
Set all subsequent functions to have the
short_call
attribute.
long_calls_off
Do not affect the
long_call
orshort_call
attributes of subsequent functions.
M32C Pragmas#
GCC memregs number
Overrides the command-line option
-memregs=
for the current file. Use with care! This pragma must be before any function in the file, and mixing different memregs values in different objects may make them incompatible. This pragma is useful when a performance-critical function uses a memreg for temporary values, as it may allow you to reduce the number of memregs used.
ADDRESS nameaddress
For any declared symbols matching
name
, this does three things to that symbol: it forces the symbol to be located at the given address (a number), it forces the symbol to be volatile, and it changes the symbol’s scope to be static. This pragma exists for compatibility with other compilers, but note that the common1234H
numeric syntax is not supported (use0x1234
instead). Example:#pragma ADDRESS port3 0x103 char port3;
MeP Pragmas#
custom io_volatile (on|off)
Overrides the command-line option
-mio-volatile
for the current file. Note that for compatibility with future GCC releases, this option should only be used once before anyio
variables in each file.
GCC coprocessor available registers
Specifies which coprocessor registers are available to the register allocator.
registers
may be a single register, register range separated by ellipses, or comma-separated list of those. Example:#pragma GCC coprocessor available $c0...$c10, $c28
GCC coprocessor call_saved registers
Specifies which coprocessor registers are to be saved and restored by any function using them.
registers
may be a single register, register range separated by ellipses, or comma-separated list of those. Example:#pragma GCC coprocessor call_saved $c4...$c6, $c31
GCC coprocessor subclass '(A|B|C|D)' = registers
Creates and defines a register class. These register classes can be used by inline
asm
constructs.registers
may be a single register, register range separated by ellipses, or comma-separated list of those. Example:#pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6 asm ("cpfoo %0" : "=B" (x));
GCC disinterrupt name , name ...
For the named functions, the compiler adds code to disable interrupts for the duration of those functions. If any functions so named are not encountered in the source, a warning is emitted that the pragma is not used. Examples:
#pragma disinterrupt foo #pragma disinterrupt bar, grill int foo () { ... }
GCC call name , name ...
For the named functions, the compiler always uses a register-indirect call model when calling the named functions. Examples:
extern int foo (); #pragma call foo
PRU Pragmas#
ctable_entry indexconstant_address
Specifies that the PRU CTABLE entry given by
index
has the valueconstant_address
. This enables GCC to emit LBCO/SBCO instructions when the load/store address is known and can be addressed with some CTABLE entry. For example:/* will compile to "sbco Rx, 2, 0x10, 4" */ #pragma ctable_entry 2 0x4802a000 *(unsigned int *)0x4802a010 = val;
RS/6000 and PowerPC Pragmas#
The RS/6000 and PowerPC targets define one pragma for controlling
whether or not the longcall
attribute is added to function
declarations by default. This pragma overrides the -mlongcall
option, but not the longcall
and shortcall
attributes.
See IBM RS/6000 and PowerPC Options, for more information about when long
calls are and are not necessary.
longcall (1)
Apply the
longcall
attribute to all subsequent function declarations.
longcall (0)
Do not apply the
longcall
attribute to subsequent function declarations.
S/390 Pragmas#
The pragmas defined by the S/390 target correspond to the S/390 target function attributes and some the additional options:
zvector
no-zvector
Note that options of the pragma, unlike options of the target
attribute, do change the value of preprocessor macros like
__VEC__
. They can be specified as below:
#pragma GCC target("string[,string]...")
#pragma GCC target("string"[,"string"]...)
Darwin Pragmas#
The following pragmas are available for all architectures running the Darwin operating system. These are useful for compatibility with other Mac OS compilers.
mark tokens...
This pragma is accepted, but has no effect.
options align=alignment
This pragma sets the alignment of fields in structures. The values of
alignment
may bemac68k
, to emulate m68k alignment, orpower
, to emulate PowerPC alignment. Uses of this pragma nest properly; to restore the previous setting, usereset
for thealignment
.
segment tokens...
This pragma is accepted, but has no effect.
unused (var [, var]...)
This pragma declares variables to be possibly unused. GCC does not produce warnings for the listed variables. The effect is similar to that of the
unused
attribute, except that this pragma may appear anywhere within the variables’ scopes.
Solaris Pragmas#
The Solaris target supports #pragma redefine_extname
(see Symbol-Renaming Pragmas). It also supports additional
#pragma
directives for compatibility with the system compiler.
align alignment (variable [, variable]...)
Increase the minimum alignment of each
variable
toalignment
. This is the same as GCC’saligned
attribute see Specifying Attributes of Variables). Macro expansion occurs on the arguments to this pragma when compiling C and Objective-C. It does not currently occur when compiling C++, but this is a bug which may be fixed in a future release.
fini (function [, function]...)
This pragma causes each listed
function
to be called after main, or during shared module unloading, by adding a call to the.fini
section.
init (function [, function]...)
This pragma causes each listed
function
to be called during initialization (beforemain
) or during shared module loading, by adding a call to the.init
section.
Symbol-Renaming Pragmas#
GCC supports a #pragma
directive that changes the name used in
assembly for a given declaration. While this pragma is supported on all
platforms, it is intended primarily to provide compatibility with the
Solaris system headers. This effect can also be achieved using the asm
labels extension (see Controlling Names Used in Assembler Code).
redefine_extname oldnamenewname
This pragma gives the C function
oldname
the assembly symbolnewname
. The preprocessor macro__PRAGMA_REDEFINE_EXTNAME
is defined if this pragma is available (currently on all platforms).
This pragma and the asm
labels extension interact in a complicated
manner. Here are some corner cases you may want to be aware of:
This pragma silently applies only to declarations with external linkage. The
asm
label feature does not have this restriction.In C++, this pragma silently applies only to declarations with ‘C’ linkage. Again,
asm
labels do not have this restriction.If either of the ways of changing the assembly name of a declaration are applied to a declaration whose assembly name has already been determined (either by a previous use of one of these features, or because the compiler needed the assembly name in order to generate code), and the new name is different, a warning issues and the name does not change.
The
oldname
used by#pragma redefine_extname
is always the C-language name.
Structure-Layout Pragmas#
For compatibility with Microsoft Windows compilers, GCC supports a
set of #pragma
directives that change the maximum alignment of
members of structures (other than zero-width bit-fields), unions, and
classes subsequently defined. The n
value below always is required
to be a small power of two and specifies the new alignment in bytes.
#pragma pack(n)
simply sets the new alignment.#pragma pack()
sets the alignment to the one that was in effect when compilation started (see also command-line option-fpack-struct[=n]
see Options for Code Generation Conventions).#pragma pack(push[,n])
pushes the current alignment setting on an internal stack and then optionally sets the new alignment.#pragma pack(pop)
restores the alignment setting to the one saved at the top of the internal stack (and removes that stack entry). Note that#pragma pack([n])
does not influence this internal stack; thus it is possible to have#pragma pack(push)
followed by multiple#pragma pack(n)
instances and finalized by a single#pragma pack(pop)
.
Some targets, e.g. x86 and PowerPC, support the #pragma ms_struct
directive which lays out structures and unions subsequently defined as the
documented __attribute__ ((ms_struct))
.
#pragma ms_struct on
turns on the Microsoft layout.#pragma ms_struct off
turns off the Microsoft layout.#pragma ms_struct reset
goes back to the default layout.
Most targets also support the #pragma scalar_storage_order
directive
which lays out structures and unions subsequently defined as the documented
__attribute__ ((scalar_storage_order))
.
#pragma scalar_storage_order big-endian
sets the storage order of the scalar fields to big-endian.#pragma scalar_storage_order little-endian
sets the storage order of the scalar fields to little-endian.#pragma scalar_storage_order default
goes back to the endianness that was in effect when compilation started (see also command-line option-fsso-struct=endianness
see Options Controlling C Dialect).
Weak Pragmas#
For compatibility with SVR4, GCC supports a set of #pragma
directives for declaring symbols to be weak, and defining weak
aliases.
#pragma weak symbol
This pragma declares
symbol
to be weak, as if the declaration had the attribute of the same name. The pragma may appear before or after the declaration ofsymbol
. It is not an error forsymbol
to never be defined at all.#pragma weak symbol1 = symbol2
This pragma declares
symbol1
to be a weak alias ofsymbol2
. It is an error ifsymbol2
is not defined in the current translation unit.
Diagnostic Pragmas#
GCC allows the user to selectively enable or disable certain types of
diagnostics, and change the kind of the diagnostic. For example, a
project’s policy might require that all sources compile with
-Werror
but certain files might have exceptions allowing
specific types of warnings. Or, a project might selectively enable
diagnostics and treat them as errors depending on which preprocessor
macros are defined.
#pragma GCC diagnostic kindoption
Modifies the disposition of a diagnostic. Note that not all diagnostics are modifiable; at the moment only warnings (normally controlled by
-W...
) can be controlled, and not all of them. Use-fdiagnostics-show-option
to determine which diagnostics are controllable and which option controls them.kind
iserror
to treat this diagnostic as an error,warning
to treat it like a warning (even if-Werror
is in effect), orignored
if the diagnostic is to be ignored.option
is a double quoted string that matches the command-line option.#pragma GCC diagnostic warning "-Wformat" #pragma GCC diagnostic error "-Wformat" #pragma GCC diagnostic ignored "-Wformat"
Note that these pragmas override any command-line options. GCC keeps track of the location of each pragma, and issues diagnostics according to the state as of that point in the source file. Thus, pragmas occurring after a line do not affect diagnostics caused by that line.
#pragma GCC diagnostic push
,#pragma GCC diagnostic pop
Causes GCC to remember the state of the diagnostics as of each
push
, and restore to that point at eachpop
. If apop
has no matchingpush
, the command-line options are restored.#pragma GCC diagnostic error "-Wuninitialized" foo(a); /* error is given for this one */ #pragma GCC diagnostic push #pragma GCC diagnostic ignored "-Wuninitialized" foo(b); /* no diagnostic for this one */ #pragma GCC diagnostic pop foo(c); /* error is given for this one */ #pragma GCC diagnostic pop foo(d); /* depends on command-line options */
#pragma GCC diagnostic ignored_attributes
Similarly to
-Wno-attributes=
, this pragma allows users to suppress warnings about unknown scoped attributes (in C++11 and C2X). For example,#pragma GCC diagnostic ignored_attributes "vendor::attr"
disables warning about the following declaration:[[vendor::attr]] void f();
whereas
#pragma GCC diagnostic ignored_attributes "vendor::"
prevents warning about both of these declarations:[[vendor::safe]] void f(); [[vendor::unsafe]] void f2();
GCC also offers a simple mechanism for printing messages during compilation.
#pragma message string
Prints
string
as a compiler message on compilation. The message is informational only, and is neither a compilation warning nor an error. Newlines can be included in the string by using the\n
escape sequence.#pragma message "Compiling " __FILE__ "..."
string
may be parenthesized, and is printed with location information. For example,#define DO_PRAGMA(x) _Pragma (#x) #define TODO(x) DO_PRAGMA(message ("TODO - " #x)) TODO(Remember to fix this)prints
/tmp/file.c:4: note: #pragma message: TODO - Remember to fix this
.
#pragma GCC error message
Generates an error message. This pragma is considered to indicate an error in the compilation, and it will be treated as such.
Newlines can be included in the string by using the
\n
escape sequence. They will be displayed as newlines even if the-fmessage-length
option is set to zero.The error is only generated if the pragma is present in the code after pre-processing has been completed. It does not matter however if the code containing the pragma is unreachable:
#if 0 #pragma GCC error "this error is not seen" #endif void foo (void) { return; #pragma GCC error "this error is seen" }
#pragma GCC warning message
This is just like
pragma GCC error
except that a warning message is issued instead of an error message. Unless-Werror
is in effect, in which case this pragma will generate an error as well.
Visibility Pragmas#
#pragma GCC visibility push(visibility)
, #pragma GCC visibility pop
This pragma allows the user to set the visibility for multiple declarations without having to give each a visibility attribute (see Declaring Attributes of Functions).
In C++,
#pragma GCC visibility
affects only namespace-scope declarations. Class members and template specializations are not affected; if you want to override the visibility for a particular member or instantiation, you must use an attribute.
Push/Pop Macro Pragmas#
For compatibility with Microsoft Windows compilers, GCC supports
#pragma push_macro("macro_name")
and #pragma pop_macro("macro_name")
.
#pragma push_macro("macro_name")
This pragma saves the value of the macro named as
macro_name
to the top of the stack for this macro.
#pragma pop_macro("macro_name")
This pragma sets the value of the macro named as
macro_name
to the value on top of the stack for this macro. If the stack formacro_name
is empty, the value of the macro remains unchanged.For example:
#define X 1
#pragma push_macro("X")
#undef X
#define X -1
#pragma pop_macro("X")
int x [X];
In this example, the definition of X as 1 is saved by #pragma
push_macro
and restored by #pragma pop_macro
.
Function Specific Option Pragmas#
#pragma GCC target (string, ...)
This pragma allows you to set target-specific options for functions defined later in the source file. One or more strings can be specified. Each function that is defined after this point is treated as if it had been declared with one
target(
string
)
attribute for eachstring
argument. The parentheses around the strings in the pragma are optional. See Declaring Attributes of Functions, for more information about thetarget
attribute and the attribute syntax.The
#pragma GCC target
pragma is presently implemented for x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only.
#pragma GCC optimize (string, ...)
This pragma allows you to set global optimization options for functions defined later in the source file. One or more strings can be specified. Each function that is defined after this point is treated as if it had been declared with one
optimize(
string
)
attribute for eachstring
argument. The parentheses around the strings in the pragma are optional. See Declaring Attributes of Functions, for more information about theoptimize
attribute and the attribute syntax.
#pragma GCC push_options
#pragma GCC pop_options
These pragmas maintain a stack of the current target and optimization options. It is intended for include files where you temporarily want to switch to using a different
#pragma GCC target
or#pragma GCC optimize
and then to pop back to the previous options.
#pragma GCC reset_options
This pragma clears the current
#pragma GCC target
and#pragma GCC optimize
to use the default switches as specified on the command line.
Loop-Specific Pragmas#
#pragma GCC ivdep
With this pragma, the programmer asserts that there are no loop-carried dependencies which would prevent consecutive iterations of the following loop from executing concurrently with SIMD (single instruction multiple data) instructions.
For example, the compiler can only unconditionally vectorize the following loop with the pragma:
void foo (int n, int *a, int *b, int *c) { int i, j; #pragma GCC ivdep for (i = 0; i < n; ++i) a[i] = b[i] + c[i]; }In this example, using the
restrict
qualifier had the same effect. In the following example, that would not be possible. Assume k < -m or k >= m. Only with the pragma, the compiler knows that it can unconditionally vectorize the following loop:void ignore_vec_dep (int *a, int k, int c, int m) { #pragma GCC ivdep for (int i = 0; i < m; i++) a[i] = a[i + k] * c; }
#pragma GCC unroll n
You can use this pragma to control how many times a loop should be unrolled. It must be placed immediately before a
for
,while
ordo
loop or a#pragma GCC ivdep
, and applies only to the loop that follows.n
is an integer constant expression specifying the unrolling factor. The values of 0 and 1 block any unrolling of the loop.