M Parent topic: M

mallopt()

Control memory allocation and the extra checking for it

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

Synopsis:

#include <malloc.h>

int mallopt( int cmd,
             intptr_t value );

Arguments:

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

The debug version also supports the following:

The normal version returns -1 and sets errno to EINVAL if you pass it one of the debug commands.

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.

Controlling memory allocation

As described in the Heap Analysis chapter of the QNX Neutrino Programmer's Guide, the memory allocator requests memory from the OS in chunks called arenas and can cache freed blocks instead of releasing them back to the OS. The libc version of mallopt() supports these commands that control how allocation is done:

MALLOC_ARENA_CACHE_FREE_NOW
Specify when changes to the arena cache occur:
  • If the value argument is 1, the arena cache is adjusted immediately, and all cached memory that can be freed to the OS is released. Exactly what can be freed depends on how the allocations up to that point have been laid out in memory.
  • If value is 0, the arena cache is adjusted immediately to correspond to the current settings. Enough cache blocks are freed to match the adjusted MALLOC_ARENA_CACHE_MAXBLK value.

If you don't use this command, changes made to the cache parameters take effect whenever memory is subsequently released to the cache.

MALLOC_ARENA_CACHE_MAXBLK
The maximum number of cached blocks. The default value is 12.

Environment variable: MALLOC_ARENA_CACHE_MAXBLK. If you set this environment variable to 0, it's ignored.

If you don't want the allocator to cache any memory cached all, specify a value of 0. This would adversely affect performance, as you'd go to the OS more often for memory, but the heap wouldn't hold on to as much memory.

MALLOC_ARENA_CACHE_MAXSZ
The maximum size of the cache, in bytes. The default is 0, indicating no maximum.

Environment variable: MALLOC_ARENA_CACHE_MAXSZ. If you set this environment variable to 0, it's ignored.

MALLOC_ARENA_SIZE
The size, in bytes, of arenas that are subsequently allocated. This size must be a multiple of 4 KB, and currently is limited to being less than 256 KB. Lowering the arena size can reduce the amount of memory required. The default is 32 KB.

Environment variable: MALLOC_ARENA_SIZE

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

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. If you enable this option, then if you try to free a block that's already freed, the library aborts the program.
MALLOC_MAX_ALIGNMENT
Set the maximum allowable alignment size, as used by memalign() and posix_memalign(). The default is 128 KB. The size used is the largest power of two that's less than or equal to value.
MALLOC_MEMORY_HOLD
Specify a value of 1 to tell the allocator to never release memory back to the OS. In this case, the heap never shrinks. The default behavior is not to hold the memory.

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
Perform a chain check, traversing the entire set of allocation chains for all arenas and blocks in the heap. If an error is found, the allocator aborts the program. The value argument is currently ignored; pass 1 for it.
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 aborts the program.

Controlling extra checking

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

MALLOC_CKACCESS
Turn on (1) or off (0) boundary checking for memory and string operations, depending on the value argument. For more information, see “Controlling the level of checking” in the Heap Analysis chapter of the QNX Neutrino Programmer's Guide,

Environment variable: MALLOC_CKACCESS

MALLOC_CKALLOC
Turn on (1) or off (0) pointer checking for realloc() and free(), depending on the value argument. If this is on, the allocator makes sure that the pointers you pass to these functions point to memory that it manages.

Environment variable: MALLOC_CKALLOC

MALLOC_CKBOUNDS
Turn on (1) or off (0) fill-area boundary checking, depending on the value argument. For more information, see “Controlling the level of checking” in the Heap Analysis chapter of the QNX Neutrino Programmer's Guide,

Environment variable: MALLOC_CKBOUNDS

MALLOC_CKCHAIN
Enable (1) or disable (0) full-chain checking, depending on the value argument. For more information, see “Controlling the level of checking” in the Heap Analysis chapter of the QNX Neutrino Programmer's Guide,

Environment variable: MALLOC_CKCHAIN

