Sun Studio 12: C User's Guide

Appendix A Compiler Options Grouped by Functionality

This chapter summarizes the C compiler options by function. Detailed explanations of the options and the compiler command-line syntax are provided in Table A–15.

A.1 Options Summarized by Function

In this section, the compiler options are grouped by function to provide a quick reference. For a detailed description of each option, refer to Table A–15Appendix B, C Compiler Options Reference. Some flags serve more than one purpose and appear more than once.

The options apply to all platforms except as noted; features that are unique to the Solaris operating system on SPARC based systems are identified as (SPARC), and the features that are unique to the Solaris operating system on x86 based systems are identified as (x86).

A.1.1 Optimization and Performance Options

Table A–1 Optimization and Performance Options Table

Option  

Action  

-fast

Selects the optimum combination of compilation options for speed of executable code.

-fma

(SPARC) Enables automatic generation of floating-point, fused, multiply-add instructions. 

-p

Prepares the object code to collect data for profiling

-xalias_level

(SPARC) Enables the compiler to perform type-based alias analysis and optimizations.

-xbinopt

Prepares the binary for later optimizations, transformations and analysis.

-xbuiltin

Improve the optimization of code that calls standard library functions.

-xcrossfile

Enables optimization and inlining across source files.

-xdepend

(SPARC) Analyzes loops for inter-iteration data dependencies and does loop restructuring.

-xF

Enables reordering of data and functions by the linker.

-xhwcprof

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

-xinline

Tries to inline only those functions specified.

-xinstrument

Compiles and instruments your program for analysis by the Thread Analyzer. 

-xipo

(SPARC) Performs whole-program optimizations by invoking an interprocedural analysis component.

-xipo_archive

Allows crossfile optimization to include archive (.a) libraries.

-xjobs

Sets how many processes the compiler creates.

-xlibmil

Inlines some library routines for faster execution.

-xlic_lib=sunperf

Links in the Sun-supplied performance libraries.

-xlinkopt

Performs link-time optimizations on relocatable object files.

-xlibmopt

Enable library of optimized math routines.

-xmaxopt

This command limits the level of pragma opt to the level specified.

-xnolibmil

Does not inline math library routines.

-xnolibmopt

Do not enable library of optimized math routines.

-x0

Optimizes the object code.

-xnorunpath

Prevents inclusion of a run-time search-path for shared libraries in the executable. 

-xpagesize

Sets the preferred page size for the stack and the heap.

-xpagesize_stack

Sets the preferred page size for the stack.

-xpagesize_heap

Sets the preferred page size for the heap.

-xpch

Reduces compile time for applications whose source files share a common set of include files.

-xpchstop

Can be used in conjunction with -xpch to specify the last include file of the viable prefix.

-xpentium

(x86) Optimizes for the PentiumTM processor.

-xprefetch

(SPARC) Enable prefetch instructions.

-xprefetch_level

(SPARC) Control the aggressiveness of automatic insertion of prefetch instructions as set by -xprefetch=auto

-xprefetch_auto_type

(SPARC) Controls how indirect prefetches are generated.

-xprofile

Collects data for a profile or uses a profile to optimize.

-xprofile_ircache

Improves compilation time of -xprofile=use phase by reusing compilation data saved from the -xprofile=collect phase

-xprofile_pathmap

Support for multiple programs or shared libraries in a single profile directory.

-xrestrict

(SPARC) Treats pointer-valued function parameters as restricted pointers.

-xsafe

(SPARC) Allows the compiler to assume no memory-based traps occur.

-xspace

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

-xunroll

Suggests to the optimizer to unroll loops n times.

A.1.2 Compile-Time and Link-Time Options

The following table lists the options that must be specified both at link-time and at compile-time.

Table A–2 Compile-Time and Link-Time Options Table

Option  

Action  

-fast

Selects the optimum combination of compilation options for speed of executable code.

-m32|-m64

Specifies the memory model for the compiled binary object. 

-mt

Macro option that expands to -D_REENTRANT -lthread.

-p

Prepares the object code to collect data for profiling with prof(1)

-xarch

