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