C++ Programming Guide |
Pragmas
This chapter describes pragmas. A pragma is a compiler directive that allows you to provide additional information to the compiler. This information can change compilation details that are not otherwise under your control. For example, the
pack
pragma affects the layout of data within a structure. Compiler pragmas are also called directives.The preprocessor keyword
pragma
is part of the C++ standard, but the form, content, and meaning of pragmas is different for every compiler. No pragmas are defined by the C++ standard. Code that depends on pragmas is not portable.3.1 Pragma Forms
The various forms of a Sun WorkShop C++ compiler pragma are:
#pragma keyword#pragma keyword ( a [ , a ] ...) [ , keyword ( a [ , a ] ...) ] ,...#pragma sun keywordThe variable keyword identifies the specific directive; a indicates an argument.
The pragma keywords that are recognized by the Sun WorkShop C++ compiler are:
align
--Makes the parameter variables memory-aligned to a specified number of bytes, overriding the default.init
--Marks a specified function as an initialization function.fini
--Marks a specified function as a finalization function.ident
--Places a specified string in the.comment
section of the executable.pack
(
n)
--Controls the layout of structure offsets. The value of n is a number--0, 1, 2, 4, or 8--that specifies the worst-case alignment desired for any structure member.unknown_control_flow
--Specifies a list of routines that violate the usual control flow properties of procedure calls.weak
--Defines weak symbol bindings.3.2 Pragma Reference
This section describes the pragma keywords that are recognized by the Sun WorkShop C++ compiler.
3.2.1
#pragma
align
#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, replacea
,b
, andc
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;}3.2.2
#pragma
init
#pragma
init(
identifier[
,
identifier]
...)
Use
init
to mark identifier as an initialization function. Such functions are expected to be of typevoid
, 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 asdlopen()
. 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.3.2.3
#pragma
fini
#pragma
fini
(
identifier[,
identifier]...)
Use
fini
to mark identifier as a finalization function. Such functions are expected to be of typevoid
, 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.3.2.4
#pragma
ident
Use
ident
to place string in the.comment
section of the executable.3.2.5
#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- 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 f
TABLE 3-1 Strictest Alignment by Platform IA 4 SPARC generic, V7, V8, V8a, V8plus, V8plusa, V8plusb 8 SPARC V9, V9a, V9b 16
or each platform.A
pack
directive applies to all structure definitions which follow it, until the nextpack
directive. If the same structure is defined in different translation units with different packing, your program may fail in unpredictable ways. In particular, you should not use apack
directive prior to including a header defining the interface of a precompiled library. The recommended usage is to place thepack
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.
3.2.6
#pragma
unknown_control_flow
#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 tosetjmp()
can be reached from an arbitrary call to any other routine. The statement is reached by a call tolongjmp()
.Because such routines render standard flowgraph analysis invalid, routines that call them cannot be safely optimized; hence, they are compiled with the optimizer disabled.
3.2.7
#pragma
weak
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 back end may or may not produce an error for invalid mangled name references. Regardless of whether it produces an error, the behavior of the back end 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.#pragma weak name
In the form
#pragma
weak
name, the directive makes name a weak symbol. The linker will not complain if it does not find a symbol definition for name. It also does not complain 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 namedping.
#pragma weak ping#pragma weak name1 = name2
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 tofoo
otherwise.
#pragma weak bar = fooIn 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
andbar
in the following example areextern
"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"Overloading Functions
When you use the identifier form, there must be exactly one function with the specified name 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 nameTo 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) weakSee the Solaris Linker and Libraries Guide for more information.
Sun Microsystems, Inc. Copyright information. All rights reserved. Feedback |
Library | Contents | Previous | Next | Index |