.\" $Id: lcc.1,v 1.15 1998/08/24 21:14:33 drh Exp $.TH LCC 1 "local \- $Date: 1998/08/24 21:14:33 $".SH NAMElcc \- ANSI C compiler.SH SYNOPSIS.B lcc[.I option|.I file]....br.SH DESCRIPTION.PP.I lccis an ANSI C compiler for a variety of platforms..PPArguments whose names end with `.c' (plus `.C' under Windows) are taken to beC source programs; they are preprocessed, compiled, andeach object program is left on the filewhose 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 programsand are assembled, producing an object file.If there are no arguments,.I lccsummarizes its options on the standard error..PP.I lccdeletes an object file if and only if exactly onesource file is mentioned and no other file(source, object, library) or.B \-loption is mentioned..PPIf the environment variable.B LCCINPUTSis set,.I lccassumes it gives a semicolon- or colon-separated list of directories in which tolook for source and object files whose names do not begin with `/'.These directories are also added to the list of directoriessearched for libraries.If.B LCCINPUTSis defined, it must contain `.' in order for the current directoryto be searched for input files..PP.I lccuses ANSI standard header files (see `FILES' below).Include files not found in the ANSI header filesare taken from the normal default include areas,which usually includes.BR /usr/include .Under Windows, if the environment variable.B includeis defined, it gives a semicolon-separated list of directories in which to search forheader files..PP.I lccinterprets the following options; unrecognized options aretaken as loader options (see.IR ld (1))unless.BR \-c ,.BR \-S ,or.B \-Eprecedes them.Except for.BR \-l ,all options are processed before any of the filesand apply to all of the files.Applicable options are passed to each compilation phase in the order given..TP.B \-cSuppress the loading phase of the compilation, and forcean object file to be produced even if only one program is compiled..TP.B \-gProduce additional symbol table information for the local debuggers..I lccwarns when.B \-gis unsupported..TP.BI \-Wf\-g n , xSet the debugging level to.I nand emit source code as comments into the generated assembly code;.I xmust be the assembly language comment character.If.I nis omitted, it defaults to 1, which is similar to.BR \-g .Omitting.BI , xjust sets the debugging level to.IR n ..TP.B \-wSuppress warning diagnostics, such as thoseannouncing unreferenced statics, locals, and parameters.The line.I#pragma ref idsimulates a reference to the variable .IR id ..TP.BI \-d nGenerate 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 \-AWarns aboutdeclarations and casts of function types without prototypes,assignments between pointers to ints and pointers to enums, andconversions from pointers to smaller integral types.A second.B \-Awarns aboutunrecognized control lines,nonANSI language extensions and source characters in literals,unreferenced variables and static functions,declaring arrays of incomplete types,and exceeding.I someANSI environmental limits, like more than 257 cases in switches.It also arranges for duplicate global definitions in separately compiledfiles to cause loader errors..TP.B \-PWrites 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 whenthere are several typedefs for the same type..TP.B \-nArrange for the compiler to produce codethat tests for dereferencing zero pointers.The code reports the offending file and line number and calls.IR abort (3)..TP.B \-Ois ignored..TP.B \-SCompile the named C programs, and leave theassembler-language output on corresponding files suffixed `.s' or `.asm'..TP.B \-ERun only the preprocessor on the named C programsand unsuffixed file arguments,and send the result to the standard output..TP.BI \-o "  output"Name the output file.IR output .If.B \-cor.B \-Sis specified and there is exactly one source file,this option names the object or assembly file, respectively.Otherwise, this option names the final executablefile generated by the loader, and `a.out' (UNIX) or `a.exe' (Windows) is left undisturbed..I lccwarns if.B \-oand.B \-cor.B \-Sare given with more than one source file and ignores the.B \-ooption..TP.BI \-D name=defDefine the.I nameto the preprocessor, as if by `#define'.If.I =defis omitted, the name is defined as "1"..TP.BI \-U nameRemove any initial definition of.IR name ..TP.BI \-I dir`#include' fileswhose names do not begin with `/' are alwayssought first in the directory of the.I filearguments, then in directories named in.B \-Ioptions, then in directories on a standard list..TP.B \-NDo not search.I anyof the standard directories for `#include' files.Only those directories specified by subsequent explicit.B \-Ioptions will be searched, in the order given..TP.BI \-B strUse the compiler.BI "" str rccinstead of the default version.Note that.I stroften requires a trailing slash.On Sparcs only,.B \-Bstaticand.BI \-Bdynamicare passed to the loader; see.IR ld (1)..TP.BI \-Wo\-lccdir= dirFind the preprocessor, compiler proper, and include directoryin the directory.I dir/or.Idir\\.If the environment variable.B LCCDIRis defined, it gives this directory..I lccwarns when this option is unsupported..TP.B \-Wf-unsigned_char=1.br.ns.TP.B \-Wf-unsigned_char=0 makes plain.B charan unsigned (1) or signed (0) type; by default,.B charis 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_intMakes wide characters the type indicated; by default,wide characters are unsigned short ints, and.B wchar_tis a typedef for unsigned short defined in stddef.h.The definition for.B wchar_tin stddef.h must correspond to the type specified..TP.B \-vPrint commands as they are executed; some of the executedprograms are directed to print their version numbers.More than one occurrence of.B \-vcauses the commands to be printed, but.I notexecuted..TP.BR \-help " or " \-?Print a message on the standard error summarizing.IR lcc 'soptions and giving the values of the environment variables.B LCCINPUTSand.BR LCCDIR ,if they are defined.Under Windows, the values of.B includeand.B libare also given, if they are defined..TP.B \-bProduce code that counts the number of times each expression is executed.If loading takes place, arrange for a.B prof.outfile to be written when the object program terminates.A listing annotated with execution counts can then be generated with.IR bprint (1)..I lccwarns when.B \-bis unsupported..B \-Wf\-Cis similar, but counts only the number of function calls..TP.B \-pProduce code that counts the number of times each function is called.If loading takes place, replace the standard startupfunction by one that automatically calls.IR monitor (3)at the start and arranges to write a.B mon.outfile when the object program terminates normally.An execution profile can then be generated with.IR prof (1)..I lccwarns when.B \-pis unsupported..TP.B \-pgCauses the compiler to produce counting code like.BR \-p ,but invokes a run-time recording mechanism that keeps moreextensive statistics and produces a .B gmon.outfile 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 lccwarns when.B \-pgis unsupported..TP.BI \-t name.br.ns.TP.BI \-tProduce 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 printthe name of the function, the activation number, and the return value.By default,.I printfdoes the printing; if.I nameappears, it does.For null.I char*values, "(null)" is printed. .BI \-target.I nameis accepted, but ignored..TP.BI \-tempdir= dirStore temporary files in the directory.I dir/or.Idir\\.The default is usually.BR /tmp ..TP.BI \-W xargpass argument.I argto the program indicated by.IR x ;.I xcan 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 argis passed as given; if a.B \-is expected, it must be given explicitly..BI \-Wo argspecifies a system-specific option,.IR arg ..PPOther argumentsare taken to be either loader option arguments, or C-compatibleobject programs, typically produced by an earlier.I lccrun, or perhaps libraries of C-compatible routines.Duplicate object files are ignored.These programs, together with the results of anycompilations specified, are loaded (in the ordergiven) to produce an executable program with name.BR a.out(UNIX) or.BR a.exe(Windows)..PP.I lccassigns the most frequently referenced scalar parameters andlocals to registers whenever possible.For each block,explicit register declarations are obeyed first;remaining registers are assigned to automatic locals if theyare `referenced' at least 3 times.Each top-level occurrence of an identifiercounts as 1 reference. Occurrences in a loop,either of the then/else arms of an if statement, or a casein 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\-acauses.I lccto read a.B prof.outfile from a previous execution and to use the data thereinto compute reference counts (see.BR \-b )..PP.I lccis a cross compiler;.BI \-Wf\-target= target/oscauses.I lccto generate code for.I targetrunning the operating system denoted by.IR os .The supported.I target/oscombinations may include.PP.RS.ta \w'sparc/solarisxx'u.nfalpha/osf	ALPHA, OSF 3.2mips/irix	big-endian MIPS, IRIX 5.2mips/ultrix	little-endian MIPS, ULTRIX 4.3sparc/solaris	SPARC, Solaris 2.3x86/win32	x86, Windows NT 4.0/Windows 95/98x86/linux	x86, Linuxsymbolic	text rendition of the generated codenull		no output.fi.RE.PPFor.BR \-Wf\-target=symbolic ,the option.B \-Wf-htmlcauses the text rendition to be emitted as HTML..B .SH LIMITATIONS.PP.I lccaccepts the C programming languageas described in the ANSI standard.If.I lccis used with the GNU C preprocessor, the.B \-Wp\-trigraphsoption is required to enable trigraph sequences..PPPlain int bit fields are signed.Bit fields are aligned like unsigned integers but are otherwise laid outas by most standard C compilers.Some compilers, such as the GNU C compiler,may choose other, incompatible layouts..PPLikewise, calling conventions are intended to be compatible withthe host C compiler,except possibly for passing and returning structures.Specifically,.I lccpasses and returns structures like host ANSI C compilerson most targets, but some older host C compilers use different conventions.Consequently, calls to/from such functions compiled witholder C compilers may not work.Calling a function that returnsa structure without declaring it as such violatesthe ANSI standard and may cause a fault..SH FILES.PPThe file names listed below are.IR typical ,but vary among installations; installation-dependent variantscan be displayed by running.I lccwith the.B \-voption..PP.RS.ta \w'$LCCDIR/liblcc.{a,lib}XX'u.nffile.{c,C}	input filefile.{s,asm}	assembly-language filefile.{o,obj}	object filea.{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 headersprof.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 lccpredefines the macro.B __LCC__on all systems.It may also predefine some installation-dependent symbols; option.B \-vexposes them..SH "SEE ALSO".PPC. W. Fraser and D. R. Hanson,.I A Retargetable C Compiler: Design and Implementation,Addison-Wesley, 1995. ISBN 0-8053-1670-1..PPThe World-Wide Web page at http://www.cs.princeton.edu/software/lcc/..PPS. P. Harbison and G. L. Steele, Jr.,.I C: A Reference Manual,4th ed., Prentice-Hall, 1995..PPB. W. Kernighan and D. M. Ritchie,.I The C Programming Language,2nd ed., Prentice-Hall, 1988..PPAmerican National Standards Inst.,.I American National Standard for Information Systems\(emProgramming.IR Language\(emC ,ANSI X3.159-1989, New York, 1990..br.SH BUGSMail bug reports along with the shortest preprocessed programthat exposes them and the details reported by.IR lcc 's.B \-voption to lcc-bugs@princeton.edu. The WWW page atURL http://www.cs.princeton.edu/software/lcc/includes detailed instructions for reporting bugs..PPThe ANSI standard headers conform to the specifications inthe Standard, which may be too restrictive for some applications,but necessary for portability.Functions given in the ANSI headers may be missing fromsome local C libraries (e.g., wide-character functions)or may not correspond exactly to the local versions;for example, the ANSI standardstdio.hspecifies that.IR printf ,.IR fprintf ,and.I sprintfreturn the number of characters written to the file or array,but some existing libraries don't implement this convention..PPOn the MIPS and SPARC, old-style variadic functions must usevarargs.hfrom MIPS or Sun. New-style is recommended..PPWith.BR \-b ,files compiled.I without.B \-bmay cause.I bprintto print erroneous call graphs.For example, if.B fcalls.B gcalls.B hand.B fand.B hare compiled with.BR \-b ,but.B gis not,.B bprintwill report that.B fcalled.BR h .The total number of calls is correct, however.