mi: add machine interface description to man page

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

diff --git a/doc/man/lttng.1 b/doc/man/lttng.1
index d4fba11878a3fb095b0b5c14f9310bd721bba0d2..80861e905fdcefd9d296931d4f58cab240fd24d2 100644 (file)
--- a/doc/man/lttng.1
+++ b/doc/man/lttng.1
@@ -77,6 +77,26 @@ Simple listing of lttng options.
 .TP
 .BR "\-\-list\-commands"
 Simple listing of lttng commands.
 .TP
 .BR "\-\-list\-commands"
 Simple listing of lttng commands.

+.TP
+.BR "\-m, \-\-mi TYPE
+Machine interface
+
+TYPE supported: XML
+
+Machine interface (MI) mode converts the traditional pretty printing to a
+machine output syntax. MI mode provides a format change-resistant way to access
+information generated via the lttng command line.
+
+When using MI mode, the data is printed on \fBstdout\fP. Error and warning are
+printed on \fBstderr\fP with the pretty print default format.
+
+If any errors occur during the execution of a command, the return value of the
+command will be different than zero. In this case, lttng does NOT guarantee the
+syntax and data validity of the generated MI output.
+
+For XML output type, a schema definition (XSD) file used for validation can be
+found under src/common/mi_lttng.xsd
+

 .SH "COMMANDS"
 
 .PP
 .SH "COMMANDS"
 
 .PP


@@ -749,8 +769,10 @@ List available domain(s)
 Load tracing session configuration
 
 If NAME is omitted, all session configurations found in both the user's session
 Load tracing session configuration
 
 If NAME is omitted, all session configurations found in both the user's session

-configuration directory and the system session configuration directory will be
-loaded.
+configuration directory (default: ~/.lttng/sessions/) and the system session
+configuration directory (default: /etc/lttng/sessions/) will be loaded. Note
+that the sessions in the user directory are loaded first and then the system
+wide directory are loaded.

 
 .B OPTIONS:
 
 
 .B OPTIONS:
 


@@ -762,7 +784,8 @@ Show summary of possible options and commands.
 Load all session configurations (default).
 .TP
 .BR "\-i, \-\-input-path PATH"
 Load all session configurations (default).
 .TP
 .BR "\-i, \-\-input-path PATH"

-Specify the input path for session configurations.
+Specify the input path for session configurations. This overrides the default
+session configuration directory.

 .TP
 .BR "\-f, -\-force"
 Overwrite current session configuration(s) if a session of the same name
 .TP
 .BR "\-f, -\-force"
 Overwrite current session configuration(s) if a session of the same name


@@ -776,8 +799,12 @@ already exists.
 Save tracing session configuration
 
 If SESSION is omitted, all session configurations will be saved to individual
 Save tracing session configuration
 
 If SESSION is omitted, all session configurations will be saved to individual

-\fB.lttng\fP files under the user's session configuration directory. The
-default session configuration file naming scheme is \fBSESSION.lttng\fP.
+\fB.lttng\fP files under the user's session configuration directory (default:
+~/.lttng/sessions/). The default session configuration file naming scheme is
+\fBSESSION.lttng\fP.
+
+For instance, a user in the tracing group saving a session from a root session
+daemon will save it in her/his user directory.

 
 .B OPTIONS:
 
 
 .B OPTIONS:
 


@@ -789,7 +816,8 @@ Show summary of possible options and commands.
 Save all session configurations (default).
 .TP
 .BR "\-o, \-\-output-path PATH"
 Save all session configurations (default).
 .TP
 .BR "\-o, \-\-output-path PATH"

-Specify the output path for saved sessions (default: ~/.lttng/sessions/).
+Specify the output path for saved sessions. This overrides the default session
+configuration directory.

 .TP
 .BR "\-f, -\-force"
 Overwrite session configuration file if session name clashes.
 .TP
 .BR "\-f, -\-force"
 Overwrite session configuration file if session name clashes.