 |
Index for Section 5 |
|
 |
Alphabetical listing for T |
|
third(5)
NAME
third - Performs memory access checks and detects memory leaks
SYNOPSIS
atom appl_prog -tool third [-env threads] [-toolargs="arg1 arg2..."]
[atom_flags...]
PARAMETERS
appl_prog
File name of a fully linked shared or nonshared executable to be
examined. This program should be compiled with the -g2 or -g3 flag
to obtain more complete debugging information. If the default
symbol table level (-g0) is used, line number information, static
procedure names, and file names are unavailable. If -g1 is used,
the variable name symbolic information is not available. Third
Degree may detect more uninitialized variables if compiler
optimization is disabled (for example, with the -O0 and -inline
none options).
OPTIONS
-tool third
Identifies the Third Degree tool to the atom command.
-env threads
Specifies that Third Degree is being invoked on an application that
runs in a threaded environment. To make run-time analysis of an
application that creates threads threadsafe, you must specify -env
threads in the third command. Only POSIX threads created using the
pthread_create function are supported.
The threadsafe instrumented executable is named appl_prog.third.threads
by default. You may omit the -env threads flag if the application does
not create threads; in this case the instrumented executable is named
appl_prog.third.
-toolargs="arg1 arg2 ..."
Passes arguments to Third Degree's instrumentation routines. Use
whitespace characters to separate arguments from their parameters (if
any) and from other arguments.
atom_flags
Specifies flags to the atom command. See the atom(1) reference page
for descriptions of other flags accepted by the atom command, such as
those that enable instrumentation of shared libraries, specify the
names of instrumented objects, and request debugging information.
Note that the -excobj Atom flag behaves as described except that those
libraries (such as libc.so and libcxx.so) that contain memory
allocation functions (such as malloc, _sbrk, and new) are partially
instrumented, as appropriate, even if they are specified in the -excobj
flag. This allows Third Degree to use instrumented versions of the
standard memory allocation functions.
Consequently, after you have instrumented an application that uses
libc.so, libcxx.so, or other shared libraries, you must set the
LD_LIBRARY_PATH environment variable to point to the directory
containing the instrumented shared libraries. Typically, this would be
the current directory or the directory specified by the -shlibdir flag.
(You may leave LD_LIBRARY_PATH pointing to this directory while running
other, uninstrumented applications.)
The Third Degree tool allows the following flags to be passed in the
-toolargs flag for Third Degree's instrumentation routine to use when
instrumenting appl_prog. Except where noted, these flags can also be
passed to the instrumented program at execution time by being defined as
part of the THIRD_ARGS environment variable.
-dirname directory
Specifies the directory path in which Third Degree creates its log
file.
-[no]pids
Specifies the name of the log file as application_program.pid.3log.
The -nopids flag overrides any previous specification of -pids.
While the instrumented appl_prog is being executed, flags specified in the
definition of the THIRD_ARGS environment variable override any
corresponding settings in the -toolargs flags. For example:
% setenv THIRD_ARGS "-dirname /mydir -pids"
DESCRIPTION
The Third Degree Atom tool performs memory access checks and memory leak
detection of C and C++ programs at run-time. It accomplishes this by using
Atom to add code to executable and shared objects. Third Degree
instruments the entire program, including the libraries it references. The
additional code performs run-time checks of memory accesses, calls to
memory allocators, procedure calls and returns, and program start and exit.
The instrumented program locates most occurrences of the worst types of
bugs in C and C++ programs: array overflows, memory smashing, and errors in
the use of the malloc and free functions. It also helps you determine the
allocation habits of your application by listing the heap and finding
memory leaks.
The instrumented program behaves in the same way as the original program
except for the following:
· The code is larger and runs more slowly because of the additional
instrumentation code that is inserted.
· Each allocated heap memory object is larger because Third Degree pads
it to allow boundary checking. You can adjust the amount of padding
by specifying the object_padding option in the .third file.
· To detect errant use of uninitialized data, Third Degree initializes
all otherwise uninitialized data to a special pattern. This can cause
the instrumented program to behave differently, behave incorrectly, or
crash (particularly if this special pattern, an invalid pointer,
appears in a pointer). All of these behaviors indicate a bug in the
program.
You can use the Third Degree for the following types of applications:
· For C or C++ applications that allocate memory by using the malloc,
calloc, realloc, valloc, alloca, sbrk, and new (C++ only) functions.
You can use Third Degree to instrument programs using other memory
allocators, such as the mmap function, but it does not check accesses
to the memory thus obtained.
Third Degree detects and forbids calls to the brk function.
Furthermore, if your program allocates memory by partitioning large
blocks it obtained by using the sbrk function, Third Degree may not be
able to precisely identify memory blocks in which errors occur.
· Applications using POSIX threads (pthread) interfaces.
Third Degree Customization File
Third Degree takes as input a user-specified customization file named
.third. This customization file allows you to enable and disable error
detection and reporting.
The following general syntax rules apply to the .third file:
· Third Degree treats lines beginning with a pound-sign character (#) as
comments.
· Specify procedure names and file names within single-quotes or
double-quotes.
· Procedure names should match those printed by the nm command. In
particular, C++ names must include the list of argument types, for
example, handler(int). Third Degree ignores inlined procedures unless
they are compiled with the cxx -noinline command or similar mechanism.
· You can omit the keyword yes when defining Boolean options. For
example, Third Degree treats heap_history and heap_history yes as
identical.
Third Degree looks for the .third file in the current directory. If the
file is not in the current directory, Third Degree looks for it in your
home directory. If Third Degree cannot find the .third file, it uses the
defaults indicated in the following list of .third file options.
Use the following options in the .third file:
all leaks at_exit
When the program exits, reports leaks introduced since the program
started running.
all leaks before|after proc_name every N
Before or after every N calls to proc_name, reports leaks introduced
since the program started running. The named procedure must not be
called from a SEGV handler.
all objects at_exit
When the program exits, reports that allocated memory blocks created
since the program started running are still reachable by means of
pointers in static and heap memory.
all objects before|after proc_name every N
Before or after every N calls to proc_name, reports which allocated
memory blocks created since the program started running are still
reachable by means of pointers in stack, static, and heap memory. The
named procedure must not be called from a SEGV handler.
new leaks at_exit
When the program exits, reports leaks introduced since the previous
leak report.
new leaks before|after proc_name every N
Before or after every N calls to proc_name, reports leaks introduced
since the previous leak report. The named procedure must not be called
from a SEGV handler.
new objects at_exit
When the program exits, reports that allocated memory blocks created
since the previous object report are still reachable by means of
pointers in static and heap memory.
new objects before|after proc_name every N
Before or after every N calls to proc_name, reports which allocated
memory blocks created since the previous object report are still
reachable by means of pointers in stack, static, and heap memory. The
named procedure must not be called from a SEGV handler.
no leaks at_exit
Disables the default report of new leaks at_exit. This option is
necessary if a SIGSEGV handler calls exit(2), but it may also be used
at will.
free_queue_bytes queue-size
Specifies the size in bytes of the queue in which freed blocks reside
before they are actually deallocated. The default size of this queue
is 1000000 bytes. Increasing the size of the queue uses more memory,
but helps troubleshoot problems in accessing freed objects.
heap_history yes|no
Generates a heap history for the program. A heap history allows you to
see how the program used dynamic memory during its execution. You can
use a heap history to identify unused fields in data structures or pack
active fields to use memory more efficiently. The heap history also
shows memory blocks that are allocated but never used by the
application. Every 32 bits of the first kilobyte of each dynamically-
allocated memory object (unless you specify otherwise with the
history_size option) is represented by one character in the contents
map for all objects allocated at the same place. (See the description
of the Third Degree log file in a later section of this reference
page.)
history_size size
Specifies the portion (in number of bytes) of each very large
dynamically-allocated memory object that is summarized in the contents
map when the heap_history option is enabled. The default history size
is 1024 bytes.
ignore proc_id [error_pattern [line line_no]]
Partially or completely disables error reporting for all routines
represented by proc_id, where proc_id equals
[obj_pattern^][file_pattern^]proc_pattern. The degree to which error
reporting is disabled depends on whether error_pattern is specified on
the ignore command line:
·
If error_pattern is not supplied, the specified routines will not be
instrumented.
·
If error_pattern is specified, those particular errors will be
filtered at analysis time.
The proc_id components file_pattern and obj_pattern are optional and
can be specified as pathnames.
Third Degree recognizes the three-letter error abbreviations listed in
the description of the Third Degree log file in a later section of this
reference page. Wildcard characters (*) can be used only in pattern
names.
For example, the following command disables instrumentation of all
routines named foobar in the application:
ignore foobar
The following commands each disable instrumentation of all routines
named foo in the library libx.so. (If multiple static routines have the
same name, these commands ensure that neither are instrumented.)
ignore libx.so^^foo
ignore libx.so^*^foo
The following command filters "read uninitialized stack errors" at
analysis time in routine foo at line 20:
ignore foo rus line 20
include file-path
Reads additional Third Degree options from file-path. A full pathname
to the included file is required.
leak_stack_depth depth
object_stack_depth depth
Specifies an integer representing the maximum number of procedure
invocations on the call stack that Third Degree uses to distinguish
objects from other objects (or leaks from other leaks). Third Degree
lists memory objects and leaks in the report by decreasing importance,
based on the number of bytes involved. It groups together objects
allocated with identical call stacks. For example, if the same call
sequence allocates a million one-byte objects, Third Degree reports
them as a one-megabyte group containing a million allocations.
For example, if you specify a depth of 1 for objects, Third Degree
groups valid objects in the heap by the function and line number that
allocated them, no matter what function was the caller. Conversely, if
you specify a very large depth for leaks, Third Degree groups only
leaks allocated at points with identical call stacks from main upwards.
The default stack depth is 10000.
leak_min_percent percentage
object_min_percent percentage
Limits the length of a Third Degree heap report by specifying a
percentage of the total memory leaked or in use by an object as a
threshold. When all smaller remaining leaks or objects amount to less
than this threshold, Third Degree groups them together under a single
final entry.
The default percentage is 1.0.
memory_errors yes|no
Enables or disables the listing of all memory access errors. By
default, all memory errors are listed. Regardless of the setting of
this option, fatal memory access errors are always listed.
object_padding pad
Specifies an integer representing the number of bytes of padding that
Third Degree adds after each heap-allocated object.
Third Degree cannot detect a chance access of the wrong object in the
heap; for example, it cannot detect that a[last+100] is the same
address as b[0]. Specifying a padding for allocated objects helps
reduce the chances of these types of accesses. Note that a larger value
for pad may catch more errors but will use more memory.
The default padding is 16 bytes.
pointer_mask mask
Activates a mask that Third Degree applies (using a logical-AND
operation) to potential pointers when searching for memory leaks.
Third Degree discovers leaks (that is, allocated objects the address of
which is not stored anywhere in memory) by searching memory for words
that contain the addresses of memory objects. If an application hides
true pointers by storing them in the address space of some other
process or by encoding them, Third Degree may report spurious leaks.
Supplying a pointer mask may reduce the reporting of such spurious
leaks.
The mask is a 64-bit hexadecimal number; the value 0xffffffffffffffff
is the default mask value.
signals yes|no
Enables or disables Third Degree's use of the default signal handler
for fatal errors.
Third Degree defines signal handlers only for those signals that
normally cause program crashes (including SIGILL, SIGTRAP, SIGABRT,
SIGEMT, SIGFPE, SIGBUS, SIGSEGV, SIGSYS, SIGXCPU, and SIGXFSZ). If
your program establishes signal handlers, there is a small chance that
Third Degree's changing of the default signal handler may interfere
with it. You can disable Third Degree's signal handling by specifying
signals no.
By default, signal handling is enabled; however, any application-
defined signal handlers will replace those defined by Third Degree,
except while Third Degree is reporting on heap objects, leaks, and
history. In the exception case, Third Degree temporarily overrides any
application-defined signal handlers.
If you disable signal handling for a multithreaded program, the all
leaks before|after proc-Name every N option and the all objects
before|after proc_name every N option are not supported.
uninit_heap yes|no
uninit_stack yes|no
Enables or disables Third Degree's filling of newly allocated heap or
stack memory to the value Third Degree uses to detect uninitialized
memory.
If the uninstrumented version of the application worked, but fails
after being instrumented by Third Degree, you can use uninit_stack no
and uninit_heap no to pinpoint the source of the error. By using one
or both options, you can alter the behavior of the instrumented program
and may likely get it to complete successfully. This will help you
determine which type of error is causing the instrumented program to
crash and, as a result, help you focus on specific messages in the log
file.
By default, Third Degree initializes newly-allocated stack and heap
memory. Do not use the uninit_heap no and uninit_stack no options
under normal operation. They hamper Third Degree's ability to detect a
program's use of uninitialized data.
use directory-spec
Adds a directory to the search path Third Degree uses to find source
files. There is no default setting. To clear the search path, specify
the use option without a directory-spec.
Third Degree Log File
Third Degree places its output in a log file that includes the .3log suffix
in its name. The log file contains the heap history, memory-access errors,
heap-object lists, and memory-leak lists that were selected by commands in
the .third file.
When heap history is enabled, Third Degree collects information about each
dynamically allocated object at the time it is freed by the application.
When program execution completes, Third Degree assembles this information
for every object still alive (including memory leaks). For each object,
Third Degree looks at the contents of the object, and categorizes each word
as follows:
· Never written by the application
· Zero
· A valid pointer value in the stack, heap, or static data area
· Some other value
Third Degree then merges the information for each object with the
information that it has gathered for all other objects allocated at the
same call stack in the program. This provides you with a cumulative picture
of the use of all objects of a given type.
Third Degree provides a summary of all of the objects allocated during the
life of the program and the purposes for which their contents were used.
The report shows one entry per allocation point (for example, a call stack
where an allocator function such as malloc or new was called). Entries are
sorted by decreasing volume of allocation.
Each entry provides the following:
· Information about all objects that have been allocated at any point up
to this point in the program's execution
· Total number of bytes allocated at the specified point in the
program's execution
· Total number of objects that have been allocated up to the specified
point in the program's execution
· Percentage of bytes of the allocated objects that have been written
· The call stack and a cumulative map of the contents of all objects
allocated by that call stack
The contents part of each entry describes how the objects allocated at the
specified point were used. If all allocated objects are not the same size,
Third Degree considers only the minimum size common to all objects. For
very large allocations, it summarizes the contents of only the beginning of
the objects (by default, the first kilobyte). You can adjust the maximum
size value by specifying the history_size option in the .third
configuration file.
In the contents portion of an entry, Third Degree uses one of the following
characters to represent each 32-bit longword it has examined:
__________________________________________________________________________
Character Description
__________________________________________________________________________
Dot (.)
Indicates a longword that was never written in any of the
objects, a definite sign of wasted memory. Further analysis
is generally required to see if it is simply a deficiency of a
test that never used this field, if it is a padding problem
solved by swapping fields or choosing better types, or if this
field is obsolete.
z
Indicates a field whose value was always 0 (zero) in every
object.
pp
Indicates a pointer; that is, a 64-bit quantity that was zero
in every object or was a valid pointer into the stack, the
static data area, or the heap.
ss
Indicates a sometime pointer. This longword looked like a
pointer in at least one of the objects, but not in all
objects. It could be a pointer that is not initialized in
some instances, or a union. However, it could also be the
sign of a serious programming error.
i
Indicates a longword that was written with some nonzero value
in at least one object and that never contained a pointer
value in any object.
__________________________________________________________________________
When memory-access checks and heap listings are enabled in the .third file,
a common format indicates the nature, characteristics, and location of each
listed error or object. The log file uses a three-letter name to identify
each error. The names are as follows:
____________________________________________________________________
Name Error
____________________________________________________________________
ror Reading out of range: neither in heap, stack, nor static area
ris Reading invalid data in stack: probably an array bound error
rus Reading an uninitialized (but valid) location in stack
rih Reading invalid data in heap: probably an array bound error
ruh Reading an uninitialized (but valid) location in heap
wor Writing out of range: neither in heap, stack, nor static area
wis Writing invalid data in stack: probably an array bound error
wih Writing invalid data in heap: probably an array bound error
for Freeing out of range: neither in heap nor stack
fis Freeing an address in the stack
fih Freeing an invalid address in the heap: no valid object there
fof Freeing an already freed object
fon Freeing a null pointer (really just a warning)
mrn malloc returned null
____________________________________________________________________
EXAMPLES
atom -tool third program -toolargs= "-dirname /tmp -nopids"
Invokes Third Degree to instrument program, creating the log file
/tmp/program.pid.3log and producing the output executable
program.third.
FILES
appl_prog.third
Instrumented version of appl_prog.
appl_prog.3log
Log of memory errors, leaks, and other reports. The name of this log
file can be overriden by the settings of the -toolargs flag or the
THIRD_ARGS environment variable.
.third
Customization file for Third Degree.
SEE ALSO
atom(1), dxheap(1) (dxheap is available as an option.)
Programmer's Guide