CTRACE(1) DOMAIN/IX SYS5 CTRACE(1)
NAME
ctrace - C program debugger
USAGE
ctrace [ options ] [ file ]
DESCRIPTION
The ctrace command lets you follow the execution of a C pro-
gram, statement by statement. The effect is similar to exe-
cuting a Shell procedure with the -x option. It reads the C
program in file (or from standard input if you do not
specify file), inserts statements to print the text of each
executable statement and the values of all variables refer-
enced or modified, and writes the modified program to the
standard output. You must put the output of ctrace in 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 vari-
ables referenced or modified in the statement, and then by
any output from the statement. When a loop is detected in
the trace output, 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.
OPTIONS
The most commonly-used options to ctrace are as follows:
-f functions Trace only the specified functions.
-v functions Trace all but the specified functions.
In using the -v option, you may 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.
String arguments to the string(3C) functions and return
values from fgets(3S), gets(3S), and sprintf(3S) are printed
as strings. You can request that variables be printed in
additional formats, if appropriate, by adding the following
characters to the -v option:
o (octal)
x (hexadecimal)
Printed 12/4/86 CTRACE-1
CTRACE(1) DOMAIN/IX SYS5 CTRACE(1)
u (unsigned)
e (floating point)
These options are used only in special circumstances:
-l n Check n consecutively executed statements for
looping 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 use
of 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). (See
``Diagnostics'' below.)
-P Run the C preprocessor on the input before tracing
it. You can also use the -D, -I, and -U options to
the cc(1) preprocessor.
Use the following options to tailor the run-time trace
package when the traced program will run in a non-UNIX sys-
tem environment:
-b Use only basic functions in the trace code, that
is, those in ctype(3C), printf(3S), and
string(3C). These are usually available even in
cross-compilers for microprocessors. In particu-
lar, 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 'string'
Change the trace print function from the default
of 'printf(' to string. For example,
'fprintf(stderr' sends the trace to the standard
error output.
-r f Use file f in place of the runtime.c trace func-
tion package. This lets you change the entire
print function, instead of just the name and lead-
ing arguments (see the -p option).
CTRACE-2 Printed 12/4/86
CTRACE(1) DOMAIN/IX SYS5 CTRACE(1)
CAUTIONS
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.
The ctrace program 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;)
causes a syntax error.
Pointer values are always treated as pointers to character
strings.
The ctrace program does not know about 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. When
printing the value of an aggregate, ctrace may choose to
print the address of an aggregate or use the wrong format
(e.g., %e for a structure with two integer members).
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.
EXAMPLES
If the file lc.c contains this 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 }
and you enter these commands and test data:
#cc lc.c
Printed 12/4/86 CTRACE-3
CTRACE(1) DOMAIN/IX SYS5 CTRACE(1)
#a.out
#1
(CTRL/D)
the program will be compiled and executed. (Note: CTRL/D,
used above, applies as an end-of-file control key sequence
only if your keyboard is mapped to /sys/dm/sys5_keys; other-
wise, you must use a CTRL/Z instead.) The output of the pro-
gram 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
CTRACE-4 Printed 12/4/86
CTRACE(1) DOMAIN/IX SYS5 CTRACE(1)
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 ctrace at the end of the trace output. This shows the
implicit return at the terminating brace in the function.
Since, by default, ctrace traces the entire program file,
you do not normally have statement-by-statement control of
the tracing, nor can 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 condi-
tionally include this code because ctrace defines the CTRACE
preprocessor variable.
For example:
#ifdef CTRACE
if (c == '!' && i > 1000)
ctron();
#endif
DIAGNOSTICS
Although this section contains diagnostic messages from
ctrace, you should know that the traced code may also get an
occasional warning message (or, in rare instances, an error
message) from cc(1). See cc for an explanation of appropri-
ate compiler 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 expres-
sion'' 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 state-
ment.
Printed 12/4/86 CTRACE-5
CTRACE(1) DOMAIN/IX SYS5 CTRACE(1)
'if ... else if' sequence too long
Split the sequence by removing an else statement 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. (See ``CAUTIONS" for more information.)
FILES
/usr/lib/ctrace/runtime.c
run-time trace package
RELATED INFORMATION
cc(1) longjmp(3C)
signal(2) printf(3S)
ctype(3C) setjmp(3C)
fflush(3S) string(3C)
CTRACE-6 Printed 12/4/86