Sun Studio 12 Collection >> Sun Studio 12: C User's Guide >> B.  C Compiler Options Reference

Previous: A.  Compiler Options Grouped by Functionality

Appendix B C Compiler Options Reference

This chapter describes the C compiler options in alphabetical order. See Appendix A, Compiler Options Grouped by Functionality for options grouped by functionality. For example, Table A–1 lists all the optimization and performance options.

Take note that the C compiler recognizes by default some of the constructs of the 1999 ISO/IEC C standard. Specifically, the supported features are detailed in Appendix D, Supported Features of C99. Use the -xc99=none command if you want to limit the compiler to the 1990 ISO/IEC C standard.

If you are porting a K&R C program to ISO C, make special note of the section on compatibility flags, B.2.63 -X[c|a|t|s]. Using them makes the transition to ISO C easier. Also refer to the discussion on the transition in 5.4 Examples of Memory Reference Constraints.

B.1 Option Syntax

The syntax of the cc command is:

% cc [options] filenames [libraries]...

where:

• options represents one or more of the options described in Table A–15.

• filenames represents one or more files used in building the executable program

  The C compiler accepts a list of C source files and object files contained in the list of files specified by filenames. The resulting executable code is placed in a.out, unless the -o option is used. In this case, the code is placed in the file named by the -o option.

  Use the C compiler to compile and link any combination of the following:

  • C source files, with a .c suffix

  • Inline template files, with a .il suffix (only when specified with .c files)

  • C preprocessed source files, with a .i suffix

  • Object-code files, with .o suffixes

  • Assembler source files, with .s suffixes

    After linking, the C compiler places the linked files, now in executable code, into a file named a.out, or into the file specified by 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.

  libraries represents any of a number of standard or user-provided libraries containing functions, macros, and definitions of constants.

See option -YP, dir to change the default directories used for finding libraries. dir is a colon-separated path list. The default library search order for cc is:

/opt/SUNWspro/prod/lib

/usr/ccs/lib

/usr/lib

cc uses getopt to parse command-line options. Options are treated as a single letter or a single letter followed by an argument. See getopt(3c).

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

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.

If you compile and link in separate steps and you compile with -mt, you might get unexpected results. If you compile one translation unit with -mt, compile all units of the program with -mt.

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

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.

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.

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.