NAME
cc - C compiler
SYNOPSIS
cc [-#] [-###] [-Aname[(tokens)]] [-B[static|dynamic]]
[-C] [-c] [-Dname[(arg[,arg])][=expansion]] [-d[y|n]]
[-dalign] [-E] [-errfmt[=[no%]error]] [-errhdr[=h]]
[-erroff[=t[,t...]]] [-errshort[=i]] [-errtags=a]
[-errwarn[=t[,t...]]] [-fast] [-fd] [-features=[a]]
[-flags] [-flteval[={any|2}]] [-fma[={none|fused}]]
[-fnonstd] [-fns=[no|yes]] [-fprecision=p] [-fround=r]
[-fsimple[=n]] [-fsingle] [-fstore] [-ftrap[=t[,t...]]]
[-G] [-g] [-H] [-hname] [-I[-|dir]] [-i] [-KPIC]
[-Kpic] [-keeptmp] [-Ldir] [-lname] [-m32|-m64] [-mc]
[-misalign] [-misalign2] [-mr[,string]] [-mt] [-native]
[-nofstore] [-O] [-On] [-ofilename] [-P] [-p] [-Q[y|n]]
[-qp] [-Rdir[:dir...]] [-S] [-s] [-Uname] [-V] [-v]
[-Wc,arg] [-w] [-X[c|a|t|s]] [-x386] [-x486] [-xa]
[-xalias_level[=a]] [-xarch=a] [-xautopar]
[-xbinopt={a}] [-xbuiltin[=a]] [-xCC] [-xc99[=o]]
[-xcache=c] [-xcg{89|92}] [-xchar[=o]]
[-xchar_byte_order[=o]] [-xcheck=n] [-xchip=c]
[-xcode=v] [-xcrossfile[=n]] [-xcsi]
[-xdebugformat=[stabs|dwarf]] [-xdepend[={yes|no}]]
[-xdryrun] [-xe] [-xexplicitpar] [-xF[=v]] [-xhelp=f]
[-xhwcprof[={enable|disable}]] [-xinline=[v[,v...]]]
[-xinstrument=[no%]datarace] [-xipo[=n]]
[-xipo_archive[=a]] [-xjobs=n] [-xldscope=[v]] [-xlib-
mieee] [-xlibmil] [-xlibmopt] [-xlic_lib=sunperf]
[-xlicinfo] [-xlinkopt[=level]] [-xloopinfo] [-xM]
[-xM1] [-xMerge] [-xmaxopt[=v]] [-xmemalign=ab]
[-xmodel=[a]] [-xnolib] [-xnolibmil] [-xnolibmopt]
[-xnorunpath] [-xOn] [-xopenmp[=i]] [-xP]
[-xpagesize=n] [-xpagesize_heap=n] [-xpagesize_stack=n]
[-xparallel] [-xpch=v] [-xpchstop] [-xpentium] [-xpg]
[-xprefetch[=val[,val]]] [-xprefetch_auto_type=[a]
[-xprefetch_level=l] [-xprofile=p]
[-xprofile_ircache[=path]]
[-xprofile_pathmap=collect_prefix:use_prefix] [-xreduc-
tion] [-xregs=r[,r...]] [-xrestrict[=f]] [-xs]
[-xsafe=mem] [-xsb] [-xsbfast] [-xsfpconst] [-xspace]
[-xstrconst] [-xtarget=t] [-xtemp=dir] [-xthreadvar[=o]
[-xtime] [-xtransition] [-xtrigraphs[=[yes|no]]
[-xunroll=n] [-xustr={ascii_utf16_ushort|no}]
[-xvector[=a]] [-xvis] [-xvpara] [-Yc,dir] [-YA,dir]
[-YI,dir] [-YP,dir] [-YS,dir] [-Zll]
DESCRIPTION
Sun Studio 12: C 5.9 compiler
A man page, by definition, is a quick reference. For more
detailed information on the C compiler and its options, see
the C User's Guide.
See the online readme file, viewable by calling
cc -xhelp=readme
for the latest important information on platforms, environ-
ments, new features, and software corrections.
Access all the installed documentation, including readme
files, user guides, and reference manuals by pointing an
HTML browser to the default installation directory:
file:/opt/SUNWspro/docs/index.html
Note- If your Sun compilers and tools are not installed in
the default /opt directory, ask your system administrator
for the equivalent path on your system.
COMPILING FOR 64-BIT PLATFORMS:
The way to specify compilation of a 32-bit or 64-bit binary
has changed in this release. The -xarch option no longer
carries an implicit memory model, 32-bit ILP32 or 64-bit
LP64, with each definition, and is now used only to specify
the instruction set of the target processor.
Use the new -m32 and -m64 options to specify the memory
model of the target compilation.
The ILP32 model specifies that C-language int, long, and
pointer data types are all 32-bits wide. The LP64 model
specifies that long and pointer data types are all 64-bits
wide. The Solaris and Linux OS also support large files and
large arrays under the LP64 memory model.
When compiling with -m64, the resulting executable will work
only on 64-bit UltraSPARC(R) or x86 processors under Solaris
OS or Linux OS running a 64-bit kernel. Compilation, link-
ing, and execution of 64-bit objects can only take place in
a Solaris or Linux OS that supports 64-bit execution.
SPECIAL x86 NOTES
There are some important issues to be aware of when compil-
ing for x86 Solaris platforms.
The legacy Sun-style parallelization pragmas are not avail-
able on x86. Use OpenMP instead. See the OpenMP API User's
Guide for information on converting legacy parallelization
directives to OpenMP.
Programs compiled with -xarch set to sse, sse2, sse2a, or
sse3 must be run only on platforms that provide these
extensions and features.
OS releases starting with Solaris 9 4/04 are SSE/SSE2-
enabled on Pentium 4-compatible platforms. Earlier versions
of Solaris OS are not SSE/SSE2-enabled. If an instruction
set selected by -xarch is not enabled in the running Solaris
OS, the compiler will not be able to generate or link code
for that instruction set.
If you compile and link in separate steps, always link using
the compiler and with same -xarch setting to ensure that the
correct startup routine is linked.
Numerical results on x86 might differ from results on SPARC
due to the x86 80-bit floating-point registers. To minimize
these differences, use the -fstore option or compile with
-xarch=sse2 if the hardware supports SSE2.
Numerical results can also differ between Solaris and Linux
because the intrinsic math libraries (for example, sin(x))
are not the same.
Binary Compatibility Verification
Starting with Sun Studio 11 and the Solaris 10 OS, program
binaries compiled and built using these specialized -xarch
hardware flags are verified that they are being run on the
appropriate platform.
On systems prior to Solaris 10, no verification is done and
it is the user's responsibility to ensure objects built
using these flags are deployed on suitable hardware.
Running programs compiled with these -xarch options on plat-
forms that are not enabled with the appropriate features or
instruction set extensions could result in segmentation
faults or incorrect results occurring without any explicit
warning messages.
This warning extends also to programs that employ .il inline
assembly language functions or __asm() assembler code that
utilize SSE, SSE2, SSE2a, and SSE3 instructions and exten-
sions.
New Sun Studio 12 Features
This section describes the new and changed features intro-
duced in the Sun Studio 12: C 5.9 compiler. See the Sun Stu-
dio 12 C User's Guide for more detailed descriptions of the
new features.
o The C compiler is now available on the following
Linux distributions(x86 and x64):
o SuSE Linux Enterprise Server 9 with Service Pack 3
(or later).
o Red Hat Enterprise Linux 4.
o Other Linux distributions based on the 2.6 kernel
though these are not officially supported.
o Use -m64 to create 64-bit executables and shared
libraries.
o New flags for -xarch replace obsolete flags.
o New values for -xtarget and -xchip provide code gen-
eration for the UltraSPARC T2 and SPARC64vi proces-
sors.
o New flag -fma=fused to enable generation of fused
multiply-add instructions on processors that support
them.
o Explicit prefetch macros accepted on x86 platforms as
well as SPARC platforms. (-xprefetch=explicit)
Overview of the C Compiler
The cc (1) manual page describes the ISO C compiler options
that are SVID compliant under Solaris 9 and Solaris 10
operating environments. Take note that the C compiler recog-
nizes by default some of the constructs of the 1999 ISO/IEC
C standard. Specifically, the supported are detailed in the
C User's Guide. Use the -xc99=none command if you want to
limit the compiler to the 1990 ISO/IEC C standard.
cc is the interface to the C compilation system. The compi-
lation process incorporates a preprocessor, compiler, code
generator, optimizer, assembler, and link editor. cc
processes the supplied options and then executes the various
components with the proper arguments. cc accepts several
types of files as arguments.
Files with .c suffix are taken to be C source files and may
be preprocessed, compiled, optimized, instrumented for pro-
filing, assembled, and link edited. Although the preproces-
sor can be used as a macro processor, this is not recom-
mended, as its output is geared toward that which would be
acceptable as input to a valid C compiler. The compilation
process may be stopped after the completion of any pass if
the appropriate options are supplied.
If the compilation process runs through the assembler, then
an object file is produced in the current working directory
with .o suffix substituted for .c. However, the .o file is
normally deleted if a single C file is compiled and then
immediately link edited.
Files with .s suffix are taken to be assembly source files;
they may be assembled and link edited. Such files are passed
to the preprocessor (/usr/ccs/lib/cpp on Solaris), and then
to the assembler.
Files with an .i are taken to be preprocessed C source
files, and may be compiled, optimized, instrumented for pro-
filing, assembled, and link edited. Files whose names do not
end in .c, .s, .S or .i are passed to the link editor, which
produces a dynamically linked executable whose name by
default is a.out.
See option -Yc, dir to change the default directories used
for finding libraries. dir is a colon-separated path list.
The default library search order for Solaris SPARC is as
follows:
/opt/SUNWspro/prod/lib/sparc
/opt/SUNWspro/prod/lib
/usr/ccs/lib
/lib
/usr/lib
The default library search order for Solaris x86 is as fol-
lows:
/opt/SUNWspro/prod/lib
/usr/ccs/lib
/lib
/usr/lib
The default library search order for Linus is as follows:
/opt/sun/sunstudio12/prod/lib
/lib
/usr/lib
OPTIONS
All platform-specific options are silently accepted on all
platforms. Any exceptions to this rule are noted under the
specific option.
The following options are interpreted by cc:
-# Turns on verbose mode, showing how command options
expand. Shows each component as it is invoked.
-### Shows each component as it would be invoked, but does
not actually execute it. Also shows how command options
would expand.
-Aname[(tokens)]
Associate name as a predicate with the specified tokens
as if by a #assert preprocessing directive.
Preassertions:system(unix)
machine(sparc) (SPARC)
machine(i386) (x86)
cpu(sparc) (SPARC)
cpu(i386) (x86)
The above are not predefined in -Xc mode.
If -A is followed by a dash (-) only, it causes all
predefined macros (other than those that begin with __)
and predefined assertions to be forgotten.
-B [static|dynamic]
Specifies whether bindings of libraries for linking are
static or dynamic, indicating whether libraries are
non-shared or shared, respectively. -B dynamic causes
the link editor to look for files named libx.so and
then for files named libx.a when given the -lx option.
-B static causes the link editor to look only for files
named libx.a. This option may be specified multiple
times on the command line as a toggle.
Note: Many system libraries, such as libc, are only
available as dynamic libraries in the Solaris 64-bit
compilation environment. Therefore, do not use -Bstatic
as the last toggle on the command line.
This option and its argument are passed to ld.
-C Prevents the C preprocessor from removing comments,
other than those on preprocessing directive lines.
-c Directs the C compiler to suppress linking with ld and
to produce a .o file for each source file. You can
explicitly name a single object file by
using the -o option. When the compiler produces object
code for each or input file, it always creates an
object file in the current working directory. If you
suppress the linking step, you also suppress the remo-
val of the object files.
-Dname[(arg[,arg])] [=expansion]
Define a macro with optional arguments as if the macro
is defined by a #define preprocessing directive. If no
=expansion is specified, the compiler assumes =1.
Predefinitions:unix
sparc (SPARC)
i386 (x86)
sun
The above are not predefined in -Xc mode.
These predefinitions are valid in all modes:
__BUILTIN_VA_ARG_INCR
__SUNPRO_C=0x590
__SVR4(SPARC)
__SunOS(Solaris)
__SunOS_OSN.N(Solaris)
__amd64(x86 with-m64)
__gnu__linux(linux)
__i386(x86)
__linux(linux)
__linux__(linux)
__sparc(SPARC)
__sparcv9(with-m64)
__sun(Solaris)
__unix
__`uname -s`_`uname -r`
__x86_64(x86)
linux(x86,linux)
The following is predefined in -Xa and -Xt modes only:
__RESTRICT
The compiler also predefines the object-like macro
__PRAGMA_REDEFINE_EXTNAME,
to indicate the pragma will be recognized.
-d [y|n]
-dy specifies dynamic linking, which is the default, in
the link editor. -dn specifies static linking in the
link editor.
This option and its argument are passed to ld.
Note: This option causes fatal errors if you use it in
combination with dynamic libraries. Most system
libraries are only available as dynamic libraries.
-dalign
(SPARC) Obsolete. You should not use this option. Use
-xmemalign=8s instead. For a complete list of obsolete
options and flags, see the C User's Guide.
-E Runs the source file through the preprocessor only and
sends the output to stdout. The preprocessor is built
directly into the compiler, except in -Xs mode, where
/usr/ccs/lib/cpp is invoked. Includes the preprocessor
line numbering information. See also -P option.
-errfmt[=[no%]error]
Use this option if you want to prefix the string
"error:" to the beginning of error messages so they are
more easily distinguishable from warning messages. The
prefix is also attached to warnings that are converted
to errors by -errwarn.
error Add the prefix "error:" to all error messages.
no%error Do not add the prefix "error:" to any error
messages.
If you do not use this option, the compiler sets it to
-errfmt=no%error. If you use specify -errfmt, but do
not supply a value, the compiler sets it to
-errfmt=error.
-errhdr [=h]
Use this option to limit the warnings from header files
to the group of header files indicated by the following
flags:
Value Meaning
%all Check all used header files.
%none Check none of the header files.
%user Default. Checks all the user header files
except those in /usr/include and its sub-
directories. Also checks all the header files
supplied by the compiler.
-erroff[=t[,t...] ]
Suppresses compiler warning messages but has no effect
on error messages. This option applies to all warning
messages whether or not they have been designated by
-errwarn to cause a non-zero exit status.
The -erroff values are members of a comma-separated
list that consists of one or more of the following:
tag Suppresses the warning message specified by
this tag. You can display the tag for a mes-
sage 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. This is the
default.
Order is important; for example, %all,no%tag suppresses
all warning messages except tag.
The default is -erroff=%none. Specifying -erroff is
equivalent to specifying -erroff=%all.
Only warning messages from the C compiler front-end
that display a tag when the -errtags option is used can
be suppressed with the -erroff option. You can achieve
finer control over error message suppression by using
#pragma error_messages.
-errshort[=i]
Use this option to control how much detail is in the
error message produced by the compiler when it discov-
ers a type mismatch. This option is particularly useful
when the compiler discovers a type mismatch that
involves a large aggregate.
i can be one of the following:
short Error messages are printed in short form with
no expansion of types. Aggregate members are
not expanded, neither are function argument
and return types.
full Error messages are printed in full verbose
form showing the full expansion of the
mismatched types.
tags Error messages are printed with tag names for
types which have tag names. If there is no tag
name, the type is shown in expanded form.
If you do not use -errshort, the compiler sets the
option to -errshort=full. If you specify -errshort, but
do not provide a value, the compiler sets the option to
-errshort=tags.
This option does not accumulate, it accepts the last
value specified on the command line.
-errtags=a
Displays the message tag for each warning message of
the C compiler front-end that can be suppressed with
the -erroff option or made a fatal error with the
-errwarn option. Messages from the C compiler driver
and other components of the C compilation system do not
have error tags, and cannot be suppressed with -erroff
and made fatal with -errwarn.
a can be either yes or no. The default is -errtags=no.
Specifying -errtags is equivalent to specifying
-errtags=yes.
-errwarn[=t[,t...] ]
Use the -errwarn option to cause the C compiler to exit
with a failure status for the given warning messages.
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 the C com-
piler to exit with a fatal status if any warning except
tag is issued.
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.
Only warning messages from the C compiler front-end
that display a tag when the -errtags option is used can
be specified with the -errwarn option to cause the C
compiler to exit with a failure status.
The default is -errwarn=%none. If you specify -errwarn
alone, it is equivalent to -errwarn=%all.
The following table details the -errwarn values:
tag Cause cc to exit with a fatal status if the
message specified by tag is issued as a warn-
ing message. Has no effect if tag in 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 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 fol-
lowed by no%tag to exempt specific warning
messages from this behavior.
%none Prevents any warning messages from causing cc
to exit with a fatal status should any warning
tag be issued. This is the default.
-fast
This option is a macro that you can effectively use as
a starting point for tuning an executable for maximum
run-time performance. The expansion of -fast can change
from one release of the compiler to the next and
includes options that are target platform specific. Use
the -# or the -xdryrun options to examine the expansion
of -fast, and incorporate the appropriate options of
-fast into the ongoing process of tuning the execut-
able.
The expansion of -fast now includes the new -xlibmopt
option. This option enables the compiler to use a
library of optimized math routines. For more informa-
tion, see the description of -xlibmopt in this man
page.
The -fast option impacts the value of errno. See the
NOTES section at the end of this man page for more
information.
Modules that are compiled with -fast must also be
linked with -fast. For a complete list of compiler
options that must be specified at both compile time and
at link time, see the C User's Guide.
The -fast option is unsuitable for programs that are
intended to run on a different target than the compila-
tion machine. In such cases, follow -fast with the
appropriate -xtarget option. For example:
% cc -fast -xtarget=ultra
For C modules depending on exception handling specified
by SUID, follow -fast by -xnolibmil
% cc -fast -xnolibmil
The -fast option acts like a macro expansion on the
command line. Therefore, you can override any of the
expanded options by following -fast with the desired
option.
If you combine -fast with other options, the last
specification applies.
These options are turned on for -fast:
-fns (SPARC, x86)
-fsimple=2 (SPARC, x86)
-fsingle (SPARC, x86)
-nofstore (x86)
-xalias_level=basic (SPARC, x86)
-xbuiltin=%all (SPARC, x86)
-xdepend (SPARC, x86)
-xlibmil (SPARC, x86)
-xlibmopt (SPARC)
-xmemalign=8s (SPARC)
-xO5 (SPARC, x86)
-xprefetch=auto,explicit (SPARC)
-xregs=frameptr (x86)
-xtarget=native (SPARC, x86)
Note that this selection of component option flags is
subject to change with each release of the compiler.
For details on the options set by -fast, see the C
User's Guide.
To determine the expansion of -fast on a running sys-
tem, execute the command cc -fast -xdryrun |& grep ###
Note: Some optimizations make certain assumptions about
program behavior. If the program does not conform to
these assumptions, the application may crash or produce
incorrect results. Please refer to the description of
the individual options to determine if your program is
suitable for compilation with -fast.
Do not use this option for programs that depend on IEEE
standard exception handling; you can get different
numerical results, premature program termination, or
unexpected SIGFPE signals.
-fd Reports K&R function declarations and definitions.
-features=[a]
The compiler's treatment of extern inline functions
conforms by default to the behavior specified by the
ISO/IEC 9899:1999 C standard. Compile new codes with
-features=no%extinl to obtain the same treatment of
extern inline functions as provided by versions 5.5, or
older, of the C and C++ compilers.
Old C and C++ objects (pre C/C++ 5.6) can be linked
with new C and C++ objects with no change of behavior
for the old objects. To get standard conforming
behavior, old code must be recompiled using the current
compiler.
a can be one of the following. If you do not specify a
flag for -features, the compiler sets it to
-features=extinl.
-features=extensions
Allows zero-sized struct/union declarations
and void function with return statements
returning a value to work.
-features=extinl
Generates extern inline functions as global
functions. This is the default, which conforms
with the 1999 C standard.
-features=no%extinl
Generates extern inline functions as static
functions.
-features=%none
The option is disabled.
-flags
Prints a one-line summary of available options.
-flteval[={any|2}]
(x86) Use this option to control how floating point
expressions are evaluated.
2 Floating point expressions are evaluated as
long double.
any Floating point expressions are evaluated
depending on the combination of the types of
the variables and constants that make up an
expression.
If you do not specify -flteval, the compiler sets it to
-flteval=any. If you do specify -flteval, but do not
provide a value, the compiler sets it to -flteval=2.
You must not specify the following options in combina-
tion with -flteval=2:
o -fprecision
o -nofstore
o -xarch=sse2
For more information, see 'Precision of Floating Point
Evaluators' in appendix E of the C User's Guide.
-fma [= { none|fused}]
(SPARC) 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 requirements are -xarch=sparcfmaf and an
optimization level of at least -xO2 for the compiler to
generate fused multiply-add instructions. The compiler
marks the binary program if fused multiply-add instruc-
tions are generated in order to prevent the program
from executing on platforms that do not support them.
-fnonstd
-fnonstd is a macro for -fns and -ftrap=common.
-fns[=[no|yes]]
For SPARC, selects the SPARC nonstandard floating-point
mode.
For x86, selects SSE flush-to-zero mode and, where
available, denormals-are-zero mode. This option causes
subnormal results to be flushed to zero on x86. 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 util-
ize the SSE or SSE2 instruction set.
The default, -fns=no, is standard floating-point mode.
Optional use of =yes or =no provides a way of toggling
the -fns flag following some other macro flag that
includes -fns, such as -fast.
-fns is the same as -fns=yes.
-fns=yes selects non-standard floating-point.
-fns=no selects standard floating-point.
On some SPARC systems, the nonstandard floating point
mode disables "gradual underflow", causing tiny results
to be flushed to zero rather than producing subnormal
numbers. It also causes subnormal operands to be
silently replaced by zero. On those SPARC systems that
do not support gradual underflow and subnormal numbers
in hardware, use of this option can significantly
improve the performance of some programs.
When nonstandard mode is enabled, floating point arith-
metic may produce results that do not conform to the
requirements of the IEEE 754 standard. See the Numeri-
cal Computation Guide for more information.
On SPARC systems, this option is effective only if used
when compiling the main program.
-fprecision=p
(x86) Initializes the rounding precision mode bits in
the Floating-point Control Word to p, which is one of
single (24 bits), double (53 bits), or extended (64
bits) respectively. The default floating-point
rounding-precision mode is extended.
Note that on x86, only the precision, not exponent,
range is affected by the setting of floating-point
rounding precision mode.
This option is effective only on x86 systems and only
if used when compiling the main program. On SPARC sys-
tems, the option is ignored.
-fround=r
Sets the IEEE 754 rounding mode that is established at
runtime during the program initialization.
r must be one of: nearest, tozero, negative, positive.
The default is -fround=nearest.
The meanings are the same as those for the ieee_flags
subroutine.
When r is tozero, negative, or positive, this flag
causes the rounding direction mode to be set to round-
to-zero, round-to-negative-infinity, or round-to-
positive-infinity respectively when a program begins
execution. When r is nearest or the -fround flag is
not used, the rounding direction mode is not altered
from its initial value (round-to-nearest by default).
This option is effective only if used when compiling
the main program.
-fsimple[=n]
Allows the optimizer to make simplifying assumptions
concerning floating-point arithmetic.
The compiler defaults to -fsimple=0. Specifying -fsim-
ple is equivalent to -fsimple=1.
If n is present, it must be 0, 1, or 2.
-fsimple=0
Permits no simplifying assumptions. Preserves strict
IEEE 754 conformance.
-fsimple=1
Allows conservative simplifications. The resulting code
does not strictly conform to IEEE 754, but numeric
results of most programs are unchanged.
With -fsimple=1, the optimizer can assume the follow-
ing:
o The IEEE 754 default rounding/trapping modes do not
change after process initialization.
o Computations producing no visible result other than
potential floating- point exceptions may be deleted.
o Computations with Infinity or NaNs as operands need
not propagate NaNs to their results. For example, x*0
may be replaced by 0.
o Computations do not depend on sign of zero.
With -fsimple=1, the optimizer is not allowed to optim-
ize completely without regard to roundoff or excep-
tions. In particular, a floating-point computation can-
not be replaced by one that produces different results
with rounding modes held constant at run time.
-fsimple=2
Includes all the functionality of -fsimple=1, and also
enables use of SIMD instructions to compute reductions
when -xvector=simd is in effect.
Also permits aggressive floating point optimizations
that may cause many programs to produce different
numeric results due to changes in rounding. For exam-
ple, -fsimple=2 permits the optimizer to attempt
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.
Even with -fsimple=2, the optimizer still is not per-
mitted to introduce a floating point exception in a
program that otherwise produces none.
See Also:
Techniques for Optimizing Applications: High Perfor-
mance Computing written by Rajat Garg and Ilya Sharapov
for a more detailed explanation of how optimization can
impact precision.
-fsingle
(-Xt and -Xs modes only) Causes the compiler to evalu-
ate float expressions as single precision, rather than
double precision. (This option has no effect if the
compiler is used in either -Xa or -Xc modes, as float
expressions are already evaluated as single precision.)
-fstore
(x86) Causes the compiler to convert the value of a
floating-point expression or function to the type on
the left-hand side of an assignment, when that expres-
sion or function is assigned to a variable, or when the
expression is cast to a shorter floating-point type,
rather than leaving the value in the register. Due to
roundoffs and truncation, the results may be different
from those generated from the register value. This is
the default mode. To turn off this option, use the
-nofstore option.
-ftrap[=t[,t...] ]
Sets the IEEE 745 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 simultane-
ously enable traps and install a SIGFPE handler. If you
specify more than one value, the list is processed
sequentially from left to right.
Value Meaning
[no%]division [Do not] Trap on division by zero.
[no%]inexact [Do not] Trap on inexact result.
[no%]invalid [Do not] Trap on invalid operation.
[no%]overflow [Do not] Trap on overflow.
[no%]underflow [Do not] Trap on underflow.
%all Trap on all the above.
%none Trap on none of the above.
common Trap on invalid, division by zero, and
overflow.
The default is -ftrap=%none.
Note that the [no%] form of the option is used only to
modify the meanings of the %all or common value 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.
Example: -ftrap=%all,no%inexact means set all traps,
except inexact.
If you compile one routine with -ftrap=t, compile all
routines of the program with the same -ftrap=t option;
otherwise, you can get unexpected results.
Use the -ftrap=inexact trap with caution, as it will
result in the trap being issued whenever a floating-
point value cannot be represented exactly. For example,
the following statement may generate this condition:
x = 1.0 / 3.0;
-G Produce a shared object rather than a dynamically
linked executable. This option is passed to ld and
cannot be used with the -dn option.
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 option on the command
line.
If you are creating a shared object by specifying -G
along with other compiler options that must be speci-
fied at both compile time and link time, make sure that
those same options are also specified when you link
with the resulting shared object.
When you create a shared object, all the object files
that are compiled with -xarch=v9 must also be compiled
with an explicit -xcode value as documented under the
description of -xcode.
-g Produces additional symbol table information for dbx(1)
and the Performance Analyzer analyzer(1).
If you specify -g, and the optimization level is -x03
or lower, the compiler provides best-effort symbolic
information with almost full optimization. Tail-call
optimization and back-end inlining are disabled.
If you specify -g and the optimization level is -x04,
the compiler provides best-effort symbolic information
with full optimization.
Compile with the -g option to use the full capabilities
of the Performance Analyzer. 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.
Note: In previous releases, this option forced the com-
piler to use the incremental linker (ild) by default
instead of the linker (ld) for link-only invocations of
the compiler. That is, with -g, the compiler's default
behavior was to automatically invoke ild in place of ld
whenever you used the compiler to link object files,
unless you specified -G or source files on the command
line. This is no longer the case. The incremental
linker is no longer available.
-H Prints, one per line, the path name of each file
included during the current compilation to standard
error.
-h name
Assigns a name to a shared dynamic library; allows you
to keep different versions of a library.
In general, the name after -h should be the same as the
file name given in the -o option. The space between -h
and name is optional.
The linker assigns the specified name to the library
and records the name in the library file as the intrin-
sic name of the library. If there is no -h name option,
then no intrinsic name is recorded in the library file.
When the runtime linker loads the library into an exe-
cutable file, it copies the intrinsic name from the
library file into the executable, into a list of needed
shared library files. Every executable has such a list.
If there is no intrinsic name of a shared library, then
the linker copies the path of the shared library file
instead.
-I[-|dir]
-Idir adds dir to the list of directories that are
searched for #include files. -I values accumulate from
left to right.
o For include statements of the form #include
<foo.h>, the preprocessor searches for the header
file in the following order:
1. The directories named with the -I option, if
any.
2. The compiler and system standard directories,
usually /usr/include.
o For include statements of the form #include
"foo.h", the compiler searches the directories in
the following order:
1. The current directory (that is, the directory
that contains the file which contains the
include statement itself.
2. The directories named with -I options, if
any.
3. The compiler and system standard directories,
usually /usr/include.
-I- changes the include-file search rules to the fol-
lowing:
o 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".
o For include files of the form #include
"foo.h", search the directories in the fol-
lowing order:
o The directories named with -I options
(both before and after -I-).
o The compiler and system standard direc-
tories, usually /usr/include.
o For include files of the form #include
<foo.h>, search the directories in the fol-
lowing order:
o The directories named with the -I
options that appear after -I- (that is,
the compiler does not search the -I
directories that appear before -I-).
o The compiler and system standard direc-
tories, usually /usr/include.
Only the first -I- option on the command line works as
described above.
-Idir looks in dir, prior to /usr/include, for included
files whose names do not begin with slash (/). Direc-
tories for multiple -I options are searched in the
order specified.
Warnings
Never specify the compiler installation area,
/usr/include, /lib, /usr/lib, as search directories.
-i Ignores the LD_LIBRARY_PATH and LD_LIBRARY_PATH_64 set-
tings.
-KPIC
(SPARC) Obsolete. You should not use this option. Use
-xcode=pic32 instead. For a complete list of obsolete
options and flags, see the C User's Guide.
(x86) -KPIC is identical to -Kpic on x86 architectures.
-Kpic
(SPARC) Obsolete. You should not use this option. Use
-xcode=pic13 instead. For a complete list of obsolete
options and flags, see the C User's Guide.
(x86) Produces 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 pc-relative
addressing mode through a procedure linkage table.
-keeptmp
Retains temporary files created during compilation,
instead of deleting them automatically.
-Ldir
Adds dir to the list of directories searched for
libraries by ld. This option and its arguments are
passed to ld.
Warnings
Never specify the compiler installation area,
/usr/include, /lib, /usr/lib, as search directories.
-lname
Links with object library libname.so or libname.a (for
ld(1)). The order of libraries in the command line is
important, as symbols are resolved from left to right.
This option must follow the sourcefile.
-m32|-m64
Specifies the memory 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.
The ILP32 memory model (32-bit int, long, pointer data
types) is the default on all Solaris platforms and on
Linux platforms that are not 64-bit enabled. The LP64
memory model (64-bit long, pointer data types) is the
default on Linux platforms that are 64-bit enabled.
-m64 is permitted only on platforms that are enabled
for the LP64 model.
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.
Note that in previous compiler releases, the memory
model, ILP32 or LP64, was implied by the choice of the
instruction set with -xarch. Starting with the Sun Stu-
dio 12 compilers, this is no longer the case. On most
platforms, just adding -m64 to the command line is suf-
ficient to create 64-bit objects.
On Solaris, -m32 is the default. On Linux systems sup-
porting 64-bit programs, -m64 -xarch=sse2 is the
default.
See also -xarch.
-mc Removes duplicate strings from the .comment section of
an object file. When you use the -mc flag, -mcs -c is
invoked.
-misalign
(SPARC) Obsolete. You should not use this option. Use
the -xmemalign=1i option instead. For a complete list
of obsolete options and flags, see the C User's Guide.
-misalign2
(SPARC) Obsolete. You should not use this option. Use
the -xmemalign=2i option instead. For a complete list
of obsolete options and flags, see the C User's Guide.
-mr[,string]
-mr removes all strings from the .comment section of an
object file. When you use the -mr flag, mcs -d is
invoked.
-mr,string removes all strings from the .comment sec-
tion and inserts string in the .comment section of the
object file. If string contains embedded blanks, it
must be enclosed in quotation marks. If string is null,
the .comment section will be empty. When you use this
flag, mcs -d -a is invoked.
-mt Compile and link for multithreaded code.
This option passes -D_REENTRANT to the preprocessor and
passes -lthread in the correct order to ld.
The -mt option is required if the application or
libraries are multithreaded.
To ensure proper library linking order, you must use
this option, rather than -lthread, to link with lib-
thread.
If you are using POSIX threads, you must link with the
options -mt -lpthread. The -mt option is necessary
because libC and libCrun need libthread for a mul-
tithreaded application.
If you compile and link in separate steps and you com-
pile with -mt, you might get unexpected results. If you
compile one translation unit with -mt, compile all
units of the program with -mt.
See also: -xnolib
-native
This option is a synonym for -xtarget=native.
-nofstore
(x86) Does not convert the value of a floating-point
expression or function to the type on the left-hand
side of an assignment, when that expression or function
is assigned to a variable, or is cast to a shorter
floating-point type; rather, it leaves the value in a
register.
-O Use default optimization level -xO3. This macro now
expands to -xO3 instead of -xO2.
The change in default yields higher run-time perfor-
mance. However, -x03 may be inappropriate for programs
that rely on all variables being automatically con-
sidered volatile. Typical programs that might have this
assumption are device drivers and older multi-threaded
applications that implement their own synchronization
primitives. The work around is to compile with -xO2
instead of -O.
-On The same as -xOn.
-o filename
Names the output file filename, instead of the default
a.out. filename cannot be the same as sourcefile since
cc does not overwrite the source file. This option and
its argument are passed to ld.
-P Preprocesses only the named C files and leaves the
result in corresponding files suffixed .i. The output
will not contain any preprocessing line directives,
unlike -E.
-p Obsolete See -xpg.
-Q[y|n]
Emits or does not emit identification information to
the output file. If y is used, identification informa-
tion about each invoked compilation tool will be added
to the output files (the default behavior). This can
be useful for software administration. -Qn suppresses
this information.
-qp Same as -p.
-Rdir[:dir...]
A colon-separated list of directories used to specify
library search directories to the runtime linker. If
present and not null, it is recorded in the output
object file and passed to the runtime linker.
If both LD_RUN_PATH and the -R option are specified,
the -R option takes precedence.
-S Compiles, but does not assemble or link edit the named
C files. The assembler-language output is left in
corresponding files suffixed .s.
-s Removes all symbolic debugging information from the
output object file. This option is passed to ld(1).
This option cannot be specified with -g.
-Uname
Causes any definition of name to be undefined. This
option removes any initial definition of the preproces-
sor symbol name created by -D on the same command line
including those placed by the command-line driver.
-U has no effect on any preprocessor directives in
source files. You can supply multiple -U options on the
command line.
If the same name is specified for both -D and -U, name
is not defined, regardless of the order of the options.
-V Causes each invoked tool to print its version informa-
tion on the standard error output.
-v Causes the compiler to perform more and stricter seman-
tic checks, and to enable certain lint-like checks on
the named C files.
-Wc,arg
Passes the argument arg to c. Each argument must be
separated from the preceding by only a comma. (A comma
can be part of an argument by escaping it by an immedi-
ately preceding backslash (\) character; the backslash
is removed from the resulting argument.) All -W argu-
ments are passed after the regular command-line argu-
ments.
c can be one of the following:
a Assembler: (fbe), (gas)
c C code generator: (cg)(SPARC)
d cc driver (1)
h Intermediate code translator (ir2hf)(x86)
i Interprocedure analysis (ube_ipa)(x86)
l Link editor (ld)
m mcs
0 (Captial letter 'o') Interprocedural optim-
izer
o Postoptimizer
p Preprocessor (cpp)
u C code generator (ube), (x86)
0 (The number zero) Compiler (acomp) (ssbd
SPARC)
2 Optimizer: (iropt)
(1) Note: You cannot use -Wd to pass the cc options
listed in this man page to the C compiler.
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 argument(s) are passed to a tool
with respect to the other specified command line
options may change.
-w Suppress compiler warning messages.
The option overrides the error_messages pragma.
-X[c|a|t|s]
Specifies the degree of conformance to the ISO C stan-
dard. The value of -xc99 affects which version of the
ISO C standard the -X option applies.
c (conformance)
Strictly conformant ISO C, without K&R C compati-
bility extensions. The compiler issues errors and
warnings for programs that use non-ISO C con-
structs. The predefined macro __STDC__ has a
value of 1 with the -Xc option.
a This is the default compiler mode. ISO C plus K&R
C compatibility extensions, with semantic changes
required by ISO C. Where K&R C and ISO C specify
different semantics for the same construct, the
compiler uses the ISO C interpretation. If the -Xa
option is used in conjunction with the -xtransi-
tion option, the compiler issues warnings about
the different semantics. The predefined macro
__STDC__ has a value of 0 with the -Xa option.
t (transition)
This option uses ISO C plus K&R C compatibility
extensions without semantic changes required by
ISO C. Where K&R C and ISO C specify different
semantics for the same construct, the compiler
uses the K&R C interpretation. If you use the -Xt
option in conjunction with the -xtransition
option, the compiler issues warnings about the
different semantics. The predefined macro __STDC__
has a value of zero with the -Xt option.
s (K&R C)
The compiler tries to warn about all language con-
structs that have differing behavior between Sun
ISO C and the K&R C. Invokes cpp for processing.
__STDC__ is not defined in this mode.
The predefined macro __STDC__ has the value 0 for -Xt
and -Xa, and 1 for -Xc. (It is not defined for -Xs.)
All warning messages about differing behavior can be
eliminated through appropriate coding; for example, use
of casts can eliminate the integral promotion change
warnings.
-x386
(x86) Obsolete. Do not use this option. Use
-xchip=generic instead. For a complete list of obsolete
options and flags, see the C User's Guide.
-x486
(x86) Obsolete. Do not use this option. Use
-xchip=generic instead. For a complete list of obsolete
options and flags, see the C User's Guide.
-xa Obsolete. Do not use this option. Use -xprofile=tcov
instead. For a complete list of obsolete options and
flags, see the C User's Guide.
-xalias_level[=a]
where a must be one of:any, basic, weak, layout,
strict, std, strong. Use this flag to place the indi-
cated alias level into effect for the whole translation
unit. In other words, the alias level you select is
applied to all of the memory references in the transla-
tion unit. If you do not supply -xalias_level, the com-
piler assumes -xalias_level=any. If you supply
-xalias_level without a value, the compiler assumes
-xalias_level=layout.
o any
The compiler assumes that all memory references can
alias at this level. There is no type-based alias anay-
lysis.
o basic
If you use the -xalias_level=basic option, the compiler
assumes that memory references that involve different C
basic types do not alias each other. The compiler also
assumes that references to all other types can alias
each other as well as any C basic type. The compiler
assumes that references using char * can alias any
other type.
o weak
If you use the -xalias_level=weak option, the compiler
assumes that any structure pointer can point to any
structure type. Any structure or union type that con-
tains a reference to any type that is either referenced
in an expression in the source being compiled or is
referenced from outside the source being compiled, must
be declared prior to the expression in the source being
compiled.
You can satisfy this restriction by including all the
header files of a program that contain types that
reference any of the types of the objects referenced in
any expression of the source being compiled.
At the level of -xalias_level=weak, the compiler
assumes that memory references that involve different C
basic types do not alias each other. The compiler
assumes that references using char * alias memory
references that involve any other type.
o layout
The compiler assumes that memory references that
involve types with the same sequence of types in memory
can alias each other. The compiler assumes that two
references with types that do not look the same in
memory do not alias each other. The compiler assumes
that any two memory accesses through different struct
types alias if the initial members of the structures
look the same in memory. However, at this level, you
should not use a pointer to a struct to access some
field of a dissimilar struct object that is beyond any
of the common initial sequence of members that look the
same in memory between the two structs. This is because
the compiler assumes that such references do not alias
each other.
At the level of -xalias_level=layout the compiler
assumes that memory references that involve different C
basic types do not alias each other. The compiler
assumes that references using char * can alias memory
references involving any other type.
o strict
The compiler assumes that memory references, that
involve types such as structs or unions, that are the
same when tags are removed, can alias each other. Con-
versely, the compiler assumes that memory references
involving types that are not the same even after tags
are removed do not alias each other. However, any
structure or union type that contains a reference to
any type that is part of any object referenced in an
expression in the source being compiled, or is refer-
enced from outside the source being compiled, must be
declared prior to the expression in the source being
compiled.
You can satisfy this restriction by including all the
header files of a program that contain types that
reference any of the types of the objects referenced in
any expression of the source being compiled.
At the level of -xalias_level=strict the compiler
assumes that memory references that involve different C
basic types do not alias each other. The compiler
assumes that references using char * can alias any
other type.
o std
The compiler assumes that types and tags need to be the
same to alias, however, references using char * can
alias any other type. This rule is the same as the res-
trictions on the dereferencing of pointers that are
found in the 1999 ISO C standard. Programs that prop-
erly use this rule will be very portable and should see
good performance gains under optimization.
o strong
The same restrictions apply as at the std level, but
additionally, the compiler assumes that pointers of
type char * are used only to access an object of type
char. Also, the compiler assumes that there are no
interior pointers. An interior pointer is defined as a
pointer that points to a member of a struct.
See Also: -xprefetch_auto_type
-xarch=isa
Specifies the target architecture instruction set
(ISA).
This option limits the code generated by the compiler
to the instructions of the specified instruction set
architecture by allowing only the specified set of
instructions. This option does not guarantee use of any
target-specific instructions. However, use of this
option can affect the portability of a binary program.
See the Notes and Warnings sections at the end of this
entry.
Note: Use the -m64 or -m32 option to specify the
intended memory model, LP64 (64-bits) or ILP32 (32-
bits) respectively. The -xarch flag no longer indi-
cates the memory model, except for compatibility with
previous releases, as indicated below.
Values for all platforms:
Value Meaning
generic This option uses the instruction set common
to most processors.
generic64 Compile for good performance on most 64-bit
platforms. (Solaris only)
This option is equivalent to
-m64 -xarch=generic
and is provided for compatibility with ear-
lier releases. Use -m64 to specify 64-bit
compilation instead of -xarch=generic64
native Compile for good performance on this system
The compiler chooses the appropriate setting
for the current system processor it is run-
ning on.
native64 Compile for good performance on this system
(Solaris only)
This option is equivalent to
-m64 -xarch=native and is provided for compa-
tibility with earlier releases.
Values specific to SPARC platforms:
sparc Compile for the SPARC-V9 ISA.
Compile for the 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 the SPARC-V9 ISA plus VIS.
Compile for SPARC-V9 plus the Visual Instruc-
tion Set (VIS) version 1.0, and with
UltraSPARC extensions. This option enables
the compiler to generate code for good per-
formance on the UltraSPARC architecture.
sparcvis2 Compile for the SPARC-V9 ISA with UltraSPARC
III extensions.
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.
sparcfmaf Compile for the sparcfmaf 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, and
the SPARC64 VI extensions for floating-point
multiply-add.
Note that you must use -xarch=sparcfmaf in
conjunction with -fma=fused and some optimi-
zation level to get the compiler to attempt
to find opportunities to use the multiply-add
instructions automatically.
v9 Is equivalent to -m64 -xarch=sparc
Legacy makefiles and scripts that use
-xarch=v9 to obtain the 64-bit memory model
need only use -m64.
v9a Is equivalent to -m64 -xarch=sparcvis and is
provided for compatibility with earlier
releases.
v9b Is equivalent to -m64 -xarch=sparcvis2 and
is provided for compatibility with earlier
releases.
Notes:
o Legacy 32-bit SPARC instruction set architectures V7
and V8 imply -m32 and cannot be combined with -m64.
o Object binary files (.o) compiled with sparc and
sparcvis can be linked and can execute together, but
only on a sparcvis compatible platform.
o Object binary files (.o) compiled with sparc,
sparcvis, and sparcvis2 can be linked and can execute
together, but only on a sparcvis2 compatible
platform.
For any particular choice, the generated executable
could run much more slowly on earlier architectures.
Also, although quad-precision floating-point instruc-
tions are available in many of these instruction set
architectures, the compiler does not use these
instructions in the code it generates.
Values specific to x86 platforms:
Value Meaning
386 Limits the instruction set to the Intel 32-
bit 386/486 architecture.
pentium_pro
Limits the instruction set to the 32-bit
pentium_pro architecture.
sse Adds the SSE instruction set to the
pentium_pro instruction set.
sse2 Adds the SSE2 instruction set to the
pentium_pro instruction set.
amd64 Is equivalent to -m64 -xarch=sse2 (Solaris
only)
Legacy makefiles and scripts that use
-xarch=amd64 to obtain the 64-bit memory
model need only use -m64.
pentium_proa
Adds the AMD extensions (3DNow!, 3DNow!
extensions, and MMX extensions) to the
pentium_pro architecture.
ssea Adds the AMD extensions (3DNow!, 3DNow!
extensions, and MMX extensions) to the 32-bit
SSE architecture.
sse2a Adds the AMD extensions (3DNow!, 3DNow!
extensions, and MMX extensions) to the SSE2
architecture.
amd64a Is equivalent to -m64 -xarch=sse2a (Solaris
only)
sse3 Adds the SSE3 instruction set to SSE2
instruction set.
Note: 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.
Defaults:
If -xarch=isa is not specified, the defaults are:
-xarch=sparc on SPARC platforms
-xarch=386 on x86/x64 platforms
Interactions:
Although this option can be used alone, it is part of
the expansion of the -xtarget option and can be used
to override the -xarch value that is set by a
specific -xtarget option.
For example, -xtarget=ultra4 expands to
-xarch=sparcvis -xcache=64/32/4:8192/128/2
-xchip=ultra4
In the following command
example% cc -xtarget=ultra4 -xarch=sparcvis2 ...
example% cc -xtarget=ultra4 -xarch=sparcvis2 ...
-xarch=sparcvis2 overrides the -xarch setting in the
expansion of -xtarget=ultra2.
Warnings:
If this option is used with optimization, the
appropriate choice can provide good performance of
the executable on the specified architecture. An
inappropriate choice, however, might result in seri-
ous degradation of performance or in in a binary pro-
gram that is not executable on all intended target
platforms.
-xautopar
Turns on automatic parallelization for multiple proces-
sors. Does dependence analysis (analyze loops for
inter- iteration data dependence) and loop restructur-
ing. If optimization is not at -xO3 or higher, optimi-
zation is raised to -xO3 and a warning is issued.
Note that -xautopar does not accept OpenMP paralleliza-
tion directives.
Avoid -xautopar if you do your own thread management.
To get faster execution, this option requires a multi-
ple processor system. On a single-processor system, the
resulting binary usually runs slower.
To run a parallelized program in a multithreaded
environment, you must set the OMP_NUM_THREADS environ-
ment variable prior to execution. See the OpenMP API
User's Guide for more information.
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 link with cc -xautopar as well. For a
complete list of all compiler options that must be
specified at both compile time and at link time, see
the C User's Guide.
-xbinopt={prepare|off}
(SPARC) Instructs the compiler to prepare the binary
for later optimizations, transformations and analysis
(see binopt(1)). This option may be used for building
executables or shared objects. This option must be used
with optimization level -xO1 or higher to be effective.
There is a modest increase in size of the binary when
built with this option..
If you compile in separate steps, -xbinopt must appear
on both compile and link steps:
example% cc -c -xO1 -xbinopt=prepare a.c b.c
example% cc -o myprog -xbinopt=prepare a.o
If some source code is not available for compilation,
this option may still be used to compile the remainder
of the code. It should then be used in the link step
that creates the final binary. In such a situation,
only the code compiled with this option can be optim-
ized, transformed or analyzed.
Compiling with -xbinopt=prepare and -g increases the
size of the executable by including debugging informa-
tion. The default is -xbinopt=off.
-xbuiltin[=a]
Use the -xbuiltin[=(%all|%none)] command when you want
to improve the optimization of code that calls standard
library functions. Many standard library functions,
such as the ones defined in math.h and stdio.h, are
commonly used by various programs. This command lets
the compiler substitute intrinsic functions or inline
system functions where profitable for performance. See
the er_src(1) man page for an explanation of how to
read compiler commentary in object files to determine
for which functions the compiler actually makes a sub-
sitution.
However, these substitutions can cause the setting of
errno to become unreliable. If your program depends on
the value of errno, avoid this option. See the NOTES
section at the end of this man page for more informa-
tion.
a stands for (%all|%none).
Note: -xbuiltin only inlines global functions defined
in system header files, never static functions defined
by the user.
The first default of this command is -xbuiltin=%none,
which means no functions from the standard libraries
are substituted or inlined. The first default applies
when you do not specify -xbuiltin.
The second default of this command is -xbuiltin=%all,
which means the compiler substitutes intrinsics or
inlines standard library functions as it determines the
optimization benefit. The second default applies when
you specify -xbuiltin but do not provide an argument.
If you compile with -fast, then -xbuiltin is set to
%all.
-xCC When you specify -xc99=none and -xCC, the compiler
accepts the C++-style comments. In particular, the "//"
can be used to indicate the start of a comment.
-xc99[=o]
The -xc99 flag controls compiler recognition of the
implemented features from the C99 standard (ISO/IEC
9899:1999, Programming Language - C).
o can be a comma separated list comprised of the fol-
lowing:
Value Meaning
[no]_lib [Do not] Enable the 1999 C standard
library semantics of routines that
appeared in both the 1990 and 1999 C
standard.
all Turn on recognition of supported C99
language features and enable the 1999 C
standard library semantics of routines
that appear in both the 1990 and 1999 C
standard.
none Turn off recognition of C99 language
features, and do not enable the 1999 C
standard library semantics of routines
that appeared in both the 1990 and 1999
C standard.
If you do not specify -xc99, the compiler defaults to
-xc99=all,no_lib.
If you specify -xc99 without any values, the option is
set to -xc99=all.
NOTE:
Though the compiler support-level defaults to the
language features of the C99 standard, the standard
headers provided by Solaris 9 in /usr/include do not
conform with the 1999 ISO/IEC C standard. If you
encounter error messages, try using -xc99=none to
obtain the 1990 ISO/IEC C standard behavior for these
headers.
The 1999 C standard library semantics of routines that
appeared in both the 1990 and 1999 C standard are not
available and therefore cannot be enabled on Solaris 9.
The compiler issues an error message when -xc99=lib has
been specified directly or indirectly on Solaris 9.
-xcache=c
Defines the cache properties for use by the optimizer.
c must be one of the following:
o generic
o native
o s1/l1/a1
o s1/l1/a1:s2/l2/a2
o s1/l1/a1:s2/l2/a2:s3/l3/a3
The si/li/ai are defined as follows:
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
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.
This option specifies the cache properties that the
optimizer can use. It does not guarantee that any par-
ticular cache property is used.
The -xcache values are:
generic
This is the default. Sets the parameters for the
best performance over most architectures.
native
Sets the parameters for the best performance on
the host environment.
s1/l1/a1
Defines level 1 cache properties.
s1/l1/a1:s2/l2/a2
Defines levels 1 and 2 cache properties.
s1/l1/a1:s2/l2/a2:s3/l3/a3
Defines levels 1, 2, and 3 cache properties.
Example:-xcache=16/32/4:1024/32/1 specifies the following:
Level 1 cache has: Level 2 cache has:
16K bytes
1024K bytes
32 bytes line size
32 bytes line size
4-way associativity
Direct mapping associativity.
-xcg{89|92}
(SPARC) Obsolete. You should not use this option.
Current Solaris operating systems no longer support
SPARC V7 architecture. Compiling with this option gen-
erates code that runs slower on current SPARC plat-
forms. Use -O instead to take advantage of defaults for
-xarch, -xchip, and -xcache.
-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. You can sub-
stitute one of the following values for o:
o signed: Treat character constants and variables
declared as char as signed. This impacts the behavior
of compiled code, it does not affect the behavior of
library routines.
o s: equivalent to signed.
o unsigned: Treat character constants and variables
declared as char as unsigned. This impacts the
behavior of compiled code, it does not affect the
behavior of library routines.
o u: equivalent to unsigned.
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.
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 particu-
lar, the value 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.
If you use -xchar, be particularly careful when you
compare a char against a predefined system macro
because the value in the macro may be signed. This 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.
It is strongly recommended that you never use -xchar to
compile routines for any interface exported through a
library. The 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 that it does not depend on whether
type char is signed or unsigned. The sign of type char
varies among compilers and operating systems.
-xchar_byte_order=o
Produce an integer constant by placing the characters
of a multi-character character-constant in the speci-
fied byte order. You can substitute one of the follow-
ing values for o:
o low: place the characters of a multi-character
character-constant in low-to-high byte order.
o high: place the characters of a multi-character
character-constant in high-to-low byte order.
o default: place the characters of a multi-character
character-constant in an order determined by the com-
pilation mode -X[a|c|s|t].
-xcheck[=n]
(SPARC) Performs a runtime check for stack overflow of
the main thread in a singly-threaded program as well as
slave-thread stacks in a multithreaded program. If a
stack overflow is detected, a SIGSEGV is generated. If
your application needs to handle a SIGSEGV caused by a
stack overflow differently than it handles other
address-space violations, see sigaltstack(2).
n must be one of the following values.
Value Meaning
%all Perform all -xcheck checks.
%none Do not perform any of the -xcheck
checks.
stkovf Enables a runtime check for stack over-
flow.
no%stkovf Turns off stack-overflow checking.
If you do not specify -xcheck, the compiler defaults to
-xcheck=%none. If you specify -xcheck without any argu-
ments, the compiler defaults to -xcheck=%all which
turns on the runtime check for stack overflow.
The -xcheck option does not accumulate on the command
line. The compiler sets the flag in accordance with the
last occurrence of the command.
-xchip=c
Specifies the target processor for use by the optim-
izer.
c must be one of the values listed below.
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.
This option specifies timing properties by specifying
the target processor.
Some effects are:
o The ordering of instructions, that is, scheduling
o The way the compiler uses branches
o The instructions to use in cases where semantically
equivalent alternatives are available
The -xchip values for SPARC platforms are:
generic
Set the parameters for the best performance over
most SPARC platform architectures. This is the
default.
native Set the parameters for the best performance on
the host environment.
old Uses the timing properties of the pre-SuperSPARC
processors.
sparc64vi
Optimize for the SPARC64 VI processor.
super Optimize for the SuperSPARC processor.
super2 Optimize for the SuperSPARC II processor.
micro Optimize for the microSPARC(TM) processor.
micro2 Optimize for the microSPARC II processor.
hyper Optimize for the hyperSPARC(TM) processor.
hyper2 Optimize for the hyperSPARC II processor.
ultra Optimize for the UltraSPARC(TM) processor.
ultra2 Optimize for the UltraSPARC II processor.
ultra2e
Optimize for the UltraSPARC IIe processor.
ultra2i
Optimize for the UltraSPARC IIi processor.
ultra3 Optimize for the UltraSPARC III processor.
ultra3cu
Optimize for the UltraSPARC IIIcu processor.
ultra3i
Optimize for the UltraSPARC IIIi processor.
ultra4 Optimize for the UltraSPARC IV processor.
ultra4plus
Optimize for the UltraSPARC IVplus processor.
ultraT1
Optimize for the UltraSPARC T1 processor.
ultraT2
Optimize for the UltraSPARC T2 processor.
The -xchip values for x86 platforms are:
generic
Optimize for most x86 platforms.
native Optimize for this host processor.
386 Optimize for the 386 architecture.
486 Optimize for the 486 architecture.
opteron
Optimize for the AMD Opteron processor.
pentium
Optimize for the pentium architecture.
pentium_pro
Optimize for the pentium_pro architecture.
pentium3
Optimize for Pentium 3 style processor
pentium4
Optimize for Pentium 4 style processor
-xcode=v
(SPARC) Specify code address space
Note: It is highly recommended that you build shared
objects by specifying -xcode=pic13 or -xcode=pic32. It
is possible to build workable shared objects with
-xarch=v9 -xcode=abs64 and with -xarch=v8 -xcode=abs32,
but these will be inefficient. Shared objects built
with -xarch=v9 -xcode=abs32 or -xarch=v9 -xcode=abs44
will not work.
The values for -xcode are:
abs32 This is the default for 32-bit systems. Gen-
erates 32-bit absolute addresses.
Code + data + bss size is limited to 2**32
bytes.
abs44 This is the default for 64-bit systems. Gen-
erates 44-bit absolute addresses.
Code + data + bss size is limited to 2**44
bytes. Available only on 64-bit architectures.
abs64 Generates 64-bit absolute addresses.
Available only on 64-bit architectures.
pic13 Generates position-independent code for use in
shared libraries (small model).
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 for use in
shared libraries (large model).
Equivalent to -KPIC. Permits references to at
most 2**30 unique external symbols on 32-bit
architectures, 2**29 on 64-bit.
The default is -xcode=abs32 for 32-bit architectures.
The default is -xcode=abs44 for 64-bit architectures.
When building shared dynamic libraries, the default
-xcode value of abs44 (not abs32) will not work with
64-bit architectures. Specify -xcode=pic13 or
-xcode=pic32 instead.
To determine whether to use -xcode=pic13 or
-xcode=pic32, check the size of the Global Offset Table
(GOT) by using elfdump -c (see the elfdump(1) man page
for more information) and to 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.
In general, use the following guidelines to determine
how you should use -xcode:
o If you are building an executable you should not use
-xcode=pic13 or -xcode=pic32.
o If you are building an archive library only for
linking into executables you should not use
-xcode=pic13 or -xcode=pic32.
o If you are building a shared library, start with
-xcode=pic13 and once the GOT size exceeds 8,192 bytes,
use -xcode=pic32.
o If you are building an archive library for linking
into shared libraries you should just use -xcode=pic32.
-xcrossfile[=n]
Enable optimization and inlining across source files
If specified, n may be 0, or 1. The default is
-xcrossfile=0 which specifies that no cross file
optimizations are performed. -xcrossfile is equivalent
to -xcrossfile=1.
Normally, the scope of the compiler's analysis is lim-
ited to each separate file on the command line. For
example, -xO4's automatic inlining is limited to sub-
programs defined and referenced within the same source
file.
With -xcrossfile, the compiler analyzes all the files
named on the command line as if they had been con-
catenated into a single source file. Consider the fol-
lowing command-line example:
example% cc -xcrossfile -xO4 -c f1.c f2.c
example% cc -xcrossfile -xO4 -c f3.c f4.c
Cross-module optimizations occur between files f1.c and
f2.c, and between f3.c and f4.c. No optimizations occur
between f1.c and f3.c or f4.c.
-xcrossfile is only effective when used with -xO4 or
-xO5.
However, this option has no effect when you direct the
compiler to produce assembly source by specifying the
-S option. Assembly (.s) files do not participate in
optimizations and inlining across source files.
The files produced from this compilation are inter-
dependent (due to possible inlining) must be used as a
unit when linking into a program. If any one routine is
changed and the files recompiled, they must all be
recompiled.
As a result, use of this option will affect how
makefiles are constructed.
See also -xldscope, -xipo.
-xcsi
This option allows the C compiler to accept source code
written in locales that do not conform to the ISO C
source character code requirements. These locales
include ja_JP.PCK.
Note: The compiler translation phases required to han-
dle such locales may result in significantly longer
compile times. You should only use this option when
you compile source files that contain source characters
from one of these locales.
The compiler does not recognize source code written in
locales that do not conform to the ISO C source charac-
ter code requirements unless you specify -xcsi.
-xdebugformat=[stabs|dwarf]
Specify -xdebugformat=dwarf if you maintain software
which reads debugging information in the dwarf format.
This option causes the compiler to generate debugging
information by using the dwarf standard format and is
the default
-xdebugformat=stabs generates debugging information
using the stabs standard format.
If you do not specify -xdebugformat, the compiler
assumes -xdebugformat=dwarf. This option requires an
argument.
This option affects the format of the data that is
recorded with the -g option. Some small amount of
debugging information is recorded even without -g, and
the format of that information is also controlled with
this option. So -xdebugformat has a an effect even
when -g is not used.
The dbx and Performance Analyzer software understand
both stabs and dwarf format so using this option does
not have any effect on the functionality of either
tool.
See also the dumpstabs(1) and dwarfdump(1) man pages
for more information.
-xdepend[=[yes|no] ]
Analyzes loops for inter-iteration data dependencies
and performs loop restructuring.
Loop restructuring includes loop interchange, loop
fusion, scalar replacement, and elimination of "dead"
array assignments. If optimization is not at -xO3 or
higher, the compiler raises the optimization to -xO3
and issues a warning.
If you do not specify -xdepend, the default is
-xdepend=no which means the compiler does not analyze
loops for data dependencies. If you specify -xdepend
but do not specify an argument, the compiler sets the
option to -xdepend=yes which means the compiler
analyzes loops for data dependencies.
Dependency analysis is included in -xautopar. The
dependency analysis is done at compile time.
Dependency analysis may help on single-processor sys-
tems. However, if you try -xdepend on single-processor
systems, you should not use either -xautopar or -xex-
plicitpar. If either of them is on, the -xdepend optim-
ization is done for multiple-processor systems.
See Also: -xprefetch_auto_type
-xdryrun
This option is a macro for -###.
-xe Performs only syntax and semantic checking on the
source file, but does not produce any object or execut-
able file.
-xexplicitpar
(SPARC) Obsolete, do not use. -xexplicitpar does not
accept OpenMP parallelization directives. However, the
Sun-specific MP pragmas have been deprecated and the
compiler supports the APIs specified by the OpenMP 2.5
standard instead. See the OpenMP API User's Guide for
migration information to the directives of the stan-
dard.
Parallelizes the loops that are specified. You do the
dependency analysis: analyze and specify loops for
inter-iteration and data dependencies. The software
parallelizes the specified loops.
Note that
If optimization is not at -xO3 or higher, then it is
raised to -xO3 and a warning is issued.
Avoid -xexplicitpar if you do your own thread manage-
ment.
To get faster code, use this option on a multiprocessor
system. On a single-processor system, the generated
code usually runs slower.
If you identify a loop for parallelization, and the
loop has dependencies, you can get incorrect results,
possibly different ones with each run, and with no
warnings. Do not apply an explicit parallel pragma to
a reduction loop. The explicit parallelization is
done, but the reduction aspect of the loop is not done,
and the results can be incorrect.
If you use -xexplicitpar and compile and link in one
step, then linking automatically includes the micro-
tasking library and the threads-safe C runtime library.
If you use -xexplicitpar and compile and link in
separate steps, then you must also link with cc -xex-
plicitpar. For a complete list of compiler options that
must be specified at both compile time and at link
time, see the C User's Guide.
Do not specify -xexplicitpar and -xopenmp together.
-xF[=v]
The -xF option enables the optimal reordering of func-
tions and variables by the linker.
This option instructs the compiler to place functions
and/or data variables into separate section fragments,
which enables the linker, using directions in a mapfile
specified by the linker's -M option, to reorder these
sections to optimize program performance. Generally,
this optimization is only effective when page fault
time constitutes a significant fraction of program run
time.
Reordering functions and variables for optimal perfor-
mance requires the following operations:
1. Compiling and linking with -xF.
2. Following the instructions in the Performance
Analyzer manual regarding how to generate a mapfile for
functions or following the instructions in the Linker
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 improve-
ment.
v can be one of the following values:
Value Meaning
[no%]func [Do not] fragment functions into
separate sections.
[no%]gbldata [Do not] fragment global data (variables
with external linkage) into separate
sections.
%all Fragment functions and global data.
%none Fragment nothing.
If you do not specify -xF, the default is -xF=%none. If
you specify -xF without any arguments, the default is
-xF=%none,func.
See Also:
analyzer(1), debugger(1), ld(1)
-xhelp=f
Displays on-line help information.
f must be either flags or readme.
-xhelp=flags displays a summary of the compiler
options;
-xhelp=readme displays the readme file;
-xhwcprof[={enable|disable}]
(SPARC) Use the -xhwcprof option to enable compiler
support for dataspace profiling.
When -xhwcprof is enabled, the compiler generates
information that helps tools associate profiled load
and store instructions with the data-types and struc-
ture 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, and provides insight into
behavior that is not easily obtained from only instruc-
tion profiling.
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. This
will provide 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. For a com-
plete list of compiler options that must be specified
at both compile time and at link time, see the C User's
Guide.
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 be turned on and
that the debug data format be set to dwarf
(-xdebugformat=dwarf).
The combination of -xhwcprof and -g increases compiler
temporary file storage requirements by more than the
sum of the increases due to -xhwcprof and -g specified
alone.
The following command compiles example.c and specifies
support for hardware counter profiling and symbolic
analysis of data types and structure members using
DWARF symbols:
example% cc -c -O -xhwcprof -g -xdebugformat=dwarf
example.c
For more information on hardware counter-based
profiling, see the Performance Analyzer manual.
-xinline[=v[,v]...]
v can be [{%auto,func_name,no%func_name}].
-xinline tries to inline only those functions specified
in the list. The list is comprised of either a comma-
separated list of function names, or a comma separated
list of no%func_name values, or the value %auto. If you
specify %nofunc_name, the compiler is not to inline the
named function. If you specify %auto, the compiler is
to attempt to automatically inline all functions in the
source files.
The list of values accumulates from left to right. So
for a specification of -xinline=%auto,no%foo the com-
piler attempts to inline all functions except foo. For
a specification of -xinline=%bar,%myfunc,no%bar the
compiler only tries to inline myfunc.
When you compile with optimization set at -xO4 or
above, the compiler normally tries to inline all refer-
ences to functions defined in the source file. You can
restrict the set of functions the compiler attempts to
inline by specifying the -xinline option. If you
specify only -xinline=, that is you do not name any
functions or auto, this indicates that none of the rou-
tines in the source files are to be inlined. If you
specify a list of func_name and no%func_name without
specifying %auto, the compiler only attempts to inline
those functions specified in the list. If %auto is
specified in the list of values with the -xinline
option at optimization level set at -xO4 or above, the
compiler attempts to inline all functions that are not
explicitly excluded by no%func_name.
A function is not inlined if any of the following apply
(no warning is issued):
o Optimization is less than -xO3
o The routine cannot be found
o Inlining the routine does not look profitable or
safe to iropt
o The source for the routine is not in the file being
compiled (however, see -xcrossfile).
If you specify multiple -xinline options on the command
line, they do not accumulate. The last -xinline on the
command line specifies what functions the compiler
attempts to inline.
See also -xldscope.
-xinstrument=[no%]datarace]
Specify this option to compile and instrument your pro-
gram for analysis by the Thread Analyzer. For more
information on the Thread Analyzer, see tha(1) for
details.
You can then use the Performance Analzyer to run the
instrumented program with collect -r races to create a
data-race-detection experiment. You can run the instru-
mented code standalone 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.
It is illegal to specify -xinstrument without an argu-
ment.
If you compile and link in seperate 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.
-xipo[=n]
The compiler performs partial-program optimizations by
invoking an interprocedural analysis pass. Unlike
-xcrossfile, -xipo performs optimizations across all
object files in the link step, and is not limited to
just the source files on the compile command. However,
just like -xcrossfile, whole-program optimizations per-
formed with -xipo do not include assembly (.s) source
files.
You must specify -xipo both at compile time and at link
time. For a complete list of compiler options that
must be specified at both compile time and at link
time, see the C User's Guide.
Analysis and optimization is limited to the object
files compiled with -xipo, and does not extend to
object files or libraries. -xipo is multiphased, so
you need to specify -xipo for each step if you compile
and link in separate steps.
The -xipo option generates significantly larger object
files due to the additional information needed to
perform optimizations across files. However, this addi-
tional information does not become part of the final
executable binary file. Any increase in the size of the
executable program is due to the additional optimiza-
tions performed. The object files created in the compi-
lation steps have additional analysis information com-
piled within them to permit crossfile optimizations to
take place at the link step.
n is 0, 1, or 2. -xipo without any arguments is
equivalent to -xipo=1. -xipo=0 is the default setting
and turns off -xipo.
With -xipo=1, the compiler performs inlining across all
source files. At -xipo=2, the compiler performs inter-
procedural aliasing analysis as well as optimization of
memory allocation and layout to improve cache perfor-
mance.
Here are some important considerations for -xipo:
o It requires an optimization level of at least -xO4.
o It conflicts with -xcrossfile. If you use these
together, the result is a compilation error.
o Objects that are compiled without -xipo can be linked
freely with objects that are compiled with -xipo.
In this example, compilation and linking occur in a
single step:
cc -xipo -xO4 -o prog part1.c part2.c part3.c
In this example, compilation and linking occur in
separate steps:
cc -xipo -xO4 -c part1.c part2.c
cc -xipo -xO4 -c part3.c
cc -xipo -xO4 -o prog part1.o part2.o part3.o
The object files created in the compilation steps have
additional analysis information compiled within them to
permit crossfile optimizations to take place at the
link step.
A restriction is that libraries, even if compiled with
-xipo do not participate in crossfile interprocedural
analysis, as shown in this example:
cc -xipo -xO4 one.c two.c three.c
ar -r mylib.a one.o two.o three.o
cc -xipo -xO4 -o myprog main.c four.c mylib.a
Here interprocedural optimizations are performed
between one.c, two.c and three.c, and between main.c
and four.c, but not between main.c or four.c and the
routines on mylib.a. (The first compilation may gen-
erate warnings about undefined symbols, but the inter-
procedural optimizations are performed because it is a
compile and link step.)
When Not To Use -xipo=2 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 follow-
ing two assumptions for any function (or subroutine)
foo() defined in this set of object files:
(1) foo() is not called explicitly by another routine
that is defined outside this set of object files at
runtime.
(2) 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 assumption (1) is not
true for the given application.
Do not compile with either -xipo=1 or -xipo=2 if
assumption (2) is not true.
As an example, consider interposing on the function
malloc() with your own version and compiling with
-xipo=2. Consequently, 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. Since this
might not be possible for system libraries, do not com-
pile 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 there is a possibility that foo()
could be interposed at runtime, then 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.
See also -xjobs and -xipo_archive
-xipo_archive[=a]
The -xipo_archive option enables the compiler to optim-
ize 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.
a is one of the following:
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 optim-
ization 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 doing so modifies the contents of the
archive library from which the code was extracted.
none
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.
It is illegal to specify -xipo_archive without a flag.
-xjobs=n
Compile with multiple processors.
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 optim-
izer 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 over-
heads among spawned jobs. Also, using a very high
number can exhaust the limits of system resources such
as swap space.
You must always specify -xjobs with a value. Otherwise
an error diagnostic is issued and compilation aborts.
Multiple instances of -xjobs on the command line over-
ride each other until the rightmost instance is
reached.
The following example compiles more quickly on a system
with two processors than the same command without the
-xjobs option.
example% cc -xipo -xO4 -xjobs=3 t1.c t2.c t3.c
-xldscope={v}
Changes the default linker scoping for the definition
of extern symbols. Changing the default can result in
faster and safer shared libraries because the implemen-
tation will be better hidden.
v must be one of the following:
Value Meaning
global Global linker scoping is the least res-
trictive linker scoping. All references
to the symbol bind to the definition in
the first dynamic module that defines
the symbol. This linker scoping is the
current linker scoping for extern sym-
bols.
symbolic Symbolic linker scoping and is more res-
trictive than global linker scoping. All
references to the symbol from within the
dynamic module being linked bind to the
symbol defined within the module. Out-
side of the module, the symbol appears
as though it were global. This linker
scoping corresponds to the linker option
-Bsymbolic.
hidden Hidden linker scoping is more restric-
tive than symbolic and global linker
scoping. All references within a dynamic
module bind to a definition within that
module. The symbol will not be visible
outside of the module.
If you do not specify -xldscope, the compiler assumes
-xldscope=global. It is not legal to specify -xldscope
without any arguments. The compiler issues an error if
you specify -xldscope without an argument. Multiple
instances of this option on the command line override
each other until the rightmost instance is reached.
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 if you specify the function name
with -xinline, if you use #pragma inline, if you com-
pile at -xO4 or higher in which case inlining can hap-
pen automatically, if you use the inline specifier, or
if you are using cross-file optimization.
For example, suppose library ABC has a default alloca-
tor 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 com-
piler 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 __sym-
bolic specifiers can be generated inline when building
the library. They are not supposed to be overridden by
clients. For more information, see chapter 2 "C-
Compiler Information Specific to Sun's Implementation"
of the C User's Guide.
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.
See Also
-xinline, -xO, -xcrossfile, ld(1).
-xlibmieee
Forces IEEE 754 style return values for math routines
in exceptional cases. In such cases, no exception mes-
sage will be printed, and errno should not be relied
on.
-xlibmil
Inlines some library routines for faster execution.
This option selects the appropriate assembly language
inline templates for the floating-point option and
platform for your system. -xlibmil inlines a function
regardless of any specification of the function as part
of the -xinline flag.
However, these substitutions can cause the setting of
errno to become unreliable. If your program depends on
the value of errno, avoid this option. See the NOTES
section at the end of this man page for more informa-
tion.
-xlibmopt
Enables the compiler to use a library of optimized math
routines. You must use default rounding mode by speci-
fying -fround=nearest when you use this option.
The math routine library is optimized for performance
and usually generates faster code. The results may be
slightly different from those produced by the normal
math library. If so, they usually differ in the last
bit.
However, these substitutions can cause the setting of
errno to become unreliable. If your program depends on
the value of errno, avoid this option. See the NOTES
section at the end of this man page for more informa-
tion.
The order on the command line for this library option
is not significant.
Interactions:
This option is implied by the -fast option.
See also:
-fast
-xnolibmopt
-xlic_lib=sunperf
Links in the Sun supplied performance libraries.
-xlicinfo
This option is silently ignored by the compiler.
-xlinkopt[=level]
(SPARC) Instructs the compiler to perform link-time
optimizations on relocatable object files.
The post-optimizer performs a number of advanced per-
formance optimizations on the binary object code at
link-time. The value level sets the level of optimiza-
tions performed, and must be 0, 1, or 2.
The optimization levels are:
0 The post-optimizer is disabled. (This is 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, includ-
ing dead-code elimination and address computa-
tion simplification, at link time.
Specifying -xlinkopt without the level parameter
implies -xlinkopt=1.
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.
This option is most effective when you use it to com-
pile the whole program, and with profile feedback.
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
For a complete list of compiler options that must be
specified at both compile time and at link time, see
the C User's Guide.
Note that the level parameter is only used when the
compiler is linking. In the example above, the post-
optimization level used is 2 even though the object
binaries were compiled with an implied level of 1.
Do not use the -zcompreloc linker option when you com-
pile with -xlinkopt.
You must use -xlinkopt on at least some of the compila-
tion commands for -xlinkopt to be useful at link time.
The optimizer can still perform some limited optimiza-
tions on object binaries not compiled with -xlinkopt.
-xlinkopt optimizes code coming from static libraries
that appear on the compiler command line, but it skips
and 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 (compil-
ing with -G ).
The link-time post-optimizer is most effective when you
use it with run-time profile feedback. Profiling
reveals the most and least used parts of the code and
directs the optimizer to focus its effort accordingly.
This is particularly important with large applications
where optimal placement of code performed at link time
can reduce instruction cache misses. Typically, this
would be compiled 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
For details on using profile feedback, see -xprofile.
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 excut-
able by including debugging information.
-xloopinfo
Shows which loops are parallelized and which are not.
This option is normally for use with the -xautopar and
-xexplicitpar options.
-xM Runs only the preprocessor on the named C programs,
requesting that it generate makefile dependencies and
send the result to the standard output (see make (1)
for details about makefiles and dependencies).
-xM1 Same as -xM except that -xM1 is not supported in -Xs
mode nor does -xM1 report dependencies for /usr/include
header files. For example:
example% more hello.c
#include <stdio.h>
main()
{
(void) printf ("hello\n");
}
example% cc -xM hello.c
hello.o: hello.c
hello.o: /usr/include/stdio.h
Compiling with -xM1 does not report header file dependencies:
example% cc -xM1 hello.c
hello.o: hello.c
-xMerge
Directs cc to merge the data segment with the text seg-
ment. Data initialized in the object file produced by
this compilation is read-only and (unless linked with
ld -N) is shared between processes.
-xmaxopt[=v]
This command limits the level of pragma opt to the
level specified. The default value is -xmaxopt=off
which causes pragma opt to be ignored. If you specify
-xmaxopt without supplying an argument, that is the
equivalent of specifying -xmaxopt=5.
If you specify both -xO and -xmaxopt, the optimization
level set with -xO must not exceed the -xmaxopt value.
-xmemalign=ab
(SPARC) This command specifes the maximum assumed
memory alignment and the behavior of misaligned data
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.
Use the -xmemalign option to specify the maximum
memory alignment of data to be assumed by the compiler
in these indeterminable situations. You can also
specify the error behavior to be followed at run-time
when a misaligned memory access does take place.
Values
Accepted values for a are:
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.
Accepted values for b are:
i Interpret access and continue execution.
s Raise signal SIGBUS.
f For variants of -xarch=v9 only. Raise signal
SIGBUS for alignments less than or equal to
4, otherwise interpret access and continue
execution. For all other -xarch values, the f
flag is equivalent to i.
You must also 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 com-
piler options that must be specified at both compile
time and at link time, see the C User's Guide.
Defaults
The default is -xmemalign=8i for all v8 architectures.
The default for all v9 architectures is -xmemalign=8s.
Specifying -xmemalign is equivalent to specifying
-xmemalign=1i.
-xmodel=[a]
(x86) The -xmodel option determines the data address
model for shared objects on the Solaris x64 platforms
and should only be specified for the compilation of
such objects.
This option is valid only when -m64 is also specified
on 64-bit enabled x64 processors.
a is one of the following:
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. 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 com-
piling with -m64.
This option is not cumulative so the compiler sets the
model value according to the rightmost 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.
It is not necessary 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.
-xnolibmil
Does not inline math library routines. Use -xnolibmil
after the -fast option:
cc -fast -xnolibmil ...
-xnolibmopt
Do not link with the optimized math routine library by
turning off any previously specified -xlibmopt options.
Use this option after the -fast option on the command
line, as in:
example% cc -fast -xnolibmopt ...
-xnorunpath
Do not build a runtime search path for shared libraries
into the executable.
Normally cc does not pass any -R path to the linker.
There are a few options that do pass -R path to the
linker such as -xliclib=sunperf and -xopenmp. The
-xnorunpath option can be used to prevent this.
This option is recommended for building executables
that will be shipped to customers who may have a dif-
ferent path for the shared libraries that are used by
the program.
-xOn Specifies optimization level (n). (Note the uppercase
letter O, followed by a digit 1, 2, 3, 4, or 5)
Generally, the higher the level of optimization with
which a program is compiled, the better runtime perfor-
mance obtained. However, higher optimization levels may
result in increased compilation time and larger execut-
able files.
There are five levels that you can use with -xOn. The
following sections describe each level for SPARC plat-
forms and for x86 platforms. The actual optimizations
performed by the compiler at each level may change with
each compiler release.
If the optimizer runs out of memory, it attempts to
proceed over again at a lower level of optimization,
resuming compilation of subsequent routines at the ori-
ginal level.
Values:
On SPARC Platforms:
-xO1 Does basic local optimization (peephole).
-xO2 Does basic local and global optimization. This
includes induction variable elimination, local and
global common subexpression elimination, algebraic
simplification, copy propagation, constant propa-
gation, loop-invariant optimization, register
allocation, basic block merging, tail recursion
elimination, dead code elimination, tail call
elimination and complex expression expansion.
This level does not assign global, external, or
indirect references or definitions to registers.
It treats these references and definitions as if
they were declared volatile. In general, the -xO2
level results in minimum code size.
-xO3 In addition to optimizations performed at the -xO2
level, also optimizes references or definitions
for external variables. Loop unrolling and
software pipelining are also performed. This level
does not trace the effects of pointer assignments.
When compiling either device drivers, or programs
that modify external variables from within signal
handlers, you may need to use the volatile type
qualifier to protect the object from optimization.
In general, the -xO3 level results in increased
code size.
-xO4 Does automatic inlining of functions contained in
the same file in addition to performing -xO3
optimizations. If you want to control which func-
tions are inlined, see the -xinline option
description in this man page. This level traces
the effects of pointer assignments, and usually
results in increased code size.
-xO5 Performs the highest level of optimization, suit-
able only for the small fraction of a program that
uses the largest fraction of computer time. 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=collect|use.
On x86 platforms:
-xO1 Preloads arguments from memory, cross-jumping
(tail-merging), as well as the single pass of the
default optimization.
-xO2 Schedules both high- and low-level instructions
and performs improved spill analysis, loop
memory-reference elimination, register lifetime
analysis, enhanced register allocation, and elimi-
nation of global common subexpressions.
-xO3 Performs loop strength reduction, induction
variable elimination, as well as the optimization
done by -xO2.
-xO4 Performs 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.
-xO5 Generates the highest level of optimization. Uses
optimization algorithms that take more compilation
time or that do not have as high a certainty of
improving execution time. Some of these include
generating local calling convention entry points
for exported functions, further optimizing spill
code and adding analysis to improve instruction
scheduling.
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 give 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.
If you use -g 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.
If you use -g and the optimization level is -xO4 or
higher, the compiler provides best-effort symbolic
information with full optimization.
Debugging with -g does not suppress -xOn, but -xOn lim-
its -g in certain ways. For example, the optimization
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.
If you specify both -xO and -xmaxopt, the optimization
level set with -xO must not exceed the -xmaxopt value.
See also:
-xldscope, -fast, -xprofile=p, csh(1) man page
Performance Analyzer discusses the effects of the dif-
ferent levels of optimization on the Analyzer's data.
-xopenmp[=i]
Use the -xopenmp option to enable explicit paralleliza-
tion with OpenMP directives. To run a parallelized
program in a multithreaded environment, you must set
the OMP_NUM_THREADS environment variable prior to exe-
cution. See the OpenMP API User's Guide for more infor-
mation.
To enable nested parallelism, you must set the
OMP_NESTED environment variable to TRUE. Nested paral-
lelism is disabled by default. See the Sun Studio
OpenMP API User's Guide for details.
The following table details the -xopenmp values:
Value Meaning
parallel Enables recognition of OpenMP pragmas. The
optimization level under -xopenmp=parallel is
-x03. The compiler changes the optimization
level to -x03 if necessary and issues a warn-
ing. This flag also defines the preprocessor
token _OPENMP.
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 token
_OPENMP.
none This flag is the default and does not enable
recognition of OpenMP pragmas, makes no change
to the optimization level of your program, and
does not predefine any preprocessor tokens.
If you specify -xopenmp, but do not include an argu-
ment, the compiler assumes -xopenmp=parallel. This
default could change in future releases. If you do not
specify -xopenmp, the compiler assumes -xopenmp=none.
If you are debugging an OpenMP program with dbx, com-
pile with -g -xopenmp=noopt so you can breakpoint
within parallel regions and display the contents of
variables.
Do not specify -xopenmp, with either -xparallel or
-xexplicitpar.
The default for -xopenmp might change in future
releases. You can avoid warning messages by explicitly
specifying an appropriate optimization.
If you compile and link in seperate steps, specify
-xopenmp in both the compilation step and the link
step. This is important if you are building a shared
object. The compiler which was used to compile the exe-
cutable must not be any older than the compiler that
built the .so with -xopenmp. This is especially impor-
tant when you compile libraries that contain OpenMP
directives.
Make sure that the latest patch of the OpenMP runtime
library, libmtsk.so, is installed on the system for
best performance.
For information that is specific to the C implementa-
tion of OpenMP, see the C User's Guide.
For a complete summary of the OpenMP Fortran 95, C, and
C++ application program interface (API) for building
multiprocessing applications, see the OpenMP API User's
Guide.
-xP Performs only syntax and semantic checking on the
source file in order to print prototypes for all K&R C
functions. This option does not produce any object or
executable code.
-xpagesize=n
Set the preferred page size for the stack and the heap.
The n value must be one of the following:
4k 8K 64K 512K 2M 4M 32M 256M 2G 16G or default.
You must specify a valid page size for the target plat-
form. If you do not specify a valid pagesize, the
request is silently ignored at run-time.
Use the getpagesize(3C) command on the Solaris operat-
ing environment to determine the number of bytes in a
page. The Solaris operating environment offers no
guarantee that the page size request will be honored.
You can use pmap(1) or meminfo(2) to determine page
size of the target platform.
The -xpagesize option has no effect unless you use it
at compile time and at link time. For a complete list
of compiler options that must be specified at both com-
pile time and at link time, see the C User's Guide.
If you specify -xpagesize=default, the operating
environment sets the page size.
Compiling with this option has the same effect as set-
ting the LD_PRELOAD environment variable to mpss.so.1
with the equivalent options, or running the Solaris
command ppgsz(1) with the equivalent options before
running the program. See the Solaris man pages for
details.
This option is a macro for -xpagesize_heap and
-xpagesize_stack. These two options accept the same
arguments as -xpagesize. You can set them both with the
same value by specifying -xpagesize=n or you can
specify them individually with different values.
-xpagesize_heap=n
Set the page size in memory for the heap.
The n value must be one of the following:
4k 8K 64K 512K 2M 4M 32M 256M 2G 16G or default.
You must specify a valid page size for the target plat-
form. If you do not specify a valid pagesize, the
request is silently ignored at run-time.
Use the getpagesize(3C) command on the Solaris operat-
ing environment to determine the number of bytes in a
page. The Solaris operating environment offers no
guarantee that the page size request will be honored.
You can use pmap(1) or meminfo(2) to determine page
size at the target platform.
If you specify -xpagesize_heap=default, the operating
system sets the page size.
Compiling with this option has the same effect as set-
ting the LD_PRELOAD environment variable to mpss.so.1
with the equivalent options, or running the Solaris
command ppgsz(1) with the equivalent options before
running the program. See the Solaris man pages for
details.
The -xpagesize_heap option has no effect unless you use
it at compile time and at link time. For a complete
list of compiler options that must be specified at both
compile time and at link time, see the C User's Guide.
-xpagesize_stack=n
Set the page size in memory for the stack.
The n value must be one of the following:
4k 8K 64K 512K 2M 4M 32M 256M 2G 16G or default.
You must specify a valid page size for the Solaris
operating environment on the target platform. If you do
not specify a valid pagesize, the request is silently
ignored at run-time.
Use the getpagesize(3C) command on the Solaris operat-
ing environment to determine the number of bytes in a
page. The Solaris operating environment offers no
guarantee that the page size request will be honored.
You can use pmap(1) or meminfo(2) to determine page
size at the target platform.
If you specify -xpagesize_stack=default, the Solaris
operating environment sets the page size.
Compiling with this option has the same effect as set-
ting the LD_PRELOAD environment variable to mpss.so.1
with the equivalent options, or running the Solaris
command ppgsz(1) with the equivalent options before
running the program. See the Solaris man pages for
details.
The -xpagesize_stack option has no effect unless you
use it at compile time and at link time. For a complete
list of compiler options that must be specified at both
compile time and at link time, see the C User's Guide.
-xparallel
(SPARC) Obsolete, do not use. Use -xopenmp instead.
This option enables legacy Sun parallelization pragmas.
These pragmas and parallelization model are deprecated
and no longer supported. The OpenMP API is the pre-
ferred and supported parallelization model. See the
-xopenmp option and the OpenMP API User's Guide for
details on converting to OpenMP.
-xparallel parallelizes loops both automatically (by
the compiler) and explicitly (as specified by the pro-
grammer). Explicit parallelization through the use of
MP pragmas is SPARC only.
Note that -xparallel does not accept OpenMP paralleli-
zation directives. However, the Sun-specific MP pragmas
have been deprecated and the compiler supports the APIs
specified by the OpenMP 2.5 standard instead. See the
OpenMP API User's Guide for migration information to
the directives of the standard.
This option is a macro and is equivalent to specifying
all three of -xautopar, -xdepend, and
-xexplicitpar. With explicit parallelization, there is
a risk of producing incorrect results.
If optimization is not at -xO3 or higher, optimization
is raised to -xO3 and a warning is issued.
Avoid -xparallel if you do your own thread management.
Do not specify -xparallel if you are specifying
-xopenmp. -xparallel sets -xexplicitpar which should
not be issued if you specify -xopenmp.
To get faster code, use this option on a multiprocessor
system. On a single-processor system, the generated
code usually runs more slowly.
If you compile and link in one step, -xparallel links
with the microtasking library and the threads-safe C
runtime library. If you compile and link in separate
steps, and you compile with -xparallel, then link with
-xparallel. For a complete list of compiler options
that must be specified at both compile time and at link
time, see the C User's Guide.
-xpch=v
This compiler option activates the precompiled-header
feature. v can be auto, autofirst,
collect:pch_filename, or use:pch_filename. You can take
advantage of this feature through the -xpch and
-xpchstop options in combination with the #pragma
hdrstop directive.
Use the -xpch option to create a precompiled-header
file and improve your compilation time. The
precompiled-header file is designed to reduce compile
time for applications whose source files share a common
set of include files containing a large amount of
source code. A precompiled header works by collecting
information about a sequence of header files from one
source file, and then using that information when
recompiling that source file, and when compiling other
source files that have the same sequence of headers.
Creating a Precompiled-Header File Automatically
You can let the compiler generate the precompiled-
header file for you automatically. Choose between one
of the following two ways to do this. One way is for
the compiler to create the precompiled-header file from
the first include file it finds in the source file. The
other way is for the compiler to select from the set of
include files found in the source file starting with
the first include file and extending through a well-
defined point that determines which include file is the
last one. Use one of the following two flags to deter-
mine which method the compiler uses to automatically
generate a precompiled header:
-xpch=auto
The contents of the precompiled-header file is
based on the longest viable prefix (see the fol-
lowing section for an explanation of how a viable
prefix is identified) that the compiler finds in
the source file. This flag produces a precompiled
header file that consists of the largest possible
number of header files.
-xpch=autofirst
This flag produces a precompiled-header file that
contains only the first header found in the source
file.
Creating the Precompiled-Header File Manually
If you decide to create your precompiled-header file
manually, you must start by first using -xpch and
specifying 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.c:
cc -xpch=collect:myheader a.c
A valid precompiled-header filename always has the suf-
fix .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.c, the
precompiled-header file is called foo.cpch.
How the Compiler Handles an Existing Precompiled-Header
File
If the compiler cannot use the precompiled-header file,
under -xpch=auto and -xpch=autofirst, it will generate
a new precompiled-header file. If the compiler cannot
use the precompiled-header file under -xpch=use, a
warning is issued and the compilation is done using the
real headers.
Directing the Compiler to Use a Specific Precompiled-
Header File
You can also direct the compiler to use a specific
precompiled header. Specify -xpch=use:pch_filename to
do this. You can specify any number of source files
with the same sequence of include files as the source
file 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.c foobar.c
You should only use an existing precompiled-header file
if the following is true. If any of the following is
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 may not be usable by another version of the
compiler.
- 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 precompiled 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 precom-
piled 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 pre-processing directives,
including #include directives, in the file you speci-
fied with -xpch=collect are the same as the sequence of
pre-processing directives in the files you specify with
-xpch=use.
The Viable Prefix
In order to share a precompiled-header file across mul-
tiple source files, those source files must share a
common set of include files as their initial sequence
of tokens. A token is a keyword, name or punctuation
mark. Comments and code that is excluded by #if direc-
tives are not recognized by the compiler as tokens.
This initial sequence of tokens is known as the viable
prefix. In other words, the viable prefix is the top
portion of the source file that is common to all source
files. The compiler uses this viable prefix as the
basis for creating a precompiled-header file and
thereby determining which header files from the source
are pre-compiled.
The viable prefix that the compiler finds during the
current compilation must match the viable prefix that
it used to create the precompiled-header file. In other
words, the viable prefix must be interpreted con-
sistently by the compiler across all the source files
that use the same precompiled-header file.
The viable prefix consists of any of the following
pre-processor directives:
#include
#if/ifdef/ifndef/else/elif/endif
#define/undef
#ident
#pragma
Any of these may reference macros. The #else, #elif,
and #endif directives must match within the viable pre-
fix. Comments are ignored.
The compiler determines the end point of the viable
prefix automatically when you specify -xpch=auto or
-xpch=autofirst and is defined as follows. For
-xpch=collect or -xpch=use, the viable prefix ends with
a #pragma hdrstop.
- The first declaration/definition statement
- The first #line directive
- A #pragma hdrstop directive
- After the named include file if you specify
-xpch=auto and -xpchstop
- The first include file if you specify -xpch=autofirst
Note: An end point within a conditional statement gen-
erates a warning and disables the automatic creation of
a precompiled-header file. Also, if you specify both
the #pragma hdrstop and the -xpchstop option, then the
compiler uses the earlier of the two stop points to
terminate 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.
Screening Header Files for Problems
What makes a header file precompileable? A header file
is precompileable when it is interpreted consistently
across different source files. Specifically, when it
contains only complete declarations. That is, a
declaration in any one file must stand alone as a valid
declaration. Incomplete type declarations, such as
struct S;, are valid declarations. The complete type
declaration can appear in some other file. Consider
these example header files:
file a.h
struct S {
#include "x.h" /* not allowed */
};
file b.h
struct T; // ok, complete declaration
struct S {
int i;
[end of file, continued in another file] /* not allowed
*/
A header file that is incorporated into a precompiled-
header file must not violate the following. The results
of compiling a program that violate any of these con-
straints is undefined.
- The header file must not use __DATE__ and __TIME__.
- The header file must not contain #pragma hdrstop.
The Precompiled-Header File Cache
When the compiler creates a precompiled-header file
automatically, the compiler writes it to the
SunWS_cache directory. This directory always resides in
the location where the object file is created. Updates
to the file are preformed under a lock so that it works
properly under dmake.
If you need to force the compiler to rebuild
automatically-generated precompiled-header files, you
can clear the precompiled-header file cache-directory
with the CCadmin tool. See the CCadmin(1) man page for
more information.
Warnings
o Do not specify conflicting -xpch flags on the command
line. For example, specifying both -xpch=collect and
-xpch=auto, or specifying both -xpch=autofirst with
-xpchstop=<include> generates an error.
o If you specify -xpch=autofirst or you specify
-xpch=auto without -xpchstop, any declaration, defini-
tion, or #line directive that appears prior to the
first include file, or appears prior to the include
file that is specified with -xpchstop for -xpch=auto,
generates a warning and disables the automatic genera-
tion of the precompiled-header file.
o A #pragma hdrstop before the first include file under
-xpch=autofirst or -xpch=auto disables the automatic
generation of the precompiled-header file.
Precompiled-Header File Dependencies and make Files
The compiler generates dependency information for
precompiled-header files when you specify
-xpch=collect. You need to create the appropriate rules
in your make files to take advantage of these dependen-
cies. Consider this sample make file:
%.o : %.c shared.cpch
$(cc) -xpch=use:shared -xpchstop=foo.h -c $<
default : a.out
foo.o + shared.cpch : foo.c
$(cc) -xpch=collect:shared -xpchstop=foo.h foo.c -c
a.out : foo.o bar.o foobar.o
$(c) foo.o bar.o foobar.o
clean :
rm -f *.o shared.cpch .make.state a.out
These make rules, along with the dependencies generated
by the compiler, force a manually created precompiled-
header file to be recreated if any source file you used
with -xpch=collect, or any of the headers that are part
of the precompiled-header file, have changed. This
prevents the use of an out of date precompiled-header
file.
For -xpch=auto or -xpch=autofirst, you do not have to
create any additional make rules in your makefiles.
See Also: -xpchstop
-xpchstop=[file|<include>]
where file is the last include file to be considered in
creating a precompiled-header file. Using -xpchstop on
the command line is equivalent to placing a hdrstop
pragma (See the C User's Guide) after the first
include-directive that references file in each of the
source files that you specify with the cc command.
Use -xpchstop=<include> with -xpch=auto to create a
precompiled-header file that is based on header files
up through and including <include>. This flag overrides
the default -xpch=auto behavior of using all header
files contained in the entire viable prefix.
See Also: -xpch, -xhelp=readme
-xpentium
(x86) Generates code for the Pentium processor.
-xpg Prepares the object code to collect data for profiling
with gprof(1). Invokes a runtime recording mechanism
that produces a gmon.out file (at normal termination).
Note: There is no advantage for -xprofile if you
specify -xpg. The two do not prepare or use data pro-
vided by the other.
Profiles are generated by using prof or gprof on 64 bit
Solaris platforms or just gprof on 32 bit Solaris plat-
forms include approximate user CPU times. These times
are derived from PC sample data (see pcsample(2)) for
routines in the main executable and routines in shared
libraries specified as linker arguments when the exe-
cutable is linked. Other shared libraries (libraries
opened after process startup using dlopen(3DL)) are not
profiled.
On 32 bit 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).
The Solaris 10 software does not include system
libraries compiled with -p. As a result, profiles col-
lected on Solaris 10 platforms do not include call
counts for system library routines.
If you specify -xpg at compile time, you must also
specify it at link time. See the C User's Guide for a
complete list of options that must be specified at both
compile time and link time.
-xprefetch[=val[,val]]
Enables prefetch instructions on those architectures
that support prefetch. You must compile withoptimiza-
tion level 3 orgreater with this option.
val must be one of the following:
auto Enable automatic generation of prefetch
instructions.
no%auto Disable automatic generation
explicit Enable explicit prefetch macros
Explicit prefetching should only be used
under special circumstances that are
supported by measurements.
no%explicit Disable explicit prefetch macros
latx:factor (SPARC) You can only combine this option
with -xprefetch=auto. Adjust the
compiler's assumed prefetch-to-load and
prefetch-to-store latencies by the
specified factor. The factor must be a
positive number of the form n.n .
The prefetch latency is the hardware
delay between the execution of a pre-
fetch 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 pre-
fetch and a store.
The compiler tunes the prefetch mechan-
ism for optimal performance across a
wide range of machines and applications.
This tuning may not always be optimal.
For memory-intensive applications, espe-
cially applications intended to run on
large multiprocessors, you may be able
to obtain better performance by increas-
ing 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 pro-
vide the maximum performance.
For applications with datasets 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 one.
To use the latx:factor suboption, start
with a factor value near 1.0 and run
performance tests against the applica-
tion. Then increase or decrease the fac-
tor, as appropriate, and run the perfor-
mance tests again. Continue adjusting
the factor and running the performance
tests until you achieve optimum perfor-
mance. 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.
yes Obsolete - do not use. Use
-xprefetch=auto,explicit instead.
no Obsolete - do not use. Use
-xprefetch=no%auto,no%explicit instead.
Defaults
If you do not specify -xprefetch, the default is now
-xprefetch=auto,explicit, not -xprefetch=yes. If you
specify -xprefetch without a value, it is also
equivalent to -xprefetch=auto,explicit. This change
adversely affects applications that have essentially
non-linear memory access patterns. To disable the
change, specify -xprefetch=no%auto,no%explicit.
The sun_prefetch.h header file provides the macros that
you can use to specify explicit prefetch instruction.
The prefetches will be approximately at the place in
the executable that corresponds to where the macros
appear.
-xprefetch_auto_type=[a]
Where a is [no%]indirect_array_access.
Use this option to determine whether or not the com-
piler generates indirect prefetches for the loops indi-
cated 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.
-xprefetch_level=l
Use this option to control the aggressiveness of
automatic insertion of prefetch instructions as deter-
mined with -xprefetch=auto.
l must be 1, 2, or 3.
Prefetch levels 2 and 3 may not be effective on older
SPARC and x86 platforms.
-xprefetch_level=1 enables automatic generation of pre-
fetch instructions. -xprefetch_level=2 enables addi-
tional generation beyond level 1 and -xprefetch=3
enables additional generation beyond level 2.
You must compile with optimization level 3 or greater
and generate code for a platform that supports pre-
fetch.
The default is -xprefetch_level=1 when you specify
-xprefetch=auto.
-xprofile=p
Collects data for a profile or use a profile to optim-
ize.
p must be collect[:name], use[:name], or tcov.
This option causes execution frequency data to be col-
lected and saved during execution, then the data can be
used in subsequent runs to improve performance. Profile
collection is safe for multithreaded applications. That
is, 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 optimi-
zation.
If compilation and linking are performed in separate
steps, the same -xprofile option must appear on the
compile as well as the link step.
collect[:name]
Collects and saves execution frequency for later
use by the optimizer with -xprofile=use. The com-
piler generates code to measure statement
execution-frequency.
Note: Do not specify -xprofile=collect when you
build shared libraries on Linux.
The name is optional. If name is not specified,
the name of the executible binary is used. a.out
is used if -o is not specified.
You can set the environment variables SUN_PROFDATA
and SUN_PROFDATA_DIR to control where a program
compiled with -xprofile=collect stores the profile
data. If set, the -xprofile=collect data is writ-
ten to SUN_PROFDATA_DIR/SUN_PROFDATA.
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 name.profile/feedback
in the current directory, where name is the name
of the executable or the name specified in the
-xprofile=collect:name flag. -xprofile does not
append .profile to name if name already ends in
.profile. If you run the program several times,
the execution frequency data accumulates in the
feedback file; that is, output from prior execu-
tions 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. For a complete list of compiler
options that must be specified at both compile
time and at link time, see the C User's Guide.
use[:name]
Uses execution frequency data to optimize strateg-
ically. The name is the name of the executable
that is being analyzed.
The name is optional. If name is not specified,
the name of the executible binary is used. a.out
is used if -o is not specified. The compiler looks
for name.profile/feedback, or
a.out.profile/feedback without name specified. For
example:
cc -xprofile=collect -o myexe prog.c
cc -xprofile=use:myexe -xO5 -o myexe prog.c
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 which in turn gen-
erated 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:name, the same program name name
must appear in the optimizing compilation:
-xprofile=use:name.
See also -xprofile_ircache for speeding up compi-
lation between collect and use phases.
tcov
Basic block coverage analysis using "new" style
tcov.
The -xprofile=tcov option is the new style of
basic block profiling for tcov. It has similar
functionality to the -xa option, but correctly
collects data for programs that have source code
in header files. See also -xa for information on
the old style of profiling, the tcov(1) man page,
and the Performance Analyzer manual for more
details.
Note: Do not specify -xprofile=collect when you
build shared libraries on Linux.
Code instrumentation is performed similarly to
that of the -xa option, but .d files are no longer
generated. instead, a single file is generated,
the name of which is based on the final execut-
able. for example, if the program is run out of
/foo/bar/myprog.profile, the data file is stored
in /foo/bar/myprog.profile/myprog.tcovd.
The -xprofile=tcov and the -xa options are compa-
tible in a single executable, that is, you can
link a program that contains some files that have
been compiled with -xprofile=tcov, and others with
-xa. You cannot compile a single file with both
options.
When running tcov, you must pass it the -x option
to make it use the new style of data. If not, tcov
uses the old .d files, if any, by default for
data, and produces unexpected output.
Unlike the -xa option, the TCOVDIR environment
variable has no effect at compile-time. However,
its value is used at program runtime. See
tcovf1(1) and the Performance Analyzer manual for
more details.
Note: tcov's code coverage report can be unreli-
able if functions are inlined due to the use of
-xO4 or higher optimization or -xinline.
When you use -xprofile=collect to compile a program for
profile collection and -xprofile=use to compile a pro-
gram for profile feedback, the source files and com-
piler options other than -xprofile=collect and
-xprofile=use must be identical in both compilations.
The profile feedback directory names specified by the
-xprofile=use:name option are accumulated from all
instances of the option in a single invocation of the
compiler. For example, assume that profile directories
a.profile, b.profile and c.profile are created as a
result of executing profiled binaries named a, b, and c
respectively.
cc -O -c foo.c -xprofile=use:a -xprofile=use:b
-xprofile=use:c
All three profile directories are used. Any valid pro-
file feedback data pertaining to a particular object
file is accumulated from the specified feedback direc-
tories when the object file is compiled.
If both -xprofile=collect and -xprofile=use are speci-
fied in the same command line, the rightmost -xprofile
option in the command line is applied as follows:
If the rightmost -xprofile option is -xprofile=use, all
profile feedback directory names specified by the
-xprofile=use options are used for feedback-directed
optimization, and the previous -xprofile=collect
options are ignored.
If the rightmost -xprofile option is -xprofile=collect,
all profile feedback directory names specified by
-xprofile=use options are ignored, and instrumentation
for profile generation is enabled.
-xprofile_ircache[=path]
(SPARC) Use -xprofile_ircache[=path] with
-xprofile=collect|use to improve compilation time dur-
ing 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 direc-
tories.
Here's a typical sequence of commands:
example% cc -xO5 -xprofile=collect -xprofile_ircache
t1.c t2.c
example% a.out // run collects feedback data
example% cc -xO5 -xprofile=use -xprofile_ircache t1.c
t2.c
-xprofile_pathmap=collect_prefix:use_prefix
(SPARC) Use the -xprofile_pathmap option when you are
also specifying the -xprofile=use command. Use
-xprofile_pathmap when both of the following are true
and the compiler is unable to find profile data for an
object file that is compiled with -xprofile=use.
o 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.
o Your object files share a common basename in the profile
but are distinguished from each other by their loca-
tion in different directories.
The collect-prefix is the prefix of the UNIX pathname
of a directory tree in which object files were compiled
using -xprofile=collect.
The use-prefix is the prefix of the UNIX pathname 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
pathname until either a matching use-prefix is identi-
fied or the last specified use-prefix is found not to
match the object file pathname.
-xreduction
Analyzes loops for reduction in automatic paralleliza-
tion. This option is valid only if one of -xautopar or
-xparallel is also specified. Otherwise the compiler
issues a warning.
When a reduction recognition is enabled, the compiler
parallelizes reductions such as dot products, maximum
and minimum finding. These reductions yield different
roundoffs from those obtained by unparallelized code.
-xregs=r[,r...]
Specify the usage of registers for the generated code.
r is a comma-separated list of one or more of the fol-
lowing: [no%]appl, [no%]float, [no%]frameptr.
Example: -xregs=appl,no%float
The -xregs values are for specific -xarch values:
[no%]appl (SPARC)
[Does not] 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)
It is strongly recommended that all system
software and libraries be compiled using
-xregs=no%appl. System software (including
shared libraries) must preserve these regis-
ters' 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 increase performance
because fewer load and store instructions are
needed. However, such use can conflict with
some old library programs written in assembly
code.
For more information on SPARC instruction
sets, see -xarch.
[no%]float (SPARC)
[Does not] 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, you need to use
-xregs=no%float and also make sure your code
does not use floating point types in any way.
[no%]frameptr (x86)
[Does not] Allow the compiler to use the
frame-pointer register (%ebp on IA32, %rbp on
x86 64-bit platforms) as an unallocated
callee-saves register.
Using this register as an unallocated callee-
saves register may improve program run time.
However, it also reduces the capacity of some
tools, such as the Performance Analyzer and
dtrace, to inspect and follow the stack. This
stack inspection capability is important for
system performance measurement and tuning.
Therefor, using this optimization may improve
local program performance at the expense of
global system performance.
Note: -xregs=frameptr is ignored and a warning
is issued by the compiler if you also specify
-xpg.
The SPARC default is -xregs=appl,float.
The x86 default is -xregs=no%frameptr. -xregs=frameptr
is included in the expansion of -fast.
It is strongly recommended that you compile code
intended for shared libraries that will link with
applications, with -xregs=no%appl,float. At the very
least, the shared library should explicitly document
how it uses the application registers so that applica-
tions linking with those libraries know how to cope
with the issue.
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.
-xrestrict[=f]
Treats pointer-valued function parameters as restricted
pointers. f is %all, %none or a comma-separated list of
one or more function names. This command-line option
can be used on its own, but is best used with optimiza-
tion of -xO3 or greater.
If a function list is specified with this option,
pointer parameters in the specified functions are
treated as restricted; if -xrestrict=%all is specified,
all pointer parameters in the entire C file are treated
as restricted.
The default is %none. Specifying -xrestrict is
equivalent to specifying -xrestrict=%all.
See Also: 'Restricted Pointers' in the C User's Guide
-xs Allows debugging by dbx without object files.
This option causes all the debug information to be
copied into the executable. This has little impact on
dbx performance or the run-time performance of the pro-
gram, but it does take more disk space.
-xsafe=mem
(SPARC) Allow 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.
Because non-faulting loads do not cause a trap when a
fault such as address misalignment or segmentation vio-
lation occurs, you should use this option only for pro-
grams 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.
This option takes effect only when used with optimiza-
tion level -xO5 and one of the following -xarch values:
sparc, sparcvis, or sparcvis2 for both -m32 and -m64.
-xsb Use this option to generate extra symbol table informa-
tion for the Source Browser. This option is not compa-
tible with the -Xs mode.
If you are compiling and linking in separate steps, be
sure to specify -xsb in both the compile step and the
link step otherwise you will see error messages from
the linker. For a complete list of compiler options
that must be specified at both compile time and at link
time, see the C User's Guide.
If you do not use -xsb to link objects that were com-
piled with -xsb, you limit the source browser data to
those references used by the executable that was
created with the link step. Also, if you do not specify
-xsb in separate compile and link steps, some symbol
references in the source browser database may be lost.
By including -xsb in both the compile step and the
separate link step, you ensure that all symbol refer-
ences in both objects are visible to the source browser
when the objects are compiled in different ways in the
same directory and linked with different executables.
-xsbfast
Create the database for the Source Browser, but do not
actually compile. This option is not valid with the -Xs
mode of the compiler.
-xsfpconst
Represents unsuffixed floating-point constants as sin-
gle precision, instead of the default mode of double
precision. Not valid with -Xc.
-xspace
Does no optimizations that increase code size. Does not
parallelize loops if it increases code size. Example:
Does not unroll loops.
-xstrconst
Inserts string literals into the read-only data section
of the text segment instead of the default data seg-
ment. Duplicate strings will be eliminated and the
remaining copy shared amongst references in the code.
-xtarget=t
Specifies the target system for the instruction set and
optimization.
t must be one of: native, native64, generic, generic64,
or system-name.
The -xtarget option permits a quick and easy specifica-
tion of the -xarch, -xchip, and -xcache combinations
that occur on real systems. The only meaning of -xtar-
get is in its expansion. See the -xdryrun explanation
for details on how to see the expansion of macro
options such as -xtarget.
-xtarget=native is equivalent to -m32, -xarch=native,
-xchip=native, -xcache=native.
-xtarget=native64 is equivalent to -m64,
-xarch=native64, -xchip=native64, -xcache=native.
-xtarget=generic is equivalent to -m32,
-xarch=generic, -xchip=generic, -xcache=generic.
-xtarget=generic64 is equivalent to -m64,
-xarch=generic64, -xchip=generic64, -xcache=generic.
The -fast macro option includes -xtarger=native in its
expansion.
The -xtarget command itself is a macro option which
acts like a macro expansion on the command line for the
-xarch -xchip and -xcache options. Therefore, you can
override any of the expanded options by following
-xtarget with the desired option. Use the -xdryrun
option to determine the expansion of -xtarget=native on
a running system.
Note: The expansion of -xtarget for a specific host
platform might not expand to the same -xarch, -xchip,
or -xcache settings as -xtarget=native when compiling
on that platform.
On SPARC platforms:
Compiling for 64-bit Solaris software on SPARC or
UltraSPARC V9 is indicated by the -m64 option. If you
specify -xtarget with a flag other than native64 or
generic64, you must also specify the -m64 option as
follows:
-xtarget=ultra ... -m64
otherwise the compiler uses a 32-bit memory model.
Value Meaning
native Set the parameters for the best performance
on the host environment (assumes a 32-bit
architecture).
native64 Set the parameters for the best performance
on the host environment (assumes a 64-bit
architecture).
generic This is the default and sets the parameters
for the best performance over most 32-bit
platform architectures.
generic64 Set the parameters for the best performance
over most 64-bit platform architectures.
system-name
Get the best performance for the specified
system.
Valid SPARC platform names are shown below.
Commonly used platform names:
ultra, ultra2, ultra2i, ultra1/140,
ultra1/170, ultra1/200, ultra2/1170,
ultra2/1200, ultra2/1300, ultra2/2170,
ultra2/2200, ultra2/2300, ultra2e, ultra2i,
ultra3, ultra3cu, ultra3i, ultra3iplus,
ultra4, ultra4plus, ultraT1, ultraT2,
sparc64vi.
The following target platforms are equivalent
to -xtarget=ultra:
entr2, entr2/1170, entr2/2170, entr2/1200,
entr2/2200, entr3000, entr4000, entr5000,
entr6000
Less commonly used platform names:
sun4/15, sun4/30, sslc, sslx, sslx2, ss4,
ss4/85, ss4/110, ss5, ss5/85, ss5/110,
ssvyger, ss10, ss10/hs11, ss10/hs12,
ss10/hs14, ss10/20, ss10/hs21, ss10/hs22,
ss10/30, ss10/40, ss10/41, ss10/50, ss10/51,
ss10/61, ss10/71, ss10/402, ss10/412,
ss10/512, ss10/514, ss10/612, ss10/712, ss20,
ss20/hs11, ss20/hs12, ss20/hs14, ss20/hs21,
ss20/hs22, ss20/50, ss20/51, ss20/61,
ss20/71, ss20/151, ss20/152, ss20/502,
ss20/512, ss20/514, ss20/612, ss20/712,
ss600/41, ss600/51, ss600/61, ss600/412,
ss600/512, ss600/514, ss600/612, ss1000,
sc2000, cs6400, solb6
On x86 platforms
Compiling for 64-bit Solaris software on 64-bit x86
platforms is indicated by the -m64 option. If you
specify -xtarget with a flag other than native64 or
generic64, you must also specify the -m64 option as
follows:
-xtarget=opteron ... -m64
otherwise the compiler uses a 32-bit memory model.
Value Meaning
o 386, 486
Obsolete. Do not use these flags. Use
-xtarget=generic instead. For a complete list
of obsolete options and flags, see the C
User's Guide.
o generic This is the default and yields the best per-
formance for generic architecture, chip and
cache on most 32-bit systems.
o generic64
Gets the best performance for generic archi-
tecture, chip and cache on most 64-bit sys-
tems.
o native The compiler generates code for the best per-
formance on the host system. This flag deter-
mines the available architecture, chip, and
cache properties of the machine on which the
compiler is running and assumes a 32-bit
architecture.
o native64
Set the parameters for the best performance
on the host system. This flag determines the
available architecture, chip, and cache pro-
perties of the machine on which the compiler
is running and assumes a 64-bit architecture.
o opteron Directs the compiler to generate code for the
best performance on the 32-bit AMD micropro-
cessor.
Note: The -xtarget=opteron option does not
automatically generate 64-bit code. You must
specify -m64 to compile 64-bit code.
o pentium Directs the compiler to generate code for the
best performance on the Pentium microproces-
sor.
o pentium_pro
Directs the compiler to generate code for the
best performance on the Pentium Pro micropro-
cessor.
o pentium3
Directs the compiler to generate code for the
best performance on the Pentium 3 micropro-
cessor.
o pentium4
Directs the compiler to generate code for the
best performance on the Pentium 4 micropro-
cessor.
Compiling for 64-bit Solaris software on SPARC on x86
platforms is indicated by the -m64 option. If you
specify -xtarget, the -m64 option must also appear, as
in:
-xtarget=ultra ... -m64
otherwise the compiler uses a 32-bit memory model.
See the section on -xtarget= t in the C User's Guide
for the -xtarget expansions that show the mnemonic
encodings of the actual system names and numbers.
-xtemp= dir
Sets the directory the compiler uses for temporary
files to dir. No space is allowed within this option
string. Without this option, temporary files go into
/tmp. -xtemp has precedence over the TMPDIR environment
variable.
-xthreadvar[=o]
Works in conjunction with the __thread declaration
specifier to take advantage of the compiler's thread-
local storage facility. After you declare the thread
variables with the __thread specifier, use -xthreadvar
to enable the use of thread-local storage with position
dependent code (non-PIC code) in dynamic (shared)
libraries. For more information on how to use __thread,
see the C User's Guide.
o must be the following:
Value Meaning
[no%]dynamic
[[Do not] Compile variables for dynamic load-
ing. Access to thread variables is signifi-
cantly faster when -xthreadvar=no%dynamic but
you cannot use the object file within a
dynamic library. That is, you can only use
the object file in an executable file.
If you do not specify -xthreadvar, the default used by
the compiler depends upon whether or not position-
independent code is enabled. If position-independent
code is enabled, the option is set to
-xthreadvar=dynamic. If position- independent code is
disabled, the option is set to -xthreadvar=no%dynamic.
If you specify -xthreadvar but do not specify any argu-
ments, the option is set to -xthreadvar=dynamic.
If there is non-position-independent code within a
dynamic library, you must specify -xthreadvar.
The linker cannot support the thread-variable
equivalent of non-PIC code in dynamic libraries. Non-
PIC thread variables are significantly faster, and
hence should be the default for executables.
If there is non-position-independent code within a
dynamic library, you must specify -xthreadvar.
Using thread variables on different versions of Solaris
software requires different options on the command
line.
On Solaris 9 software, objects that use __thread must
be compiled and linked with -mt.
See Also: -xcode, -KPIC, -Kpic
-xtime
Reports the time and resources used by each compila-
tion.
-xtransition
Issues warnings for differences between K&R C and ISO
C. The -xtransition option issues messages in conjunc-
tion with the -Xa and -Xt options. You can eliminate
all warning messages about differing behavior through
appropriate coding.
-xtrigraphs[=[yes|no)]]
Enables or disables recognition of trigraph sequences
as defined by the ISO C standard.
-xtrigraphs=yes enables recognition of trigraph
sequences in the source code.
-xtrigraphs=no disables recognition of trigraph
sequences in the source code.
Defaults:
If the -xtrigraphs option is not specified,
-xtrigraphs=no is assumed.
If only -xtrigraphs is specified -xtrigraphs=yes is
assumed.
-xunroll=n
Specifies whether or not the compiler optimizes
(unrolls) loops. n is a positive integer. When n is
1, it is a command and the compiler unrolls no loops.
When n is greater than 1, -xunroll=n allows the com-
piler to unroll loops n times.
-xustr={ascii_utf16_ushort|no}
Specify -xustr=ascii_utf16_ushort if you need to sup-
port an internationalized application that uses
ISO10646 UTF-16 string literals. In other words, use
this option if your code contains string literals that
you want the compiler to convert to UTF-16 strings in
the object file. Without this option, the compiler nei-
ther produces nor recognizes sixteen-bit character
string literals. This option enables recognition of the
U"ASCII_string" string literals as an array of unsigned
short int. Since such strings are not yet part of any
standard, this option enables recognition of non-
standard C.
You can turn off compiler recognition of
U"ASCII_string" string literals by specifying
-xustr=no. The rightmost instance of this option on the
command line overrides all previous instances.
The default is -xustr=no. If you specify -xustr without
an argument, the compiler won't accept it and instead
issues a warning. The default can change if the C or
C++ standards define a meaning for the syntax.
It is not an error to specify
-xustr=ascii_ustf16_ushort without also specifying a
U"ASCII_string" string literal.
Not all files have to be compiled with this option.
The following example shows a string literal in quotes
that is prepended by U. It also shows a command line
that specifies -xustr.
example% cat file.c
const unsigned short *foo = U"foo";
const unsigned short bar[] = U"bar";
const unsigned short *fun() { return
example% cc -xustr=ascii_utf16_ushort file.c -c
-xvector[=a]
Enables automatic generation of calls to the vector
library and/or the generation of the SIMD (Single
Instruction Multiple Data) instructions. You must use
default rounding mode by specifying -fround=nearest
when you use this option.
a is the equivalent of the following:
[no%]lib
Does [not]enable the compiler to transform math
library calls within loops into single calls to
the equivalent vector math routines when such
transformations are possible. This could result in
a performance improvement for loops with large
loop counts.
[no%]simd
Does [not]direct the compiler to use the native
x86 SSE SIMD instructions to improve performance
of certain loops. The compiler can only accept
this switch if the target architecture supports
SIMD instructions. For example, you must specify
-xarch=sse2 -m64 or -xarch=generic64. You must
also specify an optimization level of -xO3 or
above as well as -xdepend when you specify
-xvector=simd.
yes This option may be depricated in a future release.
Specify -xvector=lib instead.
no This option may be deprecated in a future release.
Specify -xvector=none instead.
The default is -xvector=%none. If you specify -xvector,
but do not provide a flag, the compiler assumes
-xvector=lib.
This option overrides previous instances so
-xvector=%none undoes a previously specified
-xvector=lib.
If you use -xvector on the command line without previ-
ously specifying -xdepend, -xvector triggers -xdepend.
The -xvector option also raises the optimization level
to -O3 if optimization is not specified or optimization
is set lower than -O3.
The compiler includes the libmvec libraries in the
load step. If you compile and link with separate com-
mands, be sure to use the same -xvector option in the
linking cc command. For a complete list of compiler
options that must be specified at both compile time and
at link time, see the C User's Guide.
-xvis
(SPARC) Use the -xvis=[yes|no] command when you are
using the assembly-language templates defined in the
VIS[tm] instruction set Software Developers Kit (VSDK).
The default is -xvis=no. Specifying -xvis is equivalent
to specifying -xvis=yes.
The VIS instruction set is an extension to the SPARC v9
instruction set. Even though the UltraSPARC processors
are 64-bit, there are many cases, especially in mul-
timedia applications, when the data are limited to
eight or 16 bits in size. The VIS instructions can pro-
cess four 16-bit data with one instruction so they
greatly improve the performance of applications that
handle new media such as imaging, linear algebra, sig-
nal processing, audio, video and networking.
For more information on the VSDK, see
http://www.sun.com/processors/vis/.
-xvpara
Show parallelization warning messages
Issues warnings about potential parallel programming
related problems that may cause incorrect results when
using OpenMP or Sun parallelization pragmas.
Use with -xopenmp and OpenMP API directives, or with
-explictpar and MP parallelization directives.
Warnings are issued when the compiler detects the fol-
lowing situations:
o Loops that are parallelized using MP directives when
there are data dependencies between different loop
iterations
o Problematic use of OpenMP data sharing attributes
clauses, such as declaring a variable "shared" whose
accesses in an OpenMP parallel region may cause data
race, or declaring a variable "private" whose value in
a parallel region is used after the parallel region.
No warnings appear if all parallelization directives
are processed without problems.
Example:
cc -xopenmp -vpara any.c
Note: Sun Studio compilers support OpenMP 2.5 API
parallelization. Consequently, the MP pragmas are
deprecated. See the OpenMP API User's Guide for infor-
mation on migrating to the OpenMP API.
-Yc, dir
Specifies a new directory dir for the location of com-
ponent c. c can consist of any of the characters
representing tools listed under the -W option.
If the location of a tool is being specified, then the
new path name for the tool will be dir/tool. If more
than one -Y option is applied to any one item, then
the last occurrence holds.
-YA, dir
Specifies a directory dir to search for all compiler
components. If a component is not found in dir, the
search reverts to the directory where the compiler is
installed.
-YI, dir
Changes default directory searched for include files.
-YP, dir
Changes default directory for finding libraries files.
-YS, dir
Changes default directory for startup object files.
-Zll (SPARC) Creates the program database for lock_lint, but
does not generate executable code.
cc recognizes -a, -e, -r, -t, -u, and -z and passes these
options and their arguments to ld. cc also passes any
unrecognized options to ld with a warning.
NOTES
If you specify -fast, you should not rely on the value of
errno because the value can change as a result of code
optimization. The easiest way to avoid this problem is to
not specify -fast.
If, however, you specify -fast and you are relying on the
value of errno, do the following:
o Do not link with the math optimization library by speci-
fying -lmopt.
o Specify -xbuiltin=none, -U__MATHERR_ERRNO_DONTCARE, -xno-
libmopt, and -xnolibmil.
PRAGMAS
The following #pragmas are recognized by the compilation
system:
#pragma align
#pragma c99
#pragma does_not_read_global_data
#pragma does_not_return
#pragma does_not_write_global_data
#pragma error_messages
#pragma fini
#pragma hdrstop
#pragma ident
#pragma init
#pragma [no_]inline
#pragma [no_]warn_missing_parameter
#pragma int_to_unsigned
#pragma opt
#pragma pack
#pragma rarely_called
#pragma redefine_extname
#pragma returns_new_memory
#pragma struct_align
#pragma unknown_control_flow
#pragma weak
See also the OpenMP API User's Guide for a list of supported
OpenMP 2.5 directives.
SPARC Only:
#pragma nomemorydepend
#pragma no_side_effect
#pragma pipeloop
#pragma unroll
Refer to the C User's Guide for more information on these
pragmas.
ENVIRONMENT
The following is a list of environment variables that you
can set along with a brief description of their function.
OMP_DYNAMIC
Enable or disable dynamic adjustment of the number
of threads.
OMP_NESTED
Enable or disable nested parallelism. See the
OpenMP API User's Guide.
OMP_NUM_THREADS
This variable tells the runtime system the maximum
number of threads the program can create. See the
OpenMP API User's Guide.
OMP_SCHEDULE
Set the run-time schedule type and chunk size. See
the OpenMP API User's Guide.
PARALLEL Same as OMP_NUM_THREADS.
STACKSIZE The executing program maintains a main memory
stack for the master thread and distinct stacks
for each slave thread. Stacks are temporary memory
address spaces used to hold arguments and
automatic variables over subprogram invocations.
The default size of the main stack is about eight
megabytes. Use the limit(1) command to display the
current main stack size as well as set it.
Each slave thread of a multithreaded program has
its own thread stack. This stack mimics the main
stack of the master thread but is unique to the
thread. The thread's private arrays and variables
(local to the thread) are allocated on the thread
stack.
All slave threads have the same stack size, which
is four megabytes for 32-bit applications and
eight megabytes for 64-bit applications by
default. The size is set with the STACKSIZE
environment variable.
Setting the thread stack size to a value larger
than the default may be necessary for some paral-
lelized code.
The syntax of the STACKSIZE environment variable
accepts a keyword for denoting the slave thread
stacksize: B for Bytes, K for Kilobytes, M for
Megabytes, G for Gigabytes.
For example, setenv STACKSIZE 8192 sets the slave
thread stack size to 8 MB. 1235B sets the slave
thread stack size for 1235 Bytes. 1235G sets it
for 1235 Gigabytes. The default for an integer
value without a suffix letter is still Kilobytes.
Sometimes the compiler may generate a warning mes-
sage that indicates a bigger stack size is needed.
However, it may not be possible to know just how
large to set it, except by trial and error, espe-
cially if private/local arrays are involved. If
the stack size is too small for a thread to run,
the program will abort with a segmentation fault.
TMPDIR cc normally creates temporary files in the direc-
tory /tmp. You may specify another directory by
setting the environment variable TMPDIR to your
chosen directory. (If TMPDIR isn't a valid direc-
tory, then cc will use /tmp). The -xtemp option
has precedence over the TMPDIR environment vari-
able.
SUNPRO_SB_INIT_FILE_NAME
The absolute path name of the directory that con-
tains the .sbinit(5) file. This variable is used
only if the -xsb or -xsbfast flag is used.
SUNPROF_DATA
Controls the name of the file in which the
-xprofile=collect command stores execution-
frequency data.
SUNPROF_DATA_DIR
Controls in which directory the -xprofile=collect
command places the execution-frequency data-file.
SUNW_MP_THR_IDLE
Controls end-of-task status of each helper thread
and can be set to spin or sleep ns. The default is
sleep. See the OpenMP API User's Guide for
details.
SUNW_MP_WARN
Set this environment variable to TURE to print
warning messages from the OpenMP and other paral-
lelization runtime-systems. If you registered a
function by using sunw_mp_register_warn() to han-
dle warning messages, then SUNW_MP_WARN prints no
warning messages, even if you set it to TRUE. If
you did not register a function and set
SUNW_MP_WARN to TRUE, SUNW_MP_WARN prints the
warning messages to stderr. If you do not register
a function and you do not set SUNW_MP_WARN, no
warning messages are issued. For more information
on sunw_mp_register_warn() see the C User's Guide.
FILES
a.out executable output file
bb_link.o tcov support
file.a library of object files
file.c C source file
file.d tcov(1) test coverage input file
file.i C source file after preprocessing
file.il inline(1) expansion file
file.ll lock_lint database
file.o object file
file.profile The directory for data used by -xprofile
file.s assembler source file
file.so dynamic library
file.tcov output from tcov(1)
acomp compiler front end
cc compiler command line driver
cg code generator (SPARC)
crt1.o runtime startup code
crti.o runtime startup code
crtn.o runtime startup code
fbe assembler
gcrt1.o startup for profiling with gprof(1)
gmon.out default profile file for -xpg
ipo Interprocedural optimizer (SPARC)
ir2hf intermediate code translator (x86)
iropt global optimizer
libldstab_ws.so
sbfocus locator
libredblack.so bids support
mcrt1.o start-up for profiling with prof(1) and
intro(3)
misalign.o misalign data support (SPARC)
mon.out default profile file for -p
postopt postoptimizer (SPARC)
ssbd Static synchronization bug detection (Solaris
Operating Environment)
stack_grow.o stack overflow checking (SPARC)
SunWS_cache The directory used to store sbrowser(1) data
when the -xsb or -xsbfast flag is used.
ube optimizer, code generator (x86)
ube_ipa Interprocedural analyzer (x86)
values-xa.o -Xa support
values-xc.o -Xc support
values-xpg4.o xpg4 support
values-xpg6.o SUSv3 support
values-xs.o -Xs support
values-xt.o -Xt support
SEE ALSO
analyzer(1), as(1), c89(1), c99(1), cflow(1), cscope(1),
ctags(1), ctrace(1), dbx(1), er_src(1), indent(1),
inline(1), ld(1), lint(1), lock_lint(1), prof(1),
sbquery(1), sunstudio(1), tmpnam(3S), version(1).
C User's Guide
OpenMP API User's Guide
The ISO/IEC 9899-1990 Programming Language - C standard,
The ISO/IEC 9899-1999 Programming Language - C standard,
The Math Libraries readme in install_path/SUNWspro/READMEs
where install_path is usually /opt.