Options for Mudflap

For Mudflap, you can set the following additional options:

• Violation options — these options control what action takes place when a violation has occurred:

  -mode-check

  Mudflap checks for memory violations. By default, this option is active.

  -mode-nop

  Mudflap does nothing. Since all main Mudflap functions are disabled, this mode is useful to count the total number of checked pointer accesses.

  -mode-populate

  Behave like each check succeeds. This mode populates the lookup cache, but doesn't actually track any objects. With this mode, performance measured is a rough upper bound of an instrumented program running an ideal implementation.

• Additional checking and tracing options — these options add a variety of extra checking and tracing:

  -collect-stats

  Print a collection of statistics when the program shuts down. This statistical data includes the number of calls to the various main() functions, and an assessment of the lookup cache utilization.

  -trace-calls

  Print a line of text to stderr for each Mudflap function.

  -verbose-trace

  Add more tracing to the internal Mudflap events.

  -verbose-violations

  Print the details for each violation, including nearby recently valid objects.

  -persistent-count=N

  Keep the descriptions of N recently valid (but now deallocated) objects in the event that a later violation may occur near them. This option is useful to help debug the use of buffers after they are freed.

  -abbreviate

  Abbreviate repeated detailed printing of the same tracked memory object.

  -free-queue-length=N

  Defer an intercepted free for N rounds, to ensure that immediately following malloc() calls, new memory will be returned. This option is useful for finding bugs in routines that manipulate tree-like structures.

  -crumple-zone=N

  Create extra inaccessible regions of N bytes before and after each allocated heap region. This option is useful for finding assumptions of contiguous memory allocation that contain bugs.

• Introspection options — these options provide additional services to applications or developers trying to debug.

  __mf_watch

  Given a pointer and a size, all objects overlapping this range are specifically marked. When accessed in the future, a special violation is signaled. This options is similar to a GDB watchpoint.

  __mf_unwatch

  Undo the marking added by the __mf_watch option.

  __mf_report

  Print a report similar to the one shown at program shut down or upon receipt of SIGUSR1.

  __mf_set_options

  Parse a given string as if it were provided at startup in the MUDFLAP_OPTIONS environment variable, to update the runtime options.

• Tuning options — to tune the performance sensitive behaviors of Mudflap. Choosing better parameters than default ones should only be done if -collect-stats indicates many unreasonable cache misses, or the application's working set changes much faster or slower than the defaults accommodate.

  -age-tree=N

  For tracking a current working set of tracked memory objects in the binary tree, Mudflap associates a value with each object, and this value is increased or decreased to satisfy a lookup cache miss. This value is decreased every N misses in order to deal with objects that haven't been accessed in a while.

  -lc-mask=N

  Set the lookup cache mask value to N.

  -lc-shift=N

  Set the lookup cache shift value to N. The value of N should be slightly smaller than the power of 2 alignment of the memory objects in the working set.

  -lc-adapt=N

  Adapt the mask and shift parameters automatically after N lookup cache misses. Set this value to zero if you're hard coding them with the above options.

• Heuristics options —to be used when a memory access violation is suspected, and are only useful when running a program that has some uninstrumented parts.

  -heur-proc-map

  For Linux, the special file /proc/self/map contains a tabular description of all the virtual memory areas mapped into the running process. This heuristic looks for a matching row that may contain the current access. If this heuristic is enabled, then (roughly speaking) libmudflap will permit all accesses that the raw operating system kernel would allow (i.e., not earn a SIGSEGV).

  -heur-start-end

  Permit accesses to the statically linked text, data, bss (holds information for the program's variables) areas of the program.

  -heur-stack-bound

  Permit accesses within the current stack area. This option is useful if uninstrumented functions pass local variable addresses to instrumented functions they call.

  -heur-argv-environ

  Add the standard C startup areas that contain the argv and environ strings to the object database.