


GCT(1)                   USER COMMANDS                     GCT(1)



NAME
     gct - Generic Coverage Tool

SYNOPSIS
     gct  [  -test-control  _c_o_n_t_r_o_l__f_i_l_e__n_a_m_e   ]   [   -test-map
     _m_a_p__f_i_l_e__n_a_m_e  ]  [  -test-dir  _m_a_s_t_e_r__d_i_r_e_c_t_o_r_y  ] [ -test-
     varargs ] [ -test-cc _a_l_t_e_r_n_a_t_e__c_o_m_p_i_l_e_r ]  _f_i_l_e_n_a_m_e ...


DESCRIPTION
     gct is a generic coverage tool for C programs. It implements
     branch  coverage,  multi-condition  coverage, loop coverage,
     and weak mutation coverage.  This  description  is  a  brief
     summary; see the User's Manual for more.

     The tool works as a preprocessor for  C  source  files.   It
     parses  the  source, adds code to test whether the program's
     execution satisfies certain _c_o_v_e_r_a_g_e _c_o_n_d_i_t_i_o_n_s, and  writes
     the  resulting  C  program.  It also writes a _m_a_p _f_i_l_e which
     describes the meaning and location (in the  original  source
     file)  of each of the coverage conditions.  The instrumented
     source can be compiled with any standard C  compiler.    The
     resulting  executable,  when  executed,  writes  a _l_o_g _f_i_l_e.
     _g_r_e_p_o_r_t(1) is then used to  see  which  coverage  conditions
     have  yet  to  be satisfied.  More tests are then written in
     the hopes of satisfying the coverage conditions.

     The _c_o_n_t_r_o_l _f_i_l_e is used to control GCT.   Control  is  very
     flexible and extensive;  see the user documentation.

OPTIONS
     -test-dir _m_a_s_t_e_r__d_i_r_e_c_t_o_r_y
          Specifies the _m_a_s_t_e_r _d_i_r_e_c_t_o_r_y where the map file  will
          be  stored  and  where  gct expects to find the control
          file. The default is the current directory. If you work
          with hierarchical makefiles that invoke other makefiles
          in other directories, this option must be used.

     -test-control _c_o_n_t_r_o_l__f_i_l_e__n_a_m_e
          Use the _c_o_n_t_r_o_l__f_i_l_e__n_a_m_e as the control file found  in
          the master directory. The default is _g_c_t-_c_t_r_l.

     -test-map _m_a_p__f_i_l_e__n_a_m_e
          The _m_a_p__f_i_l_e__n_a_m_e will be used instead of the  default,
          _g_c_t-_m_a_p.   _m_a_p__f_i_l_e__n_a_m_e  is  still found in the master
          directory.

     -test-varargs
          Print out information to help you correctly  instrument
          files  that include <varargs.h> or <stdarg.h>.  Special
          handling is required on some machines.  See _G_C_T  _T_r_o_u_b_-
          _l_e_s_h_o_o_t_i_n_g.



Sun Release 4.1   Last change: 1 November 1990                  1






GCT(1)                   USER COMMANDS                     GCT(1)



     -test-cc _a_l_t_e_r_n_a_t_e__c_o_m_p_i_l_e_r
          Tell GCT to expect that its  output  will  be  compiled
          with  _a_l_t_e_r_n_a_t_e__c_o_m_p_i_l_e_r.   On  some  machines, this is
          required for files containing functions with  variable-
          length argument lists.  See _G_C_T _T_r_o_u_b_l_e_s_h_o_o_t_i_n_g.

     In addition to these options, gct accepts gcc options.   For
     example,  when  compiling  old programs, you may need to use
     the -traditional flag.  See gcc(1).

DIAGNOSTICS
     gct instruments the files and returns exit code  0.  On  any
     error,  the  input files remain untouched and exit code 1 is
     returned.

SEE ALSO
     gcc (1), gclean (1), gcorefrom (1), gedit (1), gfilter  (1),
     gmerge  (1), gnewer (1), greport (1), grestore (1), gsummary
     (1), _G_e_n_e_r_i_c _C_o_v_e_r_a_g_e _T_o_o_l (_G_C_T) _U_s_e_r'_s _G_u_i_d_e




































Sun Release 4.1   Last change: 1 November 1990                  2






GCLEAN(1)                USER COMMANDS                  GCLEAN(1)



NAME
     gclean - remove files created by GCT.

SYNOPSIS
     gclean

DESCRIPTION
     gclean removes all the files in the current  directory  that
     GCT created.  These files are:

     gct-ps-defs.h
     gct-map
     gct-rscript
     gct-rscript.bk
     __gct-macros
     gct_backup (and all its contents)
     gct-ps-defs.c
     gct-write.c
     gct-defs.h
     gct-edit
     gct-edit.bak

     If you edited any of these files (when using race  coverage,
     for  example,  or by calling gedit), you may not want to use
     gclean.

BUGS
     gclean doesn't remove all the  gct_backup  directories  that
     might  have been created; only the one in the current direc-
     tory.

SEE ALSO
     gct(1).






















Sun Release 4.1     Last change: 10 May 1992                    1






GCOREFROM(1)             USER COMMANDS               GCOREFROM(1)



NAME
     gcorefrom - determine what GCC instrumentation caused a core
     dump

SYNOPSIS
     gcorefrom _p_r_o_g_r_a_m [ _c_o_r_e_f_i_l_e ]


DESCRIPTION
     When operand instrumention is turned on, GCT may add instru-
     mentation  that  could  cause  a bad pointer dereference and
     resulting core dump.  If a core file is  caused  by  such  a
     problem,  gcorefrom  identifies  the coverage condition that
     was being checked at the time.

     ernie-30% gcorefrom gcc
     Instrumentation point 2752 was being evaluated when core dumped.
     That corresponds to this test condition:
     00002752 gcc.c 1417 operand i might be present.
     (The second field is the source file; the third is the line number.)

     The -_d_e_r_e_f_e_r_e_n_c_e or -_a_r_r_a_y-_s_u_b_s_t_i_t_u_t_i_o_n_s options  can  avoid
     such  core  dumps,  but  also  make  operand  coverage  less
     thorough.

     In order to use  gcorefrom,  you  must  edit  _g_c_t-_d_e_f_s._h  to
     define  GCT_WEAK_MUTATION.  See that file for more.  This is
     admittedly inconvenient; if anyone uses weak mutation  seri-
     ously  enough  to  find this a real problem, I'll fix GCT to
     make the definition automatically.

SEE ALSO
     gct(1).

BUGS
     gcorefrom requires adb(1); some systems do not have it.

DIAGNOSTICS
     None.
















Sun Release 4.1   Last change: 24 January 1991                  1






GEDIT(1)                 USER COMMANDS                   GEDIT(1)



NAME
     gedit - manually suppress gct coverage conditions

SYNOPSIS
     gedit  [   -test-dir   _m_a_s_t_e_r__d_i_r_e_c_t_o_r_y   ]   [   -test-edit
     _e_d_i_t__f_i_l_e__n_a_m_e ] [ _r_e_p_o_r_t__f_i_l_e__n_a_m_e ]

