| blob | fe91bca95affa5b7ab55b2bb1ac1b2dec7d35a4b |
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) $"
3 .SH NAME
4 lcc \- ANSI C compiler
5 .SH SYNOPSIS
6 .B lcc
7 [
8 .I option
9 |
10 .I file
11 ]...
12 .br
13 .SH DESCRIPTION
14 .PP
15 .I lcc
16 is an ANSI C compiler for a variety of platforms.
17 .PP
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.
25 In the same way,
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,
30 .I lcc
31 summarizes its options on the standard error.
32 .PP
33 .I lcc
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
37 .B \-l
38 option is mentioned.
39 .PP
40 If the environment variable
41 .B LCCINPUTS
42 is set,
43 .I lcc
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.
48 If
49 .B LCCINPUTS
50 is defined, it must contain `.' in order for the current directory
51 to be searched for input files.
52 .PP
53 .I lcc
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
58 .BR /usr/include .
59 Under Windows, if the environment variable
60 .B include
61 is defined, it gives a semicolon-separated list of directories in which to search for
62 header files.
63 .PP
64 .I lcc
65 interprets the following options; unrecognized options are
66 taken as loader options (see
67 .IR ld (1))
68 unless
69 .BR \-c ,
70 .BR \-S ,
71 or
72 .B \-E
73 precedes them.
74 Except for
75 .BR \-l ,
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.
79 .TP
80 .B \-c
81 Suppress the loading phase of the compilation, and force
82 an object file to be produced even if only one program is compiled.
83 .TP
84 .B \-g
85 Produce additional symbol table information for the local debuggers.
86 .I lcc
87 warns when
88 .B \-g
89 is unsupported.
90 .TP
91 .BI \-Wf\-g n , x
92 Set the debugging level to
93 .I n
94 and emit source code as comments into the generated assembly code;
95 .I x
96 must be the assembly language comment character.
97 If
98 .I n
99 is omitted, it defaults to 1, which is similar to
100 .BR \-g .
101 Omitting
102 .BI , x
103 just sets the debugging level to
104 .IR n .
105 .TP
106 .B \-w
107 Suppress warning diagnostics, such as those
108 announcing unreferenced statics, locals, and parameters.
109 The line
110 .I
111 #pragma ref id
112 simulates a reference to the variable
113 .IR id .
114 .TP
115 .BI \-d n
116 Generate jump tables for switches whose density is at least
117 .IR n ,
118 a floating point constant between zero and one.
119 The default is 0.5.
120 .TP
121 .B \-A
122 Warns about
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.
126 A second
127 .B \-A
128 warns about
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,
133 and exceeding
134 .I some
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.
138 .TP
139 .B \-P
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.
145 .TP
146 .B \-n
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
150 .IR abort (3).
151 .TP
152 .B \-O
153 is ignored.
154 .TP
155 .B \-S
156 Compile the named C programs, and leave the
157 assembler-language output on corresponding files suffixed `.s' or `.asm'.
158 .TP
159 .B \-E
160 Run only the preprocessor on the named C programs
161 and unsuffixed file arguments,
162 and send the result to the standard output.
163 .TP
164 .BI \-o " output"
165 Name the output file
166 .IR output .
167 If
168 .B \-c
169 or
170 .B \-S
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.
175 .I lcc
176 warns if
177 .B \-o
178 and
179 .B \-c
180 or
181 .B \-S
182 are given with more than one source file and ignores the
183 .B \-o
184 option.
185 .TP
186 .BI \-D name=def
187 Define the
188 .I name
189 to the preprocessor, as if by `#define'.
190 If
191 .I =def
192 is omitted, the name is defined as "1".
193 .TP
194 .BI \-U name
195 Remove any initial definition of
196 .IR name .
197 .TP
198 .BI \-I dir
199 `#include' files
200 whose names do not begin with `/' are always
201 sought first in the directory of the
202 .I file
203 arguments, then in directories named in
204 .B \-I
205 options, then in directories on a standard list.
206 .TP
207 .B \-N
208 Do not search
209 .I any
210 of the standard directories for `#include' files.
211 Only those directories specified by subsequent explicit
212 .B \-I
213 options will be searched, in the order given.
214 .TP
215 .BI \-B str
216 Use the compiler
217 .BI "" str rcc
218 instead of the default version.
219 Note that
220 .I str
221 often requires a trailing slash.
222 On Sparcs only,
223 .B \-Bstatic
224 and
225 .BI \-Bdynamic
226 are passed to the loader; see
227 .IR ld (1).
228 .TP
229 .BI \-Wo\-lccdir= dir
230 Find the preprocessor, compiler proper, and include directory
231 in the directory
232 .I dir/
233 or
234 .I
235 dir\\.
236 If the environment variable
237 .B LCCDIR
238 is defined, it gives this directory.
239 .I lcc
240 warns when this option is unsupported.
241 .TP
242 .B \-Wf-unsigned_char=1
243 .br
244 .ns
245 .TP
246 .B \-Wf-unsigned_char=0
247 makes plain
248 .B char
249 an unsigned (1) or signed (0) type; by default,
250 .B char
251 is signed.
252 .TP
253 .B \-Wf\-wchar_t=unsigned_char
254 .br
255 .ns
256 .TP
257 .B \-Wf\-wchar_t=unsigned_short
258 .br
259 .ns
260 .TP
261 .B \-Wf\-wchar_t=unsigned_int
262 Makes wide characters the type indicated; by default,
263 wide characters are unsigned short ints, and
264 .B wchar_t
265 is a typedef for unsigned short defined in stddef.h.
266 The definition for
267 .B wchar_t
268 in stddef.h must correspond to the type specified.
269 .TP
270 .B \-v
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
274 .B \-v
275 causes the commands to be printed, but
276 .I not
277 executed.
278 .TP
279 .BR \-help " or " \-?
280 Print a message on the standard error summarizing
281 .IR lcc 's
282 options and giving the values of the environment variables
283 .B LCCINPUTS
284 and
285 .BR LCCDIR ,
286 if they are defined.
287 Under Windows, the values of
288 .B include
289 and
290 .B lib
291 are also given, if they are defined.
292 .TP
293 .B \-b
294 Produce code that counts the number of times each expression is executed.
295 If loading takes place, arrange for a
296 .B prof.out
297 file to be written when the object program terminates.
298 A listing annotated with execution counts can then be generated with
299 .IR bprint (1).
300 .I lcc
301 warns when
302 .B \-b
303 is unsupported.
304 .B \-Wf\-C
305 is similar, but counts only the number of function calls.
306 .TP
307 .B \-p
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
311 .IR monitor (3)
312 at the start and arranges to write a
313 .B mon.out
314 file when the object program terminates normally.
315 An execution profile can then be generated with
316 .IR prof (1).
317 .I lcc
318 warns when
319 .B \-p
320 is unsupported.
321 .TP
322 .B \-pg
323 Causes the compiler to produce counting code like
324 .BR \-p ,
325 but invokes a run-time recording mechanism that keeps more
326 extensive statistics and produces a
327 .B gmon.out
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
331 .IR gprof (1).
332 .I lcc
333 warns when
334 .B \-pg
335 is unsupported.
336 .TP
337 .BI \-t name
338 .br
339 .ns
340 .TP
341 .BI \-t
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.
346 By default,
347 .I printf
348 does the printing; if
349 .I name
350 appears, it does.
351 For null
352 .I char*
353 values, "(null)" is printed.
354 .BI \-target
355 .I name
356 is accepted, but ignored.
357 .TP
358 .BI \-tempdir= dir
359 Store temporary files in the directory
360 .I dir/
361 or
362 .I
363 dir\\.
364 The default is usually
365 .BR /tmp .
366 .TP
367 .BI \-W xarg
368 pass argument
369 .I arg
370 to the program indicated by
371 .IR x ;
372 .I x
373 can be one of
374 .BR p ,
375 .BR f ,
376 .BR a ,
377 or
378 .BR l ,
379 which refer, respectively, to the preprocessor, the compiler proper,
380 the assembler, and the loader.
381 .I arg
382 is passed as given; if a
383 .B \-
384 is expected, it must be given explicitly.
385 .BI \-Wo arg
386 specifies a system-specific option,
387 .IR arg .
388 .PP
389 Other arguments
390 are taken to be either loader option arguments, or C-compatible
391 object programs, typically produced by an earlier
392 .I lcc
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
398 .BR a.out
399 (UNIX) or
400 .BR a.exe
401 (Windows).
402 .PP
403 .I lcc
404 assigns the most frequently referenced scalar parameters and
405 locals to registers whenever possible.
406 For each block,
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.
415 .B \-Wf\-a
416 causes
417 .I lcc
418 to read a
419 .B prof.out
420 file from a previous execution and to use the data therein
421 to compute reference counts (see
422 .BR \-b ).
423 .PP
424 .I lcc
425 is a cross compiler;
426 .BI \-Wf\-target= target/os
427 causes
428 .I lcc
429 to generate code for
430 .I target
431 running the operating system denoted by
432 .IR os .
433 The supported
434 .I target/os
435 combinations may include
436 .PP
437 .RS
438 .ta \w'sparc/solarisxx'u
439 .nf
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
445 x86/linux x86, Linux
446 symbolic text rendition of the generated code
447 null no output
448 .fi
449 .RE
450 .PP
451 For
452 .BR \-Wf\-target=symbolic ,
453 the option
454 .B \-Wf-html
455 causes the text rendition to be emitted as HTML.
456 .B
457 .SH LIMITATIONS
458 .PP
459 .I lcc
460 accepts the C programming language
461 as described in the ANSI standard.
462 If
463 .I lcc
464 is used with the GNU C preprocessor, the
465 .B \-Wp\-trigraphs
466 option is required to enable trigraph sequences.
467 .PP
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.
473 .PP
474 Likewise, calling conventions are intended to be compatible with
475 the host C compiler,
476 except possibly for passing and returning structures.
477 Specifically,
478 .I lcc
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.
486 .SH FILES
487 .PP
488 The file names listed below are
489 .IR typical ,
490 but vary among installations; installation-dependent variants
491 can be displayed by running
492 .I lcc
493 with the
494 .B \-v
495 option.
496 .PP
497 .RS
498 .ta \w'$LCCDIR/liblcc.{a,lib}XX'u
499 .nf
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
506 $LCCDIR/rcc compiler
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)
517 .fi
518 .RE
519 .PP
520 .I lcc
521 predefines the macro
522 .B __LCC__
523 on all systems.
524 It may also predefine some installation-dependent symbols; option
525 .B \-v
526 exposes them.
527 .SH "SEE ALSO"
528 .PP
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.
532 .PP
533 The World-Wide Web page at http://www.cs.princeton.edu/software/lcc/.
534 .PP
535 S. P. Harbison and G. L. Steele, Jr.,
536 .I C: A Reference Manual,
537 4th ed., Prentice-Hall, 1995.
538 .PP
539 B. W. Kernighan and D. M. Ritchie,
540 .I The C Programming Language,
541 2nd ed., Prentice-Hall, 1988.
542 .PP
543 American National Standards Inst.,
544 .I American National Standard for Information Systems\(emProgramming
545 .IR Language\(emC ,
546 ANSI X3.159-1989, New York, 1990.
547 .br
548 .SH BUGS
549 Mail bug reports along with the shortest preprocessed program
550 that exposes them and the details reported by
551 .IR lcc 's
552 .B \-v
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.
556 .PP
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
564 stdio.h
565 specifies that
566 .IR printf ,
567 .IR fprintf ,
568 and
569 .I sprintf
570 return the number of characters written to the file or array,
571 but some existing libraries don't implement this convention.
572 .PP
573 On the MIPS and SPARC, old-style variadic functions must use
574 varargs.h
575 from MIPS or Sun. New-style is recommended.
576 .PP
577 With
578 .BR \-b ,
579 files compiled
580 .I without
581 .B \-b
582 may cause
583 .I bprint
584 to print erroneous call graphs.
585 For example, if
586 .B f
587 calls
588 .B g
589 calls
590 .B h
591 and
592 .B f
593 and
594 .B h
595 are compiled with
596 .BR \-b ,
597 but
598 .B g
599 is not,
600 .B bprint
601 will report that
602 .B f
603 called
604 .BR h .
605 The total number of calls is correct, however.