Go to main content
Oracle® Developer Studio 12.6: C++ User's Guide

Exit Print View

Updated: July 2017
 
 

14.2 Option Reference

The following section alphabetically lists all the C++ compiler options and indicates any platform restrictions.

A.2.1 -#

Turns on verbose mode, showing how command options expand. Shows each component as it is invoked. For more information, see –v.

A.2.2 -###

Shows each component as it would be invoked, but does not actually execute it. Also shows how command options would expand. For more information, see –dryrun.

A.2.3 –abiopt=[mangle5|mangle6]

This option is allowed only in –compat=5 (or –std=sun03) mode. It is an error in all other modes.

The mangle6 sub-option is allowed on all platforms. It selects correct name mangling that might not be compatible with prior compiler releases on SPARC and on x86 with the –m32 option.

The mangle5 sub-option is allowed only on SPARC with –m32 or –m64 and x86 only with –m32. It selects name mangling compatible with prior compiler releases. It is the default on SPARC and on x86 with the –m32 option.

The name mangling performed in prior releases of Oracle Developer Studio in –compat=5 mode had errors. Fixing the errors would have created binary incompatibilities. The errors were found and corrected prior to Oracle Developer Studio releases on x86 with –m64 and on Linux, but remained on the other platforms.

A.2.4 –Bbinding

Specifies whether a library binding for linking is symbolic, dynamic (shared), or static (nonshared).

You can use the –B option several times on a command line. This option is passed to the linker, ld.

A.2.4.1 Values

binding must be one of the values listed in the following table:

Value
Meaning
dynamic
Directs the link editor to look for liblib.so (shared) files, and if they are not found, to look for liblib.a (static, nonshared) files. Use this option if you want shared library bindings for linking.
static
Directs the link editor to look only for liblib.a (static, nonshared) files. Use this option if you want nonshared library bindings for linking.
symbolic
Forces symbols to be resolved within a shared library if possible, even when a symbol is already defined elsewhere.
See the ld(1) man page.

(No space is allowed between –B and the binding value.)

Defaults

If -B is not specified, –Bdynamic is assumed.

Interactions

To link the C++ default libraries statically, use the –staticlib option.

The -Bstatic and -Bdynamic options affect the linking of the libraries that are provided by default. To ensure that the default libraries are linked dynamically, the last use of –B should be –Bdynamic.

Examples

The following compiler command links libfoo.a even if libfoo.so exists; all other libraries are linked dynamically:

example% CC a.o –Bstatic –lfoo –Bdynamic
Warnings

Never use –Bsymbolic with programs containing C++ code, use linker map files instead.

With –Bsymbolic, references in different modules can bind to different copies of what is supposed to be one global object.

The exception mechanism relies on comparing addresses. If you have two copies of something, their addresses won’t compare equal, and the exception mechanism can fail because the exception mechanism relies on comparing what are supposed to be unique addresses.

If you compile and link in separate steps and are using the -Bbinding option, you must include the option in the link step.

See Also

–nolib, –staticlib, ld(1) man page, Statically Linking Standard Libraries, Oracle Solaris 11.3 Linkers and Libraries Guide

A.2.5 –c

Compile only; produce object .o files, but suppress linking.

This option directs the CC driver to suppress linking with ld and produce a .o file for each source file. If you specify only one source file on the command line, then you can explicitly name the object file with the -o option.

A.2.5.1 Examples

If you enter CC -c x.cc, the x.o object file is generated.

If you enter CC -c x.cc -o y.o, the y.o object file is generated.

Warnings

When the compiler produces object code for an input file (.c, .i), the compiler always produces a .o file in the working directory. If you suppress the linking step, the .o files are not removed.

See Also

–o filename, –xe

A.2.6 –cg{89|92}

(SPARC) Obsolete, do not use this option. Current Oracle Solaris operating system software no longer supports SPARC V7 architecture. Compiling with this option generates code that runs slower on current SPARC platforms. See the options -xarch, -xchip, and -xcache.

A.2.7 –compat={5|g}

Sets the compatibility mode of the compiler. The new -std option is preferred and provides more choices. See –std=v.

Compatibility Mode (-compat=4), which accepted the semantics and language defined by the 4.2 compiler in previous releases, was removed in Oracle Solaris Studio 12.3.

A.2.7.1 Defaults

The –compat option has a default value that depends on the platform. It is intended to match C++ libraries bundled with the operating system. See Platform-specific Option Defaults.

A.2.8 +d

Does not expand C++ inline functions.

Under the C++ language rules, a C++ inline function is a function for which one of the following statements is true:

  • The function is defined using the inline keyword,

  • The function is defined, not just declared, inside a class definition

  • The function is a compiler-generated class member function

Under the C++ language rules, the compiler can choose whether actually to inline a call to an inline function. The C++ compiler inlines calls to an inline function unless one of the following is true:

  • The function is too complex

  • The +d option is selected

  • The —g option is selected without a —xOn optimization level specified

A.2.8.1 Examples

By default, the compiler may inline the functions f() and memf2() in the following code example. In addition, the class has a default compiler-generated constructor and destructor that the compiler may inline. When you use +d, the compiler will not inline f()and C::mf2(), the constructor, and the destructor.

inline int f() {return 0;} // may be inlined
class C {
  int mf1(); // not inlined unless inline definition comes later
  int mf2() {return 0;} // may be inlined
};
Interactions

This option is automatically turned on when you specify –g, the debugging option,, unless an optimization level is also specified (—O or —xO).

The –g0 debugging option does not turn on +d.

The +d option has no effect on the automatic inlining that is performed when you use -xO4 or -xO5.

See Also

–g0, –g

A.2.9 –Dname[=def]

Define a macro with optional arguments as if the macro is defined by a #define preprocessing directive.5 mode

If no =expansion is specified, the compiler assumes 1.

See the CC(1) man page for a list of compiler predefined macros.

A.2.10 –d{y|n}

Allows or disallows dynamic libraries for the entire executable.

This option is passed to ld.

This option can appear only once on the command line.

A.2.10.1 Values

Value
Meaning
-dy
Specifies dynamic linking in the link editor.
–dn
Specifies static linking in the link editor.
Defaults

If no -d option is specified, –dy is assumed.

Warnings

This option causes fatal errors if you use it in combination with dynamic libraries. Most system libraries are only available as dynamic libraries.

See Also

ld(1) man page, Oracle Solaris 11.3 Linkers and Libraries Guide

A.2.11 –dalign

(SPARC) Obsolete — Do not use. Use -xmemalign=8s. See -xmemalign=ab for more information.

This option is silently ignored on x86 platforms.

A.2.12 –dryrun

Shows the subcommands built by driver, but does not compile.

This option directs the CC driver to show, but not execute, the subcommands constructed by the compilation driver.

A.2.13 –E

Runs the preprocessor on source files; does not compile.

Directs the CC driver to run only the preprocessor on C++ source files, and to send the result to stdout (standard output). No compilation is done; no .o files are generated.

This option causes preprocessor-type line number information to be included in the output.

To compile the output of the -E option when the source code involves templates, you might need to use the -template=no%extdef option with the -E option. If application code uses the definitions separate template source code model, the output of the -E option might still not compile. Refer to the chapters on templates for more information.

When compiling in any of –compat=g, –std=c++03, –std=c++11, or –std=c++14 modes, the compiler silently includes a private header builtins.h. If you then compile the preprocessed output, the header will be included again, resulting in many complaints about multiple declarations. To compile the preprocessed file, you must first delete the lines associated with the builtins.h header.

A.2.13.1 Examples

This option is useful for determining the changes made by the preprocessor. For example, the following program, foo.cc, generates the output shown in Examples

Example 5  Preprocessor Example Program foo.cc
#if __cplusplus < 199711L
int power(int, int);
#else
template <> int power(int, int);
#endif

int main () {
  int x;
  x=power(2, 10);
}
.
Example 6  Preprocessor Output of foo.cc Using -E Option
example% CC -E foo.cc
#4 "foo.cc"
template < > int power (int, int);


int main () {
int x;
x = power (2, 10);
}
Warnings

The output of this option might not be usable as input to a C++ compilation if the code contains templates under the definitions-separate model.

See Also

–P

A.2.14 –erroff[=t]

This command supp resses C++ compiler warning messages and has no effect on error messages. This option applies to all warning messages regardless of whether they have been designated by -errwarn to cause a non-zero exit status.

A.2.14.1 Values

t is a comma-separated list that consists of one or more of the following: tag, no%tag, %all, %none. Order is important; for example, %all,no%tag suppresses all warning messages except tag. The following table lists the -erroff values.

Table 31  -erroff Values
Value
Meaning
tag
Suppresses the warning message specified by this tag. You can display the tag for a message by using the -errtags=yes option.
no%tag
Enables the warning message specified by this tag.
%all
Suppresses all warning messages.
%none
Enables all warning messages (default).
Defaults

The default is -erroff=%none. Specifying -erroff is equivalent to specifying -erroff=%all.

Examples

For example, -erroff=tag suppresses the warning message specified by this tag. On the other hand, -erroff=%all,no%tag suppresses all warning messages except the messages identified by tag.

You can display the tag for a warning message by using the -errtags=yes option.

Warnings

Only warning messages from the C++ compiler that display a tag when the -errtags option is used can be suppressed with the -erroff option.

See Also

-errtags, -errwarn

A.2.15 –errtags[=a]

Displays the mess age tag for each warning message of the C++ compiler that can be suppressed with the -erroff option or made a fatal warning with the -errwarn option.

In previous C++ compilers, the -errtags option caused a tag to be printed as part of the message for both warnings and errors. The C++ compiler behavior is now the same as the C compiler, emitting tags only for warning messages.

A.2.15.1 Values and Defaults

a can be either yes or no. The default is -errtags=no. Specifying -errtags is equivalent to specifying -errtags=yes.

Warnings

Messages from the C++ compiler driver and other components of the compilation system do not have error tags. Therefore they cannot be suppressed with -erroff or made fatal with -errwarn.

See Also

-erroff, -errwarn

A.2.16 –errwarn[=t]

Use -errwarn to cause the C++ compiler to exit with a failure status for the given warning messages.

A.2.16.1 Values

t is a comma-separated list that consists of one or more of the following: tag, no%tag, %all, %none. Order is important; for example %all,no%tag causes cc to exit with a fatal status if any warning except tag is issued.

The following table details the -errwarn values.

Table 32  -errwarn Values
Value
Meaning
tag
Cause CC to exit with a fatal status if the message specified by this tag is issued as a warning message. Has no effect if tag is not issued.
no%tag
Prevent CC from exiting with a fatal status if the message specified by tag is issued only as a warning message. Has no effect if the message specified by tag is not issued. Use this option to revert a warning message that was previously specified by this option with tag or %all from causing cc to exit with a fatal status when issued as a warning message.
%all
Cause CC to exit with a fatal status if any warning messages are issued. %all can be followed by no%tag to exempt specific warning messages from this behavior.
%none
Prevents any warning message from causing CC to exit with a fatal status should any warning message be issued.
Defaults

The default is -errwarn=%none. Specifying -errwarn alone is equivalent to -errwarn=%all.

Warnings

Only warning messages from the C++ compiler that display a tag when the -errtags option is used can be specified with the -errwarn option to cause the compiler to exit with a failure status.

The warning messages generated by the C++ compiler change from release to release as the compiler error checking improves and features are added. Code that compiles using -errwarn=%all without error may not compile without error in the next release of the compiler.

See Also

-erroff, -errtags, -xwe

A.2.17 –fast

This option is a macro that can be effectively used as a starting point for tuning an executable for maximum runtime performance. -fast is a macro that can change from one release of the compiler to the next and expands to options that are target platform specific. Use the -dryrun or -xdryrun option to examine the expansion of -fast, and incorporate the appropriate options of -fast into the ongoing process of tuning the executable.

This option is a macro that selects a combination of compilation options for optimum execution speed on the machine upon which the code is compiled.

A.2.17.1 Expansions

This option provides near maximum performance for many applications by expanding to the following compilation options.

Table 33   -fast Expansion
Option
SPARC
x86
–fma=fused
X
X
–fns
X
X
–fsimple=2
X
X
–nofstore
-
X
-xbuiltin=%all
X
X
–xlibmil
X
X
–xlibmopt
X
X
–xmemalign
X
-
–xO5
X
X
—xregs=frameptr
-
X
–xtarget=native
X
X
Interactions

See the description for each option to determine possible interactions.

The code generation option, the optimization level, the optimization of built-in functions, and the use of inline template files can be overridden by subsequent options (see examples). The optimization level that you specify overrides a previously set optimization level.

The –fast option includes –fns –ftrap=%none; that is, this option turns off all trapping.

On x86 the —fast option includes —xregs=frameptr. See the discussion of this option for details, especially when compiling mixed C, Fortran, and C++ source codes.

Examples

The following compiler command results in an optimization level of –xO3.

example% CC –fast –xO3

The following compiler command results in an optimization level of –xO5.

example% CC -xO3 –fast
Warnings

If you compile and link in separate steps, the -fast option must appear in both the compile command and the link command.

Object binaries compiled with the -fast option are not portable. For example, using the following command on a SPARC T3 system generates a binary that will not execute on a SPARC T4 system.

example% CC -fast test.cc

Do not use this option for programs that depend on IEEE standard floating-point arithmetic. Different numerical results, premature program termination, or unexpected SIGFPE signals can occur.

The expansion of –fast includes –D_MATHERR_ERRNO_DONTCARE.

With -fast, the compiler is free to replace calls to floating-point functions with equivalent optimized code that does not set the errno variable. Further, -fast also defines the macro __MATHERR_ERRNO_DONTCARE, which allows the compiler to ignore ensuring the validity of errno and floating-point exceptions raised after a floating-point function call. As a result, user code that relies on the value of errno or an appropriate floating-point exception raised after a floating-point function call could produce inconsistent results.

One way around this problem is to avoid compiling such codes with -fast. However, if -fast optimization is required and the code depends on the value of errno being set properly or a floating-point exception being raised after floating-point library calls, you should compile with the following options after -fast on the command line to inhibit the compiler from optimizing out such library calls:

-xbuiltin=%none -U__MATHERR_ERRNO_DONTCARE -xlibmopt=%none -xnolibmil

To display the expansion of —fast on any platform, run the command CC —dryrun —fast as shown in the following example.

>CC -dryrun -fast  |& grep ###
###     command line files and options (expanded):

### -dryrun -xO5 -xchip=T4 -xcache=16/32/4/8:128/32/8/8:4096/64/16/64
-xarch=sparc4 -xdepend=yes -xmemalign=8s -fma=fused -fsimple=2 -fns=yes
-ftrap=%none -xlibmil -xlibmopt -xbuiltin=%all -D__MATHERR_ERRNO_DONTCARE
See Also

-fns, -fsimple, -ftrap=%none, -xlibmil, -nofstore, -xO5, -xlibmopt, -xtarget=native

A.2.18 –features=a[,a...]

Enables/disables various C++ language features named in a comma-separated list.

A.2.18.1 Values

Keyword a can have the values shown in the following table. The no% prefix disables the associated option.

Table 34  -features Values
Value
Meaning
[no%]altspell
Recognize alternative token spellings (for example, “and” for “&&”). The default is altspell.
[no%]anachronisms
Allow anachronistic constructs. When disabled (that is, -features=no%anachronisms), no anachronistic constructs are allowed. The default is anachronisms.
[no%]bool
Allow the bool type and literals. When enabled, the macro _BOOL=1. When not enabled, the macro is not defined. The default is bool.
[no%]conststrings
Put literal strings in read-only memory. The default is conststrings.
cplusplus_redef
Allows the normally predefined macro __cplusplus to be redefined by a -D option on the command line. Attempting to redefine __cplusplus with a #define directive in source code is not allowed. Example:
CC —features=cplusplus_redef —D__cplusplus=1...
Old versions of g++ predefined the __cplusplus macro to 1, and some source code might depend on this non-standard value.
Do not use this option unless you need to redefine __cplusplus to 1 to compile code intended for g++.
[no%]except
Allow C++ exceptions. When C++ exceptions are disabled (that is, -features=no%except), a throw-specification on a function is accepted but ignored; the compiler does not generate exception code. Note that the keywords try, throw, and catch are always reserved. See Disabling Exceptions and Mixing C and C++ Code. The default is except.
explicit
Recognize the keyword explicit. The option no%explicit is not allowed.
[no%]export
Recognize the keyword export. The default is export.
[no%]extensions
Allow nonstandard code that is commonly accepted by other C++ compilers. The default is no%extensions.
[no%]iddollar
Allow a $ symbol as a noninitial identifier character. The default is no%iddollar.
[no%]localfor
Use standard-conforming local-scope rules for the for statement. The default is localfor.
[no%]mergestrings
(SPARC) Causes the compiler to put string literals and other suitable const or read-only data into a special section of the binary where the linker removes duplicate strings.
The default is –features=no%mergestrings, and duplicate strings are not removed.
–features=mergestrings is only effective when –features=conststrings is also in effect.
[no%]mutable
Recognize the keyword mutable. The default is mutable.
namespace
Recognize the keyword namespace. The option no%namespace is not allowed.
[no%]nestedacess
Allow nested classes to access private members of the enclosing class. Default: -features=nestedaccess
[no%]rtti
Issue runtime type identification (RTTI) data in the compiled program. The default is –features=rtti. Specifying –features=no%rtti disables generation of RTTI data. RTTI data can be large, so if you don't need RTTI the program uses less data space. Some C++ language features depend on RTTI and will not work if no%rtti is in effect. The compiler issues error messages if you use a feature that is disabled by no%rtti.
[no%]rvalueref
Allow binding a non-const reference to an rvalue or temporary. Default: -features=no%rvalueref
The C++ compiler, by default, enforces the rule that a non-const reference cannot be bound to a temporary or rvalue. To override this rule, use the option -features=rvalueref.
[no%]split_init
Put initializers for nonlocal static objects into individual functions. When you use -features=no%split_init, the compiler puts all the initializers in one function. Using -features=no%split_init minimizes code size at the possible expense of compile time. The default is split_init.
[no%]transitions
Allow ARM language constructs that are problematic in standard C++ and that may cause the program to behave differently than expected or that may be rejected by future compilers. When you use -features=no%transitions, the compiler treats these as errors. When you use -features=transitions, the compiler issues warnings about these constructs instead of error messages.
The following constructs are considered to be transition errors: redefining a template after it was used, omitting the typename directive when it is needed in a template definition, and implicitly declaring type int. The set of transition errors may change in a future release. The default is transitions.
[no%]strictdestrorder
Follow the requirements specified by the C++ standard regarding the order of the destruction of objects with static storage duration. The default is strictdestrorder.
[no%]tmplrefstatic
Allow function templates to refer to dependent static functions or static function templates. The default is -features=tmplrefstatic and no%tmplrefstatic has no effect.
[no%]tmplife
Clean up the temporary objects that are created by an expression at the end of the full expression, as defined in the ANSI/ISO C++ Standard. (When -features=no%tmplife is in effect, most temporary objects are cleaned up at the end of their block.) The default is tmplife.
[no%]zla
Allow an array to be declared with a size of 0, which is otherwise not allowed in C++. For example,
struct S {
    int a[0]; // allowed only with  -features=zla
};
int b[0];     // allowed only with  -features=zla
Interactions

This option accumulates instead of overrides.

Use of the following is not compatible with the standard libraries and headers:

  • no%bool

  • no%except

  • no%mutable

no%bool is not compatible with any gcc compatibility compiler modes: –compat=g or –std=[c++03|c++11|c++14].

Warnings

Do not use -features=%all or -features=%none. These sub-options are no longer allowed.

The behavior of a program might change when you use the -features=tmplife option. Testing whether the program works both with and without the -features=tmplife option is one way to test the program’s portability.

See Also

Table 19 and the C++ Migration Guide

A.2.19 –fexceptions|–fno-exceptions

–fexceptions is equivalent to –features=except.

–fno-exceptions is equivalent to –features=no%except (and thus to –noex).

A.2.20 –filt[=filter[,filter...]]

Controls the filtering that the compiler normally applies to linker and compiler error messages.

A.2.20.1 Values

filter must be one of the values listed in the following table. The %no prefix disables the associated sub-option.

Table 35  -filt Values
Value
Meaning
[no%]errors
Show the C++ explanations of the linker error messages. The suppression of the explanations is useful when the linker diagnostics are provided directly to another tool.
[no%]names
Demangle the C++ mangled linker names.
[no%]returns
Demangle the return types of functions. Suppression of this type of demangling helps you to identify function names more quickly, but note that in the case of covariant returns, some functions differ only in the return type.
[no%]stdlib
Simplify names from the standard library in both the linker and compiler error messages and provide an easier way to recognize the names of standard library template types.
%all
Equivalent to -filt=errors,names,returns,stdlib. This is the default behavior.
%none
Equivalent to -filt=no%errors,no%names,no%returns,no%stdlib.
Defaults

If you do not specify the -filt option or if you specify -filt without any values, then the compiler assumes -filt=%all.

Examples

The following examples show the effects of compiling this code with the -filt option.

// filt_demo.cc
class type {
public:
    virtual ~type(); // no definition provided
};

int main()
{
    type t;
}

When you compile the code without the -filt option, the compiler assumes -filt=errors,names,returns,stdlib and displays the standard output.

example% CC filt_demo.cc
Undefined             first referenced
 symbol                  in file
type::~type()         filt_demo.o
type::__vtbl          filt_demo.o
[Hint: try checking whether the first non-inlined, /
non-pure virtual function of class type is defined]

ld: fatal: Symbol referencing errors. No output written to a.out

The following command suppresses the demangling of the of the C++ mangled linker names and suppresses the C++ explanations of linker errors.

example% CC -filt=no%names,no%errors filt_demo.cc
Undefined                       first referenced
 symbol                             in file
__1cEtype2T6M_v_                    filt_demo.o
__1cEtypeG__vtbl_                   filt_demo.o
ld: fatal: Symbol referencing errors. No output written to a.out

Now consider this code:

#include <string>
#include <list>
int main()
{
    std::list<int> l;
    std::string s(l); // error here
}

Specifying -filt=no%stdlib results in the following output:

Error: Cannot use std::list<int, std::allocator<int>> to initialize
std::basic_string<char, std::char_traits<char>,
std::allocator<char>>.

Specifying -filt=stdlib results in the following output:

Error: Cannot use std::list<int> to initialize std::string .
Interactions

When you specify no%names, neither returns nor no%returns has an effect. That is, the following options are equivalent:

  • -filt=no%names

  • -filt=no%names,no%returns

  • -filt=no%names,returns

A.2.21 –flags

Same as– xhelp=flags.

A.2.22 –fma[={none|fused}]

Enables automatic generation of floating-point fused multiply-add instructions. –fma=none disables generation of these instructions. –fma=fused allows the compiler to attempt to find opportunities to improve the performance of the code by using floating-point fused multiply-add instructions.

The default is –fma=none.

The minimum requirement is –xarch=sparcfmaf on SPARC and -xarch=avx2 on x86 to generate fused multiply-add instructions. The compiler marks the binary program if fused multiply-add instructions are generated in order to prevent the program from executing on platforms that do not support fused multiply-add instructions. When the minimum architecture is not used, then -fma=fused has no effect.

Fused multiply-add instructions eliminate the intermediate rounding step between the multiply and add. Consequently, programs may produce different results when compiled with -fma=fused, although precision will tend to increase rather than decrease.

A.2.23 –fno-semantic-interposition, –fsemantic-interposition

–fno-semantic-interposition allows the compiler to attempt to interprocedurally optimize functions with global linker scoping.

–fsemantic-interposition prevents the interprocedural optimization of functions with global linker scoping. Interprocedural optimizations consist of inlining functions, cloning functions, and interprocedural propagation, etc. This option is particularly useful when building libraries where it is allowed to interpose on external global functions that are also used internally within the library. While this option is useful, for example, to rewrite memory allocation functions for debugging, it is expensive in terms of code quality.

In Oracle Developer Studio 12.6, –fno-semantic-interposition is the default.

A.2.23.1 See Also

-xinline[=func-spec[,func-spec...]], -xldscope={v}, -xipo[={0|1|2}]

A.2.24 –fnonstd

This is a macro that expands to —ftrap=common on x86, and —fns —ftrap=common on SPARC.

See –fns and –ftrap=common for more information.

A.2.25 –fns[={yes|no}]

  • (SPARC) Enables/disables the SPARC nonstandard floating-point mode.

    -fns=yes (or -fns) causes the nonstandard floating point mode to be enabled when a program begins execution.

    This option provides a way of toggling the use of nonstandard or standard floating-point mode following some other macro option that includes –fns, such as –fast.

    On some SPARC architectures, the nonstandard floating-point mode disables “gradual underflow,” causing tiny results to be flushed to zero rather than to produce subnormal numbers. It also causes subnormal operands to be silently replaced by zero.

    On those SPARC architectures that do not support gradual underflow and subnormal numbers in hardware, -fns=yes (or -fns) can significantly improve the performance of some programs.

  • (x86) Selects/deselects SSE flush-to-zero mode and, where available, denormals-are-zero mode.

    This option causes subnormal results to be flushed to zero. Where available, this option also causes subnormal operands to be treated as zero.

    This option has no effect on traditional x86 floating-point operations that do not utilize the SSE or SSE2 instruction set.

A.2.25.1 Values

The -fns option can have the values listed in the following table.

Table 36  -fns Values
Value
Meaning
yes
Selects nonstandard floating-point mode
no
Selects standard floating-point mode
Defaults

If –fns is not specified, the nonstandard floating point mode is not enabled automatically. Standard IEEE 754 floating-point computation takes place, that is, underflows are gradual.

If only –fns is specified, –fns=yes is assumed.

Examples

In the following example, -fast expands to several options, one of which is -fns=yes which selects nonstandard floating-point mode. The subsequent -fns=no option overrides the initial setting and selects floating-point mode.

example% CC foo.cc -fast -fns=no
Warnings

When nonstandard mode is enabled, floating-point arithmetic can produce results that do not conform to the requirements of the IEEE 754 standard.

If you compile one routine with the -fns option you should compile all routines of the program with the –fns option. Otherwise, you might get unexpected results.

This option is effective only when compiling the main program.

Use of the –fns=yes (or -fns) option might generate warning messages if your program encounters a floating-point error normally managed by the IEEE floating-point trap handlers.

See Also

Oracle Developer Studio 12.6: Numerical Computation Guide, ieee_sun(3M) man page

A.2.26 –fopenmp

Same as -xopenmp=parallel.

A.2.27 -fpermissive

Downgrades some diagnostics of non-conformant code from errors to warnings, and allows the compilation of non-conformant code.

