aboutsummaryrefslogtreecommitdiffstats
path: root/code/tools/lcc/doc/lcc.1
blob: fe91bca95affa5b7ab55b2bb1ac1b2dec7d35a4b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
.\" $Id: lcc.1 145 2001-10-17 21:53:10Z timo $
.TH LCC 1 "local \- $Date: 2001-10-17 16:53:10 -0500 (Wed, 17 Oct 2001) $"
.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.