1
.\" $Id: lcc.1 145 2001-10-17 21:53:10Z timo $
2
.TH LCC 1 "local \- $Date: 2001-10-17 16:53:10 -0500 (Wed, 17 Oct 2001) $"
16
is an ANSI C compiler for a variety of platforms.
18
Arguments whose names end with `.c' (plus `.C' under Windows) are taken to be
19
C source programs; they are preprocessed, compiled, and
20
each object program is left on the file
21
whose name is that of the source with `.o' (UNIX) or `.obj' (Windows)
22
substituted for the extension.
23
Arguments whose names end with `.i' are treated similarly,
24
except they are not preprocessed.
26
arguments ending with `.s' (plus `.S', `.asm', and `.ASM', under Windows)
27
are taken to be assembly source programs
28
and are assembled, producing an object file.
29
If there are no arguments,
31
summarizes its options on the standard error.
34
deletes an object file if and only if exactly one
35
source file is mentioned and no other file
36
(source, object, library) or
40
If the environment variable
44
assumes it gives a semicolon- or colon-separated list of directories in which to
45
look for source and object files whose names do not begin with `/'.
46
These directories are also added to the list of directories
47
searched for libraries.
50
is defined, it must contain `.' in order for the current directory
51
to be searched for input files.
54
uses ANSI standard header files (see `FILES' below).
55
Include files not found in the ANSI header files
56
are taken from the normal default include areas,
57
which usually includes
59
Under Windows, if the environment variable
61
is defined, it gives a semicolon-separated list of directories in which to search for
65
interprets the following options; unrecognized options are
66
taken as loader options (see
76
all options are processed before any of the files
77
and apply to all of the files.
78
Applicable options are passed to each compilation phase in the order given.
81
Suppress the loading phase of the compilation, and force
82
an object file to be produced even if only one program is compiled.
85
Produce additional symbol table information for the local debuggers.
92
Set the debugging level to
94
and emit source code as comments into the generated assembly code;
96
must be the assembly language comment character.
99
is omitted, it defaults to 1, which is similar to
103
just sets the debugging level to
107
Suppress warning diagnostics, such as those
108
announcing unreferenced statics, locals, and parameters.
112
simulates a reference to the variable
116
Generate jump tables for switches whose density is at least
118
a floating point constant between zero and one.
123
declarations and casts of function types without prototypes,
124
assignments between pointers to ints and pointers to enums, and
125
conversions from pointers to smaller integral types.
129
unrecognized control lines,
130
nonANSI language extensions and source characters in literals,
131
unreferenced variables and static functions,
132
declaring arrays of incomplete types,
135
ANSI environmental limits, like more than 257 cases in switches.
136
It also arranges for duplicate global definitions in separately compiled
137
files to cause loader errors.
140
Writes declarations for all defined globals on standard error.
141
Function declarations include prototypes;
142
editing this output can simplify conversion to ANSI C.
143
This output may not correspond to the input when
144
there are several typedefs for the same type.
147
Arrange for the compiler to produce code
148
that tests for dereferencing zero pointers.
149
The code reports the offending file and line number and calls
156
Compile the named C programs, and leave the
157
assembler-language output on corresponding files suffixed `.s' or `.asm'.
160
Run only the preprocessor on the named C programs
161
and unsuffixed file arguments,
162
and send the result to the standard output.
171
is specified and there is exactly one source file,
172
this option names the object or assembly file, respectively.
173
Otherwise, this option names the final executable
174
file generated by the loader, and `a.out' (UNIX) or `a.exe' (Windows) is left undisturbed.
182
are given with more than one source file and ignores the
189
to the preprocessor, as if by `#define'.
192
is omitted, the name is defined as "1".
195
Remove any initial definition of
200
whose names do not begin with `/' are always
201
sought first in the directory of the
203
arguments, then in directories named in
205
options, then in directories on a standard list.
210
of the standard directories for `#include' files.
211
Only those directories specified by subsequent explicit
213
options will be searched, in the order given.
218
instead of the default version.
221
often requires a trailing slash.
226
are passed to the loader; see
229
.BI \-Wo\-lccdir= dir
230
Find the preprocessor, compiler proper, and include directory
236
If the environment variable
238
is defined, it gives this directory.
240
warns when this option is unsupported.
242
.B \-Wf-unsigned_char=1
246
.B \-Wf-unsigned_char=0
249
an unsigned (1) or signed (0) type; by default,
253
.B \-Wf\-wchar_t=unsigned_char
257
.B \-Wf\-wchar_t=unsigned_short
261
.B \-Wf\-wchar_t=unsigned_int
262
Makes wide characters the type indicated; by default,
263
wide characters are unsigned short ints, and
265
is a typedef for unsigned short defined in stddef.h.
268
in stddef.h must correspond to the type specified.
271
Print commands as they are executed; some of the executed
272
programs are directed to print their version numbers.
273
More than one occurrence of
275
causes the commands to be printed, but
279
.BR \-help " or " \-?
280
Print a message on the standard error summarizing
282
options and giving the values of the environment variables
287
Under Windows, the values of
291
are also given, if they are defined.
294
Produce code that counts the number of times each expression is executed.
295
If loading takes place, arrange for a
297
file to be written when the object program terminates.
298
A listing annotated with execution counts can then be generated with
305
is similar, but counts only the number of function calls.
308
Produce code that counts the number of times each function is called.
309
If loading takes place, replace the standard startup
310
function by one that automatically calls
312
at the start and arranges to write a
314
file when the object program terminates normally.
315
An execution profile can then be generated with
323
Causes the compiler to produce counting code like
325
but invokes a run-time recording mechanism that keeps more
326
extensive statistics and produces a
328
file at normal termination.
329
Also, a profiling library is searched, in lieu of the standard C library.
330
An execution profile can then be generated with
342
Produce code to print the name of the function, an activation number,
343
and the name and value of each argument at function entry.
344
At function exit, produce code to print
345
the name of the function, the activation number, and the return value.
348
does the printing; if
353
values, "(null)" is printed.
356
is accepted, but ignored.
359
Store temporary files in the directory
364
The default is usually
370
to the program indicated by
379
which refer, respectively, to the preprocessor, the compiler proper,
380
the assembler, and the loader.
382
is passed as given; if a
384
is expected, it must be given explicitly.
386
specifies a system-specific option,
390
are taken to be either loader option arguments, or C-compatible
391
object programs, typically produced by an earlier
393
run, or perhaps libraries of C-compatible routines.
394
Duplicate object files are ignored.
395
These programs, together with the results of any
396
compilations specified, are loaded (in the order
397
given) to produce an executable program with name
404
assigns the most frequently referenced scalar parameters and
405
locals to registers whenever possible.
407
explicit register declarations are obeyed first;
408
remaining registers are assigned to automatic locals if they
409
are `referenced' at least 3 times.
410
Each top-level occurrence of an identifier
411
counts as 1 reference. Occurrences in a loop,
412
either of the then/else arms of an if statement, or a case
413
in a switch statement each count, respectively, as 10, 1/2, or 1/10 references.
414
These values are adjusted accordingly for nested control structures.
420
file from a previous execution and to use the data therein
421
to compute reference counts (see
426
.BI \-Wf\-target= target/os
431
running the operating system denoted by
435
combinations may include
438
.ta \w'sparc/solarisxx'u
440
alpha/osf ALPHA, OSF 3.2
441
mips/irix big-endian MIPS, IRIX 5.2
442
mips/ultrix little-endian MIPS, ULTRIX 4.3
443
sparc/solaris SPARC, Solaris 2.3
444
x86/win32 x86, Windows NT 4.0/Windows 95/98
446
symbolic text rendition of the generated code
452
.BR \-Wf\-target=symbolic ,
455
causes the text rendition to be emitted as HTML.
460
accepts the C programming language
461
as described in the ANSI standard.
464
is used with the GNU C preprocessor, the
466
option is required to enable trigraph sequences.
468
Plain int bit fields are signed.
469
Bit fields are aligned like unsigned integers but are otherwise laid out
470
as by most standard C compilers.
471
Some compilers, such as the GNU C compiler,
472
may choose other, incompatible layouts.
474
Likewise, calling conventions are intended to be compatible with
476
except possibly for passing and returning structures.
479
passes and returns structures like host ANSI C compilers
480
on most targets, but some older host C compilers use different conventions.
481
Consequently, calls to/from such functions compiled with
482
older C compilers may not work.
483
Calling a function that returns
484
a structure without declaring it as such violates
485
the ANSI standard and may cause a fault.
488
The file names listed below are
490
but vary among installations; installation-dependent variants
491
can be displayed by running
498
.ta \w'$LCCDIR/liblcc.{a,lib}XX'u
500
file.{c,C} input file
501
file.{s,asm} assembly-language file
502
file.{o,obj} object file
503
a.{out,exe} loaded output
504
/tmp/lcc* temporary files
505
$LCCDIR/cpp preprocessor
507
$LCCDIR/liblcc.{a,lib} \fIlcc\fP-specific library
508
/lib/crt0.o runtime startup (UNIX)
509
/lib/[gm]crt0.o startups for profiling (UNIX)
510
/lib/libc.a standard library (UNIX)
511
$LCCDIR/include ANSI standard headers
512
/usr/local/include local headers
513
/usr/include traditional headers
514
prof.out file produced for \fIbprint\fR(1)
515
mon.out file produced for \fIprof\fR(1)
516
gmon.out file produced for \fIgprof\fR(1)
524
It may also predefine some installation-dependent symbols; option
529
C. W. Fraser and D. R. Hanson,
530
.I A Retargetable C Compiler: Design and Implementation,
531
Addison-Wesley, 1995. ISBN 0-8053-1670-1.
533
The World-Wide Web page at http://www.cs.princeton.edu/software/lcc/.
535
S. P. Harbison and G. L. Steele, Jr.,
536
.I C: A Reference Manual,
537
4th ed., Prentice-Hall, 1995.
539
B. W. Kernighan and D. M. Ritchie,
540
.I The C Programming Language,
541
2nd ed., Prentice-Hall, 1988.
543
American National Standards Inst.,
544
.I American National Standard for Information Systems\(emProgramming
546
ANSI X3.159-1989, New York, 1990.
549
Mail bug reports along with the shortest preprocessed program
550
that exposes them and the details reported by
553
option to lcc-bugs@princeton.edu. The WWW page at
554
URL http://www.cs.princeton.edu/software/lcc/
555
includes detailed instructions for reporting bugs.
557
The ANSI standard headers conform to the specifications in
558
the Standard, which may be too restrictive for some applications,
559
but necessary for portability.
560
Functions given in the ANSI headers may be missing from
561
some local C libraries (e.g., wide-character functions)
562
or may not correspond exactly to the local versions;
563
for example, the ANSI standard
570
return the number of characters written to the file or array,
571
but some existing libraries don't implement this convention.
573
On the MIPS and SPARC, old-style variadic functions must use
575
from MIPS or Sun. New-style is recommended.
584
to print erroneous call graphs.
605
The total number of calls is correct, however.
added
removed
code/tools/lcc/doc/lcc.1
