Fix: Initialize ret to zero
[lttng-tools.git] / include / lttng / userspace-probe.h
1 /*
2 * Copyright (C) 2017 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
3 *
4 * This library is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU Lesser General Public License, version 2.1 only,
6 * as published by the Free Software Foundation.
7 *
8 * This library is distributed in the hope that it will be useful, but WITHOUT
9 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
11 * for more details.
12 *
13 * You should have received a copy of the GNU Lesser General Public License
14 * along with this library; if not, write to the Free Software Foundation,
15 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16 */
17
18 #ifndef LTTNG_USERSPACE_PROBE_H
19 #define LTTNG_USERSPACE_PROBE_H
20
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24
25 /*
26 * Userspace probe lookup methods specifies how the userspace probe location
27 * specified by the user should be interpreted.
28 */
29 struct lttng_userspace_probe_location_lookup_method;
30
31 enum lttng_userspace_probe_location_lookup_method_type {
32 LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_UNKNOWN = -1,
33 LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_FUNCTION_DEFAULT = 0,
34 LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_FUNCTION_ELF = 1,
35 LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_TRACEPOINT_SDT = 2,
36 };
37
38 /*
39 * Get the type of a lookup method.
40 */
41 extern enum lttng_userspace_probe_location_lookup_method_type
42 lttng_userspace_probe_location_lookup_method_get_type(
43 const struct lttng_userspace_probe_location_lookup_method *lookup_method);
44
45 /*
46 * Destroy a lookup method.
47 */
48 extern void lttng_userspace_probe_location_lookup_method_destroy(
49 struct lttng_userspace_probe_location_lookup_method *lookup_method);
50
51 /*
52 * Create a tracepoint ELF function lookup method struct.
53 * Return NULL on failure.
54 */
55 extern struct lttng_userspace_probe_location_lookup_method *
56 lttng_userspace_probe_location_lookup_method_function_elf_create(void);
57
58 /*
59 * Create a tracepoint SDT tracepoint lookup method struct.
60 * Return NULL on failure.
61 */
62 extern struct lttng_userspace_probe_location_lookup_method *
63 lttng_userspace_probe_location_lookup_method_tracepoint_sdt_create(void);
64
65
66 /*
67 * Contains all the information needed to compute the instrumentation point in
68 * the binary. It is used in conjonction with a lookup method.
69 */
70 struct lttng_userspace_probe_location;
71
72 enum lttng_userspace_probe_location_status {
73 LTTNG_USERSPACE_PROBE_LOCATION_STATUS_OK = 0,
74 /* Invalid parameters provided. */
75 LTTNG_USERSPACE_PROBE_LOCATION_STATUS_INVALID = -1,
76 };
77
78 enum lttng_userspace_probe_location_type {
79 LTTNG_USERSPACE_PROBE_LOCATION_TYPE_UNKNOWN = -1,
80 /* Function. */
81 LTTNG_USERSPACE_PROBE_LOCATION_TYPE_FUNCTION = 0,
82 /* SDT probe's callsites. */
83 LTTNG_USERSPACE_PROBE_LOCATION_TYPE_TRACEPOINT = 1,
84 };
85
86 /*
87 * Get the type of the userspace probe location.
88 */
89 extern enum lttng_userspace_probe_location_type
90 lttng_userspace_probe_location_get_type(
91 const struct lttng_userspace_probe_location *location);
92
93 /*
94 * Destroy the userspace probe location.
95 */
96 extern void lttng_userspace_probe_location_destroy(
97 struct lttng_userspace_probe_location *location);
98
99
100 enum lttng_userspace_probe_location_function_instrumentation_type {
101 LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_UNKNOWN = -1,
102 /* Only instrument the function's entry. */
103 LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_ENTRY = 0,
104 };
105
106 /*
107 * Create a probe location of the function type.
108 * Receives the target binary file path and function to instrument.
109 * On failure, NULL is returned.
110 *
111 * The ownership of the lookup method is transferred to the created probe
112 * location.
113 */
114 extern struct lttng_userspace_probe_location *
115 lttng_userspace_probe_location_function_create(const char *binary_path,
116 const char *function_name,
117 struct lttng_userspace_probe_location_lookup_method *lookup_method);
118
119 /*
120 * Get the target binary path of the probe location of the function type.
121 */
122 extern const char *lttng_userspace_probe_location_function_get_binary_path(
123 const struct lttng_userspace_probe_location *location);
124
125 /*
126 * Get the target function type of the probe location of the function type.
127 */
128 extern const char *lttng_userspace_probe_location_function_get_function_name(
129 const struct lttng_userspace_probe_location *location);
130
131 /*
132 * Get the FD to the target binary file to the probe location of the function
133 * type.
134 */
135 extern int lttng_userspace_probe_location_function_get_binary_fd(
136 const struct lttng_userspace_probe_location *location);
137
138 /*
139 * Get the instrumentation type of the function probe location.
140 */
141 extern enum lttng_userspace_probe_location_function_instrumentation_type
142 lttng_userspace_probe_location_function_get_instrumentation_type(
143 const struct lttng_userspace_probe_location *location);
144
145 /*
146 * Get the instrumentation type of the function probe location.
147 * Defaults to
148 * LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_ENTRY.
149 *
150 * Returns LTTNG_USERSPACE_PROBE_LOCATION_STATUS_OK on success,
151 * LTTNG_USERSPACE_PROBE_LOCATION_STATUS_INVALID if invalid parameters
152 * are provided.
153 */
154 extern enum lttng_userspace_probe_location_status
155 lttng_userspace_probe_location_function_set_instrumentation_type(
156 const struct lttng_userspace_probe_location *location,
157 enum lttng_userspace_probe_location_function_instrumentation_type instrumentation_type);
158
159 /*
160 * Get the lookup method of the given userspace probe location.
161 * Returns NULL if the probe location type is unsupported.
162 *
163 * The ownership of the lookup method is NOT transferred to the caller.
164 */
165 extern const struct lttng_userspace_probe_location_lookup_method *
166 lttng_userspace_probe_location_get_lookup_method(
167 const struct lttng_userspace_probe_location *location);
168
169 /*
170 * Create a probe location of the tracepoint type.
171 * Receives the target binary file path, probename and probe provider to
172 * instrument.
173 * On failure, NULL is returned.
174 *
175 * The ownership of the lookup method is transferred to the created probe
176 * location.
177 */
178 extern struct lttng_userspace_probe_location *
179 lttng_userspace_probe_location_tracepoint_create(const char *binary_path,
180 const char *probe_name, const char *provider_name,
181 struct lttng_userspace_probe_location_lookup_method *lookup_method);
182
183 /*
184 * Get the target binary path of the probe location of the tracepoint type.
185 */
186 extern const char *lttng_userspace_probe_location_tracepoint_get_binary_path(
187 const struct lttng_userspace_probe_location *location);
188
189 /*
190 * Get the target probe name of the probe location of the tracepoint type.
191 */
192 extern const char *lttng_userspace_probe_location_tracepoint_get_probe_name(
193 const struct lttng_userspace_probe_location *location);
194
195 /*
196 * Get the target probe provider name of the probe location of the tracepoint
197 * type.
198 */
199 extern const char *lttng_userspace_probe_location_tracepoint_get_provider_name(
200 const struct lttng_userspace_probe_location *location);
201
202 /*
203 * Get the FD to the target binary file to the probe location of the tracepoint
204 * type.
205 */
206 extern int lttng_userspace_probe_location_tracepoint_get_binary_fd(
207 const struct lttng_userspace_probe_location *location);
208
209 #ifdef __cplusplus
210 }
211 #endif
212
213 #endif /* LTTNG_USERSPACE_PROBE_H */
This page took 0.036886 seconds and 5 git commands to generate.