DESCRIPTION
     gedit creates or  edits  the  _e_d_i_t  _f_i_l_e,  a  file  used  by
     greport(1)  to  control its display.  To use gedit, you must
     first create a report file using greport -edit:

     % greport -edit LOG > REPORT

     This report looks like:

     "test.c", line 3: [0: 1 0] if was taken TRUE 1, FALSE 0 times.
     "test.c", line 3: [1: 0] operator < might be <=.
     "test.c", line 3: [2: 1 0] condition 1 (argc, 1) was taken TRUE 1, FALSE 0 times.
     "test.c", line 3: [3: 0 0] condition 2 (argc, 1) was taken TRUE 0, FALSE 0 times.

     Each line represents one or more coverage conditions.   (For
     example,  a  branch  represents  two:  one that requires the
     branch to be taken TRUE, and one that requires the branch to
     be  taken FALSE.)  The text of interest is in brackets.  The
     number before the colon is the map file index for the  first
     of  that  line's coverage conditions.  The numbers after the
     colon show how often the respective conditions  were  satis-
     fied.   For  example,  in  the case of the IF statement, the
     TRUE condition was satisfied once and  the  FALSE  condition
     never.  The operator condition was satisfied zero times.

     If a condition is impossible to satisfy,  you  may  want  to
     tell greport not to display information about it, even if no
     test case has ruled it out.  The first step in doing this is
     to  suppress the condition by replacing its number by an "S"
     or "s".  You can also add the "S"  or  "s"  to  the  number.
     Here is an example:

     "test.c", line 3: [0: 1 0S] if was taken TRUE 1, FALSE 0 times.
     "test.c", line 3: [1: 0s] operator < might be <=.
     "test.c", line 3: [2: 1 s] condition 1 (argc, 1) was taken TRUE 1, FALSE 0 times.
     "test.c", line 3: [3: 0 S] condition 2 (argc, 1) was taken TRUE 0, FALSE 0 times.

     By doing this, you have declared that you do not want to see
     the first three lines again -- all the condition numbers are
     either non-zero or suppressed.  You want the fourth line  to
     be shown until the multi-condition is taken TRUE.

     To cause your changes to take effect, run  gedit.   It  will
     create  or  modify the edit file.  If one already existed, a
     backup is made:



Sun Release 4.1   Last change: 1 November 1990                  1






GEDIT(1)                 USER COMMANDS                   GEDIT(1)



     % gedit REPORT
     Backup file is gct-edit~.

     From this point on, greport will treat suppressed conditions
     as  if  they'd been satisfied.  The output from greport will
     look like:

     "test.c", line 3: condition 2 (argc, 1) was taken TRUE 0, FALSE 0S times.

     Notice that the FALSE case has been tagged with an S.


     Suppression is additive.  If a condition  is  suppressed  in
     the  edit file, it stays suppressed.  This matches the usual
     use, which is to suppress some set of conditions, test  some
     more,  suppress more conditions, and so on, with the goal of
     eventually producing an empty  report  when  all  conditions
     have been satisfied or suppressed.

     Loops can be confusing.  They have  three  conditions:  that
     they  be  executed no times, exactly once, and more than one
     time.  Yet the greport -edit output looks like this:

     "test.c", line 4: [17: 0 0 1 0] loop zero times: 0, one time: 1, many times: 0.


     There are four condition numbers within the  brackets.   The
     second  and  third numbers are jointly used to keep track of
     the "one time" condition.  You may suppress either of them.

OPTIONS
     -test-dir _m_a_s_t_e_r__d_i_r_e_c_t_o_r_y
          The _m_a_s_t_e_r _d_i_r_e_c_t_o_r_y is  the  directory  where  all  of
          gct's  data  files  are  kept.   By  default, it is the
          current directory.  This option changes the default.

     -test-edit _e_d_i_t__f_i_l_e__n_a_m_e
          This option changes the default name for the edit  file
          from  "gct-edit"  to some other name.  Unless the argu-
          ment is an absolute pathname, it is taken to  be  rela-
          tive to the master directory.

BUGS
     The handling of errors in the input file is crude.

     There is no way to unsuppress a condition, except  by  manu-
     ally  editing  the  gct-edit file.  This is easy to do:  use
     "greport -edit -all" to get a  complete  display,  find  the
     location  (the number before the colon), and change _g_c_t-_e_d_i_t
     so that the corresponding entry is a 0 instead of a 1.





Sun Release 4.1   Last change: 1 November 1990                  2






GEDIT(1)                 USER COMMANDS                   GEDIT(1)



SEE ALSO
     gct(1), greport(1).





















































Sun Release 4.1   Last change: 1 November 1990                  3






GFILTER(1)               USER COMMANDS                 GFILTER(1)



NAME
     gfilter - filter GCT greport output.

SYNOPSIS
     gfilter [ -branch ] [ -loop ] [ -operator ] [ -operand  ]  [
     -multi ] [ -routine ] [ -call ] [ -race ] [ _r_e_p_o_r_t__f_i_l_e__n_a_m_e
     ]

DESCRIPTION
     gfilter reads the output from greport(1).  It passes through
     only  report  lines  that correspond to flag arguments.  The
     flag arguments have the same  name  as  those  used  in  the
     gct(1) control file.

     There is no -relational option; the -operator option applies
     to relational as well as all other kinds of operator lines.

     If no file name is given, standard input is used.

     Example:

     ernie-62% gfilter report.g
     ernie-63% gfilter -multi report.g
     "test.c", line 3: condition 1 (argc, 1) was taken TRUE 1, FALSE 0 times.
     "test.c", line 3: condition 2 (argc, 1) was taken TRUE 0, FALSE 0 times.
     ernie-64% gfilter -branch -multi report.g
     "test.c", line 3: if was taken TRUE 1, FALSE 0 times.
     "test.c", line 3: condition 1 (argc, 1) was taken TRUE 1, FALSE 0 times.
     "test.c", line 3: condition 2 (argc, 1) was taken TRUE 0, FALSE 0 times.
     "test.c", line 4: while was taken TRUE 1, FALSE 1 times.


SEE ALSO
     greport(1), gct(1).





















Sun Release 4.1   Last change: 1 November 1990                  1






GMERGE(1)                USER COMMANDS                  GMERGE(1)



NAME
     gmerge - merge GCT log files

SYNOPSIS
     gmerge _l_o_g__f_i_l_e__n_a_m_e_1 [ _l_o_g__f_i_l_e__n_a_m_e_2 ... ]

DESCRIPTION
     gmerge takes one or more  log  files  produced  by  programs
     instrumented  with gct(1).  It produces a summary logfile on
     its standard output.  The counts in the summary log file are
     the sum of the counts in the input log files.

     A maximum of 100 logfiles can be merged at a time.

     Example of usage:
          host-1% gmerge test3_log test4_log > all_log

SEE ALSO
     greport(1), gct(1).




































Sun Release 4.1   Last change: 1 November 1990                  1






GNEWER(1)                USER COMMANDS                  GNEWER(1)



NAME
     gnewer - produce difference of two gct log files.

SYNOPSIS
     gnewer [ -logical ] _o_l_d-_l_o_g _n_e_w-_l_o_g


DESCRIPTION
     gnewer is used to compare two log files.  The _n_e_w-_l_o_g  is  a
     cumulative  log,  containing  all the information of _o_l_d-_l_o_g
     plus information from later test runs.

     gnewer is most often used when  testing  programs  that  run
     cyclically.  For example, suppose you have a particular test
     for the UNIX kernel, and you want to see which conditions it
     forces.   The process of booting the kernel may satisfy some
     of those conditions.  Your  test  session  would  look  like
     this:

     1. Boot the kernel and extract a snapshot, _o_l_d-_l_o_g,  of  the
     conditions that were satisfied.
     2. Execute your test.
     3. Extract another snapshot, _n_e_w-_l_o_g.
     4. Run gnewer to see which conditions were satisfied by  the
     test  (plus  whatever  conditions  were satisfied during the
     extraction):

     gnewer old-log new-log | greport
     gnewer old-log new-log | gsummary


     For  each  coverage  condition,  the  arithmetic  difference
     between the new and old logfiles is printed to standard out-
     put.  This does not distinguish between two cases:

     1) The condition was satisfied 5 times in the old  log  file
     and 10 times in the new one.
     2) The condition was satisfied 0 times in the old  log  file
     and 5 times in the new one.

     In both cases, the resulting logfile will have  5  for  that
     coverage  condition.   To distinguish them, use the -_l_o_g_i_c_a_l
     option.  Case 1 will result in a 0 in  the  output  (meaning
     that either both or neither of the test suites satisfied the
     coverage condition).  Case 2 will result  in  a  1  (meaning
     that the new tests satisfy a previously unsatisfied coverage
     condition).

     In summary, gnewer piped into gsummary will  summarize  what
     the  new  tests do; gnewer -logical piped into gsummary will
     summarize what the new tests uniquely do.




