C User's Guide

This chapter describes the C compiler 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 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, Section A.3.59, -X[c|a|t|s]. Using them makes the transition to ISO C easier. Also refer to the discussion on the transition in Chapter 7.

---

A.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 Section A.3, The cc Options
• 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.

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

---

A.2 Options Summary

In this section, the compiler options are grouped by function to provide an easy reference. The details are in the sections of the following pages. The following table summarizes the cc compiler options by functionality. Some flags serve more than one purpose and appear more than once.

---

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

A.3.1 -#

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

A.3.2 -###

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

A.3.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) (Intel)
• cpu(sparc) (SPARC)
• cpu(i386) (Intel)

These preassertions are not valid in -Xc mode.

A.3.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).

A.3.5 -C

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

A.3.6 -c

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

A.3.7 -Dname[=tokens]

Associates name with the specified tokens as if by a #define preprocessing directive. If no =tokens is specified, the token 1 is supplied.

Predefinitions (not valid in -Xc mode):

• sun
• unix
• sparc (SPARC)
• i386 (Intel)

The following predefinitions are valid in all modes.

• __sparcv9 (-xarch=v9, v9a, v9b)
• __sun
• __unix
• __SUNPRO_C=0x550
• __`uname -s`_`uname -r` (example: __SunOS_5_7)
• __sparc (SPARC)
• __i386 (Intel)
• __BUILTIN_VA_ARG_INCR
• __SVR4

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.

A.3.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).

A.3.9 -dalign

-dalign is equivalent to -xmemalign=8s. See Section A.3.102, -xmemalign=ab.

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

A.3.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 use this option, the compiler sets it to -errfmt=no%error. If you use specify -errfmt, but do not supply a value, the compiler sets it to -errfmt=error.

A.3.12 -erroff[=t]

This command suppresses C compiler warning messages and has no effect on error 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 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 Section 2.8.5, error_messages.

A.3.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 use -errshort, the compiler sets the option to -errshort=full. If you specify -errshort, but do not provide a value, the compiler sets the option to -errshort=tags.

This option does not accumulate, it accepts the last value specified on the command line.

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

A.3.15 -errwarn[=t]

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

A.3.16 -fast

Selects a set of baseline options for optimizing benchmark applications. These optimizations may alter the behavior of programs from that defined by the ISO C and IEEE standards. Modules compiled with -fast must also be linked with -fast.

-fast is a macro option 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. We suggest that you use the -# option to examine the expansion of -fast, and incorporate the appropriate options of -fast into the ongoing process of tunning the executable.

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.

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.

In previous releases, the -fast macro option included -fnonstd; now it includes -fns instead.

-fast also defines the macro __MATHERR_ERRNO_DONTCARE. This macro causes math.h to assert performance-related pragmas such as the following for some math routines prototyped in <math.h>:

• #pragma does_not_read_global_data
• #pragma does_not_write_global_data
• #pragma no_side_effect

If your code relies on the return value of errno in exceptional cases as documented in the matherr(3M) man page, you must turn off the macro by issuing the -U__MATHERR_ERRNO_DONTCARE macro after the -fast option.

You can usually improve performance for most programs with this option.

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.

See -# and -### for details of how you can see the expansion of macro options.

A.3.17 -fd

Reports K&R-style function definitions and declarations.

A.3.18 -flags

Prints a brief summary of each available compiler option.

A.3.19 -fnonstd

Causes nonstandard initialization of floating-point arithmetic hardware. In addition, the -fnonstd option causes hardware traps to be enabled for floating-point overflow, division by zero, and invalid operations exceptions. These are converted into SIGFPE signals; if the program has no SIGFPE handler, it terminates with a memory dump.

By default, IEEE 754 floating-point arithmetic is nonstop, and underflows are gradual. (See Section 2.4, Floating Point, Nonstandard Mode for a further explanation.)

(SPARC) Synonym for -fns -ftrap=common.

A.3.20 -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. This flag enables the nonstandard floating point mode when a program begins execution. By default, the non-standard floating point mode will not be enabled automatically.

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.

A.3.21 -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 Intel, only the precision, not exponent, range is affected by the setting of floating-point rounding precision mode.

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

A.3.23 -fsimple[=n]

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

If n is present, it must be 0, 1, or 2. The defaults are:

• With no -fsimple[=n], the compiler uses -fsimple=0
• With only -fsimple, no =n, the compiler uses -fsimple=1

-fsimple=0

Permits no simplifying assumptions. Preserve strict IEEE 754 conformance.

-fsimple=1

Allows conservative simplifications. The resulting code does not strictly conform to IEEE 754, but numeric results of most programs are unchanged.

With -fsimple=1, the optimizer can assume the following:

• IEEE 754 default rounding/trapping modes do not change after process initialization.
• Computations producing no visible result other than potential floating point exceptions may be deleted.
• Computations with Infinity or NaNs as operands need not propagate NaNs to their results; for example, x*0 may be replaced by 0.
• Computations do not depend on sign of zero.

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

-fsimple=2

Permits aggressive floating point optimizations that may cause many programs to produce different numeric results due to changes in rounding. For example, -fsimple=2 permits the optimizer to replace all computations of x/y in a given loop with x*z, where x/y is guaranteed to be evaluated at least once in the loop, z=1/y, and the values of y and z are known to have constant values during execution of the loop.

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

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

A.3.25 -fstore

(Intel) 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.

A.3.26 -ftrap=t

Sets the IEEE 754 trapping mode in effect at startup.

t is a comma-separated list that consists of one or more of the following: %all, %none, common, [no%]invalid, [no%]overflow, [no%]underflow, [no%</