NAME

lcc − Lucid ANSI C compiler

SYNOPSIS

lcc [ option ] ... file ... 

DESCRIPTION

lcc invokes the Lucid ANSI C compiler to compile ANSI C or K&R C source programs into assembly or object modules suitable for execution on SPARC-based systems under the SunOS 4.x operating system. 

lcc accepts a parameter list that consists of options and input file-names in any order.  Each input file-name must have one of the following suffixes:

.c, .i C source code file.  By UNIX convention, .i files contain "preprocessed" C code while .c files are user C modules. 

.s SPARC assembler source code file

.o object file (output of previous compiler or assembler run, input to linker)

Any file with none of the above suffixes is assumed to contain object code and is given to the linker. 

Unless otherwise specified, each .c, .i and .h file is translated by the compiler into a .o (object) file.  Each .s file is translated by the system assembler into a .o file.  Lastly, all the .o files are combined by the system linker, ld, into the executable result file.  If the output file name is not overridden with the "-o" option, the executable result is left in "a.out". 
 
With no parameters, or when no file names are present, lcc simply identifies itself, prints its version number, and displays a list of the most frequently needed options.
 
During its processing, lcc produces various intermediate files which are deleted after they are used. The -E, -X1, -S and -c options can be specified to terminate lcc processing at various intermediate points, leaving the corresponding intermediate files in the current working directory. By default, lcc compiles programs in extended ANSI C mode which is the same mode selected by the -Xa dialect selection option.  This (default) dialect can be overridden by use of the -XA option which invokes the strict ANSI C mode or the -Xk option which invokes the K&R mode. 
 
See the description of these options for definitions of each dialect as well as how the selected dialect can change while processing header (#include) files.

The following options are supported.  All other options, unless prefixed with -X, are passed to the linker without any processing. 

−Bstatic
Statically link the executable file, if one is created.  This will only affect the link phase and is used to suppress the default (dynamic) linking invoked by the compiler.  Due to the limitations of most debuggers in debugging dynamically linked programs, the -g (debug) option also implies -Bstatic.  The -Bdynamic switch can be used to override the latter behavior if necessary.

−c Suppress the loading phase of the compilation and leave the object module files (one .o file for each input file) in the current working directory. 

−C Leave the comments in the output of the preprocessor. This is ignored if the -E option is not specified. 

−dryrun Show the user what commands would be executed to compile his/her files.  Nothing gets executed, changed, or removed. 

−Dname=def

−Dname Define name to the preprocessor, as if by #define.  If no definition is given, name is defined as 1. 

−E Run only the preprocessor on the named C programs and send the result to the standard output. 

−g Produce additional symbol table information for use by a debugger.  This inhibits most optimizations, including inline expansion of calls to library functions and forces stack frames to be generated for all functions so the debugger can generate stack tracebacks.  It also implies passing -Bstatic to the linker because some debuggers work poorly with dynamically linked libraries. 

−h Show help information for the lcc command.  This also occurs if no file names are specified. 

−Idir #include files whose names do not begin with / and are enclosed in quotes (") are always sought first in the directory in which the including file resides, then in directories named in −I options.  Next, and only in ANSI C  modes, the files are sought in the Lucid ANSI C header directory.  Lastly, /usr/include is searched.  The same rules apply for include files whose names are enclosed in < and >, except that the including file’s directory is not searched. 

−lname Use the library libname.a to resolve any unresolved externals from all the files listed before this -l option.  See ld(1) for more information.  In ANSI C modes, the Lucid ANSI C library is automatically included after the last file-name to cause this library to be automatically searched.  In all modes, the option -lc as well as -lm are included at the end to cause the system C and Math libraries to be searched.  The Lucid ANSI C library can be excluded from the link process by the use of -X- option.  If profiling is selected by the -p option, "_p" is appended to the automatically generated -l options to cause the "profile" versions of the libraries to be searched and loaded. 

−Ldir Add dir to the list of directories in which to search for libraries at link time.  In ANSI modes, a -L option specifying the path name of the directory in which the Lucid libraries reside is automatically included after any -L options specified by the user.  See ld(1) for more information. 

−o output
Name the final output file output. If this parameter is not specified, the name of the final executable output will be a.out.  When compiling one file, this option can be used to name the resulting .o or .s file, if -c or -S is used.

−O This is the recommended optimization selection switch and is shorthand for "-O3".  See the description of "-O3" below. 

−O- Turn all optimizations off. 

−O0 Perform local optimizations on "extended" basic blocks as well as global register allocation.  This is the same as "-Oler" and is also the default optimization mode used if no "-O" options are specified. 

−O1 Perform all local optimizations, global register allocation, global constant propagation as well as code hoisting and induction variable elimination on inner loops (i.e. elimination of partial and total redundancies within loops).  This is shorthand for "-Olerg1". 

−O2 In addition to the "O1" optimizations, perform redundant store elimination and perform loop optimizations (code hoisting, induction variable elimination) on loop nests.  This is shorthand for the "-Olerg2". 

−O3 This is similar to the previous level except that it performs global copy propagation and extends the scope of elimination of partial and total redundancies to include entire functions, as opposed to loops.  This is the default for "-O" and is also shorthand for "-Olerg3s". 

−O4 This is similar to the previous level except that the global copy propagation and redundant store elimination phases are applied repeatedly (in practice up to 3 times) to each function, as long as each application results in further improvement of the generated code.  "-O4" is shorthand for "-Olerg4s". 

−O5 In addition to -O4 optimizations, make processor registers %g2-%g7 available for use by the optimizer.  This is equivalent to the combination of options, -O4 -OG.  See the descrition of -OG below. 

−O{ l,e,r,g,g1,g2,g3,g4,g5,s} This is a more detailed interface to the optimizer than the preferred "-O{-,0,1,2,3,4,5}" mechanism.  "l" is the local optimizer, "e" is the extended basic block optimizer, "r" is the global register allocator, "g" is the global optimizer, and "s" is the instruction scheduler.  "g1" thorough "g5" select increasingly higher level of global optimizations as described above, with "g" being shorthand for "g3".  Any combination of these options is acceptable (for example, "-Olge").  In case of conflicts the last option encountered is used.  If no "-O" option is used, then the compiler performs local optimizations and global register allocation, as if"-Oler" had been specified.  Also note that compilation time tends to increase with increased optimization level. 

−OG Consider all of the processor registers as available during the register-allocation phase.  Ordinarily, and to be compatible with the Sun C compiler code generation conventions, the lcc code generator will not use global registers %g2-%g7 within functions that require a register window (non-leaf function).  Relaxing this restriction may result in better code (performance) if compatibility is not a concern.  }

