ctrace(1) DG/UX 4.30 ctrace(1)
NAME
ctrace - C program debugger
SYNOPSIS
ctrace [ options ] [ file ]
DESCRIPTION
Ctrace lets you follow the execution of a C program,
statement by statement. The effect is similar to executing
a shell procedure with the -x option. Ctrace reads the C
program in file (or from standard input if you omit file),
inserts statements to print the text of each executable
statement and the values of all variables referenced or
modified, and writes the modified program to the standard
output. You must put the output of ctrace into a temporary
file because the cc(1) 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, followed by the name and value of any
variables referenced or modified in the statement, 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 bfs(1) or
tail(1) commands.
Commonly used options are:
-f functions Trace only these functions.
-v functions Trace all but these functions.
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. The options
that print variables in additional formats are:
-o Octal
-x Hexadecimal
-u Unsigned
-e Floating point
Other options for special circumstances are:
-l n Check n consecutively executed statements for looping
Licensed material--property of copyright holder(s) Page 1
ctrace(1) DG/UX 4.30 ctrace(1)
trace output, instead of the default of 20. Use 0 to
get all the trace output from loops.
-s Suppress redundant trace output from simple
assignment statements and string copy function calls.
This option can hide a bug caused by using the =
operator in place of the == operator.
-t n Trace n variables per statement instead of the
default of 10 (the maximum number is 20). The
DIAGNOSTICS section below explains when to use this
option.
-P Run the C preprocessor on the input before tracing
it. You can also use the -D, -I, and -U cc(1)
preprocessor options.
The options that tailor the run-time trace package for the
traced program to run in a non-UNIX system environment are:
-b Use only basic functions in the trace code, that is,
those in ctype(3C), printf(3S), and string(3C).
These functions are usually available even in cross-
compilers for microprocessors. In particular, this
option is needed when the traced program runs under
an operating system that does not have signal(2),
fflush(3S), longjmp(3C), or setjmp(3C).
-p 's' Change the trace print function from the default of
'printf('. For example, 'fprintf(stderr,' would send
the trace to the standard error output.
-r f Use file f in place of the runtime.c trace function
package. This lets you change the entire print
function, instead of just the name and leading
arguments (see the -p option).
EXAMPLE
If the file lc.c contains the following C program:
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 }
Licensed material--property of copyright holder(s) Page 2
ctrace(1) DG/UX 4.30 ctrace(1)
and you enter the following commands and test data:
cc lc.c
a.out
1
(ctrl-d)
the program will be compiled and executed.
The output of the program will be 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.
If you invoke ctrace with these commands:
ctrace lc.c >temp.c
cc temp.c
a.out
the output will be:
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 will be:
/* 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)
If you now enter an end of file character (ctrl-d), the
final output will be:
/* 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
Licensed material--property of copyright holder(s) Page 3
ctrace(1) DG/UX 4.30 ctrace(1)
added by ctrace at the end of the trace output. This
comment shows the implicit return at the terminating brace
in the function.
The trace output shows that variable c is assigned the value
1 in line 7, but `\n' in line 8. Once your attention is
drawn to the if statement in line 8, you will probably
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 ctrace is to trace the entire
program file, unless you use the -f or -v options to trace
specific functions. The default 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 ctroff() and ctron()
function calls to your program to turn the tracing off and
on, respectively, at execution time. Thus, you can code
arbitrarily complex criteria for trace control with if
statements, and you can even conditionally include this code
because ctrace 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 the static
variable tr_ct_ to 0 and 1, respectively.
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.
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
statement.
Licensed material--property of copyright holder(s) Page 4
ctrace(1) DG/UX 4.30 ctrace(1)
'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 ctrace input, along
with any appropriate -D, -I, and -U preprocessor
options. If you still get the error message, check the
Warnings section below.
WARNINGS
You will get a ctrace 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. Just use a different name.
Ctrace assumes that BADMAG is a preprocessor macro, and that
EOF and NULL are #defined constants. Declaring any of these
to be variables, e.g. "int EOF;", will cause a syntax error.
BUGS
Ctrace cannot handle the components of aggregates like
structures, unions, and arrays. It cannot choose a format
to print all the components of an aggregate when an
assignment is made to the entire aggregate. Ctrace may
print the address of an aggregate or use the wrong format
(e.g., %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
functions called from a loop still being traced, or the
elimination of trace output from one function in a file
until another in the same file is called.
FILES
runtime.c run-time trace package
SEE ALSO
signal(2), ctype(3C), fflush(3S), longjmp(3C), printf(3S),
setjmp(3C), string(3C) in the Programmer's Reference for the
DG/UX System.
Licensed material--property of copyright holder(s) Page 5