Although portability is a hallmark of C, its creators recognized that every C compiler needs to support 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 directive offers a way for each C compiler to offer machine-specific features while retaining overall compatibility with the C language and other C compilers.
Since pragmas are machine-specific by definition, they are usually different for every C compiler. Pragmas can be used in conditional statements to provide specific preprocessor functionality or to provide implementation-defined information to the compiler. The pragmas discussed in this section apply to the Microsoft C compiler.
#pragma pragma-directive opt new-line
The pragma-directive is one of a series of directives 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. The argument to #pragma is subject to macro expansion.
With many of these pragmas, one of the arguments can be left out. When that is done, the setting of the option returns to the command-line setting. For example:
#pragma pack(1)
struct var
{
/* Structure elements defined here */
}
#pragma pack( )
In this example, the pack pragma forces the structure to be packed on one-byte boundaries until #pragma pack( ) tells the compiler to go back to whatever the previous setting had been.
The #pragma directives instruct the compiler to implement the features specified by the argument. The Microsoft C compiler recognizes the following pragmas:
alloc_textauto_inlinecheck_pointercheck_stackcode_segcommentdata_segfunctionhdrstopcheck_stackinline_recursionintrinsiclinesizemessagenative_calleroptimizepackpagepagesize skipsubtitletitlewarning
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 must occur between a function declarator and the function definition for the named functions. The alloc_text pragma is still supported, but the recommended technique is to use __based.
#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 just before and again just after a function definition.
#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. Checks every pointer dereference to make sure the pointer is not a null or out-of-range pointer. Also enabled with the /Zr command-line option, which is only available with the /qc option. (Within PWB select Additional Debug Options from the C Compiler Options dialog box. Then select Quick Compile and Null Pointer Checking.)
#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. You can do this with either the /Gs option or the check_stack pragma.
#pragma code_seg ( [[ " segment_name" [[ , " segment_class " ]] )
Specifies a segment where functions are to be allocated, allowing the use of based allocation without rewriting code. Using #pragma code_seg is equivalent to using __based when __based is used for allocation. You can specify the class for the segment by giving the segment_class as a string. Using #pragma code_seg without a segment_name string resets allocation to whatever it was when compilation began.
#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 " ]] )
Specifies a segment where data is to be allocated, allowing the use of based allocation without rewriting code. Using #pragma data_seg is equivalent to using __based when __based is used for allocation. The segment-class allows you to assign a segment class to a segment name. This pragma applies only to initialized data and does not affect tentative definitions. Using #pragma data_seg without a segment_name string resets allocation to whatever it was when compilation began. This data_seg pragmas is not equivalent to the data_seg pragma supported by earlier versions of the compiler.
#pragma function ( function1 [[, function2, ...]] )
Specifies that calls to the specified functions will actually take place. 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.
#pragma hdrstop [[ ( "filename" ) ]]
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 on precompiled header files.
#pragma inline_depth ( [[0..255]] )
Controls the number of times that 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 inline functions, or functions that the compiler automatically expands under the /Ob2 option. Requires an /Ob command-line option setting of either 1 or 2.
#pragma inline_recursion ( [[ on | off ]] )
Controls the inline expansion of direct or mutually recursive function calls. Use this pragma to control inline functions, 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.
#pragma intrinsic ( function1 [[, function2, ...]] )
Specifies that calls to the specified functions are intrinsic (a library function known to the compiler). Alternatively, you can use the /Oi option to make intrinsic the default form for functions that have intrinsic forms. In this case, you can use the function pragma to override /Oi for specified functions. This pragma cannot be used with /qc.
The following functions have intrinsic forms:
_alloca_disable_enable_fmemcmp_fmemcpy_fmemset_fstrcat_fstrcmp_fstrcpy_fstrlen_fstrset_inp_inpw_lrotl_lrotr_outp_outpw_rotl_rotr_strsetabsacosasinatanatan2ceilcoscoshexpfabsfloorfmodlabsloglog10memcmpmemcpymemsetpowsinsinhsqrtstrcatstrcmpstrcpystrlentantanh
16-Bit Target Only:
_acosl_asinl_atanl_atan2l_ceill_cosl_coshl_expl_floorl_fmodl_logl_log10l_powl_sinl_sinhl_sqrtl_tanl_tanhl
#pragma linesize ( [[num-chars]] )
Specifies the number of characters per line in the source listing. The optional parameter num-chars is an integer constant in the range 79–132. If num-chars 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. The linesize pragma takes effect the line after it appears.
#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, and you can concatenate such macros with string literals in any combination.
#pragma native_caller ([[{ on | off }]])
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 compiler option or on a function-by-function basis with this pragma. See Chapter 3 in the Programming Techniques manual for more information on p-code.
#pragma optimize ( "[[ optimization-option-list ]]", { off | on } )
Specifies optimizations to be performed. This pragma must appear outside of 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 compiler options.
#pragma pack ( [[{ 1 | 2 | 4 }]] )
Specifies the byte boundary for packing members of C structures. You can use the /Zp option to specify the same packing for all structures in a module. The default is 2 for 16-bit computers and 4 on 32-bit computers. See “Structure Declarations,” for more information.
On 32-bit targets, the packing can be set at 8 or 16 as well as 1, 2, and 4 as given for 16-bit targets.¨
#pragma page ( [[numpages]] )
Tells the compiler to generate formfeeds in the source listing at the line where it appears. The page pragma generates one or more formfeeds (page eject) in the source listing (created with /Fs) at the place where the pragma appears. The number of formfeeds is specified by numpages. Legal values are 1–127, with the default being 1.
#pragma pagesize ( [[numlines]] )
Sets the number of lines per page in the source listing. The optional numlines parameter is an integer constant in the range 15–255 that specifies the number of lines you want on each page of the source listing to have. If numlines 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 skip ( [[numlines]] )
Skips the specified number of lines in the source listing. The skip pragma generates one or more newline characters (carriage return–linefeed) in the source listing at the point where the pragma appears. The optional numlines 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 subtitlename parameter can be a macro that expands to a string literal, and you can concatenate such macros with string literals in any combination. A null subtitlename erases any previous subtitle.
#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, and you can concatenate such macros with string literals in any combination. A null titlename erases any previous title.
#pragma warning( warning-specifier[[; warning-specifier]] )
Controls the warning level for compiler errors. The warning-specifier has the syntax warning-type:warning-number-list where warning-type can be once, default, 1, 2, 3, 4, disable, or error. The specifier once tells the compiler to display a warning only once, default is the standard compiler warning level, and 1–4 force warning levels 1–4. Specifying disable disables the selected warnings, and error forces a warning to be reported as an error. The warning-number-list can be any number between 1 and 699 or 4001 and 4699.
The loop_opt pragma has been replaced with the optimize pragma. The same_seg pragma is no longer supported. Use __based for specifying the placement of external variables in memory.