DEC C++

DEC C++

Using DEC C++ for DIGITAL UNIX Systems

 Order Number: AA–PX2BF–TE

June 1997

 This manual contains information about developing DEC C++ programs on DIGITAL UNIX systems. It describes language features specific to DEC C++ for DIGITAL UNIX Systems.

Revision/Update Information: This is a revised manual.

Software Version: DEC C++ Version 5.7 for DIGITAL UNIX

Digital Equipment Corporation
Maynard, Massachusetts

First Printing, March 1993
First Revision, May 1994
Second Revision, July 1994
Third Revision, May 1995
Fourth Revision, March 1996
Fifth Revision, October 1996
Sixth Revision, June 1997

The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document.

The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license.

Copyright ©1993, 1994, 1995, 1996, 1997

The following are trademarks of Digital Equipment Corporation: DEC, DEC FUSE, DECthreads, Ladebug, OpenVMS, ULTRIX, VAX, VAX DOCUMENT, VMS, the DEC C++ logo, and the DIGITAL logo.

The following are third-party trademarks:

AT&T is a registered trademark of American Telephone and Telegraph Company.

Hewlett-Packard is a registered tradmark of the Hewlett-Packard Company.

IEEE is a registered trademark of the Institute of Electrical and Electronics Engineers, Inc.

Microsoft is a registered trademark, and Visual C++ is a trademark of Microsoft Corporation.

OSF/1 is a registered tradmark of the Open Software Foundation, Inc.

POSIX is a registered certification mark of the Institute of Electrical and Electronic Engineers.

UNIX is a registered trademark in the United States and other countries,

Portions of the ANSI C++ Standard Library have been implemented using source licensed from and copyrighted by Rogue Wave Software, Inc.

Information pertaining to the C++ Standard Library has been edited and reprinted with permission of, Rogue Wave Software, Inc. All rights reserved.

Portions copyright 1994-1996 Rogue Wave Software, Inc.

ZK6388

This document is available on CD-ROM.

Contents Index

Preface

This manual contains information for developing and debugging DEC C++ programs on DIGITAL UNIX systems, and includes information on other DIGITAL UNIX features and tools that work with DEC C++.

Intended Audience

This manual is intended for experienced programmers who need to develop DEC C++ programs on DIGITAL UNIX systems. Users of this manual should have a basic understanding of the C++ language and some familiarity with the DIGITAL UNIX operating system.

Structure of this Document

This manual is organized as follows:

Associated Documents

The following documents contain information associated with topics in this manual:

The C++ Programming Language, 2nd Edition and the STL Tutorial and Reference Guide are available only in printed form. Online copies are not available.

Related Documents

The following documents are not included in the DEC C++ documentation set. Refer to them for additional information on the C++ programming language, DEC C, or DIGITAL UNIX programming.

Conventions Used in this Manual

Table 1 lists the conventions used in this manual.

Table 1 Conventions Used in this Manual
Convention Meaning
% A percent sign (%) is the default user prompt.
class complex{
.
.
.
}; 		A vertical ellipsis indicates that some intervening program code or output is not shown. Only the more pertinent material is shown in the example.
,... A horizontal ellipsis in a syntax description indicates that you can enter additional parameters, options, or values. A comma preceding the ellipsis indicates that successive items must be separated by commas.
The generic class...
The get() function... 		Monospaced type denotes the names of DEC C++ language elements, and also the names of classes, members, and nonmembers. Monospaced type is also used in text to reference code elements displayed in examples and file-name extensions.
italic Italic type denotes the names of variables that appear as parameters or in arguments to functions, and also denotes book titles.
boldface Boldface type in text indicates the first instance of terms defined in text.
UPPERCASE
lowercase 		The DIGITAL UNIX operating system distinquishes between uppercase and lowercase characters. Literal strings that appear in text, examples, syntax descriptions, and function definitions must be entered exactly as shown.
cxx (1) Cross-references to reference pages include the appropriate section number in parentheses.

Reader's Comments

You may send comments or suggestions regarding this manual, or any DEC C++ document, by electronic mail to the following Internet address:

cxx_docs@bookie.enet.dec.com

If you have access to a FAX machine, you may send your comments or suggestions to:

DEC C++ Documentation, ZKO2-3/K35
603-881-0120