Specify instruction set architecture.

-xautopar

Turns on automatic parallelization for multiple processors.

-xexplicitpar

(SPARC) Generates parallelized code based on specification of #pragma MP directives.

-xhwcprof

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

-xipo

Performs whole-program optimizations by invoking an interprocedural analysis component.

-xlinkopt

Performs link-time optimizations on relocatable object files.

-xmemalign

(SPARC) Specify maximum assumed memory alignment and behavior of misaligned data accesses.

-xopenmp

Supports the OpenMP interface for explicit parallelization including a set of source code directives, run-time library routines, and environment variables

-xpagesize

Sets the preferred page size for the stack and the heap.

-xpagesize_stack

Sets the preferred page size for the stack.

-xpagesize_heap

Sets the preferred page size for the heap.

-xparallel

(SPARC) Parallelizes loops both automatically by the compiler and explicitly specified by the programmer.

-xpg

Prepares the object code to collect data for profiling with gprof(1).

-xprofile

Collects data for a profile or uses a profile to optimize.

-xvector

Enable automatic generation of calls to the vector library functions.

A.1.3 Data-Alignment Options

Table A–3 Data-Alignment Options Table

Option  

Action  

-xchar_byte_order

Produce an integer constant by placing the characters of a multi-character character-constant in the specified byte order.

-xdepend

(SPARC) Analyzes loops for inter-iteration data dependencies and does loop restructuring.

-xmemalign

(SPARC) Specify maximum assumed memory alignment and behavior of misaligned data accesses.

-xopenmp

(SPARC) Supports the OpenMP interface for explicit parallelization including a set of source code directives, run-time library routines, and environment variables

A.1.4 Numerics and Floating Point Options

Table A–4 Numerics and Floating Point Options Table

Option  

Action  

-flteval

(x86) Controls floating point evaluation.

-fma

(SPARC) Enables automatic generation of floating-point, fused, multiply-add instructions. 

-fnonstd

Causes nonstandard initialization of floating-point arithmetic hardware.

-fns

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

-fprecision

(x86) Initializes the rounding-precision mode bits in the Floating-point Control Word

-fround

Sets the IEEE 754 rounding mode that is established at runtime during the program initialization.

-fsimple

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

-fsingle

Causes the compiler to evaluate float expressions as single precision rather than double precision.

-fstore

(x86) Causes the compiler to convert the value of a floating-point expression or function to the type on the left-hand side of an assignment

-ftrap

Sets the IEEE 754 trapping mode in effect at startup.

-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

-xdepend

(SPARC) Analyzes loops for inter-iteration data dependencies and does loop restructuring.

-xlibmieee

Forces IEEE 754 style return values for math routines in exceptional cases.

-xopenmp

(SPARC) Supports the OpenMP interface for explicit parallelization including a set of source code directives, run-time library routines, and environment variables

-xsfpconst

Represents unsuffixed floating-point constants as single precision

-xvector

Enable automatic generation of calls to the vector library functions.

A.1.5 Parallelization Options

Table A–5 Parallelization Options Table

Option  

Action  

-mt

Macro option that expands to -D_REENTRANT -lthread.

-xautopar

(SPARC) Turns on automatic parallelization for multiple processors.

-xcheck

(SPARC) Adds a runtime check for stack overflow.

-xdepend

(SPARC) Analyzes loops for inter-iteration data dependencies and does loop restructuring. 

-xexplicitpar

(SPARC) Generates parallelized code based on specification of #pragma MP directives.

-xloopinfo

(SPARC) Shows which loops are parallelized and which are not.

-xopenmp

(SPARC) Supports the OpenMP interface for explicit parallelization including a set of source code directives, run-time library routines, and environment variables

-xparallel

(SPARC) Parallelizes loops both automatically by the compiler and explicitly specified by the programmer.

-xreduction

(SPARC) Turns on reduction recognition during automatic parallelization.

-xrestrict

(SPARC) Treats pointer-valued function parameters as restricted pointers. 

-xvpara

(SPARC) Warns about loops that have #pragma MP directives specified but may not be properly specified for parallelization.

-xthreadvar

