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 to the end of the compilation 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 -- Specifies a copyright string.
• COPYRIGHT_DATE -- Specifies a copyright date for the copyright string.
• hdr_stop -- When using header caching, specifies the end of the prefix header region. In a given source file, this header cannot be reset.
• HP_SHLIB_VERSION -- Creates versions of a shared library routine.
• LOCALITY -- Names a code subspace.
• OPTIMIZE -- Turns optimization on or off.
• OPT_LEVEL -- Sets an optimization level.
• pack -- Allows maximum alignment of class fields having non-class types.
• VERSIONID -- Specifies a version string.

Syntax:

#pragma OPTIMIZE ON 
#pragma OPTIMIZE OFF

Description:

Use this pragma to turn off optimization in sections of a source program.

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 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.
• OPT_LEVEL 3 and 4 are allowed only at the beginning of a file.

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

Pragma hdr_stop

Syntax:

#pragma hdr_stop 

Description:

In a given source file, this pragma cannot be reset. It only allows the prefix header region to be shortened, not expanded. Also, there is no equivalent hdr_start pragma to alter the beginning of the prefix header region.

If the #pragma hdr_stop occurs as the first line in a source file, header caching is abandoned for that source file. If it occurs as the first line in a header file, header caching is abandoned for the source file that includes the header file.

Usage

Another example might be useful when only a subset of headers are undergoing code changes. You could place these headers at the end of the list of #include directives, after specifying #pragma hdr_stop. Then, if the more stable headers comprising the prefix header region and the compile environment itself do not change, no re-compile will take place.

Examples

#include <vector>     // stable headers
#include <list>
#include <SuperBase>
#include <IOBase>

#include <Magikal>    // headers you are changing
#include <Util>
                            // default END of prefix header region
void poof();            

#include <vector>     // stable headers
#include <list>
#include <SuperBase>
#include <IOBase>

#pragma hdr_stop            // END the prefix header region
                            // prior to the default

#include <Magikal>    // headers you are changing
#include <Util>

void poof();          

For More Information:

• Creating and Using Automatic Precompiled Headers
• +hdr_cache option

Pragma HP_SHLIB_VERSION

Syntax:

#pragma HP_SHLIB_VERSION ["]date["]

• month must be 1 through 12, corresponding to January through December.
• year can be specified as either the last two digits of the year (94 for 1994) or a full year specification (1994). Two-digit year codes from 00 through 40 represent the years 2000 through 2040, respectively.

Description:

HP_SHLIB_VERSION assigns a version number based on date to a module in a shared library. The version number applies to all global symbols defined in the module's source file.

This pragma should only be used if incompatible changes are made to a source file. If a version number pragma is not present in a source file, the version number of all symbols defined in the object module defaults to 1/90.

For More Information:

• Creating and Using Shared Libraries
• Advanced Shared Library Features
• See the manual HP-UX Linker and Libraries Online User Guide.

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, 1997. 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-1997"
#pragma COPYRIGHT "Brand X Software"

place the following string in the object code:

(C) Copyright Brand X Software, 1990-1997. 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 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 $CODE$.

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

Example:

#pragma LOCALITY "MINE"

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, either of the following two options are available.

• Compile with the +unum option, to generate safe but less efficient code for every indirect access to memory.

• Link in the library libhppa.a (part of the fileset ProgSupport.PROG-AUX) 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 code not compiled with the +u1 option, consider the following example. Unless compiled with -DRECOVER on the command-line and linked with /usr/lib/libhppa.a, 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 VERSIONID "string"

Description:

strings -a ObjectFileName.o