Subversion Repositories DevTools

SHERLOCK

C Programming Tool

February 1, 1990

Version 1.5

Edward K. Ream

1617 Monroe Street.

Madison, WI 53711

CHAPTER 1  INTRODUCING SHERLOCK

Welcome to Sherlock!  Sherlock is not an ordinary programming tool and

you may have some questions about it: what is it, what features does it

have, how does it operate, how will it benefit you, how do you use it, how

does it compare with other tools and techniques, how easy will it be to use,

how can you customize it?  This chapter poses and answers these kinds of

questions and along the way provides examples showing how to use

Sherlock.

What is Sherlock, anyway?

Sherlock is a debugging, tracing and profiling tool for the C programming

language.  That is, Sherlock allows you to test and debug C programs by

examining various traces.  As an added benefit, Sherlock offers detailed

statistics about your program.  Sherlock consists of C language macros

and support routines called by those macros.

Why should I use Sherlock?

Sherlock allows you to build, study, enhance and maintain more complex

programs in less time.  It gives you a better view of your program than

other kinds of debuggersDyou get more useful information and less

useless data.  Sherlock reveals your program at any level you wish, from a

global, overall, landscape view to a very detailed view.  And you get to choose the exact format in which the information is presented.  Sherlock

is very flexible and can be used with very large and complex programs,

including programs that use overlays and re-entrant programs.

How does Sherlock work?

The basic idea behind Sherlock is simple: you can create individual tracing

instructions, written in the C language, which lie dormant in your program

until enabled while your program is executing.

That sounds very simple.  What's the big deal?

The ability to add hide latent instructions inside a program and to enable

them while the program is running turns out to be very powerful.

Typically these dormant instructions are tracing statements such as print

statements.  By enabling various sets of these tracing instructions you can

produce literally thousands of different traces from your program without

changing it or recompiling it.  This is a very fast and handy way of

pinpointing the location of bugs, especially pointer bugs.

Isn't using Sherlock like putting print statements throughout a program?

Not really.  If you just insert print statements throughout your program

you are buried in useless output.  The sheer volume of the output hides the

information that would make a difference to you.  The only way to make

sense of the output is to get rid of most of it.  Alas, removing the print

statements and recompiling takes a lot of time.  Also, once print statements

have been removed they are not available later until they have been re-

inserted and and the program recompiled and relinked.  You just can't be

very flexible this way.

With Sherlock, you enable tracing statements without changing your

program in any way.  Generating different traces is done in a matter of

seconds, not minutes.  And since your program remains unchanged, bugs

remain stable;  their symptoms do not change as they would if you added

or deleted print statements.

How is it possible to enable or disable a single C instruction?

It's done with macros.  The instruction or instructions are entered as the

arguments to special tracing macros.  For instance, suppose you want to

disable the following print statement:

	printf("The value of i is %d\n", i);

The TRACE macro is one of several that you might use.  It takes two

arguments.  The first is the name that will be given to the disabled

statement, say "abc".  The second is the statement or statements we want to

disable.  The complete TRACE macro would look like this:

	TRACE("abc", printf("The value of i is %d\n", i));

Let's look at this carefully.  The name given to the print statement is

represented by the C string "abc".  The comma after the "abc" separates the

two arguments.  Next comes the printf statement and two right

parentheses, one for the printf statement and one for the TRACE macro.

Notice that the semicolon that ends the printf statement has been omitted.

It would also be all right to leave it in, like this:

	TRACE("abc", printf("The value of i is %d\n", i););

The effect of this macro is as follows: the print statement is executed when

control reaches the macro only if the symbol "abc" has already been

enabled.

Please note: the operation of the TRACE macro varies drastically from the

more traditional kind of debugging macros often used in programming

projects.  Sherlock macros enable or disable tracing code during the

execution of the program..  Traditional debugging macros require that the

program be recompiled in order to enable or disable the code in the macros

  The effect of this difference is enormous.

Can other kinds of statements besides print statements be used?

Yes.  You can disable any executable C statement or sequence of

statements, including blocks.  For instance, a very useful kind of tracing

statement might be a function call which would print out a complicated data

structure.

How do you tell Sherlock which macros you want to enable or disable?

The most common way is to add special arguments to the command line.

For instance, to enable any macro whose name is "abc" you would add the

following argument to the command line:

	++abc

You can also enable macros while your program is running using other

Sherlock macros.

Won't the extra command line arguments interfere with my program?

No.  Sherlock removes these special arguments from the command line so

they will be completely invisible to your program.  They will not interfere

with the argument processing logic of your program in any way.

