#pragma directives are used within the source program to request certain kinds of special processing. The #pragma directive is part of the standard C and C++ languages, but the meaning of any pragma is implementation-defined. The front end recognizes several pragmas. The following are described in detail in the template instantiation section of this chapter:

#pragma instantiate
#pragma do_not_instantiate
#pragma can_instantiate

and two others are described in the section on precompiled header processing:

#pragma hdrstop
#pragma no_pch

The front end also recognizes #pragma once, which, when placed at the beginning of a header file, indicates that the file is written in such a way that including it several times has the same effect as including it once. Thus, if the front end sees #pragma once at the start of a header file, it will skip over it if the file is #included again.

A typical idiom is to place an #ifndef guard around the body of the file, with a #define of the guard variable after the #ifndef:

#pragma once // optional
#ifndef FILE_H
#define FILE_H
... body of the header file ...
#endif

The #pragma once is marked as optional in this example, because the front end recognizes the #ifndef idiom and does the optimization even in its absence. #pragma once is accepted for compatibility with other compilers and to allow the programmer to use other guard-code idioms.

By default (this can be changed under a custom porting arrangement), #pragma pack is recognized. It is used to specify the maximum alignment allowed for nonstatic data members of structs and classes, even if that alignment is less than the alignment dictated by the member's type. The basic syntax is:

#pragma pack(n)
#pragma pack()

where argument n, a power-of-2 value, is the new packing alignment that is to go into effect for subsequent declarations, until another #pragma pack is seen. The second form cancels the effect of a preceding #pragma pack(n) and either restores the default packing alignment specified by the --pack_alignment command-line option or, if the option was not used, disables the packing of structs and classes. In addition, an enhanced syntax is also supported in which keywords push and pop can be used to manage a stack of packing alignment values - for instance:

#pragma pack (push, xxx)
#include "xxx.h"
#pragma pack (pop, xxx)

which has the effect saving the current packing alignment value, processing the include file (which may leave the packing alignment with an unknown setting), and restoring the original value.

By default (this can be changed under a custom porting arrangement), #pragma ident is recognized, as is #ident:

#pragma ident "string"
#ident "string"

Both are implemented by recording the string in a pragma entry and passing it to the back end.

By default (this can be changed under a custom porting arrangement), #pragma weak is not recognized. When it is, its form is:

#pragma weak name1 [ = name2 ]

where name1 is the name to be given "weak binding" and is a synonym for name2 if the latter is specified. The entire argument string is recorded in the pragma entry and passed to the back end.