Document tracing session rotation features

[lttng-tools.git] / doc / man / lttng-destroy.1.txt

diff --git a/doc/man/lttng-destroy.1.txt b/doc/man/lttng-destroy.1.txt
index d23d094ebf28c2ccd831b0a1224e76eea1613978..1e7ecade209124078a0ed020222a3cb865602aa7 100644 (file)
--- a/doc/man/lttng-destroy.1.txt
+++ b/doc/man/lttng-destroy.1.txt
@@ -10,7 +10,7 @@ lttng-destroy - Destroy an LTTng tracing session
 SYNOPSIS
 --------
 [verse]
-*lttng* ['GENERAL OPTIONS'] *destroy* [option:--all | 'SESSION']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *destroy* [option:--no-wait] [option:--all | 'SESSION']
 
 
 DESCRIPTION
@@ -18,22 +18,35 @@ DESCRIPTION
 The `lttng destroy` command destroys one or more tracing sessions.
 
 If no options are specified, the current tracing session is destroyed
-(see linklttng:lttng-create(1) for more information about the current
+(see man:lttng-create(1) for more information about the current
 tracing session).
 
 If 'SESSION' is specified, the existing tracing session named 'SESSION'
 is destroyed. `lttng list` outputs all the existing tracing sessions
-(see linklttng:lttng-list(1)).
+(see man:lttng-list(1)).
 
 If the option:--all option is used, *all* the tracing sessions, as listed
 in the output of `lttng list`, are destroyed.
 
-Destroying a tracing session stops any tracing running within the latter.
+Destroying a tracing session stops any tracing running within the
+latter. By default, the implicit man:lttng-stop(1) command invoked by
+the `lttng destroy` command ensures that the tracing session's trace
+data is valid before returning. With the option:--no-wait option, the
+man:lttng-stop(1) command finishes immediately, hence a local trace
+might not be valid when the command is done. In this case, there is no
+way to know when the trace becomes valid.
 
 Destroying a tracing session does not destroy the recorded trace data,
 if any; it frees resources acquired by the session daemon and tracer
 side, making sure to flush all trace data.
 
+If at least one rotation occurred during the chosen tracing session's
+lifetime (see man:lttng-rotate(1) and man:lttng-enable-rotation(1)), and
+without the option:--no-wait option, all the tracing session's output
+directory's subdirectories are considered trace chunk archives once the
+command returns: it is safe to read them, modify them, move them, or
+remove them.
+
 
 include::common-cmd-options-head.txt[]
 
@@ -41,6 +54,10 @@ include::common-cmd-options-head.txt[]
 option:-a, option:--all::
     Destroy all tracing sessions.
 
+option:-n, option:--no-wait::
+    Do not ensure that the chosen tracing session's trace data is valid
+    before returning to the prompt.
+
 
 include::common-cmd-help-options.txt[]
 
@@ -50,6 +67,6 @@ include::common-cmd-footer.txt[]
 
 SEE ALSO
 --------
-linklttng:lttng-create(1),
-linklttng:lttng-set-session(1),
-linklttng:lttng(1)
+man:lttng-create(1),
+man:lttng-set-session(1),
+man:lttng(1)