A.2.28 –fprecision=p

(x86) Sets the non-default floating-point precision mode.

The –fprecision option sets the rounding precision mode bits in the floating-point control word (FPCW). These bits control the precision to which the results of basic arithmetic operations (add, subtract, multiply, divide, and square root) are rounded.

A.2.28.1 Values

p must be one of the values listed in the following table.

Table 37  -fprecision Values
Value
Meaning
single
Rounds to an IEEE single-precision value.
double
Rounds to an IEEE double-precision value.
extended
Rounds to the maximum precision available.

If p is single or double, this option causes the rounding precision mode to be set to single or double precision, respectively, when a program begins execution. If p is extended or the –fprecision option is not used, the rounding precision mode remains at the extended precision.

The single precision rounding mode causes results to be rounded to 24 significant bits, and double precision rounding mode causes results to be rounded to 53 significant bits. In the default extended precision mode, results are rounded to 64 significant bits. This mode controls only the precision to which results in registers are rounded, and it does not affect the range. All results in register are rounded using the full range of the extended double format. Results that are stored in memory are rounded to both the range and precision of the destination format, however.

The nominal precision of the float type is single. The nominal precision of the long double type is extended.

Defaults

When the –fprecision option is not specified, the rounding precision mode defaults to extended.

Warnings

This option is effective only on x86 systems and only if used when compiling the main program, but is ignored if compiling for 64–bit (-m64) or SSE2–enabled (-xarch=sse2) processors. It is also ignored on SPARC systems.

A.2.29 –fround=r

Sets the IEEE rounding mode in effect at startup.

This option sets the IEEE 754 rounding mode that can be used by the compiler in evaluating constant expressions. The rounding mode is established at runtime during the program initialization.

The meanings are the same as those for the ieee_flags subroutine, which can be used to change the mode at runtime.

A.2.29.1 Values

r must be one of the values listed in the following table.

Table 38  -fround Values
Value
Meaning
nearest
Rounds towards the nearest number and breaks ties to even numbers.
tozero
Rounds to zero.
negative
Rounds to negative infinity.
positive
Rounds to positive infinity.
Defaults

When the –fround option is not specified, the rounding mode defaults to -fround=nearest.

Warnings

If you compile one routine with –fround=r, you must compile all routines of the program with the same –fround=r option. Otherwise, you might get unexpected results.

This option is effective only if used when compiling the main program.

Note that compiling with —xvector or —xlibmopt require default rounding. Programs that link with libraries compiled with either —xvector or —xlibmopt or both must ensure that default rounding is in effect.

A.2.30 –fsimple[=n]

Selects floating-point optimization preferences.

This option enables the optimizer to make simplifying assumptions concerning floating-point arithmetic.

A.2.30.1 Values

If n is present, it must be 0, 1, or 2.

Table 39  -fsimple Values
Value
Meaning
0
Permit no simplifying assumptions. Preserve strict IEEE 754 conformance.
1
Allow conservative simplification. The resulting code does not strictly conform to IEEE 754.
With -fsimple=1, the optimizer can assume the following:
  • IEEE754 default rounding/trapping modes do not change after process initialization.

  • Computation producing no visible result other than potential floating-point exceptions can be deleted.

  • Computation with infinities or NaNs as operands needs to propagate NaNs to their results; that is, x*0 can be replaced by 0.

  • Computations do not depend on sign of zero.

    With -fsimple=1, the optimizer is not allowed to optimize completely without regard to roundoff or exceptions. In particular, a floating-point computation cannot be replaced by one that produces different results when rounding modes are held constant at runtime.

2
Includes all the functionality of –fsimple=1 and also permits aggressive floating-point optimization that can cause many programs to produce different numeric results due to changes in rounding. For example, permit the optimizer to replace all computations of x/y in a given loop with x*z, where x/y is guaranteed to be evaluated at least once in the loop z=1/y, and the values of y and z are known to have constant values during execution of the loop.
-fsimple=2 allows fp-transformations which may introduce fp exceptions.
Defaults

If –fsimple is not designated, the compiler uses -fsimple=0.

If -fsimple is designated but no value is given for n, the compiler uses -fsimple=1.

Interactions

-fast implies– fsimple=2.

Warnings

This option can break IEEE 754 conformance.

See Also

-fast

A.2.31 –fstore

(x86) Forces precision of floating–point expressions.

This option causes the compiler to convert the value of a floating-point expression or function to the type on the left side of an assignment rather than leave the value in a register when the following is true:

  • The expression or function is assigned to a variable.

  • The expression is cast to a shorter floating-point type.

To turn off this option, use the –nofstore option. Both —fstore and —nofstore are ignored with a warning on SPARC platforms.

A.2.31.1 Warnings

Due to roundoffs and truncation, the results can be different from those that are generated from the register values.

See Also

–nofstore

A.2.32 –ftrap=t[,t...]

Sets the IEEE trapping mode in effect at startup but does not install a SIGFPE handler. You can use ieee_handler(3M) or fex_set_handling(3M) to simultaneously enable traps and install a SIGFPE handler. If you specify more than one value, the list is processed sequentially from left to right.

A.2.32.1 Values

t can be one of the values listed in the following table.

Table 40  The -ftrap Values
Value
Meaning
[no%]division
Trap on division by zero.
[no%]inexact
Trap on inexact result.
[no%]invalid
Trap on invalid operation.
[no%]overflow
Trap on overflow.
[no%]underflow
Trap on underflow.
%all
Trap on all of the above.
%none
Trap on none of the above.
common
Trap on invalid, division by zero, and overflow.

Note that the [no%] form of the option is used only to modify the meaning of the %all and common values, and must be used with one of these values, as shown in the example. The [no%] form of the option by itself does not explicitly cause a particular trap to be disabled.

Defaults

If you do not specify –ftrap, the compiler assumes –ftrap=%none.

Examples

–ftrap=%all,no%inexact means to set all traps except inexact.

Warnings

If you compile one routine with –ftrap=t, you should compile all routines of the program with the same -ftrap=t option. Otherwise, you might get unexpected results.

Use the -ftrap=inexact trap with caution. Use of– ftrap=inexact results in the trap being issued whenever a floating-point value cannot be represented exactly. For example, the following statement generates this condition:

x = 1.0 / 3.0;

This option is effective only if used when compiling the main program. Be cautious when using this option. If you want to enable the IEEE traps, use –ftrap=common.

See Also

ieee_handler(3M) and fex_set_handling(3M) man pages.

A.2.33 –fvisibility

The –fvisibility=v option is equivalent to the –xldscope option as follows:

–fvisibility Options
Equivalent –xldscope Options
default
global
internal
hidden
protected
symbolic
hidden
hidden

A.2.34 –G

Build a dynamic shared library instead of an executable file.

All source files specified in the command line are compiled with -xcode=pic13 by default.

When building a shared library from files that involve templates and were compiled with the -instances=extern option, any template instances referenced by the .o files will be included from the template cache automatically.

If you are creating a shared object by specifying -G along with other compiler options that must be specified at both compile time and link time, make sure that those same options are also specified at both compile time and link time when you link with the resulting shared object.

When you create a shared object, all the object files compiled for 64–bit SPARC architectures must also be compiled with an explicit -xcode value as recommended in –xcode=a. For more information, see the -shared option.

A.2.34.1 Interactions

The following options are passed to the linker if –c (the compile-only option) is not specified:

  • –dy

  • –G

  • –R

Warnings

Do not use ld -G to build shared libraries; use CC -G . The CC driver automatically passes several options to ld that are needed for C++.

When you use the -G option, the compiler does not pass any default -l options to ld. If you want the shared library to have a dependency on another shared library, you must pass the necessary -l or -library option on the command line. For example, if you want the shared library to be dependent upon libCrun, you must pass -lCrun or -library=Crun on the command line.

See Also

-dy, -xcode=pic13, –ztext, ld(1) man page, Building Dynamic (Shared) Libraries.

A.2.35 –g

See -g[n].

A.2.36 –g[n]

Produces additional symbol table information for debugging with dbx(1) or the Debugger and for analysis with the Performance Analyzer analyzer(1).

Instructs both the compiler and the linker to prepare the file or program for debugging and for performance analysis.

The tasks include:

  • Producing detailed debug information in the symbol table of the object files and the executable

  • Producing helper functions that the debugger can call to implement some of its features

  • Disabling the inline generation of functions if no optimization level is specified; that is, using this option implies the +d option if no optimization level is also specified. -g with any -O or -xO level does not disable inlining.

  • Disabling certain levels of optimization

-g is implemented as a macro that expands to various other, more primitive, options. See -xdebuginfo for the details of the expansions.

-g

Produce standard debugging information.

-gnone

Do not produce any debugging information. This is the default.

-g1

Produce file and line number as well as simple parameter information that is considered crucial during post-mortem debugging.

-g2

Same as -g.

-g3

Produce additional debugging information, which currently consists only of macro definition information. This added information can result in an increase in the size of the debug information in the resulting .o and executable when compared to using only -g.

-g0

Instructs the compiler to prepare the file or program for debugging, but not to disable inlining. This option is the same as -g, except that +d is disabled and dbx cannot step into inlined functions.

If you specify -g0 and the optimization level is -xO3 or lower, the compiler provides best-effort symbolic information with almost full optimization. Tail-call optimization and back-end inlining are disabled.

A.2.36.1 Interactions

If you use this option with –xOlevel (or its equivalent options, such as -O), you will get limited debugging information. For more information, see -xOlevel.

If you use this option and the optimization level is -xO4 or higher, the compiler provides best-effort symbolic information with full optimization. If you use —g without an optimization level specified, inlining of function calls will be disabled. (Inlining is enabled when an optimization level is specified with —g.)

When you specify this option, the +d option is specified automatically unless you also specify –O or –xO.

To use the full capabilities of the Performance Analyzer, compile with the -g option. While some performance analysis features do not require -g, you must compile with -g to view annotated source, some function level information, and compiler commentary messages. See the analyzer(1) man page and the Performance Analyzer manual for more information.

The commentary messages that are generated with -g describe the optimizations and transformations that the compiler made while compiling your program. Use the er_src(1) command to display the messages, which are interleaved with the source code.

Warnings

If you compile and link your program in separate steps, then including the -g option in one step and excluding it from the other step will not affect the correctness of the program, but it will affect the ability to debug the program. Any module that is not compiled with -g (or -g0), but is linked with -g (or -g0) will not be prepared properly for debugging. Note that compiling the module that contains the function main with the -g option (or the -g0 option) is usually necessary for debugging.

See Also

+d, –xs, analyzer(1) man page, er_src(1) man page, ld(1) man page, Oracle Developer Studio 12.6: Debugging a Program with dbx, and Oracle Developer Studio 12.6: Performance Analyzer.

A.2.37 -gz[=cmp-type]

Equivalent of specifying-xcompress=debug -xcompress_format=cmp-type.

-gz with no sub-option is equivalent to -gz=zlib.

A.2.38 –H

Prints path names of included files.

On the standard error output (stderr), this option prints, one per line, the path name of each #include file contained in the current compilation.

A.2.39 –h[ ]name

Assigns the name name to the generated dynamic shared library.

This is a linker option passed to ld. In general, the name after -h should be exactly the same as the one after –o. A space between the –h and name is optional.

The compile-time loader assigns the specified name to the shared dynamic library you are creating. It records the name in the library file as the intrinsic name of the library. If there is no –hname option, then no intrinsic name is recorded in the library file.

Every executable file has a list of shared library files that are needed. When the runtime linker links the library into an executable file, the linker copies the intrinsic name from the library into that list of needed shared library files. If there is no intrinsic name of a shared library, then the linker copies the path of the shared library file instead.

When a shared library is built without the-h option, the runtime loader looks only for the file name of the library. You can replace the library with a different library with the same file name. If the shared library has an intrinsic name, the loader checks the intrinsic name when loading the file. If the intrinsic name does not match, the loader will not use the replacement file.

A.2.39.1 Examples

example% CC -G -o libx.so.1 -h libx.so.1 a.o b.o c.o

A.2.40 –help

This option is deprecated and will be removed in a future release. Use -xhelp=flags instead.

A.2.41 –Ipathname

Add pathname to the #include file search path.

This option adds pathname to the list of directories that are searched for #include files with relative file names (those that do not begin with a slash).

