mallopt()

Arguments:

cmd

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

• M_GRANULARITY
• M_MMAP_THRESHOLD
• M_TRIM_THRESHOLD

The debug version also supports the following:

• MALLOC_CKACCESS
• MALLOC_CKALLOC
• MALLOC_CTRL_CMD
• MALLOC_CTRL_CMD_FILE
• MALLOC_DUMP_LEAKS
• MALLOC_DUMP_STATS
• MALLOC_EVENTBTDEPTH
• MALLOC_EVENTFILE
• MALLOC_FATAL
• MALLOC_HANDLE_SIGNALS
• MALLOC_TRACEBTDEPTH
• MALLOC_TRACEFILE
• MALLOC_TRACEMAX
• MALLOC_TRACEMIN
• MALLOC_TRACING
• MALLOC_TRUNCATE
• MALLOC_VERBOSE
• MALLOC_WARN (see MALLOC_FATAL)

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 Working with Memory chapter of the QNX OS 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:

M_GRANULARITY

The minimum amount of memory to mmap when the allocator asks to allocate or deallocate memory from the system. The minimum value is page size, which must be a power of 2. If set to 0, the command initializes to page size.

Increase the value of this command to prevent the system from calling allocation functions; these slow the system down.

M_MMAP_THRESHOLD

The maximum memory size before the system switches to direct mmaps. The default value is 256K. Switching to direct mmaps is beneficial because mapped memory can always be individually released back to the system. The disadvantage is that the deallocated space can't be reused for later allocations.

M_TRIM_THRESHOLD

The minimum size at which the allocator tries to munmap memory. The minimum value must be greater than page size. The default value is 2M.

Set M_TRIM_THRESHOLD to -1 to disable trimming.

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 section of the Working with Memory chapter of the QNX OS 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_CTRL_CMD

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
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_unref	A filename	MALLOC_DUMP_LEAKS
verbose	An integer	MALLOC_VERBOSE
set_action	An integer	MALLOC_WARN, MALLOC_FATAL

MALLOC_CTRL_CMD_FILE

Execute a control command (see MALLOC_CTRL_CMD) from the specified file.

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

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

Catching a signal is considered to be a fatal error.

These situations cause a warning:

• 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. 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 section of the Working with Memory chapter of the QNX OS Programmer's Guide.

Returns:

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

Environment variables:

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

• MALLOC_CKACCESS
• MALLOC_CKALLOC
• MALLOC_DUMP_LEAKS
• MALLOC_EVENTBTDEPTH
• MALLOC_EVENTFILE
• MALLOC_HANDLE_SIGNALS
• MALLOC_TRACEBTDEPTH
• MALLOC_TRACEMAX
• MALLOC_TRACEMIN
• MALLOC_TRUNCATE
• MALLOC_VERBOSE

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. Set the value to 1 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).

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 leaks, stop, and start. For example, the default mapping is "leaks:42,stop:43,start:44". 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. You must specify the output from librcheck manually.

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

Classification:

QNX OS