common_interface_defs.h 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439
  1. //===-- sanitizer/common_interface_defs.h -----------------------*- C++ -*-===//
  2. //
  3. // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
  4. // See https://llvm.org/LICENSE.txt for license information.
  5. // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  6. //
  7. //===----------------------------------------------------------------------===//
  8. //
  9. // Common part of the public sanitizer interface.
  10. //===----------------------------------------------------------------------===//
  11. #ifndef SANITIZER_COMMON_INTERFACE_DEFS_H
  12. #define SANITIZER_COMMON_INTERFACE_DEFS_H
  13. #include <stddef.h>
  14. #include <stdint.h>
  15. // GCC does not understand __has_feature.
  16. #if !defined(__has_feature)
  17. #define __has_feature(x) 0
  18. #endif
  19. #ifdef __cplusplus
  20. extern "C" {
  21. #endif
  22. // Arguments for __sanitizer_sandbox_on_notify() below.
  23. typedef struct {
  24. // Enable sandbox support in sanitizer coverage.
  25. int coverage_sandboxed;
  26. // File descriptor to write coverage data to. If -1 is passed, a file will
  27. // be pre-opened by __sanitizer_sandbox_on_notify(). This field has no
  28. // effect if coverage_sandboxed == 0.
  29. intptr_t coverage_fd;
  30. // If non-zero, split the coverage data into well-formed blocks. This is
  31. // useful when coverage_fd is a socket descriptor. Each block will contain
  32. // a header, allowing data from multiple processes to be sent over the same
  33. // socket.
  34. unsigned int coverage_max_block_size;
  35. } __sanitizer_sandbox_arguments;
  36. // Tell the tools to write their reports to "path.<pid>" instead of stderr.
  37. void __sanitizer_set_report_path(const char *path);
  38. // Tell the tools to write their reports to the provided file descriptor
  39. // (casted to void *).
  40. void __sanitizer_set_report_fd(void *fd);
  41. // Get the current full report file path, if a path was specified by
  42. // an earlier call to __sanitizer_set_report_path. Returns null otherwise.
  43. const char *__sanitizer_get_report_path();
  44. // Notify the tools that the sandbox is going to be turned on. The reserved
  45. // parameter will be used in the future to hold a structure with functions
  46. // that the tools may call to bypass the sandbox.
  47. void __sanitizer_sandbox_on_notify(__sanitizer_sandbox_arguments *args);
  48. // This function is called by the tool when it has just finished reporting
  49. // an error. 'error_summary' is a one-line string that summarizes
  50. // the error message. This function can be overridden by the client.
  51. void __sanitizer_report_error_summary(const char *error_summary);
  52. // Some of the sanitizers (for example ASan/TSan) could miss bugs that happen
  53. // in unaligned loads/stores. To find such bugs reliably, you need to replace
  54. // plain unaligned loads/stores with these calls.
  55. /// Loads a 16-bit unaligned value.
  56. ///
  57. /// \param p Pointer to unaligned memory.
  58. ///
  59. /// \returns Loaded value.
  60. uint16_t __sanitizer_unaligned_load16(const void *p);
  61. /// Loads a 32-bit unaligned value.
  62. ///
  63. /// \param p Pointer to unaligned memory.
  64. ///
  65. /// \returns Loaded value.
  66. uint32_t __sanitizer_unaligned_load32(const void *p);
  67. /// Loads a 64-bit unaligned value.
  68. ///
  69. /// \param p Pointer to unaligned memory.
  70. ///
  71. /// \returns Loaded value.
  72. uint64_t __sanitizer_unaligned_load64(const void *p);
  73. /// Stores a 16-bit unaligned value.
  74. ///
  75. /// \param p Pointer to unaligned memory.
  76. /// \param x 16-bit value to store.
  77. void __sanitizer_unaligned_store16(void *p, uint16_t x);
  78. /// Stores a 32-bit unaligned value.
  79. ///
  80. /// \param p Pointer to unaligned memory.
  81. /// \param x 32-bit value to store.
  82. void __sanitizer_unaligned_store32(void *p, uint32_t x);
  83. /// Stores a 64-bit unaligned value.
  84. ///
  85. /// \param p Pointer to unaligned memory.
  86. /// \param x 64-bit value to store.
  87. void __sanitizer_unaligned_store64(void *p, uint64_t x);
  88. // Returns 1 on the first call, then returns 0 thereafter. Called by the tool
  89. // to ensure only one report is printed when multiple errors occur
  90. // simultaneously.
  91. int __sanitizer_acquire_crash_state();
  92. /// Annotates the current state of a contiguous container, such as
  93. /// <c>std::vector</c>, <c>std::string</c>, or similar.
  94. ///
  95. /// A contiguous container is a container that keeps all of its elements
  96. /// in a contiguous region of memory. The container owns the region of memory
  97. /// <c>[beg, end)</c>; the memory <c>[beg, mid)</c> is used to store the
  98. /// current elements, and the memory <c>[mid, end)</c> is reserved for future
  99. /// elements (<c>beg <= mid <= end</c>). For example, in
  100. /// <c>std::vector<> v</c>:
  101. ///
  102. /// \code
  103. /// beg = &v[0];
  104. /// end = beg + v.capacity() * sizeof(v[0]);
  105. /// mid = beg + v.size() * sizeof(v[0]);
  106. /// \endcode
  107. ///
  108. /// This annotation tells the Sanitizer tool about the current state of the
  109. /// container so that the tool can report errors when memory from
  110. /// <c>[mid, end)</c> is accessed. Insert this annotation into methods like
  111. /// <c>push_back()</c> or <c>pop_back()</c>. Supply the old and new values of
  112. /// <c>mid</c>(<c><i>old_mid</i></c> and <c><i>new_mid</i></c>). In the initial
  113. /// state <c>mid == end</c>, so that should be the final state when the
  114. /// container is destroyed or when the container reallocates the storage.
  115. ///
  116. /// For ASan, <c><i>beg</i></c> should be 8-aligned and <c><i>end</i></c>
  117. /// should be either 8-aligned or it should point to the end of a separate
  118. /// heap-, stack-, or global-allocated buffer. So the following example will
  119. /// not work:
  120. ///
  121. /// \code
  122. /// int64_t x[2]; // 16 bytes, 8-aligned
  123. /// char *beg = (char *)&x[0];
  124. /// char *end = beg + 12; // Not 8-aligned, not the end of the buffer
  125. /// \endcode
  126. ///
  127. /// The following, however, will work:
  128. /// \code
  129. /// int32_t x[3]; // 12 bytes, but 8-aligned under ASan.
  130. /// char *beg = (char*)&x[0];
  131. /// char *end = beg + 12; // Not 8-aligned, but is the end of the buffer
  132. /// \endcode
  133. ///
  134. /// \note Use this function with caution and do not use for anything other
  135. /// than vector-like classes.
  136. ///
  137. /// \param beg Beginning of memory region.
  138. /// \param end End of memory region.
  139. /// \param old_mid Old middle of memory region.
  140. /// \param new_mid New middle of memory region.
  141. void __sanitizer_annotate_contiguous_container(const void *beg,
  142. const void *end,
  143. const void *old_mid,
  144. const void *new_mid);
  145. /// Similar to <c>__sanitizer_annotate_contiguous_container</c>.
  146. ///
  147. /// Annotates the current state of a contiguous container memory,
  148. /// such as <c>std::deque</c>'s single chunk, when the boundries are moved.
  149. ///
  150. /// A contiguous chunk is a chunk that keeps all of its elements
  151. /// in a contiguous region of memory. The container owns the region of memory
  152. /// <c>[storage_beg, storage_end)</c>; the memory <c>[container_beg,
  153. /// container_end)</c> is used to store the current elements, and the memory
  154. /// <c>[storage_beg, container_beg), [container_end, storage_end)</c> is
  155. /// reserved for future elements (<c>storage_beg <= container_beg <=
  156. /// container_end <= storage_end</c>). For example, in <c> std::deque </c>:
  157. /// - chunk with a frist deques element will have container_beg equal to address
  158. /// of the first element.
  159. /// - in every next chunk with elements, true is <c> container_beg ==
  160. /// storage_beg </c>.
  161. ///
  162. /// Argument requirements:
  163. /// During unpoisoning memory of empty container (before first element is
  164. /// added):
  165. /// - old_container_beg_p == old_container_end_p
  166. /// During poisoning after last element was removed:
  167. /// - new_container_beg_p == new_container_end_p
  168. /// \param storage_beg Beginning of memory region.
  169. /// \param storage_end End of memory region.
  170. /// \param old_container_beg Old beginning of used region.
  171. /// \param old_container_end End of used region.
  172. /// \param new_container_beg New beginning of used region.
  173. /// \param new_container_end New end of used region.
  174. void __sanitizer_annotate_double_ended_contiguous_container(
  175. const void *storage_beg, const void *storage_end,
  176. const void *old_container_beg, const void *old_container_end,
  177. const void *new_container_beg, const void *new_container_end);
  178. /// Returns true if the contiguous container <c>[beg, end)</c> is properly
  179. /// poisoned.
  180. ///
  181. /// Proper poisoning could occur, for example, with
  182. /// <c>__sanitizer_annotate_contiguous_container</c>), that is, if
  183. /// <c>[beg, mid)</c> is addressable and <c>[mid, end)</c> is unaddressable.
  184. /// Full verification requires O (<c>end - beg</c>) time; this function tries
  185. /// to avoid such complexity by touching only parts of the container around
  186. /// <c><i>beg</i></c>, <c><i>mid</i></c>, and <c><i>end</i></c>.
  187. ///
  188. /// \param beg Beginning of memory region.
  189. /// \param mid Middle of memory region.
  190. /// \param end Old end of memory region.
  191. ///
  192. /// \returns True if the contiguous container <c>[beg, end)</c> is properly
  193. /// poisoned.
  194. int __sanitizer_verify_contiguous_container(const void *beg, const void *mid,
  195. const void *end);
  196. /// Returns true if the double ended contiguous
  197. /// container <c>[storage_beg, storage_end)</c> is properly poisoned.
  198. ///
  199. /// Proper poisoning could occur, for example, with
  200. /// <c>__sanitizer_annotate_double_ended_contiguous_container</c>), that is, if
  201. /// <c>[storage_beg, container_beg)</c> is not addressable, <c>[container_beg,
  202. /// container_end)</c> is addressable and <c>[container_end, end)</c> is
  203. /// unaddressable. Full verification requires O (<c>storage_end -
  204. /// storage_beg</c>) time; this function tries to avoid such complexity by
  205. /// touching only parts of the container around <c><i>storage_beg</i></c>,
  206. /// <c><i>container_beg</i></c>, <c><i>container_end</i></c>, and
  207. /// <c><i>storage_end</i></c>.
  208. ///
  209. /// \param storage_beg Beginning of memory region.
  210. /// \param container_beg Beginning of used region.
  211. /// \param container_end End of used region.
  212. /// \param storage_end End of memory region.
  213. ///
  214. /// \returns True if the double-ended contiguous container <c>[storage_beg,
  215. /// container_beg, container_end, end)</c> is properly poisoned - only
  216. /// [container_beg; container_end) is addressable.
  217. int __sanitizer_verify_double_ended_contiguous_container(
  218. const void *storage_beg, const void *container_beg,
  219. const void *container_end, const void *storage_end);
  220. /// Similar to <c>__sanitizer_verify_contiguous_container()</c> but also
  221. /// returns the address of the first improperly poisoned byte.
  222. ///
  223. /// Returns NULL if the area is poisoned properly.
  224. ///
  225. /// \param beg Beginning of memory region.
  226. /// \param mid Middle of memory region.
  227. /// \param end Old end of memory region.
  228. ///
  229. /// \returns The bad address or NULL.
  230. const void *__sanitizer_contiguous_container_find_bad_address(const void *beg,
  231. const void *mid,
  232. const void *end);
  233. /// returns the address of the first improperly poisoned byte.
  234. ///
  235. /// Returns NULL if the area is poisoned properly.
  236. ///
  237. /// \param storage_beg Beginning of memory region.
  238. /// \param container_beg Beginning of used region.
  239. /// \param container_end End of used region.
  240. /// \param storage_end End of memory region.
  241. ///
  242. /// \returns The bad address or NULL.
  243. const void *__sanitizer_double_ended_contiguous_container_find_bad_address(
  244. const void *storage_beg, const void *container_beg,
  245. const void *container_end, const void *storage_end);
  246. /// Prints the stack trace leading to this call (useful for calling from the
  247. /// debugger).
  248. void __sanitizer_print_stack_trace(void);
  249. // Symbolizes the supplied 'pc' using the format string 'fmt'.
  250. // Outputs at most 'out_buf_size' bytes into 'out_buf'.
  251. // If 'out_buf' is not empty then output is zero or more non empty C strings
  252. // followed by single empty C string. Multiple strings can be returned if PC
  253. // corresponds to inlined function. Inlined frames are printed in the order
  254. // from "most-inlined" to the "least-inlined", so the last frame should be the
  255. // not inlined function.
  256. // Inlined frames can be removed with 'symbolize_inline_frames=0'.
  257. // The format syntax is described in
  258. // lib/sanitizer_common/sanitizer_stacktrace_printer.h.
  259. void __sanitizer_symbolize_pc(void *pc, const char *fmt, char *out_buf,
  260. size_t out_buf_size);
  261. // Same as __sanitizer_symbolize_pc, but for data section (i.e. globals).
  262. void __sanitizer_symbolize_global(void *data_ptr, const char *fmt,
  263. char *out_buf, size_t out_buf_size);
  264. // Determine the return address.
  265. #if !defined(_MSC_VER) || defined(__clang__)
  266. #define __sanitizer_return_address() \
  267. __builtin_extract_return_addr(__builtin_return_address(0))
  268. #else
  269. extern "C" void *_ReturnAddress(void);
  270. #pragma intrinsic(_ReturnAddress)
  271. #define __sanitizer_return_address() _ReturnAddress()
  272. #endif
  273. /// Sets the callback to be called immediately before death on error.
  274. ///
  275. /// Passing 0 will unset the callback.
  276. ///
  277. /// \param callback User-provided callback.
  278. void __sanitizer_set_death_callback(void (*callback)(void));
  279. // Interceptor hooks.
  280. // Whenever a libc function interceptor is called, it checks if the
  281. // corresponding weak hook is defined, and calls it if it is indeed defined.
  282. // The primary use-case is data-flow-guided fuzzing, where the fuzzer needs
  283. // to know what is being passed to libc functions (for example memcmp).
  284. // FIXME: implement more hooks.
  285. /// Interceptor hook for <c>memcmp()</c>.
  286. ///
  287. /// \param called_pc PC (program counter) address of the original call.
  288. /// \param s1 Pointer to block of memory.
  289. /// \param s2 Pointer to block of memory.
  290. /// \param n Number of bytes to compare.
  291. /// \param result Value returned by the intercepted function.
  292. void __sanitizer_weak_hook_memcmp(void *called_pc, const void *s1,
  293. const void *s2, size_t n, int result);
  294. /// Interceptor hook for <c>strncmp()</c>.
  295. ///
  296. /// \param called_pc PC (program counter) address of the original call.
  297. /// \param s1 Pointer to block of memory.
  298. /// \param s2 Pointer to block of memory.
  299. /// \param n Number of bytes to compare.
  300. /// \param result Value returned by the intercepted function.
  301. void __sanitizer_weak_hook_strncmp(void *called_pc, const char *s1,
  302. const char *s2, size_t n, int result);
  303. /// Interceptor hook for <c>strncasecmp()</c>.
  304. ///
  305. /// \param called_pc PC (program counter) address of the original call.
  306. /// \param s1 Pointer to block of memory.
  307. /// \param s2 Pointer to block of memory.
  308. /// \param n Number of bytes to compare.
  309. /// \param result Value returned by the intercepted function.
  310. void __sanitizer_weak_hook_strncasecmp(void *called_pc, const char *s1,
  311. const char *s2, size_t n, int result);
  312. /// Interceptor hook for <c>strcmp()</c>.
  313. ///
  314. /// \param called_pc PC (program counter) address of the original call.
  315. /// \param s1 Pointer to block of memory.
  316. /// \param s2 Pointer to block of memory.
  317. /// \param result Value returned by the intercepted function.
  318. void __sanitizer_weak_hook_strcmp(void *called_pc, const char *s1,
  319. const char *s2, int result);
  320. /// Interceptor hook for <c>strcasecmp()</c>.
  321. ///
  322. /// \param called_pc PC (program counter) address of the original call.
  323. /// \param s1 Pointer to block of memory.
  324. /// \param s2 Pointer to block of memory.
  325. /// \param result Value returned by the intercepted function.
  326. void __sanitizer_weak_hook_strcasecmp(void *called_pc, const char *s1,
  327. const char *s2, int result);
  328. /// Interceptor hook for <c>strstr()</c>.
  329. ///
  330. /// \param called_pc PC (program counter) address of the original call.
  331. /// \param s1 Pointer to block of memory.
  332. /// \param s2 Pointer to block of memory.
  333. /// \param result Value returned by the intercepted function.
  334. void __sanitizer_weak_hook_strstr(void *called_pc, const char *s1,
  335. const char *s2, char *result);
  336. void __sanitizer_weak_hook_strcasestr(void *called_pc, const char *s1,
  337. const char *s2, char *result);
  338. void __sanitizer_weak_hook_memmem(void *called_pc,
  339. const void *s1, size_t len1,
  340. const void *s2, size_t len2, void *result);
  341. // Prints stack traces for all live heap allocations ordered by total
  342. // allocation size until top_percent of total live heap is shown. top_percent
  343. // should be between 1 and 100. At most max_number_of_contexts contexts
  344. // (stack traces) are printed.
  345. // Experimental feature currently available only with ASan on Linux/x86_64.
  346. void __sanitizer_print_memory_profile(size_t top_percent,
  347. size_t max_number_of_contexts);
  348. /// Notify ASan that a fiber switch has started (required only if implementing
  349. /// your own fiber library).
  350. ///
  351. /// Before switching to a different stack, you must call
  352. /// <c>__sanitizer_start_switch_fiber()</c> with a pointer to the bottom of the
  353. /// destination stack and with its size. When code starts running on the new
  354. /// stack, it must call <c>__sanitizer_finish_switch_fiber()</c> to finalize
  355. /// the switch. The <c>__sanitizer_start_switch_fiber()</c> function takes a
  356. /// <c>void**</c> pointer argument to store the current fake stack if there is
  357. /// one (it is necessary when the runtime option
  358. /// <c>detect_stack_use_after_return</c> is enabled).
  359. ///
  360. /// When restoring a stack, this <c>void**</c> pointer must be given to the
  361. /// <c>__sanitizer_finish_switch_fiber()</c> function. In most cases, this
  362. /// pointer can be stored on the stack immediately before switching. When
  363. /// leaving a fiber definitely, NULL must be passed as the first argument to
  364. /// the <c>__sanitizer_start_switch_fiber()</c> function so that the fake stack
  365. /// is destroyed. If your program does not need stack use-after-return
  366. /// detection, you can always pass NULL to these two functions.
  367. ///
  368. /// \note The fake stack mechanism is disabled during fiber switch, so if a
  369. /// signal callback runs during the switch, it will not benefit from stack
  370. /// use-after-return detection.
  371. ///
  372. /// \param[out] fake_stack_save Fake stack save location.
  373. /// \param bottom Bottom address of stack.
  374. /// \param size Size of stack in bytes.
  375. void __sanitizer_start_switch_fiber(void **fake_stack_save,
  376. const void *bottom, size_t size);
  377. /// Notify ASan that a fiber switch has completed (required only if
  378. /// implementing your own fiber library).
  379. ///
  380. /// When code starts running on the new stack, it must call
  381. /// <c>__sanitizer_finish_switch_fiber()</c> to finalize
  382. /// the switch. For usage details, see the description of
  383. /// <c>__sanitizer_start_switch_fiber()</c>.
  384. ///
  385. /// \param fake_stack_save Fake stack save location.
  386. /// \param[out] bottom_old Bottom address of old stack.
  387. /// \param[out] size_old Size of old stack in bytes.
  388. void __sanitizer_finish_switch_fiber(void *fake_stack_save,
  389. const void **bottom_old,
  390. size_t *size_old);
  391. // Get full module name and calculate pc offset within it.
  392. // Returns 1 if pc belongs to some module, 0 if module was not found.
  393. int __sanitizer_get_module_and_offset_for_pc(void *pc, char *module_path,
  394. size_t module_path_len,
  395. void **pc_offset);
  396. #ifdef __cplusplus
  397. } // extern "C"
  398. #endif
  399. #endif // SANITIZER_COMMON_INTERFACE_DEFS_H