Initial import.

1 files changed, 605 insertions, 0 deletions

diff --git a/src/tools/lcc/doc/lcc.1 b/src/tools/lcc/doc/lcc.1
new file mode 100644
index 0000000..fe91bca
--- /dev/null
+++ b/src/tools/lcc/doc/lcc.1
@@ -0,0 +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.