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 struct lttng_clear_handle;
  20
  21 /*
  22  * Clear a tracing session.
  23  *
  24  * Clear the data buffers and trace data.
  25  *
  26  * For sessions saving trace data to disk and streaming over the network to a
  27  * relay daemon, the buffers content and existing stream files are cleared when
  28  * the clear command is issued.
  29  *
  30  * For snapshot sessions (flight recorder), only the buffer content is cleared.
  31  * Prior snapshots are individually recorded to disk, and are therefore
  32  * untouched by this "clear" command.
  33  *
  34  * For live sessions streaming over network to a relay daemon, the buffers
  35  * will be cleared and the files on the relay daemon side will be cleared as
  36  * well. However, any active live trace viewer currently reading an existing
  37  * trace packet will be able to proceed to read that packet entirely before
  38  * skipping over cleared stream data.
  39  *
  40  * The clear command guarantees that no trace data produced before this function
  41  * is called will be present in the resulting trace.
  42  *
  43  * Trace data produced between the moment this function is called and when it
  44  * returns might be present in the resulting trace.
  45  *
  46  * Provides an lttng_clear_handle which can be used to wait for the completion
  47  * of the session's clear.
  48  *
  49  * Return LTTNG_OK on success else a negative LTTng error code. The returned
  50  * handle is owned by the caller and must be free'd using
  51  * lttng_clear_handle_destroy().
  52  *
  53  * Important error codes:
  54  *    LTTNG_ERR_CLEAR_RELAY_DISALLOWED
  55  *    LTTNG_ERR_CLEAR_NOT_AVAILABLE_RELAY
  56  *    LTTNG_ERR_CLEAR_FAIL_CONSUMER
  57  */
  58 LTTNG_EXPORT extern enum lttng_error_code lttng_clear_session(const char *session_name,
  59                                                               struct lttng_clear_handle **handle);
  60 #ifdef __cplusplus
  61 }
  62 #endif
  63
  64 #endif /* LTTNG_CLEAR_H */