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.

Note that,

• A #pragma directive is an instruction to the compiler and is ignored during preprocessing.
• Block-scoped pragmas must appear before the first statement or declaration of the block.
• Pragmas are case in-sensitive.
• Pragma overrides the command-line option if the two are not in agreement, when a command-line option and pragma are used together.

Syntax:

#pragma pragma-string

• AUTOPAGE -- Specifies a page break
• 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
• FINI -- Specify a termination function
• FLOAT_TRAPS_ON -- Specify floating-point trap handling.
• FREQUENTLY_CALLED -- Identify frequently called functions
• HP_ALIGN -- Specify the alignment of data storage
• HIDDEN -- Symbols are assigned the hidden export class
• HP_DEFINED_EXTERNAL -- Inline import stubs
• HP_DEFINED_INTERNAL -- Inline import stubs
• IF_CONVERT -- Specify If-Conversion for a block
• INIT -- Specify an initialization function
• [NO]INLINE -- Enables/disables inlining
• LINES -- Specify the number of lines per page
• LOCALITY -- Name a code subspace
• LOCALITY_ALL -- Name a code subspace
• NO_INLINE -- Enables/disables inlining
• OPTIMIZE -- Turn optimization on or off
• OPT_LEVEL -- Set an optimization level
• PACK -- Allows maximum alignment of class fields having non-class types
• PAGE -- Causes a page break and begins a new page
• PROTECTED -- Symbols are assigned the protected export class
• RARELY_CALLED -- Identify rarely called fucntions
• SIGNAL -- Specify a signal identifier
• STDC CX_LIMITED_RANGE -- Limits mathematical range.
• STDC FP_CONTRACT -- Allows contract optimizations
• STDC FENV_ACCESS -- Access floating point environment flags
• SUBTITLE -- Specify the subtitle
• TITLE -- Specify the title
• UNROLL_FACTOR -- Specifies the unroll factor
• VERSIONID -- Specify a version string
• WIDTH -- Specify the page width

Syntax:

#pragma AUTOPAGE ON 
#pragma AUTOPAGE OFF 

Description:

Note:This pragma is supported in legacy HP C only.

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"

