 |
Index for
Section 5 |
|
 |
Alphabetical
listing for T |
|
 |
Bottom of
page |
|
third(5)
NAME
third - Performs memory access checks and detects memory leaks
SYNOPSIS
atom appl_prog -tool third [-env threads] [-toolargs="arg1 arg2..."]
[atom_options...]
This interface will be retired in a future major release. See third(1) for
the replacement interface.
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
option 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 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 option if the application
does not create threads; in this case the instrumented executable is
named appl_prog.third.
-toolargs="arg1 arg2 ..."
Passes arguments (listed below, in this section) to Third Degree's
instrumentation routines. Use whitespace characters to separate
arguments from their parameters (if any) and from other arguments.
atom_options
Specifies options to the atom command. See the atom(1) reference page
for descriptions of other options 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 option behaves as described except that
those libraries (such as libc.so and libpthread.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
option. 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, libpthread.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
option. (You may leave LD_LIBRARY_PATH pointing to this directory while
running other, uninstrumented applications.)
The Third Degree tool allows the following options to be passed in the
-toolargs option for Third Degree's instrumentation routine to use when
instrumenting appl_prog. Except where noted, these options 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 option overrides any previous specification of -pids.
-fork
Specify -fork if the program or any of its libraries calls fork(2), to
produce separate log files for the forked subprocesses, appending the
process id to the name of the associated log file as if -pids was
specified. Currently this option carries a risk of deadlock in some
threaded programs. This option is usually not needed if the
subprocesses call exec(2).
-mapbase hexvalue
Specifies that Third Degree should begin any of its own memory mapping
that uses mmap(2) at the specified hexadecimal address. This enables
you to avoid interference with an application's use of mmap(2), if
applicable. The default map base is 0x38000000000.
-override
Disables the default checking for invalid and uninitialized memory
access (that is, leaving only the default scan for memory leaks), and
prevents reading commands from a ./.third or $HOME/.third command file
or options from the THIRD_ARGS environment variable. When this option
is specified, additional options can be specified in the -toolargs
argument list, as listed for each command defined for the command file.
This option can not be specified in the THIRD_ARGS environment
variable.
While the instrumented appl_prog is being executed, options specified in
the definition of the THIRD_ARGS environment variable override any
corresponding settings in the -toolargs options. 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.
If you are instrumenting a shared-library program, you will probably need
to set the LD_LIBRARY_PATH environment variable (see atom(1) for more
information).
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. If a C++
procedure name omits the argument type list, 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). Any "*"
character in a C++ name must be quoted with a backslash ("\*"),
because "*" is interpreted as a wildcard that matches any sequence of
characters. 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 (or use the options in
parentheses in the atom command's -toolargs argument list):
all leaks at_exit (-leaks all -after exit)
When the program exits, reports leaks introduced since the program
started running.
all leaks before|after proc_name every N
(-leaks all -every N -before proc_name)
(-leaks all -every N -after proc_name)
Before or after every N calls to proc_name, reports leaks introduced
since the program started running.
all objects at_exit (-objects all -after 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
(-objects all -every N -before proc_name)
(-objects all -every N -after proc_name)
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.
new leaks at_exit (-leaks new -after exit)
When the program exits, reports leaks introduced since the previous
leak report.
new leaks before|after proc_name every N
(-leaks new -every N -before proc_name)
(-leaks new -every N -after proc_name)
Before or after every N calls to proc_name, reports leaks introduced
since the previous leak report.
new objects at_exit (-objects new -after 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
(-objects new -every N -before proc_name)
(-objects new -every N -after proc_name)
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.
no leaks at_exit (-leaks cancel)
Disables the default report of new leaks at_exit.
all|new blocks before|after proc_name every N
all|new blocks at_exit
Similar to the leaks and objects commands, but both leak and object
reports are printed each time.
free_queue_bytes queue-size (-free 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 (-history)
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 (-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 [error_pattern [line line_no]]
(-ignore 'proc [error_pattern [line line_no]]')
Partially or completely disables error reporting for all routines
represented by proc, where proc 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 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 (no equivalent)
Reads additional Third Degree options from file-path. A full pathname
to the included file is required.
leak_stack_depth depth (-depth depth)
object_stack_depth depth (-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.
hide_levels n
Specifies the number (n) of levels of system routines on the call stack
that will cause an error to be suppressed. The default is n=2. This
value causes errors detected in system routines that are called from
system routines to be suppressed, because most such errors are
spurious. Setting n to a value greater than 2 will cause some of the
suppressed errors to be reported. Setting n to 1 is not likely to be
useful, but setting n to 0 allows all stack traces to be printed even
when no line numbers are available. Any routine without line number
information is considered a system routine; therefore, application code
should be compiled with the -g option.
leak_min_percent percentage (-min percentage)
object_min_percent percentage (-min 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 (-override is similar but faster)
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 (-pad 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 (-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 (-signals implies no)
Enables or disables Third Degree's use of the default signal handler
for fatal errors. 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.
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 heap)
uninit_stack yes|no (-uninit stack)
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.
To detect uninitialized data, Third Degree fills newly-allocated stack
and heap memory 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
Degree's analysis can continue. The error reports in the log file and
debugging with atom's -gp option can help locate the cause of the
problem. Third Degree 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 Degree uses to detect reading of uninitialized variables.
·
Non-standard behavior of assembler and system procedures that have
been highly optimized for performance.
uninit_value hex_value (-uninit value hex_value)
Changes the value used for poisoning from 0xfff8a5a5 to the specified
hexadecimal value.
use directory-spec (-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.
Error logs for code in signal handlers that interrupt regular error logging
are written to a separate .3log.sig 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 option or the
THIRD_ARGS environment variable.
.third
Customization file for Third Degree.
SEE ALSO
atom(1), third(1), dxheap(1). (dxheap is available as an option.)
Programmer's Guide
|
Index for
Section 5 |
|
|
Alphabetical
listing for T |
|
 |
Top of
page |
|