Manpage: cleanup layout of version

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

diff --git a/doc/man/lttng.1 b/doc/man/lttng.1
index 39af988ed4fd17a2ffd350aa04598bff7e84e80b..e831867a2fe7c5b9fe51f9008684c6a3a631d824 100644 (file)
--- a/doc/man/lttng.1
+++ b/doc/man/lttng.1
@@ -448,8 +448,9 @@ there is data available.
 .RE
 .PP
 
 .RE
 .PP
 

-.IP "\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]"
-.nf
+.PP
+\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]
+.RS

 Enable tracing event
 
 A tracing event is always assigned to a channel. If \fB\-c, \-\-channel\fP is
 Enable tracing event
 
 A tracing event is always assigned to a channel. If \fB\-c, \-\-channel\fP is


@@ -459,87 +460,104 @@ using the wildcard "*".
 
 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
 file.
 
 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
 file.

-.fi

 
 .B OPTIONS:
 
 
 .B OPTIONS:
 

+.TP
+.BR "\-h, \-\-help"
+Show summary of possible options and commands.
+.TP
+.BR "\-\-list-options"
+Simple listing of options
+.TP
+.BR "\-s, \-\-session NAME"
+Apply on session name
+.TP
+.BR "\-c, \-\-channel NAME"
+Apply on channel name
+.TP
+.BR "\-a, \-\-all"
+Enable all tracepoints and syscalls. This actually enable a single
+wildcard event "*".
+.TP
+.BR "\-k, \-\-kernel"
+Apply for the kernel tracer
+.TP
+.BR "\-u, \-\-userspace"
+Apply for the user-space tracer
+.TP
+.BR "\-\-tracepoint"
+Tracepoint event (default). Userspace tracer supports wildcards at end
+of string. Don't forget to quote to deal with bash expansion.
+e.g.:

 .nf
 .nf

-\-h, \-\-help
-        Show summary of possible options and commands.
-\-\-list-options
-        Simple listing of options
-\-s, \-\-session NAME
-        Apply on session name
-\-c, \-\-channel NAME
-        Apply on channel name
-\-a, \-\-all
-        Enable all tracepoints and syscalls. This actually enable a single
-        wildcard event "*".
-\-k, \-\-kernel
-        Apply for the kernel tracer
-\-u, \-\-userspace
-        Apply for the user-space tracer
-
-\-\-tracepoint
-        Tracepoint event (default)
-        - userspace tracer supports wildcards at end of string. Don't forget to
-        quote to deal with bash expansion.
-        e.g.:

         "*"
         "app_component:na*"
         "*"
         "app_component:na*"

-\-\-loglevel NAME
-        Tracepoint loglevel range from 0 to loglevel. Listed in the help (\-h).
-\-\-loglevel-only NAME
-        Tracepoint loglevel (only this loglevel).
-
-        The loglevel or loglevel-only options should be combined with a
-        tracepoint name or tracepoint wildcard.
-\-\-probe [addr | symbol | symbol+offset]
-        Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...)
-        or hexadecimal (0xNNN...)
-\-\-function [addr | symbol | symbol+offset]
-        Dynamic function entry/return probe. Addr and offset can be octal
-        (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...)
-\-\-syscall
-        System call event. Enabling syscalls tracing (kernel tracer), you will
-        not be able to disable them with disable-event. This is a known
-        limitation. You can disable the entire channel to do the trick.
-
-\-\-filter 'expression'
-        Set a filter on a newly enabled event. Filter expression on event
-       fields and context. Event recording depends on evaluation. Only
-       specify on first activation of a given event within a session.
-       Filter only allowed when enabling events within a session before
-       tracing is started. If the filter fails to link with the event
-       within the traced domain, the event will be discarded.
-       Currently, filter is only implemented for the user-space tracer.
-
-        Expression examples:
-
-        'intfield > 500 && intfield < 503'
-        '(stringfield == "test" || intfield != 10) && intfield > 33'
-        'doublefield > 1.1 && intfield < 5.3'
-
-        Wildcards are allowed at the end of strings:
-        'seqfield1 == "te*"'
-        In string literals, the escape character is a '\\'. Use '\\*' for
-        the '*' character, and '\\\\' for the '\\' character. Wildcard
-       match any sequence of characters, including an empty sub-string
-       (match 0 or more characters).
-
-       Context information can be used for filtering. The examples
-       below show usage of context filtering on process name (with a
-       wildcard), process ID range, and unique thread ID for filtering.
-       The process and thread ID of running applications can be found
-       under columns "PID" and "LWP" of the "ps -eLf" command.
-
-       '$ctx.procname == "demo*"'
-       '$ctx.vpid >= 4433 && $ctx.vpid < 4455'
-       '$ctx.vtid == 1234'

 .fi
 .fi

