cccc -- Command

C compiler
cccc [_c_o_m_p_i_l_e_r _o_p_t_i_o_n_s] _f_i_l_e .... [_l_i_n_k_e_r _o_p_t_i_o_n_s]

cccc is the program that compiles  C programs.  It guides files of source and
object code  through each  phase of compilation  and linking.  cccc  has many
options to  assist in the  compilation of C programs;  in essence, however,
all you  need to do  to produce an  executable file from your  C program is
type cccc followed  by the name of the file  or files that hold your program.
cccc checks  whether the file names  you give it are  reasonable, selects the
right  phase  for  each  file,  and  performs other  tasks  that  ease  the
compilation of your programs.

_H_o_w _c_c _W_o_r_k_s
cccc works as follows:

-> If a file  ends in .cc, cccc assumes that  it contains C code, and compiles
   it.  The compiler generates  a relocatable object module with the suffix
   .oo.

-> If the file has the suffix  .ss, cccc assumes that it is a file of assembly
   language, and  invokes the assembler  aass to assemble  it.  The assembler
   also generates a relocatable object module with the suffix .oo.

-> cccc  assumes that  all files  with the suffix  .oo are  relocatable object
   modules.   It  also  assumes that  all  files  with  the  suffix .aa  are
   libraries of object modules.  It  passes both directly to the linker lldd.
   Additional  libraries can  also be  invoked by using  the -ll  option cccc,
   described below.

-> Once all  files of C  code and assembly  language have been  compiled or
   assembled,  cccc then  invokes the  linker  lldd to  link the  newly created
   object  files with  any objects  and libraries you  named on  cccc command
   line.  It also automatically  includes the C runtime startup routine and
   the standard  C library,  so you do  not have to  name these on  your cccc
   command line.

-> cccc also cleans  up after itself.  It removes all  of its temporary files
   automatically.  If  only one object file  is created during compilation,
   cccc deletes  it after linking; however,  if more than one  object file is
   created, or if an object file  of the same name existed before you began
   to compile, then the object file or files are not deleted.

Assuming that  no error occurs along  the way, cccc writes  the linked result
into a  file named after  the _f_i_l_e on  its command line,  minus that file's
suffix -- .cc, .ss, or .oo, depending upon the type of data _f_i_l_e holds.  It is
now ready to be executed.

_O_p_t_i_o_n_s
The  following lists  all  of cccc's  command-line options.   cccc passes  some
options through to the linker lldd unchanged, and correctly interprets for it
the options -oo and -uu.

A  number of  the  options are  esoteric  and normally  are  not used  when
compiling a C program.  The following are the most commonly used options:

    -cc      Compile only; do not link
    -ff      Link in floating-point pprriinnttff()
    -ll_n_a_m_e  Pass library lliibb_n_a_m_e.aa to linker
    -oo _n_a_m_e Call output file _n_a_m_e
    -VV      Print verbose listing of cccc's action

?    Print a  detailed usage message that  describes available cccc's options
     to the standard output.

-AA  MicroEMACS  option.    If  an  error  occurs   during  compilation,  cccc
    automatically  invokes  the MicroEMACS  screen  editor.   The error  or
    errors are  displayed in  one window  and the source  code file  in the
    other, with  the cursor set to  the line number indicated  by the first
    error  message.  Typing  <ccttrrll-XX>> moves to  the next  error, <ccttrrll-XX><
    moves to the previous error.   To recompile, close the edited file with
    <ccttrrll-ZZ>. Compilation  will continue either until  the program compiles
    without error,  or until  you exit from  the editor by  typing <ccttrrll-UU>
    followed by <ccttrrll-XX><ccttrrll-CC>.

