.TH LCC 1 "local \- 4/13/93"
.SH NAME
lcc \- local ANSI C compiler
.SH SYNOPSIS
.B lcc
[
.I option
|
.I file
]...
.br
.SH DESCRIPTION
.PP
.I lcc
is a local ANSI C compiler for the VAX, MIPS, SPARC, and Motorola MC68020.
.PP
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' 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' file.
.PP
.I lcc
deletes a `.o' file if and only if exactly one
source file (`.c', `.s', or `.i' file) is mentioned and no other file
(source, object, library) or
.B \-l
option is mentioned.
.PP
.I lcc
uses ANSI standard header files
in preference to the `old-style' header files normally found in
.B /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
.BR /usr/include .
.PP
.I lcc
interprets the following options; unrecognized options are
taken as loader options (see
.IR ld (1))
unless
.BR \-c ,
.BR \-S ,
or
.B \-E
precedes them.
Except for
.BR \-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.
.TP
.B \-c
Suppress the loading phase of the compilation, and force
an object file to be produced even if only one program is compiled.
.TP
.B \-g
Produce additional symbol table information for the local debuggers.
.I lcc
warns when
.B \-g
is unsupported.
.TP
.B \-w
Suppress warning diagnostics, such as those
announcing unreferenced statics, locals, and parameters.
The line
.I
#pragma ref id
simulates a reference to the variable 
.IR id .
.TP
.BI \-d n
Generate jump tables for switches whose density is at least
.IR n ,
a floating point constant between zero and one.
The default is 0.5.
.TP
.SM
.B \-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
.SM
.B \-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
.I 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.
.TP
.SM
.B \-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.
.TP
.B \-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
.IR abort (3).
.TP
.SM
.B \-O
is ignored.
.TP
.SM
.B \-S
Compile the named C programs, and leave the
assembler-language output on corresponding files suffixed `.s'.
.TP
.SM
.B \-E
Run only the preprocessor on the named C programs
and unsuffixed file arguments,
and send the result to the standard output.
.TP
.SM
.B \-C
Prevent the preprocessor from eliding comments.
.TP
.BI \-o "  output"
Name the output file
.IR output .
If
.B \-c
or
.B \-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' is left undisturbed.
.I lcc
warns if
.B \-o
and
.B \-c
or
.B \-S
are given with more than one source file and ignores the
.B \-o
option.
.TP
.SM
.BI \-D \*Sname=def
.br
.ns
.TP
.SM
.BI \-D \*Sname
Define the
.I name
to the preprocessor, as if by `#define'.
If no definition is given, the name is defined as "1".
.TP
.SM
.BI \-U \*Sname
Remove any initial definition of
.IR name .
.TP
.SM
.BI \-I \*Sdir
`#include' files
whose names do not begin with `/' are always
sought first in the directory of the
.I file
arguments, then in directories named in
.SM
.B \-I
options, then in directories on a standard list.
.TP
.SM
.B \-N
Do not search
.I any
of the standard directories for `#include' files.
Only those directories specified by explicit
.SM
.B \-I
options will be searched, in the order given.
.TP
.SM
.BI \-B \*Sstr
Use the compiler \fIstr\fP\fBrcc\fP instead of the default version.
Note that
.I str
often requires a trailing slash.
On Suns only,
.SM
.B \-Bstatic
and
.SM
.BI \-Bdynamic
are passed to the loader; see
.IR ld (1).
.TP
.B \-v
Print commands as they are executed; some of the executed
programs are directed to print their version numbers.
More than one occurrence of
.B \-v
causes the commands to be printed, but
.I not
executed.
.TP
.B \-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
.B prof.out
file when the object program terminates.
A listing annotated with execution counts can then be generated with
.IR bprint (1).
.I lcc
warns when
.B \-b
is unsupported.
.B \-Wf-C
is similar, but counts only the number of function calls.
.TP
.B \-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
.IR monitor (3)
at the start and arranges to write a
.B mon.out
file when the object program terminates normally.
An execution profile can then be generated with
.IR prof (1).
.I lcc
warns when
.B \-p
is unsupported.
.TP
.B \-pg
Causes the compiler to produce counting code like
.BR \-p ,
but invokes a run-time recording mechanism that keeps more
extensive statistics and produces a 
.B 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
.IR gprof (1).
.I lcc
warns when
.B \-pg
is unsupported.
.TP
.SM
.BI \-t \*Sname
.br
.ns
.TP
.SM
.BI \-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,
.I printf
does the printing; if
.I name
appears, it does.
For null
.I char*
values, "(null)" is printed. 
On Suns only,
.SM
.BI \-target
.I name
is accepted, but ignored.
.TP
.SM
.BI \-W \*Sx \fIarg\fP
pass argument
.I arg
to the program indicated by
.IR x ;
.I x
can be one of
.BR p ,
.BR f ,
.BR a ,
or
.BR l ,
which refer, respectively, to the preprocessor, the compiler proper,
the assembler, and the loader.
.I arg
is passed as given; if a
.B \-
is expected, it must be given explicitly.
.SM
.BI \-W \*So \fIarg\fP
specifies a system-specific option,
.IR arg .
.PP
Other arguments
are taken to be either loader option arguments, or C-compatible
object programs, typically produced by an earlier
.I lcc
run, or perhaps libraries of C-compatible routines.
Duplicate `.o' files are ignored.
These programs, together with the results of any
compilations specified, are loaded (in the order
given) to produce an executable program with name
.BR a.out .
.PP
.I 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.
.B \-Wf-a
causes
.I lcc
to read a
.B prof.out
file from a previous execution and to use the data therein
to compute reference counts (see
.BR \-b ).
.SH LIMITATIONS
.PP
.I lcc
accepts the C programming language
as described in the proposed ANSI standard
and in the second edition of Kernighan and Ritchie.
.I lcc
is intended to be used with the GNU C preprocessor, which supports the
preprocessing features introduced by the ANSI standard.
The
.SM
.B \-Wp-trigraphs
option is required to enable trigraph sequences.
.PP
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,
.IR cc (1).
Other compilers, such as the GNU C compiler,
.IR gcc (1),
may choose other, incompatible layouts.
.PP
Likewise, calling conventions are intended to be compatible with
.IR cc (1),
except possibly for passing and returning structures.
Specifically,
.I lcc
passes structures like
.I cc
on all targets,
but returns structures like
.I cc
on only the MIPS.
Consequently, calls to/from such functions compiled with
.I 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.
.SH FILES
.PP
The file names listed below are
.IR typical ,
but vary among installations; installation-dependent variants
can be displayed by running
.I lcc
with the
.B \-v
option.
.PP
.ta \w'/usr/lib/gcc-cppxx'u
.nf
file.c	input file
file.o	object file
a.out	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 startoff
/lib/[gm]crt0.o	startoffs 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 \fIbprint\fR(1)
mon.out	file produced for \fIprof\fR(1)
gmon.out	file produced for \fIgprof\fR(1)
.fi
.PP
.I lcc
predefines the macros `unix' and `__LCC__'.
It may also predefine some installation-dependent symbols; option
.B \-v
exposes them.
.SH "SEE ALSO"
B. W. Kernighan and D. M. Ritchie,
.I The C Programming Language,
Prentice-Hall, 2nd Ed., 1988.
.PP
.I
American National Standard for Information Systems, Programming Language C,
ANSI X3.159-1989, American National Standard Institute, Inc., New York, 1990.
.PP
cc(1), ld(1)
.br
.SH BUGS
Mail bug reports along with the shortest program
that exposes them and the details reported by
.IR lcc 's
.B \-v
option to lcc-bugs@princeton.edu.
.PP
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
.B stdio.h
specifies that
.IR printf ,
.IR fprintf ,
and
.I sprintf
return the number of characters written to the file or array,
but few existing libraries implement this convention.
.PP
On VAXes running 4.3bsd UNIX,
the definitions of
.I tolower
and
.I toupper
erroneously return bad values for non-letter arguments.
.PP
On the MIPS and SPARC, old-style variadic functions must use
.B varargs.h
from MIPS or Sun. New-style is recommended.
.PP
The Sun assembler version 3.5 or later is required on the MC68020,
and only the MC68881 is supported.
.PP
With
.BR \-b ,
files compiled
.I without
.B \-b
may cause
.I bprint
to print erroneous call graphs.
For example, if
.B f
calls
.B g
calls
.B h
and
.B f
and
.B h
are compiled with
.BR \-b ,
but
.B g
is not,
.B bprint
will report that
.B f
called
.BR h .
The total number of calls is correct, however.