Purify(1) LICENSED SOFTWARE Purify(1) NNNNAAAAMMMMEEEE purify - instrument a program to detect run-time memory corruption errors and memory leaks SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ppppuuuurrrriiiiffffyyyy [----_o_p_t_i_o_n ...] $(CC) $(CFLAGS) -o _p_r_o_g_r_a_m $(OBJS) $(LIBS) ppppuuuurrrriiiiffffyyyy ----vvvviiiieeeewwww [_p_r_o_g_r_a_m] [_s_a_v_e_d....ppppvvvv] DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN Purify intercepts every memory access by inserting instruc- tion sequences into the user's executable program before each load and store machine code instruction. These instruction sequences make it possible for Purify to detect memory corruption just before it happens, even if it occurs in a shared library or a third-party library. Purify also finds memory leaks - memory that has been allocated but can no longer be accessed because there are no pointers to it. Purify detects: +o Reading or writing beyond the bounds of an array. +o Reading or writing freed memory. +o Freeing memory multiple times. +o Reading and using uninitialized memory. +o Reading or writing through null pointers. +o Overflowing the stack by recursive function calls. +o Reading or writing the first page of memory. +o Having memory leaks. +o Leaving open file descriptors. +o Reading or writing memory addresses on which a watch- point has been set. SSSSeeeettttttttiiiinnnngggg UUUUpppp Purify is typically loaded from CD-ROM, and then installed using the ppppuuuurrrreeee____iiiinnnnssssttttaaaallllllll command. You will need a license certificate with a valid password; enter the information requested exactly as printed on the certificate. For more information, see the ``System Administrator's Guide.'' To use Purify, create a symbolic link from where ppppuuuurrrriiiiffffyyyy is installed (_p_u_r_i_f_y_h_o_m_e////ppppuuuurrrriiiiffffyyyy) to ////uuuussssrrrr////llllooooccccaaaallll////bbbbiiiinnnn////ppppuuuurrrriiiiffffyyyy (or some other directory on each user's $$$$PPPPAAAATTTTHHHH): Printed 1/6/97 15 Jan 1996 1 Purify(1) LICENSED SOFTWARE Purify(1) example% llllnnnn ----ssss _p_u_r_i_f_y_h_o_m_e////ppppuuuurrrriiiiffffyyyy ////uuuussssrrrr////llllooooccccaaaallll////bbbbiiiinnnn////ppppuuuurrrriiiiffffyyyy Purify follows this symbolic link to find the other files it needs in the installation directory. Under Solaris 2.x the additional program _p_u_r_i_f_y_h_o_m_e////rrrreeeeppppuuuurrrriiiiffffyyyy should also be made available: example% llllnnnn ----ssss _p_u_r_i_f_y_h_o_m_e////rrrreeeeppppuuuurrrriiiiffffyyyy ////uuuussssrrrr////llllooooccccaaaallll////bbbbiiiinnnn////rrrreeeeppppuuuurrrriiiiffffyyyy Alternatively, add _p_u_r_i_f_y_h_o_m_e to each user's $$$$PPPPAAAATTTTHHHH. BBBBuuuuiiiillllddddiiiinnnngggg Add the word ppppuuuurrrriiiiffffyyyy to the beginning of the link line in your Makefile. For example: _p_r_o_g_r_a_m: $(OBJS) ppppuuuurrrriiiiffffyyyy [----_o_p_t_i_o_n ...] $(CC) $(CFLAGS) -o _p_r_o_g_r_a_m \ $(OBJS) $(LIBS) Purify modifies the object code at link time to produce an equivalent program which has additional error checking instructions built in. The ----_o_p_t_i_o_n_s specified on the com- mand line are Purify options to customize its operation. RRRRuuuunnnnnnnniiiinnnngggg The Purify'd program is run exactly as the original program. A Purify Viewer window will be created, and error messages will be displayed as Purify detects various conditions. The messages initially appear in the Viewer as one-line sum- maries, which may be expanded and collapsed by clicking on the arrow glyph to the left. Some messages may have sub- items which may be further expanded for more detail. When you re-run the program, it will try to re-connect to the existing Purify Viewer, displaying its messages below any previously displayed. If the Viewer has exited, it will create a new one. Alternatively, messages may be output in ASCII, either to a log file, or to the standard error stream. This is the default if an X window cannot be created, or if you use the option ----wwwwiiiinnnnddddoooowwwwssss====nnnnoooo. You can also request ASCII output by using the Purify options ----lllloooogggg----ffffiiiilllleeee====_f_i_l_e_n_a_m_e or ----lllloooogggg----ffffiiiilllleeee====ssssttttddddeeeerrrrrrrr. Additionally, you can use the ----mmmmaaaaiiiillll----ttttoooo----uuuusssseeeerrrr option to send an ASCII report to a user or list of users. VVVViiiieeeewwwwiiiinnnngggg ssssaaaavvvveeeedddd ddddaaaattttaaaa You can save the messages output by Purify either using the "SSSSaaaavvvveeee aaaassss............" item from the "FFFFiiiilllleeee" menu of the Purify Viewer, or using the ----vvvviiiieeeewwww----ffffiiiilllleeee option at run-time to save directly Printed 1/6/97 15 Jan 1996 2 Purify(1) LICENSED SOFTWARE Purify(1) to a file without creating a Viewer. The messages are stored in a compact binary format called Purify View format. We recommend you use the extension ....ppppvvvv for such files. To view saved ....ppppvvvv files after a run has finished, use the command: example% ppppuuuurrrriiiiffffyyyy ----vvvviiiieeeewwww [----_o_p_t_i_o_n ...] _s_a_v_e_d....ppppvvvv This displays the messages in the Viewer for inspection just as if the program had just been run. Furthermore, the new Viewer listens for connections from other runs of the same application, and displays messages from those runs too. To invoke a Purify Viewer _j_u_s_t to listen for connections from an application without displaying saved ....ppppvvvv files, use the command: example% ppppuuuurrrriiiiffffyyyy ----vvvviiiieeeewwww [----_o_p_t_i_o_n ...] _p_r_o_g_r_a_m This form of the command may be useful if you wish to start a Viewer on one X display while running the application itself on another X display. DDDDeeeebbbbuuuuggggggggiiiinnnngggg Purify has many features that extend the power of your debugger. The most important is the function ppppuuuurrrriiiiffffyyyy____ssssttttoooopppp____hhhheeeerrrreeee(((()))). If you set a breakpoint on this func- tion, your debugger will stop on every Purify error message, right after the message is displayed and before the error actually occurs in your program: (dbx) ssssttttoooopppp iiiinnnn ppppuuuurrrriiiiffffyyyy____ssssttttoooopppp____hhhheeeerrrreeee (gdb) bbbbrrrreeeeaaaakkkk ppppuuuurrrriiiiffffyyyy____ssssttttoooopppp____hhhheeeerrrreeee (xdb) bbbb ppppuuuurrrriiiiffffyyyy____ssssttttoooopppp____hhhheeeerrrreeee This allows you to look at the state of your program before the error actually occurs to investigate its cause. Note that you should never call ppppuuuurrrriiiiffffyyyy____ssssttttoooopppp____hhhheeeerrrreeee(((()))) directly from your program; only set a breakpoint on it. MMMMeeeemmmmoooorrrryyyy LLLLeeeeaaaakkkkssss Memory leak analysis is performed when a program exits. You can also call the Purify function ppppuuuurrrriiiiffffyyyy____nnnneeeewwww____lllleeeeaaaakkkkssss(((()))) at other times from a debugger while the program is stopped: (dbx) pppprrrriiiinnnntttt ppppuuuurrrriiiiffffyyyy____nnnneeeewwww____lllleeeeaaaakkkkssss(((()))) The memory leak message reports blocks on the heap which are no longer accessible through any pointer, which have been leaked since the program started or since the last call to ppppuuuurrrriiiiffffyyyy____nnnneeeewwww____lllleeeeaaaakkkkssss(((()))). Other functions can be invoked to Printed 1/6/97 15 Jan 1996 3 Purify(1) LICENSED SOFTWARE Purify(1) profile non-leaked blocks, or to list _a_l_l leaks or blocks instead of just those generated since the last call. The memory description functions ppppuuuurrrriiiiffffyyyy____ddddeeeessssccccrrrriiiibbbbeeee(((()))) and ppppuuuurrrriiiiffffyyyy____wwwwhhhhaaaatttt____ccccoooolllloooorrrrssss(((()))) are also useful in debugging situa- tions: (dbx) pppprrrriiiinnnntttt ppppuuuurrrriiiiffffyyyy____ddddeeeessssccccrrrriiiibbbbeeee((((aaaaddddddddrrrr)))) (dbx) pppprrrriiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwhhhhaaaatttt____ccccoooolllloooorrrrssss((((bbbbuuuuffff,,,, ssssiiiizzzzeeeeooooffff((((bbbbuuuuffff)))))))) FFFFiiiilllleeee ddddeeeessssccccrrrriiiippppttttoooorrrrssss iiiinnnn uuuusssseeee File descriptor analysis is also performed at program exit, or when you call the function ppppuuuurrrriiiiffffyyyy____aaaallllllll____ffffddddssss____iiiinnnnuuuusssseeee(((()))): (dbx) pppprrrriiiinnnntttt ppppuuuurrrriiiiffffyyyy____aaaallllllll____ffffddddssss____iiiinnnnuuuusssseeee(((()))) The file descriptors message shows which file descriptors are currently open, and additional information about where and how they were opened. WWWWaaaattttcccchhhhppppooooiiiinnnnttttssss A watchpoint may be set on a memory address by invoking the function ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh(((()))): (dbx) pppprrrriiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh((((&&&&ccccoooouuuunnnntttteeeerrrr)))) Note that watchpoints are set on fixed addresses, and if such an address lies on the dynamic heap space or in the stack space (automatic variables), the watchpoint will refer to different data objects as the heap is reallocated or as functions are called and return, leaving automatic variables on the stack. By default, the watchpoint is set on the four byte word at the indicated address, for write accesses only; other functions set watchpoints of different sizes and access modes, or remove watchpoints. Watchpoints are automatically saved to the file _p_r_o_g_r_a_m.watchpoints in the current directory and are thus preserved from one run to the next. If the program is relinked (and is newer than the watchpoints file), the watchpoints file is ignored. SSSSuuuupppppppprrrreeeessssssssiiiioooonnnn From the Purify Viewer, you can suppress errors by class and location. Select the error to be suppressed and then click the suppress icon or the "SSSSuuuupppppppprrrreeeessssssss" item from the "AAAAccccttttiiiioooonnnnssss" menu. Complete the dialog which appears to suppress the message. Suppressions of this form are local to the ses- sion. You can also make suppressions permanent by copying the line which appears near the bottom of the suppression dialog into a file named ....ppppuuuurrrriiiiffffyyyy in the directory where the program lives, in directory $$$$HHHHOOOOMMMMEEEE, or in _p_u_r_i_f_y_h_o_m_e. Files Printed 1/6/97 15 Jan 1996 4 Purify(1) LICENSED SOFTWARE Purify(1) named ....ppppuuuurrrriiiiffffyyyy....ssssuuuunnnnoooossss4444, ....ppppuuuurrrriiiiffffyyyy....ssssoooollllaaaarrrriiiissss2222, or ....ppppuuuurrrriiiiffffyyyy....hhhhppppuuuuxxxx are also read for suppressions on the corresponding platforms. PPPPuuuurrrriiiiffffyyyy aaaannnndddd PPPPuuuurrrreeeeCCCCoooovvvveeeerrrraaaaggggeeee Purify is designed to work with PureCoverage to collect code coverage information at the same time as monitoring the code for access errors and memory leaks. To create a program instrumented by Purify and PureCoverage, use a command like: ppppuuuurrrriiiiffffyyyy [----_o_p_t_i_o_n ...] ppppuuuurrrreeeeccccoooovvvv [----_o_p_t_i_o_n ...] \ $(CC) $(CFLAGS) -o _p_r_o_g_r_a_m $(OBJS) $(LIBS) MMMMeeeessssssssaaaaggggeeee TTTTyyyyppppeeeessss Each run of a Purify'd program generates a sequence of mmmmeeeessss---- ssssaaaaggggeeeessss. SSSSttttaaaarrrrtttt----uuuupppp mmmmeeeessssssssaaaaggggeeee The first message in a run is the configuration message. It tells you the full name of the program, the process ID, and the date the run started, the version of Purify in use, the options in force, the command line used, and various other information. MMMMEEEESSSSSSSSAAAAGGGGEEEE DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN SSSSEEEEVVVVEEEERRRRIIIITTTTYYYY AAAABBBBRRRR AAAArrrrrrrraaaayyyy bbbboooouuuunnnnddddssss rrrreeeeaaaadddd WWWWAAAARRRRNNNNIIIINNNNGGGG An ABR message indicates that your program is about to read a value from before the beginning or after the end of an allocated block. Common causes include: +o making an array too small (e.g. failing to account for the terminating NULL in a string); +o forgetting to multiply by ssssiiiizzzzeeeeooooffff((((_t_y_p_e)))) when allocating for an array of objects; +o using an array index too large or negative; +o failing to NULL terminate a string; or +o being off-by-one in copying elements up or down an Printed 1/6/97 15 Jan 1996 5 Purify(1) LICENSED SOFTWARE Purify(1) array. AAAABBBBWWWW AAAArrrrrrrraaaayyyy bbbboooouuuunnnnddddssss wwwwrrrriiiitttteeee CCCCOOOORRRRRRRRUUUUPPPPTTTTIIIINNNNGGGG An ABW message indicates that your program is about to write a value to before the beginning or after the end of an allo- cated block. Common causes include: +o making an array too small (e.g. failing to account for the terminating NULL in a string); +o forgetting to multiply by ssssiiiizzzzeeeeooooffff((((_t_y_p_e)))) when allocating for an array of objects; +o using an array index too large or negative; +o failing to NULL terminate a string; or +o being off-by-one in copying elements up or down an array. BBBBRRRRKKKK BBBBrrrrkkkk oooorrrr ssssbbbbrrrrkkkk ccccaaaalllllllleeeedddd oooouuuuttttssssiiiiddddeeee mmmmaaaalllllllloooocccc CCCCOOOORRRRRRRRUUUUPPPPTTTTIIIINNNNGGGG A BRK message indicates that your program is using bbbbrrrrkkkk(((()))) or ssssbbbbrrrrkkkk(((()))) directly to allocate memory. Use of bbbbrrrrkkkk(((()))) or ssssbbbbrrrrkkkk(((()))) is incompatible with the use of most implementations of mmmmaaaallll---- lllloooocccc(((()))) and ffffrrrreeeeeeee(((()))). BBBBSSSSRRRR BBBBeeeeyyyyoooonnnndddd ssssttttaaaacccckkkk rrrreeeeaaaadddd WWWWAAAARRRRNNNNIIIINNNNGGGG A BSR message indicates that a function in your program is about to read beyond the current stack pointer. The data beyond the stack pointer is subject to change without notice, for example if your program takes a context switch or a signal; thus the value read by this access is not reli- able. A common cause of a BSR is a function returning a pointer to a local variable that has gone out of scope. If the caller attempts to use that variable, this error may result. To keep the value valid after the called function has returned, make such variables static. BBBBSSSSWWWW BBBBeeeeyyyyoooonnnndddd ssssttttaaaacccckkkk wwwwrrrriiiitttteeee WWWWAAAARRRRNNNNIIIINNNNGGGG A BSW message indicates that a function in your program is about to write beyond the the stack pointer. Note: unlike other write errors such as ABW, this is not a corrupting error, since it is always legal to write a value Printed 1/6/97 15 Jan 1996 6 Purify(1) LICENSED SOFTWARE Purify(1) beyond the end of the stack. However, values beyond the current stack pointer are subject to change without notice; for example, if your program takes a context switch or a signal, then the value written by this access may not be reliably re-read. A common cause of a BSW is a function returning a pointer to a local variable that has gone out of scope. If the caller attempts to use that variable, this error may result. To keep the value valid after the called function has returned, make such variables static. Note: Some compilers utilize a side-effect of the instruc- tion to write the FSR register to synchronize the FPU with the main processor. In such cases, storing the value below the stack pointer is reasonable, since the actual value is not relevant, only the side-effect of the store. If you see a BSW from floating point computation library routines, it is probably safe to suppress it. CCCCOOOORRRR FFFFaaaattttaaaallll ccccoooorrrreeee dddduuuummmmpppp FFFFAAAATTTTAAAALLLL A COR message indicates that your program has received a signal that would normally generate a core dump. COR indi- cates a fatal error. The direct cause is usually a segmentation violation (attempting to address a page of memory which has not been mapped), or a bus error (attempting to address memory with a pointer not aligned properly for the size of the datum being addressed). Common causes include: +o indirecting through a NULL pointer, which usually gen- erates a segmentation violation; +o dereferencing a pointer obtained by performing arith- metic operations on a pointer cast to an integer, which may cause a bus error; or +o using an uninitialized or completely random value as a pointer, which may cause a bus error, if the address is unaligned, or a segmentation violation, if the address points to non-existent memory. FFFFIIIIUUUU FFFFiiiilllleeee ddddeeeessssccccrrrriiiippppttttoooorrrr iiiinnnn uuuusssseeee IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNNAAAALLLL At program exit, or when you call one of these API func- tions: ppppuuuurrrriiiiffffyyyy____nnnneeeewwww____ffffddddssss____iiiinnnnuuuusssseeee(((())));;;; ppppuuuurrrriiiiffffyyyy____aaaallllllll____ffffddddssss____iiiinnnnuuuusssseeee(((())));;;; Printed 1/6/97 15 Jan 1996 7 Purify(1) LICENSED SOFTWARE Purify(1) a collection of FIU messages is generated. Each message describes what is known about the origin of one open file descriptor. If you see multiple file descriptors for the same file, or from the same call chain in the program, you should be concerned that you have a file descriptor leak, and your program may run out of file descriptors. FFFFMMMMRRRR FFFFrrrreeeeeeee mmmmeeeemmmmoooorrrryyyy rrrreeeeaaaadddd WWWWAAAARRRRNNNNIIIINNNNGGGG An FMR message indicates that your program is about to read from memory within the heap which is not in or near a currently allocated block. This could be a dangling pointer to a chunk of memory that has already been freed (caused by retaining the pointer too long, or freeing the memory too soon). Alternatively, it could be the result of indexing very far off the end of a valid block, or using a completely random pointer which happens to fall within the heap seg- ment. FFFFMMMMWWWW FFFFrrrreeeeeeee mmmmeeeemmmmoooorrrryyyy wwwwrrrriiiitttteeee CCCCOOOORRRRRRRRUUUUPPPPTTTTIIIINNNNGGGG An FMW message indicates that your program is about to write to memory within the heap which is not in or near a currently allocated block. This could be a dangling pointer to a chunk of memory that has already been freed (caused by retaining the pointer too long, or freeing the memory too soon). Alternatively, it could be the result of indexing very far off the end of a valid block, or using a completely random pointer which hap- pens to fall within the heap segment. FFFFNNNNHHHH FFFFrrrreeeeeeeeiiiinnnngggg nnnnoooonnnn----hhhheeeeaaaapppp mmmmeeeemmmmoooorrrryyyy CCCCOOOORRRRRRRRUUUUPPPPTTTTIIIINNNNGGGG An FNH message indicates that your program is calling ffffrrrreeeeeeee(((()))) with a memory address that is not in the heap (memory in stack, data or bss). Look for pointers to strings or objects which are normally allocated on the heap being initialized with pointers to constants in the program data or text segments, or on the stack. Attempts to free such addresses cause this error. FFFFUUUUMMMM FFFFrrrreeeeeeeeiiiinnnngggg uuuunnnnaaaallllllllooooccccaaaatttteeeedddd mmmmeeeemmmmoooorrrryyyy CCCCOOOORRRRRRRRUUUUPPPPTTTTIIIINNNNGGGG An FUM message indicates that your program is trying to free unallocated memory (duplicate ffffrrrreeeeeeee(((()))) or free of bad heap pointer). A common problem is lack of clear ownership of heap objects. Only the owner should free heap objects. Printed 1/6/97 15 Jan 1996 8 Purify(1) LICENSED SOFTWARE Purify(1) If there are many references to a heap object with no one reference being clearly the longest lived, the object refer- enced may have a reference count. Failure to maintain the reference count properly may also lead to this error. MMMMAAAAFFFF MMMMeeeemmmmoooorrrryyyy aaaallllllllooooccccaaaattttiiiioooonnnn ffffaaaaiiiilllleeeedddd IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNNAAAALLLL An MAF message indicates that mmmmaaaalllllllloooocccc(((()))) has failed - you have run out of swap space for the heap to grow. After the mes- sage is delivered, mmmmaaaalllllllloooocccc(((()))) returns NULL in the normal manner. MAF is an informational message about memory. Ideally, programs should handle out-of-swap conditions gracefully, but often do not. If your program next gen- erates an NPR, NPW, ZPR, or ZPW, and then a COR, then a caller of mmmmaaaalllllllloooocccc(((()))) has failed to check the return status and is dereferencing the null pointer. MMMMIIIIUUUU MMMMeeeemmmmoooorrrryyyy iiiinnnn uuuusssseeee IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNNAAAALLLL An MIU message describes heap memory that you are currently using (memory to which there is a pointer). Use one of these API functions to generate a list of memory blocks in use: ppppuuuurrrriiiiffffyyyy____nnnneeeewwww____iiiinnnnuuuusssseeee(((())));;;; ppppuuuurrrriiiiffffyyyy____aaaallllllll____iiiinnnnuuuusssseeee(((())));;;; A list of memory blocks in use is generated at exit only if the option ----iiiinnnnuuuusssseeee----aaaatttt----eeeexxxxiiiitttt====yyyyeeeessss is set, or when one of these API functions is called: ppppuuuurrrriiiiffffyyyy____nnnneeeewwww____iiiinnnnuuuusssseeee(((())));;;; ppppuuuurrrriiiiffffyyyy____aaaallllllll____iiiinnnnuuuusssseeee(((())));;;; MMMMLLLLKKKK MMMMeeeemmmmoooorrrryyyy lllleeeeaaaakkkk WWWWAAAARRRRNNNNIIIINNNNGGGG An MLK message describes heap memory that you have leaked. There are no pointers to this block, or to anywhere within this block. A list of leaked memory blocks is generated at exit (unless the option ----lllleeeeaaaakkkkssss----aaaatttt----eeeexxxxiiiitttt====nnnnoooo is set), or when one of these API functions is called: ppppuuuurrrriiiiffffyyyy____nnnneeeewwww____lllleeeeaaaakkkkssss(((())));;;; ppppuuuurrrriiiiffffyyyy____aaaallllllll____lllleeeeaaaakkkkssss(((())));;;; A memory leak is caused when the last pointer referencing a block of memory is cleared, changed, or goes out of scope. If the section of the program where the memory is allocated and leaked is executed repeatedly, you may eventually run out of swap space; this is a serious problem for long- running interactive programs. Printed 1/6/97 15 Jan 1996 9 Purify(1) LICENSED SOFTWARE Purify(1) Memory which is allocated once, referenced by a pointer (perhaps static or global), and never freed, is not a leak. Since it is allocated only once, you cannot run out of memory during extended use of the program. Note: if you call eeeexxxxiiiitttt(((()))), any blocks of memory referenced by local variables in the functions above eeeexxxxiiiitttt(((()))) on the stack continue to be in scope, and anchor blocks of memory which are not reported as leaks. However, if instead you rrrreeeettttuuuurrrrnnnn from mmmmaaaaiiiinnnn(((()))), all local variables go out of scope, and you may see additional memory leaks reported. To track memory leaks, examine the call chain where the memory was allocated, and try to figure out where it should have been freed. Another technique is to call ppppuuuurrrriiiiffffyyyy____nnnneeeewwww____lllleeeeaaaakkkkssss(((()))) regularly while the program is running to see which program interac- tions cause the leak to appear. MMMMRRRREEEE MMMMaaaalllllllloooocccc rrrreeee----eeeennnntttteeeerrrreeeedddd CCCCOOOORRRRRRRRUUUUPPPPTTTTIIIINNNNGGGG An MRE message indicates that a re-entrant call to mmmmaaaalllllllloooocccc(((()))), ffffrrrreeeeeeee(((()))), or a related function has been made while already in a call to one of these functions. Since most default mmmmaaaallll---- lllloooocccc(((()))) implementations are not re-entrant, this will likely cause problems, unless you are using an implementation known to tolerate re-entrant calls. A possible cause of MRE errors is calling pppprrrriiiinnnnttttffff(((()))) within a signal handler. If the signal interrupts while in a call to a memory allocation function, it is possible for pppprrrriiiinnnnttttffff(((()))) to attempt to call mmmmaaaalllllllloooocccc(((()))) itself to obtain an output buffer. Note that a number of C library functions call mmmmaaaalllllllloooocccc(((()))) as a side effect. These should be avoided in interrupt/signal handlers. Other possible causes include using mmmmaaaalllllllloooocccc(((()))) within threaded programs in an unsafe way, or using lllloooonnnnggggjjjjmmmmpppp(((()))) indiscrim- inately from a signal handler for a signal delivered during a call to mmmmaaaalllllllloooocccc(((()))). See the mmmmaaaalllllllloooocccc manual page, the POSIX standard, or Advanced Programming in the UNIX Environment, Section 10.6, by W.R. Stevens. MMMMSSSSEEEE MMMMeeeemmmmoooorrrryyyy sssseeeeggggmmmmeeeennnntttt eeeerrrrrrrroooorrrr WWWWAAAARRRRNNNNIIIINNNNGGGG An MSE message indicates that you are attempting to address a piece of memory which spans potentially non-contiguous segments of memory. The segments identified include the text segment, the data segment, the heap, the stack, and Printed 1/6/97 15 Jan 1996 10 Purify(1) LICENSED SOFTWARE Purify(1) memory mapped regions. One common cause is calling a string or block-copy function with too large a size or count on a chunk of memory near the end of the data segment, such that the access spills into the heap. For example, calling ssssttttrrrrlllleeeennnn(((()))) for a string not properly terminated may have this effect. Another likely cause is incorrect size calculation for read or write buffers, leading to requests for transactions with negative or huge sized buffers. NNNNPPPPRRRR NNNNuuuullllllll ppppooooiiiinnnntttteeeerrrr rrrreeeeaaaadddd FFFFAAAATTTTAAAALLLL An NPR message indicates that your program is trying to read from address zero (read from a NULL pointer). A segmenta- tion violation will usually result. One common cause is failure to check return status for a function expected to return a pointer to a string or an object. If the function returns NULL on failure, use of the NULL pointer leads to this error. NNNNPPPPWWWW NNNNuuuullllllll ppppooooiiiinnnntttteeeerrrr wwwwrrrriiiitttteeee FFFFAAAATTTTAAAALLLL An NPW message indicates that your program is trying to write to address zero (store to a NULL pointer). A segmen- tation violation will usually result. One common cause is failure to check return status for a function expected to return a pointer to a string or an object. If the function returns NULL on failure, use of the NULL pointer leads to this error. PPPPAAAARRRR BBBBaaaadddd ffffuuuunnnnccccttttiiiioooonnnn ppppaaaarrrraaaammmmeeeetttteeeerrrr WWWWAAAARRRRNNNNIIIINNNNGGGG A PAR message indicates that your program has called a com- mon library function, such as wwwwrrrriiiitttteeee(((()))), with a bad parameter. Typically Purify warns about bad parameters which involve pointer abuse, such as passing NULL as the buffer to read or write. PPPPLLLLKKKK PPPPooootttteeeennnnttttiiiiaaaallll mmmmeeeemmmmoooorrrryyyy lllleeeeaaaakkkk WWWWAAAARRRRNNNNIIIINNNNGGGG A PLK message describes heap memory that you may have leaked. There are no pointers to the start of the block, but there exist pointers pointing somewhere within the block. Memory in use may sometimes appear as a PLK if the pointer returned by mmmmaaaalllllllloooocccc(((()))) is offset. A common cause is referenc- ing a substring within a large string. Another example, Printed 1/6/97 15 Jan 1996 11 Purify(1) LICENSED SOFTWARE Purify(1) when a pointer to a C++ object is cast to the second or later base class of a multiply inherited object, it is offset past the other base class objects. Leaked memory may sometimes appear as a PLK, if some non- pointer integer within the program space, when interpreted as a pointer, points within an otherwise leaked block of memory. Fortunately, this is rather rare. Inspection of the code should usually easily differentiate between these causes of PLK messages. SSSSBBBBRRRR SSSSttttaaaacccckkkk aaaarrrrrrrraaaayyyy bbbboooouuuunnnnddddaaaarrrryyyy rrrreeeeaaaadddd WWWWAAAARRRRNNNNIIIINNNNGGGG An SBR message indicates that your program is about to read across stack frame boundaries (which divide the areas of memory used for local variables of one function from those of another). This is similar to an ABR, but concerns a local variable instead of a malloc'd block. Common causes include: +o making an automatic array too small (e.g. failing to account for the terminating NULL in a string); +o forgetting to multiply by ssssiiiizzzzeeeeooooffff((((_t_y_p_e)))) when allocating for an array of objects; +o using an array index too large or negative; +o failing to NULL terminate a string; or +o being off-by-one in copying elements up or down an array. SSSSBBBBWWWW SSSSttttaaaacccckkkk aaaarrrrrrrraaaayyyy bbbboooouuuunnnnddddaaaarrrryyyy wwwwrrrriiiitttteeee CCCCOOOORRRRRRRRUUUUPPPPTTTTIIIINNNNGGGG An SBW message indicates that your program is about to write across stack frame boundaries (which divide the areas of memory used for local variables of one function from those of another). This is similar to an ABW, but concerns a local variable instead of a malloc'd block. Common causes include: +o making an automatic array too small (e.g. failing to account for the terminating NULL in a string); +o forgetting to multiply by ssssiiiizzzzeeeeooooffff((((_t_y_p_e)))) when allocating for an array of objects; +o using an array index too large or negative; Printed 1/6/97 15 Jan 1996 12 Purify(1) LICENSED SOFTWARE Purify(1) +o failing to NULL terminate a string; or +o being off-by-one in copying elements up or down an array. SSSSIIIIGGGG FFFFaaaattttaaaallll ssssiiiiggggnnnnaaaallll hhhhaaaannnnddddlllleeeedddd IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNNAAAALLLL A SIG message indicates that your program has received a signal, such as SIGINT generated by a control-C. By default, Purify only notifies you about signals that nor- mally terminate the program. SSSSOOOOFFFF SSSSttttaaaacccckkkk oooovvvveeeerrrrfffflllloooowwww eeeerrrrrrrroooorrrr WWWWAAAARRRRNNNNIIIINNNNGGGG An SOF message indicates that your program has overflowed the stack, probably due to runaway recursion. Purify reports an SOF when the stack passes an internal limit, which may be set using the ----ssssttttaaaacccckkkk----lllliiiimmmmiiiitttt option. Set this limit to at least 100k before the real end of the stack, since Purify itself will use some stack beyond the limit in order to report the problem. This 100k includes the space for the dynamic linker. The default value is set 100k before the stack limit imposed by the system (which may be set and examined using the "lllliiiimmmmiiiitttt ssssttttaaaacccckkkk" shell command). UUUUMMMMCCCC UUUUnnnniiiinnnniiiittttiiiiaaaalllliiiizzzzeeeedddd mmmmeeeemmmmoooorrrryyyy ccccooooppppyyyy WWWWAAAARRRRNNNNIIIINNNNGGGG A UMC message indicates that an uninitialized value is being copied from one memory location to another (e.g. an assign- ment). Such copies are normally harmless, representing copying of padding fields in structures, for example. By default, this warning message is suppressed in the global ....ppppuuuurrrriiiiffffyyyy file because it may generate a lot of output. You can use UMC messages if you are getting a UMR message on a variable to which an assignment has clearly been made. The UMC messages will help you track down the sequence of copies which propagate the uninitialized value into the variable on which the UMR is being reported. Enable UMC reporting by adding a line such as the following in a ....ppppuuuurrrriiiiffffyyyy file in the same directory as the program: uuuunnnnssssuuuupppppppprrrreeeessssssss uuuummmmcccc **** Printed 1/6/97 15 Jan 1996 13 Purify(1) LICENSED SOFTWARE Purify(1) UUUUMMMMRRRR UUUUnnnniiiinnnniiiittttiiiiaaaalllliiiizzzzeeeedddd mmmmeeeemmmmoooorrrryyyy rrrreeeeaaaadddd WWWWAAAARRRRNNNNIIIINNNNGGGG A UMR message indicates that your program is about to read uninitialized memory. Often, uninitialized memory will be zero, especially during unit testing. Your program will seem to perform correctly but the UMR may eventually cause incorrect behavior. Note that it is common, and correct behavior, for a program to copy uninitialized data from one variable to another. A frequent case is during structure assignment when the struc- ture being copied has inaccessible padding bytes. For this reason, Purify does not report UMRs on copies, but instead propagates the uninitialized status to the destination of the copy. If you are getting a UMR message on a variable to which an assignment has clearly been made, it is probably because the value assigned was itself a copy of uninitialized data. You can enable the normally suppressed UMC (uninitialized memory copy) reporting to help track down such problems. Enable UMC reporting by adding a line such as the following in a ....ppppuuuurrrriiiiffffyyyy file in the same directory as the program: uuuunnnnssssuuuupppppppprrrreeeessssssss uuuummmmcccc **** Purify may attribute a UMR to the closing brace of a func- tion. This is probably because one or more execution paths did not assign a return value for the function. Please check all possible return locations. WWWWPPPPRRRR WWWWaaaattttcccchhhhppppooooiiiinnnntttt rrrreeeeaaaadddd IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNNAAAALLLL A WPR message indicates that your program is about to read from memory that has a read-type watchpoint on it. WPR is an informational message about memory. WWWWPPPPWWWW WWWWaaaattttcccchhhhppppooooiiiinnnntttt wwwwrrrriiiitttteeee IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNNAAAALLLL A WPW message indicates that your program is about to write to memory that has a write-type watchpoint on it. WPW is an informational message about memory. WWWWPPPPFFFF WWWWaaaattttcccchhhhppppooooiiiinnnntttt ffffrrrreeeeeeee IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNNAAAALLLL A WPF message indicates that your program is about to free a chunk of memory containing a watchpoint. WPF is an informa- Printed 1/6/97 15 Jan 1996 14 Purify(1) LICENSED SOFTWARE Purify(1) tional message about memory. WWWWPPPPMMMM WWWWaaaattttcccchhhhppppooooiiiinnnntttt mmmmaaaalllllllloooocccc IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNNAAAALLLL A WPM message indicates that your program is about to malloc a chunk of memory containing a watchpoint. WPM is an infor- mational message about memory. WWWWPPPPNNNN WWWWaaaattttcccchhhhppppooooiiiinnnntttt ffffuuuunnnnccccttttiiiioooonnnn eeeennnnttttrrrryyyy IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNNAAAALLLL A WPN message indicates that your program has just entered a function that is allocating local variables on the stack in watched memory. WPN is an informational message about memory. WWWWPPPPXXXX WWWWaaaattttcccchhhhppppooooiiiinnnntttt ffffuuuunnnnccccttttiiiioooonnnn eeeexxxxiiiitttt IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNNAAAALLLL A WPX message indicates that your program has exited a func- tion that had allocated local variables on the stack in watched memory. WPX is an informational message about memory. ZZZZPPPPRRRR ZZZZeeeerrrroooo ppppaaaaggggeeee rrrreeeeaaaadddd FFFFAAAATTTTAAAALLLL A ZPR message indicates that your program is trying to read from the zeroth page of memory. A segmentation violation will usually result. One common cause is failure to check return status for a function expected to return a pointer to a structure or an object. If the function returns NULL on failure, accessing a structure field from the NULL pointer leads to this error. ZZZZPPPPWWWW ZZZZeeeerrrroooo ppppaaaaggggeeee wwwwrrrriiiitttteeee FFFFAAAATTTTAAAALLLL A ZPW message indicates that your program is trying to write to the zeroth page of memory. A segmentation violation will usually result. One common cause is failure to check return status for a function expected to return a pointer to a structure or an object. If the function returns NULL on failure, accessing a structure field from the NULL pointer leads to this error. SSSSuuuummmmmmmmaaaarrrryyyy mmmmeeeessssssssaaaaggggeeee If your program calls eeeexxxxiiiitttt(((()))), ____eeeexxxxiiiitttt(((()))), or returns from mmmmaaaaiiiinnnn(((()))), a summary message is generated, which shows you the status returned and a summary of resources used by the pro- gram. Printed 1/6/97 15 Jan 1996 15 Purify(1) LICENSED SOFTWARE Purify(1) The first item is a listing of basic memory usage. This indicates how many bytes of code, data, heap, and stack were used. All these values include Purify's overhead. The heap figure represents the finishing size of the heap arena, as indicated by calling ssssbbbbrrrrkkkk((((0000)))). Usually, this indicates the peak size that the heap reached during execution, unless your program explicitly relinquishes memory back to the OS by calling ssssbbbbrrrrkkkk(((()))) or bbbbrrrrkkkk(((()))) specifying a smaller size. The second item is a summary of shared library usage, and memory mapped segment usage if any. Again, the sizes are in bytes, and include Purify's overhead. OOOOPPPPTTTTIIIIOOOONNNNSSSS Purify's operation can be customized for your program. By specifying options either at program build-time or program run-time, you can affect which errors Purify reports, what information the reports contain, how they look, and where they are displayed or saved. Other options permit you to control how the program is Purify'd and linked. Each option is a word or phrase that begins with a hyphen, for example ----lllleeeeaaaakkkkssss----aaaatttt----eeeexxxxiiiitttt. Purify ignores the case and any hyphens or underscores in the option name. The option ----lllleeeeaaaakkkkssss----aaaatttt----eeeexxxxiiiitttt is equivalent to ----LLLLEEEEAAAAKKKKSSSS____AAAATTTT____EEEEXXXXIIIITTTT and ----LLLLeeeeaaaakkkkssssAAAAttttEEEExxxxiiiitttt. All options have default values. You may override these values using the assignment syntax: ----_o_p_t_i_o_n-_n_a_m_e[====[_v_a_l_u_e]] Note that no spaces are permitted on either side of the equals sign (=) if it is supplied. You may specify Purify options: +o on the build-time link line; +o in the environment variables $$$$PPPPUUUURRRRIIIIFFFFYYYYOOOOPPPPTTTTIIIIOOOONNNNSSSS or $$$$PPPPUUUURRRREEEEOOOOPPPPTTTTIIIIOOOONNNNSSSS; or +o using the Purify Viewer "Runtime options" dialog in the "Options" menu. LLLLiiiinnnnkkkk LLLLiiiinnnneeee OOOOppppttttiiiioooonnnnssss Options may be specified on the link line, e.g.: ppppuuuurrrriiiiffffyyyy ----ccccaaaacccchhhheeee----ddddiiiirrrr====$$$$((((HHHHOOOOMMMMEEEE))))////ppppccccaaaacccchhhheeee $(CC) ... Build-time options apply to the Purify build command being run. Run-time options may also be specified on the link line. These are built into the executable and become the default values at run-time when the Purify'd executable is Printed 1/6/97 15 Jan 1996 16 Purify(1) LICENSED SOFTWARE Purify(1) run. This is a convenient way to build a program with non- standard default values for certain options, for example: ppppuuuurrrriiiiffffyyyy ----cccchhhhaaaaiiiinnnn----lllleeeennnnggggtttthhhh====11112222 $(CC) ... EEEEnnnnvvvviiiirrrroooonnnnmmmmeeeennnntttt VVVVaaaarrrriiiiaaaabbbblllleeee OOOOppppttttiiiioooonnnnssss Any option may be specified in the environment variables $$$$PPPPUUUURRRRIIIIFFFFYYYYOOOOPPPPTTTTIIIIOOOONNNNSSSS or $$$$PPPPUUUURRRREEEEOOOOPPPPTTTTIIIIOOOONNNNSSSS. Note: Values in $$$$PPPPUUUURRRRIIIIFFFFYYYYOOOOPPPPTTTTIIIIOOOONNNNSSSS have precedence over values from $$$$PPPPUUUURRRREEEEOOOOPPPPTTTTIIIIOOOONNNNSSSS. Build-time options specified in environment variables are applied when applications are built. Options specified explicitly on the build-time link line override environmen- tal values. Run-time options specified in environment variables are applied when Purify'd applications are run. The environmen- tal values in force when the program is run override any defaults specified on the link line when the application was built. Note: If an option is specified more than once in an environment variable, the first value is used. To add an overriding value for the ----lllloooogggg----ffffiiiilllleeee option, for example, without changing other options specified, use a command like: csh% sssseeeetttteeeennnnvvvv PPPPUUUURRRRIIIIFFFFYYYYOOOOPPPPTTTTIIIIOOOONNNNSSSS """"----lllloooogggg----ffffiiiilllleeee====nnnneeeewwww $$$$PPPPUUUURRRRIIIIFFFFYYYYOOOOPPPPTTTTIIIIOOOONNNNSSSS"""" ksh$ eeeexxxxppppoooorrrrtttt PPPPUUUURRRRIIIIFFFFYYYYOOOOPPPPTTTTIIIIOOOONNNNSSSS====""""----lllloooogggg----ffffiiiilllleeee====nnnneeeewwww $$$$PPPPUUUURRRRIIIIFFFFYYYYOOOOPPPPTTTTIIIIOOOONNNNSSSS"""" UUUUssssiiiinnnngggg tttthhhheeee PPPPuuuurrrriiiiffffyyyy VVVViiiieeeewwwweeeerrrr RRRRuuuunnnnttttiiiimmmmeeee DDDDiiiiaaaalllloooogggg When a Purify'd program runs with the Viewer, the Runtime dialog may be invoked using the Runtime item from the Options menu. The options window displays the option values currently in use while the program is running. The option values may be edited and applied when the program has terminated, and the modified values will take effect on subsequent runs of the program displayed in the Viewer. These changes are transient, and do not modify either the default values in the program, or the environment. When you quit the Viewer and re-run the application, the options will revert to their original values. Note: The option values from the Viewer Options window have to be sent to the application at start-up time, and so it is not possible to make modifications while the application is running. However, you can use the Run button to restart the program with the new option values in effect. Printed 1/6/97 15 Jan 1996 17 Purify(1) LICENSED SOFTWARE Purify(1) OOOOPPPPTTTTIIIIOOOONNNN TTTTYYYYPPPPEEEE DDDDEEEEFFFFAAAAUUUULLLLTTTT CCCCaaaacccchhhhiiiinnnngggg OOOOppppttttiiiioooonnnnssss ((((bbbbuuuuiiiilllldddd----ttttiiiimmmmeeee ooooppppttttiiiioooonnnnssss)))) ----ccccaaaacccchhhheeee----ddddiiiirrrr ddddiiiirrrreeeeccccttttoooorrrryyyy _p_u_r_i_f_y_h_o_m_e////ccccaaaacccchhhheeee This option sets the global directory where Purify'd ver- sions of libraries will be cached. ----aaaallllwwwwaaaayyyyssss----uuuusssseeee----ccccaaaacccchhhheeee----ddddiiiirrrr bbbboooooooolllleeeeaaaannnn nnnnoooo This option forces all Purify'd versions of libraries to be written to the global cache directory. When you use the default value, Purify caches to the original library's directory, if it is writable. If the directory is not writ- able, Purify caches it to the value of ----ccccaaaacccchhhheeee----ddddiiiirrrr. LLLLiiiinnnnkkkkeeeerrrr OOOOppppttttiiiioooonnnnssss ((((bbbbuuuuiiiilllldddd----ttttiiiimmmmeeee ooooppppttttiiiioooonnnnssss)))) ----lllliiiinnnnkkkkeeeerrrr pppprrrrooooggggrrrraaaammmm----nnnnaaaammmmeeee ////bbbbiiiinnnn////lllldddd This option specifies the name of the linker that Purify should invoke to produce the executable. You should use this option only if you need to bypass the default linker. OOOOuuuuttttppppuuuutttt OOOOppppttttiiiioooonnnnssss ((((rrrruuuunnnn----ttttiiiimmmmeeee ooooppppttttiiiioooonnnnssss)))) ----wwwwiiiinnnnddddoooowwwwssss bbbboooooooolllleeeeaaaannnn nnnnooootttt sssseeeetttt This option is used to control the generation of the Viewer. If this option is not specified, the Viewer is the preferred form of output unless one or more of ----lllloooogggg----ffffiiiilllleeee, ----vvvviiiieeeewwww----ffffiiiilllleeee or ----mmmmaaaaiiiillll----ttttoooo----uuuusssseeeerrrr are set. If this option is set to no, the Viewer will not be gen- erated, and the preferred form of output will be ASCII to stderr, unless one or more of ----lllloooogggg----ffffiiiilllleeee, ----vvvviiiieeeewwww----ffffiiiilllleeee or ----mmmmaaaaiiiillll----ttttoooo----uuuusssseeeerrrr are set. If this option is set to yes, a graphical display window will be created, in addition to any other output formats specifically requested, if any. ----lllloooogggg----ffffiiiilllleeee ffffiiiilllleeee----nnnnaaaammmmeeee nnnnooootttt sssseeeetttt If this option is not specified, a graphical display window will be the preferred form of output unless one or more of ----wwwwiiiinnnnddddoooowwwwssss====nnnnoooo, ----vvvviiiieeeewwww----ffffiiiilllleeee, or ----mmmmaaaaiiiillll----ttttoooo----uuuusssseeeerrrr are set. If this option is set to ----lllloooogggg----ffffiiiilllleeee====ssssttttddddeeeerrrrrrrr, ASCII output will be sent to the program's stderr, in addition to any other Printed 1/6/97 15 Jan 1996 18 Purify(1) LICENSED SOFTWARE Purify(1) output formats specifically requested, if any. If this option is set to a filename, ASCII output will be sent to the named file, in addition to any other output for- mats specifically requested, if any. ----aaaappppppppeeeennnndddd----llllooooggggffffiiiilllleeee bbbboooooooolllleeeeaaaannnn nnnnoooo This option enables Purify output to be appended to the current logfile rather than replacing it. ----vvvviiiieeeewwww----ffffiiiilllleeee ffffiiiilllleeee----nnnnaaaammmmeeee nnnnooootttt sssseeeetttt If this option is not specified, the Viewer will be the pre- ferred form of output unless one or more of ----wwwwiiiinnnnddddoooowwwwssss====nnnnoooo, ----lllloooogggg----ffffiiiilllleeee or ----mmmmaaaaiiiillll----ttttoooo----uuuusssseeeerrrr are set. If this option is set to a filename, compact binary data will be written to the named file, in addition to any other output formats specifically requested, if any. The contents of this file can then later be viewed with the command: example% ppppuuuurrrriiiiffffyyyy ----vvvviiiieeeewwww _f_i_l_e_n_a_m_e ----oooouuuuttttppppuuuutttt----lllliiiimmmmiiiitttt iiiinnnntttteeeeggggeeeerrrr 1111000000000000000000000000 This option is used in conjunction with the option ----lllloooogggg----ffffiiiilllleeee to restrict the size of the logfile and conserve disk space. The value of this option specifies the maximum size of the Purify report in bytes. All Purify output is truncated once this limit is reached. ----ccccooooppppyyyy----ffffdddd----oooouuuuttttppppuuuutttt----ttttoooo----llllooooggggffffiiiilllleeee ffffdddd lllliiiisssstttt nnnnooootttt sssseeeetttt This option enables output from other sources (file descrip- tors) to be appended to the logfile. This option is speci- fied as a comma-separated list of file descriptors. Output written to these file descriptors is copied into the log- file. For example, to copy output written to stdout and stderr into the logfile, interspersed with Purify output, use: ----ccccooooppppyyyy----ffffdddd----oooouuuuttttppppuuuutttt----ttttoooo----llllooooggggffffiiiilllleeee====1111,,,,2222 ----ffffoooolllllllloooowwww----cccchhhhiiiilllldddd----pppprrrroooocccceeeesssssssseeeessss bbbboooooooolllleeeeaaaannnn nnnnoooo This option controls whether Purify monitors child processes created when a Purify'd programs forks. If this option is not specified, Purify does not follow child processes. Printed 1/6/97 15 Jan 1996 19 Purify(1) LICENSED SOFTWARE Purify(1) If this option is set to yes, Purify invokes a new Viewer (if appropriate) and monitors the progress of the child pro- cess separately from the parent, reporting access errors and memory leaks. MMMMeeeessssssssaaaaggggeeee PPPPrrrreeeesssseeeennnnttttaaaattttiiiioooonnnn OOOOppppttttiiiioooonnnnssss ((((rrrruuuunnnn----ttttiiiimmmmeeee ooooppppttttiiiioooonnnnssss)))) ----mmmmeeeessssssssaaaaggggeeeessss ssssttttrrrriiiinnnngggg ffffiiiirrrrsssstttt This option controls how repeated messages are handled and displayed. If set to ----mmmmeeeessssssssaaaaggggeeeessss====ffffiiiirrrrsssstttt, only the first occurrence of each repeated message is displayed. If the same message is gen- erated again and the output is being sent to the Purify Viewer, the message is not displayed but the repeat count on the first message is updated; if the output is being sent to the tty or a logfile, subsequent repeated messages will not be reported, though the cumulative total number of messages in the summary message will still reflect them. If set to ----mmmmeeeessssssssaaaaggggeeeessss====bbbbaaaattttcccchhhh, all error messages are batched and displayed, along with repeat counts, when the program exits. This mode is useful when output is not interactively displayed, but is sent to a logfile or mail mode report and you wish to note the number of occurrences of each message. If set to ----mmmmeeeessssssssaaaaggggeeeessss====aaaallllllll, each error message is individually displayed, in the order generated. This is useful for some types of interactive debugging, where you need to correlate repeated occurrences of errors with other program actions. Note: The Purify version 2 option ----ffffiiiirrrrsssstttt----oooonnnnllllyyyy is equivalent to ----mmmmeeeessssssssaaaaggggeeeessss====ffffiiiirrrrsssstttt, and the Purify version 2 option ----bbbbaaaattttcccchhhh is equivalent to ----mmmmeeeessssssssaaaaggggeeeessss====bbbbaaaattttcccchhhh. To obtain output similar to the Purify version 2 default presentation specify ----mmmmeeeessssssssaaaaggggeeeessss====aaaallllllll. ----mmmmaaaaiiiillll----ttttoooo----uuuusssseeeerrrr uuuusssseeeerrrr lllliiiisssstttt nnnnoooonnnneeee This option specifies a comma-separated list of e-mail addresses to which the Purify reports are mailed if the pro- gram reports errors. For example, to send the reports to Chris and Pat upon completion of the Purify'd application, use: ----mmmmaaaaiiiillll----ttttoooo----uuuusssseeeerrrr====cccchhhhrrrriiiissss,,,,ppppaaaatttt When mail mode is turned on, by default no output is sent to the Viewer or to stderr unless you specify the option ----wwwwiiiinnnnddddoooowwwwssss====yyyyeeeessss or ----lllloooogggg----ffffiiiilllleeee====ssssttttddddeeeerrrrrrrr. Printed 1/6/97 15 Jan 1996 20 Purify(1) LICENSED SOFTWARE Purify(1) MMMMeeeessssssssaaaaggggeeee OOOOppppttttiiiioooonnnnssss ((((rrrruuuunnnn----ttttiiiimmmmeeee ooooppppttttiiiioooonnnnssss)))) ----cccchhhhaaaaiiiinnnn----lllleeeennnnggggtttthhhh iiiinnnntttteeeeggggeeeerrrr 6666 This option specifies the number of stack frames to be recorded and printed in the function call chain of a Purify message. This option also affects the extent of the red zone area around memory blocks used by Purify to detect array bound errors. Since Purify stores the call chain of the function allocating the memory in the red zone at the end of the block, set this to a larger value to increase this red zone and increase the extent of the area where incorrect array boundary accesses will be detected. This will also change the memory and swap space used by the pro- gram. ----gggg++++++++ bbbboooooooolllleeeeaaaannnn nnnnoooo This option tells Purify that the g++ compiler was used and invokes special processing to avoid spurious ABR errors with the delete operator. It also sets the default demangling mode so that g++ mangled function names are properly resolved. This option is normally set automatically for you if the compiler is called g++. ----aaaauuuuttttoooo----mmmmoooouuuunnnntttt----pppprrrreeeeffffiiiixxxx ddddiiiirrrreeeeccccttttoooorrrryyyy ////ttttmmmmpppp____mmmmnnnntttt This option is used to specify the directory prefix used by the file system auto-mounter, usually ////ttttmmmmpppp____mmmmnnnntttt, to mount remote file systems in NFS environments. Use this option to strip the prefix, if present, to improve the readability of source filenames in Purify reports. Note: If your automounter alters the prefix, instead of adding a prefix, use: ----aaaauuuuttttoooommmmoooouuuunnnntttt----pppprrrreeeeffffiiiixxxx====////ttttmmmmpppp____mmmmnnnntttt////hhhhoooommmmeeee::::////hhhhoooommmmeeeessss to specify that the real file name is constructed from the apparent one by replacing ////ttttmmmmpppp____mmmmnnnntttt////hhhhoooommmmeeee with ////hhhhoooommmmeeeessss. If this option is not set correctly, Purify may be unable to access files on auto-mounted filesystems. ----pppprrrrooooggggrrrraaaammmm----nnnnaaaammmmeeee pppprrrrooooggggrrrraaaammmm nnnnaaaammmmeeee aaaarrrrggggvvvv[[[[0000]]]] This option specifies the full pathname of the Purify'd pro- gram if aaaarrrrggggvvvv[[[[0000]]]] contains an undesirable or incorrect value. This can happen if you change aaaarrrrggggvvvv[[[[0000]]]] in your program, or if your program is invoked by an eeeexxxxeeeecccc(((()))) call whose path differs from the argument it passes as aaaarrrrggggvvvv[[[[0000]]]] to your program. In such cases, Purify can not find the program file, and Printed 1/6/97 15 Jan 1996 21 Purify(1) LICENSED SOFTWARE Purify(1) therefore can not interpret addresses as function names. You may need to use this option if you find little or no symbolic information in the messages from your Purify'd pro- gram. ----uuuusssseeeerrrr----ppppaaaatttthhhh ddddiiiirrrr lllliiiisssstttt nnnnoooonnnneeee This option specifies a colon-separated list of directories in which to search to find programs and source code. For example, if you have a source tree in your home directory but you also link with GNU source code, you could use: ----uuuusssseeeerrrr----ppppaaaatttthhhh====////hhhhoooommmmeeee////cccchhhhrrrriiiissss////ssssrrrrcccc::::////uuuussssrrrr////llllooooccccaaaallll////ggggnnnnuuuu////ssssrrrrcccc Purify searches for the executable file from which to read the symbol table in your $PATH, and then in directories listed in ----uuuusssseeeerrrr----ppppaaaatttthhhh. See also ----pppprrrrooooggggrrrraaaammmm----nnnnaaaammmmeeee. When searching for source-code to show in the Viewer, and for editing, Purify looks for the file in the full pathname specified in the compiled-in debug data, then in directories listed in ----uuuusssseeeerrrr----ppppaaaatttthhhh, and finally in the current directory. ----sssshhhhoooowwww----ddddiiiirrrreeeeccccttttoooorrrryyyy bbbboooooooolllleeeeaaaannnn nnnnoooo This option shows the directory path for each file in the call chain if that information is present. This information may not be available if the file is not compiled with the compiler debug option (usually ----gggg). ----sssshhhhoooowwww----ppppcccc bbbboooooooolllleeeeaaaannnn nnnnoooo This option shows the full pc value in each frame of the call chain, facilitating debugging. ----sssshhhhoooowwww----ppppcccc----ooooffffffffsssseeeetttt bbbboooooooolllleeeeaaaannnn nnnnoooo This option appends to each function name in the call chain the offset of the pc from the start of the function, facili- tating debugging. ----ffffrrrreeeeeeeezzzzeeee----oooonnnn----eeeerrrrrrrroooorrrr bbbboooooooolllleeeeaaaannnn nnnnoooo If this option is set, when an error is reported to the Purify Viewer, it will delay sending the response back to the application, which will usually cause the application to freeze. This is useful to explore the relationship between error reports and program activity. While the application is frozen, two new buttons appear at the bottom of the mes- sage region. Press "CCCCoooonnnnttttiiiinnnnuuuueeee" to continue to the next error, and "RRRReeeesssseeeetttt ffffrrrreeeeeeeezzzzeeee----oooonnnn----eeeerrrrrrrroooorrrr tttthhhheeeennnn ccccoooonnnnttttiiiinnnnuuuueeee" to continue Printed 1/6/97 15 Jan 1996 22 Purify(1) LICENSED SOFTWARE Purify(1) uninterrupted. Note: Do not attempt to use this feature when running with a debugger. Instead set a debugger breakpoint in the function ppppuuuurrrriiiiffffyyyy____ssssttttoooopppp____hhhheeeerrrreeee(((()))): (dbx) ssssttttoooopppp iiiinnnn ppppuuuurrrriiiiffffyyyy____ssssttttoooopppp____hhhheeeerrrreeee (gdb) bbbbrrrreeeeaaaakkkk ppppuuuurrrriiiiffffyyyy____ssssttttoooopppp____hhhheeeerrrreeee (xdb) bbbb ppppuuuurrrriiiiffffyyyy____ssssttttoooopppp____hhhheeeerrrreeee This is because while the application is frozen by the viewer, so is the debugger, and you cannot examine variables or obtain stack traces. MMMMeeeemmmmoooorrrryyyy LLLLeeeeaaaakkkk OOOOppppttttiiiioooonnnnssss ((((rrrruuuunnnn----ttttiiiimmmmeeee ooooppppttttiiiioooonnnnssss)))) ----lllleeeeaaaakkkkssss----aaaatttt----eeeexxxxiiiitttt bbbboooooooolllleeeeaaaannnn yyyyeeeessss This option specifies whether or not memory leaked or poten- tially leaked should be reported at program exit. Memory leaked is memory that has been allocated but has no pointers to it, and so cannot be freed. ----iiiinnnnuuuusssseeee----aaaatttt----eeeexxxxiiiitttt bbbboooooooolllleeeeaaaannnn nnnnoooo This option specifies whether or not memory in use should be reported at program exit. Memory in use is memory that has been allocated but not freed and has valid pointers to it. ----ffffddddssss----iiiinnnnuuuusssseeee----aaaatttt----eeeexxxxiiiitttt bbbboooooooolllleeeeaaaannnn yyyyeeeessss This option specifies whether or not file descriptors in use should be reported at program exit. File descriptors in use are file descriptors that have been opened, duplicated, or inherited from the parent process. ----ffffrrrreeeeeeee----qqqquuuueeeeuuuueeee----lllleeeennnnggggtttthhhh iiiinnnntttteeeeggggeeeerrrr 111100000000 This option sets the number of entries in the free queue maintained by Purify. When you free memory, Purify stores it into a FIFO queue. When the queue length is exceeded, the block queued earliest is freed and made available for re-use. This helps Purify detect free memory accesses (FMW, FMR). If you have plenty of swap space, you can use this option to increase the number of entries queued to increase the likelihood of detecting free memory accesses. ----ffffrrrreeeeeeee----qqqquuuueeeeuuuueeee----tttthhhhrrrreeeesssshhhhoooolllldddd iiiinnnntttteeeeggggeeeerrrr 11110000000000000000 This option sets the maximum size of freed blocks to be appended to the Purify free queue. Chunks larger than this are immediately freed and not queued. If you have plenty of Printed 1/6/97 15 Jan 1996 23 Purify(1) LICENSED SOFTWARE Purify(1) swap space, you can use this option to increase the size of entries queued to increase the likelihood of detecting free memory accesses. ----ppppooooiiiinnnntttteeeerrrr----ooooffffffffsssseeeetttt iiiinnnntttteeeeggggeeeerrrr 0000 This option tells Purify the size of the extra memory allo- cated by a custom malloc wrapper. If you use a malloc wrapper that allocates extra memory for bookkeeping purposes over and above the size requested, and returns an adjusted pointer past the extra memory allocated, Purify may incorrectly report potential leaks. This option ensures that Purify does not report false PLKs. ----ppppooooiiiinnnntttteeeerrrr----mmmmaaaasssskkkk hhhheeeexxxx----mmmmaaaasssskkkk 0000xxxxffffffffffffffffffffffffffffffff This option specifies a mask that will allow Purify to extract the correct value from custom pointers. If your application ORs flags into the upper bits of heap pointers, Purify cannot follow them to the memory chunks they refer to, and may incorrectly report leaks. For example, if you use the upper 4 bits of pointers for flags, use: ----ppppooooiiiinnnntttteeeerrrr----mmmmaaaasssskkkk====0000xxxx0000ffffffffffffffffffffffffffff ----sssseeeeaaaarrrrcccchhhh----mmmmmmmmaaaappppssss bbbboooooooolllleeeeaaaannnn nnnnoooo This option tells Purify to search for heap pointers in mmap'd memory. This option is necessary if you store heap pointers in mmap'd memory. It is automatically set if you use ObjectStore (OSCC). AAAAddddddddiiiittttiiiioooonnnnaaaallll OOOOppppttttiiiioooonnnnssss ((((rrrruuuunnnn----ttttiiiimmmmeeee ooooppppttttiiiioooonnnnssss)))) ----hhhhaaaannnnddddlllleeee----ssssiiiiggggnnnnaaaallllssss ssssiiiiggggnnnnaaaallll lllliiiisssstttt nnnnoooonnnneeee ----iiiiggggnnnnoooorrrreeee----ssssiiiiggggnnnnaaaallllssss ssssiiiiggggnnnnaaaallll lllliiiisssstttt ssssyyyysssstttteeeemmmm ddddeeeeppppeeeennnnddddeeeennnntttt Purify issues a SIG message whenever the program receives a signal that would be fatal. If you want Purify to report any non-fatal signals, specify them with the ----hhhhaaaannnnddddlllleeee----ssssiiiiggggnnnnaaaallllssss option. If you do not want Purify to report on some sig- nals, specify them with the ----iiiiggggnnnnoooorrrreeee----ssssiiiiggggnnnnaaaallllssss option. This allows you to specify exactly which signals Purify reports. The option value is a comma-delimited list of signal names. The default value of ----iiiiggggnnnnoooorrrreeee----ssssiiiiggggnnnnaaaallllssss is system dependent. The defaults are: +o SunOS 4.1.x: SIGHUP,SIGINT,SIGQUIT,SIGILL,SIGTRAP,SIGIOT, SIGABRT,SIGEMT,SIGFPE,SIGKILL,SIGBUS,SIGSEGV, SIGSYS,SIGPIPE,SIGTERM,SIGXCPU,SIGXFSZ,SIGLOST, SIGUSR1,SIGUSR2 Printed 1/6/97 15 Jan 1996 24 Purify(1) LICENSED SOFTWARE Purify(1) +o Solaris 2.x: SIGHUP,SIGINT,SIGQUIT,SIGILL,SIGTRAP,SIGIOT, SIGABRT,SIGEMT,SIGFPE,SIGKILL,SIGBUS,SIGSEGV, SIGSYS,SIGPIPE,SIGTERM,SIGUSR1,SIGUSR2,SIGPOLL, SIGXCPU,SIGXFSZ,SIGFREEZE,SIGTHAW,SIGRTMIN, SIGRTMAX +o HP-UX: SIGHUP,SIGINT,SIGQUIT,SIGILL,SIGTRAP,SIGABRT, SIGEMT,SIGFPE,SIGKILL,SIGBUS,SIGSEGV,SIGSYS, SIGPIPE,SIGTERM,SIGUSR1,SIGUSR2,SIGLOST, SIGRESERVE,SIGDIL For instance, if you want Purify to report on the non-fatal signals SIGALRM and SIGVTALRM, use: ----hhhhaaaannnnddddlllleeee----ssssiiiiggggnnnnaaaallllssss====SSSSIIIIGGGGAAAALLLLRRRRMMMM,,,,SSSSIIIIGGGGVVVVTTTTAAAALLLLRRRRMMMM If you do not want Purify to report on the fatal signal SIGSEGV because your program handles it, use: ----iiiiggggnnnnoooorrrreeee----ssssiiiiggggnnnnaaaallllssss====SSSSIIIIGGGGSSSSEEEEGGGGVVVV Note: Purify does not handle SIGSTOP, SIGKILL, and SIGTRAP signals, since doing so interferes with debuggers and Purify's own operation. See the man pages for ssssiiiiggggnnnnaaaallll(((()))) and ssssiiiiggggmmmmaaaasssskkkk(((()))), and the files ////uuuussssrrrr////iiiinnnncccclllluuuuddddeeee////ssssiiiiggggnnnnaaaallll....hhhh and ////uuuussssrrrr////iiiinnnncccclllluuuuddddeeee////ssssyyyyssss////ssssiiiiggggnnnnaaaallll....hhhh for more information on signals. ----wwwwaaaattttcccchhhhppppooooiiiinnnnttttssss----ffffiiiilllleeee ffffiiiilllleeee----nnnnaaaammmmeeee ....////%%%%vvvv....wwwwaaaattttcccchhhhppppooooiiiinnnnttttssss This option specifies the filename where watchpoint settings should be maintained. The default value is ....////%%%%vvvv....wwwwaaaattttcccchhhhppppooooiiiinnnnttttssss; the %%%%vvvv will be expanded to the name of your Purify'd program, thus allowing you to save watchpoints for multiple programs in the same directory. To disable saving watchpoints in a file, set this option to an empty filename, using: ----wwwwaaaattttcccchhhhppppooooiiiinnnnttttssss----ffffiiiilllleeee==== ----eeeexxxxiiiitttt----ssssttttaaaattttuuuussss bbbboooooooolllleeeeaaaannnn nnnnoooo This option enables you to control the exit status of your Purify'd program, based on the types of unsuppressed mes- sages reported. Purify ORs special bits into the exit status of the program having the following meanings: 0000xxxx44440000 MMMMeeeemmmmoooorrrryyyy aaaacccccccceeeessssssss eeeerrrrrrrroooorrrrssss 0000xxxx22220000 MMMMeeeemmmmoooorrrryyyy lllleeeeaaaakkkkssss Printed 1/6/97 15 Jan 1996 25 Purify(1) LICENSED SOFTWARE Purify(1) 0000xxxx11110000 PPPPooootttteeeennnnttttiiiiaaaallll mmmmeeeemmmmoooorrrryyyy lllleeeeaaaakkkkssss TTTThhhhrrrreeeeaaaaddddssss OOOOppppttttiiiioooonnnnssss ((((rrrruuuunnnn----ttttiiiimmmmeeee ooooppppttttiiiioooonnnnssss)))) ----tttthhhhrrrreeeeaaaaddddssss bbbboooooooolllleeeeaaaannnn nnnnoooo This option tells Purify that the program uses multiple threads. If set, Purify will keep track of threads, and will use appropriate mutex locks to operate in a thread-safe manner. This option is set automatically if you link with any of the supported threads libraries. ----mmmmaaaaxxxx----tttthhhhrrrreeeeaaaaddddssss iiiinnnntttteeeeggggeeeerrrr 22220000 This option specifies the maximum number of threads that will be used in the program. ----tttthhhhrrrreeeeaaaadddd----ssssttttaaaacccckkkk----cccchhhhaaaannnnggggeeee iiiinnnntttteeeeggggeeeerrrr 0000xxxx1111000000000000 This option specifies the maximum size of a change to the stack pointer that does not indicate a context change between threads. Changes larger than this value inform Purify that the threads package is switching from one thread to another. Multi-threaded programs that allocate large objects on the stack may need to increase this value. Multi-threaded programs that allocate stack space for dif- ferent threads close to each other may need to decrease this value. ----tttthhhhrrrreeeeaaaadddd----rrrreeeeppppoooorrrrtttt----aaaatttt----eeeexxxxiiiitttt bbbboooooooolllleeeeaaaannnn yyyyeeeessss This option specifies whether or not Purify should generate a report on thread usage at program exit. The thread report includes information about the number of threads, and stack space used by each thread. AAAAPPPPPPPPLLLLIIIICCCCAAAATTTTIIIIOOOONNNN PPPPRRRROOOOGGGGRRRRAAAAMMMMMMMMIIIINNNNGGGG IIIINNNNTTTTEEEERRRRFFFFAAAACCCCEEEE Purify's application programming interface can be used by programs as necessary and in interactive debugging environ- ments like dbx, gdb, and xdb. MMMMeeeemmmmoooorrrryyyy LLLLeeeeaaaakkkkssss AAAAPPPPIIII Printed 1/6/97 15 Jan 1996 26 Purify(1) LICENSED SOFTWARE Purify(1) iiiinnnntttt ppppuuuurrrriiiiffffyyyy____nnnneeeewwww____lllleeeeaaaakkkkssss(((()))) This function prints an incremental message including all new leaks. New leaks are leaks introduced since the last call to the functions ppppuuuurrrriiiiffffyyyy____nnnneeeewwww____lllleeeeaaaakkkkssss(((()))) or ppppuuuurrrriiiiffffyyyy____cccclllleeeeaaaarrrr____lllleeeeaaaakkkkssss(((()))). iiiinnnntttt ppppuuuurrrriiiiffffyyyy____aaaallllllll____lllleeeeaaaakkkkssss(((()))) This function prints a summary message of all memory leaks. iiiinnnntttt ppppuuuurrrriiiiffffyyyy____cccclllleeeeaaaarrrr____lllleeeeaaaakkkkssss(((()))) This function finds leaks and marks them cleared so that the function ppppuuuurrrriiiiffffyyyy____nnnneeeewwww____lllleeeeaaaakkkkssss(((()))) will not report them. It does not print a message. It is useful, for example, for ignor- ing all leaks from a certain portion of code, perhaps a start-up sequence. iiiinnnntttt ppppuuuurrrriiiiffffyyyy____nnnneeeewwww____iiiinnnnuuuusssseeee(((()))) This function prints an incremental message including all new heap memory allocations. This is memory allocated since the last call to the functions ppppuuuurrrriiiiffffyyyy____nnnneeeewwww____iiiinnnnuuuusssseeee(((()))) or ppppuuuurrrriiiiffffyyyy____cccclllleeeeaaaarrrr____iiiinnnnuuuusssseeee(((()))). iiiinnnntttt ppppuuuurrrriiiiffffyyyy____aaaallllllll____iiiinnnnuuuusssseeee(((()))) This function prints a summary message of all heap memory currently allocated. iiiinnnntttt ppppuuuurrrriiiiffffyyyy____cccclllleeeeaaaarrrr____iiiinnnnuuuusssseeee(((()))) This function finds memory in use and notes it as found so future calls to the function ppppuuuurrrriiiiffffyyyy____nnnneeeewwww____iiiinnnnuuuusssseeee(((()))) will not report it. This function does not print a message. Note that all of the leak detection functions return the totals of the unsuppressed leaks or memory in-use. This simplifies usage both programmatically and in the debugger: (dbx) pppprrrriiiinnnntttt ppppuuuurrrriiiiffffyyyy____nnnneeeewwww____lllleeeeaaaakkkkssss(((()))) (dbx) pppprrrriiiinnnntttt ppppuuuurrrriiiiffffyyyy____aaaallllllll____iiiinnnnuuuusssseeee(((()))) (dbx) ssssttttoooopppp iiiinnnn eeeevvvveeeennnntttt____lllloooooooopppp iiiiffff ((((ppppuuuurrrriiiiffffyyyy____nnnneeeewwww____lllleeeeaaaakkkkssss(((()))))))) LLLLooooggggffffiiiilllleeee AAAAPPPPIIII iiiinnnntttt ppppuuuurrrriiiiffffyyyy____llllooooggggffffiiiilllleeee____pppprrrriiiinnnnttttffff((((cccchhhhaaaarrrr**** _f_m_t,,,, ............)))) This function does a formatted print to the logfile, if the ----lllloooogggg----ffffiiiilllleeee option is set, or to the mail mode report, if the ----mmmmaaaaiiiillll----ttttoooo----uuuusssseeeerrrr option is set. This function does nothing if Printed 1/6/97 15 Jan 1996 27 Purify(1) LICENSED SOFTWARE Purify(1) neither option is set. iiiinnnntttt ppppuuuurrrriiiiffffyyyy____pppprrrriiiinnnnttttffff((((cccchhhhaaaarrrr**** _f_m_t,,,, ............)))) This function does a formatted print to the logfile, if the ----lllloooogggg----ffffiiiilllleeee option is set, to the mail mode report, if the ----mmmmaaaaiiiillll----ttttoooo----uuuusssseeeerrrr option is set, or to the standard error stream if neither is set. iiiinnnntttt ppppuuuurrrriiiiffffyyyy____pppprrrriiiinnnnttttffff____wwwwiiiitttthhhh____ccccaaaallllllll____cccchhhhaaaaiiiinnnn((((cccchhhhaaaarrrr**** _f_m_t,,,, ............)))) This function does a formatted print to the logfile, if the ----lllloooogggg----ffffiiiilllleeee option is set, to the mail mode report, if the ----mmmmaaaaiiiillll----ttttoooo----uuuusssseeeerrrr option is set, or to the standard error stream if neither is set. It also prints the call chain leading up to this function call. For example: iiiiffff ((((ddddeeeetttteeeecccctttt____eeeerrrrrrrroooorrrr)))) {{{{ ppppuuuurrrriiiiffffyyyy____pppprrrriiiinnnnttttffff____wwwwiiiitttthhhh____ccccaaaallllllll____cccchhhhaaaaiiiinnnn (((( """"FFFFoooouuuunnnndddd bbbbaaaadddd iiiinnnnppppuuuutttt vvvvaaaalllluuuueeee %%%%dddd////nnnn"""",,,, iiiinnnn____vvvvaaaallll))));;;; }}}} This will display the specified string and the function call sequence to this point. This might help track errant func- tion call requests without stepping through the debugger. In this manner, the function ppppuuuurrrriiiiffffyyyy____pppprrrriiiinnnnttttffff____wwwwiiiitttthhhh____ccccaaaallllllll____cccchhhhaaaaiiiinnnn(((()))) extends the power of debugging using pppprrrriiiinnnnttttffff(((()))). PPPPoooooooollll AAAAllllllllooooccccaaaattttiiiioooonnnn AAAAPPPPIIII vvvvooooiiiidddd ppppuuuurrrriiiiffffyyyy____sssseeeetttt____ppppoooooooollll____iiiidddd((((cccchhhhaaaarrrr**** _m_e_m,,,, iiiinnnntttt _i_d)))) This function sets the pool-id of memory _m_e_m to _i_d. vvvvooooiiiidddd ppppuuuurrrriiiiffffyyyy____sssseeeetttt____uuuusssseeeerrrr____ddddaaaattttaaaa((((cccchhhhaaaarrrr**** _m_e_m,,,, vvvvooooiiiidddd**** _d_a_t_a)))) This function sets the auxiliary user data associated with the pool of memory _m_e_m to _d_a_t_a. iiiinnnntttt ppppuuuurrrriiiiffffyyyy____ggggeeeetttt____ppppoooooooollll____iiiidddd((((cccchhhhaaaarrrr**** _m_e_m)))) This function returns the pool-id associated with the pool of memory _m_e_m. vvvvooooiiiidddd**** ppppuuuurrrriiiiffffyyyy____ggggeeeetttt____uuuusssseeeerrrr____ddddaaaattttaaaa((((cccchhhhaaaarrrr**** _m_e_m)))) This function returns the auxiliary user data associated Printed 1/6/97 15 Jan 1996 28 Purify(1) LICENSED SOFTWARE Purify(1) with the pool of memory _m_e_m. vvvvooooiiiidddd ppppuuuurrrriiiiffffyyyy____mmmmaaaapppp____ppppoooooooollll((((iiiinnnntttt _i_d,,,, vvvvooooiiiidddd ((((****_f_n)))) ((((cccchhhhaaaarrrr****,,,, uuuunnnnssssiiiiggggnnnneeeedddd)))))))) This function applies the function _f_n to all members of the pool of memory identified by pool-id _i_d. vvvvooooiiiidddd ppppuuuurrrriiiiffffyyyy____mmmmaaaapppp____ppppoooooooollll____iiiidddd((((vvvvooooiiiidddd ((((****_f_n)))) ((((cccchhhhaaaarrrr****,,,, uuuunnnnssssiiiiggggnnnneeeedddd)))))))) This function applies the function _f_n to each pool-id known to the system. WWWWaaaattttcccchhhhppppooooiiiinnnnttttssss AAAAPPPPIIII iiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh((((cccchhhhaaaarrrr**** _a_d_d_r)))) iiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh_____n_u_m((((cccchhhhaaaarrrr**** _a_d_d_r)))) iiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____wwww_____n_u_m((((cccchhhhaaaarrrr**** _a_d_d_r)))) _n_u_m====1111,,,,2222,,,,4444,,,,8888 These functions allow you to specify watchpoints that detect writes, allocations, frees, and entry and exit of memory addresses. The ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh_____n_u_m(((()))) and ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____wwww_____n_u_m(((()))) functions are identical. You can specify watchpoints for 1, 2, 4 or 8 byte variables using these functions; for example, to set a write-type watchpoint for eight bytes, use: (dbx) pppprrrriiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____wwww____8888((((mmmmyyyy____ddddoooouuuubbbblllleeee____ppppttttrrrr)))) ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh(((()))) watches 4 bytes. These functions return the number assigned to the watchpoint. iiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____rrrr_____n_u_m((((cccchhhhaaaarrrr**** _a_d_d_r)))) _n_u_m====1111,,,,2222,,,,4444,,,,8888 These functions allow you to specify watchpoints that detect reads, mallocs, frees, and entry and exit of memory addresses. You can specify watchpoints for 1, 2, 4, and 8 byte variables using these functions; for example, to set a read-type watchpoint for one byte, use: (dbx) pppprrrriiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____rrrr____1111((((&&&&rrrreeeeaaaadddd____oooonnnnllllyyyy____cccchhhhaaaarrrr)))) These functions return the number assigned to the watch- point. iiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____rrrrwwww_____n_u_m((((cccchhhhaaaarrrr**** _a_d_d_r)))) _n_u_m====1111,,,,2222,,,,4444,,,,8888 These functions allow you to specify watchpoints that detect reads, writes, mallocs, and entry and exit of memory addresses. You can specify watchpoints for 1, 2, 4, and 8 byte variables using these functions; for example, to set a read-and-write-type watchpoint for two bytes, use: Printed 1/6/97 15 Jan 1996 29 Purify(1) LICENSED SOFTWARE Purify(1) (dbx) pppprrrriiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____rrrrwwww____2222((((&&&&rrrrwwww____sssshhhhoooorrrrtttt)))) These functions return the number assigned to the watch- point. iiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____nnnn((((cccchhhhaaaarrrr**** _a_d_d_r,,,, uuuunnnnssssiiiiggggnnnneeeedddd iiiinnnntttt _s_i_z_e,,,, cccchhhhaaaarrrr**** _t_y_p_e)))) This function allows you to set a watchpoint on an arbitrary sized buffer. _a_d_d_r specifies the address of the beginning of the buffer, _s_i_z_e specifies the number of bytes to watch, and _t_y_p_e specifies whether you want to watch for writes, with "wwww"; reads, with "rrrr"; or both, with "rrrrwwww". For example: (dbx) pppprrrriiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____nnnn((((wwwwrrrriiiitttteeee____oooonnnnllllyyyy____bbbbuuuuffff,,,, 111100000000,,,, """"wwww"""")))) (dbx) pppprrrriiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____nnnn((((&&&&lllloooonnnngggg____lllloooonnnngggg,,,, 11116666,,,, """"rrrr"""")))) (dbx) pppprrrriiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____nnnn((((bbbbuuuuffff,,,, ssssiiiizzzzeeeeooooffff((((bbbbuuuuffff)))),,,, """"rrrrwwww"""")))) This function returns the number assigned to the watchpoint. Note: invoking ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____nnnn(((()))) in a debugger, you can use integer values 1111, 2222, and 3333 for "rrrr", "wwww", and "rrrrwwww" respec- tively if your debugger makes it hard to call functions with string arguments. iiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____iiiinnnnffffoooo(((()))) This function lists the active watchpoints. This function returns 0. iiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____rrrreeeemmmmoooovvvveeee((((iiiinnnntttt _w_a_t_c_h_n_o)))) iiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____rrrreeeemmmmoooovvvveeee____aaaallllllll(((()))) The function ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____rrrreeeemmmmoooovvvveeee(((()))) removes the watchpoint specified by _w_a_t_c_h_n_o. The function ppppuuuurrrriiiiffffyyyy____wwwwaaaattttcccchhhh____rrrreeeemmmmoooovvvveeee____aaaallllllll(((()))) removes all watchpoints. Both of these functions return 0. AAAAddddddddiiiittttiiiioooonnnnaaaallll FFFFuuuunnnnccccttttiiiioooonnnnssss iiiinnnntttt ppppuuuurrrriiiiffffyyyy____ddddeeeessssccccrrrriiiibbbbeeee((((cccchhhhaaaarrrr**** _a_d_d_r)))) This function prints specific details about the memory pointed to by _a_d_d_r, including its location (stack, heap, text, etc.) and, for heap memory, the call chains of its malloc and free history. iiiinnnntttt ppppuuuurrrriiiiffffyyyy____wwwwhhhhaaaatttt____ccccoooolllloooorrrrssss((((cccchhhhaaaarrrr**** _a_d_d_r,,,, uuuunnnnssssiiiiggggnnnneeeedddd iiiinnnntttt _s_i_z_e)))) This function prints out the memory state of _s_i_z_e bytes starting at memory address _a_d_d_r. The letters RRRRYYYYGGGGBBBB each show the color of one byte of memory, and represent RRRRed, YYYYellow, GGGGreen, and BBBBlue. Printed 1/6/97 15 Jan 1996 30 Purify(1) LICENSED SOFTWARE Purify(1) +o RRRReeeedddd: The heap memory is initially red. Red means that the memory is unallocated and uninitialized. It has either never been allocated or it has been allocated and subsequently freed. It is illegal to read, write or free red memory because it is not owned by the pro- gram. +o YYYYeeeelllllllloooowwww: Memory returned by malloc is yellow. Yellow means that the memory has been allocated, but is unini- tialized. The program now owns this memory. It is legal to write yellow memory, or free it if it was allocated by malloc, but it is illegal to read it because it is uninitialized. Stack frames are set to yellow upon function entry. +o GGGGrrrreeeeeeeennnn: Once yellow memory has been written, it becomes green. Green means that the memory is allocated and initialized. It is legal to read or write green memory, or free it if it was allocated by malloc. The data and bss sections of memory (initialized and zeroed global memory and static data) are automatically ini- tialized to the green state. +o BBBBlllluuuueeee: Memory which has been freed after it was initial- ized and used is blue. Blue means that the memory has been initialized, but is no longer valid for access. It is illegal to read, write or free blue memory. iiiinnnntttt ppppuuuurrrriiiiffffyyyy____iiiissss____rrrruuuunnnnnnnniiiinnnngggg(((()))) This function returns 1 if the executable is Purify'd, 0 otherwise. This function may be used to enclose special purpose application code to execute in the Purify'd environ- ment. For example: iiiiffff ((((ppppuuuurrrriiiiffffyyyy____iiiissss____rrrruuuunnnnnnnniiiinnnngggg(((()))))))) {{{{ iiiinnnnssssttttaaaallllllll____gggguuuuiiii____lllleeeeaaaakkkkssss____bbbbuuuuttttttttoooonnnn(((())));;;; }}}} iiiinnnntttt ppppuuuurrrriiiiffffyyyy____aaaasssssssseeeerrrrtttt____iiiissss____rrrreeeeaaaaddddaaaabbbblllleeee((((ccccoooonnnnsssstttt cccchhhhaaaarrrr**** _a_d_d_r,,,, iiiinnnntttt _s_i_z_e)))) iiiinnnntttt ppppuuuurrrriiiiffffyyyy____aaaasssssssseeeerrrrtttt____iiiissss____wwwwrrrriiiittttaaaabbbblllleeee((((ccccoooonnnnsssstttt cccchhhhaaaarrrr**** _a_d_d_r,,,, iiiinnnntttt _s_i_z_e)))) These functions are used to assert the readability or writa- bility of the address specified by _a_d_d_r for _s_i_z_e bytes. The function ppppuuuurrrriiiiffffyyyy____aaaasssssssseeeerrrrtttt____iiiissss____rrrreeeeaaaaddddaaaabbbblllleeee(((()))) returns 1 if the memory is allocated and initialized (green), otherwise 0, whereas ppppuuuurrrriiiiffffyyyy____aaaasssssssseeeerrrrtttt____iiiissss____wwwwrrrriiiittttaaaabbbblllleeee(((()))) returns 1 if the memory is allo- Printed 1/6/97 15 Jan 1996 31 Purify(1) LICENSED SOFTWARE Purify(1) cated (yellow or green), otherwise 0. vvvvooooiiiidddd ppppuuuurrrriiiiffffyyyy____eeeexxxxiiiitttt((((iiiinnnntttt _s_t_a_t_u_s)))) This function calls the exit system call, but arranges to have the exit status augmented to show whether Purify detected access errors (0x40), memory leaks (0x20), or potential memory leaks (0x10). The appropriate bits are ORed into the status passed to ppppuuuurrrriiiiffffyyyy____eeeexxxxiiiitttt(((()))). FFFFIIIILLLLEEEESSSS ****____ppppuuuurrrreeee____**** Cached object and library files translated by Purify. _p_u_r_i_f_y_h_o_m_e////ccccaaaacccchhhheeee////............ Central cache directory structure for caching translated object files and libraries when they cannot be written alongside the original files. ....ppppuuuurrrreeee, ....lllloooocccckkkk....**** Locking files preventing simultaneous file access by more than one user. ....ppppuuuurrrriiiiffffyyyy, ....ppppuuuurrrriiiiffffyyyy....ssssuuuunnnnoooossss4444, ....ppppuuuurrrriiiiffffyyyy....ssssoooollllaaaarrrriiiissss2222, ....ppppuuuurrrriiiiffffyyyy....hhhhppppuuuuxxxx Used to specify suppression directives for Purify. ****....wwwwaaaattttcccchhhhppppooooiiiinnnnttttssss Watchpoint settings saved from one run to the next. _p_u_r_i_f_y_h_o_m_e////PPPPuuuurrrriiiiffffyyyy....ppppuuuurrrreeeellllaaaa Contains passwords and a list of regular users for use by the Pure License Advisor. _p_u_r_i_f_y_h_o_m_e////ppppuuuurrrriiiiffffyyyy....hhhh Include file to use with Purify API. _p_u_r_i_f_y_h_o_m_e////ppppuuuurrrriiiiffffyyyy____ssssttttuuuubbbbssss....aaaa Library to be included to provide dummy Purify API function definitions for use when not linking under Purify. _p_u_r_i_f_y_h_o_m_e////PPPPuuuurrrriiiiffffyyyy....XXXXRRRReeeessssoooouuuurrrrcccceeeessss Default X resource values. SSSSEEEEEEEE AAAALLLLSSSSOOOO ppppuuuurrrreeeeccccoooovvvv((((1111)))), rrrreeeeppppuuuurrrriiiiffffyyyy((((1111)))), ddddbbbbxxxx((((1111)))), ggggddddbbbb((((1111)))) CCCCAAAAVVVVEEEEAAAATTTTSSSS Occasionally, wild random pointers accidentally point into a valid heap block. Purify checks pointer validity, and not pointer arithmetic, and thus cannot signal an error in such cases. Purify's watchpoints can help you track down such Printed 1/6/97 15 Jan 1996 32 Purify(1) LICENSED SOFTWARE Purify(1) wild pointer errors. A Purify'd program normally runs about 3 to 5 times slower, and takes about 40% more memory, than if not processed by Purify. Occasionally the additional memory required will cause the paging behavior to degrade performance to a greater degree. In this case, running the Purify'd program on a machine with more memory would be advantageous. Programs instrumented on one version of Solaris may crash or generate incorrect results if run on a different version of the operating system. A Purify'd program can, because of its different memory usage patterns, cause code that works by accident to behave slightly differently. For example, values read from unini- tialized or unallocated locations can differ with and without Purify. You will get Purify error messages for all such code. Purify will not change the behavior of your code in any other way. If Purify does change the behavior of the program (except as mentioned above), or produces incorrect error reports, please report such bugs to the appropriate address: Contact us in the US at: support@pure.com or (408) 720 1600 In Europe: support@europe.pure.com or (+31) 2356 94310 In Japan: support@japan.pure.com or (03) 3863 9283 Printed 1/6/97 15 Jan 1996 33