pragma.gml

开放源码的编译器open watcom 1.6.0版的源代码

By specifying
.id sin
in a "function" pragma, the intrinsic attribute will be removed,
causing the function
.id sin
to be treated as a regular user-defined function.
.millust begin
#include <math.h>
#pragma function( sin );

double test( double x )
{
    return( sin( x ) );
}
.millust end
.*
.section Setting Priority of Static Data Initialization (C++ Only)
.*
.np
.ix 'pragmas' 'initialize'
.ix 'initialize pragma'
The "initialize" pragma sets the priority for initialization of
static data in the file.
This priority only applies to initialization of static data that requires
the execution of code.
For example, the initialization of a class that contains a constructor
requires the execution of the constructor.
Note that if the sequence in which initialization of static data in your
program takes place has no dependencies, the "initialize" pragma need not
be used.
.np
The general form of the "initialize" pragma is as follows.
.mbox begin
:prgbeg. initialize :op.before :or. after:eop. :id.priority:eid. :prgend.

:id.priority ::=:eid. :id.n:eid. :or. library :or. program
.mbox end
.synote
.note n
is a number representing the priority and must be in the range 0-255.
The larger the priority, the later the point at which initialization will
occur.
.esynote
.np
Priorities in the range 0-20 are reserved for the C++ compiler.
This is to ensure that proper initialization of the C++ run-time system
takes place before the execution of your program.
The "library" keyword represents a priority of 32 and can be used for class
libraries that require initialization before the program is initialized.
The "program" keyword represents a priority of 64 and is the default priority
for any compiled code.
Specifying "before" adjusts the priority by subtracting one.
Specifying "after" adjusts the priority by adding one.
.np
A source file containing the following "initialize" pragma specifies that the
initialization of static data in the file will take place before
initialization of all other static data in the program since a priority of
63 will be assigned.
.exam begin
#pragma initialize before program
.exam end
.pc
If we specify "after" instead of "before", the initialization of the
static data in the file will occur after initialization of all other static
data in the program since a priority of 65 will be assigned.
.np
Note that the following is equivalent to the "before" example
.exam begin
#pragma initialize 63
.exam end
.pc
and the following is equivalent to the "after" example.
.exam begin
#pragma initialize 65
.exam end
.pc
The use of the "before", "after", and "program" keywords are more
descriptive in the intent of the pragmas.
.np
It is recommended that a priority of 32 (the priority used when the "library"
keyword is specified) be used when developing class libraries.
This will ensure that initialization of static data defined by the class
library will take place before initialization of static data defined by the
program.
The following "initialize" pragma can be used to achieve this.
.exam begin
#pragma initialize library
.exam end
.*
.section The INLINE_DEPTH Pragma (C++ Only)
.*
.ix 'pragmas' 'inline_depth'
.ix 'inline_depth pragma'
.np
When an in-line function is called, the function call may be replaced
by the in-line expansion for that function.
This in-line expansion may include calls to other in-line functions
which can also be expanded.
The "inline_depth" pragma can be used to set the number of times this
expansion of in-line functions will occur for a call.
.np
The form of the "inline_depth" pragma is as follows.
.mbox begin
:prgbeg. inline_depth :op.(:eop. :id.n:eid. :op.):eop. :prgend.
.mbox end
.synote
.note n
is the depth of expansion.
If
.id n
is 0, no expansion will occur.
If
.id n
is 1, only the original call is expanded.
If
.id n
is 2, the original call and the in-line functions invoked by the
original function will be expanded.
The default value for
.id n
is 3.
The maximum value for
.id n
is 255.
Note that no expansion of recursive in-line functions occur unless
enabled using the "inline_recursion" pragma.
.esynote
.*
.section The INLINE_RECURSION Pragma (C++ Only)
.*
.np
.ix 'pragmas' 'inline_recursion'
.ix 'inline_recursion pragma'
The "inline_recursion" pragma controls the recursive expansion of
inline functions.
The form of the "inline_recursion" pragma is as follows.
.mbox begin
:prgbeg. inline_recursion :op.(:eop. on :or. off :op.):eop. :prgend.
.mbox end
.np
Specifying "on" will enable expansion of recursive inline functions.
The depth of expansion is specified by the "inline_depth" pragma.
The default depth is 3.
Specifying "off" suppresses expansion of recursive inline functions.
This is the default.
.*
.section The INTRINSIC Pragma
.*
.np
.ix 'pragmas' 'intrinsic'
.ix 'intrinsic pragma'
Certain functions, those listed in the description of the "oi" option,
have intrinsic forms.
These functions are special functions that are recognized by the compiler
and processed in a special way.
For example, the compiler may choose to generate in-line code for the
function.
The intrinsic attribute for these special functions is set by specifying
the "oi" option or using an "intrinsic" pragma.
.np
The following describes the form of the "intrinsic" pragma.
.mbox begin
:prgbeg. intrinsic ( :id.fn:eid. :rp., :id.fn:eid.:erp. ) :prgend.
.mbox end
.synote
.note fn
is the name of a function.
.endnote
.np
Suppose the following source code was compiled without using the "oi" option
so that no function had the intrinsic attribute.
If we wanted the intrinsic form of the
.id sin
function to be used,
we could specify the function in an "intrinsic" pragma.
.millust begin
#include <math.h>
#pragma intrinsic( sin );

