diff options
Diffstat (limited to 'ioq3-r437/src/tools/lcc/doc/lcc.1')
| -rw-r--r-- | ioq3-r437/src/tools/lcc/doc/lcc.1 | 605 |
1 files changed, 0 insertions, 605 deletions
diff --git a/ioq3-r437/src/tools/lcc/doc/lcc.1 b/ioq3-r437/src/tools/lcc/doc/lcc.1 deleted file mode 100644 index fe91bca9..00000000 --- a/ioq3-r437/src/tools/lcc/doc/lcc.1 +++ /dev/null @@ -1,605 +0,0 @@ -.\" $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. |