How does Sherlock know which arguments to delete from the command line?

All Sherlock arguments are preceded by one of two prefixes: an "on

prefix" that enables macros and an "off-prefix" that disables macros.  You

should choose each prefix to be something that will distinguish Sherlock

arguments from all other arguments to your program.  In the example

above, the prefix is ++.

Putting these macros into my programs seems like a lot of work to me.

Sherlock includes a utility program called SPP, for Sherlock Pre-Processor,

which will put macros at the entry and exit of all your functions

automatically, which is where you most often want them.

You mentioned that Sherlock is also a profiling tool.  What does that mean?

Sherlock gathers statistics automatically.  Sherlock counts how many times

each macro was encountered and also computes timing statistics using an

interrupt handler.  Sherlock associates these statistics with the names

defined by the macros.  All the details are handled by the macros.  You

may print a report of the statistics at any time.

How many Sherlock macros are there?

Over 30.

Why so many?

Many macros do the same basic thing with minor variations.  For instance,

 there is a TRACEP macro which is acts the same as TRACE except that

TRACEP prints its first argument, i.e., the name associated with the

macro, before executing the disabled instruction.  This saves some space in 

your program.  There are also macros used to initialize the Sherlock

system, to enable or disable macros, and to print a report of statistics.

Must I remove all the macros when I am done debugging?

No.  You can simply undefine a single compile-time variable, recompile

and relink.  All the code generated by the macros will disappear and the 

executable portion of your program will contain absolutely no evidence that 

Sherlock macros exist in the source code. Thus, there is no need to 

physically eliminate the macros from your source files.  There is a utility 

program, called SDEL, which will remove Sherlock macros from a source 

file if you want.

Can I choose different names for the Sherlock macros?

Yes.  All you have to do is to change names defined in a standard header 

file.  You will still be able to use SPP and SDEL.  Both tools allow you to 

specify alternate macro names to be used instead of the standard macro 

names.

What if I want to change how the macros work?

Full source code is provided for all macros, support routines and utility 

programs except SPP. To use the Sherlock system on another machine you 

need only recompile the support routines on the new machines.  You will 

need to rewrite the interrupt handler only if you wish to gather timing 

statistics on the new machineDSherlock will work without the interrupt 

handler.

CHAPTER 2  BEFORE USING SHERLOCK

This chapter provides information you should know before using 

Sherlock.  It lists the hardware and software required, it reminds you to 

create a backup copy of the distribution disk containing Sherlock, and it 

lists the files that are distributed with the Sherlock system.

System Requirements

o An IBM PC/XT/AT computer or compatible with two floppy disks or a 

hard disk.

o The MS-DOS operating system.

o Either the Microsoft C compiler or the Turbo C compiler.  Minor 

modifications in Sherlock's source code will allow Sherlock to compile 

using other C compilers.

o The Microsoft MASM macro assembler.  (Used only when changing the 

interrupt handler.)

Backing Up Your Disks

Please back up the distribution disks before using Sherlock.  Use the DOS 

COPY command to copy all the files on the distribution disks to backup 

disks.  Your backup disks will be used as working disks.

Files on Your Disk

File		Description

read.me		Late breaking news and information.  Please read 

		this file first.

*.mak		Make files for the Turbo C compiler version 1.5.

*.mmk		Make files for the Microsoft C compiler version 

		5.00 or later.

*.lnk		Link files for the Turbo C linker.

*.ml		Link files for the Microsoft linker.

cpp.exe		C Preprocessor whose source code illustrates the 

		use of Sherlock's macros.

\cpp\*.c	Source code for CPP.

\cpp\*.h	Header file for CPP.

dumpregs.c	C Language source code for a program illustrating 

		the use of regs.asm.

prf.asm		Assembly language source code for the interrupt 

		handler.

prfnear.obj	Object code for interrupt handlerDfor memory 

		models with small code spaces.

prffar.obj	Object code for interrupt handlerDfor memory 

		models with large code spaces.

regs.asm	Assembly language source code for the register 

		dumper.

regsnear.obj	Object code for the register dumperDfor memory 

		models with small code spaces.

regsfar.obj	Object code for the register dumperDfor memory 

		models with large code spaces.

sdel.exe	Utility program which deletes all Sherlock macros 

		from a single source file.

sdel.c		C language source code for SDEL illustrating the 

		use of Sherlock's macros.

sdif.exe	Special purpose file comparison program.

sdif.c		The C language source code for SDIF.

sherlock.c	C language source code for support routines.

sl.h		Preferred definitions of macros.

