Unix command to insert source line print into executable

Rick Landsman rlandsma at bbn.com
Wed Nov 21 01:22:00 AEST 1990


I have received numerous requests to provide the answer when I
find my missing tool that inserts "C" source statements as printf
output into the executable for debugging. Turned out it is a
unix command, "ctrace", available on most unix versions. Below
is the man page for those (and others) that requested this info.


Thanks to Bob Seiler at BBN for helping me solve the puzzle.
regards rick - rlandsman at bbn.com



                                                        ctrace(1)



NAME
     ctrace - C program debugger

SYNTAX
     ctrace [_o_p_t_i_o_n_s] [_f_i_l_e]
     ctc [_o_p_t_i_o_n_s] [_f_i_l_e]
     ctcr [_o_p_t_i_o_n_s] [_f_i_l_e]

DESCRIPTION
     The _c_t_r_a_c_e command allows you to follow the execution of a C
     program, statement by statement.  The _c_t_r_a_c_e command reads
     the C program in _f_i_l_e (or from standard input if you do not
     specify _f_i_l_e) and inserts statements to print both the text
     of each executable statement and the values of all variables
     referenced or modified.  It then writes the modified program
     to the standard output.  You must put the output of _c_t_r_a_c_e
     into a temporary file because the _c_c command does not allow
     the use of a pipe.  You then compile and execute this file.

     As each statement in the program executes it is listed at
     the terminal.  The statement is followed by the name and
     value of any variables referenced or modified in the state-
     ment, which is followed by any output from the statement.
     Loops in the trace output are detected and tracing is
     stopped until the loop is exited or a different sequence of
     statements within the loop is executed.  A warning message
     is printed every 1000 times through the loop to help you
     detect infinite loops.

     The trace output goes to the standard output so you can put
     it into a file for examination with an editor or the _t_a_i_l
     command.

     The _c_t_c command is a shell script that prepares the speci-
     fied C program _f_i_l_e for later execution.  The _c_t_c_r command
     is a shell script that both prepares and executes the speci-
     fied C program _f_i_l_e.

OPTIONS
     The only options you will commonly use are:

     -f _f_u_n_c_t_i_o_n_s        Trace only these _f_u_n_c_t_i_o_n_s.

     -v _f_u_n_c_t_i_o_n_s        Trace all but these _f_u_n_c_t_i_o_n_s.

     You may want to add to the default formats for printing
     variables.  Long and pointer variables are always printed as
     signed integers.  Pointers to character arrays are also
     printed as strings if appropriate.  Char, short, and int
     variables are also printed as signed integers and, if
     appropriate, as characters.  Double variables are printed as
     floating point numbers in scientific notation.



                                                                1






ctrace(1)



     You can request that variables be printed in additional for-
     mats, if appropriate, with these options:

     -e                  Floating point

     -o                  Octal

     -u                  Unsigned

     -x                  Hexadecimal

     These options are used only in special circumstances:

     -l _n                Checks _n consecutively executed state-
                         ments for looping trace output, instead
                         of the default of 20.  Use 0 to get all
                         the trace output from loops.

     -P                  Runs the C preprocessor on the input
                         before tracing it.  You can also use the
                         -D, -I, and -U cc(1) preprocessor
                         options.

     -p _s                Changes the trace print functions from
                         the default of "printf(".  For example,
                         "fprintf(stderr," would send the trace
                         to the standard error output.

     -r _f                Uses file _f in place of the _r_u_n_t_i_m_e._c
                         trace function package.  This lets you
                         change the entire print function,
                         instead of just the name and leading
                         arguments.  For further information, see
                         the -p option.

     -s                  Suppresses redundant trace output from
                         simple assignment statements and string
                         copy function calls.  This option can
                         hide a bug caused by use of the = opera-
                         tor in place of the == operator.

     -t _n                Traces _n variables per statement instead
                         of the default of 10 (the maximum number
                         is 20).  The DIAGNOSTICS section
                         explains when to use this option.

EXAMPLES
     Assume the file _l_c._c contains the following C program:







2






                                                        ctrace(1)



           1 #include <stdio.h>
           2 main() /* count lines in input */
           3 {
           4   int c, nl;
           5
           6   nl = 0;
           7   while ((c = getchar()) != EOF)
           8        if (c = '\n')
           9             ++nl;
          10   printf("%d\n", nl);
          11 }


     When you enter the following commands and test data the pro-
     gram is compiled and executed:

          cc lc.c
          a.out
          1
          <CTRL/D>

     The output of the program is the number 2, which is not
     correct because there is only one line in the test data.
     The error in this program is common, but subtle.  When you
     invoke _c_t_r_a_c_e with the following commands:

          ctrace lc.c >temp.c
          cc temp.c
          a.out

     the output is

           2 main()
           6   nl = 0;
               /* nl == 0 */
           7   while ((c = getchar()) != EOF)

     The program is now waiting for input.  If you enter the same
     test data as before, the output is the following:

               /* c == 49 or '1' */
           8        if (c = '\n')
                    /* c == 10 or '\n' */
           9             ++nl;
                         /* nl == 1 */
           7   while ((c = getchar()) != EOF)
               /* c == 10 or '\n' */
           8        if (c = '\n')
                    /* c == 10 or '\n' */
           9             ++nl;
                         /* nl == 2 */
           7   while ((c = getchar()) != EOF)



                                                                3






