1//===-- dfsan_interface.h -------------------------------------------------===//
2//
3// This file is distributed under the University of Illinois Open Source
4// License. See LICENSE.TXT for details.
5//
6//===----------------------------------------------------------------------===//
7//
8// This file is a part of DataFlowSanitizer.
9//
10// Public interface header.
11//===----------------------------------------------------------------------===//
12#ifndef DFSAN_INTERFACE_H
13#define DFSAN_INTERFACE_H
14
15#include <stddef.h>
16#include <stdint.h>
17#include <sanitizer/common_interface_defs.h>
18
19#ifdef __cplusplus
20extern "C" {
21#endif
22
23typedef uint16_t dfsan_label;
24
25/// Stores information associated with a specific label identifier.  A label
26/// may be a base label created using dfsan_create_label, with associated
27/// text description and user data, or an automatically created union label,
28/// which represents the union of two label identifiers (which may themselves
29/// be base or union labels).
30struct dfsan_label_info {
31  // Fields for union labels, set to 0 for base labels.
32  dfsan_label l1;
33  dfsan_label l2;
34
35  // Fields for base labels.
36  const char *desc;
37  void *userdata;
38};
39
40/// Signature of the callback argument to dfsan_set_write_callback().
41typedef void (*dfsan_write_callback_t)(int fd, const void *buf, size_t count);
42
43/// Computes the union of \c l1 and \c l2, possibly creating a union label in
44/// the process.
45dfsan_label dfsan_union(dfsan_label l1, dfsan_label l2);
46
47/// Creates and returns a base label with the given description and user data.
48dfsan_label dfsan_create_label(const char *desc, void *userdata);
49
50/// Sets the label for each address in [addr,addr+size) to \c label.
51void dfsan_set_label(dfsan_label label, void *addr, size_t size);
52
53/// Sets the label for each address in [addr,addr+size) to the union of the
54/// current label for that address and \c label.
55void dfsan_add_label(dfsan_label label, void *addr, size_t size);
56
57/// Retrieves the label associated with the given data.
58///
59/// The type of 'data' is arbitrary.  The function accepts a value of any type,
60/// which can be truncated or extended (implicitly or explicitly) as necessary.
61/// The truncation/extension operations will preserve the label of the original
62/// value.
63dfsan_label dfsan_get_label(long data);
64
65/// Retrieves the label associated with the data at the given address.
66dfsan_label dfsan_read_label(const void *addr, size_t size);
67
68/// Retrieves a pointer to the dfsan_label_info struct for the given label.
69const struct dfsan_label_info *dfsan_get_label_info(dfsan_label label);
70
71/// Returns whether the given label label contains the label elem.
72int dfsan_has_label(dfsan_label label, dfsan_label elem);
73
74/// If the given label label contains a label with the description desc, returns
75/// that label, else returns 0.
76dfsan_label dfsan_has_label_with_desc(dfsan_label label, const char *desc);
77
78/// Returns the number of labels allocated.
79size_t dfsan_get_label_count(void);
80
81/// Sets a callback to be invoked on calls to write().  The callback is invoked
82/// before the write is done.  The write is not guaranteed to succeed when the
83/// callback executes.  Pass in NULL to remove any callback.
84void dfsan_set_write_callback(dfsan_write_callback_t labeled_write_callback);
85
86#ifdef __cplusplus
87}  // extern "C"
88
89template <typename T>
90void dfsan_set_label(dfsan_label label, T &data) {  // NOLINT
91  dfsan_set_label(label, (void *)&data, sizeof(T));
92}
93
94#endif
95
96#endif  // DFSAN_INTERFACE_H
97