sl1.h		Alternate definitions of macros.

spp.exe		Utility program which inserts Sherlock macros 

		into a single source file.

Quick Start

This is the super-condensed version of the installation procedure.

1. Insert Sherlock macros into functions that you want to trace.  Sherlock 

comes with a stand alone tool, called SPP, which will do this automatically 

for you.  See the section called SPP of the User's Manual for details.

2. Insert the SL_INIT and SL_PARSE macros into your main() function as 

the first executable statements.  Again, SPP will do this automatically for 

you.

3.  Insert the line     #include "sl.h"   in each source file containing a 

Sherlock macro.  This can be done automatically using the -i option of 

SPP.  Alternatively, if you have a single header file which is inserted in all 

your source files, insert the line  #include "sl.h" in that header file.

4. Recompile all files which contain Sherlock macros.  Make sure to 

#define the compile time symbol called SHERLOCK.  The easiest and best 

way to do this is with a command line option to the compiler.

5. Compile the source code for the Sherlock support routines, located in 

sherlock.c.  Make sure the memory model used when compiling the 

support routines is the same as the memory model used when compiling 

the rest of the files of your program.  Sample make and link files to 

accomplish this step are included in the directory called sherlock.

6. Link the following files together to produce an executable version of 

your program:

o All the .obj files produced by compiling the files of your program.

o The .obj file produced by compiling sherlock.c.

o One (and only one) of the following two files:  prffar.obj or prfnear.obj.

Note:  Use prffar.obj when using memory models that have a code space 

larger than 64K.  Use prfnear when using memory models that have a code 

space limited to 64K or less.

7. Run your program.  To enable traces, add Sherlock command line 

arguments to your program's command line. For example, to enable 

tracing of a function called f(), add the argument ++f to the command line.  

8. When you are done debugging, recompile all your files which contain 

Sherlock macros with the compile time constant SHERLOCK not 

#define'd.  The code produced by the Sherlock macros will disappear.  

Relink all those files to produce a production version of your program.  Do 

not link in the .obj file produced by compiling sherlock.c.  Do not link in 

either prffar.obj or prfnear.obj.

CHAPTER 3  USING SHERLOCK

This chapter contains a tutorial introduction to Sherlock.  It tells you 

everything you need to know to start using Sherlock.  After an initial 

overview, the various macros comprising Sherlock will be discussed in 

detail, with numerous examples along the way.  The last section discusses 

how to enable macros using command line arguments.  For some tips 

about debugging C programs, see the next chapter.  For the most complete 

information about any aspect of the Sherlock system, see chapter five.

Overview

The Sherlock system consists of three main parts: tracing macros, other 

macros including initialization and statistics reporting macros and support 

routines called by the macros.  The support routines form the "hidden 

machinery" of the Sherlock system and will not be discussed further in this 

overview.

Sherlock's tracing macros are the most visible and important part of the 

Sherlock system.  These tracing macros allow you to create tracing 

statements embedded throughout your program which can be enabled or 

disabled without recompiling your program or changing the executable 

image of your program in any way.  Tracing macros also provide a 

framework for gathering statistics about your program.

Each tracing macro defines a tracepoint, a tracepoint name and a list of 

tracepoint actions.  A tracepoint is simply the location of the macro, the 

tracepoint name is a C language string which names the tracepoint and the 

tracepoint actions consist of one or more executable C language statements 

which are executed only if the tracepoint has been enabled.

Let's look at one kind of tracing macro, called TRACE.  The format of this 

macro is:

	TRACE(tracepoint_name, tracepoint_actions);

In other words, this macro takes two arguments, a tracepoint name and a 

list of tracepoint actions.  For example:

	TRACE("print_abc", printf("The value of abc is %d/n", abc));

Notice the two closing parentheses.  The first ends the printf statement and 

the second ends the TRACE macro.  In this example, the tracepoint name is 

a string

literal, namely "print_abc", and the tracepoint actions consists of the single 

statement:

	printf("The value of abc is %d/n", abc);

The operation of this TRACE macro is straightforward: the print statement 

will be executed only if the tracepoint named print_abc has been enabled.

Please note: the operation of the TRACE macro varies drastically from the 

more traditional kind of debugging macros often used in programming 

projects.  Sherlock macros enable or disable tracing code during the 

execution of the program. Traditional debugging macros require that the 

program be recompiled in order to enable or disable the code in the macros.  

The effect of this difference is enormous.  With Sherlock, you can scatter 

tracing macros throughout your program with no ill effects. With 

traditional debugging macros, this strategy is simply not possible because 

you would be buried in tracing output.

