Pragma Directives

Put pragmas in your C++ source code where you want them to take effect. Unless otherwise noted below, a pragma is in effect from the point where it is included until the end of the translation unit or until another pragma changes its status.

A #pragma directive is an instruction to the compiler and is ignored during preprocessing.

Syntax:

#pragma pragma-string

• COPYRIGHT -- Specify a copyright string
• COPYRIGHT_DATE -- Specify a copyright date for the copyright string
• DEFAULT_BINDING -- Symbols are assigned the default export class
• EXTERN -- Inlining of import stubs for calls to default export class symbols
• ESTIMATED_FREQUENCY -- Specify execution frequency
• FREQUENTLY_CALLED -- Identify frequently called blocks
• HIDDEN -- Symbols are assigned the default hidden class
• HP_DEFINED_EXTERNAL -- Inline import stubs
• IF_CONVERT -- Specify If-Conversion for a block
• LOCALITY -- Name a code subspace
• OPTIMIZE -- Turn optimization on or off
• OPT_LEVEL -- Set an optimization level
• PACK -- Allows maximum alignment of class fields having non-class types
• PROTECTED -- Symbols are assigned the protected export class
• RARELY_CALLED -- Identify rarely called blocks
• STDC FP_CONTRACT -- Allows contract optimizations
• STDC FENV_ACCESS -- Access floating point environment flags
• VERSIONID -- Specify a version string

Syntax:

#pragma COPYRIGHT "string"

Description:

If no date is specified (using pragma COPYRIGHT_DATE), the current year is used in the copyright message.

Examples:

#pragma COPYRIGHT "Acme Software"

places the following string in the object code:

(C) Copyright Acme Software, 1999. All rights reserved.
No part of this program may be photocopied, reproduced, or
transmitted without prior written consent of Acme Software.

The following pragmas

#pragma COPYRIGHT_DATE "1990-1999"
#pragma COPYRIGHT "Brand X Software"

place the following string in the object code:

(C) Copyright Brand X Software, 1990-1999. All rights reserved.
No part of this program may be photocopied, reproduced, or
transmitted without prior written consent of Brand X Software.

NOTE: To see the COPYRIGHT string as well as any other strings in the object file, use the strings(1) command with the -a option for example:

Syntax:

#pragma COPYRIGHT_DATE "string"

Description:

Use the COPYRIGHT pragma to put the copyright message into the object file.

Example:

#pragma COPYRIGHT_DATE "1988-1992"

NOTE: To see the COPYRIGHT_DATE string as well as any other strings in the object file, use the strings(1) command with the -a option for example:

Syntax:

#pragma DEFAULT_BINDING [symbol{,symbol}]

Description:

Syntax:

#pragma ESTIMATED_FREQUENCY f

Description:

For an If/Then/Else statement, the number f should be less than 1.0 and represents the ratio of time the Then is executed because the If condition is true.

For a loop, the number is the predicted iteration count. Values less than one are permitted to indicate a loop that is rarely executed.

The pragma should precede all executable statements in the body of the loop statement or If statement.

Syntax:

#pragma EXTERN [symbol{,symbol}]

Description:

Syntax:

#pragma FREQUENTLY_CALLED [symbol{,symbol}]

Description:

Syntax:

#pragma hidden [symbol{,symbol}]

Description:

Syntax:

#pragma IF_CONVERT

Description:

If-Conversion is a compiler process that eliminates conditional branches by the use of predicates. The compiler is instructed to If-Convert all non-loop control flow nested within the current block.

For a discussion of predicates with an animated example, please see Intel documentation at this URL. Select Branch Handling, then Using Predication to Eliminate Branches.

http://developer.intel.com/software/products/itc/architec/itanium/arch_mod/index.htm

Without this pragma, the compiler would employ its own heuristics to determine whether to perform If-Conversion. With this pragma, If-Conversion is always performed.

