[enable_built_in_python_plugin_support=no]
)
+# Man pages
+# Enabled by default
+AC_ARG_ENABLE([man-pages],
+ [AS_HELP_STRING([--disable-man-pages], [Do not build and install man pages (already built in a distributed tarball])],
+ [], dnl AC_ARG_ENABLE will fill enable_built_in_plugins with the user choice
+ [enable_man_pages=yes]
+)
+
# Set automake variables for optionnal feature conditionnals in Makefile.am
AM_CONDITIONAL([ENABLE_PYTHON_BINDINGS], [test "x$enable_python_bindings" = xyes])
AM_CONDITIONAL([ENABLE_API_DOC], [test "x$enable_api_doc" = xyes])
AM_CONDITIONAL([ENABLE_BUILT_IN_PLUGINS], [test "x$enable_built_in_plugins" = xyes])
AM_CONDITIONAL([ENABLE_BUILT_IN_PYTHON_PLUGIN_SUPPORT], [test "x$enable_built_in_python_plugin_support" = xyes])
+AM_CONDITIONAL([ENABLE_MAN_PAGES], [test "x$enable_man_pages" = xyes])
# Set defines for optionnal features conditionnals in the source code
[AC_DEFINE([BT_BUILT_IN_PYTHON_PLUGIN_SUPPORT], [1], [Define to 1 to register plug-in attributes in static executable sections])]
)
+AS_IF([test "x$enable_debug_info" = xyes],
+ [ENABLE_DEBUG_INFO_VAL=1],
+ [ENABLE_DEBUG_INFO_VAL=0]
+)
+
+AC_SUBST([ENABLE_DEBUG_INFO_VAL])
+
# Check for conflicting optional features user choices
]
)
+have_asciidoc_xmlto=no
+warn_prebuilt_man_pages=no
+
+AS_IF([test "x$enable_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"], [
+ AS_IF([test "x$in_git_repo" = "xyes"], [
+ # this is an error because we're in the Git repo, which
+ # means the man pages are not already generated for us,
+ # thus asciixmlto are required because we were asked
+ # to build the man pages
+ AC_MSG_ERROR([
+You need asciidoc and xmlto to build the Babeltrace man pages. Use
+--disable-man-pages to disable building the man pages, in which case
+they will not be installed.
+ ])
+ ], [
+ # only warn here: since we're in the tarball, the man
+ # pages should already be generated at this point, thus
+ # asciidoc/xmlto are not strictly required
+ warn_prebuilt_man_pages=yes
+ ])
+ ], [
+ have_asciidoc_xmlto=yes
+ ])
+])
+
+# export AsciiDoc and xmlto existence
+AM_CONDITIONAL([HAVE_ASCIIDOC_XMLTO], [test "x$have_asciidoc_xmlto" = "xyes"])
+
+# a wonderful hack that seems necessary because $libdir is
+# literally `${exec_prefix}/lib`, and $exec_prefix is set to `NONE`
+# by autoconf when it's not specified by the user
+AS_IF([test "x$exec_prefix" = xNONE], [
+ AS_IF([test "x$prefix" = xNONE], [
+ PREFIX="$ac_default_prefix"
+ ], [
+ PREFIX="$prefix"
+ ])
+
+ LIBDIR="$PREFIX/lib"
+], [
+ LIBDIR="$libdir"
+])
+
+AC_SUBST(LIBDIR)
+
# Set global CFLAGS in AM_CFLAGS
AM_CFLAGS="-Wall -Wformat $PTHREAD_CFLAGS $GLIB_CFLAGS"
doc/bindings/Makefile
doc/bindings/python/Makefile
doc/contributing-images/Makefile
+ doc/man/Makefile
+ doc/man/asciidoc-attrs.conf
lib/Makefile
lib/prio_heap/Makefile
lib/plugin/Makefile
AS_ECHO
PPRINT_SUBTITLE([Documentation])
+
+# man pages build enabled/disabled
+m4_pushdef([build_man_pages_msg], [Build and install man pages])
+
+AS_IF([test "x$enable_man_pages" != "xno"], [
+ AS_IF([test "x$in_git_repo" = "xyes"], [
+ PPRINT_PROP_BOOL([build_man_pages_msg], 1)
+ ], [
+ AS_IF([test "x$have_asciidoc_xmlto" = "xyes"], [
+ PPRINT_PROP_BOOL([build_man_pages_msg], 1)
+ ], [
+ PPRINT_PROP_STRING([build_man_pages_msg],
+ [${PPRINT_COLOR_BLDGRN}yes (already built)],
+ $PPRINT_COLOR_SUBTITLE)
+ ])
+ ])
+], [
+ PPRINT_PROP_BOOL([build_man_pages_msg], 0)
+])
+
+m4_popdef([build_man_pages_msg])
+
test "x$enable_api_doc" = "xyes" && value=1 || value=0
PPRINT_PROP_BOOL([HTML API documentation], $value)
test "x$enable_python_bindings_doc" = "xyes" && value=1 || value=0
-SUBDIRS = bindings contributing-images
+SUBDIRS = bindings contributing-images man
if ENABLE_API_DOC
SUBDIRS += api
endif
-dist_man_MANS = babeltrace.1 babeltrace-log.1
-
-EXTRA_DIST = API.txt lttng-live.txt
+EXTRA_DIST = API.txt
+++ /dev/null
-.TH "BABELTRACE-LOG" "1" "February 16, 2012" "" ""
-
-.SH "NAME"
-babeltrace-log \(em Babeltrace Log Converter
-
-.SH "SYNOPSIS"
-
-.PP
-.nf
-babeltrace-log [OPTIONS] OUTPUT
-.fi
-.SH "DESCRIPTION"
-
-.PP
-Convert from a text log (read from standard input) to CTF.
-
-.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 "OUTPUT"
-Output trace path
-.TP
-.BR "-t"
-With timestamps (format: [sec.usec] string\\n)
-.TP
-
-.SH "SEE ALSO"
-
-.PP
-babeltrace(1), lttng(1), lttng-ust(3), lttng-sessiond(8)
-.PP
-.SH "BUGS"
-
-.PP
-No knows bugs at this point.
-
-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"
-
-Babeltrace and the babeltrace library are distributed under the MIT
-license. See the files LICENSE and mit-license.txt for details.
-.PP
-A Web site is available at http://www.efficios.com/babeltrace for more
-information on Babeltrace and the Common Trace Format. See
-http://lttng.org for more information on the LTTng project.
-.PP
-Mailing list 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"
-
-Thanks to the Linux Foundation and Ericsson for funding part of this
-work. Thanks to the Multicore Association Tool Infrastructure Working
-Group for their active role in the creation of the Common Trace Format.
-.PP
-.SH "AUTHORS"
-
-.PP
-Babeltrace was originally written by Mathieu Desnoyers, with additional
-contributions from various other people. It is currently maintained by
-Mathieu Desnoyers <mathieu.desnoyers@efficios.com>.
-.PP
+++ /dev/null
-.TH "BABELTRACE" "1" "February 6, 2012" "" ""
-
-.SH "NAME"
-babeltrace \(em Babeltrace Trace Viewer and Converter
-
-.SH "SYNOPSIS"
-
-.PP
-.nf
-babeltrace [OPTIONS] FILE...
-.fi
-.SH "DESCRIPTION"
-
-.PP
-Babeltrace is a trace viewer and converter reading and writing the
-Common Trace Format (CTF). Its main use is to pretty-print CTF traces
-into a human-readable text output ordered by time.
-
-.PP
-This program follow the usual GNU command line syntax with long options
-starting with two dashes. Below is a summary of the available options.
-.PP
-
-.TP
-.BR "FILE"
-Input trace FILE(s) or directory(ies)
-.TP
-.BR "-w, --output OUTPUT"
-Output trace path (default: stdout)
-.TP
-.BR "-i, --input-format FORMAT"
-Input trace format (default: ctf)
-.TP
-.BR "-o, --output-format FORMAT"
-Output trace format (default: text)
-.TP
-.BR "-h, --help"
-This help message
-.TP
-.BR "-l, --list"
-List available formats
-.TP
-.BR "-v, --verbose"
-Verbose mode (or set BABELTRACE_VERBOSE environment variable)
-.TP
-.BR "-d, --debug"
-Debug mode (or set BABELTRACE_DEBUG environment variable)
-.TP
-.BR "--no-delta"
-Do not print time delta between consecutive events
-.TP
-.BR "-n, --names name1<,name2,...>"
-Print field names: (payload OR args OR arg), none, all, scope, header,
-(context OR ctx), (default: payload,context).
-.TP
-.BR "-f, --fields name1<,name2,...>"
-Print additional fields: all, trace, trace:hostname, trace:domain,
-trace:procname, trace:vpid, loglevel.
-.TP
-.BR "--clock-cycles"
-Disregard internal clock offset (use raw value)
-.TP
-.BR "--clock-offset seconds"
-Clock offset in seconds
-.TP
-.BR "--clock-seconds"
-Print the timestamps as [sec.ns] (default is: [hh:mm:ss.ns])
-.TP
-.BR "--clock-date"
-Print clock date
-.TP
-.BR "--clock-gmt"
-Print clock in GMT time zone (default: local time zone)
-.TP
-.BR "--stream-intersection"
-Only print events when all streams are active
-.TP
-.BR "--debug-info-dir"
-Directory in which to look for debugging information files (default: /usr/lib/debug/)
-.TP
-.BR "--debug-info-target-prefix"
-Directory to use as a prefix for executable lookup
-.TP
-.BR "--debug-info-full-path"
-Show full debug info source and binary paths (if available)
-.TP
-
-.fi
-Formats available: ctf, lttng-live, dummy, text, ctf-metadata.
-
-.SH "ENVIRONMENT VARIABLES"
-
-.PP
-Note that all command line options will override environment variables.
-.PP
-
-.PP
-.IP "BABELTRACE_VERBOSE"
-Activate verbose Babeltrace output.
-.PP
-.IP "BABELTRACE_DEBUG"
-Activate debug Babeltrace output.
-
-.SH "SEE ALSO"
-
-.PP
-babeltrace-log(1), lttng(1), lttng-ust(3), lttng-sessiond(8)
-.PP
-.SH "BUGS"
-
-.PP
-The lttng-live plugin does not honor the the "--output" command line
-option.
-
-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"
-
-Babeltrace and the babeltrace library are distributed under the MIT
-license. See the files LICENSE and mit-license.txt for details.
-.PP
-A Web site is available at http://www.efficios.com/babeltrace for more
-information on Babeltrace and the Common Trace Format. See
-http://lttng.org for more information on the LTTng project.
-.PP
-Mailing list 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"
-
-Thanks to the Linux Foundation and Ericsson for funding part of this
-work. Thanks to the Multicore Association Tool Infrastructure Working
-Group for their active role in the creation of the Common Trace Format.
-.PP
-.SH "AUTHORS"
-
-.PP
-Babeltrace was originally written by Mathieu Desnoyers, with additional
-contributions from various other people. It is currently maintained by
-Mathieu Desnoyers <mathieu.desnoyers@efficios.com>.
-.PP
+++ /dev/null
-Babeltrace Debug Info Analysis
------------------------------
-
-The babeltrace debug info analysis is a set of features which allow
-mapping events from a trace to their location in source code or within
-a binary file, based on their `ip` (instruction pointer) field.
-
-Prerequisites
--------------
-
-In order to install a version of babeltrace with debug info support,
-the following libraries are required:
-
- * libelf
- * libdw
-
-Both of them are provided by the elfutils project
-(https://fedorahosted.org/elfutils/), and can be installed through the
-elfutils package on Ubuntu, Debian, RHEL, and others.
-
-Compiling for Debug Info Analysis
----------------------------------
-
-Traced programs on which debug info analysis is to be performed can be
-compiled in a few different ways, and still lead to useful results.
-
-Ideally, one should compile the program in debug mode, which is
-achieved on gcc by simply using the `-g` flag. This generates debug
-information in the operating system's native format, which is then
-used by babeltrace to map an event's source location to a file and
-line number, and the name of the surrounding function.
-
-Do note that only debug information in DWARF format, version 2 or
-later, is currently supported by babeltrace. Use the `-gdwarf` or
-`-gdwarf-(VERSION)` to explicitly generate DWARF debug information.
-
-If the executable is not compiled with `-g` or an equivalent option
-enabled, and thus no DWARF information is available, babeltrace will
-use ELF symbols from the executable. Instead of providing source file,
-line number and function name, however, the analysis will provide the
-name of the nearest function symbol, plus an offset in bytes to the
-location in the executable from which the event originated.
-
-If the executable has neither ELF symbols nor DWARF information,
-babeltrace will be unable to map an event to its source location and
-will simply display the instruction pointer (address), as in prior
-versions of babeltrace.
-
-Getting the Right Tracer
-------------------------
-
-Debug info analysis is performed automatically by babeltrace, provided
-the trace contains sufficient information. In order to be able to
-trace all the necessary information, the following software is
-required:
-
- * lttng-ust version 2.8.0 or later
- * lttng-tools, corresponding version
-
-You can get these from source at:
-
- * https://github.com/lttng/lttng-ust
- * https://github.com/lttng/lttng-tools
-
-Ubuntu users also have the option of installing via the LTTng daily
-PPA:
-
- * https://launchpad.net/~lttng/+archive/ubuntu/daily
-
-Tracing for Debug Info Analysis
--------------------------------
-
-Babeltrace needs some extra information from contexts, namely ip and
-vpid, to perform its analysis. These can be enabled after the creation
-of a tracing session as follows:
-
- $ lttng add-context --userspace --type ip --type vpid
-
-The tracing can then be performed as it normally would. Once the trace
-is collected, it can the be read by babeltrace for analysis.
-
-Analysing the Trace
--------------------
-
-To perform the analysis, the trace can simply be read as it normally
-would:
-
- $ babeltrace <path/to/trace>
-
-Debug info analysis is on by default and will automatically print the
-extra source location information if it can find it. A sample output
-may look like this:
-
- [...]
- [16:18:15.845829429] (+0.000011697) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D550E, debug_info = { bin = "libhello.so+0x150e", func = "foo+0xa9", src = "libhello.c:7" }, vpid = 28719 }, { my_string_field = "hello, tracer", my_integer_field = 42 }
- [16:18:15.845841484] (+0.000012055) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D55E0, debug_info = { bin = "libhello.so+0x15e0", func = "bar+0xa9", src = "libhello.c:13" }, vpid = 28719 }, { my_string_field = "recoltes et semailles", my_integer_field = 57 }
- [16:18:15.845844852] (+0.000003368) colossus my_provider:my_other_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D56A5, debug_info = { bin = "libhello.so+0x16a5", func = "baz+0x9c", src = "libhello.c:20" }, vpid = 28719 }, { some_field = 1729 }
- [...]
-
-The interesting part is the debug_info section of the context:
-
- debug_info = { bin = "libhello.so+0x150e", func = "foo+0xa9", src = "libhello.c:7" }
-
-This is the expected output for events generated by an executable for
-which DWARF information is available. It shows the name of the binary
-and offset to the tracepoint, the name of the function containing the
-tracepoint instance which generated the event ("foo") and the offset
-within the function, and its source location ("libhello.c", line 7).
-
-The second event in the sample output is of the same type
-("my_first_tracepoint"), but it was generated by a different
-tracepoint instance, hence the different source location (line 13) and
-function ("bar").
-
-The third event, of a different type, also shows debug information.
-
-If DWARF info is absent, but ELF symbols are not stripped, the output
-will instead look like this:
-
- [...]
- [16:18:15.845829429] (+0.000011697) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D550E, debug_info = { bin = "libhello.so+0x150e", func = "foo+0xa9" }, vpid = 28719 }, { my_string_field = "hello, tracer", my_integer_field = 42 }
- [16:18:15.845841484] (+0.000012055) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D55E0, debug_info = { bin = "libhello.so+0x15e0", func = "bar+0xa9" }, vpid = 28719 }, { my_string_field = "recoltes et semailles", my_integer_field = 57 }
- [16:18:15.845844852] (+0.000003368) colossus my_provider:my_other_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D56A5, debug_info = { bin = "libhello.so+0x16a5", func = "baz+0x9c" }, vpid = 28719 }, { some_field = 1729 }
- [...]
-
-The debug information now provides both binary and function location
-information, but no source location information, as this requires
-DWARF. The function names are in fact resolved using ELF symbols, so
-there may be a discrepancy with those provided by DWARF (e.g. in the
-case of mangling).
-
-Paths to the binary and to the source location (if any) can be
-expanded by using the command-line option
---debug-info-full-path. Otherwise, only the filename is shown.
-
-Debug Info and Dynamic Loading
-------------------------------
-
-Babeltrace can resolve addresses of events originating from
-dynamically loaded libraries, provided that some extra information is
-collected at tracing time.
-
-This can be achieved by preloading LTTng UST's libdl helper when
-launching the program to be traced, like so:
-
- $ LD_PRELOAD="liblttng-ust-dl.so" <path/to/executable>
-
-The tracing and analysis can now be performed as described in prior
-sections, and events from tracepoints in dlopened libraries will be
-resolved automatically by babeltrace.
-
-Separate Debug Info
--------------------
-
-It is possible to store DWARF debug information separate from an
-executable, whether for concerns of file size, or simply to facilitate
-the sharing of the debug information.
-
-This is usually achieved via one of two mechanisms, namely build ID
-and debug link. Both methods permit separate executables and debug
-information. Their use and operation is described in GDB's
-documentation at:
-
- https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html
-
-Babeltrace will find separate debug files automatically, provided they
-follow the requirements described in the documentation above. The
-debug information lookup order is the same as GDB's, that is first
-debug info is looked for within the executable, then through the build
-ID method in the standard /usr/lib/debug/.build-id/ location, and
-finally in the various possible debug link locations. The first debug
-information file found is used.
-
-The --debug-info-dir command-line option can be used to override the
-default /usr/lib/debug/ directory used in build ID and debug link
-lookups. Multiple debug info directories are currently not supported.
-
-Target Prefix
--------------
-
-The debug info analysis uses the paths to the executables as collected
-during tracing as one mechanism to resolve DWARF or ELF
-information. If the trace was taken on a separate machine, for
-instance, it is possible to use --debug-info-target-prefix to specify
-a prefix directory, representing the root of the target filesystem,
-which will then be used for lookups. For example, if an executable was
-located at /usr/bin/foo on the target system, it could be placed at
-/home/efficios/target/usr/bin/foo on the system on which the analysis
-is performed. In this case, the prefix is /home/efficios/target/.
+++ /dev/null
-LTTNG LIVE
-----------
-
-This is a brief howto for using the Babeltrace with LTTng live protocol.
-LTTng live allows the user to read a trace while it is running.
-
-In order to create a live LTTng session, please refer to the LTTng
-documentation (version >= 2.4).
-
-Once the session is created and Babeltrace is installed, you can list the
-sessions with :
-$ babeltrace -i lttng-live net://<your-relayd-hostname>
-
-The output should look like this :
-net://localhost/host/myhostname/mysessionname (timer = 1000000, 5 stream(s), 0 client(s) connected)
-
-It means that the session mysessionname on the host myhostname is currently
-streaming its data to the relayd on localhost.
-
-To attach to this session and start receiving the trace :
-$ babeltrace -i lttng-live net://localhost/host/myhostname/mysessionname
-
-You should now see trace data flowing in your console when events are produced.
-
-To report bugs, please use the same procedure as reporting bugs to Babeltrace,
-but don't forget to add the -v to the commands above to provide enough debug
-information.
--- /dev/null
+*.1
+*.7
+*.xml
+*.html
+asciidoc-attrs.conf
--- /dev/null
+# Man pages are only built if they are enabled at configure time.
+#
+# 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 = \
+ babeltrace \
+ babeltrace-convert \
+ babeltrace-help \
+ babeltrace-list-plugins \
+ babeltrace-log \
+ babeltrace-query \
+ babeltrace-run
+MAN7_NAMES =
+MAN1_NO_ASCIIDOC_NAMES =
+MAN7_NO_ASCIIDOC_NAMES = \
+ babeltrace-filter.utils.muxer \
+ babeltrace-filter.utils.trimmer \
+ babeltrace-intro \
+ babeltrace-plugin-ctf \
+ babeltrace-plugin-text \
+ babeltrace-plugin-utils \
+ babeltrace-sink.ctf.fs \
+ babeltrace-sink.text.pretty \
+ babeltrace-sink.utils.counter \
+ babeltrace-sink.utils.dummy \
+ babeltrace-source.ctf.fs \
+ babeltrace-source.ctf.lttng-live \
+ babeltrace-source.text.dmesg
+
+if ENABLE_DEBUG_INFO
+MAN7_NO_ASCIIDOC_NAMES += \
+ babeltrace-plugin-lttng-utils \
+ babeltrace-filter.lttng-utils.debug-info
+endif
+
+# AsciiDoc sources and outputs
+MAN1_TXT = $(call manaddsuffix,.1.txt,$(MAN1_NAMES))
+MAN7_TXT = $(call manaddsuffix,.7.txt,$(MAN7_NAMES))
+MAN_TXT = $(MAN1_TXT) $(MAN7_TXT)
+MAN_XML = $(patsubst $(srcdir)/%.txt,%.xml,$(MAN_TXT))
+
+# common AsciiDoc source files
+COMMON_TXT = \
+ $(srcdir)/common-cli-env.txt \
+ $(srcdir)/common-cli-files.txt \
+ $(srcdir)/common-cmd-footer.txt \
+ $(srcdir)/common-cmd-info-options.txt \
+ $(srcdir)/common-cmd-params-format.txt \
+ $(srcdir)/common-cmd-plugin-path.txt \
+ $(srcdir)/common-common-compat-env.txt \
+ $(srcdir)/common-ctf-plugin-env.txt \
+ $(srcdir)/common-footer.txt \
+ $(srcdir)/common-gen-options.txt \
+ $(srcdir)/common-lib-env.txt \
+ $(srcdir)/common-plugin-path-options.txt \
+ $(srcdir)/common-ppp-env.txt
+
+# config
+ASCIIDOC_CONF = $(srcdir)/bt-asciidoc.conf
+ASCIIDOC_ATTRS_CONF = $(builddir)/asciidoc-attrs.conf
+XSL_SRC_FILE = $(srcdir)/manpage.xsl
+
+# common dependencies
+COMMON_DEPS = $(ASCIIDOC_CONF) $(COMMON_TXT)
+
+# man pages destinations
+MAN1 = $(addsuffix .1,$(MAN1_NAMES))
+MAN7 = $(addsuffix .7,$(MAN7_NAMES))
+MAN1_NO_ASCIIDOC = $(addsuffix .1,$(MAN1_NO_ASCIIDOC_NAMES))
+MAN7_NO_ASCIIDOC = $(addsuffix .7,$(MAN7_NO_ASCIIDOC_NAMES))
+MAN = $(MAN1) $(MAN7)
+
+if ENABLE_MAN_PAGES
+# at this point, we know the user asked to build the man pages
+if HAVE_ASCIIDOC_XMLTO
+asciidoc_verbose = $(asciidoc_verbose_@AM_V@)
+asciidoc_verbose_ = $(asciidoc_verbose_@AM_DEFAULT_V@)
+asciidoc_verbose_0 = @echo " ASCIIDOC " $@;
+xmlto_verbose = $(xmlto_verbose_@AM_V@)
+xmlto_verbose_ = $(xmlto_verbose_@AM_DEFAULT_V@)
+xmlto_verbose_0 = @echo " XMLTO " $@;
+
+# tools
+ADOC = $(asciidoc_verbose)$(ASCIIDOC) -f $(ASCIIDOC_CONF) -f $(ASCIIDOC_ATTRS_CONF) -d manpage
+ADOC_DOCBOOK = $(ADOC) -b docbook
+XTO = $(xmlto_verbose)$(XMLTO) -m $(XSL_SRC_FILE) man
+
+# only add this dependency if we can build the man pages because it's
+# a file generated by the configure script, so it's more recent than
+# the pregenerated man pages in a tarball
+COMMON_DEPS += $(ASCIIDOC_ATTRS_CONF)
+
+# recipes
+%.1.xml: $(srcdir)/%.1.txt $(COMMON_DEPS)
+ $(ADOC_DOCBOOK) -o $@ $<
+
+%.1: %.1.xml $(XSL_SRC_FILE)
+ $(XTO) $< 2>/dev/null
+
+%.7.xml: $(srcdir)/%.7.txt $(COMMON_DEPS)
+ $(ADOC_DOCBOOK) -o $@ $<
+
+%.7: %.7.xml $(XSL_SRC_FILE)
+ $(XTO) $< 2>/dev/null
+
+# only clean the generated files if we have the tools to generate them again
+CLEANFILES = $(MAN_XML) $(MAN)
+else # HAVE_ASCIIDOC_XMLTO
+# create man page targets used to stop the build if we want to
+# build the man pages, but we don't have the necessary tools to do so
+ERR_MSG = "Error: Cannot build target because asciidoc or xmlto tool is missing."
+ERR_MSG += "Make sure both tools are installed and run the configure script again."
+
+%.1: $(srcdir)/%.1.txt $(COMMON_DEPS)
+ @echo $(ERR_MSG)
+ @false
+
+%.7: $(srcdir)/%.7.txt $(COMMON_DEPS)
+ @echo $(ERR_MSG)
+ @false
+endif # HAVE_ASCIIDOC_XMLTO
+endif # ENABLE_MAN_PAGES
+
+# those are always installed since they are directly written in troff
+dist_man1_MANS = $(MAN1_NO_ASCIIDOC)
+dist_man7_MANS = $(MAN7_NO_ASCIIDOC)
+
+if ENABLE_MAN_PAGES
+# building man pages: we can install and distribute them
+dist_man1_MANS += $(MAN1)
+dist_man7_MANS += $(MAN7)
+endif # ENABLE_MAN_PAGES
+
+if !ENABLE_MAN_PAGES
+dist-hook:
+ @echo "Error: Please enable the man pages before creating a distribution tarball."
+ @false
+endif # !ENABLE_MAN_PAGES
+
+# always distribute the source files
+EXTRA_DIST = README.adoc $(MAN_TXT) $(COMMON_TXT) $(XSL_SRC_FILE) \
+ $(ASCIIDOC_CONF) $(ASCIIDOC_ATTRS_CONF).in
--- /dev/null
+= Babeltrace man pages
+Philippe Proulx
+4 October 2017
+
+This directory contains the sources of the Babeltrace man pages.
+
+The Babeltrace man pages are written in
+http://www.methods.co.nz/asciidoc/[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).
+
+
+== Naming
+
+Main program::
+ +__program__.1.txt+
+
+`babeltrace(1)` command::
+ +babeltrace-__command__.1.txt+
+
+Babeltrace introduction::
+ `babeltrace-intro.7.txt`
+
+Babeltrace plugin::
+ +babeltrace-plugin-__plugin__.7.txt+
+
+Babeltrace plugin's component class::
+ +babeltrace-__type__.__plugin__.__compcls__.7.txt+
+
+
+== Macros
+
+AsciiDoc is configured with `bt-asciidoc.conf` which contains a few
+macro definitions used everywhere in the man page sources:
+
++man:__page__(__section__)+::
+ Use this macro to insert a link to another man page named
+ +__page__+ in section +__section__+. In troff, the man page's name
+ is rendered in bold.
++
+Example: `man:babeltrace-convert(1)`
+
++opt:__name__+::
+ Use this macro to insert a link to the command-line option
+ +__name__+ described in an _OPTIONS_ section in the same man page.
++
+Example: `opt:--verbose`, `opt:--color='WHEN'`
+
++manopt:__page__(__section__):__name__+::
+ Use this macro to insert a link to the command-line option
+ +__name__+ described in the _OPTIONS_ section of another Babeltrace
+ or LTTng man page named +__page__+ in section +__section__+.
++
+Example: `manopt:babeltrace(1):--log-level`,
++manopt:babeltrace-convert(1):--component=\`source.ctf.fs`+
+
++nlopt:__name__+::
+ Use this macro to write a command-line option named +__name__+
+ without inserting a link. The option does not need to be described
+ in the same man page.
++
+Example: `nlopt:--help`
+
++param:__name__+::
+ Use this macro to insert a link to the component initialization
+ parameter named +__name__+ described in an _INITIALIZATION
+ PARAMETERS_ section in the same man page.
++
+Example: `param:begin`, `param:path='PATH'`
+
++manparam:__type__.__plug__.__compclsname__:__paramname__+::
+ Use this macro to insert a link to the component initialization
+ parameter +__paramname__+ described in the _INITIALIZATION
+ PARAMETERS_ section of the man page of another Babeltrace component
+ class. The component class has the type +__type__+, is found in the
+ plugin named +__plug__+ and is named +__name__+.
++
+Example: `manparam:filter.utils.trimmer:begin`,
+`manparam:source.ctf.fs:path`
+
++nlparam:__name__+::
+ Use this macro to write a component initialization parameter named
+ +__name__+ without inserting a link. The parameter does not need to
+ be described in the same man page.
++
+Example: `nlparam:end`
+
++compcls:__type__.__plug__.__name__+::
+ Use this macro to write a component class specification. The
+ component class has the type +__type__+, is found in the plugin
+ named +__plug__+ and is named +__name__+.
++
+Example: `compcls:source.ctf.fs`, `compcls:filter.utils.muxer`
+
+`:not:`::
+ Use `:not:` to emphasize _not_.
+
+`:escstar:`::
+ Use `:escstar:` to insert `\*` literally.
+
+`:esccomma:`::
+ Use `:esccomma:` to insert `\,` literally.
+
+`:escdot:`::
+ Use `:escdot:` to insert `\.` literally.
+
+
+== Attributes
+
+`manpagetype`::
+ Each man page must set this attribute to the type (lowercase) of the
+ man page: `program`, `command`, `plugin`, or `component class`. It's
+ used in various included files to output a text that is more
+ targeted.
+
+`revdate`::
+ Each man page should have its own revision date with the following
+ https://en.wikipedia.org/wiki/Date_and_time_notation_in_the_United_Kingdom[British format]:
+ _28 October 1987_.
++
+Make sure to update this date when you update a given man page. We are
+not generating the date automatically because we want the real last
+revision date in the man page, not the last build date.
+
+Also see `asciidoc-attrs.conf` which is generated by `config.status`
+from `asciidoc-attrs.conf.in`. This file contains fixed and
+configuration-dependent attributes which you can use anywhere in the
+sources.
+
+
+== Style
+
+Apply the recommendations of the
+link:https://github.com/lttng/lttng-docs/blob/master/CONTRIBUTING.adoc#style-considerations[_Style
+considerations_] section of the LTTng Documentation's contributor's
+guide.
--- /dev/null
+[attributes]
+# default values
+system_plugin_path="@LIBDIR@/babeltrace/plugins"
+babeltrace_version="@PACKAGE_VERSION@"
+enable_debug_info="@ENABLE_DEBUG_INFO_VAL@"
--- /dev/null
+babeltrace-convert(1)
+=====================
+:manpagetype: command
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-convert - Convert one or more traces
+
+
+SYNOPSIS
+--------
+Convert one or more traces:
+
+[verse]
+*babeltrace convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
+ [opt:--omit-system-plugin-path]
+ [opt:--plugin-path='PATH'[:__PATH__]...]
+ [opt:--run-args | opt:--run-args-0] [opt:--retry-duration='DURUS']
+ 'CONVERSION ARGUMENTS'
+
+Print the metadata text of a CTF trace:
+
+[verse]
+*babeltrace convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
+ [opt:--omit-system-plugin-path]
+ [opt:--plugin-path='PATH'[:__PATH__]...]
+ opt:--output-format=`ctf-metadata` 'TRACE-PATH'
+
+Print the available http://lttng.org/docs/#doc-lttng-live[LTTng live]
+sessions:
+
+[verse]
+*babeltrace convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
+ [opt:--omit-system-plugin-path]
+ [opt:--plugin-path='PATH'[:__PATH__]...]
+ opt:--input-format=`lttng-live` 'URL'
+
+
+DESCRIPTION
+-----------
+The `convert` command creates a trace conversion graph and runs it.
+
+See man:babeltrace-intro(7) to learn more about the Babeltrace
+project and its core concepts.
+
+[NOTE]
+====
+`convert` is the default man:babeltrace(1) command: you usually don't
+need to specify its name. The following commands are equivalent
+if the `...` part does not start with another man:babeltrace(1)
+command's name, like `run` or `list-plugins`:
+
+[role="term"]
+----
+$ babeltrace convert ...
+$ babeltrace ...
+----
+
+If you need to make sure that you are executing the `convert` command,
+use `babeltrace convert` explicitly.
+====
+
+A conversion graph is a specialized trace processing graph focused on
+the conversion of one or more traces to another format, possibly
+filtering their events and other notifications in the process. A
+conversion graph is a linear chain of components after the source
+streams are merged:
+
+----
++----------+
+| source 1 |-.
++----------+ |
+ | +-------+
++----------+ '->| | +---------+ +------------+
+| source 2 |--->| muxer |--->| trimmer |--->| debug-info |-.
++----------+ .->| | +---------+ +------------+ |
+ | +-------+ |
++----------+ | .----------------------------------------'
+| ... |-' | +---------------+ +------+
++----------+ '->| other filters |--->| sink |
+ +---------------+ +------+
+----
+
+Note that the trimmer, debugging information, and other filters are
+optional. See <<comp-create-impl,Create implicit components>> to learn
+how to enable them.
+
+If you need another processing graph layout, use the more flexible
+man:babeltrace-run(1) command.
+
+Like with the man:babeltrace-run(1) command, you can create components
+explicitly with the opt:--component option (see
+<<comp-create-expl,Create explicit components>>). You can also use one
+of the many specific `convert` command options and arguments to create
+implicit components from known component classes (see
+<<comp-create-impl,Create implicit components>>). For example, you can
+specify a single path argument to print the merged events of a CTF trace
+on the console:
+
+[role="term"]
+----
+$ babeltrace /path/to/trace
+----
+
+This is the equivalent of creating and connecting together:
+
+* A compcls:src.ctf.fs component with its manparam:source.ctf.fs:path
+ initialization parameter set to `/path/to/trace`.
+
+* A compcls:filter.utils.muxer component.
+
+* A compcls:sink.text.pretty component.
+
+This creates the following conversion graph:
+
+----
++------------+ +--------------------+ +------------------+
+| src.ctf.fs | | filter.utils.muxer | | sink.text.pretty |
+| [ctf-fs] | | [muxer] | | [pretty] |
+| | | | | |
+| stream0 @--->@ out @--->@ in |
+| stream1 @--->@ | +------------------+
+| stream2 @--->@ |
+| stream3 @--->@ |
++------------+ +--------------------+
+----
+
+It is equivalent to the following command:
+
+[role="term"]
+----
+$ babeltrace run --component=ctf-fs:src.ctf.fs \
+ --key=path --value=/path/to/trace \
+ --component=pretty:sink.text.pretty \
+ --component=muxer:filter.utils.muxer \
+ --connect=ctf-fs:muxer --connect=muxer:pretty
+----
+
+You can use the opt:--run-args option to make the `convert` command
+print its equivalent man:babeltrace-run(1) arguments instead of
+creating and running the conversion graph. The printed arguments are
+escaped for shells, which means you can use them as is on the command
+line and possibly add more options to the `run` command:
+
+[role="term"]
+----
+$ babeltrace run $(babeltrace --run-args /path/to/trace) ...
+----
+
+The opt:--run-args-0 option is like the opt:--run-args option, but the
+printed arguments are :not: escaped and they are separated by a null
+character instead of a space. This is useful if the resulting arguments
+are not the direct input of a shell, for example if passed to
+`xargs -0`.
+
+See <<examples,EXAMPLES>> for usage examples.
+
+
+[[comp-create-expl]]
+Create explicit components
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+To explicitly create a component, use the opt:--component option. This
+option specifies:
+
+* **Optional**: The name of the component instance. You can also use the
+ opt:--name option for this.
+
+* The type of the component class to instantiate: source, filter, or
+ sink.
+
+* The name of the plugin in which to find the component class to
+ instantiate.
+
+* The name of the component class to instantiate.
+
+You can use the opt:--component option multiple times to create
+multiple components. You can instantiate the same component class
+multiple times as different component instances.
+
+Immediately following a opt:--component option on the command line, the
+created component is known as the _current component_ (until the next
+opt:--component option).
+
+The following, optional command-line options apply to the current
+component:
+
+opt:--name='NAME'::
+ Set the name of the current component to 'NAME'.
+
+opt:--params='PARAMS'::
+ Add 'PARAMS' to the initialization parameters of the current
+ component. If 'PARAMS' contains a key which exists in the current
+ component's initialization parameters, this parameter is replaced.
++
+See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+
+opt:--path='PATH'::
+ Set the nlparam:path initialization parameter of the current
+ component to 'PATH' (replace the parameter if it exists).
++
+You can use this option instead of manually specifying `path="PATH"` in
+a opt:--params option to use your shell's tilde expansion (`~`). Tilde
+expansion requires the tilde to be the first character of the argument,
+which is not possible with `path="PATH"`.
+
+opt:--url='URL'::
+ Set the nlparam:url initialization parameter of the current
+ component to 'URL' (replace the parameter if it exists).
+
+See <<examples,EXAMPLES>> for usage examples.
+
+
+[[comp-create-impl]]
+Create implicit components
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+An _implicit component_ is a component which is created and added to the
+conversion graph without an explicit instantiation through the
+opt:--component option. An implicit component is easier to create than
+an explicit component: this is why the `convert` command exists, as you
+can also create and run a conversion graph with the generic
+man:babeltrace-run(1) command.
+
+There are many ways to create implicit components with the `convert`
+command:
+
+* To create one or more implicit compcls:src.ctf.fs components (CTF
+ trace read from the file system), use one or more positional arguments
+ to specify the paths to the CTF traces to read, and do :not: specify
+ the opt:--input-format=`lttng-live` option.
++
+Example:
++
+[role="term"]
+----
+$ babeltrace /path/to/trace /path/to/other/trace
+----
++
+The opt:--clock-offset and opt:--clock-offset-ns options apply to _all_
+the implicit compcls:src.ctf.fs components. For example:
++
+[role="term"]
+----
+$ babeltrace --clock-offset=3 trace1 trace2
+----
++
+With the command line above, two implicit compcls:src.ctf.fs components
+have their manparam:source.ctf.fs:clock-class-offset-s initialization
+parameter set to `3`, but they have different
+manparam:source.ctf.fs:path parameters (`trace1` and `trace2`).
++
+You cannot create implicit compcls:src.ctf.fs components and an implicit
+compcls:src.ctf.lttng-live component.
+
+* To create an implicit compcls:src.ctf.lttng-live component
+ (http://lttng.org/docs/#doc-lttng-live[LTTng live] input), specify the
+ opt:--input-format=`lttng-live` option and the LTTng relay daemon's
+ URL with the positional argument.
++
+Example:
++
+[role="term"]
+----
+$ babeltrace --input-format=lttng-live \
+ net://localhost/host/abeille/my-session
+----
++
+You cannot create an implicit compcls:src.ctf.lttng-live component and
+implicit compcls:src.ctf.fs components.
+
+* To create an implicit compcls:filter.utils.trimmer component (trace
+ trimmer), specify the opt:--begin, opt:--end, or opt:--timerange
+ option.
++
+Examples:
++
+[role="term"]
+----
+$ babeltrace /path/to/trace --begin=22:14:38 --end=22:15:07
+----
++
+[role="term"]
+----
+$ babeltrace /path/to/trace --timerange=22:14:38,22:15:07
+----
++
+[role="term"]
+----
+$ babeltrace /path/to/trace --end=12:31:04.882928015
+----
+
+* To create an implicit compcls:filter.lttng-utils.debug-info (add
+ debugging information to compatible LTTng events), specify any of the
+ opt:--debug-info, opt:--debug-info-dir, opt:--debug-info-full-path, or
+ opt:--debug-info-target-prefix options.
++
+Examples:
++
+[role="term"]
+----
+$ babeltrace --debug-info /path/to/trace
+----
++
+[role="term"]
+----
+$ babeltrace /path/to/trace \
+ --debug-info-target-prefix=/tmp/tgt-root
+----
++
+[role="term"]
+----
+$ babeltrace /path/to/trace --debug-info-full-path
+----
+
+* To create an implicit compcls:sink.text.pretty component
+ (pretty-printing text output to the console or to a file), do any of:
++
+--
+* Specify no other sink components, <<comp-create-expl,explicit>> or
+ implicit. The compcls:sink.text.pretty implicit component is the
+ _default_ implicit sink component. If any other explicit or implicit
+ component exists, the default compcls:sink.text.pretty sink component
+ is not automatically created.
+
+* Specify any of the opt:--clock-cycles, opt:--clock-date,
+ opt:--clock-gmt, opt:--clock-seconds, opt:--color, opt:--fields,
+ opt:--names, or opt:--no-delta options. You can also specify the
+ opt:--output option without using the opt:--output-format=`ctf` option
+ (in which case opt:--output applies to the implicit
+ compcls:sink.ctf.fs component).
+
+* Specify the opt:--output-format=`text` option.
+--
++
+Examples:
++
+[role="term"]
+----
+$ babeltrace /path/to/trace
+----
++
+[role="term"]
+----
+$ babeltrace /path/to/trace --no-delta
+----
++
+[role="term"]
+----
+$ babeltrace /path/to/trace --output-format=text
+----
++
+[role="term"]
+----
+$ babeltrace /path/to/trace --output=/tmp/pretty-out
+----
+
+* To create an implicit compcls:sink.utils.dummy component (dummy
+ output), specify the opt:--output-format=`dummy` option. This option
+ disables the default implicit compcls:sink.text.pretty component.
++
+Example:
++
+[role="term"]
+----
+$ babeltrace /path/to/trace --output-format=dummy
+----
+
+* To create an implicit compcls:sink.ctf.fs component (CTF traces
+ written to the file system), specify the opt:--output-format=`ctf`
+ option. This option disables the default implicit
+ compcls:sink.text.pretty component. Use the opt:--output option to
+ specify the output directory.
++
+Example:
++
+[role="term"]
+----
+$ babeltrace /path/to/input/trace --output-format=ctf \
+ --output=my-traces
+----
+
+You can combine multiple methods to create implicit components. For
+example, you can trim an LTTng (CTF) trace, add debugging information to
+it, and write it as another CTF trace:
+
+[role="term"]
+----
+$ babeltrace /path/to/input/trace --timerange=22:14:38,22:15:07 \
+ --debug-info --output-format=ctf --output=out-dir
+----
+
+The equivalent man:babeltrace-run(1) command of this `convert` command
+is:
+
+[role="term"]
+----
+$ babeltrace run --component=src-ctf-fs:src.ctf.fs \
+ --key=path --value=/path/to/input/trace \
+ --component=sink-ctf-fs:sink.ctf.fs \
+ --key=path --value=out-dir \
+ --component=muxer:flt.utils.muxer \
+ --component=trimmer:flt.utils.trimmer \
+ --key=begin --value=22:14:38 \
+ --key=end --value=22:15:07 \
+ --component=dbginfo:flt.lttng-utils.debug-info \
+ --connect=src-ctf-fs:muxer --connect=muxer:trimmer \
+ --connect=trimmer:dbg-info \
+ --connect=dbginfo:sink-ctf-fs
+----
+
+See <<examples,EXAMPLES>> for more examples.
+
+
+include::common-cmd-params-format.txt[]
+
+
+[[time-fmt]]
+Time option format
+~~~~~~~~~~~~~~~~~~
+The format of the arguments of the opt:--begin and opt:--end options
+is:
+
+[verse]
+$$[$$__YYYY__-__MM__-__DD__ [__hh__:__mm__:]]__ss__[.__nnnnnnnnn__]
+
+'YYYY'::
+ 4-digit year.
+
+'MM'::
+ 2-digit month (January is `01`).
+
+'DD'::
+ 2-digit day.
+
+'hh'::
+ 2-digit hour (24-hour format).
+
+'mm'::
+ 2-digit minute.
+
+'ss'::
+ 2-digit second.
+
+'nnnnnnnnn'::
+ 9-digit nanosecond.
+
+
+include::common-cmd-plugin-path.txt[]
+
+
+OPTIONS
+-------
+include::common-gen-options.txt[]
+
+
+Explicit component creation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+See <<comp-create-expl,Create explicit components>> to learn how to
+use the following options.
+
+opt:-c $$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS', opt:--component=$$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS'::
+ Create a component initially named 'NAME' (if specified) from the
+ component class of type 'TYPE' named 'COMPCLS' found in the plugin
+ named 'PLUGIN', and set it as the current component.
++
+The available values for 'TYPE' are:
++
+--
+`source`::
+`src`::
+ Source component class.
+
+`filter`::
+`flt`::
+ Filter component class.
+
+`sink`::
+ Sink component class.
+--
+
+opt:--name='NAME'::
+ Set the name of the current component to 'NAME'. The names of all
+ the explicitly created components in the conversion graph must be
+ unique.
+
+opt:-p 'PARAMS', opt:--params='PARAMS'::
+ Add 'PARAMS' to the initialization parameters of the current
+ component. If 'PARAMS' contains a key which exists in the current
+ component's initialization parameters, replace the parameter.
+ See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+
+opt:-P 'PATH', opt:--path='PATH'::
+ Set the nlparam:path initialization parameter of the current
+ component to 'PATH' (replace the parameter if it exists).
+
+opt:-u 'URL', opt:--url='URL'::
+ Set the nlparam:url initialization parameter of the current
+ component to 'URL' (replace the parameter if it exists).
+
+
+Legacy options to create implicit components
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+opt:-i 'FORMAT', opt:--input-format='FORMAT'::
+ Create one or more implicit source components. The available values
+ for 'FORMAT' are:
++
+--
+`ctf`::
+ Create an implicit compcls:src.ctf.fs component for each positional
+ argument. Each positional argument sets the
+ manparam:source.ctf.fs:path initialization parameter of an
+ individual component. See <<impl-opts-ctf,Implicit
+ compcls:src.ctf.fs component>>.
++
+See man:babeltrace-source.ctf.fs(7) to learn more about this
+component class.
+
+`lttng-live`::
+ Depending on the format of the positional argument:
++
+--
+`net[4]://RDHOST[:RDPORT]/host/TGTHOST`::
+ Print the available LTTng live sessions of the LTTng relay daemon at
+ the address `RDHOST` and port `RDPORT`, and then exit.
+
+`net[4]://RDHOST[:RDPORT]/host/TGTHOST/SESSION`::
+ Create an implicit compcls:src.ctf.lttng-live component. The
+ position argument sets the manparam:source.ctf.lttng-live:url
+ parameter of the component.
++
+Any other format for the positional argument is invalid.
++
+See man:babeltrace-source.ctf.lttng-live(7) to learn more about
+this component class.
+--
+--
++
+You can specify at most one opt:--input-format option.
+
+opt:-o 'FORMAT', opt:--output-format='FORMAT'::
+ Create an implicit sink component. The available values for 'FORMAT'
+ are:
++
+--
+`text`::
+ Create an implicit compcls:sink.text.pretty component.
+ See <<impl-opts-text,Implicit compcls:sink.text.pretty component>>.
++
+See man:babeltrace-sink.text.pretty(7) to learn more about
+this component class.
+
+`ctf`::
+ Create an implicit compcls:sink.ctf.fs component. Specify the output
+ path with the opt:--output option.
++
+See man:babeltrace-sink.ctf.fs(7) to learn more about
+this component class.
+
+`dummy`::
+ Create an implicit compcls:sink.utils.dummy component.
++
+See man:babeltrace-sink.utils.dummy(7) to learn more about
+this component class.
+
+`ctf-metadata`::
+ Print the metadata text of a CTF trace and exit. The first
+ positional argument specifies the path to the CTF trace.
+--
++
+You can specify at most one opt:--output-format option.
+
+
+[[impl-opts-ctf]]
+Implicit compcls:src.ctf.fs component(s)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+There is one implicit compcls:src.ctf.fs component per positional
+argument (which are trace paths), unless you specify
+opt:--input-format=`lttng-live`.
+
+See man:babeltrace-source.ctf.fs(7) to learn more about this
+component class.
+
+opt:--clock-offset='SEC'::
+ Set the manparam:source.ctf.fs:clock-class-offset-s initialization
+ parameter of all the implicit compcls:src.ctf.fs components to
+ 'SEC'.
++
+The manparam:source.ctf.fs:clock-class-offset-s initialization parameter
+adds 'SEC' seconds to the offsets of all the clock classes that the
+component creates.
++
+You can combine this option with opt:--clock-offset-ns.
+
+opt:--clock-offset-ns='NS'::
+ Set the manparam:source.ctf.fs:clock-class-offset-ns initialization
+ parameter of all the implicit compcls:src.ctf.fs components to
+ 'NS'.
++
+The manparam:source.ctf.fs:clock-class-offset-ns initialization
+parameter adds 'NS' nanoseconds to the offsets of all the clock classes
+that the component creates.
++
+You can combine this option with opt:--clock-offset-s.
+
+
+Implicit compcls:filter.utils.trimmer component
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you specify at least one of the following options, you create an
+implicit compcls:filter.utils.trimmer component.
+
+See man:babeltrace-filter.utils.trimmer(7) to learn more about
+this component class.
+
+See <<time-fmt,Time option format>> for the format of 'BEGIN' and 'END'.
+
+opt:--begin='BEGIN'::
+ Set the manparam:filter.utils.trimmer:begin initialization parameter
+ of the component to 'BEGIN'. You cannot use this option with the
+ opt:--timerange option.
+
+opt:--end='END'::
+ Set the manparam:filter.utils.trimmer:end initialization parameter
+ of the component to 'END'. You cannot use this option with the
+ opt:--timerange option.
+
+opt:--timerange='BEGIN','END'::
+ Equivalent to opt:--begin='BEGIN' opt:--end='END'.
++
+You can also surround the whole argument with `[` and `]`.
+
+
+Implicit compcls:filter.lttng-utils.debug-info component
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you specify at least one of the following options, you create an
+implicit compcls:filter.lttng-utils.debug-info component. This component
+only alters compatible LTTng events.
+
+See man:babeltrace-filter.lttng-utils.debug-info(7) to learn more
+about this component class.
+
+opt:--debug-info::
+ Create an implicit compcls:filter.lttng-utils.debug-info component.
+ This option is useless if you specify any of the options below.
+
+opt:--debug-info-dir='DIR'::
+ Set the manparam:filter.lttng-utils.debug-info:debug-info-dir
+ initialization parameter of the component to 'DIR'.
++
+The manparam:filter.lttng-utils.debug-info:debug-info-dir parameter
+indicates where the component should find the debugging information it
+needs if it's not found in the actual executable files.
+
+opt:--debug-info-full-path::
+ Set the manparam:filter.lttng-utils.debug-info:full-path
+ initialization parameter of the component to true.
++
+When the manparam:filter.lttng-utils.debug-info:full-path parameter is
+true, the component writes the full (absolute) paths to files in its
+debugging information fields instead of just the short names.
+
+opt:--debug-info-target-prefix='PREFIX'::
+ Set the manparam:filter.lttng-utils.debug-info:target-prefix
+ initialization parameter of the component to 'PREFIX'.
++
+The manparam:filter.lttng-utils.debug-info:target-prefix parameter is a
+path to prepend to the paths to executables recorded in the trace. For
+example, if a trace contains the executable path `/usr/bin/ls` in its
+state dump events, and you specify
+opt:--debug-info-target-prefix=`/home/user/boards/xyz/root`, then the
+component opens the `/home/user/boards/xyz/root/usr/bin/ls` file to find
+debugging information.
+
+
+[[impl-opts-text]]
+=== Implicit compcls:sink.text.pretty component
+
+If you specify at least one of the following options, you create an
+implicit compcls:sink.text.pretty component. The `convert` command also
+creates a default implicit compcls:sink.text.pretty component if no
+other sink component exists.
+
+See man:babeltrace-sink.text.pretty(7) to learn more about this
+component class.
+
+opt:--clock-cycles::
+ Set the manparam:sink.text.pretty:clock-seconds initialization
+ parameter of the component to true.
++
+The manparam:sink.text.pretty:clock-cycles parameter makes the component
+print the event time in clock cycles.
+
+opt:--clock-date::
+ Set the manparam:sink.text.pretty:clock-date initialization
+ parameter of the component to true.
++
+The manparam:sink.text.pretty:clock-date parameter makes the component
+print the date and the time of events.
+
+opt:--clock-gmt::
+ Set the manparam:sink.text.pretty:clock-gmt initialization parameter
+ of the component to true.
++
+The manparam:sink.text.pretty:clock-gmt parameter makes the component
+not apply the local timezone to the printed times.
+
+opt:--clock-seconds::
+ Set the manparam:sink.text.pretty:clock-seconds initialization
+ parameter of the component to true.
++
+The manparam:sink.text.pretty:clock-seconds parameter makes the
+component print the event times in seconds since Epoch.
+
+opt:--color='WHEN'::
+ Set the manparam:sink.text.pretty:color initialization parameter of
+ the component to 'WHEN'.
++
+The available values for 'WHEN' are:
++
+--
+`auto`::
+ Automatic color support depending on the capabilities of the
+ terminal(s) to which the standard output and error streams are
+ connected.
+
+`never`::
+ Never emit terminal color codes.
+
+`always`::
+ Always emit terminal color codes.
+--
++
+The `auto` and `always` values have no effect if the
+`BABELTRACE_TERM_COLOR` environment variable is set to `NEVER`.
+
+opt:--fields='FIELD'[,'FIELD']...::
+ For each 'FIELD', set the nlparam:field-FIELD initialization
+ parameter of the component to true.
++
+For example, opt:--fields=`trace,loglevel,emf` sets the
+manparam:sink.text.pretty:field-trace,
+manparam:sink.text.pretty:field-loglevel, and
+manparam:sink.text.pretty:field-emf initialization parameters to true.
++
+The available value for 'FIELD' are:
++
+* `trace`
+* `trace:hostname`
+* `trace:domain`
+* `trace:procname`
+* `trace:vpid`
+* `loglevel`
+* `emf`
+* `callsite`
+
+opt:--names='NAME'[,'NAME']...::
+ For each 'NAME', set the nlparam:name-NAME initialization parameter
+ of the component to true.
++
+For example, opt:--names=`payload,scope` sets the
+manparam:sink.text.pretty:name-payload and
+manparam:sink.text.pretty:name-scope initialization parameters to true.
++
+The available value for 'NAME' are:
++
+* `payload`
+* `context`
+* `scope`
+* `header`
+
+opt:--no-delta::
+ Set the manparam:sink.text.pretty:no-delta initialization parameter
+ of the component to true.
++
+When the manparam:sink.text.pretty:no-delta parameter is true, the
+component does not print the duration since the last event on the line.
+
+
+Shared options
+~~~~~~~~~~~~~~
+opt:-w 'PATH', opt:--output='PATH'::
+ When you specify opt:--output-format=`ctf`, set the
+ manparam:sink.ctf.fs:path initialization parameter of the implicit
+ compcls:sink.ctf.fs component to 'PATH'. Otherwise, create an
+ implicit compcls:sink.text.pretty component and set its
+ manparam:sink.text.pretty:path initialization parameter to 'PATH'.
++
+See man:babeltrace-sink.ctf.fs(7) and
+man:babeltrace-sink.text.pretty(7) to learn more about those
+component classes.
+
+
+Equivalent `babeltrace run` arguments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+opt:--run-args::
+ Print the equivalent man:babeltrace-run(1) arguments instead of
+ creating and running the conversion graph. The printed arguments are
+ space-separated and individually escaped for safe shell input.
++
+You cannot use this option with the opt:--run-args-0 or
+opt:--stream-intersection option.
+
+opt:--run-args-0::
+ Print the equivalent man:babeltrace-run(1) arguments instead of
+ creating and running the conversion graph. The printed arguments are
+ separated with a null character and :not: escaped for safe shell
+ input.
++
+You cannot use this option with the opt:--run-args or
+opt:--stream-intersection option.
+
+
+Conversion graph configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+opt:--retry-duration='DURUS'::
+ Set the duration of a single retry to 'DURUS'{nbsp}µs when a
+ component reports "try again later" (busy network or file system,
+ for example).
++
+Default: 100000 (100{nbsp}ms).
+
+opt:--stream-intersection::
+ Enable the stream intersection mode. In this mode, for each trace,
+ the `convert` command filters out the events and other notifications
+ which are not in the time range where _all_ the trace's streams are
+ active.
++
+All the source components, <<comp-create-expl,explicit>> and
+<<comp-create-impl,implicit>>, must have classes which support the
+`trace-info` query object to use this option. The only Babeltrace
+project's component class which supports this query object is
+compcls:source.ctf.fs.
++
+Because it is not possible to replicate with a single
+man:babeltrace-run(1) command line what the `convert` method does with
+the opt:--stream-intersection option, you cannot use this option with
+the opt:--run-args or opt:--run-args-0 option.
+
+
+Plugin path
+~~~~~~~~~~~
+opt:--omit-home-plugin-path::
+ Do not search for plugins in `$HOME/.local/lib/babeltrace/plugins`.
+
+opt:--omit-system-plugin-path::
+ Do not search for plugins in +{system_plugin_path}+.
+
+opt:--plugin-path='PATH'[:__PATH__]...::
+ Add 'PATH' to the list of paths in which dynamic plugins can be
+ found.
+
+
+Command information
+~~~~~~~~~~~~~~~~~~~
+opt:-h, opt:--help::
+ Show command help and quit.
+
+
+[[examples]]
+EXAMPLES
+--------
+.Pretty-print the events of one or more CTF traces.
+====
+[role="term"]
+----
+$ babeltrace my-trace
+----
+
+[role="term"]
+----
+$ babeltrace my-traces
+----
+
+[role="term"]
+----
+$ babeltrace my-trace-1 my-trace-2 my-trace-3
+----
+====
+
+.Trim a CTF trace and pretty-print the events.
+====
+[role="term"]
+----
+$ babeltrace my-trace --begin=22:55:43.658582931 \
+ --end=22:55:46.967687564
+----
+
+[role="term"]
+----
+$ babeltrace my-trace --begin=22:55:43.658582931
+----
+
+[role="term"]
+----
+$ babeltrace my-trace --end=22:55:46.967687564
+----
+
+[role="term"]
+----
+$ babeltrace my-trace --timerange=22:55:43,22:55:46.967687564
+----
+====
+
+.Trim a CTF trace, enable the stream intersection mode, and generate a CTF trace.
+====
+[role="term"]
+----
+$ babeltrace my-trace --stream-intersection \
+ --timerange=22:55:43,22:55:46.967687564 \
+ --output-format=ctf --output=out-trace
+----
+====
+
+.Record LTTng live traces to the file system (as CTF traces).
+====
+[role="term"]
+----
+$ babeltrace --input-format=lttng-live \
+ net://localhost/host/myhostname/auto-20170411-134512 \
+ --output-format=ctf --output=/path/to/generated/traces
+----
+====
+
+.Read a CTF trace as fast as possible using a dummy output.
+====
+[role="term"]
+----
+$ babeltrace my-trace --output-format=dummy
+----
+====
+
+.Read three CTF traces in stream intersection mode, add debugging information, and pretty-print them to a file.
+====
+[role="term"]
+----
+$ babeltrace trace1 trace2 trace3 --stream-intersection \
+ --debug-info --output=pretty-out
+----
+====
+
+.Pretty-print a CTF trace and traces from an explicit source component, with the event times showed in seconds since Epoch.
+====
+[role="term"]
+----
+$ babeltrace ctf-trace --component=src.my-plugin.my-src \
+ --params=output-some-event-type=yes --clock-seconds
+----
+====
+
+.Send LTTng live events to an explicit sink component.
+====
+[role="term"]
+----
+$ babeltrace --input-format=lttng-live \
+ net://localhost/host/myhostname/mysession \
+ --component=sink.my-plugin.my-sink
+----
+====
+
+.Trim a CTF trace, add debugging information, apply an explicit filter component, and write as a CTF trace.
+====
+[role="term"]
+----
+$ babeltrace /path/to/trace --timerange=22:14:38,22:15:07 \
+ --debug-info --component=filter.my-plugin.my-filter \
+ --params=criteria=xyz,ignore-abc=yes \
+ --output-format=ctf --output=out-trace
+----
+====
+
+.Print the metadata text of a CTF trace.
+====
+[role="term"]
+----
+$ babeltrace /path/to/trace --output-format=ctf-metadata
+----
+====
+
+.Print the available LTTng live sessions of an LTTng relay daemon.
+====
+[role="term"]
+----
+$ babeltrace --input-format=lttng-live net://localhost
+----
+====
+
+
+include::common-cli-env.txt[]
+
+include::common-cli-files.txt[]
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace(1),
+man:babeltrace-run(1),
+man:babeltrace-intro(7)
--- /dev/null
+babeltrace-filter.lttng-utils.debug-info(7)
+===========================================
+:manpagetype: component class
+:revdate: 5 October 2017
+:comp: compcls:filter.lttng-utils.debug-info
+:defdebuginfoname: `debug_info`
+
+
+NAME
+----
+babeltrace-filter.lttng-utils.debug-info - Babeltrace's debugging
+information filter component class for LTTng traces
+
+
+DESCRIPTION
+-----------
+The Babeltrace {comp} component class, provided by the the
+man:babeltrace-plugin-lttng-utils(7) plugin, once instantiated, receives
+events from http://lttng.org/[LTTng] traces and creates new ones
+which are copies of the original ones with extra debugging information
+when it's available and possible.
+
+A {comp} component uses the LTTng state dump events as well as the event
+context's `ip` (instruction pointer) field to locate and read the
+corresponding debugging information. The component can find the extra
+debugging information in an executable file or in a directory containing
+debugging information created by the compiler.
+
+The new events contain the exact same fields as the original ones and,
+when possible, a new event context's structure field (besides the `ip`
+field) named {defdebuginfoname} by default. This structure field
+contains the following fields:
+
+`bin` (string field)::
+ Executable path or name followed by `@ADDR` or `+ADDR`, where
+ `ADDR` is the address where it was loaded while being traced.
+ `@ADDR` means `ADDR` is an absolute address, and `+ADDR` means
+ `ADDR` is a relative address.
++
+Example: `my-program@0x401040`.
+
+[[field-func]]`func` (string field)::
+ Function name followed by `+OFFSET`, where `OFFSET` is the
+ offset from the beginning of the function symbol in the executable
+ file.
++
+Example: `load_user_config+0x194`.
+
+[[field-src]]`src` (string field)::
+ Source file path or name followed by `:LINE`, where `LINE` is the
+ line number in this source file at which the event occured.
++
+Example: `user-config.c:1025`.
+
+Any of those the previous fields can be an empty string if the
+debugging information was not available for the analyzed original
+LTTng event.
+
+When a filter component creates a new event with debugging
+information, it discards the original event. If the component receives a
+non-LTTng event, the component moves the event to its output port
+without alteration.
+
+
+Compile an executable for debugging information analysis
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+With GCC or Clang, you should compile the program or library source
+files in debug mode with the nlopt:-g option. This option makes the
+compiler generate debugging information in the operating system's native
+format. This format is recognized by a {comp} component: it can
+translate the instruction pointer field of an event's context to a
+source file and line number, along with the name of the surrounding
+function.
+
+NOTE: This component class only supports the debugging information in
+DWARF format, version{nbsp}2 or later. Use the nlopt:-gdwarf or
+nlopt:-gdwarf-VERSION (where `VERSION` is the DWARF version) compiler
+options to explicitly generate DWARF debugging information.
+
+If you don't compile the executable's source files with the nlopt:-g
+option or with an equivalent option, no DWARF information is available:
+the component uses ELF symbols from the executable file instead. In this
+case, the events that the component creates do not contain the source
+file and line number (<<field-src,`src` field>>), but only the name of
+the nearest function symbol with an offset in bytes to the location in
+the executable from which the LTTng event occured (<<field-func,`func`
+field>>).
+
+If the executable file has neither ELF symbols nor DWARF information,
+the {comp} component cannot map the event to
+its source location: it emits the original LTTng event which has no
+special {defdebuginfoname} context field.
+
+
+LTTng prerequisites
+~~~~~~~~~~~~~~~~~~~
+A {comp} component can only analyze user space events generated by
+http://lttng.org[LTTng]{nbsp}2.8.0 or later.
+
+The filter component needs the LTTng-UST events to contain the
+`ip` and `vpid` fields in their context.
+
+To add those context fields with the man:lttng(1) command-line tool
+before the tracers are active (before `lttng start`):
+
+[role="term"]
+----
+$ lttng add-context --userspace --type=ip --type=vpid
+----
+
+See man:lttng-add-context(1) for more information.
+
+To get debugging information for LTTng-UST events which occur in
+dynamically loaded objects, for example plugins, start the application
+to trace with the LTTng-UST dynamic linking helper:
+
+[role="term"]
+----
+$ LD_PRELOAD=liblttng-ust-dl.so my-app
+----
+
+See man:lttng-ust-dl(3) for more information.
+
+
+Separate debugging information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+It is possible to store DWARF debugging information outside the
+executable itself, whether it is to reduce the executable's file size,
+or simply to facilitate the sharing of the debugging information.
+
+This is usually achieved via one of two mechanisms, namely _build ID_
+and _debug link_. Their use and operation is described in the
+https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging
+Information in Separate Files] section of GDB's documentation.
+
+A {comp} component can find separate debugging information files
+automatically, as long as they meet the requirements stated in this man
+page.
+
+The debugging information lookup order is the same as GDB's, namely:
+
+. Within the executable file itself.
+
+. Through the build ID method in the `/usr/lib/debug/.build-id`
+ directory.
+
+. In the various possible debug link locations.
+
+The component uses the first debugging information file that it finds.
+
+You can use the param:deubg-info-dir initialization parameter to
+override the default `/usr/lib/debug` directory used in the build ID and
+debug link methods.
+
+NOTE: It is currently not possible to make this component search for
+debugging information in multiple directories.
+
+
+Target prefix
+~~~~~~~~~~~~~
+The debugging information analysis that a {comp} component performs uses
+the paths to the executables as collected during tracing as the default
+mechanism to resolve DWARF and ELF information.
+
+If the trace was recorded on a separate machine, however, you can use
+the param:target-prefix parameter to specify a prefix directory, that
+is, the root of the target file system.
+
+For example, if an instrumented executable's path is `/usr/bin/foo` on
+the target system, you can place this file at
+`/home/user/target/usr/bin/foo` on the system on which you use the
+component. In this case, the target prefix to use is
+`/home/user/target`.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+The following parameters are optional.
+
+param:debug-info-dir='DIR' (string)::
+ Use 'DIR' as the directory from which to load debugging information
+ with the build ID and debug link methods instead of
+ `/usr/lib/debug`.
+
+param:debug-info-field-name='NAME' (string)::
+ Name the debugging information structure field in the context of
+ the created events 'NAME' instead of the default {defdebuginfoname}.
+
+param:full-path=`yes` (boolean)::
+ Use the full path when writing the executable name (`bin`) and
+ source file name (`src`) fields in the {defdebuginfoname} context
+ field of the created events.
+
+param:target-prefix='DIR' (string)::
+ Use 'DIR' as the root directory of the target file system instead of
+ `/`.
+
+
+PORTS
+-----
+Input
+~~~~~
+`in`::
+ Single input port from which the component receives the
+ notifications to augment with debugging information.
+
+
+Output
+~~~~~~
+`out`::
+ Single output port to which the component sends the augmented
+ or unaltered notifications.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-common-compat-env.txt[]
+
+`BABELTRACE_FLT_LTTNG_UTILS_DEBUG_INFO_LOG_LEVEL`::
+ Component class's log level. The available values are the
+ same as for the manopt:babeltrace(1):--log-level option of
+ man:babeltrace(1).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace-plugin-lttng-utils(7),
+man:lttng(1),
+man:lttng-add-context(1),
+man:babeltrace-intro(7)
--- /dev/null
+babeltrace-filter.utils.muxer(7)
+================================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-filter.utils.muxer - Babeltrace's notification multiplexer
+filter component class
+
+
+DESCRIPTION
+-----------
+The Babeltrace compcls:filter.utils.muxer component class, provided by
+the man:babeltrace-plugin-utils(7) plugin, once instantiated,
+multiplexes the notifications that it receives from one or more input
+ports into a linear sequence of events ordered by time on its output
+port.
+
+A compcls:filter.utils.muxer component does not alter the notifications
+it receives: it only sorts them.
+
+A compcls:filter.utils.muxer component can only work on notifications in
+which the clock value with the highest priority has an absolute clock
+class. You can use the param:assume-absolute-clock-classes parameter to
+make the component assume that all clock classes are absolute. In this
+case, you must ensure that, when more than one clock class exists, they
+are correlatable.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+The following parameters are optional.
+
+param:assume-absolute-clock-classes=`yes` (boolean)::
+ Assume that all clock classes are absolute.
+
+
+PORTS
+-----
+Input
+~~~~~
+`inN`, where `N` is a decimal integer starting at 0::
+ Input port from which the component receives notifications to
+ multiplex.
++
+When you create the component, its only input port is
+`in0`. When you connect the `in0` port, the component creates
+the `in1` input port, and so on. If you disconnect an input port,
+the component does not create a new input port: the disconnected
+input port is now available for a new connection.
++
+In other words, a compcls:filter.utils.muxer component always makes sure
+that it has at least one available input port.
+
+
+Output
+~~~~~~
+`out`::
+ Single output port to which the component sends the
+ sorted notifications.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-common-compat-env.txt[]
+
+`BABELTRACE_FLT_UTILS_MUXER_LOG_LEVEL`::
+ Component class's log level. The available values are the
+ same as for the manopt:babeltrace(1):--log-level option of
+ man:babeltrace(1).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace-plugin-utils(7),
+man:babeltrace-intro(7)
--- /dev/null
+babeltrace-filter.utils.trimmer(7)
+==================================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-filter.utils.trimmer - Babeltrace's trimmer filter
+component class
+
+
+DESCRIPTION
+-----------
+The Babeltrace compcls:filter.utils.trimmer component class, provided by
+the man:babeltrace-plugin-utils(7) plugin, once instantiated, discards
+all the received events with a time less than a given beginning time and
+greater than a given end time. It effectively ``cuts'', or trims traces.
+
+A compcls:filter.utils.trimmer component modifies the `timestamp_begin`
+and `timestamp_end` fields of the packet contexts it receives to match
+the beggining and end times of the trimming range when needed.
+
+The component used a notification's clock value with the highest
+priority to decide whether to discard it or not.
+
+
+[[time-param-fmt]]
+Time parameter format
+~~~~~~~~~~~~~~~~~~~~~
+The format of the param:begin and param:end parameters is:
+
+[verse]
+$$[$$__YYYY__-__MM__-__DD__ [__hh__:__mm__:]]__ss__[.__nnnnnnnnn__]
+
+'YYYY'::
+ 4-digit year.
+
+'MM'::
+ 2-digit month (January is `01`).
+
+'DD'::
+ 2-digit day.
+
+'hh'::
+ 2-digit hour (24-hour format).
+
+'mm'::
+ 2-digit minute.
+
+'ss'::
+ 2-digit second.
+
+'nnnnnnnnn'::
+ 9-digit nanosecond.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+You must specify at least one of the param:begin and param:end
+parameters.
+
+param:begin='BEGIN' (string or integer)::
+ Set the trimmer's beginning time to 'BEGIN'.
++
+If 'BEGIN' is a string, see <<time-param-fmt,Time parameter format>> for
+its format. If 'BEGIN' is an integer, it is the number of nanoseconds
+since Epoch.
++
+If you don't specify this parameter, the component discards no events
+until the end of the trimming range.
+
+param:clock-gmt=`yes` (boolean)::
+ Set the time zone of the param:begin and param:end parameters
+ to GMT instead of the local time zone.
+
+param:end='END' (string or integer)::
+ Set the trimmer's end time to 'END'.
++
+If 'END' is a string, see <<time-param-fmt,Time parameter format>> for
+its format. If 'END' is an integer, it is the number of nanoseconds
+since Epoch.
++
+If you don't specify this parameter, the component discards no events
+from the beginning of the trimming range.
+
+
+PORTS
+-----
+Input
+~~~~~
+`in`::
+ Single input port from which the component receives the
+ notifications.
+
+
+Output
+~~~~~~
+`out`::
+ Single output port to which the components sends the notifications
+ of which the time is in the trimming range.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-common-compat-env.txt[]
+
+`BABELTRACE_FLT_UTILS_TRIMMER_LOG_LEVEL`::
+ Component class's log level. The available values are the
+ same as for the manopt:babeltrace(1):--log-level option of
+ man:babeltrace(1).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace-plugin-utils(7),
+man:babeltrace-intro(7)
--- /dev/null
+babeltrace-help(1)
+==================
+:manpagetype: command
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-help - Get help for a Babeltrace plugin or component class
+
+
+SYNOPSIS
+--------
+[verse]
+*babeltrace help* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
+ [opt:--omit-system-plugin-path]
+ [opt:--plugin-path='PATH'[:__PATH__]...]
+ ('PLUGIN' | 'TYPE.PLUGIN.COMPCLS')
+
+
+DESCRIPTION
+-----------
+The `help` command prints the details and help text of either the plugin
+'PLUGIN' or the specific component class 'TYPE.PLUGIN.COMPCLS'.
+
+See man:babeltrace-intro(7) to learn more about the Babeltrace
+project and its core concepts.
+
+The available values for 'TYPE' are:
+
+`source` or `src`::
+ Source component class.
+
+`filter` or `flt`::
+ Filter component class.
+
+`sink`::
+ Sink component class.
+
+See <<examples,EXAMPLES>> for usage examples.
+
+
+include::common-cmd-plugin-path.txt[]
+
+
+OPTIONS
+-------
+include::common-gen-options.txt[]
+
+include::common-plugin-path-options.txt[]
+
+include::common-cmd-info-options.txt[]
+
+
+[[examples]]
+EXAMPLES
+--------
+.Get help for a plugin and all its component classes.
+====
+[role="term"]
+----
+$ babeltrace help my-plugin
+----
+====
+
+.Get help for a specific plugin's source component class.
+====
+[role="term"]
+----
+$ babeltrace help src.my-plugin.my-source
+----
+====
+
+.Get help for a specific plugin's sink component class.
+====
+[role="term"]
+----
+$ babeltrace help sink.my-plugin.my-sink
+----
+====
+
+
+include::common-cli-env.txt[]
+
+include::common-cli-files.txt[]
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace(1),
+man:babeltrace-list-plugins(1)
+man:babeltrace-intro(7)
--- /dev/null
+babeltrace-intro(7)
+===================
+:manpagetype: man page
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-intro - Introduction to Babeltrace
+
+
+DESCRIPTION
+-----------
+This man page is an introduction to the Babeltrace project.
+
+The <<what-is,WHAT IS BABELTRACE?>> section lists the parts of the
+project and shows the major changes from Babeltrace{nbsp}1 to
+Babeltrace{nbsp}2 while the <<concepts,BABELTRACE CONCEPTS>> section
+defines the core concepts of Babeltrace.
+
+The <<graph-repr,TRACE PROCESSING GRAPH REPRESENTATION>> section shows
+how some <<concepts,concepts>> are visually represented in other
+Babeltrace man pages.
+
+
+[[what-is]]
+WHAT IS BABELTRACE?
+-------------------
+Babeltrace is an open-source software project of which the purpose is
+to process or convert
+https://en.wikipedia.org/wiki/Tracing_(software)[traces].
+
+The Babeltrace project includes the following parts:
+
+[[libbabeltrace]]Babeltrace library (libbabeltrace)::
+ A shared library with a C API.
++
+With libbabeltrace, you can programmatically create <<plugin,plugins>>
+and <<comp-cls,component classes>>, build and run <<graph,processing
+graphs>>, and more (see the <<concepts,BABELTRACE CONCEPTS>> section for
+more details about those concepts). All the other Babeltrace parts rely
+on this library.
+
+[[babeltrace-1]]`babeltrace` command::
+ A command-line interface which uses libbabeltrace to load plugins,
+ create a trace processing graph, create components, and run the
+ graph.
++
+You can also use `babeltrace` to list the available plugins or to query
+an object from a component class.
++
+See man:babeltrace(1).
+
+[[python-bindings]]Babeltrace Python bindings::
+ A Python{nbsp}3 package which offers a Pythonic interface of
+ libbabeltrace.
++
+You can perform the same operations which are available in libbabeltrace
+with the Python bindings, but in a really easier way and with less code.
+
+Babeltrace project's plugins::
+ The Babeltrace <<plugin,plugins>> shipped with the project.
++
+Those plugins are not special, in that they only rely on libbabeltrace
+and you don't need them to use libbabeltrace, man:babeltrace(1), or the
+Python bindings.
++
+The Babeltrace project's plugins are:
++
+--
+`ctf`::
+ Common Trace Format input/output, including the LTTng live source.
++
+See man:babeltrace-plugin-ctf(7).
+
+`lttng-utils`::
+ Graph utilities specific to http://lttng.org/[LTTng] traces.
++
+See man:babeltrace-plugin-lttng-utils(7).
+
+`text`::
+ Text input/output.
++
+See man:babeltrace-plugin-text(7).
+
+`utils`::
+ Graph utilities (muxer, trimmer, counter, dummy sink).
++
+See man:babeltrace-plugin-utils(7).
+--
+
+Python plugin provider::
+ A shared library which libbabeltrace tries to load to add support
+ for Babeltrace plugins written in Python.
++
+The package you use to write a Python Babeltrace plugin is the one
+provided by the Python bindings.
+
+
+Changes since Babeltrace{nbsp}1
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This man page is an introduction to Babeltrace{nbsp}2, a rewrite of
+Babeltrace{nbsp}1 with a focus on extensibility and flexibility.
+
+Babeltrace{nbsp}1 exists since 2010. The major improvements brought by
+Babeltrace{nbsp}2 are:
+
+* Full plugin support: any user can distribute a Babeltrace plugin and,
+ as long as <<libbabeltrace,libbabeltrace>> finds it, any application
+ linked to libbabeltrace can load it and use it.
++
+Plugins are not just input and output formats: they provide source,
+filter, and sink <<comp-cls,component classes>> so that you can connect
+specialized, reusable components together in a graph to create a
+customized trace conversion or analysis device.
+
+* In order to support user components, all the objects of libbabeltrace
+ have a reference count. The possible reference cycles are handled
+ internally so that the library's API is clean and predictable. The two
+ reference counting functions, `bt_get()` and `bt_put()`, are all you
+ need to manage the lifetime of any Babeltrace object.
+
+* All the parts of the Babeltrace project run on the major operating
+ systems, including Windows and macOS.
+
+
+[[concepts]]
+BABELTRACE CONCEPTS
+-------------------
+This section defines the main concepts of the Babeltrace project. These
+concepts translate into types and functions in
+<<libbabeltrace,libbabeltrace>> and its <<python-bindings,Python
+bindings>>, but also as command-line actions and options in the
+<<babeltrace-1,`babeltrace` command>>. The other Babeltrace man pages
+assume that you are familiar with the following definitions.
+
+Some Babeltrace concepts are interdependent: it is normal to jump from
+one definition to another to understand the big picture.
+
+[[comp-cls]]Component class::
+ A reusable class from which you can instantiate one or more
+ <<comp,component>> instances.
++
+There are three types of component classes used to instantiate the three
+types of components (source, filter, and sink).
++
+A component class provides methods, one of which is an initialization
+method, or constructor, to create a component. You pass _initialization
+parameters_ to this method to customize the created component. For
+example, the initialization method of the compcls:src.ctf.fs component
+class accepts a mandatory manparam:source.ctf.fs:path parameter which is
+the file system path to the trace(s). It also accepts an optional
+manparam:source.ctf.fs:clock-class-offset-ns parameter which is an
+offset, in nanoseconds, to add to all the clock classes found in the
+traces's metadata.
+
+[[comp]]Component::
+ A node within a <<graph,trace processing graph>>.
++
+There are three types of components:
++
+--
+Source component::
+ An input component which produces <<notif,notifications>>.
++
+Examples: CTF files input, log file input, LTTng-live input, random
+event generator.
+
+Filter component::
+ An intermediate component which can discard the notifications it
+ receives, transform them, augment them, sort them, or create new
+ ones.
++
+Examples: filter which removes notifications based on an expression,
+filter which adds debugging information to selected events, notification
+multiplexer, trace trimmer.
+
+Sink component::
+ An output component which consumes notifications and usually writes
+ them to one or more formatted files.
++
+Examples: log file output, CTF files output, text output on the
+console.
+--
++
+Components are connected together within a <<graph,trace processing
+graph>> through their <<port,ports>>. Source components have output
+ports, sink components have input ports, and filter components have
+both.
++
+A component is the instance of a <<comp-cls,component class>>. The terms
+_component_ and _component instance_ are equivalent.
++
+Within a trace processing graph, each component has a unique name. This
+is not the name of its component class, but an instance name. If `human`
+is a component class name, than `John` could be a component name.
+
+[[port]]Port::
+ A connection point, on a <<comp,component>>, from which are sent or
+ to which are received <<notif,notifications>> when the <<graph,trace
+ processing graph>> is running.
++
+An output port is where notifications are sent. An input port is where
+notifications are received. Source components have output ports, sink
+components have input ports, and filter components have both.
++
+An output port can only be connected to a single input port at a given
+time.
++
+A filter or sink component receiving notifications from its input ports
+is said to _consume_ notifications.
++
+The link between an output port and input port is a <<conn,connection>>.
++
+A component can dynamically add and remove ports while a graph is
+running. For example, a compcls:filter.utils.muxer component always
+makes sure that it has at least one available input port.
+
+[[conn]]Connection::
+ The link between an output <<port,port>> and an input port through
+ which <<notif,notifications>> flow when a <<graph,trace processing
+ graph>> is running.
+
+[[notif]]Notification::
+ An atomic element sent from an output <<port,port>> to an
+ input port.
++
+A source <<comp,component>> produces notifications, while a sink
+component consumes them. A filter component can both consume and
+produce notifications.
++
+The main types of notifications are:
++
+--
+Event::
+ A trace event record within a packet.
+
+Packet beginning::
+ The beginning of a packet within a stream.
++
+A packet is a container of events.
+
+Packet end::
+ The end of a packet within a stream.
+
+Stream beginning::
+ The beginning of a stream.
++
+A stream is a container of packets.
++
+Usually, a given source component's output port sends packet and
+event notifications which belong to a single stream.
+
+Stream end::
+ The end of a stream.
+
+Discarded events::
+ A count of discarded events within a given time interval for a given
+ stream.
+
+Discarded packets::
+ A count of discarded packets within a given time interval for a
+ given stream.
+--
+
+[[graph]]Trace processing graph::
+ A https://en.wikipedia.org/wiki/Filter_graph[filter graph] where
+ nodes are <<comp,components>> and <<notif,notifications>> flow from
+ output <<port,ports>> to input ports.
++
+You can build a trace processing graph with
+<<libbabeltrace,libbabeltrace>>, with the <<python-bindings,Babeltrace
+Python bindings>>, or with the man:babeltrace-run(1) and
+man:babeltrace-convert(1) commands.
++
+When you _run_ a trace processing graph, the sink components consume
+notifications from their input ports, making all the graph's components
+work one notification at a time to perform the trace conversion or
+analysis.
+
+[[plugin]]Plugin::
+ A container of <<comp-cls,component classes>> as a shared library.
++
+Each component class within a plugin has a type (source, filter, or
+sink) and a name. The type and name pair is unique within a given
+plugin.
++
+<<libbabeltrace,libbabeltrace>> can load a plugin (`.so` or `.dll` file)
+at run time: the result is a plugin object in which you can find a
+specific component class and instantiate it within a <<graph,trace
+processing graph>> as a <<comp,component>>.
++
+The <<babeltrace-1,`babeltrace` command>> uses the
+'TYPE.PLUGIN.COMPCLS' format to identify a specific component
+class within a specific plugin. 'TYPE' is either `source`, `filter`,
+or `sink`.
++
+You can list the available Babeltrace plugins with the
+man:babeltrace-list-plugins(1) command.
+
+[[query]]Query::
+ An operation with which you can get a named object from a
+ <<comp-cls,component class>>, possibly with the help of query
+ parameters.
++
+The plain text metadata stream of a CTF trace and the available LTTng
+live sessions of a given LTTng relay daemon are examples of queries.
++
+You can use the man:babeltrace-query(1) command to query a component
+class's object.
+
+
+[[graph-repr]]
+TRACE PROCESSING GRAPH REPRESENTATION
+-------------------------------------
+In the Babeltrace man pages, a component is represented with a box. The
+box has the <<comp-cls,component class>> type, <<plugin,plugin>> name,
+and component class name at the top. Just below, between square
+brackets, is its component instance name within the <<graph,trace
+processing graph>>. Each <<port,port>> is represented with an `@` symbol
+on the edge of the component box with its name inside the box. Output
+ports are on the right edge while input ports are on the left edge.
+
+For example, here's a source component box:
+
+----
++------------+
+| src.ctf.fs |
+| [my-src] |
+| |
+| stream0 @
+| stream1 @
+| stream2 @
++------------+
+----
+
+This one is an instance of the compcls:src.ctf.fs component class named
+`my-src`. It has three output ports named `stream0`, `stream1`, and
+`stream2`.
+
+A trace processing graph is represented with multiple component boxes
+connected together. The <<conn,connections>> are arrows from output
+ports to input ports.
+
+For example, here's a simple conversion graph:
+
+----
++------------+ +-----------------+ +------------------+
+| src.ctf.fs | | flt.utils.muxer | | sink.text.pretty |
+| [ctf] | | [muxer] | | [text] |
+| | | | | |
+| stream0 @--->@ in0 out @--->@ in |
+| stream1 @--->@ in1 | +------------------+
+| stream2 @--->@ in2 |
++------------+ @ in3 |
+ +-----------------+
+----
+
+Note that input port `in3` of component `muxer` is not currently
+connected in this example.
+
+Sometimes, we symbolically represent other resources which are consumed
+from or produced by components. In this case, arrows are used, but they
+do not go to or from port symbols (`@`). For example, in the graph above,
+the `ctf` component consumes a CTF trace and the `text` component
+prints to the console, so here's a more complete diagram:
+
+----
+ CTF trace
+ |
+.------'
+| +------------+ +-----------------+ +------------------+
+| | src.ctf.fs | | flt.utils.muxer | | sink.text.pretty |
+'->| [ctf] | | [muxer] | | [text] |
+ | | | | | |
+ | stream0 @--->@ in0 out @--->@ in |
+ | stream1 @--->@ in1 | +--+---------------+
+ | stream2 @--->@ in2 | |
+ +------------+ @ in3 | '---> Console
+ +-----------------+
+----
+
+Here's another example of a more complex graph which splits a specific
+stream using some criteria:
+
+----
++------------+ +-----------------+ +------------------+
+| src.ctf.fs | | flt.utils.muxer | | sink.text.pretty |
+| [ctf-in] | | [muxer] | | [text] |
+| | | | | |
+| stream0 @--->@ in0 out @--->@ in |
+| stream1 @--->@ in1 | +------------------+
+| stream2 @-. @ in2 |
++------------+ | +-----------------+ +-------------+
+ | | sink.ctf.fs |
+ | | [ctf-out0] |
+ | +-------------------+ | |
+ | | flt.some.splitter | .->@ in |
+ | | [splitter] | | +-------------+
+ | | | |
+ '->@ in A @-' +-------------+
+ | B @-. | sink.ctf.fs |
+ +-------------------+ | | [ctf-out1] |
+ | | |
+ '->@ in |
+ +-------------+
+----
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace(1)
--- /dev/null
+babeltrace-list-plugins(1)
+==========================
+:manpagetype: command
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-list-plugins - List Babeltrace plugins and their properties
+
+
+SYNOPSIS
+--------
+[verse]
+*babeltrace list-plugins* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
+ [opt:--omit-system-plugin-path]
+ [opt:--plugin-path='PATH'[:__PATH__]...]
+
+
+DESCRIPTION
+-----------
+The `list-plugins` command prints a list of available Babeltrace
+plugins along with their component classes and their properties.
+
+See man:babeltrace-intro(7) to learn more about the Babeltrace
+project and its core concepts.
+
+
+include::common-cmd-plugin-path.txt[]
+
+
+OPTIONS
+-------
+include::common-gen-options.txt[]
+
+include::common-plugin-path-options.txt[]
+
+include::common-cmd-info-options.txt[]
+
+include::common-cli-env.txt[]
+
+include::common-cli-files.txt[]
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace(1),
+man:babeltrace-help(1),
+man:babeltrace-intro(7)
--- /dev/null
+babeltrace-log(1)
+=================
+:manpagetype: program
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-log - Convert a Linux kernel ring buffer to a CTF trace
+
+
+SYNOPSIS
+--------
+[verse]
+*babeltrace-log* [opt:--with-timestamps] 'OUTPUT-PATH'
+
+
+DESCRIPTION
+-----------
+The `babeltrace-log` tool reads the lines of a Linux kernel ring buffer,
+as printed by the man:dmesg(1) tool, from the standard input stream and
+converts them to a http://diamon.org/ctf/[CTF] trace written to the
+'OUTPUT-PATH' directory.
+
+Usage example:
+
+[role="term"]
+----
+$ dmesg | babeltrace-log --with-timestamps my-trace
+----
+
+The events of the generated CTF trace are named `string` and contain a
+single payload string field named `str` which contains the corresponding
+ring buffer line.
+
+By default, `babeltrace-log` does not try to extract the timestamps of
+the kernel ring buffer lines to use them as the created events's
+timestamps. A typical man:dmesg(1) line looks like this:
+
+----
+[87166.510937] PM: Finishing wakeup.
+----
+
+In the last example, the `[87166.510937]` part is a timestamp which
+could be extracted. You can make `babeltrace-log` extract timestamps
+from lines with the opt:--with-timestamps option.
+
+
+OPTIONS
+-------
+opt:-t, opt:--with-timestamps::
+ Extract timestamps from the kernel ring buffer lines: set
+ the created event's payload's `str` field to the rest of the line,
+ excluding any timestamp prefix.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+See the environment variables of man:babeltrace-source.text.dmesg(7),
+man:babeltrace-filter.utils.muxer(7), and
+man:babeltrace-sink.ctf.fs(7).
+
+include::common-lib-env.txt[]
+
+include::common-cli-files.txt[]
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace-intro(7),
+man:babeltrace-source.text.dmesg(7),
+man:babeltrace-filter.utils.muxer(7),
+man:babeltrace-sink.ctf.fs(7)
--- /dev/null
+babeltrace-plugin-ctf(7)
+========================
+:manpagetype: plugin
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-plugin-ctf - Babeltrace's CTF plugin
+
+
+DESCRIPTION
+-----------
+The Babeltrace `ctf` plugin contains component classes which can read
+and write the http://diamon.org/ctf/[Common Trace Format].
+
+See man:babeltrace-intro(7) to learn more about the Babeltrace
+project and its core concepts.
+
+
+COMPONENT CLASSES
+-----------------
+compcls:sink.ctf.fs::
+ Writes the received notifications as a CTF trace on the file system.
++
+See man:babeltrace-sink.ctf.fs(7).
+
+compcls:source.ctf.fs::
+ Opens one or more CTF traces on the file system and emits the
+ notifications of their data stream files.
++
+See man:babeltrace-source.ctf.fs(7).
+
+compcls:source.ctf.lttng-live::
+ Connects to an http://lttng.org/[LTTng] relay daemon and emits
+ the notifications of the received CTF data streams.
++
+See man:babeltrace-source.ctf.lttng-live(7).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace-sink.ctf.fs(7),
+man:babeltrace-source.ctf.fs(7),
+man:babeltrace-source.ctf.lttng-live(7),
+man:babeltrace-intro(7)
--- /dev/null
+babeltrace-plugin-lttng-utils(7)
+================================
+:manpagetype: plugin
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-plugin-lttng-utils - Babeltrace's LTTng utilities plugin
+
+
+DESCRIPTION
+-----------
+The Babeltrace `lttng-utils` plugin contains utilities that apply to
+LTTng traces. You can use the compcls:source.ctf.fs and
+compcls:source.ctf.lttng-live components to read LTTng traces (see
+man:babeltrace-plugin-ctf(7)).
+
+See man:babeltrace-intro(7) to learn more about the Babeltrace
+project and its core concepts.
+
+
+COMPONENT CLASSES
+-----------------
+compcls:filter.lttng-utils.debug-info::
+ Receives notifications from its input port and creates new,
+ equivalent notifications with additionnal debugging information.
++
+See man:babeltrace-filter.lttng-utils.debug-info(7).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace-filter.lttng-utils.debug-info(7),
+man:babeltrace-intro(7)
--- /dev/null
+babeltrace-plugin-text(7)
+=========================
+:manpagetype: plugin
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-plugin-text - Babeltrace's plain text plugin
+
+
+DESCRIPTION
+-----------
+The Babeltrace `text` plugin contains component classes which read or
+write plain text data.
+
+See man:babeltrace-intro(7) to learn more about the Babeltrace
+project and its core concepts.
+
+
+COMPONENT CLASSES
+-----------------
+compcls:sink.text.pretty::
+ Pretty-prints the notifications it receives to the console or to a
+ file.
++
+See man:babeltrace-sink.text.pretty(7).
+
+compcls:source.text.dmesg::
+ Reads the lines of a Linux kernel ring buffer, that is, the output
+ of the man:dmesg(1) tool, and emits each line as an event
+ notification.
++
+See man:babeltrace-source.text.dmesg(7).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace-sink-text.text(7),
+man:babeltrace-source-text.dmesg(7),
+man:babeltrace-intro(7),
--- /dev/null
+babeltrace-plugin-utils(7)
+==========================
+:manpagetype: plugin
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-plugin-utils - Babeltrace's utilities plugin
+
+
+DESCRIPTION
+-----------
+The Babeltrace `utils` plugin contains common, generic utility component
+classes which you can use in any processing graph.
+
+See man:babeltrace-intro(7) to learn more about the Babeltrace
+project and its core concepts.
+
+
+COMPONENT CLASSES
+-----------------
+compcls:filter.utils.muxer::
+ Multiplexes the notifications received on its multiple input ports
+ by time to its single output port.
++
+See man:babeltrace-filter.utils.muxer(7).
+
+compcls:filter.utils.trimmer::
+ Discards all the received events with a timestamp less than a given
+ beginning timestamp and greater than a given end timestamp,
+ effectively ``cutting'' the traces.
++
+See man:babeltrace-filter.utils.trimmer(7).
+
+compcls:sink.utils.dummy::
+ Receives the notifications from its single input port and discards
+ them (does absolutely nothing with them). This is useful for
+ testing and benchmarking a trace processing graph application,
+ for example man:babeltrace(1).
++
+See man:babeltrace-sink.utils.dummy(7).
+
+compcls:sink.utils.counter::
+ Prints the number of notifications received from its single input
+ port, either once at the end or periodically.
++
+See man:babeltrace-sink.utils.counter(7).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace-intro(7),
+man:babeltrace-filter.utils.muxer(7),
+man:babeltrace-filter.utils.trimmer(7),
+man:babeltrace-sink.utils.counter(7),
+man:babeltrace-sink.utils.dummy(7)
--- /dev/null
+babeltrace-query(1)
+===================
+:manpagetype: command
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-query - Query object from a component class
+
+
+SYNOPSIS
+--------
+[verse]
+*babeltrace query* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
+ [opt:--omit-system-plugin-path]
+ [opt:--plugin-path='PATH'[:__PATH__]...]
+ [opt:--params='PARAMS'] 'TYPE.PLUGIN.COMPCLS' 'OBJECT'
+
+
+DESCRIPTION
+-----------
+The `query` command queries the object named 'OBJECT' from the component
+class 'COMPCLS' of the type 'TYPE' found in the Babeltrace plugin
+'PLUGIN' and prints the results.
+
+See man:babeltrace-intro(7) to learn more about the Babeltrace
+project and its core concepts.
+
+The available values for 'TYPE' are:
+
+`source`::
+`src`::
+ Source component class.
+
+`filter`::
+`flt`::
+ Filter component class.
+
+`sink`::
+ Sink component class.
+
+The exact object names and the parameters that a given component class
+expects are described in its documentation. man:babeltrace-help(1) can
+generally provide this information.
+
+You can use the opt:--params='PARAMS' option to pass parameters to the
+component class's query function. See <<params-fmt,Parameters format>>
+for the exact format of 'PARAMS'.
+
+The output of the `query` command looks like YAML, although it is not
+guaranteed that it is YAML-compliant.
+
+See <<examples,EXAMPLES>> for usage examples.
+
+
+include::common-cmd-params-format.txt[]
+
+include::common-cmd-plugin-path.txt[]
+
+
+OPTIONS
+-------
+include::common-gen-options.txt[]
+
+
+Query parameters
+~~~~~~~~~~~~~~~~
+opt:-p 'PARAMS', opt:--params='PARAMS'::
+ Set the query parameters to 'PARAMS'. See <<params-fmt,Parameters
+ format>> for the exact format of 'PARAMS'.
+
+
+include::common-plugin-path-options.txt[]
+
+include::common-cmd-info-options.txt[]
+
+
+[[examples]]
+EXAMPLES
+--------
+.Query the available sessions of the LTTng live source component class.
+====
+[role="term"]
+----
+$ babeltrace query src.ctf.lttng-live sessions \
+ --params='url="net://RHOST/host/TGTHOST"'
+----
+====
+
+.Query the metadata info (includes the decoded text) of a CTF trace located on the local file system.
+====
+[role="term"]
+----
+$ babeltrace query src.ctf.fs metadata-info \
+ --params='path="/path/to/trace"'
+----
+====
+
+.Query the trace info of CTF traces located on the local file system.
+====
+[role="term"]
+----
+$ babeltrace query src.ctf.fs trace-info \
+ --params='path="/path/to/trace"'
+----
+====
+
+.Query some object from a sink component class without parameters.
+====
+[role="term"]
+----
+$ babeltrace query sink.my-plugin.my-sink some-object
+----
+====
+
+
+include::common-cli-env.txt[]
+
+include::common-cli-files.txt[]
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace(1),
+man:babeltrace-intro(7)
--- /dev/null
+babeltrace-run(1)
+=================
+:manpagetype: command
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-run - Create a trace processing graph and run it
+
+
+SYNOPSIS
+--------
+[verse]
+*babeltrace run* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
+ [opt:--omit-system-plugin-path]
+ [opt:--plugin-path='PATH'[:__PATH__]...]
+ [opt:--retry-duration='DURUS']
+ opt:--connect='CONN-RULE'... 'COMPONENTS'
+
+
+DESCRIPTION
+-----------
+The `run` command creates a trace processing graph and runs it.
+
+See man:babeltrace-intro(7) to learn more about the Babeltrace
+project and its core concepts.
+
+The `run` command uses libbabeltrace to dynamically load plugins which
+supply component classes. With the `run` command, you specify which
+component classes to instantiate as components and how they must be
+connected.
+
+The steps to write a `babeltrace run` command line are:
+
+. Specify which component classes to instantiate as components and
+ how. This is the 'COMPONENTS' part of the synopsis. See
+ <<create-comps,Create components>> to learn more.
+
+. Specify how to connect component instances together with one or more
+ opt:--connect options. See <<connect-comps,Connect components>> to
+ learn more.
+
+NOTE: The man:babeltrace-convert(1) command is a specialization of the
+`run` command for the very common case of converting one or more traces:
+it generates a `run` command line and executes it. You can use its
+manopt:babeltrace-convert(1):--run-args or
+manopt:babeltrace-convert(1):--run-args-0 option to make it print the
+equivalent `run` command line instead.
+
+
+[[create-comps]]
+Create components
+~~~~~~~~~~~~~~~~~
+To create a component, use the opt:--component option. This option
+specifies:
+
+* **Optional**: The name of the component instance. You can also use the
+ opt:--name option for this.
+
+* The type of the component class to instantiate: source, filter, or
+ sink.
+
+* The name of the plugin in which to find the component class to
+ instantiate.
+
+* The name of the component class to instantiate.
+
+You can use the opt:--component option multiple times to create
+multiple components. You can instantiate the same component class
+multiple times as different component instances.
+
+At any point in the command line, the opt:--base-params sets the current
+base initialization parameters and the opt:--reset-base-params resets
+them. When you specify a opt:--component option, its initial
+initialization parameters are a copy of the current base initialization
+parameters.
+
+Immediately following a opt:--component option on the command line, the
+created component is known as the _current component_ (until the next
+opt:--component option).
+
+The following, optional command-line options apply to the current
+component:
+
+opt:--name='NAME'::
+ Set the name of the current component to 'NAME'.
+
+opt:--params='PARAMS'::
+ Add 'PARAMS' to the initialization parameters of the current
+ component. If 'PARAMS' contains a key which exists in the current
+ component's initialization parameters, this parameter is replaced.
++
+See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+
+opt:--key='KEY' followed with opt:--value='VALUE'::
+ Set the current component's initialization parameter named 'KEY' to
+ the string value 'VALUE'. If 'KEY' exists in the current component's
+ initialization parameters, the parameter is replaced.
+
+
+[[connect-comps]]
+Connect components
+~~~~~~~~~~~~~~~~~~
+The components which you create from component classes with the
+opt:--component option (see <<create-comps,Create components>>) can
+create input and output _ports_ depending on their type. An output port
+is where notifications, like trace events, are sent. An input port is
+where notifications are received. For a given component instance, each
+port has a unique name.
+
+The purpose of the `run` command is to create a trace processing graph,
+that is, to know which component ports to connect together. The command
+achieves this with the help of the connection rules that you provide
+with the opt:--connect option.
+
+The format of a connection rule (the argument of the opt:--connect
+option) is:
+
+[verse]
+__UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__]
+
+'UP-COMP-PATH'::
+ Upstream component name pattern.
+
+'UP-PORT-PAT'::
+ Upstream port name pattern.
+
+'DOWN-COMP-PATH'::
+ Downstream component name pattern.
+
+'DOWN-PORT-PAT'::
+ Downstream port name pattern.
+
+When a source or filter component adds a new output port within the
+processing graph, the `run` command does the following to find an
+input port to connect it to:
+
+----
+For each connection rule:
+ If the output port's component's name matches UP-COMP-PAT and
+ the output port's name matches UP-PORT-PAT:
+ For each component COMP in the processing graph:
+ If the name of COMP matches DOWN-COMP-PAT:
+ Select the first input port of COMP of which the name
+ matches DOWN-PORT-PAT, or fail with no match.
+Fail with no match.
+----
+
+__UP-COMP-PAT__, __UP-PORT-PAT__, __DOWN-COMP-PAT__, and
+__DOWN-PORT-PAT__ are globbing patterns where only the wildcard
+character, `*`, is special: it matches zero or more characters. You must
+escape the `*`, `?`, `[`, `.`, `:`, and :bs: characters with :bs:.
+
+When you do not specify __UP-PORT-PAT__ or __DOWN-PORT-PAT__, they are
+equivalent to `*`.
+
+You can leverage this connection mechanism to specify fallbacks with a
+careful use of wildcards. For example:
+
+----
+--connect='A.out*:B.in*' --connect=A:B --connect='*:C'
+----
+
+With those connection rules:
+
+* Any output port of which the name starts with `out` of component `A`
+ is connected to the first input port of which the name starts with
+ `in` of component `B`.
+
+* Any other output port of component `A` is connected to the first
+ available input port of component `B`.
+
+* Any other output port (of any component except `A`) is connected to
+ the first available input port of component `C`.
+
+The `run` command fails when it cannot find an input port to which to
+connect a created output port using the provided connection
+rules.
+
+See <<examples,EXAMPLES>> for more examples.
+
+
+include::common-cmd-params-format.txt[]
+
+include::common-cmd-plugin-path.txt[]
+
+
+OPTIONS
+-------
+include::common-gen-options.txt[]
+
+
+Component creation
+~~~~~~~~~~~~~~~~~~
+opt:-b 'PARAMS', opt:--base-params='PARAMS'::
+ Set the current base parameters to 'PARAMS'. You can reset the
+ current base parameters with the opt:--reset-base-params option.
+ See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+
+opt:-c $$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS', opt:--component=$$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS'::
+ Create a component initially named 'NAME' (if specified) from the
+ component class of type 'TYPE' named 'COMPCLS' found in the plugin
+ named 'PLUGIN', and set it as the current component.
++
+The available values for 'TYPE' are:
++
+--
+`source`::
+`src`::
+ Source component class.
+
+`filter`::
+`flt`::
+ Filter component class.
+
+`sink`::
+ Sink component class.
+--
++
+The initial initialization parameters of this component are copied from
+the current base initialization parameters (see the opt:--base-params
+option).
+
+opt:--key='KEY'::
+ Set the current parameter key to 'KEY'. The next opt:--value option
+ uses this key to add a parameter to the current component.
+
+opt:--name='NAME'::
+ Set the name of the current component to 'NAME'. The names of all
+ the components in the processing graph must be unique.
+
+opt:-p 'PARAMS', opt:--params='PARAMS'::
+ Add 'PARAMS' to the initialization parameters of the current
+ component. If 'PARAMS' contains a key which exists in the current
+ component's initialization parameters, replace the parameter.
+ See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+
+opt:-r, opt:--reset-base-params::
+ Reset the current base parameters. You can set the current base
+ parameters with the opt:--base-params option.
+
+opt:-v 'VALUE', opt:--value='VALUE'::
+ Add a parameter to the current component's initialization parameters
+ of which the key is the argument of the last opt:--key option and
+ the string value is 'VALUE'. If the current component's
+ initialization parameters already contain a key named 'KEY', replace
+ the parameter.
+
+
+Component connection
+~~~~~~~~~~~~~~~~~~~~
+opt:-C 'CONN-RULE', opt:--connect='CONN-RULE'::
+ Add the connection rule 'CONN-RULE'. See
+ <<connect-comps,Connect components>> for the format of 'CONN-RULE'.
+
+
+Graph configuration
+~~~~~~~~~~~~~~~~~~~
+opt:--retry-duration='DURUS'::
+ Set the duration of a single retry to 'DURUS'{nbsp}µs when a
+ component reports "try again later" (busy network or file system,
+ for example).
++
+Default: 100000 (100{nbsp}ms).
+
+
+include::common-plugin-path-options.txt[]
+
+include::common-cmd-info-options.txt[]
+
+
+[[examples]]
+EXAMPLES
+--------
+.Create a single-port source component and a single-port sink component and connect them.
+====
+[role="term"]
+----
+$ babeltrace run --component=A:src.plug.my-src \
+ --component=B:sink.plug.my-sink \
+ --connect=A:B
+----
+
+Possible resulting graph:
+
+----
++-----------------+ +-------------------+
+| src.plug.my-src | | sink.plug.my-sink |
+| [A] | | [B] |
+| | | |
+| out @--->@ in |
++-----------------+ +-------------------+
+----
+====
+
+.Use the opt:--name option to name the current component.
+====
+[role="term"]
+----
+$ babeltrace run --component=src.plug.my-src --name=the-source \
+ --component=the-sink:sink.plug.my-sink \
+ --connect=the-source:the-sink
+----
+====
+
+.Use the opt:--params option to set the current component's initialization parameters.
+====
+In this example, the opt:--params option only applies to component
+`the-source`.
+
+[role="term"]
+----
+$ babeltrace run --component=the-source:src.my-plugin.my-src \
+ --params='offset=123, flag=true' \
+ --component=the-sink:sink.my-plugin.my-sink \
+ --connect=the-source:the-sink
+----
+====
+
+.Use the opt:--key and opt:--value options to set a current component's initialization parameter.
+====
+[role="term"]
+----
+$ babeltrace run --component=the-source:src.my-plugin.my-src \
+ --key=path --value ~/my-traces/the-trace
+ --component=the-sink:sink.my-plugin.my-sink \
+ --connect=the-source:the-sink
+----
+====
+
+.Use the opt:--base-params and opt:--reset-base-params options to set and reset the current base initialization parameters.
+====
+In this example, the effective initialization parameters of the
+created components are:
+
+* Component `A`: `offset=1203, flag=false`
+* Component `B`: `offset=1203, flag=true, type=event`
+* Component `C`: `ratio=0.25`
+
+[role="term"]
+----
+$ babeltrace run --base-params='offset=1203, flag=false' \
+ --component=A:src.plugin.compcls \
+ --component=B:flt.plugin.compcls \
+ --params='flag=true, type=event' \
+ --reset-base-params \
+ --component=C:sink.plugin.compcls \
+ --params='ratio=0.25' \
+ --connect=A:B --connect=B:C
+----
+====
+
+.Specify a component connection fallback rule.
+====
+In this example, any `A` output port of which the name starts with
+`foo` is connected to a `B` input port of which the name starts with
+`nin`. Any other `A` output port is connected to a `B` input port of
+which the name starts with `oth`.
+
+The order of the opt:--connect options is important here: the opposite
+order would create a system in which the first rule is always satisfied,
+and _any_ `A` output port, whatever its name, would be connected to a
+`B` input port with a name that starts with `oth`.
+
+[role="term"]
+----
+$ babeltrace run --component=A:src.plug.my-src \
+ --component=B:sink.plug.my-sink \
+ --connect='A.foo*:B:nin*' --connect='A:B.oth*'
+----
+
+Possible resulting graph:
+
+----
++-----------------+ +-------------------+
+| src.plug.my-src | | sink.plug.my-sink |
+| [A] | | [B] |
+| | | |
+| foot @--->@ nine |
+| foodies @--->@ ninja |
+| some-port @--->@ othello |
+| hello @--->@ other |
++-----------------+ +-------------------+
+----
+====
+
+
+include::common-cli-env.txt[]
+
+include::common-cli-files.txt[]
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace(1),
+man:babeltrace-convert(1),
+man:babeltrace-intro(7)
--- /dev/null
+babeltrace-sink.ctf.fs(7)
+=========================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-sink.ctf.fs - Babeltrace's file system CTF sink component
+class
+
+
+DESCRIPTION
+-----------
+The Babeltrace compcls:sink.ctf.fs component class, provided by the
+man:babeltrace-plugin-ctf(7) plugin, once instantiated, writes the
+events it receives to one or more http://diamon.org/ctf/[CTF] traces on
+the file system.
+
+A compcls:sink.ctf.fs component does not merge traces, in that it writes
+the notifications of different input traces to different output traces.
+
+This component guarantees that the output traces are semantically
+equivalent to the input traces. This means that a given output CTF trace
+contains:
+
+* The original trace environment.
+* The original clock classes.
+* The original event class names, log levels, and other static
+ attributes, except for the numeric IDs.
+* The original field _values_, except for:
+** Timestamp fields, but the equivalent clock value remains the same.
+** Numeric ID fields.
+
+The component does not guarantee to keep:
+
+* The original field type attributes (for example, the sizes of the
+ integer field types).
+* The original stream class and event class numeric IDs.
+
+
+Output path
+~~~~~~~~~~~
+The path of a CTF trace is the directory which directly contains the
+metadata and data stream files as children.
+
+The rules to determine the path of a generated CTF trace are:
+
+* If the param:single-trace parameter is true, use the value of the
+ param:path parameter.
++
+Otherwise:
++
+--
+* If the input trace has a name, use `OUTPUTPATH/TRACENAME[SUFFIX]`,
+ where `OUTPUTPATH` is the value of the param:path parameter,
+ `TRACENAME` is the input trace's name, and `SUFFIX` is an optional
+ numeric suffix if `OUTPUTPATH/TRACENAME` already exists.
++
+Note that the name of a trace that a compcls:source.ctf.fs component
+creates includes its hostname and its relative path while making sure to
+avoid conflicts.
++
+Otherwise, use `OUTPUTPATH/trace[SUFFIX]`, where `OUTPUTPATH` and
+`SUFFIX` are defined above.
+--
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+param:path='PATH' (string, mandatory)::
+ Depending on the value of the param:single-trace parameter, prefix
+ of output trace paths or full output trace path.
+
+param:single-trace=`yes` (boolean, optional)::
+ Assume that the component only receives notifications related to
+ a single source trace.
+
+
+PORTS
+-----
+Input
+~~~~~
+`in`::
+ Single input port from which the component receives the
+ notifications.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-ctf-plugin-env.txt[]
+
+
+Component class
+~~~~~~~~~~~~~~~
+include::common-common-compat-env.txt[]
+
+`BABELTRACE_SINK_CTF_FS_LOG_LEVEL`::
+ Component class's log level. The available values are the
+ same as for the manopt:babeltrace(1):--log-level option of
+ man:babeltrace(1).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace-plugin-ctf(7),
+man:babeltrace-intro(7)
--- /dev/null
+babeltrace-sink.text.pretty(7)
+==============================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-sink.text.pretty - Babeltrace's pretty-printing sink
+component class
+
+
+DESCRIPTION
+-----------
+The Babeltrace compcls:sink.text.pretty component class, provided by the
+man:babeltrace-plugin-text(7) plugin, once instantiated, pretty-prints
+the events it receives from its input port to the console or to a file.
+
+By default, a compcls:sink.text.pretty component pretty-prints to
+the standard output. You can use the param:path parameter for the
+component to write to a file instead.
+
+The component also prints warnings on the standard error stream when it
+receives a discarded packets or discarded events notification.
+
+If you don't use the param:path parameter and the application's
+standard output is connected to a color-capable terminal, the component
+emits terminal color codes to enhance the text output for human
+consumption. You can use the param:color parameter to force the color
+support or to disable it.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+The following parameters are optional.
+
+param:clock-cycles=`yes` (boolean)::
+ Print event times in clock cycles instead of hours, minutes,
+ seconds, and nanoseconds.
+
+param:clock-date=`yes` (boolean)::
+ Print event times _and_ dates.
+
+param:clock-gmt=`yes` (boolean)::
+ Print event times in the GMT time zone instead of the local time
+ zone.
+
+param:clock-seconds=`yes` (boolean)::
+ Print event times in seconds instead of hours, minutes,
+ seconds, and nanoseconds.
+
+param:color=(`never` | `auto` | `always`) (string)::
+ Force the terminal color support, one of:
++
+--
+`auto` (default)::
+ Only emit terminal color codes when the standard output and error
+ streams are connected to a color-capable terminal.
+
+`never`::
+ Never emit terminal color codes.
+
+`always`::
+ Always emit terminal color codes.
+--
++
+The `BABELTRACE_TERM_COLOR` environment variable overrides this
+parameter.
+
+param:field-default=(`show` | `hide`) (string)::
+ By default, show or hide all the fields. This sets the default value
+ of all the parameters which start with `field-`.
+
+param:field-emf=(`yes` | `no`) (boolean)::
+ Show or hide the event's Eclipse Modeling Framework URI field.
+
+param:field-loglevel=(`yes` | `no`) (boolean)::
+ Show or hide the event's logging level field.
+
+param:field-trace=(`yes` | `no`) (boolean)::
+ Show or hide the trace name field.
+
+param:field-trace:domain=(`yes` | `no`) (boolean)::
+ Show or hide the tracing domain field.
+
+param:field-trace:hostname=(`yes` | `no`) (boolean)::
+ Show or hide the hostname field.
+
+param:field-trace:procname=(`yes` | `no`) (boolean)::
+ Show or hide the process name field.
+
+param:field-trace:vpid=(`yes` | `no`) (boolean)::
+ Show or hide the virtual process ID field.
+
+param:name-context=(`yes` | `no`) (boolean)::
+ Show or hide the field names in the context scopes.
+
+param:name-default=(`show` | `hide`) (string)::
+ By default, show or hide all the names. This sets the
+ default value of all the parameters which start with `name-`.
+
+param:name-header=(`yes` | `no`) (boolean)::
+ Show or hide the field names in the header scopes.
+
+param:name-payload=(`yes` | `no`) (boolean)::
+ Show or hide the field names in the event payload scopes.
+
+param:name-scope=(`yes` | `no`) (boolean)::
+ Show or hide the scope names.
+
+param:no-delta=`yes` (boolean)::
+ Do not print the time delta between consecutive lines.
+
+param:path='PATH' (string)::
+ Print the text output to the file 'PATH' instead of the standard
+ output.
+
+param:verbose=`yes` (boolean)::
+ Turn the verbose mode on.
+
+
+PORTS
+-----
+Input
+~~~~~
+`in`::
+ Single input port from which the component receives the
+ event notifications to pretty-print.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-common-compat-env.txt[]
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace-plugin-text(7),
+man:babeltrace-intro(7)
--- /dev/null
+babeltrace-sink.utils.counter(7)
+================================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-sink.utils.counter - Babeltrace's notification counter sink
+component class
+
+
+DESCRIPTION
+-----------
+The Babeltrace compcls:sink.utils.counter component class, provided by
+the man:babeltrace-plugin-utils(7) plugin, once instantiated, prints to
+the standard output the number of notifications it receives on its input
+port, with a count for each type.
+
+The component's output looks like this:
+
+----
+ 664891 events
+ 12 stream beginnings
+ 0 stream ends
+ 93 packet beginnings
+ 81 packet ends
+ 0 inactivities
+ 6 discarded events notifications
+ 375378 known discarded events
+ 2 discarded packets notifications
+ 5 known discarded packets
+ 1040455 notifications (TOTAL)
+----
+
+By default, a compcls:sink.utils.counter component prints a new block of
+statistics every 1000 received notifications, whatever their types. You
+can use the param:step parameter to override this default period.
+
+The component always prints a block of statistics when there's no more
+notifications to receive from its input port and the last block was
+different.
+
+By default, a compcls:sink.utils.counter component prints the count of
+notifications for each type, even if this count is 0. You can make it
+hide the zero counts with the param:hide-zero parameter.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+The following parameters are optional.
+
+param:hide-zero=`yes` (boolean)::
+ Do not print the statistics lines where the count is zero.
+
+param:step='STEP' (integer)::
+ Print a new block of statistics every 'STEP' received notifications
+ instead of 1000. If 'STEP' is 0, then the component only prints
+ statistics when there's no more notifications to receive.
+
+
+PORTS
+-----
+Input
+~~~~~
+`in`::
+ Single input port from which the component receives the
+ notifications to count.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-common-compat-env.txt[]
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace-plugin-utils(7),
+man:babeltrace-intro(7)
--- /dev/null
+babeltrace-sink.utils.dummy(7)
+==============================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-sink.utils.dummy - Babeltrace's dummy sink component class
+
+
+DESCRIPTION
+-----------
+The Babeltrace compcls:sink.utils.dummy component class, provided by the
+man:babeltrace-plugin-utils(7) plugin, once instantiated, receives
+notifications from its input port and discards them (does absolutely
+nothing with them).
+
+A compcls:sink.utils.dummy sink component can be useful to run a trace
+processing graph with no sink side effect, for example to perform
+benchmarks. You should prefer this component class for such tasks
+instead of, for example, using a compcls:sink.text.pretty component and
+sending its output to `/dev/null`, as a compcls:sink.text.pretty
+component still performs pretty-printing operations.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+This component class has no initialization parameters.
+
+
+PORTS
+-----
+Input
+~~~~~
+`in`::
+ Single input port from which the component receives the
+ notifications to discard.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-common-compat-env.txt[]
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace-plugin-utils(7),
+man:babeltrace-intro(7)
--- /dev/null
+babeltrace-source.ctf.fs(7)
+===========================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-source.ctf.fs - Babeltrace's file system CTF source
+component class
+
+
+DESCRIPTION
+-----------
+The Babeltrace compcls:source.ctf.fs component class, provided by the
+man:babeltrace-plugin-ctf(7) plugin, once instantiated, opens one or
+more http://diamon.org/ctf/[CTF] traces on the file system and emits the
+notifications of their data streams on its output ports.
+
+
+Operation
+~~~~~~~~~
+A compcls:source.ctf.fs component recurses the directory given by the
+param:path parameter to find CTF traces. Note that, since a CTF trace
+directory cannot contain another CTF trace, if you need to open a single
+trace, set the param:path parameter to a directory which directly
+contains the `metadata` file.
+
+For each trace, the component creates one output port per effective data
+stream. Multiple data stream files can constitute a single effective
+data stream. The name of a data stream output port is the absolute path
+to the corresponding data stream file, or to one of the corresponding
+data stream files if there's more than one.
+
+The component skips the following files when looking for data stream
+files:
+
+* Any file which starts with `.`, including subdirectories.
+* Any non-regular file.
+
+
+[[trace-naming]]
+Trace naming
+~~~~~~~~~~~~
+A compcls:source.ctf.fs component names each trace `[HOSTNAME/]PATH`,
+with:
+
+`HOSTNAME`::
+ Value of the trace's `hostname` environment constant. If this
+ environment constant does not exist, or if its value is not a
+ string, then this part is omitted.
+
+`PATH`::
+ Relative path to the trace, starting at and including the basename
+ of the param:path parameter. This path is normalized, that is, it
+ doesn't contain path elements named `..` or `.`.
+
+For example, assume the following hierarchy:
+
+----
+/
+ home/
+ user/
+ my-traces/
+ trace1/
+ metadata
+ ...
+ node-traces/
+ server/
+ metadata
+ ...
+ client/
+ metadata
+ ...
+----
+
+If you set the param:path parameter to `/home/user/my-traces`, and
+assuming the hostname of the `trace1` and `server` traces is `machine`,
+and the hostname of the `client` trace is `embedded`, then the trace
+names are:
+
+* `machine/my-traces/trace1`
+* `machine/my-traces/node-traces/server`
+* `embedded/my-traces/node-traces/client`
+
+
+Metadata quirks
+~~~~~~~~~~~~~~~
+A compcls:source.ctf.fs component makes some efforts to support as many
+CTF traces as possible, even those of which the metadata is malformed
+or implements specification bugs.
+
+In particular:
+
+* If the component detects that the trace was produced by LTTng, it sets
+ the `monotonic` clock class as absolute so that different LTTng traces
+ are directly correlatable. An LTTng trace has its `tracer_name`
+ environment constant starting with `lttng`.
+
+* If the `timestamp_begin` or `timestamp_end` packet context field
+ type exists, but it is not mapped to a clock class, and there's
+ only one clock class at this point in the metadata stream, the
+ component maps it to this unique clock class.
+
+* If an enumeration field type's label starts with `_`, the component
+ removes the starting `_` character. This is needed to accomodate
+ an eventual variant field type which refers to the enumeration field type
+ as its tag and which has equivalent choice names also starting
+ with `_` (the `_` must be removed from field and choice names as
+ per CTF{nbsp}1.8.2).
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+The following parameters are optional unless indicated otherwise.
+
+param:clock-class-offset-ns (integer)::
+ Value to add, in nanoseconds, to the offset of all the clock classes
+ that the component creates.
++
+You can combine this parameter with the param:clock-class-offset-s
+parameter.
+
+param:clock-class-offset-s (integer)::
+ Value to add, in seconds, to the offset of all the clock classes
+ that the component creates.
++
+You can combine this parameter with the param:clock-class-offset-ns
+parameter.
+
+param:path='PATH' (string, mandatory)::
+ Path to the directory to recurse for CTF traces.
+
+
+PORTS
+-----
+Output
+~~~~~~
+For each opened trace, the component creates one output port for each
+effective data stream. The name of a data stream output port is the
+normalized (no `..` or `.` elements) absolute path to the corresponding
+data stream file, or to one of the corresponding data stream files if
+there's more than one.
+
+
+QUERY OBJECTS
+-------------
+`metadata-info`
+~~~~~~~~~~~~~~~
+You can query the `metadata-info` object for a specific CTF trace to get
+its plain text metadata stream as well as whether or not it is
+packetized.
+
+Parameters:
+
+`path` (string, mandatory)::
+ Path to the CTF trace directory which contains the `metadata` file.
+
+Returned object (map):
+
+`text` (string)::
+ Plain text metadata.
+
+`is-packetized` (boolean)::
+ True if the metadata stream is packetized.
+
+
+`trace-info`
+~~~~~~~~~~~~
+You can query the `trace-info` object for a set of CTF traces to get
+information about the data streams they contain, their intersection time
+range, and more.
+
+This query object requires that the processed CTF traces have the
+`timestamp_begin` and `timestamp_end` fields in their packet context
+field types.
+
+Parameters:
+
+`path` (string, mandatory)::
+ Path to a directory to recurse to find CTF traces.
+
+Returned object (array of maps, one element for each found trace):
+
+`name` (string)::
+ Trace name, as per the explanations in the <<trace-naming,Trace
+ naming>> section.
+
+`path` (string)::
+ Trace path.
+
+`range-ns` (map)::
+ Full time range of the trace.
++
+--
+`begin` (integer)::
+ Beginning time (ns since Epoch) of the trace.
+
+`end` (integer)::
+ End time (ns since Epoch) of the trace.
+--
+
+`intersection-range-ns` (map)::
+ This entry only exists if there is a data stream intersection range.
++
+--
+`begin` (integer)::
+ Beginning time (ns since Epoch) of the trace's data stream
+ intersection.
+
+`end` (integer)::
+ End time (ns since Epoch) of the trace's data stream intersection.
+--
+
+`streams` (array of maps, one element for each trace's effective data stream)::
++
+--
+`paths` (array of strings)::
+ Absolute paths to the data stream files which are part of this
+ data stream.
+
+`class-id` (integer)::
+ Numeric ID of the data stream's class.
+
+`range-ns` (map)::
+ Full time range of the data stream.
++
+--
+`begin` (integer)::
+ Beginning time (ns since Epoch) of the data stream.
+
+`end` (integer)::
+ End time (ns since Epoch) of the data stream.
+--
+--
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-ctf-plugin-env.txt[]
+
+
+Component class
+~~~~~~~~~~~~~~~
+include::common-common-compat-env.txt[]
+
+`BABELTRACE_SRC_CTF_FS_LOG_LEVEL`::
+ Component class's log level. The available values are the
+ same as for the manopt:babeltrace(1):--log-level option of
+ man:babeltrace(1).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace-plugin-ctf(7),
+man:babeltrace-intro(7)
--- /dev/null
+babeltrace-source.ctf.lttng-live(7)
+===================================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-source.ctf.lttng-live - Babeltrace's LTTng live source
+component class
+
+
+DESCRIPTION
+-----------
+The Babeltrace compcls:source.ctf.lttng-live source component class,
+provided by the man:babeltrace-plugin-ctf(7) plugin, once instantiated,
+connects to a local or remote http://lttng.org/[LTTng] relay daemon and
+emits the received notifications on its output ports. More information
+about LTTng live is available in the
+http://lttng.org/docs/#doc-lttng-live[LTTng Documentation].
+
+A compcls:source.ctf.lttng-live component handles the notifications of
+one, and only one LTTng tracing session. A single LTTng tracing session
+can contain one or more traces, depending on the active tracing domains
+and the configured user space buffering scheme.
+
+The component connects to an LTTng relay daemon using the param:url
+parameter.
+
+For each trace, the component creates one output port per effective data
+stream. The name of a data stream output port is `stream-` followed by
+its unique LTTng live ID within the tracing session.
+
+The component names each trace `[HOSTNAME/]SESSION/PATH`, with:
+
+`HOSTNAME`::
+ Value of the trace's `hostname` environment constant. If this
+ environment constant does not exist, or if its value is not a
+ string, then this part is omitted.
+
+`SESSION`::
+ Tracing session name.
+
+`PATH`::
+ Other path elements up to the trace directory containing the
+ `metadata` file from the LTTng relay daemon's point of view.
+ For example:
++
+----
+kernel
+----
++
+----
+ust/uid/1000/64-bit
+----
+
+For example:
+
+----
+myhost/auto-20150909-223909/ust/uid/1000/64-bit
+----
+
+A compcls:source.ctf.lttng-live never blocks: it asks the downstream
+component to try again later instead.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+param:url='URL' (string, mandatory)::
+ The URL to use to connect to the LTTng relay daemon. The format
+ of 'URL' is:
++
+--
+[verse]
+net[4]://__RDHOST__[:__RDPORT__]/host/__TGTHOST__/__SESSION__
+
+'RDHOST'::
+ LTTng relay daemon's host name or IP address.
+
+'RDPORT'::
+ LTTng relay daemon's listening port. If not specified, the default
+ port, 5344, is used.
+
+'TGTHOST'::
+ Target's host name or IP address.
+
+'SESSION'::
+ Name of the LTTng tracing session from which to receive data.
+--
+
+
+PORTS
+-----
+Output
+~~~~~~
+When you create the component, its only output port is `no-stream`. This
+port exists as long as there is no data stream output port. The port
+only asks the downstream component to try again later.
+
+For each received LTTng trace, the component creates one output port for
+each effective data stream. The name of a data stream output port is
+`stream-ID`, where `ID` is a unique LTTng live ID within the tracing
+session.
+
+
+QUERY OBJECTS
+-------------
+`sessions`
+~~~~~~~~~~
+You can query the `sessions` object to get a list of available LTTng
+live tracing sessions for a given LTTng relay daemon URL.
+
+Parameters:
+
+`url` (string, mandatory)::
+ The URL to use to connect to the LTTng relay daemon. The format
+ of 'URL' is:
++
+--
+[verse]
+net[4]://__RDHOST__[:__RDPORT__]
+
+'RDHOST'::
+ LTTng relay daemon's host name or IP address.
+
+'RDPORT'::
+ LTTng relay daemon's listening port. If not specified, the default
+ port, 5344, is used.
+--
+
+Returned object (array of maps, one element for each tracing session):
+
+`url` (string)::
+ URL to use as the param:url parameter to connect to the same LTTng
+ relay daemon and receive data from this tracing session.
+
+`target-hostname` (string)::
+ Hostname of the tracing session. This is not necessarily the
+ relay daemon's hostname.
+
+`session-name` (string)::
+ Tracing session's name.
+
+`timer-us` (integer)::
+ Tracing session's configured live timer (µs)
+ (see man:lttng-create(1)).
+
+`stream-count` (integer)::
+ Current number of streams in this tracing sessions, including the
+ metadata streams.
+
+`client-count` (integer)::
+ Current number of LTTng live clients connected to the relay daemon
+ to receive data from this tracing session.
+
+
+LIMITATIONS
+-----------
+A compcls:source.ctf.lttng-live component only accepts a connection
+to one of its output port if all its output ports are connected to the
+input ports of the same downstream component.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-ctf-plugin-env.txt[]
+
+
+Component class
+~~~~~~~~~~~~~~~
+include::common-common-compat-env.txt[]
+
+`BABELTRACE_SRC_CTF_LTTNG_LIVE_LOG_LEVEL`::
+ Component class's log level. The available values are the
+ same as for the manopt:babeltrace(1):--log-level option of
+ man:babeltrace(1).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace-plugin-ctf(7),
+man:babeltrace-intro(7),
+man:lttng-relayd(8),
+man:lttng-create(1)
--- /dev/null
+babeltrace-source.text.dmesg(7)
+===============================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace-source.text.dmesg - Babeltrace's Linux kernel ring buffer
+source component class
+
+
+DESCRIPTION
+-----------
+The Babeltrace compcls:source.text.dmesg component class, provided by
+the man:babeltrace-plugin-text(7) plugin, once instantiated, reads the
+lines of a Linux kernel ring buffer, as printed by the man:dmesg(1)
+tool, and emits corresponding event notifications on its output port.
+
+The events created by a compcls:source.text.dmesg component are named
+`string` and contain a single payload string field named `str` which
+contains the corresponding ring buffer line.
+
+By default, a compcls:source.text.dmesg component reads the lines of the
+standard input stream. You can make the component read the lines of a
+text file instead with the param:path parameter.
+
+By default, the component tries to extract the timestamps of the kernel
+ring buffer lines and use them as the created events's timestamps. A
+typical man:dmesg(1) line looks like this:
+
+----
+[87166.510937] PM: Finishing wakeup.
+----
+
+In the last example, the `[87166.510937]` part is the timestamp to
+extract. You can make the component not extract timestamps from lines
+with the param:no-extract-timestamp parameter.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+The following parameters are optional.
+
+param:no-extract-timestamp=`yes` (boolean)::
+ Do :not: extract timestamps from the kernel ring buffer lines: set
+ the created event's payload's `str` field to the whole line,
+ including any timestamp prefix.
+
+param:path='PATH' (string)::
+ Read the kernel ring buffer lines from the file 'PATH' instead of
+ the standard input stream.
+
+
+PORTS
+-----
+Output
+~~~~~~
+`out`::
+ Single output port to which the component sends the created
+ notifications.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-common-compat-env.txt[]
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace-plugin-text(7),
+man:babeltrace-intro(7)
--- /dev/null
+babeltrace(1)
+=============
+:manpagetype: program
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace - Convert or process one or more traces, and more
+
+
+SYNOPSIS
+--------
+[verse]
+*babeltrace* [opt:--debug | opt:--verbose | opt:--log-level='LVL'] ['<<commands,CMD>>'] ['CMD ARGS']
+
+
+DESCRIPTION
+-----------
+`babeltrace` is an open-source trace converter and processor. The tool
+can convert from one trace format to another, possibly with one or more
+filters in the conversion path, and perform other operations depending
+on the command 'CMD'.
+
+See man:babeltrace-intro(7) to learn more about the Babeltrace
+project and its core concepts.
+
+Most of the `babeltrace` commands load Babeltrace plugins to perform
+their operation. The search path for Babeltrace plugins is, in this
+order:
+
+. The colon-separated list of directories in the
+ `BABELTRACE_PLUGIN_PATH` environment variable.
+
+. The colon-separated list of directories in the specific command's
+ nlopt:--plugin-path option.
+
+. `$HOME/.local/lib/babeltrace/plugins`
+
+. +{system_plugin_path}+
+
+You can use the man:babeltrace-list-plugins(1) command to dynamically
+list the available plugins and what they offer. See <<plugins,PLUGINS>>
+for a list of plugins shipped with Babeltrace.
+
+
+OPTIONS
+-------
+opt:-d, opt:--debug::
+ Turn the debugging mode on.
++
+This is equivalent to opt:--log-level=`VERBOSE`.
+
+opt:--log-level='LVL'::
+ Set the log level of all known Babeltrace loggers to 'LVL'. You
+ can override the level of a specific logger with a dedicated
+ log level environment variable. If you don't specify this option,
+ it is equivalent to nlopt:--log-level=`WARNING`.
++
+The available values for 'LVL' are:
++
+--
+`NONE`::
+`N`::
+ Logging is disabled.
+
+`FATAL`::
+`F`::
+ Severe errors that lead the execution to abort immediately. This
+ level should be enabled in production.
+
+`ERROR`::
+`E`::
+ Errors that might still allow the execution to continue. Usually,
+ once one or more errors are reported at this level, the application,
+ plugin, or library won't perform any more useful task, but it should
+ still exit cleanly. This level should be enabled in production.
+
+`WARN`::
+`WARNING`::
+`W`::
+ Potentially harmful situations which still allow the execution
+ to continue. This level should be enabled in production.
+
+`INFO`::
+`I`::
+ Informational messages that highlight progress or important states
+ of the application, plugin, or library. This level can be enabled in
+ production.
+
+`DEBUG`::
+`D`::
+ Debugging information, with a higher level of details than the
+ `VERBOSE` level. This level should :not: be enabled in production.
+
+`VERBOSE`::
+`V`::
+ Low-level debugging context information. This level should :not: be
+ enabled in production.
+--
+
+opt:-v, opt:--verbose::
+ Turn the verbose mode on.
++
+This is equivalent to opt:--log-level=`INFO`.
+
+opt:-h, opt:--help::
+ Show help and quit.
+
+opt:-V, opt:--version::
+ Show version and quit.
+
+
+[[commands]]
+COMMANDS
+--------
+The following commands also have their own nlopt:--help option.
+
+man:babeltrace-convert(1)::
+ Build a trace conversion graph and run it.
++
+This is the default command: you don't need to explicitly
+specify this command name to use it.
+
+man:babeltrace-help(1)::
+ Get help for a specific plugin or plugin's component class.
+
+man:babeltrace-list-plugins(1)::
+ List the available Babeltrace plugins and their component classes.
+
+man:babeltrace-query(1)::
+ Query an object from a component class.
+
+man:babeltrace-run(1)::
+ Build a trace processing graph and run it.
+
+
+[[plugins]]
+PLUGINS
+-------
+The following plugins are provided by the Babeltrace project itself:
+
+man:babeltrace-plugin-ctf(7)::
+ CTF trace input (from the file system and from the LTTng-live
+ protocol) and output to the file system.
++
+* man:babeltrace-sink.ctf.fs(7)
+* man:babeltrace-source.ctf.fs(7)
+* man:babeltrace-source.ctf.lttng-live(7)
+
+ifeval::[{enable_debug_info} == 1]
+man:babeltrace-plugin-lttng-utils(7)::
+ Processing graph utilities for LTTng traces.
++
+* man:babeltrace-filter.lttng-utils.debug-info(7)
+endif::[]
+
+man:babeltrace-plugin-text(7)::
+ Text input and output.
++
+* man:babeltrace-sink.text.pretty(7)
+* man:babeltrace-source.text.dmesg(7)
+
+man:babeltrace-plugin-utils(7)::
+ Processing graph utilities.
++
+* man:babeltrace-filter.utils.muxer(7)
+* man:babeltrace-filter.utils.trimmer(7)
+* man:babeltrace-sink.utils.counter(7)
+* man:babeltrace-sink.utils.dummy(7)
+
+
+include::common-cli-env.txt[]
+
+include::common-cli-files.txt[]
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace-convert(1),
+man:babeltrace-help(1),
+man:babeltrace-list-plugins(1),
+man:babeltrace-query(1),
+man:babeltrace-run(1),
+man:babeltrace-intro(7)
--- /dev/null
+[macros]
+
+# command-line option in another man page macro
+#
+# Usage: manopt:page(section):--option-name
+(?su)[\\]?(?P<name>manopt):(?P<target>[a-zA-Z0-9_.-]+)\((?P<section>[a-zA-Z0-9]+)\):(?P<opt>--?[a-zA-Z0-9-]*)=
+
+# component class initialization parameter in another man page macro
+#
+# Usage: manparam:type.plugin.compcls:param-name
+(?su)[\\]?(?P<name>manparam):(?P<cctype>[a-zA-Z0-9_-]+)\.(?P<ccplug>[a-zA-Z0-9_-]+)\.(?P<ccname>[a-zA-Z0-9_-]+):(?P<pname>[a-zA-Z0-9_:.-]+(?<![:.]))=
+
+# man macro
+#
+# Usage: man:page(section)
+(?su)[\\]?(?P<name>man):(?P<target>[a-zA-Z0-9_.-]+)\((?P<section>[a-zA-Z0-9]+)\)=
+
+# no link option macro
+#
+# Usage: nlopt:--option-name
+(?su)[\\]?(?P<name>nlopt):(?P<opt>--?[a-zA-Z0-9-]*)=
+
+# command-line option macro
+#
+# Usage: opt:--option-name
+(?su)[\\]?(?P<name>opt):(?P<opt>--?[a-zA-Z0-9-]*)=
+
+# no link component class initialization parameter macro
+#
+# Usage: nlparam:param-name
+(?su)[\\]?(?P<name>nlparam):(?P<pname>[a-zA-Z0-9_:.-]+(?<![:.]))=
+
+# component class initialization parameter macro
+#
+# Usage: param:param-name
+(?su)[\\]?(?P<name>param):(?P<pname>[a-zA-Z0-9_:.-]+(?<![:.]))=
+
+# component class specification macro
+#
+# Usage: compcls:TYPE.PLUGIN.COMPCLS
+(?su)[\\]?(?P<name>compcls):(?P<cctype>[a-zA-Z0-9_-]+)\.(?P<ccplug>[a-zA-Z0-9_-]+)\.(?P<ccname>[a-zA-Z0-9_-]+)=
+
+# not macro
+#
+# Usage: :not:
+:not:=not
+
+# escstar macro
+#
+# Usage: :escstar:
+:escstar:=escstar
+
+# esccomma macro
+#
+# Usage: :esccomma:
+:esccomma:=esccomma
+
+# escdot macro
+#
+# Usage: :escdot:
+:escdot:=escdot
+
+# bs macro
+#
+# Usage: :bs:
+:bs:=bs
+
+# man macro expansions
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[man-inlinemacro]
+<citerefentry>
+<refentrytitle>{target}</refentrytitle><manvolnum>{section}</manvolnum>
+</citerefentry>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+# no link option macro expansions
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[nlopt-inlinemacro]
+<literal>{opt}</literal>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+# command-line option macro expansions
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[opt-inlinemacro]
+<literal>{opt}</literal>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+# command-line option in another man page macro expansions
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[manopt-inlinemacro]
+<literal>{opt}</literal>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+# component class initialization parameter macro expansions
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[param-inlinemacro]
+<literal>{pname}</literal>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+# no link component class initialization parameter macro expansions
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[nlparam-inlinemacro]
+<literal>{pname}</literal>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+# component class initialization parameter in another man page macro expansions
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[manparam-inlinemacro]
+<literal>{pname}</literal>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+# component class specification macro expansions
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[compcls-inlinemacro]
+<literal>{cctype}.{ccplug}.{ccname}</literal>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+# not macro expansions
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[not-inlinemacro]
+NOT
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+# escstar macro expansions
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[escstar-inlinemacro]
+<literal>\e*</literal>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+# esccomma macro expansions
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[esccomma-inlinemacro]
+<literal>\e,</literal>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+# escdot macro expansions
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[escdot-inlinemacro]
+<literal>\e,</literal>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+# bs macro expansions
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[bs-inlinemacro]
+<literal>\e</literal>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+# configure XML man page header
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+ <refentryinfo>
+ <date>{revdate}</date>
+ </refentryinfo>
+ <refmeta>
+ <refentrytitle>{mantitle}</refentrytitle>
+ <manvolnum>{manvolnum}</manvolnum>
+ <refmiscinfo class="source">Babeltrace</refmiscinfo>
+ <refmiscinfo class="version">{babeltrace_version}</refmiscinfo>
+ <refmiscinfo class="manual">Babeltrace manual</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>{manname}</refname>
+ <refpurpose>{manpurpose}</refpurpose>
+ </refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
--- /dev/null
+ENVIRONMENT VARIABLES
+---------------------
+include::common-lib-env.txt[]
+
+include::common-ppp-env.txt[]
+
+CLI
+~~~
+`BABELTRACE_CLI_LOG_LEVEL`::
+ `babeltrace` CLI's log level. The available values are the same as
+ for the manopt:babeltrace(1):--log-level option.
+
+`BABELTRACE_CLI_WARN_COMMAND_NAME_DIRECTORY_CLASH`::
+ Set to `0` to disable the warning message which `babeltrace` prints
+ when you convert a trace with a relative path that's also the name
+ of a `babeltrace` command.
--- /dev/null
+FILES
+-----
+`$HOME/.local/lib/babeltrace/plugins`::
+ User plugin directory.
+
++{system_plugin_path}+::
+ System plugin directory.
--- /dev/null
+EXIT STATUS
+-----------
+*0* on success, *1* otherwise.
+
+
+include::common-footer.txt[]
--- /dev/null
+Command information
+~~~~~~~~~~~~~~~~~~~
+opt:-h, opt:--help::
+ Show the command's help and quit.
--- /dev/null
+[[params-fmt]]
+Parameters format
+~~~~~~~~~~~~~~~~~
+The format of the 'PARAMS' option's argument is a comma-separated
+list of `NAME=VALUE` assignments:
+
+[verse]
+'NAME'='VALUE'[,'NAME'='VALUE']...
+
+'NAME'::
+ Parameter name (C{nbsp}identifier plus the `:`, `.`, and `-` characters).
+
+'VALUE'::
+ One of:
++
+--
+* `null`, `nul`, `NULL`: null value.
+
+* `true`, `TRUE`, `yes`, `YES`: true boolean value.
+
+* `false`, `FALSE`, `no`, `NO`: false boolean value.
+
+* Binary (`0b` prefix), octal (`0` prefix), decimal, or hexadecimal
+ (`0x` prefix) signed 64-bit integer.
+
+* Double precision floating point number (scientific notation is
+ accepted).
+
+* Unquoted string with no special characters, and not matching any of
+ the null and boolean value symbols above.
+
+* Double-quoted string (accepts escape characters).
+
+You may put whitespaces around the individual `=` (assignment) and `,`
+(separator) characters.
+--
+
+Example:
+
+----
+babeltrace ... --params='many=null, fresh=yes, condition=false,
+ squirrel=-782329, observe=3.14,
+ simple=beef, needs-quotes="some string",
+ escape.chars-are:allowed="a \" quote"'
+----
+
+IMPORTANT: Like in the example above, make sure to single-quote the
+whole argument when you run this command from a shell.
--- /dev/null
+Plugin path
+~~~~~~~~~~~
+This command loads Babeltrace plugins to perform its operation. The
+search path for Babeltrace plugins is, in this order:
+
+. The colon-separated list of directories in the
+ `BABELTRACE_PLUGIN_PATH` environment variable.
+
+. The colon-separated list of directories in the opt:--plugin-path
+ option.
+
+. *If the opt:--omit-home-plugin-path option is absent*:
+ `$HOME/.local/lib/babeltrace/plugins`
+
+. *If the opt:--omit-system-plugin-path option is absent*:
+ +{system_plugin_path}+
+
+You can use the man:babeltrace-list-plugins(1) command to dynamically
+list the available plugins.
--- /dev/null
+`BABELTRACE_COMMON_LOG_LEVEL`::
+ Common functions's log level. The available values are the same as
+ for the manopt:babeltrace(1):--log-level option of man:babeltrace(1).
+
+`BABELTRACE_COMPAT_LOG_LEVEL`::
+ Compatibility functions's log level. The available values are the
+ same as for the manopt:babeltrace(1):--log-level option of
+ man:babeltrace(1).
+
+`BABELTRACE_TERM_COLOR`::
+ Force the terminal color support. The available values are:
++
+--
+`AUTO`::
+ Only emit terminal color codes when the standard output and error
+ streams are connected to a color-capable terminal.
+
+`NEVER`::
+ Never emit terminal color codes.
+
+`ALWAYS`::
+ Always emit terminal color codes.
+--
--- /dev/null
+`ctf` plugin
+~~~~~~~~~~~~
+`BABELTRACE_PLUGIN_CTF_BTR_LOG_LEVEL`::
+ Binary type reader's log level. The available values are the same as
+ for the manopt:babeltrace(1):--log-level option of
+ man:babeltrace(1).
+
+`BABELTRACE_PLUGIN_CTF_METADATA_LOG_LEVEL`::
+ Metadata decoder's log level. The available values are the same as
+ for the manopt:babeltrace(1):--log-level option of
+ man:babeltrace(1).
+
+`BABELTRACE_PLUGIN_CTF_NOTIF_ITER_LOG_LEVEL`::
+ Notification iterator's log level. The available values are the same
+ as for the manopt:babeltrace(1):--log-level option of
+ man:babeltrace(1).
--- /dev/null
+BUGS
+----
+If you encounter any issue or usability problem, please report it on the
+https://bugs.linuxfoundation.org/buglist.cgi?product=Diamon&component=Babeltrace[Babeltrace
+bug tracker].
+
+
+RESOURCES
+---------
+The Babeltrace project shares some communication channels with the
+http://lttng.org/[LTTng project].
+
+* http://diamon.org/babeltrace[Babeltrace website]
+* http://git.linuxfoundation.org/?p=diamon/babeltrace.git[Git repository]
+* http://github.com/efficios/[EfficiOS GitHub organization]
+* https://ci.lttng.org/job/babeltrace_master_build/[Continuous integration]
+* http://lists.lttng.org[Mailing list] for support and
+ development: `lttng-dev@lists.lttng.org`
+* irc://irc.oftc.net/lttng[IRC channel]: `#lttng` on `irc.oftc.net`
+
+
+AUTHORS
+-------
+The Babeltrace project is the result of efforts by many regular
+developers and occasional contributors.
+
+The current project maintainer is
+mailto:jeremie.galarneau@efficios.com[Jérémie Galarneau].
+
+
+COPYRIGHT
+---------
+This {manpagetype} is part of the Babeltrace project.
+
+Babeltrace is distributed under the
+https://opensource.org/licenses/MIT[MIT license].
--- /dev/null
+General options
+~~~~~~~~~~~~~~~
+See man:babeltrace(1) for more details.
+
+nlopt:-d, nlopt:--debug::
+ Turn the debugging mode on.
+
+nlopt:--log-level='LVL'::
+ Set the log level of all known Babeltrace loggers to 'LVL'.
+
+nlopt:-v, nlopt:--verbose::
+ Turn the verbose mode on.
+
+nlopt:-h, nlopt:--help::
+ Show general help and quit.
+
+nlopt:-V, nlopt:--version::
+ Show version and quit.
--- /dev/null
+Babeltrace library
+~~~~~~~~~~~~~~~~~~
+include::common-common-compat-env.txt[]
+
+`BABELTRACE_DISABLE_PYTHON_PLUGINS`::
+ Set to `1` to disable the loading of any Babeltrace Python plugin.
+
+`BABELTRACE_LOGGING_GLOBAL_LEVEL`::
+ Babeltrace library's global log level. The available values are the
+ same as for the manopt:babeltrace(1):--log-level option of
+ man:babeltrace(1)
+
+`BABELTRACE_NO_DLCLOSE`::
+ Set to `1` to make the Babeltrace library leave any dynamically
+ loaded modules (plugins and Python plugin provider) open at exit.
+ This can be useful for debugging purposes.
+
+`BABELTRACE_PLUGIN_PATH`::
+ Colon-separated list of directories, in order, in which dynamic
+ plugins can be found before other directories are considered.
--- /dev/null
+Plugin path
+~~~~~~~~~~~
+opt:--omit-home-plugin-path::
+ Do not search for plugins in `$HOME/.local/lib/babeltrace/plugins`.
+
+opt:--omit-system-plugin-path::
+ Do not search for plugins in +{system_plugin_path}+.
+
+opt:--plugin-path='PATH'[:__PATH__]...::
+ Add 'PATH' to the list of paths in which dynamic plugins can be
+ found.
--- /dev/null
+Python plugin provider
+~~~~~~~~~~~~~~~~~~~~~~
+`BABELTRACE_PYTHON_PLUGIN_PROVIDER_LOG_LEVEL`::
+ Python plugin provider's log level. The available values are the
+ same as for the manopt:babeltrace(1):--log-level option of
+ man:babeltrace(1).
--- /dev/null
+<?xml version='1.0'?>
+<xsl:stylesheet version="1.0"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+ <!-- callouts -->
+ <xsl:template match="*[local-name() = 'co']">
+ <xsl:value-of select="concat('\','fB(',substring-after(@id,'-'),')','\','fR')"/>
+ </xsl:template>
+ <xsl:template match="*[local-name() = 'calloutlist']">
+ <xsl:value-of select="."/>
+ <xsl:text>sp </xsl:text>
+ <xsl:apply-templates/>
+ <xsl:text> </xsl:text>
+ </xsl:template>
+ <xsl:template match="*[local-name() = '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>
+
+ <!-- links -->
+ <xsl:template match="*[local-name() = 'ulink']">
+ <xsl:apply-templates/>
+ <xsl:choose>
+ <xsl:when test="starts-with(@url, 'mailto:')">
+ <xsl:text> <</xsl:text><xsl:value-of select="@url"/><xsl:text>></xsl:text>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:text> (see <</xsl:text><xsl:value-of select="@url"/><xsl:text>>)</xsl:text>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:template>
+
+ <!-- literal -->
+ <xsl:template match="*[local-name() = 'literal' and local-name(..) != 'title']">
+ <xsl:text>\fB</xsl:text>
+ <xsl:value-of select="." />
+ <xsl:text>\fR</xsl:text>
+ </xsl:template>
+
+ <!-- disable end notes -->
+ <xsl:param name="man.endnotes.are.numbered">0</xsl:param>
+</xsl:stylesheet>
projects / babeltrace.git / commitdiff
