Launching from the command line with Memory Analysis enabled

To start a program with Memory Analysis enabled, you should preload the library and set other environment variables to configure Memory Analysis options. Below is an example of running with the minimum settings:

  1. To start attaching from the IDE: MALLOC_CTHREAD=1 MALLOC_FILE=/tmp/trace.rmat ./my_app
  2. To start for postmortem analysis with allocations tracing: MALLOC_FILE=/tmp/trace.rmat MALLOC_START_TRACING=1 ./my_app
  3. To start for postmortem analysis with API control: MALLOC_FILE=/tmp/trace.rmat MALLOC_START_TRACING=0 ./my_app
  4. To set environment for launch ALL subsequent processes with Memory Analysis to only find errors:
    export MALLOC_FILE=/tmp/trace\${pid}.rmat
    export MALLOC_TRUNCATE=1
  5. To obtain a list of the environment variables for librcheck, use this command: MALLOC_HELP=1 ./my_app

Environment variable Description
MALLOC_START_TRACING=1 Enable memory tracing on start (0 to disable). If memory tracing is disabled, errors can't report allocation/deallocation backtraces for memory chunk involved in error condition.
MALLOC_FILE=file Re-direct output to a file, can use ${pid} in the file name to replace it with process Id, escape $ if running from shell. Can use "-" to redirect to standard output.
MALLOC_VERBOSE=1 Enable debug output.
MALLOC_HANDLE_SIGNALS=0 Don't install signal handlers for reporting errors on SIGSEGV, SIGBUS, etc.
MALLOC_TRACEBTDEPTH=number Set alloc traces depth to number (the larger the depth, the more memory it takes to store the backtrace - the default is 5)
MALLOC_EVENTBTDEPTH=number Set error traces depth to number (the default is 5)
MALLOC_CKCHAIN=1 Check the allocator chain integrity on every allocation/deallocation (very expensive).
MALLOC_CKBOUNDS=1 Check for out of bounds errors.
MALLOC_CKACCESS=1 Check strings and memory functions for errors (1 is default, use 0 to disable).
MALLOC_CKALLOC=1 Check alloc and free functions for errors (1 is default, use 0 to disable).
MALLOC_TRACEMIN=number Only trace allocation >= number bytes (allows you to filter in advance to reduce the amount of stored data).
MALLOC_TRACEMAX=number Only trace allocation <= number bytes.
MALLOC_STAT_BINS=bin1,bin2,... Set the custom bins. Bins are used to define a bucket, for which Memory Analysis can collect usage statistics. For example, you can check how many allocation are done for 40, 80, and 120 byte bins.
MALLOC_USE_CACHE=number Set to 0 to disable optimization. The default is 32 (turn off optimization if the application crashes during the run).
MALLOC_ACTION=number Set error action behavior: 0 - ignore (report an error and continue), 1 - abort, 2 - exit (no core), 3 - dump core, 4 - stop (send SIGSTOP to itself, later it can attach with debugger).
MALLOC_DUMP_LEAKS=1 Enable dumping leaks on exit (only works for normal exit, if you want to dump a leak on an abnormal exit, such as SIGTERM, you should install a handler to "exit" on that signal).
MALLOC_TRUNCATE=1 Truncate output files before writing (otherwise it appends to a trace file).
MALLOC_CTHREAD=1 Start control thread, and allows the IDE to send commands to the application (can't use if process forks).
MALLOC_HELP=1 Print a list of used environment variables.
Related concepts
Performing a postmortem memory analysis
The Memory Analysis tooling API
Related tasks
Attaching to a running process