Sun Release 4.1   Last change: 1 November 1990                  1






GNEWER(1)                USER COMMANDS                  GNEWER(1)



SEE ALSO
     greport(1), gct(1).

DIAGNOSTICS
     "Usage: gnewer old-log new-log"
     "gnewer:  New log contains fewer conditions than old."
         At least one condition in the new log has been satisfied
         fewer  times than the corresponding condition in the old
         log.  You've mixed two incompatible log files.  The out-
         put logfile is produced, regardless, but the exit status
         is 1.

     Besides this error, gnewer does not handle user errors  very
     gracefully.  You may get one of these messages:

     "gnewer:  Problem with _f_i_l_e"
     "gnewer:  Problem with join or awk"






































Sun Release 4.1   Last change: 1 November 1990                  2






GREPORT(1)               USER COMMANDS                 GREPORT(1)



NAME
     greport - report on execution of a program  instrumented  by
     gct.

SYNOPSIS
     greport [ -l ] [ -test-dir _m_a_s_t_e_r__d_i_r_e_c_t_o_r_y  ]  [  -test-map
     _m_a_p__f_i_l_e__n_a_m_e  ]  [  -test-edit  _m_a_p__f_i_l_e__n_a_m_e  ] [ -all ] [
     -edit ] [ _l_o_g__f_i_l_e__n_a_m_e ]

DESCRIPTION
     greport uses the map file, the log file, and the  edit  file
     to  produce  a report on the test execution that resulted in
     the log file.  The report contains information about  condi-
     tions that have not yet been fully tested.

     The map file is created during the  instrumentation  of  the
     source  code  by  gct.   The  log file is usually written by
     gct_writelog() during a test run.  The edit file is  created
     by  gedit  and is used to suppress the display of conditions
     that are judged impossible (or too difficult) to satisfy.

     The map file and edit file have default names  that  can  be
     overridden  with options.  The log file is given as the sin-
     gle argument.  If no log file is given, _g_r_e_p_o_r_t  reads  from
     standard input.

     The resulting report looks like the output  of  the  UNIX  C
     compiler  and  can  be  used  with error(1) or the GNU Emacs
     _n_e_x_t-_e_r_r_o_r  function.   The  complete   output   format   is
     described in _G_e_n_e_r_i_c _C_o_v_e_r_a_g_e _T_o_o_l (_G_C_T) _D_o_c_u_m_e_n_t_a_t_i_o_n.

     Example:

          host-1% greport test3_log
          "lc.c", line 247: if was taken TRUE 0, FALSE 3 times.
          "lc.c", line 268: operand i might be constant.
          "lc.c", line 568: loop zero times: 0S, one time: 0, many times: 1551.

     This report shows that a branching statement was never taken
     true,  a  particular  reference  to  the  variable  _I always
     yielded the same  value,  and  a  loop  was  never  executed
     exactly  one  or  exactly  zero times.  The "0S" in the last
     case indicates that the user has suppressed  this  condition
     -- the loop can never execute zero times.

     If another test is run that causes the if to be taken in the
     TRUE  direction,  a  later report will not display the first
     line.  If that test also causes  the  loop  to  execute  one
     time,  the last line will not be shown, even though the loop
     never executed zero times.





Sun Release 4.1    Last change: 27 March 1990                   1






GREPORT(1)               USER COMMANDS                 GREPORT(1)



     greport will accept partial mapfiles and mapfiles with gaps.
     In  this  case,  it prints only information about the condi-
     tions in the mapfile.  It  is  usually  more  convenient  to
     filter greport's output -- see gfilter(1) for one such tool.

     An error message is printed if the  logfile  contains  fewer
     entries  than the mapfile.  A warning is printed if the map-
     file has fewer entries than the logfile, and all the missing
     entries  are at the end of the mapfile.  This guards against
     using the wrong mapfile with a logfile.  Since  editing  the
     mapfile is allowed, the message is only a warning.  Mapfiles
     shorter because of gaps before the end are assumed  to  have
     been edited, so no warning is printed.

OPTIONS
     -test-dir _m_a_s_t_e_r__d_i_r_e_c_t_o_r_y
          The _m_a_s_t_e_r _d_i_r_e_c_t_o_r_y is  the  directory  where  all  of
          gct's  data  files  are  kept.   By  default, it is the
          current directory.  This option changes the default.

     -test-map _m_a_p__f_i_l_e__n_a_m_e
          By default, information about  coverage  conditions  is
          found  in  the  file "gct-map" in the master directory.
          This option changes the default.  Unless  the  argument
          is  an absolute pathname, it is taken to be relative to
          the master directory.

     -test-edit _e_d_i_t__f_i_l_e__n_a_m_e
          The edit file tells greport not to  report  on  certain
          coverage  conditions.   Its  name is, by default, "gct-
          edit".  This option changes the  default.   Unless  the
          argument  is  an  absolute  pathname, it is taken to be
          relative to the master directory.

     -l   Normally, greport prints file  names  relative  to  the
          master directory.  Given this option, it prints them as
          absolute pathnames.

     -all greport will display the values for all coverage condi-
          tions,  satisfied  or  no.   Such  a display might look
          like:

          "test.c", line 3: operator < might be <=. (L==R) [0]
          "test.c", line 4: while was taken TRUE 1, FALSE 1 times.
          "test.c", line 4: loop zero times: 0S, one time: 1, many times: 0.
          "test.c", line 4: operand argc might be constant.  [1]

          The numbers in brackets indicate how many times a  con-
          dition  has  been  satisfied.  A condition satisfied no
          times requires a test case.

     -edit



Sun Release 4.1    Last change: 27 March 1990                   2






GREPORT(1)               USER COMMANDS                 GREPORT(1)



          If this option is given, greport's output is in a  for-
          mat  that can be edited and used as gedit's input.  See
          _g_e_d_i_t(_1) for details.

SEE ALSO
     gsummary(1), gedit(1), gct(1).

















































Sun Release 4.1    Last change: 27 March 1990                   3






GRESTORE(1)              USER COMMANDS                GRESTORE(1)



NAME
     grestore - restore the original versions  of  files  instru-
     mented by gct.

SYNOPSIS
     grestore [ -test-dir _m_a_s_t_e_r__d_i_r_e_c_t_o_r_y ]

DESCRIPTION
     grestore replaces the instrumented source code of a  program
     with its original source. When a file is instrumented, it is
     moved into a subdirectory named gct_backup, and instructions
     for  copying it back are placed in a file called gct-rscript
     in the master directory.

     If the source files are in several directories,  there  will
     be  the  same number of gct_backup directories, but only one
     gct-rscript.

     Example of usage:
          host-1% grestore

     You may get a message that gct-rscript does not  exist  when
     you think it should.  The usual cause of this is as follows:

     1) You run GCT from within your  makefile.   GCT  fails  for
     some reason, such as a syntax error in a file.  The makefile
     halts because of the error, therefore grestore isn't run.

     2) You fix the problem and run make again.  GCT  immediately
     fails   because   you're   trying   to  instrument  already-
     instrumented files.

     3) You run grestore by hand.  Unfortunately, the first thing
     the  makefile  did  was  run  gct-init,  which  removes gct-
     rscript.

     Don't panic.  The previous  version  of  gct-rscript  is  in
     gct-rscript.bk.  All you need to do is type:

     % mv gct-rscript.bk gct-rscript
     % grestore

     Even if gct-rscript.bk is missing for some reason, the  ori-
     ginal  versions  of  the instrumented files are still in the
     gct_backup directories, and they can be copied to their ori-
     ginal locations manually.

     To avoid the problem, make sure you run grestore manually if
     the make exits abnormally.

     grestore does not remove the copies  of  the  files  in  the
     gct_backup  directory.  This wastes space, but can be useful



Sun Release 4.1   Last change: 1 November 1990                  1






GRESTORE(1)              USER COMMANDS                GRESTORE(1)



     if the original copy is accidentally deleted.

