ctrace(1)ctrace(1)Name
ctrace, ctc, ctcr - C program debugger
Syntax
ctrace [options] [file]
ctc [options] [file]
ctcr [options] [file]
Description
The command allows you to follow the execution of a C program, state‐
ment by statement. The command reads the C program in file (or from
standard input if you do not specify file) 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 into a temporary
file because the 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 refer‐
enced or modified in the statement, 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 state‐
ments 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 command.
The command is a shell script that prepares the specified C program
file for later execution. The command is a shell script that both pre‐
pares and executes the specified C program file.
Options
The only options you will commonly use 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 appropri‐
ate. Char, short, and int variables are also printed as signed inte‐
gers and, if appropriate, as characters. Double variables are printed
as floating point numbers in scientific notation.
You can request that variables be printed in additional formats, 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 statements 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 -Ucc(1) pre‐
processor 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 runtime.c trace func‐
tion package. This lets you change the entire
print function, instead of just the name and lead‐
ing 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 = operator 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 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 }
When you enter the following commands and test data the program is com‐
piled 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 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)
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 at the end of
the trace output. This 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 in line 8 it has been assigned the value “\n”. Once your
attention is drawn to this if statement, you realize that you used the
assignment operator (=) instead of the equal operator (==) as intended
in line 8. You can easily miss this error during code reading.
Execution-time Trace Control
The default operation for is to trace the entire program 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 and 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
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
Restrictions
The command does not know about the components of aggregates such as
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. The command may choose to print the address of an aggregate
or use the wrong format (for example, %e for a structure with two inte‐
ger 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 func‐
tion in a file until another in the same file is called.
Warnings
You get a 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 command assumes that BADMAG is a preprocessor macro, and that EOF
and NULL are constants. Declaring any of these to be variables, for
example, will cause a syntax error.
Diagnostics
This section contains diagnostic messages from both and since the
traced code often gets some warning messages. You can get error mes‐
sages 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.
cannot handle preprocessor code, use -P option
This is usually caused by preprocessor statements in the middle
of a C statement, or by a semicolon at the end of a preprocessor
statement.
'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 input, along with any appro‐
priate -D, -I, and -U preprocessor options. If you still get
the error message, check the Warnings section above.
Using with the -P option on a program that includes or a header
file that includes also causes this error even though you are
already using the -P option.
To avoid the problem, when you are using surround the line for
with pairs as shown in this example:
#ifndef CTRACE
#include <sys/types.h>
#endif CTRACE
The program defines the CTRACE preprocessor variable during its
execution and ignores the files when it processes your program.
Later when you compile your program, the files are included as
usual by the C preprocessor. Note that the files listed here
also include or they may be included in other include files.
Surrounding them with pairs may allow to process your program
successfully.
<sys/audit.h> <auth.h>
<sys/file.h> <grp.h>
<sys/param.h> <pwd.h>
<sys/socket.h> <signal.h>
<sys/sysmacros.h> <sys/time.h>
<sys/wait.h>
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 "possible syntax error" message above.
yacc stack overflow
See the 'if .. else if' "sequence too long" message above.
out of tree space; simplify expression
Use the -t option to reduce the number of traced variables per
statement from the default of 10. Ignore the "ctrace: too many
variables to trace" warnings you will now get.
redeclaration of signal
You may either need to correct the declaration of or to surround
the statement with an pair as described in the Diagnostics sec‐
tion.
unimplemented structure assignment
Use instead of
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 Alsoctype(3), printf(3s), setjmp(3), signal(3), string(3)ctrace(1)