diff options
Diffstat (limited to 'lcc/doc/lcc.1')
| -rwxr-xr-x | lcc/doc/lcc.1 | 1210 |
1 files changed, 605 insertions, 605 deletions
diff --git a/lcc/doc/lcc.1 b/lcc/doc/lcc.1 index 53c2cc5..fe91bca 100755 --- a/lcc/doc/lcc.1 +++ b/lcc/doc/lcc.1 @@ -1,605 +1,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.
+.\" $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. |