[Previous] [Contents] [Index] [Next]

mallopt()

Control the extra checking for memory allocation

Note: The debug version of this function is declared in <rcheck/malloc.h>. The debug version includes additional commands and settings that aren't in <malloc/malloc.h>. To use debug mallopt(), you need to link with librcheck.so or use LD_PRELOAD=librcheck.so at runtime.

Synopsis:

#include <malloc/malloc.h>

int mallopt( int cmd,
             int value );

Arguments:

cmd
The command or setting you wish to make. The normal and debug version of mallopt() both support the following:

The debug version also supports the following (which the normal version ignores):

value
A value corresponding to the command.

For more information about the commands and their possible values, see below.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The mallopt() function controls memory allocation; the debug version also controls the extra checking of memory allocation.

You can set some of the variables by using environment variables, as listed below. This is an easy way to control the memory allocation, but the environment variables are checked only when your program starts.

For more information about memory allocation and debugging it, see the Heap Analysis: Making Memory Errors a Thing of the Past chapter of the Neutrino Programmer's Guide.

Controlling memory allocation

MALLOC_ARENA_SIZE
The size of the arena, a chunk of memory that the memory allocator allocates and deallocates from the system. This value must be a multiple of 4 KB, and currently is limited to being less than 256 KB. Environment variable: MALLOC_ARENA_SIZE.

If value is 0, mallopt() returns the current arena size; if value is any other value, mallopt() returns the previous size.

MALLOC_ARENA_CACHE_FREE_NOW
Specify a value of 1 to cause the arena cache to be adjusted immediately. If MALLOC_ARENA_CACHE_FREE_NOW is 0, the changes made to the cache parameters take effect whenever memory is subsequently released to the cache.
MALLOC_ARENA_CACHE_MAXBLK
The number of cached arena blocks. Environment variable: MALLOC_ARENA_CACHE_MAXBLK.
MALLOC_ARENA_CACHE_MAXSZ
The total size of the cached arena blocks. Environment variable: MALLOC_ARENA_CACHE_MAXSZ.
MALLOC_FREE_CHECK
Specify a value of 1 to tell the library to check to see if a block that's being passed to free() has already been freed. This option is available only when you're using libmalloc (the regular version or the debug version of libmalloc.so). If you're using libmalloc.so, and you enable this option, then if you try to free a block that's already freed, the library calls assert().
MALLOC_MEMORY_HOLD
Specify a value of 1 to tell the allocator to never release memory back to the system from its arena cache. Environment variable: MALLOC_MEMORY_HOLD.
MALLOC_STATS
Get statistics about the current state of the heap allocator. The value argument is a pointer to a struct malloc_stats (defined in <malloc.h>). You need to allocate the memory for the structure. The typical usage is as follows: 
struct malloc_stats ms;
...
mallopt(MALLOC_STATS, &ms);
MALLOC_VERIFY_ON
Specify a value of 1 to enable additional checking on operations involving the heap. When this option is enabled, operations through the allocator go through additional verification. If any of the verifications of the state of the heap fail, the allocator calls assert(). This command is available only when you're using libmalloc (the regular version or the debug version of libmalloc.so).

Controlling extra checking

If you're using the debug version of mallopt(), you can use the following options to control additional checks in the library:

MALLOC_CKACCESS
Turn on (or off) boundary checking for memory and string operations.
Environment variable: MALLOC_CKACCESS.

The value argument can be:

MALLOC_CKALLOC
Turn on (or off) the argument checking for *alloc() and free() functions.
Environment variable: MALLOC_CKALLOC.

The value argument can be:

MALLOC_CKBOUNDS
Turn on (or off) fill-area boundary checking.
Environment variable: MALLOC_CKBOUNDS.

The value argument can be:

MALLOC_CKCHAIN
Enable (or disable) full-chain checking. For each of the above options, an integer argument value of one indicates that the given type of checking should be enabled from that point onward.
Environment variable: MALLOC_CKCHAIN.

The value argument can be:

MALLOC_DUMP_LEAKS
Enable leak detection on process exit if it's set. This option controls additional checks in the library and its purpose is only for the environment variable; not for the API constant.
Environment variable: MALLOC_DUMP_LEAKS.

The value argument can be:

MALLOC_EVENTBTDEPTH
Set the size of the backtrace to report for memory problems. The default size is 5.
Environment variable: MALLOC_EVENTBTDEPTH.
MALLOC_START_TRACING
Enable (disable) the automatic tracing of memory when the application starts. If tracing isn't enabled when application starts, at this point it can be enabled by using only the API, or the control thread interface (see the “Create control thread” option in the Analyzing a running program topic in the Analyzing Memory Usage and Finding Errors chapter of the IDE User's Guide.)
Environment variable: MALLOC_START_TRACING.

The value argument can be:

MALLOC_TRACEMIN
Set the integer value to determine the number of the minimum size of allocations to track; only trace the allocations greater than or equal to the minimum number specified (in bytes).
Environment variable: MALLOC_TRACEMIN.
MALLOC_TRACEMAX
Set the integer value to determine the number of the maximum size of allocations to track; only trace the allocations to that less than or equal to the maximum number specified (in bytes). Specify 0 to indicate an unlimited number of allocations.
Environment variable: MALLOC_TRACMAX.
MALLOC_TRACEBTDEPTH
Set the size of the backtrace stored for allocations. The default size is 5.
Environment variable: MALLOC_TRACEBTDEPTH.
MALLOC_TRACING
Turn on (or off) the tracing of allocations.
Environment variable: MALLOC_TRACING.
MALLOC_VERIFY
Perform a chain check. If an error is found, perform error handling. The value argument is currently ignored; pass 1 for it.
MALLOC_FATAL
Specify the malloc fatal handler.
Environment variable: MALLOC_FATAL.

Use one of the following for the value arguments:

Symbolic name Value Description
M_HANDLE_IGNORE 0 Cause the program to dump a core file.
M_HANDLE_ABORT 1 Terminate execution with a call to abort()
M_HANDLE_EXIT 2 Exit immediately
M_HANDLE_CORE 3 Cause the program to dump a core file
M_HANDLE_SIGNAL 4 Stop the program when this error occurs
MALLOC_WARN
Specify the malloc warning handler. The values are similar to MALLOC_FATAL; see above.
Environment variable: MALLOC_WARN.

For details, see “Controlling the level of checking” in the Heap Analysis: Making Memory Errors a Thing of the Past chapter of the Neutrino Programmer's Guide.

Returns:

0 on success, or -1 if an error occurs (errno is set).

For MALLOC_ARENA_SIZE, if value is 0, mallopt() returns the current arena size; if value is any other value, mallopt() returns the previous size.

Classification:

QNX Neutrino

Safety:
Cancellation point No
Interrupt handler No
Signal handler No
Thread Yes

See also:

calloc(), free(), mallinfo(), malloc(), realloc()

Heap Analysis: Making Memory Errors a Thing of the Past chapter of the Neutrino Programmer's Guide

[Previous] [Contents] [Index] [Next]