NAME

SYNOPSIS

DESCRIPTION

lcc is a local ANSI C compiler for the MIPS, SPARC, and Intel 386 and its successors.

Arguments whose names end with `.c' are taken to be C source programs; they are preprocessed, compiled, and each object program is left on the file whose name is that of the source with `.o' (UNIX) or `.obj' (DOS) substituted for `.c'. Arguments whose names end with `.i' are treated similarly, except they are not preprocessed. In the same way, arguments whose names end with `.s' are taken to be assembly source programs and are assembled, producing a `.o' (UNIX) or `.obj' (DOS) file. If there are no arguments, lcc prints a message summarizing its options on the standard error.

lcc deletes a `.o' (UNIX) or `.obj' (DOS) file if and only if exactly one source file (`.c', `.s', or `.i' file) is mentioned and no other file (source, object, library) or -l option is mentioned.

lcc uses ANSI standard header files in preference to the `old-style' header files normally found in /usr/include (see `FILES' below). Include files not found in the ANSI header files are taken from the normal default include areas, which usually includes /usr/include.

lcc interprets the following options; unrecognized options are taken as loader options (see ld(1)) unless -c, -S, or -E precedes them. Except for -l, all options are processed before any of the files and apply to all of the files. Applicable options are passed to each compilation phase in the order given.

-c

Suppress the loading phase of the compilation, and force an object file to be produced even if only one program is compiled.

-g

Produce additional symbol table information for the local debuggers. lcc warns when -g is unsupported.

-w

Suppress warning diagnostics, such as those announcing unreferenced statics, locals, and parameters. The line #pragma ref id simulates a reference to the variable id.

-dn

Generate jump tables for switches whose density is at least n, a floating point constant between zero and one. The default is 0.5.

.SM

-A Warns about declarations and casts of function types without prototypes, missing return values in returns from int functions, assignments between pointers to ints and pointers to enums, and conversions from pointers to smaller integral types. A second -A warns about unrecognized control lines, non-ANSI language extensions and source characters in literals, unreferenced variables and static functions, declaring arrays of incomplete types, and exceeding some ANSI environmental limits, like more than 257 cases in switches. It also arranges for duplicate global definitions in separately compiled files to cause loader errors.

.SM

-P Writes declarations for all defined globals on standard error. Function declarations include prototypes; editing this output can simplify conversion to ANSI C. This output may not correspond to the input when there are several typedef's for the same type.

-n

Arrange for the compiler to produce code that tests for dereferencing zero pointers. The code reports the offending file and line number and calls abort(3).

.SM

-O is ignored.

.SM

-S Compile the named C programs, and leave the assembler-language output on corresponding files suffixed `.s'.

.SM

-E Run only the preprocessor on the named C programs and unsuffixed file arguments, and send the result to the standard output.

-o output

Name the output file output. If -c or -S is specified and there is exactly one source file, this option names the object or assembly file, respectively. Otherwise, this option names the final executable file generated by the loader, and `a.out' (UNIX) or `a.exe' (DOS) is left undisturbed. lcc warns if -o and -c or -S are given with more than one source file and ignores the -o option.

.SM

-D\*Sname=def

.SM

-D\*Sname Define the name to the preprocessor, as if by `#define'. If no definition is given, the name is defined as "1".

.SM

-U\*Sname Remove any initial definition of name.

.SM

-I\*Sdir `#include' files whose names do not begin with `/' are always sought first in the directory of the file arguments, then in directories named in -I options, then in directories on a standard list.

.SM

-N Do not search any of the standard directories for `#include' files. Only those directories specified by explicit -I options will be searched, in the order given.

.SM

-B\*Sstr Use the compiler strrcc instead of the default version. Note that str often requires a trailing slash. On Suns only, -Bstatic and -Bdynamic are passed to the loader; see ld(1).

-v

Print commands as they are executed; some of the executed programs are directed to print their version numbers. More than one occurrence of -v causes the commands to be printed, but not executed.

-help

Print a message summarizing lcc's options on the standard error.

-b

Produce code that counts the number of times each expression is executed. If loading takes place, replace the standard exit function by one that writes a prof.out file when the object program terminates. A listing annotated with execution counts can then be generated with bprint(1). lcc warns when -b is unsupported. -Wf-C is similar, but counts only the number of function calls.

-p

Produce code that counts the number of times each function is called. If loading takes place, replace the standard startup function by one that automatically calls monitor(3) at the start and arranges to write a mon.out file when the object program terminates normally. An execution profile can then be generated with prof(1). lcc warns when -p is unsupported.

-pg

Causes the compiler to produce counting code like -p, but invokes a run-time recording mechanism that keeps more extensive statistics and produces a gmon.out file at normal termination. Also, a profiling library is searched, in lieu of the standard C library. An execution profile can then be generated with gprof(1). lcc warns when -pg is unsupported.

.SM

-t\*Sname

.SM

-t Produce code to print the name of the function, an activation number, and the name and value of each argument at function entry. At function exit, produce code to print the name of the function, the activation number, and the return value. By default, printf does the printing; if name appears, it does. For null char* values, "(null)" is printed. On Suns only, -target name is accepted, but ignored.

.SM

-W\*Sxarg pass argument arg to the program indicated by x; x can be one of p, f, a, or l, which refer, respectively, to the preprocessor, the compiler proper, the assembler, and the loader. arg is passed as given; if a - is expected, it must be given explicitly. -W\*Soarg specifies a system-specific option, arg.

-pipe

forces lcc to pipe the preprocessor output directly to the compiler instead of using temporary files.

lcc assigns the most frequently referenced scalar parameters and locals to registers whenever possible. For each block, explicit register declarations are obeyed first; remaining registers are assigned to automatic locals if they are `referenced' at least 3 times. Each top-level occurrence of an identifier counts as 1 reference. Occurrences in a loop, either of the then/else arms of an if statement, or a case in a switch statement each count, respectively, as 10, 1/2, or 1/10 references. These values are increased accordingly for nested control structures. -Wf-a causes lcc to read a prof.out file from a previous execution and to use the data therein to compute reference counts (see -b).