(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 fraction 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 FINI string

Description:

Example:

#pragma FINI "my_fini"void my_fini() { ... do some clean up ... }

Note:This pragma is supported in legacy HP C only.

Syntax:

#pragma FLOAT_TRAPS_ON

Description:

For example:

#pragma FLOAT_TRAPS_ON xyz,abc

informs the compiler and optimizer that xyz and abc have floating-point traps turned on and therefore LICM optimization should not be performed. A dummy name _ALL represents all functions.

Note:This pragma is supported in legacy HP C and C++ C-mode only.

Syntax:

#pragma FREQUENTLY_CALLED [symbol{,symbol}]

Description:

Syntax:

#pragma HP_ALIGN align_mode [PUSH]
#pragma HP_ALIGN POP

Note:This option is supported in C only. Instead in aC++, you can use Pragma PACK.

Description:

Data Alignment Stack

  #pragma HP_ALIGN POP
            This option to HP_ALIGN restores the previous alignment 
            environment saved using the HP_ALIGN PUSH pragma by 
            deleting the current alignment mode from the top of the 
            stack. If the alignment stack is empty, the default 
            alignment is made the current mode. 

  #pragma HP_ALIGN align_mode PUSH
            This pragma saves the current alignment environment for 
            later retrieval by pushing it into a last in, first out 
            (LIFO) stack. The align_mode is made the new current 
            alignment by placing it on the top of the stack. 

The defined values for align_mode are:

  #pragma HP_ALIGN HPUX_WORD
            Results in int and float types being halfword aligned 
            (two-byte aligned), doubles being word aligned (four byte 
            aligned), and all structs being at least halfword aligned. 
            This is the default for the Series 300/400 computer. 

  #pragma HP_ALIGN HPUX_NATURAL_S500
            Results in doubles being word aligned. This is the default 
            for the Series 500 computer. 

  #pragma HP_ALIGN HPUX_NATURAL
            Results in native alignment for the HP 9000 workstations 
            and servers. The int and float types are word aligned, 
            doubles are double-word aligned (8-byte aligned), and 
            structs may be byte aligned depending upon the data types 
            used within the structure. 

  #pragma HP_ALIGN NATURAL
            Results in a superset of the above. Uses native alignment 
            provided by HPUX_NATURAL, all structs and unions are at 
            least halfword aligned, and DOMAIN bit-field mapping is used. 

  #pragma HP_ALIGN DOMAIN_NATURAL
            Similar to NATURAL except long doubles are only 8 bytes 
            long (treated as doubles). 

  #pragma HP_ALIGN DOMAIN_WORD
            Similar to HPUX_WORD, with the following exceptions: long 
            doubles are only 8 bytes long (treated as doubles) and DOMAIN 
            bit-field mapping is used. 

  #pragma HP_ALIGN NOPADDING
            Causes all structure and union members that are not bit-fields 
            to be packed on a byte boundary. It does not cause crunched 
            data packing, where there are zero bits of padding. It only 
            ensures that there will be no full bytes of padding in the 
            structure or union. 

Accessing Data with the HP_ALIGN Pragma

The HP_ALIGN pragma differs from the +ubytes compiler option. When you use the HP_ALIGN pragma, the compiler localizes inefficient code generation to accesses of data declared with structures or unions under the HP_ALIGN pragma. The +ubytes option assumes that all references to pointer objects are misaligned and performs worst case code generation for all loads and stores of dereferenced data.

The HP_ALIGN pragma offers better run-time performance than the +unumber option. However, the HP_ALIGN pragma requires careful pointer assignment and dereferencing. The following example shows how the pragma is often misused, and what can be done to correct the mistake.

#pragma HP_ALIGN HPUX_WORD
 
struct {
   char chardata;
   int intdata;
} stvar;
 
main()
{
   int *localptr;
   int localint;
   localptr = &stvar.intdata;
   localint = *localptr;   /* invalid dereference */
}

The above program aborts at run-time when localptr is dereferenced. The structure stvar is declared under the HP_ALIGN HPUX_WORD pragma. Its members will not be natively aligned. The member stvar.intdata is aligned on a two byte boundary. The error occurs after the address of stvar.intdata is assigned to localptr. localptr is not affected by the HP_ALIGN HPUX_WORD pragma. When localptr is used to access the data, it is treated as a pointer to four-byte aligned data rather than as a pointer to two-byte aligned data and a run-time error can occur.

Two solutions help to work around this problem. First, the recommended solution is to access non-natively aligned data through structures or unions that are declared under the HP_ALIGN pragma.

For example, the above program can be transformed to:

#pragma HP_ALIGN HPUX_WORD
 
struct {
    char chardata;
    int intdata;
} stvar;   /* stvar is declared under the HP_ALIGN pragma */
 
main()
{
   int *localptr;
   int localint;
   localint = stvar.intdata; /* Valid access of non-naturally */
                             /* aligned data through a struct */
}

The second method is to inform the compiler that all access of data must assume potentially non-natural alignment. In the case of #pragma HP_ALIGN HPUX_WORD shown in the first example above, you can use the +u2 command line option. This causes all loads and stores of any data to be performed in increments of no greater than 2-bytes at a time.

Syntax:

#pragma hidden [symbol{,symbol}]

Description:

Syntax:

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

Description:

This pragma is equivalent to the #pragma EXTERN.

Syntax:

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

Description:

This pragma is equivalent to the #pragma PROTECTED.

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.

Syntax:

#pragma INIT string

Description:

Example:

#pragma INIT "my_init"void my_init() { ... do some initializations ... }

Syntax:

#pragma LINES linenum

Description:

Note:This pragma is supported in legacy HP C only.

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"

Note:This pragma is supported in legacy HP C and C++ C-mode only.

Syntax:

#pragma LOCALITY_ALL string

Description:

Syntax:

#pragma [NO]INLINE sym[, sym]

Description:

Example:

#pragma INLINE checkstat, getinput

#pragma NOINLINE opendb

See Also:

Note:This pragma is supported in legacy HP C and C++ C-mode only.

Syntax:

#pragma NO_INLINE

Description:

See Also:

• +O[no]inline Option
• Pragma [NO]INLINE

Note:This pragma is supported in legacy HP C and C++ C-mode only.

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 PAGE

Description:

Note:This pragma is supported in legacy HP C only.

Syntax:

#pragma PROTECTED [symbol{,symbol}]

Description:

Syntax:

#pragma RARELY_CALLED [symbol{,symbol}]

Description:

Syntax:

#pragma SIGNAL int

Description:

Once the signal has been received, the signal function would typically interpret the signal based upon how it is defined (i.e., abort termination, invalid function range, termination request sent to program, etc.).

Note:This pragma is supported in legacy HP C only.

Syntax:

#pragma STDC CX_LIMITED_RANGE ON
#pragma STDC CX_LIMITED_RANGE OFF 

Description

This pragma can occur outside an external declaration or within a compound statement. When outside external declarations, the pragma takes effect from its occurrence until another STDC CX_LIMITED pragma is encountered or till the end of the translation unit. When within a compound statement, the pragma takes effect from its occurrence until another STDC CX_LIMITED pragma is encountered within a nested compound statement, or until the end of the compound statement.

If this pragma is used in any other context, the behavior is undefined. The default state is off.

Note:This pragma is supported in legacy HP C only.

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 on.

Syntax:

#pragma STDC FENV_ACCESS ON
#pragma STDC FENV_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.

Also see ISO/IEC 9899 Standard.

Syntax:

#pragma SUBTITLE string

Description:

Note:This pragma is supported in legacy HP C only.

Syntax:

#pragma TITLE string

Description:

Note:This pragma is supported in legacy HP C only.

Syntax

#pragma UNROLL_FACTOR n

Description:

A user specified unroll factor will override the default unroll factor applied by the compiler.
Specifying n=1 will prevent the compiler from unrolling the loop so as to form n copies of the original body.
Specifying n=0 allows the compiler to use its own heuristics to apply the unroll factor.

Note:UNROLL_FACTOR pragma will be ignored if it is placed in a loop other than the innermost loop.

Syntax:

#pragma VERSIONID "string"

Description:

strings -a ObjectFileName.o

#pragma WIDTH pagewidth