Commit | Line | Data |
---|---|---|
f2c1f0d4 | 1 | /* |
ab5be9fa MJ |
2 | * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com> |
3 | * Copyright (C) 2019 Mathieu Desnoyers <mathieu.desnoyers@efficios.com> | |
f2c1f0d4 | 4 | * |
ab5be9fa | 5 | * SPDX-License-Identifier: LGPL-2.1-only |
f2c1f0d4 | 6 | * |
f2c1f0d4 MD |
7 | */ |
8 | ||
9 | #ifndef LTTNG_CLEAR_H | |
10 | #define LTTNG_CLEAR_H | |
11 | ||
12 | #include <lttng/lttng-error.h> | |
4bd69c5f | 13 | #include <lttng/lttng-export.h> |
f2c1f0d4 MD |
14 | |
15 | #ifdef __cplusplus | |
16 | extern "C" { | |
17 | #endif | |
18 | ||
048f01ef PP |
19 | /*! |
20 | @addtogroup api_session_clear | |
21 | @{ | |
22 | */ | |
23 | ||
f2c1f0d4 MD |
24 | struct lttng_clear_handle; |
25 | ||
048f01ef PP |
26 | /*! |
27 | @brief | |
28 | Initiates a clearing operation of the \lt_obj_session | |
29 | named \lt_p{session_name}. | |
30 | ||
31 | Depending on the mode of the recording session \lt_var{RS} | |
32 | named \lt_p{session_name}, the clearing operation attempts to: | |
33 | ||
34 | <dl> | |
35 | <dt>\ref api-session-local-mode "Local" | |
36 | <dt>\ref api-session-net-mode "Network streaming" | |
37 | <dd> | |
38 | Delete the contents of the recording buffers of \lt_var{RS}. | |
39 | ||
40 | Delete the local/remote data stream files of \lt_var{RS}. | |
41 | ||
42 | <dt>\ref api-session-snapshot-mode "Snapshot" | |
43 | <dd> | |
44 | Delete the contents of the recording buffers of \lt_var{RS}. | |
45 | ||
46 | LTTng doesn't touch prior snapshots of \lt_var{RS}. | |
47 | ||
48 | <dt>\ref api-session-live-mode "Live" | |
49 | <dd> | |
50 | Delete the contents of the recording buffers of \lt_var{RS}. | |
51 | ||
52 | Delete the remote data stream files of \lt_var{RS}. | |
53 | ||
54 | Any active live reader currently reading a data stream packet | |
55 | may continue to read said packet completely. | |
56 | </dl> | |
57 | ||
58 | The clearing operation which this function initiates, if successful, | |
59 | guarantees that any trace data which LTTng produced \em before you call | |
60 | this function won't be part of any trace, except: | |
61 | ||
62 | - Preexisting recording session | |
63 | \ref api_session_snapshot "snapshots". | |
64 | - Preexisting | |
65 | \ref api_session_rotation "trace chunk archives". | |
66 | ||
67 | It's possible that trace data which LTTng produces while you're calling | |
68 | this function makes it to a trace. | |
69 | ||
70 | Use \lt_p{*handle} to wait for the completion of the recording session | |
71 | clearing operation. | |
72 | ||
73 | @param[in] session_name | |
74 | Name of the recording session to clear. | |
75 | @param[out] handle | |
76 | @parblock | |
77 | <strong>On success</strong>, this function sets \lt_p{*handle} to | |
78 | a handle which identifies this recording session clearing operation. | |
79 | ||
80 | May be \c NULL. | |
81 | ||
82 | Wait for the completion of this clearing operation with | |
83 | lttng_clear_handle_wait_for_completion(). | |
84 | ||
85 | Destroy \lt_p{*handle} with lttng_clear_handle_destroy(). | |
86 | @endparblock | |
87 | ||
88 | @returns | |
89 | @parblock | |
90 | #LTTNG_OK on success, or a \em negative enumerator otherwise. | |
91 | ||
92 | Notable return values: | |
93 | ||
94 | <table> | |
95 | <tr> | |
96 | <td>-#LTTNG_ERR_CLEAR_RELAY_DISALLOWED | |
97 | <td> | |
98 | The relay daemon doesn't allow recording session clearing | |
99 | operations. | |
100 | <tr> | |
101 | <td>-#LTTNG_ERR_CLEAR_NOT_AVAILABLE_RELAY | |
102 | <td> | |
103 | The relay daemon doesn't support the recording session | |
104 | clearing operation. | |
105 | <tr> | |
106 | <td>-#LTTNG_ERR_CLEAR_FAIL_CONSUMER | |
107 | <td> | |
108 | A consumer daemon failed to clear the recording session named | |
109 | \lt_p{session_name}. | |
110 | </table> | |
111 | @endparblock | |
112 | ||
113 | @lt_pre_conn | |
114 | @lt_pre_not_null{session_name} | |
115 | @lt_pre_sess_exists{session_name} | |
116 | @pre | |
117 | No clearing operation is in progress for the recording session named | |
118 | \lt_p{session_name}. | |
119 | */ | |
4bd69c5f | 120 | LTTNG_EXPORT extern enum lttng_error_code lttng_clear_session(const char *session_name, |
28f23191 | 121 | struct lttng_clear_handle **handle); |
048f01ef PP |
122 | |
123 | /// @} | |
124 | ||
316f62af JR |
125 | #ifdef __cplusplus |
126 | } | |
127 | #endif | |
f2c1f0d4 MD |
128 | |
129 | #endif /* LTTNG_CLEAR_H */ |