The compiler searches for quote-included files (of the form #include "foo.h") in this order:

  1. In the directory containing the source

  2. In the directories named with -I options, if any

  3. In the include directories for compiler-provided C++ header files, ANSI C header files, and special-purpose files

  4. In the /usr/include directory

The compiler searches for bracket-included files (of the form #include <foo.h>) in this order:

  1. In the directories named with -I options, if any

  2. In the include directories for compiler-provided C++ header files, ANSI C header files, and special-purpose files

  3. In the /usr/include directory


    Note -  If the spelling matches the name of a standard header file, also refer to Standard Header Implementation.

A.2.41.1 Interactions

The -I- option allows you to override the default search rules.

If you specify -library=no%Cstd, then the compiler does not include in its search path the compiler-provided header files that are associated with the C++ standard libraries. See Replacing the C++ Standard Library.

If –ptipath is not used, the compiler looks for template files in –Ipathname.

Use –Ipathname instead of –ptipath.

This option accumulates instead of overrides.

Warnings

Never specify the compiler installation area, /usr/include, /lib, or /usr/lib, as search directories.

See Also

-I-

A.2.42 –I–

Change the include-file search rules.

For include files of the form #include "foo.h", search the directories in the following order:

1. The directories named with -I options (both before and after -I-)

2. The directories for compiler-provided C++ header files, ANSI C header files, and special-purpose files

3. The /usr/include directory

For include files of the form #include <foo.h>, search the directories in the following order:

1. The directories named in the -I options that appear after -I-

2. The directories for compiler-provided C++ header files, ANSI C header files, and special-purpose files

3. The /usr/include directory


Note -  If the name of the include file matches the name of a standard header, also refer to Standard Header Implementation.

A.2.42.1 Examples

The following example shows the results of using -I- when compiling prog.cc.

prog.cc
#include "a.h"
#include <b.h>
#include "c.h"
c.h
#ifndef _C_H_1
#define _C_H_1
int c1;
#endif
inc/a.h
#ifndef _A_H
#define _A_H
#include "c.h"
int a;
#endif
inc/b.h
#ifndef _B_H
#define _B_H
#include <c.h>
int b;
#endif
inc/c.h
#ifndef _C_H_2
#define _C_H_2
int c2;
#endif

The following command shows the default behavior of searching the current directory (the directory of the including file) for include statements of the form #include "foo.h". When processing the #include "c.h" statement in inc/a.h, the compiler includes the c.h header file from the inc subdirectory. When processing the #include "c.h" statement in prog.cc, the compiler includes the c.h file from the directory containing prog.cc. Note that the -H option instructs the compiler to print the paths of the included files.

example% CC -c -Iinc -H prog.cc
inc/a.h
        inc/c.h
inc/b.h
        inc/c.h
c.h

The next command shows the effect of the -I- option. The compiler does not look in the including directory first when it processes statements of the form #include "foo.h". Instead, it searches the directories named by the -I options in the order that they appear in the command line. When processing the #include "c.h" statement in inc/a.h, the compiler includes the ./c.h header file instead of the inc/c.h header file.

example% CC -c -I. -I- -Iinc -H prog.cc
inc/a.h
        ./c.h
inc/b.h
        inc/c.h
./c.h
Interactions

When -I- appears in the command line, the compiler never searches the current directory unless the directory is listed explicitly in a -I directive. This effect applies even for include statements of the form #include "foo.h".

Warnings

Only the first -I- in a command line causes the described behavior.

Never specify the compiler installation area, /usr/include, /lib, or /usr/lib, as search directories.

A.2.43 –i

Tells the linker, ld, to ignore any LD_LIBRARY_PATH and LD_LIBRARY_PATH_64 settings.

A.2.44 –include filename

This option causes the compiler to treat filename as if it appears in the first line of a primary source file as a #include preprocessor directive. Consider the source file t.c:

int main()
{
   ...
}

If you compile t.c with the command cc -include t.h t.c, the compilation proceeds as if the source file contains the following:

#include "t.h"
int main()
{
   ...
}

The first directory the compiler searches for filename is the current working directory and not the directory containing the main source file, as is the case when a file is explicitly included. For example, the following directory structure contains two header files with the same name, but at different locations:

foo/
   t.c
   t.h
   bar/
     u.c
     t.h

If your working directory is foo/bar and you compile with the command cc ../t.c -include t.h, the compiler includes t.h from foo/bar, not foo/ as would be the case with a #include directive from within the source file t.c.

If the compiler cannot find the file specified with –include in the current working directory, it searches the normal directory paths for the file. If you specify multiple –include options, the files are included in the order they appear on the command line.

A.2.45 –inline

This option is deprecated and will be removed in a future release. Use -xinline instead.

A.2.46 –instances=a

Controls the placement and linkage of template instances.

A.2.46.1 Values

a must be one of the values listed in the following table.

Table 41  -instances Values
Value
Meaning
extern
Places all needed instances into the template repository within linker comdat sections and gives them global linkage. (If an instance in the repository is out of date, it is reinstantiated.)
Note: If you are compiling and linking in separate steps and you specify -instance=extern for the compilation step, you must also specify it for the link step.
explicit
Places explicitly instantiated instances into the current object file and gives them global linkage. Does not generate any other needed instances.
global
Places all needed instances into the current object file and gives them global linkage.
semiexplicit
Places explicitly instantiated instances into the current object file and gives them global linkage. Places all instances needed by the explicit instances into the current object file and gives them global linkage. Does not generate any other needed instances.
static
Note: -instances=static is deprecated. You no longer need to use -instances=static because -instances=global now gives you all the advantages of static without the disadvantages. This option was provided in earlier compilers to overcome problems that do not exist in this version of the compiler.
Places all needed instances into the current object file and gives them static linkage.
Defaults

If –instances is not specified, –instances=global is assumed.

See Also

Template Instance Placement and Linkage

A.2.47 –instlib=filename

Use this option to inhibit the generation of template instances that are duplicated in a library, either shared or static, and the current object. In general, if your program shares large numbers of instances with libraries, try -instlib=filename and see whether compilation time improves.

A.2.47.1 Values

Use the filename argument to specify a library that contains template instances that could be generated by the current compilation. The filename argument must contain a forward slash ’/’ character. For paths relative to the current directory, use dot-slash ’./’.

Defaults

The -instlib=filename option has no default and is only used if you specify it. This option can be specified multiple times and accumulates.

Example

Assume that the libfoo.a and libbar.so libraries instantiate many template instances that are shared with your source file a.cc. Adding -instlib=filename and specifying the libraries helps reduce compile time by avoiding the redundancy.

example% CC -c -instlib=./libfoo.a -instlib=./libbar.so a.cc
Interactions

When you compile with -g, if the library specified with -instlib=file is not compiled with -g, those template instances will not be debuggable. The workaround is to avoid -instlib=file when you use -g.

Warning

If you specify a library with -instlib, you must link with that library.

See Also

-template, -instances, –pti

A.2.48 –KPIC

(SPARC) (Obsolete) Same as –xcode=pic32.

(x86) Same as –Kpic.

Use this option to compile source files when building a shared library. Each reference to a global datum is generated as a dereference of a pointer in the global offset table. Each function call is generated in program counter (PC)-relative addressing mode through a procedure linkage table.

A.2.49 –Kpic

(SPARC) (Obsolete) Same as –xcode=pic13.

(x86) Compiles with position-independent code.

Use this option to compile source files when building a shared library. Each reference to a global datum is generated as a dereference of a pointer in the global offset table. Each function call is generated in program counter (PC)-relative addressing mode through a procedure linkage table.

A.2.50 –keeptmp

Retains temporary files created during compilation.

Along with –verbose=diags, this option is useful for debugging.

A.2.50.1 See Also

–v, –verbose

A.2.51 –Lpath

Adds path to the list of directories to search for libraries.

This option is passed to ld. The directory that is named by path is searched before compiler-provided directories.

A.2.51.1 Interactions

This option accumulates instead of overrides.

Warnings

Never specify the compiler installation area, /usr/include, /lib, or /usr/lib, as search directories.

A.2.52 –llib

Adds library liblib.a or liblib.so to the linker’s list of search libraries.

This option is passed to ld. Libraries generally have names such as liblib.a or liblib.so, where the lib and .a or .so parts are required. You should specify the lib part with this option. You can put as many libraries as you want on a single command line. Libraries are searched in the order specified with –Ldir.

Use this option after your object file name.

A.2.52.1 Interactions

This option accumulates instead of overrides.

Put -lx after the list of sources and objects to ensure that libraries are searched in the correct order.

Warnings

If you are building a multithreaded application, you must compile and link your program with the -mt option. See –mt.

See Also

–Ldir and -mt

A.2.53 –libmieee

This option is deprecated and will be removed in a future release. Use –xlibmieee instead.

A.2.54 –libmil

This option is deprecated and will be removed in a future release. Use -xlibmil instead.

A.2.55 –library=l[,l...]

Incorporates specified CC-provided libraries into compilation and linking.

A.2.55.1 Values

Keyword l must be one of the values in the following table. The no% prefix disables the associated option.

Table 42  -library Values
Value
Meaning
[no%]f77
Deprecated. Use -xlang=f95 instead.
[no%]f90
Deprecated. Use -xlang=f90 instead.
[no%]f95
Deprecated. Use -xlang=f95 instead.
[no%]iostream
Use libiostream, the classic iostreams library.
[no%]Cstd
Use libCstd, a C++ runtime library compatible with all C++5.x releases. Available only in -compat=5 mode.
[no%]Crun
Use libCrun, the C++ compiler support library only for -compat=5 mode.
[no%]CrunG3
Use libCrunG3, the C++ compiler support library for modes -compat=g, -std=c++03, -std=c++11, and -std=c++14. Not available with -compat=5 mode.
[no%]gc
Use libgc garbage collection.
[no%]stlport4
Use the STLport implementation of the standard library instead of the default library. Code compiled with -library=stlport4 cannot be used in the same program as code compiled with -library=Cstd or -library=stdcxx4. Available only in -compat=5 mode.
[no%]stlport4_dbg
Use STLport’s debug-enabled library. Available only in -compat=5 mode.
[no%]sunperf
Use the Sun Performance Library.
[no%]stdcxx4
Use the Apache stdcxx version 4 library installed as part of Oracle Solaris. This option also sets the -mt option implicitly. The stdcxx library requires multi-threading mode. Code compiled with -library=stdcxx4 cannot be used in the same program as code compiled with -library=Cstd or -library=stlport4. Available only in -compat=5 mode.
[no%]stdcpp
Use libstdc++, the C++ runtime library for modes -compat=g, -std=c++03, -std=c++11, and -std=c++14. Not available with -compat=5 mode.
%none
In –compat=5 or –std=sun03 mode, use no libraries except libCrun. In gcc compatibility modes (any of –compat=g or –std=[c++03|c++11|c++14]) use no libraries other than libCrunG3. libCrunG3 has a dependency on the g++ runtime libraries libgcc_s and libstdc++. The option –library=%none in gcc compatibility modes will not work unless you add no%CrunG3. The libCrunG3 library provides support for operator new, dynamic_cast, RTTI, exceptions, and initializing arrays of objects. Most programs require this library.

A.2.55.2 Defaults

  • –compat=5 mode

    • The libCstd library is always included unless it is specifically excluded using -library=%none or -library=no%Cstd, —library=stdcxx4 or -library=stlport4.

    • The libCrun library is always included unless it is specifically excluded using -library=no%Crun.

The libm library is always included, even if you specify -library=%none.

For other values of –std, –library=stdcpp is the default.

The –std and –library options have default values that depend on the platform. They are intended to match C++ libraries bundled with the operating system. See Platform-specific Option Defaults.

A.2.55.3 Examples

To link in -compat=5 mode without any C++ libraries (except libCrun):

example% CC -library=%none

A.2.55.4 Interactions

If a library is specified with -library, the proper –I paths are set during compilation. The proper –L, –Y P, –R paths and –l options are set during linking.

This option accumulates instead of overrides.

The specified libraries are linked before the system support libraries are linked.

For —library=stdcxx4, the Apache stdcxx library must be installed in /usr/include and /usr/lib on Oracle Solaris platforms.

You can use at most only one of -library=stlport4, -library=stdcxx4, or -library=Cstd options on any command line.

If you include both libCstd and libiostream, you must be careful to not use the old and new forms of iostreams within a program to access the same file (for example, cout and std::cout). Mixing standard iostreams and classic iostreams in the same program is likely to cause problems if the same file is accessed from both classic and standard iostream code.

If -xnolib is specified, -library is ignored.

A.2.55.5 Warnings

If you compile and link in separate steps, the set of -library options that appear in the compile command must appear in the link command.

The set of libraries is not stable and might change from release to release.

A.2.55.6 See Also

See Note About Classic iostreams.

–I, –l, –R, –staticlib, -xlang, –xnolib, Caveats:, Redistribution and Supported STLport Libraries.

For information about using the -library=no%cstd option to enable use of your own C++ standard library, see Replacing the C++ Standard Library.

A.2.56 –m32|–m64

Specifies the data type model for the compiled binary object.

Use –m32 to create 32-bit executables and shared libraries. Use –m64 to create 64-bit executables and shared libraries.

Object files or libraries compiled with –m32 cannot be linked with object files or libraries compiled with–m64.

When compiling applications with large amounts of static data using –m64, –xmodel=medium may also be required. Be aware that some Linux platforms do not support the medium model.

Modules that are compiled with –m32|–m64 must also be linked with –m32|–m64. For a complete list of compiler options that must be specified at both compile time and link time, see Compile-Time and Link-Time Options.

The default behavior depends on the platform. The behavior is intended to match C++ libraries bundled with the operating system. See Platform-specific Option Defaults.

A.2.56.1 See Also

–xarch.

A.2.57 –mc

Removes duplicate strings from the ELF .comment section of the object file. When you use the -mc option, the mcs —c command is invoked. See the mcs(1) man page for details.

A.2.58 –misalign

(SPARC) Obsolete. This option should not be used. Use —xmemalign=2i instead..

A.2.59 –mr[,string]

Removes all strings from the .comment section of the object file and, if string is supplied, places string in that section. If the string contains blanks, the string must be enclosed in quotation marks. When you use this option, the command mcs -d [-a string] is invoked.

A.2.60 –mt[={yes|no}]

Use this option to compile and link multithreaded code.

This option passes -D_REENTRANT to the preprocessor.

-mt=yes is the default behavior of the compiler. -mt is equivalent to -mt=yes. If this behavior is not desired use the option -mt=no.

The –xopenmp option (for using the OpenMP shared-memory parallelization API) includes –mt=yes automatically.

Use this option consistently. If you compile and link one translation unit with –mt, you must compile and link all units of the program with –mt.

To determine which system support libraries will be linked by default, compile with the –dryrun option.

A.2.60.1 See Also

–xnolib, and the Oracle Solaris Multithreaded Programming Guide and Oracle Solaris 11.3 Linkers and Libraries Guide

A.2.61 –native

Same as –xtarget=native.

A.2.62 –noex

Same as –features=no%except.

A.2.63 –nofstore

(x86) Cancel -fstore on command line.

Cancels forcing expressions to have the precision of the destination variable invoked by -fstore. -nofstore is invoked by -fast. -fstore is the usual default.

A.2.63.1 See Also

–fstore

A.2.64 –nolib

This option is deprecated and will be removed in a future release. Use –xnolib instead.

A.2.65 –nolibmil

This option is deprecated and will be removed in a future release. Use –xnolibmil instead.

A.2.66 –norunpath

Does not build a runtime search path for shared libraries into the executable.

If an executable file uses shared libraries, then the compiler normally builds in a path that points the runtime linker to those shared libraries. To do so, the compiler passes the –R option to ld. The path depends on the directory where you have installed the compiler.

This option is recommended for building executables that will be shipped to customers who might use a different path for the shared libraries that are referenced by the program. Refer to Using Shared Libraries

A.2.66.1 Interactions

If you use any shared libraries under the compiler installed area and you also use –norunpath, then you should either use the –R option at link time or set the environment variable LD_LIBRARY_PATH at runtime to specify the location of the shared libraries. Doing so enables the runtime linker to find the shared libraries.

A.2.67 –O

The -O macro expands to -xO3. (Some previous releases expanded —O to –xO2).

The change in default yields higher runtime performance. However, -xO3 may be inappropriate for programs that rely on all variables being automatically considered volatile. Typical programs that might have this assumption are device drivers and older multithreaded applications that implement their own synchronization primitives. The workaround is to compile with -xO2 instead of -O.

A.2.68 –Olevel

Same as –xOlevel.

A.2.69 –o filename

Sets the name of the output file or the executable file to filename.

A.2.69.1 Interactions

This interaction discussion applies only when using instances=extern, which is not the default.

When the compiler must store template instances, it stores them in the template repository in the output file’s directory. For example, the following command writes the object file to ./sub/a.o and writes template instances into the repository contained within ./sub/SunWS_cache.

example% CC -instances=extern -o sub/a.o a.cc

The compiler reads from the template repositories corresponding to the object files that it reads. For example, the following command reads from ./sub1/SunWS_Cache and ./sub2/SunWS_cache, and, if necessary, writes to ./SunWS_cache.

example% CC -instances=extern sub1/a.o sub2/b.o

For more information, see Template Repository.

Warnings

The filename must have the appropriate suffix for the type of file to be produced by the compilation. When used with -c, filename specifies the target .o object file; with the -G or -shared options, it specifies the target .so library file. This option and its argument are passed to ld.

filename cannot be the same file as the source file because the CC driver does not overwrite the source file.

A.2.70 +p

Ignore nonstandard preprocessor asserts.

A.2.70.1 Defaults

If +p is not present, the compiler recognizes nonstandard preprocessor asserts.

Interactions

If +p is used, the following macros are not defined:

  • sun

  • unix

  • sparc

  • i386

A.2.71 –P

Only preprocesses source; does not compile. (Outputs a file with a .i suffix.)

This option does not include preprocessor-type line number information in the output.

A.2.71.1 See Also

–E

A.2.72 –p

Obsolete, see –xpg.

A.2.73 –pedantic{=[yes|no]}

When enabled, emits warnings or errors for code that is accepted by default, but which does not conform to the C++ Standard. The Standard that is in effect is determined by the -compat and -std options:

C++ 2003

–compat=[5|g] or –std=[c++03|sun03]

C++ 2011

–std=c++11

C++ 2014

–std=c++14

The option –pedantic is equivalent to –pedantic=yes.

–pedantic=no is the default when no –pedantic option is specified.

The option does not interact with the +w or -w options.

If –pedantic appears more than once, the right-most option takes precedence.

A.2.74 –pentium

(x86) Replace with –xtarget=pentium.

A.2.75 –pg

This option is deprecated and will be removed in a future release. Use –xpg instead.

A.2.76 –PIC

(SPARC) Same as –xcode=pic32.

(x86) Same as –Kpic.

A.2.77 –pic

(SPARC) Same as –xcode=pic13.

(x86) Same as -Kpic.

A.2.78 –preserve_argvalues[=simple|none]

(x86) Saves copies of register-based function arguments in the stack.

When none is specified or if the -preserve_argvalues option is not specified on the command line, the compiler behaves as usual.

When simple is specified, up to six integer arguments are saved.

The values are not updated during the function lifetime on assignments to formal parameters.

A.2.79 –pta

Same as –template=wholeclass.

A.2.80 –ptipath

Specifies an additional search directory for template source.

This option is an alternative to the normal search path set by –Ipathname. If the -ptipath option is used, the compiler looks for template definition files on this path and ignores the –Ipathname option.

Using the –Ipathname option instead of –ptipath produces less confusion.

A.2.80.1 Interactions

This option accumulates instead of overrides.

A.2.80.2 See Also

–Ipathname, and Definitions Search Path

A.2.81 –pto

Same as –instances=static.

A.2.82 –ptv

Same as –verbose=template.

A.2.83 –Qoption phase option[,option…]

Passes option to the compilation phase.

To pass multiple options, specify them in order as a comma-separated list. Options that are passed to components with -Qoption might be reordered. Options that the driver recognizes are kept in the correct order. Do not use -Qoption for options that the driver already recognizes. For example, the C++ compiler recognizes the -z option for the linker (ld). If you issue a command like the following example, the -z options are passed in order to the linker.

CC -G -zallextract mylib.a -zdefaultextract ... // correct

But if you specify the command like as in the following example, the -z options can be reordered, giving incorrect results.

CC -G -Qoption ld -zallextract mylib.a -Qoption ld -zdefaultextract ... // error

A.2.83.1 Values

phase must have one of the values listed in the following table.

Table 43  -Qoption Values
SPARC
x86
ccfe
ccfe
previse
previse
iropt
iropt
cg
ube
CClink
CClink
ld
ld

A.2.83.2 Examples

In the following command, when ld is invoked by the CC driver, –Qoption passes the –i and –m options to ld.

example% CC -Qoption ld -i,-m test.c

A.2.83.3 Warnings

Be careful to avoid unintended effects. For example, the following sequence of options:

-Qoption ccfe -features=bool,iddollar

are interpreted as:

-Qoption ccfe -features=bool -Qoption ccfe iddollar

The correct usage is

-Qoption ccfe -features=bool,-features=iddollar

These features do not require —Qoption, and are used only as an example.

A.2.83.4 See also

–Wc,arg

A.2.84 –qoption phase option

Same as –Qoption.

A.2.85 –qp

Same as –p.

A.2.86 –Qproduce sourcetype

Causes the CC driver to produce output of the type sourcetype.

sourcetype types are defined in the following table:

Table 44  -Qproduce Values
Type
Meaning
.i
Preprocessed C++ source from ccfe.
.o
Generated object code.
.s
Assembler source from cg.

A.2.87 –qproduce sourcetype

Same as –Qproduce.

A.2.88 –Rpathname[:pathname…]

Builds dynamic library search paths into the executable file.

This option is passed to ld.

A.2.88.1 Defaults

If the –R option is not present, the library search path that is recorded in the output object and passed to the runtime linker depends upon various compilation options that are in effect. These include –compat/–std, –m32/–m64, –library, and –xarch.

Examine the output from —dryrun and the —R option passed to the linker, ld, to see the default paths assumed by the compiler.

A.2.88.2 Interactions

This option accumulates instead of overrides.

If the LD_RUN_PATH environment variable is defined and the –R option is specified, then the path from –R is scanned and the path from LD_RUN_PATH is ignored.

A.2.88.3 See Also

–norunpath, Oracle Solaris 11.3 Linkers and Libraries Guide

A.2.89 –S

Compiles and generates only assembly code.

This option causes the CC driver to compile the program and output an assembly source file, without assembling the program. The assembly source file is named with a .s suffix.

A.2.90 –s

Strips the symbol table from the executable file.

This option removes all symbol information from output executable files. This option is passed to ld.

A.2.91 -shared

Builds a dynamic shared library instead of an executable file.

All source files specified in the command line are compiled with the -pic option by default.

When building a shared library from files that involve templates and are compiled with the –instances=extern option, any template instances referenced by the .o files will be included from the template cache automatically.

If you are creating a shared object by specifying the -shared option along with other compiler options that must be specified at both compile time and link time, make sure that those same options are also specified at both compile time and link time when you link with the resulting shared object.

When you create a shared object, all the object files that are compiled for 64-bit SPARC architectures must also be compiled with an explicit -xcode value as documented under the description of -xcode.

A.2.91.1 Interactions

The following options are passed to the linker, if the -c option (the compile-only option) is not specified: -dy, -G, and -R.

A.2.91.2 Notes

When you use the -shared option, the compiler passes -l options to ld, which are the same -l options that are used to link default libraries when creating an executable.

A.2.91.3 See Also

–pic, Building Dynamic (Shared) Libraries, -dy, and ld(1) man page.

A.2.92 –staticlib=l[,l...]

Indicates which C++ libraries are to be linked statically, as specified by the -library option (including its defaults), and by the -xlang option.

A.2.92.1 Values

l must be one of the values listed in the following table.

Table 45  -staticlib Values
Value
Meaning
[no%]library
Link library statically. The valid values for library are all the valid values for -library (except %all and %none), and all the valid values for -xlang.
%all
Statically link all the libraries specified in the -library option, all the libraries specified in the -xlang option.
%none
Link no libraries specified in the -library option and the -xlang option statically.

A.2.92.2 Defaults

If –staticlib is not specified, –staticlib=%none is assumed.

Exception: On Linux, -staticlib=CrunG3 is the default when compiling in -std=c++03, -std=c++11, or -std=c++14 modes. Linking statically avoids having to provide this library to end users. On Oracle Solaris, since libCrunG3.so.1 is a part of the OS, dynamic linking is appropriate.

A.2.92.3 Examples

The following command links libCrun statically because Crun is a default value for –library:

example% CC –staticlib=Crun test.cc (correct)

However, the following command does not link libgc because libgc is not linked unless explicitly specified with the -library option:

example% CC –staticlib=gc test.cc (incorrect)
example% example% CC –library=gc –staticlib=gc test.cc (correct)

To link libgc statically, use the following command:

example% CC -library=gc -staticlib=gc (correct)

The following command will link the Sun Performance Libraries dynamically because -library=sunperf must be used in conjunction with -staticlib=sunperf in order for the -staticlib option to have an effect on the linking of these libraries:

example% CC -staticlib=sunperf (incorrect)
 

This command links the Sun Performance Libraries statically:

example% CC -library=sunperf -staticlib=sunperf (correct)

A.2.92.4 Interactions

This option accumulates instead of overrides.

The -staticlib option only works for the C++ libraries that are selected explicitly with the -xlang option, and the -library option, in addition to the C++ libraries that are selected implicitly by default. On Oracle Solaris, Cstd and Crun are selected by default.

A.2.92.5 Warnings

The set of allowable values for library is not stable and might change from release to release.

On Oracle Solaris platforms, system libraries are not available as static libraries.

You should link the support libraries dynamically unless you have a specific need to link them statically. In some cases, static linking can prevent a program from working correctly.

A.2.92.6 See Also

-library, Statically Linking Standard Libraries

A.2.93 –std=v

Sets the compatibility mode of the compiler. The mode specified by v is required and is one of the following:

c++03 (zero-3, not oh-3)

Equivalent to the -compat=g option. It selects C++ 03 dialect and g++ ABI. It is binary compatible with g++ on Oracle Solaris and Linux It sets the __SUNPRO_CC_COMPAT preprocessor macro to 'G'.

c++11

Selects C++ 11 dialect and g++ binary compatibility. It sets the __SUNPRO_CC_COMPAT preprocessor macro to 'G'.

c++14

Select C++ 14 dialect and g++ binary compatibility. It sets the __SUNPRO_CC_COMPAT preprocessor macro to 'G'.

c++0x (zero-x, not oh-x)

Equivalent to c++11.

sun03 (zero-3, not oh-3)

Equivalent to the -compat=5 option. It selects C++ 03 dialect and Sun ABI; it is binary compatible with C++ 5.x. It sets the __SUNPRO_CC_COMPAT preprocessor macro to '5'.

If more than one -std option appears on the command line, only the last one (right-most) has an effect.

The g++ binary compatibility options provide compatibility with the gcc/g++ compiler on all Oracle Solaris and Linux platforms. This compatibility extends only to shared (dynamic or .so) libraries, not to individual .o files or archive (.a) libraries. The gcc headers and libraries used are those provided with the compiler, rather than the version of gcc installed on the system.

The following example shows linking a g++ shared library to an Oracle Developer Studio C++ main program:

% g++ -shared -o libfoo.so -fpic a.cc b.cc c.cc  
% CC -std=c++03 main.cc -L. -lfoo

The following example shows linking an Oracle Developer Studio C++ shared library to a g++ main program:

% CC -std=c++03 -shared -o libfoo.so -Kpic a.cc b.cc c.cc
% g++ main.cc -L. -lfoo 

A.2.93.1 Defaults:

The –std and –library options have default values that depend on the platform. They are intended to match C++ libraries bundled with the operating system. See Platform-specific Option Defaults.

A.2.93.2 Interactions:

The -compat and -std options cannot appear on the same command line.

When -std other than -std=sun03 is specified, none of the following -library sub-options can be used: Cstd, Crun, iostream, stlport4, stdcxx4.

You can use discover(1) only in limited feature mode (option -l) when compiling with -std=c++11 or –std=c++14.

A.2.93.3 Notes:

The C++11 and C++14 dialects are not available with -compat=5 binary compatibility.

A.2.94 –sync_stdio=[yes|no]

Use this option when your runtime performance is degraded due to the synchronization between C++ iostreams and C stdio. Synchronization is needed only when you use iostreams to write to cout and stdio to write to stdout in the same program. The C++ standard requires synchronization so the C++ compiler turns it on by default. However, application performance is often much better without synchronization. If your program does not write to both cout and stdout, you can use the option -sync_stdio=no to turn off synchronization.

A.2.94.1 Defaults

If you do not specify -sync_stdio, the compiler sets it to -sync_stdio=yes.

A.2.94.2 Examples

Consider the following example:

#include <stdio.h>
#include <iostream>
int main()
{
   std::cout << "Hello ";
   printf("beautiful ");
   std::cout << "world!";
   printf("\n");
}

With synchronization, the program prints on a line by itself

Hello beautiful world!
:

Without synchronization, the output gets scrambled.

A.2.94.3 Warnings

This option is only effective for linking of executables, not for libraries.

A.2.95 –temp=path

Defines the directory for temporary files.

This option sets the path name of the directory for storing the temporary files which are generated during the compilation process. The compiler gives precedence to the value set by –temp over the value of TMPDIR.

A.2.95.1 See Also

–keeptmp

A.2.96 –template=opt[,opt…]

Enables/disables various template options.

A.2.96.1 Values

opt must be one of the values listed in the following table.

Table 46  -template Values
Value
Meaning
[no%]extdef
Search for template definitions in separate source files. With no%extdef, the compiler predefines _TEMPLATE_NO_EXTDEF
[no%]geninlinefuncs
Generate unreferenced inline member functions for explicitly instantiated class templates.
[no%]wholeclass
Instantiate a whole template class, rather than only those functions that are used. You must reference at least one member of the class. Otherwise, the compiler does not instantiate any members for the class.

A.2.96.2 Defaults

If the -template option is not specified, -template=no%wholeclass,no%extdef is assumed.

A.2.96.3 Examples

Consider the following code:

example% cat Example.cc
     template <class T> struct S {
               void imf() {}
               static void smf() {}
     };

     template class S <int>;

     int main() {
     }
example%

When you specify -template=geninlinefuncs, even though the two member functions of S are not called in the program, they are generated in the object file.

example% CC -c -template=geninlinefuncs Example.cc
example% nm -C Example.o

Example.o:

[Index] Value Size Type  Bind  Other Shndx Name
[5]       0   0    NOTY  GLOB  0     ABS   __fsr_init_value
[1]       0   0    FILE  LOCL  0     ABS   b.c
[4]      16   32   FUNC  GLOB  0     2     main
[3]     104   24   FUNC  LOCL  0     2     void S<int>::imf()
                                           [__1cBS4Ci_Dimf6M_v_]
[2]     64    20   FUNC  LOCL  0     2     void S<int>::smf()
                                           [__1cBS4Ci_Dsmf6F_v_]

A.2.96.4 See Also

Whole-Class Instantiation, Template Definition Searching

A.2.97 –time

This option is deprecated and will be removed in a future release. Use –xtime instead.

A.2.98 –traceback[={%none|common|signals_list}]

Issue a stack trace if a severe error occurs in execution.

The -traceback option causes the executable to issue a stack trace to stderr, dump core, and exit if certain signals are generated by the program. If multiple threads generate a signal, a stack trace will only be produced for the first one.

To use traceback, add the -traceback option to the compiler command line when linking. The option is also accepted at compile-time but is ignored unless an executable binary is generated. Do not use -traceback with the -G or -shared options to create a shared library.

Table 47  -traceback Options
Option
Meaning
common
Specifies that a stack trace should be issued if any of a set of common signals occurs: sigill, sigfpe, sigbus, sigsegv, or sigabrt.
signals_list
Specifies a comma-separated list of names of signals that should generate a stack trace, in lowercase. The following signals (those that cause the generation of a core file) can be caught: sigquit, sigill, sigtrap, sigabrt, sigemt, sigfpe, sigbus, sigsegv, sigsys, sigxcpu, sigxfsz.
Any of these signals can be preceded with no% to disable catching the signal.
For example: -traceback=sigsegv,sigfpe will produce a stack trace and core dump if either sigsegv or sigfpe occurs.
%none or none
disables traceback

If the option is not specified, the default is -traceback=%none

-traceback alone, without an = sign, implies -traceback=common

Note: If the core dump is not wanted, you may set the core dump size limit to zero using the following command:

% limit coredumpsize 0            

The -traceback option has no effect on runtime performance.

A.2.99 –Uname

Deletes initial definition of the preprocessor symbol name.

This option removes any initial definition of the macro symbol name created by -D on the command line including those implicitly placed there by the CC driver. This option has no effect on any other predefined macros, nor on macro definitions in source files.

To see the -D options that are placed on the command line by the CC driver, add the -dryrun option to your command line.

A.2.99.1 Examples

The following command undefines the predefined symbol __sun. Preprocessor statements in foo.cc such as #ifdef(__sun) will sense that the symbol is undefined.

example% CC -U__sun foo.cc

A.2.99.2 Interactions

You can specify multiple -U options on the command line.

All -U options are processed after any -D options that are present. That is, if the same name is specified for both -D and -U on the command line, name is undefined, regardless of the order the options appear.

A.2.99.3 See Also

-D

A.2.100 –unroll=n

This option is deprecated and will be removed in a future release. Use–xunroll=n instead.

A.2.101 –V

Same as –verbose=version.

A.2.102 –v

Same as –verbose=diags.

A.2.103 –verbose=v[,v…]

Controls compiler verbosity.

A.2.103.1 Values

v must be one of the values listed in the following table. The no% prefix disables the associated option.

Table 48  -verbose Values
Value
Meaning
[no%]diags
Print the command line for each compilation pass.
[no%]template
Turn on the template instantiation verbose mode (sometimes called the “verify” mode). The verbose mode displays each phase of instantiation as it occurs during compilation.
[no%]version
Direct the CC driver to print the names and version numbers of the programs it invokes.
%all
Invokes all of the other options.
%none
-verbose=%none is the same as -verbose=no%template,no%diags,no%version.
Defaults

If –verbose is not specified, –verbose=%none is assumed.

Interactions

This option accumulates instead of overrides.

A.2.104 –Wc,arg

Passes the argument arg to a specified component c.

Arguments must be separated from the preceding only by a comma. All –W arguments are passed after the rest of the command-line arguments. To include a comma as part of an argument, use the escape character \ (backslash) immediately before the comma.

For example, -Wa,-o,objfile passes -o and objfile to the assembler in that order. Also, -Wl,-I,name causes the linking phase to override the default name of the dynamic linker, /usr/lib/ld.so.1.

The order in which the arguments are passed to a tool with respect to the other specified command line options might change an subsequent compiler releases.

The possible values for c are listed in the following table.

Table 49  -W Flags
Flag
Meaning
a
Assembler: (fbe); (gas)
c
C++ code generator: (cg) (SPARC); (ube) (Intel)
d
CC driver
l
Link editor (ld)
m
mcs
O (Capital o)
Interprocedural optimizer
o (Lowercase o)
Postoptimizer
p
Preprocessor (cpp)
0 (Zero)
Compiler (ccfe)
2
Optimizer: (iropt)
3
Static error checking: (previse)

Note: You cannot use -Wd to pass CC options to the C++ compiler.

A.2.104.1 See also

–Qoption phase option[,option…]

A.2.105 +w

Identifies code that might have unintended consequences. The +w option no longer generates a warning if a function is too large to inline or if a declared program element is unused. These warnings do not identify real problems in the source, and were thus inappropriate to some development environments. Removing these warnings from +w enables more aggressive use of +w in those environments. These warnings are still available with the +w2 option.

This option generates additional warnings about constructs that are questionable in the following ways:

  • Nonportable

  • Likely to be mistakes

  • Inefficient

A.2.105.1 Defaults

If +w is not specified, the compiler warns about constructs that are almost certainly problems.

A.2.105.2 See Also

–w, +w2

A.2.106 +w2

Emits all the warnings emitted by +w plus warnings about technical violations that are probably harmless but that might reduce the maximum portability of your program.

The +w2 option no longer warns about the use of implementation-dependent constructs in the system header files. Because the system header files are the implementation, the warning was inappropriate. Removing these warnings from +w2 enables more aggressive use of the option.

A.2.106.1 See Also

+w

A.2.107 –w

Suppresses most warning messages.

This option causes the compiler not to print warning messages. However, some warnings, particularly warnings regarding serious anachronisms, cannot be suppressed.

A.2.107.1 See Also

+w, –erroff[=t], –errtags[=a]

A.2.108 –Xlinker arg

Pass arg to linker ld(1).

A.2.108.1 See Also

-z[ ]arg

A.2.109 –Xm

Same as –features=iddollar.

A.2.110 –xaddr32

(Oracle Solaris x86/x64) The -xaddr32=yes compilation flag restricts the resulting executable or shared object to a 32-bit address space.

An executable that is compiled in this manner results in the creation of a process that is restricted to a 32-bit address space.

When -xaddr32=no is specified, a normal 64 bit binary is produced.

If the -xaddr32 option is not specified, -xaddr32=no is assumed.

If only -xaddr32 is specified -xaddr32=yes is assumed.

This option is only applicable to -m64 compilations and only on Oracle Solaris platforms supporting SF1_SUNW_ADDR32 software capability. Because Linux kernels do not support address space limitation, this option is not available on Linux.

When linking, if a single object file was compiled with -xaddr32=yes, the whole output file is assumed to be compiled with -xaddr32=yes.

A shared object that is restricted to a 32-bit address space must be loaded by a process that executes within a restricted 32-bit mode address space.

For more information, refer to the SF1_SUNW_ADDR32 software capabilities definition described in the Oracle Solaris 11.3 Linkers and Libraries Guide.

A.2.111 –xalias_level[=n]

The C++ compiler can perform type-based alias-analysis and optimizations when you specify the following commands:

-xalias_level[=n]

where n is any, simple, or compatible.

A.2.111.1 –xalias_level=any

At this level of analysis, the compiler assumes that any type may alias any other type. However, despite this assumption, some optimization is possible.

A.2.111.2 –xalias_level=simple

The compiler assumes that simple types are not aliased. Storage objects must have a dynamic type that is one of the following simple types:

-char, signed char, unsigned char wchar_t, data pointer types
-short int, unsigned short int, int unsigned int, function pointer types
-long int, unsigned long int, long long int, unsigned long long int, data member pointer types
-float, double long double, enumeration types, function member pointer types

The storage object should only be accessed through lvalues of the following types:

  • The dynamic type of the object

  • A constant or volatile qualified version of the dynamic type of the object, a type that is the signed or unsigned type which corresponds to the dynamic type of the object

  • A type that is the signed or unsigned type which corresponds to the constant or volatile qualified version of the dynamic type of the object

  • An aggregate or union type that includes one of the aforementioned types among its members (including, recursively, a member of a subaggregate or contained union)

  • A char or unsigned char type.

A.2.111.3 –xalias_level=compatible

The compiler assumes that layout-incompatible types are not aliased. A storage object is only accessed through lvalues of the following types:

  • The dynamic type of the object

  • A constant or volatile qualified version of the dynamic type of the object, a type that is the signed or unsigned type which corresponds to the dynamic type of the object

  • A type that is the signed or unsigned type which corresponds to the constant or volatile qualified version of the dynamic type of the object

  • An aggregate or union type that includes one of the aforementioned types among its members (including, recursively, a member of a subaggregate or contained union)

  • A type that is (possibly constant or volatile qualified) base class type of the dynamic type of the object

  • A char or unsigned char type.

The compiler assumes that the types of all references are layout-compatible with the dynamic type of the corresponding storage object. Two types are layout-compatible under the following conditions:

  • If two types are the same type

  • If two types differ only in constant or volatile qualification

  • If for each of the signed integer types a corresponding (but different) unsigned integer type exists, these corresponding types are layout compatible.

  • Two enumeration types are layout-compatible if they have the same underlying type.

  • Two plain old data (POD) struct types are layout compatible if they have the same number of members, and corresponding members (in order) have layout compatible types.

  • Two POD union types are layout compatible if they have the same number of members, and corresponding members (in any order) have layout compatible types.

References may be non-layout-compatible with the dynamic type of the storage object under limited circumstances:

  • If a POD union contains two or more POD structs that share a common initial sequence, and if the POD union object currently contains one of those POD structs, it is permitted to inspect the common initial part of any of them. Two POD structs share a common initial sequence if corresponding members have layout compatible types and, as applicable to bit fields, the same widths, for a sequence of one or more initial members.

  • A pointer to a POD struct object, suitably converted using a reinterpret_cast, points to its initial member, or if that member is a bit field, to the unit in which it resides.

A.2.111.4 Defaults

If you do not specify -xalias_level, the compiler sets the option to -xalias_level=any. If you specify -xalias_level but do not provide a value, the compiler sets the option to -xalias_level=compatible.

A.2.111.5 Interactions

The compiler does not perform type-based alias analysis at optimization level -xO2 and below.

A.2.111.6 Warning

If you are using reinterpret_cast or an equivalent old-style cast, the program may violate the assumptions of the analysis. Also, union type punning, as shown in the following example, violates the assumptions of the analysis.

union bitbucket{
  int i;
  float f;
};

int bitsof(float f){
    bitbucket var;
    var.f=3.6;
    return var.i;
}

A.2.112 –xanalyze={code|%none}

(Obsolete) This option will be removed in a future release. Use -xprevise instead.

Produce a static analysis of the source code that can be viewed using the Oracle Developer Studio Code Analyzer.

When compiling with —xanalyze=code and linking in a separate step, include —xanalyze=code also on the link step.

The default is —xanalyze=%none.

On Linux, -xanalyze=code needs to be specified along with -xannotate.

See the Oracle Developer Studio Code Analyzer documentation for more information.

A.2.113 –xannotate[=yes|no]

Create binaries that can later be used by the optimization and observability tools binopt(1), code-analyzer(1), discover(1), collect(1), and uncover(1).

The default on Oracle Solaris is -xannotate=yes. The default on Linux is -xannotate=no. Specifying -xannotate without a value is equivalent to -xannotate=yes.

For optimal use of the optimization and observability tools, -xannotate=yes must be in effect at both compile and link time. Compile and link with -xannotate=no to produce slightly smaller binaries and libraries when optimization and observability tools will not be used.

A.2.114 –xar

Creates archive libraries.

When building a C++ archive that uses templates, include in the archive those template functions that are instantiated in the template repository. The template repository is used only when at least one object file was compiled using the -instances=extern option. Compiling with —xar automatically adds those templates to the archive as needed.

However, since the compiler default is not to use a template cache, the —xar option is often not needed. You can use the plain ar(1) command to create archives (.a files) of C++ code unless some code was compiled with —instances=extern. In that case, or if you are not sure, use CC —xar instead of the ar command.

A.2.114.1 Values

Specify -xar to invoke ar -c -r and create an archive from scratch.

Examples

The following command line archives the template functions contained in the template cache and object files.

example% CC -xar -o libmain.a a.o b.o c.o
Warnings

Do not add .o files from the template cache on the command line.

See Also

ar(1) man page

A.2.115 –xarch=isa

Specifies the target instruction set architecture (ISA).

This option limits the code generated by the compiler to the instructions of the specified instruction set architecture. This option does not guarantee use of any target–specific instructions. However, use of this option may affect the portability of a binary program.


Note -  Use the –m64 or –m32 option to specify the intended data type model, LP64 (64-bits) or ILP32 (32-bits) respectively. The –xarch option no longer indicates the data type model except for compatibility with previous releases, as indicated below.

Code using _asm statements or inline templates (.il files) that use architecture-specific instructions might require compiling with the appropriate —xarch value to avoid compilation errors.

If you compile and link in separate steps, make sure you specify the same value for -xarch in both steps. For complete list of all compiler options that must be specified at both compile time and at link time, see Compile-Time and Link-Time Options.

A.2.115.1 –xarch Flags for SPARC and x86

The following table lists the -xarch keywords common to both SPARC and x86 platforms.

Table 50  —xarch Flags for SPARC and x86
Flag
Meaning
generic
Uses the instruction set common to most processors. This is the default.
native
Compile for good performance on this system. The compiler chooses the appropriate setting for the current system processor it is running on.

A.2.115.2 -xarch Flags for SPARC

The following table gives the details for each of the -xarch keywords on SPARC platforms.

Table 51  -xarch Flags for SPARC Platforms
Flag
Meaning
sparc
Compile for the SPARC-V9 ISA but without the Visual Instruction Set (VIS) and without other implementation-specific ISA extensions. This option enables the compiler to generate code for good performance on the V9 ISA.
sparcvis
Compile for SPARC-V9 plus the Visual Instruction Set (VIS) version 1.0, and with UltraSPARC extensions. This option enables the compiler to generate code for good performance on the UltraSPARC architecture.
sparcvis2
Enables the compiler to generate object code for the UltraSPARC architecture, plus the Visual Instruction Set (VIS) version 2.0, and with UltraSPARC III extensions.
sparcvis3
Compile for the SPARC VIS version 3 of the SPARC-V9 ISA. Enables the compiler to use instructions from the SPARC-V9 instruction set plus the UltraSPARC extensions including the Visual Instruction Set (VIS) version 1.0, the UltraSPARC-III extensions, including the Visual Instruction Set (VIS) version 2.0, the fused multiply-add instructions, and the Visual Instruction Set (VIS) version 3.0
sparcfmaf
Enables the compiler to use instructions from the SPARC-V9 instruction set, plus the UltraSPARC extensions, including the Visual Instruction Set (VIS) version 1.0, the UltraSPARC-III extensions, including the Visual Instruction Set (VIS) version 2.0, and the SPARC64 VI extensions for floating-point multiply-add.
You must use –xarch=sparcfmaf in conjunction with fma=fused and some optimization level to get the compiler to attempt to find opportunities to use the multiply-add instructions automatically.
sparcace
Compile for the sparcace version of the SPARC-V9 ISA. Enables the compiler to use instructions from the SPARC-V9 instruction set, plus the UltraSPARC extensions, including the Visual Instruction Set (VIS) version 1.0, the UltraSPARC-III extensions, including the Visual Instruction Set (VIS) version 2.0, the SPARC64 VI extensions for floating-point multiply-add, the SPARC64 VII extensions for integer multiply-add, and the SPARC64 X extensions for ACE floating-point.
sparcaceplus
Compile for the sparcaceplus version of the SPARC-V9 ISA. Enables the compiler to use instructions from the SPARC-V9 instruction set, plus the UltraSPARC extensions, including the Visual Instruction Set (VIS) version 1.0, the UltraSPARC-III extensions, including the Visual Instruction Set (VIS) version 2.0, the SPARC64 VI extensions for floating-point multiply-add, the SPARC64 VII extensions for integer multiply-add, the SPARC64 X extensions for SPARCACE floating-point, and the SPARC64 X+ extensions for SPARCACE floating-point.
sparcace2
Compile for the sparcace2 version of the SPARC-V9 ISA. Enables the compiler to use instructions from the SPARC-V9 instruction set, plus the UltraSPARC extensions, including the Visual Instruction Set (VIS) version 1.0, the UltraSPARC-III extensions, including the Visual Instruction Set (VIS) version 2.0, the SPARC64 VI extensions for floating-point multiply-add, the SPARC64 VII extensions for integer multiply-add, the SPARC64 X extensions for SPARCACE floating-point, the SPARC64 X+ extensions for SPARCACE floating-point, and the SPARC64 XII extensions for SPARCACE floating-point.
sparcima
Compile for the SPARC IMA version of the SPARC-V9 ISA. Enables the compiler to use instructions from the SPARC-V9 instruction set, plus the UltraSPARC extensions, including the Visual Instruction Set (VIS) version 1.0, the UltraSPARC-III extensions, including the Visual Instruction Set (VIS) version 2.0, the SPARC64 VI extensions for floating-point multiply-add, and the SPARC64 VII extensions for integer multiply-add.
sparc4
Compile for the SPARC4 version of the SPARC-V9 ISA. Enables the compiler to use instructions from the SPARC-V9 instruction set, plus the extensions, which includes VIS 1.0, the UltraSPARC-III extensions, which includes VIS2.0, the fused floating-point multiply-add instructions, VIS 3.0, and SPARC4 instructions.
sparc4b
Compile for the SPARC4B version of the SPARC-V9 ISA. Enables the compiler to use instructions from the SPARC-V9 instruction set, plus the UltraSPARC extensions, which includes VIS 1.0, the UltraSPARC-III extensions, which includes VIS2.0, the SPARC64 VI extensions for floating-point multiply-add, the SPARC64 VII extensions for integer multiply-add, and the PAUSE and CBCOND instructions from the SPARC T4 extensions.
sparc4c
Compile for the SPARC4C version of the SPARC-V9 ISA. Enables the compiler to use instructions from the SPARC-V9 instruction set, plus the UltraSPARC extensions, which includes VIS 1.0, the UltraSPARC-III extensions, which includes VIS2.0, the SPARC64 VI extensions for floating-point multiply-add, the SPARC64 VII extensions for integer multiply-add, the VIS3B subset of the VIS 3.0 instructions a subset of the SPARC T3 extensions, called the VIS3B subset of VIS 3.0, and the PAUSE and CBCOND instructions from the SPARC T4 extensions.
sparc5
Compile for the SPARC5 version of the SPARC-V9 ISA. Enables the compiler to use instructions from the SPARC-V9 instruction set, plus the extensions, which includes VIS 1.0, the Ultra SPARC-III extensions, which includes VIS2.0, the fused floating-point multiply-add instructions, VIS 3.0, SPARC4, and SPARC5 instructions.
v9
Equivalent to –m64 –xarch=sparc. Legacy makefiles and scripts that use –xarch=v9 to obtain the 64-bit data type model need only use –m64.
v9a
Equivalent to –m64 –xarch=sparcvis and provided for compatibility with earlier releases.
v9b
Equivalent to –m64 –xarch=sparcvis2 and provided for compatibility with earlier releases.

Also note the following:

  • Object binary files (.o) compiled with generic,sparc, sparcvis2, sparcvis3, sparcfmaf, sparcima can be linked and can execute together, but can only run on a processor supporting all the instruction sets linked.

  • For any particular choice, the generated executable might not run or run much more slowly on legacy architectures. Also, because quad-precision (long double) floating-point instructions are not implemented in any of these instruction set architectures, the compiler does not use these instructions in the code it generates.

A.2.115.3 -xarch Flags for x86

The following table lists the -xarch flags on x86 platforms.

Table 52  -xarch Flags on x86
Flag
Meaning
pentium_pro (Obsolete)
You should not use this option. Use –xarch=generic instead.
For a complete list of obsolete options, see Obsolete Options.
pentium_proa
Adds the AMD extensions (3DNow!, 3DNow! extensions, and MMX extensions) to the 32-bit Pentium Pro architecture.
sse (Obsolete)
You should not use this option. Use –xarch=generic instead.
For a complete list of obsolete options, see Obsolete Options.
ssea
Adds the AMD extensions (3DNow!, 3DNow! extensions, and MMX extensions) to the 32-bit SSE architecture.
sse2
Adds the SSE2 instruction set to the Pentium Pro architecture.
sse2a
Adds the AMD extensions (3DNow!, 3DNow! extensions, and MMX extensions) to the 32-bit SSE2 architecture.
sse3
Adds the SSE3 instruction set to SSE2 instruction set.
sse3a
Adds the AMD extended instructions including 3dnow to the SSE3 instruction set.
ssse3
Supplements the Pentium Pro, SSE, SSE2, and SSE3 instruction sets with the SSSE3 instruction set.
sse4_1
Supplements the Pentium Pro, SSE, SSE2, SSE3, and SSSE3 instruction sets with the SSE4.1 instruction set.
sse4_2
Supplements the Pentium Pro, SSE, SSE2, SSE3,SSSE3, and SSE4.1 instruction sets with the SSE4.2 instruction set.
amdsse4a
Uses the AMD SSE4a Instruction set.
aes
Uses Intel Advanced Encryption Standard instruction set.
avx
Uses Intel Advanced Vector Extensions instruction set.
avx_i
Uses Intel Advanced Vector Extensions instruction set with the RDRND, FSGSBASE and F16C instruction sets.
avx2
Uses Intel Advanced Vector Extensions 2 instruction set.
avx2_i
Supplements the pentium_pro, SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2, AVX, AVX2 instruction sets with Broadwell instructions (ADOX, ADCX, MULX, RDSEED, PREFETCHWT1).
avx512
Uses the instructions sets AVX512F, AVX512CDI, AVX512VLI, AVX512BW and AVX512DQ.

If any part of a program is compiled or linked on an x86 platform with —m64, then all parts of the program must be compiled with one of these options as well. For details on the various Intel instruction set architectures (SSE, SSE2, SSE3, SSSE3, and so on) refer to the Intel 64 and IA-32 Architectures Software Developer Manualsat http://www.intel.com.

See also Special x86 Notes and Binary Compatibility Verification.

A.2.115.4 Interactions

Although this option can be used alone, it is part of the expansion of the– -xtarget option and may be used to override the ––xarch value that is set by a specific– -xtarget option. For example, –xtarget=T3 expands to –xarch=sparcvis3 –xchip=T3 –xcache=8/16/4:6144/64/24. In the following command –xarch=sparc4 overrides the –xarch=sparcvis3 that is set by the expansion of –xtarget=T3.

example% CC -xtarget=T3 -xarch=sparc4 foo.cc

A.2.115.5 Warnings

If you use this option with optimization, the appropriate choice can provide good performance of the executable on the specified architecture. An inappropriate choice, however, might result in serious degradation of performance or in a binary program that is not executable on the intended target platform.

If you compile and link in separate steps, make sure you specify the same value for -xarch in both steps.

A.2.116 -xatomic=a

Specify which atomics support runtime library is linked.

a must be one of the following:

studio

Link with the libstatomic library bundled with Oracle Developer Studio.

gcc

Link with the libatomic library in /usr/lib.

none

Do not link with any atomics support library.

The option –xatomic=studio is the default when neither –latomic nor –xatomic is specified, and the compiler is compiling in –std={c++03|c++11|c++14} mode.

–latomic will be automatically translated to –xatomic=studio.

An explicit –xatomic option overrides the presence of –latomic regardless of the order on the command line. A warning message will be emitted if the setting of –xatomic is conflict with –latomic.

See also –compat={5|g}, –std=v, and –xnolib and the Bundled Atomics Library for the GCC compatibility impact, the application deployment impact, and some notes about the –xatomic option.

When the Oracle Solaris operating system includes a compatible standard interface and the Linux bundled library conforms to a standard interface, the need for the –xatomic option will be redundant.

A.2.117 -xautopar

Enables automatic parallelization for multiple processors. Does dependence analysis (analyze loops for inter-iteration data dependence) and loop restructuring. If optimization is not at -xO3 or higher, optimization is raised to -xO3 and a warning is issued.

Avoid -xautopar if you do your own thread management.

To achieve faster execution, this option requires a multi-processor system. On a single-processor system, the resulting binary usually runs slower.

Use the OMP_NUM_THREADS environment variable to specify the number of threads to use when running a program automatically parallelized by the -xautopar compiler option. If OMP_NUM_THREADS is not set, the default number of threads used is a multiple of the number of cores per socket (that is, cores per processor chip), which is less than or equal to the total number of cores or 32, whichever is less. For best performance, the number of threads used should not exceed the number of hardware threads (or virtual processors) available on the machine. On Oracle Solaris systems, this number can be determined by using the psrinfo(1M) command. On Linux systems, this number can be determined by inspecting the file /proc/cpuinfo. See the Oracle Developer Studio 12.6: OpenMP API User’s Guide for more information.

In addition to OMP_NUM_THREADS, other environment variables that apply to an OpenMP programs may be used with a program automatically parallelized by the -xautopar compiler option. See the Oracle Developer Studio 12.6: OpenMP API User’s Guide for descriptions of the environment variables.

If you use -xautopar and compile and link in one step, then linking automatically includes the microtasking library and the threads-safe C runtime library. If you use -xautopar and compile and link in separate steps, then you must also link with -xautopar.

Use the -xreduction option in conjunction with -xautopar to recognize reduction operations in loops.

Use the -xloopinfo option to show which loops are parallelized.

A.2.117.1 See Also

-xopenmp[={parallel|noopt|none}]

A.2.118 -xbuiltin[={%all|%default|%none}]

Enables or disables better optimization of standard library calls.

Use the -xbuiltin option to improve the optimization of code that calls standard library functions. This option lets the compiler substitute intrinsic functions or inline system functions where profitable for performance. See the er_src(1) man page to learn how to read compiler commentary output to determine which functions were substituted by the compiler.

With —xbuiltin=%all, substitutions can cause the setting of errno to become unreliable. If your program depends on the value of errno, avoid this option.

—xbuiltin=%default only inlines functions that do not set errno. The value of errno is always correct at any optimization level, and can be checked reliably. With —xbuiltin=%default at —xO3 or lower, the compiler will determine which calls are profitable to inline, and not inline others.

The-xbuiltin=%none option results in the default compiler behavior, and the compiler does not do any special optimizations for built-in functions.

A.2.118.1 Defaults

If you do not specify —xbuiltin, the default is —xbuiltin=%default when compiling with an optimization level —xO1 and higher, and —xbuiltin=%none at —xO0. If you specify —xbuiltin without an argument, the default is —xbuiltin=%all and the compiler substitutes intrinsics or inlines standard library functions much more aggressively.

Note that the —xbuiltin option only inlines global functions defined in system header files, never static functions defined by the user. User code that attempts to interpose on global functions may result in undefined behavior.

Interactions

The expansion of the macro -fast includes -xbuiltin=%all.

Examples

The following compiler command requests special handling of the standard library calls.

example% CC -xbuiltin -c foo.cc

The following compiler command requests that there be no special handling of the standard library calls. Note that the expansion of the macro -fast includes -xbuiltin=%all.

example% CC -fast -xbuiltin=%none -c foo.cc

A.2.119 –xcache=c

Defines cache properties for use by the optimizer . This option does not guarantee that any particular cache property is used.


Note -  Although this option can be used alone, it is part of the expansion of the -xtarget option. Its primary use is to override a value supplied by the -xtarget option.

The optional property [/ti] sets the number of threads that can share the cache.

A.2.119.1 Values

c must be one of the values listed in the following table.

Table 53  -xcache Values
Value
Meaning
generic
Directs the compiler to use cache properties for good performance on most x86 and SPARC processors, without major performance degradation on any of them. (The default)
With each new release, these best timing properties will be adjusted, if appropriate.
native
Set the parameters for the best performance on the host environment.
s1/l1/a1[/t1]
Defines level 1 cache properties
s1/l1/a1[/t1]:s2/l2/a2[/t2]
Defines level 1 and 2 cache properties
s1/l1/a1[/t1]:s2/l2/a2[/t2]:s3/l3/a3[/t3]
Defines level 1, 2, and 3 cache properties

The definitions of the cache properties si/li/ai/ti are described in the following table:

Property
Definition
si
The size of the data cache at level i, in kilobytes
li
The line size of the data cache at level i, in bytes
ai
The associativity of the data cache at level i
ti
The number of hardware threads sharing the cache at level i

For example, i=1 designates level 1 cache properties, s1/l1/a1.

Defaults

If -xcache is not specified, the default -xcache=generic is assumed. This value directs the compiler to use cache properties for good performance on most SPARC processors without major performance degradation on any of them.

If you do not specify a value for t, the default is 1.

Examples

–xcache=16/32/4:1024/32/1 specifies the following values:

Level 1 Cache

16 Kbytes, 32 bytes line size, four-way associativity

Level 2 Cache

1024 Kbytes, 32 bytes line size, direct mapping associativity

See Also

–xtarget=t

A.2.120 -xchar[=o]

The option is provided solely for the purpose of easing the migration of code from systems where the char type is defined as unsigned. Unless you are migrating from such a system, do not use this option. Only code that relies on the sign of a char type needs to be rewritten to explicitly specify signed or unsigned.

A.2.120.1 Values

You can substitute one of the values in the following table for o.

Table 54  The -xchar Values
Value
Meaning
signed
Treat character constants and variables declared as char as signed. This option affects the behavior of compiled code, but does not affect the behavior of library routines.
s
Equivalent to signed
unsigned
Treat character constants and variables declared as char as unsigned. This option affects the behavior of compiled code, but does not affect the behavior of library routines.
u
Equivalent to unsigned
Defaults

If you do not specify -xchar, the compiler assumes -xchar=s.

If you specify -xchar, but do not specify a value, the compiler assumes -xchar=s.

Interactions

The -xchar option changes the range of values for the type char only for code compiled with -xchar. This option does not change the range of values for type char in any system routine or header file. In particular, the values of CHAR_MAX and CHAR_MIN, as defined by limits.h, do not change when this option is specified. Therefore, CHAR_MAX and CHAR_MIN no longer represent the range of values encodable in a plain char.

Warnings

If you use -xchar=unsigned, be particularly careful when you compare a char against a predefined system macro because the value in the macro may be signed. This situation is most common for any routine that returns an error code which is accessed through a macro. Error codes are typically negative values so when you compare a char against the value from such a macro, the result is always false. A negative number can never be equal to any value of an unsigned type.

Never use -xchar to compile routines for any interface exported through a library. The Oracle Solaris ABI specifies type char as signed, and system libraries behave accordingly. The effect of making char unsigned has not been extensively tested with system libraries. Instead of using this option, modify your code so that it does not depend on whether type char is signed or unsigned. The sign variety of type char varies among compilers and operating systems.

A.2.121 -xcheck[=i[,i]]

Compiling with -xcheck=stkovf adds a runtime check for stack overflow of the main thread in a single-threaded program as well as slave-thread stacks in a multithreaded program. If a stack overflow is detected, a SIGSEGV is generated. See the sigaltstack(2) man page for information on how to handle a SIGSEGV caused by a stack overflow differently than other address-space violations.

A.2.121.1 Values

i must be one of the values listed in the following table.

Table 55  -xcheck Values
Value
Meaning
%all
Perform all checks.
%none
Perform no checks.
stkovf[action]
Generate code to detect stack overflow errors at runtime, optionally specifying an action to be taken when a stack overflow error is detected.
A stack overflow error occurs when a thread's stack pointer is set beyond the thread's allocated stack bounds. The error may not be detected if the new top of stack address is writable.
A stack overflow error is detected if a memory access violation occurs as a direct result of the error, raising an associated signal (usually SIGSEGV). The signal thus raised is said to be associated with the error.
If -xcheck=stkovf[action] is specified, the compiler generates code to detect stack overflow errors in cases involving stack frames larger than the system page size. The code includes a library call to force a memory access violation instead of setting the stack pointer to an invalid but potentially mapped address (see _stack_grow(3C)).
The optional action, if specified, must be either :detect or :diagnose.
If action is :detect, a detected stack overflow error is handled by executing the signal handler normally associated with the error.
On SPARC, –xcheck=stkovf:detect is enabled by default. This prevents silent corruption of the stack due to stack overflow. It can be disabled by specifying –xcheck=no%stkovf.
If action is :diagnose, a detected stack overflow error is handled by catching the associated signal and calling stack_violation(3C) to diagnose the error. This is the default behavior if no action is specified.
If a memory access violation is diagnosed as a stack overflow error, the following message is printed to stderr:
ERROR: stack overflow detected: pc=<inst_addr>, sp=<sp_addr>
where <inst_addr> is the address of the instruction where the error was detected, and <sp_addr> is the value of the stack pointer at the time that the error was detected. After checking for stack overflow and printing the above message if appropriate, control passes to the signal handler normally associated with the error.
-xcheck=stkovf:detect adds a stack bounds check on entry to routines with stack frames larger than system page size (see _stack_grow(3C)). The relative cost of the additional bounds check should be negligible in most applications.
-xcheck=stkovf:diagnose adds a system call to thread creation (see sigaltstack(2)). The relative cost of the additional system call depends on how frequently the application creates and destroys new threads.
-xcheck=stkovf is supported only on Oracle Solaris. The C runtime library on Linux does not support stack overflow detection.
no%stkovf
Turns off stack-overflow checking.
init_local
Initialize local variables. See the Oracle Developer Studio 12.6: C User’s Guide for details.
Exercise caution when using –xcheck with a large amount of local data, such as arrays with more than 10,000 elements. This can cause the compiler's internal representation of the program to become very large when that local date is initialized, which can result in significantly longer compilation times, especially when combined with optimization levels greater than -02.
no%init_local
Do not initialize local variables.
noreturn
Inform the compiler to add code to cause a runtime error if a routine which has been described as "do not return" returns.
A routine can be described as "do not return" by any of the following:
  • __attribute__ ((noreturn))

  • #pragma does_not_return

  • using the C11 qualifier _Noreturn

Undefined behaviour will result if a routine returns after being described as not returning. The -xcheck=noreturn flag tells the compiler to add an illegal instruction after every call to a function marked as does not return to force the target application to abort if that function returns.
Defaults

If you do not specify -xcheck, the compiler defaults to-xcheck=noreturn. If you specify -xcheck without any arguments, the compiler defaults to-xcheck=%all, unless you are on an Oracle Solaris system for SPARC, in which case the compiler defaults to -xcheck=stkovf:detect for both cases.

The -xcheck option does not accumulate on the command line. The compiler sets the flag in accordance with the last occurrence of the command.

A.2.122 -xchip=c

Specifies target processor for use by the optimizer.

The –xchip option specifies timing properties by specifying the target processor. This option affects the following properties:

  • The ordering of instructions—that is, scheduling

  • The way the compiler uses branches

  • The instructions to use in cases where semantically equivalent alternatives are available


    Note -  Although this option can be used alone, it is part of the expansion of the -xtarget option. Its primary use is to override a value supplied by the -xtarget option.

A.2.122.1 Values

c must be one of the values listed in the following two tables.

Table 56  -xchip Values for SPARC Processors
generic
Good performance on most SPARC processors.
native
Good performance on the host SPARC system on which the compiler is running.
sparc64vi
SPARC64 VI processor (Obsolete).
sparc64vii
SPARC64 VII processor (Obsolete).
sparc64viiplus
SPARC64 VII+ processor (Obsolete).
sparc64x
SPARC64 X processor.
sparc64xplus
SPARC64 X+ processor.
sparc64xii
SPARC64 XII processor.
ultraT1
UltraSPARC T1 processor (Obsolete).
ultraT2
UltraSPARC T2 processor (Obsolete).
ultraT2plus
UltraSPARC T2+ processor.
T3
SPARC T3 processor (Obsolete).
T4
SPARC T4 processor.
T5
Uses the timing properties of the SPARC T5 processor.
T7
Uses the timing properties of the SPARC T7 processor.
M5
Uses the timing properties of the SPARC M5 processor.
M6
Uses the timing properties of the SPARC M6 processor.
M7
Uses the timing properties of the SPARC M7 processor.
Table 57  -xchip Values for x86/x64 Processors
generic
Good performance on most x86 processors
native
Good performance on the host x86 system on which the compiler is running
core2
Intel Core2 processor
nehalem
Intel Nehalem processor
opteron
AMD Opteron processor
penryn
Intel Penryn processor
pentium
Obsolete. You should not use this option. Use –xchip=generic instead.
For a complete list of obsolete options, see Obsolete Options.
pentium_pro
Obsolete. You should not use this option. Use –xchip=generic instead.
For a complete list of obsolete options, see Obsolete Options.
pentium3
Obsolete. You should not use this option. Use –xchip=generic instead.
For a complete list of obsolete options, see Obsolete Options.
pentium4
Intel Pentium 4 style processor
amdfam10 (Obsolete)
AMD AMDFAM10 processor
sandybridge
Intel Sandy Bridge processor
ivybridge
Intel Ivy Bridge processor
haswell
Intel Haswell processor
westmere
Intel Westmere processor
broadwell
Intel Broadwell processor
skylake
Intel Skylake processor
Defaults

On most processors, generic is the default value that directs the compiler to use the best timing properties for good performance without major performance degradation on any of the processors.

A.2.123 –xcode=a

(SPARC) Specifies the code address space.


Note -  You should build shared objects by specifying -xcode=pic13 or -xcode=pic32. Shared objects built without pic13 or pic32 will not work correctly, and might not build at all.

A.2.123.1 Values

a must be one of the values listed in the following table.

Table 58  -xcode Values
Value
Meaning
abs32
Generates 32-bit absolute addresses, which are fast but have limited range. Code + data + bss size is limited to 2**32 bytes.
abs44
(SPARC) Generates 44-bit absolute addresses, which have moderate speed and moderate range. Code + data + bss size is limited to 2**44 bytes. Available only on 64-bit architectures. Do not use this value with dynamic (shared) libraries.
abs64
(SPARC) Generates 64-bit absolute addresses, which are slow but have full range. Available only on 64-bit architectures.
pic13
Generates position-independent code (small model), which is fast but has limited range. Equivalent to -Kpic. Permits references to at most 2**11 unique external symbols on 32-bit architectures; 2**10 on 64-bit.
pic32
Generates position-independent code (large model), which might not be as fast as pic13, but has full range. Equivalent to -KPIC. Permits references to at most 2**30 unique external symbols on 32-bit architectures; 2**29 on 64-bit.

To determine whether to use –xcode=pic13 or –xcode=pic32, check the size of the Global Offset Table (GOT) by using elfdump -c and look for the section header sh_name: .got. The sh_size value is the size of the GOT. If the GOT is less than 8,192 bytes, specify -xcode=pic13, otherwise specify -xcode=pic32. See the elfdump(1) man page for more information.

In general, use the following guidelines to determine how you should use -xcode:

  • If you are building an executable you should not use –xcode=pic13 or -xcode=pic32.

  • If you are building an archive library only for linking into executables you should not use -xcode=pic13 or -xcode=pic32.

  • If you are building a shared library, start with– xcode=pic13. Once the GOT size exceeds 8,192 bytes, use -xcode=pic32.

  • If you are building an archive library for linking into shared libraries you should only use -xcode=pic32.

Defaults

The default is -xcode=abs32 for 32–bit architectures. The default for 64–bit architectures is -xcode=abs44.

When building shared dynamic libraries, the default -xcode values of abs44 and abs32 will not work with 64–bit architectures. Specify -xcode=pic13 or -xcode=pic32 instead. There are two nominal performance costs with -xcode=pic13 and -xcode=pic32 on SPARC:

  • A routine compiled with either -xcode=pic13 or -xcode=pic32 executes a few extra instructions upon entry to set a register to point at a table (_GLOBAL_OFFSET_TABLE_) used for accessing a shared library’s global or static variables.

  • Each access to a global or static variable involves an extra indirect memory reference through _GLOBAL_OFFSET_TABLE_. If the compile is done with -xcode=pic32, there are two additional instructions per global and static memory reference.

When considering the above costs, remember that the use of -xcode=pic13 and -xcode=pic32 can significantly reduce system memory requirements due to the effect of library code sharing. Every page of code in a shared library compiled -xcode=pic13 or– xcode=pic32 can be shared by every process that uses the library. If a page of code in a shared library contains even a single non-pic (that is, absolute) memory reference, the page becomes nonsharable, and a copy of the page must be created each time a program using the library is executed.

The easiest way to tell whether a .o file has been compiled with -xcode=pic13 or –xcode=pic32 is with the nm command:

% nm file.o | grep _GLOBAL_OFFSET_TABLE_ U _GLOBAL_OFFSET_TABLE_

A .o file containing position-independent code contains an unresolved external reference to _GLOBAL_OFFSET_TABLE_, as indicated by the letter U.

To determine whether to use -xcode=pic13 or -xcode=pic32, use nm to identify the number of distinct global and static variables used or defined in the library. If the size of _GLOBAL_OFFSET_TABLE_ is under 8,192 bytes, you can use -Kpic. Otherwise, you must use -xcode=pic32.

A.2.124 -xcompress={[no%]debug}

Compress debug sections using the format specified by the -xcompress_format option if supported by the underlying Operating System. A sub-option is required. The option is ignored with a warning when Operating System support is unavailable.

A.2.125 -xcompress_format=cmp-type

When -xcompress=debug is in effect, this option specifies how the debug section is to be compressed.

The following values for cmp-type are recognized.

none

No compression of the debug section is done.

zlib

Compress the debug section using ZLIB compression.

zlib-gnu

Compress the section using ZLIB compression, using the GNU section compression format.

On Oracle Solaris, when compilation involves linking, the debug sections are compressed using the ld option –z compress-sections=cmp-type. For more information, see the ld(1) man page.

On Oracle Solaris, when compiling to an object file (.o), the debug sections are compressed using elfcompress -t cmp-type. For more information, see the elfcompress(1) man page.

On Linux, the objcopy command is used to compress debug sections of each .o file and thus objcopy --compress-debug-sections. For more information, see the objcopy(1g) man page.

The option is ignored with a warning when Operating System support is unavailable.

A.2.126 -xdebugformat=dwarf

Use this option to control the format of debugger information emitted by the compiler. Debugger information is emitted when a debugging option such as -g is used. A small amount of debugger information is emitted even without a debugging option.

A.2.126.1 Values

Table 59  -xdebugformat Flags
Value
Meaning
dwarf
-xdebugformat=dwarf generates debugging information using the standard dwarf format.
Defaults

-xdebugformat=dwarf is the default and obsolete option.

Notes

The detailed format of individual fields in dwarf format may evolve over time.

See also the man page for dwarfdump(1).

A.2.127 -xdebuginfo=a[,a...]

Control how much debugging and observability information is emitted.

The term tagtype refers to tagged types: structs, unions, enums, and classes.

The following list contains the possible values for sub-options a. The prefix no% applied to a sub-option disables that sub-option. The default is -xdebuginfo=%none. Specifying -xdebuginfo without a sub-option is forbidden.

%none

No debugging information is generated. This is the default.

[no%]line

Emit line number and file information.

[no%]param

Emit location list info for parameters. Emit full type information for scalar values (for example, int, char *) and type names but not full definitions of tagtypes.

[no%]variable

Emit location list information for lexically global and local variables, including file and function statics but excluding class statics and externs. Emit full type information for scalar values such as int and char * and type names but not full definitions of tagtypes.

[no%]decl

Emit information for function and variable declarations, member functions, and static data members in class declarations.

[no%]tagtype

Emit full type definitions of tagtypes referenced from param and variable datasets, as well as template definitions.

[no%]macro

Emit macro information.

[no%]codetag

Emit DWARF codetags. This is information regarding bitfields, structure copy, and spills used by RTC and discover.

[no%]hwcpro

Generate information critical to hardware counter profiling. This information includes ldst_map, a mapping from ld/st instructions to the symbol table entry being referenced, and branch_target table of branch-target addresses used to verify that backtracking did not cross a branch-target. See -xhwcprof for more information.


Note -  ldst_map requires the presence of tagtype information. The driver will issue an error if this requirement is not met.

These are macros which expand to combinations of -xdebuginfo and other options as follows:

-g = -g2

-gnone =
        -xdebuginfo=%none
        -xglobalize=no
        -xpatchpadding=fix
        -xkeep_unref=no%funcs,no%vars

-g0 =
        -xdebuginfo=line,param,decl,variable,tagtype
        -xglobalize=yes
        -xpatchpadding=fix
        -xkeep_unref=funcs,vars

-g1 =
        -xdebuginfo=line,param,codetag
        -xglobalize=no
        -xpatchpadding=fix
        -xkeep_unref=no%funcs,no%vars

-g2 =
        -xdebuginfo=line,param,decl,variable,tagtype,codetag
        -xglobalize=yes
        -xpatchpadding=fix
        -xkeep_unref=funcs,vars

-g3 =

        -xdebuginfo=line,param,decl,variable,tagtype,codetag,macro
        -xglobalize=yes
        -xpatchpadding=fix
        -xkeep_unref=funcs,vars

A.2.128 -xdepend=[yes|no]

Analyzes loops for inter-iteration data dependencies and does loop restructuring, including loop interchange, loop fusion, scalar replacement, and elimination of “dead array” assignments.

The –xdepend option defaults to –xdepend=yes for all optimization levels –xO3 and above. Otherwise –xdepend defaults to –xdepend=no. Specifying an explicit setting of –xdepend overrides any default setting.

Specifying –xdepend without an argument is equivalent to –xdepend=yes.

Dependency analysis is included in -xautopar. Dependency analysis is done at compile time.

Dependency analysis may help on single-processor systems. However, if you use –xdepend on single-processor systems, you should not also specify –xautopar because the –xdepend optimization will be done for a multiprocessor system.

A.2.128.1 See Also

–xprefetch_auto_type

A.2.129 -xdumpmacros[=value[,value...]]

Use this option when you want to see how macros are behaving in your program. This option provides information such as macro defines, undefines, and instances of usage. It prints output to the standard error (stderr), based on the order in which macros are processed. The -xdumpmacros option is in effect through the end of the file or until it is overridden by the dumpmacros or end_dumpmacros pragma. See #pragma dumpmacros.

A.2.129.1 Values

The following table lists the valid arguments for value. The prefix no% disables the associated value.

Table 60  -xdumpmacros Values
Value
Meaning
[no%]defs
Print all macro defines.
[no%]undefs
Print all macro undefines.
[no%]use
Print information about macros used.
[no%]loc
Print location (path name and line number) also for defs, undefs, and use.
[no%]conds
Print use information for macros used in conditional directives.
[no%]sys
Print all macros defines, undefines, and use information for macros in system header files.
%all
Sets the option to -xdumpmacros=defs,undefs,use,loc,conds,sys. A good way to use this argument is in conjunction with the [no%] form of the other arguments. For example, -xdumpmacros=%all,no%sys would exclude system header macros from the output but still provide information for all other macros.
%none
Do not print any macro information.

The option values accumulate, so specifying -xdumpmacros=sys -xdumpmacros=undefs has the same effect as -xdumpmacros=undefs,sys.


Note -  The sub-options loc, conds, and sys are qualifiers for defs, undefs and use options. By themselves, loc, conds, and sys have no effect. For example, -xdumpmacros=loc,conds,sys has no effect.
Defaults

Specifying -xdumpmacros without any arguments defaults to -xdumpmacros=defs,undefs,sys. The default when not specifying -xdumpmacros is -xdumpmacros=%none.

Examples

If you use the option -xdumpmacros=use,no%loc, the name of each macro that is used is printed only once. However, if you want more detail, use the option -xdumpmacros=use,loc so the location and macro name is printed every time a macro is used.

Consider the following file t.c:

example% cat t.c
#ifdef FOO
#undef FOO
#define COMPUTE(a, b) a+b
#else
#define COMPUTE(a,b) a-b
#endif
int n = COMPUTE(5,2);
int j = COMPUTE(7,1);
#if COMPUTE(8,3) + NN + MM
int k = 0;
#endif

The following examples show the output for file t.c based on the defs, undefs, sys, and loc arguments.

example% CC -c -xdumpmacros -DFOO t.c
#define __SunOS_5_9 1
#define __SUNPRO_CC 0x5140
#define unix 1
#define sun 1
#define sparc 1
#define __sparc 1
#define __unix 1
#define __sun 1
#define __BUILTIN_VA_ARG_INCR 1
#define __SVR4 1
#define __SUNPRO_CC_COMPAT 5
#define __SUN_PREFETCH 1
#define FOO 1
#undef FOO
#define COMPUTE(a, b) a + b

example% CC -c -xdumpmacros=defs,undefs,loc -DFOO -UBAR t.c
command line: #define __SunOS_5_9 1
command line: #define __SUNPRO_CC 0x5140
command line: #define unix 1
command line: #define sun 1
command line: #define sparc 1
command line: #define __sparc 1
command line: #define __unix 1
command line: #define __sun 1
command line: #define __BUILTIN_VA_ARG_INCR 1
command line: #define __SVR4 1
command line: #define __SUNPRO_CC_COMPAT 5
command line: #define __SUN_PREFETCH 1
command line: #define FOO 1
command line: #undef BAR
t.c, line 2: #undef FOO
t.c, line 3: #define COMPUTE(a, b) a + b

The following examples show how the use, loc, and conds arguments report macro behavior in file t.c:

example% CC -c -xdumpmacros=use t.c
used macro COMPUTE

example% CC -c -xdumpmacros=use,loc t.c
t.c, line 7: used macro COMPUTE
t.c, line 8: used macro COMPUTE

example% CC -c -xdumpmacros=use,conds t.c
used macro FOO
used macro COMPUTE
used macro NN
used macro MM

example% CC -c -xdumpmacros=use,conds,loc t.c
t.c, line 1: used macro FOO
t.c, line 7: used macro COMPUTE
t.c, line 8: used macro COMPUTE
t.c, line 9: used macro COMPUTE
t.c, line 9: used macro NN
t.c, line 9: used macro MM

Consider the file y.c:

example% cat y.c
#define X 1
#define Y X
#define Z Y
int a = Z;

The following example shows the output from -xdumpmacros=use,loc based on the macros in y.c:

example% CC -c -xdumpmacros=use,loc y.c
y.c, line 4: used macro Z
y.c, line 4: used macro Y
y.c, line 4: used macro X
See Also

Pragma dumpmacros/end_dumpmacros overrides the scope of the -xdumpmacros command-line option.

A.2.130 -xe

Checks only for syntax and semantic errors. When you specify -xe, the compiler does not produce any object code. The output for -xe is directed to stderr.

Use the -xe option if you do not need the object files produced by compilation. For example, if you are trying to isolate the cause of an error message by deleting sections of code, you can speed the edit and compile cycle by using -xe.

A.2.130.1 See Also

–c

A.2.131 –xF[=v[,v...]]

Enables optimal reordering of function s and variables by the linker.

This option instructs the compiler to place functions or data variables into separate section fragments, which enables the linker to reorder these sections to optimize program performance using directions in a mapfile specified by the linker’s -M option. Generally, this optimization is only effective when page fault time constitutes a significant fraction of program run time.

Reordering of variables can help solve the following problems which negatively impact runtime performance:

  • Cache and page contention caused by unrelated variables that are near each other in memory

  • Unnecessarily large work-set size as a result of related variables which are not near each other in memory

  • Unnecessarily large work-set size as a result of unused copies of weak variables that decrease the effective data density

Reordering variables and functions for optimal performance requires the following operations:

  1. Compiling and linking with -xF.

  2. Following the instructions in the Oracle Developer Studio 12.6: Performance Analyzer regarding how to generate a mapfile for functions or following the instructions in the Oracle Solaris 11.3 Linkers and Libraries Guide regarding how to generate a mapfile for data.

  3. Relinking with the new mapfile by using the linker’s -M option.

  4. Re-executing under the Analyzer to verify improvement.

A.2.131.1 Values

v can be one or more of the values listed in the following table. The no% prefix disables the associated value.

Table 61  –xF Values
Value
Meaning
[no%]func
Fragment functions into separate sections.
[no%]gbldata
Fragment global data (variables with external linkage) into separate sections.
[no%]lcldata
Fragment local data (variables with internal linkage) into separate sections.
%all
Fragment functions, global data, and local data.
%none
Fragment nothing.
Defaults

If you do not specify -xF, the default is -xF=%none. If you specify -xF without any arguments, the default is -xF=%none,func.

Interactions

Using -xF=lcldata inhibits some address calculation optimizations, so you should only use this flag when it is experimentally justified.

See Also

The analyzer(1) and ld(1) man pages

A.2.132 -xglobalize[={yes|no}]

Control globalization of function-level or file-level static variables.

Globalization is a technique needed by fix and continue functionality in the debugger whereby function-level or file-level static symbols are promoted to globals while a prefix is added to the name to keep identically named symbols distinct.

The default is -xglobalize=no. Specifying -xglobalize is equivalent to specifying -xglobalize=yes.

A.2.132.1 Interactions

See -xpatchpadding.

A.2.133 -xhelp=flags

Displays a brief description of each compiler option.

-xhelp=gccflags displays a summary of addtional gcc flags accepted by Studio that is not shown by the -xhelp=flags.

A.2.134 -xhwcprof

Enables compiler support for hardware counter-based profiling.

When -xhwcprof is enabled, the compiler generates information that helps tools associate profiled load and store instructions with the data-types and structure members (in conjunction with symbolic information produced with -g to which they refer. It associates profile data with the data space of the target, rather than the instruction space. This option provides insight into behavior that is not easily obtained from instruction profiling alone.

You can compile a specified set of object files with -xhwcprof. However, -xhwcprof is most useful when applied to all object files in the application, providing complete coverage to identify and correlate all memory references distributed in the application’s object files.

If you are compiling and linking in separate steps, use -xhwcprof at link time as well. Future extensions to -xhwcprof may require its use at link time.

An instance of -xhwcprof=enable or -xhwcprof=disable overrides all previous instances of -xhwcprof in the same command line.

-xhwcprof is disabled by default. Specifying -xhwcprof without any arguments is the equivalent to -xhwcprof=enable.

-xhwcprof requires that optimization is turned on and that the DWARF debug data format is selected. Note that DWARF format (-xdebugformat=dwarf) is now the default with current Oracle Developer Studio compilers.

-xhwcprof uses -xdebuginfo to automatically enable the minimum amount of debugging information it needs, so -g is not required.

The combination of -xhwcprof and -g increases compiler temporary file storage requirements by more than the sum of the increases resulting from either -xhwcprof and -g alone.

-xhwcprof is implemented as a macro that expands to various other, more primitive, options as follows:

-xhwcprof
        -xdebuginfo=hwcprof,tagtype,line
-xhwcprof=enable
        -xdebuginfo=hwcprof,tagtype,line
-xhwcprof=disable
        -xdebuginfo=no%hwcprof,no%tagtype,no%line

The following command compiles example.cc and specifies support for hardware counter profiling and symbolic analysis of data types and structure members:

example% CC -c -O -xhwcprof -g example.cc

For more information about hardware counter-based profiling, see the Performance Analyzer manual.

A.2.135 -xinline[=func-spec[,func-spec...]]

Specifies which user-written routines can be inlined by the optimizer at -xO3 levels or higher.

A.2.135.1 Values

func-spec must be one of the values listed in the following table.

Table 62  -xinline Values
Value
Meaning
%auto
Enable automatic inlining at optimization levels -xO4 or higher. This argument tells the optimizer that it can inline functions of its choosing. Note that without the %auto specification, automatic inlining is normally turned off when explicit inlining is specified on the command line by -xinline=[no%]func-name...
func_name
Strongly request that the optimizer inline the function. If the function is not declared as extern "C", the value of func_name must be mangled. You can use the nm command on the executable file to find the mangled function names. For functions declared as extern "C", the names are not mangled by the compiler.
no%func_name
When you prefix the name of a routine on the list with no%, the inlining of that routine is inhibited. The rule about mangled names for func-name applies to no%func-name as well.

Only routines in the file being compiled are considered for inlining unless you use -xipo[=1|2]. The optimizer decides which of these routines are appropriate for inlining.

A.2.135.2 Defaults

If the -xinline option is not specified, the compiler assumes -xinline=%auto.

If -xinline= is specified with no arguments, no functions are inlined regardless of the optimization level.

A.2.135.3 Examples

To enable automatic inlining while disabling inlining of the function declared int foo(), use the following command:

example% CC -xO5 -xinline=%auto,no%__1cDfoo6F_i_ -c a.cc

To strongly request the inlining of the function declared as int foo(), and to make all other functions as the candidates for inlining, use the following command:

example% CC -xO5 -xinline=%auto,__1cDfoo6F_i_ -c a.cc

To strongly request the inlining of the function declared as int foo(), and to not allow inlining of any other functions, use the following command:

example% CC -xO5 -xinline=__1cDfoo6F_i_ -c a.cc

A.2.135.4 Interactions

The -xinline option has no effect for optimization levels below -xO3. At -xO4 and higher, the optimizer decides which functions should be inlined, and does so without the -xinline option being specified. At -xO4 and higher, the compiler also attempts to determine which functions will improve performance if they are inlined.

A routine is inlined if any of the following conditions apply.

  • Optimization is -xO3 or greater

  • Inlining is judged to be profitable and safe

  • The function is in the file being compiled, or the function is in a file that was compiled with –xipo[=1|2]

A.2.135.5 Warnings

If you force the inlining of a function with -xinline, you might actually diminish performance.

A.2.135.6 See Also

-xldscope={v}

A.2.136 –xinline_param=a[,a[,a]...]

Use this option to manually change the heuristics used by the compiler for deciding when to inline a function call.

This option only has an effect at -O3 or higher. The following sub-options have an effect only at -O4 or higher when automatic inlining is on.

In the following sub-options n must be a positive integer; a can be one of the following:

Table 63  -xinline_param Sub-options
Sub-option
Meaning
default
Set the values of all the sub-options to their default values.
max_inst_hard[:n]
Automatic inlining only considers functions smaller than n pseudo instructions (counted in compiler's internal representation) as possible inline candidates.
Under no circumstances will a function larger than this be considered for inlining.
max_inst_soft[:n]
Set inlined function's size limit to n pseudo instructions (counted in compiler's internal representation).
Functions of greater size than this may sometimes be inlined.
When interacting with max_inst_hard, the value of max_inst_soft should be equal to or smaller than the value of max_inst_hard, i.e, max_inst_soft <= max_inst_hard.
In general, the compiler's automatic inliner only inlines calls whose called function's size is smaller than the value of max_inst_soft. In some cases a function may be inlined when its size is larger than the value of max_inst_soft but smaller than that of max_inst_hard. An example of this would be if the parameters passed into a function were constants.
When deciding whether to change the value of max_inst_hard or max_inst_soft for inlining one specific call site to a function, use -xinline_report=2 to report detailed inlining message and follow the suggestion in the inlining message.
max_function_inst[:n]
Allow functions to increase due to automatic inlining by up to n pseudo instructions (counted in compiler's internal representation).
max_growth[:n]
The automatic inliner is allowed to increase the size of the program by up to n% where the size is measured in pseudo instructions.
min_counter[:n]
The minimum call site frequency counter as measured by profiling feedback (-xprofile) in order to consider a function for automatic inlining.
This option is valid only when the application is compiled with profiling feedback (-xprofile=use).
level[:n]
Use this sub-option to control the degree of automatic inlining that is applied. The compiler will inline more functions with higher settings for -xinline_param=level.
n must be one of 1, 2, or 3.
The default value of n is 2 when this option is not specified, or when the options is specified without :n.
Specify the level of automatic inline:
level:1 basic inlining level:2 medium inlining (default) level:3 aggressive inlining
The level decides the specified values for the combination of the following inlining parameters:
max_growth + max_function_inst + max_inst + max_inst_call
When level = 1, all the parameters are half the values of the default.
When level = 2, all the parameters are the default value.
When level = 3, all the parameters are double the values of the default.
max_recursive_depth[:n]
When a function calls itself either directly or indirectly, it is said to be making a recursive call.
This sub-option allows a recursive call to be automatically inlined up to n levels.
max_recursive_inst[:n]
Specifies the maximum number of pseudo instructions (counted in compiler's internal representation) the caller of a recursive function can grow to by performing automatic recursive inlining.
When interactions between max_recursive_inst and max_recursive_depth occur, recursive function calls will be inlined until either the max_recursive_depth number of recursive calls, or until the size of the function being inlined into exceeds max_recursive_inst. The settings of these two parameters control the degree of inlining of small recursive functions.

If -xinline_param=default is specified, the compiler will set all the values of the sub-options to the default values.

If the option is not specified, the default is -xinline_param=default.

The list of values and options accumulate from left to right. So for a specification of -xinline_param=max_inst_hard:30,..,max_inst_hard:50, the value max_inst_hard:50 will be passed to the compiler.

If multiple -xinline_param options are specified on the command line, the list of sub-options likewise accumulate from left to right. For example, the effect of

 -xinline_param=max_inst_hard:50,min_counter:70 ...
   -xinline_param=max_growth:100,max_inst_hard:100

will be the same as that of

-xinline_param=max_inst_hard:100,min_counter:70,max_growth:100

A.2.137 –xinline_report[=n]

This option generates a report written to standard output on the inlining of functions by the compiler. The type of report depends on the value of n, which must be 0, 1, or 2.

0

No report is generated.

1

A summary report of default values of inlining parameters is generated.

2

A detailed report of inlining messages is generated, showing which callsites are inlined and which are not, with a short reason for not inlining a callsite. In some cases, this report will include suggested values for -xinline_param that can be used to inline a callsite that is not inlined.

When -xinline_report is not specified, the default value for n is 0. When -xinline_report is specified without =n, the default value is 1.

When -xlinkopt is present, the inlining messages about the callsites that are not inlined might not be accurate.

The report is limited to inlining performed by the compiler that is subject to the heuristics controllable by the -xinline_param option. Callsites inlined by the compiler for other reasons may not be reported.

A.2.138 –xinstrument=[no%]datarace

Specify this option to compile and instrument your program for analysis by the Thread Analyzer. For more information on the Thread Analyzer, see the tha(1) man page for details.

You can then use the Performance Analyzer to run the instrumented program with collect –r races to create a data-race-detection experiment. You can run the instrumented code stand-alone but it runs more slowly.

You can specify –xinstrument=no%datarace to turn off preparation of source code for the thread analyzer. This is the default.

You cannot specify –xinstrument without an argument.

If you compile and link in separate steps, you must specify –xinstrument=datarace in both the compilation and linking steps.

This option defines the preprocessor token __THA_NOTIFY. You can specify #ifdef __THA_NOTIFY to guard calls to libtha(3) routines.

This option also sets –g.

–xinstrument cannot be used together with –xlinkopt.

A.2.139 -xipo[={0|1|2}]

Performs interprocedural optimizations.

The -xipo option performs partial-program optimizations by invoking an interprocedural analysis pass. It performs optimizations across all object files in the link step, and the optimizations are not limited to just the source files on the compile command. However, whole-program optimizations performed with -xipo do not include assembly (.s) source files.

The -xipo option is particularly useful when compiling and linking large multifile applications. Object files compiled with this flag have analysis information compiled within them that enables interprocedural analysis across source and precompiled program files. However, analysis and optimization is limited to the object files compiled with -xipo, and does not extend to object files or libraries.

A.2.139.1 Values

The -xipo option can have the values listed in the following table.

Table 64  The -xipo Values
Value
Meaning
0
Do not perform interprocedural optimizations
1
Perform interprocedural optimizations
2
Perform interprocedural aliasing analysis as well as optimizations of memory allocation and layout to improve cache performance

A.2.139.2 Defaults

If -xipo is not specified, -xipo=0 is assumed.

If only -xipo is specified, -xipo=1 is assumed.

A.2.139.3 Examples

The following example compiles and links in the same step.

example% CC -xipo -xO4 -o prog  part1.cc part2.cc part3.cc

The optimizer performs crossfile inlining across all three source files in the final link step. The compilation of the source files need not all take place in a single compilation and could be accomplished over a number of separate compilations, each specifying the -xipo option.

The following example compiles and links in separate steps.

example% CC -xipo -xO4 -c part1.cc part2.cc
example% CC -xipo -xO4 -c part3.cc
example% CC -xipo -xO4 -o prog part1.o part2.o part3.o

The object files created in the compile steps have additional analysis information compiled within them to permit crossfile optimizations to take place at the link step.

A.2.139.4 When Not To Use -xipo Interprocedural Analysis

The compiler tries to perform whole-program analysis and optimizations as it works with the set of object files in the link step. The compiler makes the following two assumptions for any function or subroutine foo() defined in this set of object files:

  • foo() is not called explicitly by another routine that is defined outside this set of object files at runtime.

  • The calls to foo() from any routine in the set of object files are not interposed upon by a different version of foo() defined outside this set of object files.

Do not compile with -xipo=2, if the first assumption is not true for the given application.

Do not compile with either -xipo=1 or -xipo=2, if the second assumption is not true.

As an example, consider interposing on the function malloc() with your own version and compiling with -xipo=2. All the functions in any library that reference malloc() that are linked with your code have to be compiled with -xipo=2 also and their object files need to participate in the link step. Because this strategy might not be possible for system libraries, do not compile your version of malloc() with -xipo=2.

As another example, suppose that you build a shared library with two external calls, foo() and bar() inside two different source files. Furthermore, suppose that bar() calls foo(). If foo() could be interposed at runtime, do not compile the source file for foo() or for bar() with -xipo=1 or -xipo=2. Otherwise, foo() could be inlined into bar(), which could cause incorrect results.

A.2.139.5 Interactions

The -xipo option requires at least optimization level -xO4.

A.2.139.6 Warnings

When compiling and linking are performed in separate steps, -xipo must be specified in both steps to be effective.

Objects that are compiled without -xipo can be linked freely with objects that are compiled with -xipo.

Libraries do not participate in crossfile interprocedural analysis, even when they are compiled with -xipo, as shown in the following example.

example% CC -xipo -xO4 one.cc two.cc three.cc
example% CC -xar -o mylib.a one.o two.o three.o
...
example% CC -xipo -xO4 -o myprog main.cc four.cc mylib.a

In this example, interprocedural optimizations will be performed between one.cc, two.cc and three.cc, and between main.cc and four.cc, but not between main.cc or four.cc and the routines in mylib.a. (The first compilation may generate warnings about undefined symbols, but the interprocedural optimizations will be performed because it is a compile and link step.)

The -xipo option generates significantly larger object files due to the additional information needed to perform optimizations across files. However, this additional information does not become part of the final executable binary file. Any increase in the size of the executable program will be due to the additional optimizations performed.

If you have .o files compiled with the –xipo option from different compiler versions, mixing these files can result in failure with an error message about "IR version mismatch". When using the –xipo option, all the files should be compiled with the same version of the compiler.

A.2.139.7 See Also

-xjobs

A.2.140 -xipo_archive=[a]

The -xipo_archive option enables the compiler to optimize object files that are passed to the linker with object files that were compiled with -xipo and that reside in the archive library (.a) before producing an executable. Any object files contained in the library that were optimized during the compilation are replaced with their optimized version.

The following table lists possible values for a.

Table 65  -xipo_archive Flags
Value
Meaning
writeback
The compiler optimizes object files passed to the linker with object files compiled with -xipo that reside in the archive library (.a) before producing an executable. Any object files contained in the library that were optimized during the compilation are replaced with an optimized version.
For parallel links that use a common set of archive libraries, each link should create its own copy of archive libraries to be optimized before linking.
readonly
The compiler optimizes object files passed to the linker with object files compiled with -xipo that reside in the archive library (.a) before producing an executable.
The option –xipo_archive=readonly enables cross-module inlining and interprocedural data flow analysis of object files in an archive library specified at link time. However, it does not enable cross-module optimization of the archive library's code except for code that has been inserted into other modules by cross-module inlining.
To apply cross-module optimization to code within an archive library, –xipo_archive=writeback is required. Note that this setting modifies the contents of the archive library from which the code was extracted.
none
This is the default. There is no processing of archive files. The compiler does not apply cross-module inlining or other cross-module optimizations to object files compiled using –xipo and extracted from an archive library at link time. To do that, both –xipo and either –xipo_archive=readonly or –xipo_archive=writeback must be specified at link time.

If you do not specify a setting for -xipo_archive, the compiler sets it to -xipo_archive=none.

You cannot specify –xipo_archive without a flag.

A.2.141 -xipo_build=[yes|no]

Building -xipo without -xipo_build involves two passes through the compiler—once when producing the object files, and then again later at link time when performing the cross file optimization. Setting -xipo_build reduces compile time by avoiding optimizations during the initial pass and optimizing only at link time. Optimization is not needed for the object files, as with -xipo it will be performed at link time. If unoptimized object files built with -xipo_build are linked without including -xipo to perform optimization, the application will fail to link with an unresolved symbol error.

A.2.141.1 -xipo_build Examples

The following example performs a fast build of .o files, followed by crossfile optimization at link time:

% cc -O -xipo -xipo_build -o code1.o -c code1.c
% cc -O -xipo -xipo_build -o code2.o -c code2.c
% cc -O -xipo -o a.out code1.o code2.o

The -xipo_build will turn off -O when creating the .o files, to build these quickly. Full -O optimization will be performed at link time as part of -xipo crossfile optimization.

The following example links without using -xipo.

% cc -O -o a.out code1.o code2.o

If either code1.o or code2.o were generated with -xipo_build, the result will be a link-time failure indicating the symbol __unoptimized_object_file is unresolved.

When building .o files separately, the default behavior is -xipo_build=no. However, when the executable or library is built in a single pass from source files, -xipo_build will be implicitly enabled. For example:

% cc -fast -xipo a.c b.c c.c

will implicitly enable -xipo_build=yes for the first passes that generate a.o, b.o, and c.o. Include the option -xipo_build=no to disable this behavior.

A.2.142 -xivdep[=p]

Disable or set interpretation of #pragma ivdep pragmas (ignore vector dependencies).

The ivdep pragmas tell a compiler to ignore some or all loop-carried dependences on array references that it finds in a loop for purposes of optimization. This enables a compiler to perform various loop optimizations such as microvectorization, distribution, software pipelining, and so on, which would not be otherwise possible. It is used in cases where the user knows either that the dependences do not matter or that they never occur in practice.

The interpretation of #pragma ivdep directives depend upon the value of the —xivdep option.

The following list gives the values for p and their meaning.

loop

ignore assumed loop-carried vector dependences

loop_any

ignore all loop-carried vector dependences

back

ignore assumed backward loop-carried vector dependences

back_any

ignore all backward loop-carried vector dependences

none

do not ignore any dependences (disables ivdep pragmas)

These interpretations are provided for compatibility with other vendor's interpretations of the ivdep pragma.

A.2.143 -xjobs{=n|auto}

Compile with multiple processes. If this flag is not specified, the default behavior is -xjobs=auto.

Specify the -xjobs option to set how many processes the compiler creates to complete its work. This option can reduce the build time on a multi-cpu machine. Currently, -xjobs works only with the -xipo option. When you specify -xjobs=n, the interprocedural optimizer uses n as the maximum number of code generator instances it can invoke to compile different files.

Generally, a safe value for n is 1.5 multiplied by the number of available processors. Using a value that is many times the number of available processors can degrade performance because of context switching overheads among spawned jobs. Also, using a very high number can exhaust the limits of system resources such as swap space.

When -xjobs=auto is specified, the compiler will automatically choose the appropriate number of parallel jobs.

You must always specify -xjobs with a value. Otherwise, an error diagnostic is issued and compilation aborts.

If -xjobs is not specified, the default behavior is -xjobs=auto. This can be overridden by adding -xjobs=n to the command line. Multiple instances of -xjobs on the command line override each other until the right-most instance is reached.

A.2.143.1 -xjobs Examples

The following example links with up to three parallel processes for -xipo:

% cc -xipo -xO4 -xjobs=3 t1.o t2.o t3.o

The following example links serially with a single process for -xipo:

% cc -xipo -xO4 -xjobs=1 t1.o t2.o t3.o

The following example links in parallel, with the compiler choosing the number of jobs for -xipo:

% cc -xipo -xO4  t1.o t2.o t3.o

Note that this is exactly the same behavior as when explicitly specifying -xjobs=auto:

% cc -xipo -xO4 -xjobs=auto t1.o t2.o t3.o

A.2.144 -xkeep_unref[={[no%]funcs,[no%]vars}]

Keep definitions of unreferenced functions and variables. The no% prefix allows the compiler to potentially remove the definitions.

The default is no%funcs,no%vars. Specifying -xkeep_unref is equivalent to specifying -xkeep_unref=funcs,vars, meaning that -keep_unref keeps everything.

A.2.145 -xkeepframe[=[%all,%none,name,no%name]]

Prohibit stack related optimizations for the named functions (name).

%all

Prohibit stack related optimizations for all the code.

%none

Allow stack related optimizations for all the code.

This option is accumulative and can appear multiple times on the command line. For example, —xkeepframe=%all —xkeepframe=no%func1 indicates that the stack frame should be kept for all functions except func1. Also, —xkeepframe overrides —xregs=frameptr. For example, —xkeepframe=%all —xregs=frameptr indicates that the stack should be kept for all functions, but the optimizations for —xregs=frameptr would be ignored.

If not specified on the command line, the compiler assumes -xkeepframe=%none as the default. If specified but without a value, the compiler assumes -xkeepframe=%all

A.2.146 -xlang=language[,language]

Includes the appropriate runtime libraries and ensures the proper runtime environment for the specified language.

A.2.146.1 Values

language must be either f90, f95, or c99.

The f90 and f95 arguments are equivalent. The c99 argument invokes ISO 9899:1999 C programming language behavior for objects that were compiled with cc -std=c99 or cc -xc99=%all and are being linked with CC.

A.2.146.2 Interactions

The -xlang=f90 and -xlang=f95 options imply -library=f90. However, the -library=f90 option is not sufficient for mixed-language linking because only the -xlang option insures the proper runtime environment.

To determine which driver to use for mixed-language linking, use the following language hierarchy:

C++

Use the CC command.

Fortran 95 (or Fortran 90)

Use the f95 command. See the Oracle Developer Studio 12.6: Fortran User’s Guide for details.

C

Use the cc command. See the Oracle Developer Studio 12.6: C User’s Guide for details.

When linking Fortran 95, Fortran 77, and C++ object files together, use the driver of the highest language. For example, use the following C++ compiler command to link C++ and Fortran 95 object files:

example% CC -xlang=f95...

A.2.146.3 Warnings

Do not use -xnolib with -xlang.

If you are mixing parallel Fortran objects with C++ objects, the link line must specify the -mt flag.

A.2.146.4 See Also

-library, -staticlib

A.2.147 -xldscope={v}

Specify the -xldscope option to change the default linker scoping for the definition of extern symbols. Changing the default can result in faster and safer shared libraries and executables because the implementation are better hidden.

A.2.147.1 Values

The following table lists the possible values for v.

Table 66  The -xldscope Values
Value
Meaning
global
Global linker scoping is the least restrictive linker scoping. All references to the symbol bind to the definition in the first dynamic load module that defines the symbol. This linker scoping is the current linker scoping for extern symbols.
symbolic
Symbolic linker scoping is more restrictive than global linker scoping. All references to the symbol from within the dynamic load module being linked bind to the symbol defined within the module. Outside of the module, the symbol appears as though it is global. This linker scoping corresponds to the linker option -Bsymbolic. Although you cannot use -Bsymbolic with C++ libraries, you can use the -xldscope=symbolic without causing problems. See the ld(1) man page for more information on the linker.
hidden
Hidden linker scoping is more restrictive than symbolic and global linker scoping. All references within a dynamic load module bind to a definition within that module. The symbol will not be visible outside of the module.

A.2.147.2 Defaults

If you do not specify -xldscope, the compiler assumes -xldscope=global. If you specify -xldscope without any values, the compiler issues an error. Multiple instances of this option on the command line override each other until the right-most instance is reached.

A.2.147.3 Warning

If you intend to allow a client to override a function in a library, you must be sure that the function is not generated inline during the library build. The compiler inlines a function in the following situations:

  • The function name is specified with -xinline.

  • If you compile at -O or -xO3 or higher, in which case inlining is automatic.

  • If you use the inline specifier or cross-file optimization.

For example, suppose library ABC has a default allocator function that can be used by library clients, and is also used internally in the library:

void* ABC_allocator(size_t size) { return malloc(size); }

If you build the library at -xO4 or higher, the compiler inlines calls to ABC_allocator that occur in library components. If a library client wants to replace ABC_allocator with a customized version, the replacement will not occur in library components that called ABC_allocator. The final program will include different versions of the function.

Library functions declared with the __hidden or __symbolic specifiers can be generated inline when building the library. These specifiers are not supposed to be overridden by clients. See Linker Scoping.

Library functions declared with the __global specifier, should not be declared inline, and should be protected from inlining by use of the -xinline compiler option.

A.2.147.4 See Also

-xinline, -xO

A.2.148 -xlibmieee

Causes libm to return IEEE 754 values for math routines in exceptional cases.

The default behavior of libm is XPG-compliant.

A.2.148.1 See Also

Oracle Developer Studio 12.6: Numerical Computation Guide

A.2.149 -xlibmil

Inlines selected libm math library routines for optimization.


Note -  This option does not affect C++ inline functions.

This option selects inline templates for libm routines that produce the fastest executables for the floating-point option and platform currently being used.

A.2.149.1 Interactions

This option is implied by the –fast option.

See Also

-fast, Oracle Developer Studio 12.6: Numerical Computation Guide

A.2.150 –xlibmopt[={%none,archive,shared}]

Controls whether the compiler uses a library of optimized math routines or the standard system math routines. The possible argument values are:

%none

Do not link with the optimized math library. (This is the default when no -xlibmopt option is specified.)

archive

Link with the optimized math library in static archive form. (This is the default when -xlibmopt is specified with no argument.)

shared

(Oracle Solaris) Link with the optimized math library in shared object form.

The rightmost instance of this option on the command line overrides all the previous instances. The order of this option relative to other libraries specified on the command line is not significant.

The optimized math library includes selected math routines normally found in libm. The optimized routines typically run faster than their libm counterparts. The results may be slightly different from those produced by the libm routines, although in most cases they differ only in the least significant bit. When the static archive form of the optimized library is used, the compiler selects routines that are optimized for the instruction set indicated by the -xarch value specified when linking. When the shared object form is used, the most appropriate routines are selected at runtime based on the instruction set supported by the system being used.


Note -  The shared object form is available only on Oracle Solaris.

The routines in the optimized math library depend on the default round-to-nearest floating point rounding mode. If you use the optimized math library, you must ensure that round-to-nearest mode is in effect when any of these routines are called. These routines also do not modify errno. Do not link with the optimized math library if your program depends on math functions setting errno in response to error conditions.

A.2.150.1 Interactions

-xlibmopt=archive is implied by the –fast option. To disable linking with the optimized math library when –fast option is used, add xlibmopt=%none following the –fast option on the command line:

example% CC -fast -xlibmopt=%none...

A.2.150.2 See Also

-fast, -fround

A.2.151 -xlinkopt[=level]

(Oracle Solaris) Instructs the compiler to perform link-time optimization on the resulting executable or dynamic library over and above any optimizations in the object files. These optimizations are performed at link time by analyzing the object binary code. The object files are not rewritten but the resulting executable code may differ from the original object codes.

You must use -xlinkopt on at least some of the compilation commands for -xlinkopt to be useful at link time. The optimizer can still perform some limited optimizations on object binaries that are not compiled with -xlinkopt.

-xlinkopt optimizes code coming from static libraries that appear on the compiler command line, but does not optimize code coming from shared (dynamic) libraries that appear on the command line. You can also use -xlinkopt when you build shared libraries (compiling with -G or -shared).

A.2.151.1 Values

level sets the level of optimizations performed, and must be 0, 1, or 2. The optimization levels are listed in the following table.:

Table 67  The -xlinkopt Values
Value
Meaning
0
The link optimizer is disabled (the default).
1
Perform optimizations based on control flow analysis, including instruction cache coloring and branch optimizations, at link time.
2
Perform additional data flow analysis, including dead-code elimination and address computation simplification, at link time.

If you compile in separate steps, -xlinkopt must appear on both compile and link steps:

example% cc -c -xlinkopt a.c b.c
example% cc -o myprog -xlinkopt=2 a.o

Note that the level parameter is used only when the compiler is linking. In the example, the link optimizer level is 2 even though the object binaries are compiled with an implied level of 1.

A.2.151.2 Defaults

Specifying -xlinkopt without a level parameter implies -xlinkopt=1.

A.2.151.3 Interactions

The -xlinkopt option requires profile feedback (-xprofile) in order to optimize the program. Profiling reveals the most- and least-used parts of the code, which enables the optimizer to focus its effort accordingly. Link-time optimization is particularly important with large applications where optimal placement of code can substantially reduce instruction cache misses. Additionally, -xlinkopt is most effective when used to compile the whole program. Use this option as follows:

example% cc -o progt -xO5 -xprofile=collect:prog file.c
example% progt
example% cc -o prog -xO5 -xprofile=use:prog -xlinkopt file.c

–xlinkopt cannot be used together with –xinstrument.

For details on using profile feedback, see –xprofile=p.

A.2.151.4 Warnings

Do not use the -zcombreloc linker option when you compile with -xlinkopt.

Note that compiling with this option increases link time slightly. Object file sizes also increase, but the size of the executable remains the same. Compiling with -xlinkopt and -g increases the size of the executable by including debugging information.

A.2.152 -xloopinfo

This option shows which loops are parallelized and is normally for use with the –xautopar option.

A.2.153 –xM

Runs only the C++ preprocessor on the named C++ programs, requesting that the preprocessor generate makefile dependencies and send the result to the standard output. See the make(1) man page for details about make files and dependencies.

However, –xM only reports dependencies of the included headers and not the associated template definition files. You can use the .KEEP_STATE feature in your makefile to generate all the dependencies in the .make.state file which the make utility creates.

A.2.153.1 Examples

The following example:

#include <unistd.h>
void main(void)
{}

generates this output:

e.o: e.c
e.o: /usr/include/unistd.h
e.o: /usr/include/sys/types.h
e.o: /usr/include/sys/machtypes.h
e.o: /usr/include/sys/select.h
e.o: /usr/include/sys/time.h
e.o: /usr/include/sys/types.h
e.o: /usr/include/sys/time.h
e.o: /usr/include/sys/unistd.h

A.2.153.2 Interactions

If you specify -xM and -xMF, the compiler writes all makefile dependency information to the file specified with -xMF. This file is overwritten each time the preprocessor writes to it.

A.2.153.3 See Also

The make(1S) man page for details about makefiles and dependencies.

A.2.154 -xM1

Generates makefile dependencies like –xM except that it does not report dependencies for the /usr/include header files and it does not report dependencies for compiler-supplied header files.

If you specify -xM1 and -xMF, the compiler writes all makefile dependency information to the file specified with -xMF. This file is overwritten each time the preprocessor writes to it.

A.2.155 -xMD

Generates makefile dependencies like -xM but compilation continues. -xMD generates an output file for the makefile-dependency information derived from the -o output filename, if specified, or the input source filename, replacing (or adding) the filename suffix with .d. If you specify -xMD and -xMF, the preprocessor writes all makefile-dependency information to the file specified with -xMF. Compiling with -xMD -xMF or -xMD -o filename with more than one source file is not allowed and generates an error. The dependency file is overwritten if it already exists. When the source file is a .s file, the -xMD option will be ignored.

A.2.156 -xMF

Use this option to specify a file for the makefile-dependency output. You cannot specify individual filenames for multiple input files with -xMF on one command line. Compiling with -xMD -xMF or -xMMD -xMF with more than one source file is not allowed and generates an error. The dependency file is overwritten if it already exists.

This option cannot be used with -xM or -xM1.

A.2.157 -xMMD

Use this option to generate makefile dependencies excluding system header files. This option provides the same functionality as -xM1, but compilation continues. -xMMD generates an output file for the makefile-dependency information derived from the -o output filename, if specified, or the input source filename, replacing (or adding) the filename suffix with .d. If you specify -xMF, the compiler uses the filename you provide instead. Compiling with -xMMD -xMF or -xMMD -o filename with more than one source file is not allowed and generates an error. The dependency file is overwritten if it already exists. When the source file is a .s file, the -xMMD option will be ignored.

A.2.158 –xMerge

(SPARC) Merges the data segment with the text segment.

The data in the object file is read-only and is shared between processes unless you link with ld -N.

The three options -xMerge -ztext -xprofile=collect should not be used together. While -xMerge forces statically initialized data into read-only storage, -ztext prohibits position-dependent symbol relocations in read-only storage, and -xprofile=collect generates statically initialized, position-dependent symbol relocations in writable storage.

A.2.158.1 See Also

ld(1) man page

A.2.159 -xmaxopt[=v]

This option limits the level of pragma opt to the level specified. v is one of off, 1, 2, 3, 4, 5. The default value is -xmaxopt=off which causes pragma opt to be ignored. The default when specifying -xmaxopt without supplying an argument is -xmaxopt=5.

If you specify both -xO and -xmaxopt, the optimization level set with -xO must not exceed the -xmaxopt value.

A.2.160 -xmemalign=ab

(SPARC) Use the -xmemalign option to control the assumptions the compiler makes about the alignment of data. By controlling the code generated for potentially misaligned memory accesses and by controlling program behavior in the event of a misaligned access, you can more easily port your code to SPARC.

Specify the maximum assumed memory alignment and behavior of misaligned data accesses. You must provide a value for both a (alignment) and b (behavior). a specifies the maximum assumed memory alignment and b specifies the behavior for misaligned memory accesses.

For memory accesses where the alignment is determinable at compile time, the compiler generates the appropriate load/store instruction sequence for that alignment of data.

For memory accesses where the alignment cannot be determined at compile time, the compiler must assume an alignment to generate the needed load/store sequence.

If actual data alignment at runtime is less than the specified alignment, the misaligned access attempt (a memory read or write) generates a trap. The two possible responses to the trap are:

  • The OS converts the trap to a SIGBUS signal. If the program does not catch the signal, the program aborts. Even if the program catches the signal, the misaligned access attempt will not have succeeded.

  • The OS handles the trap by interpreting the misaligned access and returning control to the program as if the access had succeeded normally.

A.2.160.1 Values

The following lists the alignment and behavior values for -xmemalign

Values for a:

1

Assume at most 1–byte alignment.

2

Assume at most 2–byte alignment.

4

Assume at most 4–byte alignment.

8

Assume at most 8–byte alignment.

16

Assume at most 16–byte alignment.

Values for b:

i

Interpret access and continue execution.

s

Raise signal SIGBUS

f

Equivalent to specifying i when a=1, 2, or 4, and s when a=8 or 16

You must specify -xmemalign whenever you want to link to an object file that was compiled with the value of b set to either i or f. For a complete list of all compiler options that must be specified at both compile time and at link time, see Compile-Time and Link-Time Options.

A.2.160.2 Defaults

The following default values only apply when no -xmemalign option is present:

  • -xmemalign=8i for all 32–bit SPARC architectures (-m32)

  • -xmemalign=8s for all 64–bit SPARC architectures (-m64)

The following default value when the -xmemalign option is present but no value is given is:

  • -xmemalign=1i for all architectures.

A.2.160.3 Examples

The following shows how you can use -xmemalign to handle different alignment situations.

-xmemalign=1s

All memory accesses are misaligned so trap handling is too slow.

-xmemalign=8i

Occasional, intentional, misaligned accesses can occur in code that is otherwise correct.

-xmemalign=8s

No misaligned accesses occur in the program.

-xmemalign=2s

You want to check for possible odd-byte accesses.

-xmemalign=2i

You want to check for possible odd-byte access and you want the program to work.

A.2.161 -xmodel=[a]

(x86) The -xmodel option enables the compiler to modify the form of 64-bit objects for the x86 platforms and should be specified only for the compilation of such objects.

This option is invalid when specified with -m32.

The following table lists the possible values for a.

Table 68  The -xmodel Flags
Value
Meaning
small
This option generates code for the small model in which the virtual address of code executed is known at link time and all symbols are known to be located in the virtual addresses in the range from 0 to 2^31 - 2^24 - 1.
kernel
Generates code for the kernel model in which all symbols are defined to be in the range from 2^64 - 2^31 to 2^64 - 2^24.
medium
Generates code for the medium model in which no assumptions are made about the range of symbolic references to data sections. The size and address of the text section have the same limits as the small code model. Applications with large amounts of static data might require –xmodel=medium when compiling with –m64.

This option is not cumulative so the compiler sets the model value according to the right-most instance of -xmodel on the command-line.

If you do not specify -xmodel, the compiler assumes -xmodel=small. Specifying -xmodel without an argument is an error.

You do not need to compile all translation units with this option. You can compile select files as long as you ensure the object you are accessing is within reach.

Be aware that not all Linux system support the medium model.

A.2.162 –xnolib

Di sables linking with default system libraries .

Without this option, the C++ compiler links with several system support libraries to support C++ programs. With this option, the -llib options to link the default system support libraries are not passed to ld.

Normally, the compiler links with the system support libraries in the following order:

For -compat=5 on Oracle Solaris, the libraries are:

-lxxx -lCrun -lm -lc

where -lxxx is one of the following: Cstd, stlport, or stdcxx.

For -compat=5 on Linux, the libraries are:

-lxxx -lCrun -lm -lc

where -lxxx is one of the following: Cstd or stlport.

For -compat=g, -std=c++03, -std=c++11, and -std=c++14 on all platforms, the libraries are:

-lstdc++ -lgcc_s -lCrunG3 -lm -lc

On Oracle Solaris, -compat=5 -library=stdcxx4 is the default.

On Linux, -std=c++03 is the default.

On Linux, libCrunG3 is linked statically by default. When you specify system libraries, you can get the same default behaviour by using:

-lstdc++ -lgcc_s -Bstatic -lCrunG3 -Bdynamic -lm -lc

The order of the -l options is significant. The -lm option must appear before -lc.

To determine which system support libraries will be linked by default, compile with the -dryrun option. For example, the output from the following command on Oracle Solaris:

example% CC foo.cc -m64 -dryrun

shows the following in the output:

-lstdcxx4 -lCrun -lm -lc

A.2.162.1 Examples

For minimal compilation to meet the C application binary interface (that is, a C++ program with only C support required), use the following command:

example% CC -xnolib test.cc –lc

A.2.162.2 Interactions

If you specify –xnolib, you must manually link all required system support libraries in the given order. You must link the system support libraries last.

If –xnolib is specified, -library is ignored.

libstatomic and libatomic are affected by the –xnolib option, You can explicitly link libstatomic by either –xatomic=studio or –latomic and explicitly link libatomic by –xatomic=gcc.

A.2.162.3 Warnings

Many C++ language features require the use of libCrun (–compat=5 mode) or libCrunG3 (g++ compatibilty modes).

This set of system support libraries is not stable and might change from release to release.

Many C++ language features require the use of the Oracle Developer Studio C++ library libstatomic or system library libatomic (–std=c++03|c++11|c++14 mode).

A.2.162.4 See Also

–llib, –library=l[,l...], –staticlib=l[,l...], -xatomic=a

A.2.163 –xnolibmil

Cancels –xlibmil on the command line.

Use this option with –fast to override linking with the optimized math library.

A.2.164 –xnolibmopt

(Obsolete) Use -xlibmopt=%none instead. See –xlibmopt[={%none,archive,shared}].

A.2.165 –xnorunpath

Same as –norunpath

A.2.166 -xOlevel

Specifies optimization level; note the uppercase letter O followed by the digit 1, 2, 3, 4, or 5. In general, program execution speed depends on the level of optimization. The higher the level of optimization, the better the runtime performance. However, higher optimization levels can result in increased compilation time and larger executable files.

In a few cases, –xO2 might perform better than the others, and –xO3 might outperform –xO4. Try compiling with each level to see if you have one of these rare cases.

If the optimizer runs out of memory, it tries to recover by retrying the current procedure at a lower level of optimization. The optimizer resumes subsequent procedures at the original level specified in the -xOlevel option.

The following sections describe how the five -xOlevel optimization levels operate on the SPARC platform and the x86 platform.

A.2.166.1 Values

On the SPARC Platform:

  • –xO1 does only the minimum amount of optimization (peephole), which is post-pass, assembly-level optimization. Do not use -xO1 unless using -xO2 or -xO3 results in excessive compilation time, or you are running out of swap space.

  • –xO2 does basic local and global optimization, which includes:

    • Induction-variable elimination

    • Local and global common-subexpression elimination

    • Algebraic simplification

    • Copy propagation

    • Constant propagation

    • Loop-invariant optimization

    • Register allocation

    • Basic block merging

    • Tail recursion elimination

    • Dead-code elimination

    • Tail-call elimination

    • Complicated expression expansion

      This level does not optimize references or definitions for external or indirect variables.

    –xO3, in addition to optimizations performed at the –xO2 level, also optimizes references and definitions for external variables. This level does not trace the effects of pointer assignments. When compiling either device drivers that are not properly protected by volatile or programs that modify external variables from within signal handlers, use -xO2. In general, this level results in increased code size unless combined with the -xspace option.

    Performs automatic inlining of functions whose body is smaller than the overhead of calling the function. To control which functions are inlined, see -xinline=list.

  • –xO4 does automatic inlining of functions contained in the same file in addition to performing –xO3 optimizations. This automatic inlining usually improves execution speed but sometimes makes it worse. In general, this level results in increased code size unless combined with the -xspace option.

  • –xO5 generates the highest level of optimization. It is suitable only for the small fraction of a program that uses the largest fraction of computer time. This level uses optimization algorithms that take more compilation time or that do not have as high a certainty of improving execution time. Optimization at this level is more likely to improve performance if it is done with profile feedback. See –xprofile=p.

On the x86 Platform:

  • –xO1 does basic optimization. This includes algebraic simplification, register allocation, basic block merging, dead code and store elimination, and peephole optimization.

  • –xO2 performs local common subexpression elimination, local copy and constant propagation, and tail recursion elimination, as well as the optimization done by level 1.

  • –xO3 performs global common subexpression elimination, global copy and constant propagation, loop strength reduction, induction variable elimination, and loop-variant optimization, as well as the optimization done by level 2.

    Performs automatic inlining of functions whose body is smaller than the overhead of calling the function. To control which functions are inlined, see -xinline=list.

  • –xO4 does automatic inlining of functions contained in the same file as well as the optimization done by level 3. This automatic inlining usually improves execution speed but sometimes makes it worse. This level also frees the frame pointer registration (ebp) for general purpose use. In general, this level results in increased code size.

  • –xO5 generates the highest level of optimization. It uses optimization algorithms that take more compilation time or that do not have as high a certainty of improving execution time.

A.2.166.2 Interactions

If you use -g or -g0 and the optimization level is -xO3 or lower, the compiler provides best-effort symbolic information with almost full optimization.

If you use -g or -g0 and the optimization level is -xO4 or higher, the compiler provides best-effort symbolic information with full optimization.

Debugging with -g does not suppress –xOlevel, but –xOlevel limits –g in certain ways. For example, the –xOlevel options reduce the utility of debugging so that you cannot display variables from dbx, but you can still use the dbx where command to get a symbolic traceback. For more information, see Debugging a Program With dbx.

The -xipo option is effective only if it is used with -xO4 or -xO5.

The -xinline option has no effect for optimization levels below -xO3. At -xO4, the optimizer decides which functions should be inlined, and does so regardless of whether you specify the -xinline option. At -xO4, the compiler also attempts to determine which functions will improve performance if they are inlined. If you force the inlining of a function with -xinline, you might actually diminish performance.

A.2.166.3 Defaults

The default is no optimization. However, this is only possible if you do not specify an optimization level. If you specify an optimization level, there is no option for turning optimization off.

If you are trying to avoid setting an optimization level, be sure not to specify any option that implies an optimization level. For example, -fast is a macro option that sets optimization at -xO5. All other options that imply an optimization level issue a warning message that optimization has been set. The only way to compile without any optimization is to delete all options from the command line or make file that specify an optimization level.

A.2.166.4 Warnings

If you optimize at –xO3 or –xO4 with very large procedures (thousands of lines of code in a single procedure), the optimizer might require an unreasonable amount of memory. In such cases, machine performance can be degraded.

To prevent this degradation from taking place, use the limit command to limit the amount of virtual memory available to a single process. See the csh(1) man page. For example, to limit virtual memory to 4 gigabytes:

example% limit datasize 4G

This command causes the optimizer to try to recover if it reaches 4 gigabytes of data space.

The limit cannot be greater than the total available swap space of the machine, and should be small enough to permit normal use of the machine while a large compilation is in progress.

The best setting for data size depends on the degree of optimization requested, the amount of real memory, and virtual memory available.

To find the actual swap space, type swap– l

To find the actual real memory, type dmesg | grep mem

A.2.166.5 See Also

-xldscope –fast, –xprofile=p, csh(1) man page

A.2.167 -xopenmp[={parallel|noopt|none}]

Enable explicit parallelization with OpenMP directives.

A.2.167.1 Values

The following table details the -xopenmp values:

Table 69  -xopenmp Values
Values
Meaning
parallel
Enables recognition of OpenMP pragmas. The optimization level under -xopenmp=parallel is -xO3. The compiler raises the optimization to -xO3 if necessary and issues a warning.
This flag also defines the preprocessor macro _OPENMP. The _OPENMP macro is defined to have the decimal value yyyymm where yyyy and mm are the year and month designations of the version of the OpenMP API that the implementation supports. Refer to the Oracle Developer Studio 12.6: OpenMP API User’s Guide for the value of the _OPENMP macro for a particular release.
noopt
Enables recognition of OpenMP pragmas. The compiler does not raise the optimization level if it is lower than –O3.
If you explicitly set the optimization lower than –O3, as in CC -O2 -xopenmp=noopt, the compiler issues an error. If you do not specify an optimization level with -xopenmp=noopt, the OpenMP pragmas are recognized, the program is parallelized accordingly, but no optimization is done.
This flag also defines the preprocessor macro _OPENMP.
none
Does not enable recognition of OpenMP pragmas, makes no change to the optimization level of your program, and does not define any preprocessor macros. This is the default when -xopenmp is not specified.

A.2.167.2 Defaults

If you specify -xopenmp but do not specify a value, the compiler assumes -xopenmp=parallel. If you do not specify -xopenmp at all, the compiler assumes -xopenmp=none.

A.2.167.3 Interactions

If you are debugging an OpenMP program with dbx, compile with -g -xopenmp=noopt so you can breakpoint within parallel regions and display the contents of variables.

Use the OMP_NUM_THREADS environment variable to specify the number of threads to use when running an OpenMP program. If OMP_NUM_THREADS is not set, the default number of threads used is a multiple of the number of cores per socket (that is, cores per processor chip), which is less than or equal to the total number of cores or 32, whichever is less. You can specify a different number of threads by setting the OMP_NUM_THREADS environment variable, or by calling the omp_set_num_threads() OpenMP runtime routine, or by using the num_threads clause on the parallel region directive. For best performance, the number of threads used to execute a parallel region should not exceed the number of hardware threads (or virtual processors) available on the machine. On Oracle Solaris systems, this number can be determined by using the psrinfo(1M) command. On Linux systems, this number can be determined by inspecting the file /proc/cpuinfo. See the Oracle Developer Studio 12.6: OpenMP API User’s Guide for more information

Nested parallelism is disabled by default. To enable nested parallelism, you must set the OMP_NESTED environment variable to TRUE. See the Oracle Developer Studio 12.6: OpenMP API User’s Guide for details.

A.2.167.4 Warnings

The default for -xopenmp might change in a future release. You can avoid warning messages by explicitly specifying an appropriate optimization level.

If you compile and link in separate steps, specify -xopenmp in both the compilation step and the link step. When used with the link step, the -xopenmp option will link with the OpenMP runtime support library, libmtsk.so.

For up-to-date functionality and performance, make sure that the latest patch of the OpenMP runtime library, libmtsk.so, is installed on the system.

A.2.167.5 See Also

For more information about the OpenMP Fortran 95, C, and C++ application program interface (API) for building multithreaded applications, see the Oracle Developer Studio 12.6: OpenMP API User’s Guide.

A.2.168 -xpagesize=n

Sets the preferred page size for the stack and the heap.

A.2.168.1 Values

The following values are valid for SPARC: 4k, 8K, 64K, 512K, 2M, 4M, 32M, 256M, 2G, 16G, or default.

The following values are valid on x86/x64: 4K, 2M. 4M, 1G, or default.

You must specify a valid page size for the target platform. If you do not specify a valid page size, the request is silently ignored at runtime.

Use the pagesize(1) Oracle Solaris command to determine the number of bytes in a page. The operating system offers no guarantee that the page size request will be honored. However, appropriate segment alignment can be used to increase the likelihood of obtaining the requested page size. See the -xsegment_align option on how to set the segment alignment. You can use pmap(1) or meminfo(2) to determine page size of the target platform.


Note -  Compiling with this option has the same effect as setting the LD_PRELOAD environment variable to mpss.so.1 with the equivalent options, or running the Oracle Solaris command ppgsz(1) with the equivalent options before running the program. See the Oracle Solaris man pages for details.

Note -  The libhugetlbfs library is required for –xpagesize to work on Linux. See the Linux libhugetlbfs(7) man page for more information.

A.2.168.2 Defaults

If you specify -xpagesize=default, the Oracle Solaris operating system sets the page size.

A.2.168.3 Expansions

This option is a macro for -xpagesize_heap and -xpagesize_stack. These two options accept the same arguments as -xpagesize: 4k, 8K, 64K, 512K, 2M, 4M, 32M, 256M, 2G, 16G, or default. You can set them both with the same value by specifying -xpagesize or you can specify them individually with different values.

A.2.168.4 Warnings

The -xpagesize option has no effect unless you use it at compile time and at link time. See Compile-Time and Link-Time Options for a complete list of options that must be specified at both compile time and link time.

A.2.169 -xpagesize_heap=n

Set the page size in memory for the heap.

A.2.169.1 Values

n can be 4k, 8K, 64K, 512K, 2M, 4M, 32M, 256M, 2G, 16G, or default. You must specify a valid page size for the target platform. If you do not specify a valid page size, the request is silently ignored at runtime.

Use the getpagesize(3C) command on the Oracle Solaris operating system to determine the number of bytes in a page. The Oracle Solaris operating system offers no guarantee that the page size request will be honored. You can use pmap(1) or meminfo(2) to determine the page size of the target platform.


Note -  Compiling with this option has the same effect as setting the LD_PRELOAD environment variable to mpss.so.1 with the equivalent options, or running the Oracle Solaris command ppgsz(1) with the equivalent options before running the program. See the Oracle Solaris man pages for details.

A.2.169.2 Defaults

If you specify -xpagesize_heap=default, the Oracle Solaris operating system sets the page size.

A.2.169.3 Warnings

The -xpagesize_heap option has no effect unless you use it at compile time and at link time.

A.2.170 -xpagesize_stack=n

Set the page size in memory for the stack.

A.2.170.1 Values

n can be 4k, 8K, 64K, 512K, 2M, 4M, 32M, 256M, 2G, 16G, or default. You must specify a valid page size for the target platform. If you do not specify a valid page size, the request is silently ignored at runtime.

Use the getpagesize(3C) command on the Oracle Solaris operating system to determine the number of bytes in a page. The Oracle Solaris operating system offers no guarantee that the page size request will be honored. You can use pmap(1) or meminfo(2) to determine the page size of the target platform.


Note -  Compiling with this option has the same effect as setting the LD_PRELOAD environment variable to mpss.so.1 with the equivalent options, or running the Oracle Solaris command ppgsz(1) with the equivalent options before running the program. See the Oracle Solaris man pages for details.

A.2.170.2 Defaults

If you specify -xpagesize_stack=default, the Oracle Solaris operating system sets the page size.

A.2.170.3 Warnings

The -xpagesize_stack option has no effect unless you use it at compile time and at link time.

A.2.171 -xpatchpadding[={fix|patch|size}]

Reserve an area of memory before the start of each function. If fix is specified, the compiler will reserve the amount of space required by fix and continue. This is the first default. If either patch or no value is specified, the compiler will reserve a platform-specific default value. A value of -xpatchpadding=0 will reserve 0 bytes of space. The maximum value for size on x86 is 127 bytes and on SPARC is 2048 bytes.

A.2.172 -xpch=v

This compiler option activates the precompiled-header feature. The precompiled-header feature might reduce compile time for applications whose source files share a common set of include files containing a large amount of source code. The compiler collects information about a sequence of header files from one source file, and then uses that information when recompiling that source file, and when compiling other source files that have the same sequence of headers. The information that the compiler collects is stored in a precompiled-header file. You can take advantage of this feature through the -xpch and -xpchstop options in combination with the #pragma hdrstop directive.

A.2.172.1 Creating a Precompiled-Header File

When you specify -xpch=v, v can be collect:pch-filename or use:pch-filename. The first time you use -xpch, you must specify the collect mode. The compilation command that specifies -xpch=collect must only specify one source file. In the following example, the -xpch option creates a precompiled-header file called myheader.Cpch based on the source file a.cc:

CC -xpch=collect:myheader a.cc

A valid precompiled-header filename always has the suffix .Cpch. When you specify pch-filename, you can add the suffix or let the compiler add it for you. For example, if you specify cc -xpch=collect:foo a.cc, the precompiled-header file is called foo.Cpch.

When you create a precompiled-header file, pick a source file that contains the common sequence of include files across all the source files with which the precompiled-header file is to be used. The common sequence of include files must be identical across these source files. Remember, only one source filename value is legal in collect mode. For example, CC -xpch=collect:foo bar.cc is valid, whereas CC -xpch=collect:foo bar.cc foobar.cc is invalid because it specifies two source files.

Using a Precompiled-Header File

Specify -xpch=use:pch-filename to use a precompiled-header file. You can specify any number of source files with the same sequence of include files as the source file that was used to create the precompiled-header file. For example, your command in use mode could look like this: CC -xpch=use:foo.Cpch foo.c bar.cc foobar.cc.

You should only use an existing precompiled-header file if the following situations are true. If any are not true, you should recreate the precompiled-header file:

  • The compiler that you are using to access the precompiled-header file is the same as the compiler that created the precompiled-header file. A precompiled-header file created by one version of the compiler might not be usable by another version of the compiler, including differences caused by installed patches.

  • Except for the -xpch option, the compiler options you specify with -xpch=use must match the options that were specified when the precompiled-header file was created.

  • The set of included headers you specify with -xpch=use is identical to the set of headers that were specified when the precompile header was created.

  • The contents of the included headers that you specify with -xpch=use is identical to the contents of the included headers that were specified when the precompiled header was created.

  • The current directory (that is, the directory in which the compilation is occurring and attempting to use a given precompiled-header file) is the same as the directory in which the precompiled-header file was created.

  • The initial sequence of preprocessing directives, including #include directives, in the file you specified with -xpch=collect are the same as the sequence of preprocessing directives in the files you specify with -xpch=use.

In order to share a precompiled-header file across multiple source files, those source files must share a common set of include files as their initial sequence of tokens. This initial sequence of tokens is known as the viable prefix. The viable prefix must be interpreted consistently across all the source files that use the same precompiled-header file.

The viable prefix of a source file can only be comprised of comments and any of the following preprocessor directives:

#include
#if/ifdef/ifndef/else/elif/endif
#define/undef
#ident (if identical, passed through as is)
#pragma (if identical)

Any of these directives may reference macros. The #else, #elif, and #endif directives must match within the viable prefix.

Within the viable prefix of each file that shares a precompiled-header file, each corresponding #define and #undef directive must reference the same symbol. In the case of #define, each one must reference the same value. Their order of appearance within each viable prefix must be the same as well. Each corresponding pragma must also be the same and appear in the same order across all the files sharing a precompiled header.

A header file that is incorporated into a precompiled-header file must not violate the following constraints. The results of compiling a program that violates any of these constraints is undefined.

  • The header file must not contain function and variable definitions.

  • The header file must not use __DATE__ and __TIME__. Use of these preprocessor macros can generate unpredictable results.

  • The header file must not contain #pragma hdrstop.

  • The header file must not use __LINE__ and __FILE__ in the viable prefix. You can use __LINE__ and __FILE__ in included headers.

How to Modify Makefiles

This section describes possible approaches to modifying your makefiles in order to incorporate -xpch into your builds.

  • You can use the implicit make rules by using an auxiliary CCFLAGS variable and the KEEP_STATE facility of both make and dmake. The precompiled header is produced as a separate independent step.

.KEEP_STATE:
CCFLAGS_AUX = -O etc
CCFLAGS = -xpch=use:shared $(CCFLAGS_AUX)
shared.Cpch: foo.cc
     $(CCC) -xpch=collect:shared $(CCFLAGS_AUX) foo.cc
a.out: foo.o ping.o pong.o
     $(CCC) foo.o ping.o pong.o

You can also define your own compilation rule instead of trying to use an auxiliary CCFLAGS.

.KEEP_STATE:
.SUFFIXES: .o .cc
%.o:%.cc shared.Cpch
        $(CCC) -xpch=use:shared $(CCFLAGS) -c $<
shared.Cpch: foo.cc
        $(CCC) -xpch=collect:shared $(CCFLAGS) foo.cc -xe
a.out: foo.o ping.o pong.o
        $(CCC) foo.o ping.o pong.o
  • You can produce the precompiled header as a side effect of regular compilation and without using KEEP_STATE, but this approach requires explicit compilation commands.

shared.Cpch + foo.o: foo.cc bar.h
        $(CCC) -xpch=collect:shared foo.cc $(CCFLAGS) -c
ping.o: ping.cc shared.Cpch bar.h
        $(CCC) -xpch=use:shared ping.cc $(CCFLAGS) -c
pong.o: pong.cc shared.Cpch bar.h
        $(CCC) -xpch=use:shared pong.cc $(CCFLAGS) -c
a.out: foo.o ping.o pong.o
        $(CCC) foo.o ping.o pong.o

A.2.172.2 See Also

A.2.173 -xpchstop=file

Use the -xpchstop=file option to specify the last include file to be considered in creating the precompiled header file with the -xpch option. Using -xpchstop on the command line is equivalent to placing a hdrstop pragma after the first include-directive that references file in each of the source files that you specify with the cc command.

In the following example, the -xpchstop option specifies that the viable prefix for the precompiled header file ends with the include of projectheader.h. Therefore, privateheader.h is not a part of the viable prefix.

example% cat a.cc
     #include <stdio.h>
     #include <strings.h>
     #include "projectheader.h"
     #include "privateheader.h"
     .
     .
     .
example% CC -xpch=collect:foo.Cpch a.cc -xpchstop=projectheader.h -c

A.2.173.1 See Also

-xpch, pragma hdrstop

A.2.174 -xpec[={yes|no}]

(Oracle Solaris) Generates a Portable Executable Code (PEC) binary. This option puts the program intermediate representations in the object file and the binary. This binary may be used later for tuning and troubleshooting.

A binary that is built with –xpecis usually five to ten times larger than if it is built without –xpec.

If you do not specify –xpec, the compiler sets it to –xpec=no. If you specify –xpec, but do not supply a flag, the compiler sets it to –xpec=yes.

A.2.175 –xpg

Compiles for profiling with the gprof profiler.

The-xpg option compiles self-profiling code to collect data for profiling with gprof. This option invokes a runtime recording mechanism that produces a gmon.out file when the program normally terminates.


Note -  -xprofile does not benefit if you specify -xpg. The two do not prepare or use data provided by the other.

Profiles are generated by using prof(1) or gprof(1) on 64–bit Oracle Solaris platforms or just gprof on 32–bit Oracle Solaris platforms and include approximate user CPU times. These times are derived from PC sample data for routines in the main executable and routines in shared libraries specified as linker arguments when the executable is linked. Other shared libraries (libraries opened after process startup using dlopen(3C)) are not profiled.

On 32–bit Oracle Solaris systems, profiles generated using prof(1) are limited to routines in the executable. 32–bit shared libraries can be profiled by linking the executable with -xpg and using gprof(1).

On x86 systems, -xpg is incompatible with -xregs=frameptr, and these two options should not be used together. Note also that -xregs=frameptr is included in -fast.

The Oracle Solaris 10 software does not include system libraries compiled with -p. As a result, profiles collected on Oracle Solaris 10 platforms do not include call counts for system library routines.

A.2.175.1 Warnings

If you compile and link separately and you compile with –xpg, be sure to link with –xpg. See Compile-Time and Link-Time Options for a complete list of options that must be specified at both compile time and link time.

Binaries compiled with -xpg for gprof profiling should not be used with binopt(1), as they are incompatible and can result in internal errors.

A.2.175.2 See Also

–xprofile=p, the analyzer(1) man page, and the Performance Analyzer manual

A.2.176 -xport64[=(v)]

Use this option to help you debug code you are porting to a 64-bit environment. Specifically, this option warns against problems such as truncation of types (including pointers), sign extension, and changes to bit-packing that are common when code is ported from a 32-bit architecture such as V8 to a 64-bit architecture such as V9.

This option has no effect unless you are also compiling in 64–bit mode, —m64.

A.2.176.1 Values

The following table lists the valid values for v.

Table 70  -xport64 Values
Values
Meaning
no
Generate no warnings related to the porting of code from a 32–bit environment to a 64–bit environment.
implicit
Generate warning only for implicit conversions. Do not generate warnings when an explicit cast is present.
full
Generate all warnings related to the porting of code from a 32–bit environment to a 64–bit environment. This includes warnings for truncation of 64-bit values, sign-extension to 64 bits under ISO value-preserving rules, and changes to the packing of bitfields.

A.2.176.2 Defaults

If you do not specify -xport64, the default is -xport64=no. If you specify -xport64 but do not specify a flag, the default is -xport64=full.

A.2.176.3 Examples

This section provides examples of code that can cause truncation of type, sign extension, and changes to bit-packing.

Checking for the Truncation of 64-bit Values

When you port to a 64-bit architecture such as SPARC V9, your data may be truncated. The truncation could happen implicitly, by assignment, at initialization, or by an explicit cast. The difference of two pointers is the typedef ptrdiff_t, which is a 32-bit integer type in 32-bit mode, and a 64-bit integer type in 64-bit mode. The truncation of a long to a smaller size integral type generates a warning as in the following example.

example% cat test1.c
int x[10];

int diff = &x[10] - &x[5]; //warn

example% CC -c -m64 -Qoption ccfe -xport64=full test1.c
"test1.c", line 3: Warning: Conversion of 64-bit type value to "int" causes truncation.
1 Warning(s) detected.
example%

Use -xport64=implicit to disable truncation warnings in 64–bit compilation mode when an explicit cast is the cause of data truncation.

example% CC -c -m64 -Qoption ccfe -xport64=implicit test1.c
"test1.c", line 3: Warning: Conversion of 64-bit type value to "int" causes truncation.
1 Warning(s) detected.
example%

Another common issue that arises from porting to a 64-bit architecture is the truncation of a pointer. This is always an error in C++. An operation such as casting a pointer to an int which causes such a truncation results in an error diagnostic in 64–bit SPARC architectures when you specify -xport64.

example% cat test2.c
char* p;
int main() {
  p =(char*) (((unsigned int)p) & 0xFF); // -m64 error
  return 0;
}
example% CC -c -m64 -Qoption ccfe -xport64=full test2.c
"test2.c", line 3: Error: Cannot cast from char* to unsigned.
1 Error(s) detected.
example%
Checking for Sign Extension

You can also use the -xport64 option to check for situations in which the normal ISO C value-preserving rules allow for the extension of the sign of a signed-integral value in an expression of unsigned-integral type. Such sign extensions can cause subtle run-time bugs.

example% cat test3.c
int i= -1;
void promo(unsigned long l) {}

int main() {
    unsigned long l;
    l = i;  // warn
    promo(i);       // warn
}
example% CC -c -m64 -Qoption ccfe -xport64=full test3.c
"test3.c", line 6: Warning: Sign extension from "int" to 64-bit integer.
"test3.c", line 7: Warning: Sign extension from "int" to 64-bit integer.
2 Warning(s) detected.
Checking for Changes to the Packing of Bitfields

Use -xport64 to generate warnings against long bitfields. In the presence of such bitfields, packing of the bitfields might drastically change. Any program which relies on assumptions regarding the way bitfields are packed needs to be reviewed before a successful port can take place to a 64-bit architecture.

example% cat test4.c
#include <stdio.h>

union U {
   struct S {
       unsigned long b1:20;
       unsigned long b2:20;
   } s;

   long buf[2];
} u;

int main() {
   u.s.b1 = 0XFFFFF;
   u.s.b2 = 0XFFFFF;
   printf(" u.buf[0] = %lx u.buf[1] = %lx\n", u.buf[0], u.buf[1]);
   return 0;
}
example%

Output on 64–bit SPARC systems (-m64):

example% u.buf[0] = ffffffffff000000 u.buf[1] = 0

A.2.176.4 Warnings

Note that warnings are generated only when you compile in 64-bit mode using -m64.

A.2.176.5 See Also

–m32|–m64

A.2.177 -xprefetch[=a[,a...]]

Enable prefetch instructions on those architectures that support prefetch.

Explicit prefetching should only be used under special circumstances that are supported by measurements.

The following table lists the possible values of a.

Table 71  -xprefetch Values
Value
Meaning
auto
Enable automatic generation of prefetch instructions.
no%auto
Disable automatic generation of prefetch instructions.
explicit
Enable explicit prefetch macros.
no%explicit
Disable explicit prefetch macros.
latx:factor
(SPARC) Adjust the compiler’s assumed prefetch-to-load and prefetch-to-store latencies by the specified factor. You can combine this flag only with -xprefetch=auto. The factor must be a positive floating-point or integer number.
yes
Obsolete, do not use. Use -xprefetch=auto,explicit instead.
no
Obsolete, do not use. Use -xprefetch=no%auto,no%explicit instead.

With -xprefetch and -xprefetch=auto the compiler is free to insert prefetch instructions into the code it generates. This may result in a performance improvement on architectures that support prefetch.

If you are running computationally intensive codes on large multiprocessors, using -xprefetch=latx:factor could improve performance. This option instructs the code generator to adjust the default latency time between a prefetch and its associated load or store by the specified factor.

The prefetch latency is the hardware delay between the execution of a prefetch instruction and the time the data being prefetched is available in the cache. The compiler assumes a prefetch latency value when determining how far apart to place a prefetch instruction and the load or store instruction that uses the prefetched data.


Note -  The assumed latency between a prefetch and a load may not be the same as the assumed latency between a prefetch and a store.

The compiler tunes the prefetch mechanism for optimal performance across a wide range of machines and applications. This tuning may not always be optimal. For memory-intensive applications, especially applications intended to run on large multiprocessors, you may be able to obtain better performance by increasing the prefetch latency values. To increase the values, use a factor that is greater than 1 (one). A value between .5 and 2.0 will most likely provide the maximum performance.

For applications with data sets that reside entirely within the external cache, you may be able to obtain better performance by decreasing the prefetch latency values. To decrease the values, use a factor that is less than 1 (one).

To use the -xprefetch=latx:factor option, start with a factor value near 1.0 and run performance tests against the application. Then increase or decrease the factor, as appropriate, and run the performance tests again. Continue adjusting the factor and running the performance tests until you achieve optimum performance. When you increase or decrease the factor in small steps, you will see no performance difference for a few steps, then a sudden difference, then it will level off again.

A.2.177.1 Defaults

The default is -xprefetch=auto,explicit. This default adversely affects applications that have essentially non-linear memory access patterns. Specify -xprefetch=no%auto,no%explicit to override the default.

The default of auto is assumed unless explicitly overridden with an argument of no%auto or an argument of no. For example, -xprefetch=explicit is the same as -xprefetch=explicit,auto.

The default of explicit is assumed unless explicitly overridden with an argument of no%explicit or an argument of no. For example, -xprefetch=auto is the same as -xprefetch=auto,explicit.

If only -xprefetch is specified, -xprefetch=auto,explicit is assumed.

If automatic prefetching is enabled, but a latency factor is not specified, then -xprefetch=latx:1.0 is assumed.

A.2.177.2 Interactions

This option accumulates instead of overrides.

The sun_prefetch.h header file provides the macros for specifying explicit prefetch instructions. The prefetches will be approximately at the place in the executable that corresponds to where the macros appear.

To use the explicit prefetch instructions, you must be on the correct architecture, include sun_prefetch.h, and either exclude -xprefetch from the compiler command or use -xprefetch, -xprefetch=auto,explicit or -xprefetch=explicit.

If you call the macros and include the sun_prefetch.h header file but specify -xprefetch=no%explicit, the explicit prefetches will not appear in your executable.

The use of latx:factor is valid only when automatic prefetching is enabled. latx:factor is ignored unless you use it in conjunction with -xprefetch=auto,latx:factor.

A.2.177.3 Warnings

Explicit prefetching should be used only under special circumstances that are supported by measurements.

Because the compiler tunes the prefetch mechanism for optimal performance across a wide range of machines and applications, you should use -xprefetch=latx:factor only when the performance tests indicate there is a clear benefit. The assumed prefetch latencies might change from release to release. Therefore, retesting the effect of the latency factor on performance whenever switching to a different release is highly recommended.

A.2.178 -xprefetch_auto_type=a

Where a is [no%]indirect_array_access.

Use this option to determine whether the compiler generates indirect prefetches for the loops indicated by the option -xprefetch_level in the same fashion the prefetches for direct memory accesses are generated.

If you do not specify a setting for -xprefetch_auto_type, the compiler sets it to -xprefetch_auto_type=no%indirect_array_access.

Options such as -xdepend, -xrestrict, and -xalias_level can affect the aggressiveness of computing the indirect prefetch candidates and therefore the aggressiveness of the automatic indirect prefetch insertion due to better memory alias disambiguation information.

A.2.179 -xprefetch_level[=i]

Use the -xprefetch_level=i option to control the aggressiveness of the automatic insertion of prefetch instructions as determined with -xprefetch=auto. The compiler becomes more aggressive, or, in other words, introduces more prefetches, with each higher level of -xprefetch_level.

The appropriate value for -xprefetch_level depends on the number of cache misses your application has. Higher -xprefetch_level values have the potential to improve the performance of applications with a high number of cache misses.

A.2.179.1 Values

i must be one of 1, 2, or 3, as shown in the following table.

Table 72  -xprefetch_level Values
Value
Meaning
1
Enables automatic generation of prefetch instructions.
2
Targets additional loops beyond those targeted at -xprefetch_level=1 for prefetch insertion. Additional prefetches could be inserted beyond those at -xprefetch_level=1.
3
Targets additional loops beyond those targeted at -xprefetch_level=2 for prefetch insertion. Additional prefetches could be inserted beyond those at -xprefetch_level=2.

A.2.179.2 Defaults

The default is -xprefetch_level=1 when you specify -xprefetch=auto.

A.2.179.3 Interactions

This option is effective only when it is compiled with -xprefetch=auto, with optimization level 3 or greater (-xO3), and on 64–bit platforms that support prefetch (-m64).

A.2.180 -xprevise={yes|no}

Compile with this option to produce a static analysis of the source code that can be viewed using the Code Analyzer.

When compiling with -xprevise=yes and linking in a separate step, include -xprevise=yes also on the link step.

The default is -xprevise=no.

On Linux, -xprevise=yes needs to be specified along with -xannotate.

See the Oracle Developer Studio Code Analyzer documentation for further information.

A.2.181 –xprofile=p

Collects data for a profile or uses a profile to optimize.

p must be collect[:profdir], use[:profdir], or tcov[:profdir].

This option causes execution frequency data to be collected and saved during execution, then the data can be used in subsequent runs to improve performance. Profile collection is safe for multithreaded applications. Profiling a program that does its own multitasking ( -mt ) produces accurate results. This option is only valid when you specify -xO2 or greater level of optimization. If compilation and linking are performed in separate steps, the same -xprofile option must appear on the link step as well as the compile step.

collect[:profdir]

Collects and saves execution frequency for later use by the optimizer with -xprofile=use. The compiler generates code to measure statement execution-frequency.

-xMerge, -ztext, and -xprofile=collect should not be used together. While -xMerge forces statically initialized data into read-only storage, -ztext prohibits position-dependent symbol relocations in read-only storage, and -xprofile=collect generates statically initialized, position-dependent symbol relocations in writable storage.

The profile directory name profdir, if specified, is the pathname of the directory where profile data are to be stored when a program or shared library containing the profiled object code is executed. If the profdir pathname is not absolute, it is interpreted relative to the current working directory when the program is compiled with the option -xprofile=use:profdir.

If no profile directory name is specified with —xprofile=collect:prof_dir or —xprofile=tcov:prof_dir, profile data are stored at run time in a directory named program.profile where program is the basename of the profiled process's main program. In this case, the environment variables SUN_PROFDATA and SUN_PROFDATA_DIR can be used to control where the profile data are stored at run time. If set, the profile data are written to the directory given by $SUN_PROFDATA_DIR/$SUN_PROFDATA. If a profile directory name is specified at compilation time, SUN_PROFDATA_DIR and SUN_PROFDATA have no effect at run time. These environment variables similarly control the path and names of the profile data files written by tcov, as described in the tcov(1) man page.

If these environment variables are not set, the profile data is written to the directory profdir.profile in the current directory, where profdir is the name of the executable or the name specified in the -xprofile=collect:profdir flag. -xprofile does not append .profile to profdir if profdir already ends in .profile. If you run the program several times, the execution frequency data accumulates in the profdir.profile directory; that is output from prior executions is not lost.

If you are compiling and linking in separate steps, make sure that any object files compiled with -xprofile=collect are also linked with -xprofile=collect.

The following example collects and uses profile data in the directory myprof.profile located in the same directory where the program is built:

demo: CC -xprofile=collect:myprof.profile -xO5 prog.cc -o prog  
demo: ./prog        
demo: CC -xprofile=use:myprof.profile -xO5 prog.cc -o prog

The following example collects profile data in the directory /bench/myprof.profile and later uses the collected profile data in a feedback compilation at optimization level -xO5:

demo: CC -xprofile=collect:/bench/myprof.profile
\    -xO5 prog.cc -o prog  
...run prog from multiple locations..
demo: CC -xprofile=use:/bench/myprof.profile 
\    -xO5 prog.cc -o prog
use[:profdir]

Uses execution frequency data collected from code compiled with —xprofile=collect[:profdir] or —xprofile=tcov[:profdir] to optimize for the work performed when the profiled code was executed. profdir is the pathname of a directory containing profile data collected by running a program that was compiled with —xprofile=collect[:profdir] or —xprofile=tcov[:profdir].

To generate data that can be used by both tcov and —xprofile=use[:profdir], a profile directory must be specified at compilation time, using the option —xprofile=tcov[:profdir]. The same profile directory must be specified in both —xprofile=tcov:profdir and —xprofile=use:profdir. To minimize confusion, specify profdir as an absolute pathname.

The profdir pathname is optional. If profdir is not specified, the name of the executable binary is used. a.out is used if -o is not specified. The compiler looks for profdir.profile/feedback, or a.out.profile/feedback when profdir is not specified. For example:

demo: CC -xprofile=collect -o myexe prog.cc  
demo: CC -xprofile=use:myexe -xO5 -o myexe	prog.cc

The program is optimized by using the execution frequency data previously generated and saved in the feedback files written by a previous execution of the program compiled with -xprofile=collect.

Except for the -xprofile option, the source files and other compiler options must be exactly the same as those used for the compilation that created the compiled program that generated the feedback file. The same version of the compiler must be used for both the collect build and the use build as well.

If compiled with -xprofile=collect:profdir, the same profile directory name profdir must be used in the optimizing compilation: -xprofile=use:profdir.

See also -xprofile_ircache for speeding up compilation between collect and use phases.

tcov[:profdir]

Instrument object files for basic block coverage analysis using tcov(1).

If the optional profdir argument is specified, the compiler will create a profile directory at the specified location The data stored in the profile directory can be used either by tcov(1) or by the compiler with -xprofile=use:profdir. If the optional profdir pathname is omitted, a profile directory will be created when the profiled program is executed. The data stored in the profile directory can only be used by tcov(1). The location of the profile directory can be controlled using environment variables SUN_PROFDATA and SUN_PROFDATA_DIR.

If the location specified by profdir is not an absolute pathname, it is interpreted at compilation time relative to the current working directory at the time of compilation. If profdir is specified for any object file, the same location must be specified for all object files in the same program. The directory whose location is specified by profdir must be accessible from all machines where the profiled program is to be executed. The profile directory should not be deleted until its contents are no longer needed, because data stored there by the compiler cannot be restored except by recompilation.

If object files for one or more programs are compiled with -xprofile=tcov:/test/profdata, a directory named /test/profdata.profile will be created by the compiler and used to store data describing the profiled object files. The same directory will also be used at execution time to store execution data associated with the profiled object files.

If a program named myprog is compiled with -xprofile=tcov and executed in the directory /home/joe, the directory /home/joe/myprog.profile will be created at runtime and used to store runtime profile data.

A.2.182 -xprofile_ircache[=path]

(SPARC) Use -xprofile_ircache[=path] with -xprofile=collect|use to improve compilation time during the use phase by reusing compilation data saved from the collect phase.

With large programs, compilation time in the use phase can improve significantly because the intermediate data is saved. Note that the saved data could increase disk space requirements considerably.

When you use -xprofile_ircache[=path], path overrides the location where the cached files are saved. By default, these files are saved in the same directory as the object file. Specifying a path is useful when the collect and use phases happen in two different directories. The following example shows a typical sequence of commands:

example% CC -xO5 -xprofile=collect -xprofile_ircache t1.cc t2.cc
example% a.out    // run collects feedback data
example% CC -xO5 -xprofile=use -xprofile_ircache t1.cc t2.cc

A.2.183 -xprofile_pathmap

(SPARC) Use the -xprofile_pathmap=collect-prefix:use-prefix option when you are also specifying the -xprofile=use command. Use -xprofile_pathmap when both of the following conditions are true and the compiler is unable to find profile data for an object file that is compiled with -xprofile=use.

  • You are compiling the object file with -xprofile=use in a directory that is different from the directory in which the object file was previously compiled with -xprofile=collect.

  • Your object files share a common basename in the profile but are distinguished from each other by their location in different directories.

The collect-prefix is the prefix of the UNIX path name of a directory tree in which object files were compiled using -xprofile=collect.

The use-prefix is the prefix of the UNIX path name of a directory tree in which object files are to be compiled using -xprofile=use.

If you specify multiple instances of -xprofile_pathmap, the compiler processes them in the order of their occurrence. Each use-prefix specified by an instance of -xprofile_pathmap is compared with the object file path name until either a matching use-prefix is identified or the last specified use-prefix is found not to match the object file path name.

A.2.184 -xreduction

Analyzes loops for reduction in automatic parallelization. This option is valid only if –xautopar is also specified. Otherwise the compiler issues a warning.

When a reduction recognition is enabled, the compiler parallelizes reductions such as dot products and maximum and minimum finding. These reductions yield roundoffs different from those obtained by unparallelized code.

A.2.185 –xregs=r[,r...]

Specifies the usage of registers for the generated code.

r is a comma-separated list that consists of one or more of the following sub-options: appl, float,frameptr.

Prefixing a sub-option with no% disables that sub-option. For example: -xregs=appl,no%float

Note that —xregs sub-options are restricted to specific hardware platforms.

Table 73  -xregs Sub-options
Value
Meaning
appl
(SPARC) Allow the compiler to generate code using the application registers as scratch registers. The application registers are:
g2, g3, g4 (on 32–bit platforms)
g2, g3 (on 64–bit platforms)
All system software and libraries should be compiled using -xregs=no%appl. System software (including shared libraries) must preserve these registers’ values for the application. Their use is intended to be controlled by the compilation system and must be consistent throughout the application.
In the SPARC ABI, these registers are described as application registers. Using these registers can improve performance because fewer load and store instructions are needed. However, such use can conflict with some old library programs written in assembly code.
float
(SPARC) Allow the compiler to generate code by using the floating-point registers as scratch registers for integer values. Use of floating-point values may use these registers regardless of this option. If you want your code to be free of all references to floating-point registers, use -xregs=no%float and also make sure your code does not in any way use floating-point types.
(x86) Allow the compiler to generate code by using the floating-point registers as scratch registers. Floating-point values may use these registers regardless of this option. To generate binary code free of all references to floating point registers, use -xregs=no%float and make sure your source code does not in any way use floating point types. During code generation the compilers will attempt to diagnose code that results in the use of floating point, simd, or x87 instructions.
frameptr
(x86) Allow the compiler to use the frame-pointer register (%ebp on IA32, %rbp on AMD64) as a general-purpose register.
The default is -xregs=no%frameptr
The C++ compiler ignores —xregs=frameptr unless exceptions are also disabled with —features=no%except. Note that —xregs=frameptr is part of —fast but is ignored by the C++ compiler unless —features=no%except is also specified.
With -xregs=framptr the compiler is free to use the frame-pointer register to improve program performance. However, some features of the debugger and performance measurement tools may be limited as a result. Stack tracing, debuggers, and performance analyzers cannot report on functions compiled with -xregs=frameptr
Also, C++ calls to POSIX pthread_cancel() will fail to find cleanup handers.
Mixed C, Fortran, and C++ code should not be compiled with -xregs=frameptr if a C++ function called directly or indirectly from a C or Fortran function can throw an exception. If compiling such mixed source code with -fast, add -xregs=no%frameptr after the -fast option on the command line.
With more available registers on 64–bit platforms, compiling with -xregs=frameptr has a better chance of improving 32–bit code performance than 64–bit code.
The compiler ignores -xregs=frameptr and issues a warning if you also specify -xpg. Also, -xkeepframe overrides -xregs=frameptr.

The SPARC default is -xregs=appl,float.

The x86 default is -xregs=no%frameptr,float.

On x86 systems, -xpg is incompatible with -xregs=frameptr, and these two options should not be used together. Note also that -xregs=frameptr is included in -fast.

Code intended for shared libraries that will link with applications should be compiled with -xregs=no%appl,float. At the very least, the shared library should explicitly document how it uses the application registers so that applications linking with those libraries are aware of these register assignments.

For example, an application using the registers in some global sense (such as using a register to point to some critical data structure) would need to know exactly how a library with code compiled without -xregs=no%appl is using the application registers in order to safely link with that library.

A.2.186 –xrestrict[=f]

Treats pointer-valued function parameters as restricted pointers. In addition to pointers, references can also be declared restricted, with the same meaning.

f must be one of the values listed in the following table:

Table 74  -xrestrict Values
Value
Meaning
%all
All pointer parameters in the entire file are treated as restricted.
%none
No pointer parameters in the file are treated as restricted.
%source
Only functions defined within the main source file are restricted. Functions defined within included files are not restricted.
f1[,f2...]
A comma-separated list of one or more function names. If you specify a function list, the compiler treats pointer parameters in the specified functions as restricted; Refer to the following section, Restricted Pointers, for more information.
Each listed name must be the mangled name (if applicable) of the function. For example:
extern "C++" int foo(int* __restrict a, int* __restrict b) { ... }
extern "C"   int bar(int* __restrict a, int* __restrict b) { ... }
Because function bar is declared extern "C", its name is not mangled. The command line option –xrestict=foo,bar causes function bar's pointer parameters to be treated as restricted, but not those of function foo. You would need to use the mangled name of foo, which depends on the compilation mode.

This command-line option can be used on its own, but it is best used with optimization.

For example, the following command treats all pointer parameters in the file prog.c as restricted pointers.

%CC -xO3 -xrestrict=%all prog.cc

The following command treats all pointer parameters in the function agc in the file prog.c as restricted pointers:

%CC -xO3 -xrestrict=agc prog.cc

The C99 standard for the C programming language introduced the restrict keyword, but the keyword is not part of the current C++ standard. Like some other compilers, Oracle Developer Studio C++ recognizes the keywords __restrict (and __restrict__) as equivalent to the C99 restrict keyword. Use of the keyword is generally preferable to the –xrestrict command-line option, because the keyword allows finer control over which pointers are declared restricted.

Declaring a pointer restricted (using the command-line option or a keyword) primarily affects optimization opportunities, and limits the arguments that can be passed to a function.

The default is %none; specifying -xrestrict is equivalent to specifying -xrestrict=%source.

A.2.186.1 Restricted Pointers

In order for a compiler to effectively perform parallel execution of a loop, it needs to determine if certain lvalues designate distinct regions of storage. Aliases are lvalues whose regions of storage are not distinct. Determining if two pointers to objects are aliases is a difficult and time consuming process because it could require analysis of the entire program. Consider the function vsq() in the following example:

extern "C"
void vsq(int n, double *a, double *b) {
    int i;
    for (i=0; i<n; i++) {
            b[i] = a[i] * a[i];
    }
}

The compiler can parallelize the execution of the different iterations of the loops if it knows that pointers a and b access different objects. If there is an overlap in objects accessed through pointers a and b then it would be unsafe for the compiler to execute the loops in parallel.

At compile time, the compiler does not know if the objects accessed by a and b overlap by simply analyzing the function vsq(). The compiler may need to analyze the whole program to get this information. You can specify that pointer-valued function parameters be treated as restricted pointers by using the following command line option: -xrestrict[=func1,...,funcn] If a function list is specified, pointer parameters in the specified functions are treated as restricted. Otherwise, all pointer parameters in the entire source file are treated as restricted (not recommended). For example, -xrestrict=vsq qualifies the pointers a and b given in the example of the function vsq().

Declaring the pointer arguments as restricted states that the pointers designate distinct objects. The compiler can assume that a and b point to distinct regions of storage. With this alias information, the compiler is able to parallelize the loop.

Make sure you use -xrestrict correctly. If pointers qualified as restricted pointers point to objects that are not distinct, the compiler can incorrectly parallelize loops resulting in undefined behavior. For example, assume that pointers a and b of function vsq() point to objects that overlap such that b[i] and a[i+1] are the same object. If a and b are not declared as restricted pointers the loops will be executed serially. If a and b are incorrectly qualified as restricted pointers, the compiler might parallelize the execution of the loops, which is not safe because b[i+1] should only be computed after b[i] is computed.

A.2.187 –xs[={yes|no}]

(Oracle Solaris) Link debug information from object files into executable.

-xs is the same as -xs=yes.

The default is -xs=yes.

This option controls the trade-off of executable size versus the need to retain object files in order to debug. Use -xs=no to keep the executable small but depend on the object files. This option has almost no effect on dbx performance or the runtime per formance of the program.

When the compile command forces linking (that is, -c is not specified) there will be no object file(s) and the debug information must be placed in the executable. In this case, -xs=no (implicit or explicit) will be ignored.

The feature is implemented by having the compiler adjust the section flags and/or section names in the object file that it emits, which then tells the linker what to do for that object file's debug information. It is therefore a compiler option, not a linker option. It is possible to have an executable with some object files compiled -xs=yes and others compiled -xs=no.

Linux compilers accept but ignore -xs. Oracle Linux compilers do not accept -xs={yes|no}.

A.2.188 –xsafe=mem

(SPARC) Allows the compiler to assume that no memory protection violations occur.

This option allows the compiler to use the non-faulting load instruction in the SPARC V9 architecture.

A.2.188.1 Interactions

This option takes effect only when used with optimization level –xO5 and one of the following –xarch values: sparc, sparcvis, sparcvis2, or sparcvis3 for both –m32 and –m64.

A.2.188.2 Warnings

Because non-faulting loads do not cause a trap when a fault such as address misalignment or segmentation violation occurs, you should use this option only for programs in which such faults cannot occur. Because few programs incur memory-based traps, you can safely use this option for most programs. Do not use this option for programs that explicitly depend on memory-based traps to handle exceptional conditions.

A.2.189 –xsecure_code_analysis{=[yes|no]}

Enable or disable compiler secure code analysis to find and display possible memory safety violations at compile time. Secure code analysis runs in parallel with the compilation process and may result in increased compile time.

If –xsecure_code_analysis is not specified or if it is specified without a yes|no argument, the default is –xsecure_code_analysis=yes.

Use –xsecure_code_analysis=no to disable secure code analysis.

A.2.190 –xsegment_align=n

(Oracle Solaris) This option causes the driver to include a special mapfile on the link line. The mapfile aligns the text, data, and bss segments to the value specified by n. When using very large pages, it is important that the heap and stack segments are aligned on an appropriate boundary. If these segments are not aligned, small pages will be used up to the next boundary, which could cause a performance degradation. The mapfile ensures that the segments are aligned on an appropriate boundary.

The n value must be one of the following:

(SPARC) The following values are valid: 8K, 64K, 512K, 2M, 4M, 32M, 256M, 1G, and none.

(x86) The following values are valid: 4K, 8K, 64K, 512K, 2M, 4M, 32M, 256M, 1G, and none.

The default for both SPARC and x86 is none.

Recommended usage is as follows:

SPARC 32-bit compilation: -xsegment_align=64K
SPARC 64-bit compilation: -xsegment_align=4M

x86 32-bit compilation: -xsegment_align=8K
x86 64-bit compilation: -xsegment_align=4M

The driver will include the appropriate mapfile. For example, if the user specifies -xsegment_align=4M, the driver adds -M install-directory/lib/compilers/mapfiles/map.4M.align to the link line, where install-directory is the installation directory. The aforementioned segments will then be aligned on a 4M boundary.

A.2.191 –xspace

(SPARC) Does not allow optimizations that increase code size.

A.2.192 –xtarget=t

Specifies the target platform for instruction set and optimization .

The value of t must be one of the following: native, generic, or system-name.

Each specific value for -xtarget expands into a specific set of values for the -xarch, -xchip, and -xcache options. Use the -xdryrun option to determine the expansion of -xtarget=native on a running system.

For example, –xtarget=T3 is equivalent to –xchip=T3 –xcache=8/16/4:6144/64/24 –xarch=sparcvis3.

 
cc -dryrun -xtarget=T3 |& grep ###
###     command line files and options (expanded):
### -dryrun -xchip=T3 -xcache=8/16/4:6144/64/24 -xarch=sparcvis3

The data type model, either 32-bit or 64-bit, is indicated by the –m32|–m64 option. To specify the 64-bit data type model, specify the –m64 option as follows:

-xtarget=<value> ... -m64

To specify the 32-bit data type model, use the –m32 option as follows:

-xtarget=<value> ... -m32

See also the –m32|–m64 option for a discussion of the default data type model.