−Ou Perform the "loop unrolling" optimization.  This may have an impact on the size and layout of the generated code (i.e. beware of timing anomalies due to processor cache)

−p Produce "profiling" code that counts the number of times each routine is called, for use with system tool prof(1). 

−pg Produce counting code in the manner of −p, but invoke a run-time recording mechanism that keeps more extensive statistics at normal termination, for use with system tool gprof(1). 

−pic Generate position independent code in the "pic" model.  Position independent code is necessary for object modules that are to be part of a shared library. 

−PIC Generate position independent code in the "PIC" model.  Position independent code is necessary for object modules that are to be part of a shared library. 

−P Run only the preprocessor on the named C programs and send the results to the corresponding .i files. 

−S Stop the compilation after generating assembly code, leaving the assembly language .s file(s) in the current working directory. 

−Uname Remove any initial definition of name from the compilation environment.  This can be used to remove the compiler predefined preprocessor symbols (identifying the target, the compiler, etc.) from the compilation environment. 
 
The predefined symbols for each compiler dialect are as follows:
 

K&R	ANSI C	Extended ANSI C
__KR__	__STDC_EXTENDED__
	__NOT_KR	__NOT_KR
__lucid	__lucid	__lucid
__sparc	__sparc	__sparc
__sun	__sun	__sun
__unix	__unix	__unix
sparc		sparc
unix		unix

 
The symbol __STDC__ is defined as (decimal constant) 1 in the strict ANSI C mode and 2 in the extended ANSI C mode. It is not defined in the K&R mode.  Also note that the dialect-specific symbols __STDC__, defined for the ANSI C modes, as well as the symbols __DATE__, __FILE__, __LINE__, and __TIME__ which are defined for all dialects, cannot be manipulated with the -U option. 

−v Verbose mode.  Print out each top-level command that is executed by the compiler "driver" in invoking various compilation, assembly or link steps. 

−Wc,arg1[,arg2...] Hand off the argument[s] argi to pass c where c is one of [p02al] indicating the front-end/preprocessor, front-end, back-end, assembler, or link editor, respectively.  For example: -Wa,-m passes -m to the assembler. 

−w{u,c,a} Control warning diagnostics.  -w may be followed by one or more letters to selectively turn on various classes of warnings.  Specifically u indicates ordinary (i.e. "questionable usage") warnings, c indicates conformance warnings, and a denotes all warnings; that is, -wa means the same as -wuc.  If -w appears by itself with no following letters, then no warning messages will be printed.  Conformance warnings are dialect-specific warnings that are issued for usages that do not conform to the selected dialect.  For example, any text other than a comment following the #endif preprocessor directive on the same line is not permitted in ANSI C and will result in a compiler warning in -Xa or -XA modes.  The default warning option is −wu for -Xa mode −wuc for all other modes. 

