| .\" $Id: lcc.1 355 2007-02-18 22:08:49Z drh $ |
| .TH LCC 1 "local \- $Date: 2007-02-18 14:08:49 -0800 (Sun, 18 Feb 2007) $" |
| .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. |