MALLOC_CTRL_CMD
(QNX Neutrino 6.6 or later) Execute the command that the value points to. This command is a convienient way to process non-API commands received from a socket or file.
Note: The library modifies the given string.

The value argument is a string containing one of the following commands (some of which correspond to a mallopt() command), followed by the appropriate argument:

String command Argument mallopt() command
check_access 0 or 1 MALLOC_CKACCESS
check_alloc 0 or 1 MALLOC_CKALLOC
check_chain 0 or 1 MALLOC_CKCHAIN
check_bounds An integer MALLOC_CKBOUNDS
event_file A filename MALLOC_EVENTFILE
event_dump_unref None None; list the leak events
event_btdepth An integer MALLOC_EVENTBTDEPTH
ldd_replay None None; replay the loading of all DLLs
dump_leaks None MALLOC_DUMP_LEAKS
trace_file A filename MALLOC_TRACEFILE
truncate_files An integer MALLOC_TRUNCATE
tracing_enabled 0 or 1 MALLOC_TRACING
trace_btdepth An integer MALLOC_TRACEBTDEPTH
trace_min An integer MALLOC_TRACEMIN
trace_max An integer MALLOC_TRACEMAX
trace_dump_all A filename None; dump all traces
trace_dump_alloc A filename None; dump all allocations
trace_dump_alloc_state A filename None; dump the allocation statistics
trace_dump_free A filename None; dump all deallocations
trace_dump_unref A filename MALLOC_DUMP_LEAKS
verbose An integer MALLOC_VERBOSE
set_action An integer MALLOC_WARN, MALLOC_FATAL
MALLOC_CTRL_CMD_FILE
(QNX Neutrino 6.6 or later) Execute a control command (see MALLOC_CTRL_CMD) from the specified file. If you include ${pid} in the filename, the library replaces it with the process ID.

Environment variable: MALLOC_CTRL_FILE

MALLOC_DUMP_LEAKS
List the leak events. The value argument is ignored.

Environment variable: MALLOC_DUMP_LEAKS, which enables (1) or disables (0) leak detection when the process exits, depending on the value.

MALLOC_DUMP_STATS
(QNX Neutrino 6.6 or later) Dump statistics.
MALLOC_EVENTBTDEPTH
Set the depth of the backtrace for allocations (i.e., where the allocation occurred) on CPUs that support deeper backtrace levels. Currently the builtin-return-address feature of gcc is used to implement deeper backtraces for the librcheck library. The default is 5.

Environment variable: MALLOC_EVENTBTDEPTH

MALLOC_EVENTFILE
Redirect the event output to the file specified by the value argument. If you include ${pid} in the filename, mallopt() replaces it with the process ID. You can use a hyphen (-) to redirect the output to standard output.

Environment variable: MALLOC_EVENTFILE. You can use MALLOC_FILE to send the event and trace output to the same file.

MALLOC_FATAL, MALLOC_WARN
Specify how to handle a fatal error or warning, respectively. The default action is to provide a traceback.

Environment variable: MALLOC_ACTION, which sets the handling for fatal errors and warnings to the same value.

Use one of the following for the value arguments:

Symbolic name Value Description
M_HANDLE_IGNORE 0 Ignore the error and continue
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 Send a stop signal (SIGSTOP) to the current thread
Note: If you use the environment variable, you must set it to one of the numeric values, not the corresponding M_HANDLE_* symbolic name.

If you call mallopt(), you can OR any of these handlers with M_HANDLE_DUMP, to cause a complete dump of the heap before the handler takes action.

These situations are considered to be fatal errors:

  • A malloc chain is broken.
  • The end of a chain isn't what was expected.
  • A signal was caught.

These situations cause a warning:

  • Chain pointers are corrupt.
  • A bad CRC was found in a block's header.
  • A bad “magic number” was found in a block's header.
  • The thread that called strtok() with a NULL first argument isn't the one that made the first call to the function.
  • A block that the allocator thinks isn't in use is being freed or reallocated.
  • A null-pointer dereference occurred.
  • Overlapping memory regions were detected.
  • A data overrun occurred in a malloc segment.
  • A pointer isn't in the expected range.
  • An area has been used after being freed.