How are tracepoints enabled?  There are two ways: from the command line 

using special Sherlock arguments or from within your program using 

Sherlock macros.  In practice, the command line is most often used.  

Sherlock arguments consist of a prefix followed by a tracepoint name.  

There are two possible prefixes: an on_prefix which enables the following 

tracepoint name and an off_prefix which disables the following tracepoint 

name.  These prefixes are defined by an initialization macro called 

SL_PARSE and should be chosen so that Sherlock arguments can be 

distinguished from all other command line arguments.  The SL_PARSE 

macro processes all Sherlock arguments and then deletes them from the 

command line so that they will not interfere with the argument processing 

logic of your program. 

Any string may be used for these prefixes, and in this manual we will 

assume that the on prefix is ++ and the off prefix is - -.  For example, to 

enable tracing for the tracepoint named print_abc, the following command 

line argument could be used:

	++print_abc

Wildcard characters and other construction may be used in Sherlock 

arguments.  See the section on command line arguments for more details.

To summarize, here are the steps to use Sherlock:

1. Insert Sherlock macros throughout your program.  This is easy because 

Sherlock comes with a utility program called the Sherlock Preprocessor 

(SPP)  which will insert tracing macros automatically at the beginning and 

end of every function in a file.  The tracing macros created by SPP will 

print the values of all arguments to functions as well as the value returned 

from all functions.

2. The Sherlock macros are defined in a header file called sl.h.  Insert the 

following statement in every file that contains a Sherlock macro:

	#include <sl.h>

The SPP program will insert this statement for you if you desire.

3. Compile the files containing the Sherlock macros as usual and link in the 

support routines to create an executable version of your program.

4. Run your program and enable various tracepoints using Sherlock 

command line arguments.  On successive runs, focus on important details 

by enabling different tracepoints.

5. After debugging is complete, remove the code generated by Sherlock 

macros.  You can do this without removing the macros themselves by 

undefining the compile time constant called SHERLOCK and recompiling.  

Absolutely no overhead from the Sherlock macros will remain in your 

program.

6. Most people will want to leave Sherlock macros inside their source file 

so that they may be reactivated later by redefining the SHERLOCK 

constant and recompiling.  However, a utility called SDEL will remove all 

Sherlock macros from a source file if you desire.

This concludes the overview of the Sherlock system.  The next sections 

introduce you to all of the Sherlock macros and will discuss details 

concerning Sherlock command line arguments, header files and statistics.

Initialization: SL_INIT, SL_PARSE, SL_ON, and SL_OFF

Right at the start of your program, Sherlock's support routines must be 

initialized and the Sherlock arguments on the command line must be 

processed and removed.

The SL_INIT macro initializes Sherlock's support routines.  This macro 

must be executed before any other macro.  The best place for the SL_INIT 

macro is the very first executable statement of the main() routine.  The SPP 

program will insert the SL_INIT macro at that spot for you.  Note that the 

name is all UPPER CASE, as are the names of all Sherlock macros.

In the language of the draft C standard, the SL_INIT macro, like all of the 

Sherlock macros, is a "function-like" macro, which means that parentheses 

are required after it even though the macro takes no arguments.  Like this:  

SL_INIT();

The SL_PARSE macro enables or disables tracepoints by processing an 

argument list vector.  Most often, the vector is simply the argv vector 

passed by the operating system to the main() routine, but it doesn't have to 

beDyou can set up your own if you want.  The SL_PARSE macro may be 

called more than once, so you can enable or disable tracepoints from inside 

your program as well as from the command line.  Typically, the 

SL_PARSE macro should be placed immediately following the SL_INIT 

macro in the main() routine.  Again, the SPP program will insert the 

SL_PARSE macro for you there.

SL_PARSE takes four arguments.  The format is:

	SL_PARSE(argc, argv, on_prefix, off_prefix);

	int argc; char *argv[], *on_prefix, *off_prefix;

The first two arguments describe an argument list vector just like the argc 

and argv arguments passed to main().  In other words, argv is a pointer to 

a list of strings and argc is one more than the number of arguments in 

argv[].  The argv vector is terminated by a NULL string so that  argv[argc] 

is NULL.  

The on_prefix and off_prefix arguments must be C strings, either string 

literals or pointers to arrays of characters.  All arguments (i.e., all strings in 

the argv vector) whose prefix is either on_prefix or off_prefix are 

processed as Sherlock arguments and removed from the argv vector.  The 

argc count is decremented by one for every deleted argument.  Arguments 

that do not start with either the on_prefix or the off_prefix are not changed 

