% clang -fsanitize=memory -fno-omit-frame-pointer -g -O2 umr.cc
If a bug is detected, the program will print an error message to
-stderr and exit with a non-zero exit code. Currently, MemorySanitizer
-does not symbolize its output by default, so you may need to use a
-separate script to symbolize the result offline (this will be fixed in
-future).
+stderr and exit with a non-zero exit code.
.. code-block:: console
#0 0x7f45944b418a in main umr.cc:6
#1 0x7f45938b676c in __libc_start_main libc-start.c:226
-By default, MemorySanitizer exits on the first detected error.
+By default, MemorySanitizer exits on the first detected error. If you
+find the error report hard to understand, try enabling
+:ref:`origin tracking <msan-origins>`.
``__has_feature(memory_sanitizer)``
------------------------------------
reports. Make sure that ``llvm-symbolizer`` binary is in ``PATH``,
or set environment variable ``MSAN_SYMBOLIZER_PATH`` to point to it.
+.. _msan-origins:
+
Origin Tracking
===============
-MemorySanitizer can track origins of unitialized values, similar to
+MemorySanitizer can track origins of uninitialized values, similar to
Valgrind's --track-origins option. This feature is enabled by
``-fsanitize-memory-track-origins=2`` (or simply
``-fsanitize-memory-track-origins``) Clang option. With the code from
intermediate stores the uninitialized value went through. Origin
tracking has proved to be very useful for debugging MemorySanitizer
reports. It slows down program execution by a factor of 1.5x-2x on top
-of the usual MemorySanitizer slowdown.
+of the usual MemorySanitizer slowdown and increases memory overhead.
-Clang option ``-fsanitize-memory-track-origins=1`` enabled a slightly
+Clang option ``-fsanitize-memory-track-origins=1`` enables a slightly
faster mode when MemorySanitizer collects only allocation points but
not intermediate stores.
+Use-after-destruction detection
+===============================
+
+You can enable experimental use-after-destruction detection in MemorySanitizer.
+After invocation of the destructor, the object will be considered no longer
+readable, and using underlying memory will lead to error reports in runtime.
+
+This feature is still experimental, in order to enable it at runtime you need
+to:
+
+#. Pass addition Clang option ``-fsanitize-memory-use-after-dtor`` during
+ compilation.
+#. Set environment variable `MSAN_OPTIONS=poison_in_dtor=1` before running
+ the program.
+
Handling external code
-============================
+======================
MemorySanitizer requires that all program code is instrumented. This
also includes any libraries that the program depends on, even libc.
Supported Platforms
===================
-MemorySanitizer is supported on
-
-* Linux x86\_64 (tested on Ubuntu 12.04);
+MemorySanitizer is supported on Linux x86\_64/MIPS64/AArch64.
Limitations
===========
address space. This means that tools like ``ulimit`` may not work as
usually expected.
* Static linking is not supported.
-* Non-position-independent executables are not supported. Therefore, the
- ``fsanitize=memory`` flag will cause Clang to act as though the ``-fPIE``
- flag had been supplied if compiling without ``-fPIC``, and as though the
- ``-pie`` flag had been supplied if linking an executable.
-* Depending on the version of Linux kernel, running without ASLR may
- be not supported. Note that GDB disables ASLR by default. To debug
- instrumented programs, use "set disable-randomization off".
+* Older versions of MSan (LLVM 3.7 and older) didn't work with
+ non-position-independent executables, and could fail on some Linux
+ kernel versions with disabled ASLR. Refer to documentation for older versions
+ for more details.
Current Status
==============
-MemorySanitizer is an experimental tool. It is known to work on large
-real-world programs, like Clang/LLVM itself.
+MemorySanitizer is known to work on large real-world programs
+(like Clang/LLVM itself) that can be recompiled from source, including all
+dependent libraries.
More Information
================
- .. _opt_fsanitize_memory:
``-fsanitize=memory``: :doc:`MemorySanitizer`,
- an *experimental* detector of uninitialized reads. Not ready for
- widespread use.
+ a detector of uninitialized reads. Requires instrumentation of all
+ program code.
- .. _opt_fsanitize_undefined:
``-fsanitize=undefined``: :doc:`UndefinedBehaviorSanitizer`,
- ``-fno-sanitize-blacklist``: don't use blacklist file, if it was
specified earlier in the command line.
- Extra features of MemorySanitizer (require explicit
- ``-fsanitize=memory``):
-
- - ``-fsanitize-memory-track-origins[=level]``: Enables origin tracking in
- MemorySanitizer. Adds a second section to MemorySanitizer
- reports pointing to the heap or stack allocation the
- uninitialized bits came from. Slows down execution by additional
- 1.5x-2x.
-
- Possible values for level are 0 (off), 1, 2 (default). Level 2
- adds more sections to MemorySanitizer reports describing the
- order of memory stores the uninitialized value went
- through. This mode may use extra memory in programs that copy
- uninitialized memory a lot.
- - ``-fsanitize-memory-use-after-dtor``: Enables use-after-destruction
- detection in MemorySanitizer. After invocation of the destructor,
- the object is considered no longer readable. Facilitates the
- detection of use-after-destroy bugs.
-
- Setting the MSAN_OPTIONS=poison_in_dtor=1 enables the poisoning of
- memory at runtime. Any subsequent access to the destroyed object
- fails at runtime. This feature is still experimental, but this
- environment variable must be set to 1 in order for the above flag
- to have any effect.
-
The ``-fsanitize=`` argument must also be provided when linking, in
order to link to the appropriate runtime library. When using
``-fsanitize=vptr`` (or a group that includes it, such as
projects / clang / commitdiff