1
.\" @(#)user.r 1.13 10/29/86
3
.\" 2004-10-29: documented features implemented since 10/29/86
7
.\" DBUG (Macro Debugger Package) nroff source
9
.\" nroff -mm user.r >user.t
10
.\" groff -mm user.r >user.ps
12
.\" ===================================================
14
.\" === Some sort of black magic, but I forget...
16
.\" === Hyphenation control (1 = on)
18
.\" === Force all first level headings to start on new page
20
.\" === Set for breaks after headings for levels 1-3
22
.\" === Set for space after headings for levels 1-3
24
.\" === Set standard indent for one/half inch
26
.\" === Set page header
27
.PH "/DBUG User Manual//\*(DT/"
28
.\" === Set page footer
30
.\" === Set page offset
32
.\" === Set line length
37
C Program Debugging Package
43
.\" === All paragraphs indented.
46
This document introduces
48
a macro based C debugging
49
package which has proven to be a very flexible and useful tool
50
for debugging, testing, and porting C programs.
53
All of the features of the
55
package can be enabled or disabled dynamically at execution time.
56
This means that production programs will run normally when
57
debugging is not enabled, and eliminates the need to maintain two
58
separate versions of a program.
61
Many of the things easily accomplished with conventional debugging
62
tools, such as symbolic debuggers, are difficult or impossible with this
63
package, and vice versa.
68
be thought of as a replacement or substitute for
69
other debugging tools, but simply as a useful
72
program development and maintenance environment.
82
Almost every program development environment worthy of the name
83
provides some sort of debugging facility.
84
Usually this takes the form of a program which is capable of
85
controlling execution of other programs and examining the internal
86
state of other executing programs.
87
These types of programs will be referred to as external debuggers
88
since the debugger is not part of the executing program.
89
Examples of this type of debugger include the
93
debuggers provided with the
96
UNIX is a trademark of AT&T Bell Laboratories.
101
One of the problems associated with developing programs in an environment
102
with good external debuggers is that developed programs tend to have
103
little or no internal instrumentation.
104
This is usually not a problem for the developer since he is,
105
or at least should be, intimately familiar with the internal organization,
106
data structures, and control flow of the program being debugged.
107
It is a serious problem for maintenance programmers, who
108
are unlikely to have such familiarity with the program being
109
maintained, modified, or ported to another environment.
110
It is also a problem, even for the developer, when the program is
111
moved to an environment with a primitive or unfamiliar debugger,
117
is an example of an internal debugger.
118
Because it requires internal instrumentation of a program,
119
and its usage does not depend on any special capabilities of
120
the execution environment, it is always available and will
121
execute in any environment that the program itself will
123
In addition, since it is a complete package with a specific
124
user interface, all programs which use it will be provided
125
with similar debugging capabilities.
126
This is in sharp contrast to other forms of internal instrumentation
127
where each developer has their own, usually less capable, form
128
of internal debugger.
132
is an internal debugger it provides consistency across operating
134
and because it is available to all developers it provides
135
consistency across all programs in the same environment.
140
package imposes only a slight speed penalty on executing
141
programs, typically much less than 10 percent, and a modest size
142
penalty, typically 10 to 20 percent.
143
By defining a specific C preprocessor symbol both of these
144
can be reduced to zero with no changes required to the
148
The following list is a quick summary of the capabilities
152
Each capability can be individually enabled or disabled
153
at the time a program is invoked by specifying the appropriate
154
command line arguments.
158
Execution trace showing function level control flow in a
159
semi-graphically manner using indentation to indicate nesting
162
Output the values of all, or any subset of, key internal variables.
164
Limit actions to a specific set of named functions.
166
Limit function trace to a specified nesting depth.
168
Label each output line with source file name and line number.
170
Label each output line with name of current process.
172
Push or pop internal debugging state to allow execution with
173
built in debugging defaults.
175
Redirect the debug output stream to standard output (stdout)
177
The default output stream is standard error (stderr).
178
The redirection mechanism is completely independent of
179
normal command line redirection to avoid output conflicts.
184
PRIMITIVE DEBUGGING TECHNIQUES
188
Internal instrumentation is already a familiar concept
189
to most programmers, since it is usually the first debugging
191
Typically, "print\ statements" are inserted in the source
192
code at interesting points, the code is recompiled and executed,
193
and the resulting output is examined in an attempt to determine
194
where the problem is.
196
The procedure is iterative, with each iteration yielding more
197
and more output, and hopefully the source of the problem is
198
discovered before the output becomes too large to deal with
199
or previously inserted statements need to be removed.
200
Figure 1 is an example of this type of primitive debugging
212
Primitive Debugging Technique
218
Eventually, and usually after at least several iterations, the
219
problem will be found and corrected.
220
At this point, the newly inserted print statements must be
222
One obvious solution is to simply delete them all.
223
Beginners usually do this a few times until they have to
224
repeat the entire process every time a new bug pops up.
225
The second most obvious solution is to somehow disable
226
the output, either through the source code comment facility,
227
creation of a debug variable to be switched on or off, or by using the
229
Figure 2 is an example of all three techniques.
240
Debug Disable Techniques
246
Each technique has its advantages and disadvantages with respect
247
to dynamic vs static activation, source code overhead, recompilation
248
requirements, ease of use, program readability, etc.
249
Overuse of the preprocessor solution quickly leads to problems with
250
source code readability and maintainability when multiple
252
symbols are to be defined or undefined based on specific types
254
The source code can be made slightly more readable by suitable indentation
257
arguments to match the indentation of the code, but
258
not all C preprocessors allow this.
259
The only requirement for the standard
261
C preprocessor is for the '#' character to appear
262
in the first column, but even this seems
263
like an arbitrary and unreasonable restriction.
264
Figure 3 is an example of this usage.
275
More Readable Preprocessor Usage
282
FUNCTION TRACE EXAMPLE
286
We will start off learning about the capabilities of the
288
package by using a simple minded program which computes the
289
factorial of a number.
290
In order to better demonstrate the function trace mechanism, this
291
program is implemented recursively.
292
Figure 4 is the main function for this factorial program.
303
Factorial Program Mainline
311
function is responsible for processing any command line
312
option arguments and then computing and printing the factorial of
313
each non-option argument.
315
First of all, notice that all of the debugger functions are implemented
316
via preprocessor macros.
317
This does not detract from the readability of the code and makes disabling
318
all debug compilation trivial (a single preprocessor symbol,
320
forces the macro expansions to be null).
322
Also notice the inclusion of the header file
324
from the local header file directory.
325
(The version included here is the test version in the dbug source
326
distribution directory).
327
This file contains all the definitions for the debugger macros, which
334
macro informs that debugger that we have entered the
337
It must be the very first "executable" line in a function, after
338
all declarations and before any other executable line.
341
macro is generally used only once per program to
342
inform the debugger what name the program was invoked with.
345
macro modifies the current debugger state by
346
saving the previous state and setting a new state based on the
347
control string passed as its argument.
350
macro is used to print the values of each argument
351
for which a factorial is to be computed.
354
macro tells the debugger that the end of the current
355
function has been reached and returns a value to the calling
357
All of these macros will be fully explained in subsequent sections.
359
To use the debugger, the factorial program is invoked with a command
362
\fCfactorial -#d:t 1 2 3
366
function recognizes the "-#d:t" string as a debugger control
367
string, and passes the debugger arguments ("d:t") to the
369
runtime support routines via the
372
This particular string enables output from the
374
macro with the 'd' flag and enables function tracing with the 't' flag.
375
The factorial function is then called three times, with the arguments
377
Note that the DBUG_PRINT takes exactly
379
arguments, with the second argument (a format string and list
380
of printable values) enclosed in parentheses.
382
Debug control strings consist of a header, the "-#", followed
383
by a colon separated list of debugger arguments.
384
Each debugger argument is a single character flag followed
385
by an optional comma separated list of arguments specific
391
-#d,in,out:f,main:F:L
393
Note that previously enabled debugger actions can be disabled by the
397
The definition of the factorial function, symbolized as "N!", is
400
N! = N * N-1 * ... 2 * 1
402
Figure 5 is the factorial function which implements this algorithm
404
Note that this is not necessarily the best way to do factorials
405
and error conditions are ignored completely.
422
One advantage (some may not consider it so) to using the
424
package is that it strongly encourages fully structured coding
425
with only one entry and one exit point in each function.
426
Multiple exit points, such as early returns to escape a loop,
427
may be used, but each such point requires the use of an
435
To build the factorial program on a
438
link with the command:
440
\fCcc -o factorial main.c factorial.c -ldbug
442
The "-ldbug" argument tells the loader to link in the
443
runtime support modules for the
446
Executing the factorial program with a command of the form:
448
\fCfactorial 1 2 3 4 5
450
generates the output shown in figure 6.
461
\fCfactorial 1 2 3 4 5
467
Function level tracing is enabled by passing the debugger
468
the 't' flag in the debug control string.
469
Figure 7 is the output resulting from the command
470
"factorial\ -#t:o\ 2\ 3".
481
\fCfactorial -#t:o 2 3
487
Each entry to or return from a function is indicated by '>' for the
488
entry point and '<' for the exit point, connected by
489
vertical bars to allow matching points to be easily found
490
when separated by large distances.
493
This trace output indicates that there was an initial call
494
to factorial from main (to compute 2!), followed by
495
a single recursive call to factorial to compute 1!.
496
The main program then output the result for 2! and called the
497
factorial function again with the second argument, 3.
498
Factorial called itself recursively to compute 2! and 1!, then
499
returned control to main, which output the value for 3! and exited.
502
Note that there is no matching entry point "main>" for the
503
return point "<main" because at the time the
505
macro was reached in main, tracing was not enabled yet.
506
It was only after the macro
508
was executing that tracing became enabled.
509
This implies that the argument list should be processed as early as
510
possible since all code preceding the first call to
513
essentially invisible to
515
(this can be worked around by
516
inserting a temporary
517
.B DBUG_PUSH(argv[1])
518
immediately after the
519
.B DBUG_ENTER("main")
524
the trace output normally comes out on the standard error.
525
Since the factorial program prints its result on the standard
526
output, there is the possibility of the output on the terminal
527
being scrambled if the two streams are not synchronized.
528
Thus the debugger is told to write its output on the standard
529
output instead, via the 'o' flag character.
530
Note that no 'o' implies the default (standard error), a 'o'
531
with no arguments means standard output, and a 'o'
532
with an argument means used the named file.
533
i.e, "factorial\ -#t:o,logfile\ 3\ 2" would write the trace
537
implementation details, programs usually run
538
faster when writing to stdout rather than stderr, though this
539
is not a prime consideration in this example.
543
USE OF DBUG_PRINT MACRO
547
The mechanism used to produce "printf" style output is the
552
To allow selection of output from specific macros, the first argument
558
When this keyword appears in the argument list of the 'd' flag in
559
a debug control string, as in "-#d,keyword1,keyword2,...:t",
560
output from the corresponding macro is enabled.
561
The default when there is no 'd' flag in the control string is to
562
enable output from all
567
Typically, a program will be run once, with no keywords specified,
568
to determine what keywords are significant for the current problem
569
(the keywords are printed in the macro output line).
570
Then the program will be run again, with the desired keywords,
571
to examine only specific areas of interest.
574
The second argument to a
576
macro is a standard printf style
577
format string and one or more arguments to print, all
578
enclosed in parentheses so that they collectively become a single macro
580
This is how variable numbers of printf arguments are supported.
581
Also note that no explicit newline is required at the end of the format string.
582
As a matter of style, two or three small
584
macros are preferable
585
to a single macro with a huge format string.
586
Figure 8 shows the output for default tracing and debug.
597
\fCfactorial -#d:t:o 3
605
macro is indented to match the trace output
606
for the function in which the macro occurs.
607
When debugging is enabled, but not trace, the output starts at the left
608
margin, without indentation.
611
To demonstrate selection of specific macros for output, figure
612
9 shows the result when the factorial program is invoked with
613
the debug control string "-#d,result:o".
624
\fCfactorial -#d,result:o 4
630
It is sometimes desirable to restrict debugging and trace actions
631
to a specific function or list of functions.
632
This is accomplished with the 'f' flag character in the debug
634
Figure 10 is the output of the factorial program when run with the
635
control string "-#d:f,factorial:F:L:o".
636
The 'F' flag enables printing of the source file name and the 'L'
637
flag enables printing of the source file line number.
648
\fCfactorial -#d:f,factorial:F:L:o 3
654
The output in figure 10 shows that the "find" macro is in file
655
"factorial.c" at source line 8 and the "result" macro is in the same
656
file at source line 12.
664
This section summarizes the usage of all currently defined macros
668
The macros definitions are found in the user include file
670
from the standard include directory.
675
Used to tell the runtime support module the name of the function being
676
entered. The argument must be of type "pointer to character". The
677
DBUG_ENTER macro must precede all executable lines in the function
678
just entered, and must come after all local declarations. Each
679
DBUG_ENTER macro must have a matching DBUG_RETURN or DBUG_VOID_RETURN
680
macro at the function exit points. DBUG_ENTER macros used without a
681
matching DBUG_RETURN or DBUG_VOID_RETURN macro will cause warning
684
package runtime support module.
686
EX:\ \fCDBUG_ENTER\ ("main");\fR
689
Used at each exit point of a function containing a DBUG_ENTER macro at
690
the entry point. The argument is the value to return. Functions
691
which return no value (void) should use the DBUG_VOID_RETURN macro.
692
It is an error to have a DBUG_RETURN or DBUG_VOID_RETURN macro in a
693
function which has no matching DBUG_ENTER macro, and the compiler will
694
complain if the macros are actually used (expanded).
696
EX:\ \fCDBUG_RETURN\ (value);\fR
698
EX:\ \fCDBUG_VOID_RETURN;\fR
701
Used to name the current process being executed.
702
A typical argument for this macro is "argv[0]", though
703
it will be perfectly happy with any other string.
704
Im multi-threaded environment threads may have different names.
706
EX:\ \fCDBUG_PROCESS\ (argv[0]);\fR
709
Sets a new debugger state by pushing the current
711
state onto an internal stack and setting up the new state using the
712
debug control string passed as the macro argument. The most common
713
usage is to set the state specified by a debug control string
714
retrieved from the argument list. If the control string is
716
the new state is a copy of the old state, modified by the control
719
EX:\ \fCDBUG_PUSH\ (\&(argv[i][2]));\fR
721
EX:\ \fCDBUG_PUSH\ ("d:t");\fR
723
EX:\ \fCDBUG_PUSH\ ("");\fR
726
Restores the previous debugger state by popping the state stack.
727
Attempting to pop more states than pushed will be ignored and no
728
warning will be given. The DBUG_POP macro has no arguments.
730
EX:\ \fCDBUG_POP\ ();\fR
733
Modifies the current debugger state on top of the stack or pushes
734
a new state if the current is set to the initial settings, using
735
the debug control string passed as the macro argument. Unless
737
control string is used (see below), it's equivalent to a combination of
738
DBUG_POP and DBUG_PUSH.
740
EX:\ \fCDBUG_SET\ ("d:t");\fR
742
EX:\ \fCDBUG_SET\ ("+d,info");\fR
744
EX:\ \fCDBUG_SET\ ("+t:-d");\fR
747
The DBUG_FILE macro is used to do explicit I/O on the debug output
748
stream. It is used in the same manner as the symbols "stdout" and
749
"stderr" in the standard I/O package.
751
EX:\ \fCfprintf\ (DBUG_FILE,\ "Doing\ my\ own\ I/O!\\n");\fR
754
The DBUG_EXECUTE macro is used to execute any arbitrary C code. The
755
first argument is the debug keyword, used to trigger execution of the
756
code specified as the second argument. This macro must be used
757
cautiously because, like the DBUG_PRINT macro, it is automatically
758
selected by default whenever the 'd' flag has no argument list (i.e.,
759
a "-#d:t" control string).
761
EX:\ \fCDBUG_EXECUTE\ ("status",\ print_status\ ());\fR
764
Works like DBUG_EXECUTE macro, but the code is
766
executed "by default", if the keyword is not explicitly listed in
767
the 'd' flag. Used to conditionally execute "dangerous" actions, e.g
768
to crash the program testing how recovery works, or to introduce an
769
artificial delay checking for race conditions.
771
EX:\ \fCDBUG_EXECUTE_IF\ ("crashme",\ abort\ ());\fR
774
The DBUG_EVALUATE macro is similar to DBUG_EXECUTE, but it can be used in
775
the expression context. The first argument is the debug keyword that is used to
776
choose whether the second (keyword is enabled) or the third (keyword is not
777
enabled) argument is evaluated. When
779
is compiled off, the third argument is evaluated.
783
printf("Info-debug is %s",
785
DBUG_EVALUATE\ ("info", "ON", "OFF"));\fR
787
.LI DBUG_EVALUATE_IF\
788
Works like DBUG_EVALUATE macro, but the second argument is
790
evaluated, if the keyword is not explicitly listed in
791
the 'd' flag. Like DBUG_EXECUTE_IF this could be used to conditionally execute
796
if (prepare_transaction () ||
798
DBUG_EVALUATE ("crashme", (abort (), 0), 0) ||
800
commit_transaction () )\fR
803
Used to do printing via the "fprintf" library function on the current
804
debug stream, DBUG_FILE. The first argument is a debug keyword, the
805
second is a format string and the corresponding argument list. Note
806
that the format string and argument list are all one macro argument
809
be enclosed in parentheses.
811
EX:\ \fCDBUG_PRINT\ ("eof",\ ("end\ of\ file\ found"));\fR
813
EX:\ \fCDBUG_PRINT\ ("type",\ ("type\ is\ %x", type));\fR
815
EX:\ \fCDBUG_PRINT\ ("stp",\ ("%x\ ->\ %s", stp, stp\ ->\ name));\fR
818
Used to dump a memory block in hex via the "fprintf" library function
819
on the current debug stream, DBUG_FILE. The first argument is a debug
820
keyword, the second is a pointer to a memory to dump, the third is a
821
number of bytes to dump.
823
EX: \fCDBUG_DBUG\ ("net",\ packet,\ len);\fR
826
Used in place of the setjmp() function to first save the current
827
debugger state and then execute the standard setjmp call.
828
This allows to the debugger to restore its state when the
829
DBUG_LONGJMP macro is used to invoke the standard longjmp() call.
830
Currently all instances of DBUG_SETJMP must occur within the
831
same function and at the same function nesting level.
833
EX: \fCDBUG_SETJMP\ (env);\fR
836
Used in place of the longjmp() function to first restore the
837
previous debugger state at the time of the last DBUG_SETJMP
838
and then execute the standard longjmp() call.
839
Note that currently all DBUG_LONGJMP macros restore the state
840
at the time of the last DBUG_SETJMP.
841
It would be possible to maintain separate DBUG_SETJMP and DBUG_LONGJMP
842
pairs by having the debugger runtime support module use the first
843
argument to differentiate the pairs.
845
EX: \fCDBUG_LONGJMP\ (env,val);\fR
848
Used in multi-threaded environment to lock DBUG_FILE stream.
849
It can be used, for example, in functions that need to write something to a
850
debug stream more than in one fprintf() call and want to ensure that no other
851
thread will write something in between.
857
fprintf (DBUG_FILE, "a=[");
859
for (int i=0; i < a_length; i++)
861
fprintf (DBUG_FILE, "0x%03x ", a[i]);
863
fprintf (DBUG_FILE, "]");
867
.LI DBUG_UNLOCK_FILE\
868
Unlocks DBUG_FILE stream, that was locked with a DBUG_LOCK_FILE.
870
This macro just does a regular assert(). The difference is that it will be
871
disabled by DBUG_OFF togeher with the
873
library. So there will be no need to disable asserts separately with NDEBUG.
875
EX:\ \fCDBUG_ASSERT(\ a\ >\ 0\ );\fR
878
Generates control string corresponding to the current debug state.
879
The macro takes two arguments - a buffer to store the result string
880
into and its length. The macro (which could be used as a function)
881
returns 1 if the control string didn't fit into the buffer and was
882
truncated and 0 otherwise.
888
DBUG_EXPLAIN( buf, sizeof(buf) );\fR
890
.LI DBUG_SET_INITIAL\
891
.LI DBUG_EXPLAIN_INITIAL\
893
These two macros are identical to DBUG_SET and DBUG_EXPLAIN, but they
894
operate on the debug state that any new thread starts from.
897
value does not affect threads that are already running. Obviously,
898
these macros are only useful in the multi-threaded environment.
907
The debug control string is used to set the state of the debugger
912
macros. Control string consists of colon separate flags. Colons
913
that are part of ':\\', ':/', or '::' are not considered flag
914
separators. A flag may take an argument or a list of arguments.
915
If a control string starts from a '+' sign it works
917
that is, it can modify existing state without overriding it. In such a
918
string every flag may be preceded by a '+' or '-' to enable or disable
919
a corresponding option in the debugger state. This section summarizes
920
the currently available debugger options and the flag characters which
921
enable or disable them. Argument lists enclosed in '[' and ']' are
926
Redirect the debugger output stream and append it to the specified
927
file. The default output stream is stderr. A null argument list
928
causes output to be redirected to stdout.
930
EX: \fCa,C:\\tmp\\log\fR
932
Like 'a[,file]' but ensure that data are written after each write
933
(this typically implies flush or close/reopen). It helps to get
934
a complete log file in case of crashes. This mode is implicit in
935
multi-threaded environment.
937
Enable output from macros with specified keywords.
938
An empty list of keywords implies that all keywords are selected.
940
Delay for specified time after each output line, to let output drain.
941
Time is given in tenths of a second (value of 10 is one second).
944
Limit debugger actions to the specified list of functions.
945
An empty list of functions implies that all functions are selected.
947
Mark each debugger output line with the name of the source file
948
containing the macro causing the output.
950
Mark each debugger output line with the PID (or thread ID) of the
953
Enable profiling for the specified list of functions.
954
An empty list of functions enables profiling for all functions.
956
.B PROFILING\ WITH\ DBUG
959
Mark each debugger output line with the source file line number of
960
the macro causing the output.
962
Mark each debugger output line with the current function nesting depth.
964
Sequentially number each debugger output line starting at 1.
965
This is useful for reference purposes when debugger output is
966
interspersed with program output.
968
Like 'a[,file]' but overwrite old file, do not append.
970
Like 'A[,file]' but overwrite old file, do not append.
972
Limit debugger actions to the specified processes. An empty list
973
implies all processes. This is useful for processes which run child
974
processes. Note that each debugger output line can be marked with the
975
name of the current process via the 'P' flag. The process name must
976
match the argument passed to the
980
Mark each debugger output line with the name of the current process.
981
Most useful when used with a process which runs child processes that
982
are also being debugged. Note that the parent process must arrange
983
for the debugger control string to be passed to the child processes.
985
Used in conjunction with the
987
macro to reset the current
988
indentation level back to zero.
991
macros used to temporarily alter the
996
this flag forces "sanity" memory checks (for overwrites/underwrites)
1002
Enable function control flow tracing.
1003
The maximum nesting depth is specified by N, and defaults to
1006
Mark each debugger output line with the current timestamp.
1007
The value is printed with microsecond resolution, as returned by
1009
system call. The actual resolution is OS- and hardware-dependent.
1014
MULTI-THREADED DEBUGGING
1020
is used in a multi-threaded environment there are few differences from a single-threaded
1021
case to keep in mind. This section tries to summarize them.
1025
Every thread has its own stack of debugger states.
1029
affect only the thread that executed them.
1031
At the bottom of the stack for all threads there is the common
1033
state. Changes to this state (for example, with
1035
macro) affect all new threads and all running threads that didn't
1039
Every thread can have its own name, that can be set with
1041
macro. Thus, "-#p,name1,name2" can be used to limit the output to specific threads.
1043
When printing directly to
1045
it may be necessary to prevent other threads from writing something between two parts
1046
of logically indivisible output. It is done with
1050
macors. See the appropriate section for examples.
1052
"-#o,file" and "-#O,file" are treated as "-#a,file" and "-#A,file" respectively. That is
1053
all writes to a file are always followed by a flush.
1055
"-#i" prints not a PID but a thread id in the form of "T@nnn"
1066
one can do profiling in a machine independent fashion,
1067
without a need for profiled version of system libraries.
1070
can write out a file
1073
(by default). This is an ascii file containing lines of the form:
1075
\fC<function-name> E <time-entered>
1076
<function-name> X <time-exited>
1080
A second program (\fBanalyze\fR) reads this file, and produces a report on
1084
Profiling is enabled through the
1086
flag. It can take a list of
1087
function names for which profiling is enabled. By default, it
1088
profiles all functions.
1091
The profile file is opened for appending. This
1092
is in order that one can run a program several times, and get the
1093
sum total of all the times, etc.
1096
An example of the report generated follows:
1099
Profile of Execution
1100
Execution times are in milliseconds
1104
Times Percentage Time Spent Percentage
1105
Function Called of total in Function of total Importance
1106
======== ====== ========== =========== ========== ==========
1107
factorial 5 83.33 30 100.00 8333
1108
main 1 16.67 0 0.00 0
1109
======== ====== ========== =========== ==========
1110
Totals 6 100.00 30 100.00
1113
As you can see, it's quite self-evident. The
1116
metric obtained by multiplying the percentage of the calls and the percentage
1117
of the time. Functions with higher 'importance' benefit the most from
1121
As a limitation - setjmp/longjmp, or child processes, are ignored
1122
for the time being. Also, profiling does not work
1123
in a multi-threaded environment.
1126
Profiling code is (c) Binayak Banerjee.
1130
HINTS AND MISCELLANEOUS
1134
One of the most useful capabilities of the
1136
package is to compare the executions of a given program in two
1137
different environments.
1138
This is typically done by executing the program in the environment
1139
where it behaves properly and saving the debugger output in a
1141
The program is then run with identical inputs in the environment where
1142
it misbehaves and the output is again captured in a reference file.
1143
The two reference files can then be differentially compared to
1144
determine exactly where execution of the two processes diverges.
1147
A related usage is regression testing where the execution of a current
1148
version is compared against executions of previous versions.
1149
This is most useful when there are only minor changes.
1152
It is not difficult to modify an existing compiler to implement
1153
some of the functionality of the
1155
package automatically, without source code changes to the
1156
program being debugged.
1157
In fact, such changes were implemented in a version of the
1158
Portable C Compiler by the author in less than a day.
1159
However, it is strongly encouraged that all newly
1160
developed code continue to use the debugger macros
1161
for the portability reasons noted earlier.
1162
The modified compiler should be used only for testing existing
1173
package works best with programs which have "line\ oriented"
1174
output, such as text processors, general purpose utilities, etc.
1175
It can be interfaced with screen oriented programs such as
1176
visual editors by redefining the appropriate macros to call
1177
special functions for displaying the debugger results.
1178
Of course, this caveat is not applicable if the debugger output
1179
is simply dumped into a file for post-execution examination.
1182
Programs which use memory allocation functions other than
1184
will usually have problems using the standard
1187
The most common problem is multiply allocated memory.
1189
.\" .DE nroff dident like this. davida 900108
1192
.\" vim:filetype=nroff
added
removed
dbug/user.r