If-Convert can be specified in a loop containing conditional branches other than the loop-back branch. This makes it more likely the compiler will modulo schedule the loop, as loops containing conditional branches cannot be modulo scheduled. The pragma can also be used for non-looping constructs.

Pragma HP_DEFINED_EXTERNAL

Syntax:

#pragma HP_DEFINED_EXTERNAL name1[,name2,...nameN]

name1 through nameN are names of functions in shared libraries. Note that C++ mangled names are not supported.

Any named function:

• must be the name of an extern"C" function
• must not have C++ linkage
• must not be a member function

Description:

Syntax:

#pragma LOCALITY "string"

Description:

All code following the LOCALITY pragma is associated with the name specified in string. Code that is not headed by a LOCALITY pragma is associated with the name .text.

The smallest scope of a unique LOCALITY pragma is a function.

Example:

#pragma LOCALITY "MINE"

Syntax:

#pragma OPTIMIZE ON
#pragma OPTIMIZE OFF

Description:

NOTE:

• You must specify one of the optimization options on the aCC command, otherwise this pragma is ignored.
• This pragma cannot be used within a function.

Example:

aCC +O2 prog.C

#pragma OPTIMIZE OFF
void A(){    // Turn off optimization
    ...      // for this function
}

#pragma OPTIMIZE ON
void B(){    // Restore optimization
    ...      // to level 2.
}

Syntax:

#pragma OPT_LEVEL 0
#pragma OPT_LEVEL 1
#pragma OPT_LEVEL 2
#pragma OPT_LEVEL 3
#pragma OPT_LEVEL 4

Description:

NOTE:

• You must specify one of the optimization options on the aCC command, otherwise this pragma is ignored.
• This pragma cannot raise the optimization level above the level specified in the command line.
• This pragma cannot be used within a function.

Example:

aCC -O prog.C

#pragma OPT_LEVEL 1
void A(){      // Optimize this function at level 1.
   ...
}
#pragma OPT_LEVEL 2
void B(){      // Restore optimization to level 2.
   ...
}

Syntax:

#pragma PACK [n]

Description:

NOTE: The result of applying #pragma pack n to constructs other than class definitions (including struct definitions) is undefined and not supported. For example:

#pragma pack 1
int global_var; // Undefined behavior: not a class definition

void foo() {    // Also undefined
}

Usage

• Basic Example
• Template Example
• Handling Unaligned Data
• Implicit Access to Unaligned Data

Refer also to Default Data Storage and Alignment.

Basic Example

Example 1:

struct S1 {
   char c1;  // Offset 0, 3 bytes padding
   int i;    // Offset 4, no padding
   char c2;  // Offset 8, 3 bytes padding
};  // sizeof(S1)==12, alignment 4

#pragma pack 1

struct S2 {
   char c1;  // Offset 0, no padding
   int i;    // Offset 1, no padding
   char c2;  // Offset 5, no padding
};  // sizeof(S2)==6, alignment 1

// S3 and S4 show that the pragma does not affect class fields
// unless the class itself was defined under the pragma.
struct S3 {
   char c1;  // Offset 0, 3 bytes padding
   S1 s;     // Offset 4, no padding
   char c2;  // Offset 16, 3 bytes padding
};  // sizeof(S3)==20, alignment 4

struct S4 {
   char c1;  // Offset 0, no padding
   S2 s;     // Offset 1, no padding
   char c2;  // Offset 7, no padding
};  // sizeof(S4)==8, alignment 1

#pragma pack

struct S5 {  // Same as S1
   char c1;  // Offset 0, 3 bytes padding
   int i;    // Offset 4, no padding
   char c2;  // Offset 8, 3 bytes padding
};  // sizeof(S5)==12, alignment 4

Template Example

CAUTION: The alignment of specializations and partial specializations of templates is undefined and unsupported if either the primary template or the specialization is under the influence of a #pragma pack directive.

Example 2:

#pragma pack 1

template<class T>
struct ST1 {
char c1;
T x;
char c2;
};

#pragma pack

ST1<int> obj;      // Same layout as S2 in the prior example