−X- Do not supply the Lucid "include" directories for compilation or the Lucid libraries for linking.  This is to permit the user to specify desired include search directories or libraries (i.e. -I, -L and -l options) without possible interference from those (implicitly) supplied by the compiler. The system C library (-lc) will continue to be linked in with the code, though, when there are any unresolved references to the library elements. 

−X1 Stop compilation after the compiler front-end. This results in syntax and semantic checking of the source and generation of compiler intermediate files.  No object or assembly code will be generated. 

−XAIdir Indicates that the header files in dir and its subdirectories are written in ANSI C.  The companion -XKI option performs a similar function for K&R based include directories.  These are primarily for use in situations where the header files, developed independent from the application that include them, happen to belong to a different dialect.  Note that a directory can be specified for processing in one dialect while some of its subdirectories can be specified with a different dialect.  -XAI does not substitute for -I, it only affects the treatment of files that are included, not what directories are searched. 

−XA Conform to the ANSI C language and run-time library definition.  This is the recommended mode for "strictly" conforming applications that largely stay within the ANSI C specified run-time library in their interface to the system.  In general, access to other library functions should be harmless.  In some rare situations, however, link time problems (multiple definitions) or incorrect results at run time might occur due to duplication of internal data structures in the ANSI C specified functions and some of the system libraries. 

−Xa Supports the ANSI C dialect but primarily relies on the system (UNIX) C run-time library.  The library does not strictly conform to the ANSI C definition in a few minor aspects.  It does, however, provide consistent access to the entire (system) run-time library, the bulk of which is beyond that defined for ANSI C.  This is also referred to as the "extended ANSI C" dialect and is the compiler’s default mode.  Header files included from the /usr/include directory will be processed in K&R mode unless overridden with the use of the -XAI switch. 

−XAp Use  ANSI C preprocessing for this compilation, instead of that implied by the language dialect in effect.  This does not affect the preprocessing of those header files covered by -XKI option switch. 

−Xez Connect the compiler to the Energize server.  For information regarding Energize, refer to the User’s Guide for the Energize Programming System. 

−Xd Issue a warning message if a default (implicit) "int" type is used in the program.  This is useful in converting old programs to bring them to the ANSI C level. 

−XE Output the incorrect source line as part of error messages.  This is the default error reporting format. 

−Xe Do not output the source line in error messages. 

−XEL=nn Change the error limit to (the decimal value) nn.  Error limit is the number of errors that the compiler will report for a source file before it quits compiling that file.  By default the compiler reports 20 errors per file.  This limit can also be changed at compiler installation time. 

−XIdir For the (header) files included from the dir directory and its subdirectories, cancel the effect of any enclosing (covering) -XKI or -XAI switch, effectively reverting to the language dialect in effect outside any include files.  This is to enable the compiler to use the correct language dialect in compiling ANSI C header files installed in subdirectories under directories that may otherwise contain K&R style header files (e.g. /usr/include) and for which a -XKI option is specified. 

−XKIdir This is similar to the -XAI option but indicates that the header files are written in K&R C. 

−Xk Enforce the K&R C language definition, flagging non K&R constructs with warning messages.  Header files included from directories given with -XAI will be processed in the ANSI C mode. The -Xk option is recommended for use with older, pre-ANSI C programs to avoid undue aggravation. (The K&R C definition is primarily determined by the behavior of the pcc, the Portable C Compiler rather than Kernighan and Ritchie’s text.) 

−XKp Use  K&R style preprocessing for this compilation, instead of that implied by the language dialect in effect.  This does not affect the preprocessing of those header files covered by a -XAI option switch. 

−Xl

−Xli Sends a source listing file to standard output.  If "i" is present, the preprocessor include files are also listed. 

−XL

−XLi Similar to -Xl and -Xli, but the listing is left in a ".lst" file.  Diagnostics will still appear on standard error as well as in the listing file. 

−Xn Permit nesting of comments. 

−Xquiet Issue warnings for language usages that fall under the "quiet" change category of the ANSI C vs K&R C dialects.  These are constructs that are legal in both K&R C and ANSI C but which are interpreted differently in each dialect.  For example, the character constant ’\a’ is interpreted as the "alert" (BEL) character (ASCII 0x07) under ANSI C but is assumed to be identical to ’a’ (ASCII 0x41) in K&R mode. 

−Xs Truncate all symbols to 8 characters and issue error messages for name collisions due to this truncation.  This is valid only with the -Xk (K&R C) switch. 