by SL_PARSE.

Here is an example of a typical main routine:

	main(int argc, char ** argv)

	{

		declarations of local variables.

		SL_INIT();

		SL_PARSE(argc, argv, "++", "- -");

		executable statements...

	}

All examples in this manual will assume that the prefixes are ++ and - -.  

However, any C string may be used for the off prefix or on prefix.  For 

example, to set the on_prefix to !+ and the off_prefix to !-, you would use 

the following call to SL_PARSE:

	SL_PARSE(argc, argv, "!+", "!-");

Here is a program that simply prints its command line arguments.  Note 

that it will not print any Sherlock argument, i.e., any argument starting 

with ++ or - -.

	/* Echo command line arguments. */

	main(argc, argv)

	int argc;

	char **argv;

	{

		int i;

		/* Process and remove Sherlock arguments. */

		SL_INIT();

		SL_PARSE(argc, argv, "++", "- -");

		/* Print non-Sherlock arguments. */

		argc- -;

		argv++;

		for (i = 1; i < argc; i++) {

			printf("argv[%d] = %s\n", i, *argv);

			argv++;

		}

	}

The SL_ON and SL_OFF macros also enable or disable tracepoints from 

within your program and are easier to use than SL_PARSE.  Each macro 

takes one argument, the name of the tracepoint to be enabled or disabled.  

SL_ON enables the tracepoint while SL_OFF disables the tracepoint.  The 

name of the tracepoint is not preceded by either the on_prefix or the 

off_prefix.  

The following example shows how to enable tracing for a selected range of 

loop iterations:

	for (i = 0; i < 100; i++) {

		if (i = = 20) {

			SL_ON("complicated_function");

		}

		complicated_function(i);

		if (i = = 30) {

			SL_OFF("complicated_function");

		}

	}

The following sections discuss tracing macros, the heart of the Sherlock 

system.

Tracepoint Names and Statistics: STAT, STATB and STATX

STAT is the simplest tracing macro.  It takes one argument, a tracepoint 

name.  For example:

	STAT("rose");

Although closely related to the other tracing macros, STAT produces no 

output.  STAT's only function is to provide a label for a count statistic, 

which is simply the number of times control reaches the tracepoint defined 

by STAT.  All tracing macros have a count statistic associated with their 

tracepoint name.  Count statistics are always updated regardless of whether 

tracing for a particular tracepoint has been enabled or not.

In order to provide better error checking, there are restrictions on the kinds 

of characters that may appear in tracepoint names;  tracepoint names may 

contain lower case letters, numerals and the underscore character, but not  

blanks or special characters such as ( ) { } + etc.  The following are valid 

tracepoint names:

	STAT("rose_is_a_rose");

	STAT("rose25");

The following are NOT valid tracepoint names:

	STAT("rose water"); 		blank character

	STAT("wine&roses");		& special character

There are two additional members of the STAT family, STATB and 

STATX.  These two macros are used to gather timing statistics.  Timing 

statistics are generally more useful than count statistics since they relate 

directly to program speed.  On the other hand, timing statistics are a little 

more difficult to gather than count statistics.  Timing statistics measure the 

time spent in timing code.

The STATB macro works just like the STAT macro, except that the STATB 

macro is an entry macro, that is, STATB defines the start of a section of 

timing code.  Similarly, the STATX macro is an exit macro, that is, STATX 

defines the end of a section of timing code.  In general, the suffix 'B' in the 

name of a tracing macro indicates that the macro is an entry macro, while 

the suffix 'X' in the name of a tracing macro indicates the macro is an exit 

macro.  Count statistics are updated for STATB but not STATX.

Most often, timing code consists of an entire function, though that is not 

required.  For example, to measure the time spent in a function without 

generating any tracing message you would do something like:

int f()

{

	STATB("f");

	body of f;

	STATX("f");

}

The support routines keep track of statistics using an internal timing stack.  

At run time, each entry macro must be paired eventually with an exit 

macro.  For example, if you put an entry macro at the beginning of a 

function then every exit from the macro must contain an exit macro.  When 

an exit macro is executed, Sherlock verifies that its tracepoint name 

matches the tracepoint name of the last entry macro, i.e., the macro on the 

top of the timing stack.  A warning message occurs if there is a mismatch. 

Such a warning indicates that timing statistics are not accurate.

The current nesting level is the number of entry macros that have been 

executed for which an exit macro has not been executed.  The output from 

all tracing macros is preceded by level dots, i.e., one period for each level 

of nesting.

Sherlock provides two kinds of timing statistics: cumulative and non-

