|
HP C
HP C User's Guide for OpenVMS Systems
On I64 systems, the default for /IEEE_MODE is DENORM_RESULTS, which is
a change from the default of /IEEE_MODE=FAST on Alpha systems. This
means that by default, floating-point operations may silently generate
values that print as Infinity or Nan (the industry-standard behavior),
instead of issuing a fatal run-time error as they would when using VAX
floating-point format or /IEEE_MODE=FAST. Also, the smallest-magnitude
nonzero value in this mode is much smaller because results are allowed
to enter the denormal range instead of being flushed to zero as soon as
the value is too small to represent with normalization.
The conversion of VAX floating-point formats to IEEE single and IEEE
double floating-point types on the Intel Itanium architecture is a
transparent process that will not impact most applications. All you
need to do is recompile your application. Because IEEE floating-point
format is the default, unless your build explicitly specifies VAX
floating-point format options, a simple rebuild for I64 systems will
use the native IEEE formats directly. For the large class of programs
that do not directly depend on the VAX formats for correct operation,
this is the most desirable way to build for I64 systems.
When you compile an OpenVMS application that specifies an option to use
VAX floating-point on an I64 system, the compiler automatically
generates code for converting floating-point formats. Whenever the
application performs a sequence of arithmetic operations, this code
does the following:
- Converts VAX floating-point formats to either IEEE single or IEEE
double floating-point formats.
- Performs arithmetic operations in IEEE floating-point arithmetic.
- Converts the resulting data from IEEE formats back to VAX formats.
Where no arithmetic operations are performed (VAX float fetches
followed by stores), no conversion will occur. The code handles such
situations as moves.
VAX floating-point formats have the same number of bits and precision
as their equivalent IEEE floating-point formats. For most applications
the conversion process will be transparent and thus a non-issue.
In a few cases, arithmetic calculations might have different results
because of the following differences between VAX and IEEE formats:
- Values of numbers represented
- Rounding rules
- Exception behavior
These differences might cause problems for applications that do any of
the following:
- Depend on exception behavior
- Measure the limits of floating-point behaviors
- Implement algorithms at maximal processor-specific accuracy
- Perform low-level emulations of other floating-point processors
- Use direct equality comparisons between floating-point values,
instead of appropriately ranged comparisons (a practice that is
extremely vulnerable to changes in compiler version or compiler
options, as well as architecture)
You can test an application's behavior with IEEE floating-point values
by compiling it on an OpenVMS Alpha system using
/FLOAT=IEEE_FLOAT/IEEE_MODE=DENORM. If that produces acceptable
results, then simply build the application on the OpenVMS I64 system
using the same qualifier.
If you determine that simply recompiling with an /IEEE_MODE qualifier
is not sufficient because your application depends on the binary
representation of floating-point values, then first try building for
your I64 system by specifying the VAX floating-point option that was in
effect for your VAX or Alpha build. This causes the representation seen
by your code and on disk to remain unchanged, with some additional
run-time cost for the conversions generated by the compiler. If this is
not an efficient approach for your application, you can convert VAX
floating-point binary data in disk files to IEEE floating-point formats
before moving the application to an I64 system.
/GRANULARITY=option
Controls the size of shared data in memory that can be safely accessed
from different threads. The possible size values are BYTE, LONGWORD,
and QUADWORD.
Specifying BYTE allows single bytes to be accessed from different
threads sharing data in memory without corrupting surrounding bytes.
This option will slow run-time performance.
Specifying LONGWORD allows naturally aligned 4-byte longwords to be
accessed safely from different threads sharing data in memory.
Accessing data items of 3 bytes or less, or unaligned data, may result
in data items written from multiple threads being inconsistently
updated.
Specifying QUADWORD allows naturally aligned 8-byte quadwords to be
accessed safely from different threads sharing data in memory.
Accessing data items of 7 bytes or less, or unaligned data, might
result in data items written from multiple threads being inconsistently
updated. This is the default.
/IEEE_MODE=option
Selects the IEEE floating-point mode to be used if /FLOAT=IEEE_FLOAT is
specified.
Table 1-10 describes the /IEEE_MODE options.
Table 1-10 /IEEE_MODE Options
Option |
Usage |
FAST
|
During program execution, only finite values (no infinities, NaNs, or
denorms) are created. Underflows and denormal values are flushed to
zero. Exceptional conditions, such as floating-point overflow,
divide-by-zero, or use of an IEEE exceptional operand are fatal.
|
UNDERFLOW_TO_ZERO
|
Generate infinities and NaNs. Flush denormalized results and underflow
to zero without exceptions.
|
DENORM_RESULTS
|
Same as UNDERFLOW_TO_ZERO, except that denorms are generated.
|
INEXACT
|
Same as DENORM_RESULTS, except that inexact values are trapped. This is
the slowest mode, and is not appropriate for any sort of
general-purpose computations.
|
On Alpha systems, the default is /IEEE_MODE=FAST.
On I64 systems, the default is /IEEE_MODE=DENORM_RESULTS.
The INFINITY and NAN macros defined in <math.h> are
available to programs compiled with /FLOAT=IEEE and
/IEEE_MODE={anything other than FAST}, and in a compiler mode
that enables C99 extensions in the headers (any mode other than COMMON
or VAXC).
On Alpha sytems, the /IEEE_MODE qualifier generally has its greatest
effect on the generated code of a compilation. When calls are made
between functions compiled with different /IEEE_MODE qualifiers, each
function produces the /IEEE_MODE behavior with which it was compiled.
On I64 systems, the /IEEE_MODE qualifier primarily affects only the
setting of a hardware register at program startup. In general, the
/IEEE_MODE behavior for a given function is controlled by the
/IEEE_MODE option specified on the compilation that produced the main
program: the startup code for the main program sets the hardware
register according the command-line qualifiers used to compile the main
program.
When applied to a compilation that does not contain a main program, the
/IEEE_MODE qualifier does have some effect: it might affect the
evaluation of floating-point constant expressions, and it is used to
set the EXCEPTION_MODE used by the math library for calls from that
compilation. But the qualifier has no effect on the exceptional
behavior of floating-point calculations generated as inline code for
that compilation. Therefore, if floating-point exceptional behavior is
important to an application, all of its compilations, including the one
containing the main program, should be compiled with the same
/IEEE_MODE setting.
Even on Alpha systems, the particular setting of
/IEEE_MODE=UNDERFLOW_TO_ZERO has this characteristic: its primary
effect requires the setting of a run-time status register, and so it
needs to be specified on the compilation containing the main program in
order to be effective in other compilations.
/[NO]INCLUDE_DIRECTORY=(pathname[,...])
Provides similar functionality to the -I option of the cc
command on Tru64 UNIX systems. This qualifier allows you to
specify additional places to search for include files. A place can be
one of the following:
- OpenVMS file-spec to be used as a default file-spec to RMS file
services (example: DISK$:[directory])
- UNIX style pathname in quotation marks (example: "/sys")
- Empty string ("")
If one of the places is specified as an empty string, the compiler does
not search any of its conventionally-named places:
- DECC$USER_INCLUDE
- DECC$SYSTEM_INCLUDE
- DECC$LIBRARY_INCLUDE
- SYS$COMMON:[DECC$LIB.INCLUDE.*]
- DECC$TEXT_LIBRARY
- SYS$LIBRARY:DECC$RTLDEF.TLB
- SYS$LIBRARY:SYS$STARLET_C.TLB
Instead, it searches only places specified explicitly on the command
line by the /INCLUDE_DIRECTORY and /LIBRARY qualifiers (or by the
location of the primary source file, depending on the
/NESTED_INCLUDE_DIRECTORY qualifier). This behavior is similar to that
obtained by specifying -I without a directory name to the Tru64
UNIX cc command.
The basic search order depends on the form of the header-file name
(after macro expansion). Additional aspects of the search order are
controlled by other command-line qualifiers and the presence or absence
of logical name definitions.
Only the portable forms of the #include directive are affected
by the pathnames specified on an /INCLUDE_DIRECTORY qualifier:
- In quotes (example: #include "stdio.h")
- In angle brackets (example: #include <stdio.h>)
However, an empty string also affects the text-module form specific to
OpenVMS systems (example: #include stdio).
Except where otherwise specified, searching a "place" means that the
string designating the place is used as the default file-spec in a call
to an RMS system service (for example, $SEARCH/$PARSE). The file-spec
consists of the name in the #include directive without
enclosing delimiters. The search terminates successfully as soon as a
file can be opened for reading.
Note
Prior to OpenVMS VAX Version 7.1, the operating system did not provide
a SYS$LIBRARY:SYS$STARLET_C.TLB nor the headers contained therein.
Instead, the compiler installation generated these headers and placed
them in SYS$LIBRARY:DECC$RTLDEF.TLB.
|
Quoted Form
For the quoted form of inclusion, the search order is:
- One of the following:
- If /NESTED_INCLUDE_DIRECTORY=INCLUDE_FILE (the default) is in
effect, search the directory containing the file in which the
#include directive itself occurred. The directory
containing means the RMS resultant string obtained when the file
in which the #include occurred was opened, except that the
filename and subsequent components are replaced by the default file
type for headers (".h", or just "." if /ASSUME=NOHEADER_TYPE_DEFAULT is
in effect). The resultant string will not have translated any concealed
device logical.
- If /NESTED_INCLUDE_DIRECTORY=PRIMARY_FILE is in effect, search the
default file type for headers using the context of the primary source
file. This means that just the file type (".h" or ".") is used for the
default file-spec but, in addition, the chain of "related file-specs"
used to maintain the sticky defaults for processing the next top-level
source file is applied when searching for the include file. This most
closely matches the behavior of the VAX C compiler.
- If /NESTED_INCLUDE_DIRECTORY=NONE is in effect, this entire step
(Step 1) is bypassed.
- Search the places specified in the /INCLUDE_DIRECTORY qualifier, if
any. A place that can be parsed successfuly as an OpenVMS file-spec and
that does not contain an explicit file type or version specification is
edited to append the default header file type specification (".h" or
".").
A place containing a "/" character is considered to be a
UNIX-style name. If the name in the #include directive also
contains a "/" character that is not the first character and is not
preceded by a "!" character (it is not an absolute UNIX-style
pathname), then the name in the #include directive is appended
to the named place, separated by a "/" character, before applying the
decc$to_vms pathname translation function. The result of the
decc$to_vms translation is then used as the filespec to try to open.
-
If DECC$USER_INCLUDE is defined as a logical name, search
DECC$USER_INCLUDE:.H, or just DECC$USER_INCLUDE:. if
/ASSUME=NOHEADER_TYPE_DEFAULT is in effect.
- If the file is not found, follow the steps for the angle-bracketed
form of inclusion.
Angle-Bracketed Form
For the angle-bracketed form of inclusion, the search order is:
- Search the place "/". This is a UNIX-style name that can combine
only with UNIX names specified explicitly in the #include
directive. It causes a specification like <sys/types.h> to be
considered first as /sys/types.h, which is translated by decc$to_vms to
SYS:TYPES.H.
- Search the places specified in the /INCLUDE_DIRECTORY qualifier,
exactly as in Step 2 for the quoted form of inclusion.
-
If DECC$SYSTEM_INCLUDE is defined as a logical name, search
DECC$SYSTEM_INCLUDE:.H, or just DECC$SYSTEM_INCLUDE:. if
/ASSUME=NOHEADER_TYPE_DEFAULT is in effect.
-
If DECC$LIBRARY_INCLUDE is defined as a logical name and
DECC$SYSTEM_INCLUDE is not defined as a logical name, search
DECC$LIBRARY_INCLUDE:.H, or just DECC$LIBRARY_INCLUDE:. if
/ASSUME=NOHEADER_TYPE_DEFAULT is in effect.
- If neither DECC$LIBRARY_INCLUDE nor DECC$SYSTEM_INCLUDE are defined
as logical names, then search the default list of places for plain
text-file copies of compiler header files as follows:
- SYS$COMMON:[DECC$LIB.INCLUDE.DECC$RTLDEF]*.H
- SYS$COMMON:[DECC$LIB.INCLUDE.SYS$STARLET_C]*.H
Note
The compiler installation does not create these directories of header
files. Instead, it creates [DECC$LIB.REFERENCE] for your convenience.
But if you choose to create and populate
SYS$COMMON:[DECC$LIB.INCLUDE.DECC$RTLDEF] or
SYS$COMMON:[DECC$LIB.INCLUDE.SYS$STARLET_C], the compiler will search
them.
|
If the file is not found, perform the text library search described
in the next step.
- Extract the simple filename and file type from the
#include specification and use the filename as the module name
to search a list of text libraries associated with that file type.
For any file type, the initial text libraries searched consist of
those named on the command line with /LIBRARY qualifiers, searched in
left-to-right order. If the /INCLUDE_DIRECTORY qualifier contained
an empty string, no further text libraries are searched. Otherwise,
DECC$TEXT_LIBRARY is searched for all file types.
If DECC$LIBRARY_INCLUDE is defined as a logical name, then no further
text libraries are searched. Otherwise, the subsequent libraries
searched for each file type are:
- For a file type of ".h" or ".":
- SYS$LIBRARY:DECC$RTLDEF.TLB
- SYS$LIBRARY:SYS$STARLET_C.TLB
- For a file type other then ".h" or ".":
- SYS$LIBRARY:SYS$STARLET_C.TLB
- If the previous step fails, search the following:
Under /ASSUME=NOHEADER_TYPE_DEFAULT, the default file type is
modified as usual.
Text-Module Form
For the text-module (nonportable) form of inclusion, the name can only
be an identifier. It, therefore, has no associated file type.
The identifier is used as a module name to search the following:
- The text libraries named on the command line with /LIBRARY
qualifiers, in left-to-right order.
- The following list of text libraries in the order shown (unless the
/INCLUDE_DIRECTORY qualifier contains an empty string, in which case no
further text libraries are searched):
- DECC$TEXT_LIBRARY
- SYS$LIBRARY:DECC$RTLDEF.TLB
- SYS$LIBRARY:SYS$STARLET_C.TLB
The default for this qualifer is /NOINCLUDE_DIRECTORY.
/L_DOUBLE_SIZE=option
Determines how the compiler interprets the long double type.
The qualifier options are 64 and 128.
Specifying /L_DOUBLE_SIZE=64 treats all long double references
as G_FLOAT, D_FLOAT, or T_FLOAT, depending on the value of the /FLOAT
qualifier.
Specifying /L_DOUBLE_SIZE=128 treats all long double
references as X_FLOAT.
The default is /L_DOUBLE_SIZE=128.
/LIBRARY
Indicates that the associated input file is a library containing
modules of HP C source text. If the library specification does
not include a file extension, the CC command line assumes the .TLB
default type. You must join the /LIBRARY qualifier with a file
specification in a compilation unit using a plus sign (+); you cannot
place the qualifier at other places on the CC command line. No matter
where you place the /LIBRARY qualifier in a compilation unit, all files
in the unit may make reference to modules within that library. Consider
the following example:
$ CC ONE + TWO + THREE/LIBRARY[Return]
|
Files ONE.C and TWO.C can contain references to modules in THREE.TLB.
Consider the following example:
$ CC ONE + TWO + THREE/LIBRARY, FOUR[Return]
|
The file FOUR.C cannot contain references to modules in THREE.TLB since
FOUR.C is located in a separate compilation unit separated by a comma.
The placement of the library file specification does not matter. The
following command lines are equivalent:
$ CC THREE/LIBRARY + ONE + TWO[Return]
$ CC ONE + THREE/LIBRARY + TWO[Return]
$ CC ONE + TWO + THREE/LIBRARY[Return]
|
/[NO]LINE_DIRECTIVES
Governs whether or not #line directives appear in preprocess
output files.
The default is /LINE_DIRECTIVES.
/[NO]LIST[=file-spec]
Produces a source program listing. You must specify this qualifier to
get a listing. None of the other qualifiers use /LIST by default.
By default, /LIST creates a listing file with the same name as the
source file and with a file extension of .LIS. If you include a file
specification with the /LIST qualifier, the compiler uses that
specification to name the listing file.
In interactive mode, the default is /NOLIST. In batch mode, the default
is /LIST. See the descriptions of the qualifiers /[NO]MACHINE_CODE, and
/SHOW for related information. (For example, to suppress compiler
messages to the terminal or to a batch log file, use the
/SHOW=NOTERMINAL qualifier.)
/[NO]MACHINE_CODE[=option]
Lists the generated machine code in the listing file. To produce the
listing file, you must also specify /LIST.
On OpenVMS VAX systems, several formats exist to list machine code.
Table 1-11 describes the /MACHINE_CODE qualifier options.
Table 1-11 /MACHINE_CODE Qualifier Options (VAX ONLY)
Option |
Usage |
AFTER
|
Causes the lines of machine code produced during compilation to print
after all the source code in the listing.
|
BEFORE
|
Causes lines of machine code produced during compilation to print
before any source code in the listing.
|
INTERSPERSED
|
Produces a listing consisting of lines of source code followed by the
corresponding lines of machine code. This is the default option.
|
On OpenVMS Alpha sytems, the format of the generated machine code
listing is similar to what you would get using the AFTER keyword on
OpenVMS VAX systems.
The default is /NOMACHINE_CODE.
/[NO]MAIN=POSIX_EXIT
Directs the compiler to call __posix_exit instead of
exit when returning from main.
The default is /NOMAIN.
/[NO]MEMBER_ALIGNMENT
Controls whether the compiler naturally aligns data structure members.
Natural alignment means that data structure members are aligned on the
next boundary appropriate to the type of the member, rather than on the
next byte. For instance, a long variable member is aligned on
the next longword boundary; a short variable member is aligned
on the next word boundary.
Any use of the #pragma member_alignment or #pragma
nomember_alignment directives within the source code overrides the
setting established by this qualifier. Specifying /NOMEMBER_ALIGNMENT
causes data structure members to be byte-aligned (with the exception of
bit-field members).
On OpenVMS Alpha systems, the default is /MEMBER_ALIGNMENT.
On OpenVMS VAX systems, the default is /NOMEMBER_ALIGNMENT.
See the description of #pragma [no]member_alignment in
Section 5.4.13.
/[NO]MMS_DEPENDENCIES[=(option[,...])]
Directs the compiler to produce a dependency file. Dependency files
list all source files and included files for each object module. Note
that the /OBJECT qualifier has no impact on the dependency file. The
dependency file format is:
object_file_name :<tab><source file name>)
object_file_name :<tab><full path to first include file>)
object_file_name :<tab><full path to second include file>)
|
Table 1-12 shows the /MMS_DEPENDENCIES qualifier options.
Table 1-12 /MMS_DEPENDENCIES Qualifier Options
Option |
Usage |
FILE[=filespec]
|
Specifies where to save the dependency file. The default file extension
for a dependency file is
.mms. Other than using this different default extension,
/MMS_DEPENDENCY uses the same procedure that the /OBJECT and /LIST
qualifiers do for determining the name of the output file.
|
[NO]SYSTEM_INCLUDE_FILES
|
Specifies whether or not to include dependency information about system
include files (those included with
#include <
filename>.) If omitted, this option defaults to
including dependency information about system include files.
|
TARGET=string
|
Specifies the target that appears in the output
.mms file. The default is TARGET="" in which case the target
is the source file name with a .OBJ extension, as in previous versions
of the compiler. If you specify any string other than .OBJ, that string
is used as the target. For the special case of .OBJ, the compiler uses
the name of the object file (stripped of any version number and path)
for the MMS target.
Examples:
-
$ CC/MMS/OBJ=OUTPUT T.C
This command produces an
.mms file with a target of T.OBJ :
-
$ CC/MMS=(TARGET=FOO)/OBJ=OUTPUT T.C
This command produces an
.mms file with a target of FOO :
-
$ CC/MMS=(TARGET=.OBJ)/OBJ=OUTPUT T.C
This command produces an
.mms file with a target of OUTPUT.OBJ :
|
The default is /NOMMS_DEPENDENCY.
/NAMES=(option1,option2)
Option1 converts all definitions and references of external symbols and
psects to the case specified. Table 1-13 lists the option1 case
values.
Table 1-13 /NAMES Qualifier Option1 Values
Option |
Usage |
UPPERCASE
|
Converts to uppercase.
|
AS_IS
|
Leaves the case as specified in the source.
|
Option2 controls whether or not external names greater than 31
characters get truncated or shortened. Table 1-14 lists the option2
values.
Table 1-14 /NAMES Qualifier Option2 Values
Option |
Usage |
/NAMES=TRUNCATED (default)
|
Truncates long external names.
|
/NAMES=SHORTENED
|
Shortens long external names.
A shortened name consists of the first 23 characters of the name
followed by a 7-character Cyclic Redundancy Check (CRC) computed by
looking at the full name, and then a "$".
The CRC is generated by calling lib$crc as follows:
long initial_crc = -1;
crc_result = lib$crc(good_crc_table,
&initial_crc,
<descriptor of string to CRC>);
where good_crc_table is:
/*
** Default CRC table:
**
** This table was taken from Ada's
** generalized name generation algorithm.
** It represents a commonly used CRC
** polynomial known as AUTODIN-II.
** For more information see the VAX
** Macro OpenVMS documentation under the
** CRC VAX instruction.
*/
static const unsigned int good_crc_table[16] =
{0x00000000, 0x1DB71064, 0x3B6E20C8, 0x26D930AC,
0x76DC4190, 0x6B6B51F4, 0x4DB26158, 0x5005713C,
0xEDB88320, 0xF00F9344, 0xD6D6A3E8, 0xCB61B38C,
0x9B64C2B0, 0x86D3D2D4, 0xA00AE278, 0xBDBDF21C};
|
The default is /NAMES=(UPPERCASE,TRUNCATED), which provides the same
conversion-to-uppercase behavior as VAX C, and truncates the name to 31
characters.
Notes
On OpenVMS VAX systems, the /NAMES qualifier does not affect the names
of the $CODE and $DATA psects.
On OpenVMS Alpha systems, the /NAMES qualifier does not affect the
names of the $ABS$, $BSS$, $CODE$, $DATA$, $LINK$, $LITERAL$, and
$READONLY$ psects.
Specifying /NAMES=SHORTENED turns on the /REPOSITORY qualifier.
|
/NESTED_INCLUDE_DIRECTORY[=option]
Controls the first step in the compiler's search algorithm for finding
files that are included using the quoted form of the #include
preprocessing directive:
Table 1-15 describes the /NESTED_INCLUDE_DIRECTORY qualifier
options.
Table 1-15 /NESTED_INCLUDE_DIRECTORY Qualifier Options
Option |
Usage |
PRIMARY_FILE
|
Directs the compiler to search the default file type for headers using
the context of the primary source file (the .C file). This means that
just the file type (".h" or ".") is used for the default file-spec, but
the chain of "related file-specs" used to maintain the sticky defaults
for processing the next top-level source file is also applied when
searching for the include file. This most closely matches the behavior
of VAX C.
|
INCLUDE_FILE
|
Directs the compiler to first search the directory of the source file
containing the
#include directive. If the file to be included is not found,
the compiler continues searching by following normal inclusion rules.
|
NONE
|
Directs the compiler to skip the first step of processing
#include "
file.h" directives. The compiler starts its search for
the include file in the /INCLUDE_DIRECTORY directories. It does not
start by looking in the directory containing the including file or in
the directory containing the top level source file.
|
|