[lttng-tools.git] / include / lttng / clear.h

/*
 * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
 * Copyright (C) 2019 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
 *
 * SPDX-License-Identifier: LGPL-2.1-only
 *
 */

#ifndef LTTNG_CLEAR_H
#define LTTNG_CLEAR_H

#include <lttng/lttng-error.h>

#ifdef __cplusplus
extern "C" {
#endif

struct lttng_clear_handle;

/*
 * Clear a tracing session.
 *
 * Clear the data buffers and trace data.
 *
 * For sessions saving trace data to disk and streaming over the network to a
 * relay daemon, the buffers content and existing stream files are cleared when
 * the clear command is issued.
 *
 * For snapshot sessions (flight recorder), only the buffer content is cleared.
 * Prior snapshots are individually recorded to disk, and are therefore
 * untouched by this "clear" command.
 *
 * For live sessions streaming over network to a relay daemon, the buffers
 * will be cleared and the files on the relay daemon side will be cleared as
 * well. However, any active live trace viewer currently reading an existing
 * trace packet will be able to proceed to read that packet entirely before
 * skipping over cleared stream data.
 *
 * The clear command guarantees that no trace data produced before this function
 * is called will be present in the resulting trace.
 *
 * Trace data produced between the moment this function is called and when it
 * returns might be present in the resulting trace.
 *
 * Provides an lttng_clear_handle which can be used to wait for the completion
 * of the session's clear.
 *
 * Return LTTNG_OK on success else a negative LTTng error code. The returned
 * handle is owned by the caller and must be free'd using
 * lttng_clear_handle_destroy().
 *
 * Important error codes:
 *    LTTNG_ERR_CLEAR_RELAY_DISALLOWED
 *    LTTNG_ERR_CLEAR_NOT_AVAILABLE_RELAY
 *    LTTNG_ERR_CLEAR_FAIL_CONSUMER
*/
extern enum lttng_error_code lttng_clear_session(const char *session_name,
		struct lttng_clear_handle **handle);
#ifdef __cplusplus
}
#endif

#endif /* LTTNG_CLEAR_H */
Commit	Line	Data
	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	#ifdef __cplusplus
	60	}
	61	#endif
	62
	63	#endif /* LTTNG_CLEAR_H */