cumulative.  Cumulative timing statistics measure the total time spent in 

timing code, including any time spent in nested timing code.  Non-

cumulative timing statistics excludes time spent in nested timing code.  In 

other words, cumulative statistics are incremented at all levels of the timing 

stack, while non-cumulative statistics are updated only at the top of the 

timing stack.

The following paragraphs will be of interest only to advanced users of 

Sherlock who wish to gather the best timing statistics possible.  Thanks go 

to James E.G. Morris of Atari Games Corporation for suggesting 

improvements in the way timing statistics are handled.  

Version 1.5 of the support routines provides ways to adjust the timing 

statistics gathered by Sherlock to factor out the overhead caused by calling 

and returning from the Sherlock macros.  The Sherlock support routine 

sl_dump() now  subtracts a "fudge factor," called TIME_ADJUST, from 

the timing statistics as the report of the statistics is being generated.  This 

fudge factor affects only the output of the SL_DUMP macroDthe actual 

gathering of timing statistics is not affected in any way by 

TIME_ADJUST.

The units of TIME_ADJUST are ticks per 1000 calls to Sherlock macros, 

and TIME_ADJUST is supplied as a compile-time constant on the 

command line when compiling sherlock.c.  If no value for 

TIME_ADJUST is supplied, it is set to zero, which is what you get by 

default.

The proper value of TIME_ADJUST depends on several factors: the speed 

of your machine, its "tick" rate, the "speed up rate,"  i.e., the value of 

sl_speed used in sherlock.c, which version of Sherlock macros is used, 

preferred or alternate, and which memory model is used to compile your 

program.  A new utility program, called measure.c, measures the time 

overhead involved in calling Sherlock macros, and suggests appropriate 

values for TIME_ADJUST.

Here I am Messages: TICK, TICKB, TICKN and TICKX

The simplest kind of tracing output is a "here I am" message.  The TICK 

family of macros provide such messages.  The TICK macro takes exactly 

one argument, a tracepoint name.  Examples:

	char name[] = "petunia";

	TICK(name);

	TICK("marigold");

If enabled, TICK simply prints the name of the tracepoint followed by a 

colon.  The output created from the examples above would look like:

	petunia:

	marigold:

The only difference between TICK and TICKN is that TICK updates the 

count statistic associated with the tracepoint name and TICKN does not.  In 

general, the suffix 'N' in the name of a tracing macro indicates that count 

statistics are not updated by the macro.

Why suppress the gathering of count statistics?   You might use TICKN 

rather than TICK in order not to count the same section of code twice.  For 

example:

	do {

		TICK("loop");

		...

		TICKN("loop");

	} while (waiting);

Since only one TICK macro was used in the loop, the count statistic for 

"loop" will reflect how many times the loop was executed.

As you would expect, the TICKB and TICKX macros are entry and exit 

macros that otherwise work just like TICK.  Count statistics are updated 

for TICKB but not TICKX.

Tracepoints Actions: TRACE, TRACEB, TRACEN and TRACEX

The TRACE family of tracing macros create code that lies dormant until the 

appropriate tracepoint is enabled.

The members of the TRACE family take exactly two arguments.  As usual, 

the first is a tracepoint name.  The second is a list of tracepoint actions, 

consisting of one or more C language statements or blocks.  Statements in 

the list of tracepoint actions are separated by semicolons as usual.  The list 

may be terminated by a semicolon, but it doesn't have to be.   For example:

	TRACE("violet", printf("variable v = %d at xyz\n", v));

The tracepoint actions consist of a single print statement, namely:

	printf("variable v = %d at xyz\n", v);

The print statement will be executed only if the tracepoint named "violet" 

has been enabled.

Any number of C statements may appear in the list of tracepoint actions.  

For example:

	TRACE("peach",

		arg = xyz;

		p=f(arg);

		printf("f(xyz) is %lx at xyz\n", p));

The tracepoint actions consist of the three C statements:

	arg = xyz;

	p=f(arg);

	printf("f(xyz) is %lx at xyz\n", p);

Note that commas within an instruction in the list of tracepoint actions do 

not change the number of arguments to TRACE.  You can write any C 

statements in the list of tracepoint actions.  Make sure, though, that you get 

enough parentheses at the end of the macro.  Without a trailing parenthesis, 

the C preprocessor will complain about the actual parameters to the macro 

being too long.

Statements in the list of tracepoint actions may even contain other macros. 

For example:

	TRACE("abc",TRACE("xyz",

		printf("abc and xyz both enabled\n")));

The TRACEB, TRACEN and TRACEX macros function similarly to the 

