Subversion Repositories eco32

.\" $Id: lcc.1,v 1.15 1998/08/24 21:14:33 drh Exp $

.TH LCC 1 "local \- $Date: 1998/08/24 21:14:33 $"

.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.