1This is mpatrol.info, produced by makeinfo version 4.0 from 2mpatrol.texi. 3 4INFO-DIR-SECTION Programming tools 5START-INFO-DIR-ENTRY 6* mpatrol: (mpatrol). The mpatrol library. 7END-INFO-DIR-ENTRY 8 9 This file documents mpatrol, a library for controlling and tracing 10dynamic memory allocations. 11 12 Copyright (C) 1997-2002 Graeme S. Roy <graeme.roy@analog.com> 13 14 This is edition 2.13 of the mpatrol manual for version 1.4.8, 8th 15January, 2002. 16 17 Permission is granted to make and distribute verbatim copies of this 18manual provided the copyright notice and this permission notice are 19preserved on all copies. 20 21 Permission is granted to copy and distribute modified versions of 22this manual under the conditions for verbatim copying, provided that 23the entire resulting derived work is distributed under the terms of a 24permission notice identical to this one. 25 26 Permission is granted to copy and distribute translations of this 27manual into another language, under the above conditions for modified 28versions, except that this permission notice may be stated in a 29translation approved by the Free Software Foundation. 30 31 All product names mentioned in the documentation and source code for 32this library are the trademarks of their respective owners. 33 34 35File: mpatrol.info, Node: Top, Next: Foreword, Up: (dir) 36 37mpatrol 38******* 39 40 _ _ 41 | | | | 42 ____ ___ _____ _____ _| |_ _____ ____ | | 43| _ ~ _ \ | __ \ / __ | |_ _| | ___| / __ \ | | 44| | | | | | | | | | | | | | | | | | | | | | | | 45| | | | | | | |__| | | |__| | | | | | | |__| | | | 46|_| |_| |_| | ___/ \_____| |_| |_| \____/ |_| 47 | | 48 |_| 49 50 This document describes mpatrol, a library for controlling and 51tracing dynamic memory allocations. 52 53 This is edition 2.13 of the mpatrol manual for version 1.4.8, 8th 54January, 2002. 55 56* Menu: 57 58* Foreword:: Motivation and feedback. 59* Overview:: Overview of mpatrol. 60* Features:: Features of mpatrol. 61* Installation:: Building and installing. 62* Integration:: Debugging existing programs. 63* Memory allocations:: Background. 64* Operating system support:: Additional background. 65* Using mpatrol:: Using the library. 66* Tools:: Additional tools. 67* Utilities:: External programs. 68* Profiling:: Memory allocation profiling. 69* Tracing:: Memory allocation tracing. 70* Heap corruption:: Squashing those errors. 71* Memory leaks:: Detection and identification. 72* Improving performance:: Life beyond mpatrol. 73* How it works:: Implementation details. 74* Examples:: Examples of usage. 75* Tutorial:: Complete example. 76* Functions:: Library functions. 77* Environment:: Library run-time options. 78* Options:: Command line options. 79* Diagnostic messages:: Warnings and errors. 80* Library performance:: Comparitive timings. 81* File formats:: Output file layouts. 82* Supported systems:: Known platforms that mpatrol runs on. 83* Porting:: How to port mpatrol to a new system. 84* Notes:: Known bugs and future enhancements. 85* Frequently asked questions:: For answering specific problems. 86* Related software:: Similar programs. 87* References:: Additional information. 88* About the author:: Information about me. 89* Copying:: GNU Library General Public License. 90* Function index:: Library functions. 91* Index:: Main index. 92 93 94File: mpatrol.info, Node: Foreword, Next: Overview, Prev: Top, Up: Top 95 96Foreword 97******** 98 99 I first started writing this library a few years ago when the 100company I work for sent me out to a customer who had reported a memory 101leak, which he expected was coming from the code generated by our C++ 102compiler. A few years on and the library has changed dramatically from 103its first beginnings, but I thought I'd release it publicly in case 104anyone else found it useful. 105 106 When writing the library, I placed more emphasis on the quantity and 107quality of information about allocated memory rather than the speed and 108efficiency of allocating the actual memory. This means that the 109library will use dramatically more memory than normal dynamic memory 110allocation libraries and can slow down to a crawl depending on which 111options you use. However, the end results are likely to be accurate 112and reliable, and in most cases the library will run quite happily at a 113sane speed. 114 115 The mpatrol library is by no means the only library of its kind. 116Solaris has no less that 6 different malloc libraries, and there are 117plenty available as freeware or as commercial products. Try to keep in 118mind that mpatrol comes with absolutely no warranty and so if it 119doesn't work for you and you need a fast solution, try some of the 120other libraries or products available. I have listed some of the most 121popular at the end of this manual (*note Related software::). 122 123 This manual is arranged so that complete reference material on the 124mpatrol library can be found in the appendices, while introductory and 125background material can be found in the preceding chapters and 126sections. For readers who wish to delve right in and use the library, 127the Installation (*note Installation::) and Examples (*note Examples::) 128chapters should be enough to get started in combination with the quick 129reference card. Otherwise, this manual should be read from beginning 130to end in order to get the most out of the software it describes. Note 131that all of the output shown from the examples was produced on 32-bit 132environments, although mpatrol can be built to support 64-bit 133environments as well. 134 135 Due to their very nature, problems with dynamic memory allocations 136are notoriously difficult to reproduce and debug, and this is likely to 137be the case if you find a bug in the mpatrol library as it might be 138extremely hard to reproduce on another system. Details on how to 139report bugs are given elsewhere in this document (*note Notes::), but 140it would be very useful if you could try to provide as much information 141as possible when reporting a problem, and that includes having a look 142in the library source code to see if it's obvious what is wrong. 143However, please try to read the frequently asked questions (*note 144Frequently asked questions::) first in case your question or problem is 145covered there since they are usually updated every time I receive a 146question about mpatrol. 147 148 The latest version of the mpatrol library and this manual can always 149be found at `http://www.cbmamiga.demon.co.uk/mpatrol/', and any 150correspondence relating to mpatrol (bug reports, enhancement requests, 151compliments, etc.) should be sent to <mpatrol@cbmamiga.demon.co.uk>. 152I'd be very interested in hearing any success stories with using 153mpatrol to debug programs, since I get very little feedback apart from 154the occasional bug report. The mpatrol library is also registered at 155FreshMeat (`http://freshmeat.net/projects/mpatrol/') and SourceForge 156(`http://sourceforge.net/projects/mpatrol/') and several other software 157sites so you can receive notification of updates there as well. I 158normally only check my e-mail about once or twice a week, so don't 159expect an immediate response. I can also be reached at 160<graeme.roy@analog.com> but that is my work e-mail address. There is 161also a discussion group at `http://groups.yahoo.com/group/mpatrol/' 162where you can post mpatrol-related questions but you must first 163subscribe to the group before you can send mail to it. 164 165 Finally, I'd like to thank Stephan Springl (<springl@bfw-online.de>) 166for his help on reading debugging information from object files via the 167GNU BFD library, and Adam Zell (<zell@best.com>) for helping with 168patching the dynamic linker support functions for loading shared 169libraries. Both Alexander Barton (<abarton@innotrac.com>) and Dave 170Gibson (<david.gibson@analog.com>) helped to make mpatrol thread-safe. 171Roger Keane (<rgr@bcs-inc.com>) provided the perl code in the `mpsym' 172command and also the idea for the `MP_USE_ATEXIT' feature macro. Steve 173McIntyre (<smcintyre@allstor-sw.co.uk>) helped by diagnosing the 174`fork()' problem and provided example code on how to fix it. Peter 175Zijlstra (<peter@xlnt-software.com>) contributed code to enhance stack 176traces for errors. 177 178 Boris Makushkin (<oberon@antibiotic.ru>) requested, helped with, and 179provided initial testing for the FreeBSD port, and Ivan Finch 180(<i.finch@rl.ac.uk>), Gerrit Bruchhaeuser (<gbruchhaeuser@orga.com>) 181and Andreas Schallenberg 182(<andreas.schallenberg@informatik.uni-oldenburg.de>) did the same for 183the Tru64 and SuSE ports. Both Aleksandar Donev (<donev@pa.msu.edu>) 184and Van Snyder (<vsnyder@math.jpl.nasa.gov>) provided suggestions and 185code for using mpatrol with FORTRAN. Michael Anthony (<m@xyzfind.com>) 186wrote the profdiff tool and Jerome Marant (<jerome@debian.org>) did the 187Debian GNU/Linux port. 188 189 In addition, after spending well over 2000 hours designing and 190programming mpatrol, my sanity would not have been preserved in the 191state it is in today were it not for the music of The Chemical 192Brothers, The Manic Street Preachers, Orbital and The Prodigy. You can 193now argue how sane I am depending on your musical tastes! 194 195 Oh, and always remember to do final release builds without the 196mpatrol library as the library is much slower than normal malloc 197implementations and uses much more memory. 198 199 Happy debugging! 200 201 Graeme Roy, 11th October, 1999. 202 203 Edinburgh, Scotland. 204 205 206File: mpatrol.info, Node: Overview, Next: Features, Prev: Foreword, Up: Top 207 208Overview 209******** 210 211 The mpatrol library is yet another link library that attempts to 212diagnose run-time errors that are caused by the wrong use of 213dynamically allocated memory. If you don't know what the `malloc()' 214function or `operator new[]' do then this library is probably not for 215you. You have to have a certain amount of programming expertise and a 216knowledge of how to run a command line compiler and linker before you 217should attempt to use this. 218 219 Along with providing a comprehensive and configurable log of all 220dynamic memory operations that occurred during the lifetime of a 221program, the mpatrol library performs extensive checking to detect any 222misuse of dynamically allocated memory. All of this functionality can 223be integrated into existing code through the inclusion of a single 224header file at compile-time. On UNIX and Windows platforms (and 225AmigaOS when using `gcc') this may not even be necessary as the mpatrol 226library can be linked with existing object files at link-time or, on 227some platforms, even dynamically linked with existing programs at 228run-time. 229 230 All logging and tracing output from the mpatrol library is sent to a 231separate log file in order to keep its diagnostics separate from any 232that the program being tested might generate. A wide variety of 233library settings can also be changed at run-time via an environment 234variable, thus removing the need to recompile or relink in order to 235change the library's behaviour. 236 237 A file containing a summary of the memory allocation profiling 238statistics for a particular program can be produced by the mpatrol 239library. This file can then be read by a profiling tool which will 240display a set of tables based upon the accumulated data. The profiling 241information includes summaries of all of the memory allocations listed 242by size and the function that allocated them and a list of memory leaks 243with the call stack of the allocating function. It also includes a 244graph of all memory allocations listed in tabular form, and an optional 245graph specification file for later processing by the `dot' graph 246visualisation package. 247 248 A file containing a concise encoded trace of all memory allocations, 249reallocations and deallocations made by a program can also be produced 250by the mpatrol library. This file can then be read by a tracing tool 251which will decode the trace and display the events in tabular or 252graphical form, and also display any relevant statistics that could be 253calculated. 254 255 The mpatrol library has been designed with the intention of 256replacing calls to existing C and C++ memory allocation functions as 257seamlessly as possible, but in many cases that may not be possible and 258slight code modifications may be required. However, a preprocessor 259macro containing the version of the mpatrol library is provided for the 260purposes of conditional compilation so that release builds and debug 261builds can be easily automated. 262 263 264File: mpatrol.info, Node: Features, Next: Installation, Prev: Overview, Up: Top 265 266Features 267******** 268 269 An overall list of features contained in the mpatrol library is 270given below. This is not intended to be exhaustive since the best way 271to see what the library does is to read the documentation and try it 272out. 273 274 * Written for 32-bit and 64-bit UNIX, AmigaOS, Windows and Netware 275 platforms. Contains direct support for (and takes advantage of 276 most of the features of) AIX, DG/UX, DRS/NX, DYNIX/ptx, FreeBSD, 277 HP/UX, IRIX, Linux, LynxOS, NetBSD, OpenBSD, SINIX, Solaris, 278 SunOS, Tru64 and UnixWare. Also contains target-specific code to 279 take advantage of Alpha, Intel 80x86, Motorola 680x0 and 88xx0, 280 MIPS, HP PA/RISC, IBM RS/6000, PowerPC and SPARC processors. 281 282 * Has the ability to read symbols from executable files and shared 283 libraries in the `a.out', COFF, XCOFF, ELF32, ELF64 and Windows 284 Portable Executable file formats, and if the GNU BFD library is 285 available then the mpatrol library can read symbols from all of 286 the file formats that it has support for as well. Can also liase 287 with AIX, BSD-based, HP/UX, IRIX, OSF, SVR4-based and Windows 288 dynamic linkers in order to find out information about shared 289 libraries. 290 291 * Can be built to allocate memory from a fixed-sized static array 292 rather than using heap memory from the system. 293 294 * Can be built as archive, shared and/or thread-safe libraries on 295 systems that support them, or even as one large object file. A 296 lint library can also be built from the mpatrol library on UNIX 297 platforms. 298 299 * A release version of the mpatrol library is provided, which has 300 the same functional interface, but does not contain any of 301 mpatrol's debugging, tracing or profiling features. It is 302 intended to be used to quickly remove the mpatrol library. 303 304 * Details of memory allocations and free memory are stored 305 internally as a tree structure for speed and also to allow the 306 best fit allocation algorithm to be used. This also enables the 307 library to perform intelligent resizing of memory allocations and 308 can be used to quickly determine if an address has been allocated 309 on the heap. 310 311 * Contains 19 replacement C dynamic memory allocation functions: 312 313 `malloc()' ANSI Allocates memory. 314 `calloc()' ANSI Allocates zero-filled memory. 315 `memalign()' UNIX Allocates memory with a specified alignment. 316 `valloc()' UNIX Allocates page-aligned memory. 317 `pvalloc()' UNIX Allocates a number of pages. 318 `alloca()' old Allocates temporary memory. 319 `strdup()' UNIX Duplicates a string. 320 `strndup()' old Duplicates a string with a maximum length. 321 `strsave()' old Duplicates a string. 322 `strnsave()' old Duplicates a string with a maximum length. 323 `strdupa()' old Duplicates a string. 324 `strndupa()' old Duplicates a string with a maximum length. 325 `realloc()' ANSI Resizes memory. 326 `reallocf()' BSD Resizes memory and frees on failure. 327 `recalloc()' old Resizes memory allocated by `calloc()'. 328 `expand()' old Resizes memory but does not relocate it. 329 `free()' ANSI Frees memory. 330 `cfree()' old Frees memory allocated by `calloc()'. 331 `dealloca()' new Explicitly frees temporary memory. 332 333 * Contains 5 replacement C dynamic memory extension functions: 334 335 `xmalloc()' Allocates memory without failure. 336 `xcalloc()' Allocates zero-filled memory without failure. 337 `xstrdup()' Duplicates a string without failure. 338 `xrealloc()' Resizes memory without failure. 339 `xfree()' Frees memory. 340 341 * Contains 6 replacement C dynamic memory alternative functions: 342 343 `MP_MALLOC()' Allocates memory without failure. 344 `MP_CALLOC()' Allocates zero-filled memory without failure. 345 `MP_STRDUP()' Duplicates a string without failure. 346 `MP_REALLOC()' Resizes memory without failure. 347 `MP_FREE()' Frees memory. 348 `MP_FAILURE()' Sets the allocation failure handler. 349 350 * Contains 4 replacement C++ dynamic memory allocation operators (in 351 both _throw_ and _nothrow_ forms): 352 353 `operator new' Allocates memory. 354 `operator new[]' Allocates memory for an array. 355 `operator delete' Frees memory. 356 `operator delete[]' Frees memory allocated by `operator new[]'. 357 358 * Contains 10 replacement C memory operation functions: 359 360 `memset()' ANSI Fills memory with a specific byte. 361 `bzero()' UNIX Fills memory with the zero byte. 362 `memccpy()' UNIX Copies memory up to a specific byte. 363 `memcpy()' ANSI Copies non-overlapping memory. 364 `memmove()' ANSI Copies possibly-overlapping memory. 365 `bcopy()' UNIX Copies possibly-overlapping memory. 366 `memcmp()' ANSI Compares two blocks of memory. 367 `bcmp()' UNIX Compares two blocks of memory. 368 `memchr()' ANSI Searches memory for a specific byte. 369 `memmem()' UNIX Searches memory for specific bytes. 370 371 * All of the above functions can also be defined with an additional 372 underscore prepended to their external name in order to catch all 373 uses of these functions in the system and third-party libraries. 374 375 * Contains support for a user-defined low-memory handler function, 376 including a replacement for the C++ function, `set_new_handler()'. 377 378 * The C++ dynamic memory allocation operators make use of the 379 preprocessor in order to obtain source-level information. If this 380 causes problems then replacement operator names may be used so 381 that the existing operators will still work. 382 383 * Contains support for automatically registering any functions whose 384 names begin with `__mp_init_' and `__mp_fini_' to be called when 385 the mpatrol library is initialised and terminated respectively. A 386 function is also provided to register additional functions to be 387 called when the mpatrol library terminates. 388 389 * Contains support for user-defined prologue and epilogue callback 390 functions, which get called before and after every memory 391 allocation, reallocation or deallocation. 392 393 * A function is provided to return as much information as possible 394 about a given memory allocation or free block, and can be called 395 at any time during program execution. A similar function is also 396 provided for calling from within a debugger and an example command 397 file is provided for use with `gdb'. 398 399 * A function is provided to display library settings and heap usage 400 statistics, including peak memory usage. This information is also 401 displayed at program termination, and can also be placed into a 402 data structure at run-time via another function. 403 404 * The library reads any user-controllable options at run-time from 405 an environment variable, but this does not have to be set as 406 defaults will then be used. This prevents having to recompile 407 anything in order to change any library settings. An option 408 exists to display a quick-reference summary of all of the 409 recognised options to the standard error file stream. Library 410 settings can also be set and read from within user code after the 411 library has been initialised by calling two internal functions. 412 413 * All diagnostics and logging are sent to a file in the current 414 directory, but this can be overridden, including forcing the log 415 file to be the standard output or standard error file streams. An 416 environment variable specifying a default directory in which to 417 place log files can also be set. 418 419 * Options exist to log details of every memory allocation, 420 reallocation or deallocation when they occur. A function exists 421 to log the details of any memory allocation to the mpatrol log 422 file. 423 424 * Options exist to halt the program at a specific memory allocation, 425 reallocation or deallocation when running the program within a 426 debugger. These options have no effect when running the program 427 without a debugger. 428 429 * An option exists to enable memory allocation profiling, which 430 forces a summary of all memory allocation statistics to be written 431 to a specified file for later use by a profiling command. The 432 profiling file can also be written at a specified frequency. An 433 environment variable specifying a default directory in which to 434 place profiling output files can also be set. 435 436 * A profiling command is provided which reads a profiling output 437 file produced by the mpatrol library and displays a set of tables 438 based on the accumulated data. The profiling information includes 439 summaries of all of the memory allocations listed by size and the 440 function that allocated them and a list of memory leaks with the 441 call stack of the allocating function. It also includes a graph 442 of all memory allocations listed in tabular form, and an optional 443 graph specification file for later processing by the `dot' graph 444 visualisation package. 445 446 * An option exists to enable memory allocation tracing, which forces 447 certain details for every memory allocation event to be written to 448 a specified file for later use by a tracing command. The tracing 449 file is written in a concise encoded form so as to keep the size 450 of the file down. An environment variable specifying a default 451 directory in which to place tracing output files can also be set. 452 453 * A tracing command is provided which reads a tracing output file 454 produced by the mpatrol library and displays the memory allocation 455 events in tabular or graphical form. It also displays any 456 relevant statistics that could be calculated, and has options to 457 write out the trace in HATF format or write out a trace-driven 458 memory allocation simulation program as C source code. 459 460 * On UNIX platforms, the `mmap()' function can optionally be used to 461 allocate user memory instead of the `sbrk()' function, but only if 462 the system supports it. If `mmap()' is supported then internal 463 mpatrol library memory is normally allocated with this function in 464 order to segregate it from user memory but this behaviour can be 465 swapped around. 466 467 * On non-UNIX platforms where the mpatrol library overrides 468 `malloc()' without requiring the inclusion of `mpatrol.h', 469 versions of the UNIX functions `brk()' and `sbrk()' are provided 470 for compatibility with certain libraries. These should _not_ be 471 called by user code as they have only limited functionality. 472 473 * All newly-allocated memory that is not allocated by the `calloc()' 474 or `recalloc()' functions will be pre-filled with a non-zero value 475 in order to catch out programs that wrongly assume that all 476 newly-allocated memory is zeroed. This value can be modified at 477 run-time. 478 479 * Can automatically check to see if there have been any illegal 480 writes to bytes located just before and after every memory 481 allocation through the use of overflow buffers. The size of such 482 overflow buffers and the value to pre-fill them with can be 483 modified at run-time. The checks will be performed before every 484 memory allocation call to ensure that nothing has overwritten the 485 overflow buffers, but a function is also provided to perform 486 additional checks under the programmer's control and an option 487 exists to specify a range and frequency in which checks will be 488 performed. 489 490 * On systems that support them, watch point areas can be used 491 instead of overflow buffers so that every read and write to memory 492 is checked to ensure that it is not within an overflow buffer. 493 494 * Supports the `-fcheck-memory-usage' option of `gcc' to check all 495 heap memory accesses in programs that were compiled with that 496 option. Currently this only supports checking that memory 497 accesses do not overflow heap allocations or access free memory, 498 rather than keeping records of individual memory accesses that GNU 499 Checker does. 500 501 * Can automatically check to see if there have been any illegal 502 writes to free memory blocks. The value to pre-fill free memory 503 blocks with can be modified at run-time. The check will be 504 performed before every memory allocation call to ensure that 505 nothing has overwritten the free memory block, but a function is 506 also provided to perform additional checks under the programmer's 507 control and an option exists to specify a range in which checks 508 will be performed. 509 510 * On systems that support memory protection, every memory allocation 511 can optionally be allocated at least one page of memory. That 512 way, any free memory blocks can be made read and write protected 513 so that nothing can access free memory on the heap. An option is 514 provided to specify whether all memory allocations should be 515 allocated at the start or at the end of such pages, and the bytes 516 left over within the pages become overflow buffers. 517 518 * All freed memory allocations can optionally be prevented from 519 being returned to the free memory pool. This is useful for 520 detecting if use is being made of freed memory just after a memory 521 allocation has been freed. The contents of the memory allocation 522 can either be preserved or can be pre-filled with a value in order 523 to detect illegal writes to the freed memory allocation. In 524 addition, only a specified number of recently-freed memory 525 allocations can be prevented from being returned to the free 526 memory pool. Any older freed memory allocations will then 527 eventually be reused. 528 529 * The `alloca()', `strdupa()' and `strndupa()' functions are 530 implemented so that the temporary stack-based allocations that 531 they would normally make are now temporary heap-based allocations 532 that can be traced by mpatrol. Such allocations will be 533 implicitly freed when the function that allocated them returns, 534 but a function also exists to explicitly free them as well. 535 536 * Calls to memory operation functions (such as `memset()' or 537 `memcpy()') have their arguments checked to ensure that they do 538 not pass null pointers or attempt to read or write memory 539 straddling the boundary of a previously allocated memory block, 540 although an option exists to turn such an error into a warning so 541 that the operation can still be performed. Tracing from all such 542 functions can also optionally be written to the log file. 543 544 * The internal data structures used by the library are kept separate 545 from the rest of the memory allocations. On systems that support 546 memory protection, all of these internal data structures will be 547 write-protected in order to prevent corruption by the calling 548 program. This feature can be overridden at run-time as it can 549 slow the program down. 550 551 * Certain signals can be saved and restored on entry to each library 552 function and `errno' is set to `ENOMEM' if memory cannot be 553 allocated, except for the ANSI C++ operators which throw the 554 `std::bad_alloc' exception instead. 555 556 * On systems that support memory protection, the library attempts to 557 detect any illegal memory accesses and display as much information 558 as it can obtain about the address in question and where the 559 illegal memory access occurred. 560 561 * A call stack traceback from any function performing a memory 562 allocation is stored if the library supports this feature on the 563 system it is being run on. This information can then be displayed 564 when information about a specific memory allocation is required. 565 Many different call stack traceback implementations are provided 566 for different platforms. A function is also provided to write the 567 current call stack to the mpatrol log file. 568 569 * Symbol table details from executable files and shared libraries are 570 automatically read on systems that support this feature in order 571 to make the call stack tracebacks more meaningful. An option also 572 exists to display a complete list of the symbols that were read by 573 the library at program termination. A function is also provided 574 to return symbolic information about any code address. 575 576 * Compiler-generated line number tables from any debugging sections 577 that exist in executable files and shared libraries can also be 578 used by the mpatrol library in order to provide more meaningful 579 information in call stack tracebacks. An external command is also 580 provided to make use of a debugger to get such information if one 581 is available. 582 583 * If the library is unable to automatically determine a program's 584 executable filename to read symbols from then an option exists to 585 specify the full path to the program's executable file. 586 587 * Options are provided to edit and list a source file at a specific 588 line number when a warning or error occurs due to that source 589 line. An external command which provides this functionality 590 outwith the mpatrol library is included, and functions are 591 provided to do this from within user code. 592 593 * An option exists to change the default alignment used for 594 general-purpose memory allocations. 595 596 * Contains support for a user-defined limit to available memory 597 which can be useful for stress-testing a program in simulated low 598 memory conditions. 599 600 * Contains a feature to randomly fail a specific frequency of memory 601 allocations which can be useful for stress-testing error recovery 602 code in a program. 603 604 * An option exists to display a complete memory map of the heap at 605 program termination. A function to do this is also available to 606 call at any point during program execution. 607 608 * A function is provided to take a snapshot of the heap at the 609 current point in execution. The value returned by this function 610 can then be used to pinpoint the differences in heap allocation 611 details between that point and a later point in the program. 612 613 * Functions are provided to iterate across all of the current heap 614 allocations and call a user-defined callback function for each one 615 they find. 616 617 * A leak table is provided, which records a flat profile of memory 618 allocation behaviour between two points in a program and is keyed 619 by source file location. Memory allocation events can either be 620 recorded in the leak table automatically via a run-time option or 621 the leak table can be manipulated through several functions. 622 623 * Functions are provided to write user-defined information directly 624 to the mpatrol log file, as well as hexadecimal memory dumps of 625 any memory location. 626 627 * Options exist to display all freed and unfreed memory allocations 628 at program termination in order to detect memory leaks, as well as 629 all free memory blocks. A separate program is also provided for 630 locating memory leaks in unfinished log files. 631 632 * An option exists to abort the program with a failure condition if 633 there are more than a specified number of unfreed memory 634 allocations at program termination. This could be useful for 635 batch testing in order to check that all tests free up most of 636 their allocated memory. 637 638 * Memory allocations can be _marked_ to indicate to the mpatrol 639 library that they should remain allocated for the lifetime of the 640 program and should not be freed or be listed as a memory leak. 641 642 * Functions always report if their arguments are illegal in order to 643 pinpoint any errors, and options exist to perform rigorous 644 checking of arguments when allocating, reallocating and freeing 645 memory. In addition, checking is performed to ensure that memory 646 allocated by `operator new[]' is not freed with `free()' for 647 example. 648 649 * The type of function performing a memory allocation is always 650 stored along with the allocation, as well as the file and line 651 number it was called from. If compiled with `gcc', the function 652 name will also be stored and the thread identifier will be stored 653 if using the thread-safe library. 654 655 * The library uses a header file to redefine the memory allocation 656 functions as macros in order to obtain more information about 657 where they were called from. This is not strictly required on 658 UNIX and Windows platforms (and AmigaOS when using `gcc'), since 659 the library automatically redefines the default system memory 660 allocation functions. All redefinitions in the header can also be 661 disabled by defining the `NDEBUG' preprocessor macro, which also 662 disables the effect of calling any mpatrol library function. 663 664 * A command is supplied to run a program that was linked with the 665 mpatrol library with any specified options on the command line. 666 On some UNIX platforms, an option also exists to override the 667 default memory allocation routines for any dynamically-linked 668 program that was not previously linked with the mpatrol library. 669 670 * The mpatrol library can be built to liaise with Parasoft Inuse, a 671 commercial graphical memory usage tool that can display the 672 current memory map of a running process. Inuse is supplied with 673 Parasoft Insure++. 674 675 * Comes with a library of tools that are built on top of the mpatrol 676 library and can be used to extend it for specific applications. 677 678 * An automake macro is provided to ease the integration of mpatrol 679 into a new or existing project. 680 681 * A small tool is provided to read a dictionary file and display all 682 of the words that can be represented in hexadecimal form. Such 683 hexadecimal constants can be used to initialise variables in user 684 programs in order to aid debugging. 685 686 * The library and tools can be built using the GNU autoconf, 687 automake and libtool utilities. Build scripts are also supplied 688 to build both installation packages and binary distributions. A 689 Linux Software Map file is also provided. 690 691 * A small test suite is provided in order to test basic features. 692 693 * User documentation is currently available in TeXinfo format as 694 well as UNIX manual pages and a quick reference card. The source 695 code for the library and tools can also be formatted for a printed 696 manual. 697 698 699File: mpatrol.info, Node: Installation, Next: Integration, Prev: Features, Up: Top 700 701Installation 702************ 703 704 The mpatrol library was initially developed on an Amiga 4000/040 705running AmigaOS 3.1. I then installed Red Hat Linux 5.1 on my Amiga 706and added support for Linux/m68k. I've now just recently purchased a 707Dell Inspiron 7500 Notebook PC and put my Amiga in retirement, so 708development will now continue on Red Hat Linux 6.2 and above on the 709Intel platform. I've tried my best to make it as easy as possible to 710build and install mpatrol on any system, but it isn't likely to run 711smoothly for everybody. However, there shouldn't be any major problems 712if you perform the following steps. 713 714 Note that if you want to check the integrity of the files that came 715with the mpatrol distribution you can use the `CHECKSUMS' file in the 716`mpatrol' base directory. You must have the `md5sum' command installed 717on your system in order to make use of this file. 718 719 If you wish to use GNU autoconf, automake and libtool to build and 720install mpatrol you may do so by entering the `pkg/auto' directory and 721typing `./setup'. This will construct the directory structure that is 722required by these tools and will also create a `configure' script. 723Please see the `INSTALL' file in that directory for information on how 724to proceed. Note that you can clean up the `pkg/auto' directory by 725typing `make distclean' (if the `configure' script has already been 726run) followed by `./cleanup'. 727 728 For a manual installation, perform the following steps. 729 730 1. Go into the `build' directory and then into the appropriate 731 subdirectory for your system. 732 733 2. Edit the `Makefile' in that directory and check that it is using 734 the appropriate compiler and build tools. The `CC' macro 735 specifies the compiler(1), the `AR' macro specifies the tool used 736 to build the archive library and the `LD' macro specifies the tool 737 to build the shared library. The `CFLAGS' macro specifies 738 compiler options that are always to be used, the `OFLAGS' macro 739 specifies optimisation options for the compiler, the `SFLAGS' macro 740 specifies options to be passed to the compiler when building a 741 shared library and the `TFLAGS' macro specifies options to be 742 passed to the compiler when building a thread-safe library. You 743 may also need to change the library names and library build 744 commands on different systems. 745 746 Note that the generic UNIX `Makefile' contains a macro called 747 `GUISUP' which is set to `false' by default. If it is set to 748 `true' then the `mptrace' command will be built with GUI support 749 enabled. However, your system must contain the correct header 750 files and libraries in order to support this. 751 752 3. Use the `make' command (or equivalent) to build the mpatrol 753 library in archive form. The `all' target builds all possible 754 combinations of the mpatrol library for your system. The `clean' 755 target removes all relevant object files from the current 756 directory, while the `clobber' target also removes all libraries 757 that have been built from the current directory. On some UNIX 758 platforms, the `lint' target will build a `lint' library for the 759 mpatrol library. 760 761 4. If the mpatrol library is to be built with support for Parasoft 762 Inuse then the `MP_INUSE_SUPPORT' preprocessor macro must be 763 defined in the `CFLAGS' portion of the `Makefile' before building. 764 This will ensure that Inuse will be notified of every memory 765 allocation, reallocation and deallocation, but the Insure++ 766 runtime library will also have to be linked in with any program 767 that uses mpatrol. 768 769 5. Copy all of the libraries that have been built into your local 770 library directory. If there were symbolic links created in the 771 `build' directory then these should be recreated in the local 772 library directory rather than simply copying them. You may need 773 to run a command such as `ldconfig' in order for the system to 774 recognise the newly-installed libraries, and you may also need to 775 add the filename of the directory containing the newly-installed 776 libraries to an environment variable such as `LD_LIBRARY_PATH' if 777 you installed the libraries in a non-standard location. 778 779 6. Copy the `mpatrol', `mprof', `mptrace' and `mleak' programs that 780 have been built into your local bin directory. You may also wish 781 to copy the `mpsym', `mpedit' and `hexwords' commands to your 782 local bin directory as well if your system supports Bourne shell 783 scripts. 784 785 7. Go up two directory levels into the `src' directory and copy the 786 `mpatrol.h', `mpalloc.h' and `mpdebug.h' header files into your 787 local include directory. 788 789 8. Go up one directory level into the `tools' directory and copy all 790 of the header files into the `mpatrol' subdirectory (which you'll 791 need to create) in your local include directory. 792 793 9. On UNIX platforms, go up one directory level into the `man' 794 directory and copy the `man1' and `man3' subdirectories to your 795 local man directory. Unfortunately, the location for manual pages 796 varies from system to system so you may or may not also be able to 797 copy the `cat1' and `cat3' subdirectories as well. The `man*' 798 subdirectories contain the unformatted manual pages while the 799 `cat*' subdirectories contain the formatted manual pages. 800 801 10. Go up one directory level into the `doc' directory and examine the 802 files located there. The `mpatrol.texi' file contains the TeXinfo 803 source for this manual and can be translated into a wide variety 804 of documentation formats. The `refcard.tex' file contains the 805 LaTeX source for the quick reference card and can be translated 806 into formats suitable for printing onto a few pages. There should 807 already be translated files in the `doc' directory, but if not you 808 will have to generate them yourself using the `Makefile' provided. 809 You can then install or print these documents. 810 811 The mpatrol library source code can also be formatted for a 812 printed manual for later perusal. The `source' target in the 813 `Makefile' within the `doc' directory can be used to build the 814 source code documentation in DVI, postscript and PDF formats, but 815 be prepared for a large number of pages! 816 817 If you are not installing on a system that supports UNIX manual 818 pages then you should also check in the `man' directory to ensure 819 that there are alternative formats for the mpatrol manual pages 820 that you can install. If not, you will have to generate them 821 yourself using the `Makefile' provided. 822 823 Alternatively, the `pkg' directory contains files that can be used to 824automatically generate a _package_ in a specific format suitable for 825installation on a system. Four package formats (PKG, SD/UX, RPM and 826Debian) and three archive formats are currently supported (generic tape 827archive, LhA and ZIP). 828 829 The first package format is generally used on UNIX SVR4 systems, 830while the second is used on HP/UX systems. The RPM and Debian package 831formats were introduced by Red Hat and Debian respectively for use in 832their Linux distributions. 833 834 The generic tape archive can be used as a distribution for UNIX 835systems where no package format is supported, but it does not contain 836information on how to install the files on the system once they have 837been extracted from the distribution. The LhA and ZIP formats are also 838roughly the same, but the LhA format is intended for Amiga systems and 839is used for Aminet distributions, while the ZIP format is intended for 840Windows systems and is used for WinSite distributions. 841 842 You should really know what you are doing before you attempt to 843build a package, and you should also be aware that some of the package 844files may need to be modified before you begin. 845 846 In addition, a Linux Software Map index file exists in the `pkg/lsm' 847directory. 848 849 Note that the `extra' directory that comes with the mpatrol 850distribution contains several prototype configuration files for certain 851third-party programs. These files should be examined so that you can 852decide whether to integrate their contents into your existing 853configuration files. The purpose of each file is described in the 854relevant sections of this manual. 855 856 ---------- Footnotes ---------- 857 858 (1) On many systems this actually a C++ compiler by default, and 859should be a C++ compiler if you wish to use the C++ operators. 860 861 862File: mpatrol.info, Node: Integration, Next: Memory allocations, Prev: Installation, Up: Top 863 864Integration 865*********** 866 867 This section describes how to go about adding or removing the 868mpatrol library from your code. There are several levels for each 869category so it is worth reading about each before proceeding. 870 871* Menu: 872 873* Adding mpatrol:: Adding mpatrol to your program. 874* Removing mpatrol:: Removing mpatrol from your program. 875 876 877File: mpatrol.info, Node: Adding mpatrol, Next: Removing mpatrol, Up: Integration 878 879Adding mpatrol 880============== 881 882 The following steps should allow you to easily integrate the mpatrol 883library into an existing application, although some of them may not be 884available to do on many platforms. They are listed in the order of 885number of changes required to modify existing code -- the last step 886will require a complete recompilation of all your code. 887 888 1. This step is currently only available on DYNIX/ptx, FreeBSD, IRIX, 889 Linux, NetBSD, OpenBSD, Solaris and Tru64 platforms and on DG/UX 890 4.20MU07(1) or later platforms with the `LD_PRELOAD' feature. 891 892 If your program or application has been dynamically linked with 893 the system C library (`libc.so') or an alternative malloc shared 894 library then you can use the `--dynamic' option to the `mpatrol' 895 command to override the default definitions of `malloc()', etc. at 896 run-time without having to relink your program. If your program 897 is multithreaded then you must also add the `--threads' option to 898 pick up the multithreaded shared libraries instead. 899 900 For example, if your program's executable file is called 901 `testprog' and it accepts an option specifying an input file, you 902 can force the system's dynamic linker to use mpatrol's versions of 903 `malloc()', etc. instead of the default versions by typing: 904 905 mpatrol --dynamic ./testprog -i file 906 907 The resulting log file should be called `mpatrol.<procid>.log' by 908 default (where PROCID is the current process id), but if no such 909 file exists after running the `mpatrol' command then it will not 910 be possible to force the run-time linking of mpatrol functions to 911 your program and you will have to proceed to the next step. Note 912 that the `mpatrol' command overrides any previous setting of the 913 `MPATROL_OPTIONS' environment variable. 914 915 2. This step is currently only available on UNIX and Windows 916 platforms (and AmigaOS when using `gcc'). 917 918 You should be able to link in the mpatrol library when linking 919 your program without having to recompile any of your object files 920 or libraries, but this will only be worthwhile on systems where 921 stack tracebacks are supported, otherwise you should proceed to 922 the next step since there will not be enough information for you 923 to tell where the calls to dynamic memory allocation functions took 924 place. 925 926 Information on how to link the mpatrol library to an application 927 is given at the start of the examples (*note Examples::), but you 928 should note that if your program does not directly call any of the 929 functions in the mpatrol library then it will not be linked in and 930 you will not see a log file being generated when you run it. You 931 can force the linking of the mpatrol library by causing `malloc()' 932 to be undefined on the link line, usually through the use of the 933 `-u' linker option. 934 935 If your program is multithreaded then you must use the thread-safe 936 version of the mpatrol library and possibly also link in the 937 system threads library as well. Not doing this will usually 938 result in your program failing somewhere in the mpatrol library 939 code. 940 941 3. All of the following steps will require you to recompile some or 942 all of your code so that your code calls dynamic memory allocation 943 functions from the mpatrol library rather than the system C 944 library. 945 946 This first step is only available when using `gcc'. 947 948 You can make use of the `gcc' option `-fcheck-memory-usage' which 949 instructs the compiler to place calls to error-checking functions 950 before each access to memory. This can result in a dramatic 951 slowdown of your code so you may wish to limit the use of this 952 option to a few source files, but it does provide a very thorough 953 method of ensuring that you do not access memory beyond the bounds 954 of a memory allocation or attempt to access free memory. However, 955 be aware that the checks are only placed in the bodies of 956 functions that have been compiled with this option and are missing 957 from all functions that have not. You must link in the mpatrol 958 library when using this option, otherwise you will get linker 959 errors. 960 961 The `-fcheck-memory-usage' option was added to `gcc' to support 962 GNU Checker, which can be considered to be the run-time system for 963 this option. GNU Checker also includes the ability to detect 964 reads from uninitialised memory, something that mpatrol does not 965 currently support, and deals with stack objects as well. GNU 966 Checker cannot be used in conjunction with mpatrol. 967 968 4. For this step, if you have a rough idea of where the function 969 calls lie that you would like to trace or test, you need only 970 recompile the relevant source files. You should modify these 971 source files to include the `mpatrol.h' header file before any 972 calls to dynamic memory allocation or memory operation functions. 973 974 However, you should take particular care to ensure that all calls 975 to memory allocation functions in the mpatrol library will be 976 matched by calls to memory reallocation or deallocation functions 977 in the mpatrol library, since if they are unmatched then the log 978 file will either fill up with errors complaining about trying to 979 free unknown allocations, or warnings about unfreed memory 980 allocations at the end of execution. 981 982 5. This step requires you to recompile all of your source files to 983 include the `mpatrol.h' header file. Obviously, this will take 984 the longest amount of time to integrate, but need not require you 985 to change any source files if the compiler you are using has a 986 command line option to include a specific header file before any 987 source files. 988 989 For example, `gcc' comes with a `-include' option which has this 990 feature, so if you had to recompile a source file called `test.c' 991 then the following command would allow you to include `mpatrol.h' 992 without having to modify the source file: 993 994 gcc -include /usr/local/include/mpatrol.h -c test.c 995 996 In all cases, it will be desirable to compile your source files with 997compiler-generated debugging information since that may be able to be 998used by the `USEDEBUG' option or the `mpsym' command. In addition, more 999symbolic information will be available if the executable files have not 1000had their symbol tables stripped from them, although mpatrol can also 1001fall back to using the dynamic symbol table from dynamically linked 1002executable files. 1003 1004 Note that an automake macro is now provided to allow you to 1005integrate mpatrol into a new or existing project that uses the GNU 1006autoconf and automake tools. It is located in `extra/mpatrol.m4', 1007which should be copied to the directory containing all of the local 1008autoconf and automake macros on your system, usually 1009`/usr/local/share/aclocal'. The automake macro it defines is called 1010`AM_WITH_MPATROL', which should be added to the libraries section in 1011the `configure.in' file for your project. It takes one optional 1012parameter specifying whether mpatrol should be included in the project 1013(`yes') or not (`no'). This can also be specified as `threads' if you 1014wish to use the threadsafe version of the mpatrol library. You can 1015override the value of the optional parameter with the `--with-mpatrol' 1016option to the resulting `configure' shell script. 1017 1018 If you are using the `AM_WITH_MPATROL' automake macro then you may 1019wish to use the `mpdebug.h' header file instead of `mpatrol.h'. This 1020ensures that the `MP_MALLOC()' family of functions are always defined, 1021even if libmpatrol or libmpalloc are unavailable. It makes use of the 1022`HAVE_MPATROL' and `HAVE_MPALLOC' preprocessor macros that are 1023controlled by the automake macro, but in other respects behaves in 1024exactly the same way as `mpatrol.h'. 1025 1026 ---------- Footnotes ---------- 1027 1028 (1) Also available on DG/UX 4.20MU05 with patch dgux_R4.20MU05.p59 1029and DG/UX 4.20MU06 with patch dgux_R4.20MU06.p08. 1030 1031 1032File: mpatrol.info, Node: Removing mpatrol, Prev: Adding mpatrol, Up: Integration 1033 1034Removing mpatrol 1035================ 1036 1037 Once you have ironed out all of the problems in your code with the 1038help of the mpatrol library, there will come a time where you wish to 1039build your program without any of its debugging features, either to 1040improve the speed that it runs at, or perhaps even for a release. 1041Choose one of the following steps to help you remove the mpatrol 1042library from your program (you only need to perform them if you linked 1043your program with the mpatrol library). 1044 1045 1. The quickest way to remove the mpatrol library from your 1046 application is to link with libmpalloc instead of libmpatrol. 1047 This contains replacements for all of the mpatrol library 1048 functions, either implementing memory allocation or memory 1049 operation functions with the system C library, or doing nothing in 1050 the functions which perform debugging, profiling or tracing. This 1051 method is a very quick way to remove the mpatrol library but will 1052 not result in very efficient code. 1053 1054 2. The next option is to recompile all of the source files which 1055 include the `mpatrol.h' header file, but this time define the 1056 `NDEBUG' preprocessor macro. This automatically disables the 1057 redefinition of `malloc()', etc. and prevents calls being made to 1058 any mpatrol library functions. Obviously, this option is the most 1059 time-consuming of the two, but will result in the complete removal 1060 of all references to the mpatrol library. 1061 1062 3. The final option is to guard all of the mpatrol-specific code in 1063 your program with a preprocessor macro, possibly called 1064 `HAVE_MPATROL', and then recompiling all of your source code with 1065 this macro undefined. This is the best option but relies on you 1066 having originally made these changes when you first started 1067 integrating the mpatrol library into your program. 1068 1069 Note that if you used the `AM_WITH_MPATROL' automake macro as 1070detailed in the previous section to build your application then you 1071should perform a clean recompilation using the `--without-mpatrol' 1072option to the `configure' shell script in order to completely remove 1073the mpatrol library. 1074 1075 Note also that if you used the `-fcheck-memory-usage' option of the 1076GNU compiler to check all memory accesses then you must recompile 1077without that option in order for your program to run at a reasonable 1078speed. 1079 1080 1081File: mpatrol.info, Node: Memory allocations, Next: Operating system support, Prev: Integration, Up: Top 1082 1083Memory allocations 1084****************** 1085 1086 In the C and C++ programming languages there are generally three 1087different types of memory allocation that can be used to hold the 1088contents of variables. Other programming languages such as Pascal, 1089BASIC and FORTRAN also support some of these types of allocation, 1090although their implementations may be slightly different. 1091 1092* Menu: 1093 1094* Static memory allocations:: Fixed location, fixed size. 1095* Stack memory allocations:: Variable location, fixed size. 1096* Dynamic memory allocations:: Variable location, variable size. 1097 1098 1099File: mpatrol.info, Node: Static memory allocations, Next: Stack memory allocations, Up: Memory allocations 1100 1101Static memory allocations 1102========================= 1103 1104 The first type of memory allocation is known as a _static memory 1105allocation_, which corresponds to file scope variables and local static 1106variables. The addresses and sizes of these allocations are fixed at 1107the time of compilation(1) and so they can be placed in a fixed-sized 1108data area which then corresponds to a section within the final linked 1109executable file. Such memory allocations are called static because 1110they do not vary in location or size during the lifetime of the program. 1111 1112 There can be many types of data sections within an executable file; 1113the three most common are normal data, BSS data and read-only data. 1114BSS data contains variables and arrays which are to be initialised to 1115zero at run-time and so is treated as a special case, since the actual 1116contents of the section need not be stored in the executable file. 1117Read-only data consists of constant variables and arrays whose contents 1118are guaranteed not to change when a program is being run. For example, 1119on a typical SVR4 UNIX system the following variable definitions would 1120result in them being placed in the following sections: 1121 1122 int a; /* BSS data */ 1123 int b = 1; /* normal data */ 1124 const int c = 2; /* read-only data */ 1125 1126 In C the first example would be considered a _tentative_ 1127declaration, and if there was no subsequent definition of that variable 1128in the current translation unit then it would become a _common_ 1129variable in the resulting object file. When the object file gets 1130linked with other object files, any common variables with the same name 1131become one variable, or take their definition from a non-tentative 1132definition of that variable. In the former case, the variable is 1133placed in the BSS section. Note that C++ has no support for tentative 1134declarations. 1135 1136 As all static memory allocations have sizes and address offsets that 1137are known at compile-time and are explicitly initialised, there is very 1138little that can go wrong with them. Data can be read or written past 1139the end of such variables, but that is a common problem with all memory 1140allocations and is generally easy to locate in that case. On systems 1141that separate read-only data from normal data, writing to a read-only 1142variable can be quickly diagnosed at run-time. 1143 1144 ---------- Footnotes ---------- 1145 1146 (1) Or more accurately, at link time. 1147 1148 1149File: mpatrol.info, Node: Stack memory allocations, Next: Dynamic memory allocations, Prev: Static memory allocations, Up: Memory allocations 1150 1151Stack memory allocations 1152======================== 1153 1154 The second type of memory allocation is known as a _stack memory 1155allocation_, which corresponds to non-static local variables and 1156call-by-value parameter variables. The sizes of these allocations are 1157fixed at the time of compilation but their addresses will vary 1158depending on when the function which defines them is called. Their 1159contents are not immediately initialised, and must be explicitly 1160initialised by the programmer upon entry to the function or when they 1161become visible in scope. 1162 1163 Such memory allocations are placed in a system memory area called the 1164_stack_, which is allocated per process(1) and generally grows down in 1165memory. When a function is called, the state of the calling function 1166must be preserved so that when the called function returns, the calling 1167function can resume execution. That state is stored on the stack, 1168including all local variables and parameters. The compiler generates 1169code to increase the size of the stack upon entry to a function, and 1170decrease the size of the stack upon exit from a function, as well as 1171saving and restoring the values of registers. 1172 1173 There are a few common problems using stack memory allocations, and 1174most generally involve uninitialised variables, which a good compiler 1175can usually diagnose at compile-time. Some compilers also have options 1176to initialise all local variables with a bit pattern so that 1177uninitialised stack variables will cause program faults at run-time. 1178As with static memory allocations, there can be problems with reading 1179or writing past the end of stack variables, but as their sizes are 1180fixed these can usually easily be located. 1181 1182 ---------- Footnotes ---------- 1183 1184 (1) Or per thread on some systems. 1185 1186 1187File: mpatrol.info, Node: Dynamic memory allocations, Prev: Stack memory allocations, Up: Memory allocations 1188 1189Dynamic memory allocations 1190========================== 1191 1192 The last type of memory allocation is known as a _dynamic memory 1193allocation_, which corresponds to memory allocated via `malloc()' or 1194`operator new[]'. The sizes, addresses and contents of such memory vary 1195at run-time and so can cause a lot of problems when trying to diagnose 1196a fault in a program. These memory allocations are called dynamic 1197memory allocations because their location and size can vary throughout 1198the lifetime of a program. 1199 1200 Such memory allocations are placed in a system memory area called the 1201_heap_, which is allocated per process on some systems, but on others 1202may be allocated directly from the system in scattered blocks. Unlike 1203memory allocated on the stack, memory allocated on the heap is not 1204freed when a function or scope is exited and so must be explicitly 1205freed by the programmer. The pattern of allocations and deallocations 1206is not guaranteed to be (and is not really expected to be) linear and 1207so the functions that allocate memory from the heap must be able to 1208efficiently reuse freed memory and resize existing allocated memory on 1209request. In some programming languages there is support for a _garbage 1210collector_, which attempts to automatically free memory that has had 1211all references to it removed, but this has traditionally not been very 1212popular for programming languages such as C and C++, and has been more 1213widely used in functional languages like ML(1). 1214 1215 Because dynamic memory allocations are performed at run-time rather 1216than compile-time, they are outwith the domain of the compiler and must 1217be implemented in a run-time package, usually as a set of functions 1218within a linker library. Such a package manages the heap in such a way 1219as to abstract its underlying structure from the programmer, providing 1220a common interface to heap management on different systems. However, 1221this _malloc library_ must decide whether to implement a fast memory 1222allocator, a space-conserving memory allocator, or a bit of both. It 1223must also try to keep its own internal tables to a minimum so as to 1224conserve memory, but this means that it has very little capability to 1225diagnose errors if any occur. 1226 1227 In some compiler implementations there is a builtin function called 1228`alloca()'. This is a dynamic memory allocation function that allocates 1229memory from the stack rather than the heap, and so the memory is 1230automatically freed when the function that called it returns. This is 1231a non-standard feature that is not guaranteed to be present in a 1232compiler, and indeed may not be possible to implement on some 1233systems(2). However, the mpatrol library provides a debugging version 1234of this function (and a few other related functions) on all systems, so 1235that they make use of the heap instead of the stack. 1236 1237 As can be seen from the above paragraphs, dynamic memory allocations 1238are the types of memory allocations that can cause the most problems in 1239a program since almost nothing about them can be used by the compiler 1240to give the programmer useful warnings about using uninitialised 1241variables, using freed memory, running off the end of a 1242dynamically-allocated array, etc. It is these types of memory 1243allocation problems that the mpatrol library loves to get its teeth 1244into! 1245 1246 ---------- Footnotes ---------- 1247 1248 (1) There is currently at least one garbage collection package 1249available for C and C++ (*note Related software::). 1250 1251 (2) Some compilers now support variable length arrays which provide 1252roughly the same functionality. 1253 1254 1255File: mpatrol.info, Node: Operating system support, Next: Using mpatrol, Prev: Memory allocations, Up: Top 1256 1257Operating system support 1258************************ 1259 1260 Beneath every malloc library's public interface there is the 1261underlying operating system's memory management interface. This 1262provides features which can be as simple as giving processes the 1263ability to allocate a new block of memory for themselves, or it can 1264offer advanced features such as protecting areas of memory from being 1265read or written. Some embedded systems have no operating systems and 1266hence no support for dynamic memory allocation, and so the malloc 1267library must instead allocate blocks of memory from a fixed-sized array. 1268The mpatrol library can be built to support all of the above types of 1269system, but the more features an operating system can provide it with, 1270the more it can do. 1271 1272 On operating systems such as UNIX and Windows, all dynamic memory 1273allocation requests from a process are dealt with by using a feature 1274called _virtual memory_. This means that a process cannot perform 1275illegal requests without them being denied, which protects the other 1276running processes and the operating system from being affected by such 1277errors. However, on AmigaOS and Netware platforms there is no virtual 1278memory support and so all processes effectively share the same address 1279space as the operating system and any other running processes. This 1280means that one process can accidentally write into the data structures 1281of another process, usually causing the other process to fail and bring 1282down the system. In addition, a process which allocates a lot of memory 1283will result in there being less available memory for other running 1284processes, and in extreme cases the operating system itself. 1285 1286* Menu: 1287 1288* Virtual memory:: Addition facilities. 1289* Call stacks and symbol tables:: Tracing information. 1290* Threads:: Multiple threads of execution. 1291 1292 1293File: mpatrol.info, Node: Virtual memory, Next: Call stacks and symbol tables, Up: Operating system support 1294 1295Virtual memory 1296============== 1297 1298 _Virtual memory_ is an operating system feature that was originally 1299used to provide large usable address spaces for every process on 1300machines that had very little physical memory. It is used by an 1301operating system to fool(1) a running process into believing that it can 1302allocate a vast amount of memory for its own purposes, although whether 1303it is allowed to or not depends on the operating system and the 1304permissions of the individual user. 1305 1306 Virtual memory works by translating a virtual address (which the 1307process uses) into a physical address (which the operating system 1308uses). It is generally implemented via a piece of hardware called a 1309_memory management unit_, or MMU. The MMU's primary job is to 1310translate any virtual addresses that are referred to by machine 1311instructions into physical addresses by looking up a table which is 1312built by the operating system. This table contains mappings to and 1313from _pages_(2) rather than bytes since it would otherwise be very 1314inefficient to handle mappings between individual bytes. As a result, 1315every virtual memory operation operates on pages, which are indivisible 1316and are always aligned to the system page size. 1317 1318 Even though each process can now see a huge address space, what 1319happens when it attempts to allocate more pages than actually 1320physically exist, or allocate an additional page of memory when all of 1321the physical pages are in use by it and other processes? This problem 1322is solved by the operating system temporarily saving one or more of the 1323least-used pages (which might not necessarily belong that that process) 1324to a special place in the file system called a _swap file_, and mapping 1325the new pages to the physical addresses where the old pages once 1326resided. The old pages which have been _swapped out_ are no longer 1327currently accessible, but their location in the swap file is noted in 1328the translation table. 1329 1330 However, if one of the pages that has been swapped out is accessed 1331again, a _page fault_ occurs at the instruction which referred to the 1332address and the operating system catches this and reloads the page from 1333the swap file, possibly having to swap out another page to make space 1334for the new one. If this occurs too often then the operating system 1335can slow down, having to constantly swap in and swap out the same pages 1336over and over again. Such a problem is called _thrashing_ and can only 1337really be overcome by using less virtual memory or buying more physical 1338memory. 1339 1340 It is also possible to take advantage of the virtual memory system's 1341interaction between physical memory and the file system in program 1342code, since mapping an existing file to memory means that the usual 1343file I/O operations can be replaced with memory read and write 1344operations. The operating system will work out the optimum way to read 1345and write any buffers and it means that only one copy of the file 1346exists in both physical memory and the file system. Note that this is 1347how _shared libraries_(3) on UNIX platforms are generally implemented, 1348with each individual process that uses the shared library having it 1349mapped to somewhere in its address space. 1350 1351 Another major feature of virtual memory is its ability to read 1352protect and write protect individual pages of process memory. This 1353means that the operating system can control access to different parts 1354of the address space for each process, and also means that a process 1355can read and/or write protect an area of memory when it wants to ensure 1356that it won't ever read or write to it again. If an illegal memory 1357access is detected then a _signal_ will be sent to the process, which 1358can either be caught and handled or will otherwise terminate the 1359process. Note that as with all virtual memory operations, this ability 1360to protect memory only applies to pages, so that it is not possible to 1361protect individual bytes. 1362 1363 However, some versions of UNIX have programmable software _watch 1364points_ which are implemented at operating system level. These are 1365normally used by debuggers to watch a specified area of memory that is 1366expected to be read from or written to, but can just as easily be used 1367to implement memory protection at byte level. Unfortunately, as this 1368feature is implemented in software(4) rather than in hardware, watch 1369points tend to be incredibly slow, mainly as a result of the operating 1370system having to check every instruction before it is executed. In 1371addition, some UNIX platforms only allow a certain number of software 1372watch points to be in use at any one time, so even if your system 1373supports them you may not be able to use them with the mpatrol library 1374if there are many memory allocations in use at one time. 1375 1376 There is also an additional problem when using watch points, which 1377is due to misaligned reads from memory. These can occur with 1378compiler-generated code or with optimised library routines where memory 1379read, move or write operations have been optimised to work at word 1380level rather than byte level. For example, the `memcpy()' function 1381would normally be written to copy memory a byte at a time, but on some 1382systems this can be improved by copying a word at a time. 1383Unfortunately, care has to be taken when reading and writing such words 1384as the equivalent bytes may not be aligned on word boundaries. 1385Technically, reading additional bytes before or after a memory 1386allocation when they share the same word is legal, but when using watch 1387points such errors will be picked up. The mpatrol library replaces 1388most of the memory operation functions provided by the system libraries 1389with safer versions, although they may not be as efficient. 1390 1391 An operating system with virtual memory is usually going to run ever 1392so slightly slower than an operating system without it(5), but the 1393advantages of virtual memory far outweigh the disadvantages, especially 1394when used for debugging purposes. 1395 1396 ---------- Footnotes ---------- 1397 1398 (1) Well, perhaps that's too harsh a word, but it will certainly seem 1399that way to a process running on a 32-bit UNIX system with only 4 1400megabytes of physical memory, and yet it will be able to read from and 1401write to over 4 gigabytes of virtual memory! 1402 1403 (2) The size of a page varies between operating systems and 1404processor architectures, but they are generally around 4 or 8 kilobytes 1405in size, and are always a power of two. 1406 1407 (3) DLLs on Windows platforms. 1408 1409 (4) The operating system is still considered software. 1410 1411 (5) Due to the overhead of having to translate every address and 1412swap in and out pages -- although memory mapped files will usually be 1413more efficient than using normal file operations on a system without 1414virtual memory. 1415 1416 1417File: mpatrol.info, Node: Call stacks and symbol tables, Next: Threads, Prev: Virtual memory, Up: Operating system support 1418 1419Call stacks and symbol tables 1420============================= 1421 1422 As stated in the section on stack memory allocations (*note Stack 1423memory allocations::), when a function is called, a copy of the 1424caller's state information (including local variables and registers) is 1425saved on the stack so that it can be restored when the called function 1426returns. On many operating systems there is a _calling convention_(1) 1427which defines the layout of such stack entries so that code compiled in 1428different languages and with different compilers can be intermixed. 1429This usually specifies at which stack offsets the stack pointer, 1430program counter and local variables for the calling function can be 1431found, although on some processor architectures the function calling 1432conventions are specified by the hardware and so the operating system 1433must use these instead. 1434 1435 On systems that have consistent calling conventions, it is usually 1436possible to perform call stack _tracebacks_ from within the current 1437function in order to determine the stack of function calls that led to 1438the current function. This is extremely useful for debugging purposes 1439and is done by examining the current stack frame to see if there is a 1440pointer to the previous stack frame. If there is, then it can be 1441followed to find out all of the state information about the calling 1442function. This can be repeated until there are no more stack frames(2). 1443This is generally how this information is determined by debuggers when 1444a call stack traceback is requested. 1445 1446 In addition to the pointer to the previous stack frame, the saved 1447state information also always contains the saved program counter 1448register, which contains either the address of the instruction that 1449performed the function call, or the address of the instruction at which 1450to continue execution when the called function returns(3). This 1451information can be used to identify which function performed the call, 1452since the address of the instruction must lie between the start and end 1453of one of the functions in the process. 1454 1455 There are several different ways to perform stack unwinding. The 1456first requires compiler support and uses builtin functions to determine 1457the next stack frame and the return address. The GNU C compiler, 1458`gcc', supports this but unfortunately the number of stack frames to 1459traverse must be known at compile-time rather than run-time. The 1460second method requires operating system support, with a library of 1461routines provided to perform call stack traversal. Unfortunately, such 1462routines can be quite time consuming and may require a lot of 1463resources, but on the other hand they are likely to be very reliable at 1464obtaining the necessary information. The mpatrol library can be built 1465to support either of these methods, with the `MP_BUILTINSTACK_SUPPORT' 1466and the `MP_LIBRARYSTACK_SUPPORT' preprocessor macros. 1467 1468 A third way to perform stack unwinding involves reading (or 1469effectively disassembling) the instructions that are being executed in 1470order to determine the size of the stack frame being used and the 1471address of the instruction at which execution will resume when the 1472function returns. This can also be quite a reliable method of 1473obtaining call stack information but is only likely to be feasible on a 1474processor architecture which has a very simple instruction set, such as 1475a RISC(4) architecture. MIPS processors are a good example of this. 1476 1477 The final method of stack unwinding requires that the frame pointer 1478and return address are both stored on the stack whenever a new function 1479is called. The chain of frame pointers can then be followed down the 1480stack, and the return addresses can be read at a given offset from the 1481frame pointers. This is usually possible with CISC(5) processor 1482architectures that have dedicated call instructions which automatically 1483save such information on the stack, although some RISC processors also 1484save these as well. However, inline functions and compiler 1485optimisations can sometimes result in the frame pointer being omitted, 1486usually resulting in an inability to walk the stack. 1487 1488 However, in order to determine this symbolic information, it must be 1489possible to find out where the start and end addresses of all of the 1490functions in the process are. This can usually only be read from 1491object files, since they contain the symbol tables that were used by 1492the linker to generate the final executable file for the program. The 1493object file's symbol tables normally contain information about the 1494start address, size, name and visibility of every symbol that was 1495defined, but this depends on the format of the object file and if the 1496symbol tables have been stripped from the final executable file. 1497 1498 If the object file was created by a compiler then it may also 1499contain debugging information that was generated by the compiler for 1500use with a debugger. Such information may include a mapping of code 1501addresses to source lines(6), and this information can be used by the 1502mpatrol library to provide more meaningful information in call stack 1503tracebacks. 1504 1505 On systems that support shared libraries, additional work must be 1506done to determine the symbolic information for all of the functions 1507which have been defined in them. The symbols for functions that are 1508defined in shared libraries normally appear as undefined symbols in the 1509executable file for the program and so must be searched in the system 1510in order to get the necessary information. It is usually necessary to 1511liaise with the _dynamic linker_(7) on many systems. 1512 1513 ---------- Footnotes ---------- 1514 1515 (1) Usually part of the _Application Binary Interface_, or ABI. 1516 1517 (2) A process also known as _stack unwinding_. 1518 1519 (3) Also known as the _return address_. 1520 1521 (4) Reduced Instruction Set Computer. 1522 1523 (5) Complex Instruction Set Computer. 1524 1525 (6) Generally known as a line number table. 1526 1527 (7) Which is the part of the operating system that performs the 1528run-time linking of shared libraries. 1529 1530 1531File: mpatrol.info, Node: Threads, Prev: Call stacks and symbol tables, Up: Operating system support 1532 1533Threads 1534======= 1535 1536 On systems with virtual memory, such as UNIX and Windows, user 1537programs are run as _processes_ which have their own address space and 1538resources. If a process needs to create sub-processes to perform other 1539tasks it must call `fork()' or `spawn()' to create new processes, but 1540these new processes do not share the same address space or resources as 1541the parent process. If processes need to share memory they must either 1542use a message passing interface or explicitly mark a range of memory as 1543shareable. 1544 1545 Traditionally, this was not too much of a handicap as parallel 1546processing was an expensive luxury and could only be made use of by the 1547kernel of such systems. However, with the birth of fast processors and 1548parallel programming, programs could be made to run more efficiently 1549and faster on multi-processor systems by having more than one _thread_ 1550of control. This was achieved by allowing processes to have more than 1551one program counter through which the processor could execute 1552instructions, and if one thread of control stalled for a particular 1553reason then another could continue without stalling the entire process. 1554 1555 Such multithreaded programs allow parallel programming and implicit 1556shared memory between threads since all threads in a process share the 1557same address space and resources. This is similar to operating systems 1558that have no virtual memory, such as AmigaOS and Netware(1), except 1559that once a process terminates, all threads terminate as well and all 1560of its resources are still reclaimed. 1561 1562 Multithreaded programming generally needs no compiler support, but 1563does require some primitive operations to be supported by the operating 1564system for a threads library to call. The functions that are available 1565in the threads library provide the means for a process to create and 1566destroy threads. There are currently several popular threads libraries 1567available, although the POSIX threads standard remains the definitive 1568implementation. 1569 1570 It is always important to remember when programming a multithreaded 1571application that because all threads in a process share the same 1572address space, measures must be taken to prevent threads reading and 1573writing global data in a haphazard fashion. This can either be done by 1574locking with semaphores and mutexes, or can be performed by using stack 1575variables instead of global variables since every thread has its own 1576local stack. Care must be taken to write re-entrant functions -- i.e. 1577a function will give exactly the same result with one thread as it will 1578with multiple threads running it at the same time. 1579 1580 The mpatrol library can be built as a thread-safe library with 1581support for multi-threaded programs. When this library is linked with 1582your program, only one thread at a time can allocate, reallocate or 1583deallocate dynamic memory, or perform a memory operation via 1584`memcpy()', `memset()', etc. This does not take full advantage of the 1585potential concurrency in the library, but at least it will allow the 1586debugging of multi-threaded programs. 1587 1588 The process of making the mpatrol library thread-safe was made more 1589complicated by the fact that the mutexes protecting the library's data 1590structures had to be recursive, since some of the functions that the 1591library will call may call `malloc()' and `free()' or any other 1592functions redefined by the library. If this was to happen with 1593non-recursive mutexes then the recursive call would result in the 1594thread attempting to lock a mutex that it already owned. However, 1595implementing recursive mutexes was only half the problem. 1596 1597 The other problem with writing a thread-safe malloc library is that 1598it must be initialised before the program becomes multi-threaded. If 1599the library is initialised when there are multiple threads running then 1600one thread may be attempting to initialise the mutexes whilst another 1601thread may be attempting to lock an uninitialised mutex. Ideally, the 1602best place to initialise the library would be at the start of `main()' 1603but there is currently no way to do this other than getting users to 1604explicitly plant calls to initialise the library in their code. This 1605is not a very satisfactory solution if all we want to do is link in the 1606replacement malloc library without any need for recompilation. 1607 1608 Fortunately, there are some ways to plant initialisation calls before 1609`main()' is called, but they all have some drawbacks. The first way is 1610to use a static file-scope constructor in C++, which will then 1611initialise the mutexes and the library data structures before the code 1612in `main()' is executed. However, on many systems this will require 1613the final link to be performed by the C++ compiler that built the 1614library. That may not be desirable or even possible in many cases. 1615Unfortunately, this drawback appears in the second method, which 1616involves using the GNU C compiler to compile the library. This 1617compiler has an extension which allows functions to be specified as 1618constructors which will be called before `main()', but means that any 1619program which is linked with the resulting library must be linked with 1620the GNU C compiler driver. However, many systems are now GNU-based 1621which would mean that this would happen anyway. 1622 1623 The final way of initialising the mutexes and the library data 1624structures is to plant a call to the initialisation routines from a 1625special section which the system will call before `main()' is called. 1626This section is called the `.init' section on ELF-based platforms, but 1627may exist in another form on other platforms too. This has the 1628advantage that the system linker can be used to link the final program, 1629but a possible disadvantage is that the library may be initialised too 1630early, possibly before the environment or file streams have been set 1631up. You may find that if one of the above methods does not work for 1632you then perhaps another one will. 1633 1634 ---------- Footnotes ---------- 1635 1636 (1) Where the kernel is effectively a single process running all 1637user programs as threads. 1638 1639 1640File: mpatrol.info, Node: Using mpatrol, Next: Tools, Prev: Operating system support, Up: Top 1641 1642Using mpatrol 1643************* 1644 1645 This chapter contains a general description of all of the features 1646of mpatrol and how to use them effectively. You'll also find a 1647complete reference for mpatrol in the appendices, but you may wish to 1648try out the examples (*note Examples::) and the tutorial (*note 1649Tutorial::) before reading further. 1650 1651* Menu: 1652 1653* Library behaviour:: Miscellaneous information. 1654* Logging and tracing:: General information. 1655* General errors:: Everyday problems. 1656* Overwrites and underwrites:: Overflow buffers. 1657* Using with a debugger:: Setting breakpoints. 1658* Testing:: Additional checks. 1659* Library functions:: What's provided. 1660* Leak table:: Memory leak table. 1661 1662 1663File: mpatrol.info, Node: Library behaviour, Next: Logging and tracing, Up: Using mpatrol 1664 1665Library behaviour 1666================= 1667 1668 Most of the behaviour of the mpatrol library can be controlled at 1669run-time via options which are read from the `MPATROL_OPTIONS' 1670environment variable. This prevents you having to recompile or relink 1671each time you want to change a library setting, and so makes it really 1672easy to try out different settings to locate a particular bug. You 1673should know how to set the value of an environment variable on your 1674system before you read on. 1675 1676 By default, the mpatrol library will attempt to determine the 1677minimum required alignment for any generic memory allocation when it 1678first initialises itself. This may be affected by the compiler and its 1679settings when the library was built but it should normally reflect the 1680minimum alignment required by the processor on your system. If you 1681would prefer a larger (or perhaps even smaller) default alignment you 1682may change it at run-time using the `DEFALIGN' option. The value you 1683supply must be in bytes, must be a power of two, and should not be 1684larger that the system page size. If you encounter bus errors due to 1685misaligned memory accesses then you should increase this value. 1686 1687 On systems that have virtual memory the library will attempt to 1688write-protect all of its internal structures when user code is being 1689run. This ensures that it is nearly impossible for a program to 1690corrupt any mpatrol library data. However, unprotecting and then 1691protecting the structures at every library call has a slight overhead 1692so you may prefer to disable this behaviour by using the `NOPROTECT' 1693option. This has no effect on systems that have no virtual memory. 1694 1695 Usually it is desirable for many system library routines to be 1696protected from being interrupted by certain signals since they may 1697themselves be called from signal handlers. If this is not the case 1698then it may be possible to interrupt the program from within such 1699routines, perhaps causing problems if their global variables are left 1700in an undefined state. As the mpatrol library replaces some of these 1701system library routines it is also possible to specify that they are 1702protected from certain interrupt signals using the `SAFESIGNALS' option. 1703However, this can sometimes result in it being hard to interrupt the 1704program from the keyboard if a lot of processor time is spent in 1705mpatrol routines, which is why this behaviour is disabled by default(1). 1706 1707 On UNIX platforms, the `fork()' function can cause problems if it is 1708used to make a copy of the parent process without immediately calling 1709one of the `exec()' family of functions. This is because the child 1710process inherits all of the memory allocations of the parent process, 1711but also inherits the log, profile and trace files as well. If both 1712the parent and child processes make subsequent memory allocations there 1713will be multiple entries with the same allocation indices written to 1714the log, profile or trace files. This can be most confusing when 1715processing these files afterwards! As a workaround, the mpatrol 1716library will always check the current process identifier every time one 1717of its functions is called if the `CHECKFORK' option is used and will 1718open new log, profile or trace files if it has determined that the 1719process has been forked. If the `CHECKFORK' option is not used then a 1720call to `__mp_reinit()' should be added as the first function call in 1721the child process in order to duplicate the behaviour of the 1722`CHECKFORK' option. 1723 1724 On UNIX systems, the usual way for malloc libraries to allocate 1725memory from the process heap is through the `sbrk()' system call. This 1726allocates memory from a contiguous heap, but has the disadvantage in 1727that other library functions may also allocate memory using the same 1728function, thus creating holes in the heap. This is not a problem for 1729mpatrol, but you may have a suspicion that your bug is due to a 1730function from another library corrupting your data so you may wish to 1731use the `USEMMAP' option. This is only available on systems that have 1732the `mmap()' system call and allows mpatrol to allocate all of its 1733memory from a part of the process heap that is non-contiguous (i.e. 1734each call to `mmap()' may return a block of memory that is completely 1735unrelated to that returned by the previous call). It may also be 1736required on some systems in order for the mpatrol library to implement 1737memory protection. 1738 1739 Beginning with release 1.3.3, the mpatrol library now allocates its 1740internal memory in the opposite way to user memory on UNIX systems that 1741support the `mmap()' system call. This means that by default, user 1742memory is allocated with `sbrk()' whereas internal memory is allocated 1743with `mmap()', and this behaviour is reversed when the `USEMMAP' option 1744is used. This was done to segregate user memory from internal memory, 1745and was especially required for the `mptrace' command's graphical 1746display. 1747 1748 The `CHECK' option allows you to specify that every time an mpatrol 1749library function is called the library will automatically check the 1750freed memory and overflow buffers of every memory allocation, although 1751this can slow program execution down, especially if you suspect the 1752error you are looking for occurs at the 1000th memory allocation, for 1753example. You can therefore use the `CHECK' option to specify a range 1754of memory allocations at which the mpatrol library will automatically 1755check the freed memory and overflow buffers. All other allocations 1756that fall outside this range will not be checked. You can also specify 1757an optional frequency at which this checking should be performed. No 1758such checking is performed by default in mpatrol release 1.4.0 and 1759onwards -- you must specify `CHECK=-' to get the original behaviour. 1760 1761 On UNIX systems, the mpatrol library can also invoke the `mpedit' 1762command to edit source files that show up in any warnings or error 1763messages that it generates. This can only happen if the diagnostic 1764message can be traced back to a specific source line in the program; in 1765many cases this is not possible. If editing the files is not required, 1766a context listing of the appropriate source line can be generated 1767instead. The `EDIT' option specifies that files are to be edited and 1768the `LIST' option specifies that a context listing is to be generated. 1769These options are mutually exclusive. 1770 1771 If the mpatrol library that was built for your system supports 1772reading symbolic information from a program's executable file, but it 1773cannot locate the executable file, or you wish to specify an 1774alternative, you can use the `PROGFILE' option to do this. All this 1775does is instruct the mpatrol library to read symbols from this file 1776instead. Note that on systems that support dynamic linking, the 1777library can also read symbols from a dynamically linked executable file 1778that has had its normal symbol table stripped. 1779 1780 Finally, a list of all of the recognised options in the mpatrol 1781library can be displayed to the standard error file stream by using the 1782`HELP' option. This will not affect the settings of the library in any 1783way, so you should be able to use other options at the same time. 1784 1785 ---------- Footnotes ---------- 1786 1787 (1) In mpatrol release 1.0 it was enabled by default. 1788 1789 1790File: mpatrol.info, Node: Logging and tracing, Next: General errors, Prev: Library behaviour, Up: Using mpatrol 1791 1792Logging and tracing 1793=================== 1794 1795 If you would like to see a complete log of all of the memory 1796allocations, reallocations and deallocations performed by your program, 1797use the `LOGALL' option. This provides detailed tracing for each of 1798the mpatrol library functions, and a full description of the format of 1799such tracing is given in Example 1 (*note Example 1::). Alternatively, 1800you may select one or more types of functions to be traced using the 1801`LOGALLOCS', `LOGREALLOCS', `LOGFREES' and `LOGMEMORY' options if you 1802feel that the log file is too large when `LOGALL' is used. By default 1803all diagnostics from the mpatrol library get sent to `mpatrol.log' in 1804the current directory, but this can be changed using the `LOGFILE' 1805option. In fact, you can also specify a directory where all log files 1806from the mpatrol library will get placed by setting the `LOGDIR' 1807environment variable. 1808 1809 On systems that support it, every log entry also contains a call 1810stack traceback that may also include the names of the symbols that 1811appear on the call stack. If the object file access library that 1812mpatrol was built with has support for reading line number tables from 1813object files then the `USEDEBUG' option will also try to determine the 1814file name and line number for each entry in the call stack, but only if 1815the object files contain the relevant debugging information. This 1816information will only be available before program termination and so 1817any call stack tracebacks that appear after the library summary will 1818not be displayed with their corresponding file name and line number. 1819This option will also slow down program execution since a search 1820through the line number tables will have to be made every time a call 1821stack is displayed. Alternatively, the `mpsym' command may be used to 1822process an mpatrol log file with a debugger in order to obtain symbol 1823names and source level information for any call stacks. 1824 1825 Because the `alloca()', `strdupa()' and `strndupa()' functions 1826automatically free their allocations when the calling function returns, 1827the log entries for these types of memory allocation are slightly 1828different. The actual memory allocation will have an entry similar to 1829`malloc()', etc., but the memory deallocation will be marked as being 1830done by `alloca()' and will occur at the next call to an mpatrol 1831library function after the calling function has returned. However, any 1832such allocations that are explicitly deallocated with the `dealloca()' 1833function will be marked as being done by `dealloca()'. 1834 1835 The mpatrol library will always try to display as much useful 1836information as possible in this log file, and will always display a 1837summary of library settings and statistics when your program terminates 1838successfully. If you don't get this then your program did not call 1839`exit()' and either called `abort()' or was terminated by the operating 1840system instead. In such cases, either use a debugger to see where your 1841program crashed or use the `LOGALL' option to see the last successful 1842library call in the log file so that you have a rough idea of where 1843your program crashed. 1844 1845 It is also possible to get mpatrol to write more summary information 1846to the log file after it writes out its settings and statistics at 1847program termination. Use the `SHOWFREED' and `SHOWUNFREED' options to 1848display a list of freed and unfreed memory allocations. The former 1849will only be displayed if the `NOFREE' option is used, but the latter 1850can be useful for detecting memory leaks. The `SHOWFREE' option can be 1851used to display a summary of any free memory blocks. 1852 1853 The `SHOWMAP' option will display a memory map of the heap that was 1854valid when the process terminated, and the `SHOWSYMBOLS' option will 1855display any symbolic information that the mpatrol library managed to 1856obtain from any executable files and libraries that were relevant to 1857the program being tested. All of the above five options can be 1858selected with the `SHOWALL' option. 1859 1860 For the purpose of detecting memory leaks, you can instruct the 1861mpatrol library to automatically log every memory allocation event into 1862a special hash table called the leak table with the `LEAKTABLE' option. 1863This option will then cause the mpatrol library to display a sorted 1864summary of all of the memory leaks or unfreed memory allocations to the 1865mpatrol log file when the program terminates. The leak table is 1866indexed by the source file and line number where memory allocation 1867events occur, but if this information is not available then either the 1868function name or the return address will be used instead. Note that 1869this option differs from the `SHOWUNFREED' option in that it will 1870summarise where the leaks came from rather than show the full details 1871of each individual unfreed memory allocation. 1872 1873 Because the log file can contain verbose information about memory 1874allocations, reallocations, deallocations and operations, it can end up 1875being too large if all such information is being logged for a large 1876program. To get around this, it is possible to _trace_ all memory 1877allocation, reallocation and deallocation events in a concise way, to 1878be stored in a separate file for later processing by the `mptrace' 1879command. By default, no such tracing is performed but it can be 1880enabled with the `TRACE' option. The default tracing output file is 1881`mpatrol.trace', but this can be changed using the `TRACEFILE' option. 1882As with the `LOGFILE' option, you can also specify a directory where 1883all tracing output files from the mpatrol library will get placed by 1884setting the `TRACEDIR' environment variable. 1885 1886 1887File: mpatrol.info, Node: General errors, Next: Overwrites and underwrites, Prev: Logging and tracing, Up: Using mpatrol 1888 1889General errors 1890============== 1891 1892 By default, the mpatrol library follows the guidelines for ANSI C 1893and C++ regarding the behaviour of the dynamic memory allocation and 1894memory operation functions it replaces. This means that calling 1895`malloc()' with a size of zero is allowed, for example. However, 1896warnings can be generated for all of these types of calls by using the 1897`CHECKALL' option. The `CHECKALLOCS' option warns only about calls to 1898`malloc()' and similar functions with a size of zero, the 1899`CHECKREALLOCS' option warns only about calls to `realloc()' and 1900similar functions with either a null pointer or a size of zero, and the 1901`CHECKFREES' option warns only about calls to `free()' and similar 1902functions with a null pointer. The `CHECKMEMORY' option gives an error 1903if a zero-size memory operation is performed on a `NULL' pointer -- 1904this is normally allowed by default. 1905 1906 All newly-allocated memory can be pre-filled with a specified byte 1907by using the `ALLOCBYTE' option. This can be used to catch out code 1908that expects newly-allocated memory to be zeroed, although this option 1909will have no effect on memory that was allocated with `calloc()'. All 1910free memory can also be pre-filled with a different specified byte by 1911using the `FREEBYTE' option. This will catch out code that expects to 1912be able to use the contents of freed memory. Note that you may wish to 1913change these options from their default values on your system so that 1914the contents can be filled with values that are least likely to be used 1915at run-time. For example, ensuring that the pointer representation of 1916the value can never be a valid pointer, or that the floating point 1917representation will always be invalid. These values will vary across 1918operating systems and processor architectures. 1919 1920 Alternatively, the mpatrol library can be instructed to keep all (or 1921a certain number of recent) freed memory allocations so that its 1922diagnostics can be clearer about which freed allocation a piece of code 1923is erroneously trying to access. This is controlled with the `NOFREE' 1924option, which accepts an argument specifying the maximum number of 1925recently-freed memory allocations to prevent being reused. If the 1926argument is zero then all freed memory allocations will be immediately 1927reused by the mpatrol library. If the argument is non-zero then the 1928mpatrol library will use up more memory than usual since it has to keep 1929all of the freed memory allocations lying around until their lifetime 1930has expired. Note that this option distinguishes between _free_ memory 1931and _freed_ memory. _Free_ memory is unallocated memory that has been 1932taken from the system heap. _Freed_ memory is a freed memory 1933allocation, with all of the original details of the allocation 1934preserved. 1935 1936 Normally, the `NOFREE' option will fill the freed allocation with the 1937free byte so that any code that accesses it will hopefully fall over. 1938However, the original contents can be preserved using the `PRESERVE' 1939option in case you need to see what the contents were just before it 1940was freed. The `NOFREE' option is also affected by the `PAGEALLOC' 1941option, since then the freed allocation will have its contents both 1942read and write protected so that nothing can access them. If the 1943`PRESERVE' option is used in this case then the freed allocation will 1944only be made write-protected so that the original contents can be read 1945from but not written to. 1946 1947 Note that if the argument specified with the `NOFREE' option is 1948non-zero then the mpatrol library will store all recently-freed memory 1949allocations in a queue. Once the queue has filled to the point 1950specified with the `NOFREE' option then all subsequent calls to free 1951memory will result in the most recently-freed memory allocation being 1952placed at the end of the queue and the freed memory allocation at the 1953beginning of the queue will be returned to the free memory pool for 1954later reuse. Obviously, the larger the freed queue size, the better 1955chance of detecting attempts to access previously-freed memory, but 1956unfortunately more memory will be used up and the mpatrol library will 1957have to keep track of a larger number of memory allocations. 1958 1959 1960File: mpatrol.info, Node: Overwrites and underwrites, Next: Using with a debugger, Prev: General errors, Up: Using mpatrol 1961 1962Overwrites and underwrites 1963========================== 1964 1965 Once a block of memory has been allocated, it is imperative that the 1966program does not attempt to write any data past the end of the block or 1967write any data just before the beginning of the block. Even writing a 1968single byte just beyond the end of an allocation or just before the 1969beginning of an allocation can cause havoc. This is because most 1970malloc libraries store the details of the allocated block in the first 1971few words before the beginning of the block, such as its size and a 1972pointer to the next block. The mpatrol library does not do this, so a 1973program which failed using the normal malloc library and worked when 1974the mpatrol library was linked in is a possible candidate for turning 1975on overflow buffers. 1976 1977 Such memory corruption can be extremely difficult to pinpoint as it 1978is unlikely to show itself until the next call is made to the malloc 1979library, or if the internal malloc library blocks were not overwritten, 1980the next time the data is read from the block that was overwritten. If 1981the former is the case then the next library call will cause an 1982internal error or a crash, but only when the memory block that was 1983affected is referenced. This is likely to disappear when using the 1984mpatrol library since it keeps its internal structures separate, and 1985write-protects them on systems that support memory protection. 1986 1987 In order to identify such errors, it is possible to place special 1988buffers(1) on either side of every memory allocation, and these will be 1989pre-filled with a specified byte. Before every mpatrol library call, 1990the library will check the integrity of every such overflow buffer in 1991order to check for a memory underwrite or overwrite. Depending on the 1992number of allocations and size of these buffers, this can take a 1993noticable amount of time (which is why overflow buffers are disabled by 1994default), but can mean that these errors get noticed sooner. The 1995option which governs this is `OFLOWSIZE'. The byte with which they get 1996pre-filled can be changed with `OFLOWBYTE'. Depending on what gets 1997written, it might only be possible to see such errors when a different 1998size of buffer or a different pre-fill byte is used. 1999 2000 Note that you may wish to change the `OFLOWBYTE' from its default 2001value on your system so that the contents can be filled with values 2002that are least likely to be used at run-time. For example, ensuring 2003that the pointer representation of the value can never be a valid 2004pointer, or that the floating point representation will always be 2005invalid. These values will vary across operating systems and processor 2006architectures, but may also vary depending on the datatypes that you 2007will be expecting to store in the memory allocations. 2008 2009 A worse situation can occur when it is only reads from memory that 2010overflow or underflow; i.e. with the faulty code reading just before or 2011just past a memory allocation. These cannot be detected by overflow 2012buffers as it is not possible using conventional means to interrupt 2013every single read from memory. However, on systems with virtual 2014memory, it is possible to use the memory protection feature to provide 2015an alternative to overflow buffers, although at the added expense of 2016increased memory usage. 2017 2018 The `PAGEALLOC' option turns on this feature and automatically rounds 2019up the size of every memory allocation to a multiple of the system page 2020size. It also rounds up the size of every overflow buffer to a 2021multiple of the system page size so that every memory allocation 2022occupies its own set of pages of virtual memory and no two memory 2023allocations occupy the same page of virtual memory. The overflow 2024buffers are then read and write protected so that any memory accesses 2025to them will generate an error(2). Following on from the previous 2026section, the `PAGEALLOC' option also causes free memory to be read and 2027write protected as well since that will also occupy non-overlapping 2028virtual memory pages. 2029 2030 The remaining memory that is left over within an allocation's pages 2031is effectively turned into traditional overflow buffers, being 2032pre-filled with the overflow byte and checked periodically by the 2033mpatrol library to ensure that nothing has written into them. However, 2034because of this remaining memory, the library has a choice of where to 2035place the memory allocation within its pages. If it places the 2036allocation at the very beginning then it will catch memory underwrites, 2037but if it places the allocation at the very end then it will catch 2038memory overwrites. Such a choice can be controlled at run-time by 2039supplying an argument to the `PAGEALLOC' option. If `PAGEALLOC=LOWER' 2040is used then every allocation will be placed at the very beginning of 2041its pages and if `PAGEALLOC=UPPER' is used then the placement will be 2042at the very end of its pages. This is probably better explained in 2043Example 3 (*note Example 3::) where the problems with `PAGEALLOC=UPPER' 2044and alignment are also discussed. 2045 2046 Obviously, there are still some deficiencies when using `PAGEALLOC' 2047since it can use up a huge amount of memory (especially with `NOFREE') 2048and the overflow buffers within an allocation's pages can still be read 2049without causing an immediate error. Both of these deficiencies can be 2050overcome by using the `OFLOWWATCH' option to install _software watch 2051points_ instead of overflow buffers, but there are still very few 2052systems that support software watch points at the moment, and it can 2053slow a program's execution speed down by a factor of around 10,000. 2054The reason for this is that software watch points instruct the 2055operating system to check every read from and write to memory, which 2056means that it has to single-step through a process checking every 2057instruction before it is executed. However, this is a very thorough 2058way of checking for overflows and is unlikely to miss anything, 2059although there may be problems with misaligned memory accesses when 2060using watch points (*note Virtual memory::). 2061 2062 Note that from release 1.1.0 of mpatrol, the library comes with 2063replacement functions for many memory operation functions, such as 2064`memset()' and `memcpy()'. These new functions provide additional 2065checks to ensure that if a memory operation is being performed on a 2066memory block, the operation will not read or write before or beyond the 2067boundaries of that block. 2068 2069 Normally, if an error is discovered in the call to such functions, 2070the mpatrol library will report the error but prevent the operation 2071from being performed before continuing execution. If the error was 2072that the range of memory being operated on overflowed the boundaries of 2073an existing memory allocation then the `ALLOWOFLOW' option can be used 2074to turn the error into a warning and force the operation to continue. 2075This behaviour can be desirable in certain cases where third-party 2076libraries are being used that make such calls but the end result does 2077not overflow the allocation boundary. 2078 2079 From release 1.3.3 of mpatrol, the library comes with functions that 2080interface to the `-fcheck-memory-usage' option of the GNU compiler. 2081This option instructs the compiler to place error-checking calls before 2082each read or write to memory. The functions that are called then check 2083to ensure that the memory access does not overflow a heap memory 2084allocation or access free memory. This can be a very useful way to go 2085through your code looking for errors with a fine tooth-comb, but be 2086aware that it does slow down execution by a large factor. It also only 2087affects functions that were compiled with this option, so if the 2088problem lies in a function that was not recompiled with 2089`-fcheck-memory-usage' then it won't do much good. 2090 2091 To conclude, if you suspect your program has a piece of code which 2092is performing illegal memory underwrites or overwrites to a memory 2093allocation you turn on the `CHECK=-' option and you should use each of 2094the following options in sequence, but only if your system supports 2095them. If all else fails and you are using the GNU compiler then you 2096could try recompiling some or all of your code with the 2097`-fcheck-memory-usage' option. 2098 2099 1. `OFLOWSIZE=8' 2100 2101 2. `OFLOWSIZE=32' 2102 2103 3. `OFLOWSIZE=1' `PAGEALLOC=LOWER' 2104 2105 4. `OFLOWSIZE=1' `PAGEALLOC=UPPER' 2106 2107 5. `OFLOWSIZE=8' `OFLOWWATCH' 2108 2109 6. `OFLOWSIZE=32' `OFLOWWATCH' 2110 2111 ---------- Footnotes ---------- 2112 2113 (1) Commonly known as _overflow buffers_ or _fence posts_. 2114 2115 (2) This is a feature that was first used by Electric Fence (*note 2116Related software::) to track down memory corruption. 2117 2118 2119File: mpatrol.info, Node: Using with a debugger, Next: Testing, Prev: Overwrites and underwrites, Up: Using mpatrol 2120 2121Using with a debugger 2122===================== 2123 2124 If you would like to use mpatrol to pause at a specific memory 2125allocation, reallocation or deallocation in a debugger then this 2126section will describe how to go about it. Unfortunately, debuggers 2127vary widely in function and usage and are normally very 2128system-dependent. The example below will use `gdb' as the debugger, 2129but as long as you know how to set a breakpoint within a debugger, any 2130one will do. 2131 2132 First of all, decide where you would like the mpatrol library to 2133pause when running your program within the debugger. You can choose 2134one allocation index to break at using the `ALLOCSTOP' option, or you 2135can choose to break at a specific reallocation of that allocation by 2136also using the `REALLOCSTOP' option. If you use `REALLOCSTOP' without 2137using `ALLOCSTOP' then you will break at the first memory allocation 2138that has been reallocated the specified number of times. You can also 2139choose to break at the point in your program that frees a specific 2140allocation index by using the `FREESTOP' option. 2141 2142 The normal process for determining where you would like to pause 2143your program in the debugger is by using the `LOGALL' option and 2144examining the log file produced by mpatrol. If your program crashed 2145then you should look at the last entry in the log file to see what the 2146allocation index (and possibly also the reallocation index) of the last 2147successful call was. You can then decide which of the above options to 2148use. Note that the debugger will break at a point before any work is 2149done by the mpatrol library for that allocation index so that you can 2150see if it was the last successful operation that caused the damage. 2151 2152 Having decided which combination of mpatrol options to use, you 2153should set them in the `MPATROL_OPTIONS' environment variable before 2154running the debugger on your program. Alternatively, your debugger may 2155have a command that allows you to modify your environment during 2156debugging, but you're just as well setting the environment variable 2157before you run the debugger as it shouldn't make any difference(1). 2158 2159 After you get to the debugger command prompt, you should set a 2160breakpoint at the `__mp_trap()' function. This is the function that 2161gets called when the specified allocation index and/or reallocation 2162index appears and so when you run your program under the debugger the 2163mpatrol library will call `__mp_trap()' and the debugger will stop at 2164that point. If you are not running your program within a debugger, or 2165if you haven't set the breakpoint, then `__mp_trap()' will still be 2166called, but it won't do anything. Note that there may be some naming 2167issues on some platforms where the visible name of a global function 2168gets an underscore prepended to it. You may have to take that into 2169account when setting the breakpoint on such systems. 2170 2171 Now that you have set the `MPATROL_OPTIONS' environment variable and 2172have set the debugger to break at `__mp_trap()', all that is required 2173is for you to run your program. Hopefully, the debugger should stop at 2174`__mp_trap()'. If it doesn't then you may have to check your 2175environment variable settings to ensure that they are the same as when 2176you ran the program outwith the debugger, although obviously with the 2177addition of `ALLOCSTOP', etc. Once the program has been halted by the 2178debugger, you can then single-step through your code until you see 2179where it goes wrong. If this is near the end of your program then 2180you'll have saved yourself a lot of time by using this method. 2181 2182 The following example will be used to illustrate the steps involved 2183in using the `ALLOCSTOP', `REALLOCSTOP' and `FREESTOP' options. 2184However, it is only for tutorial purposes and the same effect could 2185easily be achieved by breaking at line 18 in a debugger because in this 2186case it is obvious from the code and the mpatrol log file where it is 2187going wrong. In real programs this is hardly ever the case(2). 2188 2189 1 /* 2190 2 * Allocates 1000 blocks of 16 bytes, freeing each block immediately 2191 3 * after it is allocated, and freeing the last block twice. 2192 4 */ 2193 2194 2195 7 #include "mpatrol.h" 2196 2197 2198 10 int main(void) 2199 11 { 2200 12 void *p; 2201 13 int i; 2202 2203 15 for (i = 0; i < 1000; i++) 2204 16 if (p = malloc(16)) 2205 17 free(p); 2206 18 free(p); 2207 19 return EXIT_SUCCESS; 2208 20 } 2209 2210 Compile this example code with debugging information enabled and 2211link it with the mpatrol library, then set `MPATROL_OPTIONS' to 2212`LOGALL' and run the resulting program. If you examine `mpatrol.log' 2213you will see the following near the bottom of the file. 2214 2215 ... 2216 2217 ALLOC: malloc (1000, 16 bytes, 4 bytes) [main|test.c|16] 2218 0x08049449 main+57 2219 0x4007C9CB __libc_start_main+255 2220 0x08049381 _start+33 2221 2222 returns 0x080620E8 2223 2224 FREE: free (0x080620E8) [main|test.c|17] 2225 0x08049470 main+96 2226 0x4007C9CB __libc_start_main+255 2227 0x08049381 _start+33 2228 2229 0x080620E8 (16 bytes) {malloc:1000:0} [main|test.c|16] 2230 0x08049449 main+57 2231 0x4007C9CB __libc_start_main+255 2232 0x08049381 _start+33 2233 2234 FREE: free (0x080620E8) [main|test.c|18] 2235 0x08049491 main+129 2236 0x4007C9CB __libc_start_main+255 2237 0x08049381 _start+33 2238 2239 ERROR: [NOTALL]: free: 0x080620E8 has not been allocated 2240 2241 ... 2242 2243 In this example, we'll want to use `ALLOCSTOP' to halt the program at 2244the 1000th memory allocation so that we can step through it with a 2245debugger. So, set `MPATROL_OPTIONS' to `ALLOCSTOP=1000' and load the 2246program into the debugger. If you are using `gdb' you can now do the 2247following steps, but if you are not you will have to use the equivalent 2248commands in your debugger. Note that `(gdb)' is the debugger command 2249prompt and so anything that appears on that line after that should be 2250typed as a command. 2251 2252 (gdb) break __mp_trap 2253 Breakpoint 1 at 0x804ee83 2254 (gdb) run 2255 Starting program: a.out 2256 Breakpoint 1, 0x804ee83 in __mp_trap() 2257 (gdb) backtrace 2258 #0 0x804ee83 in __mp_trap() 2259 #1 0x804c61b in __mp_getmemory() 2260 #2 0x8049894 in __mp_alloc() 2261 #3 0x8049449 in main() at test.c:16 2262 (gdb) finish 2263 Run till exit from #0 0x804ee83 in __mp_trap() 2264 0x804c61b in __mp_getmemory() 2265 (gdb) finish 2266 Run till exit from #0 0x804c61b in __mp_getmemory() 2267 0x8049894 in __mp_alloc() 2268 (gdb) finish 2269 Run till exit from #0 0x8049894 in __mp_alloc() 2270 0x8049449 in main() at test.c:16 2271 16 if (p = malloc(16)) 2272 (gdb) step 2273 17 free(p); 2274 (gdb) step 2275 15 for (i = 0; i < 1000; i++) 2276 (gdb) step 2277 18 free(p); 2278 (gdb) quit 2279 The program is running. Exit anyway? (y or n) y 2280 2281 After setting the breakpoint and running the program, the debugger 2282halts at `__mp_trap()'. Because `__mp_trap()' is a function within the 2283mpatrol library, you don't want to bother stepping through any of the 2284library functions, and in this case you can't since the mpatrol library 2285was not compiled with debugging information enabled. So, after 2286returning from all of the library functions, the source line becomes 2287line 16 because that was the location of the 1000th memory allocation. 2288Single-stepping twice gets us to line 18 which is our destination. 2289Note that the file `extra/.gdbinit' included in the mpatrol 2290distribution contains predefined commands which make setting the 2291allocation index to stop at much easier. 2292 2293 Sometimes it is useful to be able to see information about a memory 2294allocation whilst running a program from within a debugger. The 2295`__mp_printinfo()' function is provided for that purpose and takes a 2296heap address as its only argument. Using the above example, it would 2297have been possible to print out information about the pointer `p' at 2298line 17 from within `gdb': 2299 2300 (gdb) call __mp_printinfo(p) 2301 address 0x080620E8 located in allocated block: 2302 start of block: 0x080620E8 2303 size of block: 16 bytes 2304 stored type: <unknown> 2305 stored type size: <unknown> 2306 user data: 0x00000000 2307 allocated by: malloc 2308 allocation index: 1000 2309 reallocation index: 0 2310 modification event: 1999 2311 flags: none 2312 calling function: main 2313 called from file: test.c 2314 called at line: 16 2315 function call stack: 2316 0x08049449 main 2317 0x4007C9CB __libc_start_main 2318 0x08049381 _start 2319 2320 Some debuggers, such as `gdb', also allow you to define your own 2321commands for use in a debugging session. The following example defines 2322a new `gdb' command called `printalloc' which calls 2323`__mp_printinfo()'(3): 2324 2325 (gdb) define printalloc 2326 Type commands for definition of "printalloc". 2327 End with a line saying just "end". 2328 >call __mp_printinfo($arg0) 2329 >end 2330 (gdb) document printalloc 2331 Type documentation for "printalloc". 2332 End with a line saying just "end". 2333 >Displays information about an address in the heap. 2334 >end 2335 2336 ---------- Footnotes ---------- 2337 2338 (1) Unless you've linked the debugger with the mpatrol library. 2339 2340 (2) The other reason that this program is simple is because a proper 2341example would generally involve crashing the program, but on AmigaOS 2342and Netware that would also involve crashing the system -- not 2343something you'd want to do whilst trying this out. 2344 2345 (3) A sample GDB command file for use with mpatrol can be found in 2346`extra/.gdbinit'. 2347 2348 2349File: mpatrol.info, Node: Testing, Next: Library functions, Prev: Using with a debugger, Up: Using mpatrol 2350 2351Testing 2352======= 2353 2354 The mpatrol library has several features that make it useful when 2355testing a program's dynamic memory allocations. These are features 2356that do not help in fixing an existing bug, but rather help to identify 2357additional bugs that may be lurking in your code. 2358 2359 It is possible to set a simulated upper limit on the amount of heap 2360memory available to a process with the `LIMIT' option, which accepts a 2361size in bytes, but will be disabled when it is zero. This can be 2362extremely useful for testing a program under simulated low memory 2363conditions to see how it handles such errors. Of course, you should 2364set the heap limit to a value less than the amount of actual available 2365memory otherwise this option will have no effect. Note that the 2366mpatrol library may use up a small amount of heap memory when it 2367initialises itself(1) so the value passed to the `LIMIT' option may 2368need to be set slightly higher than you would normally expect. 2369 2370 It is also possible to instruct the mpatrol library to randomly fail 2371a certain number of memory allocations so that you can further test 2372error handling code in a program. The frequency at which failures 2373occur can be controlled with the `FAILFREQ' option, where a value of 2374zero means that no failures will occur, but any other value will 2375randomly cause failures. For example, a value of `10' will cause 2376roughly one in ten failures and a value of `1' will cause every memory 2377allocation to fail. The random sequence can be made predictable by 2378using the `FAILSEED' option. If this is non-zero then the same program 2379run with the same failure frequency and same failure seed will fail on 2380exactly the same memory allocations. If this is zero then the failure 2381seed will itself be set randomly, but you can see its value when the 2382summary is displayed at program termination. 2383 2384 When running _batch tests_(2) it is sometimes useful to be able to 2385detect if there have been any memory leaks. Such leaks should normally 2386be distinguished from code which has purposely not freed the memory 2387that it allocated, so there may be a certain expected number of unfreed 2388allocations at program termination. It may be that you would like to 2389highlight any additional unfreed allocations since they may be due to 2390real memory leaks, so the `UNFREEDABORT' option can be set to a 2391threshold number of expected unfreed allocations. If the library 2392detects a number of unfreed allocations higher than this then it will 2393abort the program at termination so that it fails. All tests that fail 2394in this way can then be examined after the test suite finishes. 2395 2396 ---------- Footnotes ---------- 2397 2398 (1) Actually, it's not really the mpatrol library that uses the 2399memory but the object file access libraries since they call `malloc()' 2400to allocate any memory that they require. 2401 2402 (2) A set of tests that run without user intervention. 2403 2404 2405File: mpatrol.info, Node: Library functions, Next: Leak table, Prev: Testing, Up: Using mpatrol 2406 2407Library functions 2408================= 2409 2410 Along with the standard set of C and C++ dynamic memory allocation 2411functions, the mpatrol library also comes with an additional set of 2412functions which can be used to provide additional information to your 2413program, and which can be called at various points in your code for 2414debugging purposes. You must always include the `mpatrol.h' header 2415file in order to use these functions, but you can check for a specific 2416version of the mpatrol library by checking the `MPATROL_VERSION' 2417preprocessor macro. You can check the version of the mpatrol library 2418that a program was linked with by calling the `__mp_libversion()' 2419function. 2420 2421 Certain mpatrol library options can be set after the library has been 2422initialised with the `__mp_setoption()' function. This allows you to 2423override the default options or those specified in the `MPATROL_OPTIONS' 2424environment variable from within your code. Not all options can be 2425overridden, however, since they would require a complete 2426reinitialisation of the library -- the `__mp_setoption()' function 2427returns a failure indicator in these cases. You can read the setting 2428of any mpatrol library option with the corresponding function, 2429`__mp_getoption()'. 2430 2431 On systems that support it, global functions (with C linkage) in an 2432executable file or shared library whose names begin with `__mp_init_' 2433will be noted when the mpatrol library first starts up and is reading 2434the symbols. Such functions will then be called as soon as the mpatrol 2435library is initialised, which can be useful if the initialisation 2436occurs before `main()' is called. These functions must accept no 2437arguments and must return no value. Similar behaviour exists for 2438global functions whose names begin with `__mp_fini_', except that such 2439functions will be executed when the mpatrol library terminates. Note 2440that this feature will have no effect if the symbol table is stripped 2441from the executable file or shared library before the program is run, 2442and the order in which such functions will be called if there are more 2443than one is unspecified. The `__mp_atexit()' function can also be used 2444to register functions that should be called when the mpatrol library 2445terminates. 2446 2447 It is possible to obtain a great deal of information about an 2448existing memory allocation or free block using the `__mp_info()' 2449function. This takes an address as an argument and fills in any 2450details about its corresponding memory allocation in a supplied 2451structure. The following example illustrates this (it can be found in 2452`tests/pass/test4.c'). 2453 2454 23 /* 2455 24 * Demonstrates and tests the facility for obtaining information 2456 25 * about the allocation a specific address belongs to. 2457 26 */ 2458 2459 2460 29 #include "mpatrol.h" 2461 30 #include <stdio.h> 2462 2463 2464 33 void display(void *p) 2465 34 { 2466 35 __mp_allocstack *s; 2467 36 __mp_allocinfo d; 2468 37 __mp_symbolinfo i; 2469 2470 39 if (!__mp_info(p, &d) || !d.allocated) 2471 40 { 2472 41 fprintf(stderr, "nothing known about address 0x%0*lX\n", 2473 42 sizeof(void *) * 2, p); 2474 43 return; 2475 44 } 2476 45 fprintf(stderr, "block: 0x%0*lX\n", sizeof(void *) * 2, d.block); 2477 46 fprintf(stderr, "size: %lu\n", d.size); 2478 47 fprintf(stderr, "type: %s\n", __mp_function(d.type)); 2479 48 fprintf(stderr, "alloc: %lu\n", d.alloc); 2480 49 fprintf(stderr, "realloc: %lu\n", d.realloc); 2481 50 fprintf(stderr, "thread: %lu\n", d.thread); 2482 51 fprintf(stderr, "event: %lu\n", d.event); 2483 52 fprintf(stderr, "func: %s\n", d.func ? d.func : "<unknown>"); 2484 53 fprintf(stderr, "file: %s\n", d.file ? d.file : "<unknown>"); 2485 54 fprintf(stderr, "line: %lu\n", d.line); 2486 55 for (s = d.stack; s != NULL; s = s->next) 2487 56 { 2488 57 fprintf(stderr, "\t0x%0*lX", sizeof(void *) * 2, s->addr); 2489 58 if (__mp_syminfo(s->addr, &i)) 2490 59 { 2491 60 if (i.name != NULL) 2492 61 fprintf(stderr, " %s", i.name); 2493 62 if ((i.addr != NULL) && (i.addr != s->addr)) 2494 63 fprintf(stderr, "%+ld", 2495 64 (char *) s->addr - (char *) i.addr); 2496 65 if (i.object != NULL) 2497 66 fprintf(stderr, " [%s]", i.object); 2498 67 } 2499 68 else if (s->name != NULL) 2500 69 fprintf(stderr, " %s", s->name); 2501 70 fputc('\n', stderr); 2502 71 } 2503 72 fprintf(stderr, "typestr: %s\n", 2504 73 d.typestr ? d.typestr : "<unknown>"); 2505 74 fprintf(stderr, "typesize: %lu\n", d.typesize); 2506 75 fprintf(stderr, "userdata: 0x%0*lX\n", sizeof(void *) * 2, d.userdata); 2507 76 fputs("flags: ", stderr); 2508 77 if (!d.freed && !d.marked && !d.profiled && !d.traced && !d.internal) 2509 78 fputs(" none\n", stderr); 2510 79 else 2511 80 { 2512 81 if (d.freed) 2513 82 fputs(" freed", stderr); 2514 83 if (d.marked) 2515 84 fputs(" marked", stderr); 2516 85 if (d.profiled) 2517 86 fputs(" profiled", stderr); 2518 87 if (d.traced) 2519 88 fputs(" traced", stderr); 2520 89 if (d.internal) 2521 90 fputs(" internal", stderr); 2522 91 fputc('\n', stderr); 2523 92 } 2524 93 } 2525 2526 2527 96 void func2(void) 2528 97 { 2529 98 void *p; 2530 2531 100 if (p = malloc(16)) 2532 101 { 2533 102 display(p); 2534 103 free(p); 2535 104 } 2536 105 display(p); 2537 106 } 2538 2539 2540 109 void func1(void) 2541 110 { 2542 111 func2(); 2543 112 } 2544 2545 2546 115 int main(void) 2547 116 { 2548 117 func1(); 2549 118 return EXIT_SUCCESS; 2550 119 } 2551 2552 When this is compiled and run, it should give the following output, 2553although the pointers are likely to be different. 2554 2555 block: 0x0806A0E8 2556 size: 16 2557 type: malloc 2558 alloc: 52 2559 realloc: 0 2560 thread: 0 2561 event: 97 2562 func: func2 2563 file: test4.c 2564 line: 100 2565 0x0804A743 func2+35 [./a.out] 2566 0x0804A790 func1+8 [./a.out] 2567 0x0804A79C main+8 [./a.out] 2568 0x4007C9CB __libc_start_main+255 [/lib/libc.so.6] 2569 0x0804A3E1 _start+33 [./a.out] 2570 typestr: <unknown> 2571 typesize: 0 2572 userdata: 0x00000000 2573 flags: none 2574 nothing known about address 0x0806A0E8 2575 2576 As you can see, anything that the mpatrol library knows about any 2577memory allocation can be obtained for use in your own code, which can 2578be very useful if you need to write handlers to keep track of memory 2579allocations, etc. for debugging purposes. It can also be useful to 2580have this information when running your program within a debugger, so 2581you can use the `__mp_printinfo()' function to display information 2582about a heap address if your debugger supports calling functions from 2583the command prompt. Note that the textual representation of the `type' 2584field returned by the `__mp_info()' function can be obtained by calling 2585`__mp_function()'. 2586 2587 The mpatrol library records the error code from the most recently 2588encountered warning or error in the `__mp_errno' global variable. This 2589variable can be read and compared with the known error codes listed in 2590`mpatrol.h'. It can also be reset to `MP_ET_NONE' before calling any 2591mpatrol library function in order to check to see if a warning or error 2592was encountered during the call. A string representation of the error 2593message corresponding to any mpatrol error code can be obtained by 2594calling the `__mp_strerror()' function with the specific code. 2595 2596 The `userdata' field shown in the previous example can be set for any 2597memory allocation with the `__mp_setuser()' function. This can have any 2598value and is not interpreted by the mpatrol library. It was added for 2599user code to associate its own data with memory allocations. 2600 2601 The `marked' field that is also shown in the previous example 2602indicates if a memory allocation has been _marked_ to indicate that it 2603should never be freed. This can only be performed from the source code 2604by calling `__mp_setmark()' with the address of the memory allocation. 2605Such a memory allocation can be reallocated but never freed, and will 2606not contribute to the list of memory leaks. It will also be profiled 2607and traced as freed by the end of program execution if memory 2608allocation profiling or tracing is enabled. 2609 2610 You may also have noticed the use of `__mp_syminfo()' in the above 2611example. This function is very similar to the `__mp_info()' function 2612except that instead of looking for the details of a memory allocation 2613at a specific address, it looks for the details of a function symbol at 2614that address. This provides user access to the data obtained by the 2615mpatrol symbol handler, including line number information if the 2616`USEDEBUG' option is supported and used. 2617 2618 It is also possible for you to be able to intercept calls to 2619allocate, reallocate and deallocate memory for your own purposes. You 2620can install prologue and epilogue functions that the mpatrol library 2621will call before and after every time one of its functions is called. 2622These can be used for additional tracing or simply to add extra checks 2623to your code. The following code is an example of this and can be 2624found in `tests/pass/test2.c'. 2625 2626 23 /* 2627 24 * Demonstrates and tests the facility for specifying user-defined 2628 25 * prologue and epilogue functions. 2629 26 */ 2630 2631 2632 29 #include "mpatrol.h" 2633 30 #include <stdio.h> 2634 2635 2636 33 __mp_prologuehandler old_prologue; 2637 34 __mp_epiloguehandler old_epilogue; 2638 2639 2640 37 void prologue(MP_CONST void *p, size_t l, size_t m, MP_CONST char *s, 2641 38 MP_CONST char *t, unsigned long u, MP_CONST void *a) 2642 39 { 2643 40 if (old_prologue != NULL) 2644 41 old_prologue(p, l, m, s, t, u, a); 2645 42 if (p == (void *) -1) 2646 43 fprintf(stderr, "allocating %lu bytes\n", l); 2647 44 else if (l == (size_t) -1) 2648 45 fprintf(stderr, "freeing allocation 0x%0*lX\n", sizeof(void *) * 2, p); 2649 46 else if (l == (size_t) -2) 2650 47 fprintf(stderr, "duplicating string `%s'\n", p); 2651 48 else 2652 49 fprintf(stderr, "reallocating allocation 0x%0*lX to %lu bytes\n", 2653 50 sizeof(void *) * 2, p, l); 2654 51 } 2655 2656 2657 54 void epilogue(MP_CONST void *p, MP_CONST char *s, MP_CONST char *t, 2658 55 unsigned long u, MP_CONST void *a) 2659 56 { 2660 57 if (p != (void *) -1) 2661 58 fprintf(stderr, "allocation returns 0x%0*lX\n", sizeof(void *) * 2, p); 2662 59 if (old_epilogue != NULL) 2663 60 old_epilogue(p, s, t, u, a); 2664 61 } 2665 2666 2667 64 int main(void) 2668 65 { 2669 66 void *p, *q; 2670 2671 68 old_prologue = __mp_prologue(prologue); 2672 69 old_epilogue = __mp_epilogue(epilogue); 2673 70 if (p = malloc(16)) 2674 71 if (q = realloc(p, 32)) 2675 72 free(q); 2676 73 else 2677 74 free(p); 2678 75 if (p = (char *) strdup("test")) 2679 76 free(p); 2680 77 __mp_prologue(old_prologue); 2681 78 __mp_epilogue(old_epilogue); 2682 79 return EXIT_SUCCESS; 2683 80 } 2684 2685 Once again, if you compile and run the above code, you should see 2686the following output. 2687 2688 allocating 16 bytes 2689 allocation returns 0x0806A0E8 2690 reallocating allocation 0x0806A0E8 to 32 bytes 2691 allocation returns 0x0806A0E8 2692 freeing allocation 0x0806A0E8 2693 duplicating string `test' 2694 allocation returns 0x0806A0E5 2695 freeing allocation 0x0806A0E5 2696 2697 Note that in the above code, the previous prologue and epilogue 2698functions were recorded and called. If this is not done then your 2699prologue and epilogue functions will completely override all others, 2700which is not usually the expected behaviour. In case you're wondering 2701what the last four arguments of the prologue and epilogue handlers are, 2702they are the function name, file name, line number and call address of 2703the function that called `malloc()' or a related function. These can 2704be used in the handlers to see where they were called from. 2705 2706 Along with being able to install prologue and epilogue functions, 2707you can also install a low-memory handler with the `__mp_nomemory()' 2708function, which will be called by the mpatrol library if it ever runs 2709out of memory during the call to a memory allocation function. This 2710gives you the opportunity to use that handler to either free up any 2711unneeded memory or simply to abort, thus removing the need to check for 2712failed allocations. Note that the low-memory handler also accepts the 2713same four common arguments that the prologue and epilogue handlers do. 2714 2715 It is also possible to iterate over all of the allocated and freed 2716memory allocations that are currently in the heap at any point in a 2717program. This is done by invoking the `__mp_iterate()' function with a 2718callback function which is called once per allocation with the start 2719address of the memory block being passed as the argument to the 2720callback function. Any further information about the memory allocation 2721can then be obtained via the `__mp_info()' function. Note that the 2722`__mp_iterateall()' function does the same as the `__mp_iterate()' 2723function except that it also includes all free memory blocks and memory 2724allocations that are internal to the mpatrol library. 2725 2726 Differences in the heap allocations (their details, not their 2727contents) between a previous point in a program's execution and the 2728current point of execution can be determined by calling the 2729`__mp_snapshot()' function and then invoking `__mp_iterate()' with that 2730snapshot value as its second argument at a later point in execution. 2731The callback function passed to `__mp_iterate()' will then only be 2732invoked with the start address of any memory allocation that has been 2733allocated or reallocated (or freed if the `NOFREE' option is being 2734used) since the snapshot point. This makes it possible to detect 2735localised memory leaks very easily, as the following example (found in 2736`tests/pass/test10.c') shows. 2737 2738 23 /* 2739 24 * Demonstrates and tests the facility for obtaining information on 2740 25 * local memory leaks. Will also edit or list the location of each 2741 26 * leak if the EDIT or LIST option is in effect. 2742 27 */ 2743 2744 2745 30 #include "mpatrol.h" 2746 31 #include <stdio.h> 2747 2748 2749 34 int callback(MP_CONST void *p, void *t) 2750 35 { 2751 36 __mp_allocstack *s; 2752 37 __mp_allocinfo d; 2753 2754 39 if (!__mp_info(p, &d) || !d.allocated) 2755 40 { 2756 41 fprintf(stderr, "nothing known about address 0x%0*lX\n", 2757 42 sizeof(void *) * 2, p); 2758 43 return -1; 2759 44 } 2760 45 if (!d.freed) 2761 46 { 2762 47 fprintf(stderr, "0x%0*lX", sizeof(void *) * 2, d.block); 2763 48 fprintf(stderr, " %s", d.func ? d.func : "<unknown>"); 2764 49 fprintf(stderr, " %s", d.file ? d.file : "<unknown>"); 2765 50 fprintf(stderr, " %lu", d.line); 2766 51 for (s = d.stack; s != NULL; s = s->next) 2767 52 { 2768 53 if (s == d.stack) 2769 54 fputs(" (", stderr); 2770 55 else 2771 56 fputs("->", stderr); 2772 57 if (s->name != NULL) 2773 58 fprintf(stderr, "%s", s->name); 2774 59 else 2775 60 fprintf(stderr, "0x%0*lX", sizeof(void *) * 2, s->addr); 2776 61 if (s->next == NULL) 2777 62 fputc(')', stderr); 2778 63 } 2779 64 fputc('\n', stderr); 2780 65 if ((d.file != NULL) && (d.line != 0)) 2781 66 __mp_view(d.file, d.line); 2782 67 *((unsigned long *) t) = *((unsigned long *) t) + d.size; 2783 68 return 1; 2784 69 } 2785 70 return 0; 2786 71 } 2787 2788 2789 74 void func2(unsigned long n) 2790 75 { 2791 76 void *p; 2792 2793 78 p = malloc((n * 10) + 1); 2794 79 if (n % 13) 2795 80 free(p); 2796 81 } 2797 2798 2799 84 void func1(void) 2800 85 { 2801 86 void *p; 2802 87 size_t i, n; 2803 88 unsigned long s, t; 2804 2805 90 p = malloc(16); 2806 91 s = __mp_snapshot(); 2807 92 for (i = 0; i < 128; i++) 2808 93 func2(i); 2809 94 free(p); 2810 95 t = 0; 2811 96 if (n = __mp_iterate(callback, &t, s)) 2812 97 fprintf(stderr, "Detected %lu memory leaks (%lu bytes)\n", n, t); 2813 98 if ((n != 10) || (t != 5860)) 2814 99 fputs("Expected 10 memory leaks (5860 bytes)\n", stderr); 2815 100 } 2816 2817 2818 103 int main(void) 2819 104 { 2820 105 void *p; 2821 2822 107 p = malloc(16); 2823 108 func1(); 2824 109 free(p); 2825 110 return EXIT_SUCCESS; 2826 111 } 2827 2828 Compiling this example with mpatrol and then running it will produce 2829the following list of memory leaks that were located between the points 2830of calling `__mp_snapshot()' and `__mp_iterate()'. 2831 2832 0x0806A108 func2 test10.c 78 (func2->func1->main->_start) 2833 0x0806A674 func2 test10.c 78 (func2->func1->main->_start) 2834 0x0806A6F8 func2 test10.c 78 (func2->func1->main->_start) 2835 0x0806A800 func2 test10.c 78 (func2->func1->main->_start) 2836 0x0806A988 func2 test10.c 78 (func2->func1->main->_start) 2837 0x0806AB94 func2 test10.c 78 (func2->func1->main->_start) 2838 0x0806AE20 func2 test10.c 78 (func2->func1->main->_start) 2839 0x0806B130 func2 test10.c 78 (func2->func1->main->_start) 2840 0x0806B4C0 func2 test10.c 78 (func2->func1->main->_start) 2841 0x0806B8D4 func2 test10.c 78 (func2->func1->main->_start) 2842 Detected 10 memory leaks (5860 bytes) 2843 2844 The `tools' directory in the mpatrol distribution contains two files 2845called `heapdiff.c' and `heapdiff.h' which demonstrate the use of 2846`__mp_snapshot()' and `__mp_iterate()' to find localised memory leaks. 2847Have a look at these files to see a further example of using these 2848functions, or perhaps even add these files to your application for 2849debugging purposes. Note that it is perfectly safe to allocate memory 2850in the callback function used by `__mp_iterate()', and such allocations 2851can be freed as well. The only restriction is that the callback 2852function should never free a memory allocation that it has not 2853allocated itself. 2854 2855 An alternative way to detect differences in the heap between two 2856points in a program's execution is to make use of the leak table. This 2857is a hash table that stores the number and size of memory allocations 2858and deallocations referenced by the source file and line number where 2859they occur(1). The leak table can be cleared with a call to 2860`__mp_clearleaktable()' and can be displayed with a call to 2861`__mp_leaktable()', which will display a sorted summary of the 2862allocated, freed or unfreed memory entries stored in the leak table. 2863Memory allocation events can be automatically logged in the leak table 2864by calling `__mp_startleaktable()' but this behaviour can be disabled 2865by calling `__mp_stopleaktable()'. Additional entries can be manually 2866added to the leak table with `__mp_addallocentry()' and 2867`__mp_addfreeentry()'. 2868 2869 If you wish to write your own diagnostics to the mpatrol log file 2870from within your source code then you can do so with the 2871`__mp_printf()' and `__mp_vprintf()' functions, which are the 2872functional equivalents of `printf()' and `vprintf()'. They prefix 2873every line written to the log file with `>', partly for making it clear 2874where user diagnostics occur and partly to avoid problems with external 2875utilities that parse the mpatrol log file. The `__mp_locprintf()' and 2876`__mp_vlocprintf()' functions are equivalent functions that also 2877display the source file and line number from where they were called 2878along with a stack trace, if available. 2879 2880 It is also possible to write out a memory dump in hexadecimal 2881format, a stack trace at the current point in execution and details of 2882a memory allocation to the log file in standard format using the 2883`__mp_logmemory()', `__mp_logstack()' and `__mp_logaddr()' functions 2884respectively. 2885 2886 You can also take advantage of the `mpedit' command from within the 2887mpatrol library with the `__mp_edit()', `__mp_list()' and `__mp_view()' 2888functions. The first invokes a text editor on a specified file and 2889line number, while the second displays a context listing of a file at a 2890given line number. The third function performs either or neither 2891depending on the setting of the `EDIT' or `LIST' options. 2892 2893 Finally, there are four functions which affect the mpatrol library 2894globally. The first, `__mp_check()', allows you to force an internal 2895check of the mpatrol library's data structures at any point during 2896program execution and also to free up any out of scope memory 2897allocations made by the `alloca()' family of functions. The 2898`__mp_memorymap()' function allows you to force the generation of a 2899memory map at any point in your program, in much the same way as it 2900would normally be displayed at the end of program execution if the 2901`SHOWMAP' option was used. The `__mp_summary()' function writes 2902library statistics to the mpatrol log file, while the `__mp_stats()' 2903function fills in a data structure with selected statistics for 2904examination in user code. 2905 2906 ---------- Footnotes ---------- 2907 2908 (1) If that information is not available then the function name or 2909return address will be used instead. 2910 2911 2912File: mpatrol.info, Node: Leak table, Prev: Library functions, Up: Using mpatrol 2913 2914Leak table 2915========== 2916 2917 The mpatrol library provides a hash table called a _leak table_ that 2918can be used to record memory allocations and deallocations for the 2919purpose of detecting memory leaks. It can be fully controlled from the 2920source code of a program by calling the appropriate mpatrol library 2921functions, but the mpatrol library can also be instructed to 2922automatically enter the details of each memory event into the leak 2923table by using the `LEAKTABLE' option. 2924 2925 The leak table records a flat profile of memory allocation behaviour 2926between two points in a program and is keyed by source file location. 2927What that means is, it contains an entry for each source file and line 2928number that allocated memory, and if more than one memory allocation 2929event occurred at that point then the entry will summarise the total 2930events that occurred at that point. In many cases, the source file and 2931line number is not available for a memory allocation event, in which 2932case either the function name or the return address can be used instead. 2933 2934 The following example shows the use of the leak table manipulation 2935functions. 2936 2937 1 /* 2938 2 * Illustrates the explicit and implicit manipulation of the 2939 3 * leak table. 2940 4 */ 2941 2942 2943 7 #include "mpatrol.h" 2944 2945 2946 10 int main(void) 2947 11 { 2948 12 void *p, *q; 2949 13 int r; 2950 2951 15 __mp_clearleaktable(); 2952 16 __mp_addallocentry("file.c", 1, 1); 2953 17 __mp_addfreeentry("file.c", 1, 1); 2954 18 __mp_addallocentry("file.c", 1, 2); 2955 19 __mp_addfreeentry("file.c", 1, 2); 2956 20 __mp_addallocentry("file.c", 1, 3); 2957 21 __mp_addfreeentry("file.c", 1, 3); 2958 22 __mp_addallocentry("function", 0, 8); 2959 23 __mp_addfreeentry("function", 0, 4); 2960 24 __mp_addallocentry("function", 0, 16); 2961 25 __mp_addfreeentry("function", 0, 12); 2962 26 __mp_addallocentry(NULL, 0x40000000, 8); 2963 27 r = __mp_startleaktable(); 2964 28 if (p = malloc(16)) 2965 29 if (q = realloc(p, 32)) 2966 30 free(q); 2967 31 else 2968 32 free(p); 2969 33 if (r == 0) 2970 34 __mp_stopleaktable(); 2971 35 __mp_leaktable(0, MP_LT_ALLOCATED, MP_LT_BOTTOM); 2972 36 __mp_printf("\n"); 2973 37 __mp_leaktable(0, MP_LT_FREED, MP_LT_COUNTS); 2974 38 __mp_printf("\n"); 2975 39 __mp_leaktable(0, MP_LT_UNFREED, 0); 2976 40 __mp_printf("\n"); 2977 41 return EXIT_SUCCESS; 2978 42 } 2979 2980 The output that appears in `mpatrol.log' should look similar to this. 2981 2982 bottom 5 allocated memory entries in leak table: 2983 2984 bytes count location 2985 -------- ------ -------- 2986 6 3 file.c line 1 2987 8 1 0x40000000 2988 16 1 test.c line 28 2989 24 2 function 2990 32 1 test.c line 29 2991 86 8 total 2992 2993 top 4 freed memory entries in leak table: 2994 2995 count bytes location 2996 ------ -------- -------- 2997 3 6 file.c line 1 2998 2 16 function 2999 1 32 test.c line 29 3000 1 16 test.c line 28 3001 7 70 total 3002 3003 top 2 unfreed memory entries in leak table: 3004 3005 bytes count location 3006 -------- ------ -------- 3007 8 1 0x40000000 3008 8 0 function 3009 16 1 total 3010 3011 Line 15 of the above program clears the leak table. This can be 3012done as many times as necessary during the execution of the program, 3013but note that there is only one leak table so this will affect the 3014`LEAKTABLE' option. The following 6 lines then add matching allocation 3015and deallocation entries to the leak table corresponding to a source 3016location of line 1 in a file called `file.c'. Any deallocation entries 3017must match the source position of the original allocation due to the 3018nature of the leak table. Note that these 6 lines correspond to an 3019allocation of 1 byte, followed by two reallocations of 2 and 3 bytes 3020respectively, followed by a final deallocation. 3021 3022 Lines 22-23 allocate 8 bytes from a function called `function()' but 3023only free 4 bytes, resulting in a memory leak of 4 bytes. Lines 24-25 3024do the same but allocate 16 bytes and free 12. The next line allocates 30258 bytes from a code address of `0x40000000' but does not free it, 3026resulting in a memory leak of 8 bytes. Note that if the line number is 3027specified as `0' then the filename will be taken as a function name, 3028and if the filename is specified as `NULL' then the line number will be 3029taken as a return address. If neither are specified then the number of 3030bytes will be added or subtracted from the `unknown' location. 3031 3032 Line 27 instructs mpatrol to automatically record any subsequent 3033memory allocation events in the leak table, while line 34 does the 3034opposite. The `__mp_startleaktable()' function returns `1' if 3035automatic leak table recording was turned on and `0' otherwise, so we 3036check in line 33 to see if we should turn off automatic recording by 3037examining the previous state. Lines 28-32 allocate, reallocate and 3038free some memory just to demonstrate this. 3039 3040 Finally, lines 35-40 display the contents of the memory leak table 3041that have been recorded since the call to `__mp_clearleaktable()'. 3042Three different types of display can be generated: allocated memory 3043allocations, freed memory allocations and unfreed memory allocations. 3044They can also be sorted by the total number of calls instead of the 3045total number of bytes (`MP_LT_COUNTS') or in reverse order with the 3046smallest first (`MP_LT_BOTTOM'). The count of `0' in the last table 3047indicates that there were a matching number of calls to allocate and 3048free memory within `function()' but the number of bytes freed was less 3049than the number of bytes allocated. This can only happen if the 3050entries were added by `__mp_addallocentry()' and `__mp_addfreeentry()' 3051and is usually an indication that something is wrong when making these 3052calls. 3053 3054 The leak table is a useful tool to manipulate when debugging your 3055application to check for memory leaks, but it is not as detailed as 3056full memory allocation profiling which is controlled by the `PROF' 3057option. It is probably better at summarising unfreed allocations than 3058the `SHOWUNFREED' option but does not show the call stack for each 3059allocation. 3060 3061 In addition, the `__mp_iterate()' function can be used within user 3062code to obtain details about changes in the heap since a certain point 3063in a program's execution. However, it can only provide details about 3064freed memory allocations if the `NOFREE' option is used. The leak 3065table will provide less details on freed memory allocations but its 3066advantage is that it does not require the use of the `NOFREE' option. 3067 3068 3069File: mpatrol.info, Node: Tools, Next: Utilities, Prev: Using mpatrol, Up: Top 3070 3071Tools 3072***** 3073 3074 The `tools' directory that comes with the mpatrol distribution 3075contains the source code for tools that are built on top of the mpatrol 3076library. The functions that are defined in these files are intended to 3077be useful for specific applications as well as providing real-world 3078examples of how to extend mpatrol. If you wish to use one of the 3079source files in the `tools' directory then you should first compile it 3080and then link it into your program along with the mpatrol library. 3081 3082 Alternatively, if you've already installed mpatrol on your system 3083then there should be an `mpatrol' subdirectory within the include 3084directory where `mpatrol.h' is installed that contains all of the 3085header files in the `tools' directory. There should also be a 3086libmptools library within the library directory where libmpatrol is 3087installed that contains an object file for each of the source files in 3088the `tools' directory. You can then make use of a particular tool by 3089including its header file from the `mpatrol' include subdirectory and 3090then linking with the libmptools library. 3091 3092 If you've written a useful extension to mpatrol then you might wish 3093to submit it for inclusion in the next release of mpatrol. Even if 3094it's just for a specific application, there might be other users out 3095there that may benefit from it. You'll even get a credit in the 3096manual! Note that any documentation should also be written in the 3097associated header file. 3098 3099* Menu: 3100 3101* dbmalloc:: Dbmalloc-compatible functions. 3102* dmalloc:: Dmalloc-compatible functions. 3103* heapdiff:: Determining heap differences. 3104* mgauge:: Memory allocation gauge. 3105* mtrace:: Memory allocation tracing. 3106 3107 3108File: mpatrol.info, Node: dbmalloc, Next: dmalloc, Up: Tools 3109 3110Dbmalloc-compatible functions 3111============================= 3112 3113 This file provides Dbmalloc(1)-compatible functions which are built 3114on top of the mpatrol library. They are compatible with the last known 3115public release of Dbmalloc (patch level 14), but only the 3116Dbmalloc-specific functions are defined here, leaving the overriding of 3117standard functions up to the mpatrol library. As the mpatrol library 3118does not currently override the C library string functions and the X 3119toolkit heap allocation functions, neither does this file. 3120 3121 The `dbmallopt()' function does not support the setting of all of the 3122Dbmalloc options. In fact, most of them do not make sense when applied 3123to the mpatrol library. Some of them have slightly changed behaviour 3124due to the mapping process and some of them cannot be implemented due 3125to the mpatrol library having been initialised beforehand. 3126 3127 The `malloc_dump()' function does not support the full recognition 3128of the `MALLOC_DETAIL' option in that it does not display the 3129additional columns and summary that the Dbmalloc library does. This is 3130because this would make no sense when applied to the mpatrol library, 3131but it does still affect whether freed allocations are shown in the 3132listing (although the details for such allocations are slightly 3133different, and there are no entries displayed for free memory blocks). 3134 3135 The output for the `malloc_dump()' and `malloc_list()' functions is 3136almost identical to that of the Dbmalloc library except for a slight 3137change in the pointer format when displaying the address of each memory 3138allocation. The stack information is obtained differently as well, 3139since the mpatrol library records symbolic stack tracebacks for each 3140memory allocation. As a result, `malloc_enter()' and `malloc_leave()' 3141do nothing and the return address in a stack frame is displayed if no 3142associated symbol name, file and line number could be determined. 3143Parentheses are not printed at the end of symbol names so that they can 3144be processed properly by a C++ demangler if necessary. Passing a file 3145descriptor of `0' to `malloc_dump()' or `malloc_list()' results in the 3146output being sent to the mpatrol log file. 3147 3148 The `malloc_size()' and `malloc_mark()' functions do not give an 3149error message if the pointer passed in does not correspond to a heap 3150allocation. Neither of these functions automatically perform an 3151integrity check of the heap. Note that the `malloc_chain_check()' 3152function will never return a non-zero value -- it always terminates 3153with an error message in the mpatrol log file whenever it detects heap 3154corruption. As a result, the `malloc_abort()' function is not used. 3155 3156 This file is initialised via the mpatrol library's initialiser 3157function feature, which means that if the `__mp_init_dbmalloc()' 3158function is noted by the mpatrol symbol manager then it will be called 3159when the mpatrol library is being initialised. If this feature is not 3160supported then the `dbmallinit()' function must be called as early on 3161as possible, otherwise this file will not be initialised until one of 3162its functions are called. 3163 3164 ---------- Footnotes ---------- 3165 3166 (1) Dbmalloc is copyright (C) 1990-1992 Conor P. Cahill. 3167 3168 3169File: mpatrol.info, Node: dmalloc, Next: heapdiff, Prev: dbmalloc, Up: Tools 3170 3171Dmalloc-compatible functions 3172============================ 3173 3174 This file provides Dmalloc(1)-compatible functions which are built 3175on top of the mpatrol library. They are compatible with the 4.8.2 3176release of Dmalloc, but only the Dmalloc-specific functions are defined 3177here, leaving the overriding of standard functions up to the mpatrol 3178library. As the mpatrol library does not currently override the C 3179library string functions, neither does this file. In addition, the 3180Dmalloc distribution comes with definitions for `xmemalign()', 3181`xvalloc()' and `xrecalloc()', neither of which are defined by this 3182file or by the mpatrol library. 3183 3184 This module is intended to work with the existing `dmalloc' command, 3185which sets the contents of the `DMALLOC_OPTIONS' environment variable 3186according to any specified command line options. The four documented 3187Dmalloc global variables are also defined, although the two address 3188variables are not acted upon and changing the `dmalloc_logpath' 3189variable has no effect yet. The `dmalloc_errno' variable is mapped 3190onto the `__mp_errno' variable and so the `dmalloc_strerror()' function 3191always returns strings that are specific to the mpatrol library. Note 3192that unlike the actual Dmalloc library, this file is not threadsafe, 3193and the `lockon' option has no effect. In addition, the `start' option 3194ignores the `file:line' syntax and uses allocation indices rather than 3195events. 3196 3197 The `dmalloc_debug()' function does not support the setting of all 3198of the Dmalloc flags, although this file defines preprocessor macros 3199for each of them, something which is not currently done in the 3200`dmalloc.h' file in the Dmalloc distribution. In fact, many of them do 3201not make sense when applied to the mpatrol library. Some of them have 3202slightly changed behaviour due to the mapping process and some of them 3203cannot be implemented due to the mpatrol library having been 3204initialised beforehand. 3205 3206 The `dmalloc_verify()' and `dmalloc_examine()' functions do not give 3207an error message if the pointer passed in does not correspond to a heap 3208allocation, and the latter function does not automatically perform an 3209integrity check of the heap. The `malloc_verify()' function has not 3210been included in this implementation since it is functionally identical 3211to `dmalloc_verify()'. Note that the `dmalloc_verify()' function will 3212only ever return `DMALLOC_VERIFY_ERROR' if the pointer to be checked is 3213not null and is invalid -- it always terminates with an error message 3214in the mpatrol log file whenever the pointer to be checked is null and 3215it has detected heap corruption. 3216 3217 The `dmalloc_log_heap_map()' and `dmalloc_log_stats()' functions map 3218on to the `__mp_memorymap()' and `__mp_summary()' functions and so have 3219entirely different display formats. The `dmalloc_log_unfreed()' and 3220`dmalloc_log_changed()' functions have similar display formats to the 3221original Dmalloc library, but the summary tables are displayed 3222differently and will display symbol names if they are available and 3223filename and line number information isn't. The `dmalloc_message()' 3224and `dmalloc_vmessage()' functions write tracing to the mpatrol log 3225file prefixed by three fields of optional information, which can be 3226controlled by the `LOG_*' macros when building this module. 3227 3228 This file is initialised via the mpatrol library's initialiser 3229function feature, which means that if the `__mp_init_dmalloc()' 3230function is noted by the mpatrol symbol manager then it will be called 3231when the mpatrol library is being initialised. If this feature is not 3232supported then the `dmalloc_init()' function must be called as early on 3233as possible, otherwise this file will not be initialised until one of 3234its functions are called. 3235 3236 ---------- Footnotes ---------- 3237 3238 (1) Dmalloc is copyright (C) 1992-2001 Gray Watson. 3239 3240 3241File: mpatrol.info, Node: heapdiff, Next: mgauge, Prev: dmalloc, Up: Tools 3242 3243Determining heap differences 3244============================ 3245 3246 This file defines `heapdiffstart()' and `heapdiffend()', which must 3247be called in matching pairs. They both take a `heapdiff' object as 3248their first parameter, which must still be in scope when the matching 3249call to `heapdiffend()' is made. The `heapdiff' object is initialised 3250at the call to `heapdiffstart()' and is finalised when `heapdiffend()' 3251is called. It must not be modified in between and should be treated as 3252an opaque type. `heapdiffend()' can only be called once per `heapdiff' 3253object before requiring that the `heapdiff' object be reinitialised 3254through a call to `heapdiffstart()'. 3255 3256 The second parameter to `heapdiffstart()' specifies a set of flags 3257that can be used to control what is written to the mpatrol log. A list 3258of all unfreed memory allocations can be logged with the `HD_UNFREED' 3259flag and a list of all freed memory allocations can be logged with the 3260`HD_FREED' flag, although the latter makes use of the `NOFREE' option 3261and can incur a large performance and space penalty, and also relies on 3262the `NOFREE' option being unmodified between the calls to 3263`heapdiffstart()' and `heapdiffend()'. Note that marked allocations 3264are not normally logged but this can be changed by adding the 3265`HD_MARKED' flag. 3266 3267 By default, only a minimal amount of detail is logged for each 3268allocation, but this can be changed with the `HD_FULL' flag to log full 3269details for each allocation. If the filename and line number for an 3270allocation is known and the `EDIT' or `LIST' option is being used then 3271using `HD_VIEW' will edit or list the relevant source file at the 3272correct line number, but only if the `EDIT' or `LIST' options are 3273supported. 3274 3275 If the `HD_CONTENTS' flag is specified then the contents of all 3276current memory allocations will be written to files and then compared 3277with their subsequent contents when `heapdiffend()' is called. If the 3278heap is large then this option can require a substantial amount of disk 3279space. All of the allocation contents files will be deleted when the 3280matching call to `heapdiffend()' is made. 3281 3282 3283File: mpatrol.info, Node: mgauge, Next: mtrace, Prev: heapdiff, Up: Tools 3284 3285Memory allocation gauge 3286======================= 3287 3288 This file defines `mgaugestart()', `mgaugeend()', `mgaugeon()' and 3289`mgaugeoff()' which produce and control a simple memory allocation 3290gauge in a terminal window. The gauge is displayed in textual form 3291using the standard I/O library rather than using a graphics library. 3292Since it is updated in real-time, it makes no sense to send the output 3293of the gauge to a file. Only one gauge can be in use at any one time. 3294 3295 The first argument to `mgaugestart()' is the filename of the file to 3296write the gauge to. As mentioned before, this should be a terminal 3297file that can be displayed in real-time, such as `/dev/pts*' on UNIX 3298systems or `CON:#?' on AmigaOS. If it is a null pointer then the 3299standard error file stream will be used. 3300 3301 The second argument to `mgaugestart()' specifies the character that 3302will be used to represent allocated memory. If this is given as 3303whitespace, `|' or `+' then `#' will be used instead. The third 3304argument specifies the number of bytes that the gauge represents. If 3305the total allocated memory exceeds this then `+' will be appended to 3306the gauge. The final argument specifies the frequency of memory 3307allocation events at which the gauge should be updated. If it is 3308specified as zero then all events will cause the gauge to be updated. 3309 3310 3311File: mpatrol.info, Node: mtrace, Prev: mgauge, Up: Tools 3312 3313Memory allocation tracing 3314========================= 3315 3316 This file defines `mtrace()' and `muntrace()', two functions which 3317enable and disable memory allocation tracing respectively. These 3318should be called in matching pairs but will have no effect unless the 3319`MALLOC_TRACE' environment variable is set to the filename of the trace 3320file to use. The resulting trace files can be processed by the 3321`mtrace' perl script which is distributed with the GNU C library. 3322 3323 3324File: mpatrol.info, Node: Utilities, Next: Profiling, Prev: Tools, Up: Top 3325 3326Utilities 3327********* 3328 3329 Several external programs are supplied with the mpatrol distribution 3330in the form of commands that can be used to enhance the functionality 3331of the mpatrol library. Each command comes with its own UNIX manual 3332page (although they also support the `--help' and `--version' options), 3333but a few of the commands are written as UNIX shell scripts and so will 3334not work on non-UNIX platforms. Note that the `mprof' command is 3335documented in the profiling chapter (*note Profiling::) and the 3336`mptrace' command is documented in the tracing chapter (*note 3337Tracing::). 3338 3339* Menu: 3340 3341* The mpatrol command:: Running with the library. 3342* The mleak command:: Detecting memory leaks. 3343* The mpsym command:: Obtaining symbolic information. 3344* The mpedit command:: Editing and listing files. 3345* The hexwords command:: Finding useful numbers. 3346 3347 3348File: mpatrol.info, Node: The mpatrol command, Next: The mleak command, Up: Utilities 3349 3350The `mpatrol' command 3351===================== 3352 3353 A command is provided with the mpatrol distribution which can run 3354programs that have been linked with the mpatrol library, using a 3355combination of mpatrol options that can be set via the command line. 3356Most of these options map directly onto their equivalent environment 3357variable settings and exist mainly so that the user does not have to 3358manually change the `MPATROL_OPTIONS' environment variable. 3359 3360 The main option that is the exception to this is the `--dynamic' 3361option, which can be used to run a program under the control of the 3362mpatrol library, even if it wasn't originally linked with the mpatrol 3363library. This can only be done on systems that support dynamic linking 3364and where the dynamic linker recognises the `LD_PRELOAD' or `_RLD_LIST' 3365environment variables. Even then, it can only be used when the program 3366that is being run has been dynamically linked with the system C 3367library, rather than statically linked. 3368 3369 The reason for all of these limitations is that some SVR4 UNIX 3370platforms have a special feature in the dynamic linker which can be 3371told to override the symbols from one shared library using the symbols 3372from another shared library at run-time. In this case, it involves 3373replacing the symbols for `malloc()', etc., in the system C library 3374with the mpatrol versions, but only if they were marked as undefined in 3375the original executable file and would therefore have to have been 3376loaded from `libc.so'. 3377 3378 However, if a program qualifies for use with the `--dynamic' option, 3379it means that you can trace all of its dynamic memory allocations as 3380well as running it with any of the mpatrol library's debugging options. 3381This is mainly a _toy_ feature which allows you to view and manipulate 3382the dynamic memory allocations of programs that you don't have the 3383source for, but in theory it could be quite useful if you need to debug 3384a previously released executable and are unable to recompile or relink 3385it. Note that if the program being run is multithreaded then you must 3386add the `--threads' option as well. 3387 3388 Note that the `mpatrol' command must be set up to use the correct 3389object file format access libraries that are required for your system 3390if you wish to use the `--dynamic' option. If the mpatrol library was 3391built with `FORMAT=FORMAT_COFF' or `FORMAT=FORMAT_XCOFF' support then it 3392must be told to preload the COFF access library (normally `libld.so'). 3393If it was built with `FORMAT=FORMAT_ELF32' or `FORMAT=FORMAT_ELF64' 3394support then it must be told to preload the ELF access library (normally 3395`libelf.so')(1). If it was built with `FORMAT=FORMAT_BFD' support then 3396it must be told to preload the GNU BFD access libraries (normally 3397`libbfd.so' and `libiberty.so')(2). However, if these libraries only 3398exist on your system in archive form then you must build 3399`libmpatrol.so' with these extra libraries incorporated into it so that 3400there are no dependencies on them at run-time. However, there may well 3401be problems if the resulting shared library contains position-dependent 3402code from the archive libraries you incorporated. The only way to find 3403out is for you to try it and see. 3404 3405 If you have access to the GNU linker on your system then there may 3406be a way to convert archive libraries into shared libraries if 3407position-independent code is not necessarily required for building 3408shared libraries on your system. If you use the `--whole-archive' and 3409`--shared' linker options then the GNU linker will read the entire 3410contents of one or more archive libraries before writing out a shared 3411library. All going well, you should be able to use the new shared 3412library in conjunction with the `--dynamic' `mpatrol' option. 3413 3414 In order to build a shared version of the mpatrol library with 3415embedded object file format access libraries, you must first modify the 3416`Makefile' you would normally use to build the mpatrol library. At the 3417lines where the linker is invoked to build the shared library, you must 3418explicitly add any object file format access libraries that you want to 3419use at the end of the linker command line. This ensures that all 3420references to such libraries will be resolved at link time rather than 3421run time. You must then edit the file `src/config.h' and remove all of 3422the libraries that you embedded from the definitions of the 3423`MP_PRELOAD_LIBS' and `MP_PRELOADMT_LIBS' preprocessor macros. 3424Finally, rebuild the shared version of the mpatrol library and the 3425`mpatrol' command and see if your efforts were worth it. 3426 3427 Because the `mpatrol' command sets the `MPATROL_OPTIONS' environment 3428variable for each of the programs it runs, it does not affect the value 3429of the environment variable for the current process (except on AmigaOS 3430and Netware where all processes share the same environment). However, 3431if you wish to use the `mpatrol' command to set `MPATROL_OPTIONS' in 3432the current process environment then you can use its `--show-env' 3433option to help you do so. This option will apply all of the `mpatrol' 3434command line options to the `MPATROL_OPTIONS' environment variable and 3435then display its value on the standard output without actually running 3436any programs. You can then manually set the environment variable with 3437the output from the `mpatrol' command. 3438 3439 If you wish the `MPATROL_OPTIONS' environment variable to be set in 3440the current shell process automatically with the `mpatrol' command then 3441you must use some shell trickery. The following script excerpts can be 3442found in `extra/.profile', `extra/.cshrc' and `extra/.gdbinit' and can 3443be inserted into your `ksh'/`bash', `csh'/`tcsh' and `gdb' 3444configuration files respectively. They each provide the `mallopt' 3445command, which takes `mpatrol' command options and sets the 3446`MPATROL_OPTIONS' environment variable in the current shell or debugger 3447process. 3448 3449 # mallopt for ksh/bash 3450 3451 function mallopt() 3452 { 3453 export MPATROL_OPTIONS=`mpatrol --show-env "$@"` 3454 echo "$MPATROL_OPTIONS" 3455 } 3456 3457 # mallopt for csh/tcsh 3458 3459 alias mallopt 'setenv MPATROL_OPTIONS "`mpatrol --show-env \!*`"; 3460 echo "$MPATROL_OPTIONS"' 3461 3462 # mallopt for gdb 3463 3464 define mallopt 3465 printf "Enter mpatrol library options: " 3466 shell read arg; echo set environment MPATROL_OPTIONS 3467 `mpatrol --show-env $arg` >/tmp/mpatrol.gdb 3468 source /tmp/mpatrol.gdb 3469 shell rm -f /tmp/mpatrol.gdb 3470 show environment MPATROL_OPTIONS 3471 end 3472 document mallopt 3473 Sets mpatrol library options in the current process environment. 3474 end 3475 3476 ---------- Footnotes ---------- 3477 3478 (1) A freely available version of the ELF access library, libelf, 3479can be downloaded from `ftp://sunsite.unc.edu/pub/Linux/libs/'. 3480 3481 (2) The GNU BFD access library can be downloaded from 3482`ftp://ftp.gnu.org/'. 3483 3484 3485File: mpatrol.info, Node: The mleak command, Next: The mpsym command, Prev: The mpatrol command, Up: Utilities 3486 3487The `mleak' command 3488=================== 3489 3490 Another utility program that is provided is called `mleak' and is 3491useful for detecting memory leaks in log files produced by the mpatrol 3492library. This program should be used if the mpatrol library could not 3493finish writing the log file due to abnormal program termination (which 3494would prevent the `SHOWUNFREED' option from working), but note that 3495some of the unfreed allocations might have been freed if the program 3496had terminated successfully. 3497 3498 The `mleak' command scans through an mpatrol log file looking for 3499lines beginning with `ALLOC:' and `FREE:' but ignores lines beginning 3500with `REALLOC:', so only the `LOGALLOCS' and `LOGFREES' options are 3501necessary when running a program linked with the mpatrol library. Note 3502that as a result of this, no attempt is made to account for resizing of 3503memory allocations and so the total amount of memory used by the 3504resulting unfreed allocations may not be entirely accurate. 3505 3506 This command will also read the unfreed allocations table produced 3507by the `SHOWUNFREED' option in the log file if one is present. The 3508entries in the table will be compared with the currently allocated 3509entries and will be added if not already present. However, this 3510behaviour can be disabled by supplying the `--ignore' option to the 3511`mleak' command. 3512 3513 The `mleak' command can also be instructed to limit the number of 3514lines of stack tracing information that it will display for each 3515unfreed memory allocation. This is controlled by the `--max-stack' 3516option which takes the maximum number of stack trace lines to display 3517as an argument. If the number of lines is given as `0' (the default) 3518then there will be no limit to the length of each stack trace. 3519 3520 The `mleak' command takes one optional argument which must be a valid 3521mpatrol log filename but if it is omitted then it will use 3522`mpatrol.log' as the name of the log file to use. The `mleak' command 3523makes two passes over the log file so the file must be 3524randomly-accessible. If the filename argument is given as `-' then the 3525standard input file stream will be used as the log file. Note also 3526that the `mleak' command supports the `--help' and `--version' options 3527in common with the other mpatrol command line tools. 3528 3529 Note that mpatrol patch 5 (which can be downloaded from 3530`http://www.cbmamiga.demon.co.uk/mpatrol/patches/mpatrol_patch5.tar.gz') 3531contains the source code to a FORTRAN 90 program called 3532`condenseleaklog' which offers similar facilities to the `mleak' 3533command, as well as the ability to trim and filter stack traces. 3534 3535 3536File: mpatrol.info, Node: The mpsym command, Next: The mpedit command, Prev: The mleak command, Up: Utilities 3537 3538The `mpsym' command 3539=================== 3540 3541 Another utility program that is provided is called `mpsym', which is 3542used to parse a log file produced by the mpatrol library and uses a 3543debugger to append symbol names and source level information to code 3544addresses in stack tracebacks. This should be used if the `USEDEBUG' 3545option is not supported on a particular platform or does not work 3546properly with a specific program. It will replace all existing symbols 3547and source level information associated with the stack tracebacks in 3548the mpatrol log file and will display the resulting log file on the 3549standard output file stream. 3550 3551 The first argument to `mpsym' must be the filename of the executable 3552file that produced the mpatrol log file but if it is omitted then 3553`mpsym' will use `a.out' as the name of the executable file to use. 3554The `mpsym' command will read the symbol table and debugging sections 3555from this file in order to map the code addresses that appear in the 3556mpatrol log file into symbol names and source level information. If 3557the executable file does not contain a symbol table then no symbol 3558names will be available and if it does not contain the appropriate 3559debugging sections then no source level information will be available 3560either. Obviously, if the executable file is not the same as the one 3561that created the mpatrol log file then the final output will be wrong. 3562 3563 The second argument to `mpsym' must be a valid mpatrol log filename 3564but if it is omitted then `mpsym' will use `mpatrol.log' as the name of 3565the log file to use, or `progfile.log' if it can't find that. The 3566`mpsym' command makes two passes over the log file so the file must be 3567randomly-accessable. Note also that the `mpsym' command supports the 3568`--help' and `--version' options in common with the other mpatrol 3569command line tools. 3570 3571 If the mpatrol library cannot determine the name of a symbol for 3572display in the log file then it will mark the symbol as `???'. If the 3573debugger that is being used by `mpsym' also has problems determining 3574the name of the symbol then you can pass the `--skip' option to `mpsym' 3575to instruct it to skip any symbols marked as `???' in the log file. 3576 3577 The `mpsym' command currently uses `gdb' as the debugger with which 3578to obtain the additional information about the code addresses in the 3579mpatrol log file. It also makes use of several UNIX text processing 3580commands, including `perl' if it is installed, in order to extract 3581information from the debugger's output and from the log file. As a 3582result, the `mpsym' command is only likely to work on UNIX platforms or 3583on systems which have the necessary commands installed. 3584 3585 3586File: mpatrol.info, Node: The mpedit command, Next: The hexwords command, Prev: The mpsym command, Up: Utilities 3587 3588The `mpedit' command 3589==================== 3590 3591 Yet another utility program that is provided is called `mpedit', 3592which is used to invoke a text editor on a given source file and 3593optionally jump to a specific line number. It is used as a support 3594command by the mpatrol library when the `EDIT' or `LIST' options are 3595used but it can quite easily be used as a command in its own right if 3596properly configured. Because it is a shell script it can be easily 3597configured to support other editors, but this unfortunately limits it 3598to UNIX platforms at the moment. 3599 3600 The first argument to `mpedit' must be the filename of the source 3601file to be edited or listed. If the source file does not exist then 3602the contents of the `MPATROL_SOURCEPATH' environment variable will be 3603used to help locate the source file, even if the filename contained an 3604absolute or relative path component. This environment variable should 3605consist of a colon-separated list of directory names which may contain 3606absolute paths or be relative to the current directory; the first 3607directory in the list will be searched first. If the 3608`MPATROL_SOURCEPATH' environment variable is not set then only the 3609current directory will be searched. You can also use the `--source-dir' 3610option to add directories to the search path used to locate the source 3611file. Multiple `--source-dir' options may be given, and each will be 3612prepended to the `MPATROL_SOURCEPATH' environment variable in the order 3613given on the command line. 3614 3615 If the second argument specifying the line number is omitted then it 3616is assumed to be `1'. The text editor will attempt to jump to the 3617specified line after opening the source file. The text editor that 3618`mpedit' uses is controlled by setting the `EDITOR' environment 3619variable. This can be set to the full pathname of the text editor to 3620use or it can be set to the command that would normally be used to 3621invoke the text editor, but it cannot also contain command line 3622options. You can also use the `--editor' option to specify the text 3623editor on the command line instead of using the value in the `EDITOR' 3624environment variable. 3625 3626 The currently supported editors are `vi', `vim', `elvis', `emacs', 3627`xemacs', `pico' and `nano', and if the `EDITOR' environment variable 3628is not set then the default will be `vi'. Selecting an unsupported 3629text editor will result in an error. However, you can edit the 3630`mpedit' file to add support for your own favourite text editor as long 3631as it supports a way to immediately jump to a specific line number when 3632it is first started up. Note that the text editor must also open a new 3633window to edit the source file so that it does not obscure any mpatrol 3634diagnostic messages, and if it does not support this then a new 3635terminal window must be opened for it to use. 3636 3637 If the `--listing' option is given on the command line then the 3638`mpedit' command will display a context listing of the source file at 3639the specified line number to the standard error output stream instead of 3640invoking the text editor. The listing will be annotated with line 3641numbers and will also show the contents of the five lines before and 3642after the specified line if possible. Note also that the `mpedit' 3643command supports the `--help' and `--version' options in common with 3644the other mpatrol command line tools. 3645 3646 3647File: mpatrol.info, Node: The hexwords command, Prev: The mpedit command, Up: Utilities 3648 3649The `hexwords' command 3650====================== 3651 3652 The final utility program that is provided is called `hexwords', 3653which is used to generate hexadecimal constants from a dictionary of 3654known words. Such numerical constants can be used in source files for 3655a variety of debugging problems, and problems with uninitialised 3656variables are especially relevant since these special numbers will 3657stand out if seen from within a debugger. For example, here are some 3658common (and some not-so-common) 32-bit hexadecimal constants that can 3659be used as debugging aids: 3660 3661_word_ _hex constant_ 3662addedbad `0xaddedbad' 3663allocate `0xa110ca7e' 3664badlabel `0xbad1abe1' 3665baseball `0xba5eba11' 3666codebabe `0xc0debabe' 3667codedbad `0xc0dedbad' 3668deadbeef `0xdeadbeef' 3669deadcode `0xdeadc0de' 3670failsafe `0xfa115afe' 3671feedface `0xfeedface' 3672freedata `0xf4eeda7a' 3673goodcode `0x600dc0de' 3674 3675 As can be seen above, many decimal digits can be used to represent 3676the letters that they most closely resemble, along with the hexadecimal 3677digits `A' through `F'. This provides a much larger selection of words 3678that can be matched, although the digits `3' and `8' cannot be used due 3679to the lack of any similar-looking letters. The digits and their 3680corresponding letters are given in the following table. 3681 3682_digit_ _letter_ 3683`0' O, o or Q 3684`1' I, i or l 3685`2' Z or z 3686`3' - 3687`4' q or R 3688`5' S or s 3689`6' G 3690`7' J or T 3691`8' - 3692`9' g 3693`A-F' A-F 3694`a-f' a-f 3695 3696 The argument to `hexwords' must be a valid dictionary filename but 3697if it is omitted then `hexwords' will use `/usr/dict/words' as the name 3698of the dictionary file to use. If that cannot be found then hexwords 3699will try `/usr/lib/dict/words' and `/usr/share/dict/words'. The 3700dictionary file must be a plain text file that contains one word per 3701line, otherwise few to no words will be matched. 3702 3703 The words that are matched from the dictionary file can be 3704controlled by using the `--match' option, which sets the type of 3705case-sensitivity to use. A setting of `exact' performs a 3706case-sensitive comparison of all of the words in the dictionary file 3707and the hexadecimal digits, whereas a setting of `any' does not. The 3708`lower' and `upper' settings convert the words in the dictionary file 3709to lower and upper case respectively before performing a case-sensitive 3710comparison. The default case-sensitivity is `exact'. 3711 3712 The minimum and maximum number of letters that are matched are 3713controlled by the `--minimum' and `--maximum' options. None of the 3714hexadecimal numbers displayed will have any less or more digits that 3715those specified with these options. The default minimum is `4' digits 3716and the default maximum is `8' digits. Note also that the `hexwords' 3717command supports the `--help' and `--version' options in common with 3718the other mpatrol command line tools. 3719 3720 The `hexwords' command currently makes use of several UNIX text 3721processing commands in order to extract the words and their hexadecimal 3722equivalents. As a result, the `hexwords' command is only likely to 3723work on UNIX platforms or on systems which have the necessary commands 3724installed. 3725 3726 3727File: mpatrol.info, Node: Profiling, Next: Tracing, Prev: Utilities, Up: Top 3728 3729Profiling 3730********* 3731 3732 The mpatrol library has the capability to summarise the information 3733it accumulated about the behaviour of dynamic memory allocations and 3734deallocations over the lifetime of any program that it was linked and 3735run with. This summary shows a rough profile of all memory allocations 3736that were made, and is hence called _profiling_. There are several 3737other different kinds of profiling provided with most compilation 3738tools, but they generally profile function calls or line numbers in 3739combination with the time it takes to execute them. 3740 3741 Memory allocation profiling is useful since it allows a programmer 3742to see which functions directly allocate memory from the heap, with a 3743view to optimising the memory usage or performance of a program. It 3744also summarises any unfreed memory allocations that were present at the 3745end of program execution, some of which could be as a result of memory 3746leaks. In addition, a summary of the sizes and distribution of all 3747memory allocations and deallocations is available. 3748 3749 A memory allocation call graph is also available for the programmer 3750to be able to see the caller and callee relationships for all functions 3751that allocated memory, either directly or indirectly. This graph is 3752shown in a tabular form similar to that of `gprof', but it can also be 3753written to a graph specification file for later processing by `dot'. 3754The `dot' and `dotty' commands are part of GraphViz, an excellent graph 3755visualisation package that was developed at AT&T Bell Labs and is 3756available for free download for UNIX and Windows platforms from 3757`http://www.research.att.com/sw/tools/graphviz/'. 3758 3759 Only allocations and deallocations are recorded, with each 3760reallocation being treated as a deallocation immediately followed by an 3761allocation. For full memory allocation profiling support, call stack 3762traversal must be supported in the mpatrol library and all of the 3763program's symbols must have been successfully read by the mpatrol 3764library before the program was run. The library will attempt to 3765compensate if either of these requirements are not met, but the 3766displayed tables may contain less meaningful information. Cycles that 3767appear in the allocation call graph are due to recursion and are 3768currently dealt with by only recording the memory allocations once 3769along the call stack. 3770 3771 Memory allocation profiling is disabled by default, but can be 3772enabled using the `PROF' option. This writes all of the profiling data 3773to a file called `mpatrol.out' in the current directory at the end of 3774program execution, but the name of this file can be changed using the 3775`PROFFILE' option and the default directory in which to place these 3776files can be changed by setting the `PROFDIR' environment variable. 3777Sometimes it can also be desirable for the mpatrol library to write out 3778the accumulated profiling information in the middle of program 3779execution rather than just at the end, even if it is only partially 3780complete, and this behaviour can be controlled with the `AUTOSAVE' 3781option. This can be particularly useful when running the program from 3782within a debugger, when it is necessary to analyse the profiling 3783information at a certain point during program execution. 3784 3785 When profiling memory allocations, it is necessary to distinguish 3786between small, medium, large and extra large memory allocations that 3787were made by a function. The boundaries which distinguish between 3788these allocation sizes can be controlled via the `SMALLBOUND', 3789`MEDIUMBOUND' and `LARGEBOUND' options, but they default to 32, 256 and 37902048 bytes respectively, which should suffice for most circumstances. 3791 3792 The `mprof' command is a tool designed to read a profiling output 3793file produced by the mpatrol library and display the profiling 3794information that was obtained. The profiling information includes 3795summaries of all of the memory allocations listed by size and the 3796function that allocated them and a list of memory leaks with the call 3797stack of the allocating function. It also includes a graph of all 3798memory allocations listed in tabular form, and an optional graph 3799specification file for later processing by the `dot' graph 3800visualisation package. 3801 3802 The `mprof' command also attempts to calculate the endianness of the 3803processor that produced the profiling output file and reads the file 3804accordingly. This means that it is possible to use `mprof' on a SPARC 3805machine to read a profiling output file that was produced on an Intel 380680x86 machine, for example. However, this will only work if the 3807processor that produced the profiling output file has the same word 3808size as the processor that is running the `mprof' command. For 3809example, reading a 64-bit profiling output file on a 32-bit machine 3810will not work. 3811 3812 In addition, the profiling output file also contains the version 3813number of the mpatrol library which produced it. If the major version 3814number that is embedded in the profiling output file is newer that the 3815version of mpatrol that `mprof' came with then `mprof' will refuse to 3816read the file. You should download the latest version of mpatrol in 3817that case. The reason for storing the version number is so that the 3818format of the profiling output file can change between releases of 3819mpatrol, but also allow `mprof' to cope with older versions. 3820 3821 Along with the options listed below, the `mprof' command takes one 3822optional argument which must be a valid mpatrol profiling output 3823filename but if it is omitted then it will use `mpatrol.out' as the 3824name of the file to use. If the filename argument is given as `-' then 3825the standard input file stream will be used as the profiling output 3826file. Note also that the `mprof' command supports the `--help' and 3827`--version' options in common with the other mpatrol command line tools. 3828 3829`--addresses' 3830 Specifies that different call sites from within the same function 3831 are to be differentiated and that the names of all functions 3832 should be displayed with their call site offset in bytes. This 3833 affects the direct allocation and memory leak tables, as well as 3834 the allocation call graph and the graph specification file. 3835 3836`--call-graph' 3837 Specifies that the allocation call graph should be displayed. 3838 This is not displayed by default as it can get very large for even 3839 a moderately sized profiling output file. 3840 3841`--counts' 3842 Specifies that certain tables should be sorted by the number of 3843 allocations or deallocations rather than the total number of bytes 3844 allocated or deallocated. This affects the direct allocation and 3845 memory leak tables, as well as the allocation call graph and the 3846 graph specification file. 3847 3848`--graph-file' <FILE> 3849 Specifies that the allocation call graph should also be written to 3850 a graph specification file for later visualisation with `dot'. If 3851 FILE is given as `stdout' or `stderr' then the corresponding file 3852 stream will be used as the target for the graph specification file. 3853 3854`--leaks' 3855 Specifies that memory leaks rather than memory allocations are to 3856 be written to the graph specification file. This option only 3857 affects the output from the `--graph-file' option. 3858 3859`--stack-depth' <DEPTH> 3860 Specifies the maximum stack depth to use when calculating if one 3861 call site has the same call stack as another call site. This also 3862 specifies the maximum number of functions to display in a call 3863 stack. If DEPTH is `0' then the call stack depth will be 3864 unlimited in size. The default call stack depth is `1'. This 3865 affects the memory leak table. 3866 3867 We'll now look at an example of using the mpatrol library to profile 3868the dynamic memory allocations in a program. However, remember that 3869this example will only fully work on your machine if the mpatrol 3870library supports call stack traversal and reading symbols from 3871executable files on that platform. If that is not the case then only 3872some of the features will be available. 3873 3874 The following example program performs some simple calculations and 3875displays a list of numbers on its standard output file stream, but it 3876serves to illustrate all of the different features of memory allocation 3877profiling that mpatrol is capable of. The source for the program can 3878be found in `tests/profile/test1.c'. 3879 3880 23 /* 3881 24 * Associates an integer value with its negative string equivalent in a 3882 25 * structure, and then allocates 256 such pairs randomly, displays them 3883 26 * then frees them. 3884 27 */ 3885 3886 3887 30 #include <stdio.h> 3888 31 #include <stdlib.h> 3889 32 #include <string.h> 3890 3891 3892 35 typedef struct pair 3893 36 { 3894 37 int value; 3895 38 char *string; 3896 39 } 3897 40 pair; 3898 3899 3900 43 pair *new_pair(int n) 3901 44 { 3902 45 static char s[16]; 3903 46 pair *p; 3904 3905 48 if ((p = (pair *) malloc(sizeof(pair))) == NULL) 3906 49 { 3907 50 fputs("Out of memory\n", stderr); 3908 51 exit(EXIT_FAILURE); 3909 52 } 3910 53 p->value = n; 3911 54 sprintf(s, "%d", -n); 3912 55 if ((p->string = strdup(s)) == NULL) 3913 56 { 3914 57 fputs("Out of memory\n", stderr); 3915 58 exit(EXIT_FAILURE); 3916 59 } 3917 60 return p; 3918 61 } 3919 3920 3921 64 int main(void) 3922 65 { 3923 66 pair *a[256]; 3924 67 int i, n; 3925 3926 69 for (i = 0; i < 256; i++) 3927 70 { 3928 71 n = (int) ((rand() * 256.0) / (RAND_MAX + 1.0)) - 128; 3929 72 a[i] = new_pair(n); 3930 73 } 3931 74 for (i = 0; i < 256; i++) 3932 75 printf("%3d: %4d -> \"%s\"\n", i, a[i]->value, a[i]->string); 3933 76 for (i = 0; i < 256; i++) 3934 77 free(a[i]); 3935 78 return EXIT_SUCCESS; 3936 79 } 3937 3938 After the above program has been compiled and linked with the 3939mpatrol library, it should be run with the `PROF' option set in the 3940`MPATROL_OPTIONS' environment variable. Note that `mpatrol.h' was not 3941included as it is not necessary for profiling purposes. 3942 3943 If all went well, a list of numbers should be displayed on the 3944screen and a file called `mpatrol.out' should have been produced in the 3945current directory. This is a binary file containing the total amount 3946of profiling information that the mpatrol library gathered while the 3947program was running, but it contains concise numerical data rather than 3948human-readable data. To make use of this file, the `mprof' command 3949must be run. An excerpt from the output produced when running `mprof' 3950with the `--call-graph' option is shown below(1). 3951 3952 ALLOCATION BINS 3953 3954 (number of bins: 1024) 3955 3956 allocated unfreed 3957 -------------------------------- -------------------------------- 3958 size count % bytes % count % bytes % 3959 3960 2 9 1.76 18 0.61 9 3.52 18 1.95 3961 3 105 20.51 315 10.61 105 41.02 315 34.16 3962 4 121 23.63 484 16.30 121 47.27 484 52.49 3963 5 21 4.10 105 3.54 21 8.20 105 11.39 3964 8 256 50.00 2048 68.96 0 0.00 0 0.00 3965 3966 total 512 2970 256 922 3967 3968 DIRECT ALLOCATIONS 3969 3970 (0 < s <= 32 < m <= 256 < l <= 2048 < x) 3971 3972 allocated unfreed 3973 -------------------------- -------------------------- 3974 bytes % s m l x bytes % s m l x count function 3975 3976 2970 100.00 %% 922 100.00 %% 512 new_pair 3977 3978 2970 %% 922 %% 512 total 3979 3980 MEMORY LEAKS 3981 3982 (maximum stack depth: 1) 3983 3984 unfreed allocated 3985 ---------------------------------------- ---------------- 3986 % bytes % count % bytes count function 3987 3988 100.00 922 31.04 256 50.00 2970 512 new_pair 3989 3990 922 31.04 256 50.00 2970 512 total 3991 3992 ALLOCATION CALL GRAPH 3993 3994 (number of vertices: 3) 3995 3996 allocated unfreed 3997 --------------------- --------------------- 3998 index bytes s m l x bytes s m l x function 3999 ------------------------------------------------- 4000 [1] _start [1] 4001 2970 %% 922 %% main [3] 4002 ------------------------------------------------- 4003 2970 %% 922 %% main [3] 4004 [2] new_pair [2] 4005 ------------------------------------------------- 4006 2970 %% 922 %% _start [1] 4007 [3] main [3] 4008 2970 %% 922 %% new_pair [2] 4009 4010 The first table shown is the allocation bin table which summarises 4011the sizes of all objects that were dynamically allocated throughout the 4012lifetime of the program. In this particular case, counts of all 4013allocations and deallocations of sizes 1 to 1023 bytes were recorded by 4014the mpatrol library in their own specific _bin_ and this information 4015was written to the profiling output file. Allocations and 4016deallocations of sizes larger than or equal to 1024 bytes are counted 4017as well and the total number of bytes that they represent are also 4018recorded. This information can be extremely useful in understanding 4019which sizes of data structures are allocated most during program 4020execution, and where changes might be made to make more efficient use 4021of the dynamically allocated memory. 4022 4023 As can be seen from the allocation bin table, 9 allocations of 2 4024bytes, 105 allocations of 3 bytes, 121 allocations of 4 bytes, 21 4025allocations of 5 bytes and 256 allocations of 8 bytes were made during 4026the execution of the program. However, all of these memory allocations 4027except the 8 byte allocations were still not freed by the time the 4028program terminated, resulting in a total memory leak of 922 bytes. 4029 4030 The next table shown is the direct allocation table which lists all 4031of the functions that allocated memory and how much memory they 4032allocated. The `s m l x' columns represent _small_, _medium_, _large_ 4033and _extra large_ memory allocations, which in this case are 0 bytes is 4034less than a small allocation, which is less than or equal to 32 bytes, 4035which is less than a medium allocation, which is less than or equal to 4036256 bytes, which is less than a large allocation, which is less than or 4037equal to 2048 bytes, which is less than an extra large allocation. The 4038numbers listed under these columns represent a percentage of the 4039overall total and are listed as `%%' if the percentage is 100% or as 4040`.' if the percentage is less than 1%. Percentages of 0% are not 4041displayed. 4042 4043 The information displayed in the direct allocation table is useful 4044for seeing exactly which functions in a program directly perform memory 4045allocation, and can quickly highlight where optimisations can be made 4046or where functions might be making unnecessary allocations. In the 4047example, this table shows us that 2970 bytes were allocated over 512 4048calls by `new_pair()' and that 922 bytes were left unfreed at program 4049termination. All of the allocations that were made by `new_pair()' 4050were between 1 and 32 bytes in size. 4051 4052 We could now choose to sort the direct allocation table by the 4053number of calls to allocate memory, rather than the number of bytes 4054allocated, with the `--counts' option to `mprof', but that is not 4055relevant in this example. However, we know that there are two calls to 4056allocate memory from `new_pair()', so we can use the `--addresses' 4057option to `mprof' to show all call sites within functions rather than 4058just the total for each function. This option does not affect the 4059allocation bin table so the new output from `mprof' with the 4060`--call-graph' and `--addresses' options looks like: 4061 4062 DIRECT ALLOCATIONS 4063 4064 (0 < s <= 32 < m <= 256 < l <= 2048 < x) 4065 4066 allocated unfreed 4067 -------------------------- -------------------------- 4068 bytes % s m l x bytes % s m l x count function 4069 4070 2048 68.96 69 0 0.00 256 new_pair+20 4071 922 31.04 31 922 100.00 %% 256 new_pair+140 4072 4073 2970 %% 922 %% 512 total 4074 4075 MEMORY LEAKS 4076 4077 (maximum stack depth: 1) 4078 4079 unfreed allocated 4080 ---------------------------------------- ---------------- 4081 % bytes % count % bytes count function 4082 4083 100.00 922 100.00 256 100.00 922 256 new_pair+140 4084 4085 922 31.04 256 50.00 2970 512 total 4086 4087 ALLOCATION CALL GRAPH 4088 4089 (number of vertices: 4) 4090 4091 allocated unfreed 4092 --------------------- --------------------- 4093 index bytes s m l x bytes s m l x function 4094 ------------------------------------------------- 4095 [1] _start+100 [1] 4096 2970 %% 922 %% main+120 [4] 4097 ------------------------------------------------- 4098 2048 %% 0 main+120 [4] 4099 [2] new_pair+20 [2] 4100 ------------------------------------------------- 4101 922 %% 922 %% main+120 [4] 4102 [3] new_pair+140 [3] 4103 ------------------------------------------------- 4104 2970 %% 922 %% _start+100 [1] 4105 [4] main+120 [4] 4106 2048 %% 0 new_pair+20 [2] 4107 922 %% 922 %% new_pair+140 [3] 4108 4109 The names of the functions displayed in the above tables now have a 4110byte offset appended to them to indicate at what position in the 4111function a call to allocate memory occurred(2). Now it is possible to 4112see that the first call to allocate memory from within `new_pair()' has 4113had all of its memory freed, but the second call (from `strdup()') has 4114had none of its memory freed. 4115 4116 This is also visible in the next table, which is the memory leak 4117table and lists all of the functions that allocated memory but did not 4118free all of their memory during the lifetime of the program. The 4119default behaviour of `mprof' is to show only the function that directly 4120allocated the memory in the memory leak table, but this can be changed 4121with the `--stack-depth' option. This accepts an argument specifying 4122the maximum number of functions to display in one call stack, with zero 4123indicating that all functions in a call stack should be displayed. 4124This can be useful for tracing down the functions that were indirectly 4125responsible for the memory leak. The new memory leak table displayed 4126by `mprof' with the `--addresses' and `--stack-depth 0' options looks 4127like: 4128 4129 MEMORY LEAKS 4130 4131 (maximum stack depth: 0) 4132 4133 unfreed allocated 4134 ---------------------------------------- ---------------- 4135 % bytes % count % bytes count function 4136 4137 100.00 922 100.00 256 100.00 922 256 new_pair+140 4138 main+120 4139 _start+100 4140 4141 922 31.04 256 50.00 2970 512 total 4142 4143 Now that we know where the memory leak is coming from, we can fix it 4144by freeing the string as well as the structure at line 77. A version 4145of the above program that does not contain the memory leak can be found 4146in `tests/profile/test2.c'. 4147 4148 The final table that is displayed is the allocation call graph, 4149which shows the relationship between a particular function in the call 4150graph, the functions that called it (parents), and the functions that 4151it called (children). Every function that appears in the allocation 4152call graph is displayed with a particular index that can be used to 4153cross-reference it. The functions which called a particular function 4154are displayed directly above it, while the functions that the function 4155called are displayed directly below it. In the above example, 4156`_start()' called `main()', which then called `new_pair()' which 4157allocated the memory. 4158 4159 The memory that has been allocated by a function (either directly, 4160or indirectly by its children) for its parents is shown in the details 4161for the parent functions, showing both a breakdown of the allocated 4162memory and a breakdown of the unfreed memory. This also occurs for the 4163child functions. If a function does not directly allocate memory then 4164the total memory allocated for its parents will equal the total memory 4165allocated by its children. However, if a parent or child function is 4166part of a cycle in the call graph then a `(*)' will appear in the 4167leftmost column of the call graph. In that case the total incoming 4168memory may not necessarily equal the total outgoing memory for the main 4169function. 4170 4171 In the example above when the `--addresses' option is used, it 4172should be clear that `new_pair()+20' allocates 2048 bytes for `main()', 4173while `new_pair()+140' allocates 922 bytes for `main()'. The `main()' 4174function itself allocates 2970 bytes for `_start()' overall via the 4175`new_pair()' function. 4176 4177 It is also possible to view this information graphically if you have 4178the GraphViz package mentioned above installed on your system. The 4179`--graph-file' option can be used to write a `dot' graph specification 4180file that can be processed by the `dot' or `dotty' commands that come 4181with GraphViz. The resulting graphs will show the relationships 4182between each function, its parents and its children, and will also show 4183the number of bytes that were allocated along the edges of the call 4184graph, but this can be changed to the number of calls if the `--counts' 4185option is used(3). A call graph showing unfreed memory instead of 4186allocated memory can be generated by adding the `--leaks' option. The 4187HTML, DVI, postscript and PDF versions of this manual contain graphical 4188examples of these options. 4189 4190 As a final demonstration of mpatrol's profiling features we will 4191attempt to profile a real application in order to see where the memory 4192allocations come from. Since all of the following steps were performed 4193on a Solaris machine, the `--dynamic' option of the `mpatrol' command 4194was used to allow us to replace the system memory allocation routines 4195with mpatrol's routines without requiring a relink. It also means that 4196we can profile all of the child processes that were created by the 4197application as well. 4198 4199 The application that we are going to profile is the GNU C compiler, 4200`gcc' (version 2.95.2), which is quite a complicated and large program. 4201The actual `gcc' command is really the compiler driver which invokes the 4202C preprocessor followed by the compiler, the assembler, the prelinker 4203and finally the linker (well, it does in this example). On Solaris, the 4204`gcc' distribution uses the system assembler and linker which come with 4205no symbol tables in their executable files so we will not be profiling 4206them. 4207 4208 For the purpose of this demonstration we will only be looking at the 4209graph files produced by the `--graph-file' option of the `mprof' 4210command, but ordinarily you would want to look at the tables that 4211`mprof' produces as well. All of the command line examples use the 4212`bash' shell but in most cases these will work in other shells with a 4213minimal amount of changes. 4214 4215 We will use `tests/profile/test2.c' as the source file to compile 4216with `gcc' and we'll turn on optimisation in order to cause `gcc' to 4217allocate a bit more memory than it would normally. Note that use is 4218also made of the format string feature of the `--log-file' and 4219`--prof-file' options so that it is clear which mpatrol log and 4220profiling output files belong to which processes. 4221 4222 bash$ mpatrol --dynamic --log-file=%p.log --prof-file=%p.out 4223 --prof gcc -O -o test2 test2.c 4224 bash$ ls *.log *.out 4225 as.log cc1.out cpp.log gcc.out 4226 as.out collect2.log cpp.out ld.log 4227 cc1.log collect2.out gcc.log ld.out 4228 4229 As mentioned above, we're not interested in the mpatrol log and 4230profiling output files for `as' and `ld' so we'll delete them. We can 4231now use `mprof' to create graph specification files for each of the 4232profiling output files produced. You can find these graph 4233specification files and the profiling output files used to generate 4234them in the `extra' directory in the mpatrol distribution. 4235 4236 bash$ rm as.log as.out ld.log ld.out 4237 bash$ ls *.out 4238 cc1.out collect2.out cpp.out gcc.out 4239 bash$ for file in *.out 4240 > do 4241 > mprof --graph-file=`basename $file .out`.dot $file 4242 > done >/dev/null 4243 bash$ ls *.dot 4244 cc1.dot collect2.dot cpp.dot gcc.dot 4245 4246 The graph specification files that have now been produced can be 4247viewed and manipulated with the `dotty' command, or they can be 4248converted to various image formats with the `dot' command. However, 4249this presumes that you already have the GraphViz graph visualisation 4250package installed. If you have then you can convert the graph 4251specification files to GIF and postscript images using the following 4252commands. If not, you can still view the graphs produced in the HTML, 4253DVI, postscript and PDF versions of this manual, or you can look at the 4254relevant files in the `doc/images' directory in the mpatrol 4255distribution. 4256 4257 bash$ dot -Tgif -Gsize="6,3" -Gratio=fill -o gcc.gif gcc.dot 4258 bash$ dot -Tgif -Gsize="6,3" -Gratio=fill -o cpp.gif cpp.dot 4259 bash$ dot -Tgif -Gsize="7,4" -Gratio=fill -o cc1.gif cc1.dot 4260 bash$ dot -Tgif -Gsize="4,3" -Gratio=fill -o collect2.gif collect2.dot 4261 bash$ dot -Tps -Gsize="6,3" -Gratio=fill -o gcc.ps gcc.dot 4262 bash$ dot -Tps -Gsize="6,3" -Gratio=fill -o cpp.ps cpp.dot 4263 bash$ dot -Tps -Gsize="9,6" -Gratio=fill -Grotate=90 -o cc1.ps cc1.dot 4264 bash$ dot -Tps -Gsize="4,3" -Gratio=fill -o collect2.ps collect2.dot 4265 4266 Although `mprof' does not currently offer this facility, a small tool 4267called `profdiff' which reports differences between two mpatrol 4268profiling output files can be downloaded from 4269`http://www.cbmamiga.demon.co.uk/mpatrol/patches/mpatrol_patch3.tar.gz'. 4270 4271 Much of the functionality of this implementation of memory 4272allocation profiling is based upon `mprof' by Benjamin Zorn and Paul 4273Hilfinger, which was written as a research project and ran on MIPS, 4274SPARC and VAX machines. However, the profiling output files are 4275incompatible, the tables displayed have a different format, and the way 4276they are implemented is entirely different. 4277 4278 ---------- Footnotes ---------- 4279 4280 (1) The `--call-graph' option is only needed to display the 4281allocation call graph table, which is not normally displayed by default. 4282 4283 (2) If no symbols could be read from the program's executable file, 4284or if the corresponding symbol could not be determined, then the 4285function names will be replaced with the code addresses at which the 4286calls took place. 4287 4288 (3) Cycles in the graph are marked by dashed lines along the 4289relevant edges instead of solid lines. 4290 4291 4292File: mpatrol.info, Node: Tracing, Next: Heap corruption, Prev: Profiling, Up: Top 4293 4294Tracing 4295******* 4296 4297 In addition to profiling, the mpatrol library also has the 4298capability to concisely trace the details of every dynamic memory 4299allocation, reallocation and deallocation over the lifetime of any 4300program that it was linked and run with. This information can then be 4301used to calculate trends in a program's memory allocation behaviour and 4302provide details on the lifetimes of memory allocations. In contrast to 4303profiling, it can also be used to display a program's memory allocation 4304behaviour in real-time, along with some useful information that can be 4305displayed in graphical or tabular form. 4306 4307 Only allocations, reallocations and deallocations are recorded. The 4308intention of tracing is to gather concise details about each memory 4309allocation event rather than complete information about some or all 4310memory allocations. As a result, the mpatrol log files and profiling 4311output files contain more detailed information about individual memory 4312allocations, whereas the tracing output files contain a broader view of 4313allocation behaviour throughout the entire program. 4314 4315 Memory allocation tracing is disabled by default, but can be enabled 4316using the `TRACE' option. This writes all of the tracing data to a 4317file called `mpatrol.trace' in the current directory at the end of 4318program execution, but the name of this file can be changed using the 4319`TRACEFILE' option and the default directory in which to place these 4320files can be changed by setting the `TRACEDIR' environment variable. 4321 4322 The `mptrace' command is a tool designed to read a tracing output 4323file produced by the mpatrol library and display the tracing 4324information that was obtained. The tracing information is a concise 4325encoded trace of all of the memory allocation events that occurred 4326during a program's execution, and can be decoded into tabular or 4327graphical form, along with any relevant statistics that can be 4328calculated. 4329 4330 The `mptrace' command also attempts to calculate the endianness of 4331the processor that produced the tracing output file and reads the file 4332accordingly. This means that it is possible to use `mptrace' on a 4333SPARC machine to read a tracing output file that was produced on an 4334Intel 80x86 machine, for example. However, this will only work if the 4335processor that produced the tracing output file has the same word size 4336as the processor that is running the `mptrace' command. For example, 4337reading a 64-bit tracing output file on a 32-bit machine will not work. 4338 4339 In addition, the tracing output file also contains the version 4340number of the mpatrol library which produced it. If the major version 4341number that is embedded in the tracing output file is newer that the 4342version of mpatrol that `mptrace' came with then `mptrace' will refuse 4343to read the file. You should download the latest version of mpatrol in 4344that case. The reason for storing the version number is so that the 4345format of the tracing output file can change between releases of 4346mpatrol, but also allow `mptrace' to cope with older versions. 4347 4348 Along with the usual `--help' and `--version' options, the `mptrace' 4349command accepts several other options and takes one optional argument 4350which must be a valid mpatrol tracing output filename but if it is 4351omitted then it will use `mpatrol.trace' as the name of the file to use. 4352If the filename argument is given as `-' then the standard input file 4353stream will be used as the tracing output file. 4354 4355 Normally, the `mptrace' command will simply read in the tracing 4356output file and display any statistics it has gathered. However, it 4357can also be instructed to display a tracing table which displays useful 4358details for every event in the tracing output file. The tracing table 4359can be displayed with the `--verbose' option. If the mpatrol library 4360was able to obtain source-level information for one or more memory 4361events then this can be displayed in the tracing table by adding the 4362`--source' option. 4363 4364 A C source file containing a trace-driven memory allocation 4365simulation program can be written with the `--sim-file' option. This 4366program will have the identical memory allocation behaviour to the 4367program which produced the original trace file. This option can be 4368useful to use if you wish to determine which malloc library is most 4369suitable to use for a specific application. 4370 4371 A trace file in Heap Allocation Trace Format (HATF) can also be 4372written out by the `mptrace' command by using the `--hatf-file' option. 4373It takes the name of the HATF trace file to be written as an argument 4374and writes out the HATF version of the mpatrol tracing output file 4375given as input when it is being processed. The HATF file format is an 4376attempt to standardise trace file formats for memory allocation 4377tracing, and is being developed by Benjamin Zorn, Richard Jones and 4378Trishul Chilimbi. There is a HATF DTD located in the `extra' directory 4379in the mpatrol distribution. 4380 4381 The `mptrace' command will normally be built with GUI(1) support on 4382UNIX platforms that are running X Windows. This means that a graphical 4383memory map display of the heap will be shown in a window every time 4384`mptrace' is run with the `--gui' option. This display is updated 4385every time a new event is read from the tracing output file and by 4386default uses the colour red for internal heap memory (used by the 4387mpatrol library), blue for unallocated heap memory, black for allocated 4388memory and white for free memory. Options exist to change this colour 4389scheme, as well as the dimensions of the drawing area and the window. 4390 4391 By default, it is assumed that the start address of the first event 4392that appears in the tracing output file is the base address of the 4393memory map displayed in the window. If the heap grows downwards then 4394this assumption will be incorrect (since nothing will be displayed) and 4395so the `--base' option must be used to specify a reasonable lower bound 4396for the final memory map. In addition, the visible address space 4397displayed in the memory map is fixed to a certain size (4 megabytes by 4398default), but this can be changed with the `--space' option. A small 4399delay can also be added after drawing each memory allocation event 4400through the use of the `--delay' option. 4401 4402 The following options are specific to the GUI version of `mptrace' 4403and are read by the X command line parser rather than directly by 4404`mptrace'. As a result they are parsed according to X toolkit rules 4405and do not appear in the quick-reference option summary produced by the 4406`--help' option. The application class for setting `mptrace' X 4407resources is called `MPTrace'. 4408 4409`--alloc' <COLOUR> 4410 Specifies the colour to use for displaying allocated memory. The 4411 default colour is `black'. 4412 4413`--base' <ADDRESS> 4414 Specifies the base address of the visible address space displayed 4415 in the memory map. The default address is calculated at run-time 4416 from the start address of the first memory allocation event in the 4417 tracing output file. 4418 4419`--delay' <LENGTH> 4420 Specifies that a small delay of a certain length should be added 4421 after drawing each memory allocation event. The delay does not 4422 correspond to a specific unit of time, but experimentation with 4423 the length should yield satisfactory results. The default delay 4424 is `0'. 4425 4426`--free' <COLOUR> 4427 Specifies the colour to use for displaying free memory. The 4428 default colour is `white'. 4429 4430`--height' <SIZE> 4431 Specifies the height (in pixels) of the drawing area. The default 4432 height is `512'. 4433 4434`--internal' <COLOUR> 4435 Specifies the colour to use for displaying internal heap memory. 4436 The default colour is `red'. 4437 4438`--space' <SIZE> 4439 Specifies the size (in megabytes) of the visible address space 4440 displayed in the memory map. The default size is `4'. 4441 4442`--unalloc' <COLOUR> 4443 Specifies the colour to use for displaying unallocated heap 4444 memory. The default colour is `blue'. 4445 4446`--view-height' <SIZE> 4447 Specifies the height (in pixels) of the window. The default 4448 height is `256'. 4449 4450`--view-width' <SIZE> 4451 Specifies the width (in pixels) of the window. The default width 4452 is `256'. 4453 4454`--width' <SIZE> 4455 Specifies the width (in pixels) of the drawing area. The default 4456 width is `512'. 4457 4458 We'll now look at an example of using the mpatrol library to trace 4459the dynamic memory allocations in a program. As with the previous 4460chapter we will attempt to trace a real application in order to examine 4461its memory allocation behaviour. Since all of the following steps were 4462performed on a Solaris machine, the `--dynamic' option of the `mpatrol' 4463command was used to allow us to replace the system memory allocation 4464routines with mpatrol's routines without requiring a relink. It also 4465means that we can trace all of the child processes that were created by 4466the application as well. 4467 4468 The application that we are going to trace is the GNU C compiler, as 4469before, and we will discard the tracing information generated for the 4470assembler and linker. All of the command line examples use the `bash' 4471shell but in most cases these will work in other shells with a minimal 4472amount of changes. 4473 4474 We will use `tests/profile/test2.c' as the source file to compile 4475with `gcc' and we'll turn on optimisation in order to cause `gcc' to 4476allocate a bit more memory than it would normally. Note that use is 4477also made of the format string feature of the `--log-file' and 4478`--trace-file' options so that it is clear which mpatrol log and tracing 4479output files belong to which processes. 4480 4481 bash$ mpatrol --dynamic --log-file=%p.log --trace-file=%p.trace 4482 --trace gcc -O -o test2 test2.c 4483 bash$ ls *.log *.trace 4484 as.log cc1.trace cpp.log gcc.trace 4485 as.trace collect2.log cpp.trace ld.log 4486 cc1.log collect2.trace gcc.log ld.trace 4487 4488 As mentioned above, we're not interested in the mpatrol log and 4489tracing output files for `as' and `ld' so we'll delete them. We can 4490now use `mptrace' to decode each of the tracing output files produced 4491and write their contents in tabular form to the standard output file 4492stream, which can be redirected to a file for later viewing. You can 4493find these tracing output files in the `extra' directory in the mpatrol 4494distribution. 4495 4496 Note that both the tracing files mentioned above and the examples 4497below treat reallocations as a deallocation followed by an allocation. 4498This was the behaviour in older versions of the mpatrol library and I 4499haven't bothered to update the files. However, it shouldn't affect the 4500final outcome in any way. In addition, as the `mpatrol.h' header file 4501was not included by any of the source files that comprise the compiler 4502and its toolset, there was no source-level information for memory 4503events. If there was, the `--source' option could have been used to 4504display it. 4505 4506 bash$ rm as.log as.trace ld.log ld.trace 4507 bash$ ls *.trace 4508 cc1.trace collect2.trace cpp.trace gcc.trace 4509 bash$ for file in *.trace 4510 > do 4511 > mptrace --verbose $file >`basename $file .trace`.res 4512 > done 4513 bash$ ls *.res 4514 cc1.res collect2.res cpp.res gcc.res 4515 4516 For the purposes of this example we will only be looking at the 4517tracing results for the `cc1' compiler which are now decoded in the 4518file `cc1.res'. If you examine this file you will see something 4519similar to the following. Note that the `...' marks text that has been 4520removed. 4521 4522 event type index allocation size life count bytes 4523 ------ ------ ------ ---------- -------- ------ ------ -------- 4524 internal 0x0024E000 32768 4525 internal 0x00256000 32768 4526 internal 0x0025E000 32768 4527 reserve 0x00266000 8192 4528 internal 0x00268000 32768 4529 internal 0x00270000 32768 4530 internal 0x00278000 32768 4531 internal 0x00280000 32768 4532 internal 0x00288000 32768 4533 internal 0x00290000 32768 4534 ... 4535 reserve 0x00308000 16384 4536 1 alloc 19 0x00266568 4072 1 4072 4537 2 alloc 21 0x0030A008 4072 2 8144 4538 3 alloc 22 0x0030AFF0 4072 3 12216 4539 reserve 0x0030C000 8192 4540 4 alloc 23 0x0030BFD8 4072 4 16288 4541 5 alloc 24 0x0030CFC0 4072 5 20360 4542 reserve 0x0030E000 8192 4543 6 alloc 25 0x0030DFA8 4072 6 24432 4544 7 alloc 26 0x00267550 42 7 24474 4545 ... 4546 1712 free 650 0x00373FF0 4072 827 398 321191 4547 1713 free 649 0x00376FA8 4072 829 397 317119 4548 1714 alloc 1074 0x00376FA8 4072 398 321191 4549 1715 free 233 0x0031ED18 8200 1498 397 312991 4550 1716 free 234 0x00320D20 8200 1498 396 304791 4551 1717 free 299 0x00355CC8 620 1426 395 304171 4552 1718 free 655 0x00353A28 1016 823 394 303155 4553 1719 free 303 0x0035E000 5096 1424 393 298059 4554 1720 free 653 0x00354E60 152 827 392 297907 4555 1721 free 654 0x00354EF8 152 827 391 297755 4556 4557 memory allocation tracing statistics 4558 ------------------------------------ 4559 allocated: 1056 (540776 bytes) 4560 freed: 665 (243021 bytes) 4561 unfreed: 391 (297755 bytes) 4562 peak: 489 (375169 bytes) 4563 reserved: 48 (409600 bytes) 4564 internal: 27 (884736 bytes) 4565 total: 75 (1294336 bytes) 4566 4567 smallest size: 3 bytes 4568 largest size: 8200 bytes 4569 average size: 512 bytes 4570 4571 There are eight different columns of data displayed by the `mptrace' 4572command when it decodes the tracing output file and displays it in 4573tabular format with the `--verbose' option. Here is an explanation for 4574each of them. 4575 4576`event' 4577 This contains the event number (or time line) for each memory 4578 allocation, reallocation or deallocation (heap reservations are 4579 not considered events for this purpose). Each memory allocation, 4580 reallocation or deallocation increases the current event number, 4581 and this information is used to calculate the lifetime of a heap 4582 allocation. 4583 4584`type' 4585 This contains the event type for each entry in the tracing output 4586 file. Memory allocations, reallocations and deallocations are 4587 represented by `alloc', `realloc' and `free' respectively. Normal 4588 heap reservations (that will be used for memory allocations) are 4589 represented by `reserve', while internal heap reservations (for 4590 use by the mpatrol library itself) are represented by `internal'. 4591 4592`index' 4593 This contains the allocation index that is used by the mpatrol 4594 library to keep track of each unique memory allocation, and 4595 corresponds directly to any memory allocations listed in the log 4596 file. In older tracing output files, memory allocation events 4597 that reuse allocation indices represent a reallocation of the 4598 original allocation. 4599 4600`allocation' 4601 This contains the start address of the memory allocation. 4602 4603`size' 4604 This contains the size (in bytes) of the memory allocation. 4605 4606`life' 4607 This contains the lifetime of a memory allocation and is displayed 4608 when it is is freed. It is simply the difference between the 4609 current event number and the event number at which the original 4610 allocation took place, but is useful for working out how long a 4611 memory allocation is valid throughout a program's execution. If a 4612 memory allocation is reallocated, its lifetime will be calculated 4613 from the original time of allocation, _not_ the point at which it 4614 was reallocated. 4615 4616`count' 4617 This contains a running total of the number of memory allocations 4618 currently in use. The total is calculated after processing the 4619 current event. 4620 4621`bytes' 4622 This contains a running total of the memory used by the current 4623 memory allocations. The total is calculated after processing the 4624 current event. 4625 4626 The first few entries in the table show that the mpatrol library 4627started by allocating memory from the heap for its own purposes before 4628reserving 8192 bytes for the memory allocations made by the object file 4629access library for reading the symbols from the executable file and 4630shared libraries(2). Most of the further internal heap reservation 4631events are due to the mpatrol library having to store details for all 4632of the relevant symbols that it could read at program startup. The 4633more symbols that there are, the more memory that must be used to store 4634them. Note that the heap reservation events are not really relevant to 4635the analysis of the program's memory allocations but they are used when 4636displaying the heap graphically. 4637 4638 The first few memory allocation events in the table show that 4639several memory allocations of 4072 bytes are being made along with 4640several more heap reservations that are needed to store them. The last 4641events in the table are mainly all deallocation events of allocations 4642that were made quite early on in the program. The lifetime information 4643for these events shows that some of these allocations were made very 4644near the beginning of the program, while the others were made near the 4645middle. None of them were very big and so would not be occupying much 4646memory. 4647 4648 The statistics that were gathered from the tracing output file are 4649displayed after the tracing table. The first group of entries 4650summarise the heap memory that was used, with the `allocated', `freed' 4651and `unfreed' fields showing the total number of memory allocations 4652that were made, the total number of memory allocations that were freed, 4653and the total number of unfreed memory allocations respectively. The 4654`peak' field shows the highest number of memory allocations (and total 4655number of bytes) that were in use at any one time. The `reserved' and 4656`internal' fields show the total number of pages reserved from the 4657system heap for user allocations and internal allocations respectively, 4658and the `total' field shows the total number of pages that were used 4659from the system heap. 4660 4661 The `smallest size' and `largest size' fields indicate the sizes of 4662the smallest memory allocation and the largest memory allocation 4663respectively. The `average size' field shows the mean number of bytes 4664that was allocated between each of the memory allocations. 4665 4666 If you were running a GUI version of `mptrace', information about 4667all of these events can be displayed in graphical form inside a window 4668if the `--gui' option is used. The HTML, DVI, postscript and PDF 4669versions of this manual contain a screenshot of the `mptrace' display 4670window when it is run with the `--gui' option and `cc1.trace' as input. 4671 4672 Unlike memory allocation profiling which summarises all of the 4673accumulated data, it is possible to trace memory allocation events in 4674real-time as the program runs. This can currently be done on UNIX 4675platforms by piping the tracing output file from the program being run 4676to the `mptrace' command, which can be achieved in several ways 4677depending on the UNIX system that you are using. Both of the following 4678methods are equivalent, where `testprog' is the name of the program 4679that is being traced (and has previously been linked with the mpatrol 4680library). 4681 4682 # This method specifies the standard output file stream as the 4683 # destination for the tracing output file and then runs both 4684 # commands in a shell command pipe. This has a disadvantage in 4685 # that testprog must not write anything to stdout since that would 4686 # be written out to the tracing output file. If stdout is not 4687 # suitable then stderr could be used instead if you redirect it. 4688 4689 bash$ mpatrol --trace-file=stdout --trace ./testprog | mptrace --verbose - 4690 4691 # This method creates a named pipe called myfifo (but it could be 4692 # called anything) and runs the program being traced and the mptrace 4693 # command separately (perhaps in two separate windows). If the 4694 # mkfifo command is not available on your system then try mknod. 4695 4696 bash$ mkfifo myfifo 4697 bash$ mpatrol --trace-file=myfifo --trace ./testprog & 4698 bash$ mptrace --verbose myfifo 4699 4700 The idea for graphically displaying a memory map of the heap comes 4701from the `xmem' tool supplied with the University of Toronto Computer 4702Systems Research Institute malloc library, written by Mark Moraes. 4703However, the documentation for that tool remarks that it was written as 4704a quick and dirty hack. The `mptrace' command is hopefully more stable 4705and contains a lot more functionality. 4706 4707 The mpatrol library can also generate trace files in a format that 4708is compatible with the GNU `mtrace()' option. The code to do this is 4709built on top of the mpatrol library and is in `tools/mtrace.c' and 4710`tools/mtrace.h'. Such trace files can then be processed by the GNU 4711`mtrace' command. The `tools/mgauge.c' and `tools/mgauge.h' files in 4712the same directory can be used to implement an allocated memory gauge 4713which updates in real-time in a terminal window. This can be used as 4714an alternative to the window used by the `mptrace' command's `--gui' 4715option for a simpler display. 4716 4717 ---------- Footnotes ---------- 4718 4719 (1) Graphical User Interface. 4720 4721 (2) The actual allocation events from this do not appear since they 4722were internal memory allocations. 4723 4724 4725File: mpatrol.info, Node: Heap corruption, Next: Memory leaks, Prev: Tracing, Up: Top 4726 4727Heap corruption 4728*************** 4729 4730 There can be many causes of heap corruption in a program and there 4731can be many forms in which it can appear. This chapter attempts to 4732describe the most appropriate ways to narrow down and remove the causes 4733of the most common forms of heap corruption. Note that errors such as 4734freeing an allocated block twice are not considered in this chapter 4735even though they would result in heap corruption in a normal malloc 4736library -- the mpatrol library catches these special cases so you know 4737exactly where they occur. 4738 4739 The three forms of errors we are going to look at are heap 4740corruption in free memory blocks, freed memory blocks and overflow 4741buffers. As you will soon see, the same piece of faulty code can 4742produce any one of these errors depending on which mpatrol library 4743options you use. The following discussion assumes that you have run 4744your program with the mpatrol library and you get an `ALLOVF', 4745`FRDCOR', `FRDOVF' or `FRECOR' error in the mpatrol log file when your 4746program terminates. It also assumes that you haven't set the 4747`MPATROL_OPTIONS' environment variable yet. 4748 4749 By default, the only times the mpatrol library will check the heap 4750for memory corruption are when it terminates or when `__mp_check()' is 4751called (but the latter won't be happening since you won't have modified 4752your program yet). This isn't good enough for errors such as these so 4753we need to instruct it to make checks whenever an mpatrol library 4754function is called. The `CHECK' option controls when such automated 4755checks occur, and this can normally be set to `CHECK=-' to check the 4756heap whenever a call to an mpatrol library function is made. 4757 4758 However, in programs which take a long time to execute, or programs 4759which make a large number of memory allocations, this can slow the 4760program down quite a bit so you might want to try the optional `/freq' 4761argument to the `CHECK' option. This simply instructs the mpatrol 4762library to make the checks every _freq_ calls to the mpatrol library 4763functions rather than every call. For example, `CHECK=/10' will make 4764the checks every 10 calls, which will reduce the slowdown in the 4765program but will still help narrow down where the heap corruption is 4766occurring. 4767 4768 We'll use the following program as a running example for the 4769discussions below, although you'll probably be following them using 4770your program instead of this one. It contains a small bug that doesn't 4771normally show up when using the system C library but causes a `FRECOR' 4772error when linked with mpatrol. 4773 4774 1 /* 4775 2 * A program which causes heap corruption. 4776 3 */ 4777 4778 4779 6 #include <stdio.h> 4780 7 #include "mpatrol.h" 4781 4782 4783 10 int main(void) 4784 11 { 4785 12 char *p[128]; 4786 13 size_t i; 4787 4788 15 for (i = 0; i < 128; i++) 4789 16 { 4790 17 if ((p[i] = (char *) malloc(9)) == NULL) 4791 18 { 4792 19 fputs("out of memory\n", stderr); 4793 20 exit(EXIT_FAILURE); 4794 21 } 4795 22 sprintf(p[i], "test%lu", i * 100); 4796 23 puts(p[i]); 4797 24 free(p[i]); 4798 25 } 4799 26 return EXIT_SUCCESS; 4800 27 } 4801 4802 We get the following error in the mpatrol log file when we run with 4803the above example linked to the mpatrol library. The error occurs when 4804the program returns from `main()' since that is when the mpatrol 4805library is terminating. 4806 4807 ERROR: [FRECOR]: free memory corruption at 0x0002A571 4808 0x0002A571 00555555 555555 .UUUUUU 4809 4810 If we run with the `CHECK=-' option then the above error occurs at 4811line 24 when the variable `i' is 100, which is slightly better since 4812we've narrowed down where the fault is. 4813 4814 Assuming all goes well, your program should now also terminate at an 4815earlier point, with the mpatrol library still reporting the same heap 4816corruption error in the log file. If not, it could be that the heap is 4817being corrupted after the last call to the mpatrol library is made, or 4818if you get a different error then the original heap corruption might 4819have been as a result of the earlier error. In either case you can 4820still proceed with the following instructions. 4821 4822 If you look at the summary of statistics that were produced in the 4823mpatrol log file before the error was displayed you will see an entry 4824for `allocation count'. The number following it is the number of 4825memory allocations that were made before the error occurred. Remember 4826this number because you can use this information with the `CHECK' 4827option so that checks for heap corruption are only made after a certain 4828number of memory allocations. However, you'll probably want to 4829subtract a few allocations just to be sure (or in case you are running 4830a multithreaded program that does not produce the same allocation count 4831every time it is run). That way, you don't need to check the entire 4832heap. For example, if the allocation count was 178, try setting the 4833`CHECK=170-190' option so that your program will run at a reasonable 4834speed up to that point (although make sure that it still gives the same 4835error at the same point). There is nothing worse than debugging a 4836problem that takes forever to reproduce. 4837 4838 In our example, the allocation count given is 123 (excerpt given 4839below) and running with `CHECK=120-125' gives the same behaviour as 4840when we ran with `CHECK=-' (except that we got to the error slightly 4841faster). 4842 4843 ... 4844 4845 symbols read: 5059 4846 autosave count: 0 4847 freed queue size: 0 4848 allocation count: 123 4849 allocation peak: 8 (11117 bytes) 4850 allocation limit: 0 bytes 4851 allocated blocks: 7 (1374 bytes) 4852 4853 ... 4854 4855 So we now have the allocation index of the last successful memory 4856allocation before the heap corruption occurred, and we can safely run 4857the program without performing heap checks up to that point. If the 4858error was not `FRECOR' then there will also be information displayed in 4859the mpatrol log file about the associated memory allocation that was 4860corrupted. If the error was `FRECOR' then quickly try to see if you 4861can convert it to a `FRDCOR' error or a `FRDOVF' error by also running 4862with the `NOFREE' option. You may have to use the relevant allocation 4863index as an argument to the `NOFREE' option just in case it was the 4864very first memory allocation that was freed and corrupted, but remember 4865that the `NOFREE' option may cause your program to use up a lot more 4866memory and so it might be unfeasible to use. Running with the 4867`NOFREE=123' option in our example has no effect. 4868 4869 One of the most common causes of heap corruption is to erroneously 4870write beyond the bounds of a memory allocation. This can corrupt the 4871bytes directly before and/or after the allocated bytes and can be 4872detected by placing overflow buffers on either side of the memory 4873allocation with the `OFLOWSIZE' option. By default, the mpatrol 4874library does not make use of overflow buffers so you have to explicitly 4875turn them on, giving the number of bytes to use for each overflow 4876buffer (which must a be power of two) as the argument to the `OFLOWSIZE' 4877option. In our example, if we use the `OFLOWSIZE=4' option, the 4878`FRECOR' error turns into an `ALLOVF' error, thus providing us with 4879more information (and also that the heap corruption is due to a write 4880beyond the end of a memory allocation). 4881 4882 ERROR: [ALLOVF]: allocation 0x0002A5A0 has a corrupted overflow buffer at 4883 0x0002A5A9 4884 0x0002A5A9 00AAAAAA .��� 4885 4886 0x0002A5A0 (9 bytes) {malloc:123:0} [main|test.c|17] 4887 0x0001372C main+88 4888 0x000135A4 _start+100 4889 4890 Sometimes it's not just a immediate overflow that can occur. For 4891example, if not enough memory has been allocated for a structure 4892variable and then the last field of the structure is assigned to, the 4893memory corruption may occur much further away than the few bytes 4894surrounding the allocation. In this case it may be useful to try 4895varying the argument given to the `OFLOWSIZE' option since it is 4896possible to convert otherwise unhelpful `FRECOR' errors into `ALLOVF', 4897`FRDCOR' or `FRDOVF' errors which describe the memory allocation that 4898was affected. Also, depending on the bytes that are being written to 4899corrupt the heap, you may find it helpful to change the values of the 4900free bytes and overflow bytes that the mpatrol library uses to perform 4901heap integrity checks, just in case there are illegal bytes being 4902written that are going unnoticed when the heap is being checked. In 4903our example, if the `OFLOWBYTE=0' option is used then the heap 4904corruption is hidden completely and we don't get an error at all! 4905 4906 Hopefully, we now know as much as possible about where the heap 4907corruption is happening (i.e. the details of the allocated or freed 4908memory block that is affected, or the free memory block if we are 4909unlucky) and also when it is happening (i.e. after which allocation 4910index). We now have several choices on how to narrow the problem down 4911to a specific source line. 4912 4913 On systems with virtual memory we can make use of the `PAGEALLOC' 4914option in order to write-protect a page of virtual memory on either 4915side of each memory allocation. This option takes up a lot more memory 4916since each memory allocation will occupy at least 3 pages of virtual 4917memory no matter how small it is, and on systems with a page size of 49188192 bytes that equates to a minimum 24 kilobytes of memory per 4919allocation! However, if that is still feasible for the particular 4920program that is causing the heap corruption then we can proceed by 4921first setting the `PAGEALLOC=LOWER' option. That aligns each memory 4922allocation to a page boundary so that any underwrites occurring before 4923the allocation will be trapped and cause the program to crash. This 4924can be caught in a debugger which will show the exact source line that 4925attempted to perform the illegal write to memory (assuming it is a 4926symbolic debugger and the program was compiled with debugging 4927information). 4928 4929 In our example, running with this option doesn't provide us with any 4930more information since the heap corruption was occurring beyond the end 4931of the memory allocation and not before the start. In this case we 4932need to use the `PAGEALLOC=UPPER' option to align the end of each 4933memory allocation to a page boundary so that any overwrites occurring 4934after the allocation will be trapped and cause the program to crash. 4935Unfortunately, using this option still doesn't help in our example, so 4936what's wrong? 4937 4938 The mpatrol library must align each new general-purpose memory 4939allocation to an address that allows the processor to access the 4940datatypes that may be stored there. This is typically 4 bytes on 494132-bit processors and 8 bytes on 64-bit processors, but a few processor 4942architectures (such as the Intel x86) allow the processor to read 4943misaligned data at a performance cost. This is in direct conflict with 4944the `PAGEALLOC=UPPER' option, which would like to align the end of each 4945memory allocation to a page boundary no matter what the size of the 4946allocation is. However, if we use the `DEFALIGN=1' option in our 4947example we can get the desired effect with the `PAGEALLOC=UPPER' option. 4948 4949 ERROR: [ILLMEM]: illegal memory access at address 0x00052000 4950 0x00051FF7 (9 bytes) {malloc:123:0} [main|test.c|17] 4951 0x0001372C main+88 4952 0x000135A4 _start+100 4953 4954 call stack 4955 0x7FA808E8 sprintf+64 4956 0x000137B4 main+224 4957 0x000135A4 _start+100 4958 4959 Running this in a debugger shows that the failure occurs at line 22 4960in our example since we didn't allocate enough memory at line 17. We 4961can also achieve the same effect on systems that support software 4962watchpoints by using the `OFLOWWATCH' option. This uses the same 4963amount of memory as the `OFLOWSIZE' option but can run very slowly as 4964every single memory access is checked by the system. Note that the 4965`FRDCOR' and `FRECOR' errors do not occur when using the `PAGEALLOC' 4966option since they will become illegal memory accesses instead. 4967 4968 If you don't have the luxury of being able to use the mpatrol 4969options that take advantage of virtual memory protection, you can still 4970use more traditional means of finding the error. 4971 4972 The chapter that describes how to use mpatrol (*note Using 4973mpatrol::) contains a section on how to pause at specific memory 4974allocation events in a debugger (*note Using with a debugger::). Since 4975we know what the allocation index of the last successful allocation was 4976we can use the debugger to set a watchpoint on the address of the 4977memory corruption so that it can trap the instruction that changes it. 4978Doing this is effectively the same as using the `PAGEALLOC' or 4979`OFLOWWATCH' options. There is a detailed tutorial on how to do this 4980in GDB in the aforementioned section of the manual. 4981 4982 If the debugger option isn't available to you either then you can 4983try locating the problem by modifying your code. You should know where 4984the last successful memory allocation was made from the steps taken at 4985the start of this chapter. Using this knowledge, you should be able to 4986work out the range of code that is causing the heap corruption. Then 4987you can add calls to `__mp_check()' at strategic points within that 4988range so that you can narrow down where the heap corruption is coming 4989from. If you display a unique message after each call to 4990`__mp_check()' then you should be able to narrow it down quite quickly 4991by monitoring which messages get displayed. 4992 4993 You might also find it helpful to make calls to `__mp_memorymap()' 4994so that you can keep track of the location of each memory allocation in 4995the heap, and so that you can tell which allocations neighbour each 4996other. Turning on the `LOGMEMORY' option with the `__mp_setoption()' 4997function might also help you see what is going on if there are a lot of 4998calls to the memory operation functions. Finally, if you are using the 4999GNU compiler then the `-fcheck-memory-usage' option might come in handy 5000if you can recompile the source files that you think might contain the 5001problem. However, the error may be hidden behind a call to a library 5002function that is not compiled with that option, as is the case with our 5003example. 5004 5005 Another slightly less common problem associated with heap corruption 5006is when the contents of a memory allocation have been overwritten 5007unexpectedly but do not overflow its boundaries. This is not a misuse 5008of the heap and so mpatrol will not report any errors or warnings, but 5009it may be an error in the user's code. The heapdiff tool (*note 5010heapdiff::) provided in libmptools has an option called `HD_CONTENTS' 5011which allows the entire _live_ contents of the heap to be written to 5012disk and then compared when `heapdiffend()' is called. Every single 5013difference (at the byte level) in each memory allocation is reported 5014and this information can be extremely useful in narrowing down heap 5015corruption. However, the `HD_CONTENTS' option will require a lot of 5016disk space if the heap is very large. 5017 5018 To conclude, the mpatrol library contains a wide variety of options 5019and functions that you can add to your debugging toolkit, but only if 5020you know how to use them correctly. Hopefully, after reading this 5021chapter you will feel slightly more confident about knowing how to slay 5022those heap corruption demons. 5023 5024 5025File: mpatrol.info, Node: Memory leaks, Next: Improving performance, Prev: Heap corruption, Up: Top 5026 5027Memory leaks 5028************ 5029 5030 Memory leaks can be the bane of many a programmer and is the type of 5031error that can typically go unnoticed in simple test cases. It is 5032perhaps not until an application has been released to the customer and 5033is being run in real-life situations that memory leaks get noticed and 5034become a serious problem. Luckily the mpatrol library provides tools 5035that can quickly help detect, identify and remove such errors. Note 5036that it's probably a good idea to fix any warnings or errors that 5037appear in the mpatrol log file before starting to look at removing 5038memory leaks. 5039 5040 Surprisingly, there are no less than four different groups of 5041mpatrol library run-time options that you can use to detect memory 5042leaks in a program, all without having to change a single line of code! 5043They each employ different techniques in order to locate the unfreed 5044memory allocations at program termination and operate independently of 5045one another so that any combination of techniques can be used at any 5046one time. They also have differing levels of detail in the information 5047they provide, so which options you use will depend on what your 5048requirements are. 5049 5050 If you wish to see a summary of the memory leaks grouped together by 5051call site then the `PROF' or `LEAKTABLE' options are your best bet. The 5052output file produced by the `PROF' option can be displayed by the 5053`mprof' command, which will display a list of memory leaks as one of the 5054tables that it shows. Each entry in the memory leak table will 5055normally only show one level of stack depth from its call graph but 5056this can be changed with the `--stack-depth' option in the `mprof' 5057command. The table of memory leaks can also be written to a graph 5058specification file for later visualisation with a graph package. Using 5059the `PROF' option is probably the best way to summarise where memory 5060leaks occur in a program. 5061 5062 However, the `LEAKTABLE' option can generate similar information to 5063the `PROF' option in the mpatrol log file. The drawback to this option 5064is that the entries displayed will only ever show the immediate calling 5065functions and no call stack information, but in many cases this is good 5066enough. Another drawback to this option is that it is affected by 5067calls in the code to manipulate the leak table. However, if the calls 5068aren't there then that won't be an issue. The leak table should really 5069be used from within the source code (see below) but it can still 5070provide some useful information with the `LEAKTABLE' option. 5071 5072 The third option is the `SHOWUNFREED' option, which will show the 5073details of every unfreed memory allocation at the end of program 5074execution. No attempt is made to summarise them, but the full details 5075of each (including the call stack if available) are given. This option 5076is really only useful if there are a small number of unfreed memory 5077allocations when a program terminates, but it is invaluable if all of 5078the gory details are required. 5079 5080 The final group of options are the `LOGALLOCS', `LOGREALLOCS' and 5081`LOGFREES' options(1). In some situations a program will abort 5082abnormally before it can exit, in which case the `LEAKTABLE' and 5083`SHOWUNFREED' options will not display anything, and the `PROF' option 5084will not finish writing out the profiling output file unless you are 5085exceptionally lucky with the `AUTOSAVE' option. One can argue that you 5086should be looking for the cause of the error rather than memory leaks 5087in such a program, but it is still possible to detect the latter using 5088the aforementioned `LOG*' options and the `mleak' command. 5089 5090 The `mleak' command reads in an mpatrol log file, recording the 5091details of each logged memory allocation, reallocation or deallocation 5092and then writes out what the `SHOWUNFREED' option should have written 5093out at the end of the log file. It has a few limitations compared to 5094the `SHOWUNFREED' option, but the details of each unfreed memory 5095allocation that it writes out should be accurate, although only if the 5096logging information in the log file was complete and accurate as well. 5097 5098 Note that more information from the `SHOWUNFREED' and `LOG*' options 5099can be obtained by using the `USEDEBUG' option. This will attempt to 5100add missing source file and line number information to the details 5101recorded by these options in the mpatrol log file, but only if it is 5102supported by the particular system and object file format, and then 5103only if the program was compiled with debugging information from the 5104compiler. If the `USEDEBUG' option isn't supported then it might be 5105possible to use the `mpsym' command to postprocess the mpatrol log file 5106using a symbolic debugger to fill in such information. You may also 5107find that running the log file through a C++ encoded name demangler is 5108useful as well if your program contains C++ code. 5109 5110 Despite the plethora of automated features that the mpatrol library 5111has for detecting memory leaks, the most powerful method of narrowing 5112down such leaks is by modifying the source code. The mpatrol library 5113provides several functions that can be used to keep track of 5114differences in the heap between two or more points in a program's 5115execution -- such information can be invaluable when pinpointing where 5116a memory leak is coming from. 5117 5118 The first set of functions are based upon taking a snapshot of the 5119heap at a certain point and then walking the heap to examine the 5120differences at a later point. The `__mp_snapshot()' function returns 5121the current event identifier in the mpatrol library and the 5122`__mp_iterate()' function traverses the heap calling a user-defined 5123callback function for each memory allocation that has changed since a 5124particular event identifier. This is very useful for noting memory 5125allocations that have been made since a certain point in a program but 5126have not been freed when they were expected to. The heapdiff tool 5127(*note heapdiff::) provided in libmptools makes use of these functions 5128to provide an easy-to-use interface. 5129 5130 The mpatrol library also provides a leak table (*note Leak table::) 5131that can be manipulated at any point in a program for the purpose of 5132detecting changes in the heap. The `__mp_clearleaktable()' function 5133clears the leak table, while the `__mp_leaktable()' function writes the 5134contents of the leak table to the mpatrol log file. Automatic logging 5135of memory allocations, reallocations and deallocations can be turned on 5136and off using the `__mp_startleaktable()' and `__mp_stopleaktable()' 5137functions respectively. The main advantage to using the leak table 5138instead of the functions described in the previous paragraph is that it 5139can provide a summary of unfreed allocations rather than showing the 5140details of each one individually. It can also summarise freed 5141allocations without requiring the use of the `NOFREE' option. 5142 5143 Finally, you can indicate to the mpatrol library that a particular 5144memory allocation will remain allocated until program termination and 5145that it should not be treated as a memory leak. This can be done by 5146calling the `__mp_setmark()' function, and thereafter any attempt to 5147free the newly-marked allocation will result in an error, although 5148reallocating it is possible. It is normal in many programs to make 5149several initial memory allocations that will remain in use throughout 5150the program's lifetime. On most systems, such allocations will be 5151freed when the program terminates anyway so there will be no need to 5152free them explicitly. It is these allocations that should be marked so 5153as to prevent them showing up as memory leaks. 5154 5155 ---------- Footnotes ---------- 5156 5157 (1) Note that the `LOGMEMORY' option isn't listed which is why 5158`LOGALL' wasn't listed either. 5159 5160 5161File: mpatrol.info, Node: Improving performance, Next: How it works, Prev: Memory leaks, Up: Top 5162 5163Improving performance 5164********************* 5165 5166 Because of their need to cover every eventuality, malloc library 5167implementations are very general and most do their job well when you 5168consider what is thrown at them. However, your program may not be 5169performing as well as it should simply because there may be a more 5170efficient way of dealing with dynamic memory allocations. Indeed, 5171there may even be a more efficient malloc library available for you to 5172use. 5173 5174 If you need to allocate lots of blocks of the same size(1), but you 5175won't know the number of blocks you'll require until run-time then you 5176could take the easy approach by simply allocating a new block of memory 5177for each occurrence. However, this is going to create a lot of 5178(typically small) memory blocks that the underlying malloc library will 5179have to keep track of, and even in many good malloc libraries this is 5180likely to cause memory fragmentation and possibly even result in the 5181blocks scattered throughout the address space rather than all in the 5182one place, which is not necessarily a good thing on systems with 5183virtual memory. 5184 5185 An alternative approach would be to allocate memory in multiples of 5186the block size, so that several blocks would be allocated at once. 5187This would require slightly more work on your part since you would need 5188to write interface code to return a single block, while possible 5189allocating space for more blocks if no free blocks were available. 5190However, this approach has several advantages. The first is that the 5191malloc library only needs to keep track of a few large allocations 5192rather than lots of small allocations, so splitting and merging free 5193blocks is less likely to occur. Secondly, your blocks will be 5194scattered about less in the address space of the process, which means 5195that on systems with virtual memory there are less likely to be page 5196faults if you need to access or traverse all of the blocks you have 5197created. 5198 5199 A memory allocation concept that is similar to this is called an 5200_arena_. This datatype requires functions which are built on top of 5201the existing malloc library functions and which associate each memory 5202allocation with a particular arena. An arena can have as many 5203allocations added to it as required, but allocations cannot usually be 5204freed until the whole arena is freed. Note that there are not really 5205any generic implementations of arenas that are available as everyone 5206tends to write their own version when they require it, although SGI 5207IRIX and Compaq Tru64 systems do come with an arena library called 5208_amalloc_. 5209 5210 However, what if you don't plan to free all of the blocks at the 5211same time? A slight modification to the above design could be to have 5212a _slot table_. This would involve allocating chunks of blocks as they 5213are required, adding each individual block within a chunk to a 5214singly-linked list of free blocks. Then, as new blocks are required, 5215the allocator would simply choose the first block on the free list, 5216otherwise it would allocate memory for a new chunk of blocks and add 5217them to the free list. Freeing individual blocks would simply involve 5218returning the block to the free list. If this description isn't clear 5219enough, have a look in `src/slots.h' and `src/slots.c'. This is how the 5220mpatrol library allocates memory from the system for all of its internal 5221structures. For variable-sized structures, a slightly different 5222approach needs to be taken, but for an example of this using strings 5223see `src/strtab.h' and `src/strtab.c'. 5224 5225 Another optimisation that is possible on UNIX and Windows platforms 5226is making use of memory-mapped files. This allows you to map a 5227filesystem object into the address space of your process, thus allowing 5228you to treat a file as an array of bytes. Because it uses the virtual 5229memory system to map the file, any changes you make to the mapped 5230memory will be applied to the file. This is implemented through the 5231virtual memory system treating the file as a pseudo swap file and will 5232therefore only use up physical memory when pages are accessed. It also 5233means that file operations can be replaced by memory read and write 5234operations, leading to a very fast and efficient way of performing I/O. 5235Another added bonus of this system means that entire blocks of process 5236memory can be written to a file for later re-use, just as long as the 5237file can later be mapped to the same address. This can be a lot faster 5238than writing to and reading from a specific format of file. 5239 5240 If you really don't want to keep track of dynamic memory allocations 5241at all then perhaps you should consider _garbage collection_. This 5242allows you to make dynamic memory allocations that need not necessarily 5243be matched by corresponding calls to free these allocations. A garbage 5244collector will (at certain points during program execution) attempt to 5245look for memory allocations that are no longer referenced by the 5246program and free them for later re-use, hence removing all possibility 5247of memory leaks. However, the garbage collection process can take a 5248sizable chunk of processor time depending on how large the program is, 5249so it is not really an option for real-time programming. It is also 5250very platform-dependent as it examines very low-level structures within 5251a process in order to determine which pointers point to which memory 5252allocations. But there is at least one garbage collector(2) that works 5253well with C and C++ and acts as a replacement for `malloc()' and 5254`free()', so it may be the ideal solution for you. 5255 5256 If you do choose to use an alternative malloc library make sure that 5257you have a license to do so and that you follow any distribution 5258requirements. On systems that support dynamic linking you may want to 5259link the library statically rather than dynamically so that you don't 5260have to worry about an additional file that would need to be installed. 5261However, whether you have that choice depends on the license for the 5262specific library, and some licenses also require that the source code 5263for the library be made readily available. Shared libraries have the 5264advantage that they can be updated with bug fixes so that all programs 5265that require these libraries will automatically receive these fixes 5266without needing to be relinked. 5267 5268 If all of the above suggestions do not seem to help and you still 5269feel that you have a performance bottleneck in the part of your code 5270that deals with dynamically allocated memory then you should try using 5271the memory allocation profiling feature of mpatrol. This can be used 5272at run-time to analyse the dynamic memory allocation calls that your 5273program makes during its execution, and builds statistics for later 5274viewing with the `mprof' command. It is then possible for you to see 5275exactly how many calls were made to each function and where they came 5276from. Such information can then be put to good use in order to 5277optimise the relevant parts of your code. The tracing output files 5278that can be produced by the mpatrol library may also be useful in order 5279to view patterns in memory allocation behaviour and gather information 5280about lifetimes of memory allocations. 5281 5282 And finally, some tips on how to correctly use dynamic memory 5283allocations. The first, most basic rule is to _always_ check the 5284return values from `malloc()' and related functions. _Never_ assume 5285that a call to `malloc()' will succeed, because you're unlikely to be 5286able to read the future(3). Alternatively, use (or write) an 5287`xmalloc()' or similar function(4), which calls `malloc()' but never 5288returns `NULL' since it will abort instead. With the C++ operators it 5289is slightly different because some versions use exceptions to indicate 5290failure, so you should always provide a handler to deal with this 5291eventuality. 5292 5293 Never use _features_(5) of specific malloc libraries if you want 5294your code to be portable. Always follow the ANSI C or C++ calling 5295conventions and never make assumptions about the function or operator 5296you are about to call -- the standards committees went to great lengths 5297to explicitly specify its behaviour. For example, don't assume that 5298the contents of a freed memory allocation will remain valid until the 5299next call to `malloc()', and don't assume that the contents of a newly 5300allocated memory block will be zeroed unless you created it with 5301`calloc()'. 5302 5303 Try to avoid allocating arrays on the stack if they are to hold data 5304that may overflow. In most cases this is common sense, but sometimes 5305you may allocate an array that should suffice for 99% of the time. 5306However, if there is a 1% chance that it may overflow then on some 5307systems the stack is executable and hackers can use that _feature_ to 5308break into a secure program by overwriting the current function's 5309return address on the stack. Use statically-allocated or 5310dynamically-allocated arrays for these situations, or better still, 5311check for overflow. 5312 5313 Finally, try stress-testing your program in low memory conditions. 5314The mpatrol library contains the `LIMIT' option which can place an 5315upper bound on the size of the heap, and also contains the `FAILFREQ' 5316and `FAILSEED' options which can cause random memory allocation 5317failures. Doing this will test parts of your code that you would 5318probably never expect to be called, but perhaps they will one day! Who 5319would you rather have debugging your program -- yourself or the user? 5320 5321 ---------- Footnotes ---------- 5322 5323 (1) Such as for use in a linked list. 5324 5325 (2) A freely distributably library called GC (*note Related 5326software::). 5327 5328 (3) If you can, why are you reading this -- you've already read it! 5329 5330 (4) The mpatrol library comes with the `xmalloc()' and `MP_MALLOC()' 5331families of functions. 5332 5333 (5) Whether they are documented or not. 5334 5335 5336File: mpatrol.info, Node: How it works, Next: Examples, Prev: Improving performance, Up: Top 5337 5338How it works 5339************ 5340 5341 The mpatrol library was originally written with the intention of 5342plugging it into an existing compiler so that the compiler could plant 5343calls to it in the code it generated when a specific debugging option 5344was used. These extra calls would obviously slow the code down, but 5345along with the stack checking options that would be provided, this 5346would give the user an enhanced run-time debugging environment. 5347Unfortunately, this integration never happened, but the way that 5348mpatrol works is still significantly different from other malloc tracing 5349libraries. 5350 5351 In order to quickly determine exactly which memory allocation a heap 5352address belonged to it was necessary to be able to search the heap in 5353an efficient manner. The traditional way of searching along a linked 5354list was unfeasible, so an implementation based on _red-black trees_ 5355was used, where every known memory allocation in the heap was given an 5356entry in the tree, with their start addresses as the key. Another 5357major design decision was to also choose red-black trees to implement 5358the _best fit_ allocation algorithm. Although _first fit_ was 5359considered, I decided that best fit would allow the library to have 5360more control over the heap, with every free memory block in the heap 5361given an entry in the free tree, with their sizes as the key. There 5362was a bit of work involved in getting the splitting and merging of free 5363blocks to work efficiently, but it seems to work well now. 5364 5365 My original implementation had all of the information about each 5366memory block stored just before the block itself. I eventually dropped 5367that behaviour in favour of storing all of the library's internal 5368information in a separate part of the heap. I did that for two 5369reasons. The first was because of the problems that would occur due to 5370memory allocations with different alignment requirements. The second 5371reason was that the library's internal structures could be 5372write-protected on systems with virtual memory, to prevent user code 5373interfering with the operation of the library. 5374 5375 Because the library attempts to record as much information as 5376possible about every memory allocation there will inevitably be a much 5377larger memory requirement when running a program linked with the 5378library. This will typically be two or three times larger in 5379magnitude, but will be affected by the number of memory allocations 5380made and also the number of symbols read. The latter will also affect 5381how quickly the program starts since the first call to allocate memory 5382will result in the initialisation of the library and the loading of 5383symbols from the executable file and any shared libraries. 5384 5385 Due to its design, it is also possible to allocate memory from the 5386heap using the mpatrol library functions whilst already within an 5387mpatrol library function. This does not normally occur, but on some 5388platforms calling `printf()' from within the library may result in 5389`printf()' calling `malloc()' to allocate itself a buffer, which ends 5390up as a recursive call. Luckily, this is dealt with by simply not 5391displaying the allocation in the log file, but all other details of the 5392allocation are still recorded. This can sometimes result in _hidden_ 5393memory usage which occurs behind the scenes and alters the peak memory 5394usage in the summary. This is particularly evident when the library 5395uses an object file access library to read program symbols at the time 5396of library initialisation. 5397 5398 Memory allocation profiling support was added for mpatrol release 53991.2.0. Every allocation and deallocation is recorded, with the call 5400stack information being used to differentiate all of the call sites 5401within the program. Unlike other profilers that come with UNIX 5402systems, even the symbolic information about the program being run is 5403written to the profiling output file, since it makes no sense for 5404`mprof' to re-read the symbol table from the executable file when it 5405has already been read and processed by the mpatrol library. It also has 5406the added bonus of allowing the user to save profiling output files for 5407later use even when the executable files which produced them have 5408changed or no longer exist. It also means that symbol names can be 5409obtained for functions in shared libraries. 5410 5411 Memory allocation tracing support was added for mpatrol release 54121.3.2 and was added to produce concise information for every memory 5413allocation event. This information could also be produced in a verbose 5414form in the log file, but to log every memory allocation event in a 5415large program would result in a massive log file that would be hard to 5416parse. In order to keep the size of the tracing output file down, 5417almost all of the data in the file is encoded as LEB128 numbers. The 5418idea for this comes from the DWARF 2 debugging format. 5419 5420 Support for the `alloca()' family of functions was added for mpatrol 5421release 1.3.0 and uses the heap instead of the stack in order to trace 5422and debug these functions. If full call stack tracebacks are supported 5423on a particular system then mpatrol will compare the current call stack 5424with the call stack of the function that called `alloca()' in order to 5425determine if a memory allocation made by `alloca()' is out of scope. 5426This is generally a safe way to determine when such allocations should 5427be freed, but if full call stack tracebacks are not supported then 5428mpatrol will compare the addresses of specific local variables in the 5429call stack in order to determine if the allocation should be freed. 5430This is an inferior method since it depends on the same function call 5431sequence being used each time an mpatrol function is called. 5432Therefore, a safety boundary was added that will prevent mpatrol from 5433freeing such allocations unless they are a really clear-cut case (i.e. 5434the stack frames differ by a minimum number of bytes). As a result, 5435this second method will not usually free such allocations until a much 5436later point. 5437 5438 The library is written in a modular fashion so as to make it easy to 5439add new functionality. New modules have already been added, such as 5440the _stack_, _symbol_, _profile_ and _trace_ modules. Extra 5441information about each memory allocation can be added to the 5442_allocation information_ module in `src/info.h' and `src/info.c' 5443without having to change much code in any other files. 5444 5445 The `tools' directory in the mpatrol distribution comes with a 5446collection of functions that are built on top of the mpatrol library 5447using its interface functions. This provides a way to extend the 5448mpatrol library for specific applications without requiring that all 5449applications use the extensions. It also provides a way to add new 5450interfaces to the library, perhaps for compatibility with other malloc 5451debugging libraries. 5452 5453 Platform-dependent code has been isolated to specific modules, and 5454feature macros are entirely defined and controlled from `config.h' and 5455`target.h'. The source code has been written so as to make it as easy 5456as possible to compile the library on new platforms at the first 5457attempt, although any additional features that the platform supports 5458will then have to be explicitly enabled in the code. 5459 5460 Of the UNIX platforms that the mpatrol library runs on, Solaris and 5461Linux proved to be the easiest to port to, with well documented and 5462easily accessible programming interfaces to operating system features. 5463Unfortunately, the non-UNIX ports proved a lot harder to write and do 5464not contain as many of the useful features that the UNIX ports have, 5465although sometimes not because they cannot ever support them, but 5466because there would be a huge amount of work involved. 5467 5468 5469File: mpatrol.info, Node: Examples, Next: Tutorial, Prev: How it works, Up: Top 5470 5471Examples 5472******** 5473 5474 Following are a set of examples that are intended to illustrate what 5475exactly is possible with the mpatrol library and how to go about using 5476it effectively. 5477 5478 You should already have built and installed the library and should 5479know how to link programs with the library. Unfortunately, it isn't 5480possible to give specific instructions on how to do this as it varies 5481from system to system and also depends on your preferred compiler and 5482development tools. 5483 5484 However, on a typical SVR4 UNIX system, with mpatrol installed in 5485`/usr/local', the mpatrol library can usually be incorporated into a 5486program using the following commands: 5487 5488 * If the mpatrol library was built with no support for any object 5489 file format or was built with support for the `a.out' object file 5490 format: 5491 5492 cc -I/usr/local/include <file> -L/usr/local/lib -lmpatrol 5493 5494 * If the mpatrol library was built with support for the COFF or 5495 XCOFF object file format access library (not on LynxOS systems): 5496 5497 cc -I/usr/local/include <file> -L/usr/local/lib -lmpatrol -lld 5498 5499 * If the mpatrol library was built with support for the ELF32 or 5500 ELF64 object file format access library: 5501 5502 cc -I/usr/local/include <file> -L/usr/local/lib -lmpatrol -lelf 5503 5504 * If the mpatrol library was built with support for the GNU BFD 5505 object file format access library: 5506 5507 cc -I/usr/local/include <file> -L/usr/local/lib -lmpatrol -lbfd 5508 -liberty 5509 5510 * If the mpatrol library was built on HP/UX with support for the GNU 5511 BFD object file format access library: 5512 5513 cc -I/usr/local/include <file> -L/usr/local/lib -lmpatrol -lbfd 5514 -liberty -lcl 5515 5516 On Windows platforms, with mpatrol installed in `/mpatrol', the 5517mpatrol library can usually be incorporated into a program using the 5518following commands: 5519 5520 * If the program is to be linked with the archive version of the 5521 mpatrol library: 5522 5523 cl -I/mpatrol/include -Zi <file> -link -libpath:/mpatrol/lib 5524 -defaultlib:libmpatrol -defaultlib:imagehlp -pdb:none 5525 5526 * If the program is to be linked with the DLL version of the mpatrol 5527 library: 5528 5529 cl -I/mpatrol/include -MD -Zi <file> -link -libpath:/mpatrol/lib 5530 -defaultlib:mpatrol -pdb:none 5531 5532 If you need to link with other libraries, make sure that they don't 5533contain definitions of `malloc()', etc., or if they do then you must 5534ensure that the mpatrol library appears before them on the link line. 5535Note also that if the mpatrol library was built on Tru64, or on IRIX 5536with the `MP_LIBRARYSTACK_SUPPORT' preprocessor macro defined, then the 5537`libexc' library must be linked in as well. You should also check the 5538section on supported systems (*note Supported systems::) to see if 5539there are any other issues on the platform that you are using. 5540 5541 You should also know how to set an environment variable on your 5542specific system. Again, this varies from system to system and also 5543depends on the command line interpreter or shell that you use. The 5544environment variable that the mpatrol library uses is called 5545`MPATROL_OPTIONS'. You can see exactly what options are available for 5546this environment variable by setting it to `HELP' and then running a 5547program that has been linked with the library. 5548 5549* Menu: 5550 5551* Example 1:: Getting started. 5552* Example 2:: Detecting incorrect reuse of freed memory. 5553* Example 3:: Detecting use of free memory. 5554* Example 4:: Using overflow buffers. 5555* Example 5:: Checking memory accesses. 5556* Example 6:: Bad memory operations. 5557* Example 7:: Incompatible function calls. 5558* Example 8:: The `alloca()' functions. 5559* Example 9:: The `MP_MALLOC()' functions. 5560* Example 10:: Additional useful information. 5561 5562 5563File: mpatrol.info, Node: Example 1, Next: Example 2, Up: Examples 5564 5565Getting started 5566=============== 5567 5568 The first example we'll look at is when the argument in a call to 5569`free()' doesn't match the return value from `malloc()', even though 5570the intention is to free the memory that was allocated by `malloc()'. 5571This example is in `tests/fail/test1.c' and causes many existing 5572`malloc()' implementations to crash. 5573 5574 Along the way, I'll try to describe as many features of the mpatrol 5575library as possible, and illustrate them with examples. Note that the 5576output from your version of the library is likely to vary slightly from 5577that shown in the examples, especially on non-UNIX systems. 5578 5579 23 /* 5580 24 * Allocates a block of 16 bytes and then attempts to free the 5581 25 * memory returned at an offset of 1 byte into the block. 5582 26 */ 5583 5584 5585 29 #include "mpatrol.h" 5586 5587 5588 32 int main(void) 5589 33 { 5590 34 char *p; 5591 5592 36 if (p = (char *) malloc(16)) 5593 37 free(p + 1); 5594 38 return EXIT_SUCCESS; 5595 39 } 5596 5597 Note that I've removed the copyright message from the start of the 5598file and added line numbers so that the tracing below makes more sense. 5599 5600 After compiling and linking the above program with the mpatrol 5601library, the `MPATROL_OPTIONS' environment variable should be set to be 5602`LOGALL' and the program should be executed, generating the following 5603output in `mpatrol.log'. 5604 5605 @(#) mpatrol 1.4.8 (02/01/08) 5606 Copyright (C) 1997-2002 Graeme S. Roy 5607 5608 This is free software, and you are welcome to redistribute it under 5609 certain conditions; see the GNU Library General Public License for 5610 details. 5611 5612 For the latest mpatrol release and documentation, 5613 visit http://www.cbmamiga.demon.co.uk/mpatrol. 5614 5615 operating system: UNIX 5616 system variant: Linux 5617 processor architecture: Intel 80x86 5618 processor word size: 32-bit 5619 object file format: BFD 5620 dynamic linker type: SVR4 5621 5622 Log file generated on Tue Jan 8 19:47:24 2002 5623 5624 read 310 symbols from /usr/lib/libmpatrol.so.1.4 5625 read 647 symbols from /usr/lib/libbfd-2.9.5.0.22.so 5626 read 2634 symbols from /lib/libc.so.6 5627 read 1142 symbols from /usr/lib/libstdc++-libc6.1-1.so.2 5628 read 695 symbols from /lib/libm.so.6 5629 read 178 symbols from /lib/ld-linux.so.2 5630 read 158 symbols from ./test1 5631 5632 ALLOC: malloc (52, 16 bytes, 4 bytes) [main|test1.c|36] 5633 0x0804942F main+31 5634 0x4007C9CB __libc_start_main+255 5635 0x08049381 _start+33 5636 5637 returns 0x080620E8 5638 5639 FREE: free (0x080620E9) [main|test1.c|37] 5640 0x08049457 main+71 5641 0x4007C9CB __libc_start_main+255 5642 0x08049381 _start+33 5643 5644 ERROR: [MISMAT]: free: 0x080620E9 does not match allocation of 0x080620E8 5645 0x080620E8 (16 bytes) {malloc:52:0} [main|test1.c|36] 5646 0x0804942F main+31 5647 0x4007C9CB __libc_start_main+255 5648 0x08049381 _start+33 5649 5650 system page size: 4096 bytes 5651 default alignment: 4 bytes 5652 overflow size: 0 bytes 5653 overflow byte: 0xAA 5654 allocation byte: 0xFF 5655 free byte: 0x55 5656 allocation stop: 0 5657 reallocation stop: 0 5658 free stop: 0 5659 unfreed abort: 0 5660 small boundary: 32 bytes 5661 medium boundary: 256 bytes 5662 large boundary: 2048 bytes 5663 lower check range: 0 5664 upper check range: 0 5665 check frequency: 1 5666 failure frequency: 0 5667 failure seed: 972951591 5668 prologue function: <unset> 5669 epilogue function: <unset> 5670 handler function: <unset> 5671 log file: mpatrol.log 5672 profiling file: mpatrol.out 5673 tracing file: mpatrol.trace 5674 program filename: ./test1 5675 symbols read: 5764 5676 autosave count: 0 5677 freed queue size: 0 5678 allocation count: 52 5679 allocation peak: 20 (427512 bytes) 5680 allocation limit: 0 bytes 5681 allocated blocks: 7 (1528 bytes) 5682 marked blocks: 0 (0 bytes) 5683 freed blocks: 0 (0 bytes) 5684 free blocks: 4 (432648 bytes) 5685 internal blocks: 33 (540672 bytes) 5686 total heap usage: 974848 bytes 5687 total compared: 0 bytes 5688 total located: 2 bytes 5689 total copied: 32176 bytes 5690 total set: 582856 bytes 5691 total warnings: 0 5692 total errors: 1 5693 5694 Ignoring the copyright blurb and target environment information at 5695the top of the file, let's first take a look at the initial log message 5696from the library. I've annotated each of the items with a number that 5697corresponds to the descriptions below. 5698 5699 (1) (2) (3) (4) (5) (6) (7) (8) 5700 | | | | | | | | 5701 V V V V V V V V 5702 ALLOC: malloc (52, 16 bytes, 4 bytes) [main|test1.c|36] 5703 (9) -> 0x0804942F main+31 5704 0x4007C9CB __libc_start_main+255 5705 0x08049381 _start+33 <- (10) 5706 5707 returns 0x080620E8 <- (11) 5708 5709 1. Allocation type. This generalises the type of dynamic memory 5710 operation that is being performed, and can be one of `ALLOC', 5711 `REALLOC' or `FREE'. This should make looking for all 5712 allocations, reallocations or frees in the log file a lot easier. 5713 Alternatively, if a memory operation function was called then this 5714 can also be one of `MEMSET', `MEMCOPY', `MEMFIND' or `MEMCMP'. 5715 5716 2. Allocation function. This is the name of the function that has 5717 been called to allocate the memory, in this case `malloc'. 5718 5719 3. Allocation index. This is incremented every time a new memory 5720 allocation is requested, and persists even if the memory 5721 allocation is resized with `realloc()' and its related functions, 5722 so can be useful to keep track of a memory allocation, even if its 5723 start address changes. The mpatrol library may use up the first 5724 few allocation indices when it gets initialised. 5725 5726 4. Size of requested allocation. 5727 5728 5. Alignment for requested allocation. This is normally the default 5729 system alignment for general-purpose memory allocations, but may 5730 be different depending on the type of function that is used to 5731 allocate the memory. 5732 5733 The following information contains source file details of where the 5734call to `malloc()' came from, but is only available if the source file 5735containing the call to `malloc()' included `mpatrol.h'; otherwise the 5736fields will all be `-'(1). Because of the convoluted way this 5737information is obtained for the C++ operators, you may encounter some 5738problems in existing C++ programs when making direct calls to `operator 5739new' for example. However, if you want to disable the redefinition of 5740the C++ operators in `mpatrol.h' you can define the preprocessor macro 5741`MP_NOCPLUSPLUS' before the inclusion of that file. Alternatively, you 5742may wish to define the `MP_NONEWDELETE' preprocessor macro in order to 5743use `MP_NEW', `MP_NEW_NOTHROW' and `MP_DELETE' instead of `new' and 5744`delete'. That way you can combine calls to mpatrol's operators and 5745the standard operators. Just make sure you don't mix them! 5746 5747 If you are running on a system on which mpatrol supports full 5748symbolic stack tracebacks the following information may still be useful 5749if the source files were compiled with optimisation turned on. This is 5750because the calling function may have been inlined, in which case you 5751will only see the name of the function into which the calling function 5752was expanded in the stack traceback. 5753 5754 6. Function where call to `malloc()' took place. This information is 5755 only available if the source file containing the call to 5756 `malloc()' was compiled with `gcc' or `g++'. 5757 5758 7. Filename in which call to `malloc()' took place. 5759 5760 8. Line number at which call to `malloc()' took place. 5761 5762 The following information contains function call stack details of 5763where the call to `malloc()' came from, but is only available if the 5764mpatrol library has been built on a platform that supports this. The 5765top-most entry should be the function which called `malloc()' and the 5766bottom-most entry should be the entry-point for the process. 5767 5768 9. Address of function call. This is normally the address of the 5769 machine instruction immediately after the function call 5770 instruction, also known as the return address. 5771 5772 10. Function where call took place. This information is only 5773 available if the mpatrol library has been built on a platform that 5774 supports reading symbol table information from executable files, 5775 and then only if there is an entry in the symbol table 5776 corresponding to the return address. C++ function names may still 5777 be in their mangled form, but this can be easily rectified by 5778 processing the log file with a C++ name demangler. The number 5779 after the plus sign is the offset in bytes from the beginning of 5780 the function. 5781 5782 The following information is only available when the allocation type 5783is `ALLOC' or `REALLOC' since it makes no sense when applied to `FREE'. 5784 5785 11. The address of the new memory block that has been allocated by 5786 `malloc()'. 5787 5788 As you can see, there is quite a lot of information that can be 5789displayed from a simple call to `malloc()', and hopefully this 5790information has been presented in a clear and concise format in the log 5791file. 5792 5793 The next entries in the log file correspond to the call to `free()', 5794which attempts to free the memory allocated by `malloc()', but supplies 5795the wrong address. 5796 5797 The first four lines should be self-explanatory as they are very 5798similar to those described above for `malloc()'. However, the next 5799lines signal that a terminal error has occurred in the program, so I've 5800annotated them as before. 5801 5802 FREE: free (0x080620E9) [main|test1.c|37] 5803 0x08049457 main+71 5804 0x4007C9CB __libc_start_main+255 5805 0x08049381 _start+33 5806 5807 (1) (2) (3) 5808 | | | 5809 V V V 5810 ERROR: [MISMAT]: free: 0x080620E9 does not match allocation of 0x080620E8 5811 (4) (5) (6) (7)(8) (9) (10) (11) 5812 | | | | | | | | 5813 V V V V V V V V 5814 0x080620E8 (16 bytes) {malloc:52:0} [main|test1.c|36] 5815 (12) -> 0x0804942F main+31 5816 0x4007C9CB __libc_start_main+255 5817 0x08049381 _start+33 5818 5819 1. Error severity. The mpatrol library has two different severities 5820 of error: `WARNING' and `ERROR'. The first is always recoverable, 5821 and serves only to indicate that something is not quite right, and 5822 so may be useful in determining where something started to go 5823 wrong. The second may or may not be recoverable, and the library 5824 terminates the program if it is fatal, displaying any relevant 5825 information as it does this. 5826 5827 2. Error abbreviation code. This is a code that is different for 5828 each type of error that is detected by the mpatrol library. Some 5829 warnings and errors that are not directly related to the program 5830 being run will not contain this field. See the appendix on 5831 diagnostic messages (*note Diagnostic messages::) for a complete 5832 list of all possible error abbreviation codes and their 5833 descriptions. 5834 5835 3. Allocation function. This is the name of the function used to 5836 allocate, reallocate or free memory where the error was detected. 5837 This may be omitted if an error is detected elsewhere in the 5838 library. 5839 5840 The following information is related to the information that the 5841library has stored about the relevant memory allocation. This 5842information is always displayed in this format when details of 5843individual memory allocations are required. If any information is 5844missing then it simply means that the library was not able to determine 5845it when the memory block was first allocated. 5846 5847 4. Address of memory allocation. 5848 5849 5. Size of memory allocation. 5850 5851 6. Allocation function. This is the name of the function that was 5852 called to allocate the memory block, in this case `malloc'. If 5853 the memory allocation has been resized then this will be either 5854 `realloc', `reallocf', `recalloc', `expand' or `xrealloc'. 5855 5856 7. Allocation index. 5857 5858 8. Reallocation index. This is used to count the number of times a 5859 memory allocation has been resized with `realloc()' and its 5860 related functions. 5861 5862 9. Function where original call to `malloc()' took place. If the 5863 memory allocation has been resized then this will be the name of 5864 the function which last called `realloc()' and its related 5865 functions. 5866 5867 10. Filename in which original call to `malloc()' took place. If the 5868 memory allocation has been resized then this will be the filename 5869 in which the last call to `realloc()' and its related functions 5870 took place. 5871 5872 11. Line number at which original call to `malloc()' took place. If 5873 the memory allocation has been resized then this will be the line 5874 number at which the last call to `realloc()' and its related 5875 functions took place. 5876 5877 12. Function call stack of original memory allocation. If the memory 5878 allocation has been resized then this will be the call stack of 5879 the last call to `realloc()' and related functions. 5880 5881 So, the mpatrol library detected the error in the above program and 5882terminated it. When the library terminates it always displays a 5883summary of various memory allocation statistics and settings that were 5884used during the execution of the program. 5885 5886 The various settings and statistics displayed by the library for the 5887above example have been numbered and their descriptions appear below. 5888 5889 1 system page size: 4096 bytes 5890 2 default alignment: 4 bytes 5891 3 overflow size: 0 bytes 5892 4 overflow byte: 0xAA 5893 5 allocation byte: 0xFF 5894 6 free byte: 0x55 5895 7 allocation stop: 0 5896 8 reallocation stop: 0 5897 9 free stop: 0 5898 10 unfreed abort: 0 5899 11 small boundary: 32 bytes 5900 12 medium boundary: 256 bytes 5901 13 large boundary: 2048 bytes 5902 14 lower check range: 0 5903 15 upper check range: 0 5904 16 check frequency: 1 5905 17 failure frequency: 0 5906 18 failure seed: 972951591 5907 19 prologue function: <unset> 5908 20 epilogue function: <unset> 5909 21 handler function: <unset> 5910 22 log file: mpatrol.log 5911 23 profiling file: mpatrol.out 5912 24 tracing file: mpatrol.trace 5913 25 program filename: ./test1 5914 26 symbols read: 5764 5915 27 autosave count: 0 5916 28 freed queue size: 0 5917 29 allocation count: 52 5918 30 allocation peak: 20 (427512 bytes) 5919 31 allocation limit: 0 bytes 5920 32 allocated blocks: 7 (1528 bytes) 5921 33 marked blocks: 0 (0 bytes) 5922 34 freed blocks: 0 (0 bytes) 5923 35 free blocks: 4 (432648 bytes) 5924 36 internal blocks: 33 (540672 bytes) 5925 37 total heap usage: 974848 bytes 5926 38 total compared: 0 bytes 5927 39 total located: 2 bytes 5928 40 total copied: 32176 bytes 5929 41 total set: 582856 bytes 5930 42 total warnings: 0 5931 43 total errors: 1 5932 5933 1. System page size. This value is used on some platforms when 5934 allocating and protecting system memory. 5935 5936 2. Default alignment. This value is the minimum alignment required 5937 for general purpose memory allocations, and is usually the 5938 alignment required by the most restrictive datatype on a given 5939 system. It is used when allocating memory that has no specified 5940 alignment. It can be changed at run-time using the `DEFALIGN' 5941 option, but setting this value too small may cause the program to 5942 crash due to bus errors which are caused by reading from or 5943 writing to misaligned data. 5944 5945 3. Overflow size. This value is the size used by one overflow 5946 buffer. If this is non-zero then every memory allocation will 5947 have two overflow buffers; one on either side. These buffers are 5948 used by the library to detect if the program has written too many 5949 bytes to a memory allocation, thus overflowing into one of the 5950 buffers, but these extra checks can slow down execution speed. It 5951 can be changed at run-time using the `OFLOWSIZE' option. 5952 5953 4. Overflow byte. 5954 5955 5. Allocation byte. 5956 5957 6. Free byte. These values are used by the library to pre-fill 5958 blocks of memory for checking purposes. The overflow byte is used 5959 to fill overflow buffers, the allocation byte is used to fill 5960 newly-allocated memory (except from `calloc()' or `recalloc()'), 5961 and the free byte is used to fill free blocks or freed memory 5962 allocations. These can be changed at run-time using the 5963 `OFLOWBYTE', `ALLOCBYTE' and `FREEBYTE' options. 5964 5965 7. Allocation stop. 5966 5967 8. Reallocation stop. 5968 5969 9. Free stop. These values are used by the library to halt the 5970 program when run inside a debugger whenever a specified allocation 5971 index is allocated, reallocated or freed. These can be changed at 5972 run-time using the `ALLOCSTOP', `REALLOCSTOP' and `FREESTOP' 5973 options. 5974 5975 10. Unfreed abort. This value is used when the program terminates and 5976 is used by the library to check if there are more than a given 5977 number of unfreed memory allocations. If there are then the 5978 library will cause the program to abort with an error. It can be 5979 changed at run-time using the `UNFREEDABORT' option. 5980 5981 11. Small boundary. 5982 5983 12. Medium boundary. 5984 5985 13. Large boundary. These values are used in memory allocation 5986 profiling and specify the boundaries in bytes between small, 5987 medium, large and extra large allocations. These can be changed 5988 at run-time using the `SMALLBOUND', `MEDIUMBOUND' and `LARGEBOUND' 5989 options. 5990 5991 14. Lower check range. 5992 5993 15. Upper check range. 5994 5995 16. Check frequency. These values specify the range of allocation 5996 indices through which the library will physically check every area 5997 of free memory and every overflow buffer for errors, along with 5998 the frequency at which to make the checks. A dash specifies that 5999 either the lower or upper range is infinite, but if they are both 6000 zero then no such checking will ever be performed, thus speeding 6001 up execution speed dramatically. The check frequency indicates the 6002 number of memory allocation events that must occur in between 6003 checking the heap. The library defaults to performing no such 6004 checks. This can be changed at run-time using the `CHECK' option. 6005 6006 17. Failure frequency. 6007 6008 18. Failure seed. These values are used to specify if random memory 6009 allocation failures should occur during program execution, for the 6010 purposes of stress testing a program. If the failure frequency is 6011 zero then no random failures will occur, but if it is greater than 6012 zero then the higher the number, the less frequent the failures. 6013 The failure seed is used internally by the mpatrol library when 6014 generating random numbers. If it is zero then the seed will be set 6015 randomly, but if it is greater than zero then it will be used to 6016 generate a predictable sequence of random numbers; i.e. two runs 6017 of the same program with the same failure frequencies and the same 6018 failure seeds will generate exactly the same sequence of failures. 6019 6020 19. Prologue function. 6021 6022 20. Epilogue function. 6023 6024 21. Handler function. These values contain addresses or names of 6025 functions that have been installed as callback functions for the 6026 library. These functions, if set, will be called from the library 6027 at appropriate times during program execution in order to handle 6028 specific events. These can be changed at compile-time using the 6029 `__mp_prologue()', `__mp_epilogue()' and `__mp_nomemory()' 6030 functions. 6031 6032 22. Log file. Simply contains the name of the file where all mpatrol 6033 library diagnostics go to. It can be changed at run-time using 6034 the `LOGFILE' option. 6035 6036 23. Profiling file. Contains the name of the file where all of the 6037 mpatrol library memory allocation profiling information goes when 6038 the `PROF' option is used. It can be changed at run-time using 6039 the `PROFFILE' option. 6040 6041 24. Tracing file. Contains the name of the file where all of the 6042 mpatrol library memory allocation tracing information goes when 6043 the `TRACE' option is used. It can be changed at run-time using 6044 the `TRACEFILE' option. 6045 6046 25. Program filename. Contains the full pathname to the program's 6047 executable file. This is used by the mpatrol library to read the 6048 symbol table in order to provide symbolic information in function 6049 call stacks. It can be changed at run-time using the `PROGFILE' 6050 option. 6051 6052 26. Symbols read. This value contains the total number of symbols 6053 read from a program's executable file and/or the dynamic linker, 6054 if applicable. 6055 6056 27. Autosave count. This value contains the frequency at which the 6057 mpatrol library should periodically write the profiling data to 6058 the profiling output file. When the total number of profiled 6059 memory allocations and deallocations is a multiple of this number 6060 then the current profiling information will be written to the 6061 profiling output file. It can be changed at run-time using the 6062 `AUTOSAVE' option. 6063 6064 28. Freed queue size. This value contains the maximum number of freed 6065 memory allocations that will be stored in the freed queue if the 6066 `NOFREE' option is used. Once the freed queue becomes full then 6067 the oldest freed allocation in the queue will be returned to the 6068 free memory pool for reuse every time an existing memory 6069 allocation is freed. If this value is zero then the freed queue 6070 will never contain any freed allocations. It can be changed at 6071 run-time using the `NOFREE' option. 6072 6073 29. Allocation count. This value contains the total number of memory 6074 allocations that were created by the mpatrol library. This value 6075 may be more than expected if the mpatrol library makes any memory 6076 allocations during initialisation. 6077 6078 30. Allocation peak. This value contains the peak memory usage set by 6079 the program when running; the peak number of memory allocations, 6080 and also the peak number of bytes allocated in parentheses (the 6081 two numbers may peak at different times throughout the lifetime of 6082 the program). This value may be more than expected if the mpatrol 6083 library makes any memory allocations during initialisation. 6084 6085 31. Allocation limit. This value is used to limit the amount of 6086 memory that can be allocated by a program, which can be useful for 6087 stress-testing in simulated low memory conditions. It can be 6088 changed at run-time using the `LIMIT' option. 6089 6090 32. Allocated blocks. 6091 6092 33. Marked blocks. 6093 6094 34. Freed blocks. 6095 6096 35. Free blocks. These values contain the total number of allocated, 6097 marked, freed and free blocks at the time the summary was 6098 produced. A marked block is an allocated block that the user has 6099 instructed (via the `__mp_setmark()' function) the mpatrol library 6100 should remain allocated for the rest of the lifetime of the 6101 program and should never be freed or counted as a memory leak. A 6102 freed block is an allocated block that has been freed but has not 6103 been returned to the free memory list for later allocation. These 6104 values may be different from those expected if the mpatrol library 6105 makes any memory allocations during initialisation. In this 6106 example a large amount of memory is used by the system object file 6107 access library which is used for reading the symbols from the 6108 program's executable file and any shared libraries that it 6109 requires. 6110 6111 36. Internal blocks. This value contains the total number of memory 6112 blocks (of varying sizes) that have been allocated from the system 6113 for the mpatrol library to use internally. These memory blocks 6114 will be write-protected on systems that support memory protection 6115 in order to prevent the program from corrupting the library's data 6116 structures. This can be overridden at run-time using the 6117 `NOPROTECT' option in order to speed up program execution slightly. 6118 6119 37. Total heap usage. This value contains the total amount of system 6120 heap memory that has been allocated by the mpatrol library. 6121 6122 38. Total compared. 6123 6124 39. Total located. 6125 6126 40. Total copied. 6127 6128 41. Total set. These values contain the total number of bytes that 6129 have been tracked by the mpatrol library in byte comparison 6130 operations (such as `memcmp()'), byte location operations (such as 6131 `memchr()', byte copy operations (such as `memcpy()') and byte set 6132 operations (such as `memset()') respectively. They do not take 6133 into account any other such operations that occur outwith these 6134 functions, such as loading and storing from machine instructions. 6135 6136 42. Total warnings. 6137 6138 43. Total errors. The library keeps a count of the total number of 6139 warnings and errors it has displayed so that you can quickly work 6140 out this information at program termination. 6141 6142 ---------- Footnotes ---------- 6143 6144 (1) This information may also be filled in if the `USEDEBUG' option 6145or the `mpsym' command is used and supported, and if debugging 6146information about the call to `malloc()' is available. 6147 6148 6149File: mpatrol.info, Node: Example 2, Next: Example 3, Prev: Example 1, Up: Examples 6150 6151Detecting incorrect reuse of freed memory 6152========================================= 6153 6154 The next example uses `tests/fail/test2.c' to illustrate how the 6155mpatrol library can detect whereabouts on the heap an address belongs. 6156 6157 23 /* 6158 24 * Allocates a block of 16 bytes and then immediately frees it. An 6159 25 * attempt is then made to double the size of the original block. 6160 26 */ 6161 6162 6163 29 #include "mpatrol.h" 6164 6165 6166 32 int main(void) 6167 33 { 6168 34 char *p; 6169 6170 36 if (p = (char *) malloc(16)) 6171 37 { 6172 38 free(p); 6173 39 p = (char *) realloc(p, 32); 6174 40 } 6175 41 return EXIT_SUCCESS; 6176 42 } 6177 6178 The relevant excerpts from `mpatrol.log' appear below. The format 6179of the log messages should be familiar to you now. 6180 6181 ALLOC: malloc (52, 16 bytes, 4 bytes) [main|test2.c|36] 6182 0x0804942F main+31 6183 0x4007C9CB __libc_start_main+255 6184 0x08049381 _start+33 6185 6186 returns 0x080620E8 6187 6188 FREE: free (0x080620E8) [main|test2.c|38] 6189 0x08049456 main+70 6190 0x4007C9CB __libc_start_main+255 6191 0x08049381 _start+33 6192 6193 0x080620E8 (16 bytes) {malloc:52:0} [main|test2.c|36] 6194 0x0804942F main+31 6195 0x4007C9CB __libc_start_main+255 6196 0x08049381 _start+33 6197 6198 REALLOC: realloc (0x080620E8, 32 bytes, 4 bytes) [main|test2.c|39] 6199 0x08049476 main+102 6200 0x4007C9CB __libc_start_main+255 6201 0x08049381 _start+33 6202 6203 ERROR: [NOTALL]: realloc: 0x080620E8 has not been allocated 6204 6205 returns 0x00000000 6206 6207 The mpatrol library stores all of its information about allocated 6208and free memory in tree structures so that it can quickly determine if 6209an address belongs to allocated or free memory, or if it even exists in 6210the heap that is managed by mpatrol. The above example should 6211illustrate this since after the allocation had been freed, the library 6212recognised this and reported an error. It was possible for the program 6213to continue execution even after that error since mpatrol could recover 6214from it and return `NULL'. 6215 6216 It is possible for mpatrol to give even more useful diagnostics in 6217the above situation by using the `NOFREE' option. This prevents the 6218library from returning any freed allocations to the free memory pool, 6219by preserving any information about them and marking them as freed. If 6220you add the `NOFREE=1' option to the `MPATROL_OPTIONS' environment 6221variable you should see the following entries in `mpatrol.log' instead. 6222 6223 ALLOC: malloc (52, 16 bytes, 4 bytes) [main|test2.c|36] 6224 0x0804942F main+31 6225 0x4007C9CB __libc_start_main+255 6226 0x08049381 _start+33 6227 6228 returns 0x08062F54 6229 6230 FREE: free (0x08062F54) [main|test2.c|38] 6231 0x08049456 main+70 6232 0x4007C9CB __libc_start_main+255 6233 0x08049381 _start+33 6234 6235 0x08062F54 (16 bytes) {malloc:52:0} [main|test2.c|36] 6236 0x0804942F main+31 6237 0x4007C9CB __libc_start_main+255 6238 0x08049381 _start+33 6239 6240 REALLOC: realloc (0x08062F54, 32 bytes, 4 bytes) [main|test2.c|39] 6241 0x08049476 main+102 6242 0x4007C9CB __libc_start_main+255 6243 0x08049381 _start+33 6244 6245 ERROR: [PRVFRD]: realloc: 0x08062F54 was freed with free 6246 0x08062F54 (16 bytes) {free:52:0} [main|test2.c|38] 6247 0x08049456 main+70 6248 0x4007C9CB __libc_start_main+255 6249 0x08049381 _start+33 6250 6251 returns 0x00000000 6252 6253 Note the extra information reported by `realloc()' since the library 6254knows all of the details about the freed memory allocation and when it 6255was freed. 6256 6257 The `NOFREE' option can potentially use up much more system memory 6258than normal if it is given a large numerical argument since it 6259effectively instructs the mpatrol library to allocate new memory for 6260every single memory allocation or reallocation. It can also slow down 6261program execution when overflow buffers are used, since with each new 6262memory allocation the library needs to check more and more overflow 6263buffers every time it is called. However, with a low numerical 6264argument it can be quite useful for problems such as this one. The 6265test in `tests/fail/test3.c' has a similar situation. 6266 6267 The numerical argument specified with the `NOFREE' option indicates 6268the number of recently-freed memory allocations that are to be delayed 6269from being returned to the free memory pool, with a value of zero 6270meaning that all freed memory allocations will immediately be reused. 6271Obviously, in an ideal world it would be nice to be able to specify 6272`NOFREE='_huge-number_ all the time, but this will gradually use up 6273more and more memory since no system heap memory will ever be reused. 6274Supplying a smaller number to the `NOFREE' option allows you to make a 6275compromise by storing the details of only the most recently-freed 6276memory allocations. How many details you wish to store is up to you. 6277 6278 Normally, the `NOFREE' option will cause the library to fill all 6279freed memory allocations with the free byte. However, the original 6280contents of such allocations can be preserved with the `PRESERVE' 6281option. This could help in situations when you need to determine 6282exactly if a program is relying on the contents of freed memory. 6283 6284 6285File: mpatrol.info, Node: Example 3, Next: Example 4, Prev: Example 2, Up: Examples 6286 6287Detecting use of free memory 6288============================ 6289 6290 This next example illustrates how the mpatrol library is able to 6291check to see if anything has been written into free memory. The test 6292is located in `tests/fail/test4.c' and simply writes a single byte into 6293free memory. 6294 6295 23 /* 6296 24 * Allocates a block of 16 bytes and then immediately frees it. A 6297 25 * NULL character is written into the middle of the freed memory. 6298 26 */ 6299 6300 6301 29 #include "mpatrol.h" 6302 6303 6304 32 int main(void) 6305 33 { 6306 34 char *p; 6307 6308 36 if (p = (char *) malloc(16)) 6309 37 { 6310 38 free(p); 6311 39 p[8] = '\0'; 6312 40 } 6313 41 return EXIT_SUCCESS; 6314 42 } 6315 6316 The following output was produced as part of `mpatrol.log'. Note 6317that this test was run using the same `MPATROL_OPTIONS' settings as the 6318last example, but make sure that `PRESERVE' is not set. 6319 6320 ERROR: [FRDCOR]: freed allocation 0x08062F54 has memory corruption at 0x08062F5C 6321 0x08062F5C 00555555 55555555 .UUUUUUU 6322 6323 0x08062F54 (16 bytes) {free:52:0} [main|test4.c|38] 6324 0x08049456 main+70 6325 0x4007C9CB __libc_start_main+255 6326 0x08049381 _start+33 6327 6328 The library was able to detect that something had been written into 6329free memory and could report on the memory allocation that was 6330overwritten. However, these checks are only performed whenever a 6331function in the mpatrol library is called if the `CHECK' option is 6332used, or at the end of program execution. In the example above, the 6333code which wrote into free memory could have been miles away from where 6334the library detected the error since we were not using the `CHECK' 6335option. However, adding `CHECK=-' to the `MPATROL_OPTIONS' environment 6336variable doesn't really help much since the next mpatrol function that 6337is called is the one to terminate the library anyway. 6338 6339 Note that using the `CHECK' option is equivalent to calling 6340`__mp_check()' when each mpatrol library function is called, or at the 6341range and frequency specified in the values passed to the `CHECK' 6342option. If you suspect that heap corruption is occurring in a part of 6343your code where there is a large gap between mpatrol library calls, you 6344can try to narrow the problem down by adding a few calls to 6345`__mp_check()'. 6346 6347 On platforms that support memory protection, the library also 6348supports the `PAGEALLOC' option. This option instructs the library to 6349force every single memory allocation to have a size which is a multiple 6350of the system page size. Although the library still stores the 6351original requested size, it effectively means that no two memory 6352allocations occupy the same page of memory. It can then use page 6353protection (which only operates on pages of memory) to protect all free 6354memory from being read from or written to, and uses similar features to 6355install a page of overflow buffer on either side of the allocation. 6356 6357 However, if the requested size for the memory allocation was not a 6358multiple of the page size this means that there will still be unused 6359space left over in the allocated pages. This problem is solved by 6360turning the unused space into overflow buffers that will be checked in 6361the normal way. The positioning of the allocation within its pages is 6362also important. If you want to check for illegal reads from the 6363borders of the memory allocation, unless it fits exactly into its pages 6364then there is a chance that a program could illegally read the 6365right-most overflow buffer if the allocation was left-aligned, or 6366vice-versa. Two settings therefore exist for the `PAGEALLOC' option: 6367`LOWER' and `UPPER'. They refer to the placement of every memory 6368allocation within its constituent pages. 6369 6370 The following diagram illustrates the `PAGEALLOC' option. In the 6371diagram, the system page size is assumed to be 16 bytes (very unlikely, 6372but will serve for this example) and each character represents 1 byte. 6373 6374 x = allocated memory 6375 o = overflow buffer (filled with the overflow byte) 6376 . = overflow buffer page (read and write protected) 6377 6378 PAGEALLOC=LOWER, allocation size is 16 bytes or 6379 PAGEALLOC=UPPER, allocation size is 16 bytes: 6380 ................xxxxxxxxxxxxxxxx................ 6381 6382 PAGEALLOC=LOWER, allocation size is 8 bytes: 6383 ................xxxxxxxxoooooooo................ 6384 6385 PAGEALLOC=UPPER, allocation size is 8 bytes: 6386 ................ooooooooxxxxxxxx................ 6387 6388 In our original example, if the `PAGEALLOC=LOWER' option is added to 6389the `MPATROL_OPTIONS' environment variable then the following error 6390will be produced instead of the original error. 6391 6392 ERROR: [ILLMEM]: illegal memory access at address 0x081C6008 6393 0x081C6000 (16 bytes) {free:52:0} [main|test4.c|38] 6394 0x08049456 main+70 6395 0x4007C9CB __libc_start_main+255 6396 0x08049381 _start+33 6397 6398 call stack 6399 0x0804945F main+79 6400 0x4007C9CB __libc_start_main+255 6401 0x08049381 _start+33 6402 6403 On systems that support memory protection, the mpatrol library has a 6404built-in signal handler which catches illegal memory accesses and 6405terminates the program. In the above case, the freed memory was made 6406write-protected and so could not be written to. The underlying virtual 6407memory system in the operating system noticed this and signaled this to 6408the library immediately after it happened. 6409 6410 Along with the details of the freed memory allocation that was being 6411written to, the library also attempts to display the function call 6412stack for the location in the program that caused the illegal memory 6413access, although this can be quite unreliable. A better solution would 6414be to run the program in a debugger to catch the illegal memory access. 6415 6416 Note that the `PAGEALLOC' option also modifies the behaviour of the 6417`NOFREE' and `PRESERVE' options when used together. The memory 6418allocation being freed will always be made write-protected when the 6419`PRESERVE' option is used, otherwise it will also be made read-protected 6420to prevent further accesses. 6421 6422 Note also that the `PAGEALLOC=UPPER' option is potentially much less 6423efficient at catching illegal memory accesses than the `PAGEALLOC=LOWER' 6424option. This is due to alignment requirements, since an allocation of 64251 byte requiring an alignment of 16 bytes cannot be placed at the very 6426end of a page of size 4096 bytes. The following diagram illustrates 6427this, using the same page size as the last diagram. 6428 6429 x = allocated memory 6430 o = overflow buffer (filled with the overflow byte) 6431 . = overflow buffer page (read and write protected) 6432 6433 PAGEALLOC=UPPER, allocation size is 16 bytes, alignment is 8 bytes: 6434 ................xxxxxxxxxxxxxxxx................ 6435 6436 PAGEALLOC=UPPER, allocation size is 3 bytes, alignment is 1 byte: 6437 ................oooooooooooooxxx................ 6438 6439 PAGEALLOC=UPPER, allocation size is 3 bytes, alignment is 8 bytes: 6440 ................ooooooooxxxooooo................ 6441 6442 Everything is OK until the last allocation, where the alignment 6443requirement means that there must be two overflow buffers. This slows 6444down program execution since the library must check an additional 6445overflow buffer, and also means that the program would have to read six 6446bytes beyond the end of the allocation before the illegal memory access 6447would be detected. 6448 6449 6450File: mpatrol.info, Node: Example 4, Next: Example 5, Prev: Example 3, Up: Examples 6451 6452Using overflow buffers 6453====================== 6454 6455 This example illustrates the use of overflow buffers and so the 6456`MPATROL_OPTIONS' environment variable should have `OFLOWSIZE=2' and 6457`CHECK=-' added to it. However, turn off any `PAGEALLOC' options for 6458the purposes of this example. The test is located in 6459`tests/fail/test5.c', and `tests/fail/test6.c' is very similar. 6460 6461 23 /* 6462 24 * Allocates a block of 16 bytes and then copies a string of 16 6463 25 * bytes into the block. However, the string is copied to 1 byte 6464 26 * before the allocated block which writes before the start of the 6465 27 * block. This test must be run with an OFLOWSIZE greater than 0. 6466 28 */ 6467 6468 6469 31 #include "mpatrol.h" 6470 6471 6472 34 int main(void) 6473 35 { 6474 36 char *p; 6475 6476 38 if (p = (char *) malloc(16)) 6477 39 { 6478 40 strcpy(p - 1, "this test fails!"); 6479 41 free(p); 6480 42 } 6481 43 return EXIT_SUCCESS; 6482 44 } 6483 6484 The following error should be produced in `mpatrol.log'. 6485 6486 ERROR: [ALLOVF]: allocation 0x08062FB8 has a corrupted overflow buffer at 6487 0x08062FB7 6488 0x08062FB6 AA74 .t 6489 6490 0x08062FB8 (16 bytes) {malloc:52:0} [main|test5.c|38] 6491 0x0804942F main+31 6492 0x4007C9CB __libc_start_main+255 6493 0x08049381 _start+33 6494 6495 Once again, the library attempts to show you as much detail as 6496possible about where the corruption occurred. Along with showing you a 6497memory dump of the overflow buffer that was corrupted, it also shows 6498you the allocation to which the overflow buffer belongs. 6499 6500 Using overflow buffers and the `CHECK=-' option can reduce the speed 6501of program execution since the library has to check every buffer 6502whenever it is called, and if the buffers are larger then they'll take 6503longer to check and will use up more memory. However, larger buffers 6504mean that there is less chance of the program writing past one memory 6505allocation into another. 6506 6507 Alternatively, the `CHECK' option can be used to limit the number of 6508checks that the library has to perform, thus speeding up program 6509execution. This option specifies a range of allocation indices through 6510which the library will check overflow buffers and free memory for 6511corruption. Such checks occur when they normally would, but only if 6512the current allocation index falls within the specified range. This 6513feature can be used when there is a suspicion that free memory 6514corruption or overflow buffer corruption occurs at a certain point 6515during program execution, but checking them at every library call would 6516take too long. You can also specify a frequency at which to check the 6517heap using the `CHECK' option. This can be used when attempting to 6518narrow down the search for where heap corruption occurs. 6519 6520 On systems which support software watch points, there is an extra 6521option called `OFLOWWATCH' which allows additional memory protection. 6522Watch points allow individual bytes to be read and/or write protected 6523as opposed to just pages. The `OFLOWWATCH' option installs software 6524watch points at every overflow buffer instead of requiring the library 6525to check the integrity of the overflow buffers, and can be used in 6526combination with `PAGEALLOC'. However, software watch points slow down 6527program execution to a crawl since every machine instruction must be 6528checked individually by the system to see if it accesses a watch point 6529area. Slowing the program down by a factor of 10,000 is not uncommon 6530on some systems when the `OFLOWWATCH' option is used. 6531 6532 6533File: mpatrol.info, Node: Example 5, Next: Example 6, Prev: Example 4, Up: Examples 6534 6535Checking memory accesses 6536======================== 6537 6538 For the ultimate in heap checking, if you are using the GNU compiler 6539you can use the `-fcheck-memory-usage' option. This instructs the 6540compiler to place error-checking calls before each read or write to 6541memory. The functions that are called then check to ensure that the 6542memory access does not overflow a heap memory allocation or access free 6543memory. 6544 6545 The following test (which can be found in `tests/fail/test17.c') has 6546an example of a read from memory which overflows a memory allocation's 6547boundaries. 6548 6549 23 /* 6550 24 * Allocates a single byte of memory and then attempts to read the 6551 25 * byte as a word, resulting in some uninitialised bytes being read. 6552 26 * This can sometimes be detected with PAGEALLOC=UPPER but can always 6553 27 * be detected with OFLOWWATCH or by using the -fcheck-memory-usage 6554 28 * option of gcc. 6555 29 */ 6556 6557 6558 32 #include "mpatrol.h" 6559 6560 6561 35 int main(void) 6562 36 { 6563 37 int *p; 6564 38 int r; 6565 6566 40 if (p = (int *) calloc(1, 1)) 6567 41 { 6568 42 r = p[0]; 6569 43 free(p); 6570 44 } 6571 45 return EXIT_SUCCESS; 6572 46 } 6573 6574 For this example, the above test must be compiled with `gcc' with the 6575`-fcheck-memory-usage' option on the compiler command line and linked 6576with the mpatrol library. Normally, the test will pass and not cause 6577any problems, since most malloc libraries will allocate at least one 6578word anyway. However, there are some instances where that will not be 6579the case, especially on systems where misaligned memory accesses are 6580legal. Also, if the implementation of `calloc()' only initialised the 6581number of bytes requested then the number read back might not be zero. 6582 6583 If you now run the program it should abort and produce something 6584similar to the following in the resulting `mpatrol.log'. 6585 6586 ERROR: [RNGOVF]: range [0x00022568,0x0002256B] overflows 6587 [0x00022568,0x00022568] 6588 0x00022568 (1 byte) {calloc:19:0} [main|test17.c|40] 6589 0x00010A0C main+96 6590 0x0001087C _start+100 6591 6592 As you can see, the mpatrol library detected a read beyond the 6593boundaries of the one byte memory allocation starting at `0x00022568'. 6594 6595 6596File: mpatrol.info, Node: Example 6, Next: Example 7, Prev: Example 5, Up: Examples 6597 6598Bad memory operations 6599===================== 6600 6601 In C there are several basic memory operation functions that are 6602often called to perform tasks such as clearing memory, copying memory, 6603etc. The mpatrol library contains replacements for these which allow 6604for better checking of their arguments to prevent reading and writing 6605past the boundaries of existing memory allocations. The following 6606source can be found in `tests/fail/test9.c'. 6607 6608 23 /* 6609 24 * Allocates a block of 16 bytes and then attempts to zero the contents of 6610 25 * the block. However, a zero byte is also written 1 byte before and 1 6611 26 * byte after the allocated block, resulting in an error in the log file. 6612 27 */ 6613 6614 6615 30 #include "mpatrol.h" 6616 6617 6618 33 int main(void) 6619 34 { 6620 35 char *p; 6621 6622 37 if (p = (char *) malloc(16)) 6623 38 { 6624 39 memset(p - 1, 0, 18); 6625 40 free(p); 6626 41 } 6627 42 return EXIT_SUCCESS; 6628 43 } 6629 6630 When this is compiled and run, the following should appear in the 6631log file. 6632 6633 ERROR: [RNGOVF]: memset: range [0x08062FB7,0x08062FC8] overflows 6634 [0x08062FB8,0x08062FC7] 6635 0x08062FB8 (16 bytes) {malloc:52:0} [main|test9.c|37] 6636 0x0804942F main+31 6637 0x4007C9CB __libc_start_main+255 6638 0x08049381 _start+33 6639 6640 As you can see, the library detected that the `memset()' function 6641would have written past the boundaries of the memory allocation and 6642reported this to you. It then proceeded to ignore the request to copy 6643the memory and continued with the execution of the program(1). Note 6644that this will only be done for known memory allocations. Reading and 6645writing past the boundaries of static and stack memory allocations 6646cannot be detected in this way. 6647 6648 If the `LOGMEMORY' option is added to the `MPATROL_OPTIONS' 6649environment variable then it is possible to see a log of all the 6650mpatrol library memory operation functions that were called during 6651program execution. For example, adding this option and running the 6652above program again will produce something similar to the following. 6653 6654 MEMSET: memset (0x08062FB7, 18 bytes, 0x00) [main|test9.c|39] 6655 0x0804945B main+75 6656 0x4007C9CB __libc_start_main+255 6657 0x08049381 _start+33 6658 6659 This is similar to the tracing produced for memory allocation 6660functions, except that the arguments in parentheses mean different 6661things. For `MEMSET', the first argument represents the start of the 6662memory block to set, the second argument represents the number of bytes 6663to set and the third argument represents the actual byte to set. 6664 6665 For `MEMCOPY', the first argument represents the source memory 6666block, the second argument represents the destination memory block, the 6667third argument represents the number of bytes to copy and the fourth 6668argument represents a byte to copy up to if `memccpy()' is being 6669called. This is similar for `MEMCMP'. 6670 6671 For `MEMFIND', the first and second arguments represent the source 6672memory block and its length, while the third and fourth arguments 6673represent the memory block to search for and its length. In the 6674implementation for `memchr()', the byte to search for is copied to a 6675one byte buffer and the address of that buffer is used as the memory 6676block to search for. 6677 6678 Note that as with the memory allocation functions, `MEMCMP', 6679`MEMFIND', `MEMCOPY' and `MEMSET' are used to generalise the types of 6680operations being performed and are followed by the names of the actual 6681functions being used. In some cases the functions may use a different 6682ordering of parameters than that shown. 6683 6684 ---------- Footnotes ---------- 6685 6686 (1) The error can be turned into a warning with the `ALLOWOFLOW' 6687option which will also force the operation to be performed. 6688 6689 6690File: mpatrol.info, Node: Example 7, Next: Example 8, Prev: Example 6, Up: Examples 6691 6692Incompatible function calls 6693=========================== 6694 6695 This example illustrates how the mpatrol library checks for calls to 6696incompatible pairs of memory allocation functions. It requires the use 6697of C++, although does not use any C++ features except for overloaded 6698operators. The source is in `tests/fail/test7.c', and 6699`tests/fail/test8.c' is similar. 6700 6701 23 /* 6702 24 * Allocates a block of 16 bytes using C++ operator new[] and then 6703 25 * attempts to free it using C++ operator delete. 6704 26 */ 6705 6706 6707 29 #include "mpatrol.h" 6708 6709 6710 32 int main(void) 6711 33 { 6712 34 char *p; 6713 6714 36 p = new char[16]; 6715 37 delete p; 6716 38 return EXIT_SUCCESS; 6717 39 } 6718 6719 The relevant parts of `mpatrol.log' are shown below. 6720 6721 ALLOC: operator new[] (74, 16 bytes, 4 bytes) [int main()|test7.c|36] 6722 0x0804955D main+13 6723 0x400DB9CB __libc_start_main+255 6724 0x080494C1 _start+33 6725 6726 returns 0x08062FC0 6727 6728 FREE: operator delete (0x08062FC0) [int main()|test7.c|37] 6729 0x0804956E main+30 6730 0x400DB9CB __libc_start_main+255 6731 0x080494C1 _start+33 6732 6733 ERROR: [INCOMP]: operator delete: 0x08062FC0 was allocated with operator new[] 6734 0x08062FC0 (16 bytes) {operator new[]:74:0} [int main()|test7.c|36] 6735 0x0804955D main+13 6736 0x400DB9CB __libc_start_main+255 6737 0x080494C1 _start+33 6738 6739 This shows a call to `operator new[]', closely followed by a call to 6740`operator delete'. However, in C++ calls to `operator new[]' must be 6741matched by calls to `operator delete[]' and not `operator delete'. 6742Hence, the library reports this as an error and does not free the memory 6743allocation. 6744 6745 6746File: mpatrol.info, Node: Example 8, Next: Example 9, Prev: Example 7, Up: Examples 6747 6748The `alloca()' functions 6749======================== 6750 6751 There are two examples of using `alloca()' and its related functions 6752in `tests/pass/test8.c' and `tests/fail/test16.c'. Both rely on mpatrol 6753having full call stack traceback support, although they will work 6754(albeit with slightly different results) on systems that do not. 6755 6756 The first test simply illustrates the use of `alloca()' and how its 6757memory allocations are freed when they are no longer in use. 6758 6759 23 /* 6760 24 * Tests alloca() and related functions via nested function calls. 6761 25 * The final output should be a horizontal pyramid of plus signs 6762 26 * followed by a horizontal pyramid of minus signs. 6763 27 */ 6764 6765 6766 30 #include "mpatrol.h" 6767 31 #include <stdio.h> 6768 6769 6770 34 char *f1(char *s) 6771 35 { 6772 36 char *t; 6773 37 size_t l; 6774 6775 39 l = strlen(s) + 1; 6776 40 if ((t = (char *) alloca(l + 1)) == NULL) 6777 41 return NULL; 6778 42 memcpy(t, s, l); 6779 43 t[l - 1] = t[l - 2]; 6780 44 t[l] = '\0'; 6781 45 return strdup(t); 6782 46 } 6783 6784 6785 49 char *f2(char *s) 6786 50 { 6787 51 char *t; 6788 52 size_t l; 6789 6790 54 l = strlen(s) - 1; 6791 55 if ((t = (char *) alloca(l + 1)) == NULL) 6792 56 return NULL; 6793 57 memcpy(t, s, l + 1); 6794 58 t[l] = '\0'; 6795 59 return strdup(t); 6796 60 } 6797 6798 6799 63 int f(char *s, size_t l) 6800 64 { 6801 65 char *t; 6802 66 size_t i; 6803 6804 68 puts(s); 6805 69 for (i = 0; i < l; i++) 6806 70 { 6807 71 if (((t = f1(s)) == NULL) || 6808 72 ((s = (char *) alloca(strlen(t) + 1)) == NULL)) 6809 73 return 0; 6810 74 strcpy(s, t); 6811 75 free(t); 6812 76 puts(s); 6813 77 } 6814 78 for (i = 0; i < l; i++) 6815 79 { 6816 80 if (((t = f2(s)) == NULL) || 6817 81 ((s = (char *) alloca(strlen(t) + 1)) == NULL)) 6818 82 return 0; 6819 83 strcpy(s, t); 6820 84 free(t); 6821 85 puts(s); 6822 86 } 6823 87 return 1; 6824 88 } 6825 6826 6827 91 int main(void) 6828 92 { 6829 93 char *s; 6830 6831 95 s = strdupa("+"); 6832 96 if (!f(s, 4)) 6833 97 exit(EXIT_FAILURE); 6834 98 dealloca(s); 6835 99 s = strdupa("-"); 6836 100 if (!f(s, 4)) 6837 101 exit(EXIT_FAILURE); 6838 102 dealloca(s); 6839 103 return EXIT_SUCCESS; 6840 104 } 6841 6842 When compiled and run, you should get the following output. 6843 6844 + 6845 ++ 6846 +++ 6847 ++++ 6848 +++++ 6849 ++++ 6850 +++ 6851 ++ 6852 + 6853 - 6854 -- 6855 --- 6856 ---- 6857 ----- 6858 ---- 6859 --- 6860 -- 6861 - 6862 6863 If you run it again, this time with the `MPATROL_OPTIONS' environment 6864variable set to `LOGALLOCS' and `LOGFREES', you should see the 6865following in the newly-generated `mpatrol.log' file. Note that the 6866`...' marks text that has been removed. 6867 6868 ALLOC: strdupa (1, 2 bytes, 1 byte) [main|test8.c|95] (char x 2) 6869 0x000138F0 main+52 6870 0x00013350 _start+100 6871 6872 returns 0x0008C000 6873 6874 ALLOC: alloca (2, 3 bytes, 8 bytes) [f1|test8.c|40] 6875 0x000134CC f1+76 6876 0x000136D8 f+68 6877 0x00013904 main+72 6878 0x00013350 _start+100 6879 6880 returns 0x0008C008 6881 6882 ALLOC: strdup (3, 3 bytes, 1 byte) [f1|test8.c|45] (char x 3) 6883 0x00013584 f1+260 6884 0x000136D8 f+68 6885 0x00013904 main+72 6886 0x00013350 _start+100 6887 6888 returns 0x0008C002 6889 6890 FREE: alloca (0x0008C008) [f|test8.c|72] 6891 0x00013728 f+148 6892 0x00013904 main+72 6893 0x00013350 _start+100 6894 6895 0x0008C008 (3 bytes) {alloca:2:0} [f1|test8.c|40] 6896 0x000134CC f1+76 6897 0x000136D8 f+68 6898 0x00013904 main+72 6899 0x00013350 _start+100 6900 6901 ALLOC: alloca (4, 3 bytes, 8 bytes) [f|test8.c|72] 6902 0x00013728 f+148 6903 0x00013904 main+72 6904 0x00013350 _start+100 6905 6906 returns 0x0008C008 6907 6908 ... 6909 6910 FREE: alloca (0x0008C040) [main|test8.c|102] 6911 0x000139C8 main+268 6912 0x00013350 _start+100 6913 6914 0x0008C040 (2 bytes) {alloca:50:0} [f|test8.c|81] 6915 0x00013828 f+404 6916 0x00013988 main+204 6917 0x00013350 _start+100 6918 6919 FREE: alloca (0x0008C038) [main|test8.c|102] 6920 0x000139C8 main+268 6921 0x00013350 _start+100 6922 6923 0x0008C038 (3 bytes) {alloca:47:0} [f|test8.c|81] 6924 0x00013828 f+404 6925 0x00013988 main+204 6926 0x00013350 _start+100 6927 6928 ... 6929 6930 FREE: alloca (0x0008C010) [main|test8.c|102] 6931 0x000139C8 main+268 6932 0x00013350 _start+100 6933 6934 0x0008C010 (4 bytes) {alloca:32:0} [f|test8.c|72] 6935 0x00013728 f+148 6936 0x00013988 main+204 6937 0x00013350 _start+100 6938 6939 FREE: alloca (0x0008C008) [main|test8.c|102] 6940 0x000139C8 main+268 6941 0x00013350 _start+100 6942 6943 0x0008C008 (3 bytes) {alloca:29:0} [f|test8.c|72] 6944 0x00013728 f+148 6945 0x00013988 main+204 6946 0x00013350 _start+100 6947 6948 FREE: dealloca (0x0008C000) [main|test8.c|102] 6949 0x000139C8 main+268 6950 0x00013350 _start+100 6951 6952 0x0008C000 (2 bytes) {strdupa:26:0} [main|test8.c|99] (char x 2) 6953 0x00013974 main+184 6954 0x00013350 _start+100 6955 6956 After the first call to `strdupa()', there is a call to `alloca()' 6957followed by a call to `strdup()'. Because the memory allocation made by 6958`strdupa()' is at the top level of the program it cannot automatically 6959be freed until `main()' returns. However, at the next call to 6960`alloca()' in `f()', the mpatrol library notices that the memory 6961allocation that was made by `alloca()' in `f1()' can be freed since 6962`f1()' has returned. The relevant allocation is then freed before 6963making the next memory allocation. You can see how it makes its 6964decision by examining the call stack at the point of deallocation. 6965 6966 However, all of the memory allocations made by `alloca()' in `f()' 6967cannot be freed until `f()' returns. This can be seen in the two sets 6968of eight consecutive deallocations in the log file, each set followed 6969by a call to `dealloca()'. The `dealloca()' function explicitly frees 6970a memory allocation that was made by the `alloca()' family of 6971functions, but these calls are not really necessary as all of these 6972memory allocations would be freed anyway when `main()' returns. The 6973call to `dealloca()' is really only necessary to force a deallocation 6974for a specific purpose at a certain point in the program. Note that 6975implicit deallocations are marked as being done by `alloca()' while 6976explicit deallocations are marked as being done by `dealloca()'. 6977 6978 The second test illustrates how the mpatrol library can help debug 6979`alloca()'-related problems by treating such memory allocations as 6980normal heap allocations. 6981 6982 23 /* 6983 24 * Duplicates a string using alloca() and then returns the address 6984 25 * of the allocation. This is illegal since the memory allocated 6985 26 * by alloca() will be freed when the function returns. The call 6986 27 * to memcpy() will then corrupt free memory and the call to free() 6987 28 * will attempt to free an invalid pointer. 6988 29 */ 6989 6990 6991 32 #include "mpatrol.h" 6992 33 #include <stdio.h> 6993 6994 6995 36 char *f(size_t l) 6996 37 { 6997 38 return (char *) alloca(l); 6998 39 } 6999 7000 7001 42 char *g(char *s) 7002 43 { 7003 44 char *t; 7004 45 size_t l; 7005 7006 47 l = strlen(s) + 1; 7007 48 if (t = f(l)) 7008 49 memcpy(t, s, l); 7009 50 return t; 7010 51 } 7011 7012 7013 54 int main(void) 7014 55 { 7015 56 char *s; 7016 7017 58 s = g("test"); 7018 59 free(s); 7019 60 return EXIT_SUCCESS; 7020 61 } 7021 7022 If you compile and run this example with the `MPATROL_OPTIONS' 7023environment variable containing the options `LOGALL' and `NOFREE=1' you 7024should see the following in `mpatrol.log'. 7025 7026 ALLOC: alloca (1, 5 bytes, 8 bytes) [f|test16.c|38] 7027 0x0001346C f+52 7028 0x000134A8 g+40 7029 0x00013524 main+20 7030 0x00013308 _start+100 7031 7032 returns 0x0008C000 7033 7034 FREE: alloca (0x0008C000) [g|test16.c|49] 7035 0x000134F8 g+120 7036 0x00013524 main+20 7037 0x00013308 _start+100 7038 7039 0x0008C000 (5 bytes) {alloca:1:0} [f|test16.c|38] 7040 0x0001346C f+52 7041 0x000134A8 g+40 7042 0x00013524 main+20 7043 0x00013308 _start+100 7044 7045 MEMCOPY: memcpy (0x0001F760, 0x0008C000, 5 bytes, 0x00) [g|test16.c|49] 7046 0x000134F8 g+120 7047 0x00013524 main+20 7048 0x00013308 _start+100 7049 7050 ERROR: [FRDOPN]: memcpy: attempt to perform operation on freed memory 7051 0x0008C000 (5 bytes) {alloca:1:0} [g|test16.c|49] 7052 0x000134F8 g+120 7053 0x00013524 main+20 7054 0x00013308 _start+100 7055 7056 returns 0x0008C000 7057 7058 FREE: free (0x0008C000) [main|test16.c|59] 7059 0x00013550 main+64 7060 0x00013308 _start+100 7061 7062 ERROR: [PRVFRD]: free: 0x0008C000 was freed with alloca 7063 0x0008C000 (5 bytes) {alloca:1:0} [g|test16.c|49] 7064 0x000134F8 g+120 7065 0x00013524 main+20 7066 0x00013308 _start+100 7067 7068 As you can see, memory allocations made by `alloca()' are treated in 7069almost exactly the same way as normal memory allocations, with the 7070result that errors similar to those above can be detected by the 7071mpatrol library. The only real difference between the two types of 7072memory allocations is that allocations made by the `alloca()' family of 7073functions will never show up in the list of unfreed memory allocations. 7074 7075 7076File: mpatrol.info, Node: Example 9, Next: Example 10, Prev: Example 8, Up: Examples 7077 7078The `MP_MALLOC()' functions 7079=========================== 7080 7081 The mpatrol library comes with a set of alternative dynamic memory 7082allocation functions for C. These allow it to record the type and type 7083size of every memory allocation made through these functions, which can 7084be very useful for debugging purposes. It also means that the 7085alignment for each memory allocation can be determined according to its 7086type. The following test can be found in `tests/pass/test9.c'. 7087 7088 23 /* 7089 24 * Allocates 16 floats and then resizes the allocation to 8 floats and 7090 25 * frees them. Then allocates 16 integers and resizes the allocation 7091 26 * to 32 integers before freeing them. Finally, duplicates a string 7092 27 * and then frees it. 7093 28 */ 7094 7095 7096 31 #include "mpatrol.h" 7097 7098 7099 34 int main(void) 7100 35 { 7101 36 float *f; 7102 37 int *i; 7103 38 char *s; 7104 7105 40 MP_MALLOC(f, 16, float); 7106 41 MP_REALLOC(f, 8, float); 7107 42 MP_FREE(f); 7108 43 MP_CALLOC(i, 16, int); 7109 44 MP_REALLOC(i, 32, int); 7110 45 MP_FREE(i); 7111 46 MP_STRDUP(s, "test"); 7112 47 MP_FREE(s); 7113 48 return EXIT_SUCCESS; 7114 49 } 7115 7116 If this test is compiled and linked with the mpatrol library and 7117then run with the `LOGALL' option, the following output will be seen in 7118the mpatrol log file. 7119 7120 ALLOC: xmalloc (84, 64 bytes, 4 bytes) [main|test9.c|40] (float x 16) 7121 0x0804AC36 main+38 7122 0x400A09CB __libc_start_main+255 7123 0x0804AB81 _start+33 7124 7125 returns 0x080510E8 7126 7127 REALLOC: xrealloc (0x080510E8, 32 bytes, 4 bytes) [main|test9.c|41] (float x 8) 7128 0x0804AC60 main+80 7129 0x400A09CB __libc_start_main+255 7130 0x0804AB81 _start+33 7131 7132 0x080510E8 (64 bytes) {xmalloc:84:0} [main|test9.c|40] (float x 16) 7133 0x0804AC36 main+38 7134 0x400A09CB __libc_start_main+255 7135 0x0804AB81 _start+33 7136 7137 returns 0x080510E8 7138 7139 FREE: xfree (0x080510E8) [main|test9.c|42] 7140 0x0804AC7F main+111 7141 0x400A09CB __libc_start_main+255 7142 0x0804AB81 _start+33 7143 7144 0x080510E8 (32 bytes) {xrealloc:84:1} [main|test9.c|41] (float x 8) 7145 0x0804AC60 main+80 7146 0x400A09CB __libc_start_main+255 7147 0x0804AB81 _start+33 7148 7149 ALLOC: xcalloc (85, 64 bytes, 4 bytes) [main|test9.c|43] (int x 16) 7150 0x0804ACB2 main+162 7151 0x400A09CB __libc_start_main+255 7152 0x0804AB81 _start+33 7153 7154 returns 0x080510E8 7155 7156 REALLOC: xrealloc (0x080510E8, 128 bytes, 4 bytes) [main|test9.c|44] (int x 32) 7157 0x0804ACDF main+207 7158 0x400A09CB __libc_start_main+255 7159 0x0804AB81 _start+33 7160 7161 0x080510E8 (64 bytes) {xcalloc:85:0} [main|test9.c|43] (int x 16) 7162 0x0804ACB2 main+162 7163 0x400A09CB __libc_start_main+255 7164 0x0804AB81 _start+33 7165 7166 returns 0x080510E8 7167 7168 FREE: xfree (0x080510E8) [main|test9.c|45] 7169 0x0804ACFE main+238 7170 0x400A09CB __libc_start_main+255 7171 0x0804AB81 _start+33 7172 7173 0x080510E8 (128 bytes) {xrealloc:85:1} [main|test9.c|44] (int x 32) 7174 0x0804ACDF main+207 7175 0x400A09CB __libc_start_main+255 7176 0x0804AB81 _start+33 7177 7178 ALLOC: xstrdup (86, 5 bytes, 1 byte) [main|test9.c|46] (char x 5) 7179 0x0804AD2E main+286 7180 0x400A09CB __libc_start_main+255 7181 0x0804AB81 _start+33 7182 7183 returns 0x080510E5 7184 7185 FREE: xfree (0x080510E5) [main|test9.c|47] 7186 0x0804AD4F main+319 7187 0x400A09CB __libc_start_main+255 7188 0x0804AB81 _start+33 7189 7190 0x080510E5 (5 bytes) {xstrdup:86:0} [main|test9.c|46] (char x 5) 7191 0x0804AD2E main+286 7192 0x400A09CB __libc_start_main+255 7193 0x0804AB81 _start+33 7194 7195 As you can see, the type and number of items allocated of that type 7196are associated with each memory allocation. The function names that 7197are logged as having made the memory allocations are from the 7198`xmalloc()' family of functions since that is how the `MP_MALLOC()' 7199family of functions are implemented. 7200 7201 7202File: mpatrol.info, Node: Example 10, Prev: Example 9, Up: Examples 7203 7204Additional useful information 7205============================= 7206 7207 This last example illustrates the various `SHOW' options that are 7208available for displaying additional information from the mpatrol 7209library at program termination. It also shows how to easily detect 7210memory leaks. Use the `OFLOWSIZE=16', `NOFREE=16' and `SHOWALL' 7211options in `MPATROL_OPTIONS' before running. 7212 7213 1 /* 7214 2 * Introduces a memory leak by clobbering a pointer with a new 7215 3 * memory allocation. Use with SHOWUNFREED to display it. 7216 4 */ 7217 7218 7219 7 #include "mpatrol.h" 7220 7221 7222 10 int main(void) 7223 11 { 7224 12 void *p; 7225 7226 14 p = malloc(4); 7227 15 p = malloc(4); 7228 16 if (p != NULL) 7229 17 free(p); 7230 18 return EXIT_SUCCESS; 7231 19 } 7232 7233 The information that we are interested in comes after the summary of 7234library statistics generated in the log file. The first block of data 7235shows a memory map of the heap that is being handled by mpatrol. This 7236can be used to see graphically where a particular allocation is 7237located, or to look for memory fragmentation. The `SHOWMAP' option 7238also displays this information. 7239 7240 Note that gaps in the memory map can either be due to space used by 7241internal memory blocks or to some other memory allocation library using 7242up space. On some systems that don't have virtual memory, gaps are 7243likely to be owned by other processes or belong to the system free 7244memory list. The `...' marks text that has been removed. 7245 7246 memory map: 7247 ... 7248 / 0x0002FDD0-0x0002FDDF overflow (16 bytes) 7249 |+ 0x0002FDE0-0x0002FE03 allocated (36 bytes) {calloc:13:0} [-|-|-] 7250 \ 0x0002FE04-0x0002FE13 overflow (16 bytes) 7251 --- 0x0002FE14-0x0002FE17 free (4 bytes) 7252 / 0x0002FE18-0x0002FE27 overflow (16 bytes) 7253 |+ 0x0002FE28-0x0002FF18 allocated (241 bytes) {calloc:15:0} [-|-|-] 7254 \ 0x0002FF19-0x0002FF28 overflow (16 bytes) 7255 --- 0x0002FF29-0x0002FF2F free (7 bytes) 7256 / 0x0002FF30-0x0002FF3F overflow (16 bytes) 7257 |+ 0x0002FF40-0x0002FF93 allocated (84 bytes) {calloc:16:0} [-|-|-] 7258 \ 0x0002FF94-0x0002FFA3 overflow (16 bytes) 7259 --- 0x0002FFA4-0x0002FFA7 free (4 bytes) 7260 / 0x0002FFA8-0x0002FFB7 overflow (16 bytes) 7261 |+ 0x0002FFB8-0x0002FFC4 allocated (13 bytes) {calloc:17:0} [-|-|-] 7262 \ 0x0002FFC5-0x0002FFD4 overflow (16 bytes) 7263 --- 0x0002FFD5-0x0002FFD7 free (3 bytes) 7264 / 0x0002FFD8-0x0002FFE7 overflow (16 bytes) 7265 |+ 0x0002FFE8-0x0002FFEB allocated (4 bytes) {malloc:19:0} [main|test.c|14] 7266 \ 0x0002FFEC-0x0002FFFB overflow (16 bytes) 7267 --- 0x0002FFFC-0x0002FFFF free (4 bytes) 7268 --------------------- gap (57344 bytes) 7269 / 0x0003E000-0x0003E00F overflow (16 bytes) 7270 |+ 0x0003E010-0x0003EFFF freed (4080 bytes) {free:6:0} [-|-|-] 7271 \ 0x0003F000-0x0003F00F overflow (16 bytes) 7272 / 0x0003F010-0x0003F01F overflow (16 bytes) 7273 |+ 0x0003F020-0x0003F707 freed (1768 bytes) {free:12:0} [-|-|-] 7274 \ 0x0003F708-0x0003F717 overflow (16 bytes) 7275 --- 0x0003F718-0x0003FFFF free (2280 bytes) 7276 --------------------- gap (16384 bytes) 7277 / 0x00044000-0x0004400F overflow (16 bytes) 7278 |+ 0x00044010-0x00045197 freed (4488 bytes) {free:8:0} [-|-|-] 7279 \ 0x00045198-0x000451A7 overflow (16 bytes) 7280 / 0x000451A8-0x000451B7 overflow (16 bytes) 7281 |+ 0x000451B8-0x000459AF freed (2040 bytes) {free:10:0} [-|-|-] 7282 \ 0x000459B0-0x000459BF overflow (16 bytes) 7283 / 0x000459C0-0x000459CF overflow (16 bytes) 7284 |+ 0x000459D0-0x00045D93 allocated (964 bytes) {calloc:14:0} [-|-|-] 7285 \ 0x00045D94-0x00045DA3 overflow (16 bytes) 7286 / 0x00045DA4-0x00045DB3 overflow (16 bytes) 7287 |+ 0x00045DB4-0x00045DCE allocated (27 bytes) {strdup:18:0} [-|-|-] 7288 \ 0x00045DCF-0x00045DDE overflow (16 bytes) 7289 --- 0x00045DDF-0x00045DDF free (1 byte) 7290 / 0x00045DE0-0x00045DEF overflow (16 bytes) 7291 |+ 0x00045DF0-0x00045DF3 freed (4 bytes) {free:20:0} [main|test.c|17] 7292 \ 0x00045DF4-0x00045E03 overflow (16 bytes) 7293 --- 0x00045E04-0x00045FFF free (508 bytes) 7294 7295 The next block of data shows a summary of all the symbols that could 7296be read from the program's executable file and/or any shared libraries 7297that the program requires. This can be useful to see which symbols 7298have actually been read by the mpatrol library. The `SHOWSYMBOLS' 7299option also displays this information. 7300 7301 Note that the following data has been dramatically cut down in size 7302for the purposes of this example. The `...' marks text that has been 7303removed. 7304 7305 symbols read: 3300 7306 0x000108B0 _ex_text0 [a.out] (0 bytes) 7307 0x000108B0-0x0001097F _start [a.out] (208 bytes) 7308 0x00010990-0x00010A27 main [a.out] (152 bytes) 7309 0x00010A28 _ex_text1 [a.out] (0 bytes) 7310 0x00010A28-0x00010A77 _init [a.out] (80 bytes) 7311 0x00010A78-0x00010AC7 _fini [a.out] (80 bytes) 7312 0x7FA1FFF8 _ex_text0 [/usr/lib/libc.so.1] (0 bytes) 7313 0x7FA1FFF8-0x7FA2005F atexit [/usr/lib/libc.so.1] (104 bytes) 7314 0x7FA20060-0x7FA200EF _exithandle [/usr/lib/libc.so.1] (144 bytes) 7315 0x7FA20470-0x7FA204EB __dtou [/usr/lib/libc.so.1] (124 bytes) 7316 0x7FA20500-0x7FA20577 __ftou [/usr/lib/libc.so.1] (120 bytes) 7317 0x7FA2083C-0x7FA20B2F __div64 [/usr/lib/libc.so.1] (756 bytes) 7318 0x7FA20B30-0x7FA20DEB __rem64 [/usr/lib/libc.so.1] (700 bytes) 7319 ... 7320 0x7FA96858-0x7FA96867 getpid [/usr/lib/libc.so.1] (16 bytes) 7321 0x7FA96858-0x7FA96867 _getpid [/usr/lib/libc.so.1] (16 bytes) 7322 0x7FA96868-0x7FA9689F _kill [/usr/lib/libc.so.1] (56 bytes) 7323 0x7FA96868-0x7FA9689F _libc_kill [/usr/lib/libc.so.1] (56 bytes) 7324 0x7FA968A0 _ex_text1 [/usr/lib/libc.so.1] (0 bytes) 7325 0x7FA968A0-0x7FA968DF _init [/usr/lib/libc.so.1] (64 bytes) 7326 0x7FA968E0-0x7FA9691F _fini [/usr/lib/libc.so.1] (64 bytes) 7327 0x7FB105E4-0x7FB1069F memmove [/usr/lib/libc_psr.so.1] (188 bytes) 7328 0x7FB105E4-0x7FB1069F _memmove [/usr/lib/libc_psr.so.1] (188 bytes) 7329 0x7FB106A0 forcpy [/usr/lib/libc_psr.so.1] (0 bytes) 7330 0x7FB106A0-0x7FB1190B memcpy [/usr/lib/libc_psr.so.1] (4716 bytes) 7331 0x7FB106A0-0x7FB1190B _memcpy [/usr/lib/libc_psr.so.1] (4716 bytes) 7332 0x7FB106A0-0x7FB1190B __align_cpy_1 [/usr/lib/libc_psr.so.1] (4716 bytes) 7333 ... 7334 0x7FB135B0-0x7FB135D3 __div64 [/usr/lib/libc_psr.so.1] (36 bytes) 7335 0x7FB135D4-0x7FB135F7 __udiv64 [/usr/lib/libc_psr.so.1] (36 bytes) 7336 0x7FB135F8-0x7FB1362B __umul64 [/usr/lib/libc_psr.so.1] (52 bytes) 7337 0x7FB135F8-0x7FB1362B __mul64 [/usr/lib/libc_psr.so.1] (52 bytes) 7338 0x7FB1362C-0x7FB13657 __urem64 [/usr/lib/libc_psr.so.1] (44 bytes) 7339 0x7FB13658-0x7FB13683 __rem64 [/usr/lib/libc_psr.so.1] (44 bytes) 7340 0x7FB333F8 _ex_text0 [/usr/lib/libelf.so.1] (0 bytes) 7341 0x7FB333F8-0x7FB3346F _elf32_entsz [/usr/lib/libelf.so.1] (120 bytes) 7342 0x7FB33470-0x7FB334EB elf32_fsize [/usr/lib/libelf.so.1] (124 bytes) 7343 0x7FB33470-0x7FB334EB _elf32_fsize [/usr/lib/libelf.so.1] (124 bytes) 7344 0x7FB334EC-0x7FB3352F _elf32_msize [/usr/lib/libelf.so.1] (68 bytes) 7345 0x7FB33530-0x7FB335D3 _elf32_mtype [/usr/lib/libelf.so.1] (164 bytes) 7346 ... 7347 0x7FB49054-0x7FB4921F _elf_nlist [/usr/lib/libelf.so.1] (460 bytes) 7348 0x7FB49220-0x7FB4932F nlist [/usr/lib/libelf.so.1] (272 bytes) 7349 0x7FB49330-0x7FB493E3 _elf_findop [/usr/lib/libelf.so.1] (180 bytes) 7350 0x7FB493E4 _ex_text1 [/usr/lib/libelf.so.1] (0 bytes) 7351 0x7FB493E4-0x7FB4941B _init [/usr/lib/libelf.so.1] (56 bytes) 7352 0x7FB4941C-0x7FB49453 _fini [/usr/lib/libelf.so.1] (56 bytes) 7353 0x7FB65818-0x7FB6582F __mp_newlist [/usr/lib/libmpatrol.so.1.3] (24 bytes) 7354 0x7FB65830-0x7FB65853 __mp_addhead [/usr/lib/libmpatrol.so.1.3] (36 bytes) 7355 0x7FB65854-0x7FB6587B __mp_addtail [/usr/lib/libmpatrol.so.1.3] (40 bytes) 7356 0x7FB6587C-0x7FB6589F __mp_prepend [/usr/lib/libmpatrol.so.1.3] (36 bytes) 7357 0x7FB658A0-0x7FB658C3 __mp_insert [/usr/lib/libmpatrol.so.1.3] (36 bytes) 7358 0x7FB658C4-0x7FB658EB __mp_remove [/usr/lib/libmpatrol.so.1.3] (40 bytes) 7359 ... 7360 0x7FB725F4-0x7FB7262B memmem [/usr/lib/libmpatrol.so.1.3] (56 bytes) 7361 0x7FB7262C-0x7FB72663 _memmem [/usr/lib/libmpatrol.so.1.3] (56 bytes) 7362 0x7FB72664-0x7FB72697 memcmp [/usr/lib/libmpatrol.so.1.3] (52 bytes) 7363 0x7FB72698-0x7FB726CB _memcmp [/usr/lib/libmpatrol.so.1.3] (52 bytes) 7364 0x7FB726CC-0x7FB726FF bcmp [/usr/lib/libmpatrol.so.1.3] (52 bytes) 7365 0x7FB72700-0x7FB72733 _bcmp [/usr/lib/libmpatrol.so.1.3] (52 bytes) 7366 0x7FB9085C-0x7FB90863 dlinfo [/usr/lib/libdl.so.1] (8 bytes) 7367 0x7FB9085C-0x7FB90863 _dlinfo [/usr/lib/libdl.so.1] (8 bytes) 7368 0x7FB90864-0x7FB9086B dlmap [/usr/lib/libdl.so.1] (8 bytes) 7369 0x7FB90864-0x7FB9086B _dlmap [/usr/lib/libdl.so.1] (8 bytes) 7370 0x7FB9086C-0x7FB90873 dlmopen [/usr/lib/libdl.so.1] (8 bytes) 7371 0x7FB9086C-0x7FB90873 _dlmopen [/usr/lib/libdl.so.1] (8 bytes) 7372 ... 7373 0x7FB90894-0x7FB9089B dladdr [/usr/lib/libdl.so.1] (8 bytes) 7374 0x7FB90894-0x7FB9089B _dladdr [/usr/lib/libdl.so.1] (8 bytes) 7375 0x7FB9089C-0x7FB908A3 dldump [/usr/lib/libdl.so.1] (8 bytes) 7376 0x7FB9089C-0x7FB908A3 _dldump [/usr/lib/libdl.so.1] (8 bytes) 7377 0x7FB908A4-0x7FB908AB _ld_concurrency [/usr/lib/libdl.so.1] (8 bytes) 7378 0x7FB908AC-0x7FB908B3 bind_guard [/usr/lib/libdl.so.1] (8 bytes) 7379 7380 The next table is really only useful for seeing how much memory 7381fragmentation has occurred in the memory map. It shows a breakdown of 7382the free memory blocks that have either resulted from the mpatrol 7383library allocating uninitialised memory from the system heap or from 7384freeing existing memory allocations. The column on the left shows the 7385size of the free block in bytes and the column on the right shows the 7386number of blocks of that size that are available. The `SHOWFREE' 7387option also displays this information. 7388 7389 free blocks: 10 (2919 bytes) 7390 2280: 1 7391 508: 1 7392 76: 1 7393 32: 1 7394 7: 1 7395 4: 3 7396 3: 1 7397 1: 1 7398 7399 The next block of data shows a summary of all freed memory 7400allocations. This is only possible because the `NOFREE' option was 7401also given, otherwise there would be no details on freed memory 7402allocations. All of these entries show where the allocation was freed, 7403which can be useful if you quickly needed to see where an allocation 7404was freed. The `SHOWFREED' option also displays this information. 7405Note that the list will be limited to the size of the freed queue and 7406will show only the most recently-freed items. 7407 7408 As this example was run on UNIX, the mpatrol library replaces the 7409default implementations of `malloc()', `free()', etc. As can be seen 7410below, this allows the library to trace all calls to allocate dynamic 7411memory in a process, even from functions that were not compiled with 7412mpatrol. Four of the five functions shown below were called by the 7413mpatrol library in order to read the symbols from ELF object files. 7414However, they are located in the ELF access library which was not 7415compiled with mpatrol. 7416 7417 Note that the following data has again been cut down in size for the 7418purposes of this example. The `...' marks text that has been removed. 7419 7420 freed allocations: 13 (19756 bytes) 7421 0x0002E010 (232 bytes) {free:1:0} [-|-|-] 7422 0x7FB3E5BC _elf_end+776 7423 0x7FB6B3D4 __mp_addsymbols+440 7424 0x7FB6FF5C __mp_init+208 7425 0x7FB701FC __mp_alloc+84 7426 0x000109B8 main+40 7427 0x00010970 _start+192 7428 7429 0x0002E118 (3536 bytes) {free:2:0} [-|-|-] 7430 0x7FB3E450 _elf_end+412 7431 0x7FB6B3D4 __mp_addsymbols+440 7432 0x7FB6FF5C __mp_init+208 7433 0x7FB701FC __mp_alloc+84 7434 0x000109B8 main+40 7435 0x00010970 _start+192 7436 7437 0x0002EF08 (232 bytes) {free:3:0} [-|-|-] 7438 0x7FB3E5BC _elf_end+776 7439 0x7FB6B3D4 __mp_addsymbols+440 7440 0x7FB6B4B4 __mp_addextsymbols+208 7441 0x7FB6FF64 __mp_init+216 7442 0x7FB701FC __mp_alloc+84 7443 0x000109B8 main+40 7444 0x00010970 _start+192 7445 7446 0x0002F010 (2448 bytes) {free:4:0} [-|-|-] 7447 0x7FB3E450 _elf_end+412 7448 0x7FB6B3D4 __mp_addsymbols+440 7449 0x7FB6B4B4 __mp_addextsymbols+208 7450 0x7FB6FF64 __mp_init+216 7451 0x7FB701FC __mp_alloc+84 7452 0x000109B8 main+40 7453 0x00010970 _start+192 7454 7455 ... 7456 7457 0x00045DF0 (4 bytes) {free:20:0} [main|test.c|17] 7458 0x00010A14 main+132 7459 0x00010970 _start+192 7460 7461 The final block of data shows a summary of all unfreed memory 7462allocations. This can show up memory leaks, although all but one of 7463the unfreed memory allocations in this example come from the standard C 7464library. On systems such as UNIX it does not really matter about these 7465unfreed allocations since they will automatically be returned to the 7466system on process termination. 7467 7468 However, the other unfreed allocation shows an example of a memory 7469leak, where no pointers referencing that allocation remain in the 7470program to free it with. If this was within a loop then the program 7471could quickly run away with memory, causing at least a decrease in 7472performance, and at most a memory shortage. The mpatrol library makes 7473it easier to spot memory leaks, especially if the `PROF' profiling 7474option is used. 7475 7476 The `SHOWUNFREED' option also displays this information. 7477 7478 unfreed allocations: 7 (1369 bytes) 7479 0x0002FDE0 (36 bytes) {calloc:13:0} [-|-|-] 7480 0x7FA54B7C _tzload+56 7481 0x7FA53990 _ltzset_u+444 7482 0x7FA52D98 localtime_u+28 7483 0x7FA3AF20 ctime+12 7484 0x7FB6D05C __mp_printversion+184 7485 0x7FB6FFA0 __mp_init+276 7486 0x7FB701FC __mp_alloc+84 7487 0x000109B8 main+40 7488 0x00010970 _start+192 7489 7490 0x0002FE28 (241 bytes) {calloc:15:0} [-|-|-] 7491 0x7FA54E3C _tzload+760 7492 0x7FA53990 _ltzset_u+444 7493 0x7FA52D98 localtime_u+28 7494 0x7FA3AF20 ctime+12 7495 0x7FB6D05C __mp_printversion+184 7496 0x7FB6FFA0 __mp_init+276 7497 0x7FB701FC __mp_alloc+84 7498 0x000109B8 main+40 7499 0x00010970 _start+192 7500 7501 0x0002FF40 (84 bytes) {calloc:16:0} [-|-|-] 7502 0x7FA54E64 _tzload+800 7503 0x7FA53990 _ltzset_u+444 7504 0x7FA52D98 localtime_u+28 7505 0x7FA3AF20 ctime+12 7506 0x7FB6D05C __mp_printversion+184 7507 0x7FB6FFA0 __mp_init+276 7508 0x7FB701FC __mp_alloc+84 7509 0x000109B8 main+40 7510 0x00010970 _start+192 7511 7512 0x0002FFB8 (13 bytes) {calloc:17:0} [-|-|-] 7513 0x7FA54EE8 _tzload+932 7514 0x7FA53990 _ltzset_u+444 7515 0x7FA52D98 localtime_u+28 7516 0x7FA3AF20 ctime+12 7517 0x7FB6D05C __mp_printversion+184 7518 0x7FB6FFA0 __mp_init+276 7519 0x7FB701FC __mp_alloc+84 7520 0x000109B8 main+40 7521 0x00010970 _start+192 7522 7523 0x0002FFE8 (4 bytes) {malloc:19:0} [main|test.c|14] 7524 0x000109B8 main+40 7525 0x00010970 _start+192 7526 7527 ... 7528 7529 Beginning with mpatrol release 1.4.2, the `LEAKTABLE' option is 7530available to summarise the above unfreed memory allocations without 7531including the internal memory allocations that were made when the 7532mpatrol library was initialised. If you add the `LEAKTABLE' option to 7533the `MPATROL_OPTIONS' environment variable and then re-run the program 7534you should see the following in the mpatrol log file: 7535 7536 top 1 unfreed memory entry in leak table: 7537 7538 bytes count location 7539 -------- ------ -------- 7540 4 1 test.c line 14 7541 4 1 total 7542 7543 7544File: mpatrol.info, Node: Tutorial, Next: Functions, Prev: Examples, Up: Top 7545 7546Tutorial 7547******** 7548 7549 In this chapter we'll look at a real example of using the mpatrol 7550library to debug a program. All of the following building and 7551debugging steps were performed on an Intel Linux machine so the details 7552may differ slightly on your system, but the concepts should remain the 7553same. However, on systems without virtual memory some of the steps may 7554actually cause the machine to lock up or crash so be aware of this if 7555you are running such a system -- you may be safer just reading this 7556tutorial rather than attempting it! 7557 7558 This tutorial will also make use of the option `USEDEBUG' which 7559displays source-level file names and line numbers associated with 7560symbols in call stack tracebacks, but only if the underlying object 7561file access library supports reading line tables from object files and 7562even then only if the object files were compiled with debugging 7563information enabled. Alternatively, you may be able to use the `mpsym' 7564command to obtain such information instead. 7565 7566 The program we are going to look at is a simple filter which 7567processes its standard input and displays the processed information on 7568its standard output. In this case the program converts all lowercase 7569characters to uppercase and removes any blank lines. The source for 7570the program is given below, but can also be found in 7571`tests/tutorial/test1.c'. 7572 7573 23 /* 7574 24 * Reads the standard input file stream, converts all lowercase 7575 25 * characters to uppercase, and displays all non-empty lines to the 7576 26 * standard output file stream. 7577 27 */ 7578 7579 7580 30 #include <stdio.h> 7581 31 #include <stdlib.h> 7582 32 #include <string.h> 7583 33 #include <ctype.h> 7584 7585 7586 36 char *strtoupper(char *s) 7587 37 { 7588 38 char *t; 7589 39 size_t i, l; 7590 7591 41 l = strlen(s); 7592 42 t = (char *) malloc(l); 7593 43 for (i = 0; i < l; i++) 7594 44 t[i] = toupper(s[i]); 7595 45 t[i] = '\0'; 7596 46 return t; 7597 47 } 7598 7599 7600 50 int main(void) 7601 51 { 7602 52 char *b, *s; 7603 7604 54 b = (char *) malloc(BUFSIZ); 7605 55 while (gets(b)) 7606 56 { 7607 57 s = strtoupper(b); 7608 58 if (*s != '\0') 7609 59 { 7610 60 puts(s); 7611 61 free(s); 7612 62 } 7613 63 } 7614 64 free(b); 7615 65 return EXIT_SUCCESS; 7616 66 } 7617 7618 If you quickly skimmed over the above code then you might have 7619noticed some rather obvious errors, but there are also some less 7620obvious ones hidden there as well. After compiling and linking with 7621the system C compiler and libraries it successfully runs, even when its 7622source code is piped to it. So if it runs, why bother trying to debug 7623it? 7624 7625 The short answer to that is that this program does in fact contain 7626one rather major error that is likely to prevent it from running 7627portably on other systems. However, for the purposes of this tutorial, 7628we'll pretend that we've just been handed the source code for this 7629program and have not worked on it before. So let's now try to compile 7630and link it with the mpatrol library(1). 7631 7632 First, add the inclusion of `mpatrol.h' to line 34 so that we can 7633replace calls to `malloc()' and `free()' with their mpatrol 7634equivalents(2). Then, recompile the program and link it with the 7635mpatrol library. This time, running it with the `CHECK=-' option and 7636even the simplest of non-empty input lines should cause it to abort! 7637 7638 If you look at the `mpatrol.log' file produced, you should see 7639something along the lines of the following at the end of the log file. 7640 7641 ERROR: [FRECOR]: free memory corruption at 0x08067FF6 7642 0x08067FF6 00555555 55555555 5555 .UUUUUUUUU 7643 7644 This tells us that something has written a zero byte into free 7645memory at location `0x08067FF6'. Unfortunately, the library only 7646caught it at the next call to one of its functions so it had already 7647happened somewhere in between the last call and the current call. 7648Turning on the `LOGALL' option in the `MPATROL_OPTIONS' environment 7649variable allows us to see the last successful function call to the 7650mpatrol library. 7651 7652 ALLOC: malloc (56, 8192 bytes, 4 bytes) [main|test1.c|54] 7653 0x0804960E main+34 at test1.c:54 7654 0x4007C9CB __libc_start_main+255 7655 0x080494D1 _start+33 7656 7657 returns 0x080F0B48 7658 7659 ALLOC: malloc (68, 2 bytes, 4 bytes) [strtoupper|test1.c|42] 7660 0x08049592 strtoupper+50 at test1.c:42 7661 0x08049631 main+69 at test1.c:57 7662 0x4007C9CB __libc_start_main+255 7663 0x080494D1 _start+33 7664 7665 returns 0x08067FF4 7666 7667 Unfortunately, this only tells us that the last successful mpatrol 7668library function call was `malloc()' called from `strtoupper()'. If we 7669add the option `OFLOWSIZE=8' to the `MPATROL_OPTIONS' environment 7670variable then we get slightly more information about which memory 7671allocation was affected(3). 7672 7673 ERROR: [ALLOVF]: allocation 0x08071E34 has a corrupted overflow buffer at 7674 0x08071E36 7675 0x08071E36 00AAAAAA AAAAAAAA ........ 7676 7677 0x08071E34 (2 bytes) {malloc:68:0} [strtoupper|test1.c|42] 7678 0x08049592 strtoupper+50 at test1.c:42 7679 0x08049631 main+69 at test1.c:57 7680 0x4007C9CB __libc_start_main+255 7681 0x080494D1 _start+33 7682 7683 Now we can make a better guess about what is happening. Since the 7684start of the upper overflow buffer of allocation 68 has been written 7685to, we can assume that something has written one byte beyond the end of 7686that memory allocation. You can probably see where that is happening 7687now by looking at the code, but let's try to be even more sure that 7688this is what is wrong. 7689 7690 The only foolproof way to do this is to add a watch point to keep an 7691eye on the address that is being written to. This can normally only be 7692done within a debugger, but on systems that support programmable 7693software watch points, the `OFLOWWATCH' option can be used to do the 7694same thing. For the sake of generality, we'll use the debugger watch 7695point approach, in this case with `gdb'. In order for the following 7696example to work correctly you'll need to add the `ALLOCSTOP=68' option 7697to the `MPATROL_OPTIONS' environment variable so that we can stop just 7698after the last successful memory allocation. 7699 7700 (gdb) break main 7701 Breakpoint 1 at 0x80495f2: file test1.c, line 54. 7702 (gdb) run <test1.c 7703 Starting program: a.out 7704 Breakpoint 1, main() at test1.c:54 7705 54 b = (char *) malloc(BUFSIZ); 7706 (gdb) break __mp_trap 7707 Breakpoint 2 at 0x804f083 7708 (gdb) continue 7709 Continuing. 7710 Breakpoint 2, 0x804f083 in __mp_trap() 7711 (gdb) backtrace 7712 #0 0x804f083 in __mp_trap() 7713 #1 0x804c81b in __mp_getmemory() 7714 #2 0x8049a94 in __mp_alloc() 7715 #3 0x8049592 in strtoupper(s=0x80f0be0 "/*") at test1.c:42 7716 #4 0x8049631 in main() at test1.c:57 7717 (gdb) step 7718 Single stepping until exit from function __mp_trap, 7719 which has no line number information. 7720 0x804c81b in __mp_getmemory() 7721 (gdb) step 7722 Single stepping until exit from function __mp_getmemory, 7723 which has no line number information. 7724 0x8049a94 in __mp_alloc() 7725 (gdb) step 7726 Single stepping until exit from function __mp_alloc, 7727 which has no line number information. 7728 strtoupper(s=0x80f0be0 "/*") at test1.c:43 7729 43 for (i = 0; i < l; i++) 7730 (gdb) watch *0x8071e36 7731 Hardware watchpoint 3: *134684214 7732 (gdb) continue 7733 Continuing. 7734 Hardware watchpoint 3: *134684214 7735 Old value = -1431655766 7736 New value = -1431655936 7737 strtoupper(s=0x80f0be0 "/*") at test1.c:46 7738 46 return t; 7739 (gdb) quit 7740 The program is running. Exit anyway? (y or n) y 7741 7742 After loading the program into `gdb', we need to break at `main()' 7743so that we can run to a point where all of the shared library symbols 7744have been loaded into memory(4). We can then set another breakpoint at 7745`__mp_trap()' and continue until allocation 68 has been reached. 7746 7747 Because the mpatrol library has not been built with debugging 7748information in this example we can quickly step back to the 7749`strtoupper()' function since `gdb' won't step through functions that 7750have no debugging information. We then set a watch point on address 7751`0x8071e36', which is the address of the memory location that has been 7752causing the problems. After continuing, the debugger stops at line 46, 7753but this is more likely to be line 45 since that is where a zero byte 7754is being written to(5). 7755 7756 So, we have located the problem, which is simply a case of not 7757allocating enough memory to contain the copied string _and_ the 7758terminating zero byte. We can also improve the `strtoupper()' function 7759by checking the pointer returned by `malloc()' to see if it is `NULL', 7760and if so simply exit with an error. You can try running the program 7761with the `FAILFREQ' option to see how it would originally behave in a 7762low memory situation. 7763 7764 The following listing shows the above modifications that we have 7765made to our program. It can also be found in `tests/tutorial/test2.c'. 7766 7767 23 /* 7768 24 * Reads the standard input file stream, converts all lowercase 7769 25 * characters to uppercase, and displays all non-empty lines to the 7770 26 * standard output file stream. 7771 27 */ 7772 7773 7774 30 #include <stdio.h> 7775 31 #include <stdlib.h> 7776 32 #include <string.h> 7777 33 #include <ctype.h> 7778 34 #include "mpatrol.h" 7779 7780 7781 37 char *strtoupper(char *s) 7782 38 { 7783 39 char *t; 7784 40 size_t i, l; 7785 7786 42 l = strlen(s); 7787 43 if ((t = (char *) malloc(l + 1)) == NULL) 7788 44 { 7789 45 fputs("strtoupper: out of memory\n", stderr); 7790 46 exit(EXIT_FAILURE); 7791 47 } 7792 48 for (i = 0; i < l; i++) 7793 49 t[i] = toupper(s[i]); 7794 50 t[i] = '\0'; 7795 51 return t; 7796 52 } 7797 7798 7799 55 int main(void) 7800 56 { 7801 57 char *b, *s; 7802 7803 59 b = (char *) malloc(BUFSIZ); 7804 60 while (gets(b)) 7805 61 { 7806 62 s = strtoupper(b); 7807 63 if (*s != '\0') 7808 64 { 7809 65 puts(s); 7810 66 free(s); 7811 67 } 7812 68 } 7813 69 free(b); 7814 70 return EXIT_SUCCESS; 7815 71 } 7816 7817 Leaving aside the obvious problem with `gets()' and the general 7818inefficiency of the algorithm, we could assume that our program works 7819safely now and we can release it to the outside world. However, a user 7820soon reports a problem with our program steadily using more and more 7821memory during its execution when processing very large files. 7822 7823 This is generally attributable to a memory leak and so we can use the 7824`SHOWUNFREED' option to try to detect where the memory leak is coming 7825from. Following is some example output from the mpatrol log file when 7826our program is run and is given a relatively small text file as input. 7827 7828 unfreed allocations: 10 (185 bytes) 7829 0x08062000 (176 bytes) {malloc:1:0} [-|-|-] 7830 0x400B681B __new_fopen+27 7831 0x0804F24E __mp_openlogfile+70 7832 0x080497B5 __mp_init+109 7833 0x08049973 __mp_alloc+31 7834 0x0804962E main+34 at test2.c:59 7835 0x4007C9CB __libc_start_main+255 7836 0x080494D1 _start+33 7837 7838 0x08067FF4 (1 byte) {malloc:83:0} [strtoupper|test2.c|43] 7839 0x08049593 strtoupper+51 at test2.c:43 7840 0x08049651 main+69 at test2.c:62 7841 0x4007C9CB __libc_start_main+255 7842 0x080494D1 _start+33 7843 7844 0x08067FF8 (1 byte) {malloc:89:0} [strtoupper|test2.c|43] 7845 0x08049593 strtoupper+51 at test2.c:43 7846 0x08049651 main+69 at test2.c:62 7847 0x4007C9CB __libc_start_main+255 7848 0x080494D1 _start+33 7849 7850 0x08067FFC (1 byte) {malloc:90:0} [strtoupper|test2.c|43] 7851 0x08049593 strtoupper+51 at test2.c:43 7852 0x08049651 main+69 at test2.c:62 7853 0x4007C9CB __libc_start_main+255 7854 0x080494D1 _start+33 7855 7856 0x0808B304 (1 byte) {malloc:95:0} [strtoupper|test2.c|43] 7857 0x08049593 strtoupper+51 at test2.c:43 7858 0x08049651 main+69 at test2.c:62 7859 0x4007C9CB __libc_start_main+255 7860 0x080494D1 _start+33 7861 7862 0x0808B308 (1 byte) {malloc:96:0} [strtoupper|test2.c|43] 7863 0x08049593 strtoupper+51 at test2.c:43 7864 0x08049651 main+69 at test2.c:62 7865 0x4007C9CB __libc_start_main+255 7866 0x080494D1 _start+33 7867 7868 0x0808B30C (1 byte) {malloc:101:0} [strtoupper|test2.c|43] 7869 0x08049593 strtoupper+51 at test2.c:43 7870 0x08049651 main+69 at test2.c:62 7871 0x4007C9CB __libc_start_main+255 7872 0x080494D1 _start+33 7873 7874 0x0808B310 (1 byte) {malloc:113:0} [strtoupper|test2.c|43] 7875 0x08049593 strtoupper+51 at test2.c:43 7876 0x08049651 main+69 at test2.c:62 7877 0x4007C9CB __libc_start_main+255 7878 0x080494D1 _start+33 7879 7880 0x0808B314 (1 byte) {malloc:114:0} [strtoupper|test2.c|43] 7881 0x08049593 strtoupper+51 at test2.c:43 7882 0x08049651 main+69 at test2.c:62 7883 0x4007C9CB __libc_start_main+255 7884 0x080494D1 _start+33 7885 7886 0x0808B318 (1 byte) {malloc:118:0} [strtoupper|test2.c|43] 7887 0x08049593 strtoupper+51 at test2.c:43 7888 0x08049651 main+69 at test2.c:62 7889 0x4007C9CB __libc_start_main+255 7890 0x080494D1 _start+33 7891 7892 We can discount the first entry since that is obviously coming from 7893when the mpatrol library first initialises itself. However, all of the 7894other entries appear to be coming from line 43 within `strtoupper()' 7895and appear to be only 1 byte in length. At that point in the code, the 7896only possible reason for allocating 1 byte is when the string is empty 7897and so that must mean that we are not freeing memory that contains 7898empty strings. Looking at line 66 we can see that `free()' is only 7899ever called for non-empty strings and therefore if we move the call to 7900`free()' outside the test for an empty string we will fix the memory 7901leak. The file `tests/tutorial/test3.c' contains the source for the 7902final program. 7903 7904 Note that we can come to the same conclusion as above in a much 7905quicker manner by using the `LEAKTABLE' option. The following is 7906written to the mpatrol log file when we use that option on the same 7907program (note that the internal memory allocation has not automatically 7908been added to the leak table): 7909 7910 top 1 unfreed memory entry in leak table: 7911 7912 bytes count location 7913 -------- ------ -------- 7914 9 9 test2.c line 43 7915 9 9 total 7916 7917 ---------- Footnotes ---------- 7918 7919 (1) On UNIX systems with dynamic linking it might also be possible 7920to run the program under the `mpatrol' command with its `--dynamic' 7921option without having to recompile or relink, but compiling and linking 7922with the mpatrol library is a more generic solution across different 7923platforms. 7924 7925 (2) This is not strictly necessary on UNIX and Windows platforms 7926(and AmigaOS when using `gcc'), but it does give us more debugging 7927information. 7928 7929 (3) Note that the start address of the allocation has changed 7930slightly since we added padding around it with the `OFLOWSIZE' option. 7931 7932 (4) This is really only necessary when the mpatrol library has been 7933built as a shared library. 7934 7935 (5) This is not necessarily the fault of the debugger or the 7936debugging information generated by the compiler since on most platforms 7937such watch points can only be caught after they occur, hence most 7938debuggers show the next statement to be executed rather than the current 7939one. 7940 7941 7942File: mpatrol.info, Node: Functions, Next: Environment, Prev: Tutorial, Up: Top 7943 7944Functions 7945********* 7946 7947 The mpatrol library contains implementations of dynamic memory 7948allocation functions for C and C++ suitable for tracing and debugging. 7949The library is intended to be used without requiring any changes to 7950existing user source code except the inclusion of the `mpatrol.h' 7951header file, although additional functions are supplied for extra 7952tracing and control. Note that the current version of the mpatrol 7953library is contained in the `MPATROL_VERSION' preprocessor macro. 7954 7955 All of the function definitions in `mpatrol.h' can be disabled by 7956defining the `NDEBUG' preprocessor macro, which is the same macro used 7957to control the behaviour of the `assert()' function. If `NDEBUG' is 7958defined then no macro redefinition of functions will take place and all 7959special mpatrol library functions will evaluate to empty statements. 7960The `mpalloc.h' header file will also be included in this case. It is 7961intended that the `NDEBUG' preprocessor macro be defined in release 7962builds. 7963 7964 The `MP_MALLOC()' family of functions that are defined in `mpalloc.h' 7965are also defined in `mpatrol.h' when `NDEBUG' is not defined. The 7966mpatrol versions of these functions contain more debugging information 7967than the mpalloc versions do, but they do not call the allocation 7968failure handler when no more memory is available (they cause the 7969`OUTMEM' error message to be given instead). 7970 7971* Menu: 7972 7973* Functions 1:: C dynamic memory allocation functions. 7974* Functions 2:: C dynamic memory extension functions. 7975* Functions 3:: C dynamic memory alternative functions. 7976* Functions 4:: C++ dynamic memory allocation functions. 7977* Functions 5:: C memory operation functions. 7978* Functions 6:: mpatrol library functions. 7979 7980 7981File: mpatrol.info, Node: Functions 1, Next: Functions 2, Up: Functions 7982 7983C dynamic memory allocation functions 7984===================================== 7985 7986 The following 19 functions are available as replacements for 7987existing C library functions. To use these you must include 7988`mpatrol.h' before all other header files, although on UNIX and Windows 7989platforms (and AmigaOS when using `gcc') they will be used anyway, 7990albeit with slightly less tracing information. If `alloca()' is being 7991used and `alloca.h' is included then `mpatrol.h' must appear before 7992`alloca.h' otherwise the debugging version of `alloca()' will not be 7993used. 7994 7995`void *malloc(size_t size)' 7996 Allocates SIZE uninitialised bytes from the heap and returns a 7997 pointer to the first byte of the allocation. The pointer returned 7998 will be suitably aligned for casting to any type and can be used 7999 to store data of up to SIZE bytes in length. If SIZE is `0' then 8000 the memory allocated will be implicitly rounded up to `1' byte. 8001 If there is not enough space in the heap then the `NULL' pointer 8002 will be returned and `errno' will be set to `ENOMEM'. The 8003 allocated memory must be deallocated with `free()' or reallocated 8004 with `realloc()'. 8005 8006`void *calloc(size_t nelem, size_t size)' 8007 Allocates NELEM elements of SIZE zero-initialised bytes from the 8008 heap and returns a pointer to the first byte of the allocation. 8009 The pointer returned will be suitably aligned for casting to any 8010 type and can be used to store data of up to `nelem * size' bytes 8011 in length. If `nelem * size' is `0' then the amount of memory 8012 allocated will be implicitly rounded up to `1' byte. If there is 8013 not enough space in the heap then the `NULL' pointer will be 8014 returned and `errno' will be set to `ENOMEM'. The allocated 8015 memory must be deallocated with `free()' or reallocated with 8016 `realloc()'. 8017 8018`void *memalign(size_t align, size_t size)' 8019 Allocates SIZE uninitialised bytes from the heap and returns a 8020 pointer to the first byte of the allocation. The pointer returned 8021 will be aligned to ALIGN bytes and can be used to store data of up 8022 to SIZE bytes in length. If ALIGN is zero then the default system 8023 alignment will be used. If ALIGN is not a power of two then it 8024 will be rounded up to the nearest power of two. If ALIGN is 8025 greater than the system page size then it will be truncated to 8026 that value. If SIZE is `0' then the memory allocated will be 8027 implicitly rounded up to `1' byte. If there is not enough space in 8028 the heap then the `NULL' pointer will be returned and `errno' will 8029 be set to `ENOMEM'. The allocated memory must be deallocated with 8030 `free()' or reallocated with `realloc()', although the latter will 8031 not guarantee the preservation of alignment. 8032 8033`void *valloc(size_t size)' 8034 Allocates SIZE uninitialised bytes from the heap and returns a 8035 pointer to the first byte of the allocation. The pointer returned 8036 will be aligned to the system page size and can be used to store 8037 data of up to SIZE bytes in length. If SIZE is `0' then the 8038 memory allocated will be implicitly rounded up to `1' byte. If 8039 there is not enough space in the heap then the `NULL' pointer will 8040 be returned and `errno' will be set to `ENOMEM'. The allocated 8041 memory must be deallocated with `free()' or reallocated with 8042 `realloc()', although the latter will not guarantee the 8043 preservation of alignment. 8044 8045`void *pvalloc(size_t size)' 8046 Allocates SIZE uninitialised bytes from the heap and returns a 8047 pointer to the first byte of the allocation. The pointer returned 8048 will be aligned to the system page size and can be used to store 8049 data of up to SIZE bytes in length. If SIZE is `0' then the 8050 memory allocated will be implicitly rounded up to `1' page, 8051 otherwise SIZE will be implicitly rounded up to a multiple of the 8052 system page size. If there is not enough space in the heap then 8053 the `NULL' pointer will be returned and `errno' will be set to 8054 `ENOMEM'. The allocated memory must be deallocated with `free()' 8055 or reallocated with `realloc()', although the latter will not 8056 guarantee the preservation of alignment. 8057 8058`void *alloca(size_t size)' 8059 Allocates SIZE temporary uninitialised bytes from the heap and 8060 returns a pointer to the first byte of the allocation. The 8061 pointer returned will be suitably aligned for casting to any type 8062 and can be used to store data of up to SIZE bytes in length. If 8063 SIZE is `0' then the memory allocated will be implicitly rounded 8064 up to `1' byte. If there is not enough space in the heap then the 8065 program will be terminated and the `OUTMEM' error will be given. 8066 The `alloca()' function normally allocates its memory from the 8067 stack, with the result that all such allocations will be freed 8068 when the function returns. This version of `alloca()' allocates 8069 its memory from the heap in order to provide better debugging, but 8070 the allocations may not necessarily be freed immediately when the 8071 function returns. The allocated memory can be deallocated 8072 explicitly with `dealloca()', but may not be reallocated or 8073 deallocated in any other way. This function is available for 8074 backwards compatibility with older C source code and should not be 8075 used in new code. 8076 8077`char *strdup(const char *str)' 8078 Allocates exactly enough memory from the heap to duplicate STR 8079 (including the terminating nul character) and returns a pointer to 8080 the first byte of the allocation after copying STR to the 8081 newly-allocated memory. The pointer returned will have no 8082 alignment constraints and can be used to store character data up 8083 to the length of STR. If STR is `NULL' then an error will be 8084 given and the `NULL' pointer will be returned. If there is not 8085 enough space in the heap then the `NULL' pointer will be returned 8086 and `errno' will be set to `ENOMEM'. The allocated memory must be 8087 deallocated with `free()' or reallocated with `realloc()'. 8088 8089`char *strndup(const char *str, size_t size)' 8090 Allocates exactly enough memory from the heap to duplicate STR 8091 (including the terminating nul character) and returns a pointer to 8092 the first byte of the allocation after copying STR to the 8093 newly-allocated memory. The pointer returned will have no 8094 alignment constraints and can be used to store character data up 8095 to the length of STR. If STR is `NULL' and SIZE is non-zero then 8096 an error will be given and the `NULL' pointer will be returned. 8097 If the length of STR is greater than SIZE then only SIZE 8098 characters will be allocated and copied, with one additional byte 8099 for the nul character. If there is not enough space in the heap 8100 then the `NULL' pointer will be returned and `errno' will be set to 8101 `ENOMEM'. The allocated memory must be deallocated with `free()' 8102 or reallocated with `realloc()'. This function is available for 8103 backwards compatibility with older C libraries and should not be 8104 used in new code. 8105 8106`char *strsave(const char *str)' 8107 Allocates exactly enough memory from the heap to duplicate STR 8108 (including the terminating nul character) and returns a pointer to 8109 the first byte of the allocation after copying STR to the 8110 newly-allocated memory. The pointer returned will have no 8111 alignment constraints and can be used to store character data up 8112 to the length of STR. If STR is `NULL' then an error will be 8113 given and the `NULL' pointer will be returned. If there is not 8114 enough space in the heap then the `NULL' pointer will be returned 8115 and `errno' will be set to `ENOMEM'. The allocated memory must be 8116 deallocated with `free()' or reallocated with `realloc()'. This 8117 function is available for backwards compatibility with older C 8118 libraries and should not be used in new code. 8119 8120`char *strnsave(const char *str, size_t size)' 8121 Allocates exactly enough memory from the heap to duplicate STR 8122 (including the terminating nul character) and returns a pointer to 8123 the first byte of the allocation after copying STR to the 8124 newly-allocated memory. The pointer returned will have no 8125 alignment constraints and can be used to store character data up 8126 to the length of STR. If STR is `NULL' and SIZE is non-zero then 8127 an error will be given and the `NULL' pointer will be returned. 8128 If the length of STR is greater than SIZE then only SIZE 8129 characters will be allocated and copied, with one additional byte 8130 for the nul character. If there is not enough space in the heap 8131 then the `NULL' pointer will be returned and `errno' will be set to 8132 `ENOMEM'. The allocated memory must be deallocated with `free()' 8133 or reallocated with `realloc()'. This function is available for 8134 backwards compatibility with older C libraries and should not be 8135 used in new code. 8136 8137`char *strdupa(const char *str)' 8138 Allocates exactly enough temporary memory from the heap to 8139 duplicate STR (including the terminating nul character) and 8140 returns a pointer to the first byte of the allocation after 8141 copying STR to the newly-allocated memory. The pointer returned 8142 will have no alignment constraints and can be used to store 8143 character data up to the length of STR. If STR is `NULL' then an 8144 error will be given and the `NULL' pointer will be returned. If 8145 there is not enough space in the heap then the program will be 8146 terminated and the `OUTMEM' error will be given. The `strdupa()' 8147 function normally allocates its memory from the stack, with the 8148 result that all such allocations will be freed when the function 8149 returns. This version of `strdupa()' allocates its memory from 8150 the heap in order to provide better debugging, but the allocations 8151 may not necessarily be freed immediately when the function returns. 8152 The allocated memory can be deallocated explicitly with 8153 `dealloca()', but may not be reallocated or deallocated in any 8154 other way. This function is available for backwards compatibility 8155 with older C source code and should not be used in new code. 8156 8157`char *strndupa(const char *str, size_t size)' 8158 Allocates exactly enough temporary memory from the heap to 8159 duplicate STR (including the terminating nul character) and 8160 returns a pointer to the first byte of the allocation after 8161 copying STR to the newly-allocated memory. The pointer returned 8162 will have no alignment constraints and can be used to store 8163 character data up to the length of STR. If STR is `NULL' and SIZE 8164 is non-zero then an error will be given and the `NULL' pointer 8165 will be returned. If the length of STR is greater than SIZE then 8166 only SIZE characters will be allocated and copied, with one 8167 additional byte for the nul character. If there is not enough 8168 space in the heap then the program will be terminated and the 8169 `OUTMEM' error will be given. The `strndupa()' function normally 8170 allocates its memory from the stack, with the result that all such 8171 allocations will be freed when the function returns. This version 8172 of `strndupa()' allocates its memory from the heap in order to 8173 provide better debugging, but the allocations may not necessarily 8174 be freed immediately when the function returns. The allocated 8175 memory can be deallocated explicitly with `dealloca()', but may 8176 not be reallocated or deallocated in any other way. This function 8177 is available for backwards compatibility with older C source code 8178 and should not be used in new code. 8179 8180`void *realloc(void *ptr, size_t size)' 8181 Resizes the memory allocation beginning at PTR to SIZE bytes and 8182 returns a pointer to the first byte of the new allocation after 8183 copying PTR to the newly-allocated memory, which will be truncated 8184 if SIZE is smaller than the original allocation. The pointer 8185 returned will be suitably aligned for casting to any type and can 8186 be used to store data of up to SIZE bytes in length. If PTR is 8187 `NULL' then the call will be equivalent to `malloc()'. If SIZE is 8188 `0' then the existing memory allocation will be freed and the 8189 `NULL' pointer will be returned. If SIZE is greater than the 8190 original allocation then the extra space will be filled with 8191 uninitialised bytes. If there is not enough space in the heap 8192 then the `NULL' pointer will be returned and `errno' will be set to 8193 `ENOMEM'. The allocated memory must be deallocated with `free()' 8194 and can be reallocated again with `realloc()'. 8195 8196`void *reallocf(void *ptr, size_t size)' 8197 Resizes the memory allocation beginning at PTR to SIZE bytes and 8198 returns a pointer to the first byte of the new allocation after 8199 copying PTR to the newly-allocated memory, which will be truncated 8200 if SIZE is smaller than the original allocation. The pointer 8201 returned will be suitably aligned for casting to any type and can 8202 be used to store data of up to SIZE bytes in length. If PTR is 8203 `NULL' then the call will be equivalent to `malloc()'. If SIZE is 8204 `0' then the existing memory allocation will be freed and the 8205 `NULL' pointer will be returned. If SIZE is greater than the 8206 original allocation then the extra space will be filled with 8207 uninitialised bytes. If there is not enough space in the heap 8208 then the `NULL' pointer will be returned, the original allocation 8209 will be freed and `errno' will be set to `ENOMEM'. The allocated 8210 memory must be deallocated with `free()' and can be reallocated 8211 again with `realloc()'. This function is available for backwards 8212 compatibility with older C libraries and should not be used in new 8213 code. 8214 8215`void *recalloc(void *ptr, size_t nelem, size_t size)' 8216 Resizes the memory allocation beginning at PTR to NELEM elements of 8217 SIZE bytes and returns a pointer to the first byte of the new 8218 allocation after copying PTR to the newly-allocated memory, which 8219 will be truncated if `nelem * size' is smaller than the original 8220 allocation. The pointer returned will be suitably aligned for 8221 casting to any type and can be used to store data of up to `nelem 8222 * size' bytes in length. If PTR is `NULL' then the call will be 8223 equivalent to `calloc()'. If `nelem * size' is `0' then the 8224 existing memory allocation will be freed and the `NULL' pointer 8225 will be returned. If `nelem * size' is greater than the original 8226 allocation then the extra space will be filled with 8227 zero-initialised bytes. If there is not enough space in the heap 8228 then the `NULL' pointer will be returned and `errno' will be set to 8229 `ENOMEM'. The allocated memory must be deallocated with `free()' 8230 and can be reallocated again with `realloc()'. This function is 8231 available for backwards compatibility with older C libraries and 8232 `calloc()' and should not be used in new code. 8233 8234`void *expand(void *ptr, size_t size)' 8235 Attempts to resize the memory allocation beginning at PTR to SIZE 8236 bytes and either returns PTR if there was enough space to resize 8237 it, or `NULL' if the block could not be resized for a particular 8238 reason. If PTR is `NULL' then the call will be equivalent to 8239 `malloc()'. If SIZE is `0' then the existing memory allocation 8240 will be freed and the `NULL' pointer will be returned. If SIZE is 8241 greater than the original allocation then the extra space will be 8242 filled with uninitialised bytes and if SIZE is less than the 8243 original allocation then the memory block will be truncated. If 8244 there is not enough space in the heap then the `NULL' pointer will 8245 be returned and `errno' will be set to `ENOMEM'. The allocated 8246 memory must be deallocated with `free()' and can be reallocated 8247 again with `realloc()'. This function is available for backwards 8248 compatibility with older C libraries and should not be used in new 8249 code. 8250 8251`void free(void *ptr)' 8252 Frees the memory allocation beginning at PTR so the memory can be 8253 reused by another call to allocate memory. If PTR is `NULL' then 8254 no memory will be freed. All of the previous contents will be 8255 destroyed. 8256 8257`void cfree(void *ptr, size_t nelem, size_t size)' 8258 Frees the memory allocation beginning at PTR so the memory can be 8259 reused by another call to allocate memory. If PTR is `NULL' then 8260 no memory will be freed. All of the previous contents will be 8261 destroyed. The NELEM and SIZE parameters are ignored in this 8262 implementation. This function is available for backwards 8263 compatibility with older C libraries and `calloc()' and should not 8264 be used in new code. 8265 8266`void dealloca(void *ptr)' 8267 Explicitly frees the temporary memory allocation beginning at PTR 8268 so the memory can be reused by another call to allocate memory. 8269 If PTR is `NULL' then no memory will be freed. All of the 8270 previous contents will be destroyed. This function can only be 8271 used to free memory that was allocated with the `alloca()', 8272 `strdupa()' and `strndupa()' functions, but is only really 8273 required if the mpatrol library does not automatically free such 8274 memory allocations when the allocating function returns. This 8275 function is mpatrol-specific and should not be used in release 8276 code. 8277 8278 8279File: mpatrol.info, Node: Functions 2, Next: Functions 3, Prev: Functions 1, Up: Functions 8280 8281C dynamic memory extension functions 8282==================================== 8283 8284 The following 5 functions are available as replacements for existing 8285C library extension functions that always abort and never return `NULL' 8286if there is insufficient memory to fulfil a request. To use these you 8287must include `mpatrol.h' before all other header files, although on 8288UNIX and Windows platforms (and AmigaOS when using `gcc') they will be 8289used anyway, albeit with slightly less tracing information. 8290 8291`void *xmalloc(size_t size)' 8292 Allocates SIZE uninitialised bytes from the heap and returns a 8293 pointer to the first byte of the allocation. The pointer returned 8294 will be suitably aligned for casting to any type and can be used 8295 to store data of up to SIZE bytes in length. If SIZE is `0' then 8296 the memory allocated will be implicitly rounded up to `1' byte. 8297 If there is not enough space in the heap then the program will be 8298 terminated and the `OUTMEM' error will be given. The allocated 8299 memory must be deallocated with `xfree()' or reallocated with 8300 `xrealloc()'. 8301 8302`void *xcalloc(size_t nelem, size_t size)' 8303 Allocates NELEM elements of SIZE zero-initialised bytes from the 8304 heap and returns a pointer to the first byte of the allocation. 8305 The pointer returned will be suitably aligned for casting to any 8306 type and can be used to store data of up to `nelem * size' bytes 8307 in length. If `nelem * size' is `0' then the amount of memory 8308 allocated will be implicitly rounded up to `1' byte. If there is 8309 not enough space in the heap then the program will be terminated 8310 and the `OUTMEM' error will be given. The allocated memory must 8311 be deallocated with `xfree()' or reallocated with `xrealloc()'. 8312 8313`char *xstrdup(const char *str)' 8314 Allocates exactly enough memory from the heap to duplicate STR 8315 (including the terminating nul character) and returns a pointer to 8316 the first byte of the allocation after copying STR to the 8317 newly-allocated memory. The pointer returned will have no 8318 alignment constraints and can be used to store character data up 8319 to the length of STR. If STR is `NULL' then an error will be 8320 given and the `NULL' pointer will be returned. If there is not 8321 enough space in the heap then the program will be terminated and 8322 the `OUTMEM' error will be given. The allocated memory must be 8323 deallocated with `xfree()' or reallocated with `xrealloc()'. 8324 8325`void *xrealloc(void *ptr, size_t size)' 8326 Resizes the memory allocation beginning at PTR to SIZE bytes and 8327 returns a pointer to the first byte of the new allocation after 8328 copying PTR to the newly-allocated memory, which will be truncated 8329 if SIZE is smaller than the original allocation. The pointer 8330 returned will be suitably aligned for casting to any type and can 8331 be used to store data of up to SIZE bytes in length. If PTR is 8332 `NULL' then the call will be equivalent to `xmalloc()'. If SIZE 8333 is `0' then it will be implicitly rounded up to `1'. If SIZE is 8334 greater than the original allocation then the extra space will be 8335 filled with uninitialised bytes. If there is not enough space in 8336 the heap then the program will be terminated and the `OUTMEM' 8337 error will be given. The allocated memory must be deallocated 8338 with `xfree()' and can be reallocated again with `xrealloc()'. 8339 8340`void xfree(void *ptr)' 8341 Frees the memory allocation beginning at PTR so the memory can be 8342 reused by another call to allocate memory. If PTR is `NULL' then 8343 no memory will be freed. All of the previous contents will be 8344 destroyed. 8345 8346 8347File: mpatrol.info, Node: Functions 3, Next: Functions 4, Prev: Functions 2, Up: Functions 8348 8349C dynamic memory alternative functions 8350====================================== 8351 8352 The following 6 functions are provided as convenient alternatives to 8353the ANSI C dynamic memory allocation functions (although `strdup()' is 8354not strictly an ANSI C function). They are implemented as preprocessor 8355macro functions which may evaluate their arguments more than once, so 8356extra care should be taken to avoid passing arguments with 8357side-effects. None of the functions return `NULL' if no memory is 8358available and instead abort the program with a useful error message 8359indicating where the call to allocate memory came from and what was 8360being allocated. To use these you should include the `mpatrol.h' or 8361`mpalloc.h' header files. 8362 8363`void *MP_MALLOC(void *ptr, size_t count, typename type)' 8364 Allocates COUNT uninitialised items of type TYPE from the heap, 8365 sets PTR to the result and returns a suitably-cast pointer to the 8366 first item of the allocation. The pointer returned will be 8367 suitably aligned for holding items of type TYPE. If COUNT is `0' 8368 then it will be implicitly rounded up to `1'. If there is not 8369 enough space in the heap then the program will be aborted after 8370 calling the allocation failure handler, which by default writes an 8371 appropriate error message to the standard error file stream. The 8372 allocated memory in PTR must be deallocated with `MP_FREE()' or 8373 reallocated with `MP_REALLOC()'. 8374 8375`void *MP_CALLOC(void *ptr, size_t count, typename type)' 8376 Allocates COUNT zero-initialised items of type TYPE from the heap, 8377 sets PTR to the result and returns a suitably-cast pointer to the 8378 first item of the allocation. The pointer returned will be 8379 suitably aligned for holding items of type TYPE. If COUNT is `0' 8380 then it will be implicitly rounded up to `1'. If there is not 8381 enough space in the heap then the program will be aborted after 8382 calling the allocation failure handler, which by default writes an 8383 appropriate error message to the standard error file stream. The 8384 allocated memory in PTR must be deallocated with `MP_FREE()' or 8385 reallocated with `MP_REALLOC()'. 8386 8387`char *MP_STRDUP(char *ptr, const char *str)' 8388 Allocates exactly enough memory from the heap to duplicate STR 8389 (including the terminating nul character), sets PTR to the result 8390 and returns a suitably-cast pointer to the first byte of the 8391 allocation after copying STR to the newly-allocated memory. The 8392 pointer returned will have no alignment constraints and can be 8393 used to store character data up to the length of STR. If there is 8394 not enough space in the heap then the program will be aborted 8395 after calling the allocation failure handler, which by default 8396 writes an appropriate error message to the standard error file 8397 stream. The allocated memory in PTR must be deallocated with 8398 `MP_FREE()' or reallocated with `MP_REALLOC()'. 8399 8400`void *MP_REALLOC(void *ptr, size_t count, typename type)' 8401 Resizes the memory allocation beginning at PTR to COUNT items of 8402 type TYPE and returns a suitably-cast pointer to the first item of 8403 the new allocation after copying PTR to the newly-allocated 8404 memory, which will be truncated if COUNT is smaller than the 8405 original number of items. The pointer returned will be suitably 8406 aligned for holding items of type TYPE. If PTR is `NULL' then the 8407 call will be equivalent to `MP_MALLOC()'. If COUNT is `0' then it 8408 will be implicitly rounded up to `1'. If COUNT is greater than 8409 the original number of items then the extra space will be filled 8410 with uninitialised bytes. If there is not enough space in the 8411 heap then the program will be aborted after calling the allocation 8412 failure handler, which by default writes an appropriate error 8413 message to the standard error file stream. The allocated memory 8414 must be deallocated with `MP_FREE()' and can be reallocated again 8415 with `MP_REALLOC()'. 8416 8417`void MP_FREE(void *ptr)' 8418 Frees the memory allocation beginning at PTR so the memory can be 8419 reused by another call to allocate memory, and sets PTR to `NULL' 8420 after freeing the memory. If PTR is `NULL' then no memory will be 8421 freed. 8422 8423`__mp_failhandler MP_FAILURE(__mp_failhandler func)' 8424 Installs an allocation failure handler specifically for use with 8425 `MP_MALLOC()', `MP_CALLOC()', `MP_STRDUP()' and `MP_REALLOC()' and 8426 returns a pointer to the previously installed handler, normally 8427 the default handler if no handler had been previously installed. 8428 This will be called by the above functions when there is not 8429 enough space in the heap for them to satisfy their allocation 8430 request. The default allocation failure handler will terminate 8431 the program after writing an error message to the standard error 8432 file stream indicating where the original allocation request took 8433 place and what was being allocated. 8434 8435 8436File: mpatrol.info, Node: Functions 4, Next: Functions 5, Prev: Functions 3, Up: Functions 8437 8438C++ dynamic memory allocation functions 8439======================================= 8440 8441 The following 5 functions are available as replacements for existing 8442C++ library functions, but the replacements in `mpatrol.h' will only be 8443used if the `MP_NOCPLUSPLUS' preprocessor macro is not defined. The 8444replacement operators make use of the preprocessor in order to obtain 8445source-level information. If this causes problems then you should 8446define the `MP_NONEWDELETE' preprocessor macro and use the `MP_NEW', 8447`MP_NEW_NOTHROW' and `MP_DELETE' macros instead of `new' and `delete' 8448directly. To use these C++ features you must include `mpatrol.h' 8449before all other header files, although on UNIX and Windows platforms 8450(and AmigaOS when using `gcc') they will be used anyway, albeit with 8451slightly less tracing information. 8452 8453`void *operator new(size_t size)' 8454 Allocates SIZE uninitialised bytes from the heap and returns a 8455 pointer to the first byte of the allocation. The pointer returned 8456 will be suitably aligned for casting to any type and can be used 8457 to store data of up to SIZE bytes in length. If SIZE is `0' then 8458 the memory allocated will be implicitly rounded up to `1' byte. 8459 If there is not enough space in the heap then either the 8460 `std::bad_alloc' exception will be thrown or the null pointer will 8461 be returned and `errno' will be set to `ENOMEM' -- the behaviour 8462 depends on whether the _nothrow_ version of the operator is used. 8463 The allocated memory must be deallocated with `operator delete'. 8464 8465`void *operator new[](size_t size)' 8466 Allocates SIZE uninitialised bytes from the heap and returns a 8467 pointer to the first byte of the allocation. The pointer returned 8468 will be suitably aligned for casting to any type and can be used 8469 to store data of up to SIZE bytes in length. If SIZE is `0' then 8470 the memory allocated will be implicitly rounded up to `1' byte. 8471 If there is not enough space in the heap then either the 8472 `std::bad_alloc' exception will be thrown or the null pointer will 8473 be returned and `errno' will be set to `ENOMEM' -- the behaviour 8474 depends on whether the _nothrow_ version of the operator is used. 8475 The allocated memory must be deallocated with `operator delete[]'. 8476 8477`void operator delete(void *ptr)' 8478 Frees the memory allocation beginning at PTR so the memory can be 8479 reused by another call to allocate memory. If PTR is `NULL' then 8480 no memory will be freed. All of the previous contents will be 8481 destroyed. This function must only be used with memory allocated 8482 by `operator new'. 8483 8484`void operator delete[](void *ptr)' 8485 Frees the memory allocation beginning at PTR so the memory can be 8486 reused by another call to allocate memory. If PTR is `NULL' then 8487 no memory will be freed. All of the previous contents will be 8488 destroyed. This function must only be used with memory allocated 8489 by `operator new[]'. 8490 8491`std::new_handler std::set_new_handler(std::new_handler func)' 8492 Installs a low-memory handler specifically for use with `operator 8493 new' and `operator new[]' and returns a pointer to the previously 8494 installed handler, or the null pointer if no handler had been 8495 previously installed. This will be called repeatedly by both 8496 functions when they would normally return `NULL', and this loop 8497 will continue until they manage to allocate the requested space. 8498 Note that this function is equivalent to `__mp_nomemory()' and 8499 will replace the handler installed by that function. 8500 8501 8502File: mpatrol.info, Node: Functions 5, Next: Functions 6, Prev: Functions 4, Up: Functions 8503 8504C memory operation functions 8505============================ 8506 8507 The following 10 functions are available as replacements for 8508existing C library memory operation functions. To use these you must 8509include `mpatrol.h' before all other header files, although on UNIX and 8510Windows platforms (and AmigaOS when using `gcc') they will be used 8511anyway, albeit with slightly less tracing information. 8512 8513`void *memset(void *ptr, int byte, size_t size)' 8514 Writes SIZE bytes of value BYTE to the memory location beginning at 8515 PTR and returns PTR. If SIZE is `0' then no bytes will be 8516 written. If the operation would affect an existing memory 8517 allocation in the heap but would straddle that allocation's 8518 boundaries then an error message will be generated in the log file 8519 and no bytes will be written. 8520 8521`void bzero(void *ptr, size_t size)' 8522 Writes SIZE zero bytes to the memory location beginning at PTR. If 8523 SIZE is `0' then no bytes will be written. If the operation would 8524 affect an existing memory allocation in the heap but would 8525 straddle that allocation's boundaries then an error message will 8526 be generated in the log file and no bytes will be written. This 8527 function is available for backwards compatibility with older C 8528 libraries and should not be used in new code. 8529 8530`void *memccpy(void *dest, const void *src, int byte, size_t size)' 8531 Copies SIZE bytes from SRC to DEST and returns `NULL', or copies 8532 the number of bytes up to and including the first occurrence of 8533 BYTE if BYTE exists within the specified range and returns a 8534 pointer to the first byte after BYTE. If SIZE is `0' or SRC is 8535 the same as DEST then no bytes will be copied. The source and 8536 destination ranges should not overlap, otherwise a warning will be 8537 written to the log file. If the operation would affect an 8538 existing memory allocation in the heap but would straddle that 8539 allocation's boundaries then an error message will be generated in 8540 the log file and no bytes will be copied. 8541 8542`void *memcpy(void *dest, const void *src, size_t size)' 8543 Copies SIZE bytes from SRC to DEST and returns DEST. If SIZE is 8544 `0' or SRC is the same as DEST then no bytes will be copied. The 8545 source and destination ranges should not overlap, otherwise a 8546 warning will be written to the log file. If the operation would 8547 affect an existing memory allocation in the heap but would 8548 straddle that allocation's boundaries then an error message will 8549 be generated in the log file and no bytes will be copied. 8550 8551`void *memmove(void *dest, const void *src, size_t size)' 8552 Copies SIZE bytes from SRC to DEST and returns DEST. If SIZE is 8553 `0' or SRC is the same as DEST then no bytes will be copied. If 8554 the operation would affect an existing memory allocation in the 8555 heap but would straddle that allocation's boundaries then an error 8556 message will be generated in the log file and no bytes will be 8557 copied. 8558 8559`void bcopy(const void *src, void *dest, size_t size)' 8560 Copies SIZE bytes from SRC to DEST. If SIZE is `0' or SRC is the 8561 same as DEST then no bytes will be copied. If the operation would 8562 affect an existing memory allocation in the heap but would 8563 straddle that allocation's boundaries then an error message will 8564 be generated in the log file and no bytes will be copied. This 8565 function is available for backwards compatibility with older C 8566 libraries and should not be used in new code. 8567 8568`int memcmp(const void *ptr1, const void *ptr2, size_t size)' 8569 Compares SIZE bytes from PTR1 and PTR2 and returns `0' if all of 8570 the bytes are identical, or returns the byte difference of the 8571 first differing bytes. If SIZE is `0' or PTR1 is the same as PTR2 8572 then no bytes will be compared. If the operation would read from 8573 an existing memory allocation in the heap but would straddle that 8574 allocation's boundaries then an error message will be generated in 8575 the log file and no bytes will be compared. 8576 8577`int bcmp(const void *ptr1, const void *ptr2, size_t size)' 8578 Compares SIZE bytes from PTR1 and PTR2 and returns `0' if all of 8579 the bytes are identical, or returns the byte difference of the 8580 first differing bytes. If SIZE is `0' or PTR1 is the same as PTR2 8581 then no bytes will be compared. If the operation would read from 8582 an existing memory allocation in the heap but would straddle that 8583 allocation's boundaries then an error message will be generated in 8584 the log file and no bytes will be compared. This function is 8585 available for backwards compatibility with older C libraries and 8586 should not be used in new code. 8587 8588`void *memchr(const void *ptr, int byte, size_t size)' 8589 Searches up to SIZE bytes in PTR for the first occurrence of BYTE 8590 and returns a pointer to it or `NULL' if no such byte occurs. If 8591 SIZE is `0' then no bytes will be searched. If the operation 8592 would affect an existing memory allocation in the heap but would 8593 straddle that allocation's boundaries then an error message will 8594 be generated in the log file and no bytes will be searched. 8595 8596`void *memmem(const void *ptr1, size_t size1, const void *ptr2, size_t size2)' 8597 Searches up to SIZE1 bytes in PTR1 for the first occurrence of 8598 PTR2 (which is exactly SIZE2 bytes in length) and returns a pointer 8599 to it or `NULL' if no such sequence of bytes occur. If SIZE1 or 8600 SIZE2 is `0' then no bytes will be searched. If the operation 8601 would affect an existing memory allocation in the heap but would 8602 straddle that allocation's boundaries then an error message will 8603 be generated in the log file and no bytes will be searched. 8604 8605 8606File: mpatrol.info, Node: Functions 6, Prev: Functions 5, Up: Functions 8607 8608mpatrol library functions 8609========================= 8610 8611 The following 42 functions are available as support routines for 8612additional control and tracing in the mpatrol library. Although they 8613are documented here as being prefixed by `__mp_', their equivalent 8614functions that are prefixed by `mpatrol_' are also defined as aliases 8615in the `mpatrol.h' header file. To use these you should include the 8616`mpatrol.h' header file. 8617 8618`int __mp_atexit(void (*func)(void))' 8619 Installs a function to be called when the mpatrol library 8620 terminates. Up to 32 such functions can be registered and will be 8621 called in reverse order of registration. Returns `1' on success 8622 or `0' if FUNC could not be registered. 8623 8624`unsigned long __mp_setoption(long opt, unsigned long val)' 8625 Sets the value of an mpatrol option after the library has been 8626 initialised. Options that require values are listed in 8627 `mpatrol.h' prefixed with `MP_OPT_*'. The OPT argument should be 8628 set to one of these macros, and the VAL argument should be set to 8629 the option value, cast to an unsigned integer. The return value 8630 will be `0' on success and `1' on failure. Options that are flags 8631 are listed in `mpatrol.h' prefixed with `MP_FLG_*'. Multiple 8632 flags can be set or unset at once using the `MP_OPT_SETFLAGS' and 8633 `MP_OPT_UNSETFLAGS' options respectively, with the necessary flags 8634 specified in VAL. The return value will be `0' on success and a 8635 combination of all of the flags that could not be set or unset on 8636 failure. 8637 8638`int __mp_getoption(long opt, unsigned long *val)' 8639 Gets the value of an mpatrol option after the library has been 8640 initialised. If OPT is a valid option listed in `mpatrol.h' then 8641 `1' will be returned and the associated value will be returned in 8642 VAL and cast to an unsigned integer, otherwise `0' will be 8643 returned. If OPT is `MP_OPT_SETFLAGS' then all of the mpatrol 8644 library flags that are set will be returned in VAL. If OPT is 8645 `MP_OPT_UNSETFLAGS' then all of the mpatrol library flags that are 8646 not set will be returned in VAL. 8647 8648`unsigned long __mp_libversion(void)' 8649 Returns the version number of the mpatrol library. This can be 8650 useful for verifying that the version of the mpatrol library that 8651 a program is linked with is the one expected at compile-time. 8652 8653`const char *__mp_strerror(__mp_errortype err)' 8654 Returns the error message corresponding to the error code ERR or 8655 `NULL' if no such error code exists. The most recent error code 8656 recorded by the mpatrol library can be obtained by examining 8657 `__mp_errno'. 8658 8659`const char *__mp_function(__mp_alloctype func)' 8660 Returns the name of the function corresponding to the allocation 8661 type FUNC or `NULL' if no such allocation type exists. 8662 8663`int __mp_setuser(const void *ptr, const void *data)' 8664 Sets the user data for the memory allocation containing PTR. The 8665 contents of DATA are entirely application-specific as user data 8666 will never be examined by the mpatrol library. Such data is 8667 associated with a memory allocation for its entire lifetime unless 8668 overridden by a subsequent call to `__mp_setuser()'. As such, the 8669 user data must be valid for the entire lifetime of the memory 8670 allocation, perhaps even after the allocation has been freed if 8671 the `NOFREE' option is being used. This function returns `1' if 8672 there is an allocated memory block containing PTR, and `0' 8673 otherwise. 8674 8675`int __mp_setmark(const void *ptr)' 8676 Sets the marked flag for the memory allocation containing PTR, 8677 indicating that the memory allocation cannot be freed (but can be 8678 reallocated) and thus will not be listed as a memory leak. This 8679 function returns `1' if there is an allocated memory block 8680 containing PTR, and `0' otherwise. Note that a memory allocation 8681 made by `alloca()', `strdupa()' or `strndupa()' may not be marked. 8682 8683`int __mp_info(const void *ptr, __mp_allocinfo *info)' 8684 Obtains information about a specific memory allocation by placing 8685 statistics about PTR in INFO. If PTR does not belong to a 8686 previously allocated memory allocation or free memory block then 8687 `0' will be returned, otherwise `1' will be returned and INFO will 8688 contain the following information (note that a free memory block 8689 will only contain the `block' and `size' fields and can be 8690 identified by not having the `allocated' flag set): 8691 8692 _Field_ _Description_ 8693 `block' Pointer to first byte of allocation. 8694 `size' Size of allocation in bytes. 8695 `type' Type of function which allocated memory. 8696 `alloc' Allocation index. 8697 `realloc' Number of times reallocated. 8698 `thread' Thread identifier. 8699 `event' Event of last modification. 8700 `func' Function in which allocation took place. 8701 `file' File in which allocation took place. 8702 `line' Line number at which allocation took place. 8703 `stack' Pointer to function call stack. 8704 `typestr' Type stored in allocation. 8705 `typesize' Size of type stored in allocation. 8706 `userdata' User data associated with allocation. 8707 `allocated' Indicates if allocation was allocated. 8708 `freed' Indicates if allocation has been freed. 8709 `marked' Indicates if allocation has been marked. 8710 `profiled' Indicates if allocation has been profiled. 8711 `traced' Indicates if allocation has been traced. 8712 `internal' Indicates if allocation is internal. 8713 8714`int __mp_syminfo(const void *ptr, __mp_symbolinfo *info)' 8715 Obtains symbolic information about a specific code address by 8716 placing statistics about PTR in INFO. If PTR does not belong to a 8717 function symbol then `0' will be returned, otherwise `1' will be 8718 returned and INFO will contain the following information: 8719 8720 _Field_ _Description_ 8721 `name' Name of symbol. 8722 `object' File containing symbol. 8723 `addr' Start address of symbol. 8724 `size' Size of symbol. 8725 `file' Filename corresponding to address. 8726 `line' Line number corresponding to address. 8727 8728`const char *__mp_symbol(const void *ptr)' 8729 Obtains the name of a function symbol containing the code address 8730 specified in PTR. If PTR does not belong to a function symbol 8731 then `NULL' will be returned. 8732 8733`int __mp_printinfo(const void *ptr)' 8734 Displays information about a specific memory allocation containing 8735 PTR to the standard error file stream. If PTR does not belong to 8736 a previously allocated memory allocation or free memory block then 8737 `0' will be returned, otherwise `1' will be returned. This 8738 function is intended to be called from within a debugger. 8739 8740`unsigned long __mp_snapshot(void)' 8741 Returns the current event number, effectively taking a snapshot of 8742 the heap. This number can then be used in later calls to 8743 `__mp_iterate()'. 8744 8745`size_t __mp_iterate(int (*func)(const void *, void *), void *data, unsigned long event)' 8746 Iterates over all of the current allocated and freed memory 8747 allocations, calling FUNC with the start address of every memory 8748 allocation that has been modified since event number EVENT. If 8749 FUNC is `NULL' then `__mp_printinfo()' will be used as the 8750 callback function. If EVENT is `0' then FUNC will be called with 8751 the start address of every memory allocation. If FUNC returns a 8752 negative number then the iteration process will be stopped 8753 immediately. If FUNC returns a positive number above zero then 8754 `__mp_iterate()' will return the number of times FUNC returned a 8755 non-zero number after the iteration process has stopped. The DATA 8756 argument is passed directly to FUNC as its second argument and is 8757 not read by the mpatrol library. 8758 8759`size_t __mp_iterateall(int (*func)(const void *, void *), void *data)' 8760 Iterates over all of the current allocated and freed memory 8761 allocations and any free memory blocks, calling FUNC with the 8762 start address of every memory allocation or free block. If FUNC 8763 is `NULL' then `__mp_printinfo()' will be used as the callback 8764 function. If FUNC returns a negative number then the iteration 8765 process will be stopped immediately. If FUNC returns a positive 8766 number above zero then `__mp_iterate()' will return the number of 8767 times FUNC returned a non-zero number after the iteration process 8768 has stopped. The DATA argument is passed directly to FUNC as its 8769 second argument and is not read by the mpatrol library. Note that 8770 unlike `__mp_iterate()', this function will also include internal 8771 memory allocations made by the mpatrol library and is intended for 8772 walking the entire heap. 8773 8774`int __mp_addallocentry(const char *file, unsigned long line, size_t size)' 8775 Adds an entry representing an allocation of size SIZE to the leak 8776 table. The allocation will be associated with a source filename 8777 of FILE and a line number of LINE if the former is non-`NULL' and 8778 the latter is non-zero. If FILE is non-`NULL' and LINE is `0' then 8779 FILE represents the name of the function that made the allocation. 8780 If FILE is `NULL' and LINE is non-zero then LINE represents the 8781 code address at which the allocation was made. If FILE is `NULL' 8782 and LINE is `0' then the location of the allocation is unknown. 8783 Returns `1' on success and `0' if there was no more memory 8784 available to add another entry to the leak table. 8785 8786`int __mp_addfreeentry(const char *file, unsigned long line, size_t size)' 8787 Adds an entry representing a deallocation of size SIZE to the leak 8788 table. The deallocation will be associated with a source filename 8789 of FILE and a line number of LINE if the former is non-`NULL' and 8790 the latter is non-zero. If FILE is non-`NULL' and LINE is `0' then 8791 FILE represents the name of the function that made the 8792 deallocation. If FILE is `NULL' and LINE is non-zero then LINE 8793 represents the code address at which the deallocation was made. 8794 If FILE is `NULL' and LINE is `0' then the location of the 8795 deallocation is unknown. Returns `1' on success and `0' if there 8796 was no existing allocation from the same location in the leak 8797 table. 8798 8799`void __mp_clearleaktable(void)' 8800 Deletes all of the existing entries in the leak table, making it 8801 empty. This will also affect the behaviour of the `LEAKTABLE' 8802 option since that option will then only be able to show a summary 8803 of the entries in the leak table that were collected after the 8804 last call to this function rather than from the start of program 8805 execution. 8806 8807`int __mp_startleaktable(void)' 8808 Starts the automatic logging of all memory allocations, 8809 reallocations and deallocations to the leak table. Returns `1' if 8810 such logging was already being performed and `0' otherwise. 8811 8812`int __mp_stopleaktable(void)' 8813 Stops the automatic logging of all memory allocations, 8814 reallocations and deallocations to the leak table. Returns `1' if 8815 such logging was already being performed and `0' otherwise. 8816 8817`void __mp_leaktable(size_t size, int opt, unsigned char flags)' 8818 Displays a summary of up to SIZE entries from the leak table, or 8819 all entries if SIZE is `0'. If OPT is `MP_LT_ALLOCATED' then all 8820 allocated entries will be displayed, if OPT is `MP_LT_FREED' then 8821 all freed entries will be displayed and if OPT is `MP_LT_UNFREED' 8822 then all unfreed entries will be displayed. The summary is 8823 normally sorted in descending order of total bytes from each 8824 entry, but this can be changed by setting FLAGS to any combination 8825 of `MP_LT_COUNTS' (to sort by the number of occurrences in each 8826 entry) and `MP_LT_BOTTOM' (to sort in ascending order). 8827 8828`void __mp_memorymap(int stats)' 8829 If STATS is non-zero then the current statistics of the mpatrol 8830 library will be displayed. If the heap contains at least one 8831 allocated, freed or free block then a map of the current heap will 8832 also be displayed. 8833 8834`void __mp_summary(void)' 8835 Displays information about the current state of the mpatrol 8836 library, including its settings and any relevant statistics. 8837 8838`int __mp_stats(__mp_heapinfo *info)' 8839 Obtains statistics about the current state of the heap and places 8840 them in INFO. If this information could not be determined then 8841 `0' will be returned, otherwise `1' will be returned and INFO will 8842 contain the following information: 8843 8844 _Field_ _Description_ 8845 `acount' Total number of allocated blocks. 8846 `atotal' Total size of allocated blocks. 8847 `fcount' Total number of free blocks. 8848 `ftotal' Total size of free blocks. 8849 `gcount' Total number of freed blocks. 8850 `gtotal' Total size of freed blocks. 8851 `icount' Total number of internal blocks. 8852 `itotal' Total size of internal blocks. 8853 `mcount' Total number of marked blocks. 8854 `mtotal' Total size of marked blocks. 8855 8856`void __mp_check(void)' 8857 Forces the library to perform an immediate check of the overflow 8858 buffers of every memory allocation and to ensure that nothing has 8859 overwritten any free blocks. If any memory allocations made by 8860 the `alloca()' family of functions are out of scope then this 8861 function will also cause them to be freed. 8862 8863`__mp_prologuehandler __mp_prologue(const __mp_prologuehandler func)' 8864 Installs a prologue function to be called before any memory 8865 allocation, reallocation or deallocation function. This function 8866 will return a pointer to the previously installed prologue 8867 function, or the null pointer if no prologue function had been 8868 previously installed. The following arguments will be used to 8869 call the prologue function (the last four arguments contain the 8870 function name, file name, line number and the return address of 8871 the calling function, or null pointers and zero if they cannot be 8872 determined): 8873 8874 _Argument 1_ _Argument 2_ _Argument 3_ _Called by_ 8875 `-1' SIZE ALIGN `malloc()', etc. 8876 PTR SIZE ALIGN `realloc()', etc. 8877 PTR `-1' `0' `free()', etc. 8878 PTR `-2' `1' `strdup()', etc. 8879 8880`__mp_epiloguehandler __mp_epilogue(const __mp_epiloguehandler func)' 8881 Installs an epilogue function to be called after any memory 8882 allocation, reallocation or deallocation function. This function 8883 will return a pointer to the previously installed epilogue 8884 function, or the null pointer if no epilogue function had been 8885 previously installed. The following arguments will be used to 8886 call the epilogue function (the last four arguments contain the 8887 function name, file name, line number and the return address of 8888 the calling function, or null pointers and zero if they cannot be 8889 determined): 8890 8891 _Argument_ _Called by_ 8892 PTR `malloc()', `realloc()', `strdup()', etc. 8893 `-1' `free()', etc. 8894 8895`__mp_nomemoryhandler __mp_nomemory(const __mp_nomemoryhandler func)' 8896 Installs a low-memory handler and returns a pointer to the 8897 previously installed handler, or the `NULL' pointer if no handler 8898 had been previously installed. This will be called once by C 8899 memory allocation functions, and repeatedly by C++ memory 8900 allocation functions, when they would normally return `NULL'. The 8901 four arguments contain the function name, file name, line number 8902 and the return address of the calling function, or null pointers 8903 and zero if they cannot be determined. Note that this function is 8904 equivalent to `set_new_handler()' and will replace the handler 8905 installed by that function. 8906 8907`int __mp_printf(const char *fmt, ...)' 8908 Writes format string FMT with variable arguments to the log file, 8909 with each line prefixed by `>'. The final length of the string 8910 that is written to the log file must not exceed 1024 characters. 8911 Returns the number of characters written, or a negative number 8912 upon error. 8913 8914`int __mp_vprintf(const char *fmt, va_list args)' 8915 Writes format string FMT with variable argument list ARGS to the 8916 log file, with each line prefixed by `>'. The final length of the 8917 string that is written to the log file must not exceed 1024 8918 characters. Returns the number of characters written, or a 8919 negative number upon error. 8920 8921`void __mp_locprintf(const char *fmt, ...)' 8922 Writes format string FMT with variable arguments to the log file, 8923 with each line prefixed by `>'. The final length of the string 8924 that is written to the log file must not exceed 1024 characters. 8925 It also writes information to the log file about where the call to 8926 this function was made, which includes the source file location 8927 and the call stack if they are available. 8928 8929`void __mp_vlocprintf(const char *fmt, va_list args)' 8930 Writes format string FMT with variable argument list ARGS to the 8931 log file, with each line prefixed by `>'. The final length of the 8932 string that is written to the log file must not exceed 1024 8933 characters. It also writes information to the log file about 8934 where the call to this function was made, which includes the 8935 source file location and the call stack if they are available. 8936 8937`void __mp_logmemory(const void *ptr, size_t size)' 8938 Displays the contents of a block of memory beginning at PTR, 8939 dumping SIZE consecutive bytes to the log file in hexadecimal 8940 format. 8941 8942`int __mp_logstack(size_t frames)' 8943 Displays the current call stack, skipping FRAMES stack frames from 8944 the current stack frame before writing the symbolic stack trace to 8945 the log file. Returns `1' if successful, or `0' if the call stack 8946 could not be determined or if FRAMES was too large for the current 8947 call stack. 8948 8949`int __mp_logaddr(const void *ptr)' 8950 Displays information about a specific memory allocation containing 8951 PTR to the log file. If PTR does not belong to a previously 8952 allocated memory allocation then `0' will be returned, otherwise 8953 `1' will be returned. 8954 8955`int __mp_edit(const char *file, unsigned long line)' 8956 Invokes a text editor to edit FILE at line number LINE via the 8957 `mpedit' command. Returns `1' if the text editor was successfully 8958 invoked, `-1' if there was an error, or `0' if there is no support 8959 for this feature. This function will only work on a system where 8960 the `EDIT' option works. 8961 8962`int __mp_list(const char *file, unsigned long line)' 8963 Displays a context listing of FILE at line number LINE via the 8964 `mpedit' command. Returns `1' if the listing was successfully 8965 performed, `-1' if there was an error, or `0' if there is no 8966 support for this feature. This function will only work on a 8967 system where the `LIST' option works. 8968 8969`int __mp_view(const char *file, unsigned long line)' 8970 Either invokes a text editor to edit FILE at line number LINE or 8971 displays a context listing of FILE at line number LINE depending 8972 on the setting of the `EDIT' and `LIST' options. This is done via 8973 the `mpedit' command and will have no effect if the `EDIT' and 8974 `LIST' options are not set or if these options are not supported 8975 on the system. Returns `1' if the edit or listing was 8976 successfully performed, `-1' if there was an error, or `0' if 8977 neither of the options were set or if there is no support for this 8978 feature. 8979 8980`int __mp_readcontents(const char *file, void *ptr)' 8981 Reads the contents of a memory allocation contents file into the 8982 memory allocation containing PTR. The name of the file is 8983 composed of the FILE string followed by the allocation index of 8984 the memory allocation separated by a dot. If FILE is `NULL' then 8985 it is assumed to be `.mpatrol'. Returns `1' if the contents were 8986 read successfully and `0' otherwise. 8987 8988`int __mp_writecontents(const char *file, const void *ptr)' 8989 Writes the contents of the memory allocation containing PTR to an 8990 allocation contents file. The name of the file is composed of the 8991 FILE string followed by the allocation index of the memory 8992 allocation separated by a dot. If FILE is `NULL' then it is 8993 assumed to be `.mpatrol'. Returns `1' if the contents were 8994 written successfully and `0' otherwise. 8995 8996`long __mp_cmpcontents(const char *file, const void *ptr)' 8997 Compares the contents of the memory allocation containing PTR with 8998 the contents of a previously written allocation contents file. 8999 The name of the file is composed of the FILE string followed by 9000 the allocation index of the memory allocation separated by a dot. 9001 If FILE is `NULL' then it is assumed to be `.mpatrol'. Any 9002 differences are written to the mpatrol log file. Returns the 9003 number of differences found, or `-1' if there was an error. 9004 9005`int __mp_remcontents(const char *file, const void *ptr)' 9006 Removes the memory allocation contents file that corresponds to 9007 the memory allocation containing PTR. The name of the file is 9008 composed of the FILE string followed by the allocation index of 9009 the memory allocation separated by a dot. If FILE is `NULL' then 9010 it is assumed to be `.mpatrol'. Returns `1' if the file was 9011 removed successfully and `0' otherwise. 9012 9013 9014File: mpatrol.info, Node: Environment, Next: Options, Prev: Functions, Up: Top 9015 9016Environment 9017*********** 9018 9019 The library can read certain options at run-time from an environment 9020variable called `MPATROL_OPTIONS'. This variable must contain one or 9021more valid option keywords from the list below and must be no longer 9022than 1024 characters in length. If `MPATROL_OPTIONS' is unset or empty 9023then the default settings will be used. 9024 9025 The syntax for options specified within the `MPATROL_OPTIONS' 9026environment variable is `OPTION' or `OPTION=VALUE', where `OPTION' is a 9027keyword from the list below and `VALUE' is the setting for that option. 9028If `VALUE' is numeric then it may be specified using binary, octal, 9029decimal or hexadecimal notation, with binary notation beginning with 9030either `0b' or `0B'. If `VALUE' is a character string containing 9031spaces then it may be quoted using double quotes. No whitespace may 9032appear between the `=' sign, but whitespace must appear between 9033different options. Note that option keywords can be given in lowercase 9034as well as uppercase, or a mixture of both. 9035 9036`ALLOCBYTE'=<UNSIGNED-INTEGER> 9037 Specifies an 8-bit byte pattern with which to prefill 9038 newly-allocated memory. This can be used to detect the use of 9039 memory which has not been initialised after allocation. Note that 9040 this setting will not affect memory allocated with `calloc()' or 9041 `recalloc()' as these functions always prefill allocated memory 9042 with an 8-bit byte pattern of zero. Default value: 9043 `ALLOCBYTE=0xFF'. 9044 9045`ALLOCSTOP'=<UNSIGNED-INTEGER> 9046 Specifies an allocation index at which to stop the program when it 9047 is being allocated. When the number of memory allocations reaches 9048 this number the program will be halted, and its state may be 9049 examined at that point by using a suitable debugger. Note that 9050 this setting will be ignored if its value is zero. Default value: 9051 `ALLOCSTOP=0'. 9052 9053`ALLOWOFLOW' 9054 Specifies that a warning rather than an error should be produced 9055 if any memory operation function overflows the boundaries of a 9056 memory allocation, and that the operation should still be 9057 performed. This option is provided for circumstances where it is 9058 desirable for the memory operation to be performed, regardless of 9059 whether it is erroneous or not. 9060 9061`AUTOSAVE'=<UNSIGNED-INTEGER> 9062 Specifies the frequency at which to periodically write the 9063 profiling data to the profiling output file. When the total 9064 number of profiled memory allocations and deallocations is a 9065 multiple of this number then the current profiling information 9066 will be written to the profiling output file. This option can be 9067 used to instruct the mpatrol library to dump out any profiling 9068 information just before a fatal error occurs in a program, for 9069 example. Note that this setting will be ignored if its value is 9070 zero. Default value: `AUTOSAVE=0'. 9071 9072`CHECK'=<UNSIGNED-RANGE> 9073 Specifies a range of allocation indices at which to check the 9074 integrity of free memory and overflow buffers. The range must be 9075 specified as no more than two unsigned integers separated by a 9076 dash, followed by an optional forward slash and an unsigned 9077 integer specifying an event checking frequency. If numbers on 9078 either the left side or the right side of the dash are omitted 9079 then they will be assumed to be `0' and INFINITY respectively. A 9080 value of `0' on its own indicates that no such checking will ever 9081 be performed. This option can be used to speed up the execution 9082 speed of the library at the expense of checking. Default value: 9083 `CHECK=0'. 9084 9085`CHECKALL' 9086 Equivalent to the `CHECKALLOCS', `CHECKREALLOCS', `CHECKFREES' and 9087 `CHECKMEMORY' options specified together. 9088 9089`CHECKALLOCS' 9090 Checks that no attempt is made to allocate a block of memory of 9091 size zero. A warning will be issued for every such case. 9092 9093`CHECKFORK' 9094 Checks at every call to see if the process has been forked in case 9095 new log, profiling and tracing output files need to be started. 9096 This option only has an effect on UNIX platforms, but should not 9097 be used in multithreaded programs if each thread has a different 9098 process identifier. 9099 9100`CHECKFREES' 9101 Checks that no attempt is made to deallocate a `NULL' pointer. A 9102 warning will be issued for every such case. 9103 9104`CHECKMEMORY' 9105 Checks that no attempt is made to perform a zero-length memory 9106 operation on a `NULL' pointer. 9107 9108`CHECKREALLOCS' 9109 Checks that no attempt is made to reallocate a `NULL' pointer or 9110 resize an existing block of memory to size zero. Warnings will be 9111 issued for every such case. 9112 9113`DEFALIGN'=<UNSIGNED-INTEGER> 9114 Specifies the default alignment for general-purpose memory 9115 allocations, which must be a power of two (and will be rounded up 9116 to the nearest power of two if it is not). The default alignment 9117 for a particular system is calculated at run-time. 9118 9119`EDIT' 9120 Specifies that a text editor should be invoked to edit any 9121 relevant source files that are associated with any warnings or 9122 errors when they occur. Only diagnostics which occur at source 9123 lines in the program will be affected and only then if they 9124 contain source-level information. This option is currently only 9125 available on UNIX platforms as it makes use of the `mpedit' 9126 command. It also overrides the behaviour of the `LIST' option and 9127 affects the behaviour of the `__mp_view()' function. 9128 9129`FAILFREQ'=<UNSIGNED-INTEGER> 9130 Specifies the frequency at which all memory allocations will 9131 randomly fail. For example, a value of `10' will mean that 9132 roughly 1 in 10 memory allocations will fail, but a value of `0' 9133 will disable all random failures. This option can be useful for 9134 stress-testing an application. Default value: `FAILFREQ=0'. 9135 9136`FAILSEED'=<UNSIGNED-INTEGER> 9137 Specifies the random number seed which will be used when 9138 determining which memory allocations will randomly fail. A value 9139 of `0' will instruct the library to pick a random seed every time 9140 it is run. Any other value will mean that the random failures 9141 will be the same every time the program is run, but only as long 9142 as the seed stays the same. Default value: `FAILSEED=0'. 9143 9144`FREEBYTE'=<UNSIGNED-INTEGER> 9145 Specifies an 8-bit byte pattern with which to prefill newly-freed 9146 memory. This can be used to detect the use of memory which has 9147 just been freed. It is also used internally to ensure that freed 9148 memory has not been overwritten. Note that the freed memory may 9149 be reused the next time a block of memory is allocated and so once 9150 memory has been freed its contents are not guaranteed to remain 9151 the same as the specified byte pattern. Default value: 9152 `FREEBYTE=0x55'. 9153 9154`FREESTOP'=<UNSIGNED-INTEGER> 9155 Specifies an allocation index at which to stop the program when it 9156 is being freed. When the memory allocation with the specified 9157 allocation index is to be freed the program will be halted, and 9158 its state may be examined at that point using a suitable debugger. 9159 Note that this setting will be ignored if its value is zero. 9160 Default value: `FREESTOP=0'. 9161 9162`HELP' 9163 Displays a quick-reference option summary to the `stderr' file 9164 stream. 9165 9166`LARGEBOUND'=<UNSIGNED-INTEGER> 9167 Specifies the limit in bytes up to which memory allocations should 9168 be classified as large allocations for profiling purposes. This 9169 limit must be greater than the small and medium bounds. Default 9170 value: `LARGEBOUND=2048'. 9171 9172`LEAKTABLE' 9173 Specifies that the leak table should be automatically used and a 9174 leak table summary should be displayed at the end of program 9175 execution. The summary shows a flat profile of all unfreed memory 9176 allocations since the start of the program, or since the last call 9177 to `__mp_clearleaktable()' if that function was called. 9178 9179`LIMIT'=<UNSIGNED-INTEGER> 9180 Specifies the limit in bytes at which all memory allocations 9181 should fail if the total allocated memory should increase beyond 9182 this. This can be used to stress-test software to see how it 9183 behaves in low memory conditions. The internal memory used by the 9184 library itself will not be counted as part of the total heap size, 9185 but on some systems there may be a small amount of memory required 9186 to initialise the library itself. Note that this setting will be 9187 ignored if its value is zero. Default value: `LIMIT=0'. 9188 9189`LIST' 9190 Specifies that a context listing should be shown for any relevant 9191 source files that are associated with any warnings or errors when 9192 they occur. Only diagnostics which occur at source lines in the 9193 program will be affected and only then if they contain 9194 source-level information. This option is currently only available 9195 on UNIX platforms as it makes use of the `mpedit' command. It 9196 also overrides the behaviour of the `EDIT' option and affects the 9197 behaviour of the `__mp_view()' function. 9198 9199`LOGALL' 9200 Equivalent to the `LOGALLOCS', `LOGREALLOCS', `LOGFREES' and 9201 `LOGMEMORY' options specified together. 9202 9203`LOGALLOCS' 9204 Specifies that all memory allocations are to be logged and sent to 9205 the log file. Note that any memory allocations made internally by 9206 the library will not be logged. 9207 9208`LOGFILE'=<STRING> 9209 Specifies an alternative file in which to place all diagnostics 9210 from the mpatrol library. If the `LOGDIR' environment variable is 9211 set and the specified file does not contain a path component in 9212 its filename then the log file will be located in the directory 9213 specified in `LOGDIR'. A filename of `stderr' will send all 9214 diagnostics to the `stderr' file stream and a filename of `stdout' 9215 will do the equivalent with the `stdout' file stream. Note that 9216 if a problem occurs while opening the log file or if any 9217 diagnostics require to be displayed before the log file has had a 9218 chance to be opened then they will be sent to the `stderr' file 9219 stream. Default value: `LOGFILE=mpatrol.log' or 9220 `LOGFILE=%n.%p.log' if the `LOGDIR' environment variable is set. 9221 9222`LOGFREES' 9223 Specifies that all memory deallocations are to be logged and sent 9224 to the log file. Note that any memory deallocations made 9225 internally by the library will not be logged. 9226 9227`LOGMEMORY' 9228 Specifies that all memory operations are to be logged and sent to 9229 the log file. These operations will be made by calls to functions 9230 such as `memset()' and `memcpy()'. Note that any memory 9231 operations made internally by the library will not be logged. 9232 9233`LOGREALLOCS' 9234 Specifies that all memory reallocations are to be logged and sent 9235 to the log file. Note that any memory reallocations made 9236 internally by the library will not be logged. 9237 9238`MEDIUMBOUND'=<UNSIGNED-INTEGER> 9239 Specifies the limit in bytes up to which memory allocations should 9240 be classified as medium allocations for profiling purposes. This 9241 limit must be greater than the small bound but less than the large 9242 bound. Default value: `MEDIUMBOUND=256'. 9243 9244`NOFREE'=<UNSIGNED-INTEGER> 9245 Specifies that a number of recently-freed memory allocations 9246 should be prevented from being returned to the free memory pool. 9247 Such freed memory allocations will then be flagged as freed and 9248 can be used by the library to provide better diagnostics. If the 9249 size of the freed queue is specified as zero then all freed memory 9250 will be immediately reused by the mpatrol library. Note that if 9251 this option is given a non-zero value then the mpatrol library 9252 will always force a memory reallocation to return a pointer to 9253 newly-allocated memory, but the `expand()' function will never be 9254 affected by this option. Default value: `NOFREE=0'. 9255 9256`NOPROTECT' 9257 Specifies that the mpatrol library's internal data structures 9258 should not be made read-only after every memory allocation, 9259 reallocation or deallocation. This may significantly speed up 9260 execution but this will be at the expense of less safety if the 9261 program accidentally overwrites some of the library's internal data 9262 structures. Note that this option has no effect on systems that 9263 do not support memory protection. 9264 9265`OFLOWBYTE'=<UNSIGNED-INTEGER> 9266 Specifies an 8-bit byte pattern with which to fill the overflow 9267 buffers of all memory allocations. This is used internally to 9268 ensure that nothing has been written beyond the beginning or the 9269 end of a block of allocated memory. Note that this setting will 9270 only have an effect if the `OFLOWSIZE' option is in use. Default 9271 value: `OFLOWBYTE=0xAA'. 9272 9273`OFLOWSIZE'=<UNSIGNED-INTEGER> 9274 Specifies the size in bytes to use for all overflow buffers, which 9275 must be a power of two (and will be rounded up to the nearest 9276 power of two if it is not). This is used internally to ensure 9277 that nothing has been written beyond the beginning or the end of a 9278 block of allocated memory. Note that this setting specifies the 9279 size for only one of the overflow buffers given to each memory 9280 allocation; the other overflow buffer will have an identical size. 9281 No overflow buffers will be used if this setting is zero. 9282 Default value: `OFLOWSIZE=0'. 9283 9284`OFLOWWATCH' 9285 Specifies that watch point areas should be used for overflow 9286 buffers rather than filling with the overflow byte. This can 9287 significantly reduce the speed of program execution. Note that 9288 this option has no effect on systems that do not support watch 9289 point areas. 9290 9291`PAGEALLOC'=<`LOWER'|`UPPER'> 9292 Specifies that each individual memory allocation should occupy at 9293 least one page of virtual memory and should be placed at the 9294 lowest or highest point within these pages. This allows the 9295 library to place an overflow buffer of one page on either side of 9296 every memory allocation and write-protect these pages as well as 9297 all free and freed memory. Note that this option has no effect on 9298 systems that do not support memory protection, and is disabled by 9299 default on other systems as it can slow down the speed of program 9300 execution. 9301 9302`PRESERVE' 9303 Specifies that any reallocated or freed memory allocations should 9304 preserve their original contents. This option must be used with 9305 the `NOFREE' option and has no effect otherwise. 9306 9307`PROF' 9308 Specifies that all memory allocations and deallocations are to be 9309 profiled and sent to the profiling output file. Memory 9310 reallocations are treated as a memory deallocation immediately 9311 followed by a memory allocation. 9312 9313`PROFFILE'=<STRING> 9314 Specifies an alternative file in which to place all memory 9315 allocation profiling information from the mpatrol library. If the 9316 `PROFDIR' environment variable is set and the specified file does 9317 not contain a path component in its filename then the profiling 9318 output file will be located in the directory specified in 9319 `PROFDIR'. A filename of `stderr' will send this information to 9320 the `stderr' file stream and a filename of `stdout' will do the 9321 equivalent with the `stdout' file stream. Note that if a problem 9322 occurs while opening the profiling output file then the profiling 9323 information will not be output. Default value: 9324 `PROFFILE=mpatrol.out' or `PROFFILE=%n.%p.out' if the `PROFDIR' 9325 environment variable is set. 9326 9327`PROGFILE'=<STRING> 9328 Specifies an alternative filename with which to locate the 9329 executable file containing the program's symbols. On most 9330 systems, the library will automatically be able to determine this 9331 filename, but on a few systems this option may have to be used 9332 before any or all symbols can be read. 9333 9334`REALLOCSTOP'=<UNSIGNED-INTEGER> 9335 Specifies a reallocation index at which to stop the program when a 9336 memory allocation is being reallocated. If the `ALLOCSTOP' option 9337 is non-zero then the program will be halted when the allocation 9338 matching that allocation index is reallocated the specified number 9339 of times. Otherwise the program will be halted the first time any 9340 allocation is reallocated the specified number of times. Note 9341 that this setting will be ignored if its value is zero. Default 9342 value: `REALLOCSTOP=0'. 9343 9344`SAFESIGNALS' 9345 Instructs the library to save and replace certain signal handlers 9346 during the execution of library code and to restore them 9347 afterwards. This was the default behaviour in version 1.0 of the 9348 mpatrol library and was changed since some memory-intensive 9349 programs became very hard to interrupt using the keyboard, thus 9350 giving the impression that the program or system had hung. 9351 9352`SHOWALL' 9353 Equivalent to the `SHOWFREE', `SHOWFREED', `SHOWUNFREED', 9354 `SHOWMAP' and `SHOWSYMBOLS' options specified together. 9355 9356`SHOWFREE' 9357 Specifies that a summary of all of the free memory blocks should 9358 be displayed at the end of program execution. This step will not 9359 be performed if an abnormal termination occurs or if there were no 9360 free memory blocks. 9361 9362`SHOWFREED' 9363 Specifies that a summary of all of the freed memory allocations 9364 should be displayed at the end of program execution. This option 9365 must be used in conjunction with the `NOFREE' option and this step 9366 will not be performed if an abnormal termination occurs or if 9367 there were no freed allocations. 9368 9369`SHOWMAP' 9370 Specifies that a memory map of the entire heap should be displayed 9371 at the end of program execution. This step will not be performed 9372 if an abnormal termination occurs or if the heap is empty. 9373 9374`SHOWSYMBOLS' 9375 Specifies that a summary of all of the function symbols read from 9376 the program's executable file should be displayed at the end of 9377 program execution. This step will not be performed if an abnormal 9378 termination occurs or if no symbols could be read from the 9379 executable file. 9380 9381`SHOWUNFREED' 9382 Specifies that a summary of all of the unfreed memory allocations 9383 should be displayed at the end of program execution. This step 9384 will not be performed if an abnormal termination occurs or if 9385 there are no unfreed allocations. Note that any marked memory 9386 allocations will not be listed. 9387 9388`SMALLBOUND'=<UNSIGNED-INTEGER> 9389 Specifies the limit in bytes up to which memory allocations should 9390 be classified as small allocations for profiling purposes. This 9391 limit must be greater than zero but less than the medium and large 9392 bounds. Default value: `SMALLBOUND=32'. 9393 9394`TRACE' 9395 Specifies that all memory allocations, reallocations and 9396 deallocations are to be traced and sent to the tracing output file. 9397 9398`TRACEFILE'=<STRING> 9399 Specifies an alternative file in which to place all memory 9400 allocation tracing information from the mpatrol library. If the 9401 `TRACEDIR' environment variable is set and the specified file does 9402 not contain a path component in its filename then the tracing 9403 output file will be located in the directory specified in 9404 `TRACEDIR'. A filename of `stderr' will send this information to 9405 the `stderr' file stream and a filename of `stdout' will do the 9406 equivalent with the `stdout' file stream. Note that if a problem 9407 occurs while opening the tracing output file then the tracing 9408 information will not be output. Default value: 9409 `TRACEFILE=mpatrol.trace' or `TRACEFILE=%n.%p.trace' if the 9410 `TRACEDIR' environment variable is set. 9411 9412`UNFREEDABORT'=<UNSIGNED-INTEGER> 9413 Specifies the minimum number of unfreed allocations at which to 9414 abort the program just before program termination. A summary of 9415 all the allocations will be displayed on the standard error file 9416 stream before aborting. This option may be handy for use in batch 9417 tests as it can force tests to fail if they do not free up a 9418 minimum number of memory allocations, although marked allocations 9419 will not be considered as unfreed allocations. Note that this 9420 setting will be ignored if its value is zero. Default value: 9421 `UNFREEDABORT=0'. 9422 9423`USEDEBUG' 9424 Specifies that any debugging information in the executable file 9425 should be used to obtain additional source-level information. 9426 This option will only have an effect if the executable file 9427 contains a compiler-generated line number table and will be 9428 ignored if the mpatrol library was built to support an object file 9429 access library that cannot read line tables from object files. 9430 Note that this option will slow down program execution, use up 9431 more system memory and may leave unaccounted unfreed memory 9432 allocations at program termination. 9433 9434`USEMMAP' 9435 Specifies that the library should use `mmap()' instead of `sbrk()' 9436 to allocate user memory on UNIX platforms. This option should be 9437 used if there are problems when using the mpatrol library in 9438 combination with another malloc library which uses `sbrk()' to 9439 allocate its memory. Memory internal to the mpatrol library is 9440 allocated with `mmap()' on systems where it is supported in order 9441 to segregate it from user memory, and this behaviour is reversed 9442 with the `USEMMAP' option. It is ignored on systems that do not 9443 support the `mmap()' system call. Note that some UNIX systems 9444 require this option in order for the mpatrol library to be able to 9445 perform memory protection with the `mprotect()' system call. 9446 9447 9448File: mpatrol.info, Node: Options, Next: Diagnostic messages, Prev: Environment, Up: Top 9449 9450Options 9451******* 9452 9453 A utility program called `mpatrol' is provided to run commands that 9454have been linked with the mpatrol library. 9455 9456 mpatrol [options] <command> [arguments] 9457 9458 The `mpatrol' command is used to set various mpatrol library OPTIONS 9459when running COMMAND with its ARGUMENTS. In most cases, COMMAND must 9460have been linked with the mpatrol library, unless the `--dynamic' 9461option is used in which case COMMAND need only have been dynamically 9462linked. 9463 9464 All mpatrol library diagnostics are sent to the file 9465`mpatrol.%n.log' in the current directory by default (where `%n' is the 9466current process id) but this can be changed using the `--log-file' 9467option. Similarly, the default profiling output filename is 9468`mpatrol.%n.out' and the default tracing output filename is 9469`mpatrol.%n.trace'. 9470 9471 Alternatively, the log file, profiling output file and tracing 9472output file names can contain `%p', which will be replaced with the 9473name of the program being executed without the directory components. 9474If the executable filename could not be determined or was not set then 9475it will be replaced with `mpatrol'. A similar replacement character 9476sequence is `%f', which will be replaced by the pathname of the program 9477being executed, with all path separation characters replaced by 9478underscores. 9479 9480 The current date can be entered into such filenames through the use 9481of the `%d' character sequence, which will be replaced with the date in 9482the form `YYYYMMDD'. The current time can be added with `%t', which 9483will be replaced with the time in the form `HHMMSS'. If the date or 9484time could not be determined, these will be replaced with `today' and 9485`now' respectively. 9486 9487 All of the following options (except `--dynamic', `--help', 9488`--read-env', `--show-env', `--threads' and `--version') correspond to 9489their listed mpatrol library option (*note Environment::). Note that 9490some of these options have a one character equivalent option that can 9491be used for brevity. The list of one character options can be viewed 9492with the `--help' option or viewed in the UNIX manual pages. Such 9493options are parsed on the command line in a similar way to the UNIX 9494function `getopt()'. 9495 9496`--alloc-byte' <UNSIGNED-INTEGER> 9497 [`ALLOCBYTE'] Specifies an 8-bit byte pattern with which to 9498 prefill newly-allocated memory. 9499 9500`--alloc-stop' <UNSIGNED-INTEGER> 9501 [`ALLOCSTOP'] Specifies an allocation index at which to stop the 9502 program when it is being allocated. 9503 9504`--allow-oflow' 9505 [`ALLOWOFLOW'] Specifies that a warning rather than an error 9506 should be produced if any memory operation function overflows the 9507 boundaries of a memory allocation, and that the operation should 9508 still be performed. 9509 9510`--auto-save' <UNSIGNED-INTEGER> 9511 [`AUTOSAVE'] Specifies the frequency at which to periodically 9512 write the profiling data to the profiling output file. 9513 9514`--check' <UNSIGNED-RANGE> 9515 [`CHECK'] Specifies a range of allocation indices at which to 9516 check the integrity of free memory and overflow buffers. 9517 9518`--check-all' 9519 [`CHECKALL'] Equivalent to the `--check-allocs', 9520 `--check-reallocs', `--check-frees' and `--check-memory' options 9521 specified together. 9522 9523`--check-allocs' 9524 [`CHECKALLOCS'] Checks that no attempt is made to allocate a 9525 block of memory of size zero. 9526 9527`--check-fork' 9528 [`CHECKFORK'] Checks at every call to see if the process has been 9529 forked in case new log, profiling and tracing output files need to 9530 be started. 9531 9532`--check-frees' 9533 [`CHECKFREES'] Checks that no attempt is made to deallocate a 9534 `NULL' pointer. 9535 9536`--check-memory' 9537 [`CHECKMEMORY'] Checks that no attempt is made to perform a 9538 zero-length memory operation on a `NULL' pointer. 9539 9540`--check-reallocs' 9541 [`CHECKREALLOCS'] Checks that no attempt is made to reallocate a 9542 `NULL' pointer or resize an existing block of memory to size zero. 9543 9544`--def-align' <UNSIGNED-INTEGER> 9545 [`DEFALIGN'] Specifies the default alignment for general-purpose 9546 memory allocations, which must be a power of two. 9547 9548`--dynamic' 9549 Specifies that programs which were not linked with the mpatrol 9550 library should also be traced, but only if they were dynamically 9551 linked. This option will only work if the system dynamic linker 9552 has the ability to preload a set of user-specified shared 9553 libraries via a special environment variable. 9554 9555`--edit' 9556 [`EDIT'] Specifies that a text editor should be invoked to edit 9557 any relevant source files that are associated with any warnings or 9558 errors when they occur. 9559 9560`--fail-freq' <UNSIGNED-INTEGER> 9561 [`FAILFREQ'] Specifies the frequency at which all memory 9562 allocations will randomly fail. 9563 9564`--fail-seed' <UNSIGNED-INTEGER> 9565 [`FAILSEED'] Specifies the random number seed which will be used 9566 when determining which memory allocations will randomly fail. 9567 9568`--free-byte' <UNSIGNED-INTEGER> 9569 [`FREEBYTE'] Specifies an 8-bit byte pattern with which to prefill 9570 newly-freed memory. 9571 9572`--free-stop' <UNSIGNED-INTEGER> 9573 [`FREESTOP'] Specifies an allocation index at which to stop the 9574 program when it is being freed. 9575 9576`--help' 9577 Displays a quick-reference option summary. 9578 9579`--large-bound' <UNSIGNED-INTEGER> 9580 [`LARGEBOUND'] Specifies the limit in bytes up to which memory 9581 allocations should be classified as large allocations for 9582 profiling purposes. 9583 9584`--leak-table' 9585 [`LEAKTABLE'] Specifies that the leak table should be 9586 automatically used and a leak table summary should be displayed at 9587 the end of program execution. 9588 9589`--limit' <UNSIGNED-INTEGER> 9590 [`LIMIT'] Specifies the limit in bytes at which all memory 9591 allocations should fail if the total allocated memory should 9592 increase beyond this. 9593 9594`--list' 9595 [`LIST'] Specifies that a context listing should be shown for any 9596 relevant source files that are associated with any warnings or 9597 errors when they occur. 9598 9599`--log-all' 9600 [`LOGALL'] Equivalent to the `--log-allocs', `--log-reallocs', 9601 `--log-frees' and `--log-memory' options specified together. 9602 9603`--log-allocs' 9604 [`LOGALLOCS'] Specifies that all memory allocations are to be 9605 logged and sent to the log file. 9606 9607`--log-file' <STRING> 9608 [`LOGFILE'] Specifies an alternative file in which to place all 9609 diagnostics from the mpatrol library. 9610 9611`--log-frees' 9612 [`LOGFREES'] Specifies that all memory deallocations are to be 9613 logged and sent to the log file. 9614 9615`--log-memory' 9616 [`LOGMEMORY'] Specifies that all memory operations are to be 9617 logged and sent to the log file. 9618 9619`--log-reallocs' 9620 [`LOGREALLOCS'] Specifies that all memory reallocations are to be 9621 logged and sent to the log file. 9622 9623`--medium-bound' <UNSIGNED-INTEGER> 9624 [`MEDIUMBOUND'] Specifies the limit in bytes up to which memory 9625 allocations should be classified as medium allocations for 9626 profiling purposes. 9627 9628`--no-free' <UNSIGNED-INTEGER> 9629 [`NOFREE'] Specifies that a number of recently-freed memory 9630 allocations should be prevented from being returned to the free 9631 memory pool. 9632 9633`--no-protect' 9634 [`NOPROTECT'] Specifies that the mpatrol library's internal data 9635 structures should not be made read-only after every memory 9636 allocation, reallocation or deallocation. 9637 9638`--oflow-byte' <UNSIGNED-INTEGER> 9639 [`OFLOWBYTE'] Specifies an 8-bit byte pattern with which to fill 9640 the overflow buffers of all memory allocations. 9641 9642`--oflow-size' <UNSIGNED-INTEGER> 9643 [`OFLOWSIZE'] Specifies the size in bytes to use for all overflow 9644 buffers, which must be a power of two. 9645 9646`--oflow-watch' 9647 [`OFLOWWATCH'] Specifies that watch point areas should be used for 9648 overflow buffers rather than filling with the overflow byte. 9649 9650`--page-alloc-lower' 9651 [`PAGEALLOC=LOWER'] Specifies that each individual memory 9652 allocation should occupy at least one page of virtual memory and 9653 should be placed at the lowest point within these pages. 9654 9655`--page-alloc-upper' 9656 [`PAGEALLOC=UPPER'] Specifies that each individual memory 9657 allocation should occupy at least one page of virtual memory and 9658 should be placed at the highest point within these pages. 9659 9660`--preserve' 9661 [`PRESERVE'] Specifies that any reallocated or freed memory 9662 allocations should preserve their original contents. 9663 9664`--prof' 9665 [`PROF'] Specifies that all memory allocations are to be profiled 9666 and sent to the profiling output file. 9667 9668`--prof-file' <STRING> 9669 [`PROFFILE'] Specifies an alternative file in which to place all 9670 memory allocation profiling information from the mpatrol library. 9671 9672`--prog-file' <STRING> 9673 [`PROGFILE'] Specifies an alternative filename with which to 9674 locate the executable file containing the program's symbols. 9675 9676`--read-env' 9677 Reads and passes through the contents of the `MPATROL_OPTIONS' 9678 environment variable. Such contents will be placed before any of 9679 the options resulting from `mpatrol' command line options so that 9680 they can be overridden and will only be parsed by the mpatrol 9681 library, _not_ the `mpatrol' command. 9682 9683`--realloc-stop' <UNSIGNED-INTEGER> 9684 [`REALLOCSTOP'] Specifies an allocation index at which to stop the 9685 program when a memory allocation is being reallocated. 9686 9687`--safe-signals' 9688 [`SAFESIGNALS'] Instructs the library to save and replace certain 9689 signal handlers during the execution of library code and to 9690 restore them afterwards. 9691 9692`--show-all' 9693 [`SHOWALL'] Equivalent to the `--show-free', `--show-freed', 9694 `--show-unfreed', `--show-map' and `--show-symbols' options 9695 specified together. 9696 9697`--show-env' 9698 Displays the contents of the `MPATROL_OPTIONS' environment 9699 variable. This will be shown after all of the other command line 9700 options have been processed and will prevent the specified command 9701 from being run. 9702 9703`--show-free' 9704 [`SHOWFREE'] Specifies that a summary of all of the free memory 9705 blocks should be displayed at the end of program execution. 9706 9707`--show-freed' 9708 [`SHOWFREED'] Specifies that a summary of all of the freed memory 9709 allocations should be displayed at the end of program execution. 9710 9711`--show-map' 9712 [`SHOWMAP'] Specifies that a memory map of the entire heap should 9713 be displayed at the end of program execution. 9714 9715`--show-symbols' 9716 [`SHOWSYMBOLS'] Specifies that a summary of all of the function 9717 symbols read from the program's executable file should be 9718 displayed at the end of program execution. 9719 9720`--show-unfreed' 9721 [`SHOWUNFREED'] Specifies that a summary of all of the unfreed 9722 memory allocations should be displayed at the end of program 9723 execution. 9724 9725`--small-bound' <UNSIGNED-INTEGER> 9726 [`SMALLBOUND'] Specifies the limit in bytes up to which memory 9727 allocations should be classified as small allocations for 9728 profiling purposes. 9729 9730`--threads' 9731 Specifies that the program to be run is multithreaded if the 9732 `--dynamic' option is used. This option is required if the 9733 multithreaded version of the mpatrol library should be preloaded 9734 instead of the normal version. 9735 9736`--trace' 9737 [`TRACE'] Specifies that all memory allocations are to be traced 9738 and sent to the tracing output file. 9739 9740`--trace-file' <STRING> 9741 [`TRACEFILE'] Specifies an alternative file in which to place all 9742 memory allocation tracing information from the mpatrol library. 9743 9744`--unfreed-abort' <UNSIGNED-INTEGER> 9745 [`UNFREEDABORT'] Specifies the minimum number of unfreed 9746 allocations at which to abort the program just before program 9747 termination. 9748 9749`--use-debug' 9750 [`USEDEBUG'] Specifies that any debugging information in the 9751 executable file should be used to obtain additional source-level 9752 information. 9753 9754`--use-mmap' 9755 [`USEMMAP'] Specifies that the library should use `mmap()' instead 9756 of `sbrk()' to allocate user memory. 9757 9758`--version' 9759 Displays the version number of the `mpatrol' command. 9760 9761 9762File: mpatrol.info, Node: Diagnostic messages, Next: Library performance, Prev: Options, Up: Top 9763 9764Diagnostic messages 9765******************* 9766 9767 The following table lists the warnings and errors that are likely to 9768appear in the mpatrol log file when problems with dynamic memory 9769allocations and memory operations occur. Other types of warnings and 9770errors may also appear in the log file, but they are likely to be 9771associated with parsing options and reading symbols from executable 9772files and so should be self-explanatory. 9773 9774 In all cases, if a warning or error is caused by one of the memory 9775access checking functions (invoked through the use of the 9776`-fcheck-memory-usage' option to the GNU compiler) then execution will 9777halt regardless, despite what the description of the diagnostic message 9778says. 9779 9780 If a warning or error occurs due to a direct call to an mpatrol 9781library function then an attempt will be made to provide a log entry 9782for the call. If the diagnostic was not caused by a normal memory 9783allocation, reallocation or deallocation function then the log entry 9784will be preceded by `LOG:'. The function type will be listed as 9785`check' if it does not fall into the normal categories or if not enough 9786information is available. 9787 9788 Note that on UNIX platforms, if the diagnostic message is caused by 9789a line in the program source then the `EDIT' and `LIST' options can be 9790used to illustrate more clearly where in the source code the warning or 9791error occurred. 9792 9793 * `ALLOVF' 9794 Message 9795 `allocation %1 has a corrupted overflow buffer at %2' 9796 9797 Type 9798 Error 9799 9800 `%1' 9801 The pointer to the memory allocation that has a corrupted 9802 overflow buffer. 9803 9804 `%2' 9805 The pointer to the first byte of corruption in the memory 9806 allocation's overflow buffer. 9807 9808 Cause 9809 Something has corrupted the overflow buffer of a memory 9810 allocation and this has been caught at the next invocation of 9811 an mpatrol function when the `OFLOWSIZE' or `PAGEALLOC' 9812 options were used. This particular error message will not 9813 occur if the `OFLOWWATCH' option was used since all overflow 9814 buffers will be write protected. 9815 9816 Additional 9817 The log file entry, the library summary, the contents of the 9818 overflow buffer and information about the original memory 9819 allocation. 9820 9821 Result 9822 Execution terminates. 9823 9824 * `ALLZER' 9825 Message 9826 `attempt to create an allocation of size 0' 9827 9828 Type 9829 Warning 9830 9831 Cause 9832 A function was called to allocate memory with a size of `0' 9833 when either of the `CHECKALL' or `CHECKALLOCS' options were 9834 used. This warning will not occur by default as the ANSI 9835 C/C++ standards allow this behaviour, and it is really only a 9836 portability issue. 9837 9838 Additional 9839 The log file entry. 9840 9841 Result 9842 The size is increased to 1 byte and execution continues. 9843 9844 * `BADALN' 9845 Message 9846 `alignment %1 is not a power of two' 9847 9848 Type 9849 Warning 9850 9851 `%1' 9852 The alignment in bytes. 9853 9854 Cause 9855 The `memalign()' function was called to allocate memory with 9856 an alignment which was not a power of two when either of the 9857 `CHECKALL' or `CHECKALLOCS' options were used. 9858 9859 Additional 9860 The log file entry. 9861 9862 Result 9863 The alignment is rounded up to the nearest power of two and 9864 execution continues. 9865 9866 * `FRDCOR' 9867 Message 9868 `freed allocation %1 has memory corruption at %2' 9869 9870 Type 9871 Error 9872 9873 `%1' 9874 The pointer to the freed memory allocation that has been 9875 corrupted. 9876 9877 `%2' 9878 The pointer to the first byte of corruption in the freed 9879 memory allocation. 9880 9881 Cause 9882 Something has corrupted the contents of a previously freed 9883 memory allocation and this has been caught at the next 9884 invocation of an mpatrol function when the `NOFREE' option 9885 was used. This particular error message will not occur if 9886 the `PAGEALLOC' option was used since all freed memory 9887 allocations will be write protected and will also not occur 9888 if the `PRESERVE' option was used since the free byte cannot 9889 be used to verify the freed allocation's contents. 9890 9891 Additional 9892 The log file entry, the library summary, the contents of the 9893 freed memory block and information about the original memory 9894 allocation. 9895 9896 Result 9897 Execution terminates. 9898 9899 * `FRDOPN' 9900 Message 9901 `attempt to perform operation on freed memory' 9902 9903 Type 9904 Error 9905 9906 Cause 9907 A memory operation function was called to operate on a 9908 previously freed memory allocation when the `NOFREE' option 9909 was used. 9910 9911 Additional 9912 The log file entry and information about the original memory 9913 allocation. 9914 9915 Result 9916 The memory operation fails and execution continues. 9917 9918 * `FRDOVF' 9919 Message 9920 `freed allocation %1 has a corrupted overflow buffer at %2' 9921 9922 Type 9923 Error 9924 9925 `%1' 9926 The pointer to the freed memory allocation that has a 9927 corrupted overflow buffer. 9928 9929 `%2' 9930 The pointer to the first byte of corruption in the freed 9931 memory allocation's overflow buffer. 9932 9933 Cause 9934 Something has corrupted the overflow buffer of a previously 9935 freed memory allocation and this has been caught at the next 9936 invocation of an mpatrol function when the `NOFREE' option 9937 was used in conjunction with the `OFLOWSIZE' or `PAGEALLOC' 9938 options. This particular error message will not occur if the 9939 `OFLOWWATCH' option was used since all overflow buffers will 9940 be write protected. 9941 9942 Additional 9943 The log file entry, the library summary, the contents of the 9944 overflow buffer and information about the original memory 9945 allocation. 9946 9947 Result 9948 Execution terminates. 9949 9950 * `FRECOR' 9951 Message 9952 `free memory corruption at %1' 9953 9954 Type 9955 Error 9956 9957 `%1' 9958 The pointer to the first byte of corruption in free memory. 9959 9960 Cause 9961 Something has corrupted the contents of the free memory pool 9962 and this has been caught at the next invocation of an mpatrol 9963 function. This particular error message will not occur if 9964 the `PAGEALLOC' option was used since all free memory will be 9965 write protected. 9966 9967 Additional 9968 The log file entry, the library summary and the contents of 9969 the free memory block. 9970 9971 Result 9972 Execution terminates. 9973 9974 * `FREMRK' 9975 Message 9976 `attempt to free marked allocation %1' 9977 9978 Type 9979 Error 9980 9981 `%1' 9982 The pointer to the memory allocation that has been requested 9983 to be freed. 9984 9985 Cause 9986 An attempt was made to free a marked memory allocation. This 9987 is not allowed since any memory allocations that have been 9988 marked indicate to the mpatrol library that they should 9989 remain allocated for the duration of the program. 9990 9991 Additional 9992 The log file entry and information about the original memory 9993 allocation. 9994 9995 Result 9996 No memory allocation will be freed and execution continues. 9997 9998 * `FRENUL' 9999 Message 10000 `attempt to free a NULL pointer' 10001 10002 Type 10003 Warning 10004 10005 Cause 10006 A function was called to free an existing memory allocation 10007 with a pointer of `NULL' when either of the `CHECKALL' or 10008 `CHECKFREES' options were used. This warning will not occur 10009 by default as the ANSI C/C++ standards allow this behaviour, 10010 and it is really only a portability issue. 10011 10012 Additional 10013 The log file entry. 10014 10015 Result 10016 No memory allocation will be freed and execution continues. 10017 10018 * `FREOPN' 10019 Message 10020 `attempt to perform operation on free memory' 10021 10022 Type 10023 Error 10024 10025 Cause 10026 A memory operation function was called to operate on free 10027 memory. 10028 10029 Additional 10030 The log file entry. 10031 10032 Result 10033 The memory operation fails and execution continues. 10034 10035 * `ILLMEM' 10036 Message 10037 `illegal memory access at address %1' 10038 10039 Type 10040 Error 10041 10042 `%1' 10043 The address at which the illegal memory access occurred. 10044 10045 Cause 10046 An attempt was made to read from or write to an illegal 10047 address on systems which have virtual memory. This address 10048 may or may not exist in the heap, or it may be a perfectly 10049 valid address that was misaligned and caused a bus error. In 10050 either case, the mpatrol library will attempt to associate 10051 the address with an existing memory allocation. This error 10052 may also appear instead of memory corruption errors if the 10053 `PAGEALLOC' or `OFLOWWATCH' options were used. 10054 10055 Additional 10056 The library summary, information about the original memory 10057 allocation (if possible) and the call stack of where the 10058 error occurred. 10059 10060 Result 10061 Execution terminates. 10062 10063 * `INCOMP' 10064 Message 10065 `%1 was allocated with %2' 10066 10067 Type 10068 Error 10069 10070 `%1' 10071 The pointer to the memory allocation that is to be resized or 10072 freed. 10073 10074 `%2' 10075 The name of the function which originally allocated the 10076 memory allocation. 10077 10078 Cause 10079 A function was called to resize or free a memory allocation 10080 that was allocated with a function that is incompatible with 10081 the current request. For example, a memory allocation which 10082 was allocated with `operator new' being resized with 10083 `realloc()'. 10084 10085 Additional 10086 The log file entry and information about the original memory 10087 allocation. 10088 10089 Result 10090 The reallocation or deallocation fails and execution 10091 continues. 10092 10093 * `MAXALN' 10094 Message 10095 `alignment %1 is greater than the system page size' 10096 10097 Type 10098 Warning 10099 10100 `%1' 10101 The alignment in bytes. 10102 10103 Cause 10104 The `memalign()' function was called to allocate memory with 10105 an alignment which was greater than the system page size when 10106 either of the `CHECKALL' or `CHECKALLOCS' options were used. 10107 The mpatrol library cannot currently align memory allocations 10108 to a byte alignment over this limit, but then neither can 10109 most other implementations. 10110 10111 Additional 10112 The log file entry. 10113 10114 Result 10115 The alignment is set to the system page size and execution 10116 continues. 10117 10118 * `MISMAT' 10119 Message 10120 `%1 does not match allocation of %2' 10121 10122 Type 10123 Error 10124 10125 `%1' 10126 The pointer to the memory allocation that is to be resized or 10127 freed. 10128 10129 `%2' 10130 The pointer to the memory allocation that the mpatrol library 10131 knows about. 10132 10133 Cause 10134 A function was called to resize or free a memory allocation 10135 that begins at a different address from that supplied. 10136 10137 Additional 10138 The log file entry and information about the original memory 10139 allocation. 10140 10141 Result 10142 The reallocation or deallocation fails and execution 10143 continues. 10144 10145 * `NOTALL' 10146 Message 10147 `%1 has not been allocated' 10148 10149 Type 10150 Error 10151 10152 `%1' 10153 The pointer to the memory allocation that is to be resized or 10154 freed. 10155 10156 Cause 10157 A function was called to resize or free a memory allocation 10158 that has not been allocated. It may be that the memory 10159 allocation has just been freed, in which case the `NOFREE' 10160 option should be used to provide a better diagnostic message. 10161 10162 Additional 10163 The log file entry. 10164 10165 Result 10166 The reallocation or deallocation fails and execution 10167 continues. 10168 10169 * `NULOPN' 10170 Message 10171 `attempt to perform operation on a NULL pointer' 10172 10173 Type 10174 Error 10175 10176 Cause 10177 A memory operation function was called to operate on a `NULL' 10178 pointer. If the length of the operation was zero then this 10179 error will only occur when the `CHECKALL' or `CHECKMEMORY' 10180 options were used as the ANSI C/C++ standards allow this 10181 behaviour, and it is really only a portability issue. 10182 10183 Additional 10184 The log file entry. 10185 10186 Result 10187 The memory operation fails and execution continues. 10188 10189 * `OUTMEM' 10190 Message 10191 `out of memory' 10192 10193 Type 10194 Error 10195 10196 Cause 10197 The `alloca()', `xmalloc()' or `MP_MALLOC()' families of 10198 functions were called to allocate memory, but no more memory 10199 was available to allocate and the low-memory handler, if 10200 installed, could not free up sufficient memory. This error 10201 can also be caused by a call to the `operator new' or 10202 `operator new[]' C++ operators (not the _nothrow_ versions) 10203 when they would otherwise return a `NULL' pointer and the 10204 mpatrol library was compiled with a C compiler (which means 10205 that it cannot throw a `std::bad_alloc' exception). 10206 10207 Additional 10208 The library summary. 10209 10210 Result 10211 Execution terminates. 10212 10213 * `PRVFRD' 10214 Message 10215 `%1 was freed with %2' 10216 10217 Type 10218 Error 10219 10220 `%1' 10221 The pointer to the memory allocation that is to be resized or 10222 freed. 10223 10224 `%2' 10225 The name of the function which originally freed the memory 10226 allocation. 10227 10228 Cause 10229 A function was called to resize or free a memory allocation 10230 that had previously been freed when the `NOFREE' option was 10231 used. 10232 10233 Additional 10234 The log file entry and information about the original memory 10235 allocation. 10236 10237 Result 10238 The reallocation or deallocation fails and execution 10239 continues. 10240 10241 * `RNGOVF' 10242 Message 10243 `range [%1,%2] overflows [%3,%4]' 10244 10245 Type 10246 Warning/Error 10247 10248 `%1' 10249 The start address of the memory region. 10250 10251 `%2' 10252 The end address of the memory region. 10253 10254 `%3' 10255 The start address of the memory allocation. 10256 10257 `%4' 10258 The end address of the memory allocation. 10259 10260 Cause 10261 A memory operation function was called to operate on a range 10262 of memory which overflowed the boundaries of a memory 10263 allocation. 10264 10265 Additional 10266 The log file entry and information about the original memory 10267 allocation. 10268 10269 Result 10270 The operation will be only be performed (and will be changed 10271 from an error to a warning) if the `ALLOWOFLOW' option was 10272 used, but execution will continue regardless. 10273 10274 * `RNGOVL' 10275 Message 10276 `range [%1,%2] overlaps [%3,%4]' 10277 10278 Type 10279 Warning 10280 10281 `%1' 10282 The start address of the source memory region. 10283 10284 `%2' 10285 The end address of the source memory region. 10286 10287 `%3' 10288 The start address of the destination memory region. 10289 10290 `%4' 10291 The end address of the destination memory region. 10292 10293 Cause 10294 The `memcpy()' or `memccpy()' function was called to copy 10295 overlapping memory regions. This is an error on many systems 10296 and the ANSI C/C++ standards specify that `memmove()' should 10297 be used instead. 10298 10299 Additional 10300 The log file entry. 10301 10302 Result 10303 The copy operation will still be performed but it will deal 10304 correctly with overlapping memory regions. 10305 10306 * `RSZNUL' 10307 Message 10308 `attempt to resize a NULL pointer' 10309 10310 Type 10311 Warning 10312 10313 Cause 10314 A function was called to resize an existing memory allocation 10315 with a pointer of `NULL' when either of the `CHECKALL' or 10316 `CHECKREALLOCS' options were used. This warning will not 10317 occur by default as the ANSI C/C++ standards allow this 10318 behaviour, and it is really only a portability issue. 10319 10320 Additional 10321 The log file entry. 10322 10323 Result 10324 A new memory allocation is returned and execution continues. 10325 10326 * `RSZZER' 10327 Message 10328 `attempt to resize an allocation to size 0' 10329 10330 Type 10331 Warning 10332 10333 Cause 10334 A function was called to resize an existing memory allocation 10335 to a size of `0' when either of the `CHECKALL' or 10336 `CHECKREALLOCS' options were used. This warning will not 10337 occur by default as the ANSI C/C++ standards allow this 10338 behaviour, and it is really only a portability issue. 10339 10340 Additional 10341 The log file entry. 10342 10343 Result 10344 The existing memory allocation will be freed and execution 10345 continues. 10346 10347 * `STROVF' 10348 Message 10349 `string %1 overflows [%2,%3]' 10350 10351 Type 10352 Error 10353 10354 `%1' 10355 The start address of the string. 10356 10357 `%2' 10358 The start address of the memory allocation. 10359 10360 `%3' 10361 The end address of the memory allocation. 10362 10363 Cause 10364 A string function was called to operate on a string which 10365 overflowed the boundaries of a memory allocation. 10366 10367 Additional 10368 The log file entry and information about the original memory 10369 allocation. 10370 10371 Result 10372 The operation will not be performed and execution continues. 10373 10374 * `ZERALN' 10375 Message 10376 `alignment 0 is invalid' 10377 10378 Type 10379 Warning 10380 10381 Cause 10382 The `memalign()' function was called to allocate memory with 10383 an alignment of `0' when either of the `CHECKALL' or 10384 `CHECKALLOCS' options were used. 10385 10386 Additional 10387 The log file entry. 10388 10389 Result 10390 The alignment is set to the default system alignment and 10391 execution continues. 10392 10393 10394File: mpatrol.info, Node: Library performance, Next: File formats, Prev: Diagnostic messages, Up: Top 10395 10396Library performance 10397******************* 10398 10399 The following times were obtained on a Sun Ultra 5 with an 10400UltraSPARC IIi processor running at 333MHz and running Solaris 7. The 10401test performed was the one in `tests/pass/test1.c' and all tests were 10402run on a lightly loaded system, but were run several times to obtain an 10403average result. Obviously, these times can only be an approximation, 10404but should serve to illustrate the effects on performance that each 10405option can have. All times are given in seconds, and the second time 10406on each line was obtained with the same options plus the `NOPROTECT' 10407option. The tests were all run with the default `CHECK=0' option, so 10408running with the `CHECK=-' option would slow things down dramatically, 10409albeit with more checking being performed to detect heap corruption. 10410 10411 Running with basic options: 10412 10413_no options_ 0.525 0.258 10414`OFLOWSIZE=2' 0.569 0.265 10415`OFLOWSIZE=8' 0.580 0.276 10416`PAGEALLOC=LOWER' 0.709 0.462 10417`PAGEALLOC=UPPER' 0.742 0.485 10418 10419 Running when all freed memory allocations are kept: 10420 10421`NOFREE=0xFFFF' 0.711 0.338 10422`NOFREE=0xFFFF OFLOWSIZE=2' 0.725 0.350 10423`NOFREE=0xFFFF OFLOWSIZE=8' 0.739 0.358 10424`NOFREE=0xFFFF PAGEALLOC=LOWER' 1.048 0.710 10425`NOFREE=0xFFFF PAGEALLOC=UPPER' 1.079 0.722 10426 10427 Running when all freed memory allocations are kept and their 10428contents are preserved: 10429 10430`NOFREE=0xFFFF PRESERVE' 0.725 0.341 10431`NOFREE=0xFFFF PRESERVE OFLOWSIZE=2' 0.735 0.357 10432`NOFREE=0xFFFF PRESERVE OFLOWSIZE=8' 0.745 0.360 10433`NOFREE=0xFFFF PRESERVE PAGEALLOC=LOWER' 1.055 0.722 10434`NOFREE=0xFFFF PRESERVE PAGEALLOC=UPPER' 1.081 0.729 10435 10436 Running using watch points to check the overflow buffers: 10437 10438`OFLOWSIZE=2 OFLOWWATCH' 28.758 28.372 10439 10440 Running using the Solaris malloc libraries: 10441 10442Solaris malloc(3c) library 0.030 10443Solaris malloc(3x) library 0.033 10444Solaris bsdmalloc(3x) library 0.027 10445Solaris mapmalloc(3x) library 0.030 10446Solaris watchmalloc(3x) library 30.323 10447 10448 10449File: mpatrol.info, Node: File formats, Next: Supported systems, Prev: Library performance, Up: Top 10450 10451File formats 10452************ 10453 10454 The formats of the profiling and tracing output files that are 10455produced by the mpatrol library are described here(1). 10456 10457* Menu: 10458 10459* Profiling file format:: Profiling output file layout. 10460* Tracing file format:: Tracing output file layout. 10461 10462 ---------- Footnotes ---------- 10463 10464 (1) The file `extra/magic' contains a UNIX _magic_ file excerpt for 10465automatically identifying an mpatrol log file, an mpatrol profiling 10466output file and an mpatrol tracing output file with the `file' command. 10467 10468 10469File: mpatrol.info, Node: Profiling file format, Next: Tracing file format, Up: File formats 10470 10471Profiling file format 10472===================== 10473 10474 Every mpatrol profiling output file contains the following 10475components. 10476 10477 * 4 bytes containing the characters `M', `P', `T' and `L'. 10478 10479 * 1 unsigned integer representing the value `1'. This is used by 10480 `mprof' to determine the endianness of the processor that produced 10481 the profiling output file so that it can decide whether to perform 10482 byte-swapping on the input data. 10483 10484 * 1 unsigned integer containing the version number of the mpatrol 10485 library which produced the profiling output file. 10486 10487 * 3 unsigned integers containing the small, medium and large 10488 allocation bounds. 10489 10490 * 1 unsigned integer containing the allocation bin size. If the 10491 allocation bin size is greater than zero then it is followed by 10492 the allocation bins, the large allocation totals, the deallocation 10493 bins and the large deallocation totals, where the bins are arrays 10494 of unsigned integers with dimensions of the allocation bin size 10495 and the totals are unsigned integers. 10496 10497 * 1 unsigned integer containing the number of profiling data 10498 structures. If the number of profiling data structures is greater 10499 than zero then it is followed by the profiling data structures 10500 themselves, which are of the following structure. 10501 10502 * 1 unsigned integer representing the index of this profiling 10503 data. 10504 10505 * 4 unsigned integers representing the small, medium, large and 10506 extra large allocation counts for this profiling data. 10507 10508 * 4 unsigned integers representing the small, medium, large and 10509 extra large allocation totals for this profiling data. 10510 10511 * 4 unsigned integers representing the small, medium, large and 10512 extra large deallocation counts for this profiling data. 10513 10514 * 4 unsigned integers representing the small, medium, large and 10515 extra large deallocation totals for this profiling data. 10516 10517 * 1 unsigned integer containing the number of call sites. If the 10518 number of call sites is greater than zero then it is followed by 10519 the call sites themselves, which are of the following structure. 10520 10521 * 1 unsigned integer representing the index of this call site. 10522 10523 * 1 unsigned integer representing the index of the parent call 10524 site. 10525 10526 * 1 generic pointer representing the code address of this call 10527 site. 10528 10529 * 1 unsigned integer representing the index of an associated 10530 symbol. 10531 10532 * 1 unsigned integer representing the offset of the symbol name. 10533 10534 * 1 unsigned integer representing the index of any associated 10535 profiling data. 10536 10537 * 1 unsigned integer containing the number of symbol addresses. If 10538 the number of symbol addresses is greater than zero then it is 10539 followed by the symbol addresses themselves, which are generic 10540 pointers. 10541 10542 * 1 unsigned integer containing the size of the symbol name string 10543 table. This is followed by the symbol name string table, which is 10544 an array of characters containing the nul-terminated symbol names. 10545 10546 * 4 bytes containing the characters `M', `P', `T' and `L'. 10547 10548 10549File: mpatrol.info, Node: Tracing file format, Prev: Profiling file format, Up: File formats 10550 10551Tracing file format 10552=================== 10553 10554 Every mpatrol tracing output file contains the following components. 10555 10556 * 4 bytes containing the characters `M', `T', `R' and `C'. 10557 10558 * 1 unsigned integer representing the value `1'. This is used by 10559 `mptrace' to determine the endianness of the processor that 10560 produced the tracing output file so that it can decide whether to 10561 perform byte-swapping on the input data. 10562 10563 * 1 unsigned integer containing the version number of the mpatrol 10564 library which produced the tracing output file. 10565 10566 * One or more of the following event records. 10567 10568 * If the event is a system heap allocation for use by the 10569 mpatrol library's internal data structures then the event 10570 record will begin with the character `I' followed by the 10571 start address and size in bytes of the heap allocation 10572 encoded as unsigned LEB128 numbers. 10573 10574 * If the event is a system heap allocation for use by the 10575 program's memory allocations then the event record will begin 10576 with the character `H' followed by the start address and size 10577 in bytes of the heap allocation encoded as unsigned LEB128 10578 numbers. 10579 10580 * If the event is a memory allocation then the event record 10581 will begin with the character `A' followed by the allocation 10582 index, start address and size in bytes of the memory 10583 allocation encoded as unsigned LEB128 numbers. From version 10584 1.4.5 of the mpatrol library, the thread identifier, function 10585 name, file name and line number are also written out as part 10586 of the event record (see below). 10587 10588 * If the event is a memory reallocation then the event record 10589 will begin with the character `R' followed by the allocation 10590 index, start address and size of the new memory allocation 10591 encoded as an unsigned LEB128 number. From version 1.4.5 of 10592 the mpatrol library, the thread identifier, function name, 10593 file name and line number are also written out as part of the 10594 event record (see below). 10595 10596 * If the event is a memory deallocation then the event record 10597 will begin with the character `F' followed by the allocation 10598 index of the memory allocation encoded as an unsigned LEB128 10599 number. From version 1.4.5 of the mpatrol library, the 10600 thread identifier, function name, file name and line number 10601 are also written out as part of the event record (see below). 10602 10603 * From version 1.4.5 of the mpatrol library, event records contain 10604 the following additional information. 10605 10606 * The thread identifier as an unsigned LEB128 number. 10607 10608 * The cached source function name. If the first byte is zero 10609 then there is no associated function name. If the first byte 10610 has the most significant bit set then the following 10611 null-terminated string defines a source function name 10612 associated with the number in the remaining 7 bits. If the 10613 first byte does not have the most significant bit set then it 10614 is taken to be the index of a previously defined source 10615 function name. 10616 10617 * The cached source file name. If the first byte is zero then 10618 there is no associated file name. If the first byte has the 10619 most significant bit set then the following null-terminated 10620 string defines a source file name associated with the number 10621 in the remaining 7 bits. If the first byte does not have the 10622 most significant bit set then it is taken to be the index of 10623 a previously defined source file name. 10624 10625 * The source line number as an unsigned LEB128 number. 10626 10627 * 4 bytes containing the characters `M', `T', `R' and `C'. 10628 10629 10630File: mpatrol.info, Node: Supported systems, Next: Porting, Prev: File formats, Up: Top 10631 10632Supported systems 10633***************** 10634 10635 Following is a list of systems on which the mpatrol library has been 10636built and tested. The system details include the operating system and 10637version, the processor type, the object file format and the compiler 10638used to compile the library and tests. The details following each 10639system list any features of the library that are not (or cannot be) 10640supported on that system. 10641 10642 * AIX 4.1, IBM RS/6000, XCOFF, `cc' 10643 * The thread-safe version of the library does not work. 10644 10645 * The `OFLOWWATCH' option has no effect. 10646 10647 * The `USEDEBUG' option has no effect. 10648 10649 * There is a problem obtaining the program's executable 10650 filename when using the shared library version of mpatrol. 10651 10652 * The shared library version of mpatrol does not currently 10653 override the dynamic memory allocation functions that are 10654 called from other shared libraries and so will only affect 10655 object files that are statically linked. If this is a problem 10656 then should link your programs with the following additional 10657 compiler options in order to perform a static link instead of 10658 a dynamic link: `-bnoautoimp' `-bimport:/lib/syscalls.exp' 10659 and also `-bimport:/lib/threads.exp' if linking with 10660 `libmpatrolmt.a'. 10661 10662 * A makefile called `Makefile.aix' is supplied in `build/unix' 10663 which will build the mpatrol library as an AIX shared 10664 library. The shared library will be embedded within the 10665 mpatrol archive library as is done with the system libraries. 10666 10667 * The `__mp_init_' initialisation function feature does not 10668 work since function entry points need to be referenced 10669 through the TOC. 10670 10671 * The `--dynamic' option to the `mpatrol' command has no effect. 10672 10673 * DG/UX 4.11, Intel Pentium Pro, ELF32, `gcc' 10674 * The `OFLOWWATCH' option has no effect. 10675 10676 * The `USEDEBUG' option has no effect. 10677 10678 * The `--dynamic' option to the `mpatrol' command has no effect. 10679 10680 * DG/UX 4.20MU07, Intel Pentium Pro, ELF32, `gcc' 10681 * The `OFLOWWATCH' option has no effect. 10682 10683 * The `USEDEBUG' option has no effect. 10684 10685 * The `--dynamic' option to the `mpatrol' command does not work 10686 unless `libelf.so' is available. 10687 10688 * DG/UX 4.11, Motorola 88100, ELF32, `gcc' 10689 * The thread-safe version of the library does not work if the 10690 mpatrol library is built as a shared library. 10691 10692 * The `OFLOWWATCH' option has no effect. 10693 10694 * The `USEDEBUG' option has no effect. 10695 10696 * Call stack traversal only works with unoptimised code. 10697 10698 * The `--dynamic' option to the `mpatrol' command has no effect. 10699 10700 * DRS/NX 6.2, SPARC V7, ELF32, `cc' 10701 * The option `-DSYSTEM=SYSTEM_DRSNX' must be added to the 10702 `CFLAGS' section in the `Makefile' before building the 10703 library. 10704 10705 * The thread-safe version of the library does not work. This 10706 is because there does not appear to be any evidence that this 10707 version of the operating system supports threads. 10708 10709 * The `OFLOWWATCH' option has no effect. 10710 10711 * The `USEDEBUG' option has no effect. 10712 10713 * The `--dynamic' option to the `mpatrol' command has no effect. 10714 10715 * DYNIX/ptx 4.5, Intel Pentium Pro, ELF32, `cc' 10716 * The `OFLOWWATCH' option has no effect. 10717 10718 * The `USEDEBUG' option has no effect. 10719 10720 * The `--dynamic' option to the `mpatrol' command does not work 10721 unless `libelf.so' is available. 10722 10723 * FreeBSD 4.2, Intel Celeron, ELF32, `gcc' 10724 * The `OFLOWWATCH' option has no effect. 10725 10726 * The `USEDEBUG' option has no effect. 10727 10728 * On ELF-based systems, the mpatrol library requires either the 10729 ELF access library or the GNU BFD library to be installed on 10730 the system, otherwise no symbols can be read from executable 10731 files or shared libraries and the library must be built with 10732 the `-DFORMAT=FORMAT_NONE' option. No such extra libraries 10733 are required on `a.out'-based systems. 10734 10735 * The `--dynamic' option to the `mpatrol' command does not 10736 appear to work correctly, giving spurious errors in the log 10737 file. 10738 10739 * HP/UX 10.20, HP PA/RISC 9000, BFD, `gcc' 10740 * The thread-safe version of the library does not work. This 10741 is because there does not appear to be any evidence that this 10742 version of the operating system supports threads. 10743 10744 * The `OFLOWWATCH' option has no effect. 10745 10746 * The `--dynamic' option to the `mpatrol' command has no effect. 10747 10748 * IRIX 5.3, MIPS R4000, ELF32, `cc' 10749 * The thread-safe version of the library does not work. This 10750 is because there does not appear to be any evidence that this 10751 version of the operating system supports threads. 10752 10753 * This version of the operating system only allows up to 100 10754 user-programmable software watch points, which means that the 10755 `OFLOWWATCH' option will not work properly if more than 50 10756 memory allocations exist at one time. 10757 10758 * The `USEDEBUG' option has no effect. 10759 10760 * Stack traversal may be unreliable from signal-handlers. 10761 10762 * Red Hat Linux 6.0, Intel Pentium III, BFD, `g++' 10763 * The `OFLOWWATCH' option has no effect. 10764 10765 * The `CHECKFORK' option does not work properly in 10766 multithreaded programs due to each thread having different 10767 process identifiers. 10768 10769 * The `--dynamic' option to the `mpatrol' command does not work 10770 unless `libiberty.so' is available. 10771 10772 * Red Hat Linux 6.1, Intel Pentium III, BFD, `g++' 10773 * The thread-safe version of the library does not work due to 10774 the system threads library calling `malloc()' and `bzero()' 10775 recursively. 10776 10777 * The `OFLOWWATCH' option has no effect. 10778 10779 * The `CHECKFORK' option does not work properly in 10780 multithreaded programs due to each thread having different 10781 process identifiers. 10782 10783 * The `--dynamic' option to the `mpatrol' command does not work 10784 unless `libiberty.so' is available. 10785 10786 * Red Hat Linux 6.2, Intel Pentium III, BFD, `g++' 10787 * The `OFLOWWATCH' option has no effect. 10788 10789 * The `CHECKFORK' option does not work properly in 10790 multithreaded programs due to each thread having different 10791 process identifiers. 10792 10793 * The `--dynamic' option to the `mpatrol' command does not work 10794 unless `libiberty.so' is available. 10795 10796 * Red Hat Linux 7.x, Intel Pentium III, BFD, `g++' 10797 * The `OFLOWWATCH' option has no effect. 10798 10799 * The `CHECKFORK' option does not work properly in 10800 multithreaded programs due to each thread having different 10801 process identifiers. 10802 10803 * The `--dynamic' option to the `mpatrol' command does not work 10804 unless `libiberty.so' is available. 10805 10806 * Red Hat Linux 5.1, Motorola 68040, BFD, `gcc' 10807 * The thread-safe version of the library does not work due to 10808 the system threads library calling `malloc()' and `bzero()' 10809 recursively. 10810 10811 * The `OFLOWWATCH' option has no effect. 10812 10813 * The `CHECKFORK' option does not work properly in 10814 multithreaded programs due to each thread having different 10815 process identifiers. 10816 10817 * The `--dynamic' option to the `mpatrol' command does not work 10818 unless `libiberty.so' is available. 10819 10820 * Red Hat Linux 5.1, Motorola 68040, ELF32, `gcc' 10821 * The thread-safe version of the library does not work due to 10822 the system threads library calling `malloc()' and `bzero()' 10823 recursively. 10824 10825 * The `OFLOWWATCH' option has no effect. 10826 10827 * The `CHECKFORK' option does not work properly in 10828 multithreaded programs due to each thread having different 10829 process identifiers. 10830 10831 * The `USEDEBUG' option has no effect. 10832 10833 * The `--dynamic' option to the `mpatrol' command does not work 10834 unless `libelf.so' is available. 10835 10836 * SuSE Linux 7.1, Intel Pentium II, BFD, `g++' 10837 * The `OFLOWWATCH' option has no effect. 10838 10839 * The `CHECKFORK' option does not work properly in 10840 multithreaded programs due to each thread having different 10841 process identifiers. 10842 10843 * The `--dynamic' option to the `mpatrol' command does not work 10844 unless `libiberty.so' is available. 10845 10846 * LynxOS 3.0.0, Intel Pentium Pro, BFD, `gcc' 10847 * The `OFLOWWATCH' option has no effect. 10848 10849 * The `USEMMAP' option has no effect. 10850 10851 * There is currently no support for reading symbols from COFF 10852 shared libraries. You should currently always perform a 10853 static link instead of a dynamic link when linking your 10854 program, but that is the default on LynxOS anyway. 10855 10856 * The `--dynamic' option to the `mpatrol' command has no effect. 10857 10858 * LynxOS 3.0.0, Intel Pentium Pro, COFF, `gcc' 10859 * The `OFLOWWATCH' option has no effect. 10860 10861 * The `USEDEBUG' option has no effect. 10862 10863 * The `USEMMAP' option has no effect. 10864 10865 * There is currently no support for reading symbols from COFF 10866 shared libraries. You should currently always perform a 10867 static link instead of a dynamic link when linking your 10868 program, but that is the default on LynxOS anyway. 10869 10870 * The `--dynamic' option to the `mpatrol' command has no effect. 10871 10872 * LynxOS 3.0.0, PowerPC, BFD, `gcc' 10873 * The `OFLOWWATCH' option has no effect. 10874 10875 * The `USEMMAP' option has no effect. 10876 10877 * There is currently no support for reading symbols from XCOFF 10878 shared libraries. You should currently always perform a 10879 static link instead of a dynamic link when linking your 10880 program, but that is the default on LynxOS anyway. 10881 10882 * The `__mp_init_' initialisation function feature does not 10883 work since function entry points need to be referenced 10884 through the TOC. 10885 10886 * The `--dynamic' option to the `mpatrol' command has no effect. 10887 10888 * LynxOS 3.0.0, PowerPC, XCOFF, `gcc' 10889 * The `OFLOWWATCH' option has no effect. 10890 10891 * The `USEDEBUG' option has no effect. 10892 10893 * The `USEMMAP' option has no effect. 10894 10895 * There is currently no support for reading symbols from XCOFF 10896 shared libraries. You should currently always perform a 10897 static link instead of a dynamic link when linking your 10898 program, but that is the default on LynxOS anyway. 10899 10900 * The `__mp_init_' initialisation function feature does not 10901 work since function entry points need to be referenced 10902 through the TOC. 10903 10904 * The `--dynamic' option to the `mpatrol' command has no effect. 10905 10906 * SINIX 5.43, MIPS R4000, ELF32, `cc' 10907 * The thread-safe version of the library does not work. This 10908 is because there does not appear to be any evidence that this 10909 version of the operating system supports threads. 10910 10911 * The `OFLOWWATCH' option has no effect. 10912 10913 * The `USEDEBUG' option has no effect. 10914 10915 * Stack traversal may be unreliable from signal-handlers. 10916 10917 * The `--dynamic' option to the `mpatrol' command has no effect. 10918 10919 * Solaris 2.6, Intel Pentium Pro, BFD, `gcc' 10920 * No known issues. 10921 10922 * Solaris 2.6, Intel Pentium Pro, ELF32, `gcc' 10923 * The `USEDEBUG' option has no effect. 10924 10925 * Solaris 2.5, SPARC V8, BFD, `gcc' 10926 * The thread-safe version of the library does not work due to a 10927 problem with a system library. 10928 10929 * The `OFLOWWATCH' option has no effect. The 10930 `-DMP_PROCFS_SUPPORT=0' and `-DMP_WATCH_SUPPORT=0' options 10931 must be added to `CFLAGS' in the `Makefile'. 10932 10933 * Solaris 2.5, SPARC V8, ELF32, `gcc' 10934 * The thread-safe version of the library does not work due to a 10935 problem with a system library. 10936 10937 * The `OFLOWWATCH' option has no effect. The 10938 `-DMP_PROCFS_SUPPORT=0' and `-DMP_WATCH_SUPPORT=0' options 10939 must be added to `CFLAGS' in the `Makefile'. 10940 10941 * The `USEDEBUG' option has no effect. 10942 10943 * Solaris 7, SPARC V9, BFD, `g++' 10944 * The mpatrol library can be compiled and run in a 64-bit 10945 environment. 10946 10947 * Solaris 7, SPARC V9, ELF32/ELF64, `g++' 10948 * The `USEDEBUG' option has no effect. 10949 10950 * The mpatrol library can be compiled and run in a 64-bit 10951 environment. 10952 10953 * Solaris 8, SPARC V9, BFD, `g++' 10954 * The mpatrol library can be compiled and run in a 64-bit 10955 environment. 10956 10957 * Solaris 8, SPARC V9, ELF32/ELF64, `g++' 10958 * The `USEDEBUG' option has no effect. 10959 10960 * The mpatrol library can be compiled and run in a 64-bit 10961 environment. 10962 10963 * Tru64 5.0, Alpha, BFD, `cxx' 10964 * The thread-safe version of the library has not yet been 10965 tested. 10966 10967 * The `OFLOWWATCH' option has no effect. 10968 10969 * The system exception-handling library (libexc) is used for 10970 call stack traversal. Unfortunately, this library makes 10971 several calls to `malloc()' when initialising itself and this 10972 can sometimes result in a recursive loop when used in 10973 combination with the mpatrol library. If this occurs, either 10974 `MP_BUILTINSTACK_SUPPORT=1' must be defined or the mpatrol 10975 library must be built without the `malloc.o' module. 10976 10977 * The mpatrol library can be compiled and run in a 64-bit 10978 environment. 10979 10980 * UnixWare 7.1.1, Intel Pentium II, ELF32, `gcc' 10981 * The option `-DSYSTEM=SYSTEM_UNIXWARE' must be added to the 10982 `CFLAGS' section in the `Makefile' before building the 10983 library. 10984 10985 * The thread-safe version of the library does not work. 10986 10987 * The `OFLOWWATCH' option has no effect. 10988 10989 * The `USEDEBUG' option has no effect. 10990 10991 * The `--dynamic' option to the `mpatrol' command has no effect. 10992 10993 * AmigaOS 3.1, Motorola 68040, BFD, `gcc' 10994 * No memory protection so the `PAGEALLOC' option has no effect. 10995 10996 * The `OFLOWWATCH' option has no effect. 10997 10998 * The `USEDEBUG' option has no effect. 10999 11000 * The `USEMMAP' option has no effect. 11001 11002 * The `EDIT' and `LIST' options have no effect. 11003 11004 * Limited support for call stack traversal. 11005 11006 * Limited support for reading symbols. 11007 11008 * No detection of illegal memory accesses. 11009 11010 * The `__mp_init_' initialisation function feature does not 11011 work. 11012 11013 * The `--dynamic' option to the `mpatrol' command has no effect. 11014 11015 * The `mptrace' command has no GUI. 11016 11017 * The `mpsym' and `hexwords' commands do not work unless `gdb' 11018 and the GNU text processing tools are installed. 11019 11020 * The `mpedit' command does not work. 11021 11022 * AmigaOS 3.1, Motorola 68040, n/a, SAS/C 11023 * No automatic override of `malloc()', etc., without inclusion 11024 of `mpatrol.h'. 11025 11026 * No memory protection so the `PAGEALLOC' option has no effect. 11027 11028 * The `OFLOWWATCH' option has no effect. 11029 11030 * The `USEDEBUG' option has no effect. 11031 11032 * The `USEMMAP' option has no effect. 11033 11034 * The `EDIT' and `LIST' options have no effect. 11035 11036 * No support for call stack traversal. 11037 11038 * No support for reading symbols. 11039 11040 * No detection of illegal memory accesses. 11041 11042 * The C++ compiler may come with an older version of the 11043 standard C++ library which does not place `set_new_hander()' 11044 in the `std' namespace. The `mpatrol.h' header file and the 11045 `cplus.c' source file will need to be changed accordingly. 11046 11047 * The `__mp_init_' initialisation function feature does not 11048 work. 11049 11050 * The `--dynamic' option to the `mpatrol' command has no effect. 11051 11052 * The `mptrace' command has no GUI. 11053 11054 * The `mpsym', `mpedit' and `hexwords' commands do not work. 11055 11056 * Microsoft Windows NT 4.0, Intel Pentium III, PE, Microsoft Visual 11057 C++ 11058 * The `OFLOWWATCH' option has no effect. 11059 11060 * The `USEMMAP' option has no effect. 11061 11062 * The `EDIT' and `LIST' options have no effect. 11063 11064 * The C++ compiler may come with an older version of the 11065 standard C++ library which does not place `set_new_hander()' 11066 in the `std' namespace. The `mpatrol.h' header file and the 11067 `cplus.c' source file will need to be changed accordingly. 11068 11069 * There is currently a problem when mixing the archive library 11070 version of mpatrol with the DLL version of the Microsoft 11071 Runtime Library, and vice versa. 11072 11073 * The `__mp_init_' initialisation function feature does not 11074 work. 11075 11076 * The `--dynamic' option to the `mpatrol' command has no effect. 11077 11078 * The `mptrace' command has no GUI. 11079 11080 * The `mpsym', `mpedit' and `hexwords' commands do not work. 11081 11082 11083File: mpatrol.info, Node: Porting, Next: Notes, Prev: Supported systems, Up: Top 11084 11085Porting 11086******* 11087 11088 This section describes how to port the mpatrol library to new 11089systems. It is not a complete set of guidelines as nothing can cover 11090every eventuality, but it should list most of the important issues and 11091where to make the necessary changes. Once you've made the changes (and 11092are happy with them) then send them to me and I can incorporate them 11093into the next mpatrol release. I'd also like to hear from anybody who 11094has got mpatrol working on a different version of an operating system 11095listed in the supported systems section (*note Supported systems::) 11096even if no changes were required, since that information can be useful 11097for new users wondering if mpatrol can be used on their system. 11098 11099 1. Make any required changes in `src/target.h' in order to identify 11100 the new system. 11101 11102 The `TARGET' macro is used to identify distinct families of 11103 operating systems whereas the `SYSTEM' macro is used to identify 11104 the operating system variant if `TARGET=TARGET_UNIX'. You should 11105 try to identify the predefined preprocessor macros that the system 11106 C compiler defines for the operating system type and the operating 11107 system variant, otherwise you will have to specify the `TARGET' 11108 and `SYSTEM' macros explicitly in the `Makefile' when building the 11109 mpatrol library. Note that for non-UNIX operating systems, 11110 `SYSTEM=SYSTEM_ANY' is implied. 11111 11112 The `ARCH' macro is used to identify the processor architecture 11113 and the `ENVIRON' macro is used to identify the processor word 11114 size. Again, you should try to identify the predefined 11115 preprocessor macros that the system C compiler defines for the 11116 processor architecture and processor word size, otherwise you may 11117 also have to specify the `ARCH' and `ENVIRON' macros explicitly in 11118 the `Makefile' when building the mpatrol library. The default 11119 setting for the processor word size is `ENVIRON=ENVIRON_32'. 11120 11121 You can normally figure out the preprocessor macros that are 11122 predefined by the system C compiler by using the `-#', `-v' or 11123 `-verbose' options when compiling a source file. The command line 11124 used to invoke the preprocessor should then be shown, which should 11125 show a list of all of the macros that are being defined in 11126 addition to those specified on the compiler command line. It 11127 should then be easy for you to spot the ones you need. 11128 11129 The `FORMAT' macro is used to identify the object file format and 11130 the `DYNLINK' macro is used to identify the dynamic linker type. 11131 You may be able to use the existing values for these without 11132 having to define new ones, but in any case you should attempt to 11133 set defaults for these macros depending on the values of the four 11134 preceding macros. A setting of `FORMAT=FORMAT_NONE' indicates 11135 that reading symbols from any object files is not supported and a 11136 setting of `DYNLINK=DYNLINK_NONE' indicates that reading symbols 11137 from shared libraries is not supported. 11138 11139 If the object file format of the new system is not currently 11140 supported, perhaps it is supported by the GNU BFD library. This 11141 can be used as a catch-all solution to provide symbol reading 11142 support for the mpatrol library with object file formats that are 11143 obscure or are just hard to implement readers for. You'd be 11144 surprised at how many object file formats are supported by that 11145 library and if the new format is supported then try defining 11146 `FORMAT=FORMAT_BFD' for the new system. 11147 11148 In all six of the above target macros, care should be taken not to 11149 define a new macro that is effectively the same as an existing 11150 one, unless there are significant differences. For example, the 11151 dynamic linker used on BSD systems is slightly different from the 11152 dynamic linker used on SunOS, but they both use 11153 `DYNLINK=DYNLINK_BSD' because the underlying dynamic linker uses 11154 the same data structures -- they are just named differently on the 11155 two systems. 11156 11157 Note that there are also corresponding `*_STR' macros for all six 11158 of the above target macros. These are used when displaying the 11159 target environment information in the mpatrol log file so they 11160 should be as accurate as possible so as to avoid misleading users. 11161 11162 Finally, you should determine if it is necessary to define any 11163 special macros in order to obtain all of the required definitions 11164 from the system header files. Many compilers default to providing 11165 an ANSI C or C++ environment without any extensions, but as the 11166 mpatrol library uses additional features that are not provided by 11167 these standards, it may be necessary to define additional macros 11168 that allow the compiler to see the definitions of these features. 11169 For example, the `_POSIX_SOURCE' macro is defined here for all 11170 UNIX platforms so that mpatrol can make use of the POSIX 11171 extensions. Note that `src/target.h' is the only mpatrol library 11172 source file that refers to the predefined preprocessor macros 11173 defined by the system C compiler on a particular system (apart 11174 from a few necessary exceptions) and the rest of the source code 11175 refers to the six aforementioned macros for conditional 11176 compilation. 11177 11178 2. Make any required changes in `src/memory.c' in order to support 11179 the new system. 11180 11181 The mpatrol library, like the system malloc library it is 11182 replacing, must have some way of allocating memory from the system 11183 heap for a process. For UNIX systems, this is done by calling 11184 `sbrk()' and/or `mmap()' but this is likely to be completely 11185 different for other operating systems. The mpatrol library must 11186 also have some way of returning the allocated heap memory back to 11187 the operating system, although on systems with virtual memory this 11188 is not really an issue (see `MP_DELETEHEAP' in `src/config.h'). 11189 If there is currently no support in the mpatrol library for 11190 allocating and returning system heap memory for the new system 11191 then you must modify `__mp_memalloc()' and `__mp_memfree()' to add 11192 the support. You should define `MP_MMAP_SUPPORT' in 11193 `src/config.h' if the operating system is UNIX and the system 11194 variant supports the `mmap()' system call. 11195 11196 Note that some (mainly embedded) systems may have no system heap 11197 available for a program to use. If that is the case then the 11198 mpatrol library can be built to allocate memory from a static 11199 array whose size is fixed at compile-time. The `MP_ARRAY_SUPPORT' 11200 macro should be defined in `src/config.h' and the `MP_ARRAY_SIZE' 11201 macro should be set to the maximum number of bytes that the 11202 simulated heap should be able to hold. Keep in mind that all of 11203 the internal mpatrol library data structures will also be 11204 allocated from this array so it is important to make it large 11205 enough. 11206 11207 Operating systems with virtual memory allow mpatrol to protect 11208 certain regions of heap memory to ensure that they are not 11209 overwritten. The `MP_PROTECT_SUPPORT' macro in `src/config.h' 11210 controls whether the operating system supports this, and the 11211 `__mp_memprotect()' and `__mp_memquery()' functions should be 11212 updated to support the new system. You should also define 11213 `MP_MINCORE_SUPPORT' in `src/config.h' if the operating system is 11214 UNIX and the system variant supports the `mincore()' system call. 11215 The `MP_WATCH_SUPPORT' macro controls the support of software 11216 watchpoints in a similar way and the `__mp_memwatch()' function 11217 should be updated if they are supported. 11218 11219 If the new system is a UNIX system and it supports the `/proc' 11220 filesystem then you may wish to define `MP_PROCFS_SUPPORT' in 11221 `src/config.h'. However, this is only necessary if there is a way 11222 to detect the filename the current process was invoked with 11223 (`MP_PROCFS_CMDNAME') or a way to obtain the filehandle of the 11224 executable file for the current process (`MP_PROCFS_EXENAME'). It 11225 may also be necessary if `MP_WATCH_SUPPORT' is defined and the 11226 only way to set the watchpoints is via a file in the `/proc' 11227 filesystem (`MP_PROCFS_CTLNAME'). 11228 11229 Finally, you should add support for determining the system page 11230 size in `pagesize()' and the process identifier for the current 11231 process in `__mp_processid()' if the system is not already 11232 supported(1). You will also have to add a way to determine the 11233 filename that the current process was invoked with in 11234 `progname()', otherwise the `PROGFILE' option will always have to 11235 be used in order to read symbols from the executable file. This 11236 can be done in a multitude of ways, including examining global 11237 variables, making function calls to query the system or traversing 11238 the call stack. 11239 11240 3. Make any required changes in `src/stack.c' in order to support 11241 stack traversal in the new processor architecture. 11242 11243 If the new processor architecture is CISC (complex instruction set 11244 computer) then the chances are that you can easily find the frame 11245 pointer and return address of the current stack frame by simply 11246 looking at a constant offset from the parameter to the 11247 `__mp_getframe()' function. The call chain can then be obtained 11248 by following the frame pointer at each stage. This can sometimes 11249 be disrupted by optimisations that do not preserve the frame 11250 pointer but this is usually confined to leaf routines and is not 11251 normally an issue. The Intel x86 and Motorola 680x0 processor 11252 families are good examples to look at when implementing stack 11253 traversal for a CISC processor. 11254 11255 On the other hand, things might not be so easy if the new 11256 processor architecture is RISC (reduced instruction set computer). 11257 Such processors do not always have fixed format stack frames(2) 11258 and so other means might have to be used. The Alpha and MIPS 11259 processor families are examples of these and code reading normally 11260 has to be used in order to find the call instruction from the 11261 calling routine. This then has to be done for every function in 11262 the call stack. An example of such code can be found for the 11263 generic MIPS implementation. Any assembler code that needs to be 11264 written to support the stack traversal implementation should be 11265 written in `src/machine.c'. 11266 11267 If the GNU compiler is being used then it might be possible to use 11268 its `__builtin_frame_address()' and `__builtin_return_address()' 11269 builtin functions in order to provide stack traversal. These can 11270 only be used if they return `NULL' when the bottom of the call 11271 stack is reached, but on many architectures the GNU compiler does 11272 not implement this correctly and so this method of stack traversal 11273 cannot be used. Even if it can, it still imposes an upper limit 11274 on the size of the stack that can be traversed. If this is not an 11275 issue then it can be enabled with the `MP_BUILTINSTACK_SUPPORT' 11276 macro in `src/config.h' and the maximum size of the call stack 11277 that can be traversed can be set by changing the `MP_MAXSTACK' 11278 macro in the same file. The `MP_FULLSTACK' macro in 11279 `src/config.h' should be set for stack traversal implementations 11280 that have no limit to the maximum size of the call stack that can 11281 be traversed. Obviously that is not the case for 11282 `MP_BUILTINSTACK_SUPPORT'. 11283 11284 Some operating systems have library functions that provide stack 11285 traversal facilities and so you may wish to make use of them by 11286 defining `MP_LIBRARYSTACK_SUPPORT' in `src/config.h' and 11287 implementing the code to call them in `src/stack.c'. Examples of 11288 systems that can make use of this capability are IRIX and Tru64, 11289 although they have a drawback in that they recursively call 11290 `malloc()' and so work slower than they normally would. 11291 11292 If any functions from an external system library were used to help 11293 implement stack traversal for the new processor architecture then 11294 you may also have to modify the `MP_SYSTEM_LIBS' definitions in 11295 `src/config.h', the `__mp_lib*' definitions in `src/inter.c' and 11296 the `AC_CHECK_LIB()' calls in `extra/mpatrol.m4'. 11297 11298 4. Make any required changes in `src/symbol.c' in order to support 11299 any new object file formats and dynamic linkers. 11300 11301 The best place to find information on the object file format and 11302 dynamic linker interface supported by a new system is the on-line 11303 manual pages and header files on that system. If that fails then 11304 try the hardcopy technical reference manuals that came with the 11305 system or the internet in order to find the information you need. 11306 There may also be standards that define the object file format and 11307 dynamic linker interface across several systems. 11308 11309 If you defined a new `FORMAT' macro in `src/target.h' then you must 11310 add the code to support it in `src/symbol.c'. You will typically 11311 have to add new `addsymbol()' and `addsymbols()' functions that 11312 are specific to the new object file format and then add support 11313 for that format in `__mp_addsymbols()' and `__mp_findsymbol()'. 11314 If it is possible to easily read a line number table from the 11315 object file format then you may also want to extend the 11316 `__mp_findsource()' function to handle the new format as well in 11317 order to support the `USEDEBUG' option. 11318 11319 If you defined a new `DYNLINK' macro in `src/target.h' then you 11320 must also add the code to support it in `src/symbol.c'. You will 11321 normally only have to extend the `__mp_addextsymbols()' function 11322 to support the new dynamic linker but there may be some extra work 11323 required to translate the base addresses of any symbols read from 11324 shared libraries into real addresses. 11325 11326 In both cases, try to base the new code on the structure of the 11327 existing code since it has been proven to work well and there is 11328 no point in reinventing the wheel(3). You might decide to make 11329 changes to an existing implementation instead; this was done with 11330 the COFF and XCOFF formats, for example. 11331 11332 If any functions from an external object file access library were 11333 used to help read symbols from the new object file format then you 11334 may also have to modify the `MP_SYMBOL_LIBS' definitions in 11335 `src/config.h', the `__mp_lib*' definitions in `src/inter.c' and 11336 the `AC_CHECK_LIB()' calls in `extra/mpatrol.m4'. 11337 11338 5. Make any required changes in `src/signals.c' in order to obtain 11339 the address of an illegal memory access in the new system. 11340 11341 If the system supports the `SA_SIGINFO' flag when setting up a 11342 signal handler with `sigaction()' then it supports 11343 architecture-independent determination of the address of an 11344 illegal memory access and the `MP_SIGINFO_SUPPORT' macro should be 11345 set in `src/config.h'. 11346 11347 If this is not the case then an architecture-dependent method must 11348 be employed in order to obtain this information. On UNIX systems, 11349 signal handlers can have additional arguments that may be used to 11350 probe for the address of a segmentation violation or bus error. 11351 On Windows systems, an exception record can be obtained whenever 11352 an access violation occurs. In either case, the saved register 11353 containing the relevant address must be determined. If this is 11354 not done then the mpatrol library will compile correctly, but the 11355 addresses of illegal memory accesses can never be determined. 11356 11357 6. Make any required changes in `src/mutex.c' in order to support 11358 threads in the new system. 11359 11360 The mpatrol library must be able to lock its data structures in a 11361 multithreaded environment otherwise two threads may allocate 11362 memory at the same time and the heap would become corrupted, for 11363 example. On operating systems that have virtual memory, processes 11364 have their own address space and can have more than one thread of 11365 execution running at one time. On other operating systems, there 11366 is only one process (the operating system) and the threads are the 11367 user processes that all share the same address space. For that 11368 reason, you may wish to use semaphores on such systems since they 11369 have no support for threads in a conventional sense. 11370 11371 For systems that do support threads, mutexes should be used to 11372 lock the mpatrol library data structures. On UNIX platforms, 11373 POSIX threads are used but this could easily be extended to other 11374 threads implementations. On Windows platforms, Win32 API threads 11375 are used. For other systems, POSIX threads are preferred but it 11376 should not be too hard to add support for others. There should 11377 also be a way to return the current thread identifier. 11378 11379 You should also determine if it is necessary to define any special 11380 macros in order to obtain all of the required threadsafe 11381 definitions from the system header files. Many compilers require 11382 an option to be specified on the command line in order to compile 11383 threadsafe code, but some still only require a preprocessor macro 11384 to be defined during compilation. For example, the `_REENTRANT' 11385 macro is defined for Solaris systems so that mpatrol can make use 11386 of the threadsafe definitions. Any such macros should be defined 11387 in `src/config.h' when `MP_THREADS_SUPPORT' is defined. 11388 11389 The multithreaded version of the mpatrol library must be 11390 initialised before a process becomes multithreaded and so there 11391 must be a way to do this on a new system. 11392 11393 The `MP_INIT_SUPPORT' macro should be defined in `src/config.h' if 11394 the new system supports `.init' and `.fini' sections that get 11395 executed before and after `main()' respectively. Both the 11396 contents of the `.init' section (which should call 11397 `__mp_initmutexes()' and `__mp_init()') and the `.fini' section 11398 (which should call `__mp_fini()') should be written in 11399 `src/machine.c' in assembler code. 11400 11401 There are also other methods to initialise and terminate the 11402 mpatrol library in `src/inter.c' so you may need to use one of 11403 them (or add a new method of your own) for the new system. Note 11404 that if `MP_USE_ATEXIT' is defined in `src/config.h' then these 11405 methods of terminating the mpatrol library when a process ends are 11406 replaced by registering the `__mp_fini()' function with `atexit()'. 11407 11408 There may be problems if the mpatrol library is built to override 11409 `malloc()' and related functions if the system C library calls 11410 them before the mpatrol library can be initialised. There is a 11411 function in `src/inter.c' on UNIX and Windows platforms called 11412 `crt_initialised()' which checks to see if it is safe to 11413 initialise the mpatrol library, and if not the relevant functions 11414 will use `sbrk()' to allocate the memory. You may have to modify 11415 `crt_initialised()' to support the new system if there are 11416 initialisation problems. 11417 11418 If there are no special methods to initialise the multithreaded 11419 version of the mpatrol library on a new system then it will simply 11420 be initialised at the first call to one of its functions, 11421 hopefully before the process has become multithreaded. 11422 11423 If there is support for reading symbols from object files on the 11424 new system then you should compile and run the following test with 11425 the mpatrol library to check to see if there is support for 11426 calling functions by their start address. This is not always true 11427 on certain systems and will most likely result in the test 11428 crashing if that is the case. If the test works then the 11429 `MP_INITFUNC_SUPPORT' macro should be set in `src/config.h'. 11430 11431 #include <stdio.h> 11432 #include "mpatrol.h" 11433 11434 11435 void __mp_init_test(void) 11436 { 11437 puts("__mp_init_* functions work"); 11438 } 11439 11440 11441 void __mp_fini_test(void) 11442 { 11443 puts("__mp_fini_* functions work"); 11444 } 11445 11446 11447 int main(void) 11448 { 11449 malloc(1); 11450 puts("there should be a line of output above and below"); 11451 return EXIT_SUCCESS; 11452 } 11453 11454 If any functions from an external threads library were used to 11455 lock the data structures of the multithreaded version of the 11456 mpatrol library then you may also have to modify the 11457 `MP_THREADS_LIBS' definitions in `src/config.h', the `__mp_lib*' 11458 definitions in `src/inter.c' and the `AC_CHECK_LIB()' calls in 11459 `extra/mpatrol.m4'. 11460 11461 7. Make any required changes to `src/diag.c' in order to support the 11462 new system. 11463 11464 If the directory separation characters used by filesystem 11465 pathnames on the new system are different to those already 11466 supported then you must modify `processfile()', `__mp_logfile()', 11467 `__mp_proffile()' and `__mp_tracefile()' in order to support them. 11468 The mpatrol library needs to know how to extract and join the 11469 directory and filename components in a pathname in order to 11470 support the special characters that may appear in the filenames 11471 specified in the `LOGFILE', `PROFFILE' and `TRACEFILE' options. 11472 11473 8. Make any required changes to `src/version.c' in order to support 11474 the new system. 11475 11476 Different operating systems have different ways of embedding 11477 version information into libraries. For example, on AmigaOS the 11478 `version' command looks for the `$VER:' string in a binary file 11479 and displays any information following it. If the new system uses 11480 a special format for embedding version information then an 11481 alternative definition for `__mp_version' should be added to 11482 `src/version.c'. It might also be useful to make any necessary 11483 changes to the `mupdate' shell script in the `bin' directory in 11484 order to support the new format, although that is not strictly 11485 required as it is only used when building automated mpatrol 11486 releases. 11487 11488 The RCS revision string of each mpatrol source file can also be 11489 embedded into the mpatrol library and its tools. The way this is 11490 done is controlled by the `MP_IDENT_SUPPORT' macro in 11491 `src/config.h'. If it is set then the system supports placing 11492 these strings in a special section in the object file via the 11493 `#ident' directive, otherwise the strings will be placed in a data 11494 section in the object file. 11495 11496 9. Make any required changes in `src/mpatrol.c' in order to support 11497 executing external commands. 11498 11499 The `mpatrol' command should be modified to support the execution 11500 of external commands on a new operating system. The `exec()' 11501 family of functions are used on UNIX platforms, while the 11502 `spawn()' family of functions are used on Windows platforms. The 11503 ANSI C `system()' function is currently used on all other 11504 platforms, but that runs the command indirectly via the system 11505 command line interpreter (shell) which is not usually very 11506 efficient. You may also have to add the ability to find any 11507 commands using a search path. 11508 11509 If the new operating system can support the `--dynamic' option of 11510 the `mpatrol' command then the `MP_PRELOAD_SUPPORT' macro should be 11511 defined in `src/config.h'. The name of the environment variable 11512 that must be used to specify the list of shared libraries to 11513 preload should be given in `MP_PRELOAD_NAME' and the library 11514 separator string for the list should be given in `MP_PRELOAD_SEP'. 11515 The `MP_LIBNAME' macro may also need to be modified if the naming 11516 convention of shared libraries is different on the new system. 11517 Note that the `__mp_editfile()' function in `src/diag.c' may also 11518 need to be modified to prevent editor processes from being 11519 affected by the `--dynamic' option. 11520 11521 10. Make any required changes in `src/mptrace.c' in order to support 11522 any new window systems. 11523 11524 The `mptrace' command may be built as a text-only command line 11525 tool, or it may be built with GUI support if the `MP_GUI_SUPPORT' 11526 macro is defined in `src/config.h'. If it is built with GUI 11527 support and the `--gui' option is specified then it becomes an 11528 event-driven tool and the code in `src/mptrace.c' has been written 11529 to reflect that. The `mptrace' command currently only has Motif 11530 GUI support but if you wish to add support for a new window system 11531 then it shouldn't be too hard to do. Note that you will probably 11532 have to add additional libraries to the `Makefile' when building 11533 `mptrace' with `MP_GUI_SUPPORT' defined. 11534 11535 11. Make any required changes to the shell scripts in the `bin' 11536 directory. 11537 11538 The `mpsym', `mpedit' and `hexwords' commands all require UNIX 11539 systems, or UNIX tools, to run. If the new system has the ability 11540 to run these commands then you should check that they run as 11541 expected. If not, you should make the necessary modifications to 11542 make them work, although it should be in a generic fashion as 11543 there are no checks for specific platforms or processors in these 11544 files. You may also wish to add support for other debuggers in 11545 `mpsym' and other editors in `mpedit'. 11546 11547 12. Add a new subdirectory to the `build' directory if a new operating 11548 system is being supported. 11549 11550 A new `Makefile' should be added in the new subdirectory along 11551 with any extra system-specific files that might be needed to build 11552 the mpatrol library on the new system. The new `Makefile' should 11553 be based upon one of the existing `Makefile's in the other 11554 subdirectories but should obviously differ in the 11555 platform-dependent areas. You may wish to add more than one 11556 `Makefile' to support different types of compilers on the new 11557 operating system. 11558 11559 You must also decide which object files should get built into the 11560 mpatrol library. If it is not safe to override the system 11561 `malloc()' routines on the new system then you should not include 11562 `src/malloc.c', and the same goes for `src/cplus.c' and the C++ 11563 operators. If there is no `sbrk()' function provided on the new 11564 operating system then you should include `src/sbrk.c' if you need 11565 to call `sbrk()' in `src/inter.c'. 11566 11567 If the new operating system uses a special archive or package 11568 format then you should add support for it by adding a new 11569 subdirectory to the `pkg' directory. A `build' script should be 11570 added to the new subdirectory that will automatically build the 11571 archive or package file from scratch. Include any additional 11572 files that you need to perform the build in the new subdirectory as 11573 well. 11574 11575 ---------- Footnotes ---------- 11576 11577 (1) You will also have to make any changes to `pagesize()' in 11578`src/mpalloc.c' and possibly also have to define `MP_MEMALIGN_SUPPORT' 11579in `src/config.h' if the new system supports the `memalign()' function. 11580 11581 (2) Although some do, and you can follow the instructions for CISC 11582processors above in order to provide stack traversal support for them. 11583 11584 (3) You might also be interested to note that you can safely call 11585`malloc()' in this code to allocate memory -- just remember to clean up 11586after yourself! 11587 11588 11589File: mpatrol.info, Node: Notes, Next: Frequently asked questions, Prev: Porting, Up: Top 11590 11591Notes 11592***** 11593 11594 This section contains information about known bugs and limitations 11595in the mpatrol library as well as listing potential future enhancements. 11596 11597 Bugs should be reported to <mpatrol@cbmamiga.demon.co.uk> along with 11598the details of the operating system, processor architecture and object 11599file format that the mpatrol library is being used with -- and don't 11600forget to include the version of the mpatrol library you are using! 11601Keep in mind that I only have access to a Pentium III Notebook PC 11602running Red Hat Linux 7.1 and Windows ME, so I will be most likely 11603unable to reproduce most of the system-specific bugs. A bug report 11604that comes with an associated fix will be most welcome. 11605 11606 Enhancement requests and source code containing enhancements should 11607also be sent to <mpatrol@cbmamiga.demon.co.uk> or the mpatrol 11608discussion group at `http://groups.yahoo.com/group/mpatrol/'. If you 11609are planning to implement an enhancement, let me know first in case I 11610am (or someone else is) working towards the same goal -- that way, work 11611won't be wasted. If you wish to send me source code changes please 11612send the changes as context diffs or in an e-mail attachment as a 11613compressed tar archive. 11614 11615* Menu: 11616 11617* Generic notes:: Notes for all platforms. 11618* UNIX notes:: Notes for UNIX platforms. 11619* Amiga notes:: Notes for Amiga platforms. 11620* Windows notes:: Notes for Windows platforms. 11621* Netware notes:: Notes for Netware platforms. 11622 11623 11624File: mpatrol.info, Node: Generic notes, Next: UNIX notes, Up: Notes 11625 11626Notes for all platforms 11627======================= 11628 11629 * Overriding the C++ operators to get source-level information using 11630 the preprocessor is still a bit dodgy and isn't likely to get much 11631 better, so `MP_NONEWDELETE' may have to be used a lot. Explicit 11632 references to `operator new' rather than `new' are likely to 11633 result in compilation errors, and the way that source level 11634 information is obtained for `operator delete' means that the 11635 resulting code will not be thread-safe. It might also be an idea 11636 to provide an allocation class from which user-defined memory 11637 allocators can be derived. 11638 11639 * Need to add support for other 64-bit processors in addition to the 11640 existing Alpha and SPARC V9 support. This shouldn't be too hard, 11641 but I haven't got access to such processors to test them, so I 11642 haven't been able to yet. Also need to add support for building 11643 on targets and architectures where no operating system features 11644 are required or even available. 11645 11646 * Need to improve the concurrency in the thread-safe version of the 11647 mpatrol library. Currently, only one thread at a time is allowed 11648 to enter the mpatrol library, but it should be possible to extend 11649 this to protect individual data structures. Note that this will 11650 not only help to improve efficiency, but might also allow the 11651 mpatrol library to uncover bugs in thread-safe code that are 11652 timing-dependent. 11653 11654 * Need to make the library re-entrant. This could be achieved by 11655 moving the static variables in `memory.c', `stack.c', `mutex.c', 11656 `diag.c', `trace.c', `option.c' and `sbrk.c' into the `infohead' 11657 structure and then having an array of `infohead' structures from 11658 which to allocate new memory headers when a new one is required. 11659 This is only necessary for Amiga shared libraries and Netware NLMs 11660 since UNIX and Windows platforms allocate a new copy of the data 11661 section in a shared library or DLL when it is opened by a new 11662 process. 11663 11664 * Some implementations of call stack traversal are limited and will 11665 only likely work for unoptimised code. A much better solution 11666 would be write the implementations at a lower level in assembly, 11667 but this is much less portable. Perhaps there is a library which 11668 can be used to perform this across many operating systems and 11669 processor architectures, or maybe someone would like to write 11670 one(1)? I can think of many applications that would benefit from 11671 such a library besides this one(2). 11672 11673 * An alternative implementation for call stack traversal uses the 11674 functions `__builtin_frame_address()' and 11675 `__builtin_return_address()' that are available when the library 11676 is compiled with `gcc'. However, they can only traverse a number 11677 of stack frames at compile-time, not run-time so there is a 11678 maximum number of stack frames that can be traversed at any one 11679 time. The implementation depends on both of these builtin 11680 functions returning `NULL' when the top of stack is reached. If 11681 this is not the case then this method cannot be used or should 11682 only be used with a small number of fixed stack frames. However, 11683 perhaps there might even be a use for an option to limit the 11684 number of stack frames in stack tracebacks for systems that have 11685 no such limitation. 11686 11687 * Is it worth adding functions to manually push and pop entries on 11688 the call stack for platforms which have no support for call stack 11689 traversal? This is currently not a high-priority issue since 11690 almost all of the platforms that mpatrol is available on have 11691 support for full call stack traversal. However, it might be handy 11692 anyway as an additional debugging tool for entering and leaving 11693 scopes. 11694 11695 * Need to change `__mp_compareaddrs()' so that it will improve the 11696 detection of when to free memory allocations made by `alloca()' 11697 and its related functions. This will involve checking the common 11698 return addresses in the call stacks instead of just checking them 11699 if the stack depth is the same. Also, on systems that don't have 11700 full call stack traversal, the minimum number of bytes that stack 11701 frames should differ by should be platform-dependent since the 11702 current value is way too high. 11703 11704 * Perhaps hash the call stacks when they are stored internally by 11705 the routines in `addr.c'. This would make for quick checks to see 11706 if two call stacks are identical and it might save some memory in 11707 the process. 11708 11709 * There is an issue with callback functions if they call mpatrol 11710 library functions, since this may lead to recursion in some 11711 obscure cases. Callback functions could also be defined for 11712 `__malloc_hook()', `__realloc_hook()' and `__free_hook()' in much 11713 the same way as for the GNU C library. 11714 11715 * Need to store filename and line number information in all call 11716 stacks so that the information can be used at program termination. 11717 May also need to display this information in the 11718 `__mp_printinfo()' function and add this information to the 11719 profiling output file so that `mprof' can make use of it. 11720 11721 * In object file formats that support nested symbols (such as ELF), 11722 the current implementation will tend to show some shortcomings. 11723 This is because there is currently no nesting count in the 11724 function that deals with symbol name lookup, so the wrong symbol 11725 name may be displayed in diagnostics. 11726 11727 * In object file formats that don't store the sizes of symbols (such 11728 as basic `a.out', or when using the GNU BFD library), the current 11729 implementation will simply assume that the current symbol 11730 terminates at the beginning of the next symbol in the virtual 11731 address space. 11732 11733 * Perhaps add an option to prevent symbols from being read from 11734 object files. This might be necessary if mpatrol is used in a 11735 program that loads shared libraries explicitly, or if there is too 11736 much memory being used by mpatrol to store the symbol details. 11737 11738 * Add functions to start and stop profiling, and perhaps also to 11739 clear the profiling tables and begin a new profiling output file. 11740 Should also write more information to the profiling output file, 11741 such as the date that it was produced on and the word size of the 11742 processor that it was produced on, so that `mprof' will not crash 11743 when reading a profiling output file produced on a processor that 11744 has a different word size. 11745 11746 * Perhaps add the ability to profile memory operations such as 11747 `memcpy()' and `memset()' to the existing memory allocation 11748 profiling facility. Also, add options to `mprof' to write out 11749 files that can be used by chart drawing software for a better 11750 visualisation of the first few profiling tables. 11751 11752 * Perhaps the allocation call graph table should have the capability 11753 to be sorted in `mprof' and the `--leaks' option should work with 11754 it as well. There should be better handling of cycles in the call 11755 graph and there is currently a problem in that `mprof' cannot 11756 distinguish between call sites with very low code addresses that 11757 have no symbols and that conflict with existing symbol indices. 11758 11759 * Extend the `mptrace' command to graphically display the size of 11760 the heap plotted against time and the allocation size frequency. 11761 Also rewrite the GUI support to use GNOME instead of Motif, 11762 possibly also using GLADE. 11763 11764 * Possibly add widgets to the `mptrace' window to pause and quit. 11765 Might also be handy to add the ability to write out charts 11766 summarising tracing information. 11767 11768 * Handle marked memory allocations in the leak table, and also 11769 perhaps write out to the mpatrol log file when an allocation is 11770 marked so that the `mleak' command will work correctly. 11771 11772 * Improve the speed of watch points by setting a range of allocation 11773 indices for which they will be used. This may require a lot of 11774 code changes in `alloc.c'. 11775 11776 * Add a software watch point facility that can be placed on ranges 11777 of addresses in the heap. Then, if a heap operation touches the 11778 watch point, either the user can be notified or a callback 11779 function can be called. The same could be done for local 11780 variables if the stack frame can be easily determined, which would 11781 also allow detecting if a read from or write to memory was 11782 performed just beyond the stack pointer. 11783 11784 * Add a CRC checksum to memory blocks and use it to check that freed 11785 memory allocations have not been corrupted when the `NOFREE' and 11786 `PRESERVE' options are in use on platforms which have no memory 11787 protection. 11788 11789 * Perhaps extend the `NOFREE' option to prevent the mpatrol library 11790 from reusing freed memory allocations unless it really needs to. 11791 This would mean that no freed allocations would be reused until 11792 there is no more free memory left and mpatrol would normally have 11793 to allocate more from the system. It could then convert as many 11794 freed allocations to free memory as it needs to fulfil the 11795 allocation request, although it would probably still have to abide 11796 by the minimum number of freed allocations set by the `NOFREE' 11797 option. 11798 11799 * Perhaps change the behaviour of the `NOFREE' option so that it 11800 doesn't prevent in-place reallocations if there is enough memory 11801 to perform them. Then an option could be added to force 11802 reallocations to always allocate new memory so that the behaviour 11803 could also be used when the `NOFREE' option is not used. 11804 11805 * Add an option to set up a timer that will automatically check the 11806 heap after a certain number of clock cycles have elapsed. This 11807 could be useful in programs that have long periods of time where 11808 no dynamic memory allocation functions are called, but heap 11809 allocations are still manipulated. In addition, checks could 11810 automatically be made upon receipt of special signals sent to the 11811 program by the user and information about the last successful 11812 verification of the heap could be used to narrow down problems. 11813 Perhaps even some statistics could be printed on receipt of a 11814 special signal as well. 11815 11816 * Add a diagnostic number count to each warning and error reported 11817 in the log file. This could then be used to implement a 11818 `DIAGSTOP' option which would stop the program running after a 11819 certain number of diagnostics have been displayed. 11820 11821 * Add the ability to stop in a debugger when a memory allocation is 11822 made from a particular file and line number, and perhaps also trap 11823 when a particular address is allocated as part of a memory 11824 allocation. 11825 11826 * Perhaps add time information to the details stored about each 11827 memory allocation. This is probably not useful unless the system 11828 provides a high-resolution timer. 11829 11830 * Add an option (perhaps `NOINTERNAL') to suppress the display of 11831 internal (recursive) memory allocations in the mpatrol log file 11832 and also prevent information about such allocations being written 11833 to the profiling output and tracing output files. Perhaps this 11834 could be made the default so that they behave in the same way as 11835 marked allocations, in which case we might want an option which 11836 prevents internal and marked allocations being hidden. This could 11837 also be extended to prevent memory leaks from being reported if 11838 the original allocations were made from a given set of functions. 11839 11840 * Add a function to add a block of memory to the heap, possibly a 11841 memory-mapped file. Also add a function that can shrink the heap 11842 if large areas of free memory exist. 11843 11844 * Maybe show the contents of the `MPATROL_OPTIONS' environment 11845 variable in the summary as well. 11846 11847 * Add versions of `mallopt()', `mallinfo()', `memorymap()', 11848 `mallocctl()', `mallocblksize()' and `msize()' which are provided 11849 in many other malloc libraries. These won't necessarily behave in 11850 exactly the same way as existing implementations, but at least 11851 there won't be link errors when compiling source code which uses 11852 them. Also, add support for setting as many remaining options in 11853 `__mp_setoption()' as possible and perhaps even some options 11854 before the mpatrol library has been initialised. 11855 11856 * Add similar functions to the GNU `mcheck()' and `mprobe()' 11857 functions. Perhaps also add an mpatrol tool to add compatibility 11858 with the GNU memusage tool. 11859 11860 * Perhaps add debugging/tracing versions of the string manipulation 11861 functions, such as `strlen()' and `strcmp()' in much the same way 11862 as was done for the memory operation functions. The only problem 11863 with this would be locale support, but perhaps it might be easier 11864 just to assume the C locale to begin with. Also need to have 11865 better detection of internal and free blocks when displaying 11866 memory range errors. 11867 11868 * Add wide-character equivalents of `memset()', etc. These are 11869 defined as `wmemset()', etc. and are now part of ANSI C. Also add 11870 `wcsdup()', `memdup()' and `xmemdup()' as well as `mempcpy()' and 11871 `memrchr()'. 11872 11873 * Perhaps reimplement the standard I/O library for internal use by 11874 mpatrol, thus preventing recursive calls to `malloc()' each time a 11875 write to the log file occurs on some systems. Example code to do 11876 this was submitted by Alexander Barton (<abarton@innotrac.com>) 11877 and this may well be incorporated into the library at some point 11878 in the future(3). 11879 11880 * The `LOG*' options could be extended to take a list of specific 11881 functions to log. They could also only log operations spanning a 11882 range of addresses or allocation indices as well. 11883 11884 * Add an option to limit the size of each memory allocation to a 11885 maximum number of bytes. This could be useful if a memory 11886 allocation function is called with an uninitialised variable. 11887 11888 * Add assertion macros to `mpatrol.h' that can be used in program 11889 code. These could be used to assert that pointers have not been 11890 freed, are valid heap addresses or are strings, or perhaps even 11891 that the address is readable, writable and/or executable. They 11892 would be disabled if `NDEBUG' is defined. 11893 11894 * Add support functions that could be added to user code to enter 11895 and leave scopes in a source file and ensure that all allocations 11896 allocated within the scope are freed by the time the scope has 11897 been exited. 11898 11899 * Add support for the `-finstrument-functions' option of the GNU 11900 compiler. This would allow mpatrol to keep track of the entry to 11901 and exit from every function, but would only work for code 11902 compiled with this option. 11903 11904 * Extend the Checker-support functions to store and check 11905 information about access permissions within heap memory and 11906 perhaps also in the stack as well, and also improve the 11907 diagnostics from the checker functions if they fail. Currently, 11908 the Checker-support functions only ensure that no memory accesses 11909 cross allocation boundaries or access free memory. Could also 11910 make use of the `etext', `edata' and `end' pointers that are set 11911 at run-time on most UNIX systems. Need to properly implement 11912 `chkr_check_exec()'. 11913 11914 * Details of the segments which make up the executable file and any 11915 shared libraries could be made use of in order to detect 11916 operations which cross such segments. For example, a memory 11917 operation may erroneously cross the data and BSS segments. The 11918 symbol table for data symbols could also be used to provide much 11919 finer-grained error-checking. Need to make use of the 11920 `__mp_memquery()' function. 11921 11922 * Add garbage detection support to mpatrol. This would be 11923 implemented as a function that would traverse all of the roots of 11924 the memory in a process and look for pointers into free memory or 11925 the lack of any pointers into allocated memory (to detect memory 11926 leaks). 11927 11928 * Add an option to specify that all failed memory allocations should 11929 abort (or at least give a warning) instead of returning a `NULL' 11930 pointer. Also, perhaps add an option to display the partial 11931 contents of freed and unfreed allocations in the mpatrol log file. 11932 11933 * Perhaps add memory protection to the simulated `sbrk' heap. 11934 11935 * Add an option to force the mpatrol library to return `NULL' if it 11936 is asked to allocate a zero-sized block of memory. This might be 11937 useful for SVID compliant programs. Perhaps also extend the 11938 mpatrol library to allow zero-sized blocks. I suspect the easiest 11939 way to do this is to have a special address that is always 11940 returned for such blocks and that will have the appropriate size 11941 of overflow buffers depending on the options used. 11942 11943 * Add an option to report if one thread resizes or frees another 11944 thread's allocations. This may not be useful in most cases, but 11945 it might be possible to track down some obscure bugs in some 11946 situations. 11947 11948 * Perhaps add internationalisation support through the use of 11949 locales and message catalogs. Unfortunately, there does not 11950 appear to be a unified method for doing this across all platforms 11951 and there may also be issues with third-party libraries calling 11952 `malloc()' and other related routines when the mpatrol library is 11953 attempting to initialise itself. 11954 11955 * There is currently a problem when the mpatrol library encounters 11956 an illegal memory access on UNIX and Windows platforms, and there 11957 is a further illegal memory access when it is displaying the 11958 summary. This should be prevented by disabling the signal handler 11959 at its first entry. 11960 11961 * Need to make the mpalloc library threadsafe(4). This is only 11962 likely to be an issue when calling `MP_FAILURE()'. Should also 11963 add something similar to `xmalloc_set_program_name()' in order to 11964 show the program name when a memory allocation fails. If the C++ 11965 operators fail to allocate memory in libmpalloc then there should 11966 probably also be an exception thrown to mimic the behaviour of 11967 libmpatrol, although this isn't a big issue since the program 11968 should be completely recompiled to remove mpatrol debugging before 11969 a release. In the same vein, perhaps there should be some sort of 11970 support for `set_new_handler()' in libmpalloc. 11971 11972 * Add an option to write the mpatrol log file in HTML format, or 11973 even better XML format. Need to also extend what is written out 11974 by the `--hatf-file' option. 11975 11976 * The `mpsym' command could optionally preserve any stack traceback 11977 lines that already have symbolic or debugging information 11978 associated with them. It could also support more debuggers other 11979 than just `gdb'. Finally, it could support `-' as the filename 11980 for reading the mpatrol log file from the standard input file 11981 stream. 11982 11983 * A good idea might be to have the `mpatrol' command read options 11984 from a configuration file instead of an environment variable, but 11985 that will only work if it doesn't involve allocating any memory 11986 before the mpatrol library has been initialised. 11987 11988 * Perhaps incorporate a C++ encoded name demangler into the mpatrol 11989 library. The most likely candidate is the GNU demangler that 11990 comes with the libiberty library, but that currently allocates 11991 temporary space on the heap using `xmalloc()' which means that it 11992 will run unbearably slowly under mpatrol(5). 11993 11994 * Add a script to wrap around various popular C and C++ compiler 11995 drivers so that linking with the mpatrol library is much less 11996 laborious. In addition, a user-defined command or script file 11997 could be executed at the end of every invocation of the `mpatrol' 11998 command. 11999 12000 * Add a script to automatically run the mpatrol library tests. It 12001 could be quite hard to verify the tests since the heap addresses 12002 are likely to be different on every new build and will certainly 12003 be different across different platforms. 12004 12005 * Improve the autoconf, automake and libtool support. Also update 12006 the `mupdate' shell script to automatically update the version 12007 numbers contained in the files in the `pkg' directory. 12008 12009 * The postscript version of the quick reference card seems to print 12010 at an unusual offset on some printers. In addition, the mpatrol 12011 manual should also be formatted in DocBook format once a suitable 12012 TeXinfo to DocBook translator is available. 12013 12014 * Perhaps add benchmark tests for dynamic memory allocation 12015 functions and memory operation functions. Obviously the mpatrol 12016 library would perform much worse than normal malloc libraries, but 12017 it would help to see just how much worse so that speed 12018 improvements could be made. 12019 12020 * Add support for the BeOS operating system, as well as MacOS, NeXT 12021 and OS/2. Perhaps MS-DOS might be possible as well. 12022 12023 ---------- Footnotes ---------- 12024 12025 (1) There is currently a library called StackTrace written by Bjorn 12026Reese which invokes a debugger to generate a stack traceback on certain 12027UNIX platforms. This method would be too slow for mpatrol to use 12028though. 12029 12030 (2) Looking back at these statements about six months after they 12031were written, it would appear that I have just written such a library 12032judging by the number of architectures for which stack traversal is now 12033supported. 12034 12035 (3) This code can be applied as an mpatrol library patch which can 12036be downloaded from 12037`http://www.cbmamiga.demon.co.uk/mpatrol/patches/mpatrol_patch1.tar.gz'. 12038 12039 (4) And perhaps also make the mptools library threadsafe as well 12040 12041 (5) If you really really want this functionality then code to do 12042this is available as an mpatrol library patch which can be downloaded 12043from 12044`http://www.cbmamiga.demon.co.uk/mpatrol/patches/mpatrol_patch4.tar.gz'. 12045 12046 12047File: mpatrol.info, Node: UNIX notes, Next: Amiga notes, Prev: Generic notes, Up: Notes 12048 12049Notes for UNIX platforms 12050======================== 12051 12052 * Need to improve watch point facility in order to speed it up by an 12053 order of magnitudes. This will most likely involve removing all 12054 watch points when entering the library and replacing them when 12055 returning to user code. 12056 12057 * Improve use of watch points by allowing an option which will only 12058 install write watch points instead of both read and write watch 12059 points. Not only will this speed up the use of watch points, but 12060 will also cause less problems with reading from misaligned memory 12061 allocations. 12062 12063 * There seems to be a problem on some UNIX systems in that the 12064 `mprotect()' call will not work unless it is used on memory that 12065 has been allocated with `mmap()'. This needs to be investigated 12066 further. 12067 12068 * There is currently a problem in that the call stack displayed from 12069 within the illegal memory access signal handler is not necessarily 12070 accurate with respect to the function at the top of the stack. In 12071 addition, signal handlers shouldn't technically call I/O functions 12072 in case of additional signals being caught so this may need to be 12073 improved. 12074 12075 * Need to add a way of initialising the thread-safe version of the 12076 library when it is not compiled on a system that supports `.init' 12077 sections, or if it is not compiled with the GNU C compiler, or if 12078 it is not compiled with a C++ compiler. Also perhaps need to 12079 support other threads packages instead of just POSIX threads. 12080 12081 * Need to add support for call stack traversal for the Itanium 12082 processor architecture. The current implementation of call stack 12083 traversal for the Motorola 88xx0 family is also a bit flaky and so 12084 should only be used when the library and program are built 12085 unoptimised. This could be improved on DG/UX platforms by making 12086 use of the TDESC information stored in the object files. 12087 12088 * Need to add support for obtaining the program name from the stack 12089 for the Alpha, Itanium and Motorola 88xx0 processor architectures. 12090 If there is no support for determining the filename that a 12091 program was invoked with then the `PROGFILE' option can be used to 12092 specify the program name at run-time. 12093 12094 * If the `MP_LIBRARYSTACK_SUPPORT' preprocessor macro is defined when 12095 building the mpatrol library on IRIX platforms then the `libexc' 12096 library must also be linked in. However, execution speed will 12097 fall dramatically since the `unwind()' function within that 12098 library calls `malloc()', `free()' and other memory operation 12099 functions every time it is invoked. The only reason to use this 12100 library rather than the default method of stack traversal on MIPS 12101 would be if that method failed due to a bug (in which case it 12102 should be reported anyway). 12103 12104 * The mpatrol library `unwind()' function on MIPS platforms may have 12105 problems with call stack traversal in alternative stacks, such as 12106 those used by signal handlers. The call stack will then terminate 12107 at the point at which the handler was called rather than unwinding 12108 to the top of the stack. 12109 12110 * The library cannot currently read any symbols from shared objects 12111 that have been read via `dlopen()', `shl_load()' or similar 12112 functions(1). In addition, symbols cannot currently be read from 12113 any COFF or XCOFF shared libraries on LynxOS and some work needs 12114 to be done to build the mpatrol library as a shared library on 12115 LynxOS. 12116 12117 * Perhaps add support for reading HP/UX executable files and 12118 libraries in the SOM object file format without needing to use the 12119 GNU BFD library. 12120 12121 * Perhaps add support for other popular text editors in the `mpedit' 12122 command. Also add a way to specify editor options to the `mpedit' 12123 command. 12124 12125 * Add support for SCO UNIX, Ultrix and other non-System V UNIX 12126 operating systems. Also test on NetBSD, OpenBSD and SunOS as 12127 support has been written for these systems but is untested. The 12128 SunOS port requires an ANSI C compiler, though. 12129 12130 * The `--dynamic' option to the `mpatrol' command does not always 12131 work on systems whose dynamic linkers support the `LD_PRELOAD' or 12132 `_RLD_LIST' environment variables. This is because the object 12133 file format access libraries do not exist in shared form on such 12134 systems. 12135 12136 * Perhaps add files to build the mpatrol library and tools as BSD 12137 packages. 12138 12139 ---------- Footnotes ---------- 12140 12141 (1) There is an mpatrol library patch that supports reading symbols 12142from shared libraries opened by `dlopen()' which can be downloaded from 12143`http://www.cbmamiga.demon.co.uk/mpatrol/patches/mpatrol_patch2.tar.gz'. 12144 12145 12146File: mpatrol.info, Node: Amiga notes, Next: Windows notes, Prev: UNIX notes, Up: Notes 12147 12148Notes for Amiga platforms 12149========================= 12150 12151 The Amiga has now been re-released as a completely new machine which 12152comes with a completely new operating system. As a result, I will not 12153be implementing any of the following features (or fixing any of the 12154following problems) in mpatrol for the old AmigaOS. Support for the 12155new AmigaOS may be added in the future. 12156 12157 * Perhaps add support for building mpatrol as an Amiga shared 12158 library. I attempted to do this in a previous release of mpatrol, 12159 but it would have involved too many source changes to get working 12160 fully. Perhaps it's not even worth implementing as the archive 12161 library works fine. However, if it is built as a shared library 12162 and `malloc()' and related functions are dynamically linked in 12163 some executable files then perhaps it would be possible to override 12164 these functions, thus getting the `--dynamic' option in the 12165 `mpatrol' command to work. 12166 12167 * Need to fix the problem where the maximum guaranteed alignment of 12168 an internal mpatrol library memory allocation is 8 bytes. 12169 However, this limitation does not affect the `memalign()' and 12170 related functions, and should not have any effect on the running 12171 of mpatrol since no datatypes require an alignment of more than 8 12172 bytes. 12173 12174 * Need to add proper support for call stack traversal for both the 12175 Motorola 680x0 and PowerPC processor architectures. When `gcc' is 12176 being used then up to two stack frames can be traversed, but this 12177 should really be extended without requiring 12178 `MP_BUILTINSTACK_SUPPORT'. When SAS/C is being used then there is 12179 no support for call stack traversal. 12180 12181 * Need to add proper support for reading symbols from Amiga 12182 executable files. When `gcc' is being used then the BFD library 12183 routines will be called to determine the symbols from the 12184 executable file, but this will only work for objects compiled with 12185 `gcc' and there currently appears to be a problem getting the 12186 `USEDEBUG' option to work. When SAS/C is being used then there is 12187 no support for reading symbols from executable files. Also need 12188 to add support for reading symbols from any shared libraries that 12189 are required by the program. 12190 12191 * Possibly make use of other software such as Enforcer, Mungwall or 12192 MuLib in order to provide some form of memory protection. The 12193 features of SegTracker could also be put to good use so that the 12194 file and hunk location of entries on the call stack could be 12195 determined. 12196 12197 * Could add support for the `EDIT' and `LIST' options. This would 12198 probably involve finding a way to invoke a shell script without 12199 having to search for the script file or allocating memory in the 12200 process. 12201 12202 * Add GUI support for the `mptrace' command. 12203 12204 * When using SAS/C it is currently not possible to override the 12205 definition of `malloc()', etc., without including the `mpatrol.h' 12206 header file first. This is because the compiler startup code and 12207 libraries call `malloc()' before everything is set up, and so the 12208 library cannot properly initialise itself if the `malloc()' that 12209 the startup code finds is the `malloc()' in the mpatrol library. 12210 This restriction does not exist when using `gcc'. 12211 12212 * Add support for the Amiga in the threads test in 12213 `tests/pass/test5.c'. The Amiga doesn't really have support for 12214 threads but its processes are similar enough to threads. 12215 12216 * Perhaps add an `Installer' installation script with icons. 12217 12218 12219File: mpatrol.info, Node: Windows notes, Next: Netware notes, Prev: Amiga notes, Up: Notes 12220 12221Notes for Windows platforms 12222=========================== 12223 12224 * Need to add support for processors other than the Intel 80x86. 12225 However, about 99% of Windows platforms run on this processor 12226 family -- does anyone really use Windows with other processors? 12227 Also finish Cygwin support, although this is effectively mpatrol 12228 built with `-DTARGET=TARGET_UNIX' support on Windows platforms. 12229 12230 * Perhaps add support for compiling the mpatrol library with `gcc' on 12231 Windows platforms so that the GNU BFD library can be used as well. 12232 12233 * There seems to be a problem when mixing the archive version of the 12234 mpatrol library and the Microsoft C run-time library DLL, and vice 12235 versa. This needs to be looked into, but for the moment, don't 12236 mix them. 12237 12238 * The library cannot currently read any symbols from DLLs that have 12239 been read via `LoadLibrary()'. 12240 12241 * There seems to be a disparity between different versions of the 12242 imagehlp library. It would appear that the latest incarnation of 12243 the imagehlp library has had some functions removed and placed in 12244 a new library called debughlp. Perhaps this simply means that 12245 `debughlp.lib' needs to be linked in as well, but maybe there's 12246 more to it than that. 12247 12248 * Perhaps add support for the `mpatrol' command's `--dynamic' option 12249 by preloading the mpatrol DLL from the `mpatrol' command. 12250 12251 * Could add support for the `EDIT' and `LIST' options. This would 12252 probably involve finding a way to invoke a batch file without 12253 having to search for the batch file or allocating memory in the 12254 process. 12255 12256 * Add GUI support for the `mptrace' command. 12257 12258 * Add a Windows resource file to the mpatrol library with copyright 12259 and version information. 12260 12261 * Perhaps add an `InstallShield' installation script with icons. 12262 12263 12264File: mpatrol.info, Node: Netware notes, Prev: Windows notes, Up: Notes 12265 12266Notes for Netware platforms 12267=========================== 12268 12269 There doesn't appear to have been any interest in the Netware 12270version of mpatrol and as a result I will not be implementing any of 12271the following features (or fixing any of the following problems) in 12272mpatrol for Netware. I don't even have access to a Netware machine so 12273someone else would have had to have done it anyway. 12274 12275 * The library has not yet been built (let alone tested) on Netware 12276 platforms. The names of the system functions that the library 12277 calls for Netware were obtained by looking at Novell's developer 12278 documentation, so they may not even compile correctly without 12279 modification. 12280 12281 * Need to add support for building the mpatrol library as an NLM. 12282 This is not currently a high priority requirement as the archive 12283 library should suffice for most purposes. However, if it is built 12284 as an NLM and `malloc()' and related functions are dynamically 12285 linked in some executable files then perhaps it would be possible 12286 to override these functions, thus getting the `--dynamic' option 12287 in the `mpatrol' command to work. 12288 12289 * Need to add support for processors other than the Intel 80x86. 12290 However, about 99% of Netware platforms run on this processor 12291 family -- does anyone really use Netware with other processors? 12292 12293 * Need to add way to determine when the base of the stack has been 12294 reached during call stack traversal, since on Netware every 12295 application is really a thread running under one large process. 12296 12297 * Need to add support for reading symbols from Netware load modules. 12298 Also need to add support for reading symbols from any NLMs that 12299 are required by the program. This may be possible in a limited 12300 fashion by using the GNU BFD library, but may only work with code 12301 compiled with `gcc'. 12302 12303 * Could add support for the `EDIT' and `LIST' options. This would 12304 probably involve finding a way to invoke a batch file without 12305 having to search for the batch file or allocating memory in the 12306 process. 12307 12308 * Add GUI support for the `mptrace' command. 12309 12310 * Need to investigate if it is safe (or even possible) to override 12311 the definitions of `malloc()', etc., without including the 12312 `mpatrol.h' header file first. Currently, non-macro definitions 12313 for these functions have been disabled in the Netware version of 12314 the library in case they affect other NLMs that are currently 12315 running. 12316 12317 12318File: mpatrol.info, Node: Frequently asked questions, Next: Related software, Prev: Notes, Up: Top 12319 12320Frequently asked questions 12321************************** 12322 12323 This section contains frequently asked questions about the mpatrol 12324library and their corresponding answers or solutions. 12325 12326* Menu: 12327 12328* Documentation:: Formatting, converting and printing. 12329* Building:: Compiling with the mpatrol library. 12330* Linking:: Linking with the mpatrol library. 12331* Running:: Running with the mpatrol library. 12332* Files:: Different types of files. 12333 12334 12335File: mpatrol.info, Node: Documentation, Next: Building, Up: Frequently asked questions 12336 12337Documentation 12338============= 12339 12340 1. I can't seem to format the TeXinfo manual for mpatrol into 12341 anything that I can view or print. What am I doing wrong? 12342 12343 You'll need to have the appropriate document formatting programs 12344 installed on your system before you can do this, and even then 12345 you'll also need to have suitable software for viewing or printing 12346 the formatted documents. The mpatrol distribution should already 12347 contain the latest mpatrol manual in a variety of formats and 12348 should also contain a file telling you where to get programs that 12349 can be used to view or print these files. Alternatively, you can 12350 browse the latest mpatrol manual on-line at 12351 `http://www.cbmamiga.demon.co.uk/mpatrol/'. 12352 12353 2. I'd like to convert the mpatrol manual to a different 12354 documentation format but there is no support for that format in 12355 the `Makefile'. How would I go about doing this? 12356 12357 Since TeXinfo is intended to be converted to other documentation 12358 formats it should be fairly easy for you to find a tool which will 12359 convert it into your desired format. I plan to also provide the 12360 mpatrol manual in DocBook format if and when a suitable TeXinfo to 12361 DocBook converter becomes available, but I won't provide 12362 preformatted versions of the mpatrol manual in any other format 12363 which isn't already supported. 12364 12365 3. Why is the reference card not centred in the middle of the page 12366 when I print it? 12367 12368 The reference card has three columns in landscape format and as a 12369 result requires smaller margins than LaTeX normally uses. When 12370 `dvips' converts the DVI file to a postscript file it refers to a 12371 configuration file set up for a specific printer so that it knows 12372 what that printer's capabilities are. However, you can instruct 12373 `dvips' to offset the page by a given amount with the `-O' option 12374 so that it appears centred when printed. I find that `-O 12375 -0.75in,0.25in' works for me. Note that the default paper size 12376 for the reference card is DIN A4, but you can change it to US 12377 letter in the LaTeX source file. 12378 12379 4. How do I install the mpatrol manual as a GNU info file? 12380 12381 Assuming you have the GNU info file built and copied to your 12382 system's info file directory, you should use the `install-info' 12383 command to place an entry for mpatrol in your system's GNU info 12384 directory file, otherwise the GNU info reader may not be able to 12385 locate the mpatrol entry. You may also need to modify your 12386 `INFOPATH' environment variable if you installed the GNU info file 12387 in a non-standard place. 12388 12389 5. How do I install the mpatrol manual pages? 12390 12391 This is very system-dependent, but need only be done on UNIX 12392 systems since they cannot be used on other platforms. The 12393 unformatted manual pages exist in `man/man1' and `man/man3' and 12394 should be copied to your system's manual page directory. If you 12395 don't have the `nroff', `troff' or `groff' commands installed on 12396 your system then you may also need to copy the formatted manual 12397 pages, located in `man/cat1' and `man/cat3'. You may also need to 12398 modify your `MANPATH' environment variable if you installed the 12399 manual pages in a non-standard place, and some systems require you 12400 to update the _whatis_ database after installing new manual pages, 12401 by running `makewhatis', `catman' or equivalent. 12402 12403 Alternatively, the mpatrol manual pages can be built in a variety 12404 of different documentation formats that can be viewed or printed 12405 without the need for a `man' command. If you have the correct 12406 tools installed on your system then you should be able to do this 12407 by examining the `Makefile' in the `man' directory. The mpatrol 12408 distribution should already contain the latest mpatrol manual 12409 pages in a variety of formats and should also contain a file 12410 telling you where to get programs that can be used to view or 12411 print these files. 12412 12413 6. Why does the `libmpatrol.3' manual page not display correctly when 12414 I view it with the `man' command? 12415 12416 This is likely to be due to the `tbl' command not being run to 12417 process the tables when the `man' command displays the manual 12418 page. Many UNIX systems look at the first line of the manual page 12419 to see what filters to run the page through before it is 12420 displayed, but some systems do not recognise this and instead rely 12421 on an environment variable such as `MANROFFSEQ' to specify which 12422 filters are to be run. Look at the manual page for the `man' 12423 command on your system to find out more information. 12424 12425 12426File: mpatrol.info, Node: Building, Next: Linking, Prev: Documentation, Up: Frequently asked questions 12427 12428Building 12429======== 12430 12431 1. Why does the `Makefile' assume that I am building mpatrol on 12432 platform X when I am really building on platform Y? 12433 12434 The `src/config.h' and `src/target.h' header files attempt to 12435 obtain as much information from the compiler as possible, mainly 12436 from any predefined preprocessor macros that it defines during 12437 compilation. If this information is incorrect then you can 12438 override the `TARGET', `SYSTEM', `ARCH', `ENVIRON', `FORMAT' and 12439 `DYNLINK' preprocessor macros defined in `src/target.h' to suit 12440 your particular system by explicitly defining them in `CFLAGS' 12441 within the `Makefile' when you build mpatrol. You could also 12442 choose to build different versions of mpatrol with different 12443 settings of `ENVIRON', `FORMAT' or `DYNLINK' on a single system if 12444 you wish to by changing `ENVIRON', `FORMAT' or `DYNLINK' for 12445 different builds. 12446 12447 2. The processor family I am compiling on supports both 32-bit and 12448 64-bit modes of operation. How do I specify which I want? 12449 12450 You will have to look at the documentation for the compiler you 12451 are using in order to find out how to specify which operating 12452 environment you wish to target. For example, if you are using the 12453 Sun C compiler on a SPARC V9 Solaris machine then you should 12454 specify the `-xarch=v9' option in the `Makefile' when you are 12455 building mpatrol in order to target the 64-bit environment. If 12456 you think that you are already using the correct option, but the 12457 mpatrol code is still being built to support the wrong environment 12458 then you could try explicitly setting the `ENVIRON' preprocessor 12459 macro in the `Makefile'. 12460 12461 3. I cannot include `mpatrol.h' from my C++ source code as I get lots 12462 of compilation errors. Why is this and what can I do to prevent 12463 them? 12464 12465 The most likely reason that you are getting errors is because you 12466 are calling placement `new', and the way that mpatrol derives 12467 source information from calls to `operator new' is by defining a 12468 macro called `new', thus causing lots of problems when calling 12469 placement `new' or explicitly calling `operator new'. You can 12470 either try not to use placement `new' or you can define the 12471 preprocessor macro `MP_NOCPLUSPLUS' when compiling your source 12472 file, which will disable the overriding of any C++ operators in 12473 `mpatrol.h'. Alternatively, if you define `MP_NONEWDELETE' then 12474 you can use `MP_NEW', `MP_NEW_NOTHROW' and `MP_DELETE' in order to 12475 call the mpatrol versions of the C++ operators. 12476 12477 4. I still have the above problem, but I don't think it's due to 12478 placement `new' since the compiler complains about `operator 12479 new[]', so could that be a clue? 12480 12481 Yes. The most likely reason is that the C++ compiler does not 12482 support the array `new' and `delete' operators. These were 12483 introduced some time before the standardisation of the C++ 12484 language but some compilers may not yet have support for them. It 12485 may be that you have to use a special compiler option to enable 12486 support for these operators, but if not you will probably have to 12487 edit `mpatrol.h' to temporarily allow your files to compile. 12488 12489 5. I tried both of the above suggestions, but I still can't get my 12490 C++ source code to compile. I'm using an old C++ compiler so 12491 could that be a problem? 12492 12493 Yes. The `mpatrol.h' header file defines new versions of the C++ 12494 dynamic memory allocation operators using exceptions and 12495 namespaces as required by the ANSI C++ standard. If your C++ 12496 compiler has no support for these then you should compile your C++ 12497 source files with `MP_NOCPLUSPLUS' defined. You may also be using 12498 an older C++ library in which the `new' header file does not 12499 define `set_new_handler()' to be in the `std' namespace. You will 12500 then have to change the `mpatrol.h' header file and `cplus.c' 12501 source file accordingly. 12502 12503 6. I'm calling `operator new' (not the _nothrow_ version) from my C++ 12504 source code but when my program runs out of memory the `OUTMEM' 12505 error is given in the mpatrol log file rather than throwing a 12506 `std::bad_alloc' exception. Why is this? 12507 12508 Sounds like the mpatrol library was built with a C compiler. In 12509 order for the mpatrol versions of `operator new' and `operator 12510 new[]' to throw an exception when they run out of memory, the 12511 mpatrol library must have been built with a C++ compiler. The 12512 `OUTMEM' error is only given when there is no way to throw an 12513 exception. 12514 12515 7. Why am I unable to call the mpatrol version of `alloca()'? I only 12516 ever seem to call the default version. 12517 12518 Most implementations of the `alloca()' function are compiler 12519 builtins which will be converted to inline assembler or object 12520 code in order for them to be able to dynamically modify the 12521 calling function's stack frame at run-time. As a result, the call 12522 to `alloca()' is recognised as an intrinsic keyword and is dealt 12523 with specially by the compiler. However, if this can be 12524 intercepted by the preprocessor before the compiler parses the 12525 source code then the call can be redirected to another function. 12526 This is one of the functions of the `mpatrol.h' header file, which 12527 means that it must be included before the first call the 12528 `alloca()'. If `alloca.h' is also being included then `mpatrol.h' 12529 must be included after it, otherwise it may redefine `alloca()' 12530 back to the default version. 12531 12532 8. Why do some of the `Makefile's contain the `-fno-inline-functions' 12533 option as part of `OFLAGS'? 12534 12535 The `-fno-inline-functions' option is a `gcc'-specific option 12536 which instructs the compiler not to inline any functions. This is 12537 necessary on some platforms where function call stack traversal is 12538 supported, since function inlining may significantly alter the 12539 layout of a program's stack. Normally this option is only 12540 required when building the mpatrol library, but on some platforms 12541 function call stack traversal may not work properly unless this 12542 option (or equivalent) is used for all compiled code. 12543 12544 9. What does the `MP_ALIGN' definition in `mpatrol.h' do? 12545 12546 It is a preprocessor macro function that is used to return the 12547 minimum alignment in bytes required for a specified type at 12548 compile-time. It is used in the `MP_MALLOC' family of functions 12549 to specify the required alignment of the memory allocation that is 12550 to be used to store the specified type. Some compilers provide a 12551 feature that can be used to determine the minimum alignment of a 12552 type at compile-time. For all others, this macro evaluates to `0'. 12553 12554 10. What does the `MP_INLINE' definition in `mpatrol.h' do? 12555 12556 It is used in the definition of the debugging versions of the C++ 12557 operators in `mpatrol.h' so that they are inlined correctly. We 12558 want to define the C++ operators so that they will be inlined in 12559 every source file that uses them and also not clash with the 12560 versions defined in the mpatrol library or the standard C++ 12561 library. Traditionally, this is done by defining them to be 12562 `static inline', which means that any non-inlined definition will 12563 be local to each object file. An even better technique is 12564 available with the new C++ standard which allows `extern inline' 12565 definitions, meaning that no definition will be available if the 12566 function is not inlined. Unfortunately, if optimisation is turned 12567 off in the compiler then no inlining will usually be performed and 12568 so the definitions will be real functions. Luckily, on ELF 12569 platforms the `extern inline' function definition will have a weak 12570 visibility and so will not clash with library functions. 12571 12572 11. Why do I get different stack traces in the mpatrol log file from 12573 the C++ operators in `mpatrol.h' when optimisation is turned on 12574 and off in the compiler? 12575 12576 When the compiler is optimising it will invariably be performing 12577 inlining, in which case each inlined function will share the stack 12578 frame of its caller when it is called -- the mpatrol library 12579 cannot detect this. In order to cope in both situations, the 12580 non-inlined case will contain the name of the C++ operator at the 12581 top of its stack, even though it will be removed in the inlined 12582 case. 12583 12584 12. How do I build the `mptrace' command with GUI support? 12585 12586 The GUI support for the `mptrace' command is currently written to 12587 use Motif and X Windows and so can only be built on systems with 12588 these libraries and run on systems with an X server. This will 12589 most likely be possible only on UNIX platforms. LessTif can be 12590 used instead of Motif if that is all that is available on your 12591 system. The UNIX `Makefile' has a macro called `GUISUP' which can 12592 be set to `true' or `false' depending on whether you wish to have 12593 GUI support or not. The default is `false'. GUI support is 12594 automatically enabled on platforms that support it if the 12595 `configure' script in `pkg/auto' is used. 12596 12597 13. How do I build the `mptrace' command without GUI support? 12598 12599 This is done by default on most platforms when using the 12600 `Makefile's in the `build' directory. However, if for some reason 12601 that is not the case then on UNIX platforms you will have to set 12602 the `GUISUP' `Makefile' macro to `false' when compiling `mptrace'. 12603 You might need to do this if your UNIX system does not have the 12604 correct header files and libraries installed needed for GUI 12605 support. If you are using the `configure' script in `pkg/auto' 12606 then GUI support will be automatically disabled on platforms that 12607 do not support it, but you can force it to be disabled by using the 12608 `--without-x' option. 12609 12610 12611File: mpatrol.info, Node: Linking, Next: Running, Prev: Building, Up: Frequently asked questions 12612 12613Linking 12614======= 12615 12616 1. Why do I get undefined symbols when linking with the mpatrol 12617 library? 12618 12619 This is most likely caused by the mpatrol library requiring 12620 additional symbols defined in an object file access library. If 12621 mpatrol was built with `FORMAT=FORMAT_COFF' or 12622 `FORMAT=FORMAT_XCOFF' then you'll need to add `-lld' (or 12623 equivalent) to the compiler command line straight after 12624 `-lmpatrol'. If mpatrol was built with `FORMAT=FORMAT_ELF32' or 12625 `FORMAT=FORMAT_ELF64' then you'll need to add `-lelf' (or 12626 equivalent) to the compiler command line straight after 12627 `-lmpatrol'. If mpatrol was built with `FORMAT=FORMAT_BFD' then 12628 you'll need to add `-lbfd -liberty' (or equivalent) instead. If 12629 you are using the thread-safe version of mpatrol then you may also 12630 need to link with the system threads library. 12631 12632 2. Why do I still get undefined symbols on HP/UX, IRIX, Tru64 or 12633 Windows platforms, despite following the above instructions? 12634 12635 If the symbol is called `U_get_previous_frame' on HP/UX then you 12636 still need to link with the system stack traceback library, 12637 `libcl.sl'. If the symbols are called `exc_setjmp' and `unwind' 12638 on IRIX or Tru64 and you defined the `MP_LIBRARYSTACK_SUPPORT' 12639 preprocessor macro when building the mpatrol library then you 12640 still need to link with the system exception library, `libexc.so'. 12641 If the symbols all begin with `Sym' on Windows platforms then you 12642 still need to link with the system symbol access library, 12643 `imagehlp.lib'. 12644 12645 3. I tried all of the above, but why is the `SymGetLineFromAddr' 12646 symbol still undefined on Windows platforms? 12647 12648 This is due to the `imagehlp.lib' or `imagehlp.dll' libraries on 12649 your system being out of date. The `SymGetLineFromAddr()' 12650 function was added to this library at a much later date from the 12651 original release so if you want the `USEDEBUG' option to work you 12652 should try to get an updated library from Microsoft. 12653 Alternatively, you can disable the call to it in 12654 `__mp_findsource()' but the `USEDEBUG' option will no longer work. 12655 12656 4. Why is the mpatrol library unable to read any symbols from DLLs 12657 despite the fact that my program uses them? 12658 12659 Windows executable files and DLLs only contain a list of symbol 12660 names which are imported and exported but do not contain details 12661 of such symbols at the same level as object files. To do this 12662 requires the symbolic information to be retained by the linker, 12663 but this has not been done for the system DLLs. The mpatrol 12664 library uses the imagehlp system library to read symbols from DLLs 12665 but this will only work if the required system debugging symbols 12666 are installed on your machine. In Visual C++, this can be done by 12667 selecting the `Windows NT Symbols Setup' start menu item. 12668 12669 5. Why do I get duplicate definitions of symbols when linking with 12670 the mpatrol library? 12671 12672 This is most likely caused by your code, or a library, providing 12673 definitions of `malloc()' and `free()' which conflict with those 12674 defined in the mpatrol library. You'll need to disable these in 12675 order to perform a successful link and use the replacements in 12676 mpatrol instead. 12677 12678 6. Why do I get `xmalloc()' as a multiply-defined symbol when I link 12679 with the archive version of the mpatrol library? 12680 12681 If the mpatrol library was built with `FORMAT=FORMAT_BFD' then it 12682 is because the libiberty library contains definitions of the 12683 `xmalloc()' family of functions as well. You should rebuild the 12684 mpatrol library without the definitions of the relevant 12685 `xmalloc()' functions in `malloc.c'. You're also likely to get 12686 this error if you link with the archive version of the mpatrol 12687 library and one or more of the `xmalloc()' family of functions is 12688 defined in another archive library that you are linking with. 12689 12690 7. I linked my program to a shared library version of mpatrol. Now, 12691 when I try to run my program, the system complains that it cannot 12692 find the mpatrol library. How do I get this to work? 12693 12694 You need to tell the system where to find the shared library 12695 version of the mpatrol library, either by setting your 12696 `LD_LIBRARY_PATH' environment variable (or just `PATH' on Windows 12697 platforms), or by embedding the full path to the library into the 12698 executable when you link your program by setting the `LD_RUN_PATH' 12699 environment variable. 12700 12701 8. I linked my program to a shared library version of mpatrol. Will 12702 future releases of mpatrol remain compatible with this version or 12703 will I have to relink my program? 12704 12705 Backwards compatibility is not generally guaranteed, but should be 12706 preserved if only the bug fix part of the mpatrol version number 12707 has changed, with the major and minor versions staying the same. 12708 For example, versions 1.0.3 and 1.0.8 should be compatible, but 12709 upgrading to version 1.1.0 may require a relink. 12710 12711 9. I have linked my program with the DLL version of the mpatrol 12712 library on Windows but it crashes when I run it. I suspect that 12713 the crash is occurring when the mpatrol library is being 12714 initialised, so what is going wrong? 12715 12716 There appears to be a problem when using the mpatrol DLL and the 12717 static version of the Microsoft C run-time library, and also a 12718 problem when using the static version of mpatrol and the Microsoft 12719 C run-time library DLL. Luckily, if you ensure that you use 12720 either both static libraries or both DLLs at the same time then 12721 the problem should go away. There doesn't seem to be an easier 12722 way around it at this time or, for that matter, an explanation for 12723 why it happens. 12724 12725 10. Why are mpatrol library functions not called from shared libraries 12726 on AIX? 12727 12728 AIX uses static shared libraries instead of dynamic shared 12729 libraries, which means that all shared library bindings are 12730 resolved at link time rather than load time (i.e. you must specify 12731 which shared libraries resolve all of the undefined symbols that 12732 result when building a shared library). If you would like mpatrol 12733 library functions to be called from a shared library, you must 12734 rebuild the shared library with `-lmpatrol' on the link line. 12735 However, this means that you cannot override `malloc()', etc., in 12736 shared libraries that you cannot rebuild unless you link 12737 statically with the archive library versions instead. 12738 12739 12740File: mpatrol.info, Node: Running, Next: Files, Prev: Linking, Up: Frequently asked questions 12741 12742Running 12743======= 12744 12745 1. I've just linked and run my program with the mpatrol library, but 12746 the resulting log file doesn't contain any useful information. 12747 Why does it not contain a list of all memory transactions or show 12748 any unfreed memory allocations? 12749 12750 By default, the mpatrol library will only write a summary of 12751 library settings and statistics to the log file, and that will 12752 only occur on successful program termination (i.e. when `exit()' 12753 is called). If this does not appear then it is likely that your 12754 program (or some other library function) called `abort()' due to a 12755 fatal error. However, there are a multitude of different options 12756 that you can pass to the mpatrol library via the `MPATROL_OPTIONS' 12757 environment variable that will allow you to control what is logged 12758 and what is not. Note that the `mpatrol' command will always log 12759 all calls to allocate, reallocate and free memory by default. 12760 12761 2. Why does my C++ program crash at program termination when it is 12762 linked with the mpatrol library and it appears to be doing nothing 12763 wrong? 12764 12765 If your program contains file-scope objects whose constructors get 12766 called before `main()' and whose destructors get called after 12767 `main()' then it is likely that one of these destructors is 12768 allocating memory after the mpatrol library has terminated. This 12769 should already be resolved if you built the mpatrol library on a 12770 platform that supports `.init' and `.fini' sections or if you 12771 built it with the GNU compiler or a C++ compiler. However, in 12772 certain circumstances this may not work so you may wish to try 12773 terminating the mpatrol library by getting it to register itself 12774 with `atexit()' instead, which will hopefully resolve the problem. 12775 You can do this by rebuilding the mpatrol library with the 12776 `MP_USE_ATEXIT' preprocessor macro defined. 12777 12778 3. I linked my program with the mpatrol library to trace all of its 12779 memory operations, such as `memcpy()' and `memcmp()', but I get 12780 nothing in the log file. Why is this? 12781 12782 On systems that do not support `.init' and `.fini' sections or are 12783 not `gcc' or C++ based then the memory operation functions will not 12784 automatically initialise the mpatrol library since on many systems 12785 the startup routines call them very early on. On such systems, if 12786 your program does not call any memory allocation functions to 12787 initialise the mpatrol library then you must explicitly call the 12788 `__mp_init()' function. All memory operation functions following 12789 that call with then be traced. 12790 12791 4. Why does the `USEDEBUG' option not work for me? 12792 12793 Firstly, you have to ensure that you have built the mpatrol 12794 library with support for the GNU BFD object file access library by 12795 compiling with the `FORMAT=FORMAT_BFD' preprocessor macro 12796 definition, or you are running on a Windows platform. Secondly, 12797 you have to ensure that you have compiled all relevant object 12798 files with debugging information enabled (usually by adding an 12799 option to the compiler command line), although the mpatrol library 12800 does not need to be compiled this way. The file and line number 12801 information will hopefully then appear in the log file for all 12802 symbols that have associated debugging information. If none of 12803 the above suggestions work, you may still be able to get this 12804 information with the `mpsym' command. 12805 12806 5. Why does the `mpatrol' command ignore the current value of the 12807 `MPATROL_OPTIONS' environment variable? 12808 12809 Because I would most likely get lots of bug reports or queries 12810 from people who had forgotten that they had set some options in 12811 the environment variable and had then not seen the expected 12812 behaviour from the options they specified to the `mpatrol' 12813 command. Recently, though, I've added the `--read-env' option so 12814 that this can be achieved. 12815 12816 6. Why do I get an error from the dynamic linker about not being able 12817 to locate `libiberty.so' when I use the `--dynamic' option with the 12818 `mpatrol' command? 12819 12820 The GNU libiberty library is required when the mpatrol library is 12821 build with support for the GNU BFD library but is unfortunately 12822 only available in archive form on many systems. See the section 12823 on the `mpatrol' command (*note The mpatrol command::) for 12824 information on how to get around this problem, either by embedding 12825 the libiberty library into the mpatrol library when you are 12826 building it, or by converting the archive form of the libiberty 12827 library into its corresponding shared library version. 12828 12829 7. Why does the mpatrol library not read the symbols in my executable 12830 file on Windows platforms? 12831 12832 If the mpatrol library was compiled with the `FORMAT=FORMAT_PE' 12833 preprocessor macro defined then you must ensure that you compile 12834 your files with debugging information enabled (using the `-Z7' or 12835 `-Zi' options in Visual C++) and that you tell the linker that you 12836 wish to preserve the debugging information in the executable file 12837 (using the `-debug' and `-pdb:none' options in the Microsoft 12838 linker). Unfortunately, if you do not do this then the final 12839 executable file will not have a symbol table and so the mpatrol 12840 library cannot give symbolic stack tracebacks. 12841 12842 8. Why do some mpatrol log file entries only contain a partial call 12843 stack rather than following the function call stack back to the 12844 call to `main()'? 12845 12846 This could be because the mpatrol library was compiled with 12847 limited call stack traversal support via the 12848 `MP_BUILTINSTACK_SUPPORT' configuration macro. However, it could 12849 also mean that the mpatrol library encountered a corrupt frame 12850 pointer when traversing the call stack and had to terminate the 12851 recursion. The frame pointer _must_ be preserved from function to 12852 function on most platforms, otherwise the stack cannot be 12853 traversed. See your compiler manual for further details. 12854 12855 9. I am trying to use the `mpatrol' command to debug an executable 12856 file that was not originally compiled with the mpatrol library. 12857 However, even though it runs successfully, no mpatrol log file is 12858 produced. Why is this? 12859 12860 First, check that you are passing the `--dynamic' option to the 12861 `mpatrol' command and, if necessary, the `--threads' option as 12862 well. If that doesn't work then check that the executable file 12863 has been dynamically linked; statically linked executables cannot 12864 be forced to use the mpatrol library. If it still doesn't work 12865 then it may be that the dynamic linker on your system doesn't have 12866 the ability to preload any shared libraries that have been 12867 specified in a special environment variable, in which case you 12868 can't use this feature. 12869 12870 10. I am attempting to run a multithreaded C++ program with the 12871 mpatrol library on Linux. However, my program crashes before 12872 `main()' and the debugger shows that the failure is in 12873 `__sigaction()' which is called from `__mp_initsignals()'. Is the 12874 fault with the mpatrol library? 12875 12876 There have been many reports of this problem and it turns out to 12877 be an issue with shared library dependencies. ELF shared 12878 libraries may contain initialisation functions that are executed 12879 before `main()'. However, sometimes the order in which these 12880 functions are executed is critical. In this case it is likely 12881 that the mpatrol and pthreads libraries are being initialised in 12882 the wrong order. You must ensure that `-lpthread' appears near the 12883 very end of the link line after all user libraries, and you must 12884 also ensure that none of the user libraries have a dependency on 12885 `libpthread.so'. You can verify this by running the `ldd' command 12886 on them. 12887 12888 11. I know that there's a definite heap corruption problem in my 12889 program as it keeps crashing in unrelated code due to pointer 12890 corruption, and when I link with the mpatrol library it stops 12891 crashing. What can I do? 12892 12893 Try as many of the relevant mpatrol run-time options as possible 12894 and make sure that you closely examine the mpatrol log file for 12895 warnings and errors -- your problem may have been noticed by the 12896 mpatrol library but it may not have considered it a fatal error 12897 and continued execution. If this still doesn't show up anything 12898 then you can probably rest assured that you have a memory 12899 corruption problem but you may need to use a commercial product 12900 such as Purify to isolate it. If that fails then you'll just have 12901 to employ the traditional debugging method of single-stepping 12902 through your program in a debugger until something unusual or 12903 unexpected happens. 12904 12905 12. If I link my program to version 1.0 of the mpatrol library then I 12906 cannot interrupt it using the keyboard, which I would normally be 12907 able to do without using mpatrol. Is this a bug? 12908 12909 Not really, but it is undesirable behaviour in most cases, which 12910 is why it was removed in later releases of mpatrol and replaced 12911 with the `SAFESIGNALS' option. The reason that the program could 12912 not be interrupted using the keyboard was that mpatrol would 12913 ignore such signals when its library code was being executed, 12914 otherwise user-defined signal handlers that used `malloc()' and 12915 related functions would have the capability to cause lots of 12916 undesirable side effects. However, this does not normally happen, 12917 which is why the behaviour was moved to an option for those that 12918 needed it. 12919 12920 13. Why does mpatrol not report an illegal memory access when it can 12921 be detected by a debugger? 12922 12923 First of all, illegal memory accesses can only be detected on 12924 systems that support virtual memory, so that precludes AmigaOS and 12925 Netware. Secondly, it might be possible that something is 12926 overriding the illegal memory access handler that mpatrol sets up 12927 when it is first initialised. If your program, or an external 12928 library, sets up a signal handler that handles `SIGBUS' or 12929 `SIGSEGV' (or their equivalent on Windows platforms) then mpatrol 12930 will no longer be able to catch illegal memory accesses. You can 12931 either try to live with that, or you could try disabling the 12932 overriding handlers. 12933 12934 14. How do I set a breakpoint on the `malloc()' function when it is 12935 implemented as a preprocessor macro in `mpatrol.h'? 12936 12937 There are four different mpatrol interface functions which are 12938 used to allocate memory, duplicate strings, reallocate memory and 12939 deallocate memory. If you look in `mpatrol.h' you should be able 12940 to see the name of the function that will be called when the macro 12941 is invoked. The same goes for the memory operation functions. 12942 12943 15. I've linked and run my program with mpatrol under UNIX and it uses 12944 a large amount of heap memory. However, it crashes near the end 12945 of execution and then proceeds to freeze up the whole system, 12946 sometimes requiring a reboot. What am I doing wrong? 12947 12948 The most common possible explanation for this is that you are 12949 running your program with too much access to system resources. 12950 What is likely to be happening is that when your program crashes 12951 the system attempts to dump the entire process image to a core 12952 file for later debugging in a non-symbolic debugger. If the 12953 process has a huge heap then the core file is also going to be 12954 huge, thus resulting in a massive file that may lead to the system 12955 thrashing while it attempts to write it to the disk. Technically, 12956 the system has not frozen, but it is likely to take a long time to 12957 finish writing the file. The best solution involves setting your 12958 program's maximum core file size to a reasonable limit (or just 12959 zero), and also possibly limiting your program's maximum data 12960 segment size as well. These can be set from the shell but the 12961 exact details on how to do this differ between shells. 12962 12963 16. Why does my program run so slowly after I link it with the mpatrol 12964 library? 12965 12966 Normal malloc libraries are optimised for speed but will typically 12967 fall over at the slightest hint of an error. Debugging malloc 12968 libraries are written to provide as much debugging information as 12969 possible whilst performing a multitude of additional checks, which 12970 is why they may run much slower. However, you can control which 12971 checks are performed (and when) by using the `MPATROL_OPTIONS' 12972 environment variable. Performance may also be lost if you make 12973 lots of small memory allocations rather than fewer larger 12974 allocations, but that is mainly due to the overhead of storing the 12975 extra tracing details for each memory allocation. 12976 12977 17. My program is written in C++ and is linked to the mpatrol library, 12978 but how do I go about demangling the C++ symbol names that are 12979 shown in the stack tracebacks in the resulting log file? 12980 12981 Because there is no standard way of mangling C++ symbol names, 12982 various compilers and operating systems have taken different 12983 approaches to C++ name mangling, many of which differ 12984 significantly from the method suggested in _The Annotated C++ 12985 Reference Manual_ by Margaret Ellis and Bjarne Stroustrup. 12986 However, most compilers come with a demangling tool which can be 12987 used in a command pipe to accept mangled names on its standard 12988 input file stream and demangle them on its standard output file 12989 stream, and so can be used to process the mpatrol log file. Note 12990 that mpatrol automatically demangles C++ symbol names on Windows 12991 platforms as Microsoft's name mangling is quite unreadable and 12992 would be hard to demangle using a command line tool. 12993 12994 18. Why does my program not stop when the mpatrol library notices an 12995 error? 12996 12997 The library was written to give as much information as possible 12998 and so sometimes, when a non-fatal error is discovered, the 12999 library will write the error message to the log file and continue 13000 in the hope of being able to uncover more errors during the 13001 execution of the program. This means that you should always check 13002 the number of warnings and errors given in the summary at the end 13003 of program execution, and then search backwards in the log file for 13004 `WARNING' or `ERROR'. 13005 13006 19. I have linked my program with the mpatrol library on an Amiga or 13007 Netware machine, but when it runs it still crashes the entire 13008 system. Why is this? 13009 13010 AmigaOS and Netware do not have virtual memory and so do not have 13011 memory protection turned on by default. This means that any rogue 13012 write to an erroneous address may actually overwrite the data of 13013 another process or perhaps even the operating system, thus 13014 bringing the entire machine down. There are several third-party 13015 system utilities available for the Amiga to add memory protection 13016 to machines with built-in MMUs, which can then be used in 13017 conjunction with mpatrol. I'm not sure about the availability of 13018 such software for Netware. 13019 13020 20. I have built the mpatrol library with `gcc' on AmigaOS and have 13021 successfully linked it to my program. However, why are none of 13022 the options in the `MPATROL_OPTIONS' environment variable 13023 recognised when I run it? 13024 13025 The `getenv()' function in the GNU C library is not compatible 13026 with the AmigaDOS `SetEnv' and `GetEnv' commands since it does not 13027 treat environment variables as files located in `ENV:' and is only 13028 compatible with software that uses the ixemul library. However, 13029 the `env' command that comes with most GNU software distributions 13030 allows you to set an environment variable that the GNU `getenv()' 13031 function can read when you are running in AmigaDOS. 13032 13033 21. How do I suppress all diagnostic output from the mpatrol library? 13034 13035 You can do this by setting the mpatrol log file to be your 13036 system's _bit bucket_, which is `/dev/null' on UNIX platforms and 13037 `NIL:' on AmigaOS. There doesn't appear to be an equivalent way 13038 to do this on Windows or Netware. 13039 13040 13041File: mpatrol.info, Node: Files, Prev: Running, Up: Frequently asked questions 13042 13043Files 13044===== 13045 13046 1. Why is there a `libmpatrol.o' target in the UNIX and Amiga 13047 `Makefile's? 13048 13049 This is simply used to build the mpatrol library as one large 13050 object file for full incorporation into other libraries and was 13051 used during the development of mpatrol. On UNIX platforms some 13052 linkers support the `-r' option for combining many object files 13053 into one large object file, but this is not universally supported, 13054 hence the reason for using the compiler instead. Because all of 13055 the source files are compiled at once, there may be conflicts with 13056 system header files when `malloc()' and its related functions are 13057 being compiled, which is why such an object file is not built by 13058 default. In addition, platforms which require the assembler 13059 routines in `machine.c' cannot build the mpatrol library as one 13060 large object file from `library.c'. Note that the Windows and 13061 Netware `Makefile's use `libmpatrol.obj'. 13062 13063 2. What are the `CVS' subdirectories that come with the mpatrol 13064 distribution? 13065 13066 CVS stands for Concurrent Versions System and is a project version 13067 control system. All of the source files that comprise an mpatrol 13068 release are stored in a central CVS repository so that previous 13069 releases can be easily retrieved, but the CVS system needs to have 13070 a way of determining the versions of currently checked-out files, 13071 hence the `CVS' subdirectories. The `.cvsignore' files within 13072 these directories simply inform CVS about which files to ignore 13073 when looking for changes. You shouldn't need to worry about them, 13074 so just ignore them, and in later releases they should have been 13075 removed before a distribution was made. 13076 13077 3. Why does the `mpsym' command not work for me? 13078 13079 Firstly, you have to ensure that you have compiled all relevant 13080 object files with debugging information enabled (usually by adding 13081 an option to the compiler command line). The file and line number 13082 information will hopefully then appear in the log file for all 13083 symbols that have associated debugging information when you run 13084 the `mpsym' command on the log file. Alternatively, it could be 13085 that your system does not have `gdb' or any of the required UNIX 13086 text processing tools installed, in which case you might want to 13087 try installing them. 13088 13089 4. How can I customise the `mpedit' command if I do not have the 13090 appropriate permissions to edit the file that was installed on my 13091 system? 13092 13093 You just need to take a copy of the installed `mpedit' command and 13094 place it somewhere that will be picked up earlier on your command 13095 search path. You can then edit your copy of the file and add 13096 support for your favourite text editor. 13097 13098 5. What does the `mupdate' shell script do? 13099 13100 This is for my use in order to automate every new release of 13101 mpatrol. You should never need to run this script and it should 13102 not be installed anywhere on your system. This script also uses 13103 and modifies the `VERSION' file and updates the `NEWS' and 13104 `ChangeLog' files. 13105 13106 13107File: mpatrol.info, Node: Related software, Next: References, Prev: Frequently asked questions, Up: Top 13108 13109Related software 13110**************** 13111 13112 The mpatrol library was designed to solve most common heap-related 13113problems, but there may be some cases where a different approach is 13114needed, or a commercial package is required. I have attempted to 13115provide an overview of the different types of malloc libraries and 13116memory debuggers available below, along with a comprehensive list of 13117related software. 13118 13119 The most basic type of heap debugging system simply requires the 13120redefinition of `malloc()', `realloc()' and `free()' (and related 13121functions) with debugging versions that record the file and line number 13122at which allocations occur. This might require modifications to the 13123source code in order to call these new functions or it can be done 13124through preprocessor macros which will require all source files using 13125the memory allocation functions to be recompiled. Such a system will 13126most likely live on top of the existing system malloc library, but will 13127provide an additional layer with which to store more information for 13128debugging purposes. MEM by Walter Bright is a good example of this 13129type of library. 13130 13131 On many operating systems it is usually possible to write 13132replacements for the normal memory allocation routines and place them 13133in a library so that they can be linked in to override the system 13134malloc library without requiring recompilation of any source files. 13135Such malloc libraries must take control of the heap directly and so 13136usually contain more features, including being able to track memory 13137leaks and place fence posts around allocations. Dbmalloc by Conor P. 13138Cahill and Dmalloc by Gray Watson are two of the most popular of these 13139types of libraries since they are available on a wide range of 13140platforms. Electric Fence by Bruce Perens also makes use of the memory 13141protection facilities found in UNIX systems in order to force programs 13142that access free or freed memory or read or write beyond the bounds of 13143a memory allocation to crash at the point that the illegal memory 13144access is made, rather than crashing at the next memory allocation. 13145 13146 For debugging all memory access errors (not just those on the heap) 13147it is necessary to modify (instrument) the machine code that is to be 13148run so that each individual load from memory and store to memory will 13149be checked. One method of doing this is to modify the code produced by 13150a compiler (such as is done by Checker written by Tristan Gingold) but 13151this has the disadvantage of only working within the object files that 13152have been produced by that compiler. It is also possible to modify the 13153source code itself using source to source translation (such as is done 13154by Parasoft Insure++) or instrument all accesses to memory in assembler 13155source files (as performed by APurify written by Samuel Devulder). 13156However, both of these methods suffer from the same drawback as 13157compiler-generated instrumentation. Yet another alternative is to wait 13158until link-time and then instrument the individual object files and 13159libraries before they are linked into an executable file. This is 13160effectively what Purify from Rational Software does, although Memory 13161Advisor from PLATINUM Technology does roughly the same except that it 13162disassembles the object files into a platform-independent format before 13163instrumenting them. 13164 13165 Rather than modifying a program in order to add debugging code, it 13166is sometimes possible to use a dedicated memory debugger in order to 13167quickly catch any problems. ZeroFault from The Kernel Group debugs all 13168memory-related operations in a program while it is running, whilst 13169AProbe from OC Systems allows users to dynamically add probe modules at 13170run-time in order to locate errors or perform profiling. If such a 13171memory debugger is not available for your system, you may still be able 13172to dynamically link a malloc library into your application at run-time 13173if the operating system supports it. NJAMD by Mike Perry makes 13174extensive use of this feature on some UNIX systems. On operating 13175systems that do not support virtual memory but have hardware memory 13176protection, it is sometimes possible to trap memory errors before they 13177bring down the whole system. On the Amiga, Enforcer by Michael Sinz 13178runs in the background and detects many common memory access errors in 13179running applications, whilst on the Macintosh, QC by Onyx Technology 13180provides roughly the same functionality. 13181 13182 A list of over ninety different items of software which help in 13183debugging dynamic memory allocation problems is given below(1). They 13184all provide some of the features that mpatrol contains and you may wish 13185to use one of them to solve your problem if you have trouble using 13186mpatrol. I have only ever used CSRI malloc, Dbmalloc, Dmalloc, 13187Electric Fence and Mprof, so I can't vouch for any of the others, 13188although if you have any recommendations feel free to let me know so I 13189can add them to this list. In particular, there seems to be a shortage 13190of such programs for Netware platforms. Note that there is a 13191comparison of a few of the following programs at 13192`http://www.consistent.org/terran/memorycheck.shtml' which might help 13193illustrate the differences between the various tools. 13194 13195 * AProbe 13196 Author 13197 OC Systems (<info@ocsystems.com>) 13198 13199 License 13200 Commercial Software 13201 13202 Platforms 13203 Various UNIX, Windows 13204 13205 Location 13206 `http://www.aprobe.com/' 13207 13208 Overview 13209 Instruments a program using Dynamic Action Linking in order 13210 to track down memory corruption and monitor memory usage, 13211 among other things. 13212 13213 * APurify 13214 Author 13215 Samuel Devulder (<Samuel.Devulder@info.unicaen.fr>) 13216 13217 License 13218 Free Software 13219 13220 Platforms 13221 AmigaOS 13222 13223 Location 13224 `http://wuarchive.wustl.edu/~aminet/dirs/dev_debug.html' 13225 13226 Overview 13227 Instruments an assembler source file to insert code that 13228 checks all memory accesses. 13229 13230 * BoundsChecker 13231 Author 13232 NuMega Corporation (<info@numega.com>) 13233 13234 License 13235 Commercial Software 13236 13237 Platforms 13238 Windows, MS-DOS 13239 13240 Location 13241 `http://www.numega.com/' 13242 13243 Overview 13244 Detects and diagnoses errors in static, stack and heap memory 13245 and in memory and resource leaks. 13246 13247 * C++ Debugging Support Library (libcwd) 13248 Author 13249 Carlo Wood <carlo@alinoe.com> 13250 13251 License 13252 Q Public License 13253 13254 Platforms 13255 Various UNIX 13256 13257 Location 13258 `http://sourceforge.net/projects/libcw/' 13259 13260 Overview 13261 A C++ debugging library that can also detect memory 13262 corruption and memory leaks. 13263 13264 * Ccmalloc 13265 Author 13266 Armin Biere (<biere@inf.ethz.ch>) 13267 13268 License 13269 GNU General Public License 13270 13271 Platforms 13272 Various UNIX 13273 13274 Location 13275 `http://www.inf.ethz.ch/personal/biere/projects/ccmalloc/' 13276 13277 Overview 13278 Can interface with `gdb' to find memory leaks, multiple 13279 deallocations and memory corruptions in C or C++ programs. 13280 13281 * Chaperon 13282 Author 13283 John Reiser (<jreiser@BitWagon.com>) 13284 13285 License 13286 Commercial Software 13287 13288 Platforms 13289 Linux 13290 13291 Location 13292 `http://www.bitwagon.com/chaperon.html' 13293 13294 Overview 13295 Runs existing Intel Linux binary application programs, but 13296 checks for and reports bad behaviour in accessing memory. 13297 13298 * Checker 13299 Author 13300 Tristan Gingold (<bug-checker@gnu.org>) 13301 13302 License 13303 GNU General Public License 13304 13305 Platforms 13306 Various UNIX 13307 13308 Location 13309 `http://www.gnu.org/software/checker/checker.html' 13310 13311 Overview 13312 Detects illegal memory accesses when reading from 13313 uninitialised memory, writing to freed memory or outside 13314 memory blocks. Also contains a garbage collector for 13315 detecting memory leaks. 13316 13317 * CMEM 13318 Author 13319 Brett Hunsaker (<hunsaker@eisner.decus.org>) 13320 13321 License 13322 Free Software 13323 13324 Platforms 13325 VMS 13326 13327 Location 13328 `http://www.openvms.compaq.com/freeware/CMEM/' 13329 13330 Overview 13331 Provides debugging versions of the C run-time library memory 13332 allocation routines, with support for stack tracebacks and 13333 page protection. 13334 13335 * CMM (Customisable Memory Manager) 13336 Author 13337 Giuseppe Attardi (<attardi@di.unipi.it>), Tito Flagella 13338 (<tito@di.unipi.it>) and Pietro Iglio (<iglio@di.unipi.it>) 13339 13340 License 13341 Free Software 13342 13343 Platforms 13344 Various UNIX, Windows, MacOS, DOS 13345 13346 Location 13347 `ftp://ftp.di.unipi.ti/pub/project/posso/cmm/' 13348 13349 Overview 13350 A memory management facility supporting memory intensive 13351 applications in C++, with support for multiple heaps (each 13352 one optionally implementing a different storage discipline) 13353 and garbage collection. 13354 13355 * CSRI malloc 13356 Author 13357 Mark Moraes (<moraes@deshaw.com>) 13358 13359 License 13360 Free Software 13361 13362 Platforms 13363 Various UNIX 13364 13365 Location 13366 `ftp://ftp.cs.toronto.edu/pub/moraes/malloc.tar.gz' 13367 13368 Overview 13369 A library of dynamic memory allocation functions with limited 13370 debugging and profiling support and detection of memory 13371 leaks. Also comes with a graphical tool to display a dynamic 13372 picture of the heap. 13373 13374 * Dbmalloc 13375 Author 13376 Conor P. Cahill (<cpcahil@virtech.vti.com>) 13377 13378 License 13379 Free Software 13380 13381 Platforms 13382 Various UNIX 13383 13384 Location 13385 `http://dickey.his.com/dbmalloc/dbmalloc.html' 13386 13387 Overview 13388 Provides replacements for memory management library functions 13389 and provides a full set of debugging features which detect 13390 memory overruns and other types of misuse. 13391 13392 * Dbmalloc 13393 Author 13394 Michael McTernan (<mm7323@bris.ac.uk>) 13395 13396 License 13397 Free Software 13398 13399 Platforms 13400 Various UNIX, Windows 13401 13402 Location 13403 `http://www.cs.bris.ac.uk/~mm7323/DbMalloc/' 13404 13405 Overview 13406 A drop-in replacement for the C memory allocation functions, 13407 providing facilities for quickly finding memory leaks. 13408 13409 * Debauch 13410 Author 13411 Jon A. Christopher (<jac8792@tamu.edu>) 13412 13413 License 13414 GNU General Public License 13415 13416 Platforms 13417 Linux 13418 13419 Location 13420 `http://mackerel.tamu.edu/jon/gnu/' 13421 13422 Overview 13423 A memory allocation debugger for C which will detect memory 13424 leaks, corrupted memory, stores to freed memory and more. 13425 13426 * Debug Heap 13427 Author 13428 IBM Corporation (<info@ibm.com>) 13429 13430 License 13431 Commercial Software 13432 13433 Platforms 13434 IBM AS/400 13435 13436 Location 13437 `http://www.as400.ibm.com/developer/porting/heapexternal.html' 13438 13439 Overview 13440 A heap debugging environment with stack traceback for IBM 13441 AS/400 servers. 13442 13443 * DebugObject 13444 Author 13445 Beniamin Cherniavsky (<cben@israel.crosswinds.net>) 13446 13447 License 13448 GNU General Public License 13449 13450 Platforms 13451 Various UNIX, Windows 13452 13453 Location 13454 `http://www.crosswinds.net/~cben/objc/' 13455 13456 Overview 13457 A set of classes for debugging dynamic memory problems in 13458 Objective C. 13459 13460 * Dmalloc 13461 Author 13462 Gray Watson (<gray@burger.letters.com>) 13463 13464 License 13465 Free Software 13466 13467 Platforms 13468 Various UNIX, Windows, MS-DOS 13469 13470 Location 13471 `http://www.dmalloc.com/' 13472 13473 Overview 13474 A drop-in replacement for the system's memory management 13475 routines, providing powerful debugging facilities 13476 configurable at run-time. Formerly known as Malloc_Dbg. 13477 13478 * DPCRTLMM 13479 Author 13480 David Duncan Ross Palmer (<overlord@daybologic.co.uk>) 13481 13482 License 13483 GNU General Public License 13484 13485 Platforms 13486 Various UNIX, Windows, MS-DOS 13487 13488 Location 13489 `http://www.daybologic.co.uk/dev/dpcrtlmm/' 13490 13491 Overview 13492 Detects failures to release memory and attempts to release 13493 memory which has not been allocated, and can also provide 13494 statistics and logging facilities. 13495 13496 * Electric Fence 13497 Author 13498 Bruce Perens (<bruce@pixar.com>) 13499 13500 License 13501 GNU General Public License 13502 13503 Platforms 13504 Various UNIX 13505 13506 Location 13507 `ftp://ftp.perens.com/pub/ElectricFence/' 13508 13509 Overview 13510 Uses virtual memory hardware to protect dynamically allocated 13511 memory in order to detect illegal memory accesses. 13512 13513 * Enforcer 13514 Author 13515 Michael Sinz (<Enforcer@sinz.org>) 13516 13517 License 13518 Free Software 13519 13520 Platforms 13521 AmigaOS 13522 13523 Location 13524 `http://www.iam.com/amiga/enforcer.html' 13525 13526 Overview 13527 Sets up MMU tables to watch for illegal accesses to memory, 13528 such as the low page and non-existent pages. 13529 13530 * FDA (Free Debug Allocator) 13531 Author 13532 Thomas Helvey (<tomh@inxpress.net>) 13533 13534 License 13535 GNU General Public License 13536 13537 Platforms 13538 Linux, Windows 13539 13540 Location 13541 `http://www.debian.org/Packages/unstable/devel/fda.html' 13542 13543 Overview 13544 Provides routines that can be plugged in to replace 13545 `malloc()', `calloc()', `realloc()' and `free()'. 13546 13547 * Fortify 13548 Author 13549 Simon Bullen (<sbullen@cybergraphic.com.au>) 13550 13551 License 13552 Free Software 13553 13554 Platforms 13555 AmigaOS 13556 13557 Location 13558 `http://www.geocities.com/SiliconValley/Horizon/8596/fortify.html' 13559 13560 Overview 13561 Provides a fortified shell for memory allocations, trapping 13562 memory leaks, writes beyond and before memory blocks and 13563 writes to freed memory. 13564 13565 * Gabe's Debug Library 13566 Author 13567 Gabriel Sechan <gsechan@hotmail.com> 13568 13569 License 13570 Free Software 13571 13572 Platforms 13573 Windows 13574 13575 Location 13576 `http://sourceforge.net/projects/debuglib/' 13577 13578 Overview 13579 A debugging library for C++ which performs dynamic memory 13580 management and looks for potential problems and memory leaks. 13581 13582 * GC (Garbage Collector) 13583 Author 13584 Hans-J. Boehm (<boehm@acm.org>) 13585 13586 License 13587 Free Software 13588 13589 Platforms 13590 Various UNIX, AmigaOS, Windows, MS-DOS, MacOS 13591 13592 Location 13593 `http://www.hpl.hp.com/personal/Hans_Boehm/gc/' 13594 13595 Overview 13596 A general-purpose, garbage-collecting storage allocator that 13597 is intended to be used as a plug-in replacement for 13598 `malloc()', but can also be used to detect memory leaks. 13599 13600 * GCAlloc 13601 Author 13602 Joel Bartlett (<bartlett@decwrl.dec.com>) 13603 13604 License 13605 Free Software 13606 13607 Platforms 13608 Various UNIX 13609 13610 Location 13611 `ftp://gatekeeper.dec.com/pub/DEC/CCgc/' 13612 13613 Overview 13614 A highly-portable generational, mostly-copying garbage 13615 collector for C++. 13616 13617 * GlowCode 13618 Author 13619 Electric Software, Inc. (<info@glowcode.com>) 13620 13621 License 13622 Commercial Software 13623 13624 Platforms 13625 Windows 13626 13627 Location 13628 `http://www.glowcode.com/' 13629 13630 Overview 13631 Provides a profiler, call coverage tool and resource browser 13632 which can detail memory leaks. 13633 13634 * GMemLogger 13635 Author 13636 Yves Mettier (<ymettier@libertysurf.fr>) 13637 13638 License 13639 GNU General Public License 13640 13641 Platforms 13642 Linux 13643 13644 Location 13645 `http://sourceforge.net/projects/gmemlogger/' 13646 13647 Overview 13648 Logs allocated memory for the purpose of detecting memory 13649 leaks. 13650 13651 * Great Circle 13652 Author 13653 Geodesic Systems (<info@geodesic.com>) 13654 13655 License 13656 Commercial Software 13657 13658 Platforms 13659 Various UNIX, Windows 13660 13661 Location 13662 `http://www.geodesic.com/' 13663 13664 Overview 13665 Provides complete heap profiling, allowing programmers to see 13666 what parts of a program are using the most memory with 13667 symbolic stack tracing. 13668 13669 * HeapAgent 13670 Author 13671 MicroQuill (<info@microquill.com>) 13672 13673 License 13674 Commercial Software 13675 13676 Platforms 13677 Windows 13678 13679 Location 13680 `http://www.microquill.com/' 13681 13682 Overview 13683 Instruments the heap to provide heap error detection without 13684 the need to recompile any source code. 13685 13686 * HeapCheck 13687 Author 13688 Thanassis Tsiodras (<ttsiod@softlab.ntua.gr>) 13689 13690 License 13691 GNU General Public License 13692 13693 Platforms 13694 Windows 13695 13696 Location 13697 `http://www.image.ece.ntua.gr/~ttsiod/HeapCheck.html' 13698 13699 Overview 13700 A debugging memory allocator that can detect invalid 13701 read/write accesses to heap memory, and also detects memory 13702 leaks. 13703 13704 * HeapManager 13705 Author 13706 Andrew Wulf (<heapmanager@biit.com>) 13707 13708 License 13709 Free Software 13710 13711 Platforms 13712 MacOS 13713 13714 Location 13715 `http://www.biit.com/' 13716 13717 Overview 13718 Provides a general-purpose dynamic memory allocation 13719 debugging package with symbolic stack traceback. 13720 13721 * IDH 13722 Author 13723 Ivan Skytte Jorgensen (<isj@image.dk>) 13724 13725 License 13726 Free Software 13727 13728 Platforms 13729 Various UNIX 13730 13731 Location 13732 `http://www.platypus.adsl.dk/idh/index.html/' 13733 13734 Overview 13735 Detects most overwrites, stale pointers, wild pointers, 13736 double-free and invalid mix of heap management functions. 13737 13738 * Insure++ 13739 Author 13740 ParaSoft (<info@parasoft.com>) 13741 13742 License 13743 Commercial Software 13744 13745 Platforms 13746 Various UNIX, Windows 13747 13748 Location 13749 `http://www.parasoft.com/' 13750 13751 Overview 13752 Uses Source Code Instrumentation and Runtime Pointer Tracking 13753 technologies to pinpoint memory corruption, memory leaks, 13754 operations on unrelated pointers and more. The Inuse 13755 graphical memory usage display tool is also provided with this 13756 software. 13757 13758 * JMalloc 13759 Author 13760 Jeff Dunlop 13761 13762 License 13763 Free Software 13764 13765 Platforms 13766 Windows, MS-DOS 13767 13768 Location 13769 `http://www.snippets.org/' 13770 13771 Overview 13772 Provides tracing and debugging for `malloc()' and `operator 13773 new'. 13774 13775 * JProbe 13776 Author 13777 KL Group (<info@klgroup.com>) 13778 13779 License 13780 Commercial Software 13781 13782 Platforms 13783 Various UNIX, Windows 13784 13785 Location 13786 `http://www.klgroup.com/' 13787 13788 Overview 13789 Helps pinpoint memory leaks in Java applications by tracking 13790 which objects hold references to other objects, and allows 13791 visualisation of memory usage in real-time. 13792 13793 * Leak 13794 Author 13795 Christopher Phillips (<pefv700@hermes.chpc.utexas.edu>) 13796 13797 License 13798 Free Software 13799 13800 Platforms 13801 Various UNIX 13802 13803 Location 13804 `http://sources.isc.org/devel/memleak/leak.txt' 13805 13806 Overview 13807 Logs all calls to `malloc()' and related functions to 13808 database files with the filename and line number, then 13809 attempts to validate reallocations and deallocations and 13810 detect memory leaks. 13811 13812 * Leak 13813 Author 13814 Josh McCormick (<jmccorm@galstar.com>) 13815 13816 License 13817 Free Software 13818 13819 Platforms 13820 Various UNIX 13821 13822 Location 13823 `http://www.galstar.com/~jmccorm/leak/' 13824 13825 Overview 13826 A simple shell script that monitors the system looking for 13827 processes which leak memory. 13828 13829 * LeakBug 13830 Author 13831 Christian Hammond (<chipx86@portaldesign.net>), Domenico 13832 Andreoli (<cavok@filibusta.crema.unimi.it>) and Gerry Jo 13833 Jellestad (<gerry@c64.org>) 13834 13835 License 13836 GNU General Public License 13837 13838 Platforms 13839 Various UNIX 13840 13841 Location 13842 `http://www.gnupdate.org/' 13843 13844 Overview 13845 A memory leak tracer that specializes in detecting leaks from 13846 a program's own calls to `malloc()', `strdup()', etc, but 13847 does not detect leaks from outside libraries. 13848 13849 * Leakers 13850 Author 13851 Gabriel M. Deal (<gmd@yellowleaf.org>) 13852 13853 License 13854 GNU General Public License 13855 13856 Platforms 13857 Various UNIX 13858 13859 Location 13860 `http://www.yellowleaf.org/gmd/software/leakers/' 13861 13862 Overview 13863 Detects memory allocation errors by writing a log file and 13864 then examining it for memory leaks and attempts to free 13865 memory multiple times. 13866 13867 * LeakTracer 13868 Author 13869 Erwin Andreasen (<erwin@andreasen.org>) 13870 13871 License 13872 Free Software 13873 13874 Platforms 13875 Various UNIX 13876 13877 Location 13878 `http://www.andreasen.org/LeakTracer/' 13879 13880 Overview 13881 Detects memory leaks in C++ programs by overriding `operator 13882 new' and `operator delete'. 13883 13884 * Leaky 13885 Author 13886 Kipp Hickman (<kipp@netscape.com>) 13887 13888 License 13889 Netscape Public License 13890 13891 Platforms 13892 Linux 13893 13894 Location 13895 `http://www.mozilla.org/unix/leaky.html' 13896 13897 Overview 13898 A program which helps find memory leaks and helps debug 13899 reference count problems with xpcom objects. 13900 13901 * LibKmalloc 13902 Author 13903 Akira Higuchi (<a@kondara.org>) 13904 13905 License 13906 GNU General Public License 13907 13908 Platforms 13909 Linux 13910 13911 Location 13912 `http://www.kondara.org/~a/libkmalloc.html' 13913 13914 Overview 13915 A tiny malloc debugger which detects multiple frees and 13916 buffer overruns and underruns. 13917 13918 * LibSafe 13919 Author 13920 AT&T Bell Labs (<libsafe@research.bell-labs.com>) 13921 13922 License 13923 GNU General Public License 13924 13925 Platforms 13926 Linux 13927 13928 Location 13929 `http://www.bell-labs.com/org/11356/libsafe.html' 13930 13931 Overview 13932 Protects a process against the exploitation of buffer 13933 overflow vulnerabilities in process stacks. 13934 13935 * Malloc Debug 13936 Author 13937 Brandon S. Allbery <allbery@ncoast.org> 13938 13939 License 13940 Free Software 13941 13942 Platforms 13943 Various UNIX 13944 13945 Location 13946 `http://www.leo.org/pub/comp/usenet/comp.sources.misc/malloc-debug/' 13947 13948 Overview 13949 A debugging malloc package with stack traceback capability. 13950 13951 * Malloc Debug Library 13952 Author 13953 Rammi (<rammi@quincunx.escape.de>) 13954 13955 License 13956 Free Software 13957 13958 Platforms 13959 Various UNIX 13960 13961 Location 13962 `http://www.escape.de/users/quincunx/rmdebug.html' 13963 13964 Overview 13965 Implements wrappers for the normal heap handling functions. 13966 13967 * MallocTrace 13968 Author 13969 Mark Brader (<msb@sq.sq.com>) 13970 13971 License 13972 Free Software 13973 13974 Platforms 13975 Various UNIX 13976 13977 Location 13978 `ftp://ftp.uu.net/usenet/comp.sources.unix/volume18/malloc-trace.Z' 13979 13980 Overview 13981 A malloc package with call stack tracebacks. 13982 13983 * MalTrace 13984 Author 13985 Michael Schwartz (<schwartz@cs.washington.edu>) 13986 13987 License 13988 Free Software 13989 13990 Platforms 13991 Various UNIX 13992 13993 Location 13994 `http://www.mit.edu/afs/sipb/user/tytso/News/maltrace' 13995 13996 Overview 13997 Traces all calls to `malloc()' and `free()' in order to 13998 detect memory leaks. 13999 14000 * Mark_Malloc 14001 Author 14002 Sed (<sed@free.fr>) 14003 14004 License 14005 Free Software 14006 14007 Platforms 14008 Various UNIX 14009 14010 Location 14011 `http://sed.free.fr/mark_malloc' 14012 14013 Overview 14014 Marks memory allocations in order to detect memory leaks. 14015 14016 * MCheck 14017 Author 14018 Ronald Veldema (<rveldema@cs.vu.nl>) 14019 14020 License 14021 GNU General Public License 14022 14023 Platforms 14024 Linux 14025 14026 Location 14027 `http://www.cs.vu.nl/~rveldema/mcheck/mcheck.html' 14028 14029 Overview 14030 A memory usage and malloc checker for C and C++. Comes with 14031 a Java application for browsing the trace files produced. 14032 14033 * MEM 14034 Author 14035 Walter Bright 14036 14037 License 14038 Free Software 14039 14040 Platforms 14041 MS-DOS 14042 14043 Location 14044 `http://www.snippets.org/' 14045 14046 Overview 14047 A set of functions for debugging pointer and memory 14048 allocation problems. 14049 14050 * MemCheck 14051 Author 14052 Stratosware Corporation (<info@stratosware.com>) 14053 14054 License 14055 Commercial Software 14056 14057 Platforms 14058 Windows 14059 14060 Location 14061 `http://www.stratosware.com/' 14062 14063 Overview 14064 Detects various run-time errors related to operating system 14065 resources and provides information on memory leaks. 14066 14067 * MemCheck 14068 Author 14069 IBM Corporation (<info@ibm.com>) 14070 14071 License 14072 Commercial Software 14073 14074 Platforms 14075 IBM OS/390 14076 14077 Location 14078 `http://www.s390.ibm.com/oe/tools/memcheck_2_1.html' 14079 14080 Overview 14081 Aids the discovery of memory leaks in single- and 14082 multi-threaded C/C++ programs. 14083 14084 * MemDebug 14085 Author 14086 Rene Schmit (<rene.schmit@bss.lu>) 14087 14088 License 14089 Free Software 14090 14091 Platforms 14092 Various UNIX, Windows, MS-DOS, MacOS 14093 14094 Location 14095 `http://www.bss.lu/Memdebug/Memdebug.html' 14096 14097 Overview 14098 Provides memory management error detection, memory usage 14099 error detection, memory usage profiling and error simulation. 14100 14101 * MemLeak 14102 Author 14103 Keith Packard (<keithp@ncd.com>) 14104 14105 License 14106 Free Software 14107 14108 Platforms 14109 Various UNIX 14110 14111 Location 14112 `ftp://ftp.x.org/pub/R6.4/xc/util/memleak/' 14113 14114 Overview 14115 Replaces the C library allocation functions and provides 14116 extensive memory checking, locating lost memory, detecting 14117 free memory still in use and stores to free memory along with 14118 stack tracebacks. 14119 14120 * Memory Advisor 14121 Author 14122 PLATINUM Technology (<info@platinum.com>) 14123 14124 License 14125 Commercial Software 14126 14127 Platforms 14128 Various UNIX 14129 14130 Location 14131 `http://www.platinum.com/' 14132 14133 Overview 14134 Disassembles an object module into system-independent 14135 assembler code, inserts error checking instructions, then 14136 re-assembles the code. Can also replace existing malloc 14137 libraries in order to provide greater error checking. 14138 Formerly known as Sentinel. 14139 14140 * Memory Sleuth 14141 Author 14142 TurboPower (<info@turbopower.com>) 14143 14144 License 14145 Commercial Software 14146 14147 Platforms 14148 Windows 14149 14150 Location 14151 `http://www.turbopower.com/' 14152 14153 Overview 14154 Quickly tracks down memory leaks and resource allocation 14155 errors with C++Builder and Delphi. 14156 14157 * Memprof 14158 Author 14159 Owen Taylor (<otaylor@redhat.com>) 14160 14161 License 14162 GNU General Public License 14163 14164 Platforms 14165 Linux 14166 14167 Location 14168 `http://people.redhat.com/otaylor/memprof/' 14169 14170 Overview 14171 A tool for profiling memory usage and detecting memory leaks. 14172 14173 * Memproof 14174 Author 14175 AutomatedQA (<info@totalqa.com>) 14176 14177 License 14178 Free Software 14179 14180 Platforms 14181 Windows 14182 14183 Location 14184 `http://www.totalqa.com/' 14185 14186 Overview 14187 A memory and resource leak debugger for Borland's family of 14188 Windows compilers. 14189 14190 * MemTest 14191 Author 14192 Jim Buchanan (<jbuchana@iquest.net>) 14193 14194 License 14195 Free Software 14196 14197 Platforms 14198 Various UNIX 14199 14200 Location 14201 `ftp://ftp.loxinfo.co.th/pub/unix/utils/mem_test-0_10_tar.gz' 14202 14203 Overview 14204 Helps locate memory leaks in a program under development by 14205 creating a log file that records most memory allocations and 14206 deallocations. 14207 14208 * MemTrace 14209 Author 14210 Nico Hoogervorst (<nico@knoware.nl>) 14211 14212 License 14213 Free Software 14214 14215 Platforms 14216 Windows 14217 14218 Location 14219 `http://utopia.knoware.nl/users/nico/tools/c/memtrace/' 14220 14221 Overview 14222 A simple enhancement for C source code which makes it easier 14223 to find memory leaks. 14224 14225 * MemTrace 14226 Author 14227 Frank Pilhofer (<fp@informatik.uni-frankfurt.de>) 14228 14229 License 14230 Free Software 14231 14232 Platforms 14233 Various UNIX 14234 14235 Location 14236 `http://www.informatik.uni-frankfurt.de/~fp/Tools/MemTrace/' 14237 14238 Overview 14239 Searches for memory leaks in a program and uses various 14240 platform-specific features to record a stack trace each time 14241 a memory chunk is allocated. 14242 14243 * MemWatch 14244 Author 14245 Johan Lindh (<johan@link-data.com>) 14246 14247 License 14248 Free Software 14249 14250 Platforms 14251 Various UNIX, Windows 14252 14253 Location 14254 `http://www.link-data.com/' 14255 14256 Overview 14257 A fault-tolerant memory leak and corruption detection tool. 14258 14259 * MemWatch 14260 Author 14261 Doug Walker (<walker@unx.sas.com>) 14262 14263 License 14264 Free Software 14265 14266 Platforms 14267 AmigaOS 14268 14269 Location 14270 `http://wuarchive.wustl.edu/~aminet/dirs/dev_debug.html' 14271 14272 Overview 14273 Provides replacement memory allocation routines for adding 14274 lots of memory debugging features that you link into your 14275 program. 14276 14277 * MemWatch 14278 Author 14279 Sundial Services (<info@sundialservices.com>) 14280 14281 License 14282 Free Software 14283 14284 Platforms 14285 Windows 14286 14287 Location 14288 `http://www.sundialservices.com/download/memwatch.pas' 14289 14290 Overview 14291 Provides replacement dynamic memory allocation functions for 14292 Delphi which look for memory underwrites and overwrites. 14293 14294 * MM (Shared Memory Library) 14295 Author 14296 Ralf S. Engelschall (<rse@engelschall.com>) 14297 14298 License 14299 Free Software 14300 14301 Platforms 14302 Various UNIX, Windows 14303 14304 Location 14305 `http://www.engelschall.com/sw/mm/' 14306 14307 Overview 14308 Simplifies the usage (and can help debug) the use of shared 14309 memory between related processes. 14310 14311 * MM 14312 Author 14313 Dave Clements (<clements@cs.uoregon.edu>) 14314 14315 License 14316 Free Software 14317 14318 Platforms 14319 Various UNIX 14320 14321 Location 14322 `http://www.cirl.uoregon.edu/clements/memoryManager.html' 14323 14324 Overview 14325 Overrides the C dynamic memory allocation functions to 14326 provide better debugging capabilities. 14327 14328 * Mmalloc 14329 Author 14330 Mike Haertel (<mike@ai.mit.edu>) and Fred Fish 14331 (<fnf@cygnus.com>) 14332 14333 License 14334 GNU General Public License 14335 14336 Platforms 14337 Various UNIX 14338 14339 Location 14340 `http://www.gnu.org/' 14341 14342 Overview 14343 Uses `mmap()' to allocate separate pools of memory which can 14344 be mapped onto files for later reuse. 14345 14346 * MPR 14347 Author 14348 Taj Khattra (<taj.khattra@pobox.com>) 14349 14350 License 14351 Free Software 14352 14353 Platforms 14354 Linux 14355 14356 Location 14357 `http://metalab.unc.edu/pub/Linux/devel/lang/c/mpr-2.0.tar.gz' 14358 14359 Overview 14360 Attempts to find memory leaks in C/C++ programs by writing a 14361 log file during program execution, which can then be 14362 processed for obtaining further information. 14363 14364 * Mprof 14365 Author 14366 Ben Zorn (<zorn@microsoft.com>) 14367 14368 License 14369 Free Software 14370 14371 Platforms 14372 Various UNIX 14373 14374 Location 14375 `ftp://gatekeeper.dec.com/pub/misc/mprof-3.0.tar.Z' 14376 14377 Overview 14378 Profiles the dynamic memory allocation behaviour of programs 14379 by logging details for each function than makes a memory 14380 allocation, including call stack tracebacks. 14381 14382 * MSS (Memory Supervision System) 14383 Author 14384 Juan Jesus Alcolea Picazo (<a920101@zipi.fi.upm.es>) and 14385 Peter Palotas (<blizzar@hem1.passagen.se>) 14386 14387 License 14388 GNU General Public License 14389 14390 Platforms 14391 Linux, Windows, MS-DOS 14392 14393 Location 14394 `http://hem.passagen.se/blizzar/mss/' 14395 14396 Overview 14397 Full-featured malloc library for C and C++ providing 14398 detection of memory leaks, use of uninitialised memory and 14399 out of range block accesses as well as lots of tracing 14400 facilities. 14401 14402 * MTrace 14403 Author 14404 Morris R. Dovey (<mrdovey@iedu.com>) 14405 14406 License 14407 Free Software 14408 14409 Platforms 14410 Various UNIX, Windows 14411 14412 Location 14413 `http://www.iedu.com/mrd/c/mtrace.c' 14414 14415 Overview 14416 A very simple malloc tracing package. 14417 14418 * MuForce 14419 Author 14420 Thomas Richter (<thor@einstein.math.tu-berlin.de>) 14421 14422 License 14423 Free Software 14424 14425 Platforms 14426 AmigaOS 14427 14428 Location 14429 `http://www.math.tu-berlin.de/~thor/thor/index.html' 14430 14431 Overview 14432 Uses the MMU to monitor the system for any writes to 14433 non-existent memory and reports them over the serial port or 14434 any other output stream. 14435 14436 * MuGuardianAngel 14437 Author 14438 Thomas Richter (<thor@einstein.math.tu-berlin.de>) 14439 14440 License 14441 Free Software 14442 14443 Platforms 14444 AmigaOS 14445 14446 Location 14447 `http://www.math.tu-berlin.de/~thor/thor/index.html' 14448 14449 Overview 14450 An extension to the MuForce program which protects free 14451 memory and detects all illegal memory accesses. 14452 14453 * MuLib 14454 Author 14455 Thomas Richter (<thor@einstein.math.tu-berlin.de>) 14456 14457 License 14458 Free Software 14459 14460 Platforms 14461 AmigaOS 14462 14463 Location 14464 `http://www.math.tu-berlin.de/~thor/thor/index.html' 14465 14466 Overview 14467 Provides access to the MMU in modern Amigas so that features 14468 such as virtual memory can be implemented. 14469 14470 * MULTI 14471 Author 14472 Green Hills Software, Inc. (<sales@ghs.com>) 14473 14474 License 14475 Commercial Software 14476 14477 Platforms 14478 Various UNIX, Windows 14479 14480 Location 14481 `http://www.ghs.com' 14482 14483 Overview 14484 Inserts special checks into a program to watch for and report 14485 a broad variety of run-time errors, including freeing 14486 unallocated memory and memory leaks. 14487 14488 * Mungwall 14489 Author 14490 Commodore-Amiga, Inc. (<info@amiga.de>) 14491 14492 License 14493 Free Software 14494 14495 Platforms 14496 AmigaOS 14497 14498 Location 14499 `http://wuarchive.wustl.edu/~aminet/dirs/dev_debug.html' 14500 14501 Overview 14502 Patches the system to check for free memory corruption. 14503 14504 * NJAMD (Not Just Another Malloc Debugger) 14505 Author 14506 Mike Perry (<mikepery@fscked.org>) 14507 14508 License 14509 GNU General Public License 14510 14511 Platforms 14512 Various UNIX 14513 14514 Location 14515 `http://fscked.org/proj/njamd.shtml/' 14516 14517 Overview 14518 Helps track down a wide range of memory allocation problems 14519 and is divided into a front end executable and a library back 14520 end. 14521 14522 * ObjectCenter 14523 Author 14524 CenterLine Development Systems (<info@centerline.com>) 14525 14526 License 14527 Commercial Software 14528 14529 Platforms 14530 Various UNIX 14531 14532 Location 14533 `http://www.centerline.com/' 14534 14535 Overview 14536 Provides a C and C++ programming environment that can detect 14537 memory leaks, duplicate frees and illegal access errors 14538 including loads from uninitialised objects. 14539 14540 * Optimizeit 14541 Author 14542 Intuitive Systems, Inc. (<info@optimizeit.com>) 14543 14544 License 14545 Commercial Software 14546 14547 Platforms 14548 Various UNIX, Windows 14549 14550 Location 14551 `http://www.optimizeit.com/' 14552 14553 Overview 14554 Attempts to locate memory leaks and performance bottlenecks 14555 in Java programs. 14556 14557 * Plumber 14558 Author 14559 Owen O'Malley (<omalley@ics.uci.edu>) 14560 14561 License 14562 GNU General Public License 14563 14564 Platforms 14565 Linux, Solaris, SunOS 14566 14567 Location 14568 `http://www.ics.uci.edu/~softtest/plumber.html' 14569 14570 Overview 14571 A tool that replaces the normal Ada and C/C++ dynamic memory 14572 allocation functions and detects unfreed memory blocks. 14573 14574 * Purify 14575 Author 14576 Rational Software (<info@rational.com>) 14577 14578 License 14579 Commercial Software 14580 14581 Platforms 14582 Various UNIX, Windows 14583 14584 Location 14585 `http://www.rational.com/' 14586 14587 Overview 14588 Uses Object Code Insertion technology to provide run-time 14589 error checking and memory leak detection. 14590 14591 * QC 14592 Author 14593 Onyx Technology (<sales@onyx-tech.com>) 14594 14595 License 14596 Commercial Software 14597 14598 Platforms 14599 MacOS 14600 14601 Location 14602 `http://www.onyx-tech.com/' 14603 14604 Overview 14605 Runs in the background as a control panel and detects various 14606 memory errors which can then be caught and run under a 14607 debugger. 14608 14609 * SBase 14610 Author 14611 Ben Lilburne (<blilburn@cit.nepean.uws.edu.au>) 14612 14613 License 14614 Free Software 14615 14616 Platforms 14617 Various UNIX, Windows 14618 14619 Location 14620 `http://www.cit.uws.edu.au/~blilburn/sbase/' 14621 14622 Overview 14623 A set of classes for debugging dynamic memory problems in 14624 Objective C. 14625 14626 * SCID 14627 Author 14628 Richard Mills (<rich@xerp.freeserve.co.uk>) 14629 14630 License 14631 GNU General Public License 14632 14633 Platforms 14634 Various UNIX 14635 14636 Location 14637 `http:///www.xerp.demon.co.uk/' 14638 14639 Overview 14640 A program that tries to help locate bugs caused by the 14641 reading and writing of invalid pointers in C code by source 14642 code insertion. 14643 14644 * SmartAlloc 14645 Author 14646 John Walker 14647 14648 License 14649 Free Software 14650 14651 Platforms 14652 Various UNIX, MS-DOS 14653 14654 Location 14655 `http://www.fourmilab.ch/smartall/' 14656 14657 Overview 14658 Detects orphaned buffers of dynamic memory allocations and 14659 also helps to find other common problems in management of 14660 dynamic storage. 14661 14662 * SmartHeap 14663 Author 14664 MicroQuill (<info@microquill.com>) 14665 14666 License 14667 Commercial Software 14668 14669 Platforms 14670 Various UNIX, Windows, OS/2, MS-DOS, MacOS 14671 14672 Location 14673 `http://www.microquill.com/' 14674 14675 Overview 14676 Provides optimised heap performance along with detecting 14677 memory leaks, memory overwrites, double-freeing, wild 14678 pointers, invalid parameters, etc. 14679 14680 * Spotlight 14681 Author 14682 Onyx Technology (<sales@onyx-tech.com>) 14683 14684 License 14685 Commercial Software 14686 14687 Platforms 14688 MacOS 14689 14690 Location 14691 `http://www.onyx-tech.com/' 14692 14693 Overview 14694 Performs memory protection on PowerPC executables and helps 14695 detect memory leaks. 14696 14697 * StackTrace 14698 Author 14699 Bjorn Reese (<breese@mail1.stofanet.dk>) 14700 14701 License 14702 Free Software 14703 14704 Platforms 14705 Various UNIX 14706 14707 Location 14708 `http://home1.stofanet.dk/breese/debug/debug.tar.gz' 14709 14710 Overview 14711 Provides code to generate a stack trace of the program at any 14712 point during execution using either a debugger or built-in 14713 methods found in the GNU C compiler or on some systems. 14714 14715 * TestCenter 14716 Author 14717 CenterLine Development Systems (<info@centerline.com>) 14718 14719 License 14720 Commercial Software 14721 14722 Platforms 14723 Various UNIX 14724 14725 Location 14726 `http://www.centerline.com/' 14727 14728 Overview 14729 Detects memory leaks, duplicate frees and illegal access 14730 errors including loads from uninitialised objects. 14731 14732 * Third Degree 14733 Author 14734 Digital Equipment Corporation (<info@digital.com>) 14735 14736 License 14737 Commercial Software 14738 14739 Platforms 14740 Digital UNIX 14741 14742 Location 14743 `http://www.digital.com/' 14744 14745 Overview 14746 A tool that performs memory access checks and memory leak 14747 detection of C, C++ and Fortran programs at run-time. 14748 Applications are modified using ATOM to determine if any 14749 memory locations are accessed when not properly allocated or 14750 initialised. 14751 14752 * Vmalloc 14753 Author 14754 Kiem-Phong Vo (<kpv@research.att.com>) 14755 14756 License 14757 AT&T Source Code License 14758 14759 Platforms 14760 Various UNIX, Windows 14761 14762 Location 14763 `http://akpublic.research.att.com/sw/tools/vmalloc/' 14764 14765 Overview 14766 A discipline and method library for dynamic memory 14767 allocation, with support for regions, debugging and profiling. 14768 14769 * Wipeout 14770 Author 14771 Olaf Barthel (<olsen@sourcery.han.de>) 14772 14773 License 14774 Free Software 14775 14776 Platforms 14777 AmigaOS 14778 14779 Location 14780 `http://wuarchive.wustl.edu/~aminet/dirs/dev_debug.html' 14781 14782 Overview 14783 Runs in the background checking free memory for corruption. 14784 14785 * YaMa 14786 Author 14787 Venkatesha Murthy G. (<gvmt@vsnl.com>) 14788 14789 License 14790 Free Software 14791 14792 Platforms 14793 Linux 14794 14795 Location 14796 `http://www.geocities.com/ipsgvm/libyama/' 14797 14798 Overview 14799 A memory allocator with leak tracing and some anti-heap 14800 corruption facilities. 14801 14802 * YAMD (Yet Another Malloc Debugger) 14803 Author 14804 Nate Eldredge (<neldredge@hmc.edu>) 14805 14806 License 14807 GNU General Public License 14808 14809 Platforms 14810 Linux, MS-DOS 14811 14812 Location 14813 `http://www3.hmc.edu/~neldredge/yamd/' 14814 14815 Overview 14816 A tool for finding bugs related to dynamic memory allocation 14817 in C and C++, and includes paging mechanisms to catch bugs 14818 immediately. 14819 14820 * ZeroFault 14821 Author 14822 The Kernel Group (<info@zerofault.com>) 14823 14824 License 14825 Commercial Software 14826 14827 Platforms 14828 AIX UNIX 14829 14830 Location 14831 `http://www.zerofault.com/' 14832 14833 Overview 14834 Uses run-time emulator technology to provide run-time error 14835 checking and memory leak detection. 14836 14837 However, before you try out any of the above software, there may 14838already be a malloc library with debugging support on your system that 14839might be suitable for solving your problem. For example, on Solaris 14840the following libraries are available: 14841 14842`malloc(3c)' 14843 Trade-off between performance and efficiency. 14844 14845`malloc(3x)' 14846 Slower performance, space-efficient. 14847 14848`bsdmalloc(3x)' 14849 Better performance, space-inefficient. 14850 14851`mtmalloc(3t)' 14852 Thread-safe memory allocator. 14853 14854`mapmalloc(3x)' 14855 Uses `mmap()' instead of `sbrk()' to allocate heap space. 14856 14857`watchmalloc(3x)' 14858 Uses watch point areas to check for overflows. 14859 14860 On platforms with the GNU C library, such as Linux, there are several 14861environment variables that can be used to enable various debugging 14862features of `malloc()', etc. There are also extra functions provided 14863in the library which can be used to aid in debugging, and some shell 14864scripts which can translate return addresses or locate unfreed memory 14865allocations in the log files produced. Useful information on the 14866debugging features available within the GNU C library is located at 14867`http://sdb.suse.de/sdb/en/html/aj_debug.html'. 14868 14869 If you suspect that the debugging problem you are looking at is 14870likely to be related to UNIX system calls then some systems come with 14871the `strace' or `truss' commands which allow you to trace all of the 14872system calls that a program makes when running. This can sometimes be 14873invaluable in pinpointing the exact point at which a program fails, but 14874as it only operates at the system call level, no information about 14875individual memory allocations is available. 14876 14877 On Windows 2000 (and probably later releases of the operating system 14878as well) there is a utility called `pageheap' which acts in a similar 14879way to the `mpatrol' command in that it overrides the definitions of 14880`malloc()' and related functions for any programs that it runs. It has 14881a similar behaviour to the `--page-alloc-upper' option but has far less 14882features. However, it could be very useful if you can't get mpatrol to 14883work for you. 14884 14885 ---------- Footnotes ---------- 14886 14887 (1) This list can be considered to be a slightly more up to date 14888version of `Debugging Tools for Dynamic Storage Allocation and Memory 14889Management' (`http://www.cs.colorado.edu/~zorn/MallocDebug.html') by 14890Ben Zorn (<zorn@microsoft.com>). 14891 14892 14893File: mpatrol.info, Node: References, Next: About the author, Prev: Related software, Up: Top 14894 14895References 14896********** 14897 14898 This section contains references to interesting papers and resources 14899on related topics and the field of memory management in general. The 14900vast majority of theoretical information can be found at the Memory 14901Management Reference, although this does tend to concentrate on garbage 14902collection. The other references take a more practical approach to 14903memory management and in some cases provide implementation details. 14904Let me know if you'd like to see any other references or resources 14905added to this list. 14906 14907 * Avoiding Motif Memory Leaks 14908 Author 14909 Kenton Lee (<kenton@rahul.net>) 14910 14911 Location 14912 `http://www.rahul.net/kenton/txa/mar96.html' 14913 14914 Overview 14915 An article on avoiding memory leaks in Motif applications. 14916 14917 * C++ FAQ Lite: Freestore Management 14918 Author 14919 Marshall Cline (<cline@parashift.com>) 14920 14921 Location 14922 `http://www.parashift.com/c++-faq-lite/freestore-mgmt.html' 14923 14924 Overview 14925 Everything you ever wanted to know about C++ memory 14926 management. 14927 14928 * Debugging Memory On Linux 14929 Author 14930 Petr Sorfa (<editor@ssc.com>) 14931 14932 Location 14933 `http://www.linuxjournal.com/article.php?sid=4681' 14934 14935 Overview 14936 An article detailing the tools available to debug memory 14937 problems on Linux. 14938 14939 * Effective C++ Memory Allocation 14940 Author 14941 Aaron Dailey (<adailey@chaparraltec.com>) 14942 14943 Location 14944 `http://www.embedded.com/1999/9901/9901feat2.htm' 14945 14946 Overview 14947 Documents techniques for better use of the C++ dynamic memory 14948 allocation operators. 14949 14950 * How To Debug Memory Leaks 14951 Author 14952 The Mozilla Organization (<webmaster@mozilla.org>) 14953 14954 Location 14955 `http://www.lxr.mozilla.org/mozilla/source/xpcom/doc/MemoryTools.html' 14956 14957 Overview 14958 A list of memory analysis tools that the Mozilla team have 14959 developed in order to quickly spot and fix memory leaks. 14960 14961 * Just Say No To Memory Leaks 14962 Author 14963 Steve Litt (<slitt@troubleshooters.com>) 14964 14965 Location 14966 `http://www.troubleshooters.com/codecorn/memleak.htm' 14967 14968 Overview 14969 An article discussing memory leaks and how to avoid them. 14970 14971 * A Memory Allocator 14972 Author 14973 Doug Lea (<dl@gee.cs.oswego.edu>) 14974 14975 Location 14976 `http://gee.cs.oswego.edu/dl/html/malloc.html' 14977 14978 Overview 14979 Information on general memory allocation principles. 14980 14981 * The Memory Management Reference 14982 Author 14983 XANALYS Software Tools (<mm-web@xanalys.com>) 14984 14985 Location 14986 `http://www.xanalys.com/software_tools/mm/' 14987 14988 Overview 14989 Links to many documents and research papers in the field of 14990 memory management, and has a large glossary which lists and 14991 explains related terms. 14992 14993 * My Rant on C++'s `operator new' 14994 Author 14995 David Mazieres (<dm@cs.nyu.edu>) 14996 14997 Location 14998 `http://www.pdos.lcs.mit.edu/~dm/c++-new.html' 14999 15000 Overview 15001 Provides a scathing critique on the C++ dynamic memory 15002 allocation operators. 15003 15004 * The Virtual Memory Tutorial 15005 Author 15006 The Hyperlearning Center (<webmaster@cne.gmu.edu>) 15007 15008 Location 15009 `http://www.cne.gmu.edu/modules/vm/' 15010 15011 Overview 15012 Provides a comprehensive tutorial on virtual memory, as well 15013 as detailing its history, theory and implementation. 15014 15015 * X Window System Memory Leaks and Other Memory Bugs 15016 Author 15017 Kenton Lee (<kenton@rahul.net>) 15018 15019 Location 15020 `http://www.rahul.net/kenton/txa/feb96.html' 15021 15022 Overview 15023 An article on debugging memory problems in X applications. 15024 15025 15026File: mpatrol.info, Node: About the author, Next: Copying, Prev: References, Up: Top 15027 15028About the author 15029**************** 15030 15031 I live in Edinburgh (the capital city of Scotland) and work for an 15032American company called Analog Devices which designs and manufactures 15033digital and analogue electronic equipment, as well as Digital Signal 15034Processors (DSPs). The company I used to work for was called Edinburgh 15035Portable Compilers, a small Edinburgh-based company which designed, 15036wrote and sold compilers for various programming languages and 15037operating systems (mainly UNIX variants). A few years ago it became a 15038wholly-owned subsidiary of Analog Devices and our focus was shifted to 15039write C and C++ compilers for the various ADI DSPs. 15040 15041 I started working at EPC immediately after obtaining my honours 15042degree in Computer Science at Edinburgh University. My interests lie 15043in operating systems and programming tools so this was an ideal working 15044environment for me to apply my knowledge and learn more about the bits 15045and pieces that most programmers and computer users know little or 15046nothing about. 15047 15048 Writing compilers is a complex business that most people take for 15049granted. The popular view is that once you have a lexer and a parser 15050for a particular programming language then you are 90% of the way to 15051having a compiler. However, modern compilers are required to perform 15052more and more aggressive optimisations on user code, all of which 15053require complex algorithms, and most of which are applied at the 15054code-generator level. Add accurate debugging information generation, 15055C++ exceptions and templates, inline assembler support and an efficient 15056run-time library and you begin to see why writing and maintaining a 15057compiler is not a solo effort! 15058 15059 I originally wrote the mpatrol library in my spare time with the 15060intention of selling it to EPC as a comprehensive memory debugging 15061solution for integration with their UNIX compilers. Unfortunately, EPC 15062was taken over by ADI before it was finished and ADI had no use for 15063such a library in their DSP toolchain. However, I still feel that it 15064was worth the effort (not least because of all the knowledge of other 15065operating systems that I gained whilst writing it), and I hope you do 15066too! 15067 15068 15069File: mpatrol.info, Node: Copying, Next: Function index, Prev: About the author, Up: Top 15070 15071Copying 15072******* 15073 15074 GNU LIBRARY GENERAL PUBLIC LICENSE 15075 Version 2, June 1991 15076 15077 Copyright (C) 1991 Free Software Foundation, Inc. 15078 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA 15079 Everyone is permitted to copy and distribute verbatim copies 15080 of this license document, but changing it is not allowed. 15081 15082 [This is the first released version of the library GPL. It is 15083 numbered 2 because it goes with version 2 of the ordinary GPL.] 15084 15085 Preamble 15086 15087 The licenses for most software are designed to take away your 15088 freedom to share and change it. By contrast, the GNU General Public 15089 Licenses are intended to guarantee your freedom to share and change 15090 free software--to make sure the software is free for all its users. 15091 15092 This license, the Library General Public License, applies to some 15093 specially designated Free Software Foundation software, and to any 15094 other libraries whose authors decide to use it. You can use it for 15095 your libraries, too. 15096 15097 When we speak of free software, we are referring to freedom, not 15098 price. Our General Public Licenses are designed to make sure that you 15099 have the freedom to distribute copies of free software (and charge for 15100 this service if you wish), that you receive source code or can get it 15101 if you want it, that you can change the software or use pieces of it 15102 in new free programs; and that you know you can do these things. 15103 15104 To protect your rights, we need to make restrictions that forbid 15105 anyone to deny you these rights or to ask you to surrender the rights. 15106 These restrictions translate to certain responsibilities for you if 15107 you distribute copies of the library, or if you modify it. 15108 15109 For example, if you distribute copies of the library, whether gratis 15110 or for a fee, you must give the recipients all the rights that we gave 15111 you. You must make sure that they, too, receive or can get the source 15112 code. If you link a program with the library, you must provide 15113 complete object files to the recipients so that they can relink them 15114 with the library, after making changes to the library and recompiling 15115 it. And you must show them these terms so they know their rights. 15116 15117 Our method of protecting your rights has two steps: (1) copyright 15118 the library, and (2) offer you this license which gives you legal 15119 permission to copy, distribute and/or modify the library. 15120 15121 Also, for each distributor's protection, we want to make certain 15122 that everyone understands that there is no warranty for this free 15123 library. If the library is modified by someone else and passed on, we 15124 want its recipients to know that what they have is not the original 15125 version, so that any problems introduced by others will not reflect on 15126 the original authors' reputations. 15127 15128 Finally, any free program is threatened constantly by software 15129 patents. We wish to avoid the danger that companies distributing free 15130 software will individually obtain patent licenses, thus in effect 15131 transforming the program into proprietary software. To prevent this, 15132 we have made it clear that any patent must be licensed for everyone's 15133 free use or not licensed at all. 15134 15135 Most GNU software, including some libraries, is covered by the ordinary 15136 GNU General Public License, which was designed for utility programs. This 15137 license, the GNU Library General Public License, applies to certain 15138 designated libraries. This license is quite different from the ordinary 15139 one; be sure to read it in full, and don't assume that anything in it is 15140 the same as in the ordinary license. 15141 15142 The reason we have a separate public license for some libraries is that 15143 they blur the distinction we usually make between modifying or adding to a 15144 program and simply using it. Linking a program with a library, without 15145 changing the library, is in some sense simply using the library, and is 15146 analogous to running a utility program or application program. However, in 15147 a textual and legal sense, the linked executable is a combined work, a 15148 derivative of the original library, and the ordinary General Public License 15149 treats it as such. 15150 15151 Because of this blurred distinction, using the ordinary General 15152 Public License for libraries did not effectively promote software 15153 sharing, because most developers did not use the libraries. We 15154 concluded that weaker conditions might promote sharing better. 15155 15156 However, unrestricted linking of non-free programs would deprive the 15157 users of those programs of all benefit from the free status of the 15158 libraries themselves. This Library General Public License is intended to 15159 permit developers of non-free programs to use free libraries, while 15160 preserving your freedom as a user of such programs to change the free 15161 libraries that are incorporated in them. (We have not seen how to achieve 15162 this as regards changes in header files, but we have achieved it as regards 15163 changes in the actual functions of the Library.) The hope is that this 15164 will lead to faster development of free libraries. 15165 15166 The precise terms and conditions for copying, distribution and 15167 modification follow. Pay close attention to the difference between a 15168 "work based on the library" and a "work that uses the library". The 15169 former contains code derived from the library, while the latter only 15170 works together with the library. 15171 15172 Note that it is possible for a library to be covered by the ordinary 15173 General Public License rather than by this special one. 15174 15175 GNU LIBRARY GENERAL PUBLIC LICENSE 15176 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 15177 15178 0. This License Agreement applies to any software library which 15179 contains a notice placed by the copyright holder or other authorized 15180 party saying it may be distributed under the terms of this Library 15181 General Public License (also called "this License"). Each licensee is 15182 addressed as "you". 15183 15184 A "library" means a collection of software functions and/or data 15185 prepared so as to be conveniently linked with application programs 15186 (which use some of those functions and data) to form executables. 15187 15188 The "Library", below, refers to any such software library or work 15189 which has been distributed under these terms. A "work based on the 15190 Library" means either the Library or any derivative work under 15191 copyright law: that is to say, a work containing the Library or a 15192 portion of it, either verbatim or with modifications and/or translated 15193 straightforwardly into another language. (Hereinafter, translation is 15194 included without limitation in the term "modification".) 15195 15196 "Source code" for a work means the preferred form of the work for 15197 making modifications to it. For a library, complete source code means 15198 all the source code for all modules it contains, plus any associated 15199 interface definition files, plus the scripts used to control compilation 15200 and installation of the library. 15201 15202 Activities other than copying, distribution and modification are not 15203 covered by this License; they are outside its scope. The act of 15204 running a program using the Library is not restricted, and output from 15205 such a program is covered only if its contents constitute a work based 15206 on the Library (independent of the use of the Library in a tool for 15207 writing it). Whether that is true depends on what the Library does 15208 and what the program that uses the Library does. 15209 15210 1. You may copy and distribute verbatim copies of the Library's 15211 complete source code as you receive it, in any medium, provided that 15212 you conspicuously and appropriately publish on each copy an 15213 appropriate copyright notice and disclaimer of warranty; keep intact 15214 all the notices that refer to this License and to the absence of any 15215 warranty; and distribute a copy of this License along with the 15216 Library. 15217 15218 You may charge a fee for the physical act of transferring a copy, 15219 and you may at your option offer warranty protection in exchange for a 15220 fee. 15221 15222 2. You may modify your copy or copies of the Library or any portion 15223 of it, thus forming a work based on the Library, and copy and 15224 distribute such modifications or work under the terms of Section 1 15225 above, provided that you also meet all of these conditions: 15226 15227 a) The modified work must itself be a software library. 15228 15229 b) You must cause the files modified to carry prominent notices 15230 stating that you changed the files and the date of any change. 15231 15232 c) You must cause the whole of the work to be licensed at no 15233 charge to all third parties under the terms of this License. 15234 15235 d) If a facility in the modified Library refers to a function or a 15236 table of data to be supplied by an application program that uses 15237 the facility, other than as an argument passed when the facility 15238 is invoked, then you must make a good faith effort to ensure that, 15239 in the event an application does not supply such function or 15240 table, the facility still operates, and performs whatever part of 15241 its purpose remains meaningful. 15242 15243 (For example, a function in a library to compute square roots has 15244 a purpose that is entirely well-defined independent of the 15245 application. Therefore, Subsection 2d requires that any 15246 application-supplied function or table used by this function must 15247 be optional: if the application does not supply it, the square 15248 root function must still compute square roots.) 15249 15250 These requirements apply to the modified work as a whole. If 15251 identifiable sections of that work are not derived from the Library, 15252 and can be reasonably considered independent and separate works in 15253 themselves, then this License, and its terms, do not apply to those 15254 sections when you distribute them as separate works. But when you 15255 distribute the same sections as part of a whole which is a work based 15256 on the Library, the distribution of the whole must be on the terms of 15257 this License, whose permissions for other licensees extend to the 15258 entire whole, and thus to each and every part regardless of who wrote 15259 it. 15260 15261 Thus, it is not the intent of this section to claim rights or contest 15262 your rights to work written entirely by you; rather, the intent is to 15263 exercise the right to control the distribution of derivative or 15264 collective works based on the Library. 15265 15266 In addition, mere aggregation of another work not based on the Library 15267 with the Library (or with a work based on the Library) on a volume of 15268 a storage or distribution medium does not bring the other work under 15269 the scope of this License. 15270 15271 3. You may opt to apply the terms of the ordinary GNU General Public 15272 License instead of this License to a given copy of the Library. To do 15273 this, you must alter all the notices that refer to this License, so 15274 that they refer to the ordinary GNU General Public License, version 2, 15275 instead of to this License. (If a newer version than version 2 of the 15276 ordinary GNU General Public License has appeared, then you can specify 15277 that version instead if you wish.) Do not make any other change in 15278 these notices. 15279 15280 Once this change is made in a given copy, it is irreversible for 15281 that copy, so the ordinary GNU General Public License applies to all 15282 subsequent copies and derivative works made from that copy. 15283 15284 This option is useful when you wish to copy part of the code of 15285 the Library into a program that is not a library. 15286 15287 4. You may copy and distribute the Library (or a portion or 15288 derivative of it, under Section 2) in object code or executable form 15289 under the terms of Sections 1 and 2 above provided that you accompany 15290 it with the complete corresponding machine-readable source code, which 15291 must be distributed under the terms of Sections 1 and 2 above on a 15292 medium customarily used for software interchange. 15293 15294 If distribution of object code is made by offering access to copy 15295 from a designated place, then offering equivalent access to copy the 15296 source code from the same place satisfies the requirement to 15297 distribute the source code, even though third parties are not 15298 compelled to copy the source along with the object code. 15299 15300 5. A program that contains no derivative of any portion of the 15301 Library, but is designed to work with the Library by being compiled or 15302 linked with it, is called a "work that uses the Library". Such a 15303 work, in isolation, is not a derivative work of the Library, and 15304 therefore falls outside the scope of this License. 15305 15306 However, linking a "work that uses the Library" with the Library 15307 creates an executable that is a derivative of the Library (because it 15308 contains portions of the Library), rather than a "work that uses the 15309 library". The executable is therefore covered by this License. 15310 Section 6 states terms for distribution of such executables. 15311 15312 When a "work that uses the Library" uses material from a header file 15313 that is part of the Library, the object code for the work may be a 15314 derivative work of the Library even though the source code is not. 15315 Whether this is true is especially significant if the work can be 15316 linked without the Library, or if the work is itself a library. The 15317 threshold for this to be true is not precisely defined by law. 15318 15319 If such an object file uses only numerical parameters, data 15320 structure layouts and accessors, and small macros and small inline 15321 functions (ten lines or less in length), then the use of the object 15322 file is unrestricted, regardless of whether it is legally a derivative 15323 work. (Executables containing this object code plus portions of the 15324 Library will still fall under Section 6.) 15325 15326 Otherwise, if the work is a derivative of the Library, you may 15327 distribute the object code for the work under the terms of Section 6. 15328 Any executables containing that work also fall under Section 6, 15329 whether or not they are linked directly with the Library itself. 15330 15331 6. As an exception to the Sections above, you may also compile or 15332 link a "work that uses the Library" with the Library to produce a 15333 work containing portions of the Library, and distribute that work 15334 under terms of your choice, provided that the terms permit 15335 modification of the work for the customer's own use and reverse 15336 engineering for debugging such modifications. 15337 15338 You must give prominent notice with each copy of the work that the 15339 Library is used in it and that the Library and its use are covered by 15340 this License. You must supply a copy of this License. If the work 15341 during execution displays copyright notices, you must include the 15342 copyright notice for the Library among them, as well as a reference 15343 directing the user to the copy of this License. Also, you must do one 15344 of these things: 15345 15346 a) Accompany the work with the complete corresponding 15347 machine-readable source code for the Library including whatever 15348 changes were used in the work (which must be distributed under 15349 Sections 1 and 2 above); and, if the work is an executable linked 15350 with the Library, with the complete machine-readable "work that 15351 uses the Library", as object code and/or source code, so that the 15352 user can modify the Library and then relink to produce a modified 15353 executable containing the modified Library. (It is understood 15354 that the user who changes the contents of definitions files in the 15355 Library will not necessarily be able to recompile the application 15356 to use the modified definitions.) 15357 15358 b) Accompany the work with a written offer, valid for at 15359 least three years, to give the same user the materials 15360 specified in Subsection 6a, above, for a charge no more 15361 than the cost of performing this distribution. 15362 15363 c) If distribution of the work is made by offering access to copy 15364 from a designated place, offer equivalent access to copy the above 15365 specified materials from the same place. 15366 15367 d) Verify that the user has already received a copy of these 15368 materials or that you have already sent this user a copy. 15369 15370 For an executable, the required form of the "work that uses the 15371 Library" must include any data and utility programs needed for 15372 reproducing the executable from it. However, as a special exception, 15373 the source code distributed need not include anything that is normally 15374 distributed (in either source or binary form) with the major 15375 components (compiler, kernel, and so on) of the operating system on 15376 which the executable runs, unless that component itself accompanies 15377 the executable. 15378 15379 It may happen that this requirement contradicts the license 15380 restrictions of other proprietary libraries that do not normally 15381 accompany the operating system. Such a contradiction means you cannot 15382 use both them and the Library together in an executable that you 15383 distribute. 15384 15385 7. You may place library facilities that are a work based on the 15386 Library side-by-side in a single library together with other library 15387 facilities not covered by this License, and distribute such a combined 15388 library, provided that the separate distribution of the work based on 15389 the Library and of the other library facilities is otherwise 15390 permitted, and provided that you do these two things: 15391 15392 a) Accompany the combined library with a copy of the same work 15393 based on the Library, uncombined with any other library 15394 facilities. This must be distributed under the terms of the 15395 Sections above. 15396 15397 b) Give prominent notice with the combined library of the fact 15398 that part of it is a work based on the Library, and explaining 15399 where to find the accompanying uncombined form of the same work. 15400 15401 8. You may not copy, modify, sublicense, link with, or distribute 15402 the Library except as expressly provided under this License. Any 15403 attempt otherwise to copy, modify, sublicense, link with, or 15404 distribute the Library is void, and will automatically terminate your 15405 rights under this License. However, parties who have received copies, 15406 or rights, from you under this License will not have their licenses 15407 terminated so long as such parties remain in full compliance. 15408 15409 9. You are not required to accept this License, since you have not 15410 signed it. However, nothing else grants you permission to modify or 15411 distribute the Library or its derivative works. These actions are 15412 prohibited by law if you do not accept this License. Therefore, by 15413 modifying or distributing the Library (or any work based on the 15414 Library), you indicate your acceptance of this License to do so, and 15415 all its terms and conditions for copying, distributing or modifying 15416 the Library or works based on it. 15417 15418 10. Each time you redistribute the Library (or any work based on the 15419 Library), the recipient automatically receives a license from the 15420 original licensor to copy, distribute, link with or modify the Library 15421 subject to these terms and conditions. You may not impose any further 15422 restrictions on the recipients' exercise of the rights granted herein. 15423 You are not responsible for enforcing compliance by third parties to 15424 this License. 15425 15426 11. If, as a consequence of a court judgment or allegation of patent 15427 infringement or for any other reason (not limited to patent issues), 15428 conditions are imposed on you (whether by court order, agreement or 15429 otherwise) that contradict the conditions of this License, they do not 15430 excuse you from the conditions of this License. If you cannot 15431 distribute so as to satisfy simultaneously your obligations under this 15432 License and any other pertinent obligations, then as a consequence you 15433 may not distribute the Library at all. For example, if a patent 15434 license would not permit royalty-free redistribution of the Library by 15435 all those who receive copies directly or indirectly through you, then 15436 the only way you could satisfy both it and this License would be to 15437 refrain entirely from distribution of the Library. 15438 15439 If any portion of this section is held invalid or unenforceable under any 15440 particular circumstance, the balance of the section is intended to apply, 15441 and the section as a whole is intended to apply in other circumstances. 15442 15443 It is not the purpose of this section to induce you to infringe any 15444 patents or other property right claims or to contest validity of any 15445 such claims; this section has the sole purpose of protecting the 15446 integrity of the free software distribution system which is 15447 implemented by public license practices. Many people have made 15448 generous contributions to the wide range of software distributed 15449 through that system in reliance on consistent application of that 15450 system; it is up to the author/donor to decide if he or she is willing 15451 to distribute software through any other system and a licensee cannot 15452 impose that choice. 15453 15454 This section is intended to make thoroughly clear what is believed to 15455 be a consequence of the rest of this License. 15456 15457 12. If the distribution and/or use of the Library is restricted in 15458 certain countries either by patents or by copyrighted interfaces, the 15459 original copyright holder who places the Library under this License may add 15460 an explicit geographical distribution limitation excluding those countries, 15461 so that distribution is permitted only in or among countries not thus 15462 excluded. In such case, this License incorporates the limitation as if 15463 written in the body of this License. 15464 15465 13. The Free Software Foundation may publish revised and/or new 15466 versions of the Library General Public License from time to time. 15467 Such new versions will be similar in spirit to the present version, 15468 but may differ in detail to address new problems or concerns. 15469 15470 Each version is given a distinguishing version number. If the Library 15471 specifies a version number of this License which applies to it and 15472 "any later version", you have the option of following the terms and 15473 conditions either of that version or of any later version published by 15474 the Free Software Foundation. If the Library does not specify a 15475 license version number, you may choose any version ever published by 15476 the Free Software Foundation. 15477 15478 14. If you wish to incorporate parts of the Library into other free 15479 programs whose distribution conditions are incompatible with these, 15480 write to the author to ask for permission. For software which is 15481 copyrighted by the Free Software Foundation, write to the Free 15482 Software Foundation; we sometimes make exceptions for this. Our 15483 decision will be guided by the two goals of preserving the free status 15484 of all derivatives of our free software and of promoting the sharing 15485 and reuse of software generally. 15486 15487 NO WARRANTY 15488 15489 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO 15490 WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. 15491 EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR 15492 OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY 15493 KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE 15494 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 15495 PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE 15496 LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME 15497 THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 15498 15499 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN 15500 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY 15501 AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU 15502 FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR 15503 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE 15504 LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING 15505 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A 15506 FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF 15507 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH 15508 DAMAGES. 15509 15510 END OF TERMS AND CONDITIONS 15511 15512 How to Apply These Terms to Your New Libraries 15513 15514 If you develop a new library, and you want it to be of the greatest 15515 possible use to the public, we recommend making it free software that 15516 everyone can redistribute and change. You can do so by permitting 15517 redistribution under these terms (or, alternatively, under the terms of the 15518 ordinary General Public License). 15519 15520 To apply these terms, attach the following notices to the library. It is 15521 safest to attach them to the start of each source file to most effectively 15522 convey the exclusion of warranty; and each file should have at least the 15523 "copyright" line and a pointer to where the full notice is found. 15524 15525 <one line to give the library's name and a brief idea of what it does.> 15526 Copyright (C) <year> <name of author> 15527 15528 This library is free software; you can redistribute it and/or 15529 modify it under the terms of the GNU Library General Public 15530 License as published by the Free Software Foundation; either 15531 version 2 of the License, or (at your option) any later version. 15532 15533 This library is distributed in the hope that it will be useful, 15534 but WITHOUT ANY WARRANTY; without even the implied warranty of 15535 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15536 Library General Public License for more details. 15537 15538 You should have received a copy of the GNU Library General Public 15539 License along with this library; if not, write to the Free Software 15540 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA 15541 15542 Also add information on how to contact you by electronic and paper mail. 15543 15544 You should also get your employer (if you work as a programmer) or your 15545 school, if any, to sign a "copyright disclaimer" for the library, if 15546 necessary. Here is a sample; alter the names: 15547 15548 Yoyodyne, Inc., hereby disclaims all copyright interest in the 15549 library `Frob' (a library for tweaking knobs) written by James Random Hacker. 15550 15551 <signature of Ty Coon>, 1 April 1990 15552 Ty Coon, President of Vice 15553 15554 That's all there is to it! 15555 15556 15557File: mpatrol.info, Node: Function index, Next: Index, Prev: Copying, Up: Top 15558 15559Function index 15560************** 15561 15562* Menu: 15563 15564* __mp_addallocentry: Functions 6. 15565* __mp_addfreeentry: Functions 6. 15566* __mp_atexit: Functions 6. 15567* __mp_check: Functions 6. 15568* __mp_clearleaktable: Functions 6. 15569* __mp_cmpcontents: Functions 6. 15570* __mp_edit: Functions 6. 15571* __mp_epilogue: Functions 6. 15572* __mp_function: Functions 6. 15573* __mp_getoption: Functions 6. 15574* __mp_info: Functions 6. 15575* __mp_iterate: Functions 6. 15576* __mp_iterateall: Functions 6. 15577* __mp_leaktable: Functions 6. 15578* __mp_libversion: Functions 6. 15579* __mp_list: Functions 6. 15580* __mp_locprintf: Functions 6. 15581* __mp_logaddr: Functions 6. 15582* __mp_logmemory: Functions 6. 15583* __mp_logstack: Functions 6. 15584* __mp_memorymap: Functions 6. 15585* __mp_nomemory: Functions 6. 15586* __mp_printf: Functions 6. 15587* __mp_printinfo: Functions 6. 15588* __mp_prologue: Functions 6. 15589* __mp_readcontents: Functions 6. 15590* __mp_remcontents: Functions 6. 15591* __mp_setmark: Functions 6. 15592* __mp_setoption: Functions 6. 15593* __mp_setuser: Functions 6. 15594* __mp_snapshot: Functions 6. 15595* __mp_startleaktable: Functions 6. 15596* __mp_stats: Functions 6. 15597* __mp_stopleaktable: Functions 6. 15598* __mp_strerror: Functions 6. 15599* __mp_summary: Functions 6. 15600* __mp_symbol: Functions 6. 15601* __mp_syminfo: Functions 6. 15602* __mp_view: Functions 6. 15603* __mp_vlocprintf: Functions 6. 15604* __mp_vprintf: Functions 6. 15605* __mp_writecontents: Functions 6. 15606* alloca: Functions 1. 15607* bcmp: Functions 5. 15608* bcopy: Functions 5. 15609* bzero: Functions 5. 15610* calloc: Functions 1. 15611* cfree: Functions 1. 15612* dealloca: Functions 1. 15613* expand: Functions 1. 15614* free: Functions 1. 15615* malloc: Functions 1. 15616* memalign: Functions 1. 15617* memccpy: Functions 5. 15618* memchr: Functions 5. 15619* memcmp: Functions 5. 15620* memcpy: Functions 5. 15621* memmem: Functions 5. 15622* memmove: Functions 5. 15623* memset: Functions 5. 15624* MP_CALLOC: Functions 3. 15625* MP_FAILURE: Functions 3. 15626* MP_FREE: Functions 3. 15627* MP_MALLOC: Functions 3. 15628* MP_REALLOC: Functions 3. 15629* MP_STRDUP: Functions 3. 15630* operator delete: Functions 4. 15631* operator delete[]: Functions 4. 15632* operator new: Functions 4. 15633* operator new[]: Functions 4. 15634* pvalloc: Functions 1. 15635* realloc: Functions 1. 15636* reallocf: Functions 1. 15637* recalloc: Functions 1. 15638* set_new_handler: Functions 4. 15639* strdup: Functions 1. 15640* strdupa: Functions 1. 15641* strndup: Functions 1. 15642* strndupa: Functions 1. 15643* strnsave: Functions 1. 15644* strsave: Functions 1. 15645* valloc: Functions 1. 15646* xcalloc: Functions 2. 15647* xfree: Functions 2. 15648* xmalloc: Functions 2. 15649* xrealloc: Functions 2. 15650* xstrdup: Functions 2. 15651 15652 15653File: mpatrol.info, Node: Index, Prev: Function index, Up: Top 15654 15655Index 15656***** 15657 15658* Menu: 15659 15660* -addresses: Profiling. 15661* -alloc: Tracing. 15662* -alloc-byte: Options. 15663* -alloc-stop: Options. 15664* -allow-oflow: Options. 15665* -auto-save: Options. 15666* -base: Tracing. 15667* -call-graph: Profiling. 15668* -check: Options. 15669* -check-all: Options. 15670* -check-allocs: Options. 15671* -check-fork: Options. 15672* -check-frees: Options. 15673* -check-memory: Options. 15674* -check-reallocs: Options. 15675* -counts: Profiling. 15676* -def-align: Options. 15677* -delay: Tracing. 15678* -dynamic: Options. 15679* -edit: Options. 15680* -editor: The mpedit command. 15681* -fail-freq: Options. 15682* -fail-seed: Options. 15683* -free: Tracing. 15684* -free-byte: Options. 15685* -free-stop: Options. 15686* -graph-file: Profiling. 15687* -gui: Tracing. 15688* -hatf-file: Tracing. 15689* -height: Tracing. 15690* -help: Options. 15691* -ignore: The mleak command. 15692* -internal: Tracing. 15693* -large-bound: Options. 15694* -leak-table: Options. 15695* -leaks: Profiling. 15696* -limit: Options. 15697* -list: Options. 15698* -listing: The mpedit command. 15699* -log-all: Options. 15700* -log-allocs: Options. 15701* -log-file: Options. 15702* -log-frees: Options. 15703* -log-memory: Options. 15704* -log-reallocs: Options. 15705* -match: The hexwords command. 15706* -max-stack: The mleak command. 15707* -maximum: The hexwords command. 15708* -medium-bound: Options. 15709* -minimum: The hexwords command. 15710* -no-free: Options. 15711* -no-protect: Options. 15712* -oflow-byte: Options. 15713* -oflow-size: Options. 15714* -oflow-watch: Options. 15715* -page-alloc-lower: Options. 15716* -page-alloc-upper: Options. 15717* -preserve: Options. 15718* -prof: Options. 15719* -prof-file: Options. 15720* -prog-file: Options. 15721* -read-env: Options. 15722* -realloc-stop: Options. 15723* -safe-signals: Options. 15724* -show-all: Options. 15725* -show-env: Options. 15726* -show-free: Options. 15727* -show-freed: Options. 15728* -show-map: Options. 15729* -show-symbols: Options. 15730* -show-unfreed: Options. 15731* -sim-file: Tracing. 15732* -skip: The mpsym command. 15733* -small-bound: Options. 15734* -source: Tracing. 15735* -source-dir: The mpedit command. 15736* -space: Tracing. 15737* -stack-depth: Profiling. 15738* -threads: Options. 15739* -trace: Options. 15740* -trace-file: Options. 15741* -unalloc: Tracing. 15742* -unfreed-abort: Options. 15743* -use-debug: Options. 15744* -use-mmap: Options. 15745* -verbose: Tracing. 15746* -version: Options. 15747* -view-height: Tracing. 15748* -view-width: Tracing. 15749* -width: Tracing. 15750* .cshrc: The mpatrol command. 15751* .cvsignore: Files. 15752* .gdbinit: Using with a debugger. 15753* .profile: The mpatrol command. 15754* 32-bit: Building. 15755* 64-bit: Building. 15756* __mp_errno: Library functions. 15757* __mp_fini_ functions: Library functions. 15758* __mp_init_ functions: Library functions. 15759* _RLD_LIST: The mpatrol command. 15760* a.out: Examples. 15761* ABI: Call stacks and symbol tables. 15762* acknowledgements: Foreword. 15763* adding mpatrol: Adding mpatrol. 15764* address space: Tracing. 15765* address, physical: Virtual memory. 15766* address, virtual: Virtual memory. 15767* ADI: About the author. 15768* AIX, IBM RS/6000: Supported systems. 15769* alignment: Library behaviour. 15770* all (make target): Installation. 15771* alloca: Dynamic memory allocations. 15772* allocated blocks: Example 1. 15773* allocation algorithm: How it works. 15774* allocation bin table: Profiling. 15775* allocation bins: Profiling. 15776* allocation boundaries: Profiling. 15777* allocation byte: General errors. 15778* allocation index: Example 1. 15779* allocation information: Functions 6. 15780* allocation type: Example 1. 15781* ALLOCBYTE: Environment. 15782* ALLOCSTOP: Environment. 15783* ALLOVF: Diagnostic messages. 15784* ALLOWOFLOW: Environment. 15785* ALLZER: Diagnostic messages. 15786* AM_WITH_MPATROL: Adding mpatrol. 15787* amalloc: Improving performance. 15788* Amiga 4000/040: Installation. 15789* Amiga notes: Amiga notes. 15790* AmigaOS, Motorola 680x0: Supported systems. 15791* Aminet: Installation. 15792* Analog Devices: About the author. 15793* ANSI: Improving performance. 15794* application binary interface: Call stacks and symbol tables. 15795* AProbe: Related software. 15796* APurify: Related software. 15797* AR: Installation. 15798* ARCH: Building. 15799* archive library: Features. 15800* arenas: Improving performance. 15801* articles: References. 15802* assembler: Profiling. 15803* ATOM: Related software. 15804* author, contacting: Foreword. 15805* author, details: About the author. 15806* autoconf: Installation. 15807* automake: Installation. 15808* AutomatedQA: Related software. 15809* AUTOSAVE: Environment. 15810* backwards compatibility: Linking. 15811* BADALN: Diagnostic messages. 15812* base address: Tracing. 15813* bash: The mpatrol command. 15814* BASIC: Memory allocations. 15815* batch testing: Testing. 15816* best fit: How it works. 15817* BFD: Examples. 15818* bin: Profiling. 15819* binary: Environment. 15820* binary file: Profiling. 15821* bit bucket: Running. 15822* blocks: Example 1. 15823* BoundsChecker: Related software. 15824* breakpoint: Using with a debugger. 15825* bsdmalloc(3x): Related software. 15826* BSS: Static memory allocations. 15827* buffers, overflow: Overwrites and underwrites. 15828* bug reports: Foreword. 15829* bugs: Notes. 15830* building questions: Building. 15831* building the library: Installation. 15832* bus errors: Library behaviour. 15833* bytes compared: Example 1. 15834* bytes copied: Example 1. 15835* bytes located: Example 1. 15836* bytes set: Example 1. 15837* C: Memory allocations. 15838* C++: Memory allocations. 15839* C++ Debugging Support Library (libcwd): Related software. 15840* C++ mangled names: Example 1. 15841* call sites: Profiling. 15842* call stacks: Call stacks and symbol tables. 15843* call-by-value: Stack memory allocations. 15844* callback functions: Example 1. 15845* calling convention: Call stacks and symbol tables. 15846* CC: Installation. 15847* Ccmalloc: Related software. 15848* CenterLine Development Systems: Related software. 15849* CFLAGS: Installation. 15850* ChangeLog: Files. 15851* Chaperon: Related software. 15852* CHECK: Environment. 15853* CHECKALL: Environment. 15854* CHECKALLOCS: Environment. 15855* Checker: Related software. 15856* CHECKFORK: Environment. 15857* CHECKFREES: Environment. 15858* CHECKMEMORY: Environment. 15859* CHECKREALLOCS: Environment. 15860* CHECKSUMS: Installation. 15861* children: Profiling. 15862* CISC: Call stacks and symbol tables. 15863* clean (make target): Installation. 15864* cleanup: Installation. 15865* clobber (make target): Installation. 15866* CMEM: Related software. 15867* CMM (Customisable Memory Manager): Related software. 15868* COFF: Examples. 15869* command line options: Options. 15870* command pipe: Tracing. 15871* Commodore-Amiga, Inc.: Related software. 15872* common variables: Static memory allocations. 15873* compiler: Installation. 15874* compiling: Installation. 15875* condenseleaklog: The mleak command. 15876* configure: Installation. 15877* contacting the author: Foreword. 15878* context listing: The mpedit command. 15879* contributors: Foreword. 15880* core file: Running. 15881* corruption: Heap corruption. 15882* crash: Example 1. 15883* csh: The mpatrol command. 15884* CSRI malloc: Related software. 15885* CVS: Files. 15886* cycles: Profiling. 15887* data sections: Static memory allocations. 15888* Dbmalloc: dbmalloc. 15889* Debauch: Related software. 15890* Debian package: Installation. 15891* Debug Heap: Related software. 15892* debugger: Using with a debugger. 15893* debugging: Using with a debugger. 15894* debugging information: Call stacks and symbol tables. 15895* DebugObject: Related software. 15896* decimal: Environment. 15897* declarations, tentative: Static memory allocations. 15898* DEFALIGN: Environment. 15899* Dell Inspiron 7500: Installation. 15900* demangler: Example 1. 15901* DG/UX, Intel 80x86: Supported systems. 15902* DG/UX, Motorola 88xx0: Supported systems. 15903* diagnostic messages: Diagnostic messages. 15904* Digital Equipment Corporation: Related software. 15905* direct allocation table: Profiling. 15906* direct allocations: Profiling. 15907* distclean (make target): Installation. 15908* DLLs: Call stacks and symbol tables. 15909* Dmalloc: dmalloc. 15910* DocBook: Documentation. 15911* documentation: Installation. 15912* documentation formats: Documentation. 15913* documentation questions: Documentation. 15914* dot: Profiling. 15915* dotty: Profiling. 15916* DPCRTLMM: Related software. 15917* driver: Profiling. 15918* DRS/NX, SPARC: Supported systems. 15919* dumping memory: Example 4. 15920* duplicate symbols: Linking. 15921* DVI: Documentation. 15922* DWARF: How it works. 15923* dynamic link libraries: Call stacks and symbol tables. 15924* dynamic linker: Call stacks and symbol tables. 15925* dynamic linking: Call stacks and symbol tables. 15926* dynamic memory allocations: Dynamic memory allocations. 15927* DYNIX/ptx, Intel 80x86: Supported systems. 15928* DYNLINK: Building. 15929* Edinburgh: About the author. 15930* Edinburgh Portable Compilers: About the author. 15931* EDIT: Environment. 15932* EDITOR: The mpedit command. 15933* editor: The mpedit command. 15934* Electric Fence: Related software. 15935* Electric Software, Inc.: Related software. 15936* ELF32: Examples. 15937* ELF64: Examples. 15938* elvis: The mpedit command. 15939* emacs: The mpedit command. 15940* embedded libraries: The mpatrol command. 15941* embedded systems: Operating system support. 15942* endianness: Profiling. 15943* Enforcer: Related software. 15944* enhancements: Notes. 15945* entry-point: Example 1. 15946* ENVIRON: Building. 15947* environment: Environment. 15948* EPC: About the author. 15949* epilogue function: Example 1. 15950* error abbreviation code: Example 1. 15951* error severity: Example 1. 15952* errors: Diagnostic messages. 15953* errors, run-time: Overview. 15954* event: Tracing. 15955* examples: Examples. 15956* exec: Library behaviour. 15957* executable files: Call stacks and symbol tables. 15958* extensions: Tools. 15959* extern inline: Building. 15960* extra: Installation. 15961* FAILFREQ: Environment. 15962* FAILSEED: Environment. 15963* failure frequency: Testing. 15964* failure seed: Testing. 15965* FAQ: Frequently asked questions. 15966* fatal errors: Example 1. 15967* fault, page: Virtual memory. 15968* FDA (Free Debug Allocator): Related software. 15969* features: Features. 15970* fence posts: Overwrites and underwrites. 15971* file formats: File formats. 15972* file scope variables: Static memory allocations. 15973* files questions: Files. 15974* files, mapping: Virtual memory. 15975* first fit: How it works. 15976* fitting allocations: Example 3. 15977* foreword: Foreword. 15978* fork: Library behaviour. 15979* forked processes: Library behaviour. 15980* FORMAT: Building. 15981* format string: Profiling. 15982* Fortify: Related software. 15983* FORTRAN: Memory allocations. 15984* frame pointer: Running. 15985* FRDCOR: Diagnostic messages. 15986* FRDOPN: Diagnostic messages. 15987* FRDOVF: Diagnostic messages. 15988* FRECOR: Diagnostic messages. 15989* free blocks: Example 1. 15990* free byte: General errors. 15991* free memory: General errors. 15992* FreeBSD, Intel 80x86: Supported systems. 15993* FREEBYTE: Environment. 15994* freed blocks: Example 1. 15995* freed memory: General errors. 15996* freed queue: Example 1. 15997* FREESTOP: Environment. 15998* FREMRK: Diagnostic messages. 15999* FRENUL: Diagnostic messages. 16000* FREOPN: Diagnostic messages. 16001* frequently asked questions: Frequently asked questions. 16002* FreshMeat: Foreword. 16003* function call stacks: Call stacks and symbol tables. 16004* functions: Functions. 16005* functions, callback: Example 1. 16006* functions, handler: Example 1. 16007* future enhancements: Notes. 16008* g++: Example 1. 16009* Gabe's Debug Library: Related software. 16010* garbage collector: Dynamic memory allocations. 16011* GC (Garbage Collector): Related software. 16012* GCAlloc: Related software. 16013* gcc: Example 1. 16014* gdb: Using with a debugger. 16015* general errors: General errors. 16016* Geodesic Systems: Related software. 16017* getting updates: Foreword. 16018* GlowCode: Related software. 16019* GMemLogger: Related software. 16020* GNU C library: Related software. 16021* gprof: Profiling. 16022* graph: Profiling. 16023* graph specification file: Profiling. 16024* graphical user interface: Tracing. 16025* GraphViz: Profiling. 16026* Great Circle: Related software. 16027* Green Hills Software, Inc.: Related software. 16028* GUI: Tracing. 16029* GUISUP: Installation. 16030* halting the library: Using with a debugger. 16031* handler functions: Example 1. 16032* hash table: Leak table. 16033* HATF: Tracing. 16034* HAVE_MPALLOC: Adding mpatrol. 16035* HAVE_MPATROL: Adding mpatrol. 16036* heap: Dynamic memory allocations. 16037* Heap Allocation Trace Format: Tracing. 16038* heap corruption: Heap corruption. 16039* heap usage: Example 1. 16040* HeapAgent: Related software. 16041* HeapCheck: Related software. 16042* heapdiff: heapdiff. 16043* HeapManager: Related software. 16044* HELP: Environment. 16045* hexadecimal: Environment. 16046* hexwords: The hexwords command. 16047* hexwords command: The hexwords command. 16048* hidden memory: How it works. 16049* hints: Improving performance. 16050* HP/UX, HP PA/RISC: Supported systems. 16051* Hyperlearning Center: References. 16052* IBM Corporation: Related software. 16053* IDH: Related software. 16054* illegal memory accesses: Example 3. 16055* ILLMEM: Diagnostic messages. 16056* implementation details: How it works. 16057* improving performance: Improving performance. 16058* INCOMP: Diagnostic messages. 16059* INFOPATH: Documentation. 16060* information about an allocation: Functions 6. 16061* inline functions: Building. 16062* installation: Installation. 16063* instrumentation: Related software. 16064* Insure++: Related software. 16065* integration: Integration. 16066* internal blocks: Example 1. 16067* Intuitive Systems, Inc.: Related software. 16068* Inuse: Installation. 16069* IRIX, MIPS: Supported systems. 16070* JMalloc: Related software. 16071* JProbe: Related software. 16072* Kernel Group, The: Related software. 16073* KL Group: Related software. 16074* known bugs: Notes. 16075* ksh: The mpatrol command. 16076* LARGEBOUND: Environment. 16077* LaTeX: Installation. 16078* LD: Installation. 16079* LD_LIBRARY_PATH: Linking. 16080* LD_PRELOAD: The mpatrol command. 16081* LD_RUN_PATH: Linking. 16082* ldconfig: Installation. 16083* Leak: Related software. 16084* leak table: Leak table. 16085* LeakBug: Related software. 16086* Leakers: Related software. 16087* leaks: Memory leaks. 16088* LEAKTABLE: Environment. 16089* LeakTracer: Related software. 16090* Leaky: Related software. 16091* LessTif: Building. 16092* LhA archive: Installation. 16093* LibKmalloc: Related software. 16094* library behaviour: Library behaviour. 16095* library functions: Library functions. 16096* library settings: Logging and tracing. 16097* library statistics: Logging and tracing. 16098* library, archive: Features. 16099* library, building: Installation. 16100* library, mpatrol: Overview. 16101* library, shared: Features. 16102* library, thread-safe: Features. 16103* LibSafe: Related software. 16104* libtool: Installation. 16105* lifetime: Tracing. 16106* LIMIT: Environment. 16107* limitations: Notes. 16108* limiting available memory: Testing. 16109* line number table: Call stacks and symbol tables. 16110* linker: Installation. 16111* linking: Installation. 16112* linking questions: Linking. 16113* links, symbolic: Installation. 16114* lint: Installation. 16115* lint (make target): Installation. 16116* Linux Software Map: Installation. 16117* Linux, Intel 80x86: Supported systems. 16118* Linux, Motorola 680x0: Supported systems. 16119* LIST: Environment. 16120* list: The mpedit command. 16121* local static variables: Static memory allocations. 16122* log file: Example 1. 16123* LOGALL: Environment. 16124* LOGALLOCS: Environment. 16125* LOGDIR: Environment. 16126* LOGFILE: Environment. 16127* LOGFREES: Environment. 16128* logging: Logging and tracing. 16129* LOGMEMORY: Environment. 16130* LOGREALLOCS: Environment. 16131* low memory handler function: Example 1. 16132* LSM: Installation. 16133* LynxOS, Intel 80x86: Supported systems. 16134* LynxOS, PowerPC: Supported systems. 16135* magic: File formats. 16136* make: Installation. 16137* Makefile: Installation. 16138* Malloc Debug: Related software. 16139* Malloc Debug Library: Related software. 16140* malloc libraries for Solaris: Related software. 16141* malloc(3c): Related software. 16142* malloc(3x): Related software. 16143* Malloc_Dbg: Related software. 16144* MallocTrace: Related software. 16145* mallopt: The mpatrol command. 16146* MalTrace: Related software. 16147* mangled names: Example 1. 16148* MANPATH: Documentation. 16149* MANROFFSEQ: Documentation. 16150* manual layout: Foreword. 16151* manual pages: Installation. 16152* map of memory: Logging and tracing. 16153* mapmalloc(3x): Related software. 16154* mapping files: Virtual memory. 16155* Mark_Malloc: Related software. 16156* marked blocks: Example 1. 16157* MAXALN: Diagnostic messages. 16158* MCheck: Related software. 16159* md5sum: Installation. 16160* MEDIUMBOUND: Environment. 16161* MEM: Related software. 16162* MemCheck: Related software. 16163* MemDebug: Related software. 16164* MemLeak: Related software. 16165* Memory Advisor: Related software. 16166* memory allocation profiling: Profiling. 16167* memory allocation tracing: Tracing. 16168* memory allocations: Memory allocations. 16169* memory allocations, dynamic: Dynamic memory allocations. 16170* memory allocations, stack: Stack memory allocations. 16171* memory allocations, static: Static memory allocations. 16172* memory blocks: Example 1. 16173* memory debugger: Related software. 16174* memory dump: Example 4. 16175* memory leak table: Profiling. 16176* memory leaks: Memory leaks. 16177* memory management interface: Operating system support. 16178* Memory Management Reference: References. 16179* memory management unit: Virtual memory. 16180* memory map: Logging and tracing. 16181* memory mapped files: Virtual memory. 16182* memory protection: Virtual memory. 16183* Memory Sleuth: Related software. 16184* memory usage: Example 1. 16185* memory, physical: Virtual memory. 16186* memory, virtual: Virtual memory. 16187* Memprof: Related software. 16188* Memproof: Related software. 16189* MemTest: Related software. 16190* MemTrace: Related software. 16191* MemWatch: Related software. 16192* message passing: Threads. 16193* mgauge: mgauge. 16194* MicroQuill: Related software. 16195* Microsoft: Supported systems. 16196* misaligned data: Library behaviour. 16197* misaligned memory accesses: Virtual memory. 16198* MISMAT: Diagnostic messages. 16199* mkfifo: Tracing. 16200* mknod: Tracing. 16201* ML: Dynamic memory allocations. 16202* mleak: The mleak command. 16203* mleak command: The mleak command. 16204* MM (Shared Memory Library): Related software. 16205* Mmalloc: Related software. 16206* mmap: Library behaviour. 16207* MMU: Virtual memory. 16208* modules: How it works. 16209* Motif: Building. 16210* Mozilla: References. 16211* MP_ALIGN: Building. 16212* MP_BUILTINSTACK_SUPPORT: Call stacks and symbol tables. 16213* MP_DELETE: Functions 4. 16214* MP_GUI_SUPPORT: Building. 16215* MP_INLINE: Building. 16216* MP_LIBRARYSTACK_SUPPORT: Call stacks and symbol tables. 16217* MP_NEW: Functions 4. 16218* MP_NEW_NOTHROW: Functions 4. 16219* MP_NOCPLUSPLUS: Functions 4. 16220* MP_NONEWDELETE: Functions 4. 16221* MP_USE_ATEXIT: Running. 16222* mpatrol: Overview. 16223* mpatrol command: The mpatrol command. 16224* mpatrol features: Features. 16225* mpatrol library: Overview. 16226* mpatrol.h: Functions. 16227* mpatrol.log: Example 1. 16228* mpatrol.out: Profiling. 16229* mpatrol.trace: Tracing. 16230* MPATROL_OPTIONS: Environment. 16231* MPATROL_SOURCEPATH: The mpedit command. 16232* MPATROL_VERSION: Functions. 16233* mpdebug.h: Adding mpatrol. 16234* mpedit: The mpedit command. 16235* mpedit command: The mpedit command. 16236* MPR: Related software. 16237* Mprof: Related software. 16238* mprof: Profiling. 16239* mprof command: Profiling. 16240* mpsym: The mpsym command. 16241* mpsym command: The mpsym command. 16242* mptrace: Tracing. 16243* mptrace command: Tracing. 16244* MSS (Memory Supervision System): Related software. 16245* mtmalloc(3t): Related software. 16246* mtrace: mtrace. 16247* MuForce: Related software. 16248* MuGuardianAngel: Related software. 16249* MuLib: Related software. 16250* MULTI: Related software. 16251* multi-processor systems: Threads. 16252* Mungwall: Related software. 16253* mupdate: Files. 16254* mutexes: Threads. 16255* nano: The mpedit command. 16256* NDEBUG: Functions. 16257* Netware notes: Netware notes. 16258* NEWS: Files. 16259* NJAMD (Not Just Another Malloc Debugger): Related software. 16260* NOFREE: Environment. 16261* non-static local variables: Stack memory allocations. 16262* NOPROTECT: Environment. 16263* NOTALL: Diagnostic messages. 16264* notes: Notes. 16265* notes for all platforms: Generic notes. 16266* notes for Amiga platforms: Amiga notes. 16267* notes for Netware platforms: Netware notes. 16268* notes for UNIX platforms: UNIX notes. 16269* notes for Windows platforms: Windows notes. 16270* NULOPN: Diagnostic messages. 16271* NuMega Corporation: Related software. 16272* object files: Call stacks and symbol tables. 16273* ObjectCenter: Related software. 16274* OC Systems: Related software. 16275* octal: Environment. 16276* OFLAGS: Installation. 16277* OFLOWBYTE: Environment. 16278* OFLOWSIZE: Environment. 16279* OFLOWWATCH: Environment. 16280* Onyx Technology: Related software. 16281* operating systems: Operating system support. 16282* optimisation: Installation. 16283* Optimizeit: Related software. 16284* option summary: Environment. 16285* options: Options. 16286* original implementation: How it works. 16287* other programs: Related software. 16288* OUTMEM: Diagnostic messages. 16289* overflow buffers: Overwrites and underwrites. 16290* overflow byte: Overwrites and underwrites. 16291* overflow size: Overwrites and underwrites. 16292* overview: Overview. 16293* overwrites: Overwrites and underwrites. 16294* page: Virtual memory. 16295* page fault: Virtual memory. 16296* page size: Virtual memory. 16297* PAGEALLOC: Environment. 16298* pageheap: Related software. 16299* papers: References. 16300* parallel programming: Threads. 16301* parameter variables: Stack memory allocations. 16302* Parasoft: Related software. 16303* parents: Profiling. 16304* Pascal: Memory allocations. 16305* PATH: Linking. 16306* PE: Examples. 16307* peak memory usage: Example 1. 16308* performance bottleneck: Improving performance. 16309* performance improvements: Improving performance. 16310* performance times: Library performance. 16311* physical address: Virtual memory. 16312* physical memory: Virtual memory. 16313* pico: The mpedit command. 16314* pipe: Tracing. 16315* PKG package: Installation. 16316* platform-independent notes: Generic notes. 16317* platforms: Supported systems. 16318* PLATINUM Technology: Related software. 16319* Plumber: Related software. 16320* portability: Improving performance. 16321* porting: Porting. 16322* POSIX threads: Threads. 16323* postscript: Documentation. 16324* prelinker: Profiling. 16325* preprocessor: Profiling. 16326* PRESERVE: Environment. 16327* preserve freed contents: General errors. 16328* prevent freeing memory: General errors. 16329* printing: Installation. 16330* process id: Options. 16331* PROF: Environment. 16332* profdiff: Profiling. 16333* PROFDIR: Environment. 16334* PROFFILE: Environment. 16335* profiling: Profiling. 16336* profiling file format: Profiling file format. 16337* PROGFILE: Environment. 16338* program counter: Call stacks and symbol tables. 16339* programs: Related software. 16340* prologue function: Example 1. 16341* PRVFRD: Diagnostic messages. 16342* Purify: Related software. 16343* QC: Related software. 16344* questions: Frequently asked questions. 16345* quick reference card: Installation. 16346* random failures: Testing. 16347* Rational Software: Related software. 16348* re-entrancy: Threads. 16349* read protection: Virtual memory. 16350* REALLOCSTOP: Environment. 16351* recompilation: Adding mpatrol. 16352* recoverable errors: Example 1. 16353* Red Hat: Supported systems. 16354* reference card: Installation. 16355* references: References. 16356* registers: Stack memory allocations. 16357* related software: Related software. 16358* release builds: Foreword. 16359* removing mpatrol: Removing mpatrol. 16360* reporting bugs: Foreword. 16361* resources: References. 16362* return address: Call stacks and symbol tables. 16363* RISC: Call stacks and symbol tables. 16364* RNGOVF: Diagnostic messages. 16365* RNGOVL: Diagnostic messages. 16366* RPM package: Installation. 16367* RSZNUL: Diagnostic messages. 16368* RSZZER: Diagnostic messages. 16369* run-time errors: Overview. 16370* running questions: Running. 16371* SAFESIGNALS: Environment. 16372* SBase: Related software. 16373* sbrk: Library behaviour. 16374* SCID: Related software. 16375* Scotland: About the author. 16376* SD/UX package: Installation. 16377* sections: Static memory allocations. 16378* semaphores: Threads. 16379* Sentinel: Related software. 16380* settings: Logging and tracing. 16381* setup: Installation. 16382* severity of errors: Example 1. 16383* SFLAGS: Installation. 16384* shared libraries: Call stacks and symbol tables. 16385* shared library: Features. 16386* shared memory: Threads. 16387* SHOWALL: Environment. 16388* SHOWFREE: Environment. 16389* SHOWFREED: Environment. 16390* SHOWMAP: Environment. 16391* SHOWSYMBOLS: Environment. 16392* SHOWUNFREED: Environment. 16393* signal handler: Example 3. 16394* signals: Features. 16395* similar programs: Related software. 16396* simulation, trace-driven: Features. 16397* single-step: Using with a debugger. 16398* SINIX, MIPS: Supported systems. 16399* slot tables: Improving performance. 16400* SMALLBOUND: Environment. 16401* SmartAlloc: Related software. 16402* SmartHeap: Related software. 16403* software: Related software. 16404* Solaris malloc libraries: Related software. 16405* Solaris, Intel 80x86: Supported systems. 16406* Solaris, SPARC: Supported systems. 16407* source code documentation: Installation. 16408* SourceForge: Foreword. 16409* Spotlight: Related software. 16410* stack: Stack memory allocations. 16411* stack memory allocations: Stack memory allocations. 16412* stack tracebacks: Call stacks and symbol tables. 16413* stack unwinding: Call stacks and symbol tables. 16414* StackTrace: Related software. 16415* static inline: Building. 16416* static memory allocations: Static memory allocations. 16417* statistics: Logging and tracing. 16418* strace: Related software. 16419* Stratosware Corporation: Related software. 16420* stress testing: Improving performance. 16421* stripped executable file: Library behaviour. 16422* STROVF: Diagnostic messages. 16423* summary of options: Environment. 16424* supported systems: Supported systems. 16425* SuSE: Supported systems. 16426* SVR4: Examples. 16427* swap file: Virtual memory. 16428* swap in: Virtual memory. 16429* swap out: Virtual memory. 16430* swapping: Virtual memory. 16431* symbol summary: Logging and tracing. 16432* symbol tables: Call stacks and symbol tables. 16433* symbolic links: Installation. 16434* symbols: Call stacks and symbol tables. 16435* SYSTEM: Building. 16436* system page size: Virtual memory. 16437* systems: Supported systems. 16438* systems, embedded: Operating system support. 16439* TAR archive: Installation. 16440* TARGET: Building. 16441* tcsh: The mpatrol command. 16442* tentative declarations: Static memory allocations. 16443* test suite: Features. 16444* TestCenter: Related software. 16445* testing: Testing. 16446* TeXinfo: Installation. 16447* text editor: The mpedit command. 16448* TFLAGS: Installation. 16449* Third Degree: Related software. 16450* thrashing: Virtual memory. 16451* thread-safe library: Features. 16452* threads: Threads. 16453* threads library: Threads. 16454* times: Library performance. 16455* tips: Improving performance. 16456* tools: Tools. 16457* TRACE: Environment. 16458* trace-driven simulation: Features. 16459* tracebacks: Call stacks and symbol tables. 16460* TRACEDIR: Environment. 16461* TRACEFILE: Environment. 16462* tracing: Tracing. 16463* tracing file format: Tracing file format. 16464* tree structure: Example 2. 16465* Tru64, Alpha: Supported systems. 16466* truss: Related software. 16467* TurboPower: Related software. 16468* tutorial: Tutorial. 16469* type of allocation: Example 1. 16470* undefined symbols: Linking. 16471* underwrites: Overwrites and underwrites. 16472* unfreed allocations: Example 1. 16473* UNFREEDABORT: Environment. 16474* UNIX notes: UNIX notes. 16475* UnixWare, Intel 80x86: Supported systems. 16476* updates: Foreword. 16477* USEDEBUG: Environment. 16478* USEMMAP: Environment. 16479* using mpatrol: Using mpatrol. 16480* using with a debugger: Using with a debugger. 16481* utilities: Utilities. 16482* variable length arrays: Dynamic memory allocations. 16483* variables, file scope: Static memory allocations. 16484* variables, local static: Static memory allocations. 16485* variables, non-static local: Stack memory allocations. 16486* variables, parameter: Stack memory allocations. 16487* VAX: Profiling. 16488* VERSION: Files. 16489* vi: The mpedit command. 16490* vim: The mpedit command. 16491* virtual address: Virtual memory. 16492* virtual memory: Virtual memory. 16493* Virtual Memory Tutorial: References. 16494* Vmalloc: Related software. 16495* warnings: Diagnostic messages. 16496* warranty: Foreword. 16497* watch points: Virtual memory. 16498* watchmalloc(3x): Related software. 16499* Windows notes: Windows notes. 16500* Windows symbols setup: Linking. 16501* Windows, Intel 80x86: Supported systems. 16502* WinSite: Installation. 16503* Wipeout: Related software. 16504* write protection: Virtual memory. 16505* X Windows: Tracing. 16506* XANALYS Software Tools: References. 16507* XCOFF: Examples. 16508* xemacs: The mpedit command. 16509* xmem: Tracing. 16510* YaMa: Related software. 16511* YAMD (Yet Another Malloc Debugger): Related software. 16512* ZERALN: Diagnostic messages. 16513* ZeroFault: Related software. 16514* ZIP archive: Installation. 16515 16516 16517 16518Tag Table: 16519Node: Top1261 16520Node: Foreword3874 16521Node: Overview9864 16522Node: Features12856 16523Node: Installation35465 16524Ref: Installation-Footnote-143864 16525Node: Integration43996 16526Node: Adding mpatrol44458 16527Ref: Adding mpatrol-Footnote-152473 16528Node: Removing mpatrol52594 16529Node: Memory allocations55043 16530Node: Static memory allocations55720 16531Ref: Static memory allocations-Footnote-158181 16532Node: Stack memory allocations58223 16533Ref: Stack memory allocations-Footnote-160087 16534Node: Dynamic memory allocations60126 16535Ref: Dynamic memory allocations-Footnote-163548 16536Ref: Dynamic memory allocations-Footnote-263667 16537Node: Operating system support63771 16538Node: Virtual memory65731 16539Ref: Virtual memory-Footnote-171759 16540Ref: Virtual memory-Footnote-272015 16541Ref: Virtual memory-Footnote-372191 16542Ref: Virtual memory-Footnote-472226 16543Ref: Virtual memory-Footnote-572285 16544Node: Call stacks and symbol tables72509 16545Ref: Call stacks and symbol tables-Footnote-178187 16546Ref: Call stacks and symbol tables-Footnote-278255 16547Ref: Call stacks and symbol tables-Footnote-378306 16548Ref: Call stacks and symbol tables-Footnote-478350 16549Ref: Call stacks and symbol tables-Footnote-578392 16550Ref: Call stacks and symbol tables-Footnote-678434 16551Ref: Call stacks and symbol tables-Footnote-778482 16552Node: Threads78588 16553Ref: Threads-Footnote-184594 16554Node: Using mpatrol84689 16555Node: Library behaviour85551 16556Ref: Library behaviour-Footnote-192771 16557Node: Logging and tracing92829 16558Node: General errors98514 16559Node: Overwrites and underwrites102791 16560Ref: Overwrites and underwrites-Footnote-1111230 16561Ref: Overwrites and underwrites-Footnote-2111293 16562Node: Using with a debugger111417 16563Ref: Using with a debugger-Footnote-1120823 16564Ref: Using with a debugger-Footnote-2120891 16565Ref: Using with a debugger-Footnote-3121147 16566Node: Testing121236 16567Ref: Testing-Footnote-1123973 16568Ref: Testing-Footnote-2124154 16569Node: Library functions124213 16570Ref: Library functions-Footnote-1146154 16571Node: Leak table146262 16572Node: Tools153248 16573Node: dbmalloc155094 16574Ref: dbmalloc-Footnote-1158285 16575Node: dmalloc158346 16576Ref: dmalloc-Footnote-1162174 16577Node: heapdiff162230 16578Node: mgauge164420 16579Node: mtrace165826 16580Node: Utilities166352 16581Node: The mpatrol command167318 16582Ref: The mpatrol command-Footnote-1174012 16583Ref: The mpatrol command-Footnote-2174146 16584Node: The mleak command174226 16585Node: The mpsym command176915 16586Node: The mpedit command179677 16587Node: The hexwords command183099 16588Node: Profiling186452 16589Ref: Profiling-Footnote-1214311 16590Ref: Profiling-Footnote-2214448 16591Ref: Profiling-Footnote-3214672 16592Node: Tracing214776 16593Ref: Tracing-Footnote-1236428 16594Ref: Tracing-Footnote-2236462 16595Node: Heap corruption236568 16596Node: Memory leaks252034 16597Ref: Memory leaks-Footnote-1259698 16598Node: Improving performance259796 16599Ref: Improving performance-Footnote-1269263 16600Ref: Improving performance-Footnote-2269305 16601Ref: Improving performance-Footnote-3269382 16602Ref: Improving performance-Footnote-4269454 16603Ref: Improving performance-Footnote-5269550 16604Node: How it works269594 16605Node: Examples277302 16606Node: Example 1281299 16607Ref: Example 1-Footnote-1306680 16608Node: Example 2306870 16609Node: Example 3312364 16610Node: Example 4319939 16611Node: Example 5323664 16612Node: Example 6326056 16613Ref: Example 6-Footnote-1329856 16614Node: Example 7329985 16615Node: Example 8331843 16616Node: Example 9342044 16617Node: Example 10346438 16618Node: Tutorial362722 16619Ref: Tutorial-Footnote-1377783 16620Ref: Tutorial-Footnote-2378074 16621Ref: Tutorial-Footnote-3378223 16622Ref: Tutorial-Footnote-4378360 16623Ref: Tutorial-Footnote-5378459 16624Node: Functions378740 16625Node: Functions 1380622 16626Node: Functions 2398211 16627Node: Functions 3401984 16628Node: Functions 4407068 16629Node: Functions 5410730 16630Node: Functions 6416583 16631Node: Environment438247 16632Node: Options459978 16633Node: Diagnostic messages472072 16634Node: Library performance490026 16635Node: File formats492475 16636Ref: File formats-Footnote-1492899 16637Node: Profiling file format493111 16638Node: Tracing file format496373 16639Node: Supported systems500308 16640Node: Porting517319 16641Ref: Porting-Footnote-1544296 16642Ref: Porting-Footnote-2544505 16643Ref: Porting-Footnote-3544647 16644Node: Notes544805 16645Node: Generic notes546407 16646Ref: Generic notes-Footnote-1567583 16647Ref: Generic notes-Footnote-2567801 16648Ref: Generic notes-Footnote-3568023 16649Ref: Generic notes-Footnote-4568186 16650Ref: Generic notes-Footnote-5568255 16651Node: UNIX notes568472 16652Ref: UNIX notes-Footnote-1573083 16653Node: Amiga notes573300 16654Node: Windows notes576964 16655Node: Netware notes578899 16656Node: Frequently asked questions581459 16657Node: Documentation582082 16658Node: Building586837 16659Node: Linking596850 16660Node: Running603500 16661Node: Files619891 16662Node: Related software623107 16663Ref: Related software-Footnote-1666448 16664Node: References666689 16665Node: About the author670447 16666Node: Copying672686 16667Node: Function index700581 16668Node: Index705405 16669 16670End Tag Table 16671
