13.7 Pragma Directives

Each implementation of C++ supports some features unique to its host machine. Some programs, for instance, need to exercise precise control over the memory areas where data is placed or to control the way certain functions receive parameters. The #pragma directives offer a way for each C++ compiler to offer machine-specific features while retaining overall compatibility with the C++ language. Since pragmas are machine-specific by definition, they usually are different for every C++ compiler.

Important:

The pragmas discussed in this section apply to Microsoft C/C++ version 7.0.

Syntax

#pragmatoken-string

The token-string is a series of characters that gives a specific compiler instruction and arguments, if any. The number sign (#) must be the first nonwhite-space character on the line containing the pragma; white-space characters can separate the number sign and the word pragma. Following #pragma, write any text that the translator can parse as preprocessing tokens. The argument to #pragma is subject to macro expansion.

If the compiler finds a pragma that it does not recognize, it issues a warning, but compilation continues.

Pragmas can be used in conditional statements, to provide new preprocessor functionality, or to provide implementation-defined information to the compiler.

The #pragma directives instruct the compiler to implement the features specified by the argument. The Microsoft C++ compiler recognizes the following pragmas:@TABLE TEXT = alloc_text@TABLE TEXT = auto_inline@TABLE TEXT = check_pointer@TABLE TEXT = check_stack@TABLE TEXT = comment@TABLE TEXT = function@TABLE TEXT = inline_depth@TABLE TEXT = inline_recursion@TABLE TEXT = intrinsic@TABLE TEXT = linesize@TABLE TEXT = loop_opt@TABLE TEXT = message@TABLE TEXT = optimize@TABLE TEXT = pack@TABLE TEXT = page@TABLE TEXT = pagesize@TABLE TEXT = same_seg@TABLE TEXT = skip@TABLE TEXT = subtitle@TABLE TEXT = title

These pragma directives are summarized in the following list.

#pragma alloc_text( textsegment, function1, ...)

Names the segment where the specified routine definitions are to reside. This pragma takes effect at the first function defined after the pragma is seen.

#pragma auto_inline( [[on | off]] )

Inhibits the inline expansion of a function. The auto_inline pragma inhibits the preprocessor from expanding a function when the /Ob2 command-line option is in effect. To use it, place one pragma before and immediately after a function definition. This pragma takes effect at the first function definition after the pragma is seen.

#pragma check_pointer ([[{ on | off }]])

Instructs the compiler to turn off pointer checking if off is specified, or to turn on pointer checking if on is specified. If you do not specify either on or off, the effect of check_pointer is to reverse the current state of pointer checking. If pointer checking is on, it is turned off and vice versa.

This pragma takes effect at the first function defined after the pragma is seen.

#pragma check_stack ([[{ on | off }]])

Instructs the compiler to turn off stack probes if off is specified, or to turn on stack probes if on is specified. If no argument is given, stack probes are treated according to the default (on, unless /Gs was used). You can reduce the size of a program and speed up execution slightly by removing stack probes with either the /Gs option or the check_stack pragma.

This pragma takes effect at the first function defined after the pragma is seen.

#pragma code_seg ( [[ "segment-name" [[, "segment-class"]] )

The code_seg pragma specifies the default segment for functions. This is equivalent to using the /NT (name of TEXT segment) compilation option. It is also equivalent to specifying functions as based. You can, optionally, specify the class as well as the segment name. For example:

#pragma code_seg( “MY_CODE”, “CODE” )

Specifying the code_seg pragma with no arguments causes the compiler to allocate all following functions in the default code segment.

The preceding example causes functions following to be allocated in a segment called MY_CODE. The segment is given a CODE class.

Note:

There is no way to specify the segment class using based function allocation or the /NT compilation option.

C++ functions allocated using the /NT option or code_seg pragma do not retain any information about their location. However, C++ functions allocated using the based function-allocation syntax retain that information in their external name.

#pragma comment( comment-type [[, commentstring]])

Allows you to place a comment record in an object file or executable file. The comment-type specifies the type of comment record. The optional commentstring is a string literal that provides additional information for some comment types. Because comment-type is a string literal, it obeys all the rules for string literals with respect to escape characters, embedded quotation marks ("), and concatenation.

#pragma data_seg ( [[ "segment-name"[[, "segment-class"]] )

The data_seg pragma specifies the default segment for data. This is equivalent to using the /ND (name of DATA segment) compilation option. It is also equivalent to specifying objects or pointers as based. You can, optionally, specify the class as well as the segment name. For example:

#pragma data_seg( “MY_DATA”, “DATA” )

Specifying the data_seg pragma with no arguments causes the compiler to allocate all following data in the default data segment.

The preceding example causes functions following to be allocated in a segment called MY_DATA. The segment is given a DATA class.

Note:

There is no way to specify the segment class using based function allocation or the /ND compilation option.

C++ data allocated using the /ND option or data_seg pragma do not retain any information about their location. However, C++ data allocated using the based syntax retain that information in their external name.

#pragma function( function1 [[, function2, ...]] )

Specifies that calls to the specified functions will be normal. The intrinsic pragma affects a specified function beginning where the pragma appears. The effect continues to the end of the source file or to the appearance of a function pragma specifying that function.

This pragma takes effect at the first function defined after the pragma is seen.

#pragma hdrstop [[ ( "filename" ) ]]

The hdrstop pragma controls the way precompiled headers work. The filename is the name of the precompiled header file to use or create (depending on compilation options). If filename does not contain a path specification, the precompiled header file is assumed to be in the same directory as the source file. See Chapter 2 in the Programming Techniques manual for more information about precompiled header files.

#pragma init_seg ( { compiler | lib | user | "seg-name" } )

The init_seg pragma specifies a keyword or segment that affects the order in which startup code is executed. Because initialization of global static objects can involve executing code, you must specify a keyword that defines when the objects are to be constructed. It is particularly important to use the init_seg pragma in DLLs or libraries requiring initialization.

The options to the init_seg pragma are:

If you need to defer initialization (for example, in a DLL), you may choose to specify the segment name explicitly. You must then call the constructors for each static object. For an example of how these initializations are done, see the file CRT0DAT.ASM in the STARTUP\DOS directory.

#pragma inline_depth( [[0... 255]] )

Controls the number of times inline expansion can occur by controlling the number of times that a series of function calls can be expanded (from 0 to 255 times). Use this pragma to control functions marked as inline and __inline, or functions that the compiler automatically expands under the /Ob2 option. Requires an /Ob command-line option setting of either 1 or 2.

This pragma takes effect at the first function defined after the pragma is seen. Its default setting is 8. Once the depth set by this pragma is exceeded, calls are made.

#pragma inline_recursion( [[on | off]] )

Controls the inline expansion of direct or mutually recursive function calls. Use this pragma to control functions marked as inline and __inline, or functions that the compiler automatically expands under the /Ob2 option. Requires an /Ob command-line option setting of either 1 or 2. The default state for inline_recursion is off.

This pragma takes effect at the first function defined after the pragma is seen.

#pragma intrinsic( function1 [[, function2, ...]] )

Specifies that calls to the specified functions are intrinsic. Alternatively, you can use the /Oi option to make intrinsic the default for functions that have intrinsic forms. In this case, you can use the function pragma to override /Oi for specified functions.

This pragma takes effect at the first function defined after the pragma is seen.

The following functions have intrinsic forms:@TABLE TEXT = abs@TABLE TEXT = _alloca@TABLE TEXT = _disable@TABLE TEXT = _enable@TABLE TEXT = _inp@TABLE TEXT = _inpw@TABLE TEXT = labs@TABLE TEXT = _lrotl@TABLE TEXT = _lrotr@TABLE TEXT = memcmp@TABLE TEXT = memcpy@TABLE TEXT = memset@TABLE TEXT = _outp@TABLE TEXT = _outpw@TABLE TEXT = _rotl@TABLE TEXT = _rotr@TABLE TEXT = setjmp@TABLE TEXT = strcat@TABLE TEXT = strcmp@TABLE TEXT = strcpy@TABLE TEXT = strlen@TABLE TEXT = _strset

#pragma linesize( [[characters]] )

Specifies the number of characters per line in the source listing. The optional parameter characters is an integer constant in the range 79–132. If characters is absent, the compiler uses the value specified in the /Sl option or, if that option is absent, the default value of 79 characters per line.

#pragma loop_opt( [[{off | on}]] )

The loop_opt pragma is obsolete. Use the l option of the optimize pragma in its place.

#pragma message( messagestring )

Sends a string literal to the standard output without terminating the compilation. The messagestring parameter can be a macro that expands to a string literal. You can concatenate such macros with string literals in any combination.

#pragma native_caller ( [[ { on | off } ]] )

The native_caller pragma controls the removal of native-code entry points from within source code. If you have p-code functions that are called only by other p-code functions, you can omit those entry points and save those bytes by using the /Gn compilation option or, on a function-by-function basis, using this pragma. See Chapter 3 in the Programming Techniques manual for more information about p-code.

#pragma optimize( "[[optimization-option-list]]", {off | on} )

Specifies optimizations to be performed. Must appear outside a function. The optimization option list may be zero or more of the following: a, c, e, g, l, n, p, q, t, and w. These letters correspond to the /O compilation options.

This pragma takes effect at the first function defined after the pragma is seen.

#pragma pack( [[{1 | 2 | 4 }]] )

Specifies packing alignment for structure types. You can use the /Zp option to specify the same packing for all structures in a module.

This pragma takes effect at the first function defined after the pragma is seen.

#pragma page( [[pages]] )

Skips the specified number of pages in the source listing. The page pragma generates a formfeed (page eject) in the source listing (created with /Fs) at the place where the pragma appears.

#pragma pagesize( [[lines]] )

Sets the number of lines per page in the source listing. The optional lines parameter is an integer constant in the range 15–255 that specifies the number of lines that you want each page of the source listing to have. If lines is absent, the pragma sets the page size to the number of lines specified in the /Sp option or, if that option is absent, to a default value of 63 lines.

#pragma same_seg( variable1, ...)

Tells the compiler to assume that the specified external variables are allocated in the same data segment. You are responsible for making sure that these variables are put in the same data segment. One way to do this is to specify the /ND option when you compile the program. Variables specified in a same_seg pragma must be explicitly declared with extern storage class, and they must either be explicitly declared with the __far keyword or assumed to be far because of the memory model used (compact, large, or huge).

This pragma takes effect at the first function defined after the pragma is seen.

#pragma skip( [[lines]] )

Skips the specified number of lines in the source listing. The skip pragma generates a newline character (carriage return–linefeed) in the source listing at the point where the pragma appears. The optional lines parameter is an integer constant in the range 1–127 that specifies the number of lines to skip. If this parameter is absent, the skip pragma defaults to one line.

#pragma subtitle( "subtitlename" )

Specifies a subtitle for the source listing. The titlename parameter can be a macro that expands to a string literal. You can concatenate such macros with string literals in any combination.

#pragma title( "titlename" )

Specifies a title for the source listing. The title appears in the upper-left corner of each page of the listing. The titlename parameter can be a macro that expands to a string literal. You can concatenate such macros with string literals in any combination.

#pragma warning( warning-specifier : warning-number-list [[,warning-specifier : warning-number-list...]] )

The warning pragma allows selective modification of the behavior of compiler warning messages.

The warning-specifier can be: once, default, 1, 2, 3, 4, disable, or error. These work as follows:

The warning-number-list can contain any warning numbers in the ranges 1 through 699, and 4001 through 4699. Multiple options can be specified in the same pragma directive as follows:

#pragma warning( disable : 4507 34; once : 4385; error : 164 )

This is functionally equivalent to:

#pragma warning( disable : 4138 34 ) // Disable warning messages

// 4507 and 34.

#pragma warning( once : 4306 ) // Issue warning 4385

// only once.

#pragma warning( error : 164 ) // Report warning 164

// as an error.