X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=include%2Flttng%2Fclear.h;h=8961e166fb0d122c82c00a92291f0306c9795814;hp=34ace3d9a17fa502e5e0604a553ae686f11ef378;hb=HEAD;hpb=ab5be9fa2eb5ba9600a82cd18fd3cfcbac69169a

diff --git a/include/lttng/clear.h b/include/lttng/clear.h
index 34ace3d9a..34d8e4981 100644
--- a/include/lttng/clear.h
+++ b/include/lttng/clear.h
@@ -10,51 +10,120 @@
 #define LTTNG_CLEAR_H
 
 #include <lttng/lttng-error.h>
+#include <lttng/lttng-export.h>
 
 #ifdef __cplusplus
 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:
+
+<dl>
+  <dt>\ref api-session-local-mode "Local"
+  <dt>\ref api-session-net-mode "Network streaming"
+  <dd>
+    Delete the contents of the recording buffers of \lt_var{RS}.
+
+    Delete the local/remote data stream files of \lt_var{RS}.
+
+  <dt>\ref api-session-snapshot-mode "Snapshot"
+  <dd>
+    Delete the contents of the recording buffers of \lt_var{RS}.
+
+    LTTng doesn't touch prior snapshots of \lt_var{RS}.
+
+  <dt>\ref api-session-live-mode "Live"
+  <dd>
+    Delete the contents of the recording buffers of \lt_var{RS}.
+
+    Delete the remote data stream files of \lt_var{RS}.
+
+    Any active live reader currently reading a data stream packet
+    may continue to read said packet completely.
+</dl>
+
+The clearing operation which this function initiates, if successful,
+guarantees that any trace data which LTTng produced \em before you call
+this function won't be part of any trace, except:
+
+- Preexisting recording session
+  \ref api_session_snapshot "snapshots".
+- Preexisting
+  \ref api_session_rotation "trace chunk archives".
+
+It's possible that trace data which LTTng produces while you're calling
+this function makes it to a trace.
+
+Use \lt_p{*handle} to wait for the completion of the recording session
+clearing operation.
+
+@param[in] session_name
+    Name of the recording session to clear.
+@param[out] handle
+    @parblock
+    <strong>On success</strong>, this function sets \lt_p{*handle} to
+    a handle which identifies this recording session clearing operation.
+
+    May be \c NULL.
+
+    Wait for the completion of this clearing operation with
+    lttng_clear_handle_wait_for_completion().
+
+    Destroy \lt_p{*handle} with lttng_clear_handle_destroy().
+    @endparblock
+
+@returns
+    @parblock
+    #LTTNG_OK on success, or a \em negative enumerator otherwise.
+
+    Notable return values:
+
+    <table>
+      <tr>
+	<td>-#LTTNG_ERR_CLEAR_RELAY_DISALLOWED
+	<td>
+	  The relay daemon doesn't allow recording session clearing
+	  operations.
+      <tr>
+	<td>-#LTTNG_ERR_CLEAR_NOT_AVAILABLE_RELAY
+	<td>
+	  The relay daemon doesn't support the recording session
+	  clearing operation.
+      <tr>
+	<td>-#LTTNG_ERR_CLEAR_FAIL_CONSUMER
+	<td>
+	  A consumer daemon failed to clear the recording session named
+	  \lt_p{session_name}.
+    </table>
+    @endparblock
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+@pre
+    No clearing operation is in progress for the recording session named
+    \lt_p{session_name}.
 */
-extern enum lttng_error_code lttng_clear_session(const char *session_name,
-		struct lttng_clear_handle **handle);
+LTTNG_EXPORT extern enum lttng_error_code lttng_clear_session(const char *session_name,
+							      struct lttng_clear_handle **handle);
+
+/// @}
+
+#ifdef __cplusplus
+}
+#endif
 
 #endif /* LTTNG_CLEAR_H */