These might be considered to be fatal errors or warnings, depending on the circumstances:

  • A pointer isn't in a malloc area.
  • A pointer is beyond the expected bounds.
MALLOC_HANDLE_SIGNALS
Install (1) or don't install (0), depending on the value argument, a handler for the abnormal-termination signals (SIGSEGV, SIGBUS, SIGILL, and SIGFPE). The default is to install a signal handler that prints an error message and then aborts the program.

Environment variable: MALLOC_HANDLE_SIGNALS

MALLOC_MARKER
(QNX Neutrino 6.6 or later) Insert a marker. The value argument is an integer that you want to use as a marker.
MALLOC_TRACEBTDEPTH
Set the depth of the backtrace for errors and warnings on CPUs that support deeper backtrace levels. Currently the builtin-return-address feature of gcc is used to implement deeper backtraces for the librcheck library. The default is 5.

Environment variable: MALLOC_TRACEBTDEPTH

MALLOC_TRACEFILE
Redirect the trace output to the file specified by the value argument. If you include ${pid} in the filename, mallopt() replaces it with the process ID. You can use a hyphen (-) to redirect the output to standard output. If the value argument points to an empty string, the library turns off tracing.

Environment variable: MALLOC_FILE, which sends the event and trace output to the same file.

MALLOC_TRACEMAX
Specify the maximum size of allocations to track; trace only the allocations that are less than or equal to the maximum number specified (in bytes). The default is 0, to indicate no maximum.

Environment variable: MALLOC_TRACEMAX

MALLOC_TRACEMIN
Specify the minimum size of allocations to track; trace only the allocations that are greater than or equal to the minimum number specified (in bytes). The default is 0, to indicate no minimum.

Environment variable: MALLOC_TRACEMIN

MALLOC_TRACING
Turn on (1) or off (0) the tracing of allocations. By default, tracing is turned off.
MALLOC_TRUNCATE
Truncate (1) or don't truncate (0) output files when opening them. The default is to truncate the files.

Environment variable: MALLOC_TRUNCATE

MALLOC_VERBOSE
Be verbose; if the value argument is nonzero, the library sends extra information to standard error.

Environment variable: MALLOC_VERBOSE

For details, see “Controlling the level of checking” in the Heap Analysis chapter of the QNX 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.

Environment variables:

The libc and librcheck libraries check some environment variables when you start your program:

Variables supported by libc and librcheck

Both libraries support the following environment variables, which correspond to the command with the same name:

as well as the following:

MALLOC_FREE_LIFO
If set, malloc() changes the free queueing strategy from the default (FIFO) to LIFO.
MALLOC_BAND_CONFIG_STR
Use this environment variable to configure the bands of memory. The string format is: 
N:s1,n1,p1:s2,n2,p2:s3,n3,p3: ... :sN,nN,pN

where the components are:

N
The number of bands.
s
The band size, in bytes.
n
The number of blocks in the band.
p
The number of blocks to preallocate, which can be zero.

The parsing is simple and strict:

  • The sizes must all be distinct and be provided in ascending order (i.e., s1 < s2 < s3, and so on).
  • You must specify s, n, and p for each band.
  • The string can't include any spaces; the only valid characters are digits, colons (:), and commas (,).

If the allocator doesn't like the string, it ignores it completely.

The default bands are 16, 24, 32, 48, 64, 80, 96, and 128. The 24-byte band is defined only when you compile for 32-bit architectures.

