X-Git-Url: http://git.lttng.org/?a=blobdiff_plain;f=include%2Flttng%2Fclear.h;h=34d8e49815bd87eda62acc8891599f18503623f2;hb=048f01efd5931e364cc777d47c284c3f7d7d6ed6;hp=8961e166fb0d122c82c00a92291f0306c9795814;hpb=78f5b22de60c114c5c83410015a08bdd212edc0b;p=lttng-tools.git diff --git a/include/lttng/clear.h b/include/lttng/clear.h index 8961e166f..34d8e4981 100644 --- a/include/lttng/clear.h +++ b/include/lttng/clear.h @@ -16,47 +16,112 @@ extern "C" { #endif +/*! +@addtogroup api_session_clear +@{ +*/ + 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 - */ +/*! +@brief + Initiates a clearing operation of the \lt_obj_session + named \lt_p{session_name}. + +Depending on the mode of the recording session \lt_var{RS} +named \lt_p{session_name}, the clearing operation attempts to: + +
-#LTTNG_ERR_CLEAR_RELAY_DISALLOWED + | + The relay daemon doesn't allow recording session clearing + operations. + |
-#LTTNG_ERR_CLEAR_NOT_AVAILABLE_RELAY + | + The relay daemon doesn't support the recording session + clearing operation. + |
-#LTTNG_ERR_CLEAR_FAIL_CONSUMER + | + A consumer daemon failed to clear the recording session named + \lt_p{session_name}. + |