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 or short_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 common 1234H numeric syntax is not supported (use 0x1234 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 any io 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 value constant_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 be mac68k, to emulate m68k alignment, or power, to emulate PowerPC alignment. Uses of this pragma nest properly; to restore the previous setting, use reset for the alignment.

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 to alignment. This is the same as GCC’s aligned 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 (before main) 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 symbol newname. 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 of symbol. It is not an error for symbol to never be defined at all.

#pragma weak symbol1 = symbol2

This pragma declares symbol1 to be a weak alias of symbol2. It is an error if symbol2 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 is error to treat this diagnostic as an error, warning to treat it like a warning (even if -Werror is in effect), or ignored 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 each pop. If a pop has no matching push, 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 for macro_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 each string argument. The parentheses around the strings in the pragma are optional. See Declaring Attributes of Functions, for more information about the target 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 each string argument. The parentheses around the strings in the pragma are optional. See Declaring Attributes of Functions, for more information about the optimize 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 or do 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.