|
|
This manual page is part of Xcode Tools version 3.2To obtain these tools:
If you are running a version of Xcode Tools other than 3.2, view the documentation locally:
Reading manual pagesManual pages are intended as a quick reference for people who already understand a technology.
|
libgmalloc.dylib(3) BSD Library Functions Manual libgmalloc.dylib(3)
NAME
libgmalloc.dylib -- (Guard Malloc), an aggressive debugging malloc library
DESCRIPTION
libgmalloc is a debugging malloc library that can track down insidious bugs in your code or library.
If your application crashes when using libgmalloc, then you've found a bug.
libgmalloc uses the virtual memory system to identify such bugs. Each malloc allocation is placed on
its own virtual memory page, with the end of the buffer at the end of the page's memory, and the next
page is kept unallocated. As a result, accesses beyond the end of the buffer cause a bus error immedi-ately. immediately.
ately. When memory is freed, libgmalloc deallocates its virtual memory, causing reads or writes to the
freed buffer cause a bus error. Thus, nasty, hard-to-track-down bugs are immediately obvious, and
you'll know exactly which code is causing the problem. This is thread-safe and works for all uses of
malloc(), NSZoneMalloc(), and friends.
As of Mac OS X 10.5, libgmalloc aligns the start of allocated buffers on 16-byte boundaries by default,
to allow proper use of vector instructions (e.g., SSE or Altivec). (The use of vector instructions is
becoming more common, including in some Mac OS X system libraries. The regular system malloc also uses
16-byte alignment.) Because of this 16-byte alignment, up to 15 bytes at the end of an allocated block
may be excess at the end of the page, and libgmalloc will not detect buffer overruns into that area by
default. This default alignment can be changed with environment variables.
libgmalloc is available in /usr/lib/libgmalloc.dylib. To use it, set this environment variable:
set DYLD_INSERT_LIBRARIES to /usr/lib/libgmalloc.dylib
Note: it is no longer necessary to set DYLD_FORCE_FLAT_NAMESPACE.
This tells dyld to use Guard Malloc instead of the standard version of malloc. Run the program, and
wait for the crash indicating the bad access. When the program crashes, examine it in the debugger to
identify the cause.
As of Mac OS X 10.6, libgmalloc can be used with the standard malloc stack logging by setting the Mal-locStackLogging MallocStackLogging
locStackLogging environment variable. The malloc_history(1) command can then be used to show back-traces backtraces
traces of all malloc and free events made when using libgmalloc.
USING libgmalloc WITH THE XCODE DEBUGGER OR GDB
Because the goal of libgmalloc is to "encourage" your application to crash if memory access errors
occur, it is best to run your application under a debugger such as the Xcode IDE's debugger, or gdb at
the command line.
To use Guard Malloc with the Xcode debugger, choose the "Enable Guard Malloc" menu item from the Debug
menu before launching your executable for debugging. That automatically sets the environment variables
properly. Xcode retains that setting with that executable. If you need to set any of the additional
environment variables described below, select your executable in the Groups & Files outline, then bring
up the Executable Inspector. Choose the Arguments tab, and add the environment variable to the envi-ronment environment
ronment variables list.
If you're using gdb from the command line, use gdb's 'set env' command to set the environment vari-ables. variables.
ables.
EXAMPLE
% cat gmalloctest.c
#include <stdlib.h>
#include <stdio.h>
main()
{
unsigned *buffer = (unsigned *)malloc(sizeof(unsigned) * 100);
unsigned i;
for (i = 0; i < 200; i++) {
buffer[i] = i;
}
for (i = 0; i < 200; i++) {
printf ("%d ", buffer[i]);
}
}
% cc -g -o gmalloctest gmalloctest.c
% gdb gmalloctest
Reading symbols for shared libraries .. done
(gdb) set env DYLD_INSERT_LIBRARIES /usr/lib/libgmalloc.dylib
(gdb) r
Starting program: gmalloctest
Reading symbols for shared libraries .. done
GuardMalloc: Allocations will be placed on 16 byte boundaries.
GuardMalloc: - Some buffer overruns may not be noticed.
GuardMalloc: - Applications using vector instructions (e.g., SSE or Altivec) should work.
GuardMalloc: GuardMalloc version 19
Program received signal EXC_BAD_ACCESS, Could not access memory.
Reason: KERN_PROTECTION_FAILURE at address: 0xb000d000
0x00001f65 in main () at gmalloctest.c:10
10 buffer[i] = i;
(gdb) print i
$1 = 100
(gdb) where
#0 0x00001f65 in main () at gmalloctest.c:10
(gdb)
Once you have the backtrace, you can examine that line of source code to see what variable would have
been accessed, and determine why that value would have been invalid memory. If you looked at the
source for the example above, you might find that this function looks one character too far beyond the
string it's operating on and causes a bus error when accessing the protected page following the string.
These sorts of problems may seem minor, especially when the application normally behaves correctly.
However, they're usually the hallmark of intermittent bugs or unexplained crashes in long running pro-
grams. In normal use, the bug in the example program might have caused no problems at all... or it
might have trashed the following buffer, leading occasionally to corrupted data. If the application
had been referencing freed memory, the program might have worked fine until the one time where the
freed memory was immediately reused and modified.
ENVIRONMENT
libgmalloc's behavior can be changed with several additional environment variables:
MALLOC_PROTECT_BEFORE If this flag is set, then libgmalloc tries harder to detect buffer
underruns. Specifically, libgmalloc places the malloc-allocated buffer
at the beginning of a virtual memory page, then protects the page
before. Buffer underruns then cause an error. The behavior without
this variable set would be to place the buffer at the end of the page,
and protect the page after.
MALLOC_FILL_SPACE This flag causes libgmalloc to fill the buffer with 0x55 upon creation.
This can help catch uninitialized memory problems.
MALLOC_ALLOW_READS This flag allows the guard page after the buffer to be readable so that
reads past the ends of buffers do not cause the program to crash. With
the MALLOC_PROTECT_BEFORE flag set, this command instead sets the guard
page before the buffer to be readable.
MALLOC_VECTOR_SIZE This option is the default alignment, as of Mac OS X 10.5. With this
option, Guard Malloc places allocations on 16 byte boundaries, because
vector instructions (e.g., SSE or Altivec) require buffers to be on 16
byte boundaries. (The use of vector instructions is becoming more com-mon common
mon in some Mac OS X system libraries.) MALLOC_VECTOR_SIZE is now the
preferred name of this environment variable; the older MAL-LOC_ALTIVEC_SIZE MALLOC_ALTIVEC_SIZE
LOC_ALTIVEC_SIZE is deprecated but supported for backward compatibility.
MALLOC_WORD_SIZE This flag specifies that Guard Malloc should place allocations on word
(4-byte) boundaries, with the end of the buffer on the last 4 bytes of
the page. This option is useful because Carbon assumes that pointers
are word aligned, and without the word alignment, any program relying on
Cocoa or Carbon would immediately crash.
MALLOC_STRICT_SIZE This flag specifies that Guard Malloc should always align all alloca-tions allocations
tions on single-byte boundaries such that the last byte of the buffer is
at the end of the page. This will immediately catch even one-byte
buffer overruns, but applications that use Carbon or Cocoa, or vector
instructions, may not run properly with this option.
MALLOC_PERMIT_INSANE_REQUESTS GuardMalloc tries to protect against requests for insane amounts of mem-ory memory
ory by instructing the program to trap (if running under the debugger)
if more than 100MB is requested. If this environment variable is set,
then the check is disabled.
MALLOC_CHECK_HEADER This flag is enabled by default, which causes Guard Malloc to check the
validity of a magic number in the malloc block header when a block is
freed or reallocated. To turn off this checking, set this environment
variable to NO or 0.
MALLOC_NO_BACKTRACE By default when a block is allocated with malloc() or realloc(), Guard
Malloc records twenty frames of the backtrace at which the allocation
occurred. Set this environment variable to disable that recording of
the backtraces.
MallocStackLogging If this flag is set, then standard system malloc stack logging is
enabled. The malloc_history(1) command can then be used to show back-traces backtraces
traces of all malloc and free events made when using libgmalloc. The
use of MallocStackLogging is independent of the stack backtraces that
libgmalloc records with the allocated blocks themselves (see below), and
which are controlled by MALLOC_NO_BACKTRACE.
MEMORY VALUES USED BY GUARD MALLOC
It's often useful to understand how Guard Malloc uses memory when debugging. Guard Malloc writes
strange byte sequences to catch certain problems. If the MALLOC_FILL_SPACE environment variable is
set, newly allocated buffers will be filled with the value 0x55 in hopes of catching references to
uninitialized memory.
The space right before the buffer is dedicated to header information. The header is organized as:
size of buffer + size of header (0x60 + requested size rounded to appropriate boundary)
thread id
stack backtrace where allocation occurred (twenty frames; longer stack traces are truncated, and
smaller stack traces will leave the unused frames zeroed.)
magic number (0xdeadbeef)
beginning of buffer
CAVEATS
libgmalloc doesn't come without some weaknesses. First, because each allocation requires two pages of
virtual memory, only about 500,000 malloc allocations could conceivably exist before you run out of
virtual memory. The extravagant use of virtual memory will also cause much more swapping, so the pro-gram program
gram will run much slower than usual -- usually two orders of magnitude (100x).
In addition, the extra pressure on the virtual memory system when running an application with Guard
Malloc can cause top(1) to update its output more slowly.
Don't forget -- if there's a memory bug in your program, the program will crash in Guard Malloc. This
is a feature!
SEE ALSO
malloc_history(1)
Mac OS X Mar. 10, 2009 Mac OS X
|
The way to report a problem with this manual page depends on the type of problem: