projects / lttng-tools.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
lttng-enable-channel(1): reword and fix style of --blocking-timeout description
[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 e238830d3bc63aafb722741dcd79897e80fc7612..bec0906428c5bfba6e9f91ab3e8f783cd96b472e 100644 (file)
--- a/doc/man/lttng-enable-channel.1.txt
+++ b/doc/man/lttng-enable-channel.1.txt
@@ -12,8 +12,8 @@ SYNOPSIS
 Create a Linux kernel channel:
 
 [verse]
 Create a Linux kernel channel:
 
 [verse]
-*lttng* ['GENERAL OPTIONS'] *enable-channel* option:--kernel
-      [option:--discard | option:--overwrite] [option:--output=(`mmap` | `splice`)]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--kernel
+      [option:--overwrite] [option:--output=(`mmap` | `splice`)]
       [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
       [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
       [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
       [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
       [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
       [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
@@ -22,17 +22,18 @@ Create a Linux kernel channel:
 Create a user space channel:
 
 [verse]
 Create a user space channel:
 
 [verse]
-*lttng* ['GENERAL OPTIONS'] *enable-channel* option:--userspace
-      [option:--discard | option:--overwrite] [option:--buffers-pid]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace
+      [option:--overwrite] [option:--buffers-pid]
       [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
       [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
       [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
       [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
+      [option:--blocking-timeout='TIMEOUTUS']
       [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
       [option:--session='SESSION'] 'CHANNEL'
 
 Enable existing channel(s):
 
 [verse]
       [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
       [option:--session='SESSION'] 'CHANNEL'
 
 Enable existing channel(s):
 
 [verse]
-*lttng* ['GENERAL OPTIONS'] *enable-channel* (option:--userspace | option:--kernel)
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel)
       [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']...
 
 
       [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']...
 
 
@@ -42,7 +43,7 @@ The `lttng enable-channel` command can create a new channel, or enable
 one or more existing and disabled ones.
 
 A channel is the owner of sub-buffers holding recorded events. Event,
 one or more existing and disabled ones.
 
 A channel is the owner of sub-buffers holding recorded events. Event,
-rules, when created using linklttng:lttng-enable-event(1), are always
+rules, when created using man:lttng-enable-event(1), are always
 assigned to a channel. When creating a new channel, many parameters
 related to those sub-buffers can be fine-tuned. They are described in
 the subsections below.
 assigned to a channel. When creating a new channel, many parameters
 related to those sub-buffers can be fine-tuned. They are described in
 the subsections below.
@@ -51,30 +52,21 @@ When 'CHANNEL' does not name an existing channel, a channel named
 'CHANNEL' is created. Otherwise, the disabled channel named 'CHANNEL'
 is enabled.
 
 'CHANNEL' is created. Otherwise, the disabled channel named 'CHANNEL'
 is enabled.
 
-Note that the linklttng:lttng-enable-event(1) command can automatically
+Note that the man:lttng-enable-event(1) command can automatically
 create default channels when no channel exist.
 
 A channel is always contained in a tracing session
 create default channels when no channel exist.
 
 A channel is always contained in a tracing session
-(see linklttng:lttng-create(1) for creating a tracing session). The
+(see man:lttng-create(1) for creating a tracing session). The
 session in which a channel is created using `lttng enable-channel` can
 be specified using the option:--session option. If the option:--session
 option is omitted, the current tracing session is targeted.
 
 Existing enabled channels can be disabled using
 session in which a channel is created using `lttng enable-channel` can
 be specified using the option:--session option. If the option:--session
 option is omitted, the current tracing session is targeted.
 
 Existing enabled channels can be disabled using
-linklttng:lttng-disable-channel(1). Channels of a given session can be
-listed using linklttng:lttng-list(1).
+man:lttng-disable-channel(1). Channels of a given session can be
+listed using man:lttng-list(1).
 
 
-As of this version of LTTng, it is not possible to:
-
-* Reconfigure a channel once it is created.
-* Re-enable a disabled channel once its tracing session has been active
-  at least once.
-* Create a channel once its tracing session has been active
-  at least once.
-* Create a user space channel with a given buffering scheme
-  (option:--buffers-uid or option:--buffers-pid options) and create
-  a second user space channel with a different buffering scheme in the
-  same tracing session.
+See the <<limitations,LIMITATIONS>> section below for a list of
+limitations of this command to consider.
 
 
 Event loss modes
 
 
 Event loss modes
@@ -209,10 +201,11 @@ in conjunction with the option:--tracefile-size option.
 
 For example, consider this command:
 
 
 For example, consider this command:
 
------------------------------------------------------
-lttng enable-channel --kernel --tracefile-size=4096 \
+[role="term"]
+----
+$ lttng enable-channel --kernel --tracefile-size=4096 \
                      --tracefile-count=32 my-channel
                      --tracefile-count=32 my-channel
------------------------------------------------------
+----
 
 Here, for each stream, the maximum size of each trace file is
 4 kiB and there can be a maximum of 32 different files. When there is
 
 Here, for each stream, the maximum size of each trace file is
 4 kiB and there can be a maximum of 32 different files. When there is
@@ -236,7 +229,7 @@ option:-u, option:--userspace::
 
 Target
 ~~~~~~
 
 Target
 ~~~~~~
-option:-s, option:--session='SESSION'::
+option:-s 'SESSION', option:--session='SESSION'::
     Create or enable channel in the tracing session named 'SESSION'
     instead of the current tracing session.
 
     Create or enable channel in the tracing session named 'SESSION'
     instead of the current tracing session.
 
@@ -260,8 +253,12 @@ option:--num-subbuf='COUNT'::
 +
 Default values:
 +
 +
 Default values:
 +
-* `metadata` channel: 2
-* Everything else: 4
+* option:--userspace and option:--buffers-uid options:
+  {default_ust_uid_channel_subbuf_num}
+* option:--userspace and option:--buffers-pid options:
+  {default_ust_pid_channel_subbuf_num}
+* option:--kernel option: {default_kernel_channel_subbuf_num}
+* `metadata` channel: {default_metadata_subbuf_num}
 
 option:--subbuf-size='SIZE'::
     Set the individual size of sub-buffers to 'SIZE' bytes.
 
 option:--subbuf-size='SIZE'::
     Set the individual size of sub-buffers to 'SIZE' bytes.
@@ -274,10 +271,12 @@ command shows the current system's page size: `getconf PAGE_SIZE`.
 +
 Default values:
 +
 +
 Default values:
 +
-* option:--userspace and option:--buffers-uid options: `128k`
-* option:--userspace and option:--buffers-pid options: `4k`
-* option:--kernel option: `256k`
-* `metadata` channel: `4k`
+* option:--userspace and option:--buffers-uid options:
+  {default_ust_uid_channel_subbuf_size}
+* option:--userspace and option:--buffers-pid options:
+  {default_ust_pid_channel_subbuf_size}
+* option:--kernel option: {default_kernel_channel_subbuf_size}
+* `metadata` channel: {default_metadata_subbuf_size}
 
 option:--output='TYPE'::
     Set channel's output type to 'TYPE'.
 
 option:--output='TYPE'::
     Set channel's output type to 'TYPE'.
@@ -314,7 +313,8 @@ Trace files
 ~~~~~~~~~~~
 option:--tracefile-count='COUNT'::
     Limit the number of trace files created by this channel to
 ~~~~~~~~~~~
 option:--tracefile-count='COUNT'::
     Limit the number of trace files created by this channel to
-    'COUNT'. 0 means unlimited. Default: 0.
+    'COUNT'. 0 means unlimited. Default:
+    {default_channel_tracefile_count}.
 +
 Use this option in conjunction with the option:--tracefile-size option.
 +
 +
 Use this option in conjunction with the option:--tracefile-size option.
 +
@@ -325,7 +325,7 @@ the first trace file of the stream is cleared and used again.
 option:--tracefile-size='SIZE'::
     Set the maximum size of each trace file written by
     this channel within a stream to 'SIZE' bytes. 0 means unlimited.
 option:--tracefile-size='SIZE'::
     Set the maximum size of each trace file written by
     this channel within a stream to 'SIZE' bytes. 0 means unlimited.
-    Default: 0.
+    Default: {default_channel_tracefile_size}.
 +
 Note: traces generated with this option may inaccurately report
 discarded events as of CTF 1.8.
 +
 Note: traces generated with this option may inaccurately report
 discarded events as of CTF 1.8.
@@ -339,23 +339,71 @@ option:--read-timer::
 +
 Default values:
 +
 +
 Default values:
 +
-* option:--userspace and option:--buffers-uid options: 0
-* option:--userspace and option:--buffers-pid options: 0
-* option:--kernel option: 200000
-* `metadata` channel: 0
+* option:--userspace and option:--buffers-uid options:
+  {default_ust_uid_channel_read_timer}
+* option:--userspace and option:--buffers-pid options:
+  {default_ust_pid_channel_read_timer}
+* option:--kernel option: {default_kernel_channel_read_timer}
+* `metadata` channel: {default_metadata_read_timer}
 
 option:--switch-timer='PERIODUS'::
     Set the channel's switch timer's period to 'PERIODUS' µs. 0 means
 
 option:--switch-timer='PERIODUS'::
     Set the channel's switch timer's period to 'PERIODUS' µs. 0 means
-    a disabled switch timer. Default: 0.
+    a disabled switch timer.
++
+Default values:
++
+* option:--userspace and option:--buffers-uid options:
+  {default_ust_uid_channel_switch_timer}
+* option:--userspace and option:--buffers-pid options:
+  {default_ust_pid_channel_switch_timer}
+* 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[]
 
 
 
 
 include::common-cmd-help-options.txt[]
 
 
+[[limitations]]
+LIMITATIONS
+-----------
+As of this version of LTTng, it is not possible to perform the following
+actions with the `lttng enable-channel` command:
+
+* Reconfigure a channel once it is created.
+* Re-enable a disabled channel once its tracing session has been active
+  at least once.
+* Create a channel once its tracing session has been active
+  at least once.
+* Create a user space channel with a given buffering scheme
+  (option:--buffers-uid or option:--buffers-pid options) and create
+  a second user space channel with a different buffering scheme in the
+  same tracing session.
+
+
 include::common-cmd-footer.txt[]
 
 
 SEE ALSO
 --------
 include::common-cmd-footer.txt[]
 
 
 SEE ALSO
 --------
-linklttng:lttng-disable-channel(1),
-linklttng:lttng(1)
+man:lttng-disable-channel(1),
+man:lttng(1),
+man:lttng-ust(3)
LTTng 2.0 tools and control repository
This page took 0.025685 seconds and 4 git commands to generate.