lttng-enable-channel(1): reword --blocking-timeout, document in description

Also change the synopsis so that you can specify --blocking-timeout,
--overwrite, or none, but not both.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/doc/man/lttng-enable-channel.1.txt b/doc/man/lttng-enable-channel.1.txt
index c4781c0f1953bfaad67382a9f948a686cd09fe9c..787666ad5d1969d3f23598f1015c631443a8a99e 100644 (file)
--- a/doc/man/lttng-enable-channel.1.txt
+++ b/doc/man/lttng-enable-channel.1.txt
@@ -24,10 +24,10 @@ Create a user space channel:
 
 [verse]
 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace
-      [option:--overwrite] [option:--buffers-pid]
+      [option:--overwrite | option:--blocking-timeout='TIMEOUTUS'] [option:--buffers-pid]
       [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
       [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
-      [option:--monitor-timer='PERIODUS'] [option:--blocking-timeout='TIMEOUTUS']
+      [option:--monitor-timer='PERIODUS']
       [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
       [option:--session='SESSION'] 'CHANNEL'
 
@@ -72,14 +72,20 @@ limitations of this command to consider.
 
 Event loss modes
 ~~~~~~~~~~~~~~~~
-LTTng tracers are non-blocking: when no empty sub-buffer exists,
-losing events is acceptable when the alternative would be to cause
-substantial delays in the instrumented application's execution.
+LTTng tracers are non-blocking by default: when no empty sub-buffer
+exists, losing events is acceptable when the alternative would be to
+cause substantial delays in the instrumented application's execution.
 
 LTTng privileges performance over integrity, aiming at perturbing the
 traced system as little as possible in order to make tracing of subtle
 race conditions and rare interrupt cascades possible.
 
+You can allow the user space tracer to block with a
+option:--blocking-timeout option set to a positive value or to `inf`,
+and with an application which is instrumented with LTTng-UST started
+with a set `LTTNG_UST_ALLOW_BLOCKING` environment variable. See
+man:lttng-ust(3) for more details.
+
 When it comes to losing events because no empty sub-buffer is available,
 the channel's event loss mode, specified by one of the option:--discard
 and option:--overwrite options, determines what to do amongst:
@@ -262,6 +268,27 @@ option:-s 'SESSION', option:--session='SESSION'::
 
 Event loss mode
 ~~~~~~~~~~~~~~~
+option:--blocking-timeout='TIMEOUTUS'::
+    Set the channel's blocking timeout value to 'TIMEOUTUS' µs for
+    instrumented applications executed with a set
+    `LTTNG_UST_ALLOW_BLOCKING` environment variable:
++
+--
+0 (default)::
+    Do not block (non-blocking mode).
+
+`inf`::
+    Block forever until room is available in the sub-buffer to write the
+    event record.
+
+__n__, a positive value::
+    Wait for at most __n__ µs when trying to write into a sub-buffer.
+    After __n__ µs, discard the event record.
+--
++
+This option is only available with the option:--userspace option and
+without the option:--overwrite option.
+
 One of:
 
 option:--discard::
@@ -398,25 +425,6 @@ Default values:
 * option:--kernel option: {default_kernel_channel_switch_timer}
 * `metadata` channel: {default_metadata_switch_timer}
 
-Timeouts
-~~~~~~~~
-option:--blocking-timeout='TIMEOUTUS'::
-    Set the channel's blocking timeout value to 'TIMEOUTUS' µs
-    for applications executed with a set `LTTNG_UST_ALLOW_BLOCKING`
-    environment variable:
-+
---
-0 (default)::
-    Do not block.
-
--1::
-    Block forever until room is available in the sub-buffer to write the
-    event record.
-
-__n__, a positive value::
-    Wait for at most __n__ µs when trying to write into a sub-buffer.
---
-
 
 include::common-cmd-help-options.txt[]