lcc is a cross compiler; -Wf-target=target-os causes lcc to generate code for target running the operating system denoted by os. The supported target-os combinations may include

mips-irix	big-endian MIPS, IRIX 4.0
mips-ultrix	little-endian MIPS, ULTRIX 4.3
sparc-sun	SPARC, SunOS 4.1
sparc-solaris	SPARC, Solaris 2.3
x86-dos	[345]86, DOS 6.0
symbolic	textual rendition of the generated code
null		no output

The -v option lists the target-os combinations supported by specific installations of lcc.

LIMITATIONS

lcc accepts the C programming language as described in the ANSI standard and in the second edition of Kernighan and Ritchie. lcc is intended to be used with the GNU C preprocessor, which supports the preprocessing features introduced by the ANSI standard. The -Wp-trigraphs option is required to enable trigraph sequences.

Wide-character literals are accepted but are treated as plain char literals. Plain chars are signed chars, ints and long ints are the same size as are doubles and long doubles, and plain int bit fields are signed. Bit fields are aligned like unsigned integers but are otherwise laid out as if by the standard C compiler, cc(1). Other compilers, such as the GNU C compiler, gcc(1), may choose other, incompatible layouts.

Likewise, calling conventions are intended to be compatible with cc(1), except possibly for passing and returning structures. Specifically, lcc passes structures like cc on all targets, but returns structures like cc on only the MIPS. Consequently, calls to/from such functions compiled with cc or other C compilers may not work. Calling a function that returns a structure without declaring it as such violates the ANSI standard and may cause a core dump.

FILES

The file names listed below are typical, but vary among installations; installation-dependent variants can be displayed by running lcc with the -v option.

file.c	input file
file.{o,obj}	object file
a.{out,exe}	loaded output
/tmp/lcc?	temporaries
/usr/lib/gcc-cpp	preprocessor
/usr/lib/rcc	compiler
/usr/lib/bbexit.o	exit for profiling
/lib/crt0.o	runtime startup
/lib/[gm]crt0.o	startups for profiling
/lib/libc.a	standard library
/usr/include/lcc	ANSI standard headers
/usr/include/libc	local ANSI headers
/usr/include	traditional headers
prof.out	file produced for bprint(1)
mon.out	file produced for prof(1)
gmon.out	file produced for gprof(1)

lcc predefines the macro `__LCC__' on all systems and the macros `unix' on UNIX systems. It may also predefine some installation-dependent symbols; option -v exposes them.

SEE ALSO

American National Standard for Information Systems, Programming Language C, ANSI X3.159-1989, American National Standards Institute, Inc., New York, 1990.

C. W. Fraser and D. R. Hanson, A Benjamin Cummings, 1995. ISBN 0-8053-1670-1.

The Wide World Web page at URL http://www.cs.princeton.edu/software/lcc.

cc(1), ld(1)

BUGS

The `ANSI standard headers' conform to the specifications in the standard, which may be too restrictive for some applications, but necessary for portability. Functions given in the ANSI headers may be missing from the local C library (e.g., `wide character' functions) or may not correspond exactly to the local version; for example, the ANSI standard stdio.h specifies that printf, fprintf, and sprintf return the number of characters written to the file or array, but few existing libraries implement this convention.

On the MIPS and SPARC, old-style variadic functions must use varargs.h from MIPS or Sun. New-style is recommended.

With -b, files compiled without -b may cause bprint to print erroneous call graphs. For example, if f calls g calls h and f and h are compiled with -b, but g is not, bprint will report that f called h. The total number of calls is correct, however.