B.2 The cc Options

This section describes the cc options, arranged alphabetically. These descriptions are also available in the man page, cc(1). Use the cc -flags option for a one-line summary of these descriptions.

Options noted as being unique to one or more platforms are accepted without error and ignored on all other platforms. For an explanation of the typographic notations used with the options and arguments, refer to Typographic Conventions.

B.2.1 -#

Turns on verbose mode, showing how command options expand. Shows each component as it is invoked.

B.2.2 -###

Shows each component as it would be invoked, but does not actually execute it. Also shows how command options would expand.

B.2.3 -Aname[(tokens)]

Associates 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)

These preassertions are not valid 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.2.4 -B[static|dynamic]

Specifies whether bindings of libraries for linking are static or dynamic, indicating whether libraries are non-shared or shared, respectively.

–Bdynamic causes the link editor to look for files named libx.so and then for files named libx.a when given the -lx option.

–Bstatic 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. This option and its argument are passed to ld(1).

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 the linker.

B.2.5 -C

Prevents the C preprocessor from removing comments, except those on the preprocessing directive lines.

B.2.6 -c

Directs the C compiler to suppress linking with ld(1) and to produce a .o file for each source file. You can explicitly name a single object file using the-o option. When the compiler produces object code for each .i or .c input file, it always creates an object (.o) file in the current working directory. If you suppress the linking step, you also suppress the removal of the object files.

B.2.7 -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 (not valid in-Xc mode):

• sun

• unix

• sparc (SPARC)

• i386 (x86)

The following predefinitions are valid in all modes.

• __BUILTIN_VA_ARG_INCR

• __SUNPRO_C=0x590

• __SVR4 (SPARC)

• __SunOS (Solaris Operating System)

• __SunOS_n_n (Solaris Operating System)

• __amd64 ( x86 with -m64)

• __gnu__linux (linux)

• __i386 (x86)

• __linux (linux)

• __linux__ (linux)

• __sparc (SPARC)

• __sparcv9 (-xarch=v9, v9a, v9b)

• __sun (Solaris Operating System)

• __unix

• __SunOS_n_n (Solaris Operating System) (example: __SunOS_5_9)

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.

B.2.8 -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 arguments are passed to ld(1).

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

B.2.9 -dalign

(SPARC) Obsolete. You should not use this option. Use -xmemalign=8s instead. See B.2.111 -xmemalign=ab for more information. For a complete list of obsolete options, see A.1.15 Obsolete Options.

B.2.10 -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 the– P option.

B.2.11 -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.

If you do not specify this option, the compiler sets it to -errfmt=no%error. If you specify -errfmt, but do not supply a value, the compiler sets it to -errfmt=error.

B.2.12 -erroff[=t]

This command suppresses C compiler warning messages and 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.

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

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. See 2.8.6 error_messages.

B.2.13 -errshort[=i]

Use this option to control how much detail is in the error message produced by the compiler when it discovers 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:

If you do not specify -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.

B.2.14 -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.

