/tests/regression/tools/live/live_test
/tests/unit/ini_config/ini_config
+# man pages
+/doc/man/*.1
+/doc/man/*.3
+/doc/man/*.8
+/doc/man/*.xml
+/doc/man/*.html
+!/doc/man/lttng-crash.1
+!/doc/man/lttng-health-check.3
+!/doc/man/lttng-relayd.8
+!/doc/man/lttng-sessiond.8
+
/benchmark/
/include/version.h
LTTng-tools
===========
+[](https://ci.lttng.org/job/lttng-tools_master_build/)
+[](https://scan.coverity.com/projects/lttng-tools)
+
LTTng-tools is a set of tools to control [LTTng](https://lttng.org/)
tracing. The project includes the LTTng session daemon, consumer damon
and relay daemon, as well as `liblttng-ctl`, a C library used to
- **modprobe**: needed for automatic LTTng kernel modules loading
(kernel tracing).
- **bash**: needed for running `make check`.
+ - **man** (manual pager): needed to view LTTng-tools commands' man
+ pages with the `--help` option or with the `lttng help` command.
+ Note that without `man`, you cannot get offline help with
+ LTTng-tools commands, not even their usage.
LTTng-tools supports both the [LTTng Linux Kernel tracer](https://lttng.org)
and [LTTng user space tracer](https://lttng.org) released as part of the same
portability. Here are some things you should have on your system in
order to compile the Git repository tree:
- - GNU Autotools (Automake >= 1.10, Autoconf >= 2.64,
- Autoheader >= 2.50; make sure your system-wide `automake` points to
- a recent version!)
- - [GNU Libtool](http://www.gnu.org/software/autoconf/) >= 2.2
- - Flex >= 2.5.35
- - Bison >= 2.4
+ - **GNU Autotools** (**Automake >= 1.10**, **Autoconf >= 2.64**,
+ **Autoheader >= 2.50**; make sure your system-wide `automake` points
+ to a recent version!)
+ - **[GNU Libtool](http://www.gnu.org/software/autoconf/) >= 2.2**
+ - **Flex >= 2.5.35**
+ - **Bison >= 2.4**
+
+Optional packages to build LTTng-tools man pages:
+
+ - **AsciiDoc >= 8.4.5** (previous versions may work, but were
+ not tested)
+ - **xmlto >= 0.0.21** (previous versions may work, but were
+ not tested)
If you use GNU gold, which is _not_ mandatory, make sure you have this
version:
- - GNU gold >= 2.22
+ - **GNU gold >= 2.22**
Before this version of GNU gold, we hit a
[known bug](http://sourceware.org/bugzilla/show_bug.cgi?id=11317).
- `include`: the public header files that will be installed on the system.
- `src/bin`: source code of LTTng-tools programs.
- `lttng-consumerd`: consumer daemon.
+ - `lttng-crash`: crash trace viewer.
- `lttng-relayd`: relay daemon.
- `lttng-sessiond`: session daemon.
- `lttng`: command line interface for LTTng tracing control.
AC_PREREQ([2.64])
-AC_INIT([lttng-tools],[2.8.0-pre],[jeremie.galarneau@efficios.com],[],[https://lttng.org])
+AC_INIT([lttng-tools],[2.9.0-pre],[jeremie.galarneau@efficios.com],[],[https://lttng.org])
AC_CONFIG_HEADERS([include/config.h])
AC_CONFIG_AUX_DIR([config])
AC_PROG_MAKE_SET
AC_PROG_SED
AC_PROG_YACC
+AC_PATH_PROG(report_fold, fold)
LT_INIT
# Check for objcopy, required by the base address statedump and dynamic linker tests
major_version=$(echo AC_PACKAGE_VERSION | $SED 's/^\([[0-9]]\)*\.[[0-9]]*\.[[0-9]]*.*$/\1/')
minor_version=$(echo AC_PACKAGE_VERSION | $SED 's/^[[0-9]]*\.\([[0-9]]*\)\.[[0-9]]*.*$/\1/')
patchlevel_version=$(echo AC_PACKAGE_VERSION | $SED 's/^[[0-9]]*\.[[0-9]]*\.\([[0-9]]*\).*$/\1/')
+
AC_SUBST([MAJOR_VERSION], [$major_version])
AC_SUBST([MINOR_VERSION], [$minor_version])
AC_SUBST([PATCHLEVEL_VERSION], [$patchlevel_version])
AC_DEFINE_UNQUOTED([VERSION_MINOR], $minor_version, [LTTng-Tools minor version number])
AC_DEFINE_UNQUOTED([VERSION_PATCHLEVEL], $patchlevel_version, [LTTng-Tools patchlevel version number])
-version_name="Herbe à Détourne"
-version_description='Brewed with unrestrained amounts of Citra hop, the Herbe à Détourne is a fantastic New World Tripel brewed by "Dieu du Ciel!". Aromas of mango, cantaloupe melon and passion fruit, combined with a controlled bitter finish, unite in making this smooth golden-orange beer stand apart.'
+version_name="Codename TBD"
+version_description='Description TBD'
version_description_c=$(echo $version_description | $SED 's/"/\\"/g')
AC_DEFINE_UNQUOTED([VERSION_NAME], ["$version_name"], "")
gethostbyname gethostname getpagesize localtime_r memchr memset \
mkdir munmap putenv realpath rmdir socket strchr strcspn strdup \
strncasecmp strndup strnlen strpbrk strrchr strstr strtol strtoul \
- strtoull dirfd gethostbyname2 getipnodebyname \
+ strtoull dirfd gethostbyname2 getipnodebyname epoll_create1 \
])
# Babeltrace viewer check
fi
fi
+# set $IN_GIT_REPO if we're in the Git repository; the `bootstrap` file
+# is not distributed in tarballs
+AS_IF([test -f "$srcdir/bootstrap"], [in_git_repo=yes], [in_git_repo=no])
+AM_CONDITIONAL([IN_GIT_REPO], [test "x$in_git_repo" = "xyes"])
+
+# enable building man pages
+AC_ARG_ENABLE(
+ build-man-pages,
+ AS_HELP_STRING(
+ [--enable-build-man-pages],
+ [Build man pages (already built in a distributed tarball)]
+ ),
+ [enable_build_man_pages=yes],
+ [enable_build_man_pages=no]
+)
+
+# export man page build condition
+AM_CONDITIONAL([BUILD_MAN_PAGES], [test "x$enable_build_man_pages" != "xno"])
+
+# check for asciidoc and xmlto if we enabled building the man pages
+AS_IF([test "x$enable_build_man_pages" = "xyes"], [
+ AC_PATH_PROG([ASCIIDOC], [asciidoc], [no])
+ AC_PATH_PROG([XMLTO], [xmlto], [no])
+
+ AS_IF([test "x$ASCIIDOC" = "xno" || test "x$XMLTO" = "xno"], [
+ AC_MSG_ERROR([Both asciidoc and xmlto are needed to build the LTTng man pages.])
+ ])
+])
+
# Python agent test
UST_PYTHON_AGENT="lttngust"
#
# Mini-report on what will be built.
#
-AS_ECHO()
-AS_ECHO("Version name: $version_name")
-AS_ECHO("$version_description")
+PPRINT_INIT
+PPRINT_SET_INDENT(1)
+PPRINT_SET_TS(38)
+
+AS_ECHO
+AS_ECHO("${PPRINT_COLOR_BLDBLU}LTTng-tools $PACKAGE_VERSION \"$version_name\"$PPRINT_COLOR_RST")
+AS_ECHO
-AS_ECHO()
+AS_IF([test -n "$report_fold"], [
+ AS_ECHO("`AS_ECHO("$version_description") | $report_fold -s`")
+], [
+ AS_ECHO("$version_description")
+])
+
+AS_ECHO
+PPRINT_SUBTITLE([Features])
# Target architecture we're building for.
target_arch=$host_cpu
fi
done
]
-AS_ECHO_N("Target architecture: ")
-AS_ECHO($target_arch)
+PPRINT_PROP_STRING([Target architecture], $target_arch)
# kmod enabled/disabled
-AS_ECHO_N("libkmod support: ")
-AS_IF([test "x$kmod_found" = "xyes"],[
- AS_ECHO("Enabled")
-],[
- AS_ECHO("Disabled")
-])
+test "x$kmod_found" = "xyes" && value=1 || value=0
+PPRINT_PROP_BOOL([libkmod support], $value)
# LTTng-UST enabled/disabled
-AS_ECHO_N("Lttng-UST support: ")
-AS_IF([test "x$lttng_ust_support" = "xyes"],[
- AS_ECHO("Enabled")
-],[
- AS_ECHO("Disabled")
-])
+test "x$lttng_ust_support" = "xyes" && value=1 || value=0
+PPRINT_PROP_BOOL([LTTng-UST support], $value)
-AS_ECHO()
-AS_ECHO("Binaries:")
+AS_ECHO
+PPRINT_SUBTITLE([Binaries])
# List binaries to be built
-AS_ECHO_N("lttng: ")
-AS_IF([test x$enable_bin_lttng != xno],[
- AS_ECHO("Enabled")
-],[
- AS_ECHO("Disabled")
-])
-
-AS_ECHO_N("lttng-consumerd: ")
-AS_IF([test x$enable_bin_lttng_consumerd != xno],[
- AS_ECHO("Enabled")
-],[
- AS_ECHO("Disabled")
-])
-
-AS_ECHO_N("lttng-crash: ")
-AS_IF([test x$enable_bin_lttng_crash != xno],[
- AS_ECHO("Enabled")
-],[
- AS_ECHO("Disabled")
-])
+test x$enable_bin_lttng != xno && value=1 || value=0
+PPRINT_PROP_BOOL([lttng], $value)
-AS_ECHO_N("lttng-relayd: ")
-AS_IF([test x$enable_bin_lttng_relayd != xno],[
- AS_ECHO("Enabled")
-],[
- AS_ECHO("Disabled")
-])
+test x$enable_bin_lttng_consumerd != xno && value=1 || value=0
+PPRINT_PROP_BOOL([lttng-consumerd], $value)
-AS_ECHO_N("lttng-sessiond: ")
-AS_IF([test x$enable_bin_lttng_sessiond != xno],[
- AS_ECHO("Enabled")
-],[
- AS_ECHO("Disabled")
-])
+test x$enable_bin_lttng_crash != xno && value=1 || value=0
+PPRINT_PROP_BOOL([lttng-crash], $value)
-AS_ECHO_N("Extras: ")
-AS_IF([test x$enable_extras != xno],[
- AS_ECHO("Enabled")
-],[
- AS_ECHO("Disabled")
-])
+test x$enable_bin_lttng_relayd != xno && value=1 || value=0
+PPRINT_PROP_BOOL([lttng-relayd], $value)
-# Print the bindir and libdir this `make install' will install into.
-AS_ECHO()
-AS_ECHO_N("Binaries will be installed in: ")
-AS_ECHO("`eval eval echo $bindir`")
-AS_ECHO_N("Libraries will be installed in: ")
-AS_ECHO("`eval eval echo $libdir`")
+test x$enable_bin_lttng_sessiond != xno && value=1 || value=0
+PPRINT_PROP_BOOL([lttng-sessiond], $value)
+# Extras
+test x$enable_extras != xno && value=1 || value=0
+AS_ECHO
+PPRINT_SET_INDENT(0)
+PPRINT_PROP_BOOL([Extras], $value, $PPRINT_COLOR_SUBTITLE)
+PPRINT_SET_INDENT(1)
-AS_ECHO()
+AS_ECHO
+PPRINT_SUBTITLE([Tests])
# Print clear message that tests won't be built
AS_IF([test "x$build_tests" = "xno"],[
- AS_ECHO("WARNING: Tests won't be built since some binaries were disabled")
+ PPRINT_WARN([Tests won't be built since some binaries were disabled])
])
-AS_ECHO("Tests:")
-
# LTTng UST Java agent JUL tests enabled/disabled
-AS_ECHO_N("LTTng-UST Java agent JUL tests: ")
-AS_IF([test "x$test_java_agent_jul" = "xyes"],[
- AS_ECHO("Enabled")
-],[
- AS_ECHO("Disabled")
-])
+test "x$test_java_agent_jul" = "xyes" && value=1 || value=0
+PPRINT_PROP_BOOL([LTTng-UST Java agent JUL tests], $value)
# LTTng UST Java agent Log4j tests enabled/disabled
-AS_ECHO_N("LTTng-UST Java agent Log4j tests: ")
-AS_IF([test "x$test_java_agent_log4j" = "xyes"],[
- AS_ECHO("Enabled")
-],[
- AS_ECHO("Disabled")
-])
+test "x$test_java_agent_log4j" = "xyes" && value=1 || value=0
+PPRINT_PROP_BOOL([LTTng-UST Java agent Log4j tests], $value)
-AS_ECHO_N("LTTng-UST Python2 agent tests: ")
-AS_IF([test ! -z "$PYTHON2_AGENT"],[
- AS_ECHO("Enabled")
-],[
- AS_ECHO("Disabled")
-])
+test ! -z "$PYTHON2_AGENT" && value=1 || value=0
+PPRINT_PROP_BOOL([LTTng-UST Python2 agent tests], $value)
-AS_ECHO_N("LTTng-UST Python3 agent tests: ")
-AS_IF([test ! -z "$PYTHON3_AGENT"],[
- AS_ECHO("Enabled")
-],[
- AS_ECHO("Disabled")
-])
+test ! -z "$PYTHON3_AGENT" && value=1 || value=0
+PPRINT_PROP_BOOL([LTTng-UST Python3 agent tests], $value)
#Python binding enabled/disabled
-AS_ECHO_N("Python binding: ")
-AS_IF([test "x${enable_python_binding:-yes}" = xyes], [
- AS_ECHO("Enabled")
-],[
- AS_ECHO("Disabled")
+test "x${enable_python_binding:-yes}" = xyes && value=1 || value=0
+AS_ECHO
+PPRINT_SET_INDENT(0)
+PPRINT_PROP_BOOL([Python binding], $value, $PPRINT_COLOR_SUBTITLE)
+PPRINT_SET_INDENT(1)
+
+AS_ECHO
+PPRINT_SUBTITLE([Man pages])
+
+# man pages build enabled/disabled
+test "x$enable_build_man_pages" = "xyes" && value=1 || value=0
+AS_IF([test "x$enable_build_man_pages" = "xyes"], [
+ PPRINT_PROP_BOOL([Build man pages], 1)
+], [
+ AS_IF([test "x$in_git_repo" = "xyes"], [
+ PPRINT_PROP_BOOL([Build man pages], 0)
+ ], [
+ PPRINT_PROP_STRING([Build man pages], [${PPRINT_COLOR_BLDGRN}Already built])
+ ])
])
+# man pages install enabled/disabled (always true in tarball)
+test "x$enable_build_man_pages" = "xno" && test "x$in_git_repo" = "xyes" && value=0 || value=1
+PPRINT_PROP_BOOL([Install man pages], $value)
+
+report_bindir="`eval eval echo $bindir`"
+report_libdir="`eval eval echo $libdir`"
+
+# Print the bindir and libdir this `make install' will install into.
+AS_ECHO
+PPRINT_SUBTITLE([Install directories])
+PPRINT_PROP_STRING([Binaries], [$report_bindir])
+PPRINT_PROP_STRING([Libraries], [$report_libdir])
+
+AS_ECHO
+PPRINT_SUBTITLE([Search directories])
+
# If we build the sessiond, print the paths it will use
-AS_ECHO()
-AS_ECHO_N("The lttng command will search for the lttng-sessiond executable at: ")
AS_IF([test "$SESSIOND_BIN" = ""],[
- AS_ECHO_N("`eval eval echo $bindir`")
- AS_ECHO("/lttng-sessiond")
+ path="$report_bindir/lttng-sessiond"
],[
- AS_ECHO("$SESSIOND_BIN")
+ path="$SESSIOND_BIN"
])
+PPRINT_PROP_STRING([lttng-sessiond executable], [$path])
-AS_ECHO()
-AS_ECHO("The sessiond daemon will search the following directories: ")
-AS_ECHO_N("32-bit consumerd executable: ")
AS_IF([test "$CONSUMERD32_BIN" = ""],[
- AS_ECHO_N("`eval eval echo $lttnglibexecdir`")
- AS_ECHO("/lttng-consumerd")
+ path="`eval eval echo $lttnglibexecdir`/lttng-consumerd"
],[
- AS_ECHO("$CONSUMERD32_BIN")
+ path="$CONSUMERD32_BIN"
])
+PPRINT_PROP_STRING([32-bit lttng-consumerd executable], [$path])
-AS_ECHO_N("32-bit consumer libraries: ")
AS_IF([test "$CONSUMERD32_LIBDIR" = ""],[
- AS_ECHO("`eval eval echo $libdir`")
+ path="`eval eval echo $libdir`"
],[
- AS_ECHO("$CONSUMERD32_LIBDIR")
+ path="$CONSUMERD32_LIBDIR"
])
+PPRINT_PROP_STRING([32-bit consumer libraries], [$path])
-AS_ECHO_N("64-bit consumerd executable: ")
AS_IF([test "$CONSUMERD64_BIN" = ""],[
- AS_ECHO_N("`eval eval echo $lttnglibexecdir`")
- AS_ECHO("/lttng-consumerd")
+ path="`eval eval echo $lttnglibexecdir`/lttng-consumerd"
],[
- AS_ECHO("$CONSUMERD64_BIN")
+ path="$CONSUMERD64_BIN"
])
+PPRINT_PROP_STRING([64-bit lttng-consumerd executable], [$path])
-AS_ECHO_N("64-bit consumer libraries: ")
AS_IF([test "$CONSUMERD64_LIBDIR" = ""],[
- AS_ECHO("`eval eval echo $libdir`")
+ path="`eval eval echo $libdir`"
],[
- AS_ECHO("$CONSUMERD64_LIBDIR")
+ path="$CONSUMERD64_LIBDIR"
])
-
-AS_ECHO()
-
+PPRINT_PROP_STRING([64-bit consumer libraries], [$path])
-dist_man1_MANS = lttng.1 lttng-crash.1
-dist_man8_MANS = lttng-sessiond.8 lttng-relayd.8
+# Man pages are only built if the --enable-build-man-pages option was passed
+# to the configure script.
+#
+# They should always be built before creating a distribution tarball.
+
+# function which adds the source directory prefix and adds a given suffix
+manaddsuffix = $(addsuffix $(1),$(addprefix $(srcdir)/,$(2)))
+
+# List only the names without the .*.txt extension here:
+MAN1_NAMES = \
+ lttng \
+ lttng-create \
+ lttng-destroy \
+ lttng-set-session \
+ lttng-save \
+ lttng-load \
+ lttng-start \
+ lttng-stop \
+ lttng-version \
+ lttng-view \
+ lttng-enable-channel \
+ lttng-disable-channel \
+ lttng-add-context \
+ lttng-list \
+ lttng-calibrate \
+ lttng-track \
+ lttng-untrack \
+ lttng-status \
+ lttng-help \
+ lttng-snapshot \
+ lttng-enable-event \
+ lttng-disable-event \
+ lttng-crash \
+ lttng-metadata
+MAN3_NAMES =
+MAN8_NAMES = lttng-sessiond lttng-relayd
+MAN1_NO_ASCIIDOC_NAMES =
+MAN3_NO_ASCIIDOC_NAMES = lttng-health-check
+MAN8_NO_ASCIIDOC_NAMES =
+
+# man pages destinations
+MAN1 = $(call manaddsuffix,.1,$(MAN1_NAMES))
+MAN3 = $(call manaddsuffix,.3,$(MAN3_NAMES))
+MAN8 = $(call manaddsuffix,.8,$(MAN8_NAMES))
+MAN1_NO_ASCIIDOC = $(call manaddsuffix,.1,$(MAN1_NO_ASCIIDOC_NAMES))
+MAN3_NO_ASCIIDOC = $(call manaddsuffix,.3,$(MAN3_NO_ASCIIDOC_NAMES))
+MAN8_NO_ASCIIDOC = $(call manaddsuffix,.8,$(MAN8_NO_ASCIIDOC_NAMES))
+MAN = $(MAN1) $(MAN3) $(MAN8)
+
+# those are always installed since they are written in troff
+dist_man1_MANS = $(MAN1_NO_ASCIIDOC)
+dist_man3_MANS = $(MAN3_NO_ASCIIDOC)
+dist_man8_MANS = $(MAN8_NO_ASCIIDOC)
+
+# only build man pages if it was enabled
+if BUILD_MAN_PAGES
+# dist + install
+dist_man1_MANS += $(MAN1)
+dist_man3_MANS += $(MAN3)
+dist_man8_MANS += $(MAN8)
+
+# AsciiDoc sources and outputs
+MAN1_TXT = $(call manaddsuffix,.1.txt,$(MAN1_NAMES))
+MAN3_TXT = $(call manaddsuffix,.3.txt,$(MAN3_NAMES))
+MAN8_TXT = $(call manaddsuffix,.8.txt,$(MAN8_NAMES))
+MAN_TXT = $(MAN1_TXT) $(MAN3_TXT) $(MAN8_TXT)
+MAN_XML = $(patsubst $(srcdir)/%.txt,%.xml,$(MAN_TXT))
+
+# common AsciiDoc source files
+COMMON_TXT = \
+ $(srcdir)/common-footer.txt \
+ $(srcdir)/common-cmd-footer.txt \
+ $(srcdir)/common-cmd-options-head.txt \
+ $(srcdir)/common-cmd-help-options.txt
+
+# config
+ASCIIDOC_CONF = $(srcdir)/asciidoc.conf
+XSL_FILES = \
+ manpage.xsl \
+ manpage-base.xsl \
+ manpage-bold-literal.xsl \
+ manpage-ulinks.xsl
+XSL_SRC_FILES = $(addprefix $(srcdir)/xsl/,$(XSL_FILES))
+
+# common dependencies
+COMMON_DEPS = $(ASCIIDOC_CONF) $(COMMON_TXT)
+
+# tools
+ADOC = $(ASCIIDOC) -f $(ASCIIDOC_CONF) -d manpage \
+ -a lttng_version=$(PACKAGE_VERSION)
+ADOC_DOCBOOK = $(ADOC) -b docbook
+XTO = $(XMLTO) -m $(firstword $(XSL_SRC_FILES)) man
+
+# recipes
+%.1.xml: $(srcdir)/%.1.txt $(COMMON_DEPS)
+ $(ADOC_DOCBOOK) -o $@ $<
+
+%.1: %.1.xml $(XSL_SRC_FILES)
+ $(XTO) $<
+
+%.3.xml: $(srcdir)/%.3.txt $(COMMON_DEPS)
+ $(ADOC_DOCBOOK) -o $@ $<
+
+%.3: %.3.xml $(XSL_SRC_FILES)
+ $(XTO) $<
+
+%.8.xml: $(srcdir)/%.8.txt $(COMMON_DEPS)
+ $(ADOC_DOCBOOK) -o $@ $<
+
+%.8: %.8.xml $(XSL_SRC_FILES)
+ $(XTO) $<
+
+clean-local:
+ rm -rf $(MAN_XML)
+ rm -rf $(MAN)
+else
+if IN_GIT_REPO
+# we are in the Git repo: the man pages should be built for distribution
+dist-hook:
+ @echo
+ @echo 'Error: Please build the man pages before creating a tarball.'
+ @echo
+ @false
+else
+# we are in the tarball, hence the man pages are already built
+dist_man1_MANS += $(MAN1)
+dist_man3_MANS += $(MAN3)
+dist_man8_MANS += $(MAN8)
+endif # IN_GIT_REPO
+endif # BUILD_MAN_PAGES
--- /dev/null
+LTTng-tools man pages
+=====================
+
+This directory contains the sources of the LTTng-tools man pages.
+
+LTTng-tools man pages are written in
+[AsciiDoc](http://www.methods.co.nz/asciidoc/), and then converted to
+DocBook (XML) using the `asciidoc` command, and finally to troff using
+the appropriate DocBook XSL stylesheet (using the `xmlto` command).
+
+
+Custom XSL stylesheets
+----------------------
+
+There are a few custom XSL stylesheets applied for customizing the
+generated man pages in the `xsl` directory.
+
+
+Macros
+------
+
+AsciiDoc is configured with `asciidoc.conf` which contains a few
+macro definitions used everywhere in the man page sources.
+
+
+### linklttng
+
+The linklttng macro is used to link to another LTTng man page. Its
+output is different depending on the back-end. In troff, the man page
+name is rendered in bold, whereas the HTML5 output renders a hyperlink.
+
+Usage example: `linklttng:lttng-enable-channel(1)`.
+
+
+### option
+
+The option macro is used to write a command-line option.
+
+Usage example: `option:--no-output`, `option:--loglevel=TRACE_WARNING`
+
+
+### not
+
+The `:not:` macro is used to emphasize on _not_.
+
+
+Includes
+--------
+
+ * `common-cmd-footer.txt`: common `lttng` command footer.
+ * `common-cmd-help-options.txt`: common program information section
+ of `lttng` command options.
+ * `common-cmd-options-head.txt`: common `lttng` command head of
+ options section.
+ * `common-footer.txt`: common footer for all commands.
+
+
+Convention
+----------
+
+Please follow those rules when updating the current man pages or
+writing new ones:
+
+ * Always use macros when possible (link to other LTTng man page,
+ command-line option, NOT, etc.).
+ * Use callouts for command-line examples.
+ * Always refer to _long_ options in the text.
+ * Use the `option:--option=parameter` format (with `=`) when providing
+ a parameter to long options.
+ * Write _user space_, not _userspace_ nor _user-space_.
+ (neither _user land_).
+ * Write _file system_, not _filesystem_.
+ * Write _use case_, not _use-case_ nor _usecase_.
+ * Write _log level_, not _loglevel_.
+ * Write complete LTTng project names: _LTTng-modules_, _LTTng-UST_ and
+ _LTTng-tools_, not _modules_, _UST_ and _tools_.
+ * Prefer simple emphasis to strong emphasis for emphasizing text.
+ * Try to stay behind the 72th column mark if possible, and behind
+ the 80th column otherwise.
+ * Do not end directory paths with a forward slash
+ (good: `include/trace/events`, bad: `include/trace/events/`).
+ * Minimize the use of the future tense (_will_).
+ * Do not use Latin abbreviations (_e.g._, _i.e._, _etc._).
--- /dev/null
+[macros]
+
+# linklttng macro
+#
+# Inspired by linkgit macro:
+# <https://github.com/git/git/blob/master/Documentation/asciidoc.conf>
+#
+# Usage: linklttng:command(manpage-section)
+(?su)[\\]?(?P<name>linklttng):(?P<target>\S*?)\((?P<attrlist>.*?)\)=
+
+# option macro
+#
+# Usage: option:--option-name
+(?su)[\\]?(?P<name>option):(?P<opt>--?[a-zA-Z0-9-]*)=
+
+# not macro
+#
+# Usage: :not:
+:not:=not
+
+# linklttng macro expansions
+ifdef::backend-docbook[]
+[linklttng-inlinemacro]
+{0%{target}}
+{0#<citerefentry>}
+{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
+{0#</citerefentry>}
+endif::backend-docbook[]
+
+# option macro expansions
+ifdef::backend-docbook[]
+[option-inlinemacro]
+<literal>{opt}</literal>
+endif::backend-docbook[]
+
+# not macro expansions
+ifdef::backend-docbook[]
+[not-inlinemacro]
+NOT
+endif::backend-docbook[]
+
+# configure XML man page header
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">LTTng</refmiscinfo>
+<refmiscinfo class="version">{lttng_version}</refmiscinfo>
+<refmiscinfo class="manual">LTTng Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+ <refname>{manname}</refname>
+ <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
--- /dev/null
+ENVIRONMENT VARIABLES
+---------------------
+`LTTNG_HOME`::
+ Overrides the `$HOME` environment variable. Useful when the user
+ running the commands has a non-writable home directory.
+
+`LTTNG_MAN_BIN_PATH`::
+ Absolute path to the man pager to use for viewing help information
+ about LTTng commands (using linklttng:lttng-help(1) or
+ `lttng COMMAND --help`).
+
+`LTTNG_SESSION_CONFIG_XSD_PATH`::
+ Path in which the `session.xsd` session configuration XML
+ schema may be found.
+
+`LTTNG_SESSIOND_PATH`::
+ Full session daemon binary path.
++
+The option:--sessiond-path option has precedence over this
+environment variable.
+
+Note that the linklttng:lttng-create(1) command can spawn an LTTng
+session daemon automatically if none is running. See
+linklttng:lttng-sessiond(8) for the environment variables influencing
+the execution of the session daemon.
+
+
+EXIT STATUS
+-----------
+*0*::
+ Success
+
+*1*::
+ Command error
+
+*2*::
+ Undefined command
+
+*3*::
+ Fatal error
+
+*4*::
+ Command warning (something went wrong during the command)
+
+
+include::common-footer.txt[]
--- /dev/null
+Program information
+~~~~~~~~~~~~~~~~~~~
+option:-h, option:--help::
+ Show command help.
++
+This option, like linklttng:lttng-help(1), attempts to launch
+`/usr/bin/man` to view the command's man page. The path to the man pager
+can be overridden by the `LTTNG_MAN_BIN_PATH` environment variable.
+
+option:--list-options::
+ List available command options.
--- /dev/null
+OPTIONS
+-------
+General options are described in linklttng:lttng(1).
--- /dev/null
+BUGS
+----
+If you encounter any issue or usability problem, please report it on the
+LTTng bug tracker: *<https://bugs.lttng.org/projects/lttng-tools>*.
+
+
+RESOURCES
+---------
+LTTng project website: *<http://lttng.org>*.
+
+LTTng documentation: *<http://lttng.org/docs>*.
+
+Git repositories: *<http://git.lttng.org>*.
+
+http://lists.lttng.org[Mailing list] for support and
+development: `lttng-dev@lists.lttng.org`.
+
+IRC channel: `#lttng` on `irc.oftc.net` (http://www.oftc.net/[OFTC]).
+
+
+COPYRIGHTS
+----------
+This program is part of the LTTng-tools project.
+
+LTTng-tools is distributed under the
+http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html[GNU General
+Public License version 2]. See the
+https://github.com/lttng/lttng-tools/blob/master/LICENSE[`LICENSE`] file
+for details.
+
+
+THANKS
+------
+Special thanks to Michel Dagenais and the
+http://www.dorsal.polymtl.ca/[DORSAL laboratory] at École Polytechnique
+de Montréal for the LTTng journey.
+
+Also thanks to the Ericsson teams working on tracing which helped us
+greatly with detailed bug reports and unusual test cases.
+
+
+AUTHORS
+-------
+LTTng-tools was originally written by Mathieu Desnoyers,
+Julien Desfossez, and David Goulet. More people have since
+contributed to it.
+
+LTTng-tools is currently maintained by
+Jérémie Galarneau
+(*mailto:jeremie.galarneau@efficios.com[jeremie.galarneau@efficios.com]*).
--- /dev/null
+lttng-add-context(1)
+====================
+
+
+NAME
+----
+lttng-add-context - Add context fields to an LTTng channel
+
+
+SYNOPSIS
+--------
+Add context fields to a channel:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *add-context*
+ (option:--kernel | option:--userspace | option:--jul | option:--log4j)
+ [option:--session='SESSION'] [option:--channel='CHANNEL']
+ option:--type='TYPE' [option:--type='TYPE']...
+
+List the available context fields:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *add-context* --list
+
+
+DESCRIPTION
+-----------
+The `lttng add-context` command adds one or more context fields to a
+channel.
+
+Channels are created with the linklttng:lttng-enable-channel(1) command.
+
+When context fields are added to a channel, all the events emitted
+within this channel contain the dynamic values of those context fields.
+
+If the option:--session option is omitted, the current tracing session
+is used. If the option:--channel option is omitted, the context fields
+are added to all the selected tracing session's channels.
+
+Many context fields can be added to a channel at once by repeating the
+option:--type option.
+
+perf counters are available as per-CPU (`perf:cpu:` prefix) as well as
+per-thread (`perf:thread:` prefix) counters. Currently, per-CPU counters
+can only be used in the Linux kernel tracing domain, while per-thread
+counters can only be used in the user space tracing domain.
+
+Application-specific context fields can be added to a channel using the
+following syntax:
+
+[verse]
+$app.'PROVIDER':__TYPE__
+
+with:
+
+'PROVIDER'::
+ Provider name.
+
+'TYPE'::
+ Context type name.
+
+Use the option:--list option without other arguments to list the
+available context field names.
+
+
+include::common-cmd-options-head.txt[]
+
+
+Domain
+~~~~~~
+One of:
+
+option:-j, option:--jul::
+ Add context to channel in the `java.util.logging` (JUL) domain.
+
+option:-k, option:--kernel::
+ Add context to channel in the Linux kernel domain.
+
+option:-l, option:--log4j::
+ Add context to channel in the Apache log4j domain.
+
+option:-u, option:--userspace::
+ Add context to channel in the user space domain.
+
+
+Target
+~~~~~~
+option:-c, option:--channel='CHANNEL'::
+ Add context fields to a channel named 'CHANNEL' instead of adding
+ them to all the channels.
+
+option:-s, option:--session='SESSION'::
+ Add context fields to a channel in the tracing session named 'SESSION'
+ instead of the current tracing session.
+
+
+Context
+~~~~~~~
+option:--list::
+ List the available context fields. Use this option alone.
+
+option:-t, option:--type='TYPE'::
+ Add context field named 'TYPE'. This option can be repeated as
+ many times as needed on the command-line.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng(1)
--- /dev/null
+lttng-calibrate(1)
+==================
+
+
+NAME
+----
+lttng-calibrate - Quantify LTTng overhead
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *calibrate*
+
+
+DESCRIPTION
+-----------
+The `lttng calibrate` commands quantifies the overhead of LTTng tracers.
+
+The `lttng calibrate` command can be used to find out the combined
+average overhead of the LTTng tracers and the instrumentation mechanisms
+used. This overhead can be calibrated in terms of time or using any of
+the PMU performance counter available on the system.
+
+For now, the only implemented calibration is the Linux kernel function
+instrumentation (_kretprobes_).
+
+
+Calibrate Linux kernel function instrumentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As an example, we use an i7 processor with 4 general-purpose PMU
+registers. This information is available by issuing `dmesg`, looking
+for `generic registers`.
+
+The following sequence of commands gathers a trace executing a kretprobe
+hooked on an empty function, gathering PMU counters LLC
+(Last Level Cache) misses information (use `lttng add-context --list` to
+get the list of available PMU counters).
+
+------------------------------------------------------------------------
+lttng create calibrate-function
+lttng enable-event calibrate --kernel \
+ --function=lttng_calibrate_kretprobe
+lttng add-context --kernel --type=perf:cpu:LLC-load-misses \
+ --type=perf:cpu:LLC-store-misses \
+ --type=perf:cpu:LLC-prefetch-misses
+lttng start
+
+for a in $(seq 1 10); do
+ lttng calibrate --kernel --function
+done
+
+lttng destroy
+babeltrace $(ls -1drt ~/lttng-traces/calibrate-function-* | tail -n 1)
+------------------------------------------------------------------------
+
+The output from linklttng:babeltrace(1) can be saved to a text file and
+opened in a spreadsheet (for example, in LibreOffice) to focus on the
+per-PMU counter delta between consecutive `calibrate_entry` and
+`calibrate_return` events. Note that these counters are per-CPU, so
+scheduling events would need to be present to account for migration
+between CPUs. Therefore, for calibration purposes, only events staying
+on the same CPU must be considered.
+
+Here's an example of the average result, for the i7, on 10 samples:
+
+[width="40%",options="header"]
+|=============================================================
+| PMU counter | Average | Standard deviation
+| `perf_LLC_load_misses` | 5.0 | 0.577
+| `perf_LLC_store_misses` | 1.6 | 0.516
+| `perf_LLC_prefetch_misses` | 9.0 | 14.742
+|=============================================================
+
+As we can notice, the load and store misses are relatively stable across
+runs (their standard deviation is relatively low) compared to the
+prefetch misses. We could conclude from this information that LLC load
+and store misses can be accounted for quite precisely, but prefetches
+within a function seems to behave too erratically (not much causality
+link between the code executed and the CPU prefetch activity) to be
+accounted for.
+
+
+include::common-cmd-options-head.txt[]
+
+
+Domain
+~~~~~~
+One of:
+
+option:-k, option:--kernel::
+ Quantify LTTng overhead in the Linux kernel domain.
+
+option:-u, option:--userspace::
+ Quantify LTTng overhead in the user space domain.
+
+
+Calibration
+~~~~~~~~~~~
+option:--function::
+ Use dynamic function entry/return probes to calibrate (default).
++
+This option requires the option:--kernel option.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng(1)
+++ /dev/null
-.TH "LTTNG-CRASH" "1" "March 26th, 2015" "" ""
-
-.SH "NAME"
-lttng-crash \- LTTng Crash Trace Viewer
-
-.SH "SYNOPSIS"
-
-.PP
-lttng-crash [OPTIONS] FILE
-.SH "DESCRIPTION"
-
-.PP
-The LTTng project aims at providing highly efficient tracing tools for Linux.
-Its tracers help track down performance issues and debug problems involving
-multiple concurrent processes and threads. Tracing across multiple systems
-is also possible.
-
-The \fBlttng-crash\fP command line tool, part of the lttng-tools package, is used to
-view or recover trace buffers in the event of a crash.
-.SH "OPTIONS"
-
-.PP
-This program follows the usual GNU command line syntax with long options starting with
-two dashes. Below is a summary of the available options.
-.PP
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-V, \-\-version"
-Show version.
-.TP
-.BR "\-v, \-\-verbose"
-Increase verbosity.
-Three levels of verbosity are available which are triggered by putting additional v to
-the option (\-vv or \-vvv)
-.TP
-.BR "\-e, \-\-viewer NAME"
-Specify viewer and/or options to use. This will completely override the default
-viewers therefore make sure to specify the full command. The trace directory paths are
-appended at the end to the arguments. (defaults: babeltrace)
-.TP
-.BR "\-x, \-\-extract PATH"
-Extract trace(s) to the specified path. Don't display the trace.
-
-.SH "SEE ALSO"
-.BR babeltrace(1),
-.BR lttng(1),
-.BR lttng-ust(3),
-.BR lttng-sessiond(8),
-.BR lttng-relayd(8),
-
-.SH "BUGS"
-
-.PP
-If you encounter any issues or usability problem, please report it on our
-mailing list <lttng-dev@lists.lttng.org> to help improve this project or
-at https://bugs.lttng.org which is a bug tracker.
-.PP
-
-.SH "CREDITS"
-
-.PP
-lttng is distributed under the GNU General Public License version 2. See the file
-COPYING for details.
-.PP
-A Web site is available at http://lttng.org for more information on the LTTng
-project.
-.PP
-You can also find our git tree at http://git.lttng.org.
-.PP
-Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
-.PP
-You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
-.PP
-.SH "AUTHORS"
-
-.PP
-lttng-crash was originally written by Mathieu Desnoyers. It is currently
-maintained by Jérémie Galarneau <jeremie.galarneau@efficios.com>.
-.PP
--- /dev/null
+lttng-crash(1)
+==============
+
+
+NAME
+----
+lttng-crash - Recover and view LTTng 2 trace buffers in the event of a crash
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng-crash* [option:--extract='PATH' | option:--viewer='VIEWER'] [option:-v | option:-vv | option:-vvv]
+
+
+DESCRIPTION
+-----------
+The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
+source software package used for correlated tracing of the Linux kernel,
+user applications, and user libraries.
+
+LTTng consists of Linux kernel modules (for Linux kernel tracing) and
+dynamically loaded libraries (for user application and library tracing).
+
+The _`lttng-crash`_ command-line tool is used to recover and view
+LTTng trace buffers in the event of a system crash.
+
+
+OPTIONS
+-------
+option:-x, option:--extract='PATH'::
+ Extract recovered traces to path 'PATH'; do not execute the trace
+ viewer.
+
+option:-v, option:--verbose::
+ Increase verbosity.
++
+Three levels of verbosity are available, which are triggered by
+appending additional `v` letters to the option
+(that is, `-vv` and `-vvv`).
+
+option:-e, option:--viewer='VIEWER'::
+ Use trace viewer 'VIEWER' to view the trace buffers. 'VIEWER' is the
+ absolute path to the viewer command to use, and it can contain
+ command arguments as well. The trace directory paths are passed to
+ the 'VIEWER' command as its last arguments.
++
+Default: `babeltrace`.
+
+
+Program information
+~~~~~~~~~~~~~~~~~~~
+option:-h, option:--help::
+ Show help.
+
+option:-V, option:--version::
+ Show version.
+
+
+EXIT STATUS
+-----------
+*0*::
+ Success
+
+*1*::
+ Error
+
+*3*::
+ Fatal error
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng(1),
+linklttng:lttng-sessiond(8),
+linklttng:lttng-relayd(8),
+linklttng:lttng-ust(3),
+linklttng:babeltrace(1)
--- /dev/null
+lttng-create(1)
+===============
+
+
+NAME
+----
+lttng-create - Create an LTTng tracing session
+
+
+SYNOPSIS
+--------
+Normal mode:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *create* [option:--output='PATH' | option:--no-output]
+ [option:--shm-path='PATH'] ['SESSION']
+
+Snapshot mode:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *create* option:--snapshot
+ [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
+ [option:--shm-path='PATH'] ['SESSION']
+
+Live mode:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *create* option:--live[='DELAYUS']
+ [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
+ [option:--shm-path='PATH'] ['SESSION']
+
+
+DESCRIPTION
+-----------
+The `lttng create` command creates a new tracing session.
+
+A tracing session is a named container of channels, which in turn
+contain event rules. It is domain-agnostic, in that channels and event
+rules can be enabled for the user space tracer and/or the Linux
+kernel tracer.
+
+On execution, an `.lttngrc` file is created, if it does not exist, in the
+user's home directory. This file contains the name of the current tracing
+session. When creating a new tracing session with `lttng create`, the
+current tracing session is set to this new tracing session. The
+linklttng:lttng-set-session(1) command can be used to set the current
+tracing session without manually editing the `.lttngrc` file.
+
+If 'SESSION' is omitted, a session name is automatically created having
+this form: `auto-YYYYmmdd-HHMMSS`. 'SESSION' *must not* contain the
+character `/`.
+
+The option:--shm-path option can be used to specify the path to the
+shared memory holding the ring buffers. Specifying a location on an
+NVRAM file system makes it possible to retrieve the latest recorded
+trace data when the system reboots after a crash. To view the events
+of ring buffer files after a system crash, use the
+linklttng:lttng-crash(1) utility.
+
+Tracing sessions are destroyed using the linklttng:lttng-destroy(1)
+command.
+
+
+Creation modes
+~~~~~~~~~~~~~~
+There are three tracing session modes:
+
+Normal mode::
+ Traces the local system and writes the trace to the local
+ file system. The option:--output option specifies the trace path.
+ If omitted, the trace is written in the `$LTTNG_HOME/lttng-traces`
+ directory (`$LTTNG_HOME` defaults to `$HOME`). The file system
+ output can be disabled using the option:--no-output option.
+
+Snapshot mode::
+ Traces the local system without writing the trace to the local file
+ system (implicit option:--no-output option). Channels are automatically
+ configured to be snapshot-ready on creation (see
+ linklttng:lttng-enable-channel(1)). The linklttng:lttng-snapshot(1)
+ command is used to take snapshots of the current ring buffers.
+ The option:--set-url, or option:--ctrl-url and option:--data-url
+ options set the default snapshot output destination.
+
+Live mode::
+ Traces the local system, sending trace data to an LTTng relay daemon
+ over the network (see linklttng:lttng-relayd(8)). The
+ option:--set-url, or option:--ctrl-url and option:--data-url options
+ set the trace output destination. The live output URLs cannot use
+ the `file://` protocol (see URL format below).
+
+
+[[url-format]]
+URL format
+~~~~~~~~~~
+The option:--set-url, option:--ctrl-url, and option:--data-url options
+specify URLs.
+
+The format of those URLs is one of:
+
+[verse]
+file://'TRACEPATH'
+'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEPATH']
+
+The `file://` protocol targets the *local file system*.
+
+'TRACEPATH'::
+ Absolute path to trace files on the local file system.
+
+The other version is used for *network streaming*.
+
+'NETPROTO'::
+ Network protocol, amongst:
++
+* `net`: TCP over IPv4; the default values of `<ctrl port>` and
+ `<data port>` are resp. 5342 and 5343
+* `net6`: TCP over IPv6: same default ports as `net` protocol
+* `tcp`: same as `net` protocol; can only be used with the
+ option:--ctrl-url and option:--data-url options together
+* `tcp6`: same as `net6` protocol; can only be used with the
+ option:--ctrl-url and option:--data-url options together
+
+('HOST' | 'IPADDR')::
+ Hostname or IP address (IPv6 address *must* be enclosed in brackets
+ (`[` and `]`); see https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).
+
+'CTRLPORT'::
+ Control port.
+
+'DATAPORT'::
+ Data port.
+
+'TRACEPATH'::
+ Path of trace files on the remote file system. This path is relative
+ to the base output directory set on the relay daemon side;
+ see linklttng:lttng-relayd(8).
+
+
+include::common-cmd-options-head.txt[]
+
+
+Mode
+~~~~
+option:--live[='DELAYUS']::
+ Create the session in live mode. The optional 'DELAYUS' parameter,
+ given in microseconds, is the maximum time the user can wait for
+ the data to be flushed. This mode can be set with a network URL
+ (options option:--set-url, or option:--ctrl-url and option:--data-url)
+ and must have a relay daemon listening (see linklttng:lttng-relayd(1)).
++
+By default, 'DELAYUS' is 1000000 and the network URL is set to
+`net://127.0.0.1`.
+
+option:--snapshot::
+ Create the session in snapshot mode. This is the equivalent of using
+ the option:--no-output option and creating all the channels of this
+ new tracing session in overwrite mode with an `mmap` output type.
+
+
+Output
+~~~~~~
+option:--no-output::
+ Do not output any trace data.
+
+option:-o, option:--output='PATH'::
+ Set trace output path to 'PATH'.
+
+option:--shm-path='PATH'::
+ Create shared memory holding buffers at 'PATH'.
+
+
+URL
+~~~
+See the <<url-format,URL format>> section above for more information
+about the syntax of the following options' 'URL' argument.
+
+option:-C, option:--ctrl-url='URL'::
+ Set control path URL to 'URL' (must use option:--data-url option
+ also).
+
+option:-D, option:--data-url='URL'::
+ Set data path URL to 'URL' (must use option:--ctrl-url option
+ also).
+
+option:-U, option:--set-url='URL'::
+ Set URL destination of the trace data to 'URL'. It is persistent for
+ the session lifetime. This option sets both data
+ (option:--data-url option) and control (option:--ctrl-url option)
+ URLs at the same time.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng-destroy(1),
+linklttng:lttng-set-session(1),
+linklttng:lttng(1)
--- /dev/null
+lttng-destroy(1)
+===============
+
+
+NAME
+----
+lttng-destroy - Destroy an LTTng tracing session
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *destroy* [option:--all | 'SESSION']
+
+
+DESCRIPTION
+-----------
+The `lttng destroy` command destroys one or more tracing sessions.
+
+If no options are specified, the current tracing session is destroyed
+(see linklttng:lttng-create(1) for more information about the current
+tracing session).
+
+If 'SESSION' is specified, the existing tracing session named 'SESSION'
+is destroyed. `lttng list` outputs all the existing tracing sessions
+(see linklttng:lttng-list(1)).
+
+If the option:--all option is used, *all* the tracing sessions, as listed
+in the output of `lttng list`, are destroyed.
+
+Destroying a tracing session stops any tracing running within the latter.
+
+Destroying a tracing session does not destroy the recorded trace data,
+if any; it frees resources acquired by the session daemon and tracer
+side, making sure to flush all trace data.
+
+
+include::common-cmd-options-head.txt[]
+
+
+option:-a, option:--all::
+ Destroy all tracing sessions.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng-create(1),
+linklttng:lttng-set-session(1),
+linklttng:lttng(1)
--- /dev/null
+lttng-disable-channel(1)
+=======================
+
+
+NAME
+----
+lttng-disable-channel - Disable LTTng channels
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *disable-channel* (option:--kernel | option:--userspace)
+ [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']...
+
+
+DESCRIPTION
+-----------
+The `lttng disable-channel` command disables one or more channels
+previously enabled by the linklttng:lttng-enable-channel(1) command.
+
+A channel is always contained in a tracing session
+(see linklttng:lttng-create(1) for creating a tracing session). The
+session in which a channel is disabled using `lttng disable-channel` can
+be specified using the option:--session option. If the option:--session
+option is omitted, the current tracing session is targeted.
+
+Note that re-enabling a disabled channel once its tracing session
+has been active at least once is currently not supported.
+
+
+include::common-cmd-options-head.txt[]
+
+
+Domain
+~~~~~~
+One of:
+
+option:-k, option:--kernel::
+ Disable channel in the Linux kernel domain.
+
+option:-u, option:--userspace::
+ Disable channel in the user space domain.
+
+
+Target
+~~~~~~
+option:-s, option:--session='SESSION'::
+ Disable channels in the tracing session named 'SESSION'
+ instead of the current tracing session.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng-disable-channel(1),
+linklttng:lttng(1)
--- /dev/null
+lttng-disable-event(1)
+======================
+
+
+NAME
+----
+lttng-disable-event - Disable LTTng event rules
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *disable-event*
+ (option:--kernel [option:--probe | option:--function | option:--syscall] |
+ option:--userspace | option:--jul | option:--log4j | option:--python)
+ [option:--session='SESSION'] [option:--channel='CHANNEL']
+ (option:--all-events | 'EVENT'[,'EVENT']...)
+
+DESCRIPTION
+-----------
+The `lttng disable-event` command disables one or more event rules
+previously enabled by the linklttng:lttng-enable-event(1) command.
+
+Event rules are always assigned to a channel when they are created. If
+the option:--channel option is omitted, the default channel named
+`channel0` is used.
+
+If the option:--session option is omitted, the chosen channel is picked
+from the current tracing session.
+
+If the option:--all-events option is used, all the existing event rules
+of the chosen domain are disabled. Otherwise, at least one event rule
+to disable named 'EVENT' must be specified.
+
+With the option:--kernel option, the event source type can be specified
+using one of the option:--tracepoint, option:--probe,
+option:--function, or option:--syscall options. See
+linklttng:lttng-enable-event(1) for more details about event source
+types.
+
+Events can be disabled while tracing is active
+(use linklttng:lttng-start(1) to make a tracing session active).
+
+
+include::common-cmd-options-head.txt[]
+
+
+Domain
+~~~~~~
+One of:
+
+option:-j, option:--jul::
+ Disable event rules in the `java.util.logging` (JUL) domain.
+
+option:-k, option:--kernel::
+ Disable event rules in the Linux kernel domain.
+
+option:-l, option:--log4j::
+ Disable event rules in the Apache log4j domain.
+
+option:-p, option:--python::
+ Disable event rules in the Python domain.
+
+option:-u, option:--userspace::
+ Disable event rules in the user space domain.
+
+
+Target
+~~~~~~
+option:-c, option:--channel='CHANNEL'::
+ Disable event rules in the channel named 'CHANNEL' instead
+ of the default channel name `channel0`.
+
+option:-s, option:--session='SESSION'::
+ Disable event rules in the tracing session named 'SESSION'
+ instead of the current tracing session.
+
+
+Event source type
+~~~~~~~~~~~~~~~~~
+One of:
+
+option:--function::
+ Linux kernel kretprobe. Only available with the option:--kernel
+ domain option.
+
+option:--probe::
+ Linux kernel kprobe. Only available with the option:--kernel
+ domain option.
+
+option:--syscall::
+ Linux kernel system call. Only available with the option:--kernel
+ domain option.
+
+option:--tracepoint::
+ Linux kernel or application tracepoint. Only available
+ with the option:--kernel domain option (default Linux kernel
+ domain event source type).
+
+
+Disabling
+~~~~~~~~~
+option:-a, option:--all-events::
+ Disable all enabled event rules in the chosen tracing session,
+ tracing domain, and channel.
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng-enable-event(1),
+linklttng:lttng(1)
--- /dev/null
+lttng-enable-channel(1)
+=======================
+
+
+NAME
+----
+lttng-enable-channel - Create or enable LTTng channels
+
+
+SYNOPSIS
+--------
+Create a Linux kernel channel:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *enable-channel* option:--kernel
+ [option:--discard | 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:--session='SESSION'] 'CHANNEL'
+
+Create a user space channel:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *enable-channel* option:--userspace
+ [option:--discard | option:--overwrite] [option:--buffers-pid]
+ [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:--session='SESSION'] 'CHANNEL'
+
+Enable existing channel(s):
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *enable-channel* (option:--userspace | option:--kernel)
+ [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']...
+
+
+DESCRIPTION
+-----------
+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,
+rules, when created using linklttng: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.
+
+When 'CHANNEL' does not name an existing channel, a channel named
+'CHANNEL' is created. Otherwise, the disabled channel named 'CHANNEL'
+is enabled.
+
+Note that the linklttng:lttng-enable-event(1) command can automatically
+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
+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).
+
+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.
+
+
+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 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.
+
+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:
+
+Discard::
+ Drop the newest events until a sub-buffer is released.
+
+Overwrite::
+ Clear the sub-buffer containing the oldest recorded events and start
+ recording the newest events there. This mode is sometimes called
+ _flight recorder mode_ because it behaves like a flight recorder:
+ always keep a fixed amount of the latest data.
+
+Which mechanism to choose depends on the context: prioritize the newest
+or the oldest events in the ring buffer?
+
+Beware that, in overwrite mode (option:--overwrite option), a whole
+sub-buffer is abandoned as soon as a new event doesn't find an empty
+sub-buffer, whereas in discard mode (option:--discard option), only the
+event that doesn't fit is discarded.
+
+Also note that a count of lost events is incremented and saved in the
+trace itself when an event is lost in discard mode, whereas no
+information is kept when a sub-buffer gets overwritten before being
+committed.
+
+The probability of losing events, if it is experience in a given
+context, can be reduced by fine-tuning the sub-buffers count and size
+(see next subsection).
+
+
+Sub-buffers count and size
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+The option:--num-subbuf and option:--subbuf-size options respectively
+set the number of sub-buffers and their individual size when creating
+a new channel.
+
+Note that there is a noticeable tracer's CPU overhead introduced when
+switching sub-buffers (marking a full one as consumable and switching
+to an empty one for the following events to be recorded). Knowing this,
+the following list presents a few practical situations along with how
+to configure sub-buffers for them when creating a channel in overwrite
+mode (option:--overwrite option):
+
+High event throughput::
+ In general, prefer bigger sub-buffers to lower the risk of losing
+ events. Having bigger sub-buffers also ensures a lower sub-buffer
+ switching frequency. The number of sub-buffers is only meaningful
+ if the channel is enabled in overwrite mode: in this case, if a
+ sub-buffer overwrite happens, the other sub-buffers
+ are left unaltered.
+
+Low event throughput::
+ In general, prefer smaller sub-buffers since the risk of losing
+ events is already low. Since events happen less frequently, the
+ sub-buffer switching frequency should remain low and thus the
+ tracer's overhead should not be a problem.
+
+Low memory system::
+ If the target system has a low memory limit, prefer fewer first,
+ then smaller sub-buffers. Even if the system is limited in memory,
+ it is recommended to keep the sub-buffers as big as possible to
+ avoid a high sub-buffer switching frequency.
+
+In discard mode (option:--discard option), the sub-buffers count
+parameter is pointless: using two sub-buffers and setting their size
+according to the requirements of the context is fine.
+
+
+Switch and read timers
+~~~~~~~~~~~~~~~~~~~~~~
+When a channel's switch timer fires, a sub-buffer switch happens. This
+timer may be used to ensure that event data is consumed and committed
+to trace files periodically in case of a low event throughput.
+
+It's also convenient when big sub-buffers are used to cope with sporadic
+high event throughput, even if the throughput is normally lower.
+
+By default, a notification mechanism is used to signal a full sub-buffer
+so that it can be consumed. When such notifications must be avoided,
+for example in real-time applications, the channel's read timer can be
+used instead. When the read timer fires, sub-buffers are checked for
+consumption when they are full.
+
+
+Buffering scheme
+~~~~~~~~~~~~~~~~
+In the user space tracing domain, two buffering schemes are available
+when creating a channel:
+
+Per-process buffering (option:--buffers-pid option)::
+ Keep one ring buffer per process.
+
+Per-user buffering (option:--buffers-uid option)::
+ Keep one ring buffer for all the processes of a single user.
+
+The per-process buffering scheme consumes more memory than the per-user
+option if more than one process is instrumented for LTTng-UST.
+However, per-process buffering ensures that one process having a high
+event throughput won't fill all the shared sub-buffers, only its own.
+
+The Linux kernel tracing domain only has one available buffering scheme
+which is to use a single ring buffer for the whole system
+(option:--buffers-global option).
+
+
+Trace files limit and size
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+By default, trace files can grow as large as needed. The maximum size
+of each trace file written by a channel can be set on creation using the
+option:--tracefile-size option. When such a trace file's size reaches
+the channel's fixed maximum size, another trace file is created to hold
+the next recorded events. A file count is appended to each trace file
+name in this case.
+
+If the option:--tracefile-size option is used, the maximum number of
+created trace files is unlimited. To limit them, the
+option:--tracefile-count option can be used. This option is always used
+in conjunction with the option:--tracefile-size option.
+
+For example, consider this command:
+
+-----------------------------------------------------
+lttng enable-channel --kernel --tracefile-size=4096 \
+ --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
+no space left in the last file, _trace file rotation_ happens: the first
+file is cleared and new sub-buffers containing events are written there.
+
+
+include::common-cmd-options-head.txt[]
+
+
+Domain
+~~~~~~
+One of:
+
+option:-k, option:--kernel::
+ Enable channel in the Linux kernel domain.
+
+option:-u, option:--userspace::
+ Enable channel in the user space domain.
+
+
+Target
+~~~~~~
+option:-s, option:--session='SESSION'::
+ Create or enable channel in the tracing session named 'SESSION'
+ instead of the current tracing session.
+
+
+Event loss mode
+~~~~~~~~~~~~~~~
+One of:
+
+option:--discard::
+ Discard events when sub-buffers are full (default).
+
+option:--overwrite::
+ Flight recorder mode: always keep a fixed amount of the latest
+ data.
+
+
+Sub-buffers
+~~~~~~~~~~~
+option:--num-subbuf='COUNT'::
+ Use 'COUNT' sub-buffers. Rounded up to the next power of two.
++
+Default values:
++
+* `metadata` channel: 2
+* Everything else: 4
+
+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.
+ Rounded up to the next power of two.
++
+The minimum sub-buffer size, for each tracer, is the maximum value
+between the default below and the system's page size. The following
+command shows the current system's page size: `getconf PAGE_SIZE`.
++
+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:--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
+~~~~~~~~~~~~~~~~
+One of:
+
+option:--buffers-global::
+ Use shared sub-buffers for the whole system (only available with the
+ option:--kernel option).
+
+option:--buffers-pid::
+ Use different sub-buffers for each traced process (only available
+ with the the option:--userspace option). This is the default
+ buffering scheme for user space channels.
+
+option:--buffers-uid::
+ Use shared sub-buffers for all the processes of the user running
+ the command (only available with the option:--userspace option).
+
+
+Trace files
+~~~~~~~~~~~
+option:--tracefile-count='COUNT'::
+ Limit the number of trace files created by this channel to
+ 'COUNT'. 0 means unlimited. Default: 0.
++
+Use this option in conjunction with the option:--tracefile-size option.
++
+The file count within a stream is appended to each created trace
+file. If 'COUNT' files are created and more events need to be recorded,
+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.
+ Default: 0.
++
+Note: traces generated with this option may inaccurately report
+discarded events as of CTF 1.8.
+
+
+Timers
+~~~~~~
+option:--read-timer::
+ Set the channel's read timer's period to 'PERIODUS' µs. 0 means a
+ disabled read timer.
++
+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:--switch-timer='PERIODUS'::
+ Set the channel's switch timer's period to 'PERIODUS' µs. 0 means
+ a disabled switch timer. Default: 0.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng-disable-channel(1),
+linklttng:lttng(1)
--- /dev/null
+lttng-enable-event(1)
+=====================
+
+
+NAME
+----
+lttng-enable-event - Create or enable LTTng event rules
+
+
+SYNOPSIS
+--------
+Create or enable Linux kernel event rules:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *enable-event* option:--kernel
+ [option:--probe='SOURCE' | option:--function='SOURCE' | option:--syscall]
+ [option:--filter='EXPR'] [option:--session='SESSION']
+ [option:--channel='CHANNEL'] 'EVENT'[,'EVENT']...
+
+Create or enable an "all" Linux kernel event rule:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *enable-event* option:--kernel option:--all [option:--syscall]
+ [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL']
+
+Create or enable application event rules:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *enable-event*
+ (option:--userspace | option:--jul | option:--log4j | option:--python)
+ [option:--filter='EXPR'] [option:--exclude='EVENT'[,'EVENT']...]
+ [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL']
+ [option:--session='SESSION'] [option:--channel='CHANNEL'] (option:--all | 'EVENT'[,'EVENT']...)
+
+
+DESCRIPTION
+-----------
+The `lttng enable-event` command can create a new event rule, or enable
+one or more existing and disabled ones.
+
+An event rule created by `lttng enable-event` is a set of conditions
+that must be satisfied in order for an actual event to be emitted by
+an LTTng tracer when the execution of an application or the Linux kernel
+reaches an event source (tracepoint, system call, dynamic probe).
+Event sources can be listed with the linklttng:lttng-list(1) command.
+
+The linklttng:lttng-disable-event(1) command can be used to disable
+existing event rules.
+
+Event rules are always assigned to a channel when they are created. If
+the option:--channel option is omitted, a default channel named
+`channel0` is used (and created automatically if it does not exist for
+the specified domain in the selected tracing session).
+
+If the option:--session option is omitted, the chosen channel is picked
+from the current tracing session.
+
+Events can be enabled while tracing is active
+(use linklttng:lttng-start(1) to make a tracing session active).
+
+
+Event source types
+~~~~~~~~~~~~~~~~~~
+Four types of event sources are available in the Linux kernel tracing
+domain (option:--kernel option):
+
+Tracepoint (option:--tracepoint option; default)::
+ A Linux kernel tracepoint, that is, a static instrumentation point
+ placed in the kernel source code. Standard tracepoints are designed
+ and placed in the source code by developers and record useful
+ payload fields.
+
+Dynamic probe (option:--probe option)::
+ A Linux kernel kprobe, that is, an instrumentation point placed
+ dynamically in the compiled kernel code. Dynamic probe events do not
+ record any payload field.
+
+Function probe (option:--function option)::
+ A Linux kernel kretprobe, that is, two instrumentation points placed
+ dynamically where a function is entered and where it returns in the
+ compiled kernel code. Function probe events do not record any
+ payload field.
+
+System call (option:--syscall option)::
+ A Linux kernel system call. Two instrumentation points are
+ statically placed where a system call function is entered and where
+ it returns in the compiled kernel code. System call event sources
+ record useful payload fields.
+
+The application tracing domains (option:--userspace, option:--jul,
+option:--log4j, or option:--python options) only support tracepoints.
+In the cases of the JUL, Apache log4j, and Python domains, the event
+names correspond to _logger_ names.
+
+
+Understanding event rule conditions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When creating an event rule with `lttng enable-event`, conditions are
+specified using options. The logical conjunction (logical AND) of all
+those conditions must be true when an event source is reached by an
+application or by the Linux kernel in order for an actual event
+to be emitted by an LTTng tracer.
+
+Any condition that is not explicitly specified on creation is considered
+a _don't care_.
+
+For example, consider the following commands:
+
+----------------------------------------------------------------
+lttng enable-event --userspace hello:world
+lttng enable-event --userspace hello:world --loglevel=TRACE_INFO
+----------------------------------------------------------------
+
+Here, two event rules are created. The first one has a single condition:
+the tracepoint name must match `hello:world`. The second one has two
+conditions:
+
+* The tracepoint name must match `hello:world`, _and_
+* The tracepoint's defined log level must be at least as severe as
+ the `TRACE_INFO` level.
+
+In this case, the second event rule is pointless because the first one
+is more general: it does not care about the tracepoint's log level.
+If an event source matching both event rules is reached by the
+application's execution, only one event is emitted.
+
+The available conditions for the Linux kernel domain are:
+
+* Tracepoint/system call name ('EVENT' argument with
+ option:--tracepoint or option:--syscall options) or
+ dynamic probe/function name/address
+ (option:--probe or option:--function option's argument) which must
+ match event source's equivalent.
++
+Wildcard using the `*` character are supported _at the end_ of
+tracepoint and system call names.
+
+* Filter expression (option:--filter option) executed against the
+ dynamic values of event fields at execution time that must evaluate
+ to true. See the <<filter-syntax,Filter expression syntax>> section
+ below for more information.
+
+The available conditions for the application domains are:
+
+* Tracepoint name ('EVENT' with option:--tracepoint option) which must
+ match event source's equivalent.
++
+Wildcard using the `*` character are supported _at the end_ of
+tracepoint names. When creating an event rule with a tracepoint name
+containing a wildcard, specific tracepoint names can be excluded from
+the match using the option:--exclude option.
+
+* Filter expression (option:--filter option) executed against the
+ dynamic values of event fields at execution time that must evaluate
+ to true. See the <<filter-syntax,Filter expression syntax>> section
+ below for more information.
+* Event's log level that must be at least as severe as a given
+ log level (option:--loglevel option) or match exactly a given log
+ level (option:--loglevel-only option).
+
+When using `lttng enable-event` with a set of conditions that does not
+currently exist for the chosen tracing session, domain, and channel,
+a new event rule is created. Otherwise, the existing event rule is
+enabled if it is currently disabled
+(see linklttng:lttng-disable-event(1)).
+
+The option:--all option can be used alongside the option:--tracepoint
+or option:--syscall options. When this option is used, no 'EVENT'
+argument must be specified. This option defines a single event rule
+matching _all_ the possible events of a given tracing domain for the
+chosen channel and tracing session. It is the equivalent of an 'EVENT'
+argument named `*` (wildcard).
+
+
+[[filter-syntax]]
+Filter expression syntax
+~~~~~~~~~~~~~~~~~~~~~~~~
+Filter expressions can be specified with the option:--filter option
+when creating a new event rule. If the filter expression evaluates
+to true when executed against the dynamic values of an event's fields
+when tracing, the filtering condition passes.
+
+The filter expression syntax is very similar to C language conditional
+expressions (expressions that can be evaluated by an `if` statement).
+
+The following logical operators are supported:
+
+[width="40%",options="header"]
+|=====================================
+| Name | Syntax
+| Logical negation (NOT) | `!a`
+| Logical conjunction (AND) | `a && b`
+| Logical disjunction (OR) | `a \|\| b`
+|=====================================
+
+The following comparison operators/relational operators are supported:
+
+[width="40%",options="header"]
+|====================================
+| Name | Syntax
+| Equal to | `a == b`
+| Not equal to | `a != b`
+| Greater than | `a > b`
+| Less than | `a < b`
+| Greater than or equal to | `a >= b`
+| Less than or equal to | `a <= b`
+|====================================
+
+The arithmetic and bitwise operators are :not: supported.
+
+The precedence table of the operators above is the same as the one of
+the C language. Parentheses are supported to bypass this.
+
+The dynamic value of an event field is read by using its name as
+a C identifier.
+
+The dynamic value of a statically-known context field is read by
+prefixing its name with `$ctx.`. Statically-known context fields are
+context fields added to channels without the `$app.` prefix using the
+linklttng:lttng-add-context(1) command.
+
+The dynamic value of an application-specific context field is read by
+prefixing its name with `$app.` (follows the format used to add such a
+context field with the linklttng:lttng-add-context(1) command).
+
+When a comparison includes a non existent event field, the whole filter
+expression evaluates to false (the event is discarded).
+
+C integer and floating point number constants are supported, as well as
+literal strings between double quotes (`"`). Literal strings can contain
+a wildcard character (`*`) at the end to match more than one string.
+This wildcard can be escaped using `\\*`.
+
+LTTng-UST enumeration fields can be compared to integer values (fields
+or constants).
+
+NOTE: Although it is possible to filter the process ID of an event when
+the `pid` context has been added to its channel using, for example,
+`$ctx.pid == 2832`, it is recommended to use the PID tracker instead,
+which is much more efficient (see linklttng:lttng-track(1)).
+
+Examples:
+
+----------------------------
+msg_id == 23 && size >= 2048
+----------------------------
+
+-------------------------------------------------
+$ctx.procname == "lttng*" && (!flag || poel < 34)
+-------------------------------------------------
+
+---------------------------------------------------------
+$app.my_provider:my_context == 17.34e9 || some_enum >= 14
+---------------------------------------------------------
+
+
+[[log-levels]]
+Log levels
+~~~~~~~~~~
+Tracepoints and log statements in applications have an attached log
+level. Application event rules can contain a _log level_ condition.
+
+With the option:--loglevel option, the event source's log level must
+be at least as severe as the option's argument. With the
+option:--loglevel-only option, the event source's log level must match
+the option's argument.
+
+The available log levels are:
+
+User space domain (option:--userspace option)::
+ Shortcuts such as `system` are allowed.
++
+* `TRACE_EMERG` (0)
+* `TRACE_ALERT` (1)
+* `TRACE_CRIT` (2)
+* `TRACE_ERR` (3)
+* `TRACE_WARNING` (4)
+* `TRACE_NOTICE` (5)
+* `TRACE_INFO` (6)
+* `TRACE_DEBUG_SYSTEM` (7)
+* `TRACE_DEBUG_PROGRAM` (8)
+* `TRACE_DEBUG_PROCESS` (9)
+* `TRACE_DEBUG_MODULE` (10)
+* `TRACE_DEBUG_UNIT` (11)
+* `TRACE_DEBUG_FUNCTION` (12)
+* `TRACE_DEBUG_LINE` (13)
+* `TRACE_DEBUG` (14)
+
+`java.util.logging` domain (option:--jul option)::
+ Shortcuts such as `severe` are allowed.
++
+* `JUL_OFF` (`INT32_MAX`)
+* `JUL_SEVERE` (1000)
+* `JUL_WARNING` (900)
+* `JUL_INFO` (800)
+* `JUL_CONFIG` (700)
+* `JUL_FINE` (500)
+* `JUL_FINER` (400)
+* `JUL_FINEST` (300)
+* `JUL_ALL` (`INT32_MIN`)
+
+Apache log4j domain (option:--log4j option)::
+ Shortcuts such as `severe` are allowed.
++
+* `LOG4J_OFF` (`INT32_MAX`)
+* `LOG4J_FATAL` (50000)
+* `LOG4J_ERROR` (40000)
+* `LOG4J_WARN` (30000)
+* `LOG4J_INFO` (20000)
+* `LOG4J_DEBUG` (10000)
+* `LOG4J_TRACE` (5000)
+* `LOG4J_ALL` (`INT32_MIN`)
+
+Python domain (option:--python option)::
+ Shortcuts such as `critical` are allowed.
++
+* `PYTHON_CRITICAL` (50)
+* `PYTHON_ERROR` (40)
+* `PYTHON_WARNING` (30)
+* `PYTHON_INFO` (20)
+* `PYTHON_DEBUG` (10)
+* `PYTHON_NOTSET` (0)
+
+
+include::common-cmd-options-head.txt[]
+
+
+Domain
+~~~~~~
+One of:
+
+option:-j, option:--jul::
+ Create or enable event rules in the `java.util.logging`
+ (JUL) domain.
+
+option:-k, option:--kernel::
+ Create or enable event rules in the Linux kernel domain.
+
+option:-l, option:--log4j::
+ Create or enable event rules in the Apache log4j domain.
+
+option:-p, option:--python::
+ Create or enable event rules in the Python domain.
+
+option:-u, option:--userspace::
+ Create or enable event rules in the user space domain.
+
+
+Target
+~~~~~~
+option:-c, option:--channel='CHANNEL'::
+ Create or enable event rules in the channel named 'CHANNEL' instead
+ of the default channel name `channel0`.
+
+option:-s, option:--session='SESSION'::
+ Create or enable event rules in the tracing session named 'SESSION'
+ instead of the current tracing session.
+
+
+Event source type
+~~~~~~~~~~~~~~~~~
+One of:
+
+option:--function='SOURCE'::
+ Linux kernel kretprobe. Only available with the option:--kernel
+ domain option. 'SOURCE' is one of:
++
+* Function address (`0x` prefix supported)
+* Function symbol
+* Function symbol and offset (`SYMBOL+OFFSET` format)
+
+option:--probe='SOURCE'::
+ Linux kernel kprobe. Only available with the option:--kernel
+ domain option. 'SOURCE' is one of:
++
+* Address (`0x` prefix supported)
+* Symbol
+* Symbol and offset (`SYMBOL+OFFSET` format)
+
+option:--syscall::
+ Linux kernel system call. Only available with the option:--kernel
+ domain option.
+
+option:--tracepoint::
+ Linux kernel or application tracepoint (default).
+
+
+Log level
+~~~~~~~~~
+One of:
+
+option:--loglevel='LOGLEVEL'::
+ Add log level condition to the event rule: the event source's
+ defined log level must be at least as severe as 'LOGLEVEL'.
+ See the <<log-levels,Log levels>> section above for the available
+ log levels. Only available with application domains.
+
+option:--loglevel-only='LOGLEVEL'::
+ Add log level condition to the event rule: the event source's
+ defined log level must match 'LOGLEVEL'. See the
+ <<log-levels,Log levels>> section above for the available log
+ levels. Only available with application domains.
+
+
+Filtering and exclusion
+~~~~~~~~~~~~~~~~~~~~~~~
+option:-x, option:--exclude='EVENT'[,'EVENT']...::
+ Exclude events named 'EVENT' from the event rule. This option
+ can be used when the command's 'EVENT' argument contains a wildcard
+ (`*`) to exclude specific names. Only available with application
+ domains.
+
+option:-f, option:--filter='EXPR'::
+ Add filter expression condition to the event rule. Expression 'EXPR'
+ must evaluate to true when executed against the dynamic values of
+ event fields. See the <<filter-syntax,Filter expression syntax>>
+ section above for more information.
+
+
+Shortcuts
+~~~~~~~~~
+option:-a, option:--all::
+ Equivalent to an 'EVENT' argument named `*` (wildcard) when also
+ using the option:--tracepoint (default) or option:--syscall option.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng-disable-event(1),
+linklttng:lttng(1)
--- /dev/null
+lttng-help(1)
+=============
+
+
+NAME
+----
+lttng-help - Display help information about an LTTng command
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *help* ['COMMAND']
+
+
+DESCRIPTION
+-----------
+The `lttng help` command displays help information about an LTTng
+command.
+
+This command is the equivalent of:
+
+--------------------
+lttng COMMAND --help
+--------------------
+
+where `COMMAND` is the name of the command about which to get help. If
+'COMMAND' is omitted, `lttng help` shows general help about the
+linklttng:lttng(1) command.
+
+The `lttng help` command attempts to launch `/usr/bin/man` to view
+the command's man page. The path to the man pager can be overridden
+by the `LTTNG_MAN_BIN_PATH` environment variable.
+
+
+include::common-cmd-options-head.txt[]
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng(1)
--- /dev/null
+lttng-list(1)
+=============
+
+
+NAME
+----
+lttng-list - List LTTng tracing sessions, domains, channels, and events
+
+
+SYNOPSIS
+--------
+List existing tracing sessions:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *list*
+
+List available event sources:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *list* [option:--fields]
+ [option:--kernel [option:--syscall]] [option:--userspace] [option:--jul] [option:--log4j] [option:--python]
+
+List tracing session's domains:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *list* option:--domain 'SESSION'
+
+List tracing session's channels and event rules:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *list* [option:--channel='CHANNEL'] 'SESSION'
+
+
+DESCRIPTION
+-----------
+The `lttng list` command lists tracing sessions, tracing domains,
+channels, and events.
+
+Without arguments, `lttng list` lists the existing tracing sessions
+and shows if they are active or not.
+
+With one or more of the option:--kernel, option:--userspace,
+option:--jul, option:--log4j, and option:--python domain options, the
+command lists the available event sources of the selected domain on the
+system. The JUL, log4j, and Python domains list the names of their
+available _loggers_. The option:--syscall option can be used alongside
+the option:--kernel option to get a list of traceable Linux system
+calls. The option:--fields option can be used to show the fields of the
+listed event sources.
+
+Providing a tracing session name 'SESSION' targets a specific tracing
+session. If the option:--domain option is used, domains containing at
+least one channel in the selected tracing session are listed. Otherwise,
+all the domains, channels, and event rules of the selected tracing
+session are listed along with its details (trace path, for example),
+except when the option:--channel option is used to isolate a specific
+channel by name.
+
+
+include::common-cmd-options-head.txt[]
+
+
+Domain
+~~~~~~
+option:-j, option:--jul::
+ List event sources in the `java.util.logging` (JUL) domain.
+
+option:-k, option:--kernel::
+ List event sources in the Linux kernel domain.
+
+option:-l, option:--log4j::
+ List event sources in the Apache log4j domain.
+
+option:-p, option:--python::
+ List event sources in the Python domain.
+
+option:-u, option:--userspace::
+ List event sources in the user space domain.
+
+
+Target
+~~~~~~
+option:-c, option:--channel='CHANNEL'::
+ Only list the details of the channel named 'CHANNEL'.
+
+
+Listing
+~~~~~~~
+option:-d, option:--domain::
+ Show the domains of the target tracing session in which at least one
+ channel exists.
+
+option:-f, option:--fields::
+ When listing the event sources with one of the domain options,
+ also show their fields.
+
+option:--syscall::
+ When listing the event sources of the Linux kernel domain, list
+ the traceable system calls instead of the kernel tracepoints.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng(1)
--- /dev/null
+lttng-load(1)
+=============
+
+
+NAME
+----
+lttng-load - Load LTTng tracing session configurations
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *load* [option:--force] [option:--input-path='PATH'] ['SESSION']
+
+
+DESCRIPTION
+-----------
+The `lttng load` command loads the configurations of one or more
+tracing sessions from files.
+
+The `lttng load` command is used in conjunction with the
+linklttng:lttng-save(1) command to save and restore the complete
+configurations of tracing sessions. This includes the enabled channels
+and event rules, the context added to channels, the tracing activity,
+and more.
+
+Once one or more tracing session configurations are loaded, they appear
+exactly as they were saved from the user's point of view.
+
+The default input path is `$LTTNG_HOME/.lttng/sessions`
+(`$LTTNG_HOME` defaults to `$HOME`). The input path can be
+overridden with the option:--input-path option.
+
+If the input path is a directory, then if 'SESSION' is specified, the
+tracing session configuration named 'SESSION' is searched in all the
+files of this directory and loaded if found. If 'SESSION' is not
+specified, the option:--all option is implicit: all the tracing session
+configurations found in all the files in this directory are loaded.
+
+If the input path is a file, then if 'SESSION' is specified, the tracing
+session configuration named 'SESSION' is searched in this file and
+loaded if found. If 'SESSION' is not specified, the option:--all option
+is implicit: all the tracing session configurations found in this file
+are loaded.
+
+By default, existing tracing sessions are not overwritten when loading;
+the command fails. The option:--force option can be used to allow this.
+
+
+include::common-cmd-options-head.txt[]
+
+
+option:-a, option:--all::
+ Load all tracing session configurations (default).
+
+option:-f, option:--force::
+ Overwrite existing tracing sessions when loading.
+
+option:-i, option:--input-path='PATH'::
+ Set input path to 'PATH', either a directory or a file, in which
+ tracing session configurations are searched for.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng-save(1),
+linklttng:lttng(1)
--- /dev/null
+lttng-metadata(1)
+=================
+
+
+NAME
+----
+lttng-metadata - Manage an LTTng tracing session's metadata generation
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *metadata regenerate* [option:--session='SESSION']
+
+
+DESCRIPTION
+-----------
+The `lttng metadata` command manages a tracing session's metadata
+generation options.
+
+As of this version, only the `regenerate` command's action is available.
+Regenerating a tracing session's metadata can be used to
+resample the offset between the system's monotonic clock and
+the wall-clock time.
+
+This command is meant to be used to resample the wall-clock time
+following a major
+link:https://en.wikipedia.org/wiki/Network_Time_Protocol[NTP]
+correction. As such, a system booting with an incorrect wall time can be
+traced before its wall time is NTP-corrected. Regenerating the tracing
+session's metadata ensures that trace viewers can accurately determine
+the events time relative to Unix Epoch.
+
+
+include::common-cmd-options-head.txt[]
+
+
+option:-s, option:--session='SESSION'::
+ Manage the metadata generation of the tracing session named 'SESSION'
+ instead of the current tracing session.
+
+
+include::common-cmd-help-options.txt[]
+
+
+LIMITATIONS
+-----------
+The `lttng metadata regenerate` command can only be used on kernel and
+user space tracing sessions (using per-user buffering), in non-live
+mode.
+
+See linklttng:lttng-enable-channel(1) for more information about
+buffering schemes and linklttng:lttng-create(1) for more information
+about the different tracing session modes.
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng(1)
+++ /dev/null
-.TH "LTTNG-RELAYD" "8" "July 15, 2012" "" ""
-
-.SH "NAME"
-lttng-relayd \- LTTng remote trace collection daemon
-
-.SH "SYNOPSIS"
-
-.PP
-.nf
-lttng-relayd [OPTIONS]
-.fi
-.SH "DESCRIPTION"
-
-.PP
-The LTTng project aims at providing highly efficient tracing tools for Linux.
-It's tracers help tracking down performance issues and debugging problems
-involving multiple concurrent processes and threads. Tracing across multiple
-systems is also possible.
-
-The relay daemon listens by default on all network interfaces to gather
-trace data, but only on localhost for viewer connections. This daemon
-does not require any particular permissions as long as it can write in
-the output folder and listen on the ports. If a user is within a secured
-network and/or has proper firewall settings, lttng-relayd can listen to
-viewer connections from all network interfaces by specifying '-L
-tcp://0.0.0.0:5344'.
-
-Traces can be either viewed "live" (as they are produced) by attaching
-to the live viewer port using LTTng live protocol, or after tracing has
-been stopped. Once a trace has been streamed completely, the trace can
-be processed by any tool that can process a local LTTng CTF trace.
-
-By default, the relayd outputs the traces in :
-~/lttng-traces/hostname/session-name/domain-name
-
-The prefix (~/lttng-traces) can be configured on the relayd side (see below for
-the option), the other folders can be configured when creating the trace on the
-sessiond side.
-.SH "OPTIONS"
-
-.PP
-This program follows the usual GNU command line syntax with long options starting
-with two dashes. Below is a summary of the available options.
-.PP
-
-.TP
-.BR "-h, --help"
-Show summary of possible options and commands
-.TP
-.BR "\-V, \-\-version"
-Show version.
-.TP
-.BR "-v, --verbose"
-Increase verbosity
-
-There is three debugging level which will print on stderr. Maximum verbosity is
-\fB-vvv\fP.
-.TP
-.BR "-d, --daemonize"
-Start as a daemon
-.TP
-.BR "-b, --background"
-Start as a daemon, keeping console open
-.TP
-.BR "-g, --group NAME"
-Specify the tracing group name. (default: tracing)
-.TP
-.BR "-C, --control-port"
-Control port URL (tcp://0.0.0.0:5342 is the default)
-.TP
-.BR "-D, --data-port"
-Data port URL (tcp://0.0.0.0:5343 is the default)
-.TP
-.BR "-L, --live-port URL"
-Live view port URL (tcp://localhost:5344 is the default).
-.TP
-.BR "-o, --output"
-Output base directory. Must use an absolute path (~/lttng-traces is the default)
-.TP
-.BR "-V, --version"
-Show version number
-.SH "ENVIRONMENT VARIABLES"
-
-.PP
-.IP "LTTNG_NETWORK_SOCKET_TIMEOUT"
-Control timeout of socket connection, receive and send. Takes an integer
-parameter: the timeout value, in milliseconds. A value of 0 or -1 uses
-the timeout of the operating system (this is the default).
-.IP "LTTNG_RELAYD_HEALTH"
-File path used for relay daemon health check communication.
-.PP
-
-.SH "SEE ALSO"
-
-.PP
-babeltrace(1), lttng-sessiond(8), lttng-ust(3), lttng(1)
-.PP
-
-.SH "LIMITATIONS"
-
-.PP
-For now only TCP is supported on both control and data port.
-Control will always remain TCP-only since it is low-volume and needs absolutely
-to be reliable, but eventually the data connection could support UDP.
-
-For unprivileged user running lttng-relayd, the maximum number of file
-descriptors per process is usually 1024. This limits the number of connections
-and tracefiles opened. This limit can be configured see ulimit(3).
-.PP
-
-.SH "BUGS"
-
-.PP
-No show stopper bugs are known yet in this version.
-
-If you encounter any issues or usability problem, please report it on our
-mailing list <lttng-dev@lists.lttng.org> to help improve this project.
-.SH "CREDITS"
-
-.PP
-lttng-relayd is distributed under the GNU General Public License version 2. See the
-file COPYING for details.
-.PP
-A Web site is available at http://lttng.org for more information on the LTTng
-project.
-.PP
-You can also find our git tree at http://git.lttng.org.
-.PP
-Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
-.PP
-You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
-.PP
-.SH "AUTHORS"
-
-.PP
-lttng-relay was originally written by Julien Desfossez and
-David Goulet. More people have since contributed to it. It is currently
-maintained by Julien Desfossez <jdesfossez@efficios.com>.
-.PP
--- /dev/null
+lttng-relayd(8)
+===============
+
+
+NAME
+----
+lttng-relayd - LTTng 2 relay daemon
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng-relayd* [option:--background | option:--daemonize]
+ [option:--control-port='URL'] [option:--data-port='URL'] [option:--live-port='URL']
+ [option:--output='PATH'] [option:-v | option:-vv | option:-vvv]
+
+
+DESCRIPTION
+-----------
+The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
+source software package used for correlated tracing of the Linux kernel,
+user applications, and user libraries.
+
+LTTng consists of Linux kernel modules (for Linux kernel tracing) and
+dynamically loaded libraries (for user application and library tracing).
+
+The _LTTng relay daemon_ is responsible for receiving trace data from
+possibly remote LTTng session/consumer daemons and for writing it to
+the local file system. The relay daemon also accepts _LTTng live_
+connections from compatible viewers; this is the official approach to
+viewing LTTng events as they are emitted.
+
+The relay daemon listens by default on all network interfaces to gather
+trace data, but only on localhost for LTTng live connections.
+
+The relay daemon does not require any particular permissions, as long as
+it can write to the output directory and listen on the configured ports.
+If a user is within a secured network and/or has proper firewall
+settings, `lttng-relayd` can listen to LTTng live connections from _all_
+network interfaces by specifying `--live-port=tcp://0.0.0.0:5344`.
+
+Once a trace has been streamed completely, the trace can be processed by
+any tool that can process an LTTng trace located on the local
+file system.
+
+
+[[output-directory]]
+Output directory
+~~~~~~~~~~~~~~~~
+By default, the relay daemon writes the traces to:
+
+[verse]
+$HOME/lttng-traces/'HOSTNAME'/'SESSION'/'DOMAIN'
+
+with:
+
+'HOSTNAME'::
+ Remote hostname.
+
+'SESSION'::
+ Full session name.
+
+'DOMAIN'::
+ Tracing domain.
+
+You can override the default output directory prefix
+(`$HOME/lttng-traces`) with the option:--output option. The other
+parts depend on the remote configuration.
+
+
+[[url-format]]
+URL format
+~~~~~~~~~~
+The option:--control-port, option:--data-port, and option:--live-port
+options specify URLs.
+
+The format of those URLs is:
+
+[verse]
+tcp://('HOST' | 'IPADDR'):__PORT__
+
+with:
+
+('HOST' | 'IPADDR')::
+ Binding hostname or IP address (IPv6 address *must* be enclosed in
+ brackets (`[` and `]`); see
+ https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).
+
+'PORT'::
+ TCP port.
+
+
+OPTIONS
+-------
+Daemon
+~~~~~~
+option:-b, option:--background::
+ Start as Unix daemon, but keep file descriptors (console) open.
+ Use the option:--daemonize option instead to close the file
+ descriptors.
+
+option:-d, option:--daemonize::
+ Start as Unix daemon, and close file descriptors (console). Use the
+ option:--background option instead to keep the file descriptors
+ open.
+
+option:-g, option:--group='GROUP'::
+ Use 'GROUP' as Unix tracing group (default: `tracing`).
+
+option:-o, option:--output='PATH'::
+ Set base directory of written trace data to 'PATH'.
++
+See the <<output-directory,Output directory>> section above for more
+information.
+
+option:-v, option:--verbose::
+ Increase verbosity.
++
+Three levels of verbosity are available, which are triggered by
+appending additional `v` letters to the option
+(that is, `-vv` and `-vvv`).
+
+
+Ports
+~~~~~
+See the <<url-format,URL format>> section above for more information
+about the syntax of the following options' 'URL' argument.
+
+option:-C, option:--control-port='URL'::
+ Listen to control data on URL 'URL' (default: `tcp://0.0.0.0:5342`).
+
+option:-D, option:--data-port='URL'::
+ Listen to trace data on URL 'URL' (default: `tcp://0.0.0.0:5343`).
+
+option:-L, option:--live-port='URL'::
+ Listen to LTTng live connections on URL 'URL'
+ (default: `tcp://0.0.0.0:5344`).
+
+
+Program information
+~~~~~~~~~~~~~~~~~~~
+option:-h, option:--help::
+ Show help.
+
+option:-V, option:--version::
+ Show version.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+`LTTNG_NETWORK_SOCKET_TIMEOUT`::
+ Socket connection, receive and send timeout (milliseconds). A value
+ of 0 or -1 uses the timeout of the operating system (default).
+
+`LTTNG_RELAYD_HEALTH`::
+ Path to relay daemon health's socket.
+
+
+EXIT STATUS
+-----------
+*0*::
+ Success
+
+*1*::
+ Error
+
+*3*::
+ Fatal error
+
+
+LIMITATIONS
+-----------
+As of this version, only the TCP protocol is supported for both control
+and data ports. In future versions, TCP will remain the sole available
+protocol for control data since those communications are low-volume and
+need absolute reliability; trace data could be carried over UDP.
+
+For an unprivileged user running `lttng-relayd`, the maximum number of
+file descriptors per process is usually 1024. This limits the number of
+connections and opened trace files. This limit can be configured with
+*ulimit*(3).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng(1),
+linklttng:lttng-sessiond(8),
+linklttng:lttng-crash(1),
+linklttng:lttng-ust(3),
+linklttng:babeltrace(1)
--- /dev/null
+lttng-save(1)
+=============
+
+
+NAME
+----
+lttng-save - Save LTTng tracing session configurations
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *save* [option:--force] [option:--output-path='PATH'] ['SESSION']
+
+
+DESCRIPTION
+-----------
+The `lttng save` command saves the configurations of one or more
+tracing sessions to files.
+
+The `lttng save` command is used in conjunction with the
+linklttng:lttng-load(1) command to save and restore the complete
+configurations of tracing sessions. This includes the enabled channels
+and event rules, the context added to channels, the tracing activity,
+and more. `lttng save` does not save tracing data, only the tracing
+session parameters.
+
+If 'SESSION' is omitted, all the existing tracing session configurations
+are saved (equivalent to using the option:--all option). Otherwise,
+'SESSION' is the name of an existing tracing session. `lttng list`
+outputs all the existing tracing sessions (see linklttng:lttng-list(1)).
+
+The default output directory path is `$LTTNG_HOME/.lttng/sessions`
+(`$LTTNG_HOME` defaults to `$HOME`). Each tracing session configuration
+file is named `SESSION.lttng`, where `SESSION` is the original tracing
+session name. The default output directory path can be overridden with
+the option:--output-path option.
+
+By default, existing tracing session configuration files are not
+overwritten when saving; the command fails. The option:--force option
+can be used to allow this.
+
+
+include::common-cmd-options-head.txt[]
+
+
+option:-a, option:--all::
+ Save all tracing session configurations (default).
+
+option:-f, option:--force::
+ Overwrite existing tracing session configuration files when
+ saving.
+
+option:-o, option:--output-path='PATH'::
+ Set output directory path to 'PATH'.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng-load(1),
+linklttng:lttng(1)
+++ /dev/null
-.TH "LTTNG-SESSIOND" "8" "January 31, 2012" "" ""
-
-.SH "NAME"
-lttng-sessiond \- LTTng 2.x central tracing registry session daemon.
-
-.SH "SYNOPSIS"
-
-.PP
-.nf
-lttng-sessiond [OPTIONS]
-.fi
-.SH "DESCRIPTION"
-
-.PP
-The LTTng project aims at providing highly efficient tracing tools for Linux.
-It's tracers help tracking down performance issues and debugging problems
-involving multiple concurrent processes and threads. Tracing across multiple
-systems is also possible.
-
-The session daemon, acting as a tracing registry, allow you to interact with
-multiple tracers (kernel and user-space) inside the same container, a tracing
-session. Trace can be gathered from the kernel and/or instrumented applications
-(lttng-ust(3)). Aggregating those traces is done using a viewer, like the
-babeltrace(1) text viewer.
-
-In order to trace the kernel, the session daemon needs to be running as root.
-LTTng provides the use of a \fBtracing group\fP (default: tracing). Whomever is
-in that group can interact with the root session daemon and thus trace the
-kernel. Session daemons can co-exist meaning that you can have a session daemon
-running as Alice that can be used to trace her applications along side with a
-root daemon or even a Bob daemon. We highly recommend to start the session
-daemon at boot time for stable and long term tracing.
-
-The session daemon is in charge of managing trace data consumers by spawning
-them when the time has come. The user don't need to manage the lttng-consumerd.
-.SH "OPTIONS"
-
-.PP
-This program follows the usual GNU command line syntax with long options starting
-with two dashes. Below is a summary of the available options.
-.PP
-
-.TP
-.BR "-h, --help"
-Show summary of possible options and commands
-.TP
-.BR "\-V, \-\-version"
-Show version.
-.TP
-.BR "-v, --verbose"
-Increase verbosity
-
-There is three debugging level which will print on stderr. Maximum verbosity is
-\fB-vvv\fP.
-.TP
-.BR " --verbose-consumer"
-Verbose mode for consumer. Activate DBG() macro.
-.TP
-.BR "-d, --daemonize"
-Start as a daemon
-.TP
-.BR "-b, --background"
-Start as a daemon, keeping console open
-.TP
-.BR "-g, --group=NAME"
-Specify the tracing group name. (default: tracing)
-.TP
-.BR "-V, --version"
-Show version number
-.TP
-.BR "-S, --sig-parent"
-Send SIGUSR1 to parent pid to notify readiness.
-
-This is used by \fBlttng(1)\fP to get notified when the session daemon is ready
-to accept command. When building a third party tool over liblttng-ctl, this option
-can be very handy to synchronize the control tool and the session daemon.
-.TP
-.BR "-q, --quiet"
-No output at all.
-.TP
-.BR " --no-kernel"
-No kernel tracer support
-.TP
-.BR " --agent-tcp-port"
-Agent application registration TCP port (default: 5345)
-.TP
-.BR " --kmod-probes=probe1, probe2, ..."
-Specify the kernel modules containing LTTng probes to load by the session daemon.
-Only the component name of the probe needs to be specified, e.g. to load the
-lttng-probe-irq and lttng-probe-sched use: --kmod-probes="irq, sched".
-.TP
-.BR " --extra-kmod-probes=probe1, probe2, ..."
-Specify extra kernel modules containing LTTng probes to be loaded by the session
-daemon. The list follows the format of the \fB--kmod-probes\fP option.
-This list is appended to the list provided by \fB--kmod-probes\fP or, if
-\fB--kmod-probes\fP is missing, to the default list of probes.
-.TP
-.BR "-c, --client-sock=PATH"
-Specify path for the client unix socket
-.TP
-.BR "-a, --apps-sock PATH"
-Specify path for apps unix socket
-.TP
-.BR " --kconsumerd-err-sock=PATH"
-Specify path for the kernel consumer error socket
-.TP
-.BR " --kconsumerd-cmd-sock=PATH
-Specify path for the kernel consumer command socket
-.TP
-.BR " --ustconsumerd32-err-sock=PATH
-Specify path for the 32-bit UST consumer error socket
-.TP
-.BR " --ustconsumerd64-err-sock=PATH
-Specify path for the 64-bit UST consumer error socket
-.TP
-.BR " --ustconsumerd32-cmd-sock=PATH
-Specify path for the 32-bit UST consumer command socket
-.TP
-.BR " --ustconsumerd64-cmd-sock=PATH
-Specify path for the 64-bit UST consumer command socket
-.TP
-.BR " --consumerd32-path=PATH
-Specify path for the 32-bit UST consumer daemon binary
-.TP
-.BR " --consumerd32-libdir=PATH
-Specify path for the 32-bit UST consumer daemon libraries
-.TP
-.BR " --consumerd64-path=PATH
-Specify path for the 64-bit UST consumer daemon binary
-.TP
-.BR " --consumerd64-libdir=PATH
-Specify path for the 64-bit UST consumer daemon libraries
-.TP
-.BR "-l, --load PATH
-Specify path from which to automatically load session configuration(s).
-.TP
-.BR "-f, --config PATH
-Specify path from which to load daemon configuration.
-
-.SH "LOADING SESSIONS"
-
-.PP
-By default, the session daemon tries to load session configuration(s) located
-in the user default directory \fB~/.lttng/sessions/auto/\fP and in the system
-wide one in \fB/etc/lttng/sessions/auto/\fP. Note that the directory containing
-the session's configuration and lttng-sessiond MUST have the same UID for them
-to be automatically loaded.
-
-Specifying a path with \-l, \-\-load PATH overrides the default directory and
-UID check. The lttng-sessiond will simply check if it's accessible and try to
-load every session file in it.
-.PP
-
-.SH "ENVIRONMENT VARIABLES"
-
-.PP
-Note that all command line options will override environment variables.
-.PP
-
-.PP
-.IP "LTTNG_CONSUMERD32_BIN"
-Specify the 32-bit consumer binary path. \fB--consumerd32-path\fP
-override this variable.
-.IP "LTTNG_CONSUMERD64_BIN"
-Specify the 64-bit consumer binary path. \fB--consumerd64-path\fP
-override this variable.
-.IP "LTTNG_CONSUMERD32_LIBDIR"
-Specify the 64-bit library path containing libconsumer.so.
-\fB--consumerd32-libdir\fP override this variable.
-.IP "LTTNG_CONSUMERD64_LIBDIR"
-Specify the 32-bit library path containing libconsumer.so.
-\fB--consumerd64-libdir\fP override this variable.
-.IP "LTTNG_DEBUG_NOCLONE"
-Debug-mode disabling use of clone/fork. Insecure, but required to allow
-debuggers to work with sessiond on some operating systems.
-.IP "LTTNG_APP_SOCKET_TIMEOUT"
-Control the timeout of application's socket when sending and receiving
-commands. Takes an integer parameter: the timeout value, in seconds.
-After this period of time, the application is unregistered by the
-session daemon. A value of 0 or -1 means an infinite timeout. Default
-value is 5 seconds.
-.IP "LTTNG_NETWORK_SOCKET_TIMEOUT"
-Control timeout of socket connection, receive and send. Takes an integer
-parameter: the timeout value, in milliseconds. A value of 0 or -1 uses
-the timeout of the operating system (this is the default).
-.IP "LTTNG_SESSION_CONFIG_XSD_PATH"
-Specify the path that contains the XML session configuration schema (xsd).
-.IP "LTTNG_KMOD_PROBES"
-Specify the kernel modules probes that should be loaded by the session daemon.
-.IP "LTTNG_EXTRA_KMOD_PROBES"
-Specify extra kernel modules probes that should be loaded by the session daemon.
-.SH "SEE ALSO"
-
-.PP
-babeltrace(1), lttng-ust(3), lttng(1)
-.PP
-
-.SH "LIMITATIONS"
-
-.PP
-For unprivileged user running lttng-sessiond, the maximum number of file
-descriptors per process is usually 1024. This limits the number of traceable
-applications since for each instrumented application there is two file
-descriptors per-CPU and one more socket for bidirectional communication.
-
-For the root user, the limit is bumped to 65535. Future version will deal with
-this limitation.
-.PP
-
-.SH "BUGS"
-
-.PP
-No show stopper bugs are known yet in this version.
-
-If you encounter any issues or usability problem, please report it on our
-mailing list <lttng-dev@lists.lttng.org> to help improve this project.
-.SH "CREDITS"
-
-.PP
-lttng-sessiond is distributed under the GNU General Public License version 2. See the
-file COPYING for details.
-.PP
-A Web site is available at http://lttng.org for more information on the LTTng
-project.
-.PP
-You can also find our git tree at http://git.lttng.org.
-.PP
-Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
-.PP
-You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
-.PP
-.SH "THANKS"
-
-.PP
-Thanks to Yannick Brosseau without whom this project would never have been so
-lean and mean! Also thanks to the Ericsson teams working on tracing which helped
-us greatly with detailed bug reports and unusual test cases.
-
-Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA
-maintainer) and Jon Bernard for our Debian packages.
-
-Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de
-Montreal for the LTTng journey.
-.PP
-.SH "AUTHORS"
-
-.PP
-lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and
-David Goulet. More people have since contributed to it. It is currently
-maintained by Jérémie Galarneau <jeremie.galarneau@efficios.com>.
-.PP
--- /dev/null
+lttng-sessiond(8)
+=================
+
+
+NAME
+----
+lttng-sessiond - LTTng 2 tracing session daemon
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng-sessiond* [option:--background | option:--daemonize] [option:--sig-parent]
+ [option:--config='PATH'] [option:--group='GROUP'] [option:--load='PATH']
+ [option:--agent-tcp-port='PORT']
+ [option:--apps-sock='PATH'] [option:--client-sock='PATH']
+ [option:--no-kernel | [option:--kmod-probes='PROBE'[,'PROBE']...]
+ [option:--extra-kmod-probes='PROBE'[,'PROBE']...]
+ [option:--kconsumerd-err-sock='PATH']
+ [option:--kconsumerd-cmd-sock='PATH']]
+ [option:--ustconsumerd32-err-sock='PATH']
+ [option:--ustconsumerd64-err-sock='PATH']
+ [option:--ustconsumerd32-cmd-sock='PATH']
+ [option:--ustconsumerd64-cmd-sock='PATH']
+ [option:--consumerd32-path='PATH'] [option:--consumerd32-libdir='PATH']
+ [option:--consumerd64-path='PATH'] [option:--consumerd64-libdir='PATH']
+ [option:--quiet | [option:-v | option:-vv | option:-vvv] [option:--verbose-consumer]]
+
+
+DESCRIPTION
+-----------
+The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
+source software package used for correlated tracing of the Linux kernel,
+user applications, and user libraries.
+
+LTTng consists of Linux kernel modules (for Linux kernel tracing) and
+dynamically loaded libraries (for user application and library tracing).
+
+The _LTTng session daemon_ is a tracing registry which allows the user
+to interact with multiple tracers (kernel and user space) within the
+same container, a _tracing session_. Traces can be gathered from the
+Linux kernel and/or from instrumented applications (see
+linklttng:lttng-ust(3)). You can aggregate and read the events of LTTng
+traces using linklttng:babeltrace(1).
+
+To trace the Linux kernel, the session daemon needs to be running as
+`root`. LTTng uses a _tracing group_ to allow specific users to interact
+with the root session daemon. The default tracing group name is
+`tracing`. You can use the option:--group option to set the tracing
+group name to use.
+
+Session daemons can coexist. You can have a session daemon running as
+user Alice that can be used to trace her applications alongside a root
+session daemon or a session daemon running as user Bob.
+
+The LTTng session daemon manages trace data consumer daemons by spawning
+them when necessary. You do not need to manage the consumer daemons
+manually.
+
+NOTE: It is highly recommended to start the session daemon at boot time
+for stable and long-term tracing.
+
+
+Loading tracing session configurations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+By default, the LTTng session daemon tries to load tracing session
+configurations located in the user default directory
+`$HOME/.lttng/sessions` and in the system one, `/etc/lttng/sessions`.
+Note that both the directory containing the tracing session
+configurations and the session daemon binary _must_ have the same UID
+for the configurations to be automatically loaded.
+
+Specifying a path with the option:--load option overrides the default
+directory _and_ the UID check. The session daemon simply checks if the
+path is accessible and tries to load every tracing session configuration
+in it.
+
+
+OPTIONS
+-------
+Daemon configuration
+~~~~~~~~~~~~~~~~~~~~
+option:-b, option:--background::
+ Start as Unix daemon, but keep file descriptors (console) open.
+ Use the option:--daemonize option instead to close the file
+ descriptors.
+
+option:-d, option:--daemonize::
+ Start as Unix daemon, and close file descriptors (console). Use the
+ option:--background option instead to keep the file descriptors
+ open.
+
+option:-f, option:--config='PATH'::
+ Load session daemon configuration from path 'PATH'.
+
+option:-g, option:--group='GROUP'::
+ Use 'GROUP' as Unix tracing group (default: `tracing`).
+
+option:-l, option:--load='PATH'::
+ Automatically load tracing session configurations from path 'PATH'.
+
+option:-S, option:--sig-parent::
+ Send `SIGUSR1` to parent process to notify readiness.
++
+NOTE: This is used by linklttng:lttng(1) to get notified when the
+session daemon is ready to accept commands. When building a third party
+tool on liblttng-ctl, this option can be very handy to synchronize the
+control tool and the session daemon.
+
+
+Linux kernel tracing
+~~~~~~~~~~~~~~~~~~~~
+option:--extra-kmod-probes='PROBE'[,'PROBE']...::
+ Load specific LTTng Linux kernel modules when kernel tracing
+ is enabled (option:--no-kernel option is :not: specified), in
+ addition to loading the default list of LTTng kernel modules.
++
+Only the name of the probe needs to be specified, without the
+`lttng-probe-` prefix and without the kernel module extension suffix.
+For example, specify `sched` to load the `lttng-probe-sched.ko` kernel
+module.
+
+option:--kmod-probes='PROBE'[,'PROBE']...::
+ Only load specific LTTng Linux kernel modules when kernel tracing
+ is enabled (option:--no-kernel option is :not: specified).
++
+Only the name of the probe needs to be specified, without the
+`lttng-probe-` prefix and without the kernel module extension suffix.
+For example, specify `sched` to load the `lttng-probe-sched.ko` kernel
+module.
+
+option:--no-kernel::
+ Disable Linux kernel tracing.
+
+
+Paths and ports
+~~~~~~~~~~~~~~~
+option:--agent-tcp-port='PORT'::
+ Listen on TCP port 'PORT' for agent application registrations
+ (default: 5345).
+
+option:-a, option:--apps-sock='PATH'::
+ Set application Unix socket path to 'PATH'.
+
+option:-c, option:--client-sock='PATH'::
+ Set client Unix socket path to 'PATH'.
+
+option:--consumerd32-libdir='PATH'::
+ Set 32-bit consumer daemon library directory to 'PATH'.
+
+option:--consumerd32-path='PATH'::
+ Set 32-bit consumer daemon binary path to 'PATH'.
+
+option:--consumerd64-libdir='PATH'::
+ Set 64-bit consumer daemon library directory to 'PATH'.
+
+option:--consumerd64-path='PATH'::
+ Set 64-bit consumer daemon binary path to 'PATH'.
+
+option:--kconsumerd-cmd-sock='PATH'::
+ Set Linux kernel consumer daemon's command Unix socket path
+ to 'PATH'.
+
+option:--kconsumerd-err-sock='PATH'::
+ Set Linux kernel consumer daemon's error Unix socket path
+ to 'PATH'.
+
+option:--ustconsumerd32-cmd-sock='PATH'::
+ Set 32-bit consumer daemon's command Unix socket path to 'PATH'.
+
+option:--ustconsumerd64-cmd-sock='PATH'::
+ Set 64-bit consumer daemon's command Unix socket path to 'PATH'.
+
+option:--ustconsumerd32-err-sock='PATH'::
+ Set 32-bit consumer daemon's error Unix socket path to 'PATH'.
+
+option:--ustconsumerd64-err-sock='PATH'::
+ Set 64-bit consumer daemon's error Unix socket path to 'PATH'.
+
+
+Verbosity
+~~~~~~~~~
+option:-q, option:--quiet::
+ Suppress all messages, including warnings and errors.
+
+option:-v, option:--verbose::
+ Increase verbosity.
++
+Three levels of verbosity are available, which are triggered by
+appending additional `v` letters to the option
+(that is, `-vv` and `-vvv`).
+
+option:--verbose-consumer::
+ Increase verbosity of consumer daemons spawned by this session
+ daemon.
+
+
+Program information
+~~~~~~~~~~~~~~~~~~~
+option:-h, option:--help::
+ Show help.
+
+option:-V, option:--version::
+ Show version.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+Note that command-line options override their equivalent environment
+variable.
+
+`LTTNG_APP_SOCKET_TIMEOUT`::
+ Application socket's timeout (seconds) when sending/receiving
+ commands. After this period of time, the application is unregistered
+ by the session daemon. A value of 0 or -1 means an infinite timeout.
+ Default value: 5.
+
+`LTTNG_CONSUMERD32_BIN`::
+ 32-bit consumer daemon binary path.
++
+The option:--consumerd32-path option overrides this variable.
+
+`LTTNG_CONSUMERD32_LIBDIR`::
+ 32-bit consumer daemon library path.
++
+The option:--consumerd32-libdir option overrides this variable.
+
+`LTTNG_CONSUMERD64_BIN`::
+ 64-bit consumer daemon binary path.
++
+The option:--consumerd64-path option overrides this variable.
+
+`LTTNG_CONSUMERD64_LIBDIR`::
+ 64-bit consumer daemon library path.
++
+The option:--consumerd64-libdir option overrides this variable.
+
+`LTTNG_DEBUG_NOCLONE`::
+ Set to 1 to disable the use of `clone()`/`fork()`. Setting this
+ variable is considered insecure, but it is required to allow
+ debuggers to work with the session daemon on some operating systems.
+
+`LTTNG_EXTRA_KMOD_PROBES`::
+ Load specific LTTng Linux kernel modules when kernel tracing
+ is enabled (option:--no-kernel option is :not: specified), in
+ addition to loading the default list of LTTng kernel modules.
++
+The option:--extra-kmod-probes option overrides this variable.
+
+`LTTNG_KMOD_PROBES`::
+ Only load specific LTTng Linux kernel modules when kernel tracing
+ is enabled (option:--no-kernel option is :not: specified).
++
+The option:--kmod-probes option overrides this variable.
+
+`LTTNG_NETWORK_SOCKET_TIMEOUT`::
+ Socket connection, receive and send timeout (milliseconds). A value
+ of 0 or -1 uses the timeout of the operating system (default).
+
+`LTTNG_SESSION_CONFIG_XSD_PATH`::
+ Tracing session configuration XML schema definition (XSD) path.
+
+
+EXIT STATUS
+-----------
+*0*::
+ Success
+
+*1*::
+ Error
+
+*3*::
+ Fatal error
+
+
+LIMITATIONS
+-----------
+For an unprivileged user running `lttng-sessiond`, the maximum number of
+file descriptors per process is usually 1024. This limits the number of
+traceable applications, since for each instrumented application, there
+is two file descriptors per CPU and one more socket for bidirectional
+communication.
+
+For the root user, the limit is bumped to 65535. A future version will
+deal with this limitation.
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng(1),
+linklttng:lttng-relayd(8),
+linklttng:lttng-crash(1),
+linklttng:lttng-ust(3),
+linklttng:babeltrace(1)
--- /dev/null
+lttng-set-session(1)
+====================
+
+
+NAME
+----
+lttng-set-session - Set the current LTTng tracing session
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *set-session* 'SESSION'
+
+
+DESCRIPTION
+-----------
+The `lttng set-session` command sets the current tracing session.
+
+'SESSION' is the name of an existing tracing session. `lttng list`
+outputs all the existing tracing sessions (see linklttng:lttng-list(1)).
+
+The current tracing session is used by default when a session can be
+specified in other commands. See linklttng:lttng-create(1) for more
+information about the current tracing session.
+
+
+include::common-cmd-options-head.txt[]
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng-create(1),
+linklttng:lttng-destroy(1),
+linklttng:lttng(1)
--- /dev/null
+lttng-snapshot(1)
+=================
+
+
+NAME
+----
+lttng-snapshot - Take LTTng snapshots and configure snapshot outputs
+
+
+SYNOPSIS
+--------
+Add a snapshot output:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *snapshot add-output* [option:--max-size='SIZE']
+ [option:--name='NAME'] [option:--session='SESSION']
+ (option:--ctrl-url='URL' option:--data-url='URL' | 'URL')
+
+Remove a snapshot output:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *snapshot del-output* [option:--session='SESSION']
+ ('ID' | 'NAME')
+
+List current snapshot outputs:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *snapshot list-output* [option:--session='SESSION']
+
+Take a snapshot:
+
+[verse]
+*lttng* ['GENERAL OPTIONS'] *snapshot record* [option:--max-size='SIZE']
+ [option:--name='NAME'] [option:--session='SESSION']
+ (option:--ctrl-url='URL' option:--data-url='URL' | 'URL')
+
+
+DESCRIPTION
+-----------
+The `lttng snapshot` command manages the snapshot outputs and takes
+snapshots.
+
+A _snapshot_ is a dump of the current sub-buffers of all the channels
+of a given tracing session. When a snapshot is taken, the memory dump
+is sent to the registered snapshot outputs.
+
+The tracing session should be created in _snapshot mode_ to make sure
+taking snapshots is allowed. This is done at tracing session creation
+time using the linklttng:lttng-create(1) command.
+
+Note that, when a snapshot is taken, the sub-buffers are not cleared.
+This means that different recorded snapshots may contain the same
+events.
+
+
+Snapshot outputs
+~~~~~~~~~~~~~~~~
+Snapshot outputs are the destinations of snapshot files when a
+snapshot is taken using the `record` action.
+
+As of this version, only one snapshot output is allowed.
+
+A snapshot output can be added using the `add-output` action. The
+output destination URL is set using either the 'URL' positional
+argument, or both the option:--ctrl-url and option:--data-url options.
+See linklttng:lttng-create(1) to learn more about the URL format.
+
+A name can be assigned to an output when adding it using the
+option:--name option. This name is part of the names of the
+snapshot files written to this output.
+
+By default, the snapshot files can be as big as the sum of the
+sizes of all the sub-buffers or all the channels of the selected
+tracing session. The maximum total size of all the snapshot files can
+be configured using the option:--max-size option.
+
+Snapshot outputs can be listed using the `list-output` action.
+
+Snapshot outputs can be removed using the `del-output` action. The
+configured name can be used when removing an output, or an ID as
+listed by the `list-output` action.
+
+
+Taking a snapshot
+~~~~~~~~~~~~~~~~~
+Taking a snapshot of the current tracing session is as easy as:
+
+---------------------
+lttng snapshot record
+---------------------
+
+This writes the snapshot files to the configured output. It is possible
+to use a custom, unregistered output at record time using the same
+options supported by the `add-output` action.
+
+NOTE: Before taking a snapshot on a system with a high event throughput,
+it is recommended to first run `lttng stop` (see
+linklttng:lttng-stop(1)). Otherwise, the snapshot could contain "holes",
+the result of the tracers overwriting unconsumed trace packets during
+the record operation. After the snapshot is recorded, the tracers can be
+started again with `lttng start` (see linklttng:lttng-start(1)).
+
+
+include::common-cmd-options-head.txt[]
+
+
+Target
+~~~~~~
+option:-s, option:--session='SESSION'::
+ Take a snapshot of the sub-buffers of the channels contained in
+ the tracing session named 'SESSION' instead of the current
+ tracing session.
+
+
+Snapshot output
+~~~~~~~~~~~~~~~
+option:-C, option:--ctrl-url='URL'::
+ Set control path URL to 'URL' (must use option:--data-url option
+ also).
+
+option:-D, option:--data-url='URL'::
+ Set data path URL to 'URL' (must use option:--ctrl-url option
+ also).
+
+option:-m, option:--max-size='SIZE'::
+ Limit the total size of all the snapshot files written when
+ recording a snapshot to 'SIZE' bytes. The `k` (kiB), `M` (MiB),
+ and `G` (GiB) suffixes are supported.
+
+option:-n, option:--name='NAME'::
+ Assign the name 'NAME' to the snapshot output.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng(1)
--- /dev/null
+lttng-start(1)
+==============
+
+
+NAME
+----
+lttng-start - Start LTTng tracers
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *start* ['SESSION']
+
+
+DESCRIPTION
+-----------
+The `lttng start` command starts the various LTTng tracers for a
+given inactive tracing session.
+
+Starting the LTTng tracers has the effect that all enabled event rules
+within enabled channels can make their target event sources _emit_ trace
+events. Whether they are recorded to the local file system, sent over
+the network, or not recorded at all depends on the specific
+configuration of the tracing session in which tracing is started. See
+linklttng:lttng-create(1) for different session modes.
+
+A tracing session with running tracers is said to be _active_. Active
+tracing sessions can return to the inactive state using the
+linklttng:lttng-stop(1) command.
+
+If 'SESSION' is omitted, the LTTng tracers are started for the current
+tracing session (see linklttng:lttng-create(1) for more information
+about the current tracing session). Otherwise, they are started for the
+existing tracing session named 'SESSION'. `lttng list`
+outputs all the existing tracing sessions (see linklttng:lttng-list(1)).
+
+
+include::common-cmd-options-head.txt[]
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng-stop(1),
+linklttng:lttng(1)
--- /dev/null
+lttng-status(1)
+===============
+
+
+NAME
+----
+lttng-status - Get the current LTTng tracing session's status
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *status*
+
+
+DESCRIPTION
+-----------
+The `lttng status` command shows the status of the current
+tracing session.
+
+This command is the exact equivalent of:
+
+---------------------
+lttng list CURSESSION
+---------------------
+
+where `CURSESSION` is the name of the current tracing session.
+Use linklttng:lttng-set-session(1) to set the current tracing session.
+
+
+include::common-cmd-options-head.txt[]
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng-set-session(1),
+linklttng:lttng(1)
--- /dev/null
+lttng-stop(1)
+=============
+
+
+NAME
+----
+lttng-stop - Stop LTTng tracers
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *stop* [option:--no-wait] ['SESSION']
+
+
+DESCRIPTION
+-----------
+The `lttng stop` command stops the various LTTng tracers for a given
+active tracing session.
+
+Stoping the LTTng tracers has the effect that all enabled event rules
+within enabled channels cannot make event sources _emit_ trace events
+anymore.
+
+A tracing session with no running tracers is said to be _inactive_.
+Inactive tracing sessions can be set active using the
+linklttng:lttng-start(1) command.
+
+If 'SESSION' is omitted, the LTTng tracers are stopped for the current
+tracing session (see linklttng:lttng-create(1) for more information
+about the current tracing session). Otherwise, they are stopped for the
+existing tracing session named 'SESSION'. `lttng list`
+outputs all the existing tracing sessions (see linklttng:lttng-list(1)).
+
+By default, the `lttng stop` command ensures that the tracing session's
+trace data is valid before returning to the prompt. With the
+option:--no-wait option, the command finishes immediately, hence a local
+trace might not be valid when the command is done. In this case, there
+is no way to know when the trace becomes valid.
+
+
+include::common-cmd-options-head.txt[]
+
+
+option:-n, option:--no-wait::
+ Do not ensure that the chosen tracing session's trace data is valid
+ before returning to the prompt.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng-start(1),
+linklttng:lttng(1)
--- /dev/null
+lttng-track(1)
+==============
+
+
+NAME
+----
+lttng-track - Add one or more entries to an LTTng resource tracker
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *track* (option:--kernel | option:--userspace)
+ [option:--session='SESSION'] (option:--pid='PID'[,'PID']... | option:--all option:--pid)
+
+
+DESCRIPTION
+-----------
+The `lttng track` commands adds one or more entries to a
+resource tracker.
+
+A resource tracker is a _whitelist_ of resources. Tracked resources are
+allowed to emit events, provided those events are targeted by enabled
+event rules (see linklttng:lttng-enable-event(1)).
+
+Tracker entries can be removed from the whitelist with
+linklttng:lttng-untrack(1).
+
+As of this version, the only available tracker is the *PID tracker*. The
+process ID (PID) tracker follows one or more process IDs; only the
+processes with a tracked PID are allowed to emit events. By default, all
+possible PIDs on the system are tracked: any process may emit enabled
+events (equivalent of `lttng track --pid --all` for all domains).
+
+With the PID tracker, it is possible, for example, to record all system
+calls called by a given process:
+
+-------------------------------------------
+lttng enable-event --kernel --all --syscall
+lttng track --kernel --pid=2345
+lttng start
+-------------------------------------------
+
+If all the PIDs are tracked (i.e. `lttng track --pid --all`, which is
+the default state of all domains when creating a tracing session), then
+using the track command with one or more specific PIDs has the effect of
+first removing all the PIDs from the whitelist, then adding the
+specified PIDs.
+
+
+Example
+~~~~~~~
+Assume the maximum system PID is 7 for this example.
+
+Initial whitelist:
+
+-------------------------------
+[0] [1] [2] [3] [4] [5] [6] [7]
+-------------------------------
+
+Command:
+
+-----------------------------------
+lttng track --userspace --pid=3,6,7
+-----------------------------------
+
+Whitelist:
+
+-------------------------------
+[ ] [ ] [ ] [3] [ ] [ ] [6] [7]
+-------------------------------
+
+Command:
+
+---------------------------------
+lttng untrack --userspace --pid=7
+---------------------------------
+
+Whitelist:
+
+-------------------------------
+[ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
+-------------------------------
+
+Command:
+
+---------------------------------
+lttng track --userspace --pid=1,5
+---------------------------------
+
+Whitelist:
+
+-------------------------------
+[ ] [1] [ ] [3] [ ] [5] [6] [ ]
+-------------------------------
+
+It should be noted that the PID tracker tracks the numeric process IDs.
+Should a process with a given ID exit and another process be given this
+ID, then the latter would also be allowed to emit events.
+
+See the linklttng:lttng-untrack(1) for more details about removing
+entries.
+
+
+include::common-cmd-options-head.txt[]
+
+
+Domain
+~~~~~~
+One of:
+
+option:-k, option:--kernel::
+ Track resources in the Linux kernel domain.
+
+option:-u, option:--userspace::
+ Track resources in the user space domain.
+
+
+Target
+~~~~~~
+option:-s, option:--session='SESSION'::
+ Track resources in the tracing session named 'SESSION' instead of
+ the current tracing session.
+
+
+Tracking
+~~~~~~~~
+option:-a, option:--all::
+ Used in conjunction with an empty option:--pid option: track _all_
+ process IDs (add all entries to the whitelist).
+
+option:-p, option:--pid[='PID'[,'PID']...]::
+ Track process IDs 'PID' (add them to the current whitelist).
++
+The 'PID' argument must be omitted when also using the option:--all
+option.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng-untrack(1),
+linklttng:lttng(1)
--- /dev/null
+lttng-untrack(1)
+================
+
+
+NAME
+----
+lttng-untrack - Remove one or more entries from an LTTng resource tracker
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *untrack* (option:--kernel | option:--userspace)
+ [option:--session='SESSION'] (option:--pid='PID'[,'PID']... | option:--all option:--pid)
+
+
+DESCRIPTION
+-----------
+The `lttng untrack` commands removes one or more entries from a
+resource tracker.
+
+See linklttng:lttng-track(1) to learn more about LTTng trackers.
+
+The untrack command removes specific resources from a tracker. The
+resources to remove must have been precedently added by
+linklttng:lttng-track(1). It is also possible to remove all the
+resources from the whitelist using the option:--all option.
+
+As of this version, the only available tracker is the PID tracker.
+
+
+Example
+~~~~~~~
+One common operation is to create a tracing session
+(see linklttng:lttng-create(1)), remove all the entries from the PID
+tracker whitelist, start tracing, and then manually track PIDs
+while tracing is active.
+
+Assume the maximum system PID is 7 for this example.
+
+Command:
+
+------------
+lttng create
+------------
+
+Initial whitelist:
+
+-------------------------------
+[0] [1] [2] [3] [4] [5] [6] [7]
+-------------------------------
+
+Command:
+
+-------------------------------------
+lttng untrack --userspace --pid --all
+-------------------------------------
+
+Whitelist:
+
+-------------------------------
+[ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
+-------------------------------
+
+Commands:
+
+----------------------------------
+lttng enable-event --userspace ...
+lttng start
+...
+lttng track --userspace --pid=3,5
+----------------------------------
+
+Whitelist:
+
+-------------------------------
+[ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
+-------------------------------
+
+Command:
+
+-------------------------------
+lttng track --userspace --pid=2
+-------------------------------
+
+Whitelist:
+
+-------------------------------
+[ ] [ ] [2] [3] [ ] [5] [ ] [ ]
+-------------------------------
+
+
+include::common-cmd-options-head.txt[]
+
+
+Domain
+~~~~~~
+One of:
+
+option:-k, option:--kernel::
+ Untrack resources tracked in the Linux kernel domain.
+
+option:-u, option:--userspace::
+ Untrack resources tracked in the user space domain.
+
+
+Target
+~~~~~~
+option:-s, option:--session='SESSION'::
+ Untrack resources in the tracing session named 'SESSION' instead of
+ the current tracing session.
+
+
+Untracking
+~~~~~~~~~~
+option:-a, option:--all::
+ Used in conjunction with an empty option:--pid option: untrack _all_
+ process IDs (clear the whitelist).
+
+option:-p, option:--pid[='PID'[,'PID']...]::
+ Untrack process IDs 'PID' (remove them from the current whitelist).
++
+The 'PID' argument must be omitted when also using the option:--all
+option.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng-track(1),
+linklttng:lttng(1)
--- /dev/null
+lttng-version(1)
+================
+
+
+NAME
+----
+lttng-version - Get the version of LTTng-tools
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *version*
+
+
+DESCRIPTION
+-----------
+The `lttng version` command outputs the version of LTTng-tools.
+
+The output of `lttng version` is broke down into the following parts:
+
+* Major, minor, and patch numbers
+* Git commit information, if available
+* Release name with its description
+* LTTng project's website URL
+* License information
+
+
+include::common-cmd-options-head.txt[]
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng(1)
--- /dev/null
+lttng-view(1)
+=============
+
+
+NAME
+----
+lttng-view - View the traces of an LTTng tracing session
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['GENERAL OPTIONS'] *view* [option:--viewer='CMD'] [option:--trace-path='PATH' | 'SESSION']
+
+
+DESCRIPTION
+-----------
+The `lttng view` command launches an external trace viewer to view the
+current trace of a tracing session.
+
+If 'SESSION' is omitted, the viewer is launched for the current tracing
+session (see linklttng:lttng-create(1) for more information
+about the current tracing session). Otherwise, it is launched for the
+existing tracing session named 'SESSION'. `lttng list`
+outputs all the existing tracing sessions (see linklttng:lttng-list(1)).
+
+By default, the linklttng:babeltrace(1) trace viewer is launched.
+Another trace viewer command can be specified using the
+option:--viewer option.
+
+By default, the trace path of the chosen tracing session is given
+as the first positional argument to the trace viewer. This path can
+be overridden using the option:--trace-path option.
+
+
+include::common-cmd-options-head.txt[]
+
+
+option:-t, option:--trace-path='PATH'::
+ View trace at path 'PATH' instead of using the chosen tracing
+ session's trace path.
+
+option:-e, option:--viewer='CMD'::
+ Use 'CMD' as the trace viewer.
+
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng(1)
+++ /dev/null
-.TH "LTTNG" "1" "May 13th, 2014" "" ""
-
-.SH "NAME"
-lttng \- LTTng 2.x tracer control command line tool
-
-.SH "SYNOPSIS"
-
-.PP
-lttng [OPTIONS] <COMMAND>
-.SH "DESCRIPTION"
-
-.PP
-The LTTng project aims at providing highly efficient tracing tools for Linux.
-Its tracers help track down performance issues and debug problems
-involving multiple concurrent processes and threads. Tracing across multiple
-systems is also possible.
-
-The \fBlttng\fP command line tool from the lttng-tools package is used to control
-both kernel and user-space tracing. Every interaction with the tracer should
-be done by this tool or by the liblttng-ctl library provided by the lttng-tools
-package.
-
-LTTng uses a session daemon (lttng-sessiond(8)), acting as a tracing registry,
-which allows you to interact with multiple tracers (kernel and user-space)
-inside the same container, a tracing session. Traces can be gathered from the
-kernel and/or instrumented applications (lttng-ust(3)). Aggregating and reading
-those traces is done using the babeltrace(1) text viewer.
-
-We introduce the notion of \fBtracing domains\fP which is essentially a type of
-tracer (kernel, user space, JUL, LOG4J or Python for now). In the future, we
-could see more tracer like for instance an hypervisor. For some commands,
-you'll need to specify on which domain the command operates (\-u, \-k, \-l, \-j
-or \-p). For instance, the kernel domain must be specified when enabling a
-kernel event.
-
-In order to trace the kernel, the session daemon needs to be running as root.
-LTTng provides the use of a \fBtracing group\fP (default: tracing). Whomever is
-in that group can interact with the root session daemon and thus trace the
-kernel. Session daemons can co-exist, meaning that you can have a session daemon
-running as Alice that can be used to trace her applications along side with a
-root daemon or even a Bob daemon. We highly recommend starting the session
-daemon at boot time for stable and long term tracing.
-
-Each user-space application instrumented with lttng-ust(3) will automatically
-register with the root session daemon and its user session daemon. This allows
-each daemon to list the available traceable applications and tracepoints at any
-given moment (See the \fBlist\fP command).
-.SH "OPTIONS"
-
-.PP
-This program follows the usual GNU command line syntax with long options starting with
-two dashes. Below is a summary of the available options.
-.PP
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-V, \-\-version"
-Show version.
-.TP
-.BR "\-v, \-\-verbose"
-Increase verbosity.
-Three levels of verbosity are available which are triggered by putting additional v to
-the option (\-vv or \-vvv)
-.TP
-.BR "\-q, \-\-quiet"
-Suppress all messages (even errors).
-.TP
-.BR "\-g, \-\-group NAME"
-Set unix tracing group name. (default: tracing)
-.TP
-.BR "\-n, \-\-no-sessiond"
-Don't automatically spawn a session daemon.
-.TP
-.BR "\-\-sessiond\-path PATH"
-Set session daemon full binary path.
-.TP
-.BR "\-\-list\-options"
-Simple listing of lttng options.
-.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
-\fBadd-context\fP [OPTIONS]
-.RS
-Add context to event(s) and/or channel(s).
-
-A context is basically extra information appended to a channel. For instance,
-you could ask the tracer to add the PID information for all events in a
-channel. You can also add performance monitoring unit counters (perf PMU) using
-the perf kernel API.
-
-For example, this command will add the context information 'prio' and two per-CPU
-perf counters (hardware branch misses and cache misses), to all events in the trace
-data output:
-
-.nf
-# lttng add-context \-k \-t prio \-t perf:cpu:branch-misses \\
- \-t perf:cpu:cache-misses
-.fi
-
-Please take a look at the help (\-h/\-\-help) for a detailed list of available
-contexts.
-
-Perf counters are available as per-CPU ("perf:cpu:...") and per-thread
-("perf:thread:...") counters. Currently, per-CPU counters can only be
-used with the kernel tracing domain, and per-thread counters can only be
-used with the UST tracing domain.
-
-If no channel is given (\-c), the context is added to all channels that were
-already enabled. If the session has no channel, a default channel is created.
-Otherwise the context will be added only to the given channel (\-c).
-
-If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
-file.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-s, \-\-session NAME"
-Apply on session name.
-.TP
-.BR "\-c, \-\-channel NAME"
-Apply on channel name.
-.TP
-.BR "\-k, \-\-kernel"
-Apply for the kernel tracer
-.TP
-.BR "\-u, \-\-userspace"
-Apply for the user-space tracer
-.TP
-.BR "\-t, \-\-type TYPE"
-Context type. You can repeat this option on the command line. Please
-use "lttng add-context \-h" to list all available types.
-.RE
-.PP
-
-.PP
-\fBcalibrate\fP [OPTIONS]
-.RS
-Quantify LTTng overhead
-
-The LTTng calibrate command can be used to find out the combined average
-overhead of the LTTng tracer and the instrumentation mechanisms used. This
-overhead can be calibrated in terms of time or using any of the PMU performance
-counter available on the system.
-
-For now, the only calibration implemented is that of the kernel function
-instrumentation (kretprobes).
-
-* Calibrate kernel function instrumentation
-
-Let's use an example to show this calibration. We use an i7 processor with 4
-general-purpose PMU registers. This information is available by issuing dmesg,
-looking for "generic registers".
-
-This sequence of commands will gather a trace executing a kretprobe hooked on
-an empty function, gathering PMU counters LLC (Last Level Cache) misses
-information (see lttng add-context \-\-help to see the list of available PMU
-counters).
-
-.nf
-# lttng create calibrate-function
-# lttng enable-event calibrate \-\-kernel \\
- \-\-function lttng_calibrate_kretprobe
-# lttng add-context \-\-kernel \-t perf:cpu:LLC-load-misses \\
- \-t perf:cpu:LLC-store-misses \\
- \-t perf:cpu:LLC-prefetch-misses
-# lttng start
-# for a in $(seq 1 10); do \\
- lttng calibrate \-\-kernel \-\-function;
- done
-# lttng destroy
-# babeltrace $(ls \-1drt ~/lttng-traces/calibrate-function-* \\
- | tail \-n 1)
-.fi
-
-The output from babeltrace can be saved to a text file and opened in a
-spreadsheet (e.g. oocalc) to focus on the per-PMU counter delta between
-consecutive "calibrate_entry" and "calibrate_return" events. Note that these
-counters are per-CPU, so scheduling events would need to be present to account
-for migration between CPU. Therefore, for calibration purposes, only events
-staying on the same CPU must be considered.
-
-The average result, for the i7, on 10 samples:
-
-.nf
- Average Std.Dev.
-perf_LLC_load_misses: 5.0 0.577
-perf_LLC_store_misses: 1.6 0.516
-perf_LLC_prefetch_misses: 9.0 14.742
-.fi
-
-As we can notice, the load and store misses are relatively stable across runs
-(their standard deviation is relatively low) compared to the prefetch misses.
-We can conclude from this information that LLC load and store misses can be
-accounted for quite precisely, but prefetches within a function seems to behave
-too erratically (not much causality link between the code executed and the CPU
-prefetch activity) to be accounted for.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-k, \-\-kernel"
-Apply for the kernel tracer
-.TP
-.BR "\-u, \-\-userspace"
-Apply for the user-space tracer
-.TP
-.BR "\-\-function"
-Dynamic function entry/return probe (default)
-.RE
-.PP
-
-.PP
-\fBcreate\fP [NAME] [OPTIONS]
-.RS
-Create tracing session.
-
-A tracing session contains channel(s) which contains event(s). It is domain
-agnostic, meaning that channels and events can be enabled for the
-user-space tracer and/or the kernel tracer. It acts like a container
-aggregating multiple tracing sources.
-
-On creation, a \fB.lttngrc\fP file is created in your $HOME directory
-containing the current session name. If NAME is omitted, a session name is
-automatically created having this form: 'auto-yyyymmdd-hhmmss'.
-
-If no \fB\-o, \-\-output\fP is specified, the traces will be written in
-$HOME/lttng-traces.
-
-The $HOME environment variable can be overridden by defining the environment
-variable LTTNG_HOME. This is useful when the user running the commands has
-a non-writeable home directory.
-
-The session name MUST NOT contain the character '/'.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.TP
-.BR "\-o, \-\-output PATH"
-Specify output path for traces
-.TP
-.BR "\-\-no-output"
-Traces will not be output
-.TP
-.BR "\-\-snapshot"
-Set the session in snapshot mode. Created in no-output mode and uses the
-URL, if one is specified, as the default snapshot output. Every channel will be set
-in overwrite mode and with mmap output (splice not supported).
-.TP
-.BR "\-\-live [USEC]"
-Set the session exclusively in live mode. The parameter is the delay in micro
-seconds before the data is flushed and streamed. The live mode allows you to
-stream the trace and view it while it's being recorded by any tracer. For that,
-you need a lttng-relayd and this session requires a network URL (\-U or
-\-C/\-D). If no USEC nor URL is provided, the default is to use a timer value
-set to 1000000 and the network URL set to net://127.0.0.1.
-
-To read a live session, you can use babeltrace(1) or the live streaming
-protocol in doc/live-reading-protocol.txt. Here is an example:
-
-.nf
-$ lttng-relayd -o /tmp/lttng
-$ lttng create --live 200000 -U net://localhost
-$ lttng enable-event -a --userspace
-$ lttng start
-.fi
-
-After the start, you'll be able to read the events while they are being
-recorded in /tmp/lttng.
-
-.TP
-.BR "\-\-shm-path PATH"
-
-Path where shared memory holding buffers should be created. Useful
-when used with PRAMFS or other persistent memory filesystems to extract
-trace data in the event of a crash requiring a reboot.
-
-See the \fBlttng-crash(1)\fP utility for more information on crash recovery.
-
-.TP
-.BR "\-U, \-\-set-url=URL"
-Set URL for the consumer output destination. It is persistent for the
-session lifetime. Redo the command to change it. This will set both data
-and control URL for network.
-.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)
-.PP
-Using these options, each API call can be controlled individually. For
-instance, \-C does not enable the consumer automatically. You'll need the \-e
-option for that.
-
-.B URL FORMAT:
-
-proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH]
-
-Supported protocols are (proto):
-.TP
-.BR "file://..."
-Local filesystem full path.
-
-.TP
-.BR "net://..."
-This will use the default network transport layer which is TCP for both
-control (PORT1) and data port (PORT2). The default ports are
-respectively 5342 and 5343. Note that net[6]:// is not yet supported.
-
-.TP
-.BR "tcp[6]://..."
-Can only be used with -C and -D together
-
-NOTE: IPv6 address MUST be enclosed in brackets '[]' (rfc2732)
-
-.B EXAMPLES:
-
-.nf
-# lttng create -U net://192.168.1.42
-.fi
-Uses TCP and default ports for the given destination.
-
-.nf
-# lttng create -U net6://[fe80::f66d:4ff:fe53:d220]
-.fi
-Uses TCP, default ports and IPv6.
-
-.nf
-# lttng create s1 -U net://myhost.com:3229
-.fi
-Create session s1 and set its consumer to myhost.com on port 3229 for control.
-.RE
-.PP
-
-.PP
-\fBdestroy\fP [NAME] [OPTIONS]
-.RS
-Teardown tracing session
-
-Free memory on the session daemon and tracer side. It's gone!
-
-If NAME is omitted, the session name is taken from the .lttngrc file.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-a, \-\-all"
-Destroy all sessions
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.RE
-.PP
-
-.PP
-\fBenable-channel\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS]
-.RS
-Enable tracing channel
-
-To enable an event, you must enable both the event and the channel that
-contains it.
-
-If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
-file.
-
-Exactly one of \-k or -u must be specified.
-
-It is important to note that if a certain type of buffers is used, the session
-will be set with that type and all other subsequent channel needs to have the
-same type.
-
-Note that once the session has been started and enabled on the tracer side,
-it's not possible anymore to enable a new channel for that session.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show this help
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.TP
-.BR "\-s, \-\-session NAME"
-Apply on session name
-.TP
-.BR "\-k, \-\-kernel"
-Apply to the kernel tracer
-.TP
-.BR "\-u, \-\-userspace"
-Apply to the user-space tracer
-.TP
-.BR "\-\-discard"
-Discard event when subbuffers are full (default)
-.TP
-.BR "\-\-overwrite"
-Flight recorder mode: overwrites events when subbuffers are full. The
-number of subbuffer must be 2 or more.
-.TP
-.BR "\-\-subbuf-size SIZE"
-Subbuffer size in bytes {+k,+M,+G}.
-(default UST uid: 131072, UST pid: 4096, kernel: 262144, metadata: 4096)
-Rounded up to the next power of 2.
-
-The minimum subbuffer size, for each tracer, is the max value between
-the default above and the system page size. You can issue this command
-to get the current page size on your system: \fB$ getconf PAGE_SIZE\fP
-.TP
-.BR "\-\-num-subbuf NUM"
-Number of subbuffers. (default UST uid: 4, UST pid: 4, kernel: 4,
-metadata: 2) Rounded up to the next power of 2.
-.TP
-.BR "\-\-switch-timer USEC"
-Switch subbuffer timer interval in µsec.
-(default UST uid: 0, UST pid: 0, kernel: 0, metadata: 0)
-.TP
-.BR "\-\-read-timer USEC"
-Read timer interval in µsec.
-(default UST uid: 0, UST pid: 0, kernel: 200000, metadata: 0)
-.TP
-.BR "\-\-output TYPE"
-Channel output type. Possible values: mmap, splice
-(default UST uid: mmap, UST pid: mmap, kernel: splice, metadata: mmap)
-.TP
-.BR "\-\-buffers-uid"
-Use per UID buffer (\-u only). Buffers are shared between applications
-that have the same UID.
-.TP
-.BR "\-\-buffers-pid"
-Use per PID buffer (\-u only). Each application has its own buffers.
-.TP
-.BR "\-\-buffers-global"
-Use shared buffer for the whole system (\-k only)
-.TP
-.BR "\-C, \-\-tracefile-size SIZE"
-Maximum size of each tracefile within a stream (in bytes).
-0 means unlimited. (default: 0)
-Note: traces generated with this option may inaccurately report
-discarded events as of CTF 1.8.
-.TP
-.BR "\-W, \-\-tracefile-count COUNT"
-Used in conjunction with \-C option, this will limit the number of files
-created to the specified count. 0 means unlimited. (default: 0)
-
-.B EXAMPLES:
-
-.nf
-$ lttng enable-channel -k -C 4096 -W 32 chan1
-.fi
-For each stream, the maximum size of each trace file will be 4096 bytes and
-there will be a maximum of 32 different files. The file count is appended after
-the stream number as seen in the following example. The last trace file is
-smaller than 4096 since it was not completely filled.
-
-.nf
- ~/lttng-traces/[...]/chan1_0_0 (4096)
- ~/lttng-traces/[...]/chan1_0_1 (4096)
- ~/lttng-traces/[...]/chan1_0_2 (3245)
- ~/lttng-traces/[...]/chan1_1_0 (4096)
- ...
-.fi
-
-.nf
-$ lttng enable-channel -k -C 4096
-.fi
-This will create trace files of 4096 bytes and will create new ones as long as
-there is data available.
-.RE
-.PP
-
-.PP
-\fBenable-event\fP NAME[,NAME2,...] (\-k | \-u | \-j | \-l | \-p) [OPTIONS]
-.RS
-Enable tracing event
-
-A tracing event is always assigned to a channel. If \fB\-c, \-\-channel\fP is
-omitted, a default channel named '\fBchannel0\fP' is created and the event is
-added to it. If \fB\-c, \-\-channel\fP is omitted, but a non-default
-channel already exists within the session, an error is returned. For the
-user-space tracer, using \fB\-a, \-\-all\fP is the same as using the
-wildcard "*".
-
-If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
-file.
-
-.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 enables 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 "\-j, \-\-jul"
-Apply for Java application using Java Util Logging interface (JUL)
-.TP
-.BR "\-l, \-\-log4j"
-Apply for Java application using LOG4J
-.TP
-.BR "\-p, \-\-python"
-Apply for Python application using the logging module.
-.TP
-.BR "\-\-tracepoint"
-Tracepoint event (default). Userspace tracer supports wildcards at the end
-of string. Don't forget to quote to deal with bash expansion.
-e.g.:
-.nf
- "*"
- "app_component:na*"
-.fi
-.TP
-.BR "\-\-loglevel NAME"
-Tracepoint loglevel range from 0 to loglevel. Listed in the help (\-h).
-For the JUL domain, the loglevel ranges are detailed with the \-\-help
-option thus starting from SEVERE to FINEST.
-For the LOG4J domain, loglevels range from FATAL to TRACE which are also
-detailed in the help.
-For the Python domain, loglevels range from CRITICAL to DEBUG which are
-detailed in the help as well.
-.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.
-.TP
-.BR "\-\-filter 'expression'"
-Set a filter on a newly enabled event. Filter expression on event
-fields and context. The event will be recorded if the filter's
-expression evaluates to TRUE. Only specify on first activation of a
-given event within a session.
-Specifying a filter is 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.
-
-Expression examples:
-
-.nf
- 'intfield > 500 && intfield < 503'
- '(strfield == "test" || intfield != 10) && intfield > 33'
- 'doublefield > 1.1 && intfield < 5.3'
- 'enumfield == 1234'
-.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 sequence. Wildcard
-matches any sequence of characters, including an empty sub-string
-(matches 0 or more characters). Enumeration fields can currently only be
-compared as integers.
-
-Context information can be used for filtering. The examples below shows
-usage of context filtering on the process name (using a wildcard), process ID
-range, and unique thread ID. The process and thread IDs 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
-
-Context information is available to all filters whether or not the add-context
-command has been used to add it to the event's channel, as long as the context
-field exists for that domain. For example, the filter examples given above will
-never fail to link: no add-context is required for the event's channel.
-
-.TP
-.BR "\-x, \-\-exclude LIST"
-Add exclusions to UST tracepoints:
-Events that match any of the items in the comma-separated LIST are not
-enabled, even if they match a wildcard definition of the event.
-
-This option is also applicable with the \fB\-a, \-\-all\fP option,
-in which case all UST tracepoints are enabled except the ones whose
-names match any of the items in LIST.
-.RE
-.PP
-
-.PP
-\fBdisable-channel\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS]
-.RS
-Disable tracing channel
-
-Disabling a channel disables the tracing of all of the channel's events. A channel
-can be re-enabled by calling \fBlttng enable-channel NAME\fP again.
-
-If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
-file.
-
-.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 "\-k, \-\-kernel"
-Apply for the kernel tracer
-.TP
-.BR "\-u, \-\-userspace"
-Apply for the user-space tracer
-.RE
-.PP
-
-.PP
-\fBdisable-event\fP NAME[,NAME2,...] (\-k | \-u | \-j | \-l | \-p) [TYPE] [OPTIONS]
-.RS
-Disable tracing event
-
-The event, once disabled, can be re-enabled by calling \fBlttng enable-event
-NAME\fP again.
-
-If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
-file.
-
-If \fB\-c, \-\-channel\fP is omitted, the default channel name is used.
-If \fB\-c, \-\-channel\fP is omitted, but a non-default channel already
-exists within the session, an error is returned.
-
-.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-events"
-Disable all events. This does NOT ONLY 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
-.TP
-.BR "\-j, \-\-jul"
-Apply for Java application using Java Util Logging interface (JUL)
-.TP
-.BR "\-l, \-\-log4j"
-Apply for Java application using LOG4J
-.TP
-.BR "\-p, \-\-python"
-Apply for Python application using the logging module
-
-.TP
-.B TYPE (kernel domain only):
-
-.TP
-.BR "\-\-all"
-Disable event of all type
-.TP
-.BR "\-\-tracepoint"
-Disable event of type tracepoint
-.TP
-.BR "\-\-syscall"
-Disable event of type syscall
-.TP
-.BR "\-\-probe"
-Disable event of type probe
-.TP
-.BR "\-\-function"
-Disable event of type function
-.RE
-.PP
-
-.PP
-\fBlist\fP [OPTIONS] [SESSION [SESSION OPTIONS]]
-.RS
-List tracing session information.
-
-With no arguments, it will list available tracing session(s).
-
-With the session name, it will display the details of the session including
-the trace file path, the associated channels and their state (activated
-and deactivated), the activated events and more.
-
-With \-k alone, it will list all available kernel events (except the system
-calls events).
-With \-j alone, the available JUL event from registered application will be
-list. The event corresponds to the Logger name in the Java JUL application.
-With \-l alone, the available LOG4J event from registered application will be
-list. The event corresponds to the Logger name in the Java LOG4J application.
-With \-p alone, the available Python event from registered application will be
-list. The event corresponds to the Logger name in the Python application.
-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)
-.fi
-
-You can now enable any event listed by using the name :
-\fBust_tests_hello:tptest\fP.
-
-.B OPTIONS:
-
-.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.
-.TP
-.BR "\-j, \-\-jul"
-Apply for Java application using JUL
-.TP
-.BR "\-l, \-\-log4j"
-Apply for Java application using LOG4J
-.TP
-.BR "\-p, \-\-python"
-Apply for Python application using the logging module.
-.TP
-.BR "\-f, \-\-fields"
-List event fields
-
-.PP
-.B SESSION OPTIONS:
-
-.TP
-.BR "\-c, \-\-channel NAME"
-List details of a channel
-.TP
-.BR "\-d, \-\-domain"
-List available domain(s)
-.RE
-.PP
-
-.PP
-\fBload\fP [OPTIONS] [NAME]
-.RS
-Load tracing session configuration
-
-If NAME is omitted, all session configurations found in both the user's session
-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:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-a, \-\-all"
-Load all session configurations (default).
-.TP
-.BR "\-i, \-\-input-path PATH"
-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
-already exists.
-.RE
-.PP
-
-.PP
-\fBmetadata\fP [OPTIONS] ACTION
-.RS
-Metadata command for a LTTng session.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-
-.PP
-.B ACTION:
-
-.TP
-\fBregenerate\fP [-s <NAME>]
-Regenerate the metadata of a session. This allows the user to regenerate the
-metadata after a major NTP correction and that way update the clock offset from
-epoch in the metadata. Only works on kernel, UST per-uid and non-live sessions.
-.RE
-.PP
-
-.PP
-\fBsave\fP [OPTIONS] [SESSION]
-.RS
-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 (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:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-a, \-\-all"
-Save all session configurations (default).
-.TP
-.BR "\-o, \-\-output-path PATH"
-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.
-.RE
-.PP
-
-.PP
-\fBset-session\fP NAME [OPTIONS]
-.RS
-Set current session name
-
-Will change the session name in the .lttngrc file.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.RE
-.PP
-
-.PP
-\fBsnapshot\fP [OPTIONS] ACTION
-.RS
-Snapshot command for LTTng session.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-
-.PP
-.B ACTION:
-
-.TP
-\fBadd-output\fP [-m <SIZE>] [-s <NAME>] [-n <NAME>] <URL> | -C <URL> -D <URL>
-
-Setup and add a snapshot output for a session. Output is 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 output's ID. You can either specify the
-output by name or use its ID as returned by the list-output command.
-
-.TP
-\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
-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.
-
-.nf
-$ lttng snapshot 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*/
-
-.PP
-.B DETAILED ACTION OPTIONS
-
-.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 maximum size does not include the
-metadata file. Human readable format is accepted: {+k,+M,+G}. For instance,
-\-\-max-size 5M
-.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
-
-.PP
-\fBstart\fP [NAME] [OPTIONS]
-.RS
-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.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.RE
-.PP
-
-.PP
-\fBstop\fP [NAME] [OPTIONS]
-.RS
-Stop tracing
-
-It will stop tracing for all tracers for a specific tracing session. Before
-returning, the command checks for data availability meaning that it will wait
-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.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.TP
-.BR "\-\-no-wait"
-Don't wait for data availability.
-.RE
-.PP
-
-.PP
-\fBtrack\fP (-k | -u) --pid [PID1[,PID2[,...]]] [OPTIONS]
-.RS
-Adds one or more entries to a tracker
-
-The \fBtrack\fP command adds one or more entries to a tracker. A tracker is
-a whitelist of resources. Tracked resources are allowed to emit events, provided
-those events are enabled (see the \fBenable-event\fP command).
-
-Tracker entries can be removed from the whitelist with the
-\fBuntrack\fP command.
-
-As of this version, the only available tracker is the \fBPID tracker\fP. The
-process ID (PID) tracker follows one or more process IDs;
-only the processes with a tracked PID are allowed to emit events. By default,
-all possible PIDs on the system are tracked: any process may emit enabled
-events (equivalent of \fBlttng track \-\-pid \-\-all\fR for all domains).
-
-With the PID tracker, it is possible, for example, to record all system calls
-called by a given process:
-
-.nf
- $ lttng enable-event --kernel --all --syscall
- $ lttng track --kernel --pid 2345
- $ lttng start
-.fi
-
-If all the PIDs are tracked (i.e. \fBlttng track \-\-pid \-\-all\fR, which
-is the default state of all domains when creating a tracing session), then
-using the \fBtrack\fR command with one or more specific PIDs has the effect of
-first removing all the PIDs from the whitelist, then adding the specified PIDs.
-
-Assume the maximum PID is 7 for the following examples:
-
-.nf
- Initial whitelist: [0] [1] [2] [3] [4] [5] [6] [7]
-
- $ lttng track --userspace --pid 3,6,7
-
- Whitelist: [ ] [ ] [ ] [3] [ ] [ ] [6] [7]
-
- $ lttng untrack --userspace --pid 7
-
- Whitelist: [ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
-
- $ lttng track --userspace --pid 1,5
-
- Whitelist: [ ] [1] [ ] [3] [ ] [5] [6] [ ]
-.fi
-
-It should be noted that the PID tracker tracks the numeric process IDs.
-Should a process with a given ID exit and another process be given this
-ID, then the latter would also be allowed to emit events.
-
-See the \fBuntrack\fR command's documentation for more details about
-removing entries.
-
-.B OPTIONS:
-
-.TP
-.BR "\-s, \-\-session NAME"
-Apply to session name.
-.TP
-.BR "\-k, \-\-kernel"
-Apply to the kernel tracer.
-.TP
-.BR "\-u, \-\-userspace"
-Apply to the user space tracer.
-.TP
-.BR "\-p, \-\-pid [PIDS]"
-Track process IDs PIDS (add to whitelist).
-
-PIDS is a comma-separated list of PIDs to add to the PID tracker.
-
-The PIDS argument must be omitted when also using the \fB\-\-all\fP option.
-.TP
-.BR "\-a, \-\-all"
-Used in conjunction with an empty \fB\-\-pid\fP option: track all process IDs
-(add all entries to whitelist).
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.RE
-.PP
-
-.PP
-\fBuntrack\fP (-k | -u) --pid [PID1[,PID2[,...]]] [OPTIONS]
-.RS
-Removes one or more entries from a tracker
-
-See the \fBtrack\fP command's documentation to learn more about LTTng
-trackers.
-
-The \fBuntrack\fP command removes specific resources from a tracker. The
-resources to remove must have been precedently added by the
-\fBtrack\fP command. It is also possible to remove all the resources
-from the whitelist using the \fB\-\-all\fR option.
-
-As of this version, the only available tracker is the \fBPID tracker\fP.
-
-One common operation is to create a tracing session, remove all the entries
-from the PID tracker whitelist, start tracing, and then manually track PIDs
-while tracing is active.
-
-Assume the maximum PID is 7 for the following examples:
-
-.nf
- $ lttng create
-
- Initial whitelist: [0] [1] [2] [3] [4] [5] [6] [7]
-
- $ lttng untrack --userspace --pid --all
-
- Whitelist: [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
-
- $ lttng enable-event --userspace ...
- $ lttng start
- ...
- $ lttng track --userspace --pid 3,5
-
- Whitelist: [ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
-
- $ lttng track --userspace --pid 2
-
- Whitelist: [ ] [ ] [2] [3] [ ] [5] [ ] [ ]
-.fi
-
-See the \fBtrack\fR command's documentation for more details about
-adding entries.
-
-.B OPTIONS:
-
-.TP
-.BR "\-s, \-\-session NAME"
-Apply to session name.
-.TP
-.BR "\-k, \-\-kernel"
-Apply to the kernel tracer.
-.TP
-.BR "\-u, \-\-userspace"
-Apply to the user space tracer.
-.TP
-.BR "\-p, \-\-pid [PIDS]"
-Stop tracking process IDs PIDS (remove from whitelist).
-
-PIDS is a comma-separated list of PIDs to remove from the PID tracker.
-
-The PIDS argument must be omitted when also using the \fB\-\-all\fP option.
-.TP
-.BR "\-a, \-\-all"
-Used in conjunction with an empty \fB\-\-pid\fP option: stop tracking all
-process IDs (remove all entries from whitelist).
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.RE
-.PP
-
-.PP
-\fBversion\fP
-.RS
-Show version information
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.RE
-.PP
-
-.PP
-\fBview\fP [SESSION_NAME] [OPTIONS]
-.RS
-View traces of a tracing session. By default, the babeltrace viewer
-will be used for text viewing. If SESSION_NAME is omitted, the session
-name is taken from the .lttngrc file.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show this help
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.TP
-.BR "\-t, \-\-trace-path PATH"
-Trace directory path for the viewer
-.TP
-.BR "\-e, \-\-viewer CMD"
-Specify viewer and/or options to use This will completely override the
-default viewers so please make sure to specify the full command. The
-trace directory path of the session will be appended at the end to the
-arguments
-.RE
-.PP
-
-.SH "JUL/LOG4J DOMAIN"
-
-This section explains the JUL and LOG4J domain where JUL stands for Java Util
-Logging. You can use these by using the \fBliblttng-ust-<domain>-jni.so\fP from
-the lttng-ust(3) project.
-
-The LTTng Java Agent uses JNI to link the UST tracer to the Java application
-that uses the agent. Thus, it behaves similarly to the UST domain (\-u). When
-enabling events, you enable a Logger name that will then be mapped to a default
-UST tracepoint called \fBlttng_jul:<domain>_event\fP in the
-\fBlttng_<domain>_channel\fP. Using the lttng-ctl API, any JUL/LOG4J events
-must use the tracepoint event type (same as \-\-tracepoint).
-
-Because of the default immutable channel, the \fBenable-channel\fP command CAN
-NOT be used with the JUL and LOG4J domain thus not having any options.
-
-Also, loglevels are supported. Use \fBlttng enable-event \-h\fP to list them.
-Wildcards are NOT supported except the "*" meaning all events (same as \-a).
-
-Exactly like the UST domain, if the Java application has the same UID as you,
-you can trace it. Same goes for the tracing group accessing root applications.
-
-Finally, you can list every Logger name that are available from registered
-applications to the session daemon by using \fBlttng list \-j\fP or \fB\-l\fP.
-
-Here is an example on how to use the JUL domain.
-
-.nf
-$ lttng list -j
-[...]
-$ lttng create aSession
-$ lttng enable-event -s aSession -j MyCustomLoggerName
-$ lttng start
-.fi
-
-More information can be found in the lttng-ust documentation, see
-java-util-logging.txt
-.PP
-
-.SH "EXIT VALUES"
-.PP
-On success 0 is returned and a positive value on error. Value of 1 means a command
-error, 2 an undefined command, 3 a fatal error and 4 a command warning meaning that
-something went wrong during the command.
-
-Any other value above 10, please refer to
-.BR "<lttng/lttng-error.h>"
-for a detailed list or use lttng_strerror() to get a human readable string of
-the error code.
-.PP
-
-.SH "ENVIRONMENT VARIABLES"
-
-.PP
-Note that all command line options override environment variables.
-.PP
-
-.PP
-.IP "LTTNG_SESSIOND_PATH"
-Allows one to specify the full session daemon binary path to lttng command line
-tool. You can also use \-\-sessiond-path option having the same effect.
-.PP
-
-.PP
-.IP "LTTNG_SESSION_CONFIG_XSD_PATH"
-Set the path in which the \fBsession.xsd\fP session configuration schema may be
-found.
-.PP
-
-.SH "SEE ALSO"
-.BR babeltrace(1),
-.BR lttng-ust(3),
-.BR lttng-sessiond(8),
-.BR lttng-relayd(8),
-.BR lttng-crash(1),
-
-.SH "BUGS"
-
-.PP
-If you encounter any issues or usability problem, please report it on our
-mailing list <lttng-dev@lists.lttng.org> to help improve this project or
-at https://bugs.lttng.org which is a bug tracker.
-.PP
-
-.SH "CREDITS"
-
-.PP
-lttng is distributed under the GNU General Public License version 2. See the file
-COPYING for details.
-.PP
-A Web site is available at http://lttng.org for more information on the LTTng
-project.
-.PP
-You can also find our git tree at http://git.lttng.org.
-.PP
-Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
-.PP
-You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
-.PP
-.SH "THANKS"
-
-.PP
-Thanks to Yannick Brosseau without whom this project would never have been so
-lean and mean! Also thanks to the Ericsson teams working on tracing which
-helped us greatly with detailed bug reports and unusual test cases.
-
-Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA
-maintainer) and Jon Bernard for our Debian packages.
-
-Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de
-Montreal for the LTTng journey.
-.PP
-.SH "AUTHORS"
-
-.PP
-lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and
-David Goulet. More people have since contributed to it. It is currently
-maintained by Jérémie Galarneau <jeremie.galarneau@efficios.com>.
-.PP
--- /dev/null
+lttng(1)
+========
+
+
+NAME
+----
+lttng - LTTng 2 tracer control command-line tool
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* [option:--group='GROUP'] [option:--mi='TYPE'] [option:--no-sessiond | option:--sessiond-path='PATH']
+ [option:--quiet | option:-v | option:-vv | option:-vvv] 'COMMAND' ['COMMAND OPTIONS']
+
+
+DESCRIPTION
+-----------
+The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
+source software package used for correlated tracing of the Linux kernel,
+user applications, and user libraries.
+
+LTTng consists of Linux kernel modules (for Linux kernel tracing) and
+dynamically loaded libraries (for user application and library tracing).
+
+An LTTng _session daemon_, linklttng:lttng-sessiond(8), receives
+commands from the command-line interface `lttng` to control the LTTng
+tracers. All interactions with the LTTng tracers happen through the
+`lttng` tool or through the liblttng-ctl library shipped with the
+LTTng-tools package.
+
+A _tracing domain_ is a tracer category. There are five available
+domains. For some commands, the domain needs to be specified with a
+command-line option. The domain options are:
+
+option:-j, option:--jul::
+ Apply command to the `java.util.logging` (JUL) domain.
+
+option:-k, option:--kernel::
+ Apply command to the Linux kernel domain.
+
+option:-l, option:--log4j::
+ Apply command to the Apache log4j 1.2 (Java) domain.
+
+option:-p, option:--python::
+ Apply command to the Python domain.
+
+option:-u, option:--userspace::
+ Apply command to the user space domain.
+
+The LTTng session daemon is a tracing registry which allows the user to
+interact with multiple tracers (kernel and user space) within the same
+container, a _tracing session_. Traces can be gathered from the Linux
+kernel and/or from instrumented applications (see
+linklttng:lttng-ust(3)). You can aggregate and read the events of LTTng
+traces using linklttng:babeltrace(1).
+
+To trace the Linux kernel, the session daemon needs to be running as
+`root`. LTTng uses a _tracing group_ to allow specific users to interact
+with the root session daemon. The default tracing group name is
+`tracing`. You can use the option:--group option to set the tracing
+group name to use.
+
+Session daemons can coexist. You can have a session daemon running as
+user Alice that can be used to trace her applications alongside a root
+session daemon or a session daemon running as user Bob.
+
+NOTE: It is highly recommended to start the session daemon at boot time
+for stable and long-term tracing.
+
+User applications instrumented with LTTng automatically register to the
+root session daemon and to user session daemons. This allows any session
+daemon to list the available traceable applications and event sources
+(see linklttng:lttng-list(1)).
+
+By default, the linklttng:lttng-create(1) command automatically spawns a
+user session daemon if none is currently running. The
+option:--no-sessiond general option can be set to avoid this.
+
+
+OPTIONS
+-------
+option:-g, option:--group='GROUP'::
+ Use 'GROUP' as Unix tracing group (default: `tracing`).
+
+option:-m, option:--mi='TYPE'::
+ Print the command's result using the machine interface type 'TYPE'
+ instead of a human-readable output.
++
+Supported types: `xml`.
++
+The machine interface (MI) mode converts the traditional pretty-printing
+to a machine output syntax. The MI mode provides a change-resistant way
+to access information generated by the `lttng` command-line program.
++
+When using the MI mode, the data is printed to the standard output.
+Errors and warnings are printed on the standard error with the
+pretty-print default format.
++
+If any error occurs during the execution of a command, the return value
+of the command will be different than 0. In this case, `lttng` does
+:not: guarantee the syntax and data validity of the generated MI output.
++
+For the `xml` MI type, an XML schema definition (XSD) file used for
+validation is available: see the `src/common/mi_lttng.xsd` file in
+the LTTng-tools source tree.
+
+option:-n, option:--no-sessiond::
+ Do not automatically spawn a session daemon.
+
+option:-q, option:--quiet::
+ Suppress all messages, including warnings and errors.
+
+option:--sessiond-path='PATH'::
+ Set the session daemon binary's absolute path to 'PATH'.
+
+option:-v, option:--verbose::
+ Increase verbosity.
++
+Three levels of verbosity are available, which are triggered by
+appending additional `v` letters to the option
+(that is, `-vv` and `-vvv`).
+
+
+Program information
+~~~~~~~~~~~~~~~~~~~
+option:-h, option:--help::
+ Show help.
+
+option:--list-commands::
+ List available commands.
+
+option:--list-options::
+ List available general options.
+
+option:-V, option:--version::
+ Show version.
+
+
+COMMANDS
+--------
+The following commands also have their own option:--help option.
+
+
+Tracing sessions
+~~~~~~~~~~~~~~~~
+linklttng:lttng-create(1)::
+ Create a tracing session.
+
+linklttng:lttng-destroy(1)::
+ Tear down tracing sessions.
+
+linklttng:lttng-load(1)::
+ Load tracing session configurations.
+
+linklttng:lttng-metadata(1)::
+ Manage an LTTng tracing session's metadata generation.
+
+linklttng:lttng-save(1)::
+ Save tracing session configurations.
+
+linklttng:lttng-set-session(1)::
+ Set current tracing session.
+
+
+Channels
+~~~~~~~~
+linklttng:lttng-add-context(1)::
+ Add context fields to a channel.
+
+linklttng:lttng-disable-channel(1)::
+ Disable tracing channels.
+
+linklttng:lttng-enable-channel(1)::
+ Create or enable tracing channels.
+
+
+Event rules
+~~~~~~~~~~~
+linklttng:lttng-disable-event(1)::
+ Disable event rules.
+
+linklttng:lttng-enable-event(1)::
+ Create or enable event rules.
+
+
+Status
+~~~~~~
+linklttng:lttng-list(1)::
+ List tracing sessions, domains, channels, and events.
+
+linklttng:lttng-status(1)::
+ Get the status of the current tracing session.
+
+
+Control
+~~~~~~~
+linklttng:lttng-snapshot(1)::
+ Snapshot buffers of current tracing session.
+
+linklttng:lttng-start(1)::
+ Start tracing.
+
+linklttng:lttng-stop(1)::
+ Stop tracing.
+
+
+Resource tracking
+~~~~~~~~~~~~~~~~~
+linklttng:lttng-track(1)::
+ Track specific system resources.
+
+linklttng:lttng-untrack(1)::
+ Untrack specific system resources.
+
+
+Miscellaneous
+~~~~~~~~~~~~~
+linklttng:lttng-calibrate(1)::
+ Quantify LTTng overhead.
+
+linklttng:lttng-help(1)::
+ Display help information about a command.
+
+linklttng:lttng-version(1)::
+ Show version information.
+
+linklttng:lttng-view(1)::
+ Start trace viewer.
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+linklttng:lttng-sessiond(8),
+linklttng:lttng-relayd(8),
+linklttng:lttng-crash(1),
+linklttng:lttng-ust(3),
+linklttng:babeltrace(1)
--- /dev/null
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <xsl:template match="co">
+ <xsl:value-of select="concat('\','fB(',substring-after(@id,'-'),')','\','fR')"/>
+ </xsl:template>
+ <xsl:template match="calloutlist">
+ <xsl:value-of select="."/>
+ <xsl:text>sp </xsl:text>
+ <xsl:apply-templates/>
+ <xsl:text> </xsl:text>
+ </xsl:template>
+ <xsl:template match="callout">
+ <xsl:value-of select="concat('\','fB',substring-after(@arearefs,'-'),'. ','\','fR')"/>
+ <xsl:apply-templates/>
+ <xsl:value-of select="."/>
+ <xsl:text>br </xsl:text>
+ </xsl:template>
+</xsl:stylesheet>
--- /dev/null
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <xsl:template match="literal">
+ <xsl:text>\fB</xsl:text>
+ <xsl:value-of select="." />
+ <xsl:text>\fR</xsl:text>
+ </xsl:template>
+</xsl:stylesheet>
--- /dev/null
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <xsl:template match="ulink">
+ <xsl:apply-templates/>
+ </xsl:template>
+</xsl:stylesheet>
--- /dev/null
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <xsl:import href="manpage-base.xsl" />
+ <xsl:import href="manpage-bold-literal.xsl" />
+ <xsl:import href="manpage-ulinks.xsl" />
+
+ <!-- disable end notes -->
+ <xsl:param name="man.endnotes.are.numbered">0</xsl:param>
+</xsl:stylesheet>
--- /dev/null
+# Pretty printing macros.
+#
+# Author: Philippe Proulx <pproulx@efficios.com>
+
+# PPRINT_INIT(): initializes the pretty printing system.
+#
+# Use this macro before using any other PPRINT_* macro.
+AC_DEFUN([PPRINT_INIT], [
+ m4_define([PPRINT_CONFIG_TS], 50)
+ m4_define([PPRINT_CONFIG_INDENT], 2)
+ PPRINT_YES_MSG=yes
+ PPRINT_NO_MSG=no
+
+ # find tput, which tells us if colors are supported and gives us color codes
+ AC_PATH_PROG(pprint_tput, tput)
+
+ AS_IF([test -n "$pprint_tput"], [
+ AS_IF([test -n "$PS1" && test `"$pprint_tput" colors` -ge 8 && test -t 1], [
+ # interactive shell and colors supported and standard output
+ # file descriptor is opened on a terminal
+ PPRINT_COLOR_TXTBLK=`"$pprint_tput" setf 0`
+ PPRINT_COLOR_TXTBLU=`"$pprint_tput" setf 1`
+ PPRINT_COLOR_TXTGRN=`"$pprint_tput" setf 2`
+ PPRINT_COLOR_TXTCYN=`"$pprint_tput" setf 3`
+ PPRINT_COLOR_TXTRED=`"$pprint_tput" setf 4`
+ PPRINT_COLOR_TXTPUR=`"$pprint_tput" setf 5`
+ PPRINT_COLOR_TXTYLW=`"$pprint_tput" setf 6`
+ PPRINT_COLOR_TXTWHT=`"$pprint_tput" setf 7`
+ PPRINT_COLOR_BLD=`"$pprint_tput" bold`
+ PPRINT_COLOR_BLDBLK=$PPRINT_COLOR_BLD$PPRINT_COLOR_TXTBLK
+ PPRINT_COLOR_BLDBLU=$PPRINT_COLOR_BLD$PPRINT_COLOR_TXTBLU
+ PPRINT_COLOR_BLDGRN=$PPRINT_COLOR_BLD$PPRINT_COLOR_TXTGRN
+ PPRINT_COLOR_BLDCYN=$PPRINT_COLOR_BLD$PPRINT_COLOR_TXTCYN
+ PPRINT_COLOR_BLDRED=$PPRINT_COLOR_BLD$PPRINT_COLOR_TXTRED
+ PPRINT_COLOR_BLDPUR=$PPRINT_COLOR_BLD$PPRINT_COLOR_TXTPUR
+ PPRINT_COLOR_BLDYLW=$PPRINT_COLOR_BLD$PPRINT_COLOR_TXTYLW
+ PPRINT_COLOR_BLDWHT=$PPRINT_COLOR_BLD$PPRINT_COLOR_TXTWHT
+ PPRINT_COLOR_RST=`"$pprint_tput" sgr0`
+
+ # colored yes and no
+ PPRINT_YES_MSG="$PPRINT_COLOR_BLDGRN$PPRINT_YES_MSG$PPRINT_COLOR_RST"
+ PPRINT_NO_MSG="$PPRINT_COLOR_BLDRED$PPRINT_NO_MSG$PPRINT_COLOR_RST"
+
+ # subtitle color
+ PPRINT_COLOR_SUBTITLE=$PPRINT_COLOR_BLDCYN
+ ])
+ ])
+])
+
+# PPRINT_SET_INDENT(indent): sets the current indentation.
+#
+# Use PPRINT_INIT() before using this macro.
+AC_DEFUN([PPRINT_SET_INDENT], [
+ m4_define([PPRINT_CONFIG_INDENT], $1)
+])
+
+# PPRINT_SET_TS(ts): sets the current tab stop.
+#
+# Use PPRINT_INIT() before using this macro.
+AC_DEFUN([PPRINT_SET_TS], [
+ m4_define([PPRINT_CONFIG_TS], $1)
+])
+
+# PPRINT_SUBTITLE(subtitle): pretty prints a subtitle.
+#
+# The subtitle is put as is in a double-quoted shell string so the user
+# needs to escape ".
+#
+# Use PPRINT_INIT() before using this macro.
+AC_DEFUN([PPRINT_SUBTITLE], [
+ AS_ECHO("${PPRINT_COLOR_SUBTITLE}$1$PPRINT_COLOR_RST")
+])
+
+AC_DEFUN([_PPRINT_INDENT], [
+ m4_if(PPRINT_CONFIG_INDENT, 0, [
+ ], [
+ m4_for([pprint_i], 0, m4_eval(PPRINT_CONFIG_INDENT * 2 - 1), 1, [
+ AS_ECHO_N(" ")
+ ])
+ ])
+])
+
+# PPRINT_PROP_STRING(title, value, title_color?): pretty prints a
+# string property.
+#
+# The title is put as is in a double-quoted shell string so the user
+# needs to escape ".
+#
+# The $PPRINT_CONFIG_INDENT variable must be set to the desired indentation
+# level.
+#
+# Use PPRINT_INIT() before using this macro.
+AC_DEFUN([PPRINT_PROP_STRING], [
+ m4_pushdef([pprint_title], [$1])
+ m4_pushdef([pprint_value], [$2])
+
+ m4_if([$#], 3, [
+ m4_pushdef([pprint_title_color], [$3])
+ ], [
+ m4_pushdef([pprint_title_color], [])
+ ])
+
+ m4_pushdef([pprint_title_len], m4_len(pprint_title))
+ m4_pushdef([pprint_spaces_cnt], m4_eval(PPRINT_CONFIG_TS - pprint_title_len - (PPRINT_CONFIG_INDENT * 2) - 1))
+
+ m4_if(m4_eval(pprint_spaces_cnt <= 0), 1, [
+ m4_define([pprint_spaces_cnt], 1)
+ ])
+
+ m4_pushdef([pprint_spaces], [])
+
+ m4_for([pprint_i], 0, m4_eval(pprint_spaces_cnt - 1), 1, [
+ m4_append([pprint_spaces], [ ])
+ ])
+
+ _PPRINT_INDENT
+
+ AS_ECHO_N("pprint_title_color""pprint_title$PPRINT_COLOR_RST:pprint_spaces")
+ AS_ECHO("${PPRINT_COLOR_BLD}pprint_value$PPRINT_COLOR_RST")
+
+ m4_popdef([pprint_spaces])
+ m4_popdef([pprint_spaces_cnt])
+ m4_popdef([pprint_title_len])
+ m4_popdef([pprint_title_color])
+ m4_popdef([pprint_value])
+ m4_popdef([pprint_title])
+])
+
+# PPRINT_PROP_BOOL(title, value, title_color?): pretty prints a boolean
+# property.
+#
+# The title is put as is in a double-quoted shell string so the user
+# needs to escape ".
+#
+# The value is evaluated at shell runtime. Its evaluation must be
+# 0 (false) or 1 (true).
+#
+# Uses the PPRINT_PROP_STRING() with the "yes" or "no" string.
+#
+# Use PPRINT_INIT() before using this macro.
+AC_DEFUN([PPRINT_PROP_BOOL], [
+ m4_pushdef([pprint_title], [$1])
+ m4_pushdef([pprint_value], [$2])
+
+ test pprint_value -eq 0 && pprint_msg="$PPRINT_NO_MSG" || pprint_msg="$PPRINT_YES_MSG"
+
+ m4_if([$#], 3, [
+ PPRINT_PROP_STRING(pprint_title, $pprint_msg, $3)
+ ], [
+ PPRINT_PROP_STRING(pprint_title, $pprint_msg)
+ ])
+
+ m4_popdef([pprint_value])
+ m4_popdef([pprint_title])
+])
+
+# PPRINT_WARN(msg): pretty prints a warning message.
+#
+# The message is put as is in a double-quoted shell string so the user
+# needs to escape ".
+#
+# Use PPRINT_INIT() before using this macro.
+AC_DEFUN([PPRINT_WARN], [
+ m4_pushdef([pprint_msg], [$1])
+
+ _PPRINT_INDENT
+ AS_ECHO("${PPRINT_COLOR_TXTYLW}WARNING:$PPRINT_COLOR_RST ${PPRINT_COLOR_BLDYLW}pprint_msg$PPRINT_COLOR_RST")
+
+ m4_popdef([pprint_msg])
+])
+
+# PPRINT_ERROR(msg): pretty prints an error message and exits.
+#
+# The message is put as is in a double-quoted shell string so the user
+# needs to escape ".
+#
+# Use PPRINT_INIT() before using this macro.
+AC_DEFUN([PPRINT_ERROR], [
+ m4_pushdef([pprint_msg], [$1])
+
+ AC_MSG_ERROR(${PPRINT_COLOR_BLDRED}pprint_msg$PPRINT_COLOR_RST)
+
+ m4_popdef([pprint_msg])
+])
#include <version.h>
#include <lttng/lttng.h>
#include <common/common.h>
+#include <common/utils.h>
#define DEFAULT_VIEWER "babeltrace"
{ NULL, 0, NULL, 0 },
};
-static void usage(FILE *ofp)
+static void usage(void)
{
- fprintf(ofp, "LTTng Crash Trace Viewer " VERSION " - " VERSION_NAME "%s\n\n",
- GIT_VERSION[0] == '\0' ? "" : " - " GIT_VERSION);
- fprintf(ofp, "usage: lttng-crash [OPTIONS] FILE\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -V, --version Show version.\n");
- fprintf(ofp, " -h, --help Show this help.\n");
- fprintf(ofp, " --list-options Simple listing of lttng-crash options.\n");
- fprintf(ofp, " -v, --verbose Increase verbosity.\n");
- fprintf(ofp, " -e, --viewer Specify viewer and/or options to use. This will\n"
- " completely override the default viewers so please\n"
- " make sure to specify the full command. The trace\n"
- " directory paths appended at the end to the\n"
- " arguments.\n");
- fprintf(ofp, " -x, --extract PATH Extract trace(s) to specified path. Don't view\n"
- " trace.\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Please see the lttng-crash(1) man page for full documentation.\n");
- fprintf(ofp, "See http://lttng.org for updates, bug reports and news.\n");
+ int ret = utils_show_man_page(1, "lttng-crash");
+
+ if (ret) {
+ ERR("Cannot view man page lttng-crash(1)");
+ perror("exec");
+ exit(EXIT_FAILURE);
+ }
}
static void version(FILE *ofp)
int opt, ret = 0;
if (argc < 2) {
- usage(stderr);
+ usage();
exit(EXIT_FAILURE);
}
ret = 1;
goto end;
case 'h':
- usage(stdout);
+ usage();
ret = 1;
goto end;
case 'v':
ret = 1;
goto end;
default:
- usage(stderr);
+ ERR("Unknown command-line option");
goto error;
}
}
}
/* No leftovers, or more than one input path, print usage and quit */
- if ((argc - optind) == 0 || (argc - optind) > 1) {
- usage(stderr);
+ if (argc - optind != 1) {
+ ERR("Command-line error: Specify exactly one input path");
goto error;
}
static const char *config_ignore_options[] = { "help", "config" };
-/*
- * usage function on stderr
- */
-static void usage(void)
-{
- fprintf(stderr, "Usage: %s OPTIONS\n\nOptions:\n", progname);
- fprintf(stderr, " -h, --help Display this usage.\n");
- fprintf(stderr, " -d, --daemonize Start as a daemon.\n");
- fprintf(stderr, " -b, --background Start as a daemon, keeping console open.\n");
- fprintf(stderr, " -C, --control-port URL Control port listening.\n");
- fprintf(stderr, " -D, --data-port URL Data port listening.\n");
- fprintf(stderr, " -L, --live-port URL Live view port listening.\n");
- fprintf(stderr, " -o, --output PATH Output path for traces. Must use an absolute path.\n");
- fprintf(stderr, " -v, --verbose Verbose mode. Activate DBG() macro.\n");
- fprintf(stderr, " -g, --group NAME Specify the tracing group name. (default: tracing)\n");
- fprintf(stderr, " -f --config Load daemon configuration file\n");
-}
-
/*
* Take an option from the getopt output and set it in the right variable to be
* used later.
}
break;
case 'h':
- usage();
+ ret = utils_show_man_page(8, "lttng-relayd");
+ if (ret) {
+ ERR("Cannot view man page lttng-relayd(8)");
+ perror("exec");
+ }
exit(EXIT_FAILURE);
case 'o':
if (lttng_is_setuid_setgid()) {
return NULL;
}
-
-/*
- * usage function on stderr
- */
-static void usage(void)
-{
- fprintf(stderr, "Usage: %s OPTIONS\n\nOptions:\n", progname);
- fprintf(stderr, " -h, --help Display this usage.\n");
- fprintf(stderr, " -c, --client-sock PATH Specify path for the client unix socket\n");
- fprintf(stderr, " -a, --apps-sock PATH Specify path for apps unix socket\n");
- fprintf(stderr, " --kconsumerd-err-sock PATH Specify path for the kernel consumer error socket\n");
- fprintf(stderr, " --kconsumerd-cmd-sock PATH Specify path for the kernel consumer command socket\n");
- fprintf(stderr, " --ustconsumerd32-err-sock PATH Specify path for the 32-bit UST consumer error socket\n");
- fprintf(stderr, " --ustconsumerd64-err-sock PATH Specify path for the 64-bit UST consumer error socket\n");
- fprintf(stderr, " --ustconsumerd32-cmd-sock PATH Specify path for the 32-bit UST consumer command socket\n");
- fprintf(stderr, " --ustconsumerd64-cmd-sock PATH Specify path for the 64-bit UST consumer command socket\n");
- fprintf(stderr, " --consumerd32-path PATH Specify path for the 32-bit UST consumer daemon binary\n");
- fprintf(stderr, " --consumerd32-libdir PATH Specify path for the 32-bit UST consumer daemon libraries\n");
- fprintf(stderr, " --consumerd64-path PATH Specify path for the 64-bit UST consumer daemon binary\n");
- fprintf(stderr, " --consumerd64-libdir PATH Specify path for the 64-bit UST consumer daemon libraries\n");
- fprintf(stderr, " -d, --daemonize Start as a daemon.\n");
- fprintf(stderr, " -b, --background Start as a daemon, keeping console open.\n");
- fprintf(stderr, " -g, --group NAME Specify the tracing group name. (default: tracing)\n");
- fprintf(stderr, " -V, --version Show version number.\n");
- fprintf(stderr, " -S, --sig-parent Send SIGUSR1 to parent pid to notify readiness.\n");
- fprintf(stderr, " -q, --quiet No output at all.\n");
- fprintf(stderr, " -v, --verbose Verbose mode. Activate DBG() macro.\n");
- fprintf(stderr, " -p, --pidfile FILE Write a pid to FILE name overriding the default value.\n");
- fprintf(stderr, " --verbose-consumer Verbose mode for consumer. Activate DBG() macro.\n");
- fprintf(stderr, " --no-kernel Disable kernel tracer\n");
- fprintf(stderr, " --agent-tcp-port Agent registration TCP port\n");
- fprintf(stderr, " -f --config PATH Load daemon configuration file\n");
- fprintf(stderr, " -l --load PATH Load session configuration\n");
- fprintf(stderr, " --kmod-probes Specify kernel module probes to load\n");
- fprintf(stderr, " --extra-kmod-probes Specify extra kernel module probes to load\n");
-}
-
static int string_match(const char *str1, const char *str2)
{
return (str1 && str2) && !strcmp(str1, str2);
tracing_group_name_override = 1;
}
} else if (string_match(optname, "help") || opt == 'h') {
- usage();
- exit(EXIT_SUCCESS);
+ ret = utils_show_man_page(8, "lttng-sessiond");
+ if (ret) {
+ ERR("Cannot view man page lttng-sessiond(8)");
+ perror("exec");
+ }
+ exit(ret ? EXIT_FAILURE : EXIT_SUCCESS);
} else if (string_match(optname, "version") || opt == 'V') {
fprintf(stdout, "%s\n", VERSION);
exit(EXIT_SUCCESS);
commands/track-untrack.c \
commands/status.c \
commands/metadata.c \
+ commands/help.c \
utils.c utils.h lttng.c
lttng_LDADD = $(top_builddir)/src/lib/lttng-ctl/liblttng-ctl.la \
#define DECL_COMMAND(_name) \
extern int cmd_##_name(int, const char **)
+#define SHOW_HELP() \
+ do { \
+ ret = show_cmd_man_page(argv[0]); \
+ \
+ if (ret) { \
+ ERR("Cannot view man page lttng-%s(1)", argv[0]); \
+ perror("exec"); \
+ ret = CMD_ERROR; \
+ } \
+ } while (0)
+
enum cmd_error_code {
CMD_SUCCESS = 0,
CMD_ERROR,
DECL_COMMAND(untrack);
DECL_COMMAND(metadata);
+extern int cmd_help(int argc, const char **argv,
+ const struct cmd_struct commands[]);
+
#endif /* _LTTNG_CMD_H */
#include "../command.h"
-#define PRINT_LINE_LEN 80
-
static char *opt_channel_name;
static char *opt_session_name;
static int opt_kernel;
OPT_JUL,
OPT_LOG4J,
OPT_LIST_OPTIONS,
+ OPT_LIST,
};
static struct lttng_handle *handle;
{"jul", 'j', POPT_ARG_NONE, 0, OPT_JUL, 0, 0},
{"log4j", 'l', POPT_ARG_NONE, 0, OPT_LOG4J, 0, 0},
{"type", 't', POPT_ARG_STRING, &opt_type, OPT_TYPE, 0, 0},
+ {"list", 0, POPT_ARG_NONE, NULL, OPT_LIST, NULL, NULL},
{"list-options", 0, POPT_ARG_NONE, NULL, OPT_LIST_OPTIONS, NULL, NULL},
{0, 0, 0, 0, 0, 0, 0}
};
*/
static void print_ctx_type(FILE *ofp)
{
- const char *indent = " ";
- int indent_len = strlen(indent);
- int len, i = 0;
+ int i = 0;
- fprintf(ofp, "%s", indent);
- len = indent_len;
while (ctx_opts[i].symbol != NULL) {
if (!ctx_opts[i].hide_help) {
- if (len > indent_len) {
- if (len + strlen(ctx_opts[i].symbol) + 2
- >= PRINT_LINE_LEN) {
- fprintf(ofp, ",\n");
- fprintf(ofp, "%s", indent);
- len = indent_len;
- } else {
- len += fprintf(ofp, ", ");
- }
- }
- len += fprintf(ofp, "%s", ctx_opts[i].symbol);
+ fprintf(ofp, "%s\n", ctx_opts[i].symbol);
}
i++;
}
}
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng add-context -t TYPE [-k|-u] [OPTIONS]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "If no channel is given (-c), the context is added to\n");
- fprintf(ofp, "all channels.\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Otherwise the context is added only to the channel (-c).\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Exactly one domain (-k or -u) must be specified.\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " --list-options Simple listing of options\n");
- fprintf(ofp, " -s, --session NAME Apply to session name\n");
- fprintf(ofp, " -c, --channel NAME Apply to channel\n");
- fprintf(ofp, " -k, --kernel Apply to the kernel tracer\n");
- fprintf(ofp, " -u, --userspace Apply to the user-space tracer\n");
- fprintf(ofp, " -j, --jul Apply to Java application using JUL\n");
- fprintf(ofp, " -l, --log4j Apply for Java application using LOG4j\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Context:\n");
- fprintf(ofp, " -t, --type TYPE Context type. You can repeat that option on\n");
- fprintf(ofp, " the command line to specify multiple contexts at once.\n");
- fprintf(ofp, " (--kernel preempts --userspace)\n");
- fprintf(ofp, " TYPE can be one of the strings below:\n");
- print_ctx_type(ofp);
- fprintf(ofp, "\n");
- fprintf(ofp, "Note that the vpid, vppid and vtid context types represent the virtual process id,\n"
- "virtual parent process id and virtual thread id as seen from the current execution context\n"
- "as opposed to the pid, ppid and tid which are kernel internal data structures.\n\n");
- fprintf(ofp, "Example:\n");
- fprintf(ofp, "This command will add the context information 'prio' and two per-cpu\n"
- "perf counters (hardware branch misses and cache misses), to all channels\n"
- "in the trace data output:\n");
- fprintf(ofp, "# lttng add-context -k -t prio -t perf:cpu:branch-misses -t perf:cpu:cache-misses\n");
- fprintf(ofp, "\n");
-}
-
/*
* Find context numerical value from string.
*
char *session_name = NULL;
if (argc < 2) {
- usage(stderr);
ret = CMD_ERROR;
goto end;
}
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
+ goto end;
+ case OPT_LIST:
+ print_ctx_type(stdout);
goto end;
case OPT_TYPE:
{
list_cmd_options(stdout, long_options);
goto end;
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
if (!opt_type) {
ERR("Missing mandatory -t TYPE");
- usage(stderr);
ret = CMD_ERROR;
goto end;
}
{0, 0, 0, 0, 0, 0, 0}
};
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng calibrate [-k|-u] [OPTIONS]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " --list-options Simple listing of options\n");
- fprintf(ofp, " -k, --kernel Apply to the kernel tracer\n");
- fprintf(ofp, " -u, --userspace Apply to the user-space tracer\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Calibrate options:\n");
- fprintf(ofp, " --function Dynamic function entry/return probe (default)\n");
- fprintf(ofp, "\n");
-}
-
/*
* Calibrate LTTng.
*
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_TRACEPOINT:
ret = CMD_UNDEFINED;
list_cmd_options(stdout, long_options);
goto end;
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
extern int _lttng_create_session_ext(const char *name, const char *url,
const char *datetime);
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng create [NAME] [OPTIONS] \n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Without a given NAME, the default is 'auto-<yyyymmdd>-<hhmmss>'\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " --list-options Simple listing of options\n");
- fprintf(ofp, " -o, --output PATH Specify output path for traces\n");
- fprintf(ofp, " --no-output Traces will not be outputted\n");
- fprintf(ofp, " --snapshot Set the session in snapshot mode.\n");
- fprintf(ofp, " Created in no-output mode and uses the URL,\n");
- fprintf(ofp, " if one, as the default snapshot output.\n");
- fprintf(ofp, " Every channel will be set in overwrite mode\n");
- fprintf(ofp, " and with mmap output (splice not supported).\n");
- fprintf(ofp, " --live [USEC] Set the session in live-reading mode.\n");
- fprintf(ofp, " The delay parameter in micro-seconds is the\n");
- fprintf(ofp, " maximum time the user can wait for the data\n");
- fprintf(ofp, " to be flushed. Can be set with a network\n");
- fprintf(ofp, " URL (-U or -C/-D) and must have a relayd listening.\n");
- fprintf(ofp, " By default, %u is used for the timer and the\n",
- DEFAULT_LTTNG_LIVE_TIMER);
- fprintf(ofp, " network URL is set to net://127.0.0.1.\n");
- fprintf(ofp, " --shm-path PATH Path where shared memory holding buffers\n");
- fprintf(ofp, " should be created. Useful when used with pramfs\n");
- fprintf(ofp, " to extract trace data after crash.\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Extended Options:\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Using these options, each API call can be controlled individually.\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " -U, --set-url=URL Set URL destination of the trace data.\n");
- fprintf(ofp, " It is persistent for the session lifetime.\n");
- fprintf(ofp, " This will set both data and control URL.\n");
- fprintf(ofp, " -C, --ctrl-url=URL Set control path URL. (Must use -D also)\n");
- fprintf(ofp, " -D, --data-url=URL Set data path URL. (Must use -C also)\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Please refer to the man page (lttng(1)) for more information on network\n");
- fprintf(ofp, "streaming mechanisms and explanation of the control and data port\n");
- fprintf(ofp, "You must have a running remote lttng-relayd for network streaming\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "URL format is has followed:\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " Supported protocols are (proto):\n");
- fprintf(ofp, " > file://...\n");
- fprintf(ofp, " Local filesystem full path.\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " > net[6]://...\n");
- fprintf(ofp, " This will use the default network transport layer which is\n");
- fprintf(ofp, " TCP for both control (PORT1) and data port (PORT2).\n");
- fprintf(ofp, " The default ports are respectively 5342 and 5343.\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " > tcp[6]://...\n");
- fprintf(ofp, " Can only be used with -C and -D together\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "NOTE: IPv6 address MUST be enclosed in brackets '[]' (rfc2732)\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Examples:\n");
- fprintf(ofp, " # lttng create -U net://192.168.1.42\n");
- fprintf(ofp, " Uses TCP and default ports for the given destination.\n");
- fprintf(ofp, " # lttng create -U net6://[fe80::f66d:4ff:fe53:d220]\n");
- fprintf(ofp, " Uses TCP, default ports and IPv6.\n");
- fprintf(ofp, " # lttng create s1 -U net://myhost.com:3229\n");
- fprintf(ofp, " Set the consumer to the remote HOST on port 3229 for control.\n");
- fprintf(ofp, "\n");
-}
-
/*
* Retrieve the created session and mi output it based on provided argument
* This is currently a summary of what was pretty printed and is subject to
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_LIST_OPTIONS:
list_cmd_options(stdout, long_options);
break;
}
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
{0, 0, 0, 0, 0, 0, 0}
};
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng destroy [NAME] [OPTIONS]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Where NAME is an optional session name. If not specified, lttng will\n");
- fprintf(ofp, "get it from the configuration directory (.lttng).\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " -a, --all Destroy all sessions\n");
- fprintf(ofp, " --list-options Simple listing of options\n");
- fprintf(ofp, " -n, --no-wait Don't wait for data availability\n");
- fprintf(ofp, "\n");
-}
-
/*
* destroy_session
*
}
session_was_stopped = ret == -LTTNG_ERR_TRACE_ALREADY_STOPPED;
if (!opt_no_wait) {
- _MSG("Waiting for data availability");
- fflush(stdout);
+ bool printed_wait_msg = false;
+
do {
ret = lttng_data_pending(session->name);
if (ret < 0) {
* returned value indicates availability.
*/
if (ret) {
+ if (!printed_wait_msg) {
+ _MSG("Waiting for data availability");
+ fflush(stdout);
+ }
+
+ printed_wait_msg = true;
usleep(DEFAULT_DATA_AVAILABILITY_WAIT_TIME);
_MSG(".");
fflush(stdout);
}
} while (ret != 0);
- MSG("");
+ if (printed_wait_msg) {
+ MSG("");
+ }
}
if (!session_was_stopped) {
/*
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
break;
case OPT_LIST_OPTIONS:
list_cmd_options(stdout, long_options);
break;
default:
- usage(stderr);
ret = CMD_UNDEFINED;
break;
}
{0, 0, 0, 0, 0, 0, 0}
};
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng disable-channel NAME[,NAME2,...] (-k | -u) [OPTIONS]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " --list-options Simple listing of options\n");
- fprintf(ofp, " -s, --session NAME Apply to session name\n");
- fprintf(ofp, " -k, --kernel Apply to the kernel tracer\n");
- fprintf(ofp, " -u, --userspace Apply to the user-space tracer\n");
- fprintf(ofp, "\n");
-}
-
static int mi_partial_channel_print(char *channel_name, unsigned int enabled,
int success)
{
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_USERSPACE:
opt_userspace = 1;
list_cmd_options(stdout, long_options);
goto end;
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
opt_channels = (char*) poptGetArg(pc);
if (opt_channels == NULL) {
ERR("Missing channel name(s).\n");
- usage(stderr);
ret = CMD_ERROR;
goto end;
}
{0, 0, 0, 0, 0, 0, 0}
};
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng disable-event NAME[,NAME2,...] (-k | -u | -j | -l | -p) [OPTIONS]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " --list-options Simple listing of options\n");
- fprintf(ofp, " -s, --session NAME Apply to session name\n");
- fprintf(ofp, " -c, --channel NAME Apply to this channel\n");
- fprintf(ofp, " -a, --all-events Disable all tracepoints\n");
- fprintf(ofp, " -k, --kernel Apply to the kernel tracer\n");
- fprintf(ofp, " -u, --userspace Apply to the user-space tracer\n");
- fprintf(ofp, " -j, --jul Apply to Java application using JUL\n");
- fprintf(ofp, " -l, --log4j Apply to Java application using LOG4j\n");
- fprintf(ofp, " -p, --python Apply to Python application using logging\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Event type options (Only supported with kernel domain):\n");
- fprintf(ofp, " --all All event types (default)\n");
- fprintf(ofp, " --tracepoint Tracepoint event\n");
- fprintf(ofp, " --syscall System call event\n");
- fprintf(ofp, " --probe Probe event\n");
- fprintf(ofp, " --function Function event\n");
- fprintf(ofp, "\n");
-}
-
static
const char *print_channel_name(const char *name)
{
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_TYPE_SYSCALL:
opt_event_type = LTTNG_EVENT_SYSCALL;
list_cmd_options(stdout, long_options);
goto end;
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
if ((opt_userspace || opt_jul || opt_log4j || opt_python)
&& opt_event_type != LTTNG_EVENT_ALL) {
ERR("Disabling userspace and agent (-j | -l | -p) event(s) based on instrumentation type is not supported.\n");
- usage(stderr);
ret = CMD_ERROR;
goto end;
}
opt_event_list = (char*) poptGetArg(pc);
if (opt_event_list == NULL && opt_disable_all == 0) {
ERR("Missing event name(s).\n");
- usage(stderr);
ret = CMD_ERROR;
goto end;
}
{0, 0, 0, 0, 0, 0, 0}
};
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng enable-channel NAME[,NAME2,...] (-u | -k) [OPTIONS]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " --list-options Simple listing of options\n");
- fprintf(ofp, " -s, --session NAME Apply to session name\n");
- fprintf(ofp, " -k, --kernel Apply to the kernel tracer\n");
- fprintf(ofp, " -u, --userspace Apply to the user-space tracer\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Channel options:\n");
- fprintf(ofp, " --discard Discard event when buffers are full%s\n",
- DEFAULT_CHANNEL_OVERWRITE ? "" : " (default)");
- fprintf(ofp, " --overwrite Flight recorder mode%s\n",
- DEFAULT_CHANNEL_OVERWRITE ? " (default)" : "");
- fprintf(ofp, " --subbuf-size SIZE Subbuffer size in bytes {+k,+M,+G}\n");
- fprintf(ofp, " (default UST uid: %zu, UST pid: %zu, kernel: %zu, metadata: %zu)\n",
- default_get_ust_uid_channel_subbuf_size(),
- default_get_ust_pid_channel_subbuf_size(),
- default_get_kernel_channel_subbuf_size(),
- default_get_metadata_subbuf_size());
- fprintf(ofp, " Rounded up to the next power of 2.\n");
- fprintf(ofp, " --num-subbuf NUM Number of subbufers\n");
- fprintf(ofp, " (default UST uid: %u, UST pid: %u, kernel: %u, metadata: %u)\n",
- DEFAULT_UST_UID_CHANNEL_SUBBUF_NUM, DEFAULT_UST_PID_CHANNEL_SUBBUF_NUM,
- DEFAULT_KERNEL_CHANNEL_SUBBUF_NUM, DEFAULT_METADATA_SUBBUF_NUM);
- fprintf(ofp, " Rounded up to the next power of 2.\n");
- fprintf(ofp, " --switch-timer USEC Switch timer interval in usec\n");
- fprintf(ofp, " (default UST uid: %u, UST pid: %u, kernel: %u, metadata: %u)\n",
- DEFAULT_UST_UID_CHANNEL_SWITCH_TIMER, DEFAULT_UST_PID_CHANNEL_SWITCH_TIMER,
- DEFAULT_KERNEL_CHANNEL_SWITCH_TIMER, DEFAULT_METADATA_SWITCH_TIMER);
- fprintf(ofp, " --read-timer USEC Read timer interval in usec.\n");
- fprintf(ofp, " (default UST uid: %u, UST pid: %u, kernel: %u, metadata: %u)\n",
- DEFAULT_UST_UID_CHANNEL_READ_TIMER, DEFAULT_UST_UID_CHANNEL_READ_TIMER,
- DEFAULT_KERNEL_CHANNEL_READ_TIMER, DEFAULT_METADATA_READ_TIMER);
- fprintf(ofp, " --output TYPE Channel output type (Values: %s, %s)\n",
- output_mmap, output_splice);
- fprintf(ofp, " (default UST uid: %s, UST pid: %s, kernel: %s, metadata: %s)\n",
- DEFAULT_UST_UID_CHANNEL_OUTPUT == LTTNG_EVENT_MMAP ? output_mmap : output_splice,
- DEFAULT_UST_PID_CHANNEL_OUTPUT == LTTNG_EVENT_MMAP ? output_mmap : output_splice,
- DEFAULT_KERNEL_CHANNEL_OUTPUT == LTTNG_EVENT_MMAP ? output_mmap : output_splice,
- DEFAULT_METADATA_OUTPUT == LTTNG_EVENT_MMAP ? output_mmap : output_splice);
- fprintf(ofp, " --buffers-uid Use per UID buffer (-u only)\n");
- fprintf(ofp, " --buffers-pid Use per PID buffer (-u only)\n");
- fprintf(ofp, " --buffers-global Use shared buffer for the whole system (-k only)\n");
- fprintf(ofp, " -C, --tracefile-size SIZE\n");
- fprintf(ofp, " Maximum size of each tracefile within a stream (in bytes). 0 means unlimited.\n");
- fprintf(ofp, " (default: %u)\n", DEFAULT_CHANNEL_TRACEFILE_SIZE);
- fprintf(ofp, " Note: traces generated with this option may inaccurately report\n");
- fprintf(ofp, " discarded events as per CTF 1.8.\n");
- fprintf(ofp, " -W, --tracefile-count COUNT\n");
- fprintf(ofp, " Used in conjunction with -C option, this will limit the number\n");
- fprintf(ofp, " of files created to the specified count. 0 means unlimited.\n");
- fprintf(ofp, " (default: %u)\n", DEFAULT_CHANNEL_TRACEFILE_COUNT);
- fprintf(ofp, "\n");
-}
-
/*
* Set default attributes depending on those already defined from the command
* line.
} else {
ERR("Unknown output type %s. Possible values are: %s, %s\n",
opt_output, output_mmap, output_splice);
- usage(stderr);
ret = CMD_ERROR;
goto error;
}
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_DISCARD:
chan.attr.overwrite = 0;
list_cmd_options(stdout, long_options);
goto end;
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
opt_channels = (char*) poptGetArg(pc);
if (opt_channels == NULL) {
ERR("Missing channel name.\n");
- usage(stderr);
ret = CMD_ERROR;
success = 0;
goto mi_closing;
{0, 0, 0, 0, 0, 0, 0}
};
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng enable-event NAME[,NAME2,...] (-k | -u | -j | -l | -p) [OPTIONS] \n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " --list-options Simple listing of options\n");
- fprintf(ofp, " -s, --session NAME Apply to session name\n");
- fprintf(ofp, " -c, --channel NAME Apply to this channel\n");
- fprintf(ofp, " -a, --all Enable all tracepoints and syscalls\n");
- fprintf(ofp, " -k, --kernel Apply to the kernel tracer\n");
- fprintf(ofp, " -u, --userspace Apply to the user-space tracer\n");
- fprintf(ofp, " -j, --jul Apply to Java application using JUL\n");
- fprintf(ofp, " -l, --log4j Apply for Java application using LOG4j\n");
- fprintf(ofp, " -p, --python Apply for Python application\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Event options:\n");
- fprintf(ofp, " --tracepoint Tracepoint event (default)\n");
- fprintf(ofp, " - userspace tracer supports wildcards at end of string.\n");
- fprintf(ofp, " Don't forget to quote to deal with bash expansion.\n");
- fprintf(ofp, " e.g.:\n");
- fprintf(ofp, " \"*\"\n");
- fprintf(ofp, " \"app_component:na*\"\n");
- fprintf(ofp, " --probe (addr | symbol | symbol+offset)\n");
- fprintf(ofp, " Dynamic probe.\n");
- fprintf(ofp, " Addr and offset can be octal (0NNN...),\n");
- fprintf(ofp, " decimal (NNN...) or hexadecimal (0xNNN...)\n");
- fprintf(ofp, " --function (addr | symbol | symbol+offset)\n");
- fprintf(ofp, " Dynamic function entry/return probe.\n");
- fprintf(ofp, " Addr and offset can be octal (0NNN...),\n");
- fprintf(ofp, " decimal (NNN...) or hexadecimal (0xNNN...)\n");
- fprintf(ofp, " --syscall System call event\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " --loglevel name\n");
- fprintf(ofp, " Tracepoint loglevel range from 0 to loglevel.\n");
- fprintf(ofp, " For JUL/LOG4j/Python domains, see the table below for the range values.\n");
- fprintf(ofp, " --loglevel-only name\n");
- fprintf(ofp, " Tracepoint loglevel (only this loglevel)\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " The loglevel or loglevel-only options should be\n");
- fprintf(ofp, " combined with a tracepoint name or tracepoint\n");
- fprintf(ofp, " wildcard.\n");
- fprintf(ofp, " Available loglevels:\n");
- fprintf(ofp, " (higher value is more verbose)\n");
- fprintf(ofp, " TRACE_EMERG = 0\n");
- fprintf(ofp, " TRACE_ALERT = 1\n");
- fprintf(ofp, " TRACE_CRIT = 2\n");
- fprintf(ofp, " TRACE_ERR = 3\n");
- fprintf(ofp, " TRACE_WARNING = 4\n");
- fprintf(ofp, " TRACE_NOTICE = 5\n");
- fprintf(ofp, " TRACE_INFO = 6\n");
- fprintf(ofp, " TRACE_DEBUG_SYSTEM = 7\n");
- fprintf(ofp, " TRACE_DEBUG_PROGRAM = 8\n");
- fprintf(ofp, " TRACE_DEBUG_PROCESS = 9\n");
- fprintf(ofp, " TRACE_DEBUG_MODULE = 10\n");
- fprintf(ofp, " TRACE_DEBUG_UNIT = 11\n");
- fprintf(ofp, " TRACE_DEBUG_FUNCTION = 12\n");
- fprintf(ofp, " TRACE_DEBUG_LINE = 13\n");
- fprintf(ofp, " TRACE_DEBUG = 14\n");
- fprintf(ofp, " (shortcuts such as \"system\" are allowed)\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " Available JUL domain loglevels:\n");
- fprintf(ofp, " JUL_OFF = INT32_MAX\n");
- fprintf(ofp, " JUL_SEVERE = %d\n", LTTNG_LOGLEVEL_JUL_SEVERE);
- fprintf(ofp, " JUL_WARNING = %d\n", LTTNG_LOGLEVEL_JUL_WARNING);
- fprintf(ofp, " JUL_INFO = %d\n", LTTNG_LOGLEVEL_JUL_INFO);
- fprintf(ofp, " JUL_CONFIG = %d\n", LTTNG_LOGLEVEL_JUL_CONFIG);
- fprintf(ofp, " JUL_FINE = %d\n", LTTNG_LOGLEVEL_JUL_FINE);
- fprintf(ofp, " JUL_FINER = %d\n", LTTNG_LOGLEVEL_JUL_FINER);
- fprintf(ofp, " JUL_FINEST = %d\n", LTTNG_LOGLEVEL_JUL_FINEST);
- fprintf(ofp, " JUL_ALL = INT32_MIN\n");
- fprintf(ofp, " (shortcuts such as \"severe\" are allowed)\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " Available LOG4j domain loglevels:\n");
- fprintf(ofp, " LOG4J_OFF = INT32_MAX\n");
- fprintf(ofp, " LOG4J_FATAL = %d\n", LTTNG_LOGLEVEL_LOG4J_FATAL);
- fprintf(ofp, " LOG4J_ERROR = %d\n", LTTNG_LOGLEVEL_LOG4J_ERROR);
- fprintf(ofp, " LOG4J_WARN = %d\n", LTTNG_LOGLEVEL_LOG4J_WARN);
- fprintf(ofp, " LOG4J_INFO = %d\n", LTTNG_LOGLEVEL_LOG4J_INFO);
- fprintf(ofp, " LOG4J_DEBUG = %d\n", LTTNG_LOGLEVEL_LOG4J_DEBUG);
- fprintf(ofp, " LOG4J_TRACE = %d\n", LTTNG_LOGLEVEL_LOG4J_TRACE);
- fprintf(ofp, " LOG4J_ALL = INT32_MIN\n");
- fprintf(ofp, " (shortcuts such as \"severe\" are allowed)\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " Available Python domain loglevels:\n");
- fprintf(ofp, " PYTHON_CRITICAL = %d\n", LTTNG_LOGLEVEL_PYTHON_CRITICAL);
- fprintf(ofp, " PYTHON_ERROR = %d\n", LTTNG_LOGLEVEL_PYTHON_ERROR);
- fprintf(ofp, " PYTHON_WARNING = %d\n", LTTNG_LOGLEVEL_PYTHON_WARNING);
- fprintf(ofp, " PYTHON_INFO = %d\n", LTTNG_LOGLEVEL_PYTHON_INFO);
- fprintf(ofp, " PYTHON_DEBUG = %d\n", LTTNG_LOGLEVEL_PYTHON_DEBUG);
- fprintf(ofp, " PYTHON_NOTSET = %d\n", LTTNG_LOGLEVEL_PYTHON_NOTSET);
- fprintf(ofp, " (shortcuts such as \"critical\" are allowed)\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " -f, --filter \'expression\'\n");
- fprintf(ofp, " Filter expression on event fields and context.\n");
- fprintf(ofp, " Event recording depends on evaluation.\n");
- fprintf(ofp, " Only specify on first activation of\n");
- fprintf(ofp, " a given event within a session.\n");
- fprintf(ofp, " Filter only allowed when enabling\n");
- fprintf(ofp, " events within a session before tracing\n");
- fprintf(ofp, " is started. If the filter fails to link\n");
- fprintf(ofp, " with the event within the traced domain,\n");
- fprintf(ofp, " the event will be discarded. Currently,\n");
- fprintf(ofp, " filter is only implemented for the user-space\n");
- fprintf(ofp, " tracer.\n");
- fprintf(ofp, " Expression examples:.\n");
- fprintf(ofp, " \n");
- fprintf(ofp, " 'intfield > 500 && intfield < 503'\n");
- fprintf(ofp, " '(strfield == \"test\" || intfield != 10) && intfield > 33'\n");
- fprintf(ofp, " 'doublefield > 1.1 && intfield < 5.3'\n");
- fprintf(ofp, " \n");
- fprintf(ofp, " Wildcards are allowed at the end of strings:\n");
- fprintf(ofp, " 'seqfield1 == \"te*\"'\n");
- fprintf(ofp, " In string literals, the escape character is '\\'.\n");
- fprintf(ofp, " Use '\\*' for the '*' character, and '\\\\' for\n");
- fprintf(ofp, " the '\\' character. Wildcard match any sequence of,\n");
- fprintf(ofp, " characters including an empty sub-string (match 0 or\n");
- fprintf(ofp, " more characters).\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " Context information can be used for filtering. The\n");
- fprintf(ofp, " examples below show usage of context filtering on\n");
- fprintf(ofp, " process name (with a wildcard), process ID range, and\n");
- fprintf(ofp, " unique thread ID for filtering. The process and\n");
- fprintf(ofp, " thread ID of running applications can be found under\n");
- fprintf(ofp, " columns \"PID\" and \"LWP\" of the \"ps -eLf\" command.\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " '$ctx.procname == \"demo*\"'\n");
- fprintf(ofp, " '$ctx.vpid >= 4433 && $ctx.vpid < 4455'\n");
- fprintf(ofp, " '$ctx.vtid == 1234'\n");
- fprintf(ofp, " -x, --exclude LIST\n");
- fprintf(ofp, " Add exclusions to UST tracepoints:\n");
- fprintf(ofp, " Events that match any of the items\n");
- fprintf(ofp, " in the comma-separated LIST are not\n");
- fprintf(ofp, " enabled, even if they match a wildcard\n");
- fprintf(ofp, " definition of the event.\n");
- fprintf(ofp, "\n");
-}
-
/*
* Parse probe options.
*/
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_TRACEPOINT:
opt_event_type = LTTNG_EVENT_TRACEPOINT;
case OPT_EXCLUDE:
break;
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
opt_event_list = (char*) poptGetArg(pc);
if (opt_event_list == NULL && opt_enable_all == 0) {
ERR("Missing event name(s).\n");
- usage(stderr);
ret = CMD_ERROR;
goto end;
}
--- /dev/null
+/*
+ * Copyright (C) 2015 - Philippe Proulx <pproulx@efficios.com>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License, version 2 only,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#define _LGPL_SOURCE
+#include <popt.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "../command.h"
+#include <common/utils.h>
+
+enum {
+ OPT_HELP = 1,
+ OPT_LIST_OPTIONS,
+};
+
+static struct poptOption long_options[] = {
+ /* longName, shortName, argInfo, argPtr, value, descrip, argDesc */
+ {"help", 'h', POPT_ARG_NONE, 0, OPT_HELP, 0, 0},
+ {"list-options", 0, POPT_ARG_NONE, NULL, OPT_LIST_OPTIONS, NULL, NULL},
+ {0, 0, 0, 0, 0, 0, 0}
+};
+
+/*
+ * cmd_help
+ */
+int cmd_help(int argc, const char **argv, const struct cmd_struct commands[])
+{
+ int opt, ret = CMD_SUCCESS;
+ char *cmd_name;
+ static poptContext pc;
+ const struct cmd_struct *cmd;
+ int found = 0;
+
+ pc = poptGetContext(NULL, argc, argv, long_options, 0);
+ poptReadDefaultConfig(pc, 0);
+
+ while ((opt = poptGetNextOpt(pc)) != -1) {
+ switch (opt) {
+ case OPT_HELP:
+ SHOW_HELP();
+ goto end;
+ case OPT_LIST_OPTIONS:
+ list_cmd_options(stdout, long_options);
+ goto end;
+ default:
+ ret = CMD_UNDEFINED;
+ goto end;
+ }
+ }
+
+ /* Get command name */
+ cmd_name = (char *) poptGetArg(pc);
+
+ if (cmd_name == NULL) {
+ /* Fall back to lttng(1) */
+ ret = utils_show_man_page(1, "lttng");
+
+ if (ret) {
+ ERR("Cannot view man page lttng(1)");
+ perror("exec");
+ ret = CMD_ERROR;
+ goto end;
+ }
+ }
+
+ /* Make sure command name exists */
+ cmd = &commands[0];
+
+ while (cmd->name != NULL) {
+ if (strcmp(cmd->name, cmd_name) == 0) {
+ found = 1;
+ break;
+ }
+
+ cmd++;
+ }
+
+ if (!found) {
+ ERR("Unknown command \"%s\"", cmd_name);
+ ret = CMD_ERROR;
+ goto end;
+ }
+
+ /* Show command's man page */
+ ret = show_cmd_man_page(cmd_name);
+
+ if (ret) {
+ ERR("Cannot view man page lttng-%s(1)", cmd_name);
+ perror("exec");
+ ret = CMD_ERROR;
+ }
+
+end:
+ poptFreeContext(pc);
+ return ret;
+}
{0, 0, 0, 0, 0, 0, 0}
};
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng list [OPTIONS] [SESSION [SESSION OPTIONS]]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "With no arguments, list available tracing session(s)\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Without a session, -k lists available kernel events\n");
- fprintf(ofp, "Without a session, -u lists available userspace events\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " --list-options Simple listing of options\n");
- fprintf(ofp, " -k, --kernel Select kernel domain\n");
- fprintf(ofp, " -u, --userspace Select user-space domain.\n");
- fprintf(ofp, " -j, --jul Apply for Java application using JUL\n");
- fprintf(ofp, " -l, --log4j Apply for Java application using LOG4J\n");
- fprintf(ofp, " -p, --python Apply for Python application using logging\n");
- fprintf(ofp, " -f, --fields List event fields.\n");
- fprintf(ofp, " --syscall List available system calls.\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Session Options:\n");
- fprintf(ofp, " -c, --channel NAME List details of a channel\n");
- fprintf(ofp, " -d, --domain List available domain(s)\n");
- fprintf(ofp, "\n");
-}
-
/*
* Get command line from /proc for a specific pid.
*
memset(&domain, 0, sizeof(domain));
if (argc < 1) {
- usage(stderr);
ret = CMD_ERROR;
goto end;
}
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_USERSPACE:
opt_userspace = 1;
list_cmd_options(stdout, long_options);
goto end;
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
{0, 0, 0, 0, 0, 0, 0}
};
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng load [OPTIONS] [SESSION]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " -a, --all Load all sessions (default)\n");
- fprintf(ofp, " -i, --input-path PATH Input path of the session file(s).\n");
- fprintf(ofp, " If a directory, load all files in it\n");
- fprintf(ofp, " else try to load the given file.\n");
- fprintf(ofp, " -f, --force Override existing session(s).\n");
- fprintf(ofp, " This will destroy existing session(s)\n");
- fprintf(ofp, " before creating new one(s).\n");
-}
-
static int mi_partial_session(const char *session_name)
{
int ret;
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_ALL:
opt_load_all = 1;
opt_force = 1;
break;
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
{ NULL, NULL } /* Array closure */
};
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng metadata [OPTION] ACTION\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Actions:\n");
- fprintf(ofp, " regenerate\n");
- fprintf(ofp, " Regenerate and overwrite the metadata of the session.\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help.\n");
- fprintf(ofp, " --list-options Simple listing of options.\n");
- fprintf(ofp, " -s, --session NAME Apply to session name.\n");
- fprintf(ofp, "\n");
-}
-
/*
* Count and return the number of arguments in argv.
*/
int ret = CMD_SUCCESS, i = 0, argc, command_ret = CMD_SUCCESS;
if (argv == NULL) {
- usage(stderr);
+ SHOW_HELP();
command_ret = CMD_ERROR;
goto end;
}
static poptContext pc;
if (argc < 1) {
- usage(stderr);
+ SHOW_HELP();
ret = CMD_ERROR;
goto end;
}
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_LIST_OPTIONS:
list_cmd_options(stdout, long_options);
list_commands(actions, stdout);
goto end;
default:
- usage(stderr);
+ SHOW_HELP();
ret = CMD_UNDEFINED;
goto end;
}
static struct mi_writer *writer;
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng save [OPTIONS] [SESSION]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " -a, --all Save all sessions (default)\n");
- fprintf(ofp, " -o, --output-path Output path of the session configuration(s)\n");
- fprintf(ofp, " -f, --force Overwrite existing session configuration(s)\n");
-}
-
static int mi_partial_session(const char *session_name)
{
int ret;
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_ALL:
opt_save_all = 1;
list_cmd_options(stdout, save_opts);
goto end;
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
{0, 0, 0, 0, 0, 0, 0}
};
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng set-session NAME [OPTIONS]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " --list-options Simple listing of options\n");
- fprintf(ofp, "\n");
-}
-
/*
* Print the necessary mi for a session and name.
*/
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_LIST_OPTIONS:
list_cmd_options(stdout, long_options);
goto end;
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
opt_session_name = (char *) poptGetArg(pc);
if (opt_session_name == NULL) {
ERR("Missing session name");
- usage(stderr);
ret = CMD_ERROR;
goto end;
}
{ NULL, NULL } /* Array closure */
};
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng snapshot [OPTION] ACTION\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Actions:\n");
- fprintf(ofp, " add-output [-m <SIZE>] [-s <NAME>] [-n <NAME>] <URL> | -C <URL> -D <URL>\n");
- fprintf(ofp, " Setup and add an snapshot output for a session.\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " del-output ID | NAME [-s <NAME>]\n");
- fprintf(ofp, " Delete an output for a session using the ID.\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " list-output [-s <NAME>]\n");
- fprintf(ofp, " List the output of a session.\n");
- fprintf(ofp, "\n");
- fprintf(ofp, " record [-m <SIZE>] [-s <NAME>] [-n <NAME>] [<URL> | -C <URL> -D <URL>]\n");
- fprintf(ofp, " Snapshot a session's buffer(s) for all domains. If an URL is\n");
- fprintf(ofp, " specified, it is used instead of a previously added output.\n");
- fprintf(ofp, " Specifying only a name or/a size will override the current output value.\n");
- fprintf(ofp, " For instance, you can record a snapshot with a custom maximum size\n");
- fprintf(ofp, " or with a different name.\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " --list-options Simple listing of options\n");
- fprintf(ofp, " -s, --session NAME Apply to session name\n");
- fprintf(ofp, " -n, --name NAME Name of the output or snapshot\n");
- fprintf(ofp, " -m, --max-size SIZE Maximum bytes size of the snapshot {+k,+M,+G}\n");
- fprintf(ofp, " -C, --ctrl-url URL Set control path URL. (Must use -D also)\n");
- fprintf(ofp, " -D, --data-url URL Set data path URL. (Must use -C also)\n");
- fprintf(ofp, "\n");
-}
-
/*
* Count and return the number of arguments in argv.
*/
int ret;
if (argc < 2 && (!opt_data_url || !opt_ctrl_url)) {
- usage(stderr);
ret = CMD_ERROR;
goto end;
}
long id;
if (argc < 2) {
- usage(stderr);
ret = CMD_ERROR;
goto end;
}
if (argv == NULL || (!opt_ctrl_url && opt_data_url) ||
(opt_ctrl_url && !opt_data_url)) {
- usage(stderr);
command_ret = CMD_ERROR;
goto end;
}
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_LIST_OPTIONS:
list_cmd_options(stdout, snapshot_opts);
break;
}
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
{0, 0, 0, 0, 0, 0, 0}
};
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng start [NAME] [OPTIONS]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Where NAME is an optional session name. If not specified, lttng will\n");
- fprintf(ofp, "get it from the configuration directory (.lttng).\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " --list-options Simple listing of options\n");
- fprintf(ofp, "\n");
-}
-
static int mi_print_session(char *session_name, int enabled)
{
int ret;
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_LIST_OPTIONS:
list_cmd_options(stdout, long_options);
goto end;
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
{0, 0, 0, 0, 0, 0, 0}
};
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "Usage: lttng status [options]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " --list-options List options\n");
-}
-
static int status(void)
{
const char *argv[2];
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_LIST_OPTIONS:
list_cmd_options(stdout, long_options);
goto end;
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
if (poptPeekArg(pc) != NULL) {
ERR("This command does not accept positional arguments.\n");
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
{0, 0, 0, 0, 0, 0, 0}
};
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng stop [NAME] [OPTIONS]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Where NAME is an optional session name. If not specified, lttng will\n");
- fprintf(ofp, "get it from the configuration directory (.lttng).\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " --list-options Simple listing of options\n");
- fprintf(ofp, " -n, --no-wait Don't wait for data availability\n");
- fprintf(ofp, "\n");
-}
/*
* Mi print of partial session
*/
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_LIST_OPTIONS:
list_cmd_options(stdout, long_options);
goto end;
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
{ 0, 0, 0, 0, 0, 0, 0, },
};
-/*
- * usage
- */
-static void usage(FILE *ofp, const char *cmd_str)
-{
- fprintf(ofp, "usage: lttng %s [-k|-u] [OPTIONS]\n", cmd_str);
- fprintf(ofp, "\n");
- fprintf(ofp, "If no session is given (-s), the context is added to\n");
- fprintf(ofp, "the current sesssion. Exactly one domain (-k or -u)\n");
- fprintf(ofp, "must be specified.\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help.\n");
- fprintf(ofp, " --list-options Simple listing of options.\n");
- fprintf(ofp, " -s, --session NAME Apply to session name.\n");
- fprintf(ofp, " -k, --kernel Apply to the kernel tracer.\n");
- fprintf(ofp, " -u, --userspace Apply to the user-space tracer.\n");
- fprintf(ofp, " -p, --pid [PID] Process ID tracker. Leave PID empty when used with --all.\n");
- fprintf(ofp, " -a, --all All PIDs (use with --pid).\n");
- fprintf(ofp, "\n");
-}
-
static
int parse_pid_string(const char *_pid_string,
int all, int **_pid_list, int *nr_pids)
ret = parse_pid_string(pid_string, all, &pid_list, &nr_pids);
if (ret != CMD_SUCCESS) {
ERR("Error parsing PID string");
- usage(stderr, cmd_str);
retval = CMD_ERROR;
goto end;
}
struct mi_writer *writer = NULL;
if (argc < 1) {
- usage(stderr, cmd_str);
command_ret = CMD_ERROR;
goto end;
}
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout, cmd_str);
+ SHOW_HELP();
goto end;
case OPT_LIST_OPTIONS:
list_cmd_options(stdout, long_options);
opt_pid = 1;
break;
default:
- usage(stderr, cmd_str);
command_ret = CMD_UNDEFINED;
goto end;
}
/* Currently only PID tracker is supported */
if (!opt_pid) {
ERR("Please specify at least one tracker with its expected arguments");
- usage(stderr, cmd_str);
command_ret = CMD_ERROR;
goto end;
}
{0, 0, 0, 0, 0, 0, 0}
};
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng version [OPTIONS]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " --list-options Simple listing of options\n");
- fprintf(ofp, "\n");
-}
-
/*
* create_version
*/
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_LIST_OPTIONS:
list_cmd_options(stdout, long_options);
goto end;
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
/* Is the session we are trying to view is in live mode. */
static int session_live_mode;
-/*
- * usage
- */
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "usage: lttng view [SESSION_NAME] [OPTIONS]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "By default, the babeltrace viewer will be used for text viewing\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Where SESSION_NAME is an optional session name. If not specified, lttng will\n");
- fprintf(ofp, "get it from the configuration file (.lttngrc).\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " --list-options Simple listing of options\n");
- fprintf(ofp, " -t, --trace-path PATH Trace directory path for the viewer\n");
- fprintf(ofp, " -e, --viewer CMD Specify viewer and/or options to use\n");
- fprintf(ofp, " This will completely override the default viewers so\n");
- fprintf(ofp, " please make sure to specify the full command. The trace\n");
- fprintf(ofp, " directory path of the session will be appended at the end\n");
- fprintf(ofp, " to the arguments\n");
- fprintf(ofp, "\n");
-}
-
static struct viewers *parse_options(void)
{
if (opt_viewer == NULL) {
while ((opt = poptGetNextOpt(pc)) != -1) {
switch (opt) {
case OPT_HELP:
- usage(stdout);
+ SHOW_HELP();
goto end;
case OPT_LIST_OPTIONS:
list_cmd_options(stdout, long_options);
goto end;
default:
- usage(stderr);
ret = CMD_UNDEFINED;
goto end;
}
#include <lttng/lttng.h>
#include <common/error.h>
#include <common/compat/getenv.h>
+#include <common/utils.h>
#include "command.h"
/* First level command */
static struct cmd_struct commands[] = {
- { "list", cmd_list},
- { "status", cmd_status},
+ { "add-context", cmd_add_context},
+ { "calibrate", cmd_calibrate},
{ "create", cmd_create},
{ "destroy", cmd_destroy},
- { "start", cmd_start},
- { "stop", cmd_stop},
- { "enable-event", cmd_enable_events},
+ { "disable-channel", cmd_disable_channels},
{ "disable-event", cmd_disable_events},
{ "enable-channel", cmd_enable_channels},
- { "disable-channel", cmd_disable_channels},
- { "add-context", cmd_add_context},
+ { "enable-event", cmd_enable_events},
+ { "help", NULL},
+ { "list", cmd_list},
+ { "load", cmd_load},
+ { "metadata", cmd_metadata},
+ { "save", cmd_save},
{ "set-session", cmd_set_session},
- { "version", cmd_version},
- { "calibrate", cmd_calibrate},
- { "view", cmd_view},
{ "snapshot", cmd_snapshot},
- { "save", cmd_save},
- { "load", cmd_load},
+ { "start", cmd_start},
+ { "status", cmd_status},
+ { "stop", cmd_stop},
{ "track", cmd_track},
{ "untrack", cmd_untrack},
- { "metadata", cmd_metadata},
+ { "help", NULL},
+ { "version", cmd_version},
+ { "view", cmd_view},
{ NULL, NULL} /* Array closure */
};
-static void usage(FILE *ofp)
-{
- fprintf(ofp, "LTTng Trace Control " VERSION " - " VERSION_NAME "%s\n\n",
- GIT_VERSION[0] == '\0' ? "" : " - " GIT_VERSION);
- fprintf(ofp, "usage: lttng [OPTIONS] <COMMAND> [<ARGS>]\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Options:\n");
- fprintf(ofp, " -V, --version Show version\n");
- fprintf(ofp, " -h, --help Show this help\n");
- fprintf(ofp, " --list-options Simple listing of lttng options\n");
- fprintf(ofp, " --list-commands Simple listing of lttng commands\n");
- fprintf(ofp, " -v, --verbose Increase verbosity\n");
- fprintf(ofp, " -q, --quiet Quiet mode\n");
- fprintf(ofp, " -m, --mi TYPE Machine Interface mode.\n");
- fprintf(ofp, " Type: xml\n");
- fprintf(ofp, " -g, --group NAME Unix tracing group name. (default: tracing)\n");
- fprintf(ofp, " -n, --no-sessiond Don't spawn a session daemon\n");
- fprintf(ofp, " --sessiond-path PATH Session daemon full path\n");
- fprintf(ofp, " --relayd-path PATH Relayd daemon full path\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Commands:\n");
- fprintf(ofp, " add-context Add context to event and/or channel\n");
- fprintf(ofp, " calibrate Quantify LTTng overhead\n");
- fprintf(ofp, " create Create tracing session\n");
- fprintf(ofp, " destroy Tear down tracing session\n");
- fprintf(ofp, " enable-channel Enable tracing channel\n");
- fprintf(ofp, " enable-event Enable tracing event\n");
- fprintf(ofp, " disable-channel Disable tracing channel\n");
- fprintf(ofp, " disable-event Disable tracing event\n");
- fprintf(ofp, " list List possible tracing options\n");
- fprintf(ofp, " set-session Set current session name\n");
- fprintf(ofp, " snapshot Snapshot buffers of current session name\n");
- fprintf(ofp, " start Start tracing\n");
- fprintf(ofp, " status Show current session's details\n");
- fprintf(ofp, " stop Stop tracing\n");
- fprintf(ofp, " version Show version information\n");
- fprintf(ofp, " view Start trace viewer\n");
- fprintf(ofp, " save Save session configuration\n");
- fprintf(ofp, " load Load session configuration\n");
- fprintf(ofp, " track Track specific system resources\n");
- fprintf(ofp, " untrack Untrack specific system resources\n");
- fprintf(ofp, " metadata Regenerate the metadata of a session\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Each command also has its own -h, --help option.\n");
- fprintf(ofp, "\n");
- fprintf(ofp, "Please see the lttng(1) man page for full documentation.\n");
- fprintf(ofp, "See http://lttng.org for updates, bug reports and news.\n");
-}
-
static void version(FILE *ofp)
{
fprintf(ofp, "%s (LTTng Trace Control) " VERSION" - " VERSION_NAME "%s\n",
goto end;
}
+ /* Special case for help command which needs the commands array */
+ if (strcmp(argv[0], "help") == 0) {
+ ret = cmd_help(argc, (const char**) argv, commands);
+ goto end;
+ }
+
cmd = &commands[i];
- while (cmd->func != NULL) {
+ while (cmd->name != NULL) {
/* Find command */
if (strcmp(argv[0], cmd->name) == 0) {
ret = cmd->func(argc, (const char**) argv);
}
if (argc < 2) {
- usage(stderr);
clean_exit(EXIT_FAILURE);
}
ret = 0;
goto end;
case 'h':
- usage(stdout);
- ret = 0;
+ ret = utils_show_man_page(1, "lttng");
+
+ if (ret) {
+ ERR("Cannot view man page lttng(1)");
+ perror("exec");
+ }
goto end;
case 'v':
/* There is only 3 possible level of verbosity. (-vvv) */
ret = 0;
goto end;
default:
- usage(stderr);
ret = 1;
goto error;
}
lttng_opt_verbose = 0;
}
- /* No leftovers, print usage and quit */
+ /* No leftovers, quit */
if ((argc - optind) == 0) {
- usage(stderr);
ret = 1;
goto error;
}
ERR("Command error");
break;
case CMD_UNDEFINED:
- ERR("Undefined command");
+ ERR("Undefined command or invalid arguments");
break;
case CMD_FATAL:
ERR("Fatal error");
ERR("Unsupported command");
break;
case -1:
- usage(stderr);
ret = 1;
break;
case 0:
#include <netinet/in.h>
#include <arpa/inet.h>
#include <inttypes.h>
+#include <unistd.h>
#include <common/error.h>
#include <common/utils.h>
+#include <common/defaults.h>
#include "conf.h"
#include "utils.h"
end:
return;
}
+
+int show_cmd_man_page(const char *cmd_name)
+{
+ int ret;
+ char page_name[32];
+
+ ret = sprintf(page_name, "lttng-%s", cmd_name);
+ assert(ret > 0 && ret < 32);
+
+ return utils_show_man_page(1, page_name);
+}
int spawn_relayd(const char *pathname, int port);
int check_relayd(void);
void print_session_stats(const char *session_name);
+int show_cmd_man_page(const char *cmd_name);
#endif /* _LTTNG_UTILS_H */
-AM_CPPFLAGS = -I$(top_srcdir)/include -I$(top_srcdir)/src
+AM_CPPFLAGS = -I$(top_srcdir)/include -I$(top_srcdir)/src \
+ -DMANPATH=\""$(mandir)"\"
AUTOMAKE_OPTIONS = subdir-objects
LPOLLNVAL = EPOLLHUP,
LPOLLRDHUP = EPOLLRDHUP,
/* Close on exec feature of epoll */
-#if __GLIBC_PREREQ(2, 9)
+#if defined(HAVE_EPOLL_CREATE1) && defined(EPOLL_CLOEXEC)
LTTNG_CLOEXEC = EPOLL_CLOEXEC,
#else
/*
#define lttng_poll_create(events, size, flags) \
compat_epoll_create(events, size, flags)
-#if __GLIBC_PREREQ(2, 9)
+#if defined(HAVE_EPOLL_CREATE1) && defined(EPOLL_CLOEXEC)
static inline int compat_glibc_epoll_create(int size __attribute__((unused)),
int flags)
{
/* Environment variable to set session daemon binary path. */
#define DEFAULT_SESSIOND_PATH_ENV "LTTNG_SESSIOND_PATH"
+/* Environment variable to set man pager binary path. */
+#define DEFAULT_MAN_BIN_PATH_ENV "LTTNG_MAN_BIN_PATH"
+
+/* Default man pager binary path. */
+#define DEFAULT_MAN_BIN_PATH "/usr/bin/man"
+
/* Default trace output directory name */
#define DEFAULT_TRACE_DIR_NAME "lttng-traces"
#define _LTT_KERNEL_IOCTL_H
#define LTTNG_MODULES_ABI_MAJOR_VERSION 2
-#define LTTNG_MODULES_ABI_MINOR_VERSION 0
+#define LTTNG_MODULES_ABI_MINOR_VERSION 1
/* Get a snapshot of the current ring buffer producer and consumer positions */
#define RING_BUFFER_SNAPSHOT _IO(0xF6, 0x00)
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
+#include <sys/types.h>
#include <unistd.h>
#include <pthread.h>
PERROR("lseek");
goto end;
}
-
end:
return ret;
}
+
+static const char *get_man_bin_path(void)
+{
+ char *env_man_path = getenv(DEFAULT_MAN_BIN_PATH_ENV);
+
+ if (env_man_path) {
+ return env_man_path;
+ }
+
+ return DEFAULT_MAN_BIN_PATH;
+}
+
+LTTNG_HIDDEN
+int utils_show_man_page(int section, const char *page_name)
+{
+ char section_string[8];
+ const char *man_bin_path = get_man_bin_path();
+ int ret;
+
+ /* Section integer -> section string */
+ ret = sprintf(section_string, "%d", section);
+ assert(ret > 0 && ret < 8);
+
+ /*
+ * Execute man pager.
+ *
+ * We provide --manpath to man here because LTTng-tools can
+ * be installed outside /usr, in which case its man pages are
+ * not located in the default /usr/share/man directory.
+ */
+ ret = execlp(man_bin_path, "man", "--manpath", MANPATH,
+ section_string, page_name, NULL);
+ return ret;
+}
int utils_create_lock_file(const char *filepath);
int utils_recursive_rmdir(const char *path);
int utils_truncate_stream_file(int fd, off_t length);
+int utils_show_man_page(int section, const char *page_name);
#endif /* _COMMON_UTILS_H */
projects / lttng-tools.git / commitdiff
