| 1 | /* |
| 2 | * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com> |
| 3 | * Copyright (C) 2019 Mathieu Desnoyers <mathieu.desnoyers@efficios.com> |
| 4 | * |
| 5 | * SPDX-License-Identifier: LGPL-2.1-only |
| 6 | * |
| 7 | */ |
| 8 | |
| 9 | #ifndef LTTNG_CLEAR_H |
| 10 | #define LTTNG_CLEAR_H |
| 11 | |
| 12 | #include <lttng/lttng-error.h> |
| 13 | #include <lttng/lttng-export.h> |
| 14 | |
| 15 | #ifdef __cplusplus |
| 16 | extern "C" { |
| 17 | #endif |
| 18 | |
| 19 | /*! |
| 20 | @addtogroup api_session_clear |
| 21 | @{ |
| 22 | */ |
| 23 | |
| 24 | struct lttng_clear_handle; |
| 25 | |
| 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 | */ |
| 120 | LTTNG_EXPORT extern enum lttng_error_code lttng_clear_session(const char *session_name, |
| 121 | struct lttng_clear_handle **handle); |
| 122 | |
| 123 | /// @} |
| 124 | |
| 125 | #ifdef __cplusplus |
| 126 | } |
| 127 | #endif |
| 128 | |
| 129 | #endif /* LTTNG_CLEAR_H */ |