docs: Added UNIX V10 Manuals

1 files changed, 505 insertions, 0 deletions

diff --git a/static/v10/man1/lcc.1 b/static/v10/man1/lcc.1
new file mode 100644
index 00000000..29ab1194
--- /dev/null
+++ b/static/v10/man1/lcc.1
@@ -0,0 +1,505 @@
+.TH LCC 1 "local \- 4/13/93"
+.SH NAME
+lcc \- local ANSI C compiler
+.SH SYNOPSIS
+.B lcc
+[
+.I option
+|
+.I file
+]...
+.br
+.SH DESCRIPTION
+.PP
+.I lcc
+is a local ANSI C compiler for the VAX, MIPS, SPARC, and Motorola MC68020.
+.PP
+Arguments whose names end with `.c' 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' substituted for `.c'.
+Arguments whose names end with `.i' are treated similarly,
+except they are not preprocessed.
+In the same way,
+arguments whose names end with `.s' are taken to be assembly source programs
+and are assembled, producing a `.o' file.
+.PP
+.I lcc
+deletes a `.o' file if and only if exactly one
+source file (`.c', `.s', or `.i' file) is mentioned and no other file
+(source, object, library) or
+.B \-l
+option is mentioned.
+.PP
+.I lcc
+uses ANSI standard header files
+in preference to the `old-style' header files normally found in
+.B /usr/include
+(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 .
+.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
+.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
+.SM
+.B \-A
+Warns about
+declarations and casts of function types without prototypes,
+missing return values in returns from int functions,
+assignments between pointers to ints and pointers to enums, and
+conversions from pointers to smaller integral types.
+A second
+.SM
+.B \-A
+warns about
+unrecognized control lines,
+non-ANSI 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
+.SM
+.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 typedef's 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
+.SM
+.B \-O
+is ignored.
+.TP
+.SM
+.B \-S
+Compile the named C programs, and leave the
+assembler-language output on corresponding files suffixed `.s'.
+.TP
+.SM
+.B \-E
+Run only the preprocessor on the named C programs
+and unsuffixed file arguments,
+and send the result to the standard output.
+.TP
+.SM
+.B \-C
+Prevent the preprocessor from eliding comments.
+.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' 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
+.SM
+.BI \-D \*Sname=def
+.br
+.ns
+.TP
+.SM
+.BI \-D \*Sname
+Define the
+.I name
+to the preprocessor, as if by `#define'.
+If no definition is given, the name is defined as "1".
+.TP
+.SM
+.BI \-U \*Sname
+Remove any initial definition of
+.IR name .
+.TP
+.SM
+.BI \-I \*Sdir
+`#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
+.SM
+.B \-I
+options, then in directories on a standard list.
+.TP
+.SM
+.B \-N
+Do not search
+.I any
+of the standard directories for `#include' files.
+Only those directories specified by explicit
+.SM
+.B \-I
+options will be searched, in the order given.
+.TP
+.SM
+.BI \-B \*Sstr
+Use the compiler \fIstr\fP\fBrcc\fP instead of the default version.
+Note that
+.I str
+often requires a trailing slash.
+On Suns only,
+.SM
+.B \-Bstatic
+and
+.SM
+.BI \-Bdynamic
+are passed to the loader; see
+.IR ld (1).
+.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
+.B \-b
+Produce code that counts the number of times each expression is executed.
+If loading takes place, replace the standard exit
+function by one that writes a
+.B prof.out
+file 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
+.SM
+.BI \-t \*Sname
+.br
+.ns
+.TP
+.SM
+.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. 
+On Suns only,
+.SM
+.BI \-target
+.I name
+is accepted, but ignored.
+.TP
+.SM
+.BI \-W \*Sx \fIarg\fP
+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.
+.SM
+.BI \-W \*So \fIarg\fP
+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 `.o' 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 .
+.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 increased 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 ).
+.SH LIMITATIONS
+.PP
+.I lcc
+accepts the C programming language
+as described in the proposed ANSI standard
+and in the second edition of Kernighan and Ritchie.
+.I lcc
+is intended to be used with the GNU C preprocessor, which supports the
+preprocessing features introduced by the ANSI standard.
+The
+.SM
+.B \-Wp-trigraphs
+option is required to enable trigraph sequences.
+.PP
+Wide-character literals are accepted
+but are treated as plain char literals.
+Plain chars are signed chars,
+ints and long ints are the same size
+as are doubles and long doubles, and
+plain int bit fields are signed.
+Bit fields are aligned like unsigned integers but are otherwise laid out
+as if by the standard C compiler,
+.IR cc (1).
+Other compilers, such as the GNU C compiler,
+.IR gcc (1),
+may choose other, incompatible layouts.
+.PP
+Likewise, calling conventions are intended to be compatible with
+.IR cc (1),
+except possibly for passing and returning structures.
+Specifically,
+.I lcc
+passes structures like
+.I cc
+on all targets,
+but returns structures like
+.I cc
+on only the MIPS.
+Consequently, calls to/from such functions compiled with
+.I cc
+or other 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 core dump.
+.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
+.ta \w'/usr/lib/gcc-cppxx'u
+.nf
+file.c	input file
+file.o	object file
+a.out	loaded output
+/tmp/lcc?	temporaries
+/usr/lib/gcc-cpp	preprocessor
+/usr/lib/rcc	compiler
+/usr/lib/bbexit.o	exit for profiling
+/lib/crt0.o	runtime startoff
+/lib/[gm]crt0.o	startoffs for profiling
+/lib/libc.a	standard library
+/usr/include/lcc	ANSI standard headers
+/usr/include/libc	local ANSI 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
+.PP
+.I lcc
+predefines the macros `unix' and `__LCC__'.
+It may also predefine some installation-dependent symbols; option
+.B \-v
+exposes them.
+.SH "SEE ALSO"
+B. W. Kernighan and D. M. Ritchie,
+.I The C Programming Language,
+Prentice-Hall, 2nd Ed., 1988.
+.PP
+.I
+American National Standard for Information Systems, Programming Language C,
+ANSI X3.159-1989, American National Standard Institute, Inc., New York, 1990.
+.PP
+cc(1), ld(1)
+.br
+.SH BUGS
+Mail bug reports along with the shortest program
+that exposes them and the details reported by
+.IR lcc 's
+.B \-v
+option to lcc-bugs@princeton.edu.
+.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
+the local C library (e.g., `wide character' functions)
+or may not correspond exactly to the local version;
+for example, the ANSI standard
+.B stdio.h
+specifies that
+.IR printf ,
+.IR fprintf ,
+and
+.I sprintf
+return the number of characters written to the file or array,
+but few existing libraries implement this convention.
+.PP
+On VAXes running 4.3bsd UNIX,
+the definitions of
+.I tolower
+and
+.I toupper
+erroneously return bad values for non-letter arguments.
+.PP
+On the MIPS and SPARC, old-style variadic functions must use
+.B varargs.h
+from MIPS or Sun. New-style is recommended.
+.PP
+The Sun assembler version 3.5 or later is required on the MC68020,
+and only the MC68881 is supported.
+.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.