 |
Index for
Section 1 |
|
 |
Alphabetical
listing for T |
|
 |
Bottom of
page |
|
third(1)
NAME
third - Third Degree: heap usage and leak profiler, and memory-access error
checker for C and C++ programs.
SYNOPSIS
third [-pthread] [-fork] [-invalid] [-uninit heap+stack+...] [-hide n] [-g]
[option...] program [argument...]
See the start of the OPTIONS section below for details of Third Degree
options that may be essential for the correct execution of the program.
The atom -tool third interface is still available, for compatibility with
earlier releases. However, it is now undocumented, and it will be retired
in a future release.
DESCRIPTION
See prof_intro(1) for an introduction to the application performance tuning
tools provided with Tru64 UNIX.
Third Degree (third) creates an instrumented version of a debuggable C or
C++ program (naming it program.third) that, by default, produces a log file
of stack traces for places where heap memory was allocated and subsequently
leaked during a test run of the instrumented program.
If you specify program arguments (argument...) or -run, the instrumented
program is executed also. If you specify -display, more is run afterwards
to display the log file. If the program name is omitted, a usage message
is printed.
For example, to instrument, run, and display the leaks in a multi-threaded
program:
cc -g -pthread -o program *.c
third -pthread -display program data/*
Specify -all or -incobj to report stack traces that lead through shared
libraries and to check memory references made by the shared libraries.
Specify -hide 0 if you need to see reports of problems in code that was not
compiled -g or -g1. Specify -g to keep debug information, so that the
instrumented program can be debugged.
To check for leaks at times before program exit, specify -before proc or
-after proc, which trigger a check when the procedure proc executes.
To check the program for access to invalid addresses within the stack and
heap areas, specify the -invalid option, and see the messages in the log
file.
To check the program for reading variables that have not been initialized,
specify the -uninit option with a value of at least heap, stack, or
heap+stack. This option may cause the instrumented program to malfunction,
because it poisons all uninitialized memory with an unusual value --
0xfff8a5a5. This can be used to advantage by running regression tests on
the instrumented program and comparing its results with those that were
expected. Use the -quiet option to suppress the usual informational
messages, or just manually run the program.third file for each test after
instrumenting it once (for example, without the -run option or program
arguments):
third -quiet program -uninit h+s -inv program data/* | diff benchmark -
The pixie -testcoverage command can be used to list which source lines were
not exercised (and therefore not checked) by the regression tests.
An alternative display technique for -invalid and -uninit errors is to give
the log file to emacs as if it contained compiler diagnostics. This enables
emacs to place its cursor on the source line referenced by each error
message in turn:
xemacs (run xemacs in working directory)
ESC-x compile (or click the "Compile" button in xemacs)
cat program.3log (changed from "make -k")
CTL-x ` (place cursor on code for next error - repeat)
OPERANDS
program
File name of a fully linked call-shared or nonshared executable to be
profiled. This program should be compiled with the -g or -g2 option to
obtain the most complete error reports and profiles.In particular,
errors in code compiled with the default -g0 option are usually not
reported unless the -hide 0 option is specified, and line numbers,
static procedure names, and file names are unavailable. If -g1 was
used, variable names are unavailable. Inlined procedures are not
displayed separate from their callers, so they are best
avoided.Programs that are stripped or are optimized by spike or cc -om
are not supported.
argument
All arguments following the program name are considered to be arguments
needed by the instrumented program to execute the procedures, lines,
and instructions of interest. Multiple arguments can be specified. They
imply -run if any are specified, and they can be replaced by -run if
none are needed.
OPTIONS
Options can be abbreviated to three characters, option keyword values to
one.
Essential Options
Some or all of these options may be needed to prevent the instrumented
program from malfunctioning:
-pthread
Specify -pthread if the program or any of its libraries calls
pthread_create(3), for example if it was compiled with either the
-pthread option or the -threads compatibility option. This will make
the log file reporting thread-safe.
-fork
Specify -fork if the program calls any variant of fork(2). It is not
usually needed if the subprocesses also call any variant of exec(2).
The -fork option ensures that forked multi-threaded programs are
profiled in a thread-safe way, and it produces separate log files for
the forked subprocesses, including the process id in their file names
as if -pids was specified. Failure to use -fork might lead to deadlock
in the forked child processes.
-heapbase addr|taso
The heap space for the program being analysed is located at the usual
address, immediately following the program's static data. By default,
any heap space needed by Third Degree's run-time analysis code is
located separately, starting at the address 38000000000. If the program
needs to use this address range, use -heapbase to tell third to use
memory at a specific hexadecimal address (for example, 10000) or taso
for the default 31-bit address (if the program was linked with the
-taso option).
-mapbase addr
By default, third memory maps large areas between address 3c000000000
and 3ff00000000. If the program needs to use this address range, use
-mapbase to specify what address (for example, 10000) third can map.
-signals
Disables third's handling of signals SIGILL, SIGTRAP, SIGABRT, SIGEMT,
SIGFPE, SIGBUS, SIGSEGV, SIGSYS, SIGXCPU, and SIGXFSZ. Also disables
reports of reentrant calls to heap management routines (malloc, free,
and so on) from signal handlers; may avoid deadlock in applications
that make significant use of signal handlers. This option can not be
used with the -before or -after options for leak detection and heap
tracing.
File Generating Options
-quiet
Does not print informational and progress messages on the standard
error stream.
-v Prints the command lines used to instrument the program and to execute
the instrumented program.
-output file
Names the instrumented program file instead of the default
program.third.
-dirname path
Specifies the directory to which the instrumented program writes the
log file(s) for each test run. The default is the current directory.
-pids
Adds the process-id of the instrumented program's test run to the name
of the log file produced (that is, program.pid.3log). By default, the
file is named program.3log, but the process-id is always included for
the log files of forked subprocesses.
Stack-Trace Generating Options
-use path
Searches for source files in the specified directory when printing
their names in stack traces in the log file.
-depth n
When distinguishing different heap allocation calls, considers only the
top n procedures on the program's call stack--for example, when memory
is allocated by a common procedure that is called by many others. The
default stack depth is 200.
-hide n
Controls the degree to which error reports for system libraries and
other non-debuggable code are hidden (that is, not printed). By
default, n=2, so errors in code compiled with -g0 are not reported
unless one of the next two stack frames has debuggable code. Values of
n>2 request printing of errors deeper into non-debuggable code. Use
-hide 0 to request that all errors be printed, if you need to debug
code that was compiled with -g0, but note that this may yield a large
number of spurious errors for system library routines (which should be
ignored).
Heap History Options
-history
Displays the usage of each block of memory allocated in the heap
(grouped by similar allocation-site stack trace). Each 32-bit word of
the first 1024 bytes is classified as one of the following: never
written, always zero, a pointer, sometimes a pointer, or non-zero non-
pointer.
-size n
Classifies the first n bytes of each heap object, instead of the 1024
bytes selected by the -history option.
Leak Detection and Heap Tracing Options
-blocks cancel
Cancels the default -blocks new -after exit heap scan.
-blocks new|all
Specifies that each of the following -before or -after options will
trigger a heap scan that will print the stack trace of the allocation
of: (1) each heap leak--a heap block that is no longer referenced by
any active stack variable, static variable, or non-leak heap object;
(2) each heap object--a heap block that has not been deallocated but is
still referenced.
Leak reports also distinguish leaks that are not referenced by other
leaks. They are often the root of a tree or otherwise the cause of many
other leaks.
Reports of new leaks or objects include only those that occurred since
the last scan.
The alternative options -leaks new|all and -objects new|all can be used
to select reports of just leaks or just objects, but note that Third
Degree may not distinguish between the referenced and unreferenced heap
blocks reported by -blocks appropriately for some applications.
-every n
Specifies that each of the following -before or -after options will
trigger a heap scan every n calls to the named procedure, instead of
the default n = 1.
-before|-after proc
Triggers a heap scan at calls to (-before) or returns from (-after) the
procedure proc, of the type defined by the last -blocks, -leaks, or
-objects option, and of the frequency defined by the last -every
option. If the named procedure is in a shared library, that shared
library must be instrumented for the scan to be triggered. Specify -all
or -incobj to instrument the shared library; but note that, in a
multi-threaded program, -after exit is the only trigger possible for
system library procedures, because libpthread and the libraries it uses
are always excluded from instrumentation. See the -ignore option for
use of the wildcard character (*) in the procedure name.
-min %
Leaks or objects that comprise less than the specified percentage (%)
of the total leaked or allocated heap will be reported as a single
subtotal, instead of being described individually. The default is 1.0
-mask addr
During a heap scan, words of memory will be masked with the specified
hexadecimal value addr before being matched against the existing
address ranges of heap objects, to allow for non-address information
being encoded in unused bits of pointer values. The default mask is
ffffffffffffffff, meaning the whole value is used.
Heap Management Options
-free n
The last n bytes of freed heap objects are kept in a queue instead of
being returned to the heap's free pool, as a means of trapping code
that accesses heap memory after it has been freed. By default,
1,000,000 bytes of freed objects are kept in this queue.
If the program allocated memory blocks larger than a million bytes, the
-free option should specify a size larger than the largest block to
ensure complete reporting of deallocation errors.
-pad n
Adds n bytes of memory to the end of each allocated heap object, so
that the -invalid option can report overrun errors. The default padding
is 16 bytes.
Memory Access Error Debugging Options
-g Runs the instrumented program under the control of the dbx debugger,
instead of simply executing it. Usually, the procedure names, source
file names, and line numbers in the log file are sufficient to show the
location of a memory access error. However, if the procedure was not
instrumented, no report can be printed in the log file; and if the
procedure was not compiled -g, the relevant variable name, file name,
and line number can not be printed. In these cases, the debugger can be
used to examine further - for example, to look for the poisoned memory
values in variables and registers after a segmentation fault.
This option implies the -leaks cancel option, and if any -before and
-after options are specified, dbx will ignore SEGV, so checking for
leaks in separate non-debugging test runs is recommended.
The ladebug debugger can also be run on a program instrumented with -g,
if it is installed on the system.
-invalid
Reports any attempt to access memory in a heap or stack area that is
out of bounds for application code. For example, the heap's free space
data or reserved parts of a stack frame. Addresses that are not in the
stack or heap (for example, memory mapped) are not checked.
-uninit heap+stack+repeat+copy+value=hex
Reports any attempt to read memory in a heap or stack area that has not
previously been initialized by application code or by calloc. Note that
this feature poisons all heap and/or stack memory (as selected) with
the value fff8a5a5, which will cause a SEGV signal if used as a pointer
or a NaN exception if used as a floating point number, and which is
likely to cause the program to malfunction otherwise. The problem in
the program must be corrected before third's analysis can continue. The
error reports in the log file and the -g option can help locate the
cause of the problem. The cc -trapuv command offers a similar but
simpler capability for stack variables, without the need for
instrumentation.
The option value's keywords, described below, can be abbreviated to one
letter. They must be separated by a "+" sign:
heap and/or stack
To indicate which areas need to be checked.
repeat
For warnings on every line of a procedure that uses an
uninitialized data value, instead of just on the procedure's first
use of it. Each execution of a given line is still reported only
once.
copy
For warnings on the first access to the uninitialized memory,
instead of on the first computation that uses it (which may follow
several copy operations).
value=hex
Changes the value used for poisoning from 0xfff8a5a5 to the
specified hexadecimal value.
-ignore [obj^file^|obj^^|file^]proc [error-code [line n]]
Tells third to disregard memory errors (if error-code is represented by
a three-letter mnemonic, or an asterisk, or if none is specified) or
leak and object reports (if error-code is represented by leaks,
objects, or blocks) for a specific procedure (proc). Optionally, the
location of the error can be further qualified by specifying a program
or shared library (obj), source file (file), procedure (proc), or
source line (line). The three-letter mnemonic error-code can be found
at the start of all error reports in the log file. The obj, file, and
proc can contain a wildcard character (*) to match any number of
characters. If the procedure name contains the character "*", the
latter must be escaped with "\". C++ procedures can omit the argument
type list, though this will match all overloaded procedures with that
name. To select a specific procedure, specify the full symbol name (as
printed by the nm command). Symbol names containing spaces, *, and so
on must be quoted. If a "blocks" error-code is specified, both leak and
object reports will be supressed.
Examples:
Ignore "read uninitialized heap" memory error in procedure main of
program program in source file main.c:
-ignore program^main.c^main ruh
Ignore the same error in procedure memcpy of shared library libc.so:
-ignore libc.so^^memcpy ruh
Ignore "read invalid heap" memory error in procedure cat located on
line 6 of source file main.c:
-ignore main.c^cat rih line 6
Ignore "read invalid heap" memory errors in procedure cat found on any
source line:
-ignore cat rih
Do not report leaks if one of the stack trace entries points to
procedure proc1 on line 6 of source file array.cxx:
-ignore array.cxx^proc1 leaks line 6
Suppress all leak or object reports if the stack trace entry contains
references to procedure proc2:
-ignore proc2 blocks
Shared-Library Analysis Options
These options are needed for the -before, -after, -invalid, and -uninit
options to be applied to shared libraries.
-all
Analyzes all the shared libraries in addition to the program's
executable.
-excobj lib
If -all was specified, does not analyze the shared library lib.
-incobj lib
Analyzes the shared library lib.
-Lpath
Searches for shared libraries in the specified directory before
searching the default directories. Use the same options that were used
when linking the program with ld.
Execution Control Options
-run
Executes the instrumented program, even if no arguments are specified.
By default, the program is just instrumented for later execution.
-display
Executes the instrumented program, and runs more on the resulting .3log
file(s).
-version
Prints the tool's version number.
NOTES
If third finds any previously instrumented shared libraries in the working
directory, it will reuse them if they meet current requirements, to reduce
re-instrumentation costs.
Forked subprocesses are analyzed if the -fork option is specified, and
their log file contains the process-id, as if -pids had been specified.
Errors detected in signal handlers for the top-level process and all
subprocesses are reported in a single program.sig.3log file if the
process's primary log file is busy. This ensures that the primary log files
have a defined format, tbough the format of program.sig.3log is not defined
when errors are reported concurrently.
Temporary instrumentation files are created in /tmp. Set the TMPDIR
environment variable to a different directory to create the files
elsewhere, for example in a disk partition with more space.
RESTRICTIONS
Heap managers other than those of C and C++ are not supported.
Third Degree has the following leak reporting limitations:
· Sometimes, some leaks may not be reported because old pointers were
found in memory. Selecting checks for uninitialized heap memory may
reduce this.
· Any degree of optimization will skew results, because instructions
that the compiler considers non-essential may be optimized away.
Third Degree may print warnings for apparent problems that are really
harmless and do not need to be fixed. Such reports can be ignored, or the
-g option can be used to check the accuracy of the report by running the
instrumented program under the control of the dbx debugger. If desired,
the -ignore option can be used to prevent selected warnings being printed,
in much the same way as lint(1) provides options to suppress certain of its
static checks. For example, third cannot always distinguish the following
valid behavior from invalid behavior, resulting in false reports:
· Initialization of variables and structure members that are less than
32 bits in size (for example, C bit-field, char, and short types).
· Use of actual data whose value matches the poison value (0xfff8a5a5)
that third uses to detect reading of uninitialized variables.
· Nonstandard behavior of assembler and system procedures that have been
highly optimized for performance.
· Variable size stack frames.
The procedures in system libraries that are used by the POSIX threads
package can not be instrumented in multi-threaded programs.
Approximate performance estimates are as follows but will vary according to
the application and the machine's CPU count, type, and clock rate. Third
Degree instrumentation takes ~3s per Mb of program file on a 500-MHz EV6
(21264) Alpha system, using ~15 Mb of memory plus another ~25 Mb per Mb of
the largest program file. Large procedures can increase both time and
memory usage significantly. By default the instrumented files are ~1.5 Mb
larger than the originals and run ~3 times slower, but adding the -invalid
or -uninit option can make the files ~2.5 times larger and make them run
~10 times slower. The program executable also includes data for each
instrumented shared library -- ~30% of the library size.
FILES
program.third
Instrumented version of program produced by third.
program[.pid|sig].3log
Error log file produced by program.third.
lib*.so.instrumented-executable
Instrumented shared libraries produced by third.
.third.pid
Temporary file created and deleted in the current and -dirname path
directories.
SEE ALSO
Introduction: prof_intro(1)
atom(1), cc(1), dbx(1), dlopen(3), dxheap(1), emacs(1), fork(2),
ladebug(1), ld(1), nm(1), pthread(3) (dxheap is available as an option.)
Programmer's Guide
|
Index for
Section 1 |
|
|
Alphabetical
listing for T |
|
 |
Top of
page |
|