Purify User’s Guide Version 4.0 [email protected] http://www.pure.com IMPORTANT NOTICE DISCLAIMER OF WARRANTY Pure Software Inc. makes no representations or warranties, either express or implied, by or with respect to anything in this guide, and shall not be liable for any implied warranties of merchantability or fitness for a particular purpose or for any indirect, special or consequential damages. COPYRIGHT NOTICE Purify, copyright 1992-1996 Pure Software Inc. All rights reserved. Purify, PureCoverage, and Quantify are covered by one or more of U.S. Patent Nos. 5,193,180, 5,335,344, and 5,535,329. Purify is licensed under Sun Microsystems Inc.'s U.S. Pat. No. 5,404,499. Other U.S. and foreign patents pending. No part of this publication may be reproduced, stored in a retrieval system or transmitted, in any form or by any means, photocopying, recording or otherwise, without prior written consent of Pure Software Inc. No patent liability is assumed with respect to the use of the information contained herein. While every precaution has been taken in the preparation of this book, Pure Software Inc. assumes no responsibility for errors or omissions. This publication and features described herein are subject to change without notice. The program and information contained herein are licensed only pursuant to a license agreement that contains use, reverse engineering, disclosure and other restrictions; accordingly, it is “Unpublished — rights reserved under the copyright laws of the United States” for purposes of the FARs. RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure by the Government is subject to the restrictions as set forth in subparagraph (c) (1) (a) of the Rights in Technical Data and Computer Software clause of the DFARs 252.227-7013 and FAR 52.227-19(c) and any successor rules or regulations. TRADEMARKS Pure Software, PureCoverage, Quantify, PureLink, and Purify are U. S. registered trademarks of Pure Software Inc. PureVision, PureDDTS, WebTracker, WebTrackerLite, and the Pure Software logo are U. S. trademarks of Pure Software Inc. All other products or services mentioned in this guide are covered by the trademarks, service marks, or product names as designated by the companies who market those products. Printed in the U.S.A. on recycled paper. PURIFY USER’S GUIDE Contents Welcome to Purify Getting started . .xi Mastering the basics . .xi Learning to use special features . .xi Using the reference chapters . xii Using online Help . xii Conventions used in this guide . xiii Displaying the release notes . xiii Installing Purify . xiii Contacting technical support . xiv 1 Introducing Purify When to use Purify . 1-2 Starting to use Purify . 1-3 Getting the most out of Purify . 1-5 Customizing Purify . 1-5 Using your debugger with Purify . 1-5 Calling Purify’s API functions . 1-6 Integrating Purify into makefiles and scripts . 1-6 Using Purify with other Pure Software products . 1-7 Using Purify with PureCoverage . 1-7 Using PureLink with Purify and PureCoverage . 1-8 Using Purify with PureDDTS . 1-8 Using Purify with PureTestExpert . 1-8 Checking for memory errors . 1-9 Memory access errors . 1-9 Accessing through dangling pointers . 1-9 iii Uninitialized memory reads . 1-10 Memory allocation errors . 1-10 Memory leaks . 1-11 Errors in third-party code and libraries . 1-11 2 Finding Errors in Hello World Before you start . 2-2 Building a Purify’d program . 2-3 Compiling and linking in separate stages . 2-3 Running a Purify’d program . 2-4 Using the Purify Viewer . 2-5 Analyzing an ABR message . 2-6 Using line numbers and source filenames . 2-7 Finding the exact location of the error . 2-8 Correcting the ABR error . 2-9 Looking at the file descriptors message . 2-10 Understanding the memory leaked summary . 2-11 Looking at the MLK error . 2-12 Looking at the exit status summary . 2-14 Rerunning a Purify’d program . 2-15 3 Memory Access Errors How Purify finds memory access errors . 3-2 How Purify checks statically allocated memory . 3-4 Notes and limitations . 3-5 Building the testHash example program . 3-6 Running the testHash program without Purify . 3-7 Running the Purify’d testHash program . 3-8 Debugging the testHash program . 3-9 Debugging with dbx . 3-9 Debugging with xdb . 3-10 Reading uninitialized memory . 3-11 A UMR example . 3-11 iv Finding the cause of the UMR error . 3-13 Correcting the UMR error . 3-13 Reading and writing beyond the bounds of an array . 3-14 An ABW example . 3-14 Finding the cause of the ABW error . 3-15 Correcting the ABW error . 3-16 An ABR example . 3-16 Reading or writing freed memory . 3-17 An FMR example . 3-18 Finding the cause of the FMR error . 3-19 Correcting the FMR error . 3-20 Freeing unallocated or non-heap memory . 3-21 An FNH example . 3-21 Finding the cause of the FNH error . 3-22 Correcting the FNH error . 3-23 4 Memory Leaks How Purify reports memory leaks . 4-1 Notes and limitations . 4-3 Finding the memory leaks in testHash . 4-4 Finding the source of memory leaks . 4-6 Using your debugger to set breakpoints . 4-7 Running purify_new_leaks . 4-8 Correcting the error . 4-10 Using the new leaks button . 4-10 Disabling memory leaked messages . 4-11 5 Analyzing File Descriptors File descriptors in use messages . 5-1 File descriptor leak example . 5-3 Analyzing FIU messages . 5-4 Disabling FIU messages . 5-4 Notes and limitations . 5-4 v 6 Customizing Purify Controlling Purify output . 6-2 Saving Purify output as ASCII text . 6-2 Saving Purify output to a view file . 6-3 Prestarting the Viewer . 6-5 Mailing Purify output to developers . 6-6 Using the -mail-to-user-option . 6-6 Protecting your run-time option settings . 6-6 Annotating Purify’s output . 6-7 Customizing Purify messages . 6-9 Controlling the content and appearance of messages . 6-9 Controlling message batching . 6-9 Customizing the thread summary message . 6-10 Enabling JIT debugging . 6-11 Reporting Purify status at exit . 6-13 Running shell scripts at exit . 6-14 Customizing the Purify Viewer . 6-15 Customizing Purify scripts . 6-16 Customizing the program controls . 6-17 Managing cached object files . 6-19 Deleting cached object files . ..