−Xtemp=refix Use prefix as the prefix for the names of intermediate files.  If this parameter is not specified, a prefix of /tmp/ptmpid is used where pid is the current process id. 

−Xt Print the time (elapsed, user, system) spent in each compilation phase. 

−Xu Invoke the native UNIX C compiler, passing along all arguments except the -Xu option. 

−Xv Print the compiler’s version and serial number. 

−Xx Suppress inline expansion of certain library functions.  In the absence of this flag, such functions are always expanded inline. 

−Xz Causes storage for file-scope variables defined with no explicit storage class specifier (e.g. "int i;" outside any function body) to be allocated as "common".  This permits multiple definitions with no explicit storage class specifier to coexist.  Although both ANSI and K&R explicitly prohibit doing this, UNIX compilers have traditionally permitted it and many existing programs unknowingly depend upon it. 
 
To accommodate the existing practice, the -Xz switch is implicitly supplied for all dialects except for the strict ANSI C mode.

−Y [p02alSILU],dirname Specify a new path name, dirname, for the locations of the tools and directories designated in the first argument.  [p02alSILU] represents:

p       front-end/preprocessor
0       front-end
2       back-end
a       assembler
l       link editor
S       directory containing the start-up routines
I       default library directory searched by ld
U       second default library directory searched by ld

If the location of a tool is being specified, then the new path name for the tool will be dirname/tool.  If more than one -Y option is applied to any one tool or directory, then the last occurrence holds. 

−fe file-name Use file-name as the compiler front-end instead of the normal front-end. 

−be file-name Use file-name as the compiler back-end instead of the normal back-end. 

−as file-name Use file-name as the assembler instead of the normal assembler. 

−Xld file-name Use file-name as the linker instead of the normal linker. 

FILES

The following file types are either input files or are intermediate files whose names are derived from input files by deleting the prefix directories and changing the suffix.  The directories LucidInclude and LucidLib are configuration specific directories that are determined at the compiler installation time. 

file.s Assembler source code file

file.c C source code file

file.i Preprocessor output C source code file

file.lst Compiler generated listing file

file.n Compiler intermediate file output by the compiler front-end

file.o Object module (assembler output, linker input)

a.out (absolute) result file produced when the -o option is not used. 
 

OTHER FILES

/usr/include standard directory containing system header files. 

LucidInclude standard directory for ‘#include <...>’ files in the ANSI C modes (the exact name of this directory is determined at the compiler installation time). /usr/include will still be searched after other implicit "include" directories. 

LucidLib Lucid ANSI C run-time library. 
 

SEE ALSO

 
Energize Programming System User’s Guide, Lucid, Inc., April 1992. 
 
B. W. Kernighan and D. M. Ritchie, The C Programming Language, Prentice-Hall, 1978 (updated 1988). 
 
S. P. Harbison and G. L. Steele, C — A Reference Manual, Third Edition, Prentice-Hall, 1991. 
 
American National Standard for Information Systems — Programming Language C, ANSI X3.159-1989. 
 
 
IEEE Standard, Portable Operating System Interface for Computer Environments, IEEE Std 1003.1-1988. 
 
IEEE Standard, Binary Floating-Point Arithmetic, ANSI/IEEE Std 754-1985. 
 
ld(1) and SunOS Reference Manual, Sun Microsystems, Inc., P.N. 800-1751-10,  Rev. A of May 1988. 
 
SunOs 4.0, Programming Utilities & Libraries, Sun Microsystems, Inc., P.N. 800-1774-15,  Rev. A of May 1988. 
 

DIAGNOSTICS

In some cases, an erroneous statement may cause additional errors to be reported on subsequent statements where none exists.  Compilation is terminated if a preset number of errors (currently 20) are reported.  By default, the compiler’s error messages and warnings are somewhat verbose; use -Xe for terse messages. 
 

BUGS

If compilation and link steps are performed separately, the same dialect selection option should be in effect.  Otherwise wrong/incompatible libraries may be used during the link step.  In particular, when invoked only on .o, .s and .a files with no explicit dialect selection option, the extended ANSI C library will be used for linking.  The -XA option must be used explicitly when linking .o files that are the result of a previous strict ANSI C compilation. 
 

OTHER FEATURES

For most ANSI C applications, unless strict compliance with the ANSI C run-time library definition is necessary, extended ANSI C is the recommended dialect.  The strict mode may run into conflict with the non-ANSI C based system libraries, if the application refers to incompatible (non-ANSI C) UNIX library functions.  Refer to the description of -XA, -Xa and -Xk options for the differences between these dialects.  Also, the -Xquiet option can be used to help in migrating (from K&R C) to ANSI C. 

Lucid C Rev. 2.2   —  Last change: 8/18/92