This section describes the pragma keywords that are recognized by the C++ compiler.
#pragma align integer(variable[,variable...])
Use align to make the listed variables memory-aligned to integer bytes, overriding the default. The following limitations apply:
integer must be a power of 2 between 1 and 128. Valid values are 1, 2, 4, 8, 16, 32, 64, and 128.
variable is a global or static variable. It cannot be a local variable or a class member variable.
If the specified alignment is smaller than the default, the default is used.
The pragma line must appear before the declaration of the variables that it mentions. Otherwise, it is ignored.
Any variable mentioned on the pragma line but not declared in the code following the pragma line is ignored. Variables in the following example are properly declared.
#pragma align 64 (aninteger, astring, astruct)
int aninteger;
static char astring[256];
struct S {int a; char *b;} astruct;When #pragma align is used inside a namespace, mangled names must be used. For example, in the following code, the #pragma align statement will have no effect. To correct the problem, replace a, b, and c in the #pragma align statement with their mangled names.
namespace foo {
#pragma align 8 (a, b, c)
static char a;
static char b;
static char c;
}
#pragma does_not_read_global_data(funcname[, funcname])
This pragma asserts that the specified routines do not read global data directly or indirectly, enabling better optimization of code around calls to such routines. In particular, assignment statements or stores could be moved around such calls.
This pragma is permitted only after the prototype for the specified functions are declared. If the assertion about global access is not true, then the behavior of the program is undefined.
For a more detailed explanation of how the pragma treats overloaded function names as arguments, see Overloaded Functions as Pragma Arguments.
#pragma does_not_return(funcname[, funcname])
This pragma is an assertion to the compiler that the calls to the specified routines will not return, enabling the compiler to perform optimizations consistent with that assumption. For example, register life-times terminate at the call sites which in turn enables more optimizations.
If the specified function does return, then the behavior of the program is undefined.
This pragma is permitted only after the prototype for the specified functions are declared, as the following example shows:
extern void exit(int); #pragma does_not_return(exit) extern void __assert(int); #pragma does_not_return(__assert)
For a more detailed explanation of how the pragma treats overloaded function names as arguments, see Overloaded Functions as Pragma Arguments.
#pragma does_not_write_global_data(funcname[, funcname])
This pragma asserts that the specified list of routines do not write global data directly or indirectly, enabling better optimization of code around calls to such routines. In particular, assignment statements or stores could be moved around such calls.
This pragma is permitted only after the prototype for the specified functions are declared. If the assertion about global access is not true, then the behavior of the program is undefined.
For a more detailed explanation of how the pragma treats overloaded function names as arguments, see Overloaded Functions as Pragma Arguments.
#pragma dumpmacros (value[,value...])
Use this pragma when you want to see how macros are behaving in your program. This pragma provides information such as macro defines, undefines, and instances of usage. It prints output to the standard error (stderr) based on the order macros are processed. The dumpmacros pragma is in effect through the end of the file or until it reaches a #pragma end_dumpmacro. See #pragma end_dumpmacros. The following table lists the possible values for value:
|
The dumpmacros pragma has the same effect as the command-line option, however, the pragma overrides the command-line option. See -xdumpmacros[=value[,value...]].
The dumpmacros pragma does not nest so the following lines of code stop printing macro information when the #pragma end_dumpmacros is processed:
#pragma dumpmacros(defs, undefs) #pragma dumpmacros(defs, undefs) ... #pragma end_dumpmacros
The effect of the dumpmacros pragma is cumulative. The following lines
#pragma dumpmacros(defs, undefs) #pragma dumpmacros(loc)
have the same effect as:
#pragma dumpmacros(defs, undefs, loc)
If you use the option #pragma dumpmacros(use,no%loc), the name of each macro that is used is printed only once. If you use the option #pragma dumpmacros(use,loc), the location and macro name is printed every time a macro is used.
#pragma end_dumpmacros
This pragma marks the end of a dumpmacros pragma and stops printing information about macros. If you do not use an end_dumpmacros pragma after a dumpmacros pragma, the dumpmacros pragma continues to generate output through the end of the file.
#pragma error_messages (on|off|default, tag… tag)
The error message pragma provides control within the source program over the messages issued by the compiler. The pragma has an effect on warning messages only. The -w command-line option overrides this pragma by suppressing all warning messages.
#pragma error_messages (on, tag… tag)
The on option ends the scope of any preceding #pragma error_messages option, such as the off option, and overrides the effect of the -erroff option.
#pragma error_messages (off, tag… tag)
The off option prevents the compiler program from issuing the given messages beginning with the token specified in the pragma. The scope of the pragma for any specified error message remains in effect until overridden by another #pragma error_messages, or the end of compilation.
#pragma error_messages (default, tag… tag)
The default option ends the scope of any preceding #pragma error_messages directive for the specified tags.
#pragma fini (identifier[,identifier...])
Use fini to mark identifier as a finalization function. Such functions are expected to be of type void, to accept no arguments, and to be called either when a program terminates under program control or when the containing shared object is removed from memory. As with initialization functions, finalization functions are executed in the order processed by the link editor.
In a source file, the functions specified in #pragma fini are executed after the static destructors in that file. You must declare the identifiers before using them in the pragma.
Such functions are called once for every time they appear in a #pragma fini directive.
Embed the hdrstop pragma in your source-file headers to identify the end of the viable source prefix. For example, consider the following files:
example% cat a.cc #include "a.h" #include "b.h" #include "c.h" #include <stdio.h> #include "d.h" . . . example% cat b.cc #include "a.h" #include "b.h" #include "c.h"
The viable source prefix ends at c.h so you would insert a #pragma hdrstop after c.h in each file.
#pragma hdrstop must only appear at the end of the viable prefix of a source file that is specified with the CC command. Do not specify #pragma hdrstop in any include file.
See -xpch=v and -xpchstop=file.
#pragma ident string
Use ident to place string in the .comment section of the executable.
#pragma init(identifier[,identifier...])
Use init to mark identifier as an initialization function. Such functions are expected to be of type void, to accept no arguments, and to be called while constructing the memory image of the program at the start of execution. Initializers in a shared object are executed during the operation that brings the shared object into memory, either at program start up or during some dynamic loading operation, such as dlopen(). The only ordering of calls to initialization functions is the order in which they are processed by the link editors, both static and dynamic.
Within a source file, the functions specified in #pragma init are executed after the static constructors in that file. You must declare the identifiers before using them in the pragma.
Such functions are called once for every time they appear in a #pragma init directive.
The ivdep pragmas tell a compiler to ignore some or all loop-carried dependences on array references that it finds in a loop for purposes of optimization. This enables a compiler to perform various loop optimizations such as microvectorization, distribution, software pipelining, and so on., which would not be otherwise possible. It is used in cases where the user knows either that the dependences do not matter or that they never occur in practice.
The interpretation of #pragma ivdep directives depend upon the value of the —xivdep option.
#pragma must_have_frame(funcname[,funcname])
This pragma requests that the specified list of functions always be compiled to have a complete stack frame (as defined in the System V ABI). You must declare the prototype for a function before listing that function with this pragma.
extern void foo(int); extern void bar(int); #pragma must_have_frame(foo, bar)
This pragma is permitted only after the prototype for the specified functions is declared. The pragma must precede the end of the function.
void foo(int) {
.
#pragma must_have_frame(foo)
.
return;
}See Overloaded Functions as Pragma Arguments
#pragma no_side_effect(name[,name...])
Use no_side_effect to indicate that a function does not change any persistent state. The pragma declares that the named functions have no side effects of any kind. That is, the functions return result values that depend on the passed arguments only. In addition, the functions and their called descendants behave as follows:
Do not access for reading or writing any part of the program state visible in the caller at the point of the call.
Do not perform I/O.
Do not change any part of the program state not visible at the point of the call.
The compiler can use this information when doing optimizations.
If the function does have side effects, the results of executing a program which calls this function are undefined.
The name argument specifies the name of a function within the current translation unit. The pragma must be in the same scope as the function and must appear after the function declaration. The pragma must be before the function definition.
For a more detailed explanation of how the pragma treats overloaded function names as arguments, see Overloaded Functions as Pragma Arguments.
#pragma opt level (funcname[, funcname])
funcname specifies the name of a function defined within the current translation unit. The value of level specifies the optimization level for the named function. You can assign optimization levels 0, 1, 2, 3, 4, 5. You can turn off optimization by setting level to 0. The functions must be declared with a prototype or empty parameter list prior to the pragma. The pragma must proceed the definitions of the functions to be optimized.
The level of optimization for any function listed in the pragma is reduced to the value of -xmaxopt. The pragma is ignored when -xmaxopt=off.
For a more detailed explanation of how the pragma treats overloaded function names as arguments, see Overloaded Functions as Pragma Arguments.
#pragma pack([n])
Use pack to affect the packing of structure members.
If present, n must be 0 or a power of 2. A value of other than 0 instructs the compiler to use the smaller of n-byte alignment and the platform’s natural alignment for the data type. For example, the following directive causes the members of all structures defined after the directive (and before subsequent pack directives) to be aligned no more strictly than on 2-byte boundaries, even if the normal alignment would be on 4–byte or 8-byte boundaries.
#pragma pack(2)
When n is 0 or omitted, the member alignment reverts to the natural alignment values.
If the value of n is the same as or greater than the strictest alignment on the platform, the directive has the effect of natural alignment. The following table shows the strictest alignment for each platform.
|
A pack directive applies to all structure definitions which follow it until the next pack directive. If the same structure is defined in different translation units with different packing, your program might fail in unpredictable ways. In particular, you should not use a pack directive prior to including a header defining the interface of a precompiled library. The recommended usage is to place the pack directive in your program code, immediately before the structure to be packed, and to place #pragma pack() immediately after the structure.
When using #pragma pack on a SPARC platform to pack denser than the type’s default alignment, the -misalign option must be specified for both the compilation and the linking of the application. The following table shows the storage sizes and default alignments of the integral data types.
#pragms rarely_called(funcname[, funcname])
This pragma provides a hint to the compiler that the specified functions are called infrequently, enabling the compiler to perform profile-feedback style optimizations on the call-sites of such routines without the overhead of a profile-collections phase. Since this pragma is a suggestion, the compiler may not perform any optimizations based on this pragma.
The #pragma rarely_called preprocessor directive is only permitted after the prototype for the specified functions are declares. The following is an example of #pragma rarely_called:
extern void error (char *message); #pragma rarely_called(error)
For a more detailed explanation of how the pragma treats overloaded function names as arguments, see Overloaded Functions as Pragma Arguments.
#pragma returns_new_memory(name[,name...])
This pragma asserts that each named function returns the address of newly allocated memory and that the pointer does not alias with any other pointer. This information allows the optimizer to better track pointer values and to clarify memory location, resulting in improved scheduling and pipelining.
If the assertion is false, the results of executing a program which calls this function are undefined.
The name argument specifies the name of a function within the current translation unit. The pragma must be in the same scope as the function and must appear after the function declaration. The pragma must be before the function definition.
For a more detailed explanation of how the pragma treats overloaded function names as arguments, see Overloaded Functions as Pragma Arguments.
#pragma unknown_control_flow(name[,name...])
Use unknown_control_flow to specify a list of routines that violate the usual control flow properties of procedure calls. For example, the statement following a call to setjmp() can be reached from an arbitrary call to any other routine. The statement is reached by a call to longjmp().
Because such routines render standard flowgraph analysis invalid, routines that call them cannot be safely optimized; hence, they are compiled with the optimizer disabled.
If the function name is overloaded, the most recently declared function is chosen.
#pragma weak name1 [= name2]
Use weak to define a weak global symbol. This pragma is used mainly in source files for building libraries. The linker does not warn you if it cannot resolve a weak symbol.
The weak pragma can specify symbols in one of two forms:
String form. The string must be the mangled name for a C++ variable or function. The behavior for an invalid mangled name reference is unpredictable. The compiler might not produce an error for invalid mangled name references. Regardless of whether it produces an error, the behavior of the compiler when invalid mangled names are used is unpredictable.
Identifier form. The identifier must be an unambiguous identifier for a C++ function that was previously declared in the compilation unit. The identifier form cannot be used for variables. The front end (ccfe) will produce an error message if it encounters an invalid identifier reference.
In the form #pragma weak name, the directive makes name a weak symbol. The linker will not indicate if it does not find a symbol definition for name. It also does not warn about multiple weak definitions of the symbol. The linker simply takes the first one it encounters.
If another compilation unit has a strong definition for the function or variable, name will be linked to that. If there is no strong definition for name, the linker symbol will have a value of 0.
The following directive defines ping to be a weak symbol. No error messages are generated if the linker cannot find a definition for a symbol named ping.
#pragma weak ping
In the form #pragma weak name1 = name2, the symbol name1 becomes a weak reference to name2. If name1 is not defined elsewhere, name1 will have the value name2. If name1 is defined elsewhere, the linker uses that definition and ignores the weak reference to name2. The following directive instructs the linker to resolve any references to bar if it is defined anywhere in the program, and to foo otherwise.
#pragma weak bar = foo
In the identifier form, name2 must be declared and defined within the current compilation unit. For example:
extern void bar(int) {...}
extern void _bar(int);
#pragma weak _bar=barWhen you use the string form, the symbol does not need to be previously declared. If both _bar and bar in the following example are extern "C", the functions do not need to be declared. However, bar must be defined in the same object.
extern "C" void bar(int) {...}
#pragma weak "_bar" = "bar"
When you use the identifier form, exactly one function with the specified name must be in scope at the pragma location. Attempting to use the identifier form of #pragma weak with an overloaded function is an error. For example:
int bar(int); float bar(float); #pragma weak bar // error, ambiguous function name
To avoid the error, use the string form, as shown in the following example.
int bar(int); float bar(float); #pragma weak "__1cDbar6Fi_i_" // make float bar(int) weak
See the Oracle Solaris 11.3 Linkers and Libraries Guide for more information.