This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

mallopt()

Control the extra checking for memory allocation

---

The debug version of this function is declared in <malloc_g/malloc.h>. The debug version includes additional commands and settings that aren't in <malloc/malloc.h>.

---

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:

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

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

• MALLOC_CKACCESS
• MALLOC_FILLAREA
• MALLOC_CKCHAIN
• 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_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.

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_FILLAREA

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

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_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

See also:

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

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