double test( double x )
{
    return( sin( x ) );
}
.millust end
.*
.section The MESSAGE Pragma
.*
.np
.ix 'pragmas' 'message'
.ix 'message pragma'
The "message" pragma can be used to issue a message with the specified
text to the standard output without terminating compilation.
The following describes the form of the "message" pragma.
.mbox begin
:prgbeg. message ( :id."message text":eid. ) :prgend.
.mbox end
.synote
.note "message text"
is the text of the message that you wish to display.
.endnote
.np
The following is an example.
.millust begin
#if defined(__386__)
    ...
#else
#pragma message ( "assuming 16-bit compile" );
#endif
.millust end
.*
.section The ONCE Pragma
.*
.np
.ix 'pragmas' 'once'
.ix 'once pragma'
.ix 'optimization'
The "once" pragma can be used to indicate that the file which contains
this pragma should only be opened and processed "once".
The following describes the form of the "once" pragma.
.mbox begin
:prgbeg. once :prgend.
.mbox end
.np
Assume that the file "foo.h" contains the following text.
.exam begin
#ifndef _FOO_H_INCLUDED
#define _FOO_H_INCLUDED
#pragma once
    .
    .
    .
#endif
.exam end
.np
The first time that the compiler processes "foo.h" and encounters the
"once" pragma, it records the file's name.
Subsequently, whenever the compiler encounters a
.mono #include
statement that refers to "foo.h", it will not open the include file
again.
This can help speed up processing of
.mono #include
files and reduce the time required to compile an application.
.*
.section The PACK Pragma
.*
.np
.ix 'pragmas' 'pack'
.ix 'pack pragma'
The "pack" pragma can be used to control the way in which structures
are stored in memory.
There are 4 forms of the "pack" pragma.
.np
The following form of the "pack" pragma can be used to change the
alignment of structures and their fields in memory.
.mbox begin
:prgbeg. pack ( :id.n:eid. ) :prgend.
.mbox end
.synote
.note n
is 1, 2, 4, 8 or 16 and specifies the method of alignment.
.endnote
.np
The alignment of structure members is described in the following
table.
If the size of the member is 1, 2, 4, 8 or 16, the alignment is given
for each of the "zp" options.
If the member of the structure is an array or structure, the alignment
is described by the row "x".
.millust begin
                    zp1     zp2     zp4     zp8     zp16
sizeof(member)  \---------------------------------------
        1       |   0       0       0       0       0
        2       |   0       2       2       2       2
        4       |   0       2       4       4       4
        8       |   0       2       4       8       8
        16      |   0       2       4       8       16
        x       |   aligned to largest member