+.TP
+.BR "\-\-loglevel NAME"
+Tracepoint loglevel range from 0 to loglevel. Listed in the help (\-h).
+.TP
+.BR "\-\-loglevel-only NAME"
+Tracepoint loglevel (only this loglevel).
+The loglevel or loglevel-only options should be combined with a
+tracepoint name or tracepoint wildcard.
+.TP
+.BR "\-\-probe (addr | symbol | symbol+offset)"
+Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...)
+or hexadecimal (0xNNN...)
+.TP
+.BR "\-\-function (addr | symbol | symbol+offset)"
+Dynamic function entry/return probe. Addr and offset can be octal
+(0NNN...), decimal (NNN...) or hexadecimal (0xNNN...)
+.TP
+.BR "\-\-syscall"
+System call event. Enabling syscalls tracing (kernel tracer), you will
+not be able to disable them with disable-event. This is a known
+limitation. You can disable the entire channel to do the trick.
+.TP
+.BR "\-\-filter 'expression'"
+Set a filter on a newly enabled event. Filter expression on event
+fields and context. Event recording depends on evaluation. Only
+specify on first activation of a given event within a session.
+Filter only allowed when enabling events within a session before
+tracing is started. If the filter fails to link with the event
+within the traced domain, the event will be discarded.
+Currently, filter is only implemented for the user-space tracer.
+
+Expression examples:

 
 

-.IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"

 .nf
 .nf

+  'intfield > 500 && intfield < 503'
+  '(strfield == "test" || intfield != 10) && intfield > 33'
+  'doublefield > 1.1 && intfield < 5.3'
+.fi
+
+Wildcards are allowed at the end of strings:
+  'seqfield1 == "te*"'
+In string literals, the escape character is a '\\'. Use '\\*' for
+the '*' character, and '\\\\' for the '\\' character. Wildcard
+match any sequence of characters, including an empty sub-string
+(match 0 or more characters).
+
+Context information can be used for filtering. The examples below show
+usage of context filtering on process name (with a wildcard), process ID
+range, and unique thread ID for filtering.  The process and thread ID of
+running applications can be found under columns "PID" and "LWP" of the
+"ps -eLf" command.
+
+.nf
+  '$ctx.procname == "demo*"'
+  '$ctx.vpid >= 4433 && $ctx.vpid < 4455'
+  '$ctx.vtid == 1234'
+.fi
+
+.RE
+.PP
+
+.PP
+\fBdisable-channel\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS]
+.RS

 Disable tracing channel
 
 Disabling a channel makes all event(s) in that channel to stop tracing. You can
 Disable tracing channel
 
 Disabling a channel makes all event(s) in that channel to stop tracing. You can


@@ -547,25 +565,30 @@ enable it back by calling \fBlttng enable-channel NAME\fP again.
 
 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
 file.
 
 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
 file.

-.fi

 
 .B OPTIONS:
 
 
 .B OPTIONS:
 

-.nf
-\-h, \-\-help
-        Show summary of possible options and commands.
-\-\-list-options
-        Simple listing of options
-\-s, \-\-session NAME
-        Apply on session name
-\-k, \-\-kernel
-        Apply for the kernel tracer
-\-u, \-\-userspace
-        Apply for the user-space tracer
-.fi
+.TP
+.BR "\-h, \-\-help"
+Show summary of possible options and commands.
+.TP
+.BR "\-\-list-options"
+Simple listing of options
+.TP
+.BR "\-s, \-\-session NAME"
+Apply on session name
+.TP
+.BR "\-k, \-\-kernel"
+Apply for the kernel tracer
+.TP
+.BR "\-u, \-\-userspace"
+Apply for the user-space tracer
+.RE
+.PP

 
 