Chapter 1
Building and Running DEC C++ Programs

This chapter provides information about the basic steps involved in developing a DEC C++ program on a DIGITAL UNIX system. It explains how to compile, link, and debug DEC C++ programs.

DEC C++ is an implementation of the C++ programming language. The DEC C++ compiler is part of the DIGITAL UNIX compiler system. See the DIGITAL UNIX Programmer's Guide for program development information that applies to all DIGITAL UNIX languages, such as using the compiler system, creating shared libraries, profiling, and optimization.

1.1 Compiling a DEC C++ Program

The cxx command invokes the DEC C++ compiler. For a full description of the cxx command, see Using the DEC C++ Compiler in this chapter, or the cxx(1) reference page. For additional information about this release, see the online release notes in: 


/usr/lib/cmplrs/cxx/DECCXXnnn.release-notes

You can compile a mixture of C++ and C source code by entering a single cxx compile command. The DEC C++ compiler distinguishes between C++ source files (for example, .cxx) and C source files (for example, .c) based on their file extensions, and compiles the modules appropriately.

Unless you use the -x option to direct the DEC C++ compiler to ignore file-name extensions, passing a file with a .c extension to the cxx command causes the compiler driver to treat the file as a C file and pass it on to the cc command. If the file contains C++ code instead of C code, the compilation may produce errors.

Using the DEC C++ Compiler

The cxx command invokes the DEC C++ compiler, and possibly other components of the compiler system, depending on the specified command options and files. When you start the cxx compiler, it normally performs the following tasks:

The cxx command compiles C++ code into machine-readable instructions. The desired output is specified with an option on the command line, and can be object files or symbolic assembly language.

The compiler produces one object file for each file that is compiled. If the linker is called and only one source file was specified on the command line, the single object file is deleted after the linking operation.

Syntax 


/usr/bin/cxx [ option ] ...file ...

An option is an optional list of compile-time options.

A file is one or more file specifications separated by white space.

You cannot group multiple options after a single hyphen; that is, -pg is different than -p -g.

Supply complete relative or absolute path information when the source file is not in your current directory.

Use the -c option to stop compiler operation before linking, which results in one or more output files with the .o extension. Use the -E option to run only the preprocessor.

The detection of an error in one source file does not affect compilation of other source files specified on the same command line.

Unless you use the -x option to direct the DEC C++ compiler to ignore file-name extensions, the compiler recognizes the following extensions as having the special significance noted:
.cxx
.CXX
.cpp
.CPP
.cc
.CC
.C 		C++ source code.
.hxx C++ header file.
.ixx C++ source code already processed by the preprocessor.
.a Linker library. -x has no effect on files with this extension.
.c C source code to be compiled with the DEC C compiler.
.i C source code already processed by the preprocessor.
.o Linker object module. -x has no effect on files with this extension.
.so Shared object (shared library).

Command options recognized by the cxx compiler are described in the General Options section in this chapter. Some of the options affect the behavior of the preprocessor. The preprocessor is invoked through the cxx command for C++ files, and is not invoked with a separate command. Any options not recognized by the cxx compiler are assumed to be linker options and are passed through to the linker. See the ld(1) reference page for linker options.

Macro Names

The following standard macro names are understood by the preprocessor. These names cannot be redefined or undefined.
__LINE__ The current line number (a decimal integer).
__FILE__ The current file name (a character string).
__DATE__ The source file's compilation date (a character string literal of the form "Mmm dd yyyy", where the month names are the same as those generated by the asctime function, and the first character of "dd" is a space character if the value is less than 10).
__TIME__ The source file's compilation time (a character string literal of the form "hh:mm:ss", as in the time generated by the asctime function).

In addition, the following macro names are predefined for DEC C++. These names can be undefined or redefined.

These names are useful in preprocessor #ifdef and #if defined directives to isolate code intended for one of the particular cases. You can use these names anywhere you use other defined names, including within macros.

General Options

The following general options are supported by the cxx command:
-assume option Allow the compiler to make assumptions regarding certain alignments or code transformations. The following options are supported:
  [no]accuracy_sensitive --- specifies whether certain code transformations that affect floating-point operations are allowed. These changes may affect the accuracy of the program's results.

The accuracy_sensitive option directs the compiler to use only certain scalar rules for calculations. This setting can prevent some optimizations. This is the default.