TRACE macroDthe TRACEN macro does not update count statistics, 

while the TRACEB macro is an entry macro and the TRACEX macro is an 

exit macro.

TRACEP, TRACEPB, TRACEPN and TRACEPX

The four members of the TRACEP family function just like the 

corresponding four members of the TRACE family except that the 

members of the TRACEP family print the name of the tracepoint, a colon 

and a space before executing the tracepoint actions.  This is often just what 

you want and it saves a little space in your program.  For example, the 

following two macros are exactly equivalent, except that the TRACEP 

macro takes less space:

	TRACE("daisy", printf("daisy: (arg: %d)\n", n));

	TRACEP("daisy", printf("(arg: %d\n", n));

In order to keep the names of the macros straight, it is useful to think of 

TRACE and TRACEP as separate families of macros.  In other words, the 

letter 'P' is  not  a suffix.  For example, there is a macro named TRACEPB 

but no macro named TRACEBP.

The SPP program uses TRACEPB macros to trace the arguments on entry 

to a function.  For example, SPP will insert a TRACEPB as shown:

	int example (char *s, int i, float f)

	{

		TRACEPB("example",

			printf("(%s, %d, %f)\n", s, i, f));

		...

	}

Other Tracepoint Actions

All the tracepoint actions shown so far have consisted of printf statements.  

While that is common, it is often useful to use other statements.  Sherlock 

is an open ended tool;  the following paragraphs discuss various kinds of 

statements that may be used inside macros.

fprintf statements: Useful for sending tracing output to someplace other 

than the console.  Note that output generated from macros is sent to the 

standard output stream so that if you redirect output using fprintf be sure to 

redirect the standard output stream as well.  For example:

	TRACE("mum", fprintf(out_file, "mum: (%s)\n", flower_name));

Function calls: Useful for printing the contents of complicated data 

structures.  This is an important benefitDyou can afford to create tracing 

tools that produce a lot of output, because they will be called only when 

needed.  You won't get swamped with unwanted output.

For example, suppose you have written a routine called print_vcs() which 

prints the contents of a complicated data structure.  You would want to 

control that routine by putting it in a Sherlock macro as follows:

	struct very_complicated_struct *vcsp;

	...

	TRACE("vcs2", print_vcs(vcsp));

Assignment statements: Useful for controlling debugging switches using 

command line arguments.  Use assignment statements with caution: they 

may produce unexpected results if you enable all tracepoints with a 

wildcard.  For example, suppose you have a variable called enable_pass2 

which controls whether your program will call a routine called pass2().  

You can disable that routine from the command line if you insert the 

following into your program:

	TRACE("no_pass2", enable_pass2 = FALSE);

Flow of control statements: These may sometimes be useful for altering the 

operation of your program while debugging.  Just as with assignment 

statements, use these kinds of statements with caution.  For example, you 

might want to set up a header for some kind of report as follows:

	TRACE("hdr", if(hdr= =NULL){hdr="Pre-Release Version";});

Other Sherlock macros: Sherlock macros may be nested.  This can be used 

to create levels of debugging.  Indeed, it is often helpful to have several 

tracepoints with the same name, e.g., v for verbose.  In the following 

example, the function named dump() is called only if both the verbose 

option and the dump_x option have been enabled.

	TRACEN("v", TRACE("dump_x", dump(x)));

The RETURN_xxx Family of Macros

There are eleven members of the RETURN_xxx family.  All are exit 

macros.  In addition to signaling the end of timing code, these macros take 

the place of return instructions.  There is one RETURN_xxx macro for 

each type that a function can return: char, double, float, int, long, unsigned 

int, unsigned long and void, and several additional macros for types that 

benefit from special formatting: bool, pointer and string.

The RETURN family consists of the following members: 

RETURN_BOOL, RETURN_CHAR, RETURN_DOUBLE, 

RETURN_FLOAT, RETURN_INT, RETURN_LONG, 

RETURN_UINT, RETURN_ULONG, RETURN_PTR, 

RETURN_STRING and RETURN_VOID.

All RETURN_xxx macros except RETURN_VOID take two arguments, 

the second of which is an expression of the type indicated by the macro.  

The expression is evaluated exactly once, regardless of whether the 

tracepoint is enabled.  If so, the macro prints out a message telling the 

value of the expression.  For example:

	RETURN_BOOL("begonia", 0);

The last example prints the following message if begonia is enabled:

	begonia: returns: FALSE

