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  * This library is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU Lesser General Public License, version 2.1 only,
   7  * as published by the Free Software Foundation.
   8  *
   9  * This library is distributed in the hope that it will be useful, but WITHOUT
  10  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
  12  * for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public License
  15  * along with this library; if not, write to the Free Software Foundation,
  16  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  17  */
  18
  19 #ifndef LTTNG_CLEAR_H
  20 #define LTTNG_CLEAR_H
  21
  22 #include <lttng/lttng-error.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 struct lttng_clear_handle;
  29
  30 /*
  31  * Clear a tracing session.
  32  *
  33  * Clear the data buffers and trace data.
  34  *
  35  * For sessions saving trace data to disk and streaming over the network to a
  36  * relay daemon, the buffers content and existing stream files are cleared when
  37  * the clear command is issued.
  38  *
  39  * For snapshot sessions (flight recorder), only the buffer content is cleared.
  40  * Prior snapshots are individually recorded to disk, and are therefore
  41  * untouched by this "clear" command.
  42  *
  43  * For live sessions streaming over network to a relay daemon, the buffers
  44  * will be cleared and the files on the relay daemon side will be cleared as
  45  * well. However, any active live trace viewer currently reading an existing
  46  * trace packet will be able to proceed to read that packet entirely before
  47  * skipping over cleared stream data.
  48  *
  49  * The clear command guarantees that no trace data produced before this function
  50  * is called will be present in the resulting trace.
  51  *
  52  * Trace data produced between the moment this function is called and when it
  53  * returns might be present in the resulting trace.
  54  *
  55  * Provides an lttng_clear_handle which can be used to wait for the completion
  56  * of the session's clear.
  57  *
  58  * Return LTTNG_OK on success else a negative LTTng error code. The returned
  59  * handle is owned by the caller and must be free'd using
  60  * lttng_clear_handle_destroy().
  61  *
  62  * Important error codes:
  63  *    LTTNG_ERR_CLEAR_RELAY_DISALLOWED
  64  *    LTTNG_ERR_CLEAR_NOT_AVAILABLE_RELAY
  65  *    LTTNG_ERR_CLEAR_FAIL_CONSUMER
  66 */
  67 extern enum lttng_error_code lttng_clear_session(const char *session_name,
  68                 struct lttng_clear_handle **handle);
  69
  70 #endif /* LTTNG_CLEAR_H */