The noaccuracy_sensitive option frees the compiler to reorder floating-point operations based on algebraic identities (inverses, associativity, and distribution). This allows the compiler to move divide operations outside of loops, which may improve performance.

  [no]aligned_objects --- controls the alignment assumptions for code generated for indirect load and store instructions.
  The aligned_objects option causes the compiler to assume that a dereferenced object's alignment matches or exceeds the alignment indicated by the pointer to the object. This is the default. On DIGITAL UNIX systems, dereferencing a pointer to a longword- or quadword-aligned object is more efficient than dereferencing a pointer to a byte- or word-aligned object. Therefore, when the compiler assumes that a pointer object of an aligned pointer type does point to an aligned object, it can generate better code for pointer dereferences of aligned pointer types.
  The noaligned_objects option causes the compiler to generate longer code sequences to perform indirect load and store operations to avoid hardware alignment faults for arbitrarily aligned addresses. Although this flag may generate less efficient code than the aligned_objects option, by avoiding hardware alignment faults, it speeds the execution of programs that reference unaligned data.
  The compiler assumes that the alignment of pointers meets or exceeds that of the objects to which they point. The following rules apply:
  • A pointer of type short points to objects that are at least short-aligned.
  • A pointer of type int points to objects that are at least int-aligned.
  • A pointer of type struct points to objects that have an alignment that is the strictest member alignment, or byte alignment if you have specified #pragma nomember_alignment for struct .
  If your module breaks one of these rules, using the noaligned_objects flag to compile the module will ensure that your program does not get alignment faults during execution (having such faults degrades performance). However, if relatively few of the pointers in a large module point to unaligned data, the noaligned_objects flag approach may be unnecessarily heavy-handed; a suitable alternative would be to add the __unaligned type qualifier to the pointer definitions in question. When data is accessed through a pointer declared __unaligned , the compiler generates the additional code necessary to copy or store the data without causing alignment errors.

The aligned_objects and noaligned_objects options can be used in the same cxx command, permitting you to turn this option on and off as needed by individual source files.

  [no]trusted_short_alignment --- allows the compiler additional assumptions about the alignment of short types that, although naturally aligned, may cross a quadword boundary.

The trusted_short_alignment option indicates that the compiler should assume any short type accessed through a pointer is naturally aligned. This generates the fastest code, but can silently generate the wrong results when an unaligned short object crosses a quadword boundary.

The notrusted_short_alignment option tells the compiler that short objects may not be naturally aligned. The compiler generates slightly larger (and slower) code that will give the correct result, regardless of the actual alignment of the data. This is the default.

Note that the notrusted_short_alignment option does not override the __unaligned type qualifier, the -misalign option, or the -assume noaligned_objects option.

-B string Append string to all names specified by the -t flag. If no -t flag has been processed before the -B option, then a -B string is passed to the loader to use with its -lx arguments and the -t flag is assumed to be hpfjusmocablyzrntL . This list designates all names.

Invoking the compiler with a name of the form cxx string has the same effect as using a -B string option on the command line.

-c Suppress the linking phase of the compilation and force production of one or more object files with the .o extension. If the file-name argument already has the .o extension, do nothing at all.
-call_shared Produce a dynamic executable file that uses sharable objects during run time. This is the default. The loader uses shareable objects to resolve undefined symbols. The run-time loader (/sbin/loader) is invoked to bring in all required shareable objects and to resolve any symbols that remained undefined during static link time.
-cfront Interpret source programs according to certain language rules followed by AT&T's "cfront" implementation. This option also defines the macro __CFRONT .
-check Perform compile-time code checking. With this option, the compiler checks for code that exhibits nonportable behavior, represents a possible unintended code sequence, or possibly affects program operation because of a quiet change in the language standard. Some of these checks traditionally have been associated with the lint utility.
-compress Cause the output object file to be produced in compressed object-file format, resulting in a substantially smaller object file. Use of this option passes the -compress flag to the cc compiler driver when linking.
-cord Run the procedure rearranger on the resulting file after linking. Rearrangement is performed to reduce the cache conflicts of the program's text. At least one -feedback file must be specified.
-define_templates Interpret each use of a template as an attempt to define the template. For class templates, a use is an occurrence of a template class name that instantiates a version of the class template. For function templates, a use is a call that matches the function template.
-denorm Force denormalized constant numbers to 0 when IEEE support is enabled.
-feedback file This option is used with the -cord option to specify a feedback file. The feedback file is produced by the prof command with its -feedback option from an execution of the program produced by the pixie command.
-fprm option Specify rounding mode. Only one -fprm option can be used on a command line. The following options are supported:
c Round toward 0 (chop).
d Set rounding mode for IEEE floating-point instructions dynamically, as determined from the contents of the floating-point control register. The dynamic rounding mode can be changed or read at execution time by a call to write_rnd(3) or read_rnd(3) . If you specify this option, the IEEE floating-point rounding mode defaults to round to nearest.
m Round toward minus infinity.
n Set normal rounding mode (unbiased round to nearest). This is the default.
-fptm option Specify trapping mode. Only one -fptm option can be used on a command line. The following options are supported:
n Generate instructions that do not trigger floating-point underflow or inexact trapping modes. Any floating point overflow, divide-by-zero, or invalid operation will unconditionally generate a trap. This is the default.
u Generate intructions that trap floating-point underflow, overflow, divide-by-zero, and invalid operations.