-BB[_p_a_t_h]
    Backup option.   Use an alternative  _p_a_t_h for the  compiler phases cccc00,
    cccc11, cccc22, and cccc33. If _p_a_t_h is supplied, cccc prefixes it onto the name of
    each phase of the compiler, to form the name of the new compiler phase,
    and the path to the directory  in which it lives.  If you do not supply
    a _s_t_r_i_n_g, cccc prefixes the name of the current directory.

    If you precede a -BB option with a -tt option, the -BB option affects only
    the phase of  the compiler that the -tt option  names.  For example, the
    command

        cc -t0 -B/usr/fred/bin hello.c

    compiles  hheelllloo.cc   using  the  version  of   cccc00  found  in  directory
    /uussrr/ffrreedd/bbiinn.  You  can include  any  number  of pairs  of  -tt and  -BB
    options,  with each  -tt option  naming phase of  the compiler  that the
    subsequent -BB option affects.

    If followed by the prefix option  -MM, the name of the compiler phase in
    question  is  prefixed by  the  string  named in  the  -MM option.   For
    example, the command

        cc -t0 -B/usr/fred/cc -Mnew a.c

    tells the compiler  to look for /uussrr/ffrreedd/cccc/nneewwcccc00 and execute instead
    of the usual cccc00.

-cc  Compile option.  Suppress linking and the removal of the object files.

-DD_n_a_m_e[=_v_a_l_u_e]
    Define _n_a_m_e to the preprocessor, as  if set by a #ddeeffiinnee directive.  If
    _v_a_l_u_e is present, it is used to initialize the definition.

-EE  Expand option.   Run the C  preprocessor ccpppp and write  its output onto
    the standard output.

-ff  Floating-point option.   Include the version of  pprriinnttff() that converts
    floating-point numbers to text.  If a program is compiled without the -
    ff option but attempts to print a floating-point number during execution
    by using the ee, ff, or  gg format specifications to pprriinnttff(), the program
    prints the error message

        You must compile with -f option for floating point

    and exits.

    Note that if you wish to include the lliibbmm library routines that perform
    floating-point  mathematics  functions, you  must  specify  -llmm on  the
    command line to load the library lliibbmm.aa.

-gg  Generate debugging information.  Same as option -VVDDBB, described below.

-II_n_a_m_e
    IInclude option.  Specify a directory the preprocessor should search for
    files given  in #iinncclluuddee directives,  using the following  criteria: If
    the #iinncclluuddee statement reads

        #include "file.h"

    cccc  searches for  ffiillee.hh first  in  the source  directory, then  in the
    directory  named in  the  -II_n_a_m_e option,  and finally  in the  system's
    default directories.  If the #iinncclluuddee statement reads

        #include <file.h>

    cccc searches  for ffiillee.hh  first in the  directories named in  the -II_n_a_m_e
    option, and then  in the system's default directories.  Multiple -II_n_a_m_e
    options are executed in the order of their appearance.

-KK  Keep  option.  Do  not erase  the  intermediate files  generated during
    compilation.   Temporary  files   will  be  written  into  the  current
    directory.

-LL_d_i_r_e_c_t_o_r_y
    Tell  the linker  lldd to  search ddiirreeccttoorryy for  its libraries  before it
    searches the  directories named in the  environmental variable LLIIBBPPAATTHH.
    You can use multiple -LL options in a cccc command.

-ll_n_a_m_e
    Pass  the name  of a  library to  the linker.   cccc expands  -ll_n_a_m_e into
    /lliibb/lliibb_n_a_m_e.aa.  If an alternative library prefix has been specified by
    the -ttll  and -BB_s_t_r_i_n_g options, then  -ll_n_a_m_e expands to _s_t_r_i_n_glliibb_n_a_m_e.aa.
    Note that this is a _l_i_n_k_e_r _o_p_t_i_o_n, and so must appear at the end of the
    cccc command line, or it will not be processed correctly.

-MM_s_t_r_i_n_g
    Machine option.  Use an alternate version of cccc00, cccc11, cccc11aa, cccc11bb, cccc22,
    cccc33,  aass,  lliibb*.aa, and  ccrrttss00.oo,  named by  fixing  _s_t_r_i_n_g between  the
    directory  name and  the pass  and file names.   For examples,  see the
    description of option -BB, above.

-oo _n_a_m_e
    Output option.   Rename the executable  file from the  default to _n_a_m_e.
    Unlike  UNIX, the  COHERENT implementation  of cccc  by default  names an
    executable after  the first first  .cc or .oo  file given on  the command
    line, instead of naming it aa.oouutt. If you want cccc to conform to the UNIX
    standard,  set   include  the  option   -oo  aa.oouutt  when   you  set  the
    environmental   variable  CCCCHHEEAADD.    This  environmental   variable  is
    described  below.   Another  approach  is  to  invoke mmaakkee  to  control
    compilation.  For details, see the Lexicon entry for mmaakkee.

