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.