ctrace man page on Ultrix

Man page or keyword search:  
man Server   3690 pages
apropos Keyword Search (all sections)
Output format
Ultrix logo
[printable version]

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

								     ctrace(1)
[top]

List of man pages available for Ultrix

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
...................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net