< Previous PageNext Page > Hide TOC

Enabling the Malloc Debugging Features

The malloc library provides debugging features to help you track down memory smashing bugs, heap corruption, references to freed memory, and buffer overruns. You enable these debugging options through a set of environment variables. With the exception of MallocCheckHeapStart and MallocCheckHeapEach, the value for most of these environment variables is ignored. To disable a variable from Terminal, use the unsetenv command. Table 1 lists some of the key environment variables and describes their basic function. For a complete list of variables, see the malloc man page.

Table 1  Malloc environment variables

Variable

Description

MallocStackLogging

If set, malloc remembers the function call stack at the time of each allocation.

MallocStackLoggingNoCompact

This option is similar to MallocStackLogging but makes sure that all allocations are logged, no matter how small or how short lived the buffer may be.

MallocScribble

If set, free sets each byte of every released block to the value 0x55.

MallocPreScribble

If set, malloc sets each byte of a newly allocated block to the value 0xAA. This increases the likelihood that a program making assumptions about freshly allocated memory fails.

MallocGuardEdges

If set, malloc adds guard pages before and after large allocations.

MallocDoNotProtectPrelude

Fine-grain control over the behavior of MallocGuardEdges: If set, malloc does not place a guard page at the head of each large block allocation.

MallocDoNotProtectPostlude

Fine-grain control over the behavior of MallocGuardEdges: If set, malloc does not place a guard page at the tail of each large block allocation.

MallocCheckHeapStart

Set this variable to the number of allocations before malloc will begin validating the heap. If not set, malloc does not validate the heap.

MallocCheckHeapEach

Set this variable to the number of allocations before malloc should validate the heap. If not set, malloc does not validate the heap.

The following example enables stack logging and heap checking before running an application. The value for MallocCheckHeapStart is set to 1 but is irrelevant and can be set to any value you want. You could also set these variables from you shell’s startup file.

% setenv MallocStackLogging 1
% setenv MallocCheckHeapStart 1000
% setenv MallocCheckHeapEach 100
% ./my_tool

If you want to run your program in gdb, you can set environment variables from the Xcode debugging console using the command set env, as shown in the following example:

% gdb
(gdb) set env MallocStackLogging 1
(gdb) run

Some of the performance tools require these options to be set in order to gather their data. For example, the malloc_history tool can identify the allocation site of specific blocks if the MallocStackLogging flag is set. This tool can also describe the blocks previously allocated at an address if the MallocStackLoggingNoCompact environment variable is set. The leaks command line tool will name the allocation site of a leaked buffer if MallocStackLogging is set. See the man pages for leaks and malloc_history for more details.

Contents:

Detecting Double Freed Memory
Detecting Heap Corruption
Detecting Memory Smashing Bugs


Detecting Double Freed Memory

The malloc library reports attempts to call free on a buffer that has already been freed. If you have set the MallocStackLoggingNoCompact option set, you can use the logged stack information to find out where in your code the second free call was made. You can then use this information to set up an appropriate breakpoint in the debugger and track down the problem.

The malloc library reports information to stderr.

Detecting Heap Corruption

To enable heap checking, assign values to the MallocCheckHeapStart and MallocCheckHeapEach environment variables. You must set both of these variables to enable heap checking. The MallocCheckHeapStart variable tells the malloc library how many malloc calls to process before initiating the first heap check. Set the second to the number of malloc calls to process between heap checks.

The MallocCheckHeapStart variable is useful when the heap corruption occurs at a predictable time. Once it hits the appropriate start point, the malloc library starts logging allocation messages to the Terminal window. You can watch the number of allocations and use that information to determine approximately where the heap is being corrupted. Adjust the values for MallocCheckHeapStart and MallocCheckHeapEach as necessary to narrow down the actual point of corruption.

Detecting Memory Smashing Bugs

To find memory smashing bugs, enable the MallocScribble variable. This variable writes invalid data to freed memory blocks, the execution of which causes an exception to occur. When using this variable, you should also set the MallocStackLogging and MallocStackLoggingNoCompact variables to log the location of the exception. When the exception occurs, you can then use the malloc_history command to track down the code that allocated the memory block. You can then use this information to track through your code and look for any lingering pointers to this block.



< Previous PageNext Page > Hide TOC


© 2003, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-06-28)


Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.