(SPARC) Controls the implementation of thread local variables. 

-Zll

(SPARC) Creates the program database for lock_lint, but does not generate executable code.

A.1.6 Source-Code Options

Table A–6 Source-Code Options Table

Option  

Action  

-A

Associates name as a predicate with the specified tokens as if by a #assert preprocessing directive.

-C

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

-D

Associates name with the specified tokens as if by a #define preprocessing directive.

-E

Runs the source file through the preprocessor only and sends the output to stdout.

-fd

Reports K&R-style function definitions and declarations.

-H

Prints to standard error, one per line, the path name of each file included during the current compilation.

-I

Adds directories to the list that is searched for #include files with relative file names.

-P

Runs the source file through the C preprocessor only.

-U

Removes any initial definition of the preprocessor symbol name.

-X

The -X options specify varying degrees of compliance to the ISO C standard.

-xCC

Accepts the C++-style comments.

-xc99

Controls compiler recognition of supported C99 features.

-xchar

Helps with migration from systems where char is defined as unsigned.

-xcsi

Allows the C compiler to accept source code written in locales that do not conform to the ISO C source character code requirements

-xM

Runs only the preprocessor on the named C programs, requesting that it generate makefile dependencies and send the result to the standard output

-xM1

Collects dependencies like -xM, but excludes /usr/include files.

-xMD

Generates makefile dependencies like -xM but includes compilation.

-xMF

Specifies a filename which stores makefile dependency information.

-xMMD

Generates makefile dependencies but excludes system headers.

-xP

Prints prototypes for all K&R C functions defined in this module

-xpg

Prepares the object code to collect data for profiling with gprof(1).

-xtrigraphs

Determines recognition of trigraph sequences.

-xustr

Enables recognition of string literals composed of sixteen-bit characters.

A.1.7 Compiled-Code Options

Table A–7 Compiled-Code Options Table

Option  

Action  

-c

Directs the compiler to suppress linking with ld(1) and to produce a .o file in the current working directory for each source file

-o

Names the output file

-S

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

A.1.8 Compilation-Mode Options

Table A–8 Compilation-Mode Options Table

Option  

Action  

-#

Turns on verbose mode, which shows how command options expand and shows each component as it is invoked.

-###

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

-features

Ensures compatibility between old binaries with extern inline functions and new binaries.

-keeptmp

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

-V

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

-W

Passes arguments to C compilation-system components.

-X

The -X options specify varying degrees of compliance to the ISO C standard.

-xc99

Controls compiler recognition of supported C99 features.

-xchar

Preserves the sign of a char

-xhelp

Displays on-line help information.

-xjobs

Sets how many processes the compiler creates.

-xpch

Reduces compile time for applications whose source files share a common set of include files.

-xpchstop

Can be used in conjunction with -xpch to specify the last include file of the viable prefix.

-xtemp

Sets the directory for temporary files used by cc to dir.

-xtime

Reports the time and resources used by each compilation component.

-Y

Specifies a new directory for the location of a C compilation-system component.

-YA

Changes the default directory searched for components.

-YI

Changes the default directory searched for include files.

-YP

Changes the default directory for finding library files.

-YS

Changes the default directory for startup object files.

A.1.9 Diagnostic Options

Table A–9 Diagnostic Options Table

Option  

Action  

-errfmt

Prefix error messages with string “error:” for ready distinction from warning messages.

-errhdr

Limits the warnings from header files to a specified group. 

-erroff

Suppresses compiler warning messages.

-errshort

Control how much detail is in the error message produced by the compiler when it discovers a type mismatch.

-errtags

Displays the message tag for each warning message.

-errwarn

If the indicated warning message is issued, cc exits with a failure status.

-v

Directs the compiler to perform stricter semantic checks and to enable other lint-like checks.

-w

Suppresses compiler warning messages.

-xe

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

-xtransition

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

-xvpara

(SPARC) Warns about loops that have #pragma MP directives specified but may not be properly specified for parallelization.

A.1.10 Debugging Options

Table A–10 Debugging Options Table

Option  

Action  

-xcheck

Adds a runtime check for stack overflow.

