Check for pending notification on notification channel activity

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

diff --git a/doc/man/lttng-enable-channel.1.txt b/doc/man/lttng-enable-channel.1.txt
index cad26a8643edf052a67bd0aa0738cfe834c14ba5..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::
@@ -286,6 +313,19 @@ Default values:
 * option:--kernel option: {default_kernel_channel_subbuf_num}
 * `metadata` channel: {default_metadata_subbuf_num}
 
+option:--output='TYPE'::
+    Set channel's output type to 'TYPE'.
++
+Available types: `mmap` (always available) and `splice` (only available
+with the option:--kernel option).
++
+Default values:
++
+* option:--userspace and option:--buffers-uid options: `mmap`
+* option:--userspace and option:--buffers-pid options: `mmap`
+* option:--kernel option: `splice`
+* `metadata` channel: `mmap`
+
 option:--subbuf-size='SIZE'::
     Set the individual size of sub-buffers to 'SIZE' bytes.
     The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported.
@@ -304,18 +344,6 @@ Default values:
 * option:--kernel option: {default_kernel_channel_subbuf_size}
 * `metadata` channel: {default_metadata_subbuf_size}
 
-option:--output='TYPE'::
-    Set channel's output type to 'TYPE'.
-+
-Available types: `mmap` (always available) and `splice` (only available
-with the option:--kernel option).
-+
-Default values:
-+
-* option:--userspace and option:--buffers-uid options: `mmap`
-* option:--userspace and option:--buffers-pid options: `mmap`
-* option:--kernel option: `splice`
-* `metadata` channel: `mmap`
 
 Buffering scheme
 ~~~~~~~~~~~~~~~~
@@ -397,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[]