Content-type: text/html Man page of third

third

Section: File Formats (5)
Index Return to Main Contents
 

NAME

third - Performs memory access checks and detects memory leaks  

SYNOPSIS

atom appl_prog -tool third [-env threads] [-toolargs="arg1 arg2..."] [atom_flags...]


 

PARAMETERS

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

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 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. Passes arguments to Third Degree's instrumentation routines. Use whitespace characters to separate arguments from their parameters (if any) and from other arguments. 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. 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"


 

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: 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.

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 Reads additional Third Degree options from file-path. A full pathname to the included file is required. 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. 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. 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. 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. 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. 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. 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. 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:


CharacterDescription

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:


NameError

rorReading out of range: neither in heap, stack, nor static area
risReading invalid data in stack: probably an array bound error
rusReading an uninitialized (but valid) location in stack
rihReading invalid data in heap: probably an array bound error
ruhReading an uninitialized (but valid) location in heap
worWriting out of range: neither in heap, stack, nor static area
wisWriting invalid data in stack: probably an array bound error
wihWriting invalid data in heap: probably an array bound error
forFreeing out of range: neither in heap nor stack
fisFreeing an address in the stack
fihFreeing an invalid address in the heap: no valid object there
fofFreeing an already freed object
fonFreeing a null pointer (really just a warning)
mrnmalloc returned null


 

EXAMPLES

Invokes Third Degree to instrument program, creating the log file /tmp/program.pid.3log and producing the output executable program.third.
 

FILES

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.
 

SEE ALSO

atom(1), dxheap(1) (dxheap is available as an option.)

Programmer's Guide


 

Index

NAME
SYNOPSIS
PARAMETERS
OPTIONS
DESCRIPTION
Third Degree Customization File
Third Degree Log File
EXAMPLES
FILES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 02:43:07 GMT, October 02, 2010