template <>        // Explicit specialization
struct ST1<void> {
   char c1;
   char c2;
};                       // Undefined (unsupported) behavior
                         // ST1 was defined under a #pragma pack 1
                         // directive.

Handling Unaligned Data

Indirect access (through pointers and references) to unaligned class fields is also handled automatically.

CAUTION: If you take the address of a data field and assign it to a pointer, it is not handled automatically and is likely to result in premature termination of the program if not handled appropriately. For example:

Example 3:

#include <stdio.h>
#pragma pack 1
struct S1 {
   char c1;
   int i;
   char c2;
};
#pragma pack
int main() {
	S1 s;
	S1 *p = &s;
	printf("%d\n", s.i);   // OK
	printf("%d\n", p->i);  // OK
	int *ip = &p->i;       // Undefined behavior
						   // Likely Abort unless compiled with +u1
						   // The address of a reference (*ip) is
				   // assigned to an int pointer.
	printf("%d\n", *ip);
}

To enable indirect access to unaligned data that has been assigned to another type, use the following:

• Link in the library -lunalign and arm the appropriate signal handler with a call to allow_unaligned_data_access(). This causes every signal due to unaligned access to be intercepted and handled as expected. It also creates significant run-time overhead for every access to unaligned data, but does not impact access to aligned data.

Implicit Access to Unaligned Data

Furthermore, virtual function calls often require indirect access to a hidden field of a class that could be unaligned under the influence of the #pragma pack directive.

If passing the address of a field to other code, consider the following example. Unless compiled with -DRECOVER on the command line and linked with -lunalign, Example 4 is likely to prematurely terminate with a bus error.

Example 4:

#include <stdio.h>
#ifdef RECOVER
extern "C" void allow_unaligned_data_access();
#endif

#pragma pack 1

struct PS1 {
   PS1();
   ~PS1();
private:
   char c;
   int a;
};

#pragma pack

PS1::PS1(): a(1) {   // There appears to be no pointer, but there
                     // is an unaligned access, possibly through "this."
   printf("In constructor.\n");
}

PS1::~PS1() {
   a = 0;           // Misaligned access, possibly though "this"
   printf("In destructor.\n");
}

int main() {
#if defined(RECOVER)
   allow_unaligned_data_access();
#endif
   PS1 s;
}

Syntax:

#pragma PROTECTED [symbol{,symbol}]

Description:

Syntax:

#pragma RARELY_CALLED [symbol{,symbol}]

Description:

Syntax:

#pragma STDC FP_CONTRACT ON
#pragma STDC FP_CONTRACT OFF

Description:

Each pragma can occur either outside external declarations or preceding all explicit declarations and statements inside a compound statement. When outside external declarations, the pragma takes effect from its occurrence until another FP_CONTRACT pragma is encountered, or until the end of the translation unit. When inside a compound statement, the pragma takes effect from its occurrence until another FP_CONTRACT pragma is encountered within a nested compound statement, or until the end of the compound statement. At the end of a compound statement, the state for the pragma is restored to its condition before the compound statement. If this pragma is used in any other context, the behavior is undefined. The default state is off.

Syntax:

#pragma STDC FP_ACCESS ON
#pragma STDC FP_ACCESS OFF

Description:

The pragma can be placed either outside external declarations or preceding all explicit declarations and statements inside a compound statement. When outside external declarations, the pragma takes effect from its occurrence until another fenv_access pragma is encountered or until the end of the translation unit. When inside a compound statement, the pragma is in effect from its occurrence until another fenv_access pragma is encountered within the nested compound statement or until the end of the compound statement. At the end of a compound statement, the state for the pragma is restored to its condition just before the compound statement.

If the pragma is used in any other context, the behavior is undefined. If part of a program tests flags or runs under non-default mode settings but was translated with the state for the fenv_access pragma off, then the behavior of the program is undefined.

Syntax:

#pragma VERSIONID "string"

Description:

strings -a ObjectFileName.o