OPTIONS
     -test-dir _m_a_s_t_e_r__d_i_r_e_c_t_o_r_y
          If you specified a master directory when you used  gct,
          gct-rscript  is  in  that  directory.  You must use the
          -test-dir option to give grestore the same directory as
          you gave gct.

BUGS
     The restored file's attributes should be  identical  to  the
     original  file's,  save for an updated modification time (to
     force replacement of the instrumented object file  the  next
     time  the  program  is rebuilt).  GCT currently falls short.
     The read-write-execute bits of the mode will  be  the  same,
     but other mode bits are lost.  (It's rare for C source files
     to have the other bits set.)  The file will be owned by  the
     instrumenter, who may not have been the original owner.

SEE ALSO
     gct(1).


































Sun Release 4.1   Last change: 1 November 1990                  2






GSUMMARY(1)              USER COMMANDS                GSUMMARY(1)



NAME
     gsummary - summary report on execution of a program  instru-
     mented by gct.

SYNOPSIS
     gsummary  [  -test-dir  _m_a_s_t_e_r__d_i_r_e_c_t_o_r_y   ]   [   -test-map
     _m_a_p__f_i_l_e__n_a_m_e  ]  [  -test-edit  _m_a_p__f_i_l_e__n_a_m_e  ]  [  -p ] [
     _l_o_g__f_i_l_e__n_a_m_e ]

DESCRIPTION
     gsummary uses the map file, the log file, and the edit  file
     to produce a summary report.

     The gct map file is created during  the  instrumentation  of
     the  source code by gct.  The log file is usually written by
     gct_writelog() during a test run.  The edit file is  created
     by  gedit  and is used to suppress the display of conditions
     that are judged impossible (or too difficult) to satisfy.

     The map file and edit file have default names  that  can  be
     overridden  with options.  The log file is given as the sin-
     gle argument.  If no log file is given, gsummary reads  from
     standard input.

     The resulting report looks like this:

          ernie-5% gsummary LOG

          BINARY BRANCH INSTRUMENTATION (76 conditions total)
          3 ( 3.95%) not satisfied.
          73 (96.05%) fully satisfied.

          SWITCH INSTRUMENTATION (14 conditions total)
          0 ( 0.00%) not satisfied.
          14 (100.00%) fully satisfied.

          LOOP INSTRUMENTATION (24 conditions total)
          4 (16.67%) not satisfied.
          20 (83.33%) fully satisfied.

          MULTIPLE CONDITION INSTRUMENTATION (38 conditions total)
          2 ( 5.26%) not satisfied.
          36 (94.74%) fully satisfied.

          OPERATOR INSTRUMENTATION (27 conditions total)
          1 ( 3.70%) not satisfied.
          26 (96.30%) fully satisfied.

          SUMMARY OF ALL CONDITION TYPES (179 total)
          10 ( 5.59%) not satisfied.
          169 (94.41%) fully satisfied.




Sun Release 4.1   Last change: 1 November 1990                  1






GSUMMARY(1)              USER COMMANDS                GSUMMARY(1)



     This report shows that three branch  directions  were  never
     taken,  all  cases (including default) were taken, four loop
     execution conditions were not satisfied, and so on.

     In cases where the user suppressed  some  conditions,  using
     the _g_c_t-_e_d_i_t file, the contribution of the suppressed condi-
     tions will be given in brackets, like this:

     BINARY BRANCH INSTRUMENTATION (76 conditions total)
     0 ( 0.00%) not satisfied.
     76 (100.00%) fully satisfied. [2 ( 2.63%) suppressed]

     In this case, two branch directions were manually suppressed
     (presumably because they are impossible to exercise).

     gsummary will accept  partial  mapfiles  and  mapfiles  with
     gaps.  This can be used to find summary information for par-
     ticular files  when  a  large  multi-file  system  has  been
     instrumented.  Here is an example:

          % grep "myfile.c" gct-map > /tmp/gct-map
          % gsummary -test-map /tmp/gct-map LOG


     An error message is printed if the  logfile  contains  fewer
     entries  than the mapfile.  A warning is printed if the map-
     file has fewer entries than the logfile, and all the missing
     entries  are at the end of the mapfile.  This guards against
     using the wrong mapfile with a logfile.  Since  editing  the
     mapfile is allowed, the message is only a warning.  Mapfiles
     shorter because of gaps before the end are assumed  to  have
     been edited, so no warning is printed.

OPTIONS
     -p   In cases  like  branches,  loops,  and  multi-condition
          instrumentation,  gsummary  can  treat  several related
          coverage conditions as single conditions.  For example,
          two  separate requirements -- that a branch be taken in
          the true direction, and that it be taken in  the  false
          direction  --  are  merged  into one which can be "par-
          tially" satisfied.  This  is  provided  for  historical
          reasons, but its use is discouraged.

     -test-dir _m_a_s_t_e_r__d_i_r_e_c_t_o_r_y
          The _m_a_s_t_e_r _d_i_r_e_c_t_o_r_y is  the  directory  where  all  of
          gct's  data  files  are  kept.   By  default, it is the
          current directory.  This option changes the default.

     -test-map _m_a_p__f_i_l_e__n_a_m_e
          By default, information about  coverage  conditions  is
          found  in  the  file "gct-map" in the master directory.
          This option changes the default.  Unless  the  argument



Sun Release 4.1   Last change: 1 November 1990                  2






GSUMMARY(1)              USER COMMANDS                GSUMMARY(1)



          is  an absolute pathname, it is taken to be relative to
          the master directory.

     -test-edit _e_d_i_t__f_i_l_e__n_a_m_e
          The edit file tells gsummary not to report  on  certain
          coverage  conditions.   Its  name is, by default, "gct-
          edit".  This option changes the  default.   Unless  the
          argument  is  an  absolute  pathname, it is taken to be
          relative to the master directory.

SEE ALSO
     gct(1), greport(1).











































Version 1.36      Last change: 1 November 1990                  3






GCC(1)                   USER COMMANDS                     GCC(1)



NAME
     gcc - GNU project C Compiler

SYNOPSIS
     gcc [ options ] files

WARNING
     This man page is an extract of the documentation of the  _G_N_U
     _C _c_o_m_p_i_l_e_r and is limited to the meaning of the options.  It
     is updated only occasionally, because the GNU  project  does
     not  use  nroff.  For complete, current documentation, refer
     to the Info file gcc or the DVI file gcc.dvi which are  made
     from the Texinfo source file gcc.texinfo.

DESCRIPTION
     The _G_N_U _C _c_o_m_p_i_l_e_r uses a command syntax much like the  Unix
     C  compiler.  The _g_c_c program accepts options and file names
     as operands.  Multiple  single-letter  options  may  _n_o_t  be
     grouped:  -dr is very different from -d -r.  When you invoke
     GNU CC, it normally does preprocessing, compilation,  assem-
     bly  and linking.  File names which end in .c are taken as C
     source to be preprocessed and compiled; file names ending in
     .i are taken as preprocessor output to be compiled; compiler
     output files plus any input files with names  ending  in  .s
     are  assembled;  then  the  resulting object files, plus any
     other input files, are linked together to produce an execut-
     able.   Command options allow you to stop this process at an
     intermediate stage.  For example, the -c option says not  to
     run  the  linker.   Then the output consists of object files
     output by the assembler.  Other command options  are  passed
     on  to  one  stage  of processing.  Some options control the
     preprocessor and others  the  compiler  itself.   Yet  other
     options  control  the  assembler  and  linker; these are not
     documented here, but you rarely need to use any of them.

OPTIONS
     Here are the options to control the overall compilation pro-
     cess,  including  those that say whether to link, whether to
     assemble, and so on.

     -o _f_i_l_e
          Place output in file _f_i_l_e.  This applies regardless  to
          whatever  sort  of output is being produced, whether it
          be an executable file, an  object  file,  an  assembler
          file or preprocessed C code.

          If -o is not specified, the default is to put  an  exe-
          cutable  file  in  a.out,  the  object file _s_o_u_r_c_e.c in
          _s_o_u_r_c_e.o, an assembler file in  _s_o_u_r_c_e.s,  and  prepro-
          cessed C on standard output.

     -c   Compile or assemble the source files, but do not  link.