-OO  Optimize option.  Run the code  generated by the C compiler through the
    peephole  optimizer.  The  optimizer pass is  mandatory for  the i8086,
    Z8000, and M68000 compilers, and need not be requested.  It is optional
    for the PDP-11 compiler, but  is recommended for all files except those
    that consist entirely of initialized tables of data.

-pp  Generate code to  profile functions calls.  Programs compiled with this
    option can be run with the  command pprrooff to print a summary of how much
    time the  program spends in each subroutine, to  help you optimize your
    programs.   You  must use  this  option to  compile  each module  whose
    functions you wish to examine; and you must also use this option on the
    cccc command  line with which  you link the  program, to ensure  that the
    appropriate library routines are linked into your executable.

-QQ  Quiet option.  Suppress all messages, no matter how awful an error they
    indicate.

-SS  Suppress   the  object-writing   and  link   phases,  and   invoke  the
    disassembler cccc33. This  option produces an assembly-language version of
    a  C program  for examination,  for  example if  a compiler  problem is
    suspected.   The assembly-language  output  file name  replaces the  .cc
    suffix with .ss. This is equivalent to the -VVAASSMM option.

-TT_s_i_z_e
    cccc writes its temporary data into two 64-kilobytes buffers that grow as
    needed.  The  -TT option  tells cccc  to use buffers  of _s_i_z_e  bytes each.
    Setting these  to a  larger size may  help large files  compile faster.
    Setting _s_i_z_e to zero forces cccc  to use temporary files written onto the
    disk.

-tt_p_h_a_s_e
    Take option.  Use  an alternate versions of the phase  or phases of the
    compiler specified by  pphhaassee, which must consist of one  or more of the
    characters 0011aabb2233ssddllrrtt.  If no _p_h_a_s_e string  appears, cccc uses alternate
    version of  every phase of  the compiler, except  the preprocessor.  If
    the -tt option is followed by a -BB option, cccc prefixes the path named in
    the -BB  option to  the phases  and files named  in the -tt  option.  For
    examples, see the description of option -BB, above,

-UU_n_a_m_e
    Undefine  symbol _n_a_m_e.  Use this  option to  undefine symbols  that the
    preprocessor defines implicitly, such  as the name of the native system
    or machine.   Users who wants  serious ISO namespace  compliance should
    compile with the options:

        -UCOHERENT -UMWC -U_I386 -U_IEEE

    These options turn off the  macros CCOOHHEERREENNTT, MMWWCC, _II338866, and _IIEEEEEE, all
    of which are automatically defined by the COHERENT preprocessor.

-VV  Verbose  option.  cccc  prints onto  the  standard output  a step-by-step
    description of each action it takes.