.millust end
.pc
An alignment of 0 means no alignment, 2 means word boundary,
4 means doubleword boundary, etc.
If the largest member of structure "x" is 1 byte then "x" is not
aligned.
If the largest member of structure "x" is 2 bytes then "x" is aligned
according to row 2.
If the largest member of structure "x" is 4 bytes then "x" is aligned
according to row 4.
If the largest member of structure "x" is 8 bytes then "x" is aligned
according to row 8.
If the largest member of structure "x" is 16 bytes then "x" is aligned
according to row 16.
.np
.if &version ge 107 .do begin
.if '&machine' eq '8086' .do begin
If no value is specified in the "pack" pragma, a default value of 2 is
used.
.do end
.if '&machine' eq '80386' .do begin
If no value is specified in the "pack" pragma, a default value of 8 is
used.
.do end
.do end
.el .do begin
If no value is specified in the "pack" pragma, a default value of 1 is
used.
.do end
Note that the default value can be changed with the "zp" &cmpname
compiler command line option.
.np
The following form of the "pack" pragma can be used to save the current
alignment amount on an internal stack.
.mbox begin
:prgbeg. pack ( push ) :prgend.
.mbox end
.np
The following form of the "pack" pragma can be used to save the current
alignment amount on an internal stack and set the current alignment.
.mbox begin
:prgbeg. pack ( push, :id.number:eid. ) :prgend.
.mbox end
.np
The following form of the "pack" pragma can be used to restore the
previous alignment amount from an internal stack.
.mbox begin
:prgbeg. pack ( pop ) :prgend.
.mbox end
.*
.section The READ_ONLY_FILE Pragma
.*
.np
.ix 'pragmas' 'read_only_file'
.ix 'read_only_file pragma'
.ix 'AUTODEPEND'
Explicit listing of dependencies in a makefile can often be tedious
in the development and maintenance phases of a project.
The &cmpname compiler will insert dependency information into the
object file as it processes source files so that a complete snapshot
of the files necessary to build the object file are recorded.
The "read_only_file" pragma can be used to prevent the name of the
source file that includes it from being included in the dependency
information that is written to the object file.
.np
This pragma is commonly used in system header files since they change
infrequently (and, when they do, there should be no impact on source
files that have included them).
.np
The form of the "read_only_file" pragma follows.
.mbox begin
:prgbeg. read_only_file :prgend.
.mbox end
.np
For more information on make dependencies, see the section
entitled "Automatic Dependency Detection (.AUTODEPEND)" in the
.book &product Tools User's Guide.
.*
.section The TEMPLATE_DEPTH Pragma (C++ Only)
.*
.ix 'pragmas' 'template_depth'
.ix 'template_depth pragma'
.np
The "template_depth" pragma provides a hard limit for the amount of
nested template expansions allowed so that infinite expansion can be
detected.
.np
The form of the "template_depth" pragma is as follows.
.mbox begin
:prgbeg. template_depth :op.(:eop. :id.n:eid. :op.):eop. :prgend.
.mbox end
.synote
.note n
is the depth of expansion.
If the value of
.id n
is less than 2, if will default to 2.
If
.id n
is not specified, a warning message will be issued and the default
value for
.id n
will be 100.
.esynote
.np
The following example of recursive template expansion illustrates why
this pragma can be useful.
.exam begin
#pragma template_depth(10);

template <class T>
struct S {
    S<T*> x;
};

S<char> v;
.exam end
.*
.section The WARNING Pragma (C++ Only)
.*
.np
.ix 'pragmas' 'warning'
.ix 'warning pragma'
The "warning" pragma sets the level of warning messages.
The form of the "warning" pragma is as follows.
.mbox begin
:prgbeg. warning :id.msg_num:eid. :id.level:eid. :prgend.
.mbox end
.synote
.note msg_num
is the number of the warning message.
.if &e'&dohelp eq 0 .do begin
This number corresponds to the number issued by the compiler and can
be found in the appendix entitled :HDREF refid='cppmsgs'..
.do end
.el .do begin
This number corresponds to the number issued by the compiler.
.do end
If
.id msg_num
is "*", the level of all warning messages is changed to the specified
level.
Make sure to strip all leading zeroes from the message number (to
avoid interpretation as an octal constant).
.note level
is a number from 0 to 9 and represents the level of the warning message.
When a value of zero is specified, the warning becomes an error.
.esynote
.*
.do end
.*
.section Auxiliary Pragmas
.*
.np
.ix 'pragmas' 'auxiliary'
.ix 'auxiliary pragma'
The following sections describe the capabilities provided by auxiliary
pragmas.
.if '&lang' eq 'FORTRAN 77' .do begin
.np
The backslash character ('\') is used to continue a pragma on the next
line.
Text following the backslash character is ignored.
The line continuing the pragma must start with a comment character
('c', 'C' or '*').
.do end
.*
.beglevel
.*
.section Specifying Symbol Attributes
.*