Version 1.36        Last change: 18 June 1989                   1






GCC(1)                   USER COMMANDS                     GCC(1)



          Produce object files with names made by replacing .c or
          .s with .o at the end of  the  input  file  names.   Do
          nothing at all for object files specified as input.

     -S   Compile into assembler code but do not  assemble.   The
          assembler output file name is made by replacing .c with
          .s at the end of the input file name.   Do  nothing  at
          all  for  assembler source files or object files speci-
          fied as input.

     -E   Run only the C  preprocessor.   Preprocess  all  the  C
          source  files specified and output the results to stan-
          dard output.

     -v   Compiler driver program prints the commands it executes
          as it runs the preprocessor, compiler proper, assembler
          and linker.  Some of these are directed to print  their
          own version numbers.

     -pipe
          Use pipes rather than temporary files for communication
          between  the various stages of compilation.  This fails
          to work on some systems where the assembler  is  unable
          to read from a pipe; but the GNU assembler has no trou-
          ble.

     -B_p_r_e_f_i_x
          Compiler driver program tries _p_r_e_f_i_x as  a  prefix  for
          each  program it tries to run.  These programs are _c_p_p,
          _c_c_1, _a_s and _l_d.

          For each subprogram to  be  run,  the  compiler  driver
          first tries the -B prefix, if any.  If that name is not
          found, or if -B was not specified, the driver tries two
          standard   prefixes,   which   are   /usr/lib/gcc-  and
          /usr/local/lib/gcc-.  If neither of those results in  a
          file name that is found, the unmodified program name is
          searched for using the directories  specified  in  your
          PATH environment variable.

          The run-time support file gnulib is also  searched  for
          using  the  -B  prefix,  if needed.  If it is not found
          there, the two standard prefixes above are  tried,  and
          that is all.  The file is left out of the link if it is
          not found by those means.  Most of the  time,  on  most
          machines, you can do without it.

          You can get a similar result from the environment vari-
          able  GCC_EXEC_PREFIX;  if  it is defined, its value is
          used as a prefix in the  same  way.   If  both  the  -B
          option  and  the  GCC_EXEC_PREFIX variable are present,
          the  -B  option  is  used  first  and  the  environment



Version 1.36        Last change: 18 June 1989                   2






GCC(1)                   USER COMMANDS                     GCC(1)



          variable value second.

     -b_p_r_e_f_i_x
          The argument _p_r_e_f_i_x is used as a second prefix for  the
          compiler  executables  and  libraries.   This prefix is
          optional: the compiler tries each file first  with  it,
          then without it.  This prefix follows the prefix speci-
          fied with -B or the default prefixes.

          Thus, -bvax- -Bcc/ in the presence of environment vari-
          able GCC_EXEC_PREFIX with definition /u/foo/ causes GNU
          CC to try the following file names for the preprocessor
          executable:

               cc/vax-cpp
               cc/cpp
               /u/foo/vax-cpp
               /u/foo/cpp
               /usr/local/lib/gcc-vax-cpp
               /usr/local/lib/gcc-cpp
               /usr/lib/gcc-vax-cpp
               /usr/lib/gcc-cpp These options control the details
          of C compilation itself.

     -ansi
          Support all ANSI standard C programs.

          This turns off certain  features  of  GNU  C  that  are
          incompatible  with  ANSI C, such as the asm, inline and
          typeof keywords, and predefined macros such as unix and
          vax that identify the type of system you are using.  It
          also enables the undesirable and rarely used ANSI  tri-
          graph feature.

          The  alternate   keywords   __asm__,   __inline__   and
          __typeof__  continue  to work despite -ansi.  You would
          not want to use them in an ANSI C program,  of  course,
          but it useful to put them in header files that might be
          included in compilations done  with  -ansi.   Alternate
          predefined macros such as __unix__ and __vax__ are also
          available, with or without -ansi.

          The -ansi option does not cause non-ANSI programs to be
          rejected gratuitously.  For that, -pedantic is required
          in addition to -ansi.

          The macro __STRICT_ANSI__ is predefined when the  -ansi
          option  is  used.   Some  header  files may notice this
          macro and refrain from declaring certain  functions  or
          defining  certain macros that the ANSI standard doesn't
          call for; this is to avoid interfering  with  any  pro-
          grams that might use these names for other things.



Version 1.36        Last change: 18 June 1989                   3






GCC(1)                   USER COMMANDS                     GCC(1)



     -traditional
          Attempt to support some aspects of traditional  C  com-
          pilers.  Specifically:

        * All extern declarations take effect  globally  even  if
          they are written inside of a function definition.  This
          includes implicit declarations of functions.

        * The keywords typeof, inline, signed, const and volatile
          are not recognized.

        * Comparisons between pointers and  integers  are  always
          allowed.

        * Integer types unsigned short and unsigned char  promote
          to unsigned int.

        * Out-of-range floating point literals are not an error.

        * All  automatic  variables  not  declared  register  are
          preserved  by  _l_o_n_g_j_m_p(3C).   Ordinarily, GNU C follows
          ANSI C: automatic variables not declared  volatile  may
          be clobbered.

        * In the preprocessor, comments  convert  to  nothing  at
          all,  rather  than to a space.  This allows traditional
          token concatenation.

        * In the preprocessor,  macro  arguments  are  recognized
          within  string  constants  in  a  macro definition (and
          their values are stringified, though without additional
          quote  marks, when they appear in such a context).  The
          preprocessor always considers a string constant to  end
          at a newline.

        * The predefined macro __STDC__ is not defined  when  you
          use -traditional, but __GNUC__ is (since the GNU exten-
          sions which __GNUC__  indicates  are  not  affected  by
          -traditional).   If you need to write header files that
          work differently depending on whether  -traditional  is
          in  use, by testing both of these predefined macros you
          can distinguish four situations: GNU C, traditional GNU
          C, other ANSI C compilers, and other old C compilers.

     -O   Optimize.  Optimizing compilation takes  somewhat  more
          time, and a lot more memory for a large function.

          Without -O, the compiler's goal is to reduce  the  cost
          of  compilation  and  to  make  debugging  produce  the
          expected results.  Statements are independent:  if  you
          stop  the program with a breakpoint between statements,
          you can then assign a new  value  to  any  variable  or



Version 1.36        Last change: 18 June 1989                   4






GCC(1)                   USER COMMANDS                     GCC(1)



          change  the  program  counter to any other statement in
          the function and get  exactly  the  results  you  would
          expect from the source code.

          Without -O, only variables declared register are  allo-
          cated  in  registers.  The resulting compiled code is a
          little worse than produced by PCC without -O.

          With -O, the compiler tries to  reduce  code  size  and
          execution time.

          Some of the -f options described  below  turn  specific
          kinds of optimization on or off.

     -g   Produce debugging information in the operating system's
          native format (for DBX or SDB).  GDB also can work with
          this debugging information.

          Unlike most other C compilers, GNU CC allows you to use
          -g  with -O.  The shortcuts taken by optimized code may
          occasionally produce surprising results: some variables
          you  declared may not exist at all; flow of control may
          briefly move where you did not expect it;  some  state-
          ments may not be executed because they compute constant
          results or their values  were  already  at  hand;  some
          statements may execute in different places because they
          were moved out of loops.  Nevertheless it proves possi-
          ble  to  debug optimized output.  This makes it reason-
          able to use the optimizer for programs that might  have
          bugs.

     -gg  Produce debugging  information  in  GDB's  own  format.
          This  requires the GNU assembler and linker in order to
          work.

          This feature  will  probably  be  eliminated.   It  was
          intended to enable GDB to read the symbol table faster,
          but it doesn't result in enough  of  a  speedup  to  be
          worth  the larger object files and executables.  We are
          working on other ways of making GDB start even  faster,
          which  work  with  DBX format debugging information and
          could be made to work with SDB format.

     -w   Inhibit all warning messages.

     -W   Print extra warning messages for these events:

        * An automatic variable is used without first being  ini-
          tialized.

          These warnings are possible only in optimizing compila-
          tion,  because  they require data flow information that



