include/sanitizer/msan_interface.h

   1 //===-- msan_interface.h --------------------------------------------------===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This file is a part of MemorySanitizer.
  11 //
  12 // Public interface header.
  13 //===----------------------------------------------------------------------===//
  14 #ifndef MSAN_INTERFACE_H
  15 #define MSAN_INTERFACE_H
  16
  17 #include <sanitizer/common_interface_defs.h>
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22   /* Returns a string describing a stack origin.
  23      Return NULL if the origin is invalid, or is not a stack origin. */
  24   const char *__msan_get_origin_descr_if_stack(uint32_t id);
  25
  26   /* Set raw origin for the memory range. */
  27   void __msan_set_origin(const volatile void *a, size_t size, uint32_t origin);
  28
  29   /* Get raw origin for an address. */
  30   uint32_t __msan_get_origin(const volatile void *a);
  31
  32   /* Returns non-zero if tracking origins. */
  33   int __msan_get_track_origins();
  34
  35   /* Returns the origin id of the latest UMR in the calling thread. */
  36   uint32_t __msan_get_umr_origin();
  37
  38   /* Make memory region fully initialized (without changing its contents). */
  39   void __msan_unpoison(const volatile void *a, size_t size);
  40
  41   /* Make a null-terminated string fully initialized (without changing its
  42      contents). */
  43   void __msan_unpoison_string(const volatile char *a);
  44
  45   /* Make memory region fully uninitialized (without changing its contents). */
  46   void __msan_poison(const volatile void *a, size_t size);
  47
  48   /* Make memory region partially uninitialized (without changing its contents).
  49    */
  50   void __msan_partial_poison(const volatile void *data, void *shadow,
  51                              size_t size);
  52
  53   /* Returns the offset of the first (at least partially) poisoned byte in the
  54      memory range, or -1 if the whole range is good. */
  55   intptr_t __msan_test_shadow(const volatile void *x, size_t size);
  56
  57   /* Checks that memory range is fully initialized, and reports an error if it
  58    * is not. */
  59   void __msan_check_mem_is_initialized(const volatile void *x, size_t size);
  60
  61   /* Set exit code when error(s) were detected.
  62      Value of 0 means don't change the program exit code. */
  63   void __msan_set_exit_code(int exit_code);
  64
  65   /* For testing:
  66      __msan_set_expect_umr(1);
  67      ... some buggy code ...
  68      __msan_set_expect_umr(0);
  69      The last line will verify that a UMR happened. */
  70   void __msan_set_expect_umr(int expect_umr);
  71
  72   /* Change the value of keep_going flag. Non-zero value means don't terminate
  73      program execution when an error is detected. This will not affect error in
  74      modules that were compiled without the corresponding compiler flag. */
  75   void __msan_set_keep_going(int keep_going);
  76
  77   /* Print shadow and origin for the memory range to stderr in a human-readable
  78      format. */
  79   void __msan_print_shadow(const volatile void *x, size_t size);
  80
  81   /* Print shadow for the memory range to stderr in a minimalistic
  82      human-readable format. */
  83   void __msan_dump_shadow(const volatile void *x, size_t size);
  84
  85   /* Returns true if running under a dynamic tool (DynamoRio-based). */
  86   int  __msan_has_dynamic_component();
  87
  88   /* Tell MSan about newly allocated memory (ex.: custom allocator).
  89      Memory will be marked uninitialized, with origin at the call site. */
  90   void __msan_allocated_memory(const volatile void* data, size_t size);
  91
  92   /* This function may be optionally provided by user and should return
  93      a string containing Msan runtime options. See msan_flags.h for details. */
  94   const char* __msan_default_options();
  95
  96   // Sets the callback to be called right before death on error.
  97   // Passing 0 will unset the callback.
  98   void __msan_set_death_callback(void (*callback)(void));
  99
 100   /***********************************/
 101   /* Allocator statistics interface. */
 102
 103   /* Returns the estimated number of bytes that will be reserved by allocator
 104      for request of "size" bytes. If Msan allocator can't allocate that much
 105      memory, returns the maximal possible allocation size, otherwise returns
 106      "size". */
 107   size_t __msan_get_estimated_allocated_size(size_t size);
 108
 109   /* Returns true if p was returned by the Msan allocator and
 110      is not yet freed. */
 111   int __msan_get_ownership(const volatile void *p);
 112
 113   /* Returns the number of bytes reserved for the pointer p.
 114      Requires (get_ownership(p) == true) or (p == 0). */
 115   size_t __msan_get_allocated_size(const volatile void *p);
 116
 117   /* Number of bytes, allocated and not yet freed by the application. */
 118   size_t __msan_get_current_allocated_bytes();
 119
 120   /* Number of bytes, mmaped by msan allocator to fulfill allocation requests.
 121      Generally, for request of X bytes, allocator can reserve and add to free
 122      lists a large number of chunks of size X to use them for future requests.
 123      All these chunks count toward the heap size. Currently, allocator never
 124      releases memory to OS (instead, it just puts freed chunks to free
 125      lists). */
 126   size_t __msan_get_heap_size();
 127
 128   /* Number of bytes, mmaped by msan allocator, which can be used to fulfill
 129      allocation requests. When a user program frees memory chunk, it can first
 130      fall into quarantine and will count toward __msan_get_free_bytes()
 131      later. */
 132   size_t __msan_get_free_bytes();
 133
 134   /* Number of bytes in unmapped pages, that are released to OS. Currently,
 135      always returns 0. */
 136   size_t __msan_get_unmapped_bytes();
 137
 138   /* Malloc hooks that may be optionally provided by user.
 139      __msan_malloc_hook(ptr, size) is called immediately after
 140        allocation of "size" bytes, which returned "ptr".
 141      __msan_free_hook(ptr) is called immediately before
 142        deallocation of "ptr". */
 143   void __msan_malloc_hook(const volatile void *ptr, size_t size);
 144   void __msan_free_hook(const volatile void *ptr);
 145 #ifdef __cplusplus
 146 }  // extern "C"
 147 #endif
 148
 149 #endif