include/lttng/clear.h

   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 */