Version 1.36        Last change: 18 June 1989                   5






GCC(1)                   USER COMMANDS                     GCC(1)



          is computed only when optimizing.  If you don't specify
          -O, you simply won't get these warnings.

          These warnings occur only for variables that are candi-
          dates  for register allocation.  Therefore, they do not
          occur for a variable  that  is  declared  volatile,  or
          whose  address is taken, or whose size is other than 1,
          2, 4 or 8 bytes.  Also, they do not  occur  for  struc-
          tures,  unions  or arrays, even when they are in regis-
          ters.

          Note that there may be no warning about a variable that
          is  used  only  to compute a value that itself is never
          used, because such computations may be deleted by  data
          flow analysis before the warnings are printed.

          These warnings are made optional because GNU CC is  not
          smart  enough to see all the reasons why the code might
          be correct despite appearing to have an error.  Here is
          one example of how this can happen:

               {
                 int x;
                 switch (y)
                   {
                   case 1: x = 1;
                     break;
                   case 2: x = 4;
                     break;
                   case 3: x = 5;
                   }
                 foo (x);
               }

          If the value of _y is always 1, 2 or 3, then _x is always
          initialized,  but  GNU  CC  doesn't know this.  Here is
          another common case:

               {
                 int save_y;
                 if (change_y) save_y = y, y = new_y;
                 ...
                 if (change_y) y = save_y;
               }

          This has no bug because _s_a_v_e__y is used only  if  it  is
          set.

          Some spurious warnings can be avoided if you declare as
          volatile all the functions you use that never return.

        * A nonvolatile automatic variable might be changed by  a



Version 1.36        Last change: 18 June 1989                   6






GCC(1)                   USER COMMANDS                     GCC(1)



          call to _l_o_n_g_j_m_p(3C).  These warnings as well are possi-
          ble only in optimizing compilation.

          The compiler sees only the  calls  to  _s_e_t_j_m_p(3C).   It
          cannot  know where _l_o_n_g_j_m_p(3C) will be called; in fact,
          a signal handler could call it  at  any  point  in  the
          code.   As  a  result,  you may get a warning even when
          there is in fact no problem because _l_o_n_g_j_m_p(3C)  cannot
          in  fact  be  called  at  the place which would cause a
          problem.

        * A function can return either with or without  a  value.
          (Falling off the end of the function body is considered
          returning without a value.) For example, this  function
          would evoke such a warning:

               foo (a)
               {
                 if (a > 0)
                   return a;
               }

          Spurious warnings can occur because  GNU  CC  does  not
          realize that certain functions (including _a_b_o_r_t(3C) and
          _l_o_n_g_j_m_p(3C)) will never return.

        * An expression-statement contains no side effects.

          In the  future,  other  useful  warnings  may  also  be
          enabled by this option.

     -Wimplicit
          Warn whenever a function is implicitly declared.

     -Wreturn-type
          Warn whenever a function is defined with a  return-type
          that  defaults  to  int.   Also  warn  about any return
          statement with no  return-value  in  a  function  whose
          return-type is not void.

     -Wunused
          Warn whenever a local variable is unused aside from its
          declaration, and whenever a function is declared static
          but never defined.

     -Wswitch
          Warn whenever  a  switch  statement  has  an  index  of
          enumeral  type  and lacks a case for one or more of the
          named codes of that enumeration.  (The  presence  of  a
          default  label prevents this warning.) case labels out-
          side the enumeration range also provoke  warnings  when
          this option is used.



Version 1.36        Last change: 18 June 1989                   7