To use IEEE floating-point semantics, see the -ieee command line option.

-fp_reorder Same as -assume noaccuracy_sensitive .
-g Produce symbol table information for full symbolic debugging, but do not perform optimizations that limit full symbolic debugging. Same as -g2 .
-g0 Do not produce symbol table information for symbolic debugging. This is the default.
-g1 Produce symbol table information for accurate, but limited, symbolic debugging of partially optimized code.
-g2 Produce symbol table information for full symbolic debugging, but do not perform optimizations that limit full symbolic debugging. Same as -g .
-g3 Produce symbol table information for full symbolic debugging of fully optimized code. This option can affect debugger accuracy.
-G num Specify the maximum size, in bytes, of a data item that is to be accessed from the global pointer. The num argument is interpreted as a decimal number. If num is 0, data is not accessed from the global pointer. The default value for num is 8 bytes.
-gen_feedback Generate accurate profile information to be used with -feedback optimizations. Such optimizations should be used in the compiling and linking phases. When compiling a program for profiling, add -gen_feedback to your existing set of command line options. The -feedback flag should not be used when generating profile information.
-h path Use the specified path instead of the directory where the name specified by the -t flag is normally found.
-H c Halt compiling after the stage specified by the character c, producing an intermediate file for the next stage. The c argument can be any one of the following:
  • f C++ compiling and template instantiating
  • a as0
  • b as1
  • l ld
  • y ftoc
  • z cord
-ieee Support all portable features of the IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Standard 754-1985), including the treatment of denormalized numbers, NaNs, infinities, and the handling of error cases. This option also sets the _IEEE_FP macro.

If your program must use IEEE signaling features that are not portable across different IEEE implementations, see the ieee(3) reference page for information on how to access these features under the DIGITAL UNIX operating system.

-inline keyword Provide inline expansion of functions that yield optimized code when they are expanded. Functions must conform to the rules specified in the description of the #pragma inline preprocessor directive to be eligible for inline expansion. In choosing calls to expand inline, the compiler also considers the function size, how often the call is executed, how many registers the inline expansion will require, and other factors. The following keywords are supported:
  none Do not do any inlining. This is the default when compiling with the -O0 and -O1 optimization level.
  manual Inline only those function calls explicitly requested for inlining by an inline keyword. This is the default when compiling with the -O2 and -O3 flags.
  size Inline all of the function calls in the manual category, plus any additional calls that the compiler determines would improve run-time performance without significantly increasing the size of the program. This is the default when compiling with -O , -O4 , or -O5 .
  speed Inline all of the function calls in the manual category, plus any additional calls that the compiler determines would improve run-time performance, even where it may significantly increase the size of the program.
  all Inline every call that can be inlined while still generating correct code. Recursive routines, however, will not cause an infinite loop at compile time.
  For optimization level 0 ( -O0 ), the compiler ignores the -inline option and no inlining is done.
-K Build and use intermediate files, producing a file with the conventional extension for the type of file. These intermediate files are not removed, even when a stage encounters a fatal error. Extensions are appended to the output if it does not already have an extension.
-machine_code List the generated machine code in the listing file. To produce the listing file, you must also specify -source_listing . The default is to not list the generated machine code.
-misalign Specify that code generated for indirect load and store instructions should not generate alignment faults for arbitrarily aligned addresses. Using this option increases the size of generated code and might have a negative impact on performance.