B.2.15 -errwarn[=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 cc 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 following table details the -errwarn values:

The default is -errwarn=%none. If you specify -errwarn alone, it is equivalent to -errwarn=%all.

B.2.16 -fast

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

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 information, see B.2.99 -xlibmopt.

The -fast option impacts the value of errno. See 2.10 The Value of errno for more information.

Modules that are compiled with -fast must also be linked with -fast. For a complete list of all compiler options that must be specified at both compile time and at link time, see A.1.2 Compile-Time and Link-Time Options.

The –fast option is unsuitable for programs intended to run on a different target than the compilation machine. In such cases, follow -fast with the appropriate -xtarget option. For example:

cc -fast -xtarget=ultra ...

For C modules that depend on exception handling specified by SUID, follow -fast by -xnolibmil:

% cc -fast -xnolibmil

With -xlibmil, exceptions cannot be noted by setting errno or calling matherr(3m).

The –fast option is unsuitable for programs that require strict conformance to the IEEE 754 Standard.

The following table lists the set of options selected by -fast across platforms.

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.

The optimizations performed by these options may alter the behavior of programs from that defined by the ISO C and IEEE standards. See the description of the specific option for details.

–fast acts like a macro expansion on the command line. Therefore, you can override the optimization level and code generation option aspects by following -fast with the desired optimization level or code generation option. Compiling with the -fast -xO4 pair is like compiling with the -xO2 -xO4 pair. The latter specification takes precedence.

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.

B.2.17 -fd

Reports K&R-style function definitions and declarations.

B.2.18 -features=[[no%]extinl|%none]

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 (created with Sun compilers prior to this release) can be linked with new C and C++ objects with no change of behavior for the old objects. To get standard conforming behavior, you must recompile old code with the current compiler.

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

B.2.19 -flags

Prints a brief summary of each available compiler option.

B.2.20 -flteval[={any|2}]

(x86) Use this option to control how floating point expression are evaluated.

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 combination with -flteval=2:

• -fprecision

• -nofstore

• -xarch=amd64

• -xarch=sse2

See also D.1.1 Precision of Floating Point Evaluators.

B.2.21 -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 instructions are generated in order to prevent the program from executing on platforms that do not support them.

B.2.22 -fnonstd

(SPARC) This option is a macro for -fns and -ftrap=common.

B.2.23 -fns[={no|yes}]

• (SPARC) Turns on the SPARC nonstandard floating-point mode.

  The default is -fns=no, the SPARC standard floating-point mode. -fns is the same as -fns=yes.

  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.

  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 replaced silently 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 arithmetic may produce results that do not conform to the requirements of the IEEE 754 standard. See the Numerical Computation Guide for more information.

  This option is effective only on SPARC systems and only if used when compiling the main program. On x86 systems, the option is ignored.

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

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

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

B.2.24 -fprecision=p

(x86) -fprecision={single, double, extended}

Initializes the rounding-precision mode bits in the Floating-point Control Word to 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.

B.2.25 -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 sets the rounding direction mode 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.

B.2.26 -fsimple[=n]

Allows the optimizer to make simplifying assumptions concerning floating-point arithmetic.

The compiler defaults to -fsimple=0. Specifying -fsimple, is equivalent to -fsimple=1.

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

Even with -fsimple=2, the optimizer is not permitted to introduce a floating point exception in a program that otherwise produces none.

See Techniques for Optimizing Applications: High Performance Computing written by Rajat Garg and Ilya Sharapov for a more detailed explanation of how optimization can impact precision.

B.2.27 -fsingle

(-Xt and -Xs modes only) Causes the compiler to evaluate 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.

B.2.28 -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 expression 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 a register. Due to rounding and truncation, the results may be different from those that are generated from the register value. This is the default mode.

To turn off this option, use the -nofstore option.

B.2.29 -ftrap=t[,t...]

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

t can be one of the following values.

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

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

Example: –ftrap=%all,no%inexact means to 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 might get unexpected results.

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

x = 1.0 / 3.0;

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

B.2.30 -G

Produce a shared object rather than a dynamically linked executable. This option is passed to ld(1), 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 specified 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 in B.2.80 -xcode[=v].

B.2.31 -g

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

If you specify -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 specify -g and the optimization level is -xO4, 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.

In previous releases, this option forced the compiler 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.

For more information on debugging, see the Debugging a Program With dbx manual.

B.2.32 -H

Prints to standard error, one per line, the path name of each file included during the current compilation. The display is indented so as to show which files are included by other files.

Here, the program sample.c includes the files, stdio.h and math.h; math.h includes the file, floatingpoint.h, which itself includes functions that use sys/ieeefp.h:

% cc -H sample.c
    /usr/include/stdio.h
    /usr/include/math.h
        /usr/include/floatingpoint.h
            /usr/include/sys/ieeefp.h

B.2.33 -h name

Assigns a name to a shared dynamic library as a way to have different versions of a library. In general, the name after -h should be the same as the file name given after 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 intrinsic name of the library. If there is no -hname option, then no intrinsic name is recorded in the library file.

When the runtime linker loads the library into an executable 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.

B.2.34 -I[-|dir]

-I dir adds dir to the list of directories that are searched for #include files with relative file names prior to /usr/include, that is, those directory paths not beginning with a / (slash).

Directories for multiple -I options are searched in the order specified.

For more information on the search pattern of the compiler, see 2.14.1 Using the -I- Option to Change the Search Algorithm.

B.2.35 -i

Passes the option to the linker to ignore any LD_LIBRARY_PATH or LD_LIBRARY_PATH_64 setting.

B.2.36 -KPIC

(SPARC) Obsolete. You should not use this option. Use -xcode=pic32 instead.

For more information, see B.2.80 -xcode[=v]. For a complete list of obsolete options, see A.1.15 Obsolete Options.

(x86) -KPIC is identical to -Kpic.

B.2.37 -Kpic

(SPARC) Obsolete. You should not use this option. Use -xcode=pic13 instead. For more information, see B.2.80 -xcode[=v]. For a complete list of obsolete options, see A.1.15 Obsolete Options.

(x86) Generate position-independent code for use in shared libraries (small model). Permits references to, at most, 2**11 unique external symbols.

B.2.38 -keeptmp

Retains temporary files created during compilation instead of deleting them automatically.

B.2.39 -Ldir

Adds dir to the list of directories searched for libraries by ld(1). This option and its arguments are passed to ld(1).

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

B.2.40 -lname

Links with object library libname.so, or libname.a. The order of libraries in the command-line is important, as symbols are resolved from left to right.

This option must follow the sourcefile arguments.

B.2.41 -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.

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

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 Studio 12 compilers, this is no longer the case. On most platforms, just adding -m64 to the command line is sufficient to create 64-bit objects.

On Solaris, -m32 is the default. On Linux systems supporting 64-bit programs, -m64 -xarch=sse2 is the default.

See also -xarch.

B.2.42 -mc

Removes duplicate strings from the .comment section of the object file. When you use the -mc flag, mcs -c is invoked.

B.2.43 -misalign

(SPARC) Obsolete. You should not use this option. Use the -xmemalign=1i option instead. For more information, see B.2.111 -xmemalign=ab. For a complete list of obsolete options, see A.1.15 Obsolete Options.

B.2.44 -misalign2

(SPARC) Obsolete. You should not use this option. Use the -xmemalign=2i option instead. For more information, see B.2.111 -xmemalign=ab. For a complete list of obsolete options, see A.1.15 Obsolete Options.

B.2.45 -mr[,string]

-mr removes all strings from the .comment section. When you use this flag, mcs -d -a is invoked.

-mr,string removes all strings from the .comment section and inserts string in that section of the object file. If string contains embedded blanks, it must be enclosed in quotation marks. A null string results in an empty .comment section. This option is passed as -d -astring to mcs.

B.2.46 -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 libthread.

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 multithreaded application.

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

If you compile one translation unit with -mt, compile all units of the program with -mt.

See also B.2.113 -xnolib.

B.2.47 -native

This option is a synonym for -xtarget=native.

B.2.48 -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. See also B.2.28 -fstore.

B.2.49 -O

Use default optimization level -xO3. The -O macro now expands to -xO3 instead of -xO2.

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

B.2.50 -o filename

Names the output file filename (as opposed to the default, a.out). filename cannot be the same as sourcefile, since cc does not overwrite the source file. This option and its arguments are passed to ld(1).

B.2.51 -P

Runs the source file through the C preprocessor only. It then puts the output in a file with a .i suffix. Unlike -E, this option does not include preprocessor-type line number information in the output. See also the -E option.

B.2.52 -p

Obsolete, see B.2.127 -xpg.

B.2.53 -Q[y|n]

Emits or does not emit identification information to the output file. -Qy is the default.

If -Qy is used, identification information about each invoked compilation tool is added to the .comment section of output files, which is accessible with mcs. This option can be useful for software administration.

-Qn suppresses this information.

B.2.54 -qp

Same as -p.

B.2.55 -Rdir[:dir]

Passes 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.

B.2.56 -S

Directs cc to produce an assembly source file but not to assemble the program.

B.2.57 -s

Removes all symbolic debugging information from the output object file. This option cannot be specified with -g.

Passed to ld(1).

B.2.58 -Uname

Undefines the preprocessor symbol name. This option removes any initial definition of the preprocessor symbol name created by -D on the same command line including those placed there by the command-line driver.

-U has no effect on any preprocessor directives in source files. You can give multiple -U options on the command line.

If the same name is specified for both -D and -U on the command line, name is undefined, regardless of the order the options appear. In the following example, -U undefines __sun:

cc -U__sun text.c

Preprocessor statements of the following form in test.c will not take effect because __sun is undefined.

#ifdef(__sun)

See B.2.7 -Dname[(arg[,arg])][=expansion] for a list of predefined symbols.

B.2.59 -V

Directs cc to print the name and version ID of each component as the compiler executes.

B.2.60 -v

Directs the compiler to perform stricter semantic checks and to enable other lint-like checks. For example, the code:

#include <stdio.h>
main(void)
{
     printf("Hello World.\n");
}

compiles and executes without problem. With -v, it still compiles; however, the compiler displays this warning:

"hello.c", line 5: warning: function has no return statement:
 main

-v does not give all the warnings that lint(1) does. Try running the above example through lint.

B.2.61 -Wc,arg

Passes the argument arg to a specified component c. See Table 1–1 for a list of components.

Each argument must be separated from the preceding only by a comma. All -W arguments are passed after the regular command-line arguments. A comma can be part of an argument by using the escape character \ (backslash) immediately before the comma. All -W arguments are passed after the regular command-line arguments.

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.

c can be one of the following:

B.2.62 -w

Suppresses compiler warning messages.

This option overrides the error_messages pragma.

B.2.63 -X[c|a|t|s]

The -X (note uppercase X) options specify varying degrees of compliance to the ISO C standard. The value of -xc99 affects which version of the ISO C standard the -X option applies. The -xc99 option defaults to -xc99=all which supports the 1999 ISO/IEC C standard. -xc99=none supports the 1990 ISO/IEC C standard. See Table C–6 for a discussion of supported 1999 ISO/IEC features. See G.2 The libfast.a Library for a discussion of differences between ISO/IEC C and K&R C.

The default mode is -Xa.

-Xc

(c = conformance) Issues errors and warnings for programs that use non-ISO C constructs. This option is strictly conformant ISO C, without K&R C compatibility extensions. The predefined macro __STDC__ has a value of 1 with the-Xc option.

-Xa

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 -xtransition option, the compiler issues warnings about the different semantics. The predefined macro __STDC__has a value of -0 with the-Xa option.

-Xt

(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 0 with the -Xt option.

-Xs

(s = K&R C) Attempts to warn about all language constructs that have differing behavior between ISO C and K&R C. The compiler language includes all features compatible with K&R C. This option invokes cpp for preprocessing. __STDC__ is not defined in this mode.

B.2.64 -x386

(x86) Obsolete. You should not use this option. Use -xchip=generic instead. For a complete list of obsolete options, see A.1.15 Obsolete Options.

B.2.65 -x486

(x86) Obsolete. You should not use this option. Use -xchip=generic instead. For a complete list of obsolete options, see A.1.15 Obsolete Options.

B.2.66 -xa

Obsolete. Do not use this option. Use -xprofile=tcov instead. For a complete list of obsolete options and flags, see A.1.15 Obsolete Options.

B.2.67 -xalias_level[=l]

The compiler uses the -xalias_level option to determine what assumptions it can make in order to perform optimizations using type-based alias-analysis. This option places the indicated alias level into effect for the translation units being compiled.

If you do not specify the -xalias_level command, the compiler assumes -xalias_level=any. If you specify -xalias_level without a value, the default is -xalias_level=layout.

The -xalias_level option requires optimization level -xO3 or above. If optimization is set lower, a warning is issued and the -xalias_level option is ignored.

Remember that if you issue the -xalias_level option but you fail to adhere to all of the assumptions and restrictions about aliasing described for any of the alias levels, the behavior of your program is undefined.

Replace l with one of the terms in the following table.

B.2.68 -xarch=isa

Specify instruction set architecture (ISA). If you use this option with optimization, the appropriate choice can provide good performance of the executable on the specified architecture. An inappropriate choice results in a binary program that is not executable on the intended target platform.

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

If you compile and link in separate steps, make sure you specify the same value for -xarch in both steps. For a complete list of all compiler options that must be specified at both compile time and at link time, see Table A–2.

Although-xarch can be used alone, it is part of the expansion of the-xtarget option and may be used to override the-xarch value that is set by a specific-xtarget option. For example:

% cc -xtarget=ultra2 -xarch=v8plusb ...

overrides the-xarch=v8 set by-xtarget=ultra2.

B.2.68.1 -xarch Flags for SPARC

The following table details the performance of an executable that is compiled with a given-xarch option and then executed by various SPARC processors. The purpose of this table is to help you identify the best-xarch option for your executable given a particular target machine. Start by identifying the range of machines that are of interest to you and then consider the cost of maintaining multiple binaries versus the benefit of extracting the last iota of performance from newer machines.

• N reflects Nominal performance. The program executes and takes full advantage of the processor’s instruction set.

• S reflects Satisfactory performance. The program executes but may not exploit all available processor instructions.

• PD reflects Performance Degradation. The program executes, but depending on the instructions used, may experience slight to significant performance degradation. The degradation occurs when instructions that are not implemented by the processor are emulated by the kernel.

• NE means Not Executable. The program will not execute because the kernel does not emulate the instructions that are not implemented by the processor.

If you are compiling your executable with the v8plus or v8plusa instruction set, consider compiling with v9 or v9a instead. The v8plus and v8plusa options are provided so that programs can take advantage of some SPARC V9 and UltraSPARC features prior to the availability of Solaris 8 software with its support for 64-bit programs. Programs compiled with the v8plus or v8plusa option are not portable to SPARC V8 or older machines. You can recompile such programs with v9 or v9a, respectively, to take full advantage of all the features of SPARC V9 and UltraSPARC. The V8+ Technical Specification white paper, part number 802-7447-10, is available through your Sun representative and explains the limitations of v8plus and v8plusa.

• SPARC instruction set architectures V8 and V8a are binary compatible.

• Object binary files (.o) compiled with v8plus and v8plusa can be linked and can execute together, but only on a SPARC V8plusa compatible platform.

• Object binary files (.o) compiled with v8plus, v8plusa, and v8plusb can be linked and can execute together, but only on a SPARC V8plusb compatible platform.

• -xarch values v9, v9a, and v9b are only available on UltraSPARC 64-bit Solaris operating systems.

• Object binary files (.o) compiled with v9 and v9a can be linked and can execute together, but will run only on a SPARC V9a compatible platform.

• Object binary files (.o) compiled with v9, v9a, and v9b can be linked and can execute together, but will run only on a SPARC V9b compatible platform.

For any particular choice, the generated executable may run much more slowly on earlier architectures. Also, although quad-precision (REAL*16 and long double) floating-point instructions are available in many of these instruction set architectures, the compiler does not use these instructions in the code it generates.

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

B.2.68.2 -xarch Flags for x86

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

Special x86 Notes

There are some important issues to be aware of when compiling for x86 Solaris platforms.

The legacy Sun-style parallelization pragmas are not available on x86. Use OpenMP instead. See the Sun Studio 12: 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 using the same -xarch setting to ensure that the correct startup routine is linked.

Numerical results on x86 may 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 platforms 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 extensions.

B.2.68.3 The SPARC Default

The default architecture for which the C compiler produces code is now v8plus (UltraSPARC). Support for v7 will be dropped in a future release.

The new default yields higher run-time performance for nearly all machines in current use. However, applications that are intended for deployment on pre-UltraSPARC computers no longer execute by default on those computers. Compile with -xarch=v8 to ensure that the applications execute on those computers.

If you want to deploy on v8 systems, you must specify the option -xarch=v8 explicitly on every compiler command line as well as any link-time commands. The provided system libraries run on v8 architectures.

If you want to deploy on v7 systems, you must specify the option -xarch=v7 explicitly on every compiler command line as well as any link-time commands. The provided system libraries use the v8 instruction set. For this release, the only supported operating system for v7 is the Solaris 8 software. When a v8 instruction is encountered, the Solaris 8 operating system interprets the instruction in software. The program runs, but performance is degraded.

B.2.68.4 The x86 Default

For x86, -xarch defaults to generic. Note that -fast on x86 expands to -xarch=native. This option limits the code generated by the compiler to the instructions of the specified instruction set architecture. This option does not guarantee use of any target–specific instructions. However, use of this option may affect the portability of a binary program.

B.2.69 -xautopar

This option does not accept OpenMP parallelization directives. The Sun-specific MP pragmas have been deprecated and are no longer supported. See the Sun Studio 12: OpenMP API User’s Guide for migration information to the directives of the standard.

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

Avoid-xautopar if you do your own thread management.

To achieve faster execution, this option requires a multiple 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 environment variable prior to execution. See the Sun Studio 12: 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 also link with-xautopar. For a complete list of all compiler options that must be specified at both compile time and at link time, see Table A–2.

B.2.70 -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 optimized, transformed or analyzed.

Compiling with -xbinopt=prepare and -g increases the size of the executable by including debugging information. The default is -xbinopt=off.

B.2.71 -xbuiltin[=(%all|%none)]

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 substitution.

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 also 2.10 The Value of errno.

If you do not specify -xbuiltin, the default is -xbuiltin=%none, which means no functions from the standard libraries are substituted or inlined. If you specify -xbuiltin, but do not provide any argument, the default is -xbuiltin%all, which means the compiler substitutes intrinsics or inlines standard library functions as it determines the optimization benefit.

If you compile with -fast, then -xbuiltin is set to %all.

-xbuiltin only inlines global functions defined in system header files, never static functions defined by the user.

B.2.72 -xCC

When you specify -xc99=none and -xCC, the compiler accepts the C++-style comments. In particular, // can be used to indicate the start of a comment.

B.2.73 -xc99[=o]

The -xc99 option 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 following:

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.

Though the compiler support-level defaults to the language features of the C99 standard, the standard headers provided by the Solaris 8 and Solaris 9 operating systems in /usr/include do not conform with the 1999 ISO/IEC C standard. If you encounter error messages, try specifying -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 8 and Solaris 9 software. The compiler issues an error message when you specify -xc99=lib directly or indirectly on Solaris 8 or Solaris 9 software.

B.2.74 -xcache[=c]

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

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 release introduces an optional property [/ti] which sets the number of threads that can share the cache. If you do not specify a value for t, the default is 1.

c must be one of the following:

• generic

• native

• s1/l1/a1[/t1]

• s1/l1/a1[/t1]:s2/l2/a2[/t2]

• s1/l1/a1[/t1]:s2/l2/a2[/t2]:s3/l3/a3[/t3]

The s/l/a/t properties are defined as follows:

The following table lists the-xcache values.

Example:-xcache=16/32/4:1024/32/1 specifies the following:

B.2.75 –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 generates code that runs slower on current SPARC platforms. Use -O instead and take advantage of compiler defaults for -xarch, -xchip, and -xcache.

B.2.76 -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 substitute one of the following for o:

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 particular, 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 so that it does not depend on whether type char is signed or unsigned. The sign of type char varies among compilers and operating systems.

B.2.77 -xchar_byte_order[=o]

Produce an integer constant by placing the characters of a multi-character character-constant in the specified byte order. You can substitute one of the following values for o:

• low: place the characters of a multi-character character-constant in low-to-high byte order.

• high: place the characters of a multi-character character-constant in high-to-low byte order.

• default: place the characters of a multi-character character-constant in an order determined by the compilation mode B.2.63 -X[c|a|t|s]. For more information, see 2.1.2 Character Constants.

B.2.78 -xcheck[=o]

(SPARC) Compiling with -xcheck=stkovf adds 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).

You can substitute one of the following values for o:

If you do not specify -xcheck, the compiler defaults to-xcheck=%none. If you specify -xcheck without any arguments, 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.

B.2.79 -xchip[=c]

Specifies the target processor for use by the optimizer.

c must be one of the following: generic, old, super, super2, micro, micro2, hyper, hyper2, powerup, ultra, ultra2, ultra2e, ultra2i, ultra3, ultra3cu, pentium, pentium_pro.

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:

• The ordering of instructions, that is, scheduling

• The way the compiler uses branches

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

The following table lists the -xchip values for SPARC platforms:

The following table lists the -xchip values for the x86 platforms:

B.2.80 -xcode[=v]

(SPARC) Specify code address space.

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.

v must be one of:

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

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

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

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

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

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

% nm file.o | grep _GLOBAL_OFFSET_TABLE_ U _GLOBAL_OFFSET_TABLE_

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

To determine whether to use– xcode=pic13 or– xcode=pic32, 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:

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

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

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

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

B.2.81 -xcrossfile[=n]

Enables optimization and inlining across source files. If specified, n can be 0 or 1.

The default is -xcrossfile=0 which specifies that no crossfile optimizations are performed. -xcrossfile is equivalent to -xcrossfile=1.

Consider the following 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.

Normally the scope of the compiler’s analysis is limited to each separate file on the command line. For example, -xO4’s automatic inlining is limited to subprograms 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 concatenated into a single source file. -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 interdependent due to possible inlining, and must be used as a unit when they are linked into a program. If any one routine is changed and the files recompiled, they must all be recompiled. As a result, using this option affects the construction of make files.

See also -xldscope.

B.2.82 -xcsi

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.

The compiler translation phases required to handle such locales may result in significantly longer compilation 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 character code requirements unless you specify -xcsi.

B.2.83 -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.

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 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.

B.2.84 -xdepend=[yes|no]

(SPARC) Analyzes loops for inter-iteration data dependencies and does 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 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 also included with -xautopar or -xparallel. The dependency analysis is done at compile time.

Dependency analysis may help on single-processor systems. However, if you try -xdepend on single-processor systems, you should not use either -xautopar or -xexplicitpar. If either of them is on, then the -xdepend optimization is done for multiple-processor systems.

B.2.85 -xdryrun

This option is a macro for -###.

B.2.86 -xe

Performs only syntax and semantic checking on the source file, but does not produce any object or executable code.

B.2.87 -xexplicitpar

(SPARC) Obsolete, do not use. Use -xopenmp instead.

-xexplicitpar does not accept OpenMP parallelization directives. However, the Sun-specific MP pragmas have been deprecated and are no longer supported. The compiler supports the APIs specified by the OpenMP 2.5 standard instead. See theSun Studio 12: OpenMP API User’s Guide for migration information to the directives of the standard.

(SPARC) Generates parallelized code based on specification of #pragma MP directives. You do the dependency analysis: analyze and specify loops for inter-iteration data dependencies. The software parallelizes the specified loops. If optimization is not at -xO3 or higher, optimization is raised to -xO3 and a warning is issued. Avoid -xexplicitpar if you do your own thread management.

To get faster code, this option requires 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.

In summary, to parallelize explicitly:

• Analyze the loops to find those that are safe to parallelize.

• Insert #pragma MP to parallelize a loop. See the 3.8.3 Explicit Parallelization and Pragmas” for more information.

• Use the -xexplicitpar option.

The following is an example of inserting a parallel pragma immediately before the loop:

#pragma MP taskloop
  for (j=0; j<1000; j++){
  ...
  }

If you use -xexplicitpar and compile and link in one step, then linking automatically includes the microtasking 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 -xexplicitpar. For a complete list of all compiler options that must be specified at both compile time and at link time, see Table A–2.

Do not specify -xexplicitpar and -xopenmp together.

B.2.88 -xF[=v[,v...]]

Enables optimal reordering of functions 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.

Reording of variables can help solve the following problems which negatively impact run-time performance:

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

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

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

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

1. Compiling and linking with -xF.

2. Following the instructions in the "Program Performance Analysis" Tools 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 improvement.

B.2.88.1 Values

v can be one or more of the following:

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

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

analyzer(1), debugger(1), ld(1) man pages.

B.2.89 -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.

B.2.90 -xhwcprof

(SPARC) Enables compiler support for hardware counter-based profiling.

When -xhwcprof is enabled, the compiler generates information that helps tools associate profiled load and store instructions with the data-types and structure members (in conjunction with symbolic information produced with -gto 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 instruction 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 complete list of all compiler options that must be specified at both compile time and at link time, see Table A–2.

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 Program Performance Analysis Tools manual.

B.2.91 -xinline=list

The format of the list for -xinline is as follows: [{%auto,func_name,no%func_name}[,{%auto,func_name,no%func_name}]...]

-xinline tries to inline only those functions specified in the optional list. The list is either empty, or comprised of a comma-separated list of func_name, no%func_name, or %auto, where func_name is a function name. -xinline only has an effect at -xO3 or higher.

The list of values accumulates from left to right. So for a specification of -xinline=%auto,no%foo the compiler 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 references 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 routines 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 conditions apply. No warning is issued.

• Optimization is less than -xO3.

• The routine cannot be found.

• Inlining the routine does not look practicable to the optimizer.

• 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.

B.2.92 -xinstrument=[no%]datarace

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

You can then use the Performance Analyzer to run the instrumented program with collect -r races to create a data-race-detection experiment. You can run the instrumented code 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 argument.

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

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

This option also sets -g.

B.2.93 -xipo[=a]

(SPARC) Replace a with 0, 1, or 2. -xipo without any arguments is equivalent -xipo=1. -xipo=0 is the default setting and turns off -xipo. With -xipo=1, the compiler performs inlining across all source files.

With -xipo=2, the compiler performs interprocedural aliasing analysis as well as optimizations of memory allocation and layout to improve cache performance.

The compiler performs partial-program optimizations by invoking an interprocedural analysis component. Unlike -xcrossfile, -xipo performs optimizations across all object files in the link step, and is not limited to just the source files of the compile command. However, just like -xcrossfile, whole-program optimizations performed 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 all compiler options that must be specified at both compile time and at link time, see Table A–2.

The -xipo option generates significantly larger object files due to the additional information needed to perform optimizations across files. However, this additional information does not become part of the final executable binary file. Any increase in the size of the executable program is due to the additional optimizations performed. 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.

-xipo is particularly useful when compiling and linking large multi-file applications. Object files compiled with this flag have analysis information compiled within them that enables interprocedural analysis across source and pre-compiled program files.

However, 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.

Other important information about -xipo:

• It requires an optimization level of at least -xO4.

• It conflicts with -xcrossfile. If you use these together, the result is a compilation error.

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

B.2.93.1 Examples

In this example, compilation and linking occur in a single step:

cc -xipo -xO4 -o prog part1.c part2.c part3.c

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

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

A restriction is that libraries, even if compiled with -xipo, do not participate in crossfile interprocedural analysis, as this example shows:

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 generate warnings about undefined symbols, but the interprocedural optimizations are performed because it is a compile and link step.)

B.2.93.2 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 following two assumptions for any function (or subroutine) foo() defined in this set of object files:

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

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

Do not compile with 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 compile your version of malloc with -xipo=2.

As another example, suppose that you build a shared library with two external calls, foo() and bar() inside two different source files. Furthermore, suppose that bar() calls foo(). If 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.

B.2.94 -xipo_archive=[a]

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

a is one of the following:

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

It is illegal to specify -xipo_archive without a flag.

B.2.95 -xjobs=n

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

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

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 override each other until the right-most 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

It is illegal to specify -xipo_archive without a flag.

B.2.96 -xldscope={v}

Specify the -xldscope option to change the default linker scoping for the definition of extern symbols. Changing the default can result in faster and safer shared libraries because the implementation is better hidden.

v must be one of the following:

If you do not specify -xldscope, the compiler assumes -xldscope=global. 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 compile at -xO4 or higher in which case inlining can happen automatically, if you use the inline specifier, if you use the inline pragma, or if you are using cross-file optimization.

For example, suppose library ABC has a default allocator function that can be used by library clients, and is also used internally in the library:

void* ABC_allocator(size_t size) { return malloc(size); }

If you build the library at -xO4 or higher, the compiler inlines calls to ABC_allocator that occur in library components. If a library client wants to replace ABC_allocator with a customized version, the replacement will not occur in library components that called ABC_allocator. The final program will include different versions of the function.

Library functions declared with the __hidden or __symbolic specifiers can be generated inline when building the library. They are not supposed to be overridden by clients. See 2.2 Linker Scoping Specifiers.

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, #pragma inline

B.2.97 -xlibmieee

Forces IEEE 754 style return values for math routines in exceptional cases. In such cases, no exception message is printed, and you should not rely on errno.

B.2.98 -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 also 2.10 The Value of errno.

B.2.99 -xlibmopt

Enables the compiler to use a library of optimized math routines. You must use default rounding mode by specifying -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 also 2.10 The Value of errno.

The order on the command line for this library option is not significant.

This option is set by the -fast option.

See also: -fast -xnolibmopt

B.2.100 -xlic_lib=sunperf

Links in the Sun supplied performance libraries.

B.2.101 -xlicinfo

This option is silently ignored by the compiler.

B.2.102 -xlinkopt[=level]

(SPARC) Instructs the compiler to perform link-time optimizations on relocatable object files. These optimizations are performed at link time by analyzing the object binary code. The object files are not rewritten but the resulting executable code may differ from the original object codes.

You must use -xlinkopt on at least some of the compilation commands for -xlinkopt to be useful at link time. The optimizer can still perform some limited optimizations on object binaries that are not compiled with -xlinkopt.

-xlinkopt optimizes code coming from static libraries that appear on the compiler command line, but 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 (compiling with -G ).

level sets the level of optimizations performed, and must be 0, 1, or 2. The optimization levels are:

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 all compiler options that must be specified at both compile time and at link time, see Table A–2.

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.

Specifying -xlinkopt without a level parameter implies -xlinkopt=1.

This option is most effective when you use it to compile the whole program, and with profile feedback. Profiling reveals the most and least used parts of the code and building 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 compiles 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 B.2.131 -xprofile=p.

Do not use the -zcompreloc linker option when you compile with -xlinkopt.

Note that compiling with this option increases link time slightly. Object file sizes also increase, but the size of the executable remains the same. Compiling with -xlinkopt and -g increases the size of the executable by including debugging information.

B.2.103 -xloopinfo

(SPARC) Shows which loops are parallelized and which are not. Gives a short reason for not parallelizing a loop. The -xloopinfo option is valid only if -xautopar, or -xparallel, or -xexplicitpar is specified; otherwise, the compiler issues a warning.

To achieve faster execution, this option requires a multiprocessor system. On a single-processor system, the generated code usually runs slower.

B.2.104 -xM

Runs only the C preprocessor on the named C programs, requesting that the preprocessor generate makefile dependencies and send the result to the standard output (see make(1) for details about make files and dependencies).

For example:

#include <unistd.h>
void main(void)
{}

generates this output:

e.o: e.c
e.o: /usr/include/unistd.h
e.o: /usr/include/sys/types.h
e.o: /usr/include/sys/machtypes.h
e.o: /usr/include/sys/select.h
e.o: /usr/include/sys/time.h
e.o: /usr/include/sys/types.h
e.o: /usr/include/sys/time.h
e.o: /usr/include/sys/unistd.h

If you specify -xM and -xMF, the compiler appends all makefile dependency information to the file specified with -xMF.

B.2.105 -xM1

Generates makefile dependencies like -xM, but excludes /usr/include files. For example:

more hello.c
#include<stdio.h>
main()
{
    (void)printf(“hello\n”);
}
cc– xM hello.c
hello.o: hello.c
hello.o: /usr/include/stdio.h

Compiling with -xM1 does not report header file dependencies:

cc– xM1 hello.c
hello.o: hello.c

-xM1 is not available under -Xs mode.

If you specify -xM1 and -xMF, the compiler appends all makefile dependency information to the file specified with -xMF.

B.2.106 -xMD

Generates makefile dependencies like -xM but includes compilation. -xMD generates an output file for the makefile-dependency information based on the input filename but with the addition of a .d suffix. If you specify -xMD and-xMF, the preprocessor appends all makefile dependency information to the file specified with -xMF.

B.2.107 -xMF filename

Use this option to specify a file for the makefile-dependency output. There is no way to specify individual filenames for multiple input files with -xMFon one command line.

B.2.108 -xMMD

Use this option to generate makefile dependencies excluding system header files. This is the same functionality as -xM1, but includes compilation. -xMMD generates an output file for the makefile-dependency information based on the input filename but with the addition of a .d suffix. If you specify -xMF, the compiler uses the filename you provide instead.

B.2.109 -xMerge

Merges data segments into text segments. Data initialized in the object file produced by this compilation is read-only and (unless linked with ld -N) is shared between processes.

B.2.110 -xmaxopt[=v]

This command limits the level of pragma opt to the level specified. v is one of off, 1, 2, 3, 4, 5. The default value is -xmaxopt=off which causes pragma opt to be ignored. 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.

B.2.111 -xmemalign=ab

(SPARC) Use the -xmemalign option to control the assumptions the compiler makes about the alignment of data. By controlling the code generated for potentially misaligned memory accesses and by controlling program behavior in the event of a misaligned access, you can more easily port your code to SPARC.

Specify the maximum assumed memory alignment and behavior of misaligned data accesses. There must be a value for both a (alignment) and b (behavior). a specifies the maximum assumed memory alignment and b specifies the behavior for misaligned memory accesses. The following table lists the alignment and behavior values for -xmemalign.

You must specify -xmemalign whenever you want to link to an object file that was compiled with the value of b set to either i or f. For a complete list of all compiler options that must be specified at both compile time and at link time, see Table A–2.

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.

The -xmemalign option allows you to specify the maximum memory alignment of data to be assumed by the compiler in these indeterminable situations. It also specifies the error behavior to be followed at run time when a misaligned memory access does take place.

If actual data alignment at runtime is less than the specified alignment, the misaligned access attempt (a memory read or write) generates a trap. The two possible responses to the trap are

• The OS converts the trap to a SIGBUS signal. If the program does not catch the signal, the program aborts. Even if the program catches the signal, the misaligned access attempt will not have succeeded.

• The OS handles the trap by interpreting the misaligned access and returning control to the program as if the access had succeeded normally.

The following default values only apply when no -xmemalign option is present:

• -xmemalgin=8i for all v8 architectures.

• -xmemalign=8s for all v9 architectures.

Here is the default when -xmemalign option is present but no value is given:

• -xmemalign=1i for all -xarch values.

The following table shows how you can use -xmemalign to handle different alignment situations.

B.2.112 -xmodel=[a]

(x86) The -xmodel option enables the compiler to modify the form of 64-bit objects for the Solaris x86 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 must be one of the following:

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.

B.2.113 -xnolib

Does not link any libraries by default; that is, no -l options are passed to ld(1). Normally, the cc driver passes -lc to ld.

When you use -xnolib, you have to pass all the -l options yourself.

B.2.114 -xnolibmil

Does not inline math library routines. Use it after the –fast option. For example:

% cc– fast– xnolibmil....

B.2.115 -xnolibmopt

Prevents the use of an optimized math library by the compiler by turning off any previously specified -xlibmopt option. Use this option after -fast which enables use of the optimized math library by setting -xlibmopt:

% cc -fast -xnolibmopt ...

B.2.116 -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 different path for the shared libraries that are used by the program.

B.2.117 -xO[1|2|3|4|5]

Optimizes the object code; note the uppercase letter O followed by the digit 1, 2, 3, 4, or 5. Generally, the higher the level of optimization, the better the run-time performance. However, higher optimization levels can result in longer compilation time and larger executable files.

In a few cases,– xO2 might perform better than the others, and– xO3 might outperform– xO4. Try compiling with each level to see if you have one of these rare cases.

If the optimizer runs out of memory, it tries to recover by retrying the current procedure at a lower level of optimization and resumes subsequent procedures at the original level specified in the command-line option.

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 limits -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 Optimized Code” in Chapter 1 of Debugging a Program With dbx.

If you specify both -xO and -xmaxopt, the optimization level set with -xO must not exceed the -xmaxopt value.

If you optimize at -xO3 or -xO4 with very large procedures (thousands of lines of code in the same procedure), the optimizer may require a large amount of virtual memory. In such cases, machine performance may degrade.

B.2.117.1 Explanation of SPARC Optimizations

The following table describes how they operate on the SPARC platform.

B.2.117.2 Explanation of x86 Optimizations

The following table describes how the optimization levels work on the x86 platform.

For more information on debugging, see the Sun Studio 12: Debugging a Program With dbx manual. For more information on optimization, see theSun Studio 12: Performance Analyzer manual.

See also -xldscope and -xmaxopt.

B.2.118 -xopenmp[=i]

Use the -xopenmp option to enable explicit parallelization with OpenMP directives. To run a parallelized program in a multithreaded environment, you must set the OMP_NUM_THREADS environment variable prior to execution.

To enable nested parallelism, you must set the OMP_NESTED environment variable to TRUE. Nested parallelism is disabled by default.

The following table lists the values for i:

If you specify -xopenmp, but do not include a value, the compiler assumes -xopenmp=parallel. If you do not specify -xopenmp, the compiler assumes -xopenmp=none.

If you are debugging an OpenMP program with dbx, compile with -g and -xopenmp=noopt so you can breakpoint within parallel regions and display the contents of variables.

Do not specify -xopenmp, with either -xexplicitpar, or -xparallel.

The default for -xopenmp might change in future releases. You can avoid warning messages by explicitly specifying an appropriate optimization.

If you use -xopenmp while building any .so, you must use -xopenmp when linking the executable, and the compiler of the executable must not be any older than the compiler that built the .so with -xopenmp. This is especially important when you compile libraries that contain OpenMP directives. For a complete list of all compiler options that must be specified at both compile time and at link time, see Table A–2.

Make sure that the latest patch of the OpenMP runtime library, libmtsk.so, is installed on the system for best performance.

For more information that is specific to the C implementation of OpenMP, see 3.2 Parallelizing for OpenMP.

For information on OpenMP, see the Sun Studio 12: OpenMP API User’s Guide.

B.2.119 -xP

The compiler 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. For example, specifying -xP with the following source file,

f()
{
}

main(argc,argv)
int argc;
char *argv[];
{
}

produces this output:

int f(void);
int main(int, char **);

B.2.120 -xpagesize=n

Sets 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. If you do not specify a valid page size, the request is silently ignored at run-time.

You must specify a valid page size for the target platform.

Use the getpagesize(3C) command on the Solaris operating system to determine the number of bytes in a page. The Solaris operating system 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.

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 all compiler options that must be specified at both compile time and at link time, see Table A–2.

This feature is not available on the Solaris 8 operating system. A program compiled with this option will not link on the Solaris 8 operating system.

If you specify -xpagesize=default, the Solaris operating system sets the page size.

Compiling with this option has the same effect as setting the LD_PRELOAD environment variable to mpss.so.1 with the equivalent options, or running the 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: 4k, 8K, 64K, 512K, 2M, 4M, 32M, 256M, 2G, 16G, or default. You can set them both with the same value by specifying -xpagesize or you can specify them individually with different values.

B.2.121 -xpagesize_heap=n

Set the page size in memory for the heap.

The value for n must be one of the following: 4k, 8K, 64K, 512K, 2M, 4M, 32M, 256M, 2G, 16G, or default. If you do not specify a valid page size, the request is silently ignored at run-time.

Use the getpagesize(3C) command on the Solaris operating system to determine the number of bytes in a page. The Solaris operating system 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.

You can use pmap(1) or meminfo(2) to determine page size at the target platform.

If you specify -xpagesize_heap=default, the Solaris operating system sets the page size.

Compiling with this option has the same effect as setting the LD_PRELOAD environment variable to mpss.so.1 with the equivalent options, or running the 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 all compiler options that must be specified at both compile time and at link time, see Table A–2.

This feature is not available on the Solaris 8 operating system. A program compiled with this option will not link on the Solaris 8 operating system.

B.2.122 -xpagesize_stack=n

Set the page size in memory for the stack.

The value for n must be one of the following: 8K, 64K, 512K, 4M, 32M, 256M, 2G, 16G, or default. If you do not specify a valid page size, the request is silently ignored at run-time.

Use the getpagesize(3C) command on the Solaris operating system to determine the number of bytes in a page. The Solaris operating system 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.

If you specify -xpagesize_stack=default, the Solaris operating system sets the page size.

Compiling with this option has the same effect as setting the LD_PRELOAD environment variable to mpss.so.1 with the equivalent options, or running the 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 all compiler options that must be specified at both compile time and at link time, see Table A–2.

This feature is not available on the Solaris 8 operating system. A program compiled with this option will not link on the Solaris 8 operating system.

B.2.123 -xparallel

(SPARC) Obsolete, do not use. Use -xopenmp instead.

-xparallel does not accept OpenMP parallelization directives. However, the Sun-specific MP pragmas have been deprecated and are no longer supported. The OpenMP API is the preferred and supported parallelization model. See the Sun Studio 12: OpenMP API User’s Guide for migration information to the directives of the standard.

Parallelizes loops both automatically by the compiler and explicitly specified by the programmer. The -xparallel option is a macro, and is equivalent to specifying all three of -xautopar, -xdepend, and -xexplicitpar. With explicit parallelization of loops, 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 use -xparallel if you are issuing -xopenmp. -xparallel sets -xexplicitpar which should not be used if you specify -xopenmp.

To get faster code, this option requires a multiprocessor system. On a single-processor system, the generated code usually runs slower.

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 all compiler options that must be specified at both compile time and at link time, see Table A–2.

B.2.124 -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 (detailed in B.2.124 -xpch=v) and -xpchstop (detailed in B.2.125 -xpchstop=[file|<include>]) options in combination with the #pragma hdrstop directive (detailed under 2.8.8 hdrstop).

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. The information that the compiler collects is stored in a precompiled-header file.

See Also:

• B.2.125 -xpchstop=[file|<include>].

• 2.8.8 hdrstop.

B.2.124.1 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 determine which method the compiler uses to automatically generate a precompiled header:

B.2.124.2 Creating a 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 suffix .cpch. When you specify pch_filename, you can add the suffix or let the compiler add it for you. For example, if you specify cc -xpch=collect:foo a.c, the precompiled-header file is called foo.cpch.

B.2.124.3 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 generates 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.

B.2.124.4 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 that was used to create the precompiled-header file. For example, your command in use mode could look like this: cc -xpch=use:foo.cpch foo.c bar.c foobar.c.

You should only use an existing precompiled-header file if the following are 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 precompile header was created.

• The contents of the included headers that you specify with -xpch=use is identical to the contents of the included headers that were specified when the precompiled header was created.

• The current directory (that is, the directory in which the compilation is occurring and attempting to use a given precompiled-header file) is the same as the directory in which the precompiled-header file was created.

• The initial sequence of pre-processing directives, including #include directives, in the file you specified with -xpch=collect are the same as the sequence of pre-processing directives in the files you specify with -xpch=use.

B.2.124.5 The Viable Prefix

In order to share a precompiled-header file across multiple source files, those source files must share a common set of include files as their initial sequence of tokens. A token is a keyword, name or punctuation mark. Comments and code that is excluded by #if directives 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, viable prefix must be interpreted consistently across all the source files that use the same precompiled-header file.

The viable prefix of a source file can only be comprised of comments and any of the following pre-processor directives:

#include
#if/ifdef/ifndef/else/elif/endif
#define/undef
#ident (if identical, passed through as is)
#pragma (if identical)

Any of these may reference macros. The #else, #elif, and #endif directives must match within the viable prefix. 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 generates 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.

B.2.124.6 Screening a Header File for Problems

What makes a header file precompilable? A header file is precompilable 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 violates any of these constraints is undefined.

• The header file must not use __DATE__ and __TIME__.

• The header file must not contain #pragma hdrstop.

B.2.124.7 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.

B.2.124.8 Warnings

• 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.

• If you specify -xpch=autofirst or you specify -xpch=auto without -xpchstop, any declaration, definition, 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 generation of the precompiled-header file.

• A #pragma hdrstop before the first include file under -xpch=autofirst or -xpch=auto disables the automatic generation of the precompiled-header file.

B.2.124.9 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 dependencies. 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
         $(CC) 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.

You do not have to create any additional make rules in your makefiles for -xpch=auto or -xpch=autofirst.

B.2.125 -xpchstop=[file|<include>]

Use the -xpchstop=file option to specify the last include file of the viable prefix for the precompiled-header file. Using -xpchstop on the command line is equivalent to placing a hdrstop pragma after the first include-directive that references file in each of the source files that you specify with the cc command.

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 that are contained in the entire viable prefix.

In the following example, the -xpchstop option specifies that the viable prefix for the precompiled-header file ends with the include of projectheader.h. Therefore, privateheader.h is not a part of the viable prefix.

example% cat a.c
     #include <stdio.h>
     #include <strings.h>
     #include "projectheader.h"
     #include "privateheader.h"
     .
     .
     .
example% cc -xpch=collect:foo.cpch a.c -xpchstop=projectheader.h -c

See also -xpch.

B.2.126 -xpentium

(x86) Generates code for the Pentium processor.

B.2.127 -xpg

Prepares the object code to collect data for profiling with gprof(1). It invokes a runtime recording mechanism that produces a gmon.out file at normal termination.

There is no advantage for -xprofile if you specify -xpg. The two do not prepare or use data provided by the other.

Profiles are generated by using prof(1) or gprof(1) on 64 bit Solaris platforms or just gprof on 32 bit Solaris platforms and 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 executable 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 collected 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 A.1.2 Compile-Time and Link-Time Options for a complete list of options that must be specified at both compile time and link time.

B.2.128 -xprefetch[=val[,val]]

Enable prefetch instructions on those architectures that support prefetch.

Explicit prefetching should only be used under special circumstances that are supported by measurements.

val must be one of the following:

The default is -xprefetch=auto,explicit. This default adversely affects applications that have essentially non-linear memory access patterns. Specify -xprefetch=no%auto,no%explicit to override the default.

The sun_prefetch.h header file provides the macros that you can use to specify explicit prefetch instructions. The prefetches are approximately at the place in the executable that corresponds to where the macros appear.

B.2.128.1 Prefetch Latency Ratio

The prefetch latency is the hardware delay between the execution of a prefetch instruction and the time the data being prefetched is available in the cache.

The factor must be a positive number of the form n.n.

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. The assumed latency between a prefetch and a load may not be the same as the assumed latency between a prefetch and a store.

The compiler tunes the prefetch mechanism for optimal performance across a wide range of machines and applications. This tuning may not always be optimal. For memory-intensive applications, especially applications intended to run on large multiprocessors, you may be able to obtain better performance by increasing the prefetch latency values. To increase the values, use a factor that is greater than 1 (one). A value between .5 and 2.0 will most likely pro vide the maximum performance.

For applications with data sets that reside entirely within the external cache, you may be able to obtain better performance by decreasing the prefetch latency values. To decrease the values, use a factor that is less than one.

To use the latx:factor suboption, start with a factor value near 1.0 and run performance tests against the application. Then increase or decrease the factor, as appropriate, and run the performance tests again. Continue adjusting the factor and running the performance tests until you achieve optimum performance. When you increase or decrease the factor in small steps, you will see no performance difference for a few steps, then a sudden difference, then it will level off again.

B.2.129 -xprefetch_auto_type=a

Where a is [no%]indirect_array_access.

Use this option to determine whether or not the compiler generates indirect prefetches for the loops indicated by the option -xprefetch_level in the same fashion the prefetches for direct memory accesses are generated.

If you do not specify a setting for -xprefetch_auto_type, the compiler sets it to -xprefetch_auto_type=no%indirect_array_access.

Options such as -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.

B.2.130 -xprefetch_level=l

Use the -xprefetch_level option to control the aggressiveness of automatic insertion of prefetch instructions as determined with -xprefetch=auto. l must be 1, 2, or 3. The compiler becomes more aggressive, or in other words, introduces more prefetches with each, higher, level of -xprefetch_level.

The appropriate value for the -xprefetch_level depends on the number of cache misses the application may have. Higher -xprefetch_level values have the potential to improve the performance of applications.

This option is effective only when it is compiled with -xprefetch=auto, with optimization level 3 or greater, and generate code for a platform that supports prefetch (v8plus, v8plusa, v9, v9a, v9b, generic64, native64).

-xprefetch_level=1 enables automatic generation of prefetch instructions. -xprefetch_level=2 enables additional generation beyond level 1 and -xprefetch_level=3 enables additional generation beyond level 2.

The default is -xprefetch_level=1 when you specify -xprefetch=auto.

B.2.131 -xprofile=p

Use this option to collect and save execution-frequency data so you can then use the data in subsequent runs to improve performance. This option is only valid when you specify optimization at level -xO2 or above.

You must specify -xprofile at compile time as well as link time. For a complete list of all compiler options that must be specified at both compile time and at link time, see Table A–2.

Compiling with high optimization levels (for example -xO5) is enhanced by providing the compiler with runtime-performance feedback. In order to produce runtime-performance feedback, you must compile with -xprofile=collect, run the executable against a typical data set, and then recompile at the highest optimization level and with -xprofile=use.

Profile collection is safe for multithreaded applications. That is, profiling a program that does its own multitasking ( -mt ) produces accurate results.

p must be collect[:name], use[:name], or tcov.

• collect[:name]

  Collects and saves execution-frequency data for later use by the optimizer with -xprofile=use. The compiler generates code to measure statement execution-frequency.

  ---

  Note –

  Do not specify -xprofile=collect when you build shared libraries on Linux.

  ---

  The name is the name of the program that is being analyzed. This name is optional. If name is not specified, a.out is assumed to be the name of the executable.

  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 written 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 executions-frequency data accumulates in the feedback file; that is, output from prior executions is not lost.

  If you are compiling and linking in separate steps, make sure that any object files compiled with -xprofile=collect are also linked with -xprofile=collect.

• use[:name]

  The program is optimized by using the execution-frequency data generated and saved in the feedback files from a previous execution of the program that was compiled with– xprofile=collect.

  The name is the name of the program that is being analyzed. This name is optional. If name is not specified, a.out is assumed to be the name of the executable.

  Except for the -xprofile option which changes from -xprofile=collect to -xprofile=use, 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 generated the feedback file. The same version of the compiler must be used for both the collect build and the use build as well. If compiled with -xprofile=collect:name, the same program name name must appear in the optimizing compilation: -xprofile=use:name.

  The association between an object file and its profile data is based on the UNIX pathname of the object file when it is compiled with -xprofile=collect. In some circumstances, the compiler will not associate an object file with its profile data: the object file has no profile data because it was not previously compiled with -xprofile=collect, the object file is not linked in a program with -xprofile=collect, the program has never been executed.

  The compiler can also become confused if an object file was previously compiled in a different directory with -xprofile=collect and this object file shares a common basename with other object files compiled with -xprofile=collect but they cannot be uniquely identified by the names of their containing directories. In this case, even if the object file has profile data, the compiler will not be able to find it in the feedback directory when the object file is recompiled with -xprofile=use.

  All of these situations cause the compiler to lose the association between an object file and its profile data. Therefore, if an object file has profile data but the compiler is unable to associate it with the object file’s pathname when you specify -xprofile=use, use the -xprofile_pathmap option to identify correct directory. See B.2.133 -xprofile_pathmap.

• 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 B.2.66 -xa for information on the old style of profiling, the tcov(1) man page, and Program Performance Analysis Tools for more details.

  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 executable. 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 compatible 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 tcov(1) and Program Performance Analysis Tools for more details.

  ---

  Note –

  tcov’s code coverage report can be unreliable if there is inlining of routines due to -xO4 or -xinline.

  ---

When you use -xprofile=collect to compile a program for profile collection and -xprofile=use to compile a program for profile feedback, the source files and compiler 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 profile feedback data pertaining to a particular object file is accumulated from the specified feedback directories when the object file is compiled.

If both -xprofile=collect and -xprofile=use are specified 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 right-most -xprofile option is -xprofile=collect, all profile feedback directory names specified by -xprofile=use options are ignored, and instrumentation for profile generation is enabled.

See also: -xhwcprof, -xprofile_ircache, -xprofile_pathmap

B.2.132 -xprofile_ircache[=path]

(SPARC) Use -xprofile_ircache[=path] with -xprofile=collect|use to improve compilation time during the use phase by reusing compilation data saved from the collect phase.

With large programs, compilation time in the use phase can improve significantly because the intermediate data is saved. Note that the saved data could increase disk space requirements considerably.

When you use -xprofile_ircache[=path], path overrides the location where the cached files are saved. By default, these files are saved in the same directory as the object file. Specifying a path is useful when the collect and use phases happen in two different directories. 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

B.2.133 -xprofile_pathmap

(SPARC) Use the -xprofile_pathmap=collect_prefix:use_prefix option when you are also specifying the -xprofile=use command. Use -xprofile_pathmap when both of the following are true and the compiler is unable to find profile data for an object file that is compiled with -xprofile=use.

• You are compiling the object file with -xprofile=use in a directory that is different from the directory in which the object file was previously compiled with -xprofile=collect.

• Your object files share a common basename in the profile but are distinguished from each other by their location in different directories.

The collect-prefix is the prefix of the UNIX 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 identified or the last specified use-prefix is found not to match the object file pathname.

B.2.134 -xreduction

(SPARC) Turns on reduction recognition during automatic parallelization. -xreduction must be specified with -xautopar, or -xparallel otherwise the compiler issues a warning.

When reduction recognition is enabled, the compiler parallelizes reductions such as dot products, maximum and minimum finding. These reductions yield different roundoffs than obtained by unparallelized code.

B.2.135 -xregs=r[,r…]

Specifies the usage of registers for the generated code.

r is a comma-separated list that consists of one or more of the following: [no%]appl, [no%]float,[no%]frameptr.

Example: -xregs=appl,no%float

The SPARC default is -xregs=appl,float.

The x86 default is -xregs=no%frameptr. -xregs=frameptr in 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 applications 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.

B.2.136 -xrestrict[=f]

(SPARC) Treats pointer-valued function parameters as restricted pointers . f is %all, %none, or a comma-separated list of one or more function names: {%all|%none|fn[,fn...]}.

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. Refer to 3.8.2 Restricted Pointers, for more information.

This command-line option can be used on its own, but it is best used with optimization. For example, the command:

%cc -xO3 -xrestrict=%all prog.c

treats all pointer parameters in the file prog.c as restricted pointers. The command:

%cc -xO3 -xrestrict=agc prog.c

treats all pointer parameters in the function agc in the file prog.c as restricted pointers.

The default is %none; specifying -xrestrict is equivalent to specifying -xrestrict=%all.

B.2.137 -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 program, but it does take more disk space.

B.2.138 -xsafe=mem

(SPARC) Allows the compiler to assume no memory protection violations occur.

This option grants permission to use non-faulting load instruction on the SPARC V9 architecture.

Because non-faulting loads do not cause a trap when a fault such as address misalignment or segmentation violation occurs, you should use this option only for programs in which such faults cannot occur. Because few programs incur memory-based traps, you can safely use this option for most programs. Do not use this option for programs that explicitly depend on memory-based traps to handle exceptional conditions.

This option takes effect only when used with optimization level -xO5 and one of the following -xarch values: sparc, sparcvis, or sparcvis2 for both -m32 and -m64.

B.2.139 -xsb

Obsolete — do not use. The source browser functionality is no longer supported.

B.2.140 -xsbfast

Obsolete — do not use. The source browser functionality is no longer supported.

B.2.141 -xsfpconst

Represents unsuffixed floating-point constants as single precision, instead of the default mode of double precision. Not valid with -Xc.

B.2.142 -xspace

Does no optimizations or parallelization of loops that increase code size.

Example: The compiler will not unroll loops or parallelize loops if it increases code size.

B.2.143 -xstrconst

Inserts string literals into the read-only data section of the text segment instead of the default data segment. Duplicate strings will be eliminated and the remaining copy shared amongst references in the code.

B.2.144 -xtarget=t

Specifies the target system for instruction set and optimization.

The value of t must be one of the following: native, generic, native64, generic64, system-name.

Each specific value for -xtarget expands into a specific set of values for the -xarch, -xchip, and -xcache options. Use the -xdryrun option to determine the expansion of -xtarget=native on a running system.

For example, -xtarget=sun4/15 is equivalent to: -xarch=v8a -xchip=micro -xcache=2/16/1.

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.

The performance of some programs may benefit by providing the compiler with an accurate description of the target computer hardware. When program performance is critical, the proper specification of the target hardware could be very important. This is especially true when running on the newer SPARC processors. However, for most programs and older SPARC processors, the performance gain is negligible and a generic specification is sufficient.

B.2.144.1 -xtarget Values 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.

B.2.144.2 -xtarget Values 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.

B.2.145 -xtemp=dir

Sets the directory for temporary files used by cc 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.

B.2.146 -xthreadvar[=o]

Specify -xthreadvar to control the implementation of thread local variables. Use this option 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, specify -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 2.3 Thread Local Storage Specifier.

o must be one the following:

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 values, 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.

Using thread variables on different versions of Solaris software requires different options on the command line.

• On Solaris 8 software, objects that use __thread must be compiled with -mt and must be linked with -mt -L/usr/lib/lwp -R/usr/lib/lwp.

• On Solaris 9 software, objects that use __thread must be compiled and linked with -mt.

See Also: -xcode, -KPIC, -Kpic

B.2.147 -xtime

Reports the time and resources used by each compilation component.

B.2.148 -xtransition

Issues warnings for the differences between K&R C and Sun ISO C.

The -xtransition option issues warnings in conjunction with the -Xa and -Xt options. You can eliminate all warning messages about differing behavior through appropriate coding. The following warnings no longer appear unless you issue the -xtransition option:

• \a is ISO C “alert” character

• \x is ISO C hex escape

• bad octal digit

• base type is really type tag: name

• comment is replaced by “##”

• comment does not concatenate tokens

• declaration introduces new type in ISO C: type tag

• macro replacement within a character constant

• macro replacement within a string literal

• no macro replacement within a character constant

• no macro replacement within a string literal

• operand treated as unsigned

• trigraph sequence replaced

• ISO C treats constant as unsigned: operator

• semantics of operator change in ISO C; use explicit cast

B.2.149 -xtrigraphs

The -xtrigraphs option determines whether the compiler recognizes trigraph sequences as defined by the ISO C standard.

By default, the compiler assumes -xtrigraphs=yes and recognizes all trigraph sequences throughout the compilation unit.

If your source code has a literal string containing question marks (?) that the compiler is interpreting as a trigraph sequence, you can use the -xtrigraph=no suboption to turn off the recognition of trigraph sequences. The -xtrigraphs=no option turns off recognition of all trigraphs throughout the entire compilation unit.

Consider the following example source file named trigraphs_demo.c.

#include <stdio.h>

int main ()
{

  (void) printf("(\?\?) in a string appears as (??)\n");

  return 0;
}

Here is the output if you compile this code with -xtrigraphs=yes.

example% cc -xtrigraphs=yes trigraphs_demo.c
example% a.out
(??) in a string appears as (]

Here is the output if you compile this code with -xtrigraphs=no.

example% cc -xtrigraphs=no trigraphs_demo.c
example% a.out
(??) in a string appears as (??)

B.2.150 -xunroll=n

Suggests to the optimizer to unroll loops n times. 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, the -xunroll=n merely suggests to the compiler that it unroll loops n times.

B.2.151 -xustr={ascii_utf16_ushort|no}

Use this option if you need to support an internationalized application that uses ISO10646 UTF-16 string literals. In other words, use this option if your code contains a string literal that you want the compiler to convert to UTF-16 strings in the object file. Without this option, the compiler neither produces nor recognizes sixteen-bit character string literals. This option enables recognition of the U"ASCII_string" string literals as an array of type 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 right-most 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_utf16_ushort without also specifying a U"ASCII_string" string literals.

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.