-.IP "\fBdisable-event\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
-.nf
+.PP
+\fBdisable-event\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS]
+.RS

 Disable tracing event
 
 The event, once disabled, can be re-enabled by calling \fBlttng enable-event
 Disable tracing event
 
 The event, once disabled, can be re-enabled by calling \fBlttng enable-event


@@ -573,28 +596,34 @@ NAME\fP again.
 
 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
 file.
 
 If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
 file.

-.fi

 
 .B OPTIONS:
 
 
 .B OPTIONS:
 

-.nf
-\-h, \-\-help
-        Show summary of possible options and commands.
-\-\-list-options
-        Simple listing of options
-\-s, \-\-session NAME
-        Apply on session name
-\-a, \-\-all-events
-        Disable all events. This does NOT disable "*" but rather
-        every known events of the session.
-\-k, \-\-kernel
-        Apply for the kernel tracer
-\-u, \-\-userspace
-        Apply for the user-space tracer
-.fi
+.TP
+.BR "\-h, \-\-help"
+Show summary of possible options and commands.
+.TP
+.BR "\-\-list-options"
+Simple listing of options
+.TP
+.BR "\-s, \-\-session NAME"
+Apply on session name
+.TP
+.BR "\-a, \-\-all-events"
+Disable all events. This does NOT disable "*" but rather every known
+events of the session.
+.TP
+.BR "\-k, \-\-kernel"
+Apply for the kernel tracer
+.TP
+.BR "\-u, \-\-userspace"
+Apply for the user-space tracer
+.RE
+.PP

 
 

-.IP "\fBlist\fP [\-k|\-u] [SESSION [SESSION_OPTIONS]]"
-.nf
+.PP
+\fBlist\fP [OPTIONS] [SESSION [SESSION OPTIONS]]
+.RS

 List tracing session information.
 
 With no arguments, it will list available tracing session(s).
 List tracing session information.
 
 With no arguments, it will list available tracing session(s).


@@ -608,84 +637,96 @@ calls events).
 With \-u alone, it will list all available user-space events from registered
 applications. Here is an example of 'lttng list \-u':
 
 With \-u alone, it will list all available user-space events from registered
 applications. Here is an example of 'lttng list \-u':
 

+.nf

 PID: 7448 - Name: /tmp/lttng-ust/tests/hello/.libs/lt-hello
       ust_tests_hello:tptest_sighandler (type: tracepoint)
       ust_tests_hello:tptest (type: tracepoint)
 PID: 7448 - Name: /tmp/lttng-ust/tests/hello/.libs/lt-hello
       ust_tests_hello:tptest_sighandler (type: tracepoint)
       ust_tests_hello:tptest (type: tracepoint)

+.fi

 
 You can now enable any event listed by using the name :
 \fBust_tests_hello:tptest\fP.
 
 You can now enable any event listed by using the name :
 \fBust_tests_hello:tptest\fP.

-.fi

 
 .B OPTIONS:
 
 
 .B OPTIONS:
 

-.nf
-\-h, \-\-help
-        Show summary of possible options and commands.
-\-\-list-options
-        Simple listing of options
-\-k, \-\-kernel
-        Select kernel domain
-\-u, \-\-userspace
-        Select user-space domain.
+.TP
+.BR "\-h, \-\-help"
+Show summary of possible options and commands.
+.TP
+.BR "\-\-list-options"
+Simple listing of options
+.TP
+.BR "\-k, \-\-kernel"
+Select kernel domain
+.TP
+.BR "\-u, \-\-userspace"
+Select user-space domain.

 
 

+.PP

 .B SESSION OPTIONS:
 
 .B SESSION OPTIONS:
 