Here are some more examples:

	RETURN_VOID("void_function");

	RETURN_BOOL("boolean", pi = = 3);

	RETURN_CHAR("character", '@');

	RETURN_DOUBLE("double_precision", (double) sin(x));

	RETURN_FLOAT("floating_point", sin(pi/2.0));

	RETURN_INT("integer", floor(i));

	RETURN_UINT("unsigned_int", 0xffff);

	RETURN_ULONG("unsigned_long", 0xffff);

	RETURN_LONG("long", 0L);

	RETURN_PTR("pointer", malloc(255));

	RETURN_STRING("string", p -> name);

SPP will replace all return instructions by RETURN_xxx macros.  For 

example, the following instruction:

	return &array[25];

will be replaced by:

	RETURN_PTR(&array[25]);

SPP will generate RETURN_BOOL macros for all functions declared bool 

as long as the following typedef appears before the function:

	typedef int bool;

Be aware that SPP treats all pointers to char as being pointers to a valid 

string. This will cause problems in functions such as malloc() which return 

a pointer to char which may not be used as a string.  Change 

RETURN_STRING to RETURN_PTR in such cases.

Printing Statistics: SL_DUMP and SL_CLEAR

The SL_DUMP macro prints out a report of all statistics gathered so far. 

It takes no arguments and can be called at any time.  For example:

	SL_DUMP();

The report contains several columns. The tracepoints column is an 

alphabetized list of tracepoint names, the ticks column gives count statistics 

for each tracepoint name, the times1 column gives non-cumulative timing 

statistics, the times2 column gives cumulative timing statistics and the 

tracing column indicates whether the tracepoint was enabled at the time 

SL_DUMP was called.

The SL_CLEAR macro zeros all statistics.  Statistics are zeroed by 

SL_INIT so you normally don't need to use SL_CLEAR.  It might be 

useful, though, if your program were divided into phases and you wanted 

to keep separate statistics for each phase.

Command Line Arguments

Any command line argument which starts either with the on_prefix or the 

off_prefix is interpreted as a command to enable or disable a tracepoint or 

group of tracepoints.  For example, suppose the program you are testing, 

called z, is usually invoked with two arguments as follows:

	z in out

To enable the tracepoint called abc, precede its name with the on_prefix, 

i.e., ++.  Like this:

	z ++abc in out

A Sherlock argument may appear anywhere on the command lineDits 

position relative to non-Sherlock arguments does not matter because 

SL_PARSE eliminates all Sherlock arguments from the argv vector.  As far 

as the rest of your program is concerned, the command line is: 

	z in out

Use the asterisk wildcard and question mark wildcard to select groups of 

tracepoints.  The asterisk (*) matches zero or more characters and the 

question mark (?) matches exactly one character.  For example, the 

following enables all tracepoint names that start with "abc" :

	z ++abc* in out

The following enables all tracepoint names that start with abc and contain 

exactly five letters:

	z ++abc?? in out

Any argument which starts with the off_prefix, i.e., '- -', disables one or 

more tracepoints.  Sherlock evaluates arguments from left to right, so that 

their order is significant.  The following enables all tracepoint names 

starting with abc except abc1:

	z ++abc* - -abc1 in out 

The following enables all tracepoint names starting with abc except those 

containing exactly five characters, and in addition the tracepoint named 

abc12 is also enabled:

	z ++abc* - -abc?? ++abc12 in out

It is easy to use wildcards to enable or disable groups of tracepoints if you 

name your breakpoints in a systematic manner.  A good scheme is to prefix 

all tracepoint names in a function with the name of that function.

The tracepoint name called "trace" is treated as a special case.  Disabling 

that tracepoint name disables all tracepoints.  For example, the following 

two command lines will produce identical results, but the first will execute 

more quickly than the second:

	z - -trace in out 

	z in out

Tracepoints can be re-enabled using the SL_PARSE or SL_ON macros, 

but beware of putting those macros inside some other macro, such as 

TRACE.  In other words, the following will not work if all tracing has 

been disabled:

	TRACE("any", SL_ON("*"));

You can temporarily disable a tracepoint by preceding its name with a 

disable count.  For example, the following will suppress the execution of 

the first 100 calls to the tracepoint called loop_trace, after which it will be 

enabled.

	z in out ++100loop_trace

You can temporarily disable all tracepoints (except STAT macros) by giving 

a global disable count, which is simply the on_prefix followed by a count.  

For example, the following will suppress all tracepoints until 1000 macros 

have been encountered, after which only abc will be enabled:

	z ++1000 ++abc in out

Beware of extra spaces in command line arguments.  Compare the 

following lines: 

	++99abc

	++99  abc