ctrace(1)



     If you now enter an end of file character <CTRL/D>, the
     final output is the following:

               /* c == -1 */
          10   printf("%d\n", nl);
               /* nl == 2 */2
                return


     Note that the program output printed at the end of the trace
     line for the nl variable.  Also note the return comment
     added by _c_t_r_a_c_e at the end of the trace output.  This shows
     the implicit return at the terminating brace in the func-
     tion.

     The trace output shows that variable c is assigned the value
     "1" in line 7, but in line 8 it has the value "\n".  Once
     your attention is drawn to this _i_f statement, you realize
     that you used the assignment operator (=) in place of the
     equal operator (==).  You can easily miss this error during
     code reading.

EXECUTION-TIME TRACE CONTROL
     The default operation for _c_t_r_a_c_e is to trace the entire pro-
     gram file, unless you use the -f or -v options to trace
     specific functions.  This does not give you statement by
     statement control of the tracing, nor does it let you turn
     the tracing off and on when executing the traced program.

     You can do both of these by adding _c_t_r_o_f_f and _c_t_r_o_n function
     calls to your program to turn the tracing off and on,
     respectively, at execution time.  Thus, you can code arbi-
     trarily complex criteria for trace control with _i_f state-
     ments, and you can even conditionally include this code
     because _c_t_r_a_c_e defines the CTRACE preprocessor variable.
     For example:

          #ifdef CTRACE
               if (c == '!' && i > 1000)
                    ctron();
          #endif

     You can also turn the trace off and on by setting static
     variable tr_ct_ to 0 and 1, respectively.  This is useful if
     you are using a debugger that cannot call these functions
     directly, such as _a_d_b(1).

RESTRICTIONS
     The _c_t_r_a_c_e command does not know about the components of
     aggregates such as structures, unions, and arrays.  It can-
     not choose a format to print all the components of an aggre-
     gate when an assignment is made to the entire aggregate.



4






                                                        ctrace(1)



     The _c_t_r_a_c_e command may choose to print the address of an
     aggregate or use the wrong format (for example, %e for a
     structure with two integer members) when printing the value
     of an aggregate.

     Pointer values are always treated as pointers to character
     strings.

     The loop trace output elimination is done separately for
     each file of a multi-file program.  This can result in func-
     tions called from a loop still being traced, or the elimina-
     tion of trace output from one function in a file until
     another in the same file is called.

WARNINGS
     You get a _c_t_r_a_c_e syntax error if you omit the semicolon at
     the end of the last element declaration in a structure or
     union, just before the right brace (}).  This is optional in
     some C compilers.

     Defining a function with the same name as a system function
     may cause a syntax error if the number of arguments is
     changed.  Use a different name.

     The _c_t_r_a_c_e command assumes that BADMAG is a preprocessor
     macro, and that EOF and NULL are #defined constants.
     Declaring any of these to be variables, for example, "int
     EOF;", will cause a syntax error.

DIAGNOSTICS
     This section contains diagnostic messages from both _c_t_r_a_c_e
     and _c_c, since the traced code often gets some _c_c warning
     messages.  You can get _c_c error messages in some rare cases,
     all of which can be avoided.

     ctrace Diagnostics

     warning: some variables are not traced in this statement

          Only 10 variables are traced in a statement to prevent
          the C compiler "out of tree space; simplify expression"
          error.  Use the -t option to increase this number.



     warning: statement too long to trace

          This statement is over 400 characters long.  Make sure
          that you are using tabs to indent your code, not
          spaces.





                                                                5






ctrace(1)



     cannot handle preprocessor code, use -P option

          This is usually caused by #ifdef/#endif preprocessor
          statements in the middle of a C statement, or by a
          semicolon at the end of a #define preprocessor state-
          ment.



      'if ... else if' sequence too long

          Split the sequence by removing an else from the middle.



     possible syntax error, try -P option

          Use the -P option to preprocess the _c_t_r_a_c_e input, along
          with any appropriate -D, -I, and -U preprocessor
          options.  If you still get the error message, check the
          Warnings section above.



     cc Diagnostics

     warning: floating point not implemented
     warning: illegal combination of pointer and integer
     warning: statement not reached
     warning: sizeof returns 0

          Ignore these messages.



     compiler takes size of function

          See the _c_t_r_a_c_e "possible syntax error" message above.



     yacc stack overflow

          See the _c_t_r_a_c_e "'if ... else if' sequence too long"
          message above.



     out of tree space; simplify expression

          Use the -t option to reduce the number of traced vari-
          ables per statement from the default of 10.  Ignore the



6






                                                        ctrace(1)



          "ctrace: too many variables to trace" warnings you will
          now get.



     redeclaration of signal

          Either correct this declaration of _s_i_g_n_a_l(3), or remove
          it and #include <signal.h>.



     unimplemented structure assignment

          Use _p_c_c instead of _c_c(1).

FILES
     /usr/bin/ctc             preparation shell script
     /usr/bin/ctcr            preparation and run shell script
     /usr/lib/ctrace/runtime.c          run-time trace package

SEE ALSO
     ctype(3), printf(3s), setjmp(3), signal(3), string(3)
































                                                                7





Test Signature



More information about the Comp.lang.c mailing list