-VV_s_t_r_i_n_g
    Variant  option.  Toggle  (i.e.,  turn on  or off)  the variant  _s_t_r_i_n_g
    during the  compilation.  Variants that are marked oonn  are turned on by
    default.   Options marked  SSttrriicctt: generate messages  that warn  of the
    conditions in question.  cccc recognizes the following variants:

    -VVAASSMM
       Output  assembly-language  code.   Identical  to -SS  option,  above.
       Default is ooffff.

    -VVCCOOMMMM
       Permit .ccoomm-style data items.  Default is oonn.

    -VVCCPPLLUUSS
       Ignore C++-style comments, which are deliminted by `//'.

    -VVDDBB
       Generate debugging  information, same as option  -gg described above.
       Default is ooffff.

    -VVFFLLOOAATT
       Include floating-point pprriinnttff()  code.  Same as option -ff, described
       above.

    -VVNNDDPP
       Generate code  to execute hardware  floating-point arithmetic.  Code
       generated with this  option executes floating-point arithmetic on an
       80387 or  80486-DX, if present;  or use software emulation  if it is
       not.   Note that  code generated  with this option  will not  run on
       version of COHERENT prior to  release 4.2.  Note, too, that you must
       not  link objects  compiled with  option with  objects that  are not
       compiled with it.  For more information, see the section on hardware
       floating-point arithmetic, below.

    -VVNNOOWWAARRNN
       Suppress all  warning and strict  messages.  Use this  option if you
       wish  to suppress  cascades of  warning  message about,  say, nested
       comments.

    -VVPPRROOFF
       Same as the option -pp, described above.

    -VVPPSSTTRR
       ``imPure'' strings: Place all string literals into the .ddaattaa segment
       rather than  in .tteexxtt.  This  may be necessary  for sloppily written
       code that assumes it can overwrite string literals.

    -VVQQUUIIEETT
       Suppress all messages.  Identical to -QQ option.  Default is ooffff.

    -VVSS
       Turn on all strict checking.  Default is oonn.

    -VVSSBBOOOOKK
       Strict:  note deviations  from _T_h_e  _C  _P_r_o_g_r_a_m_m_i_n_g _L_a_n_g_u_a_g_e,  ed. 1.
       Default is ooffff.

    -VVSSCCCCOONN
       Strict: note constant conditional.  Default is ooffff.

    -VVSSIINNUU
       Implement   struct-in-union   rules   instead   of   Berkeley-member
       resolution  rules.  Default  is ooffff,  i.e.,  Berkeley rules  are the
       default.

    -VVSSLLCCOONN
       Strict:  iinntt constant  promoted to  lloonngg because  value is  too big.
       Default is oonn.

    -VVSSMMEEMMBB
       Strict:  check  use  of  structure/union  members for  adherence  to
       standard rules of C.  Default is oonn.

    -VVSSNNRREEGG
       Strict: register declaration reduced to auto.  Default is oonn.

    -VVSSPPVVAALL
       Strict: pointer value truncated.  Default is ooffff.

    -VVSSRRTTVVCC
       Strict: risky types in truth contexts.  Default is ooffff.

    -VVSSTTAATT
       Give statistics on optimization.

    -VVSSUURREEGG
       Strict: note unused registers.  Default is ooffff.

    -VVSSUUVVAARR
       Strict: note unused variables.  Default is oonn.

    -VVVVEERRSSIIOONN
       Print  to the  standard error the  compiler's version  number.  This
       information is useful when reporting bugs.

    -VVWWIIDDEENN
       Warn the user  if a parameter is widened from  cchhaarr or sshhoorrtt to iinntt,
       or from ffllooaatt to ddoouubbllee. Default is ooffff.

    -VV33GGRRAAPPHH
       Translate ANSI trigraphs.  Default is ooffff.

cccc reads  the environmental variables  CCCCHHEEAADD and CCCCTTAAIILL  and appends their
contents to,  respectively, the  beginning and the  end of the  cccc command.
For example, if you insert the following entries into your .pprrooffiillee

    export CCHEAD='-f -o a.out'
    export CCTAIL=-lm

then  cccc will  always use  the floating-point  version of  pprriinnttff(), always
write its  executable into file  aa.oouutt, and always link  in the mathematics
library lliibbmm.  In effect, it turns the command

    cc hello.c

into:

    cc -f -o a.out hello.c -lm

If you set a command option in CCCCHHEEAADD or CCCCTTAAIILL, you can always override it
for specific cccc commands.  For example, if you have set -oo aa.oouutt in CCCCHHEEAADD,
typing the command

    cc -o hello hello.c

generates the command:

    cc -o a.out -o hello hello.c

The latter -oo  option is the one used, and  in effect cancels the effect of
the CCCCHHEEAADD entry.  Thus, setting CCCCHHEEAADD  and CCCCTTAAIILL give you a flexible way
to set cccc's default behavior.

Note that

    CCHEAD='-Wa,-f -Wl,-oa.out'

will  give you  a compilation  environment  that matches  that of  the UNIX
operating system.

_L_i_n_k_i_n_g _O_b_j_e_c_t_s
The linker lldd does not know  about paths: it links exactly what you tell it
to link  via the  cccc command  line.  cccc looks  for compiler phases  and for
runtime  startoff and  library by  searching the  directories named  in the
environmental  variable  LLIIBBPPAATTHH. If  you  do not  define  LLIIBBPPAATTHH in  your
environment,   it   searches    the   default   LLIIBBPPAATTHH   as   defined   in
/uussrr/iinncclluuddee/ppaatthh.hh. If you  define LLIIBBPPAATTHH, cccc searches the directories in
the order you specify.  For example, a typical definition is:

    export LIBPATH=:/lib:/usr/lib

This searches the current directory `.', then /lliibb, then /uussrr/lliibb.