-g

Produces additional symbol table information for the debugger.

-s

Removes all symbolic debugging information from the output object file.

-xdebugformat

Generates debugging information in dwarf format instead of stabs format.

-xpagesize

Sets the preferred page size for the stack and the heap.

-xpagesize_stack

Sets the preferred page size for the stack.

-xpagesize_heap

Sets the preferred page size for the heap.

-xs

Disables Auto-Read of object files for dbx.

-xvis

(SPARC) Enables compiler recognition of the assembly-language templates defined in the VIS[tm] instruction set

A.1.11 Linking and Libraries Options

Table A–11 Linking and Libraries Options Table

Option  

Action  

-B

Specifies whether bindings of libraries for linking are static or dynamic.

-d

Specifies dynamic or static linking in the link editor.

-G

Passes the option to the link editor to produce a shared object rather than a dynamically linked executable.

-h

Assigns a name to a shared dynamic library as a way to have different versions of a library.

-i

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

-L

Adds directories to the list that the linker searches for libraries.

-l

Links with object library libname.so, or libname.a.

-mc

Removes duplicate strings from the .comment section of the object file.

-mr

Removes all strings from the .comment section. Can also insert a string in that section of the object file.

-Q

Emits or does not emit identification information to the output file.

-R

Passes a colon-separated list of directories used to specify library search directories to the runtime linker.

-xMerge

Merges data segments into text segments.

-xcode

Specify code address space.

-xldscope

Controls the default scope of variable and function definitions to create faster and safer shared libraries.

-xnolib

Does not link any libraries by default

-xnolibmil

Does not inline math library routines.

-xstrconst

Inserts string literals into the read-only data section of the text segment instead of the default data segment.

A.1.12 Target-Platform Options

Table A–12 Target-Platform Options Table

Option  

Action  

-m32|-m64

Specifies the memory model for the compiled binary object. 

-xarch

Specify instruction set architecture.

-xcache

Defines the cache properties for use by the optimizer.

-xchip

Specifies the target processor for use by the optimizer.

-xregs

(SPARC) Specifies the usage of registers for the generated code.

-xtarget

Specifies the target system for instruction set and optimization.

A.1.13 x86-Specific Options

Table A–13 x86-Specific Options Table

Option  

Action  

-flteval

Controls floating point evaluation.

-fprecision

Initializes the rounding-precision mode bits in the Floating-point Control Word

-fstore

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

-nofstore

Does not convert the value of a floating-point expression or function to the type on the left-hand side of an assignment

-xmodel

Modifies the form of 64-bit objects for the Solaris x86 platforms

-xpentium

Optimizes for the Pentium processor.

A.1.14 Licensing Options

Table A–14 Licensing Options Table

Option  

Action  

-xlicinfo

Returns information about the licensing system.

A.1.15 Obsolete Options

The following table lists the options that have been deprecated. Note that the compiler may still accept these options, but may not do so in future releases. Begin using the suggested alternative option as soon as possible.

Table A–15 Obsolete Options Table

Option  

Action  

-dalign

Use -xmemalign=8s instead.

-KPIC (SPARC)

Use -xcode=pic32 instead.

-Kpic (SPARC)

Use -xcode=pic13 instead.

-misalign

Use -xmemalign=1i instead.

-misalign2

Use -xmemalign=2i instead.

-x386

Use -xchip=generic instead.

-x486

Use -xchip=generic instead.

-xa

Use -xprofile=tcov instead.

-xcg

Use -O instead to take advantage of the default values for -xarch, -xchip, and -xcache.

-xnativeconnect

Obsolete, there is no alternative option. 

-xprefetch=yes

Use -xprefetch=auto,explicit instead.

-xprefetch=no

Use -xprefetch=no%auto,no%explicit instead.

-xsb

Obsolete, there is no alternative option. 

-xsbfast 

Obsolete, there is no alternative option. 

-xtarget=386

Use -xtarget=generic instead.

-xtarget=486

Use -xtarget=generic instead.

-xvector=yes

Use -xvector=lib instead.

-xvector=no

Use -xvecttor=none instead.