Content-type: text/html
third - Performs memory access checks and detects memory leaks
atom appl_prog -tool third [-env threads] [-toolargs="arg1 arg2..."] [atom_flags...]
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).
Identifies the Third Degree tool to the atom command. 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 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. Specifies the directory path in which Third Degree creates its log file. 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"
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 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: When the program exits, reports leaks introduced since the program started running. 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. 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. 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. When the program exits, reports leaks introduced since the previous leak report. 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. 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. 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. 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. 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. 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.) 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. 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.
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 |
Invokes Third Degree to instrument
program,
creating the log file
/tmp/program.pid.3log
and producing the output executable
program.third.
Instrumented version of
appl_prog.
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.
Customization file for Third Degree.
atom(1), dxheap(1) (dxheap is available as an option.)
Programmer's Guide