Fix: unchecked buffer size for communication header
[lttng-tools.git] / src / common / payload-view.h
1 /*
2 * Copyright (C) 2020 Jérémie Galarneau <jeremie.galarneau@efficios.com>
3 *
4 * SPDX-License-Identifier: LGPL-2.1-only
5 *
6 */
7
8 #ifndef LTTNG_PAYLOAD_VIEW_H
9 #define LTTNG_PAYLOAD_VIEW_H
10
11 #include <common/buffer-view.h>
12 #include <common/dynamic-array.h>
13
14 struct lttng_payload;
15 struct fd_handle;
16
17 /*
18 * An lttng_payload_view references a payload and allows code to share
19 * a `const` version of a subset of a payload.
20 *
21 * A payload view is invalidated whenever its source (a payload, or another
22 * payload view) is modified.
23 *
24 * While a payload view does not allow users to modify the underlying bytes
25 * of the payload, it can be used to 'pop' file descriptor handles using an
26 * iterator belonging to the top-level payload view.
27 *
28 * Hence, a payload view created from a payload or a dynamic buffer contains
29 * an implicit file descriptor handle iterator. Any payload view created from
30 * another payload view will share the same underlying file descriptor handle
31 * iterator.
32 *
33 * The rationale for this is that a payload is never consumed directly, it must
34 * be consumed through a payload view.
35 *
36 * Typically, a payload view will be used to rebuild a previously serialized
37 * object hierarchy. Sharing an underlying iterator allows aggregate objects
38 * to provide a restricted view of the payload to their members, which will
39 * report the number of bytes consumed and `pop` the file descriptor handle they
40 * should own. In return, those objects can create an even narrower view for
41 * their children, allowing them to also consume file descriptor handles.
42 *
43 * Note that a payload view never assumes any ownership of the underlying
44 * payload.
45 */
46 struct lttng_payload_view {
47 struct lttng_buffer_view buffer;
48 /* private */
49 const struct lttng_dynamic_pointer_array _fd_handles;
50 struct {
51 size_t *p_fd_handles_position;
52 size_t fd_handles_position;
53 } _iterator;
54 };
55
56 /**
57 * Checks if a payload view's buffer is safe to access.
58 *
59 * After calling the payload view creation functions, callers should verify
60 * if the resquested length (if any is explicitly provided) could be mapped
61 * to a new view.
62 */
63 LTTNG_HIDDEN
64 bool lttng_payload_view_is_valid(const struct lttng_payload_view *view);
65
66 /**
67 * Return a payload view referencing a subset of a payload.
68 *
69 * @payload Source payload to reference
70 * @offset Offset to apply to the payload's buffer
71 * @len Length of the contents to reference. Passing -1 will
72 * cause the view to reference the whole payload from the
73 * offset provided.
74 */
75 LTTNG_HIDDEN
76 struct lttng_payload_view lttng_payload_view_from_payload(
77 const struct lttng_payload *payload, size_t offset,
78 ptrdiff_t len);
79
80 /**
81 * Return a payload view referencing a subset of a payload referenced by
82 * another payload view.
83 *
84 * @view Source payload view to reference
85 * @offset Offset to apply to the payload view's buffer view
86 * @len Length of the contents to reference. Passing -1 will
87 * cause the payload view to reference the whole payload view's
88 * buffer view from the offset provided.
89 */
90 LTTNG_HIDDEN
91 struct lttng_payload_view lttng_payload_view_from_view(
92 struct lttng_payload_view *view, size_t offset,
93 ptrdiff_t len);
94
95 /**
96 * Return a payload view referencing a subset of a dynamic buffer.
97 *
98 * Meant as an adapter for code paths that need to create a payload view
99 * from an existing dynamic buffer.
100 *
101 * @src Source dynamic buffer to reference
102 * @offset Offset to apply to the dynamic buffer
103 * @len Length of the buffer contents to reference. Passing -1 will
104 * cause the payload view to reference the whole payload from the
105 * offset provided.
106 */
107 LTTNG_HIDDEN
108 struct lttng_payload_view lttng_payload_view_from_dynamic_buffer(
109 const struct lttng_dynamic_buffer *buffer, size_t offset,
110 ptrdiff_t len);
111 /**
112 *
113 * Return a payload view referencing a subset of a dynamic buffer.
114 *
115 * Meant as an adapter for code paths that need to create a payload view
116 * from an existing buffer view.
117 *
118 * @src Source buffer view to reference
119 * @offset Offset to apply to the buffer view
120 * @len Length of the buffer contents to reference. Passing -1 will
121 * cause the payload view to reference the whole payload from the
122 * offset provided.
123 */
124 LTTNG_HIDDEN
125 struct lttng_payload_view lttng_payload_view_from_buffer_view(
126 const struct lttng_buffer_view *view, size_t offset,
127 ptrdiff_t len);
128
129 /**
130 * Return a payload view referencing a subset of the memory referenced by a raw
131 * pointer.
132 *
133 * @src Source buffer to reference
134 * @offset Offset to apply to the source memory buffer
135 * @len Length of the memory contents to reference.
136 *
137 * Note that a payload view never assumes the ownership of the memory it
138 * references.
139 */
140 LTTNG_HIDDEN
141 struct lttng_payload_view lttng_payload_view_init_from_buffer(
142 const char *src, size_t offset, ptrdiff_t len);
143
144 /**
145 * Get the number of file descriptor handles left in a payload view.
146 *
147 * @payload Payload instance
148 *
149 * Returns the number of file descriptor handles left on success, -1 on error.
150 */
151 LTTNG_HIDDEN
152 int lttng_payload_view_get_fd_handle_count(
153 const struct lttng_payload_view *payload_view);
154
155 /**
156 * Pop an fd handle from a payload view.
157 *
158 * A reference to the returned fd_handle is acquired on behalf of the caller.
159 *
160 * @payload Payload instance
161 *
162 * Returns an fd_handle on success, -1 on error.
163 */
164 LTTNG_HIDDEN
165 struct fd_handle *lttng_payload_view_pop_fd_handle(
166 struct lttng_payload_view *payload_view);
167
168 #endif /* LTTNG_PAYLOAD_VIEW_H */
This page took 0.045887 seconds and 4 git commands to generate.