The default condition is for code generated for indirect load instructions and store instructions to generate alignment faults for arbitrarily aligned addresses. Same as -assume noaligned_objects .

-ms Interpret source programs according to certain language rules followed by Microsoft's Visual C++. This option also defines the macro __MS .
-no_misalign Negate the -misalign option. Same as -assume aligned_objects .
-no_pg Selectively disable profiling for individual modules when using the -pg graph profiling option.
-nocleanup Disable generation of implicit exception handlers. Procedures without explicit handlers may have implicit handlers. For example, the compiler creates a handler for each automatic object that has a destructor. The compiler also creates handlers for constructors that initialize subobjects that have destructors. In such a constructor, the compiler creates a handler for each member with a destructor, and a handler for each base class with a destructor. The -nocleanup option suppresses generation of such implicit handlers, which results in a slightly smaller executable.

The -nocleanup option lets the compiler do additional optimizations because it is freed from concern with the abnormal transfer of control that occurs when exceptions are raised. Note that this can cause problems in your program if an exception does get raised or if setjmp() and exc_longjmp() are used. This option should not be used in programs that raise exceptions or call setjmp() and exc_longjmp() .

-nodemangle Do not pipe linker messages through the demangler. This causes linker messages to contain mangled names. By default, cxx pipes linker messages through the demangler so that demangled names are displayed.
-noinline
or -no_inline 		Do not compile any function calls as inline code.
-noinline_auto Compile only inline functions that are explicitly declared to be inline.
-nomember_alignment Direct the compiler to byte-align data structure members (with the exception of bit-field members). By default, data structure members are aligned on natural boundaries (the next boundary appropriate to the type of the member) rather than the next byte. For example, an int variable member is aligned on the next longword boundary; a short variable member is aligned on the next word boundary. Using any of the #pragma member_alignment , #pragma nomember_alignment , and #pragma pack directives within the source code overrides the setting established by this option.
-non_shared Do not produce a dynamic executable file. The loader uses regular archives to resolve undefined symbols and object files ( .o suffix) from archives included in the executable produced.
-noobject Do not produce an object file.
-nopragma_template Disable all #pragma define_template directives in the source code. This option has no affect on the -define_templates command line option.
-nopt Direct the compiler not to automatically instantiate templates.
-o file Name the final output file, rather than use the default a.out . The given name is used regardless of the type of file (executable, object, assembly, or other type).
-O[ n] Set the level of optimization. Note that different optimizations are performed at each level, depending on whether you invoke the compiler with or without the -migrate option. (The -migrate option is provided for compatibility with older versions of DEC C.) The following table lists the types of optimizations that are performed if the -migrate option is not explicitly specified:
   
Option Optimization
-O0 No optimization.
-O1 Optimization with space as the primary criterion. This is the default if no optimization option is specified.
-O2 Optimization with time as the primary criterion.
-O3 For DEC C++, the same as -O2 . If you use the cxx command to compile C source files, -O3 enables inline expansion of C global functions.
-O4 , -O5 Additional global optimizations that improve speed at the cost of extra code size. The -O4 and -O5 options have the same effect.
  In addition to affecting the generated code, the -O level is passed on to ld and om (if om is specified).
  The general guidelines for optimization are as follows:
  • If the speed of the generated code is more important that code size, specify -O (same as -O2 ). In some cases, -O4 may produce faster code. Using inline all at -O or -O4 may produce more inline calls (particularly calls to constructors) and improve speed, but this option may increase the code size for some programs beyond an acceptable limit. If you are potentially interested in this option, build your program both with and without the option and compare the code size.
  • If the size of the generated code is more important than speed, you may need to experiment somewhat to determine the best optimization option. Although -O1 (the default if an optimization level is not specified) is intended to optimize for code size, in some cases code that is compiled with -O (or -O2 ) to optimize for speed may actually be smaller. Also try -O -unroll 1 to see if a smaller size is generated. Using -unroll 1 disables a loop unrolling optimization and generally reduces the code size when you use -O . You might also try compiling with the -noinline option, both with and without -O , to see if a reduction in code size occurs.
  Other switches that can possibly affect run-time size and speed are as follows:
