uprobe: transmit binary file descritptor through lttng_payload
[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
16 /*
17 * An lttng_payload_view references a payload and allows code to share
18 * a `const` version of a subset of a payload.
19 *
20 * A payload view is invalidated whenever its source (a payload, or another
21 * payload view) is modified.
22 *
23 * While a payload view does not allow users to modify the underlying bytes
24 * of the payload, it can be used to 'pop' file descriptors using an iterator
25 * belonging to the top-level payload view.
26 *
27 * Hence, a payload view created from a payload or a dynamic buffer contains
28 * an implicit file descriptor iterator. Any payload view created from another
29 * payload view will share the same underlying file descriptor iterator.
30 *
31 * The rationale for this is that a payload is never consumed directly, it
32 * must be consumed through a payload view.
33 *
34 * Typically, a payload view will be used to rebuild a previously serialized
35 * object hierarchy. Sharing an underlying iterator allows aggregate objects
36 * to provide a restricted view of the payload to their members, which will
37 * report the number of bytes consumed and `pop` the file descriptors they
38 * should own. In return, those objects can create an even narrower view for
39 * their children, allowing them to also consume file descriptors.
40 *
41 * Note that a payload view never assumes any ownership of the underlying
42 * payload.
43 */
44 struct lttng_payload_view {
45 struct lttng_buffer_view buffer;
46 /* private */
47 const struct lttng_dynamic_array _fds;
48 struct {
49 size_t *p_fds_position;
50 size_t fds_position;
51 } _iterator;
52 };
53
54 /**
55 * Return a payload view referencing a subset of a payload.
56 *
57 * @payload Source payload to reference
58 * @offset Offset to apply to the payload's buffer
59 * @len Length of the contents to reference. Passing -1 will
60 * cause the view to reference the whole payload from the
61 * offset provided.
62 */
63 LTTNG_HIDDEN
64 struct lttng_payload_view lttng_payload_view_from_payload(
65 const struct lttng_payload *payload, size_t offset,
66 ptrdiff_t len);
67
68 /**
69 * Return a payload view referencing a subset of a payload referenced by
70 * another payload view.
71 *
72 * @view Source payload view to reference
73 * @offset Offset to apply to the payload view's buffer view
74 * @len Length of the contents to reference. Passing -1 will
75 * cause the payload view to reference the whole payload view's
76 * buffer view from the offset provided.
77 */
78 LTTNG_HIDDEN
79 struct lttng_payload_view lttng_payload_view_from_view(
80 struct lttng_payload_view *view, size_t offset,
81 ptrdiff_t len);
82
83 /**
84 * Return a payload view referencing a subset of a dynamic buffer.
85 *
86 * Meant as an adapter for code paths that need to create a payload view
87 * from an existing dynamic buffer.
88 *
89 * @src Source dynamic buffer to reference
90 * @offset Offset to apply to the dynamic buffer
91 * @len Length of the buffer contents to reference. Passing -1 will
92 * cause the payload view to reference the whole payload from the
93 * offset provided.
94 */
95 LTTNG_HIDDEN
96 struct lttng_payload_view lttng_payload_view_from_dynamic_buffer(
97 const struct lttng_dynamic_buffer *buffer, size_t offset,
98 ptrdiff_t len);
99 /**
100 *
101 * Return a payload view referencing a subset of a dynamic buffer.
102 *
103 * Meant as an adapter for code paths that need to create a payload view
104 * from an existing buffer view.
105 *
106 * @src Source buffer view to reference
107 * @offset Offset to apply to the buffer view
108 * @len Length of the buffer contents to reference. Passing -1 will
109 * cause the payload view to reference the whole payload from the
110 * offset provided.
111 */
112 LTTNG_HIDDEN
113 struct lttng_payload_view lttng_payload_view_from_buffer_view(
114 const struct lttng_buffer_view *view, size_t offset,
115 ptrdiff_t len);
116
117 /**
118 * Return a payload view referencing a subset of the memory referenced by a raw
119 * pointer.
120 *
121 * @src Source buffer to reference
122 * @offset Offset to apply to the source memory buffer
123 * @len Length of the memory contents to reference.
124 *
125 * Note that a payload view never assumes the ownership of the memory it
126 * references.
127 */
128 LTTNG_HIDDEN
129 struct lttng_payload_view lttng_payload_view_init_from_buffer(
130 const char *src, size_t offset, ptrdiff_t len);
131
132 /**
133 * Get the number of file descriptors left in a payload view.
134 *
135 * @payload Payload instance
136 *
137 * Returns the number of file descriptors left on success, -1 on error.
138 */
139 LTTNG_HIDDEN
140 int lttng_payload_view_get_fd_count(struct lttng_payload_view *payload_view);
141
142 /**
143 * Pop an fd from a payload view.
144 * No ownership of the file descriptor is assumed by the payload.
145 *
146 * @payload Payload instance
147 *
148 * Returns a file descriptor on success, -1 on error.
149 */
150 LTTNG_HIDDEN
151 int lttng_payload_view_pop_fd(struct lttng_payload_view *payload_view);
152
153 #endif /* LTTNG_PAYLOAD_VIEW_H */
This page took 0.044227 seconds and 4 git commands to generate.