[1831] in Athena Bugs
[Mark Lillibridge: RT 6.1A: hc2 man page missing]
daemon@ATHENA.MIT.EDU (probe@ATHENA.MIT.EDU)
Tue Feb 28 04:16:40 1989
From: <probe@ATHENA.MIT.EDU>
Date: Tue, 28 Feb 89 04:16:13 EST
To: manbugs@ATHENA.MIT.EDU
Cc: "Follow up information" <bugs@ATHENA.MIT.EDU>
Reply-To: Richard Basch <probe@ATHENA.MIT.EDU>
I dug up a copy of the "hc" man page from the IBM source distribution
machine (STYX.MIT.EDU). Their "hc" man page corresponds to our "hc2",
so this should be appropriate after all the references to "hc" are
changed appropriately.
Documentation: This is an RT-specific man page.
-Richard
-------------------------------- cut here -------------------------------------
.\"
.\" 5799-WZQ (C) COPYRIGHT IBM CORPORATION 1986,1987,1988
.\" LICENSED MATERIALS - PROPERTY OF IBM
.\" REFER TO COPYRIGHT INSTRUCTIONS FORM NUMBER G120-2083
.\"
.\"$Header:hc.1_ca 12.0$
.\"$ACIS:hc.1_ca 12.0$
.\"$Source: /ibm/acis/usr/man/man1/RCS/hc.1_ca,v $
.\" This file contains -man macros.
.nh
.ad l
.TH HC 1 "Sept 1988" "Space overwritten by .AC macro" " "
.AC 1 0
.SH NAME
hc \- Optimizing High C compiler
.SH SYNOPSIS
.B hc
[ \fIoptions\fR ] \fIfile\fR ...
.SH DESCRIPTION
The
.I hc
command invokes version 2 of the High C compiler.
The compiler accepts C-language programs at the draft ANSI Standard
C level and compiles with or without global optimization.
The command
accepts several types of arguments:
.TP 3
\(bu
Arguments with filenames ending in ``.c'' are taken to be
C source programs. They are preprocessed either by
.I cpp
or the inboard preprocessor,
compiled to assembler source, and assembled
.IR as (1)
to produce object files with the same names ending in ``.o''
instead of ``.c''.
The ``.o'' file is normally deleted if a single
C program is compiled and loaded at one time.
.TP
\(bu
In the same way,
arguments with names ending in ``.s'' are taken to be assembly source programs
and are assembled, producing ``.o'' files.
.PP
Unless the loading is suppressed by the
.B \-c
option, all produced ``.o'' and argument ``.o'' files are linked
.IR ld (1)
with standard startoff and library routines to produce an
executable module named
.BR a.out .
.PP
Arguments that begin with ``-'' are options that modify
the behavior of
.IR hc (1),
the
.I cpp
preprocessor,
.IR as (1),
or
.IR ld (1).
The following options are interpreted by
.IR hc .
See
.IR ld (1)
for load-time options.
By convention, options applicable only to the High C compiler
are prefixed with an
.BR H .
The
.BI \-H xxxx
options are described in detail in the ``High C Programmer's Guide.''
The most frequently used
.BI \-H xxxx
options are included in the following list.
.TP 10
.B \-c
Suppress the loading phase of the compilation, and force
an object (.o)
file to be produced even if only one program is compiled.
.TP
.B \-g
Have
the compiler produce additional symbol-table information
for
.IR dbx (1).
This flag turns off certain optimizations that complicate
debugging by rearranging code. Use the
.B \-O
flag in conjunction with
.B \-g
if you wish all normal optimizations to be included.
.TP
.B \-w
Suppress warning diagnostics.
.TP
.B \-p
Arrange for the compiler to produce code
that counts the number of times each routine is called during execution.
If loading takes place, search the profiling library
.I /usr/lib/libc_p.a
in lieu of the standard C library
.IR /lib/libc.a .
Also
replace the standard startup
routine by one that automatically calls
.IR monitor (3)
at the start and arranges to write out a
.I mon.out
file at normal termination of execution of the object program.
An execution profile can then be generated by
use of
.IR prof (1).
.TP
.B \-pg
Like
.BR \-p ,
but invoke a run-time recording mechanism that keeps more
extensive statistics and produces a
.I gmon.out
file at normal termination.
An execution profile can then be generated by use of
.IR gprof (1).
.TP
.B \-O
Perform all optimizations supported by the compiler.
Many optimizations are performed even without the
.B \-O
option.
.TP
.B \-R
Pass this flag on to
.I as,
making initialized variables shared and read-only.
.TP
.B \-S
Suppress assembly and loading.
Produces a ``.s'' file for each ``.c'' file argument.
The
.B \-Hanno
option annotates the ``.s'' file.
.TP
.B \-M
Run only the cpp macro preprocessor on the named C programs,
requesting it to generate Makefile dependencies and send the result to the
standard output.
.TP
.B \-E
Run only the cpp macro preprocessor
on the named C programs, and send the result to the
standard output.
.TP
.B \-C
Prevent the cpp macro preprocessor from removing comments.
.TP
.BI \-o " output"
Name the final output file
.IR output .
If this option is used, the file
.B a.out
will be left undisturbed.
.TP
.BI \-D name=def
.br
.ns
.TP
.BI \-D \*Sname
Define
.I name
to the preprocessor,
as if by
``#define''.
If no definition is given,
.I name
is defined as 1 (one).
.TP
.BI \-U \*Sname
Remove any initial definition of
.IR name .
.TP
.BI \-I \*Sdir
``#include'' files
that do not have names beginning in ``/'' are always
sought first in the directory
of the
.I file
argument,
then in directories named in
.B \-I
options,
and finally in directories on a standard list.
.TP
.BI \-L \*Sdir
Library archives are sought first in directories named in
.B \-L
options, then in directories on a standard list.
.TP
.BI \-B \*Sstring
Find substitute compiler executables in the files named
.I string
with the suffixes ``hc1com'' and ``hc2com.''
.TP
.B \-v
Display each subprocess being executed on standard error.
.TP
.BI \-m x
Compile using some machine-dependent options. The
available options are:
.RS 10
.TP
.B \-ma
Support use of
.IR alloca (3)
by the compiled function.
.I Alloca
places some constraints on compiled code, making it slightly less efficient.
Only the individual functions that call
.I alloca
need be compiled with
.BR \-ma .
.TP
.B \-ms
Forces the compiler to put out minimum-size floating point
data blocks. (Normally they are generously padded.)
This guarantees that the size of objects will remain approximate
to that of previous releases, at a small cost in performance.
See the ``IBM/4.3 Linkage Convention'' article
for more information.
.RS -10
.TP
.B \-Hanno
Annotate the generated ``.s'' file with comment lines
containing the source code from the ``.c'' file.
.TP
.B \-Hansi
Causes the compiler to only accept programs conforming
to the proposed ANSI standard.
.TP
.B \-Hcpp
Invoke the cpp macro preprocessor on all source
files before compiling. This is the default.
.TP
.B \-Hnocpp
Use the
.I hc
ANSI-conforming macro preprocessor instead of cpp.
.TP
.B \-Hlist
Produce a source listing on standard output.
.TP
.BI \-Hon =toggle
.br
.ns
.TP
.BI \-Hoff =toggle
Turn
.I toggle
on or off. (See Compiler Toggles in the
\*(lqHigh C Programmer's Guide\*(rq
for a description of the compiler toggles.)
.TP
.B \-Hpcc
Specifies that the compiler is to run in ``PCC'' mode.
In ``PCC'' mode the compiler relaxes enough of the ANSI
extensions to more or less emulate the Portable
C Compiler.
This permits old C programs that would not ordinarily compile
to compile with few (if any) modifications. See the
``High C Programmer's Guide'' for details.
.TP
.B \-Hvolatile
Inhibit optimization of pointer dereferencing,
forcing each instance to generate a memory access.
Consider this a conversion aid to be used until truly
volatile objects have been identified and labeled with the
.B volatile
type qualifier.
.TP
.B \-H+w
Issue all warnings.
The default is to suppress low-severity warnings.
.SH FILES
.ta \w'/usr/lib/libc_p.a 'u
file.c C source file
.br
file.o object file
.br
file.s assembler source file
.br
a.out loaded output
.br
/tmp/pp.* temporary
.br
/lib/cpp outboard macro preprocessor
.br
/usr/lib/hc1com compiler pass 1
.br
/usr/lib/hc2com compiler pass 2
.br
/lib/crt0.o runtime startoff
.br
/lib/mcrt0.o startoff for profiling
.br
/usr/lib/gcrt0.o startoff for gprof-profiling
.br
/lib/libc.a standard library, see
.IR intro (3)
.br
/usr/lib/libc_p.a profiling library, see
.IR intro (3)
.br
/usr/include directory for #include files
.br
mon.out file produced for analysis by
.IR prof (1)
.br
gmon.out file produced for analysis by
.IR gprof (1)
.SH "SEE ALSO"
B. W. Kernighan and D. M. Ritchie,
.I The C Programming Language,
Prentice-Hall,
1978
.br
B. W. Kernighan,
.I
Programming in C\(ema tutorial
.br
D. M. Ritchie,
.I
C Reference Manual
.br
``IBM/4.3 Linkage Convention'' in the supplementary documents
.br
\*(lqHigh C Programmer's Guide\*(rq in Appendix C
.br
\fIHigh C Language Extensions Manual with Rationale and Tutorials\fR,
from MetaWare Incorporated.
.br
\*(lqRecompiling with High C\*(rq in the supplementary documents
.br
adb(1), as(1), cc(1), dbx(1), gprof(1), ld(1), pcc(1), prof(1), malloc(3), monitor(3)