MALLOC_MEMORY_PREALLOCATE
Preallocate and populate the arena cache by setting this environment variable to a value that specifies the size of the total arena cache. The default is 0.
MALLOC_OPTIONS
(QNX Neutrino 6.4.1 or later) Control the way calloc(), malloc(), and realloc() behave if you specify a size of 0 (or a value of 0 for the n argument to calloc()). The V (“System V”) and R (“use the realloc() behavior of QNX Neutrino 6.4.0 and earlier”) columns below indicate how the functions behave if the value of MALLOC_OPTIONS includes that letter:
Function Default V R
calloc(n, 0) Non-NULL NULL No effect
malloc(0) Non-NULL NULL No effect
realloc(NULL, 0) Non-NULL NULL No effect
realloc(non-NULL, 0) Non-NULL NULL NULL

In all the above cases, if the function returns a non-NULL pointer, it's valid only for a corresponding call to free() or realloc(). By default, neither V nor R is set.

Variables supported only by librcheck

The librcheck library also checks the following environment variables, which correspond to the command with the same name:

as well as the following:

MALLOC_ACTION=0|1|2|3|4
Specify the handling for fatal errors and warnings; for more information, see the MALLOC_FATAL and MALLOC_WARNING commands. The default action is to provide a traceback.
MALLOC_CTHREAD=0|1|2
Start (1 or 2) or don't start (0) a control thread. A control thread lets the IDE send commands to the application. Set the value to 1 if you want the IDE to send commands via /dev/rcheck (but you need to be root). Set the value to 2 if you want the IDE to send commands using signals. The default is 0.
MALLOC_CTRL_FILE=file
Specify a file for the control command (to use with the control signal). If you include ${pid} in the filename, the library replaces it with the process ID; quote the $ if you're running from the shell.
MALLOC_CTRL_SIG=sigs
Override the default mapping of commands to signals. The value is a string in the form:

command:signal_num, ...

where command is one of control, leaks, stop, start, and marker. For example, the default mapping is "control:41,leaks:42,stop:43,start:44,marker:45". Specifying 0 as the signal number disables the command; specifying 0 for the environment variable disables all signals.

MALLOC_FILE=file
Redirect both event and trace output to the given file. If you include ${pid} in the filename, the library replaces it with the process ID; quote the $ if you're running from the shell. You can use a hyphen (-) to redirect the output to standard output (the default).
MALLOC_HELP=1
Display a list of the supported environment variables and then exit; for example: 
LD_PRELOAD=librcheck.so MALLOC_HELP=1 ./my_app
MALLOC_SAMPLING=millis
Run a sampling thread to produce heap statistics every millis milliseconds.
MALLOC_START_TRACING=0|1
Enable (1) or disable (0) the automatic tracing of memory when the application starts. If tracing isn't enabled when application starts, the only way you can enable it is to use the MALLOC_TRACING command or the control thread interface (see “Memory Analysis” in the References chapter of the IDE User's Guide). The default is 0.
MALLOC_STAT_BINS=bin1,bin2,...
Set the custom bins. Bins are used to define allocation ranges that you want to collect usage statistics for. For example, you can check how many allocations are done for the 40-, 80-, and 120-byte bins. The default bins are 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, and ULONG_MAX (the last bin catches all allocations larger than 4096 bytes).
MALLOC_USE_CACHE=number
Specify the size of the pointer cache; the value must be a power of 2 in the range from 0 through 2048. Set to 0 to disable optimization. The default is 32 (turn off optimization if the application crashes during the run).

Reverting to the behavior of Neutrino 6.2

In order to revert to the allocator behavior from QNX Neutrino 6.2, do one of the following:

You can also set both variables to fine-tune the allocator's behavior. The easiest way is to explicitly set the MALLOC_ARENA_CACHE_MAXSZ value to set a cap on the total amount of memory held in the allocator. The MALLOC_ARENA_CACHE_MAXBLK value is more difficult to configure, because the blocks aren't necessarily the same size, and hence setting the number alone may not give the exact desired behavior.

Classification:

QNX Neutrino

Safety:  
Cancellation point No
Interrupt handler No
Signal handler No
Thread Yes
Related concepts
Heap Analysis (QNX Neutrino Programmer's Guide)
Related reference
aligned_alloc()
calloc()
free()
mallinfo()
malloc()
realloc()
Parent topic: M