*** UNIX MANUAL PAGE BROWSER ***

third(5) File Formats Manual 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 File name of a fully linked shared or nonshared executable to be exam- ined. This program should be compiled with the -g2 or -g3 flag to ob- tain 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 sym- bolic information is not available. Third Degree may detect more uninitialized variables if compiler optimization is disabled (for exam- ple, 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 sup- ported. 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 parame- ters (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 speci- fied in the -excobj flag. This allows Third Degree to use in- strumented 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 direc- tory 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 applica- tions.) 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 direc- tory 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 cor- responding 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 De- gree instruments the entire program, including the libraries it refer- ences. 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 pro- gram 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 spec- ifying the object_padding option in the file. To detect errant use of uninitialized data, Third Degree initializes all otherwise uninitial- ized data to a special pattern. This can cause the instrumented pro- gram 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 al- locators, 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. Fur- thermore, 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 error detection and reporting. The following general syntax rules apply to the 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 exam- ple, Third Degree treats heap_history and heap_history yes as identi- cal. Third Degree looks for the 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 file, it uses the defaults indicated in the following list of file options. Use the following options in the 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 sta- tic and heap memory. Before or after every N calls to proc_name, re- ports 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 han- dler. 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 ob- jects. Generates a heap history for the program. A heap history al- lows you to see how the program used dynamic memory during its execu- tion. 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 dynami- cally-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_pat- tern^][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 partic- ular 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 rou- tines 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 ob- jects 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 De- gree 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 identi- cal 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 mem- ory 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 fi- nal 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 repre- senting 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 ad- dress 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 ad- dress space of some other process or by encoding them, Third De- gree may report spurious leaks. Supplying a pointer mask may re- duce the reporting of such spurious leaks. The mask is a 64-bit hexadecimal number; the value 0xffffffffffffffff is the default mask value. Enables or dis- ables 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, SIGA- BRT, 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 sig- nal handler may interfere with it. You can disable Third De- gree's signal handling by specifying signals no. By default, signal handling is enabled; however, any applica- tion-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 tem- porarily 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 ob- jects 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 suffix in its name. The log file contains the heap history, memory-access er- rors, heap-object lists, and memory-leak lists that were selected by commands in the file. When heap history is enabled, Third Degree collects information about each dynamically allocated object at the time it is freed by the appli- cation. 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 cat- egorizes 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 in- formation 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 exe- cution 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 configuration file. In the contents portion of an entry, Third Degree uses one of the fol- lowing characters to represent each 32-bit longword it has examined: l lw(6.2i). _ Character Description _ Dot (.) T{ Indicates a long- word 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. T} z T{ Indicates a field whose value was always 0 (zero) in every object. T} pp T{ 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. T} ss T{ 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. How- ever, it could also be the sign of a serious programming error. T} i T{ 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. T} _ When memory-access checks and heap listings are enabled in the 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: l l. _ 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 in- valid 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 (re- ally just a warning) mrn malloc returned null _ EXAMPLES Invokes Third Degree to instrument program, creating the log file /tmp/program.pid.3log and producing the output executable pro- gram.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 set- tings of the -toolargs flag or the THIRD_ARGS environment variable. Customization file for Third Degree. SEE ALSO atom(1), dxheap(1) (dxheap(1) is available only if the Developer's Tool Kit and associated reference pages are installed on your system.) Programmer's Guide third(5)