_H_a_r_d_w_a_r_e _F_l_o_a_t_i_n_g-_P_o_i_n_t _A_r_i_t_h_m_e_t_i_c
The  C compiler  shipped  with version  of  COHERENT prior  to release  4.2
generated software floating point calls.  That is, floating-point code such
as

    d1 = d2 + 2.5;

generated  calls to  software routines to  perform the  desired operations.
This is called ``software floating-point arithmetic''.

Beginning with release 4.2, the COHERENT C compiler can also generate calls
to  execute floating-point  operations on a  numeric data  processor (NDP),
such as the 80387.  This is called ``hardware floating-point arithmetic''.

A program  compiled to perform software  floating-point arithmetic will run
correctly on  any computer, regardless  of whether it contains  an NDP; the
code ignores  the NDP and simply performs  all floating-point arithmetic on
the CPU.  A  program compiled to perform hardware floating-point arithmetic
will also run  correctly on any computer: if the  computer contains an NDP,
the code  executes on that  part; but if  the computer does  not contain an
NDP, the code  emulates the operation of the NDP.   Note, however, that the
speed with which each type of floating-point arithmetic executes will vary,
depending  on the  type of  computer it  is run on.   This is  described in
detail below.

The  compiler generates  software floating-point code  by default.   To use
hardware floating-point,  compile your programs with  the compiler option -
VVNNDDPP.  This option  also  tells the  linker  lldd to  look  for libraries  in
/lliibb/nnddpp or  /uussrr/lliibb/nnddpp rather  than in /lliibb  or /uussrr/lliibb. Note  that the
standard libraries  for software floating point and  NDP floating point are
different.   If you  mix objects  compiled with  -VVNNDDPP option  with objects
compiled  with it,  either you  will see  errors when you  try to  link the
program or the program will not run correctly.

Because of  these changes (among others), you  _c_a_n_n_o_t link objects compiled
with  the version  4.0 compiler  with  those compiled  with version  4.2 or
later.  Before you relink your program, you _m_u_s_t compile all object modules
with the new compiler.

Because release  of COHERENT prior to release 4.2  did not support hardware
floating-point arithmetic,  you cannot run any program  compiled with the -
VVNNDDPP under  any version of COHERENT  prior to release 4.2.   If you are not
sure which  version of COHERENT  a user is  running, check the  contents of
file /eettcc/iinnssttaallll.lloogg.

As mentioned above, there is  a speed trade-off in using hardware floating-
point arithmetic.  Consider  the following benchmarks, which were generated
with a program that computes transcendental functions:

    Software floating point: 10.1 seconds
    Hardware floating point with NDP: 1.0 seconds
    Hardware floating point, no NDP: 54.0 seconds

As you  can see, hardware  floating-point arithmetic runs  much faster than
software floating-point  arithmetic when the machine  has an NDP installed.
However,  hardware  floating-point  runs  much  more slowly  than  software
floating-point arithmetic when an  NDP is _n_o_t installed.  You should choose
carefully  the type  of floating-point arithmetic  you use,  depending upon
what machines you expect your code to be run on.

_F_i_l_e_s
/bbiinn/cccc -- C compiler

_S_e_e _A_l_s_o
aass,  CC llaanngguuaaggee,  cccc00, cccc11,  cccc22, cccc33, ccoommmmaannddss,  CC pprreepprroocceessssoorr,  ccpppp, lldd,
LLIIBBPPAATTHH, TTMMPPDDIIRR
_T_h_e _C _L_a_n_g_u_a_g_e, tutorial

_N_o_t_e_s
If you see the message

    Out of memory

when compiling,  this probably  means that  your program has  exhausted the
buffer space available to it.  Use  the option -TT00 to force cccc to write its
temporary files on the disk.

Prior  to COHERENT  release 4.2,  cccc wrote its  diagnostic messages  to the
standard  output device.   cccc  now writes  its diagnostic  messages to  the
standard  error.  You  may need  to  modify any  scripts that  redirect the
output of cccc.
