606 lines
14 KiB
Groff
606 lines
14 KiB
Groff
.\" $Id$
|
|
.TH LCC 1 "local \- $Date$"
|
|
.SH NAME
|
|
lcc \- ANSI C compiler
|
|
.SH SYNOPSIS
|
|
.B lcc
|
|
[
|
|
.I option
|
|
|
|
|
.I file
|
|
]...
|
|
.br
|
|
.SH DESCRIPTION
|
|
.PP
|
|
.I lcc
|
|
is an ANSI C compiler for a variety of platforms.
|
|
.PP
|
|
Arguments whose names end with `.c' (plus `.C' under Windows) 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' (Windows)
|
|
substituted for the extension.
|
|
Arguments whose names end with `.i' are treated similarly,
|
|
except they are not preprocessed.
|
|
In the same way,
|
|
arguments ending with `.s' (plus `.S', `.asm', and `.ASM', under Windows)
|
|
are taken to be assembly source programs
|
|
and are assembled, producing an object file.
|
|
If there are no arguments,
|
|
.I lcc
|
|
summarizes its options on the standard error.
|
|
.PP
|
|
.I lcc
|
|
deletes an object file if and only if exactly one
|
|
source file is mentioned and no other file
|
|
(source, object, library) or
|
|
.B \-l
|
|
option is mentioned.
|
|
.PP
|
|
If the environment variable
|
|
.B LCCINPUTS
|
|
is set,
|
|
.I lcc
|
|
assumes it gives a semicolon- or colon-separated list of directories in which to
|
|
look for source and object files whose names do not begin with `/'.
|
|
These directories are also added to the list of directories
|
|
searched for libraries.
|
|
If
|
|
.B LCCINPUTS
|
|
is defined, it must contain `.' in order for the current directory
|
|
to be searched for input files.
|
|
.PP
|
|
.I lcc
|
|
uses ANSI standard header files (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 .
|
|
Under Windows, if the environment variable
|
|
.B include
|
|
is defined, it gives a semicolon-separated list of directories in which to search for
|
|
header files.
|
|
.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
|
|
.BI \-Wf\-g n , x
|
|
Set the debugging level to
|
|
.I n
|
|
and emit source code as comments into the generated assembly code;
|
|
.I x
|
|
must be the assembly language comment character.
|
|
If
|
|
.I n
|
|
is omitted, it defaults to 1, which is similar to
|
|
.BR \-g .
|
|
Omitting
|
|
.BI , x
|
|
just sets the debugging level to
|
|
.IR n .
|
|
.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
|
|
.B \-A
|
|
Warns about
|
|
declarations and casts of function types without prototypes,
|
|
assignments between pointers to ints and pointers to enums, and
|
|
conversions from pointers to smaller integral types.
|
|
A second
|
|
.B \-A
|
|
warns about
|
|
unrecognized control lines,
|
|
nonANSI 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
|
|
.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 typedefs 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
|
|
.B \-O
|
|
is ignored.
|
|
.TP
|
|
.B \-S
|
|
Compile the named C programs, and leave the
|
|
assembler-language output on corresponding files suffixed `.s' or `.asm'.
|
|
.TP
|
|
.B \-E
|
|
Run only the preprocessor on the named C programs
|
|
and unsuffixed file arguments,
|
|
and send the result to the standard output.
|
|
.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' (UNIX) or `a.exe' (Windows) 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
|
|
.BI \-D name=def
|
|
Define the
|
|
.I name
|
|
to the preprocessor, as if by `#define'.
|
|
If
|
|
.I =def
|
|
is omitted, the name is defined as "1".
|
|
.TP
|
|
.BI \-U name
|
|
Remove any initial definition of
|
|
.IR name .
|
|
.TP
|
|
.BI \-I dir
|
|
`#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
|
|
.B \-I
|
|
options, then in directories on a standard list.
|
|
.TP
|
|
.B \-N
|
|
Do not search
|
|
.I any
|
|
of the standard directories for `#include' files.
|
|
Only those directories specified by subsequent explicit
|
|
.B \-I
|
|
options will be searched, in the order given.
|
|
.TP
|
|
.BI \-B str
|
|
Use the compiler
|
|
.BI "" str rcc
|
|
instead of the default version.
|
|
Note that
|
|
.I str
|
|
often requires a trailing slash.
|
|
On Sparcs only,
|
|
.B \-Bstatic
|
|
and
|
|
.BI \-Bdynamic
|
|
are passed to the loader; see
|
|
.IR ld (1).
|
|
.TP
|
|
.BI \-Wo\-lccdir= dir
|
|
Find the preprocessor, compiler proper, and include directory
|
|
in the directory
|
|
.I dir/
|
|
or
|
|
.I
|
|
dir\\.
|
|
If the environment variable
|
|
.B LCCDIR
|
|
is defined, it gives this directory.
|
|
.I lcc
|
|
warns when this option is unsupported.
|
|
.TP
|
|
.B \-Wf-unsigned_char=1
|
|
.br
|
|
.ns
|
|
.TP
|
|
.B \-Wf-unsigned_char=0
|
|
makes plain
|
|
.B char
|
|
an unsigned (1) or signed (0) type; by default,
|
|
.B char
|
|
is signed.
|
|
.TP
|
|
.B \-Wf\-wchar_t=unsigned_char
|
|
.br
|
|
.ns
|
|
.TP
|
|
.B \-Wf\-wchar_t=unsigned_short
|
|
.br
|
|
.ns
|
|
.TP
|
|
.B \-Wf\-wchar_t=unsigned_int
|
|
Makes wide characters the type indicated; by default,
|
|
wide characters are unsigned short ints, and
|
|
.B wchar_t
|
|
is a typedef for unsigned short defined in stddef.h.
|
|
The definition for
|
|
.B wchar_t
|
|
in stddef.h must correspond to the type specified.
|
|
.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
|
|
.BR \-help " or " \-?
|
|
Print a message on the standard error summarizing
|
|
.IR lcc 's
|
|
options and giving the values of the environment variables
|
|
.B LCCINPUTS
|
|
and
|
|
.BR LCCDIR ,
|
|
if they are defined.
|
|
Under Windows, the values of
|
|
.B include
|
|
and
|
|
.B lib
|
|
are also given, if they are defined.
|
|
.TP
|
|
.B \-b
|
|
Produce code that counts the number of times each expression is executed.
|
|
If loading takes place, arrange for a
|
|
.B prof.out
|
|
file to be written 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
|
|
.BI \-t name
|
|
.br
|
|
.ns
|
|
.TP
|
|
.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.
|
|
.BI \-target
|
|
.I name
|
|
is accepted, but ignored.
|
|
.TP
|
|
.BI \-tempdir= dir
|
|
Store temporary files in the directory
|
|
.I dir/
|
|
or
|
|
.I
|
|
dir\\.
|
|
The default is usually
|
|
.BR /tmp .
|
|
.TP
|
|
.BI \-W xarg
|
|
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.
|
|
.BI \-Wo arg
|
|
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 object 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
|
|
(UNIX) or
|
|
.BR a.exe
|
|
(Windows).
|
|
.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 adjusted 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 ).
|
|
.PP
|
|
.I lcc
|
|
is a cross compiler;
|
|
.BI \-Wf\-target= target/os
|
|
causes
|
|
.I lcc
|
|
to generate code for
|
|
.I target
|
|
running the operating system denoted by
|
|
.IR os .
|
|
The supported
|
|
.I target/os
|
|
combinations may include
|
|
.PP
|
|
.RS
|
|
.ta \w'sparc/solarisxx'u
|
|
.nf
|
|
alpha/osf ALPHA, OSF 3.2
|
|
mips/irix big-endian MIPS, IRIX 5.2
|
|
mips/ultrix little-endian MIPS, ULTRIX 4.3
|
|
sparc/solaris SPARC, Solaris 2.3
|
|
x86/win32 x86, Windows NT 4.0/Windows 95/98
|
|
x86/linux x86, Linux
|
|
symbolic text rendition of the generated code
|
|
null no output
|
|
.fi
|
|
.RE
|
|
.PP
|
|
For
|
|
.BR \-Wf\-target=symbolic ,
|
|
the option
|
|
.B \-Wf-html
|
|
causes the text rendition to be emitted as HTML.
|
|
.B
|
|
.SH LIMITATIONS
|
|
.PP
|
|
.I lcc
|
|
accepts the C programming language
|
|
as described in the ANSI standard.
|
|
If
|
|
.I lcc
|
|
is used with the GNU C preprocessor, the
|
|
.B \-Wp\-trigraphs
|
|
option is required to enable trigraph sequences.
|
|
.PP
|
|
Plain int bit fields are signed.
|
|
Bit fields are aligned like unsigned integers but are otherwise laid out
|
|
as by most standard C compilers.
|
|
Some compilers, such as the GNU C compiler,
|
|
may choose other, incompatible layouts.
|
|
.PP
|
|
Likewise, calling conventions are intended to be compatible with
|
|
the host C compiler,
|
|
except possibly for passing and returning structures.
|
|
Specifically,
|
|
.I lcc
|
|
passes and returns structures like host ANSI C compilers
|
|
on most targets, but some older host C compilers use different conventions.
|
|
Consequently, calls to/from such functions compiled with
|
|
older 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 fault.
|
|
.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
|
|
.RS
|
|
.ta \w'$LCCDIR/liblcc.{a,lib}XX'u
|
|
.nf
|
|
file.{c,C} input file
|
|
file.{s,asm} assembly-language file
|
|
file.{o,obj} object file
|
|
a.{out,exe} loaded output
|
|
/tmp/lcc* temporary files
|
|
$LCCDIR/cpp preprocessor
|
|
$LCCDIR/rcc compiler
|
|
$LCCDIR/liblcc.{a,lib} \fIlcc\fP-specific library
|
|
/lib/crt0.o runtime startup (UNIX)
|
|
/lib/[gm]crt0.o startups for profiling (UNIX)
|
|
/lib/libc.a standard library (UNIX)
|
|
$LCCDIR/include ANSI standard headers
|
|
/usr/local/include local 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
|
|
.RE
|
|
.PP
|
|
.I lcc
|
|
predefines the macro
|
|
.B __LCC__
|
|
on all systems.
|
|
It may also predefine some installation-dependent symbols; option
|
|
.B \-v
|
|
exposes them.
|
|
.SH "SEE ALSO"
|
|
.PP
|
|
C. W. Fraser and D. R. Hanson,
|
|
.I A Retargetable C Compiler: Design and Implementation,
|
|
Addison-Wesley, 1995. ISBN 0-8053-1670-1.
|
|
.PP
|
|
The World-Wide Web page at http://www.cs.princeton.edu/software/lcc/.
|
|
.PP
|
|
S. P. Harbison and G. L. Steele, Jr.,
|
|
.I C: A Reference Manual,
|
|
4th ed., Prentice-Hall, 1995.
|
|
.PP
|
|
B. W. Kernighan and D. M. Ritchie,
|
|
.I The C Programming Language,
|
|
2nd ed., Prentice-Hall, 1988.
|
|
.PP
|
|
American National Standards Inst.,
|
|
.I American National Standard for Information Systems\(emProgramming
|
|
.IR Language\(emC ,
|
|
ANSI X3.159-1989, New York, 1990.
|
|
.br
|
|
.SH BUGS
|
|
Mail bug reports along with the shortest preprocessed program
|
|
that exposes them and the details reported by
|
|
.IR lcc 's
|
|
.B \-v
|
|
option to lcc-bugs@princeton.edu. The WWW page at
|
|
URL http://www.cs.princeton.edu/software/lcc/
|
|
includes detailed instructions for reporting bugs.
|
|
.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
|
|
some local C libraries (e.g., wide-character functions)
|
|
or may not correspond exactly to the local versions;
|
|
for example, the ANSI standard
|
|
stdio.h
|
|
specifies that
|
|
.IR printf ,
|
|
.IR fprintf ,
|
|
and
|
|
.I sprintf
|
|
return the number of characters written to the file or array,
|
|
but some existing libraries don't implement this convention.
|
|
.PP
|
|
On the MIPS and SPARC, old-style variadic functions must use
|
|
varargs.h
|
|
from MIPS or Sun. New-style is recommended.
|
|
.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.
|