-\-c, \-\-channel NAME
-        List details of a channel
-\-d, \-\-domain
-        List available domain(s)
-.fi
+.TP
+.BR "\-c, \-\-channel NAME"
+List details of a channel
+.TP
+.BR "\-d, \-\-domain"
+List available domain(s)
+.RE
+.PP

 
 

-.IP "\fBset-session\fP NAME"
-.nf
+.PP
+\fBset-session\fP NAME [OPTIONS]
+.RS

 Set current session name
 
 Will change the session name in the .lttngrc file.
 Set current session name
 
 Will change the session name in the .lttngrc file.

-.fi

 
 .B OPTIONS:
 
 
 .B OPTIONS:
 

-.nf
-\-h, \-\-help
-        Show summary of possible options and commands.
-\-\-list-options
-        Simple listing of options
-.fi
-
-.IP
+.TP
+.BR "\-h, \-\-help"
+Show summary of possible options and commands.
+.TP
+.BR "\-\-list-options"
+Simple listing of options
+.RE
+.PP

 
 

-.IP "\fBsnapshot\fP ACTION"
-.nf
+.PP
+\fBsnapshot\fP [OPTIONS] ACTION
+.RS

 Snapshot command for LTTng session.
 Snapshot command for LTTng session.

-.fi

 
 .B OPTIONS:
 
 
 .B OPTIONS:
 

-.nf
-\-h, \-\-help
-        Show summary of possible options and commands.
-\-\-list-options
-        Simple listing of options
-.fi
+.TP
+.BR "\-h, \-\-help"
+Show summary of possible options and commands.
+.TP
+.BR "\-\-list-options"
+Simple listing of options

 
 

+.PP

 .B ACTION:
 
 .B ACTION:
 

-.nf
+.TP

 \fBadd-output\fP [-m <SIZE>] [-s <NAME>] [-n <NAME>] <URL> | -C <URL> -D <URL>
 
 Setup and add an snapshot output for a session. Output are the destination
 where the snapshot will be sent. Only one output is permitted. To change it,
 you'll need to delete it and add back the new one.
 
 \fBadd-output\fP [-m <SIZE>] [-s <NAME>] [-n <NAME>] <URL> | -C <URL> -D <URL>
 
 Setup and add an snapshot output for a session. Output are the destination
 where the snapshot will be sent. Only one output is permitted. To change it,
 you'll need to delete it and add back the new one.
 

+.TP

 \fBdel-output\fP ID | NAME [-s <NAME>]
 
 Delete an output for a session using the ID. You can either specify the
 output's ID that can be found with list-output or the name.
 
 \fBdel-output\fP ID | NAME [-s <NAME>]
 
 Delete an output for a session using the ID. You can either specify the
 output's ID that can be found with list-output or the name.
 

+.TP

 \fBlist-output\fP [-s <NAME>]
 
 List the output of a session. Attributes of the output are printed.
 
 \fBlist-output\fP [-s <NAME>]
 
 List the output of a session. Attributes of the output are printed.
 

+.TP

 \fBrecord\fP [-m <SIZE>] [-s <NAME>] [-n <NAME>] [<URL> | -C <URL> -D <URL>]
 
 Snapshot a session's buffer(s) for all domains. If an URL is specified, it is
 \fBrecord\fP [-m <SIZE>] [-s <NAME>] [-n <NAME>] [<URL> | -C <URL> -D <URL>]
 
 Snapshot a session's buffer(s) for all domains. If an URL is specified, it is


@@ -693,54 +734,59 @@ used instead of a previously added output. Specifying only a name or/and a max
 size will override the current output values. For instance, you can record a
 snapshot with a custom maximum size or with a different name.
 
 size will override the current output values. For instance, you can record a
 snapshot with a custom maximum size or with a different name.
 

+.nf

 $ lttng add-output -n mysnapshot file:///data/snapshot
 [...]
 $ lttng snapshot record -n new_name_snapshot
 $ lttng add-output -n mysnapshot file:///data/snapshot
 [...]
 $ lttng snapshot record -n new_name_snapshot

+.fi

 
 The above will create a snapshot in /data/snapshot/new_name_snapshot* directory
 rather then in mysnapshot*/
 
 The above will create a snapshot in /data/snapshot/new_name_snapshot* directory
 rather then in mysnapshot*/