Compiler -fp_reorder , -misalign , -nocleanup , -noinline , -tune , -assume trusted_short_alignment , -unroll
Linker -non_shared , -om
  When you use -g for best debugging, optimizations are suppressed. Thus, when comparing the effects of different optimization levels, you should not specify -g or -g2 . For such comparisons, you specify -g0 , which suppresses debugging information.
  As noted previously, different optimizations are performed at each level, depending on whether you invoke the compiler with or without the -migrate flag. The following table lists the types of optimizations that are performed if -migrate is specified:
   
Option Optimization
-O0 -migrate No optimization.
-O1 -migrate Limited local optimization. This is the default if -migrate is specified.
-O2 -migrate Optimization with space as the primary criterion.
-O3 -migrate Optimization with time as the primary criterion.
-O4 -migrate Optimization with time as the primary criterion. For DEC C++, -O3 and -O4 generally produce similar results, although -O4 allows the inline expansion of functions for some additional cases.

This is the default if you specify -O without a level number.

-O5 -migrate Additional global optimizations that improve speed at the cost of extra code size.
  The correspondence between optimization levels when -migrate is not specified and when it is specified is as follows:
   
--O[n] without the --migrate option Equivalent with the --migrate option
-O0 -O0 -migrate
-O1 -O2 -migrate
-O2 -O4 -migrate
-O3 -O4 -migrate
-O4 -O5 -migrate
-O5 -O5 -migrate
-O[ n] not specified at all -O2 -migrate
-O -O4 -migrate
-om Perform code optimization after linking, including nop (No Operation) removal, .lita removal, and reallocation of common symbols. This option also positions the global pointer register so the maximum addresses fall in the global pointer-accessible window. The -om option is supported only for programs compiled with the -non_shared option. The following options can be passed directly to -om by using the -WL compiler flag:
  -WL,-om_compress_lita --- remove unused .lita entries after optimization, and then compress the .lita section.
  -WL,-om_dead_code --- remove dead code (unreachable instructions) generated after applying optimizations. The .lita section is not compressed by this option.
  -WL,-om_ireorg_feedback, file --- use the pixie-produced information in file.Counts and file.Addrs to reorganize the instructions to reduce cache thrashing.
  -WL,-om_no_inst_sched --- turn off instruction scheduling.
  -WL,-om_no_align_labels --- turn off alignment of labels. Normally, the -om option quadword aligns the targets of all branches to improve loop performance.
  -WL,-om_Gcommon, num --- set size threshold of "common" symbols. Every "common" symbol whose size is less than or equal to num will be allocated close to each other. This flag can be used to improve the probability that the symbol can be accessed directory from the global pointer register. Normally, the -om option causes the compiler to try to collect all "common" symbols together.
-p Perform profiling by periodically sampling the value of the program counter. This option affects only linking. When linking is done, this option replaces the standard run-time startup routine with the profiling run-time startup routine mcrt0.o and searches the level 1 profiling library libprof1.a . When profiling is completed, the startup routine calls the monstartup routine and produces a mon.out file that contains execution-profiling data for use with the postprocessor prof . Same as -p1 .
-p0 Do not perform profiling. This is the default.
-p1 Same as -p .
-pg Perform call graph profiling using the gprof tool.

For more information on profiling C++ code, see the DIGITAL UNIX Programmer's Guide and the appropriate reference pages.

-pt Direct the compiler to automatically instantiate templates.
-pthread Direct the linker to use the threadsafe version of any library specified with the -l flag when linking programs. This option also tells the linker to include the POSIX 1003.1c-conformant DECthreads interfaces in libpthread when linking the program.
-ptr pathname Specify a repository, with ./cxx_repository as the default. If you specify several repositories, only the first is writable, and the default repository is ignored unless explicitly named.

Specifying this option at link time enables DEC C++ to recognize and use the various template instantiations within the specified repository. If you use this option, make sure that the repository current at compile time is the same one accessed by the linker at link time.