GCC(1)                   USER COMMANDS                     GCC(1)



     -Wcomment
          Warn whenever a comment-start sequence /* appears in  a
          comment.

     -Wtrigraphs
          Warn if any trigraphs are  encountered  (assuming  they
          are enabled).

     -Wall
          All of the above -W options combined.   These  are  all
          the  options  which  pertain  to  usage  that we do not
          recommend and that we believe is always easy to  avoid,
          even in conjunction with macros.

          The other -W...  options below are not implied by -Wall
          because  certain  kinds  of  useful  macros  are almost
          impossible to write without causing those warnings.

     -Wshadow
          Warn whenever a local variable  shadows  another  local
          variable.

     -Wid-clash-_l_e_n
          Warn whenever two distinct  identifiers  match  in  the
          first _l_e_n characters.  This may help you prepare a pro-
          gram that will compile with  certain  obsolete,  brain-
          damaged compilers.

     -Wpointer-arith
          Warn about anything that depends on the size of a func-
          tion type or of void.  GNU C assigns these types a size
          of 1, for  convenience  in  calculations  with  void  *
          pointers and pointers to functions.

     -Wcast-qual
          Warn whenever a pointer is cast so as to remove a  type
          qualifier from the target type.  For example, warn if a
          const char * is cast to an ordinary char *.

     -Wwrite-strings
          Give string constants the type  const  char[_l_e_n_g_t_h]  so
          that copying the address of one into a non-const char *
          pointer will get a warning.  These warnings  will  help
          you  find  at  compile  time code that can try to write
          into a string constant, but only if you have been  very
          careful  about  using  const in declarations and proto-
          types.  Otherwise, it will just be a nuisance; this  is
          why we did not make -Wall request these warnings.

     -p   Generate extra code to write profile information  suit-
          able for the analysis program _p_r_o_f(1).




Version 1.36        Last change: 18 June 1989                   8






GCC(1)                   USER COMMANDS                     GCC(1)



     -pg  Generate extra code to write profile information  suit-
          able for the analysis program _g_p_r_o_f(1).

     -a   Generate extra code to write  profile  information  for
          basic   blocks,   suitable  for  the  analysis  program
          _t_c_o_v(1).  Eventually GNU _g_p_r_o_f(1) should be extended to
          process this data.

     -l_l_i_b_r_a_r_y
          Search a standard list of  directories  for  a  library
          named   _l_i_b_r_a_r_y,   which   is  actually  a  file  named
          lib_l_i_b_r_a_r_y.a.  The linker uses this file as if  it  had
          been specified precisely by name.

          The directories searched include several standard  sys-
          tem directories plus any that you specify with -L.

          Normally the files found this way are  library  files--
          archive  files  whose  members  are  object files.  The
          linker handles an archive file by scanning  through  it
          for  members which define symbols that have so far been
          referenced but not defined.  But if the  file  that  is
          found  is  an ordinary object file, it is linked in the
          usual fashion.  The only difference between using an -l
          option  and  specifying a file name is that -l searches
          several directories.

     -L_d_i_r
          Add directory _d_i_r to the  list  of  directories  to  be
          searched for -l.

     -nostdlib
          Don't use the standard  system  libraries  and  startup
          files  when  linking.  Only the files you specify (plus
          gnulib) will be passed to the linker.

     -m_m_a_c_h_i_n_e_s_p_e_c
          Machine-dependent option specifying something about the
          type  of  target machine.  These options are defined by
          the macro TARGET_SWITCHES in the  machine  description.
          The  default  for  the  options is also defined by that
          macro, which enables you to change the defaults.

          These are the -m options defined in the  68000  machine
          description:

          -m68020
          -mc68020
               Generate output for a 68020 (rather than a 68000).
               This  is  the  default  if  you use the unmodified
               sources.




Version 1.36        Last change: 18 June 1989                   9






GCC(1)                   USER COMMANDS                     GCC(1)



          -m68000
          -mc68000
               Generate output for a 68000 (rather than a 68020).

          -m68881
               Generate output containing 68881 instructions  for
               floating  point.   This  is the default if you use
               the unmodified sources.

          -mfpa
               Generate output containing  Sun  FPA  instructions
               for floating point.

          -msoft-float
               Generate  output  containing  library  calls   for
               floating point.

          -mshort
               Consider type int to be 16 bits wide,  like  short
               int.

          -mnobitfield
               Do not use the  bit-field  instructions.   -m68000
               implies -mnobitfield.

          -mbitfield
               Do  use  the  bit-field   instructions.    -m68020
               implies  -mbitfield.   This  is the default if you
               use the unmodified sources.

          -mrtd
               Use a different  function-calling  convention,  in
               which  functions that take a fixed number of argu-
               ments return with the rtd instruction, which  pops
               their  arguments  while returning.  This saves one
               instruction in the caller since there is  no  need
               to pop the arguments there.

               This calling convention is incompatible  with  the
               one normally used on Unix, so you cannot use it if
               you need to call libraries compiled with the  Unix
               compiler.

               Also, you must provide function prototypes for all
               functions  that take variable numbers of arguments
               (including printf(3S)); otherwise  incorrect  code
               will be generated for calls to those functions.

               In addition, seriously incorrect code will  result
               if  you  call  a function with too many arguments.
               (Normally,   extra   arguments   are    harmlessly
               ignored.)



Version 1.36        Last change: 18 June 1989                  10






GCC(1)                   USER COMMANDS                     GCC(1)



               The rtd instruction is supported by the 68010  and
               68020 processors, but not by the 68000.

          These  -m  options  are  defined  in  the  Vax  machine
          description:

          -munix
               Do not output certain  jump  instructions  (aobleq
               and  so  on)  that  the Unix assembler for the Vax
               cannot handle across long ranges.

          -mgnu
               Do output those jump instructions, on the  assump-
               tion  that  you  will assemble with the GNU assem-
               bler.

          -mg
               Output code for g-format  floating  point  numbers
               instead of d-format.

          These -m switches are supported on the Sparc:

          -mfpu
               Generate output containing floating point instruc-
               tions.  This is the default if you use the unmodi-
               fied sources.

          -msoft-float
               Generate  output  containing  library  calls   for
               floating point.

          -mno-epilogue
               Generate separate return instructions  for  return
               statements.   This  has both advantages and disad-
               vantages; I don't recall what they are.

          These -m options are  defined  in  the  Convex  machine
          description:

          -mc1
               Generate output for a C1.   This  is  the  default
               when the compiler is configured for a C1.

          -mc2
               Generate output for a C2.   This  is  the  default
               when the compiler is configured for a C2.

          -margcount
               Generate code which puts an argument count in  the
               word  preceding each argument list.  Some nonport-
               able Convex  and  Vax  programs  need  this  word.
               (Debuggers  don't;  this  info  is  in  the symbol



Version 1.36        Last change: 18 June 1989                  11






GCC(1)                   USER COMMANDS                     GCC(1)



               table.)

          -mnoargcount
               Omit the argument count word.  This is the default
               if you use the unmodified sources.

     -f_f_l_a_g
          Specify machine-independent  flags.   Most  flags  have
          both  positive and negative forms; the negative form of
          -ffoo would be -fno-foo.  In the table below, only  one
          of  the  forms  is  listed--the  one  which  is not the
          default.  You can figure out the other form  by  either
          removing no- or adding it.

     -fpcc-struct-return
          Use the same convention for returning struct and  union
          values  that  is  used  by the usual C compiler on your
          system.  This convention is less  efficient  for  small
          structures,  and  on many machines it fails to be reen-
          trant; but it has the advantage of allowing intercalla-
          bility between GCC-compiled code and PCC-compiled code.

     -ffloat-store
          Do not store  floating-point  variables  in  registers.
          This  prevents undesirable excess precision on machines
          such as the 68000 where the floating registers (of  the
          68881) keep more precision than a double is supposed to
          have.

          For most programs, the excess precision does only good,
          but  a  few  programs rely on the precise definition of
          IEEE floating point.  Use -ffloat-store for  such  pro-
          grams.

     -fno-asm
          Do not recognize asm, inline or typeof  as  a  keyword.
          These  words  may then be used as identifiers.  You can
          use __asm__, __inline__ and __typeof__ instead.

     -fno-defer-pop
          Always pop the arguments to each function call as  soon
          as  that function returns.  Normally the compiler (when
          optimizing) lets arguments accumulate on the stack  for
          several function calls and pops them all at once.

     -fstrength-reduce
          Perform the optimizations of  loop  strength  reduction
          and elimination of iteration variables.

     -fcombine-regs
          Allow the combine pass to combine an  instruction  that
          copies  one register into another.  This might or might



Version 1.36        Last change: 18 June 1989                  12






GCC(1)                   USER COMMANDS                     GCC(1)



          not produce better code when used in addition to -O.  I
          am  interested  in  hearing  about  the difference this
          makes.

     -fforce-mem
          Force memory  operands  to  be  copied  into  registers
          before  doing  arithmetic  on  them.   This may produce
          better code by making all memory  references  potential
          common subexpressions.  When they are not common subex-
          pressions, instruction combination should eliminate the
          separate  register-load.   I  am  interested in hearing
          about the difference this makes.

     -fforce-addr
          Force memory address constants to be copied into regis-
          ters before doing arithmetic on them.  This may produce
          better code just as -fforce-mem may.  I  am  interested
          in hearing about the difference this makes.

     -fomit-frame-pointer
          Don't keep the frame pointer in a  register  for  func-
          tions  that  don't  need one.  This avoids the instruc-
          tions to save, set up and restore  frame  pointers;  it
          also  makes  an  extra register available in many func-
          tions.  It also makes debugging impossible.

          On some machines, such as the Vax,  this  flag  has  no
          effect, because the standard calling sequence automati-
          cally handles the frame pointer and nothing is saved by
          pretending  it  doesn't exist.  The machine-description
          macro FRAME_POINTER_REQUIRED controls whether a  target
          machine supports this flag.

     -finline-functions
          Integrate all simple functions into their callers.  The
          compiler heuristically decides which functions are sim-
          ple enough to be worth integrating in this way.

          If all calls to a given function  are  integrated,  and
          the  function  is declared static, then the function is
          normally not output as assembler code in its own right.

     -fcaller-saves
          Enable values to be allocated in registers that will be
          clobbered by function calls, by emitting extra instruc-
          tions to save and restore  the  registers  around  such
          calls.   Such  allocation is done only when it seems to
          result in better code than would otherwise be produced.

          This option is enabled by default on certain  machines,
          usually those which have no call-preserved registers to
          use instead.



Version 1.36        Last change: 18 June 1989                  13






GCC(1)                   USER COMMANDS                     GCC(1)



     -fkeep-inline-functions
          Even if all calls to a given function  are  integrated,
          and  the function is declared static, nevertheless out-
          put a separate run-time callable version of  the  func-
          tion.

     -fwritable-strings
          Store string constants in the writable data segment and
          don't  uniquize  them.   This is for compatibility with
          old programs which assume they can  write  into  string
          constants.  Writing into string constants is a very bad
          idea; constants should be constant.

     -fcond-mismatch
          Allow conditional expressions with mismatched types  in
          the  second  and third arguments.  The value of such an
          expression is void.

     -fno-function-cse
          Do not put function addresses in registers;  make  each
          instruction  that calls a constant function contain the
          function's address explicitly.

          This option results in less efficient  code,  but  some
          strange  hacks  that  alter the assembler output may be
          confused  by  the  optimizations  performed  when  this
          option is not used.

     -fvolatile
          Consider all memory references through pointers  to  be
          volatile.

     -fshared-data
          Requests that the data and non-const variables of  this
          compilation  be  shared  data rather than private data.
          The distinction makes sense only on  certain  operating
          systems,  where shared data is shared between processes
          running the same program, while private data exists  in
          one copy per process.

     -funsigned-char
          Let the type char be the unsigned, like unsigned char.

          Each kind of machine has a default for what char should
          be.  It is either like unsigned char by default or like
          signed char by default.   (Actually,  at  present,  the
          default is always signed.)

          The type char is always a  distinct  type  from  either
          signed  char or unsigned char, even though its behavior
          is always just like one of those two.




Version 1.36        Last change: 18 June 1989                  14






GCC(1)                   USER COMMANDS                     GCC(1)



          Note that this is equivalent to -fno-signed-char, which
          is the negative form of -fsigned-char.

     -fsigned-char
          Let the type char be signed, like signed char.

          Note that this  is  equivalent  to  -fno-unsigned-char,
          which is the negative form of -funsigned-char.

     -fdelayed-branch
          If supported for the target machine, attempt to reorder
          instructions  to  exploit  instruction  slots available
          after delayed branch instructions.

     -ffixed-_r_e_g
          Treat the register named _r_e_g as a fixed register;  gen-
          erated code should never refer to it (except perhaps as
          a stack pointer, frame pointer or in some  other  fixed
          role).

          _r_e_g must be the name of a register.  The register names
          accepted  are  machine-specific  and are defined in the
          REGISTER_NAMES macro in the machine  description  macro
          file.

          This flag does not have a  negative  form,  because  it
          specifies a three-way choice.

     -fcall-used-_r_e_g
          Treat the register named _r_e_g as an allocatable register
          that  is  clobbered by function calls.  It may be allo-
          cated for temporaries or variables  that  do  not  live
          across  a  call.   Functions compiled this way will not
          save and restore the register REG.

          Use of this flag for a register that has a  fixed  per-
          vasive  role  in the machine's execution model, such as
          the stack pointer or frame pointer, will produce disas-
          trous results.

          This flag does not have a  negative  form,  because  it
          specifies a three-way choice.

     -fcall-saved-_r_e_g
          Treat the register named _r_e_g as an allocatable register
          saved  by functions.  It may be allocated even for tem-
          poraries or variables that live across a  call.   Func-
          tions  compiled  this  way  will  save  and restore the
          register _r_e_g if they use it.

          Use of this flag for a register that has a  fixed  per-
          vasive  role  in the machine's execution model, such as



Version 1.36        Last change: 18 June 1989                  15






GCC(1)                   USER COMMANDS                     GCC(1)



          the stack pointer or frame pointer, will produce disas-
          trous results.

          A different sort of disaster will result from  the  use
          of  this  flag  for a register in which function values
          may be returned.

          This flag does not have a  negative  form,  because  it
          specifies a three-way choice.

     -d_l_e_t_t_e_r_s
          Says to make debugging  dumps  at  times  specified  by
          _l_e_t_t_e_r_s.  Here are the possible letters:

          r
               Dump after RTL generation.
          j
               Dump after first jump optimization.
          J
               Dump after last jump optimization.
          s
               Dump after CSE (including  the  jump  optimization
               that sometimes follows CSE).
          L
               Dump after loop optimization.
          f
               Dump after flow analysis.
          c
               Dump after instruction combination.
          l
               Dump after local register allocation.
          g
               Dump after global register allocation.
          d
               Dump after delayed branch scheduling.
          m
               Print statistics on memory usage, at  the  end  of
               the run.

     -pedantic
          Issue all the warnings demanded by strict ANSI standard
          C; reject all programs that use forbidden extensions.

          Valid ANSI standard C programs should compile  properly
          with  or  without  this  option (though a rare few will
          require -ansi).  However, without this option,  certain
          GNU extensions and traditional C features are supported
          as well.  With this option, they are  rejected.   There
          is  no  reason  to  use  this option; it exists only to
          satisfy pedants.

          -pedantic does not cause warning messages  for  use  of



Version 1.36        Last change: 18 June 1989                  16






GCC(1)                   USER COMMANDS                     GCC(1)



          the  alternate  keywords whose names begin and end with
          __.

     -static
          On Suns running version 4, this prevents  linking  with
          the  shared libraries.  (-g has the same effect.) These
          options control the C preprocessor,  which  is  run  on
          each  C  source file before actual compilation.  If you
          use the `-E' option, nothing is done except  C  prepro-
          cessing.    Some  of  these  options  make  sense  only
          together with `-E' because  they  request  preprocessor
          output that is not suitable for actual compilation.

     -C   Tell the preprocessor not to  discard  comments.   Used
          with the -E option.

     -I_d_i_r
          Search directory _d_i_r for include files.

     -I-  Any directories specified with -I  options  before  the
          -I-  option  are searched only for the case of #include
          "_f_i_l_e"; they are not searched for #include <_f_i_l_e>.

          If additional directories are specified with -I options
          after  the  -I-, these directories are searched for all
          #include directives.  (Ordinarily  _a_l_l  -I  directories
          are used this way.)

          In addition, the -I- option inhibits  the  use  of  the
          current  directory  as  the  first search directory for
          #include "_f_i_l_e".  Therefore, the current  directory  is
          searched  only  if it is requested explicitly with -I..
          Specifying both -I- and -I. allows you to control  pre-
          cisely   which  directories  are  searched  before  the
          current one and which are searched after.

     -nostdinc
          Do not  search  the  standard  system  directories  for
          header  files.  Only the directories you have specified
          with  -I  options  (and  the  current   directory,   if
          appropriate) are searched.

          Between -nostdinc and -I-, you can eliminate all direc-
          tories from the search path except those you specify.

     -M   Tell the preprocessor to output  a  rule  suitable  for
          make(_1)  describing  the  dependencies  of  each source
          file.  For each source file, the  preprocessor  outputs
          one  make-rule whose target is the object file name for
          that source file and whose  dependencies  are  all  the
          files  #included in it.  This rule may be a single line
          or may be continued with \-newline if it is long.



Version 1.36        Last change: 18 June 1989                  17






GCC(1)                   USER COMMANDS                     GCC(1)



          -M implies -E.

     -MM  Like -M but the output mentions  only  the  user-header
          files  included  with  #include  "_f_i_l_e".  System header
          files included with #include <_f_i_l_e> are omitted.

          -MM implies -E.

     -D_m_a_c_r_o
          Define macro _m_a_c_r_o with the empty string as its defini-
          tion.

     -D_m_a_c_r_o=_d_e_f_n
          Define macro _m_a_c_r_o as _d_e_f_n.

     -U_m_a_c_r_o
          Undefine macro _m_a_c_r_o.

     -trigraphs
          Support ANSI C trigraphs.  You don't want to know about
          this  brain-damage.   The  -ansi  option  also has this
          effect.

FILES
     file.c             C source file
     file.s             assembly language file
     file.o             object file
     a.out              link edited output
     /tmp/cc*           temporary files
     _L_I_B_D_I_R/gcc-cpp     preprocessor
     _L_I_B_D_I_R/gcc-cc1     compiler
     _L_I_B_D_I_R/gcc-gnulib  library needed by GCC on some machines
     /lib/crt[01n].o    start-up routine
     /lib/libc.a        standard C library, see _i_n_t_r_o(3)
     /usr/include       standard directory for #include files
     _L_I_B_D_I_R/gcc-include standard gcc directory for #include files

     _L_I_B_D_I_R is usually /usr/local/lib.

SEE ALSO
     as(1), ld(1), adb(1), dbx(1), sdb(1).

BUGS
     Bugs should be reported  to  bug-gcc@prep.ai.mit.edu.   Bugs
     tend  actually to be fixed if they can be isolated, so it is
     in your interest to report them in such a way that they  can
     be easily reproduced.

COPYING
     Copyright (c) 1988 Free Software Foundation,  Inc.   Permis-
     sion  is  granted  to make and distribute verbatim copies of
     this  manual  provided  the  copyright   notice   and   this



Version 1.36        Last change: 18 June 1989                  18






GCC(1)                   USER COMMANDS                     GCC(1)



     permission  notice  are preserved on all copies.  Permission
     is granted to copy and distribute modified versions of  this
     manual  under  the conditions for verbatim copying, provided
     that the entire resulting derived work is distributed  under
     the  terms  of  a  permission  notice identical to this one.
     Permission is granted to copy and distribute translations of
     this  manual  into  another language, under the above condi-
     tions for modified versions,  except  that  this  permission
     notice  may be included in translations approved by the Free
     Software Foundation instead of in the original English.

AUTHORS
     See the GNU CC Manual for the contributors to GNU CC.










































Version 1.36        Last change: 18 June 1989                  19



