mpatrol A library for controlling and tracing dynamic memory allocations Edition 2.13 for mpatrol version 1.4.8 8th January, 2002 Graeme S. Roy Copyright c 1997-2002 Graeme S. Roy <[email protected]> Permission is granted to make and distribute verbatim copies of this manual provided the copy- right notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the condi- tions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation. All product names mentioned in the documentation and source code for this library are the trademarks of their respective owners. i Table of Contents mpatrol ......................................... 1 Foreword ........................................ 3 1 Overview..................................... 5 2 Features ..................................... 7 3 Installation.................................. 13 4 Integration .................................. 15 4.1 Adding mpatrol ............................................ 15 4.2 Removing mpatrol.......................................... 17 5 Memory allocations .......................... 19 5.1 Static memory allocations ................................... 19 5.2 Stack memory allocations ................................... 19 5.3 Dynamic memory allocations ................................ 20 6 Operating system support.................... 21 6.1 Virtual memory ............................................ 21 6.2 Call stacks and symbol tables ............................... 22 6.3 Threads ................................................... 24 7 Using mpatrol ............................... 27 7.1 Library behaviour .......................................... 27 7.2 Logging and tracing ........................................ 28 7.3 General errors.............................................. 30 7.4 Overwrites and underwrites ................................. 30 7.5 Using with a debugger ...................................... 32 7.6 Testing .................................................... 36 7.7 Library functions ........................................... 37 7.8 Leak table ................................................. 45 8 Tools ....................................... 49 8.1 Dbmalloc-compatible functions .............................. 49 8.2 Dmalloc-compatible functions ............................... 50 8.3 Determining heap differences ................................ 51 8.4 Memory allocation gauge.................................... 51 8.5 Memory allocation tracing .................................. 51 ii mpatrol 9 Utilities ..................................... 53 9.1 The mpatrol command ..................................... 53 9.2 The mleak command ....................................... 55 9.3 The mpsym command ....................................... 55 9.4 The mpedit command ...................................... 56 9.5 The hexwords command .................................... 57 10 Profiling ................................... 59 11 Tracing .................................... 73 12 Heap corruption ............................ 81 13 Memory leaks .............................. 87 14 Improving performance ..................... 89 15 How it works............................... 93 16 Examples .................................. 95 16.1 Getting started............................................ 96 16.2 Detecting incorrect reuse of freed memory .................. 104 16.3 Detecting use of free memory.............................. 106 16.4 Using overflow buffers .................................... 109 16.5 Checking memory accesses ................................ 110 16.6 Bad memory operations................................... 111 16.7 Incompatible function calls................................ 112 16.8 The alloca() functions .................................. 113 16.9 The MP_MALLOC() functions ............................... 119 16.10 Additional useful information ............................ 121 17 Tutorial................................... 129 Appendix A Functions ........................ 137 A.1 C dynamic memory allocation functions .................... 137 A.2 C dynamic memory extension functions..................... 141 A.3 C dynamic memory alternative functions ................... 142 A.4 C++ dynamic memory allocation functions .................. 143 A.5 C memory operation functions ............................. 144 A.6 mpatrol library functions .................................. 146 Appendix B Environment ..................... 153 Appendix C Options ......................... 161 Appendix D Diagnostic messages .............. 167 Appendix E Library performance.............. 175 iii Appendix F File formats...................... 177 F.1 Profiling file format ....................................... 177 F.2 Tracing file format ........................................ 178 Appendix G Supported systems ............... 179 Appendix H Porting.......................... 185 Appendix I Notes ............................ 193 I.1 Notes for all platforms ..................................... 193 I.2 Notes for UNIX platforms .................................. 198 I.3 Notes for Amiga platforms ................................. 199 I.4 Notes for Windows platforms ............................... 200 I.5 Notes for Netware platforms ................................ 200 Appendix J Frequently asked questions ........ 203 J.1 Documentation............................................ 203 J.2 Building .................................................. 204 J.3 Linking ................................................... 206 J.4 Running .................................................. 207 J.5 Files ..................................................... 211 Appendix K Related software ................. 213 Appendix L References ....................... 233 Appendix M About the author ................ 235 Appendix N Copying ......................... 237 Function index ................................ 247 Index ......................................... 249 iv mpatrol mpatrol 1 mpatrol This document describes mpatrol, a library for controlling and tracing dynamic memory allocations. This is edition 2.13 of the mpatrol manual for version 1.4.8, 8th January, 2002. 2 mpatrol Foreword 3 Foreword I first started writing this library a few years ago when the company I work for sent me out to a customer who had reported a memory leak, which he expected was coming from the code generated by our C++ compiler. A few years on and the library has changed dramatically from its first beginnings, but I thought I'd release it publicly in case anyone else found it useful. When writing the library, I placed more emphasis on the quantity and quality of information about allocated memory rather than the speed and efficiency of allocating the actual memory. This means that the library will use dramatically more memory than normal dynamic memory allocation libraries and can slow down to a crawl depending on which options you use. However, the end results are likely to be accurate and reliable, and in most cases the library will run quite happily at a sane speed. The mpatrol library is by no means the only library of its kind. Solaris has no less that 6 different malloc libraries, and there are plenty available as freeware or as commercial products. Try to keep in mind that mpatrol comes with absolutely no warranty and so if it doesn't work for you and you need a fast solution, try some of the other libraries or products available. I have listed some of the most popular at the end of this manual (see Appendix K [Related software], page 213). This manual is arranged so that complete reference material on the mpatrol library can be found in the appendices, while introductory and background material can be found in the preceding chapters and sections. For readers who wish to delve right in and use the library, the Installation (see Chapter 3 [Installation], page 13) and Examples (see Chapter 16 [Examples], page 95) chapters should be enough to get started in combination with the quick reference card. Otherwise, this manual should be read from beginning to end in order to get the most out of the software it describes. Note that all of the output shown from the examples was produced on 32-bit environments, although mpatrol can be built to support 64-bit environments as well. Due to their very nature, problems with dynamic memory allocations are notoriously difficult to reproduce and debug, and this is likely to be the case if you find a bug in the mpatrol library as it might be extremely hard to reproduce on another system. Details on how to report bugs are given elsewhere in this document (see Appendix I [Notes], page 193), but it would be very useful if you could try to provide as much information as possible when reporting a problem, and that includes having a look in the library source code to see if it's obvious what is wrong. However, please try to read the frequently asked questions (see Appendix J [Frequently asked questions], page 203) first in case your question or problem is covered there since they are usually updated every time I receive a question about mpatrol. The latest version