mallopt()

#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:

• MALLOC_ARENA_SIZE
• MALLOC_ARENA_CACHE_FREE_NOW
• MALLOC_ARENA_CACHE_MAXBLK
• MALLOC_ARENA_CACHE_MAXSZ
• MALLOC_FREE_CHECK
• MALLOC_MEMORY_HOLD
• MALLOC_STATS
• MALLOC_VERIFY_ON

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

• MALLOC_CKACCESS
• MALLOC_CKALLOC
• MALLOC_CKBOUNDS
• MALLOC_CKCHAIN
• MALLOC_DUMP_LEAKS
• MALLOC_EVENTBTDEPTH
• MALLOC_START_TRACING
• MALLOC_TRACEMIN
• MALLOC_TRACEMAX
• MALLOC_TRACEBTDEPTH
• MALLOC_TRACING
• MALLOC_VERIFY
• MALLOC_FATAL
• MALLOC_WARN

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:

• zero to disable the checking
• nonzero to enable it

MALLOC_CKALLOC

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

Environment variable: MALLOC_CKALLOC.

The value argument can be:

• zero to disable the checking
• nonzero to enable it

MALLOC_CKBOUNDS

Turn on (or off) fill-area boundary checking.

Environment variable: MALLOC_CKBOUNDS.

The value argument can be:

• zero to disable the checking
• nonzero to enable it

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:

• zero to disable the checking
• nonzero to enable it

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:

• zero to disable the checking
• nonzero to enable it

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:

• zero to disable the checking
• 1 to enable it

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