ctrace(1) ctrace(1)NAME ctrace - C program debugger SYNOPSIS ctrace [-b] [-e] [-ffunctions] [-ln] [-o] [-p 's'] [-P] [-rf] [-s] [-tn] [-u] [-vfunctions] [-x] [file] DESCRIPTION ctrace allows you to follow the execution of a C program, statement by statement. The effect is similar to executing a shell procedure with the -x flag option. ctrace 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 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 will be listed at the terminal, followed by the name and value of any vari- ables 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 ex- ecuted. 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 that you may put it into a file for examination with an editor or the bfs(1) or tail(1) commands. The only flag options you will commonly use are: -f functions Trace only these functions. -v functions Trace all but these functions. You may want to print variables in other formats besides the default. 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 ap- propriate, as characters. Double variables are printed as floating point numbers in scientific notation. You may re- quest that variables be printed in additional formats, if appropriate, with these flag options: -o Octal -x Hexadecimal -u Unsigned -e Floating point April, 1990 1
ctrace(1) ctrace(1)These flag 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 assign- ment statements and string copy function calls. This flag 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 de- fault of 10 (the maximum number is 20). The DIAGNOS- TICS section explains when to use this flag option. -P Run the C preprocessor on the input before tracing it. You can also use the -D, -I, and -U cc(1) preprocessor flag options. These flag options are used to tailor the run-time trace package when the traced program will run in another environ- ment than that of the UNIX system: -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 particular, this flag option is needed when the traced program runs under an operating system that does not have signal(3), 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 func- tion, instead of just the name and leading arguments (see the -p flag option). 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; 2 April, 1990
ctrace(1) ctrace(1)10 printf("%d\n", nl); 11 } and you enter these commands and test data: cc lc.c a.out 1 (CONTROL-d), the program will be compiled and executed. The output of the program will be the number 2, which is not correct be- cause 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 /* repeating */ If you now enter an end-of-file character (CONTROL-d), the final output will be: /* c == -1 */ 10 printf("%d\n", nl); /* nl == 2 */2 /* return */ April, 1990 3
ctrace(1) ctrace(1)Note that the program output printed at the end of the trace line for the nl variable. Also note the return comment ad- ded by ctrace 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 if statement, you will probably realize that you used the assignment operator (=) in place of the equal operator (==). During code reading, it is easy to miss this error. EXECUTION-TIME TRACE CONTROL The default operation for ctrace is to trace the entire pro- gram file, unless you use the -f or -v flag 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 ctroff() and ctron() function calls to your program to turn the tracing off and on, respectively, at execution time. Thus, you can code ar- bitrarily complex criteria for trace control with if state- ments, and you can even conditionally include this code be- cause ctrace defines the CTRACE preprocessor variable. For example: #ifdef CTRACE if (c == '!' && i > 1000) ctron(); #endif You can also call these functions from sdb(1) if you compile with the -g flag option. For example, to trace all but lines 7 to 10 in the main function, enter: sdb a.out main:7b ctroff() main:11b ctron() r You can also turn the trace off and on by setting the static variable tr_ct_ to 0 and 1, respectively. This is useful if you are using a debugger that cannot call these functions directly. DIAGNOSTICS This section contains diagnostic messages from both ctrace and cc(1), since the traced code often gets some cc warning messages. You can get cc error messages in some rare cases, all of which can be avoided. 4 April, 1990
ctrace(1) ctrace(1)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 expres- sion'' error. Use the -t flag 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. ``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 flag option to preprocess the ctrace input, along with any appropriate -D, -I, and -U preprocessor flag options. If you still get the error message, check the WARNINGS section, below. 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 ctrace ``possible syntax error'' message above. yacc stack overflow See the ctrace 'if ... else if' sequence too long mes- sage, above. Out of tree space; simplify expression Use the -t flag 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 Either correct this declaration of signal(3), or remove it and #include <signal.h>. April, 1990 5
ctrace(1) ctrace(1)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. To fix this, just use a different name. ctrace assumes that BADMAG is a preprocessor macro, and that EOF and NULL are #define d constants. Declaring any of these to be variables, e.g., int EOF will cause a syntax er- ror. BUGS ctrace 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 assign- ment is made to the entire 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) 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. FILES /usr/bin/ctrace /usr/lib/ctrace SEE ALSO sdb(1), ctype(3C), fflush(3S), longjmp(3C), printf(3S), setjmp(3C), signal(3), string(3C). 6 April, 1990