-ptsuf" list" Specify a list of file-name extensions that are valid for template definition files.
-ptv Turn on verbose or verify mode to display each phase of template instantiation as it occurs. This option is useful as a automatic instantiation learning aid.
-r Retain relocation entries in the output file. Relocation entries must be saved if the output file is to become an input file in a subsequent linker run. This option prevents final definitions from being given to common symbols; it also suppresses the diagnosis of undefined symbols.
-readonly_strings Make all string literals read only. This is the default.
-rpath string Set the rpath to the specified string. This option is meaningful for shared linkage only.
-S Compile the specified source programs and produce symbolic assembly language in corresponding files with a .s extension. Do not assemble these files. If the file name argument already has a .s extension, do nothing at all.
-shared Produce a shared object. This includes creating all of the tables for run-time linking, and resolving references to other specified shared objects. The object created may be used by the linker to make dynamic executables.
-show keyword [, keyword,...] Specify one or more items to be included in the listing file. When specifying multiple keywords, separate them by commas (with no intervening blanks). To use any of the -show keywords, you must also specify the -source_listing option. The -show keywords are as follows:
  all Enable all options.
  [no]expansion Determine whether or not to place final macro expansions in the program listing. When you specify the expansion keyword, the number printed in the margin indicates the maximum depth of macro substitutions that occur on each line.
  [no]header Determine whether or not to produce header lines at the top of each page of listing.
  [no]include Determine whether or not to place contents of #include files in the program listing.
  none Disable all options.
  [no]statistics Determine whether or not to place compiler performance statistics in the program listing.
  [no]source Determine whether or not to place source program statements in the program listing.
  The default is to show page headers and source; that is:
-show header,source .
-signed Cause all char declarations to have the same machine representation and value set as signed char declarations. This is the default.
-source_listing Produce a source code listing file of the same name as the source file, but with the extension .lis .
-strong_volatile Allow byte and word access of data at byte granularity by using a load-locked instruction sequence for byte and word stores. This means that, for assignments to objects that are less than or equal to 16 bits in size and have been declared as volatile, assignments to adjacent volative small objects by different threads in a multithreaded program will not cause one of the objects to receive an incorrect value.

The generated code includes a load-locked instruction for the enclosing longword or quadword, an insertion of the new value of the object, and a store-conditional instruction for the enclosing longword or quadword.

-t Select a name to use for a particular pass, startup routine, or standard library, from the set of -t[fablyzrnL] , -h path , and -B string flags. These arguments are processed from left to right so their order is significant. When the compiler encounters the -B flag, the selection of names takes place using the last -h and -t flags. Therefore, the -B flag is always required when using -h or -t . Sets of these flags can be used to select any combination of names.

The -p[01] flags must precede all -B flags because they can affect the location of run times and what run times are used.

Use the -t[fablyzrnL] suboptions to select the names. The names selected are those designated by the characters following the -t flag as follows:

  • f gemc_cxx
  • a as0
  • b as1
  • l ld
  • y ftoc
  • z cord
  • r [m]crt0.o
  • n libprof1.a
  • L om
-taso Tell the linker that the executable file should be loaded in the lower 31-bit addressable virtual address range. You can also use the -T and -D options to the ld command to ensure that the adresses of text and data segments are loaded into low memory.

Besides setting default addresses for text and data segments, the -taso option also causes shared libraries linked outside the 31-bit address space to be appropriately relocated by the loader. If you specify -taso and also specify text and data segment addresses with -T and -D , those addresses override the -taso default addresses. The -taso option is useful for porting 32-bit programs to DIGITAL UNIX systems.

-threads Direct the linker to use the thread-safe version of any library specified with the -l flag when linking programs. This option also tells the linker to include both the DECthread interfaces that are conformant with POSIX 1003.4a Draft 4. The flag is supported only for compatability with earlier releases of the DIGITAL UNIX operating system. New designs should use the -pthread option.
-tune option Select processor-specific instruction tuning for implementations of the operating system architecture. Using -tune causes the generated code to run correctly on all implementations of the architecture. Tuning for a specific implementation may improve run-time performance; however, code tuned for a specific target may run slower on another target.

The following options are supported:
generic Selects instruction tuning that is appropriate for all implementations of the Alpha architecture. This is the default.
host Selects instruction tuning that is appropriate for the machine on which the code is being compiled.
ev4 Selects instruction tuning for the 21064, 21064A, 21066, and 21068 implementations of the architecture.
ev5 Selects instruction tuning for the 21164 implementation of the architecture.

