Launching from the command line with Memory Analysis enabled

To start a program with Memory Analysis enabled, you should preload the librcheck.so 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:
    LD_PRELOAD=librcheck.so MALLOC_CTHREAD=1 MALLOC_FILE=/tmp/trace.rmat ./my_app
  2. To start for postmortem analysis with allocations tracing:
    LD_PRELOAD=librcheck.so MALLOC_FILE=/tmp/trace.rmat MALLOC_START_TRACING=1 ./my_app
  3. To start for postmortem analysis with API control:
    LD_PRELOAD=librcheck.so 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 LD_PRELOAD=librcheck.so 
    export MALLOC_FILE=/tmp/trace\${pid}.rmat
    export MALLOC_TRUNCATE=1
    ./my_app1
    ./my_app2
  5. To obtain a list of the environment variables for librcheck, use this command:
    LD_PRELOAD=librcheck.so 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