Commit | Line | Data |
---|---|---|
1239a312 | 1 | /* |
ab5be9fa MJ |
2 | * Copyright (C) 2014 David Goulet <dgoulet@efficios.com> |
3 | * Copyright (C) 2016 Jérémie Galarneau <jeremie.galarneau@efficios.com> | |
1239a312 | 4 | * |
ab5be9fa | 5 | * SPDX-License-Identifier: LGPL-2.1-only |
1239a312 | 6 | * |
1239a312 DG |
7 | */ |
8 | ||
9 | #ifndef LTTNG_EVENT_H | |
10 | #define LTTNG_EVENT_H | |
11 | ||
048f01ef PP |
12 | #ifdef __cplusplus |
13 | extern "C" { | |
14 | #endif | |
15 | ||
4bd69c5f SM |
16 | #include <lttng/handle.h> |
17 | #include <lttng/lttng-export.h> | |
18 | #include <lttng/userspace-probe.h> | |
19 | ||
048f01ef PP |
20 | /*! |
21 | @brief | |
22 | \ref api-rer-conds-inst-pt-type "Instrumentation type condition" | |
23 | of a recording event | |
1239a312 | 24 | |
048f01ef PP |
25 | @ingroup api_rer |
26 | */ | |
1239a312 | 27 | enum lttng_event_type { |
048f01ef | 28 | /// Match LTTng kernel tracepoint and Linux system call events. |
28f23191 | 29 | LTTNG_EVENT_ALL = -1, |
048f01ef PP |
30 | |
31 | /// Match LTTng tracepoint or Java/Python logging events. | |
28f23191 | 32 | LTTNG_EVENT_TRACEPOINT = 0, |
048f01ef PP |
33 | |
34 | /*! | |
35 | Match Linux | |
36 | <a href="https://www.kernel.org/doc/html/latest/trace/kprobes.html">kprobe</a> | |
37 | events. | |
38 | */ | |
28f23191 | 39 | LTTNG_EVENT_PROBE = 1, |
048f01ef PP |
40 | |
41 | /*! | |
42 | Match Linux | |
43 | <a href="https://www.kernel.org/doc/html/latest/trace/kprobes.html">kretprobe</a> | |
44 | events. | |
45 | */ | |
28f23191 | 46 | LTTNG_EVENT_FUNCTION = 2, |
048f01ef PP |
47 | |
48 | /// @cond UNUSED | |
28f23191 JG |
49 | LTTNG_EVENT_FUNCTION_ENTRY = 3, |
50 | LTTNG_EVENT_NOOP = 4, | |
048f01ef PP |
51 | /// @endcond |
52 | ||
53 | /// Match Linux system call events. | |
28f23191 | 54 | LTTNG_EVENT_SYSCALL = 5, |
048f01ef PP |
55 | |
56 | /*! | |
57 | Match Linux | |
58 | <a href="https://lwn.net/Articles/499190/">uprobe</a> | |
59 | events. | |
60 | */ | |
28f23191 | 61 | LTTNG_EVENT_USERSPACE_PROBE = 6, |
1239a312 DG |
62 | }; |
63 | ||
048f01ef PP |
64 | /*! |
65 | @brief | |
66 | Operand of the | |
67 | \ref api-rer-conds-ll "instrumentation point log level condition" | |
68 | of a recording event rule. | |
69 | ||
70 | @ingroup api_rer | |
71 | ||
72 | In the enumerator descriptions below, consider that \lt_var{LL} is the | |
73 | log level value of the condition, that is, the value of the | |
74 | lttng_event::loglevel member when the lttng_event::loglevel_type member | |
75 | is the described enumerator. | |
76 | ||
77 | Depending on the \lt_obj_domain of the recording event rule, \lt_var{LL} | |
78 | is one of the enumerators of #lttng_loglevel, #lttng_loglevel_jul, | |
79 | #lttng_loglevel_log4j, or #lttng_loglevel_python. | |
80 | */ | |
1239a312 | 81 | enum lttng_loglevel_type { |
048f01ef | 82 | /// Match events regardless of their log level. |
28f23191 | 83 | LTTNG_EVENT_LOGLEVEL_ALL = 0, |
048f01ef PP |
84 | |
85 | /*! | |
86 | Match events with a log level that's at least as severe as | |
87 | \lt_var{LL}. | |
88 | */ | |
28f23191 | 89 | LTTNG_EVENT_LOGLEVEL_RANGE = 1, |
048f01ef PP |
90 | |
91 | /// Match events with a log level that's exacty \lt_var{LL}. | |
28f23191 | 92 | LTTNG_EVENT_LOGLEVEL_SINGLE = 2, |
1239a312 DG |
93 | }; |
94 | ||
048f01ef PP |
95 | /*! |
96 | @brief | |
97 | Value of the | |
98 | \ref api-rer-conds-ll "instrumentation point log level condition"= | |
99 | of an LTTng | |
100 | \link #LTTNG_DOMAIN_UST user space\endlink tracepoint | |
101 | recording event rule. | |
102 | ||
103 | @ingroup api_rer | |
104 | ||
105 | @sa #lttng_loglevel_type -- | |
106 | Operand of the log level condition of a recording event rule. | |
107 | */ | |
1239a312 | 108 | enum lttng_loglevel { |
048f01ef | 109 | /// System is unusable. |
28f23191 | 110 | LTTNG_LOGLEVEL_EMERG = 0, |
048f01ef PP |
111 | |
112 | /// Action must be taken immediately. | |
28f23191 | 113 | LTTNG_LOGLEVEL_ALERT = 1, |
048f01ef PP |
114 | |
115 | /// Critical conditions. | |
28f23191 | 116 | LTTNG_LOGLEVEL_CRIT = 2, |
048f01ef PP |
117 | |
118 | /// Error conditions. | |
28f23191 | 119 | LTTNG_LOGLEVEL_ERR = 3, |
048f01ef PP |
120 | |
121 | /// Warning conditions. | |
28f23191 | 122 | LTTNG_LOGLEVEL_WARNING = 4, |
048f01ef PP |
123 | |
124 | /// Normal, but significant, condition. | |
28f23191 | 125 | LTTNG_LOGLEVEL_NOTICE = 5, |
048f01ef PP |
126 | |
127 | /// Informational message. | |
28f23191 | 128 | LTTNG_LOGLEVEL_INFO = 6, |
048f01ef PP |
129 | |
130 | /// Debug information with system-level scope (set of programs). | |
28f23191 | 131 | LTTNG_LOGLEVEL_DEBUG_SYSTEM = 7, |
048f01ef PP |
132 | |
133 | /// Debug information with program-level scope (set of processes). | |
28f23191 | 134 | LTTNG_LOGLEVEL_DEBUG_PROGRAM = 8, |
048f01ef PP |
135 | |
136 | /// Debug information with process-level scope (set of modules). | |
28f23191 | 137 | LTTNG_LOGLEVEL_DEBUG_PROCESS = 9, |
048f01ef PP |
138 | |
139 | /*! | |
140 | Debug information with module (executable/library) scope | |
141 | (set of units). | |
142 | */ | |
28f23191 | 143 | LTTNG_LOGLEVEL_DEBUG_MODULE = 10, |
048f01ef PP |
144 | |
145 | /// Debug information with compilation unit scope (set of functions). | |
28f23191 | 146 | LTTNG_LOGLEVEL_DEBUG_UNIT = 11, |
048f01ef PP |
147 | |
148 | /// Debug information with function-level scope. | |
28f23191 | 149 | LTTNG_LOGLEVEL_DEBUG_FUNCTION = 12, |
048f01ef PP |
150 | |
151 | /// Debug information with line-level scope. | |
28f23191 | 152 | LTTNG_LOGLEVEL_DEBUG_LINE = 13, |
048f01ef PP |
153 | |
154 | /// Debug-level message. | |
28f23191 | 155 | LTTNG_LOGLEVEL_DEBUG = 14, |
1239a312 DG |
156 | }; |
157 | ||
048f01ef PP |
158 | /*! |
159 | @brief | |
160 | Value of the | |
161 | \ref api-rer-conds-ll "instrumentation point log level condition" | |
162 | of a | |
163 | \link #LTTNG_DOMAIN_JUL <code>java.util.logging</code>\endlink | |
164 | recording event rule. | |
165 | ||
166 | @ingroup api_rer | |
167 | ||
168 | @sa #lttng_loglevel_type -- | |
169 | Operand of the log level condition of a recording event rule. | |
170 | */ | |
1239a312 | 171 | enum lttng_loglevel_jul { |
048f01ef | 172 | /// Logging turned off. |
28f23191 | 173 | LTTNG_LOGLEVEL_JUL_OFF = INT32_MAX, |
048f01ef PP |
174 | |
175 | /// Serious failure. | |
28f23191 | 176 | LTTNG_LOGLEVEL_JUL_SEVERE = 1000, |
048f01ef PP |
177 | |
178 | /// Potential problem. | |
28f23191 | 179 | LTTNG_LOGLEVEL_JUL_WARNING = 900, |
048f01ef PP |
180 | |
181 | /// Informational messages. | |
28f23191 | 182 | LTTNG_LOGLEVEL_JUL_INFO = 800, |
048f01ef PP |
183 | |
184 | /// Static configuration messages. | |
28f23191 | 185 | LTTNG_LOGLEVEL_JUL_CONFIG = 700, |
048f01ef PP |
186 | |
187 | /// Tracing information. | |
28f23191 | 188 | LTTNG_LOGLEVEL_JUL_FINE = 500, |
048f01ef PP |
189 | |
190 | /// Fairly detailed tracing message. | |
28f23191 | 191 | LTTNG_LOGLEVEL_JUL_FINER = 400, |
048f01ef PP |
192 | |
193 | /// Highly detailed tracing message. | |
28f23191 | 194 | LTTNG_LOGLEVEL_JUL_FINEST = 300, |
048f01ef PP |
195 | |
196 | /// All messages. | |
28f23191 | 197 | LTTNG_LOGLEVEL_JUL_ALL = INT32_MIN, |
1239a312 DG |
198 | }; |
199 | ||
048f01ef PP |
200 | /*! |
201 | @brief | |
202 | Value of the | |
203 | \ref api-rer-conds-ll "instrumentation point log level condition" | |
204 | of an | |
205 | \link #LTTNG_DOMAIN_LOG4J Apache log4j\endlink | |
206 | recording event rule. | |
207 | ||
208 | @ingroup api_rer | |
209 | ||
210 | @sa #lttng_loglevel_type -- | |
211 | Operand of the log level condition of a recording event rule. | |
212 | */ | |
5cdb6027 | 213 | enum lttng_loglevel_log4j { |
048f01ef | 214 | /// Logging turned off. |
28f23191 | 215 | LTTNG_LOGLEVEL_LOG4J_OFF = INT32_MAX, |
048f01ef PP |
216 | |
217 | /*! | |
218 | Very severe error events that will presumably lead the | |
219 | application to abort. | |
220 | */ | |
28f23191 | 221 | LTTNG_LOGLEVEL_LOG4J_FATAL = 50000, |
048f01ef PP |
222 | |
223 | /*! | |
224 | Error events that might still allow the application to continue | |
225 | running. | |
226 | */ | |
28f23191 | 227 | LTTNG_LOGLEVEL_LOG4J_ERROR = 40000, |
048f01ef PP |
228 | |
229 | /// Potentially harmful situations. | |
28f23191 | 230 | LTTNG_LOGLEVEL_LOG4J_WARN = 30000, |
048f01ef PP |
231 | |
232 | /*! | |
233 | Informational messages that highlight the progress of the | |
234 | application at coarse-grained level. | |
235 | */ | |
28f23191 | 236 | LTTNG_LOGLEVEL_LOG4J_INFO = 20000, |
048f01ef PP |
237 | |
238 | /*! | |
239 | Fine-grained informational events that are most useful to debug | |
240 | an application. | |
241 | */ | |
28f23191 | 242 | LTTNG_LOGLEVEL_LOG4J_DEBUG = 10000, |
048f01ef PP |
243 | |
244 | /*! | |
245 | Finer-grained informational events than the | |
246 | #LTTNG_LOGLEVEL_LOG4J_DEBUG level. | |
247 | */ | |
28f23191 | 248 | LTTNG_LOGLEVEL_LOG4J_TRACE = 5000, |
048f01ef PP |
249 | |
250 | /// All levels, including custom levels. | |
28f23191 | 251 | LTTNG_LOGLEVEL_LOG4J_ALL = INT32_MIN, |
5cdb6027 DG |
252 | }; |
253 | ||
048f01ef PP |
254 | /*! |
255 | @brief | |
256 | Value of the | |
257 | \ref api-rer-conds-ll "instrumentation point log level condition" | |
258 | of a | |
259 | \link #LTTNG_DOMAIN_PYTHON Python\endlink | |
260 | recording event rule. | |
261 | ||
262 | @ingroup api_rer | |
263 | ||
264 | @sa #lttng_loglevel_type -- | |
265 | Operand of the log level condition of a recording event rule. | |
266 | */ | |
0e115563 | 267 | enum lttng_loglevel_python { |
048f01ef | 268 | /// Critical. |
28f23191 | 269 | LTTNG_LOGLEVEL_PYTHON_CRITICAL = 50, |
048f01ef PP |
270 | |
271 | /// Error. | |
28f23191 | 272 | LTTNG_LOGLEVEL_PYTHON_ERROR = 40, |
048f01ef PP |
273 | |
274 | /// Warning. | |
28f23191 | 275 | LTTNG_LOGLEVEL_PYTHON_WARNING = 30, |
048f01ef PP |
276 | |
277 | /// Information. | |
28f23191 | 278 | LTTNG_LOGLEVEL_PYTHON_INFO = 20, |
048f01ef PP |
279 | |
280 | /// Debugging. | |
28f23191 | 281 | LTTNG_LOGLEVEL_PYTHON_DEBUG = 10, |
048f01ef PP |
282 | |
283 | /// Logging turned off. | |
28f23191 | 284 | LTTNG_LOGLEVEL_PYTHON_NOTSET = 0, |
0e115563 DG |
285 | }; |
286 | ||
048f01ef PP |
287 | /*! |
288 | @brief | |
289 | Channel output type. | |
290 | ||
291 | @ingroup api_channel | |
292 | */ | |
1239a312 | 293 | enum lttng_event_output { |
048f01ef | 294 | /// Use the \lt_man_gen{splice,2} system call. |
28f23191 | 295 | LTTNG_EVENT_SPLICE = 0, |
048f01ef PP |
296 | |
297 | /// Use the \lt_man_gen{mmap,2} system call. | |
28f23191 | 298 | LTTNG_EVENT_MMAP = 1, |
1239a312 DG |
299 | }; |
300 | ||
048f01ef PP |
301 | /*! |
302 | @brief | |
303 | Context field type. | |
304 | ||
305 | @ingroup api_channel | |
306 | ||
307 | The following table indicates, for each enumerator, its description, for | |
308 | which \lt_obj_domain it's available, and the | |
309 | data type and the name of the resulting context field in traces. | |
310 | ||
311 | <table> | |
312 | <tr> | |
313 | <th>Enumerator | |
314 | <th>Description | |
315 | <th>Tracing domain | |
316 | <th>Field type | |
317 | <th>Field name | |
318 | <tr> | |
319 | <td>#LTTNG_EVENT_CONTEXT_PID | |
320 | <td>Process ID | |
321 | <td>#LTTNG_DOMAIN_KERNEL | |
322 | <td>Integer | |
323 | <td><code>pid</code> | |
324 | <tr> | |
325 | <td>#LTTNG_EVENT_CONTEXT_PROCNAME | |
326 | <td>Process name | |
327 | <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST | |
328 | <td>String | |
329 | <td><code>procname</code> | |
330 | <tr> | |
331 | <td>#LTTNG_EVENT_CONTEXT_PRIO | |
332 | <td>Process priority | |
333 | <td>#LTTNG_DOMAIN_KERNEL | |
334 | <td>Integer | |
335 | <td><code>prio</code> | |
336 | <tr> | |
337 | <td>#LTTNG_EVENT_CONTEXT_NICE | |
338 | <td>Nice value of the process | |
339 | <td>#LTTNG_DOMAIN_KERNEL | |
340 | <td>Integer | |
341 | <td><code>nice</code> | |
342 | <tr> | |
343 | <td>#LTTNG_EVENT_CONTEXT_VPID | |
344 | <td>Virtual process ID | |
345 | <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST | |
346 | <td>Integer | |
347 | <td><code>vpid</code> | |
348 | <tr> | |
349 | <td>#LTTNG_EVENT_CONTEXT_TID | |
350 | <td>Thread ID | |
351 | <td>#LTTNG_DOMAIN_KERNEL | |
352 | <td>Integer | |
353 | <td><code>tid</code> | |
354 | <tr> | |
355 | <td>#LTTNG_EVENT_CONTEXT_VTID | |
356 | <td>Virtual thread ID | |
357 | <td>#LTTNG_DOMAIN_KERNEL | |
358 | <td>Integer | |
359 | <td><code>vtid</code> | |
360 | <tr> | |
361 | <td>#LTTNG_EVENT_CONTEXT_PPID | |
362 | <td>ID of the parent process | |
363 | <td>#LTTNG_DOMAIN_KERNEL | |
364 | <td>Integer | |
365 | <td><code>ppid</code> | |
366 | <tr> | |
367 | <td>#LTTNG_EVENT_CONTEXT_VPPID | |
368 | <td>Virtual ID of the parent process | |
369 | <td>#LTTNG_DOMAIN_KERNEL | |
370 | <td>Integer | |
371 | <td><code>vppid</code> | |
372 | <tr> | |
373 | <td>#LTTNG_EVENT_CONTEXT_PTHREAD_ID | |
374 | <td>POSIX thread ID | |
375 | <td>#LTTNG_DOMAIN_KERNEL | |
376 | <td>Integer | |
377 | <td><code>pthread_id</code> | |
378 | <tr> | |
379 | <td>#LTTNG_EVENT_CONTEXT_HOSTNAME | |
380 | <td>Hostname | |
381 | <td>#LTTNG_DOMAIN_KERNEL | |
382 | <td>String | |
383 | <td><code>hostname</code> | |
384 | <tr> | |
385 | <td>#LTTNG_EVENT_CONTEXT_IP | |
386 | <td>Instruction pointer | |
387 | <td>#LTTNG_DOMAIN_UST | |
388 | <td>Integer | |
389 | <td><code>ip</code> | |
390 | <tr> | |
391 | <td>#LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER | |
392 | <td> | |
393 | Per-CPU perf counter. | |
394 | ||
395 | If the lttng_event_context::ctx member of an #lttng_event_context | |
396 | structure is #LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER, then the | |
397 | lttng_event_context::lttng_event_context_u::perf_counter member | |
398 | of lttng_event_context::u selects a specific per-CPU perf counter. | |
399 | <td>#LTTNG_DOMAIN_KERNEL | |
400 | <td>Integer | |
401 | <td>Depends on the selected perf counter | |
402 | <tr> | |
403 | <td>#LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER | |
404 | <td> | |
405 | Per-thread perf counter. | |
406 | ||
407 | If the lttng_event_context::ctx member of an #lttng_event_context | |
408 | structure is #LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER, then the | |
409 | lttng_event_context::lttng_event_context_u::perf_counter member | |
410 | of lttng_event_context::u selects a specific per-thread | |
411 | perf counter. | |
412 | <td>#LTTNG_DOMAIN_UST | |
413 | <td>Integer | |
414 | <td>Depends on the selected perf counter | |
415 | <tr> | |
416 | <td>#LTTNG_EVENT_CONTEXT_APP_CONTEXT | |
417 | <td> | |
418 | Application-specific context. | |
419 | ||
420 | If the lttng_event_context::ctx member of an #lttng_event_context | |
421 | structure is #LTTNG_EVENT_CONTEXT_APP_CONTEXT, then the | |
422 | lttng_event_context::lttng_event_context_u::app_ctx member of | |
423 | of lttng_event_context::u selects | |
424 | a specific application-specific context. | |
425 | <td>#LTTNG_DOMAIN_JUL or #LTTNG_DOMAIN_LOG4J | |
426 | <td>Integer or string | |
427 | <td>Depends on the selected application-specific context | |
428 | <tr> | |
429 | <td>#LTTNG_EVENT_CONTEXT_INTERRUPTIBLE | |
430 | <td>Whether or not the process is interruptible | |
431 | <td>#LTTNG_DOMAIN_KERNEL | |
432 | <td>Integer (0 or 1) | |
433 | <td><code>interruptible</code> | |
434 | <tr> | |
435 | <td>#LTTNG_EVENT_CONTEXT_PREEMPTIBLE | |
436 | <td>Whether or not the process is preemptible | |
437 | <td>#LTTNG_DOMAIN_KERNEL | |
438 | <td>Integer (0 or 1) | |
439 | <td><code>preemptible</code> | |
440 | <tr> | |
441 | <td>#LTTNG_EVENT_CONTEXT_NEED_RESCHEDULE | |
442 | <td>Whether or not the process needs a reschedule | |
443 | <td>#LTTNG_DOMAIN_KERNEL | |
444 | <td>Integer (0 or 1) | |
445 | <td><code>need_reschedule</code> | |
446 | <tr> | |
447 | <td>#LTTNG_EVENT_CONTEXT_MIGRATABLE | |
448 | <td>Whether or not the process is migratable | |
449 | <td>#LTTNG_DOMAIN_KERNEL | |
450 | <td>Integer (0 or 1) | |
451 | <td><code>migratable</code> | |
452 | <tr> | |
453 | <td>#LTTNG_EVENT_CONTEXT_CALLSTACK_KERNEL | |
454 | <td>Linux kernel call stack | |
455 | <td>#LTTNG_DOMAIN_KERNEL | |
456 | <td>Dynamic-length array of integers (instruction pointers) | |
457 | <td><code>callstack_kernel</code> | |
458 | <tr> | |
459 | <td>#LTTNG_EVENT_CONTEXT_CALLSTACK_USER | |
460 | <td> | |
461 | User space call stack. | |
462 | ||
463 | Only supported on IA-32 and x86-64 architectures. | |
464 | <td>#LTTNG_DOMAIN_KERNEL | |
465 | <td>Dynamic-length array of integers (instruction pointers) | |
466 | <td><code>callstack_user</code> | |
467 | <tr> | |
468 | <td>#LTTNG_EVENT_CONTEXT_CGROUP_NS | |
469 | <td> | |
470 | Control group root directory namespace ID. | |
471 | ||
472 | @sa \lt_man_gen{cgroup_namespaces,7} | |
473 | <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST | |
474 | <td>Integer | |
475 | <td><code>cgroup_ns</code> | |
476 | <tr> | |
477 | <td>#LTTNG_EVENT_CONTEXT_IPC_NS | |
478 | <td> | |
479 | System V IPC and POSIX message queue namespace ID. | |
480 | ||
481 | @sa \lt_man_gen{ipc_namespaces,7} | |
482 | <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST | |
483 | <td>Integer | |
484 | <td><code>ipc_ns</code> | |
485 | <tr> | |
486 | <td>#LTTNG_EVENT_CONTEXT_MNT_NS | |
487 | <td> | |
488 | Mount point namespace ID. | |
489 | ||
490 | @sa \lt_man_gen{mount_namespaces,7} | |
491 | <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST | |
492 | <td>Integer | |
493 | <td><code>mnt_ns</code> | |
494 | <tr> | |
495 | <td>#LTTNG_EVENT_CONTEXT_NET_NS | |
496 | <td> | |
497 | Networking namespace ID. | |
498 | ||
499 | @sa \lt_man_gen{network_namespaces,7} | |
500 | <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST | |
501 | <td>Integer | |
502 | <td><code>net_ns</code> | |
503 | <tr> | |
504 | <td>#LTTNG_EVENT_CONTEXT_PID_NS | |
505 | <td> | |
506 | Process ID namespace ID. | |
507 | ||
508 | @sa \lt_man_gen{pid_namespaces,7} | |
509 | <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST | |
510 | <td>Integer | |
511 | <td><code>pid_ns</code> | |
512 | <tr> | |
513 | <td>#LTTNG_EVENT_CONTEXT_USER_NS | |
514 | <td> | |
515 | User and group ID namespace ID. | |
516 | ||
517 | @sa \lt_man_gen{user_namespaces,7} | |
518 | <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST | |
519 | <td>Integer | |
520 | <td><code>user_ns</code> | |
521 | <tr> | |
522 | <td>#LTTNG_EVENT_CONTEXT_UTS_NS | |
523 | <td> | |
524 | Hostname and NIS domain name namespace ID. | |
525 | ||
526 | @sa \lt_man_gen{uts_namespaces,7} | |
527 | <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST | |
528 | <td>Integer | |
529 | <td><code>uts_ns</code> | |
530 | <tr> | |
531 | <td>#LTTNG_EVENT_CONTEXT_TIME_NS | |
532 | <td> | |
533 | Boot and monotonic clock namespace ID. | |
534 | ||
535 | @sa \lt_man_gen{time_namespaces,7} | |
536 | <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST | |
537 | <td>Integer | |
538 | <td><code>time_ns</code> | |
539 | <tr> | |
540 | <td>#LTTNG_EVENT_CONTEXT_UID | |
541 | <td>User ID | |
542 | <td>#LTTNG_DOMAIN_KERNEL | |
543 | <td>Integer | |
544 | <td><code>uid</code> | |
545 | <tr> | |
546 | <td>#LTTNG_EVENT_CONTEXT_EUID | |
547 | <td>Effective user ID | |
548 | <td>#LTTNG_DOMAIN_KERNEL | |
549 | <td>Integer | |
550 | <td><code>euid</code> | |
551 | <tr> | |
552 | <td>#LTTNG_EVENT_CONTEXT_SUID | |
553 | <td>Set owner user ID | |
554 | <td>#LTTNG_DOMAIN_KERNEL | |
555 | <td>Integer | |
556 | <td><code>suid</code> | |
557 | <tr> | |
558 | <td>#LTTNG_EVENT_CONTEXT_GID | |
559 | <td>Group ID | |
560 | <td>#LTTNG_DOMAIN_KERNEL | |
561 | <td>Integer | |
562 | <td><code>gid</code> | |
563 | <tr> | |
564 | <td>#LTTNG_EVENT_CONTEXT_EGID | |
565 | <td>Effective group ID | |
566 | <td>#LTTNG_DOMAIN_KERNEL | |
567 | <td>Integer | |
568 | <td><code>egid</code> | |
569 | <tr> | |
570 | <td>#LTTNG_EVENT_CONTEXT_SGID | |
571 | <td>Set owner group ID | |
572 | <td>#LTTNG_DOMAIN_KERNEL | |
573 | <td>Integer | |
574 | <td><code>sgid</code> | |
575 | <tr> | |
576 | <td>#LTTNG_EVENT_CONTEXT_VUID | |
577 | <td>Virtual user ID | |
578 | <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST | |
579 | <td>Integer | |
580 | <td><code>vuid</code> | |
581 | <tr> | |
582 | <td>#LTTNG_EVENT_CONTEXT_VEUID | |
583 | <td>Virtual effective user ID | |
584 | <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST | |
585 | <td>Integer | |
586 | <td><code>veuid</code> | |
587 | <tr> | |
588 | <td>#LTTNG_EVENT_CONTEXT_VSUID | |
589 | <td>Virtual set owner user ID | |
590 | <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST | |
591 | <td>Integer | |
592 | <td><code>vsuid</code> | |
593 | <tr> | |
594 | <td>#LTTNG_EVENT_CONTEXT_VGID | |
595 | <td>Virtual group ID | |
596 | <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST | |
597 | <td>Integer | |
598 | <td><code>vgid</code> | |
599 | <tr> | |
600 | <td>#LTTNG_EVENT_CONTEXT_VEGID | |
601 | <td>Virtual effective group ID | |
602 | <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST | |
603 | <td>Integer | |
604 | <td><code>vegid</code> | |
605 | <tr> | |
606 | <td>#LTTNG_EVENT_CONTEXT_VSGID | |
607 | <td>Virtual set owner group ID | |
608 | <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST | |
609 | <td>Integer | |
610 | <td><code>vsgid</code> | |
611 | </table> | |
612 | ||
613 | @ingroup api_channel | |
614 | */ | |
1239a312 | 615 | enum lttng_event_context_type { |
048f01ef | 616 | /// Process ID. |
28f23191 | 617 | LTTNG_EVENT_CONTEXT_PID = 0, |
048f01ef PP |
618 | |
619 | /// @cond BACKWARD_COMPAT_EVENT_CTX_TYPES | |
28f23191 | 620 | LTTNG_EVENT_CONTEXT_PERF_COUNTER = 1, /* Backward compat. */ |
048f01ef PP |
621 | /// @endcond |
622 | ||
623 | /// Process name. | |
28f23191 | 624 | LTTNG_EVENT_CONTEXT_PROCNAME = 2, |
048f01ef PP |
625 | |
626 | /// Process priority. | |
28f23191 | 627 | LTTNG_EVENT_CONTEXT_PRIO = 3, |
048f01ef PP |
628 | |
629 | /// Nice value of the process. | |
28f23191 | 630 | LTTNG_EVENT_CONTEXT_NICE = 4, |
048f01ef PP |
631 | |
632 | /// Virtual process ID. | |
28f23191 | 633 | LTTNG_EVENT_CONTEXT_VPID = 5, |
048f01ef PP |
634 | |
635 | /// Thread ID. | |
28f23191 | 636 | LTTNG_EVENT_CONTEXT_TID = 6, |
048f01ef PP |
637 | |
638 | /// Virtual thread ID. | |
28f23191 | 639 | LTTNG_EVENT_CONTEXT_VTID = 7, |
048f01ef PP |
640 | |
641 | /// ID of the parent process. | |
28f23191 | 642 | LTTNG_EVENT_CONTEXT_PPID = 8, |
048f01ef PP |
643 | |
644 | /// Virtual ID of the parent process. | |
28f23191 | 645 | LTTNG_EVENT_CONTEXT_VPPID = 9, |
048f01ef PP |
646 | |
647 | /// POSIX thread ID. | |
28f23191 | 648 | LTTNG_EVENT_CONTEXT_PTHREAD_ID = 10, |
048f01ef PP |
649 | |
650 | /// Hostname. | |
28f23191 | 651 | LTTNG_EVENT_CONTEXT_HOSTNAME = 11, |
048f01ef PP |
652 | |
653 | /// Instruction pointer. | |
28f23191 | 654 | LTTNG_EVENT_CONTEXT_IP = 12, |
048f01ef PP |
655 | |
656 | /// Per-CPU perf counter. | |
28f23191 | 657 | LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER = 13, |
048f01ef PP |
658 | |
659 | /// Per-thread perf counter. | |
1239a312 | 660 | LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER = 14, |
048f01ef PP |
661 | |
662 | /// Application-specific context. | |
28f23191 | 663 | LTTNG_EVENT_CONTEXT_APP_CONTEXT = 15, |
048f01ef PP |
664 | |
665 | /// Whether or not the process is interruptible. | |
28f23191 | 666 | LTTNG_EVENT_CONTEXT_INTERRUPTIBLE = 16, |
048f01ef PP |
667 | |
668 | /// Whether or not the process is preemptible. | |
28f23191 | 669 | LTTNG_EVENT_CONTEXT_PREEMPTIBLE = 17, |
048f01ef PP |
670 | |
671 | /// Whether or not the process needs a reschedule. | |
28f23191 | 672 | LTTNG_EVENT_CONTEXT_NEED_RESCHEDULE = 18, |
048f01ef PP |
673 | |
674 | /// Whether or not the process is migratable. | |
28f23191 | 675 | LTTNG_EVENT_CONTEXT_MIGRATABLE = 19, |
048f01ef PP |
676 | |
677 | /// Linux kernel call stack. | |
28f23191 | 678 | LTTNG_EVENT_CONTEXT_CALLSTACK_KERNEL = 20, |
048f01ef PP |
679 | |
680 | /// User space call stack. | |
681 | LTTNG_EVENT_CONTEXT_CALLSTACK_USER = 21, | |
682 | ||
683 | /// Control group root directory namespace ID. | |
28f23191 | 684 | LTTNG_EVENT_CONTEXT_CGROUP_NS = 22, |
048f01ef PP |
685 | |
686 | /// System V IPC and POSIX message queue namespace ID. | |
28f23191 | 687 | LTTNG_EVENT_CONTEXT_IPC_NS = 23, |
048f01ef PP |
688 | |
689 | /// Mount point namespace ID. | |
28f23191 | 690 | LTTNG_EVENT_CONTEXT_MNT_NS = 24, |
048f01ef PP |
691 | |
692 | /// Networking namespace ID. | |
28f23191 | 693 | LTTNG_EVENT_CONTEXT_NET_NS = 25, |
048f01ef PP |
694 | |
695 | /// Process ID namespace ID. | |
28f23191 | 696 | LTTNG_EVENT_CONTEXT_PID_NS = 26, |
048f01ef PP |
697 | |
698 | /// User and group ID namespace ID. | |
28f23191 | 699 | LTTNG_EVENT_CONTEXT_USER_NS = 27, |
048f01ef PP |
700 | |
701 | /// Hostname and NIS domain name namespace ID. | |
28f23191 | 702 | LTTNG_EVENT_CONTEXT_UTS_NS = 28, |
048f01ef PP |
703 | |
704 | /// User ID namespace ID. | |
28f23191 | 705 | LTTNG_EVENT_CONTEXT_UID = 29, |
048f01ef PP |
706 | |
707 | /// Effective user ID namespace ID. | |
28f23191 | 708 | LTTNG_EVENT_CONTEXT_EUID = 30, |
048f01ef PP |
709 | |
710 | /// Set owner user ID namespace ID. | |
28f23191 | 711 | LTTNG_EVENT_CONTEXT_SUID = 31, |
048f01ef PP |
712 | |
713 | /// Group ID namespace ID. | |
28f23191 | 714 | LTTNG_EVENT_CONTEXT_GID = 32, |
048f01ef PP |
715 | |
716 | /// Effective group ID namespace ID. | |
28f23191 | 717 | LTTNG_EVENT_CONTEXT_EGID = 33, |
048f01ef PP |
718 | |
719 | /// Set owner group ID namespace ID. | |
28f23191 | 720 | LTTNG_EVENT_CONTEXT_SGID = 34, |
048f01ef PP |
721 | |
722 | /// Virtual user ID namespace ID. | |
28f23191 | 723 | LTTNG_EVENT_CONTEXT_VUID = 35, |
048f01ef PP |
724 | |
725 | /// Virtual effective user ID namespace ID. | |
28f23191 | 726 | LTTNG_EVENT_CONTEXT_VEUID = 36, |
048f01ef PP |
727 | |
728 | /// Virtual set owner user ID namespace ID. | |
28f23191 | 729 | LTTNG_EVENT_CONTEXT_VSUID = 37, |
048f01ef PP |
730 | |
731 | /// Virtual group ID namespace ID. | |
28f23191 | 732 | LTTNG_EVENT_CONTEXT_VGID = 38, |
048f01ef PP |
733 | |
734 | /// Virtual effective group ID namespace ID. | |
28f23191 | 735 | LTTNG_EVENT_CONTEXT_VEGID = 39, |
048f01ef PP |
736 | |
737 | /// Virtual set owner group ID namespace ID. | |
28f23191 | 738 | LTTNG_EVENT_CONTEXT_VSGID = 40, |
048f01ef PP |
739 | |
740 | /// Boot and monotonic clock namespace ID. | |
28f23191 | 741 | LTTNG_EVENT_CONTEXT_TIME_NS = 41, |
1239a312 DG |
742 | }; |
743 | ||
048f01ef PP |
744 | /*! |
745 | @brief | |
746 | LTTng tracepoint field data type | |
747 | (type of the lttng_event_field::type member). | |
748 | ||
749 | @ingroup api_inst_pt | |
750 | */ | |
1239a312 | 751 | enum lttng_event_field_type { |
048f01ef | 752 | /// Other/unknown. |
28f23191 | 753 | LTTNG_EVENT_FIELD_OTHER = 0, |
048f01ef PP |
754 | |
755 | /// Integer. | |
28f23191 | 756 | LTTNG_EVENT_FIELD_INTEGER = 1, |
048f01ef PP |
757 | |
758 | /// Enumeration. | |
28f23191 | 759 | LTTNG_EVENT_FIELD_ENUM = 2, |
048f01ef PP |
760 | |
761 | /// Floating point number. | |
28f23191 | 762 | LTTNG_EVENT_FIELD_FLOAT = 3, |
048f01ef PP |
763 | |
764 | /// String. | |
28f23191 | 765 | LTTNG_EVENT_FIELD_STRING = 4, |
1239a312 DG |
766 | }; |
767 | ||
048f01ef PP |
768 | /*! |
769 | @brief | |
770 | \ref api-rer-inst-pt-descr "Instrumentation point descriptor" | |
771 | flag (type of the lttng_event::flags member). | |
772 | ||
773 | @ingroup api_inst_pt | |
774 | */ | |
834978fd | 775 | enum lttng_event_flag { |
048f01ef PP |
776 | /*! |
777 | @brief | |
778 | 32-bit Linux system call. | |
779 | ||
780 | Only valid when the lttng_event::type member is | |
781 | #LTTNG_EVENT_SYSCALL. | |
782 | */ | |
28f23191 | 783 | LTTNG_EVENT_FLAG_SYSCALL_32 = (1U << 0), |
048f01ef PP |
784 | |
785 | /*! | |
786 | @brief | |
787 | 64-bit Linux system call. | |
788 | ||
789 | Only valid when the lttng_event::type member is | |
790 | #LTTNG_EVENT_SYSCALL. | |
791 | */ | |
28f23191 | 792 | LTTNG_EVENT_FLAG_SYSCALL_64 = (1U << 1), |
834978fd DG |
793 | }; |
794 | ||
28f23191 | 795 | #define LTTNG_PERF_EVENT_PADDING1 16 |
048f01ef PP |
796 | |
797 | /*! | |
798 | @brief | |
799 | perf counter context field descriptor. | |
800 | ||
801 | @ingroup api_channel | |
802 | ||
803 | If the lttng_event_context::ctx member of an #lttng_event_context | |
804 | structure is #LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER or | |
805 | #LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER, then the | |
806 | lttng_event_context::lttng_event_context_u::perf_counter member | |
807 | of lttng_event_context::u selects a specific perf counter. | |
808 | ||
809 | You must initialize such a structure to zeros before setting its members | |
810 | and using it, for example: | |
811 | ||
812 | @code | |
813 | struct lttng_event_perf_counter_ctx perf_counter_ctx; | |
814 | ||
815 | memset(&perf_counter_ctx, 0, sizeof(perf_counter_ctx)); | |
816 | @endcode | |
817 | */ | |
1239a312 | 818 | struct lttng_event_perf_counter_ctx { |
048f01ef PP |
819 | /*! |
820 | @brief | |
821 | perf counter type ID. | |
822 | ||
823 | One of: | |
824 | ||
825 | <table> | |
826 | <tr> | |
827 | <th>Type | |
828 | <th>ID | |
829 | <tr> | |
830 | <td>Hardware counter | |
831 | <td>0 | |
832 | <tr> | |
833 | <td>Software counter | |
834 | <td>1 | |
835 | <tr> | |
836 | <td>Hardware cache counter | |
837 | <td>3 | |
838 | <tr> | |
839 | <td>Performance Monitoring Unit (PMU) counter | |
840 | <td>4 | |
841 | </table> | |
842 | */ | |
1239a312 | 843 | uint32_t type; |
048f01ef PP |
844 | |
845 | /*! | |
846 | @brief | |
847 | perf counter configuration. | |
848 | ||
849 | Depending on the lttng_event_perf_counter_ctx::type member: | |
850 | ||
851 | <dl> | |
852 | <dt>0 (hardware counter) | |
853 | <dd> | |
854 | One of: | |
855 | ||
856 | <table> | |
857 | <tr> | |
858 | <th>Counter | |
859 | <th>ID | |
860 | <tr> | |
861 | <td>CPU cycles | |
862 | <td>0 | |
863 | <tr> | |
864 | <td>Instructions | |
865 | <td>1 | |
866 | <tr> | |
867 | <td>Cache references | |
868 | <td>2 | |
869 | <tr> | |
870 | <td>Cache misses | |
871 | <td>3 | |
872 | <tr> | |
873 | <td>Branch instructions | |
874 | <td>4 | |
875 | <tr> | |
876 | <td>Branch misses | |
877 | <td>5 | |
878 | <tr> | |
879 | <td>Bus cycles | |
880 | <td>6 | |
881 | <tr> | |
882 | <td>Stalled cycles (front end) | |
883 | <td>7 | |
884 | <tr> | |
885 | <td>Stalled cycles (back end) | |
886 | <td>8 | |
887 | </table> | |
888 | ||
889 | <dt>1 (software counter) | |
890 | <dd> | |
891 | One of: | |
892 | ||
893 | <table> | |
894 | <tr> | |
895 | <th>Counter | |
896 | <th>ID | |
897 | <tr> | |
898 | <td>CPU clock | |
899 | <td>0 | |
900 | <tr> | |
901 | <td>Task clock | |
902 | <td>1 | |
903 | <tr> | |
904 | <td>Page faults | |
905 | <td>2 | |
906 | <tr> | |
907 | <td>Context switches | |
908 | <td>3 | |
909 | <tr> | |
910 | <td>CPU migrations | |
911 | <td>4 | |
912 | <tr> | |
913 | <td>Minor page faults | |
914 | <td>5 | |
915 | <tr> | |
916 | <td>Major page faults | |
917 | <td>6 | |
918 | <tr> | |
919 | <td>Alignment faults | |
920 | <td>7 | |
921 | <tr> | |
922 | <td>Emulation faults | |
923 | <td>8 | |
924 | </table> | |
925 | ||
926 | <dt>3 (hardware cache counter) | |
927 | <dd> | |
928 | The result of a bitwise OR operation between a cache ID, | |
929 | an operation ID, and a result ID, as follows: | |
930 | ||
931 | <table> | |
932 | <tr> | |
933 | <th>Cache ID | |
934 | <th>Description | |
935 | <tr> | |
936 | <td>0 | |
937 | <td>Data L1 | |
938 | <tr> | |
939 | <td>1 | |
940 | <td>Instructions L1 | |
941 | <tr> | |
942 | <td>2 | |
943 | <td>LL | |
944 | <tr> | |
945 | <td>3 | |
946 | <td>Data <a | |
947 | href="https://en.wikipedia.org/wiki/Translation_lookaside_buffer">TLB</a> <tr> <td>4 | |
948 | <td>Instruction TLB | |
949 | <tr> | |
950 | <td>5 | |
951 | <td>Branch prediction unit (BPU) | |
952 | </table> | |
953 | ||
954 | <table> | |
955 | <tr> | |
956 | <th>Operator ID | |
957 | <th>Description | |
958 | <tr> | |
959 | <td>0 | |
960 | <td>Read | |
961 | <tr> | |
962 | <td>0x100 | |
963 | <td>Write | |
964 | <tr> | |
965 | <td>0x200 | |
966 | <td>Prefetch | |
967 | </table> | |
968 | ||
969 | <table> | |
970 | <tr> | |
971 | <th>Result ID | |
972 | <th>Description | |
973 | <tr> | |
974 | <td>0 | |
975 | <td>Access | |
976 | <tr> | |
977 | <td>0x10000 | |
978 | <td>Miss | |
979 | </table> | |
980 | ||
981 | <dt>4 (PMU counter) | |
982 | <dd> | |
983 | PMU counter raw ID. | |
984 | ||
985 | @sa \lt_man_gen{perf-record,1} | |
986 | </dl> | |
987 | */ | |
1239a312 | 988 | uint64_t config; |
048f01ef PP |
989 | |
990 | /// Context field name. | |
1239a312 DG |
991 | char name[LTTNG_SYMBOL_NAME_LEN]; |
992 | ||
993 | char padding[LTTNG_PERF_EVENT_PADDING1]; | |
994 | }; | |
995 | ||
28f23191 | 996 | #define LTTNG_EVENT_CONTEXT_PADDING1 16 |
07c4863f | 997 | #define LTTNG_EVENT_CONTEXT_PADDING2 (LTTNG_SYMBOL_NAME_LEN + 32) |
048f01ef PP |
998 | |
999 | /*! | |
1000 | @brief | |
1001 | Context field descriptor. | |
1002 | ||
1003 | @ingroup api_channel | |
1004 | ||
1005 | Such a structure describes a context field to be recorded within all the | |
1006 | \ref api_rer "event records" of a given \lt_obj_channel (see | |
1007 | lttng_add_context()). | |
1008 | ||
1009 | You must initialize such a structure to zeros before setting its members | |
1010 | and using it, for example: | |
1011 | ||
1012 | @code | |
1013 | struct lttng_event_context ctx; | |
1014 | ||
1015 | memset(&ctx, 0, sizeof(ctx)); | |
1016 | @endcode | |
1017 | */ | |
1239a312 | 1018 | struct lttng_event_context { |
048f01ef PP |
1019 | /*! |
1020 | @brief | |
1021 | Context field type. | |
1022 | ||
1023 | Some types have a \lt_obj_domain | |
1024 | constraint. | |
1025 | ||
1026 | If this member has the value | |
1027 | #LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER or | |
1028 | #LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER, then you must also set | |
1029 | the lttng_event_context::lttng_event_context_u::perf_counter | |
1030 | member of lttng_event_context::u. | |
1031 | ||
1032 | If this member has the value #LTTNG_EVENT_CONTEXT_APP_CONTEXT, | |
1033 | then you must also set the | |
1034 | lttng_event_context::lttng_event_context_u::app_ctx member | |
1035 | of lttng_event_context::u. | |
1036 | */ | |
1239a312 | 1037 | enum lttng_event_context_type ctx; |
048f01ef | 1038 | |
1239a312 DG |
1039 | char padding[LTTNG_EVENT_CONTEXT_PADDING1]; |
1040 | ||
048f01ef PP |
1041 | /*! |
1042 | @brief | |
1043 | perf counter or application-specific context field | |
1044 | descriptor. | |
1045 | ||
1046 | @ingroup api_channel | |
1047 | */ | |
1048 | union lttng_event_context_u { | |
1049 | /*! | |
1050 | @brief | |
1051 | perf counter context field descriptor. | |
1052 | ||
1053 | Only used when the lttng_event_context::ctx member | |
1054 | is #LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER or | |
1055 | #LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER. | |
1056 | */ | |
1239a312 | 1057 | struct lttng_event_perf_counter_ctx perf_counter; |
048f01ef | 1058 | |
2001793c | 1059 | struct { |
048f01ef | 1060 | /// Provider name. |
2001793c | 1061 | char *provider_name; |
048f01ef PP |
1062 | |
1063 | /// Field type. | |
2001793c | 1064 | char *ctx_name; |
048f01ef PP |
1065 | } |
1066 | ||
1067 | /*! | |
1068 | @brief | |
1069 | Application-specific context field descriptor. | |
1070 | ||
1071 | Only used when the lttng_event_context::ctx member | |
1072 | is #LTTNG_EVENT_CONTEXT_APP_CONTEXT. | |
1073 | */ | |
1074 | app_ctx; | |
1075 | ||
1239a312 | 1076 | char padding[LTTNG_EVENT_CONTEXT_PADDING2]; |
048f01ef PP |
1077 | } |
1078 | ||
1079 | /// perf counter or application-specific context field descriptor. | |
1080 | u; | |
1239a312 DG |
1081 | }; |
1082 | ||
28f23191 | 1083 | #define LTTNG_EVENT_PROBE_PADDING1 16 |
048f01ef PP |
1084 | |
1085 | /*! | |
1086 | @brief | |
1087 | Legacy Linux kprobe/kretprobe location. | |
1088 | ||
1089 | @ingroup api_rer | |
1090 | ||
1091 | Such a structure indicates the location of a Linux kprobe/kretprobe for | |
1092 | a \lt_obj_rer having such an instrumentation point type. | |
1093 | ||
1094 | You must initialize such a structure to zeros before setting its members | |
1095 | and using it, for example: | |
1096 | ||
1097 | @code | |
1098 | struct lttng_event_probe_attr loc; | |
1099 | ||
1100 | memset(&loc, 0, sizeof(loc)); | |
1101 | @endcode | |
1102 | ||
1103 | Set either lttng_event_probe_attr::addr or | |
1104 | lttng_event_probe_attr::symbol_name and lttng_event_probe_attr::offset. | |
1105 | ||
1106 | @sa \ref api-rer-conds-inst-pt-type "Instrumentation point type condition". | |
1107 | */ | |
1239a312 | 1108 | struct lttng_event_probe_attr { |
048f01ef PP |
1109 | /*! |
1110 | @brief | |
1111 | kprobe/kretprobe address. | |
1112 | ||
1113 | If this member is not 0, then | |
1114 | lttng_event_probe_attr::symbol_name must be an empty string. | |
1115 | */ | |
1239a312 DG |
1116 | uint64_t addr; |
1117 | ||
048f01ef PP |
1118 | /*! |
1119 | @brief | |
1120 | kprobe/kretprobe address offset from the symbol named | |
1121 | lttng_event_probe_attr::symbol_name. | |
1122 | */ | |
1239a312 | 1123 | uint64_t offset; |
048f01ef PP |
1124 | |
1125 | /*! | |
1126 | @brief | |
1127 | kprobe/kretprobe symbol name. | |
1128 | ||
1129 | The actual kprobe/kretprobe address is the address of the named | |
1130 | symbol plus the value of lttng_event_probe_attr::offset. | |
1131 | ||
1132 | If this member is not an empty string, then | |
1133 | lttng_event_probe_attr::addr must be 0. | |
1134 | */ | |
1239a312 DG |
1135 | char symbol_name[LTTNG_SYMBOL_NAME_LEN]; |
1136 | ||
1137 | char padding[LTTNG_EVENT_PROBE_PADDING1]; | |
1138 | }; | |
1139 | ||
1140 | /* | |
1141 | * Function tracer | |
1142 | * | |
1143 | * The structures should be initialized to zero before use. | |
1144 | */ | |
28f23191 | 1145 | #define LTTNG_EVENT_FUNCTION_PADDING1 16 |
1239a312 DG |
1146 | struct lttng_event_function_attr { |
1147 | char symbol_name[LTTNG_SYMBOL_NAME_LEN]; | |
1148 | ||
1149 | char padding[LTTNG_EVENT_FUNCTION_PADDING1]; | |
1150 | }; | |
1151 | ||
1152 | /* | |
1153 | * Generic lttng event | |
1154 | * | |
1155 | * The structures should be initialized to zero before use. | |
1156 | */ | |
28f23191 | 1157 | #define LTTNG_EVENT_PADDING1 12 |
07c4863f | 1158 | #define LTTNG_EVENT_PADDING2 (LTTNG_SYMBOL_NAME_LEN + 32) |
048f01ef PP |
1159 | |
1160 | /*! | |
1161 | @brief | |
1162 | \lt_obj_c_rer descriptor. | |
1163 | ||
1164 | @ingroup api_rer | |
1165 | ||
1166 | Such a structure describes a recording event rule. More specifically, | |
1167 | it describes the \ref api-rer-conds "conditions" of a recording | |
1168 | event rule. | |
1169 | ||
1170 | lttng_list_events() sets a pointer to an array of all the recording | |
1171 | event rule descriptors of a given \lt_obj_channel. | |
1172 | ||
1173 | @note | |
1174 | \anchor api-rer-inst-pt-descr lttng_list_tracepoints() | |
1175 | and lttng_list_syscalls() also set | |
1176 | a pointer to an array of instances of this structure. In this | |
1177 | context, the #lttng_event structure is named | |
1178 | \"<em>instrumentation point descriptor</em>\". | |
1179 | ||
1180 | lttng_enable_event(), lttng_enable_event_with_filter(), and | |
1181 | lttng_enable_event_with_exclusions() expect such a structure to create | |
1182 | or enable a recording event rule. | |
1183 | ||
1184 | Most properties are members of the structure itself, but the | |
1185 | following ones have their own dedicated accessors: | |
1186 | ||
1187 | <dl> | |
1188 | <dt> | |
1189 | Linux uprobe location (when the lttng_event::type member is | |
1190 | #LTTNG_EVENT_USERSPACE_PROBE) | |
1191 | <dd> | |
1192 | - lttng_event_get_userspace_probe_location() | |
1193 | - lttng_event_set_userspace_probe_location() | |
1194 | ||
1195 | <dt>\ref api-rer-conds-event-name "Event name" exclusion patterns | |
1196 | <dd> | |
1197 | lttng_event_get_exclusion_name() | |
1198 | ||
1199 | <dt>\ref api-rer-conds-filter "Event payload and context filter" expression | |
1200 | <dd> | |
1201 | lttng_event_get_filter_expression() | |
1202 | </dl> | |
1203 | ||
1204 | Create an empty recording event rule descriptor with | |
1205 | lttng_event_create(). | |
1206 | ||
1207 | \anchor api-rer-valid-event-struct A \em valid #lttng_event structure | |
1208 | satisfies the following constraints: | |
1209 | ||
1210 | - If the lttng_event::type member is #LTTNG_EVENT_PROBE or | |
1211 | #LTTNG_EVENT_FUNCTION, then the lttng_event::lttng_event_attr_u::probe | |
1212 | member of lttng_event::attr is valid according to the | |
1213 | documentation of #lttng_event_probe_attr. | |
1214 | ||
1215 | - If the lttng_event::type member is #LTTNG_EVENT_USERSPACE_PROBE, then | |
1216 | the recording event rule descriptor has a Linux uprobe location | |
1217 | (you called lttng_event_set_userspace_probe_location() on it to | |
1218 | set it). | |
1219 | ||
1220 | Destroy a recording event rule descriptor with lttng_event_destroy(). | |
1221 | */ | |
1239a312 | 1222 | struct lttng_event { |
fe9ecacb | 1223 | /* Offset 0 */ |
048f01ef | 1224 | /// \ref api-rer-conds-inst-pt-type "Instrumentation point type condition". |
1239a312 | 1225 | enum lttng_event_type type; |
fe9ecacb PP |
1226 | |
1227 | /* Offset 4 */ | |
048f01ef PP |
1228 | /*! |
1229 | @brief \ref api-rer-conds-event-name "Event name" pattern | |
1230 | condition. | |
1231 | ||
1232 | If empty, lttng_enable_event(), | |
1233 | lttng_enable_event_with_filter(), and | |
1234 | lttng_enable_event_with_exclusions() use <code>*</code> (match | |
1235 | events with any name). | |
1236 | ||
1237 | If the lttng_event::type member is #LTTNG_EVENT_PROBE, | |
1238 | #LTTNG_EVENT_FUNCTION, or #LTTNG_EVENT_USERSPACE_PROBE, then | |
1239 | this member is actually the name of the created Linux | |
1240 | kprobe/kretprobe/uprobe instrumentation point (future event | |
1241 | name). | |
1242 | ||
1243 | If this structure is an | |
1244 | \ref api-rer-inst-pt-descr "instrumentation point descriptor", | |
1245 | then this member is the name of the LTTng tracepoint, Linux | |
1246 | system call, or Java/Python logger. | |
1247 | */ | |
1239a312 DG |
1248 | char name[LTTNG_SYMBOL_NAME_LEN]; |
1249 | ||
fe9ecacb | 1250 | /* Offset 260 */ |
048f01ef PP |
1251 | /*! |
1252 | @brief | |
1253 | Operand of the | |
1254 | \ref api-rer-conds-ll "instrumentation point log level condition". | |
1255 | */ | |
1239a312 | 1256 | enum lttng_loglevel_type loglevel_type; |
fe9ecacb PP |
1257 | |
1258 | /* Offset 264 */ | |
048f01ef PP |
1259 | /*! |
1260 | @brief Value of the | |
1261 | \ref api-rer-conds-ll "instrumentation point log level condition". | |
1262 | ||
1263 | This member must be one of the enumerators of | |
1264 | #lttng_loglevel, #lttng_loglevel_jul, #lttng_loglevel_log4j, or | |
1265 | #lttng_loglevel_python, depending on the | |
1266 | \lt_obj_domain when you call lttng_enable_event(), | |
1267 | lttng_enable_event_with_filter(), or | |
1268 | lttng_enable_event_with_exclusions(). | |
1269 | ||
1270 | If this structure is an | |
1271 | \ref api-rer-inst-pt-descr "instrumentation point descriptor", | |
1272 | then this member is the log level of the LTTng tracepoint or | |
1273 | Java/Python logger. | |
1274 | */ | |
1239a312 DG |
1275 | int loglevel; |
1276 | ||
fe9ecacb | 1277 | /* Offset 268 */ |
048f01ef PP |
1278 | /*! |
1279 | @brief | |
1280 | 1 if this recording event rule is enabled, or 0 otherwise. | |
1281 | ||
1282 | This is a read-only member. | |
1283 | ||
1284 | @sa lttng_enable_event() -- | |
1285 | Creates or enables a recording event rule. | |
1286 | @sa lttng_disable_event_ext() -- | |
1287 | Disables a recording event rule. | |
1288 | */ | |
28f23191 | 1289 | int32_t enabled; /* Does not apply: -1 */ |
fe9ecacb PP |
1290 | |
1291 | /* Offset 272 */ | |
048f01ef PP |
1292 | /*! |
1293 | @brief | |
1294 | ID of the process which offers the instrumentation point | |
1295 | described by this structure. | |
1296 | ||
1297 | This is a read-only member. | |
1298 | ||
1299 | This member is \em not part of a recording event rule. | |
1300 | */ | |
1239a312 | 1301 | pid_t pid; |
fe9ecacb PP |
1302 | |
1303 | /* Offset 276 */ | |
048f01ef PP |
1304 | /*! |
1305 | @brief | |
1306 | 1 if the recording event rule described by this has an | |
1307 | \ref api-rer-conds-filter "event payload and context filter" | |
1308 | expression, or 0 otherwise. | |
1309 | ||
1310 | This is a read-only member: use the \lt_p{filter_expr} parameter | |
1311 | of lttng_enable_event_with_filter() or | |
1312 | lttng_enable_event_with_exclusions() when you create a | |
1313 | recording event rule to set an event payload and context | |
1314 | filter expression. | |
1315 | ||
1316 | If this member is 1, then get the actual filter expression | |
1317 | string with lttng_event_get_filter_expression(). | |
1318 | */ | |
1319 | unsigned char filter; | |
fe9ecacb PP |
1320 | |
1321 | /* Offset 277 */ | |
048f01ef PP |
1322 | /*! |
1323 | @brief | |
1324 | 1 if the recording event rule described by this has | |
1325 | \ref api-rer-conds-event-name "event name" exclusion | |
1326 | patterns (part of the event name condition), or 0 otherwise. | |
1327 | ||
1328 | This is a read-only member: use the | |
1329 | \lt_p{event_name_exclusion_count} and | |
1330 | \lt_p{event_name_exclusions} parameters of | |
1331 | lttng_enable_event_with_exclusions() when you create a recording | |
1332 | event rule to set event name exclusion patterns. | |
1333 | ||
1334 | If this member is 1, then get the actual event name exclusion | |
1335 | patterns with lttng_event_get_exclusion_name_count() and | |
1336 | lttng_event_get_exclusion_name(). | |
1337 | */ | |
1338 | unsigned char exclusion; | |
1239a312 | 1339 | |
fe9ecacb PP |
1340 | /* Offset 278 */ |
1341 | char padding2[2]; | |
1342 | ||
1343 | /* Offset 280 */ | |
048f01ef PP |
1344 | /*! |
1345 | @brief | |
1346 | \ref api-rer-inst-pt-descr "Instrumentation point descriptor" | |
1347 | flags (bitwise OR). | |
1348 | ||
1349 | This is a read-only member. | |
1350 | ||
1351 | This member is \em not part of a recording event rule. | |
1352 | */ | |
834978fd DG |
1353 | enum lttng_event_flag flags; |
1354 | ||
fe9ecacb | 1355 | /* Offset 284 */ |
b4e3ceb9 PP |
1356 | char padding[4]; |
1357 | ||
1358 | /* Offset 288 */ | |
1359 | union { | |
4829ae55 | 1360 | uint64_t padding; |
b4e3ceb9 PP |
1361 | void *ptr; |
1362 | } extended; | |
1239a312 | 1363 | |
fe9ecacb | 1364 | /* Offset 296 */ |
048f01ef PP |
1365 | /*! |
1366 | @brief | |
1367 | Linux kprobe/kretprobe recording event rule configuration. | |
1368 | ||
1369 | @ingroup api_rer | |
1370 | */ | |
1371 | union lttng_event_attr_u { | |
1372 | /*! | |
1373 | @brief | |
1374 | Linux kprobe/kretprobe location. | |
1375 | ||
1376 | Only valid when the lttng_event::type member is | |
1377 | #LTTNG_EVENT_PROBE or #LTTNG_EVENT_FUNCTION. | |
1378 | */ | |
1239a312 | 1379 | struct lttng_event_probe_attr probe; |
048f01ef | 1380 | |
1239a312 DG |
1381 | struct lttng_event_function_attr ftrace; |
1382 | ||
1383 | char padding[LTTNG_EVENT_PADDING2]; | |
048f01ef PP |
1384 | } |
1385 | ||
1386 | /*! | |
1387 | @brief | |
1388 | Linux kprobe/kretprobe recording event rule configuration. | |
1389 | ||
1390 | Only valid when the lttng_event::type member is | |
1391 | #LTTNG_EVENT_PROBE or #LTTNG_EVENT_FUNCTION. | |
1392 | */ | |
1393 | attr; | |
1239a312 DG |
1394 | }; |
1395 | ||
07c4863f | 1396 | #define LTTNG_EVENT_FIELD_PADDING (LTTNG_SYMBOL_NAME_LEN + 32) |
048f01ef PP |
1397 | |
1398 | /*! | |
1399 | @brief | |
1400 | LTTng tracepoint field description. | |
1401 | ||
1402 | @ingroup api_inst_pt | |
1403 | ||
1404 | lttng_list_tracepoint_fields() sets a pointer to an array of all the | |
1405 | tracepoint field descriptions of a given \lt_obj_domain. | |
1406 | */ | |
1239a312 | 1407 | struct lttng_event_field { |
048f01ef | 1408 | /// Field name. |
1239a312 | 1409 | char field_name[LTTNG_SYMBOL_NAME_LEN]; |
048f01ef PP |
1410 | |
1411 | /// Field data type. | |
1239a312 | 1412 | enum lttng_event_field_type type; |
048f01ef | 1413 | |
1239a312 | 1414 | char padding[LTTNG_EVENT_FIELD_PADDING]; |
048f01ef PP |
1415 | |
1416 | /*! | |
1417 | @brief | |
1418 | \ref api-rer-inst-pt-descr "Descriptor" of the tracepoint | |
1419 | which contains this field. | |
1420 | */ | |
1239a312 | 1421 | struct lttng_event event; |
048f01ef PP |
1422 | |
1423 | /*! | |
1424 | @brief | |
1425 | 0 if LTTng writes this field to an event record, or 1 | |
1426 | otherwise. | |
1427 | */ | |
1239a312 DG |
1428 | int nowrite; |
1429 | }; | |
1430 | ||
048f01ef PP |
1431 | /*! |
1432 | @brief | |
1433 | Sets \lt_p{*event_rules} to the descriptors of the | |
1434 | \lt_obj_rers of the \lt_obj_channel named \lt_p{channel_name} | |
1435 | within the recording session handle \lt_p{handle}. | |
1436 | ||
1437 | @ingroup api_channel | |
1438 | ||
1439 | @param[in] handle | |
1440 | Recording session handle which contains the name of the | |
1441 | recording session and the summary | |
1442 | of the \lt_obj_domain which own the channel (named | |
1443 | \lt_p{channel_name}) of which to get the recording event rule | |
1444 | descriptors. | |
1445 | @param[in] channel_name | |
1446 | Name of the channel, within \lt_p{handle}, of which to get all the | |
1447 | recording event rule descriptors. | |
1448 | @param[out] event_rules | |
1449 | @parblock | |
1450 | <strong>On success</strong>, this function sets \lt_p{*event_rules} | |
1451 | to the recording event rule descriptors. | |
1452 | ||
1453 | Free \lt_p{*event_rules} with <code>free()</code>. | |
1454 | @endparblock | |
1455 | ||
1456 | @returns | |
1457 | The number of items in \lt_p{*event_rules} on success, or a | |
1458 | \em negative #lttng_error_code enumerator otherwise. | |
1459 | ||
1460 | @lt_pre_conn | |
1461 | @lt_pre_not_null{handle} | |
1462 | @lt_pre_valid_c_str{handle->session_name} | |
1463 | @lt_pre_sess_exists{handle->session_name} | |
1464 | @pre | |
1465 | \lt_p{handle->domain} is valid as per the documentation of | |
1466 | #lttng_domain. | |
1467 | @lt_pre_not_null{channel_name} | |
1468 | @pre | |
1469 | \lt_p{channel_name} names an existing channel within the recording | |
1470 | session and tracing domain of \lt_p{handle}. | |
1471 | @lt_pre_not_null{event_rules} | |
1472 | */ | |
4bd69c5f | 1473 | LTTNG_EXPORT extern int lttng_list_events(struct lttng_handle *handle, |
28f23191 | 1474 | const char *channel_name, |
048f01ef | 1475 | struct lttng_event **event_rules); |
1239a312 | 1476 | |
048f01ef PP |
1477 | /*! |
1478 | @brief | |
1479 | Creates and returns an empty recording event rule descriptor. | |
1480 | ||
1481 | @ingroup api_rer | |
1482 | ||
1483 | After you create a recording event rule descriptor with this function, | |
1484 | you can modify its properties and call | |
1485 | lttng_enable_event_with_exclusions() to create and enable a recording | |
1486 | event rule. | |
1487 | ||
1488 | @returns | |
1489 | @parblock | |
1490 | New recording event rule descriptor. | |
1491 | ||
1492 | Destroy the returned recording event rule descriptor with | |
1493 | lttng_event_destroy(). | |
1494 | @endparblock | |
1495 | ||
1496 | @sa lttng_event_destroy() -- | |
1497 | Destroys a recording event rule descriptor. | |
1498 | */ | |
4bd69c5f | 1499 | LTTNG_EXPORT extern struct lttng_event *lttng_event_create(void); |
ef0e06bc | 1500 | |
048f01ef PP |
1501 | /*! |
1502 | @brief | |
1503 | Destroys the recording event rule descriptor \lt_p{event_rule}. | |
ef0e06bc | 1504 | |
048f01ef | 1505 | @ingroup api_rer |
d31d3e8c | 1506 | |
048f01ef PP |
1507 | @note |
1508 | This function doesn't destroy the recording event rule | |
1509 | which \lt_p{event_rule} describes: you can't destroy a | |
1510 | recording event rule. | |
f086e50e | 1511 | |
048f01ef PP |
1512 | @param[in] event_rule |
1513 | @parblock | |
1514 | Recording event rule descriptor to destroy. | |
1515 | ||
1516 | May be \c NULL. | |
1517 | @endparblock | |
1518 | ||
1519 | @pre | |
1520 | <strong>If not \c NULL</strong>, \lt_p{event_rule} was created with | |
1521 | lttng_event_create(). | |
1522 | ||
1523 | @sa lttng_event_create() -- | |
1524 | Creates an empty recording event rule descriptor. | |
1525 | */ | |
1526 | LTTNG_EXPORT extern void lttng_event_destroy(struct lttng_event *event_rule); | |
1527 | ||
1528 | /*! | |
1529 | @brief | |
1530 | Sets \lt_p{*filter_expr} to the | |
1531 | \ref api-rer-conds-filter "event payload and context filter" | |
1532 | expression of the recording event rule described by | |
1533 | \lt_p{event_rule}. | |
1534 | ||
1535 | @ingroup api_rer | |
1536 | ||
1537 | @param[in] event_rule | |
1538 | Descriptor of the recording event rule of which to get the event | |
1539 | payload and context filter expression. | |
1540 | @param[out] filter_expr | |
1541 | @parblock | |
1542 | <strong>On success</strong>, this function sets \lt_p{*filter_expr} | |
1543 | to: | |
1544 | ||
1545 | <dl> | |
1546 | <dt> | |
1547 | If \lt_p{event_rule} has an event payload and context filter | |
1548 | expression | |
1549 | <dd> | |
1550 | The event payload and context filter | |
1551 | expression of \lt_p{event_rule}. | |
1552 | ||
1553 | \lt_p{*filter_expr} remains valid as long as \lt_p{event_rule} | |
1554 | exists and you don't modify it. | |
1555 | ||
1556 | <dt>Otherwise | |
1557 | <dd>\c NULL | |
1558 | </dl> | |
1559 | @endparblock | |
1560 | ||
1561 | @returns | |
1562 | 0 on success, or a \em negative #lttng_error_code enumerator | |
1563 | otherwise. | |
1564 | ||
1565 | @lt_pre_not_null{event_rule} | |
1566 | @lt_pre_not_null{filter_expr} | |
1567 | ||
1568 | @sa lttng_event::filter -- | |
1569 | Indicates whether or not a recording event rule has an event payload | |
1570 | and context filter. | |
1571 | */ | |
1572 | LTTNG_EXPORT extern int lttng_event_get_filter_expression(struct lttng_event *event_rule, | |
1573 | const char **filter_expr); | |
1574 | ||
1575 | /*! | |
1576 | @brief | |
1577 | Returns the number of \ref api-rer-conds-event-name "event name" | |
1578 | exclusion patterns of the recording | |
1579 | event rule described by \lt_p{event_rule}. | |
1580 | ||
1581 | @ingroup api_rer | |
1582 | ||
1583 | @param[in] event_rule | |
1584 | Descriptor of the recording event rule of which to get the number | |
1585 | of event name exclusion patterns. | |
1586 | ||
1587 | @returns | |
1588 | Number of event name exclusion patterns of \lt_p{event_rule}, or a | |
1589 | \em negative #lttng_error_code enumerator otherwise. | |
1590 | ||
1591 | @lt_pre_not_null{event_rule} | |
1592 | ||
1593 | @sa lttng_event_get_exclusion_name() -- | |
1594 | Returns an event name exclusion pattern by index of a recording | |
1595 | event rule. | |
1596 | @sa lttng_event::exclusion -- | |
1597 | Indicates whether or not a recording event rule has event name | |
1598 | exclusion patterns. | |
1599 | */ | |
1600 | LTTNG_EXPORT extern int lttng_event_get_exclusion_name_count(struct lttng_event *event_rule); | |
1601 | ||
1602 | /*! | |
1603 | @brief | |
1604 | Sets \lt_p{*event_name_exclusion} to the | |
1605 | \ref api-rer-conds-event-name "event name" exclusion | |
1606 | pattern at index \lt_p{index} of the recording event rule described | |
1607 | by \lt_p{event_rule}. | |
1608 | ||
1609 | @ingroup api_rer | |
1610 | ||
1611 | @param[in] event_rule | |
1612 | Descriptor of the recording event rule of which to get the event | |
1613 | name exclusion pattern at index \lt_p{index}. | |
1614 | @param[in] index | |
1615 | Index of the event name exclusion pattern to get from | |
1616 | \lt_p{event_rule}. | |
1617 | @param[out] event_name_exclusion | |
1618 | @parblock | |
1619 | <strong>On success</strong>, this function sets | |
1620 | \lt_p{*event_name_exclusion} to the event name exclusion pattern at | |
1621 | index \lt_p{index} of | |
1622 | \lt_p{event_rule}. | |
1623 | ||
1624 | \lt_p{*event_name_exclusion} remains valis as long as | |
1625 | \lt_p{event_rule} exists and you don't modify it. | |
1626 | @endparblock | |
1627 | ||
1628 | @returns | |
1629 | 0 on success, or a \em negative #lttng_error_code enumerator | |
1630 | otherwise. | |
1631 | ||
1632 | @lt_pre_not_null{event_rule} | |
1633 | @pre | |
1634 | \lt_p{index} is less than the number of event name exclusion | |
1635 | patterns (as returned by lttng_event_get_exclusion_name_count()) | |
1636 | of \lt_p{event_rule}. | |
1637 | @lt_pre_not_null{event_name_exclusion} | |
1638 | ||
1639 | @sa lttng_event_get_exclusion_name_count() -- | |
1640 | Returns the number of event name exclusion patterns of a recording | |
1641 | event rule. | |
1642 | */ | |
1643 | LTTNG_EXPORT extern int lttng_event_get_exclusion_name(struct lttng_event *event_rule, | |
28f23191 | 1644 | size_t index, |
048f01ef | 1645 | const char **event_name_exclusion); |
f086e50e | 1646 | |
048f01ef PP |
1647 | /*! |
1648 | @brief | |
1649 | Returns the Linux uprobe location of the recording event rule | |
1650 | described by \lt_p{event_rule}. | |
1651 | ||
1652 | @ingroup api_rer | |
1653 | ||
1654 | @param[in] event_rule | |
1655 | Descriptor of the recording event rule of which to get the | |
1656 | Linux uprobe location. | |
1657 | ||
1658 | @returns | |
1659 | @parblock | |
1660 | Linux uprobe location of the recording event rule described by | |
1661 | \lt_p{event_rule}, or \c NULL if none. | |
1662 | ||
1663 | The returned location remains valid as long as \lt_p{event_rule} | |
1664 | exists and you don't modify it. | |
1665 | @endparblock | |
1666 | ||
1667 | @lt_pre_not_null{event_rule} | |
1668 | @pre | |
1669 | \lt_p{event_rule->type} (see lttng_event::type) is | |
1670 | #LTTNG_EVENT_USERSPACE_PROBE. | |
1671 | ||
1672 | @sa lttng_event_set_userspace_probe_location() -- | |
1673 | Sets the Linux uprobe location of a recording event rule. | |
1674 | @sa \ref api-rer-conds-inst-pt-type "Instrumentation point type condition". | |
1675 | */ | |
4bd69c5f | 1676 | LTTNG_EXPORT extern const struct lttng_userspace_probe_location * |
048f01ef | 1677 | lttng_event_get_userspace_probe_location(const struct lttng_event *event_rule); |
ef0e06bc | 1678 | |
048f01ef PP |
1679 | /*! |
1680 | @brief | |
1681 | Sets the Linux uprobe location of the recording event rule described | |
1682 | by \lt_p{event_rule} to \lt_p{location}. | |
1683 | ||
1684 | @ingroup api_rer | |
1685 | ||
1686 | @param[in] event_rule | |
1687 | Descriptor of the recording event rule of which to set the | |
1688 | Linux uprobe location to \lt_p{location}. | |
1689 | @param[in] location | |
1690 | New Linux uprobe location of \lt_p{event_rule}. | |
1691 | ||
1692 | @returns | |
1693 | 0 on success, or a \em negative #lttng_error_code enumerator | |
1694 | otherwise. | |
1695 | ||
1696 | @lt_pre_not_null{event_rule} | |
1697 | @pre | |
1698 | \lt_p{event_rule} was created with lttng_event_create(). | |
1699 | @pre | |
1700 | \lt_p{event_rule->type} (see lttng_event::type) is | |
1701 | #LTTNG_EVENT_USERSPACE_PROBE. | |
1702 | @lt_pre_not_null{location} | |
1703 | ||
1704 | @post | |
1705 | <strong>On success</strong>, \lt_p{*location} is invalid | |
1706 | (its ownership is transfered to \lt_p{event_rule}). | |
1707 | ||
1708 | @sa lttng_event_get_userspace_probe_location() -- | |
1709 | Returns the Linux uprobe location of a recording event rule. | |
1710 | @sa \ref api-rer-conds-inst-pt-type "Instrumentation point type condition". | |
1711 | */ | |
28f23191 | 1712 | LTTNG_EXPORT extern int |
048f01ef PP |
1713 | lttng_event_set_userspace_probe_location(struct lttng_event *event_rule, |
1714 | struct lttng_userspace_probe_location *location); | |
ef0e06bc | 1715 | |
048f01ef PP |
1716 | /*! |
1717 | @brief | |
1718 | Sets \lt_p{*descrs} to the | |
1719 | \ref api-rer-inst-pt-descr "descriptors" of the | |
1720 | available LTTng tracepoints or Java/Python loggers for the | |
1721 | \lt_obj_domain of \lt_p{handle}. | |
1722 | ||
1723 | @ingroup api_inst_pt | |
1724 | ||
1725 | @param[in] handle | |
1726 | @parblock | |
1727 | Recording session handle which contains the summary of the | |
1728 | \lt_obj_domain which offers the LTTng tracepoints or Java/Python | |
1729 | loggers of which to get the descriptors. | |
1730 | ||
1731 | This function ignores \lt_p{handle->session_name}. | |
1732 | @endparblock | |
1733 | @param[out] descrs | |
1734 | @parblock | |
1735 | <strong>On success</strong>, this function sets \lt_p{*descrs} | |
1736 | to the descriptors of the available tracepoints or Java/Python | |
1737 | loggers of \lt_p{handle}. | |
1738 | ||
1739 | Free \lt_p{*descrs} with <code>free()</code>. | |
1740 | @endparblock | |
1741 | ||
1742 | @returns | |
1743 | The number of items in \lt_p{*descrs} on success, or a \em | |
1744 | negative #lttng_error_code enumerator otherwise. | |
1745 | ||
1746 | @lt_pre_conn | |
1747 | @lt_pre_not_null{handle} | |
1748 | @pre | |
1749 | \lt_p{handle->domain} is valid as per the documentation of | |
1750 | #lttng_domain. | |
1751 | @lt_pre_not_null{descrs} | |
1752 | ||
1753 | @sa lttng_list_tracepoint_fields() -- | |
1754 | Returns all the field descriptions of all the available LTTng | |
1755 | tracepoints. | |
1756 | @sa lttng_list_syscalls() -- | |
1757 | Returns the descriptors of all the available Linux system calls. | |
1758 | */ | |
4bd69c5f | 1759 | LTTNG_EXPORT extern int lttng_list_tracepoints(struct lttng_handle *handle, |
048f01ef | 1760 | struct lttng_event **descrs); |
1239a312 | 1761 | |
048f01ef PP |
1762 | /*! |
1763 | @brief | |
1764 | Sets \lt_p{*fields} to the field descriptions of all the available | |
1765 | LTTng tracepoints for the \lt_obj_domain of \lt_p{handle}. | |
1766 | ||
1767 | @ingroup api_inst_pt | |
1768 | ||
1769 | @param[in] handle | |
1770 | @parblock | |
1771 | Recording session handle which contains the summary of the | |
1772 | \lt_obj_domain which offers the LTTng tracepoints of which to get | |
1773 | the field descriptions. | |
1774 | ||
1775 | This function ignores \lt_p{handle->session_name}. | |
1776 | @endparblock | |
1777 | @param[out] fields | |
1778 | @parblock | |
1779 | <strong>On success</strong>, this function sets \lt_p{*fields} | |
1780 | to the descriptions of the available LTTng tracepoint fields of | |
1781 | \lt_p{handle}. | |
1782 | ||
1783 | Each #lttng_event_field instance in \lt_p{*fields} contains a | |
1784 | pointer to the \ref api-rer-inst-pt-descr "descriptor" of | |
1785 | a tracepoint which contains the described field | |
1786 | (lttng_event_field::event member). | |
1787 | ||
1788 | Free \lt_p{*fields} with <code>free()</code>. | |
1789 | @endparblock | |
1790 | ||
1791 | @returns | |
1792 | The number of items in \lt_p{*fields} on success, or a \em | |
1793 | negative #lttng_error_code enumerator otherwise. | |
1794 | ||
1795 | @lt_pre_conn | |
1796 | @lt_pre_not_null{handle} | |
1797 | @pre | |
1798 | \lt_p{handle->domain} is valid as per the documentation of | |
1799 | #lttng_domain. | |
1800 | @lt_pre_not_null{fields} | |
1801 | ||
1802 | @sa lttng_list_tracepoints() -- | |
1803 | Returns the descriptors of all the available LTTng tracepoints | |
1804 | or Java/Python loggers. | |
1805 | @sa lttng_list_syscalls() -- | |
1806 | Returns the descriptors of all the available Linux system calls. | |
1807 | */ | |
4bd69c5f | 1808 | LTTNG_EXPORT extern int lttng_list_tracepoint_fields(struct lttng_handle *handle, |
28f23191 | 1809 | struct lttng_event_field **fields); |
1239a312 | 1810 | |
048f01ef PP |
1811 | /*! |
1812 | @brief | |
1813 | Sets \lt_p{*descrs} to the | |
1814 | \ref api-rer-inst-pt-descr "descriptors" of the | |
1815 | available Linux system calls for the | |
1816 | #LTTNG_DOMAIN_KERNEL tracing domain. | |
834978fd | 1817 | |
048f01ef PP |
1818 | @ingroup api_inst_pt |
1819 | ||
1820 | @param[out] descrs | |
1821 | @parblock | |
1822 | <strong>On success</strong>, this function sets \lt_p{*descrs} | |
1823 | to the available system calls. | |
1824 | ||
1825 | The #lttng_event instances of \lt_p{*descrs} have an | |
1826 | lttng_event::flags member which indicates whether the described | |
1827 | system call is 32-bit, 64-bit, or both. | |
1828 | ||
1829 | Free \lt_p{*descrs} with <code>free()</code>. | |
1830 | @endparblock | |
1831 | ||
1832 | @returns | |
1833 | The number of items in \lt_p{*descrs} on success, or a \em | |
1834 | negative #lttng_error_code enumerator otherwise. | |
1835 | ||
1836 | @lt_pre_conn | |
1837 | @lt_pre_not_null{descrs} | |
1838 | ||
1839 | @sa lttng_list_tracepoint_fields() -- | |
1840 | Returns all the field descriptions of all the available LTTng | |
1841 | tracepoints. | |
1842 | @sa lttng_list_syscalls() -- | |
1843 | Returns the descriptors of all the available Linux system calls. | |
1844 | */ | |
1845 | LTTNG_EXPORT extern int lttng_list_syscalls(struct lttng_event **descrs); | |
1846 | ||
1847 | /*! | |
1848 | @brief | |
1849 | Makes the future \ref api_rer "event records" of the | |
1850 | \lt_obj_channel named \lt_p{channel_name} (or of a default channel | |
1851 | or all the channels if \c NULL) within the | |
1852 | \lt_obj_session and \lt_obj_domain of \lt_p{handle} | |
1853 | have a context field described by \lt_p{context_field_descriptor}. | |
1854 | ||
1855 | @ingroup api_channel | |
1856 | ||
1857 | Context values (for example, the ID of the current process, the | |
1858 | instruction pointer, or the hostname) are always available during | |
1859 | tracing. This function makes LTTng record a specific context value as a | |
1860 | field for each future event record of the selected channel(s). | |
1861 | ||
1862 | @param[in] handle | |
1863 | Recording session handle which contains the name of the recording | |
1864 | session and the summary of the \lt_obj_domain which own the | |
1865 | channel(s) to select. | |
1866 | @param[in] context_field_descriptor | |
1867 | Descriptor of the context field to add to each event record of | |
1868 | the selected channel(s). | |
1869 | @param[in] event_name | |
1870 | Unused: must be \c NULL. | |
1871 | @param[in] channel_name | |
1872 | @parblock | |
1873 | Name of the channel to select. | |
1874 | ||
1875 | If \c NULL, then: | |
1876 | ||
1877 | <dl> | |
1878 | <dt> | |
1879 | If the recording session and tracing domain of | |
1880 | \lt_p{handle} have no channels | |
1881 | <dd> | |
1882 | LTTng creates a new, default channel named \c channel0 within | |
1883 | \lt_p{handle} which becomes the selected channel. | |
1884 | ||
1885 | <dt>Otherwise | |
1886 | <dd> | |
1887 | LTTng selects all the channels of \lt_p{handle}. | |
1888 | </dl> | |
1889 | @endparblock | |
1890 | ||
1891 | @returns | |
1892 | 0 on success, or a \em negative #lttng_error_code enumerator | |
1893 | otherwise. | |
1894 | ||
1895 | @lt_pre_conn | |
1896 | @lt_pre_not_null{handle} | |
1897 | @lt_pre_valid_c_str{handle->session_name} | |
1898 | @lt_pre_sess_exists{handle->session_name} | |
1899 | @lt_pre_sess_never_active{handle->session_name} | |
1900 | @pre | |
1901 | \lt_p{handle->domain} is valid (you passed a | |
1902 | \lt_obj_domain summary to | |
1903 | lttng_create_handle() when you created \lt_p{handle}). | |
1904 | @pre | |
1905 | \lt_p{context_field_descriptor} is valid according to the | |
1906 | documentation of #lttng_event_context. | |
1907 | @pre | |
1908 | \lt_p{event_name} is \c NULL. | |
1909 | @pre | |
1910 | <strong>If not \c NULL</strong>, \lt_p{channel_name} names an | |
1911 | existing channel within the recording session and tracing domain of | |
1912 | \lt_p{handle}. | |
1913 | */ | |
4bd69c5f | 1914 | LTTNG_EXPORT extern int lttng_add_context(struct lttng_handle *handle, |
048f01ef | 1915 | struct lttng_event_context *context_field_descriptor, |
28f23191 JG |
1916 | const char *event_name, |
1917 | const char *channel_name); | |
1239a312 | 1918 | |
048f01ef PP |
1919 | /*! |
1920 | @brief | |
1921 | Alias of lttng_enable_event_with_exclusions() which passes the | |
1922 | \ref api-rer-conds-filter "event payload and context filter" | |
1923 | expression of \lt_p{event_rule} | |
1924 | as the \lt_p{filter_expr} parameter and the | |
1925 | \ref api-rer-conds-event-name "event name" exclusion patterns | |
1926 | of \lt_p{event_rule} as the | |
1927 | \lt_p{event_name_exclusion_count} and | |
1928 | \lt_p{event_name_exclusions} parameters. | |
1239a312 | 1929 | |
048f01ef PP |
1930 | @ingroup api_rer |
1931 | ||
1932 | This function is equivalent to: | |
1933 | ||
1934 | @code | |
1935 | int ret; | |
1936 | int i; | |
1937 | char **event_name_exclusions = NULL; | |
1938 | const char *filter_expr = NULL; | |
1939 | const int event_name_exclusion_count = lttng_event_get_exclusion_name_count(event_rule); | |
1940 | ||
1941 | assert(event_name_exclusion_count >= 0); | |
1942 | ||
1943 | if (event_name_exclusion_count > 0) { | |
1944 | event_name_exclusions = calloc(event_name_exclusion_count, | |
1945 | sizeof(*event_name_exclusions)); | |
1946 | assert(event_name_exclusions); | |
1947 | ||
1948 | for (i = 0; i < event_name_exclusion_count; i++) { | |
1949 | const char *event_name_exclusion; | |
1950 | ||
1951 | ret = lttng_event_get_exclusion_name(event_rule, (size_t) i, | |
1952 | &event_name_exclusion); | |
1953 | assert(ret == 0); | |
1954 | event_name_exclusions[i] = (char *) event_name_exclusion; | |
1955 | } | |
1956 | } | |
1957 | ||
1958 | ret = lttng_event_get_filter_expression(event_rule, &filter_expr); | |
1959 | assert(ret == 0); | |
1960 | ret = lttng_enable_event_with_exclusions(handle, event_rule, channel_name, | |
1961 | filter_expr, | |
1962 | event_name_exclusion_count, | |
1963 | event_name_exclusions); | |
1964 | free(event_name_exclusions); | |
1965 | return ret; | |
1966 | @endcode | |
1967 | */ | |
1968 | LTTNG_EXPORT extern int lttng_enable_event(struct lttng_handle *handle, | |
1969 | struct lttng_event *event_rule, | |
1970 | const char *channel_name); | |
1971 | ||
1972 | /*! | |
1973 | @brief | |
1974 | Alias of lttng_enable_event_with_exclusions() which passes the | |
1975 | the \ref api-rer-conds-event-name "event name" exclusion patterns | |
1976 | of \lt_p{event_rule} as the | |
1977 | \lt_p{event_name_exclusion_count} and | |
1978 | \lt_p{event_name_exclusions} parameters. | |
1979 | ||
1980 | @ingroup api_rer | |
1981 | ||
1982 | This function is equivalent to: | |
1983 | ||
1984 | @code | |
1985 | int ret; | |
1986 | int i; | |
1987 | char **event_name_exclusions = NULL; | |
1988 | const char *filter_expr = NULL; | |
1989 | const int event_name_exclusion_count = lttng_event_get_exclusion_name_count(event_rule); | |
1990 | ||
1991 | assert(event_name_exclusion_count >= 0); | |
1992 | ||
1993 | if (event_name_exclusion_count > 0) { | |
1994 | event_name_exclusions = calloc(event_name_exclusion_count, | |
1995 | sizeof(*event_name_exclusions)); | |
1996 | assert(event_name_exclusions); | |
1997 | ||
1998 | for (i = 0; i < event_name_exclusion_count; i++) { | |
1999 | const char *event_name_exclusion; | |
2000 | ||
2001 | ret = lttng_event_get_exclusion_name(event_rule, (size_t) i, | |
2002 | &event_name_exclusion); | |
2003 | assert(ret == 0); | |
2004 | event_name_exclusions[i] = (char *) event_name_exclusion; | |
2005 | } | |
2006 | } | |
2007 | ||
2008 | ret = lttng_enable_event_with_exclusions(handle, event_rule, channel_name, | |
2009 | filter_expr, | |
2010 | event_name_exclusion_count, | |
2011 | event_name_exclusions); | |
2012 | free(event_name_exclusions); | |
2013 | return ret; | |
2014 | @endcode | |
2015 | */ | |
4bd69c5f | 2016 | LTTNG_EXPORT extern int lttng_enable_event_with_filter(struct lttng_handle *handle, |
048f01ef | 2017 | struct lttng_event *event_rule, |
28f23191 | 2018 | const char *channel_name, |
048f01ef | 2019 | const char *filter_expr); |
1239a312 | 2020 | |
048f01ef PP |
2021 | /*! |
2022 | @brief | |
2023 | Creates or enables a recording event rule | |
2024 | described by \lt_p{event_rule}, having the | |
2025 | \ref api-rer-conds-filter "event payload and context filter" | |
2026 | expression \lt_p{filter_expr} and the | |
2027 | \ref api-rer-conds-event-name "event name" exclusion patterns | |
2028 | \lt_p{event_name_exclusions}, within | |
2029 | the \lt_obj_channel named \lt_p{channel_name} | |
2030 | (or within a default channel if \c NULL) within the recording | |
2031 | session handle \lt_p{handle}. | |
2032 | ||
2033 | @ingroup api_rer | |
2034 | ||
2035 | This function, depending on the | |
2036 | \ref api-rer-conds-inst-pt-type "instrumentation point type", | |
2037 | \ref api-rer-conds-event-name "event name", | |
2038 | and \ref api-rer-conds-ll "log level" conditions of \lt_p{event_rule}, | |
2039 | as well as on \lt_p{filter_expr} and \lt_p{event_name_exclusions}: | |
2040 | ||
2041 | <dl> | |
2042 | <dt> | |
2043 | The conditions and parameters describe an existing recording event | |
2044 | rule within the selected channel | |
2045 | <dd> | |
2046 | Enables the existing recording event rule. | |
2047 | ||
2048 | <dt>Otherwise | |
2049 | <dd> | |
2050 | Creates and enables a new recording event rule within the | |
2051 | selected channel. | |
2052 | </dl> | |
2053 | ||
2054 | If \lt_p{event_rule->type} is #LTTNG_EVENT_ALL and | |
2055 | \lt_p{handle->domain.type} is #LTTNG_DOMAIN_KERNEL, then this | |
2056 | function actually creates or enables two recording event rules: one with | |
2057 | the #LTTNG_EVENT_TRACEPOINT type, and one with the #LTTNG_EVENT_SYSCALL | |
2058 | type. | |
2059 | ||
2060 | @param[in] handle | |
2061 | Recording session handle which contains the name of the recording | |
2062 | session and the summary of the \lt_obj_domain which own the selected | |
2063 | channel. | |
2064 | @param[in] event_rule | |
2065 | @parblock | |
2066 | Descriptor of the recording event rule to create or enable. | |
2067 | ||
2068 | This function: | |
2069 | ||
2070 | - Ignores any event payload and context filter | |
2071 | expression within \lt_p{event_rule}: it always uses | |
2072 | \lt_p{filter_expr}. | |
2073 | ||
2074 | - Ignores any event name exclusion patterns within | |
2075 | \lt_p{event_rule}: it always uses \lt_p{event_name_exclusions}. | |
2076 | @endparblock | |
2077 | @param[in] channel_name | |
2078 | @parblock | |
2079 | Name of the channel, within \lt_p{handle}, to select (that is, | |
2080 | containing the recording event rule to create or enable). | |
2081 | ||
2082 | If \c NULL, then this function uses \c channel0. If no channel named | |
2083 | \c channel0 within \lt_p{handle} exists, then LTTng creates a new, | |
2084 | default channel named as such and selects it before it creates the | |
2085 | recording event rule described by \lt_p{event_rule}. | |
2086 | @endparblock | |
2087 | @param[in] filter_expr | |
2088 | @parblock | |
2089 | Event payload and context filter expression of the recording | |
2090 | event rule to create or enable. | |
2091 | ||
2092 | <strong>If \c NULL</strong>, the created or enabled recording event | |
2093 | rule has no event payload and context filter expression. | |
2094 | ||
2095 | This parameter, even when \c NULL, overrides any existing | |
2096 | event payload and context filter expression within | |
2097 | \lt_p{event_rule}. | |
2098 | @endparblock | |
2099 | @param[in] event_name_exclusion_count | |
2100 | Number of items in \lt_p{event_name_exclusions}. | |
2101 | @param[in] event_name_exclusions | |
2102 | @parblock | |
2103 | Event name exclusion patterns of the recording event rule to create | |
2104 | or enable. | |
2105 | ||
2106 | This function copies the strings of this array. | |
2107 | ||
2108 | \lt_p{event_name_exclusion_count} indicates the size of this | |
2109 | array, which may be \c NULL if \lt_p{event_name_exclusion_count} | |
2110 | is 0. | |
2111 | ||
2112 | This parameter, even when \c NULL or empty, overrides any existing | |
2113 | event name exclusion patterns within \lt_p{event_rule}. | |
2114 | @endparblock | |
2115 | ||
2116 | @returns | |
2117 | 0 on success, or a \em negative #lttng_error_code enumerator | |
2118 | otherwise. | |
2119 | ||
2120 | @lt_pre_conn | |
2121 | @lt_pre_not_null{handle} | |
2122 | @lt_pre_valid_c_str{handle->session_name} | |
2123 | @lt_pre_sess_exists{handle->session_name} | |
2124 | @pre | |
2125 | \lt_p{handle->domain} is valid as per the documentation of | |
2126 | #lttng_domain. | |
2127 | @lt_pre_not_null{event_rule} | |
2128 | @pre | |
2129 | \lt_p{event_rule} is \ref api-rer-valid-event-struct "valid". | |
2130 | @pre | |
2131 | <strong>If \lt_p{handle->domain.type} is \em not | |
2132 | #LTTNG_DOMAIN_KERNEL</strong>, then \lt_p{event_rule->type} is | |
2133 | #LTTNG_EVENT_TRACEPOINT. | |
2134 | @pre | |
2135 | <strong>If \lt_p{handle->domain.type} is \em not | |
2136 | #LTTNG_DOMAIN_UST</strong>, then \lt_p{event_name_exclusion_count} | |
2137 | is 0. | |
2138 | @pre | |
2139 | <strong>If this function must enable an existing recording event | |
2140 | rule</strong>, then the recording event rule to enable is disabled. | |
2141 | @pre | |
2142 | <strong>If not \c NULL</strong>, \lt_p{channel_name} names an | |
2143 | existing channel within the recording session and tracing domain of | |
2144 | \lt_p{handle}. | |
2145 | @pre | |
2146 | <strong>If \lt_p{channel_name} is \c NULL</strong>, then | |
2147 | \lt_p{handle} contains either no channels or a default channel named | |
2148 | \c channel0. | |
2149 | @pre | |
2150 | <strong>If not \c NULL</strong>, \lt_p{filter_expr} is a valid | |
2151 | event payload and context filter expression. | |
2152 | @pre | |
2153 | \lt_p{event_name_exclusion_count} ≥ 0. | |
2154 | ||
2155 | @sa lttng_enable_event() -- | |
2156 | Alias which calls this function with the event payload and context | |
2157 | filter expression and event name exclusion patterns of the | |
2158 | recording event rule descriptor. | |
2159 | @sa lttng_enable_event_with_filter() -- | |
2160 | Alias which calls this function with the event name exclusion | |
2161 | patterns of the recording event rule descriptor. | |
2162 | @sa lttng_disable_event_ext() -- | |
2163 | Disables a recording event rule. | |
2164 | */ | |
4bd69c5f | 2165 | LTTNG_EXPORT extern int lttng_enable_event_with_exclusions(struct lttng_handle *handle, |
048f01ef | 2166 | struct lttng_event *event_rule, |
28f23191 | 2167 | const char *channel_name, |
048f01ef PP |
2168 | const char *filter_expr, |
2169 | int event_name_exclusion_count, | |
2170 | char **event_name_exclusions); | |
1239a312 | 2171 | |
048f01ef PP |
2172 | /*! |
2173 | @brief | |
2174 | Alias of lttng_disable_event_ext() which creates a temporary | |
2175 | recording event rule descriptor, settings its | |
2176 | lttng_event::name member to \lt_p{event_name} if not \c NULL and | |
2177 | its lttng_event::type member to #LTTNG_EVENT_ALL. | |
2178 | ||
2179 | @ingroup api_rer | |
2180 | ||
2181 | This function is equivalent to: | |
2182 | ||
2183 | @code | |
2184 | struct lttng_event event_rule = { 0 }; | |
2185 | ||
2186 | event_rule.type = LTTNG_EVENT_ALL; | |
2187 | ||
2188 | if (event_name) { | |
2189 | strcpy(event_rule.name, event_name); | |
2190 | } | |
2191 | ||
2192 | event_rule.loglevel = -1; | |
2193 | return lttng_disable_event_ext(handle, &event_rule, channel_name, NULL); | |
2194 | @endcode | |
2195 | */ | |
28f23191 | 2196 | LTTNG_EXPORT extern int |
048f01ef | 2197 | lttng_disable_event(struct lttng_handle *handle, const char *event_name, const char *channel_name); |
1239a312 | 2198 | |
048f01ef PP |
2199 | /*! |
2200 | @brief | |
2201 | Disables recording event rules by | |
2202 | \ref api-rer-conds-inst-pt-type "instrumentation point type" and | |
2203 | \ref api-rer-conds-event-name "event name" condition within the | |
2204 | \lt_obj_channel named \lt_p{channel_name} | |
2205 | (or within a default channel if \c NULL) within the recording | |
2206 | session handle \lt_p{handle}. | |
2207 | ||
2208 | @ingroup api_rer | |
2209 | ||
2210 | Depending on \lt_p{event_rule->name}, this function: | |
2211 | ||
2212 | <dl> | |
2213 | <dt>Not empty | |
2214 | <dd> | |
2215 | Depending on \lt_p{event_rule->type}: | |
2216 | ||
2217 | <dl> | |
2218 | <dt>#LTTNG_EVENT_ALL | |
2219 | <dd> | |
2220 | Disables \em all the recording event rules of which the event | |
2221 | name pattern is exactly \lt_p{event_rule->name} within the | |
2222 | selected channel. | |
2223 | ||
2224 | <dt>Otherwise | |
2225 | <dd> | |
2226 | Disables all the recording event rules of which the | |
2227 | instrumentation point type is | |
2228 | \lt_p{event_rule->type} and the event | |
2229 | name pattern is exactly \lt_p{event_rule->name} within the | |
2230 | selected channel. | |
2231 | ||
2232 | Only supported when \lt_p{handle->domain.type} is | |
2233 | #LTTNG_DOMAIN_KERNEL. | |
2234 | </dl> | |
2235 | ||
2236 | <dt>Empty | |
2237 | <dd> | |
2238 | Depending on \lt_p{event_rule->type}: | |
2239 | ||
2240 | <dl> | |
2241 | <dt>#LTTNG_EVENT_ALL | |
2242 | <dd> | |
2243 | Disables \em all the recording event rules within the selected | |
2244 | channel. | |
2245 | ||
2246 | <dt>Otherwise | |
2247 | <dd> | |
2248 | Disables all the recording event rules of which the | |
2249 | instrumentation point type is | |
2250 | \lt_p{event_rule->type} within the | |
2251 | selected channel. | |
2252 | ||
2253 | Only supported when \lt_p{handle->domain.type} is | |
2254 | #LTTNG_DOMAIN_KERNEL. | |
2255 | </dl> | |
2256 | </dl> | |
2257 | ||
2258 | This function ignores all the other \ref api-rer-conds "condition" | |
2259 | properties of \lt_p{event_rule}. | |
2260 | ||
2261 | To use this function, create a temporary, zeroed | |
2262 | \link #lttng_event recording event rule descriptor\endlink, | |
2263 | setting only: | |
2264 | ||
2265 | - <strong>Optional, and only if \lt_p{handle->domain.type} | |
2266 | is #LTTNG_DOMAIN_KERNEL</strong>: its lttng_event::type member. | |
2267 | ||
2268 | - <strong>Optional</strong>: its lttng_event::name member | |
2269 | ||
2270 | - Its lttng_event::loglevel member to -1. | |
2271 | ||
2272 | For example: | |
2273 | ||
2274 | @code | |
2275 | struct lttng_event event_rule = { 0 }; | |
2276 | ||
2277 | event_rule.type = LTTNG_EVENT_SYSCALL; | |
2278 | strcpy(event_rule.name, "open*"); | |
2279 | event_rule.loglevel = -1; | |
2280 | @endcode | |
2281 | ||
2282 | @param[in] handle | |
2283 | Recording session handle which contains the name of the recording | |
2284 | session and the summary of the \lt_obj_domain which own the selected | |
2285 | channel. | |
2286 | @param[in] event_rule | |
2287 | @parblock | |
2288 | Recording event rule descriptor which contains the | |
2289 | instrumentation point type and event name conditions to consider | |
2290 | to disable recording event rules within the selected channel. | |
2291 | @endparblock | |
2292 | @param[in] channel_name | |
2293 | @parblock | |
2294 | Name of the channel, within \lt_p{handle}, to select (that is, | |
2295 | containing the recording event rules to disable). | |
2296 | ||
2297 | If \c NULL, then this function uses \c channel0. | |
2298 | @endparblock | |
2299 | @param[in] filter_expr | |
2300 | Unused: must be \c NULL. | |
2301 | ||
2302 | @returns | |
2303 | 0 on success, or a \em negative #lttng_error_code enumerator | |
2304 | otherwise. | |
2305 | ||
2306 | @lt_pre_conn | |
2307 | @lt_pre_not_null{handle} | |
2308 | @lt_pre_valid_c_str{handle->session_name} | |
2309 | @lt_pre_sess_exists{handle->session_name} | |
2310 | @pre | |
2311 | \lt_p{handle->domain} is valid as per the documentation of | |
2312 | #lttng_domain. | |
2313 | @lt_pre_not_null{event_rule} | |
2314 | @pre | |
2315 | <strong>If \lt_p{handle->domain.type} is \em not | |
2316 | #LTTNG_DOMAIN_KERNEL</strong>, then \lt_p{event_rule->type} | |
2317 | is #LTTNG_EVENT_ALL. | |
2318 | @pre | |
2319 | <strong>If not #LTTNG_EVENT_ALL</strong>, then | |
2320 | \lt_p{event_rule->type} is the instrumentation point type of at | |
2321 | least one Linux kernel recording event rule within the selected | |
2322 | channel. | |
2323 | @pre | |
2324 | <strong>If not empty</strong>, then \lt_p{event_rule->name} is the | |
2325 | exact event name pattern of at least one recording event rule within | |
2326 | the selected channel. | |
2327 | @pre | |
2328 | The recording event rules to disable are enabled. | |
2329 | @pre | |
2330 | <strong>If not \c NULL</strong>, then \lt_p{channel_name} names an | |
2331 | existing channel within the recording session and tracing domain of | |
2332 | \lt_p{handle}. | |
2333 | @pre | |
2334 | <strong>If \lt_p{channel_name} is \c NULL</strong>, then the | |
2335 | channel named \c channel0 exists within the recording session and | |
2336 | tracing domain of \lt_p{handle}. | |
2337 | ||
2338 | @sa lttng_disable_event() -- | |
2339 | Alias which calls this function with \lt_p{event_rule->type} | |
2340 | set to #LTTNG_EVENT_ALL. | |
2341 | @sa lttng_enable_event_with_exclusions() -- | |
2342 | Creates or enables a recording event rule. | |
2343 | */ | |
4bd69c5f | 2344 | LTTNG_EXPORT extern int lttng_disable_event_ext(struct lttng_handle *handle, |
048f01ef | 2345 | struct lttng_event *event_rule, |
28f23191 | 2346 | const char *channel_name, |
048f01ef | 2347 | const char *filter_expr); |
6e911cad | 2348 | |
1239a312 DG |
2349 | #ifdef __cplusplus |
2350 | } | |
2351 | #endif | |
2352 | ||
2353 | #endif /* LTTNG_EVENT_H */ |