-unroll n Control loop unrolling done by the optimizer. The integer n signifies the number of times to unroll loop bodies. Specifying 0 for n tells the optimizer to use its own default unroll amount. This is the default.
-unsigned Cause all char declarations to have the same machine representation and value set as unsigned char declarations. The -unsigned option overrides -signed if both are specified on the command line.
-use_ld_input Direct the DEC C++ compiler to record in the writable repository the names of requested automatic template instantiation object files in a linker options file.

The DEC C++ compiler then adds the linker options file to the ld command line using the ld -input <file> option.

The default behavior is to add the instantiation file names directly to the ld command line.

You can use the -use_ld_input option to reduce long ld command lines that cause ld to fail because of Arg list too long errors.

This option is supported only on DIGITAL UNIX Version 3.2C and later systems.

-v Print the names of compiler phases as they execute, along with their arguments and input and output files. This option also prints resource usage in the following format: user time, system time, total elapsed time, percentage use of CPU cycles.
-V Enable printing of the version of the compiler and its phases.
-varargs Print warnings for all lines that may require macros contained in the header file varargs.h .
-verbose Include identifiers with messages the compiler issues in response to #pragma message directives.
-volatile Compile all variables as volatile .
-vptr_size Make 64 bits the default size of virtual function and virtual base pointers in a C++ class object (64 bits is the normal default). This option also enables #pragma pointer_size and passes -taso to the linker.
-vptr_size_short Make 32 bits the default size of virtual function and virtual base pointers in a C++ class object. This option also enables #pragma pointer_size and passes -taso to the linker.
-w Suppress warning and informational compiler messages, but not back-end messages. Same as -w2 .
-w0 Display all levels of compiler messages.
-w1 Suppress informational compiler messages. This is the default.
-w2 Same as -w .
-W c[ c...],
arg1[, arg2...] 		Pass the arguments arg2...] to the compiler stages c[ c...]. Use this option to pass arguments through to a particular stage, which otherwise would be consumed by an earlier stage. The c argument selects the compiler stage in the same way as it does in the -H option. Valid characters for c are: a, b, f, l, L, n, r, t, y , and z .
-weak_volatile Do not generate load-locked instructions for a sequence of byte or word stores for assignments to objects that are less than or equal to 16 bits in size and have been declared as volatile. This allows byte or word access to memory-like I/O devices for which larger access will not cause read or write side effects. Because the sequence does not access byte or word data independently directly in memory (that is, ensure byte granularity), adjacent volatile data can be corrupted when such byte or word accesses are performed in a multithreaded environment (for example, two volative short s stored in a longword and accessed asynchronously).
-writable_strings Make string literals writeable.
-x cxx Cause all subsequent file names to be compiled as C++ source files, regardless of their suffixes (except .a and .o). This option applies to all following file names up to the next -x option on the command line.
-x none Cause all subsequent file names to be treated according to their file name suffixes. This option reverses the effect of the -x cxx option. It applies to all following file names until the next -x option on the command line.

In the following example, files one.cxx and two.c will be compiled as C++ source files, and file three.c will be compiled as a C source file: 

cxx one.cxx -x cxx two.c -x none three.c
-xref
-xref_stdout 		Direct the DEC C++ compiler to generate a data file that the DEC FUSE Database Manager uses to create a cross-reference database file. This database file is used by the DEC FUSE C++ Class Browser, Call Graph Browser, and Cross-Referencer.

Specifying the -xref_stdout option directs the compiler to output the data file to standard output.

-xtaso Set the default pointer size of the compilation unit to 64 bits (for all pointers except virtual function and virtual base pointers; 64 bits is the normal default). This option enables #pragma pointer_size and passes -taso to the linker.
-xtaso_short Set the default pointer size of the compilation unit to 32 bits (for all pointers except virtual function and virtual base pointers). This option also enables #pragma pointer_size and passes -taso to the linker. The this pointer is unaffected by this option, it remains the system default pointer size, which is 64 bits.
-Zp n Align structure members on alignment specified by the integer n, where n can be 1, 2, or 4. This option specifies packing so that each structure member after the first is stored on n-byte boundaries as specified by the flag you choose. When you specify the -Zp option without an n value, structure members are packed on 1-byte boundaries.

Preprocessor Options

Next Contents Index