-.fi
-
-.B LONG OPTIONS

 
 

-.nf
-\-s, \-\-session NAME
-        Apply to session name.
-\-n, \-\-name NAME
-        Name of the snapshot's output.
-\-m, \-\-max-size SIZE
-        Maximum size in bytes of the snapshot. The maxium size does not
-        include the metadata file.
-\-C, \-\-ctrl-url URL
-        Set control path URL. (Must use -D also)
-\-D, \-\-data-url URL
-        Set data path URL. (Must use -C also)
-.fi
+.PP
+.B DETAILED ACTION OPTIONS

 
 

-.IP
+.TP
+.BR "\-s, \-\-session NAME"
+Apply to session name.
+.TP
+.BR "\-n, \-\-name NAME"
+Name of the snapshot's output.
+.TP
+.BR "\-m, \-\-max-size SIZE"
+Maximum size in bytes of the snapshot. The maxium size does not include
+the metadata file.
+.TP
+.BR "\-C, \-\-ctrl-url URL"
+Set control path URL. (Must use -D also)
+.TP
+.BR "\-D, \-\-data-url URL"
+Set data path URL. (Must use -C also)
+.RE
+.PP

 
 

-.IP "\fBstart\fP [NAME] [OPTIONS]"
-.nf
+.PP
+\fBstart\fP [NAME] [OPTIONS]
+.RS

 Start tracing
 
 It will start tracing for all tracers for a specific tracing session.
 Start tracing
 
 It will start tracing for all tracers for a specific tracing session.

-

 If NAME is omitted, the session name is taken from the .lttngrc file.
 If NAME is omitted, the session name is taken from the .lttngrc file.

-.fi

 
 .B OPTIONS:
 
 
 .B OPTIONS:
 

-.nf
-\-h, \-\-help
-        Show summary of possible options and commands.
-\-\-list-options
-        Simple listing of options
-.fi
-
-.IP
+.TP
+.BR "\-h, \-\-help"
+Show summary of possible options and commands.
+.TP
+.BR "\-\-list-options"
+Simple listing of options
+.RE
+.PP

 
 

-.IP "\fBstop\fP [NAME] [OPTIONS]"
-.nf
+.PP
+\fBstop\fP [NAME] [OPTIONS]
+.RS

 Stop tracing
 
 It will stop tracing for all tracers for a specific tracing session. Before
 Stop tracing
 
 It will stop tracing for all tracers for a specific tracing session. Before


@@ -749,36 +795,35 @@ until the trace is readable for the session. Use \-\-no-wait to avoid this
 behavior.
 
 If NAME is omitted, the session name is taken from the .lttngrc file.
 behavior.
 
 If NAME is omitted, the session name is taken from the .lttngrc file.

-.fi

 
 .B OPTIONS:
 
 
 .B OPTIONS:
 

-.nf
-\-h, \-\-help
-        Show summary of possible options and commands.
-\-\-list-options
-        Simple listing of options
-\-\-no-wait
-        Don't wait for data availability.
-.fi
-
-.IP
+.TP
+.BR "\-h, \-\-help"
+Show summary of possible options and commands.
+.TP
+.BR "\-\-list-options"
+Simple listing of options
+.TP "\-\-no-wait"
+Don't wait for data availability.
+.RE
+.PP

 
 

-.IP "\fBversion\fP"
-.nf
+.PP
+\fBversion\fP
+.RS

 Show version information
 Show version information

-.fi

 
 .B OPTIONS:
 
 
 .B OPTIONS:
 

-.nf
-\-h, \-\-help
-        Show summary of possible options and commands.
-\-\-list-options
-        Simple listing of options
-.fi
-
-.IP
+.TP
+.BR "\-h, \-\-help"
+Show summary of possible options and commands.
+.TP
+.BR "\-\-list-options"
+Simple listing of options
+.RE
+.PP

 
 .IP "\fBview\fP [SESSION_NAME] [OPTIONS]"
 .nf
 
 .IP "\fBview\fP [SESSION_NAME] [OPTIONS]"
 .nf