digitalmars.com                        
Last update Sun Sep 8 21:42:01 2013

Pragmas

Digital Mars C++ implements the following #pragma directives. The preprocessor ignores unrecognized pragmas.

Pragma directives are case sensitive. They have the form:

#pragma pragma-directive [pragma_args]

#ident "string"

Embed string in executable file.

#pragma alias("name1","name2")

Inserts an alias record in the object file, where the linker will substitute references to name1 with references to name2. The strings are inserted into the object file verbatim.

#pragma alias(identifier,"name2")

Inserts an alias record in the object file, where the linker will substitute references to the global symbol identifier with references to name2. "name2" is inserted into the object file verbatim. The identifier must have already been declared.

#pragma align [1|2|4|8|16]

Obsolete. Use #pragma pack().

#pragma code_seg("csname")

Causes subsequent code to be placed in the segment csname. When used with -NS, the -NS switch overrides the pragma for global far functions.

The -NT, -NS and #pragma cseg can all be used independently or in any combination.

#pragma comment(compiler)

Embed compiler version string in object file.

#pragma comment(lib,"filespec")

This embeds a reference to the library filespec into the object file, so that the linker will search that library to resolve any undefined externals. This works the same as the INCLUDELIB directive in MASM.

It is most useful when placed in the .h file that references a special library, for instance, in stream.h which references the oldstrx.lib library.

#pragma comment(exestr,"string")

Embed string in executable file. Same as #ident "string".

#pragma comment(user,"string")

Embed string in object file.

#pragma cseg csname

Obsolete. Use #pragma code_seg().

#pragma dbcs

This pragma defines how the compiler interprets double-byte characters in character strings. The syntax is one of:
#pragma dbcs()
#pragma dbcs(n)
#pragma dbcs(push, n)
#pragma dbcs(pop)
#pragma dbcs() tells the compiler to interpret double-byte characters as specified on the compiler command line, via the -j compiler option (see Compiling Code).

#pragma dbcs(n) tells the compiler to interpret double-byte characters according to the value for n, as follows:

n
0 No double-byte characters in strings
1 Japanese
2 Chinese (Republic of China or People's Republic of China)
3 Korean
Specify push and pop together, in combination with n. When #pragma dbcs(push, n) is specified, the current value for n is "pushed" and n is set to the specified value. When #pragma dbcs(pop) is specified, the pushed value for n is "popped" and becomes the current value again.

#pragma DOSSEG

Marks the generated object file with the DOSSEG switch. At least one object file in a program needs the DOSSEG switch (or the DOSSEG switch can be thrown on the linker) in order for the segments to be sorted in the right order. DOSSEG is normally in the startup code, this pragma is handy when not linking in the usual startup code from the runtime library.

#pragma ident

This pragma is recognized and ignored. It is included for compatibility with some UNIX software.

#pragma include_alias( <filename>,<aliasname>)

#pragma include_alias( "filename","aliasname")

This pragma is used when an include file has an alias. Whenever a #include "filename" is encountered, the "aliasname" is substituted. The same holds for <> names.

The alias pragmas must lexically precede the #include directives they affect.

For example:

#pragma include_alias(<stdio.h>,<mystudio.h>)
#include <stdio.h>
is equivalent to:
#include <mystudio.h>

#pragma includelib "filespec"

Obsolete. Use #pragma comment(lib,"filespec")

#pragma init_seg(compiler|lib|user)

Sets the segment into which static constructors go. All the static constructors in the 'compiler' segment get executed first, followed by the static constructors in the 'lib' segment, followed by the ones in the 'user' seg. The user seg is the default.

#pragma linkage(name, _cdecl | _pascal | cdecl | far16 | pascal | system )

name refers to a function, followed by an identifier giving the type of linkage for that function. The pragma can precede or follow the declaration of name. name cannot be overloaded. This pragma is for compatibility with IBM's C compiler.

#pragma message "text"

Causes the compiler to print text as an informational message while compiling.

#pragma noreturn(identifier)

Where identifier is the name of a previously declared function. This pragma informs the compiler that the function does not return, enabling the compiler to generate improved code. The pragma is useful for marking functions like exit(), _exit(), abort(), longjmp() and especially _assert() (For those of us who use assert() macros a lot, this can be a significant win).

#pragma once

Use in an include file that should only be parsed once, regardless of the number of times it is #include'd. This can replace the clumsy (but portable) method of putting wrappers around the text:
In file.c:
    #ifndef __TEST_H
    #include "test.h"
    #endif
In test.h:
    #ifndef __TEST_H
    #define __TEST_H 1
    ... contents of file ...
    #endif
The simpler scheme is:
In file.c:
    #include "test.h"
In test.h:
    #pragma once
Digital Mars's RCC resource compiler also supports this pragma.

#pragma pack(n)

Set the alignment for struct and class members to n. If n is blank, then the alignment is set to the default (affected by the -a command line switch). Example:
#pragma pack(__DEFALIGN)  // to default alignment
struct ABC { ... };       // lay out structure
#pragma pack()            // back to previous alignment

#pragma pack(push,n)

Push the previous value of the struct member alignment. Set the new value to n.

#pragma pack(pop)

Pop the value most recently pushed by #pragma(push,n), and set the current struct member alignment to that value. Always using push and pop pack pragmas in corresponding nested pairs.

#pragma setlocale("locale")

Sets the current locale to "locale". The specified locale must be supported by the operating system. The locale controls how multibyte characters are handled in strings, and how multibyte strings are converted to Unicode. This is a better solution than the old -j switches. The default locale is "C".

#pragma startaddress(name)

Puts a startaddress record into the object file. name must be a symbol that was previously declared, e.g.:
void startup();
#pragma startaddress(startup)
Overloading of name is not supported.
Home | Runtime Library | IDDE Reference | STL | Search | Download | Forums