Control memory allocation and the extra checking for it
 |
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.h>.
To use debug mallopt(), you need to link with librcheck.so or use LD_PRELOAD=librcheck.so at runtime. |
#include <malloc.h>
int mallopt( int cmd,
int value );
- 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:
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.
libc
Use the -l c option to
qcc
to link against this library.
This library is usually included automatically.
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.
As described in the
Heap Analysis
chapter of the 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 any memory cached by the allocator at 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
- 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 MALLOC_ARENA_SIZE can reduce the amount of
memory required.
The default is 32 KB.
Environment variable: MALLOC_ARENA_SIZE.
If you set this environment variable to 0, it's ignored.
If the value argument is 0, mallopt() returns the current
arena size; if value is any other value, mallopt()
returns the previous size.
- MALLOC_ERROR_GET_FNPTR, MALLOC_ERROR_SET_FNPTR
- Get or set a pointer to the function that's called when an error occurs.
This function's prototype is:
void my_malloc_error(const char * const fn, uintptr_t lno, const char * const msg);
The arguments are:
- fn — the filename of the source code
- lno — the line number where the error occurred
- msg — a log message
- 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.
The default is 128 KB.
- MALLOC_MEMORY_HOLD
- Specify a value of 1 to tell the allocator to never release
memory back to the OS from its arena cache.
In this case, the heap never shrinks.
The default 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.
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_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_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 |
|
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_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 (or off) 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 Neutrino Programmer's Guide.
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.
The libc and librcheck libraries check
some environment variables when you start your program:
- some are supported by both libc and librcheck
- some are supported only by 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_MMAP_NOZERO
- If this environment variable is nonzero, then when malloc()
needs to expand the heap, it specifies the MAP_NOINIT flag
when it calls
mmap();
if the physical memory being mapped was previously
unmapped with UNMAP_INIT_OPTIONAL, then the POSIX requirement
that the memory be zeroed is relaxed.
For more information, see
“Initializing allocated memory”
in the Interprocess Communication (IPC) chapter of the
System Architecture guide.
By default, the kernel initializes the memory, but you can control this
by using the -mi or -m~i option to
procnto.
- 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.
- 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.
By default, bands in the allocator are defined as multiples of
_MALLOC_ALIGN (which is 8):
- _MALLOC_ALIGN × 2 = 16
- _MALLOC_ALIGN × 3 = 24
- _MALLOC_ALIGN × 4 = 32
- _MALLOC_ALIGN × 6 = 48
- _MALLOC_ALIGN × 8 = 64
- _MALLOC_ALIGN × 10 = 80
- _MALLOC_ALIGN × 12 = 96
- _MALLOC_ALIGN × 16 = 128
- MALLOC_MEMORY_BANDCONFIG
- If you specify the band configurations, you also have to set this
environment variable to 1 to ensure that your configurations are picked.
- 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.
- 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.
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
- Start (1) or don't start (0) a control thread.
A control thread lets the IDE send commands to the application.
The default is 0.
- MALLOC_CTRL_FILE=file
- Specify a file for the control command (to use with the control signal).
You can use ${pid} in the filename to replace
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 for a signal disables it;
specifying 0 or an empty string for the environment variable disables all signals.
- MALLOC_FILE=file
- Redirect output to the given file.
You can use ${pid} in the filename to replace
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
that you can enable it is to use the
MALLOC_TRACING command,
or the control thread interface (see the
“Create control thread” option in the
Analyzing a running program
section in the Analyzing Memory Usage and Finding Errors 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).
In order to revert to the allocator behavior from QNX Neutrino 6.2,
do one of the following:
- Set MALLOC_ARENA_CACHE_MAXBLK to 0, which results in no
caching of freed blocks.
Or:
- Set MALLOC_ARENA_CACHE_MAXSZ to 400000, which limits the
total caching of the blocks to 400000 bytes.
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.
QNX Neutrino
| Safety: | |
|---|
| Cancellation point |
No |
| Interrupt handler |
No |
| Signal handler |
No |
| Thread |
Yes |
calloc(),
free(),
mallinfo(),
malloc(),
realloc()
Heap Analysis chapter of
the Neutrino Programmer's Guide