ctrace(1)						      General Commands Manual							 ctrace(1)

Name
       ctrace - 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, statement 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
       referenced  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 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 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 appropriate.  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 -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 runtime.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 = 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 = '
')
	9	      ++nl;
       10   printf("%d
", nl);
       11 }
       When you enter the following commands and test data the program 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 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 = '
')
		 /* c == 10 or '
' */
	9	      ++nl;
		      /* nl == 1 */
	7   while ((c = getchar()) != EOF)
	    /* c == 10 or '
' */
	8	 if (c = '
')
		 /* c == 10 or '
' */
	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
", 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 "
".	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 pro-
       gram.

       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 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.

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 differ-
       ent 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 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.

       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 appropriate -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 vari-
	      ables 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 section.

       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 Also
       ctype(3), printf(3s), setjmp(3), signal(3), string(3)

																	 ctrace(1)