From: Philippe Proulx <eeppeliteloop@gmail.com>
Date: Fri, 28 Jul 2017 20:30:42 +0000 (-0400)
Subject: lttng-enable-channel(1): reword --blocking-timeout, document in description
X-Git-Tag: v2.11.0-rc1~457
X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=commitdiff_plain;h=7197e9ec670114d94064a1b1658a9a2ca3b348a9

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 c4781c0f1..787666ad5 100644
--- 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[]