Return to lcc.1 CVS log

Up to [Research Unix] / researchv10no / cmd / lcc / etc

Annotation of researchv10no/cmd/lcc/etc/lcc.1, revision 1.1

1.1     ! root        1: .TH LCC 1 "local \- 4/13/93"
        !             2: .SH NAME
        !             3: lcc \- local ANSI C compiler
        !             4: .SH SYNOPSIS
        !             5: .B lcc
        !             6: [
        !             7: .I option
        !             8: |
        !             9: .I file
        !            10: ]...
        !            11: .br
        !            12: .SH DESCRIPTION
        !            13: .PP
        !            14: .I lcc
        !            15: is a local ANSI C compiler for the VAX, MIPS, SPARC, and Motorola MC68020.
        !            16: .PP
        !            17: Arguments whose names end with `.c' are taken to be
        !            18: C source programs; they are preprocessed, compiled, and
        !            19: each object program is left on the file
        !            20: whose name is that of the source with `.o' substituted for `.c'.
        !            21: Arguments whose names end with `.i' are treated similarly,
        !            22: except they are not preprocessed.
        !            23: In the same way,
        !            24: arguments whose names end with `.s' are taken to be assembly source programs
        !            25: and are assembled, producing a `.o' file.
        !            26: .PP
        !            27: .I lcc
        !            28: deletes a `.o' file if and only if exactly one
        !            29: source file (`.c', `.s', or `.i' file) is mentioned and no other file
        !            30: (source, object, library) or
        !            31: .B \-l
        !            32: option is mentioned.
        !            33: .PP
        !            34: .I lcc
        !            35: uses ANSI standard header files
        !            36: in preference to the `old-style' header files normally found in
        !            37: .B /usr/include
        !            38: (see `FILES' below).
        !            39: Include files not found in the ANSI header files
        !            40: are taken from the normal default include areas,
        !            41: which usually includes
        !            42: .BR /usr/include .
        !            43: .PP
        !            44: .I lcc
        !            45: interprets the following options; unrecognized options are
        !            46: taken as loader options (see
        !            47: .IR ld (1))
        !            48: unless
        !            49: .BR \-c ,
        !            50: .BR \-S ,
        !            51: or
        !            52: .B \-E
        !            53: precedes them.
        !            54: Except for
        !            55: .BR \-l ,
        !            56: all options are processed before any of the files
        !            57: and apply to all of the files.
        !            58: Applicable options are passed to each compilation phase in the order given.
        !            59: .TP
        !            60: .B \-c
        !            61: Suppress the loading phase of the compilation, and force
        !            62: an object file to be produced even if only one program is compiled.
        !            63: .TP
        !            64: .B \-g
        !            65: Produce additional symbol table information for the local debuggers.
        !            66: .I lcc
        !            67: warns when
        !            68: .B \-g
        !            69: is unsupported.
        !            70: .TP
        !            71: .B \-w
        !            72: Suppress warning diagnostics, such as those
        !            73: announcing unreferenced statics, locals, and parameters.
        !            74: The line
        !            75: .I
        !            76: #pragma ref id
        !            77: simulates a reference to the variable 
        !            78: .IR id .
        !            79: .TP
        !            80: .BI \-d n
        !            81: Generate jump tables for switches whose density is at least
        !            82: .IR n ,
        !            83: a floating point constant between zero and one.
        !            84: The default is 0.5.
        !            85: .TP
        !            86: .SM
        !            87: .B \-A
        !            88: Warns about
        !            89: declarations and casts of function types without prototypes,
        !            90: missing return values in returns from int functions,
        !            91: assignments between pointers to ints and pointers to enums, and
        !            92: conversions from pointers to smaller integral types.
        !            93: A second
        !            94: .SM
        !            95: .B \-A
        !            96: warns about
        !            97: unrecognized control lines,
        !            98: non-ANSI language extensions and source characters in literals,
        !            99: unreferenced variables and static functions,
        !           100: declaring arrays of incomplete types,
        !           101: and exceeding
        !           102: .I some
        !           103: ANSI environmental limits, like more than 257 cases in switches.
        !           104: It also arranges for duplicate global definitions in separately compiled
        !           105: files to cause loader errors.
        !           106: .TP
        !           107: .SM
        !           108: .B \-P
        !           109: Writes declarations for all defined globals on standard error.
        !           110: Function declarations include prototypes;
        !           111: editing this output can simplify conversion to ANSI C.
        !           112: This output may not correspond to the input when
        !           113: there are several typedef's for the same type.
        !           114: .TP
        !           115: .B \-n
        !           116: Arrange for the compiler to produce code
        !           117: that tests for dereferencing zero pointers.
        !           118: The code reports the offending file and line number and calls
        !           119: .IR abort (3).
        !           120: .TP
        !           121: .SM
        !           122: .B \-O
        !           123: is ignored.
        !           124: .TP
        !           125: .SM
        !           126: .B \-S
        !           127: Compile the named C programs, and leave the
        !           128: assembler-language output on corresponding files suffixed `.s'.
        !           129: .TP
        !           130: .SM
        !           131: .B \-E
        !           132: Run only the preprocessor on the named C programs
        !           133: and unsuffixed file arguments,
        !           134: and send the result to the standard output.
        !           135: .TP
        !           136: .SM
        !           137: .B \-C
        !           138: Prevent the preprocessor from eliding comments.
        !           139: .TP
        !           140: .BI \-o "  output"
        !           141: Name the output file
        !           142: .IR output .
        !           143: If
        !           144: .B \-c
        !           145: or
        !           146: .B \-S
        !           147: is specified and there is exactly one source file,
        !           148: this option names the object or assembly file, respectively.
        !           149: Otherwise, this option names the final executable
        !           150: file generated by the loader, and `a.out' is left undisturbed.
        !           151: .I lcc
        !           152: warns if
        !           153: .B \-o
        !           154: and
        !           155: .B \-c
        !           156: or
        !           157: .B \-S
        !           158: are given with more than one source file and ignores the
        !           159: .B \-o
        !           160: option.
        !           161: .TP
        !           162: .SM
        !           163: .BI \-D \*Sname=def
        !           164: .br
        !           165: .ns
        !           166: .TP
        !           167: .SM
        !           168: .BI \-D \*Sname
        !           169: Define the
        !           170: .I name
        !           171: to the preprocessor, as if by `#define'.
        !           172: If no definition is given, the name is defined as "1".
        !           173: .TP
        !           174: .SM
        !           175: .BI \-U \*Sname
        !           176: Remove any initial definition of
        !           177: .IR name .
        !           178: .TP
        !           179: .SM
        !           180: .BI \-I \*Sdir
        !           181: `#include' files
        !           182: whose names do not begin with `/' are always
        !           183: sought first in the directory of the
        !           184: .I file
        !           185: arguments, then in directories named in
        !           186: .SM
        !           187: .B \-I
        !           188: options, then in directories on a standard list.
        !           189: .TP
        !           190: .SM
        !           191: .B \-N
        !           192: Do not search
        !           193: .I any
        !           194: of the standard directories for `#include' files.
        !           195: Only those directories specified by explicit
        !           196: .SM
        !           197: .B \-I
        !           198: options will be searched, in the order given.
        !           199: .TP
        !           200: .SM
        !           201: .BI \-B \*Sstr
        !           202: Use the compiler \fIstr\fP\fBrcc\fP instead of the default version.
        !           203: Note that
        !           204: .I str
        !           205: often requires a trailing slash.
        !           206: On Suns only,
        !           207: .SM
        !           208: .B \-Bstatic
        !           209: and
        !           210: .SM
        !           211: .BI \-Bdynamic
        !           212: are passed to the loader; see
        !           213: .IR ld (1).
        !           214: .TP
        !           215: .B \-v
        !           216: Print commands as they are executed; some of the executed
        !           217: programs are directed to print their version numbers.
        !           218: More than one occurrence of
        !           219: .B \-v
        !           220: causes the commands to be printed, but
        !           221: .I not
        !           222: executed.
        !           223: .TP
        !           224: .B \-b
        !           225: Produce code that counts the number of times each expression is executed.
        !           226: If loading takes place, replace the standard exit
        !           227: function by one that writes a
        !           228: .B prof.out
        !           229: file when the object program terminates.
        !           230: A listing annotated with execution counts can then be generated with
        !           231: .IR bprint (1).
        !           232: .I lcc
        !           233: warns when
        !           234: .B \-b
        !           235: is unsupported.
        !           236: .B \-Wf-C
        !           237: is similar, but counts only the number of function calls.
        !           238: .TP
        !           239: .B \-p
        !           240: Produce code that counts the number of times each function is called.
        !           241: If loading takes place, replace the standard startup
        !           242: function by one that automatically calls
        !           243: .IR monitor (3)
        !           244: at the start and arranges to write a
        !           245: .B mon.out
        !           246: file when the object program terminates normally.
        !           247: An execution profile can then be generated with
        !           248: .IR prof (1).
        !           249: .I lcc
        !           250: warns when
        !           251: .B \-p
        !           252: is unsupported.
        !           253: .TP
        !           254: .B \-pg
        !           255: Causes the compiler to produce counting code like
        !           256: .BR \-p ,
        !           257: but invokes a run-time recording mechanism that keeps more
        !           258: extensive statistics and produces a 
        !           259: .B gmon.out
        !           260: file at normal termination.
        !           261: Also, a profiling library is searched, in lieu of the standard C library.
        !           262: An execution profile can then be generated with
        !           263: .IR gprof (1).
        !           264: .I lcc
        !           265: warns when
        !           266: .B \-pg
        !           267: is unsupported.
        !           268: .TP
        !           269: .SM
        !           270: .BI \-t \*Sname
        !           271: .br
        !           272: .ns
        !           273: .TP
        !           274: .SM
        !           275: .BI \-t
        !           276: Produce code to print the name of the function, an activation number,
        !           277: and the name and value of each argument at function entry.
        !           278: At function exit, produce code to print
        !           279: the name of the function, the activation number, and the return value.
        !           280: By default,
        !           281: .I printf
        !           282: does the printing; if
        !           283: .I name
        !           284: appears, it does.
        !           285: For null
        !           286: .I char*
        !           287: values, "(null)" is printed. 
        !           288: On Suns only,
        !           289: .SM
        !           290: .BI \-target
        !           291: .I name
        !           292: is accepted, but ignored.
        !           293: .TP
        !           294: .SM
        !           295: .BI \-W \*Sx \fIarg\fP
        !           296: pass argument
        !           297: .I arg
        !           298: to the program indicated by
        !           299: .IR x ;
        !           300: .I x
        !           301: can be one of
        !           302: .BR p ,
        !           303: .BR f ,
        !           304: .BR a ,
        !           305: or
        !           306: .BR l ,
        !           307: which refer, respectively, to the preprocessor, the compiler proper,
        !           308: the assembler, and the loader.
        !           309: .I arg
        !           310: is passed as given; if a
        !           311: .B \-
        !           312: is expected, it must be given explicitly.
        !           313: .SM
        !           314: .BI \-W \*So \fIarg\fP
        !           315: specifies a system-specific option,
        !           316: .IR arg .
        !           317: .PP
        !           318: Other arguments
        !           319: are taken to be either loader option arguments, or C-compatible
        !           320: object programs, typically produced by an earlier
        !           321: .I lcc
        !           322: run, or perhaps libraries of C-compatible routines.
        !           323: Duplicate `.o' files are ignored.
        !           324: These programs, together with the results of any
        !           325: compilations specified, are loaded (in the order
        !           326: given) to produce an executable program with name
        !           327: .BR a.out .
        !           328: .PP
        !           329: .I lcc
        !           330: assigns the most frequently referenced scalar parameters and
        !           331: locals to registers whenever possible.
        !           332: For each block,
        !           333: explicit register declarations are obeyed first;
        !           334: remaining registers are assigned to automatic locals if they
        !           335: are `referenced' at least 3 times.
        !           336: Each top-level occurrence of an identifier
        !           337: counts as 1 reference. Occurrences in a loop,
        !           338: either of the then/else arms of an if statement, or a case
        !           339: in a switch statement each count, respectively, as 10, 1/2, or 1/10 references.
        !           340: These values are increased accordingly for nested control structures.
        !           341: .B \-Wf-a
        !           342: causes
        !           343: .I lcc
        !           344: to read a
        !           345: .B prof.out
        !           346: file from a previous execution and to use the data therein
        !           347: to compute reference counts (see
        !           348: .BR \-b ).
        !           349: .SH LIMITATIONS
        !           350: .PP
        !           351: .I lcc
        !           352: accepts the C programming language
        !           353: as described in the proposed ANSI standard
        !           354: and in the second edition of Kernighan and Ritchie.
        !           355: .I lcc
        !           356: is intended to be used with the GNU C preprocessor, which supports the
        !           357: preprocessing features introduced by the ANSI standard.
        !           358: The
        !           359: .SM
        !           360: .B \-Wp-trigraphs
        !           361: option is required to enable trigraph sequences.
        !           362: .PP
        !           363: Wide-character literals are accepted
        !           364: but are treated as plain char literals.
        !           365: Plain chars are signed chars,
        !           366: ints and long ints are the same size
        !           367: as are doubles and long doubles, and
        !           368: plain int bit fields are signed.
        !           369: Bit fields are aligned like unsigned integers but are otherwise laid out
        !           370: as if by the standard C compiler,
        !           371: .IR cc (1).
        !           372: Other compilers, such as the GNU C compiler,
        !           373: .IR gcc (1),
        !           374: may choose other, incompatible layouts.
        !           375: .PP
        !           376: Likewise, calling conventions are intended to be compatible with
        !           377: .IR cc (1),
        !           378: except possibly for passing and returning structures.
        !           379: Specifically,
        !           380: .I lcc
        !           381: passes structures like
        !           382: .I cc
        !           383: on all targets,
        !           384: but returns structures like
        !           385: .I cc
        !           386: on only the MIPS.
        !           387: Consequently, calls to/from such functions compiled with
        !           388: .I cc
        !           389: or other C compilers may not work.
        !           390: Calling a function that returns
        !           391: a structure without declaring it as such violates
        !           392: the ANSI standard and may cause a core dump.
        !           393: .SH FILES
        !           394: .PP
        !           395: The file names listed below are
        !           396: .IR typical ,
        !           397: but vary among installations; installation-dependent variants
        !           398: can be displayed by running
        !           399: .I lcc
        !           400: with the
        !           401: .B \-v
        !           402: option.
        !           403: .PP
        !           404: .ta \w'/usr/lib/gcc-cppxx'u
        !           405: .nf
        !           406: file.c input file
        !           407: file.o object file
        !           408: a.out  loaded output
        !           409: /tmp/lcc?      temporaries
        !           410: /usr/lib/gcc-cpp       preprocessor
        !           411: /usr/lib/rcc   compiler
        !           412: /usr/lib/bbexit.o      exit for profiling
        !           413: /lib/crt0.o    runtime startoff
        !           414: /lib/[gm]crt0.o        startoffs for profiling
        !           415: /lib/libc.a    standard library
        !           416: /usr/include/lcc       ANSI standard headers
        !           417: /usr/include/libc      local ANSI headers
        !           418: /usr/include   traditional headers
        !           419: prof.out       file produced for \fIbprint\fR(1)
        !           420: mon.out        file produced for \fIprof\fR(1)
        !           421: gmon.out       file produced for \fIgprof\fR(1)
        !           422: .fi
        !           423: .PP
        !           424: .I lcc
        !           425: predefines the macros `unix' and `__LCC__'.
        !           426: It may also predefine some installation-dependent symbols; option
        !           427: .B \-v
        !           428: exposes them.
        !           429: .SH "SEE ALSO"
        !           430: B. W. Kernighan and D. M. Ritchie,
        !           431: .I The C Programming Language,
        !           432: Prentice-Hall, 2nd Ed., 1988.
        !           433: .PP
        !           434: .I
        !           435: American National Standard for Information Systems, Programming Language C,
        !           436: ANSI X3.159-1989, American National Standard Institute, Inc., New York, 1990.
        !           437: .PP
        !           438: cc(1), ld(1)
        !           439: .br
        !           440: .SH BUGS
        !           441: Mail bug reports along with the shortest program
        !           442: that exposes them and the details reported by
        !           443: .IR lcc 's
        !           444: .B \-v
        !           445: option to [email protected].
        !           446: .PP
        !           447: The `ANSI standard headers' conform to the specifications in
        !           448: the standard, which may be too restrictive for some applications,
        !           449: but necessary for portability.
        !           450: Functions given in the ANSI headers may be missing from
        !           451: the local C library (e.g., `wide character' functions)
        !           452: or may not correspond exactly to the local version;
        !           453: for example, the ANSI standard
        !           454: .B stdio.h
        !           455: specifies that
        !           456: .IR printf ,
        !           457: .IR fprintf ,
        !           458: and
        !           459: .I sprintf
        !           460: return the number of characters written to the file or array,
        !           461: but few existing libraries implement this convention.
        !           462: .PP
        !           463: On VAXes running 4.3bsd UNIX,
        !           464: the definitions of
        !           465: .I tolower
        !           466: and
        !           467: .I toupper
        !           468: erroneously return bad values for non-letter arguments.
        !           469: .PP
        !           470: On the MIPS and SPARC, old-style variadic functions must use
        !           471: .B varargs.h
        !           472: from MIPS or Sun. New-style is recommended.
        !           473: .PP
        !           474: The Sun assembler version 3.5 or later is required on the MC68020,
        !           475: and only the MC68881 is supported.
        !           476: .PP
        !           477: With
        !           478: .BR \-b ,
        !           479: files compiled
        !           480: .I without
        !           481: .B \-b
        !           482: may cause
        !           483: .I bprint
        !           484: to print erroneous call graphs.
        !           485: For example, if
        !           486: .B f
        !           487: calls
        !           488: .B g
        !           489: calls
        !           490: .B h
        !           491: and
        !           492: .B f
        !           493: and
        !           494: .B h
        !           495: are compiled with
        !           496: .BR \-b ,
        !           497: but
        !           498: .B g
        !           499: is not,
        !           500: .B bprint
        !           501: will report that
        !           502: .B f
        !           503: called
        !           504: .BR h .
        !           505: The total number of calls is correct, however.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.