AC_PROG_GREP
AC_PROG_MAKE_SET
AC_PROG_SED
+AC_PROG_MKDIR_P
AC_PATH_PROG([report_fold], [fold])
LT_INIT
fi
fi
+# API documentation using Doxygen
+AC_ARG_ENABLE([api-doc], [
+ AS_HELP_STRING([--enable-api-doc], [build HTML API documentation])
+], [api_doc=$enableval], [api_doc=no])
+
+AS_IF([test "x$api_doc" = xyes], [
+ DX_DOXYGEN_FEATURE(ON)
+ DX_DOT_FEATURE(OFF)
+ DX_HTML_FEATURE(ON)
+ DX_CHM_FEATURE(OFF)
+ DX_CHI_FEATURE(OFF)
+ DX_MAN_FEATURE(OFF)
+ DX_RTF_FEATURE(OFF)
+ DX_XML_FEATURE(OFF)
+ DX_PDF_FEATURE(OFF)
+ DX_PS_FEATURE(OFF)
+ DX_INIT_DOXYGEN(["LTTng control library"], [$(builddir)/Doxyfile], [output])
+
+ AS_IF([test -z "$DX_DOXYGEN"], [
+ AC_MSG_ERROR([You need Doxygen to build the liblttng-ctl API documentation])
+ ])
+])
+
+AM_CONDITIONAL([API_DOC], [test "x$api_doc" = xyes])
+
# enable building man pages (user's intention)
AC_ARG_ENABLE(
man-pages,
AC_CONFIG_FILES([
Makefile
doc/Makefile
+ doc/api/Makefile
+ doc/api/liblttng-ctl/Doxyfile
+ doc/api/liblttng-ctl/Makefile
doc/examples/Makefile
doc/examples/rotation/Makefile
doc/examples/trigger-condition-event-matches/Makefile
test "x$embedded_help" = xyes && value=1 || value=0
PPRINT_PROP_BOOL([Embed --help messages], $value, $PPRINT_COLOR_SUBTITLE)
+test "x$api_doc" = xyes && value=1 || value=0
+PPRINT_PROP_BOOL([liblttng-ctl HTML API documentation], $value, $PPRINT_COLOR_SUBTITLE)
+
PPRINT_SET_INDENT(1)
report_bindir="`eval eval echo $bindir`"
dist_doc_DATA = quickstart.txt streaming-howto.txt python-howto.txt \
snapshot-howto.txt live-reading-howto.txt \
live-reading-protocol.txt valgrind-howto.txt
+
+if API_DOC
+SUBDIRS += api
+endif
--- /dev/null
+output/
+Doxyfile
+README.html
--- /dev/null
+# SPDX-License-Identifier: GPL-2.0-only
+
+SUBDIRS = liblttng-ctl
+EXTRA_DIST = README.adoc
--- /dev/null
+// Render with Asciidoctor
+
+= LTTng-tools C API documentation guidelines
+Philippe Proulx <pproulx@efficios.com>
+25 August 2021
+:toc: left
+
+This document explains how to write documentation for the LTTng-tools
+C{nbsp}API.
+
+== General rules
+
+* Use four spaces to indent Doxygen text and two spaces to indent HTML.
+
+* Try to stay behind the 72^th^ column mark when possible.
+
+* Use https://en.wikipedia.org/wiki/Non-breaking_space[`+ +`]
+ wherever needed.
+
+* Refer to a function with the `func()` form and to an
+ enumerator/structure/variable or type with the `#name` syntax.
++
+You don't need any `struct`/`enum` prefix with Doxygen.
+
+* When you refer to any keyword or definition, use the `+\c+` command if
+ it's a single word, otherwise surround the words with `<code>` and
+ `</code>`:
++
+--
+----
+@returns
+ Event rule on success, or \c NULL on error.
+----
+--
+
+* Use the `$$\$$__command__` style in text (paragraphs, list items,
+ definition terms, and the rest) and the `@__command__` style for
+ other locations (for example, `@brief`, `@param`, `@sa`, `@file`).
+
+* Use a `@code{.unparsed}` block for a plain text block (shell input,
+ for example):
++
+----
+@code{.unparsed}
+$ lttng enable-event --all --kernel --syscall
+@endcode
+----
+
+* In the text, use custom aliases when applicable.
++
+See `Doxyfile.in` for the list of available aliases.
+
+== Function documentation
+
+Full example:
+
+----
+/*!
+@brief
+ Does something (third person singular, simple present) with some
+ parameter \lt_p{param} unless some other parameter
+ \lt_p{other_param} has some value.
+
+Full documentation goes here and adds any relevant information that's
+not in the brief description.
+
+@code
+/* If needed, put any C code in a code block. */
+@endcode
+
+Crucifix scenester vegan organic neutra palo santo glossier occupy
+truffaut. Meh fixie taiyaki single-origin coffee wayfarers. Thundercats
+farm-to-table shoreditch vinyl.
+
+@remarks
+ This is where you would put some remarks. Occupy flexitarian neutra,
+ edison bulb bespoke sriracha post-ironic. Mlkshk plaid pop-up
+ polaroid chillwave, ennui neutra.
+
+See this image:
+
+@image html mein-illustration.png "Caption goes here."
+
+@note
+ @parblock
+ This is a multiparagraph note.
+
+ Tote bag sartorial distillery, try-hard succulents wayfarers DIY
+ YOLO four loko jianbing farm-to-table unicorn vice.
+
+ Mumblecore semiotics raw denim palo santo chartreuse helvetica
+ shabby chic, distillery pabst poke swag copper mug blue bottle.
+ @endpar
+
+@attention
+ Use an attention command if this message is really important.
+
+@attention
+ @parblock
+ An attention block with more than one paragraph:
+
+ @code
+ some_code(23)
+ @endcode
+
+ Elit dolore pariatur ex anim officia cupidatat adipisicing mollit
+ incididunt irure anim nostrud.
+ @endparblock
+
+@param[in] param
+ Description of this parameter.
+@param[in] other_param
+ @parblock
+ Description of this other parameter. Nulla consequat tempus libero,
+ sed finibus velit.
+
+ Offal actually vinyl taiyaki kickstarter etsy.
+ @endparblock
+@param[out] out_param
+ <strong>On success</strong>, \lt_p{*out_param} contains to something
+ useful.
+
+@retval #LTTNG_SOME_STATUS_OK
+ Success.
+@retval #LTTNG_SOME_STATUS_MEMORY_ERROR
+ Out of memory.
+@retval #LTTNG_SOME_STATUS_ERROR
+ @parblock
+ Longer description for this specific status.
+
+ Organic locavore sartorial 3 wolf moon brooklyn, VHS pug distillery
+ schlitz tofu banjo chambray you probably haven't heard of them hot
+ chicken copper mug.
+
+ Neutra kale chips kombucha, salvia green juice live-edge swag
+ biodiesel scenester austin yuccie dreamcatcher cronut small batch.
+ @endparblock
+
+@lt_pre_not_null{param}
+@lt_pre_not_null{other_param}
+@pre
+ \lt_p{param} is like this or like that.
+
+@post
+ \lt_p{other_param} is still in some state, and woke jean waistcoat.
+
+@sa lttng_some_other_function() --
+ Does something else with some parameter.
+@sa lttng_another_function() --
+ Cardigan celiac palo santo, tacos chicharrones pitchfork chambray
+ photo booth subway tile 90's street.
+*/
+----
+
+Parts:
+
+. **Opening Doxygen comment**.
++
+Use `+/*!+`.
+
+. **Brief description**.
++
+Use third person singular in the simple present tense: you're
+documenting what the function does. Assume that the sentence implicitly
+starts with "`This function`".
++
+Try to mention, briefly, all the parameters (with `\lt_p`) and what the
+function returns.
++
+End the sentence with a period.
+
+. **Detailed description**.
++
+Write complete sentences.
++
+Refer to parameters (with `\lt_p`) as much as possible.
++
+In general, keep paragraphs short: often, a single sentence is enough.
++
+Refer to the documented function with "`this function`".
++
+Write notes (`@note` command), remarks (`@remark` command), or
+attentions (`@attention` command) when needed. Most notes and remarks,
+however, can be simple paragraphs. Use `@parblock` end `@endparblock` to
+have more than one note/remark/warning paragraph.
+
+. **Parameter descriptions** (if any).
++
+Use the `@param[in]`, `@param[out]`, and `@param[in,out]` commands
+depending on the parameter direction.
++
+Document parameters in the declaration order.
++
+Refer to other parameters (with `\lt_p`) when useful for the reader.
++
+End each description with a period.
++
+Use `@parblock` end `@endparblock` to have more than one paragraph for a
+given parameter description.
++
+Make sure there's no blank line, except within a `@parblock` block,
+within the parameter description block so that Doxygen puts all the
+descriptions in the same section. For example, _don't_ write this:
++
+----
+@param[in] hexagon
+ Ugh literally +1 aesthetic, fashion axe try-hard mixtape pork belly
+ four loko.
+
+@param[in] selfies
+ Brooklyn ethical migas, viral edison bulb meggings butcher
+ flexitarian letterpress humblebrag kombucha pour-over etsy sriracha
+ blog.
+----
+
+. **Return value** (if any).
++
+If the function returns a status code::
+ Use the `@retval` command multiple times to document each relevant
+ status:
++
+----
+@retval #LTTNG_SOME_STATUS_OK
+ Success.
+@retval #LTTNG_SOME_STATUS_SOME_ERROR
+ Some error.
+----
++
+End each description with a period.
++
+Use `@parblock` and `@endparblock` to have more than one paragraph for a
+given return value description.
++
+Make sure there's no blank line, except within a `@parblock` block,
+within the return value description block so that Doxygen puts all the
+descriptions in the same section. For example, _don't_ write this:
++
+----
+@retval #LTTNG_SOME_STATUS_OK
+ Success.
+
+@retval #LTTNG_SOME_STATUS_SOME_ERROR
+ Some error.
+----
+
+If the function returns a simple value::
+ Use the `@returns` command to document it.
++
+Refer to parameters (with `\lt_p`) when useful for the reader.
++
+End the description with a period.
+
+. **Preconditions** (if any).
++
+List all the function's preconditions with the `@pre` command or any
+alias which starts with `@lt_pre` (see `Doxyfile.in`).
++
+Use the simple present tense.
++
+Do not write the word "`must`" as a precondition is already a
+requirement.
++
+End the description with a period.
++
+Make sure there's no blank line within the precondition description
+block so that Doxygen puts all the descriptions in the same section. For
+example, _don't_ write this:
++
+----
+@lt_pre_not_null{param}
+
+@pre
+ \lt_p{param} is like this or like that.
+----
+
+. **Postconditions** (if any).
++
+List all the function's _relevant_ postconditions with the `@post`
+command or any alias which starts with `@lt_post` (see `Doxyfile.in`).
++
+Anything that the body of the function documentation describes and which
+forms the nature of the function doesn't need to be written as an
+explicit postcondition. For example, if a function adds some
+object{nbsp}A to some object{nbsp}B, don't write the postcondition
+"`B{nbsp}contains{nbsp}A`".
++
+Use the simple present tense.
++
+End the description with a period.
++
+Make sure there's no blank line within the postcondition description
+block so that Doxygen puts all the descriptions in the same section. For
+example, _don't_ write this:
++
+----
+@post
+ The returned pointer is blue.
+
+@post
+ \lt_p{other_param} is still in some state, and woke jean waistcoat.
+----
+
+. **Items to see also** (if any).
++
+Use the `@sa` command, multiple times if needed, to refer to related
+functions or types.
++
+This is a way for you to inform the reader about other existing, related
+items. Keep in mind that the reader doesn't always know where to look
+for things.
++
+In the brief description of the referred item, _don't_ mention its
+parameters, if any.
++
+End each brief description with a period.
++
+Make sure there's no blank line within the item description block so
+that Doxygen puts all the descriptions in the same section. For example,
+_don't_ write this:
++
+----
+@sa lttng_some_other_function() --
+ Does something else with a parameter.
+
+@sa lttng_another_function() --
+ Cardigan celiac palo santo, tacos chicharrones pitchfork chambray
+ photo booth subway tile 90's street.
+----
+
+
+== Writing style
+
+The ultimate goal of the LTTng-tools C{nbsp}API documentation is to make
+the layman write code using this API as fast and correct as possible
+without having to ask for help. For this purpose, the documentation must
+be as clear as possible, just like the function and type names try to
+be.
+
+Don't hesitate to repeat technical terms, even in the same sentence, if
+needed. For example, if you document an "`event rule`", then always use
+the term "`event rule`" in the documentation, not "`event`", nor
+"`rule`", since they are ambiguous.
+
+You can use light emphasis to show the importance of a part of the text
+with the `\em` command (one word) or by surrounding the text to
+emphasize with `<em>` and `</em>`. Likewise, you can use strong emphasis
+when needed with the `\b` command (one word) or with `<strong>` and
+`</strong>`. In general, prefer light emphasis to strong emphasis, and
+use it economically.
+
+Links to other parts of the documentation are very important. Consider
+that the reader never knows that other functions exist other than the
+one she's reading. Use as many internal links as possible. Use the
+following forms of links:
+
+`__func__()`::
+ Automatic link to the function or macro named `__func__`.
+
+`#__name__`::
+ Automatic link to the type or enumerator named `__name__`.
+
+`\ref __ref__`::
+ Link to `__ref__` (page name, group name, function or macro name,
+ type name, variable name, etc.) using its default text.
+
+`\ref __ref__ "__some text__"`::
+ Link to `__ref__` (page name, group name, function or macro name,
+ type name, variable name, etc.) using the text `__some text__`.
+
+See Doxygen's "`http://www.doxygen.nl/manual/autolink.html[Automatic
+link generation]`" page for other ways to create automatic links.
+
+Follow, as much as possible, the
+https://docs.microsoft.com/en-ca/style-guide/welcome/[Microsoft Style
+Guide] when you document the API. This includes:
+
+* Use an active voice.
+* Use a gender-neutral language.
+* Use the present tense (you almost never need the future tense).
+* Address your reader directly (use "`you`").
+* Use contractions ("`it's`", "`you're`", "`don't`", and the rest).
+* Avoid anthropomorphism.
+* Ensure parallelism in lists, procedures, and sentences.
+* Terminate list items with a period, except when the list only contains
+ very short items.
+* Do not use Latin abbreviations.
+* Use "`and`" or "`or`" instead of a slash.
+* Avoid using negatives.
+* Avoid using "`should`": most of the time, you mean "`must`", and
+ that's very clear for the reader.
--- /dev/null
+DOXYFILE_ENCODING = UTF-8
+PROJECT_NAME = "LTTng control library C API"
+PROJECT_NUMBER = @PACKAGE_VERSION@
+CREATE_SUBDIRS = NO
+ALLOW_UNICODE_NAMES = NO
+OUTPUT_LANGUAGE = English
+BRIEF_MEMBER_DESC = YES
+REPEAT_BRIEF = YES
+ALWAYS_DETAILED_SEC = NO
+INLINE_INHERITED_MEMB = NO
+FULL_PATH_NAMES = YES
+STRIP_FROM_PATH = "@top_srcdir@/include"
+STRIP_FROM_INC_PATH =
+SHORT_NAMES = NO
+JAVADOC_AUTOBRIEF = NO
+QT_AUTOBRIEF = NO
+MULTILINE_CPP_IS_BRIEF = YES
+INHERIT_DOCS = YES
+SEPARATE_MEMBER_PAGES = NO
+TAB_SIZE = 4
+ALIASES =
+
+# Aliases: general
+ALIASES += lt_version="@PACKAGE_VERSION@"
+ALIASES += lt_version_maj_min="@MAJOR_VERSION@.@MINOR_VERSION@"
+ALIASES += lt_api="LTTng control library C API"
+ALIASES += lt_p{1}="<code class=\"lt-param\">\1</code>"
+ALIASES += lt_var{1}="<strong class=\"lt-var\">\1</strong>"
+ALIASES += lt_dt_opt="<strong><em>Optional</em></strong>:"
+ALIASES += lt_man_nl{2}="<code><strong>\1</strong>(\2)</code>"
+ALIASES += lt_man{2}="<a href=\"https://lttng.org/man/\2/\1/v\lt_version_maj_min/\">\lt_man_nl{\1,\2}</a>"
+ALIASES += lt_man_gen{2}="<a href=\"https://man7.org/linux/man-pages/man\2/\1.\2.html\">\lt_man_nl{\1,\2}</a>"
+ALIASES += lt_voidp="<code>void *</code>"
+
+# Aliases: preconditions
+ALIASES += lt_pre_not_null{1}="@pre \lt_p{\1} is \em not \c NULL."
+ALIASES += lt_pre_valid_c_str{1}="@pre \lt_p{\1} is a valid (null-terminated) C string."
+ALIASES += lt_pre_sess_exists{1}="@pre \lt_p{\1} names an accessible \ref api_session \"recording session\" within the \ref api-gen-sessiond-conn \"connected session daemon\"."
+ALIASES += lt_pre_sess_never_active{1}="@pre \lt_p{\1} names a \ref api_session \"recording session\" which never became \link lttng_session::enabled active\endlink (started) since its creation."
+ALIASES += lt_pre_sess_active{1}="@pre \lt_p{\1} names an \link lttng_session::enabled active\endlink (started) \ref api_session \"recording session\"."
+ALIASES += lt_pre_sess_inactive{1}="@pre \lt_p{\1} names an \link lttng_session::enabled inactive\endlink (stopped) \ref api_session \"recording session\"."
+ALIASES += lt_pre_sess_name_not_auto{1}="@pre \lt_p{\1} is not \c auto."
+ALIASES += lt_pre_conn="@pre liblttng-ctl can \ref api-gen-sessiond-conn \"connect to a session daemon\"."
+ALIASES += lt_pre_has_type{2}="@pre \lt_p{\1} has the type #\2."
+
+# Aliases: default values
+ALIASES += lt_def_net_ctrl_port="@DEFAULT_NETWORK_CONTROL_PORT@"
+ALIASES += lt_def_net_data_port="@DEFAULT_NETWORK_DATA_PORT@"
+ALIASES += lt_def_net_ctrl_url="<code>net://127.0.0.1:@DEFAULT_NETWORK_CONTROL_PORT@</code>"
+ALIASES += lt_def_net_data_url="<code>net://127.0.0.1:@DEFAULT_NETWORK_DATA_PORT@</code>"
+ALIASES += lt_def_net_url="<code>net://127.0.0.1:@DEFAULT_NETWORK_CONTROL_PORT@:@DEFAULT_NETWORK_DATA_PORT@</code>"
+
+# Aliases: object names
+ALIASES += lt_obj_session="\ref api_session \"recording session\""
+ALIASES += lt_obj_c_session="\ref api_session \"Recording session\""
+ALIASES += lt_obj_session_descr="\ref api_session_descr \"recording session descriptor\""
+ALIASES += lt_obj_c_session_descr="\ref api_session_descr \"Recording session descriptor\""
+ALIASES += lt_obj_domain="\ref api-channel-domain \"tracing domain\""
+ALIASES += lt_obj_domains="\ref api-channel-domain \"tracing domains\""
+ALIASES += lt_obj_c_domain="\ref api-channel-domain \"Tracing domain\""
+ALIASES += lt_obj_channel="\ref api-channel-channel \"channel\""
+ALIASES += lt_obj_channels="\ref api-channel-channel \"channels\""
+ALIASES += lt_obj_c_channel="\ref api-channel-channel \"Channel\""
+ALIASES += lt_obj_rer="\ref api_rer \"recording event rule\""
+ALIASES += lt_obj_rers="\ref api_rer \"recording event rules\""
+ALIASES += lt_obj_c_rer="\ref api_rer \"Recording event rule\""
+ALIASES += lt_obj_trigger="\ref api_trigger \"trigger\""
+ALIASES += lt_obj_triggers="\ref api_trigger \"triggers\""
+ALIASES += lt_obj_c_trigger="\ref api_trigger \"Trigger\""
+
+
+OPTIMIZE_OUTPUT_FOR_C = YES
+MARKDOWN_SUPPORT = NO
+TOC_INCLUDE_HEADINGS = 0
+AUTOLINK_SUPPORT = YES
+SUBGROUPING = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS = NO
+TYPEDEF_HIDES_STRUCT = NO
+LOOKUP_CACHE_SIZE = 0
+
+EXTRACT_ALL = NO
+EXTRACT_PRIVATE = NO
+EXTRACT_PACKAGE = NO
+EXTRACT_STATIC = YES
+EXTRACT_LOCAL_CLASSES = YES
+EXTRACT_LOCAL_METHODS = NO
+EXTRACT_ANON_NSPACES = NO
+HIDE_UNDOC_MEMBERS = YES
+HIDE_UNDOC_CLASSES = YES
+HIDE_FRIEND_COMPOUNDS = NO
+HIDE_IN_BODY_DOCS = YES
+INTERNAL_DOCS = NO
+CASE_SENSE_NAMES = NO
+HIDE_SCOPE_NAMES = NO
+HIDE_COMPOUND_REFERENCE = NO
+SHOW_INCLUDE_FILES = NO
+SHOW_GROUPED_MEMB_INC = NO
+FORCE_LOCAL_INCLUDES = NO
+INLINE_INFO = YES
+SORT_MEMBER_DOCS = YES
+SORT_BRIEF_DOCS = YES
+SORT_MEMBERS_CTORS_1ST = NO
+SORT_GROUP_NAMES = NO
+SORT_BY_SCOPE_NAME = NO
+STRICT_PROTO_MATCHING = NO
+GENERATE_TODOLIST = YES
+GENERATE_TESTLIST = YES
+GENERATE_BUGLIST = YES
+GENERATE_DEPRECATEDLIST = YES
+ENABLED_SECTIONS =
+MAX_INITIALIZER_LINES = 0
+SHOW_USED_FILES = NO
+SHOW_FILES = NO
+SHOW_NAMESPACES = NO
+FILE_VERSION_FILTER =
+LAYOUT_FILE = "@srcdir@/DoxygenLayout.xml"
+CITE_BIB_FILES =
+
+QUIET = NO
+WARNINGS = YES
+WARN_IF_UNDOCUMENTED = YES
+WARN_IF_DOC_ERROR = YES
+WARN_NO_PARAMDOC = YES
+WARN_AS_ERROR = NO
+WARN_FORMAT = "$file:$line: $text"
+WARN_LOGFILE =
+
+INPUT = "@srcdir@/dox/groups.dox" \
+ "@top_srcdir@/include/lttng/constant.h" \
+ "@top_srcdir@/include/lttng/handle.h" \
+ "@top_srcdir@/include/lttng/lttng.h" \
+ "@top_srcdir@/include/lttng/lttng-error.h" \
+ "@top_srcdir@/include/lttng/clear.h" \
+ "@top_srcdir@/include/lttng/clear-handle.h" \
+ "@top_srcdir@/include/lttng/session.h" \
+ "@top_srcdir@/include/lttng/session-descriptor.h" \
+ "@top_srcdir@/include/lttng/destruction-handle.h" \
+ "@top_srcdir@/include/lttng/domain.h" \
+ "@top_srcdir@/include/lttng/channel.h" \
+ "@top_srcdir@/include/lttng/event.h"
+INPUT_ENCODING = UTF-8
+FILE_PATTERNS = *.h *.dox
+RECURSIVE = NO
+EXCLUDE =
+EXCLUDE_SYMLINKS = NO
+EXCLUDE_PATTERNS =
+EXCLUDE_SYMBOLS =
+EXAMPLE_PATTERNS = *
+EXAMPLE_RECURSIVE = NO
+IMAGE_PATH = "@srcdir@/images"
+INPUT_FILTER =
+FILTER_PATTERNS =
+FILTER_SOURCE_FILES = NO
+FILTER_SOURCE_PATTERNS =
+USE_MDFILE_AS_MAINPAGE =
+
+SOURCE_BROWSER = NO
+INLINE_SOURCES = NO
+STRIP_CODE_COMMENTS = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION = NO
+REFERENCES_LINK_SOURCE = NO
+SOURCE_TOOLTIPS = YES
+USE_HTAGS = NO
+VERBATIM_HEADERS = YES
+
+ALPHABETICAL_INDEX = YES
+IGNORE_PREFIX =
+
+OUTPUT_DIRECTORY = @builddir@/output
+
+GENERATE_HTML = YES
+HTML_FILE_EXTENSION = .html
+HTML_HEADER =
+HTML_FOOTER =
+HTML_STYLESHEET =
+HTML_EXTRA_STYLESHEET = @srcdir@/style.css
+HTML_EXTRA_FILES =
+HTML_COLORSTYLE_HUE = 220
+HTML_COLORSTYLE_SAT = 100
+HTML_COLORSTYLE_GAMMA = 120
+HTML_TIMESTAMP = NO
+HTML_DYNAMIC_SECTIONS = NO
+HTML_DYNAMIC_MENUS = NO
+HTML_INDEX_NUM_ENTRIES = 100
+
+GENERATE_DOCSET = NO
+GENERATE_HTMLHELP = NO
+GENERATE_CHI = NO
+GENERATE_QHP = NO
+GENERATE_ECLIPSEHELP = NO
+
+DISABLE_INDEX = NO
+GENERATE_TREEVIEW = YES
+ENUM_VALUES_PER_LINE = 4
+TREEVIEW_WIDTH = 300
+EXT_LINKS_IN_WINDOW = NO
+FORMULA_FONTSIZE = 10
+FORMULA_TRANSPARENT = YES
+USE_MATHJAX = NO
+MATHJAX_FORMAT = HTML-CSS
+MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest
+MATHJAX_EXTENSIONS =
+MATHJAX_CODEFILE =
+SEARCHENGINE = YES
+SERVER_BASED_SEARCH = NO
+EXTERNAL_SEARCH = NO
+SEARCHENGINE_URL =
+SEARCHDATA_FILE = searchdata.xml
+EXTERNAL_SEARCH_ID =
+EXTRA_SEARCH_MAPPINGS =
+
+GENERATE_LATEX = NO
+GENERATE_RTF = NO
+GENERATE_MAN = NO
+GENERATE_XML = NO
+GENERATE_PERLMOD = NO
--- /dev/null
+<doxygenlayout version="1.0">
+ <navindex>
+ <tab type="mainpage" visible="yes" title="Bonjour!"/>
+ <tab type="pages" visible="yes" title="All pages" intro=""/>
+ <tab type="modules" visible="yes" title="API reference"
+ intro="List of all API reference modules:"/>
+ <tab type="classlist" visible="yes" title="Structures"/>
+ </navindex>
+
+ <group>
+ <detaileddescription/>
+ <briefdescription visible="no"/>
+ <memberdecl>
+ <nestedgroups visible="yes" title=""/>
+ <classes visible="yes" title=""/>
+ <typedefs title=""/>
+ <enums title=""/>
+ <enumvalues title=""/>
+ <defines title=""/>
+ <variables title=""/>
+ <functions title=""/>
+ <membergroups visible="yes"/>
+ </memberdecl>
+ <memberdef>
+ <pagedocs/>
+ <classes visible="yes" title=""/>
+ <typedefs title=""/>
+ <enums title=""/>
+ <enumvalues title=""/>
+ <defines title=""/>
+ <variables title=""/>
+ <functions title=""/>
+ </memberdef>
+ <authorsection visible="yes"/>
+ </group>
+
+ <directory>
+ <detaileddescription title=""/>
+ <briefdescription visible="no"/>
+ <directorygraph visible="yes"/>
+ <memberdecl>
+ <dirs visible="yes"/>
+ <files visible="yes"/>
+ </memberdecl>
+ </directory>
+</doxygenlayout>
--- /dev/null
+# SPDX-License-Identifier: GPL-2.0-only
+
+API_DOC_INSTALL_DIR = "$(DESTDIR)$(docdir)/api/liblttng-ctl"
+
+all-local: doxygen-doc
+
+install-data-local: doxygen-doc
+ $(mkdir_p) "$(API_DOC_INSTALL_DIR)"
+ cp -rv output/html "$(API_DOC_INSTALL_DIR)"
+
+@DX_RULES@
+
+MOSTLYCLEANFILES = $(DX_CLEANFILES)
+EXTRA_DIST = \
+ Doxyfile.in \
+ DoxygenLayout.xml \
+ style.css \
+ dox \
+ images
--- /dev/null
+/*!
+@mainpage Bonjour!
+
+Welcome to the <strong>\lt_api</strong> (liblttng-ctl) documentation!
+
+The
+<a href="https://lttng.org/"><em>Linux Trace Toolkit: next generation</em></a>
+is an open-source software package used for correlated tracing of the
+Linux kernel, user applications, and user libraries.
+
+liblttng-ctl, which is part of the LTTng-tools project, makes it
+possible to control <a href="https://lttng.org/">LTTng</a> tracing, but
+also to
+\ref api_trigger "receive notifications when specific events occur".
+
+<h2>Plumbing</h2>
+
+The following diagram shows the components of LTTng:
+
+@image html plumbing.png "Components of LTTng."
+
+As you can see, liblttng-ctl is a bridge between a user application
+and a session daemon (see \lt_man{lttng-sessiond,8} and
+\ref api-gen-sessiond-conn "Session daemon connection").
+
+The \lt_man{lttng,1} command-line tool which ships with LTTng-tools, for
+example, uses liblttng-ctl to perform its commands.
+
+See the
+<a href="https://lttng.org/docs/v\lt_version_maj_min/#doc-plumbing"><em>Components of LTTng</em></a>
+section of the LTTng Documentation to learn more.
+
+<h2>Contents</h2>
+
+This API documentation has three main modules:
+
+- The \ref api_session makes it possible to create, manipulate
+ (\ref api_session_snapshot "take a snapshot",
+ \ref api_session_rotation "rotate",
+ \ref api_session_clear "clear", and the rest), and destroy
+ <em>recording sessions</em>.
+
+ A recording session is a per-Unix user dialogue for everything related
+ to event recording.
+
+ A recording session owns \lt_obj_channels which
+ own \lt_obj_rers. Those objects constitute
+ the main configuration of a recording session.
+
+- The \ref api_inst_pt makes it possible to get details about the
+ available LTTng tracepoints, Java/Python loggers, and Linux kernel
+ system calls without needing any \lt_obj_session.
+
+- The \ref api_trigger makes it possible to create and register
+ <em>triggers</em>.
+
+ A trigger associates a condition to one or more actions: when the
+ condition of a trigger is satisfied, LTTng attempts to execute its
+ actions.
+
+ This API is fully decoupled from the \ref api_session.
+
+ Amongst the interesting available trigger conditions and actions
+ are the
+ \link #LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES <em>event rule matches</em>\endlink
+ condition and the
+ \link #LTTNG_ACTION_TYPE_NOTIFY <em>notify</em>\endlink
+ action. With those, your application can receive an asynchronous
+ message (a notification) when a specified event rule matches
+ an LTTng event.
+
+The three modules above often refer to the \ref api_gen which offers
+common enumerations, macros, and functions.
+
+See <a href="modules.html">API reference</a> for the complete table
+of contents.
+
+<h2>Build with liblttng-ctl</h2>
+
+To build an application with liblttng-ctl:
+
+<dl>
+ <dt>Header file
+ <dd>
+ Include <code>%lttng/lttng.h</code>:
+
+ @code
+ #include <lttng/lttng.h>
+ @endcode
+
+ With
+ <a href="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</a>,
+ get the required C flags with:
+
+ @code{.unparsed}
+ $ pkg-config --cflags lttng-ctl
+ @endcode
+
+ <dt>Linking
+ <dd>
+ Link your application with <code>liblttng-ctl</code>:
+
+ @code{.unparsed}
+ $ cc my-app.o ... -llttng-ctl
+ @endcode
+
+ With pkg-config, get the required linker options with:
+
+ @code{.unparsed}
+ $ pkg-config --libs lttng-ctl
+ @endcode
+</dl>
+
+@defgroup api_gen General API
+
+The general \lt_api offers:
+
+- \ref lttng_error_code "Error code enumerators" and lttng_strerror().
+
+- \ref api-gen-sessiond-conn "Session daemon connection" functions:
+
+ - lttng_session_daemon_alive()
+ - lttng_set_tracing_group()
+
+<h1>\anchor api-gen-sessiond-conn Session daemon connection</h1>
+
+Many functions of the \lt_api require a connection to a listening LTTng
+session daemon (see \lt_man{lttng-sessiond,8}) to control LTTng tracing.
+
+liblttng-ctl connects to a session daemon through a Unix domain socket
+when you call some of its public functions, \em not when it loads.
+
+Each Unix user may have its own independent running session daemon.
+However, liblttng-ctl must connect to the session daemon of the
+\c root user (the root session daemon) to control Linux kernel tracing.
+
+How liblttng-ctl chooses which session daemon to connect to is as
+follows, considering \lt_var{U} is the Unix user of the process running
+liblttng-ctl:
+
+<dl>
+ <dt>\lt_var{U} is \c root
+ <dd>Connect to the root session daemon.
+
+ <dt>\lt_var{U} is not \c root
+ <dd>
+ <dl>
+ <dt>If \lt_var{U} is part of the current liblttng-ctl Unix <em>tracing group</em>
+ <dd>
+ Try to connect to the root session daemon.
+
+ If the root session daemon isn't running, connect to the
+ session daemon of \lt_var{U}.
+
+ <dt>If \lt_var{U} is not part of the tracing group
+ <dd>
+ Connect to the session daemon of \lt_var{U}.
+ </dl>
+</dl>
+
+The Unix tracing group of the root session daemon is one of:
+
+<dl>
+ <dt>
+ With the <code>\--group=<em>GROUP</em></code> option of the root
+ session daemon
+ <dd>
+ Exactly <code><em>GROUP</em></code>.
+
+ In that case, you must call lttng_set_tracing_group(), passing
+ exactly <code><em>GROUP</em></code>, \em before you call a
+ liblttng-ctl function which needs to connect to a session daemon.
+
+ <dt>
+ Without the <code>\--group</code> option of the root
+ session daemon
+ <dd>
+ Exactly \c tracing (also the default Unix tracing group of
+ liblttng-ctl, therefore you don't need to call
+ lttng_set_tracing_group()).
+</dl>
+
+Check that your application can successfully connect to a session daemon
+with lttng_session_daemon_alive().
+
+LTTng-instrumented user applications automatically register to both the
+root and user session daemons. This makes it possible for both session
+daemons to list the available instrumented applications and their
+\ref api_inst_pt "instrumentation points".
+
+@defgroup api_session Recording session API
+
+A <strong><em>recording session</em></strong> is a stateful dialogue
+between an application and a session daemon for everything related to
+event recording.
+
+Everything that you do when you control LTTng tracers to record events
+happens within a recording session. In particular, a recording session:
+
+- Has its own name, unique for a given session daemon.
+
+- Has its own set of trace files, if any.
+
+- Has its own state of
+ \link lttng_session::enabled activity\endlink (started or stopped).
+
+ An active recording session is an implicit
+ \lt_obj_rer condition.
+
+- Has its own \ref api-session-modes "mode"
+ (local, network streaming, snapshot, or live).
+
+- Has its own \lt_obj_channels to which are attached
+ their own recording event rules.
+
+- Has its own \ref api_pais "process attribute inclusion sets".
+
+Those attributes and objects are completely isolated between different
+recording sessions.
+
+A recording session is like an
+<a href="https://en.wikipedia.org/wiki/Automated_teller_machine">ATM</a>
+session: the operations you do on the
+banking system through the ATM don't alter the data of other users of
+the same system. In the case of the ATM, a session lasts as long as your
+bank card is inside. In the case of LTTng, a recording session lasts
+from a call to lttng_create_session_ext() to the completion of its
+destruction operation (which you can initiate with
+lttng_destroy_session_ext()).
+
+A recording session belongs to a session daemon (see
+\lt_man{lttng-sessiond,8} and
+\ref api-gen-sessiond-conn "Session daemon connection"). For a given
+session daemon, each Unix user has its own, private recording sessions.
+Note, however, that the \c root Unix user may operate on or destroy
+another user's recording session.
+
+@image html many-sessions.png "Each Unix user has its own, private recording sessions."
+
+@sa The <em>RECORDING SESSION</em> section of \lt_man{lttng-concepts,7}.
+
+<h1>Operations</h1>
+
+The recording session operations are:
+
+<table>
+ <tr>
+ <th>Operation
+ <th>Means
+ <tr>
+ <td>Creation
+ <td>
+ -# Create a \lt_obj_session_descr
+ with one of the dedicated creation functions depending on the
+ \ref api-session-modes "recording session mode".
+
+ -# Call lttng_create_session_ext(), passing the recording session
+ descriptor of step 1.
+
+ -# When you're done with the recording session descriptor, destroy
+ it with lttng_session_descriptor_destroy().
+
+ @sa \lt_man{lttng-create,1}
+ <tr>
+ <td>Destruction
+ <td>
+ -# Call lttng_destroy_session_ext(), passing the name of the
+ recording session to destroy.
+
+ This function initiates a destruction operation, returning
+ immediately.
+
+ This function can set a pointer to a
+ \ref api_session_destr_handle "destruction handle"
+ (#lttng_destruction_handle) so that you can wait for the
+ completion of the operation. Without such a handle, you can't
+ know when the destruction operation completes and whether or
+ not it does successfully.
+
+ -# <strong>If you have a destruction handle from
+ step 1</strong>:
+
+ -# Call lttng_destruction_handle_wait_for_completion() to wait
+ for the completion of the destruction operation.
+
+ -# Call lttng_destruction_handle_get_result() to get whether or
+ not the destruction operation successfully completed.
+
+ You can also call
+ lttng_destruction_handle_get_rotation_state() and
+ lttng_destruction_handle_get_archive_location() at this
+ point.
+
+ -# Destroy the destruction handle with
+ lttng_destruction_handle_destroy().
+
+ @sa \lt_man{lttng-destroy,1}
+ <tr>
+ <td>Basic property access
+ <td>
+ See:
+
+ - The members of #lttng_session
+ - lttng_session_descriptor_get_session_name()
+ - lttng_session_get_creation_time()
+ - lttng_set_session_shm_path()
+ - lttng_data_pending()
+ <tr>
+ <td>\lt_obj_c_domain access
+ <td>
+ -# Call lttng_list_domains(), passing the name of the recording
+ session of which to get the tracing domains.
+
+ This function sets a pointer to an array of
+ \link #lttng_domain tracing domain summaries\endlink
+ and returns the number of entries.
+
+ -# Access the properties of each tracing domain summary through
+ structure members.
+
+ -# When you're done with the array of tracing domain summaries,
+ free it with <code>free()</code>.
+ <tr>
+ <td>\lt_obj_c_channel access
+ <td>
+ -# Create a \link #lttng_handle recording session handle\endlink
+ with lttng_create_handle() to specify the name of the
+ recording session and the summary of the
+ \lt_obj_domain of the channels to access.
+
+ -# Call lttng_list_channels(), passing the recording session
+ handle of step 1.
+
+ This function sets a pointer to an array of
+ \link #lttng_channel channel summaries\endlink
+ and returns the number of entries.
+
+ -# Destroy the recording session handle of step 1 with
+ lttng_destroy_handle().
+
+ -# Access the \ref api-channel-channel-props "properties" of each
+ channel summary through structure members or using dedicated
+ getters.
+
+ -# When you're done with the array of channel summaries,
+ free it with <code>free()</code>.
+ <tr>
+ <td>Activity control
+ <td>
+ See:
+
+ - lttng_start_tracing()
+ - lttng_stop_tracing()
+ - lttng_stop_tracing_no_wait()
+
+ The #LTTNG_ACTION_TYPE_START_SESSION and
+ #LTTNG_ACTION_TYPE_STOP_SESSION trigger actions can also
+ activate and deactivate a recording session.
+ <tr>
+ <td>Listing
+ <td>
+ -# Call lttng_list_sessions().
+
+ This function sets a pointer to an array of
+ \link #lttng_session recording session summaries\endlink
+ and returns the number of entries.
+
+ -# Access the properties of each recording session summary through
+ structure members or using dedicated getters.
+
+ -# When you're done with the array of recording session summaries,
+ free it with <code>free()</code>.
+
+ @sa \lt_man{lttng-list,1}
+ <tr>
+ <td>Process attribute inclusion set access
+ <td>See \ref api_pais
+ <tr>
+ <td>Clearing
+ <td>See \ref api_session_clear
+ <tr>
+ <td>Snapshot recording
+ <td>
+ See \ref api_session_snapshot
+
+ The #LTTNG_ACTION_TYPE_SNAPSHOT_SESSION trigger action can also
+ take a recording session snapshot.
+ <tr>
+ <td>Rotation
+ <td>
+ See \ref api_session_rotation
+
+ The #LTTNG_ACTION_TYPE_ROTATE_SESSION trigger action can also
+ rotate a recording session.
+ <tr>
+ <td>Saving and loading
+ <td>See \ref api_session_save_load
+ <tr>
+ <td>Trace data regeneration
+ <td>
+ See:
+
+ - lttng_regenerate_metadata()
+ - lttng_regenerate_statedump()
+
+ @sa \lt_man{lttng-regenerate,1}
+</table>
+
+<h1>\anchor api-session-modes Recording session modes</h1>
+
+LTTng offers four <strong><em>recording session modes</em></strong>:
+
+<table>
+ <tr>
+ <th>Mode
+ <th>Description
+ <th>Descriptor creation function(s)
+ <tr>
+ <td>\anchor api-session-local-mode Local
+ <td>
+ Write the trace data to the local file system, or do not write any
+ trace data.
+ <td>
+ - lttng_session_descriptor_create()
+ - lttng_session_descriptor_local_create()
+ <tr>
+ <td>\anchor api-session-net-mode Network streaming
+ <td>
+ Send the trace data over the network to a listening relay daemon
+ (see \lt_man{lttng-relayd,8}).
+ <td>lttng_session_descriptor_network_create()
+ <tr>
+ <td>\anchor api-session-snapshot-mode Snapshot
+ <td>
+ Only write the trace data to the local file system or send it to a
+ listening relay daemon when LTTng
+ takes a \ref api_session_snapshot "snapshot".
+
+ LTTng takes a snapshot of such a recording session when:
+
+ - You call lttng_snapshot_record().
+
+ - LTTng executes an #LTTNG_ACTION_TYPE_SNAPSHOT_SESSION trigger
+ action.
+
+ LTTng forces the
+ \ref api-channel-er-loss-mode "event record loss mode" of all
+ the channels of such a recording session to be
+ \"\ref api-channel-overwrite-mode "overwrite"\".
+ <td>
+ - lttng_session_descriptor_snapshot_create()
+ - lttng_session_descriptor_snapshot_local_create()
+ - lttng_session_descriptor_snapshot_network_create()
+ <tr>
+ <td>\anchor api-session-live-mode Live
+ <td>
+ Send the trace data over the network to a listening relay daemon
+ for live reading.
+
+ An LTTng live reader (for example,
+ <a href="https://babeltrace.org/">Babeltrace 2</a>) can
+ connect to the same relay daemon to receive trace data while the
+ recording session is active.
+ <td>
+ lttng_session_descriptor_live_network_create()
+</table>
+
+@sa The <em>Recording session modes</em> section of
+\lt_man{lttng-concepts,7}.
+
+<h1>\anchor api-session-url Output URL format</h1>
+
+Some functions of the \lt_api require an <strong><em>output
+URL</em></strong>.
+
+An output URL is a C string which specifies where to send trace
+data and, when LTTng connects to a relay daemon (see
+\lt_man{lttng-relayd,8}), control commands.
+
+There are three available output URL formats:
+
+<table>
+ <tr>
+ <th>Type
+ <th>Description
+ <th>Format
+ <tr>
+ <td>\anchor api-session-local-url Local
+ <td>
+ Send trace data to the local file system, without connecting to a
+ relay daemon.
+
+ Accepted by:
+
+ - lttng_create_session() (deprecated)
+ - lttng_create_session_snapshot() (deprecated)
+ - lttng_snapshot_output_set_local_path()
+ - lttng_save_session_attr_set_output_url()
+ - lttng_load_session_attr_set_input_url()
+ - lttng_load_session_attr_set_override_url()
+ <td>
+ <code>file://<em>TRACEDIR</em></code>
+
+ <dl>
+ <dt><code><em>TRACEDIR</em></code>
+ <dd>
+ Absolute path to the directory containing the trace data on
+ the local file system.
+ </dl>
+ <tr>
+ <td>\anchor api-session-one-port-url Remote: single port
+ <td>
+ Send trace data and/or control commands to a specific relay daemon
+ with a specific TCP port.
+
+ Accepted by:
+
+ - lttng_session_descriptor_network_create()
+ - lttng_session_descriptor_snapshot_network_create()
+ - lttng_session_descriptor_live_network_create()
+ - lttng_snapshot_output_set_network_urls()
+ - lttng_snapshot_output_set_ctrl_url()
+ - lttng_snapshot_output_set_data_url()
+ - lttng_load_session_attr_set_override_ctrl_url()
+ - lttng_load_session_attr_set_override_data_url()
+ <td>
+ <code><em>PROTO</em>://<em>HOST</em></code>[<code>:<em>PORT</em></code>][<code>/<em>TRACEDIR</em></code>]
+
+ <dl>
+ <dt><code><em>PROTO</em></code>
+ <dd>
+ Network protocol, amongst:
+
+ <dl>
+ <dt>\c net
+ <dd>
+ TCP over IPv4.
+
+ <dt>\c net6
+ <dd>
+ TCP over IPv6.
+
+ <dt>\c tcp
+ <dd>
+ Same as <code>net</code>.
+
+ <dt>\c tcp6
+ <dd>
+ Same as <code>net6</code>.
+ </dl>
+
+ <dt><code><em>HOST</em></code>
+ <dd>
+ Hostname or IP address.
+
+ An IPv6 address must be enclosed in square brackets (<code>[</code>
+ and <code>]</code>); see
+ <a href="https://www.ietf.org/rfc/rfc2732.txt">RFC 2732</a>.
+
+ <dt><code><em>PORT</em></code>
+ <dd>
+ TCP port.
+
+ If it's missing, the default control and data ports are
+ respectively \lt_def_net_ctrl_port and
+ \lt_def_net_data_port.
+
+ <dt><code><em>TRACEDIR</em></code>
+ <dd>
+ Path of the directory containing the trace data on the remote
+ file system.
+
+ This path is relative to the base output directory of the
+ LTTng relay daemon (see the <em>Output directory</em>
+ section of \lt_man{lttng-relayd,8}).
+ </dl>
+ <tr>
+ <td>\anchor api-session-two-port-url Remote: control and data ports
+ <td>
+ Send trace data and control commands to a specific relay daemon
+ with specific TCP ports.
+
+ This form is usually a shorthand for two
+ \ref api-session-one-port-url "single-port output URLs" with
+ specified ports.
+
+ Accepted by:
+
+ - lttng_create_session_snapshot() (deprecated)
+ - lttng_create_session_live() (deprecated)
+ - lttng_session_descriptor_network_create()
+ - lttng_session_descriptor_snapshot_network_create()
+ - lttng_session_descriptor_live_network_create()
+ - lttng_snapshot_output_set_network_url()
+ - lttng_snapshot_output_set_network_urls()
+ - lttng_snapshot_output_set_ctrl_url()
+ - lttng_load_session_attr_set_override_url()
+ - lttng_load_session_attr_set_override_ctrl_url()
+ <td>
+ <code><em>PROTO</em>://<em>HOST</em>:<em>CTRLPORT</em>:<em>DATAPORT</em></code>[<code>/<em>TRACEDIR</em></code>]
+
+ <dl>
+ <dt><code><em>PROTO</em></code>
+ <dd>
+ Network protocol, amongst:
+
+ <dl>
+ <dt>\c net
+ <dd>
+ TCP over IPv4.
+
+ <dt>\c net6
+ <dd>
+ TCP over IPv6.
+
+ <dt>\c tcp
+ <dd>
+ Same as <code>net</code>.
+
+ <dt>\c tcp6
+ <dd>
+ Same as <code>net6</code>.
+ </dl>
+
+ <dt><code><em>HOST</em></code>
+ <dd>
+ Hostname or IP address.
+
+ An IPv6 address must be enclosed in square brackets (<code>[</code>
+ and <code>]</code>); see
+ <a href="https://www.ietf.org/rfc/rfc2732.txt">RFC 2732</a>.
+
+ <dt><code><em>CTRLPORT</em></code>
+ <dd>
+ Control TCP port.
+
+ <dt><code><em>DATAPORT</em></code>
+ <dd>
+ Trace data TCP port.
+
+ <dt><code><em>TRACEDIR</em></code>
+ <dd>
+ Path of the directory containing the trace data on the remote
+ file system.
+
+ This path is relative to the base output directory of the
+ LTTng relay daemon (see the <code>\--output</code> option of
+ \lt_man{lttng-relayd,8}).
+ </dl>
+</table>
+
+@defgroup api_session_descr Recording session descriptor API
+@ingroup api_session
+
+A <strong><em>recording session descriptor</em></strong> describes the
+properties of a \lt_obj_session to be (not created
+yet).
+
+To create a recording session from a recording session descriptor:
+
+-# Create a recording session descriptor
+ with one of the dedicated creation functions, depending on the
+ \ref api-session-modes "recording session mode":
+
+ <dl>
+ <dt>\ref api-session-local-mode "Local mode"
+ <dd>
+ One of:
+
+ - lttng_session_descriptor_create()
+ - lttng_session_descriptor_local_create()
+
+ <dt>\ref api-session-net-mode "Network streaming mode"
+ <dd>
+ lttng_session_descriptor_network_create()
+
+ <dt>\ref api-session-snapshot-mode "Snapshot mode"
+ <dd>
+ One of:
+
+ - lttng_session_descriptor_snapshot_create()
+ - lttng_session_descriptor_snapshot_local_create()
+ - lttng_session_descriptor_snapshot_network_create()
+
+ <dt>\ref api-session-live-mode "Live mode"
+ <dd>
+ lttng_session_descriptor_live_network_create()
+ </dl>
+
+-# Call lttng_create_session_ext(), passing the recording session
+ descriptor of step 1.
+
+ After a successful call to this function, you can call
+ lttng_session_descriptor_get_session_name() to get the name of the
+ created recording session (set when creating the descriptor or
+ automatically generated).
+
+-# When you're done with the recording session descriptor, destroy
+ it with lttng_session_descriptor_destroy().
+
+@defgroup api_session_destr_handle Recording session destruction handle API
+@ingroup api_session
+
+A <strong><em>recording session destruction handle</em></strong>
+represents a \lt_obj_session destruction operation.
+
+The main purposes of a recording session destruction handle is to:
+
+- Wait for the completion of the recording session
+ destruction operation with
+ lttng_destruction_handle_wait_for_completion() and get whether or not
+ it was successful with lttng_destruction_handle_get_result().
+
+- Get the state of any
+ \ref api_session_rotation "recording session rotation"
+ which the recording session destruction operation caused
+ with lttng_destruction_handle_get_rotation_state(), and the location
+ of its trace chunk archive with
+ lttng_destruction_handle_get_archive_location().
+
+To destroy a recording session:
+
+-# Call lttng_destroy_session_ext(), passing the name of the recording
+ session to destroy.
+
+ This function initiates a destruction operation, returning
+ immediately.
+
+ This function can set a pointer to a
+ \link #lttng_destruction_handle destruction handle\endlink so that
+ you can wait for the completion of the operation. Without such a
+ handle, you can't know when the destruction operation completes and
+ whether or not it does successfully.
+
+-# Call lttng_destruction_handle_wait_for_completion() to wait
+ for the completion of the destruction operation.
+
+-# Call lttng_destruction_handle_get_result() to get whether or
+ not the destruction operation successfully completed.
+
+-# <strong>If LTTng performed at least one
+ \ref api_session_rotation "rotation" of the destroyed recording
+ session</strong>, call lttng_destruction_handle_get_rotation_state()
+ to know whether or not the last rotation was successful and
+ lttng_destruction_handle_get_archive_location() to get the location
+ of its trace chunk archive.
+
+-# Destroy the destruction handle with
+ lttng_destruction_handle_destroy().
+
+@defgroup api_channel Domain and channel API
+@ingroup api_session
+
+<h1>\anchor api-channel-domain Tracing domain</h1>
+
+A <strong><em>tracing domain</em></strong> identifies a type of LTTng
+tracer.
+
+A tracing domain has its own properties and features.
+
+There are currently five available tracing domains:
+
+<table>
+ <tr>
+ <th>Domain name
+ <th>Type enumerator
+ <tr>
+ <td>Linux kernel
+ <td>#LTTNG_DOMAIN_KERNEL
+ <tr>
+ <td>User space
+ <td>#LTTNG_DOMAIN_UST
+ <tr>
+ <td><a href="https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html"><code>java.util.logging</code></a> (JUL)
+ <td>#LTTNG_DOMAIN_JUL
+ <tr>
+ <td><a href="https://logging.apache.org/log4j/1.2/">Apache log4j</a>
+ <td>#LTTNG_DOMAIN_LOG4J
+ <tr>
+ <td><a href="https://docs.python.org/3/library/logging.html">Python logging</a>
+ <td>#LTTNG_DOMAIN_PYTHON
+</table>
+
+A \lt_obj_channel is always part of a tracing domain.
+
+Many liblttng-ctl functions require a tracing domain type (sometimes
+within a
+\link #lttng_handle recording session handle\endlink)
+to target specific tracers or to avoid ambiguity. For example, because
+the Linux kernel and user space tracing domains support named
+tracepoints as \ref api_inst_pt "instrumentation points", you need to
+specify a tracing domain when you create a
+\lt_obj_rer with lttng_enable_event_with_exclusions() because both
+tracing domains could have LTTng tracepoints sharing the same name.
+
+@sa The <em>TRACING DOMAIN</em> section of \lt_man{lttng-concepts,7}.
+
+<h1>\anchor api-channel-channel Channel</h1>
+
+A <strong><em>channel</em></strong> is an object which is responsible
+for a set of ring buffers.
+
+Each ring buffer is divided into multiple <em>sub-buffers</em>. When a
+\lt_obj_rer matches an event, LTTng can record it to one or more
+sub-buffers of one or more channels.
+
+A channel is always associated to a \lt_obj_domain.
+The \link #LTTNG_DOMAIN_JUL <code>java.util.logging</code>\endlink,
+\link #LTTNG_DOMAIN_LOG4J Apache log4j\endlink, and
+\link #LTTNG_DOMAIN_PYTHON Python\endlink tracing
+domains each have a default channel which you can't configure.
+
+Note that the some functions, like lttng_enable_event_with_exclusions(),
+can automatically create a default channel with sane defaults when no
+channel exists for the provided \lt_obj_domain.
+
+A channel owns \lt_obj_rers.
+
+@image html concepts.png "A recording session contains channels that are members of tracing domains and contain recording event rules."
+
+You can't destroy a channel.
+
+<h2>Operations</h2>
+
+The channel operations are:
+
+<table>
+ <tr>
+ <th>Operation
+ <th>Means
+ <tr>
+ <td>Creation
+ <td>
+ -# Call lttng_channel_create() with a \lt_obj_domain summary to
+ create an initial channel summary.
+
+ This function calls lttng_channel_set_default_attr() to set
+ the properties of the created channel summary to default values
+ depending on the tracing domain summary.
+
+ -# Set the properties of the channel summary of step 1
+ through direct members or with dedicated setters.
+
+ See the property table below.
+
+ -# Create a \link #lttng_handle recording session handle\endlink
+ structure to specify the name of the recording session and the
+ tracing domain of the channel to create.
+
+ -# Call lttng_enable_channel() with the recording session handle
+ of step 3 and the channel summary of step 1
+ o create the channel.
+
+ -# Destroy the recording session handle with
+ lttng_destroy_handle() and the channel summary with
+ lttng_channel_destroy().
+
+ @sa \lt_man{lttng-enable-channel,1}
+ <tr>
+ <td>Basic property access
+ <td>
+ See the \ref api-channel-channel-props "property table" below.
+ <tr>
+ <td>\lt_obj_c_rer access
+ <td>
+ -# Create a \link #lttng_handle recording session handle\endlink
+ with lttng_create_handle() to specify the name of the
+ recording session and the summary of the
+ \lt_obj_domain of the channel of which to get the recording
+ event rule descriptors.
+
+ -# Call lttng_list_events(), passing the recording session
+ handle of step 1 and a channel name.
+
+ This function sets a pointer to an array of
+ \link #lttng_event recording event rule descriptors\endlink
+ and returns the number of entries.
+
+ -# Destroy the recording session handle of step 1 with
+ lttng_destroy_handle().
+
+ -# Access the properties of each
+ recording event rule descriptor through structure members or
+ using dedicated getters.
+
+ -# When you're done with the array of recording event rule
+ descriptors, free it with <code>free()</code>.
+ <tr>
+ <td>Event record context field adding
+ <td>
+ -# Initialize a #lttng_event_context structure, setting
+ its properties to describe the context field to be added.
+
+ -# Create a \link #lttng_handle recording session handle\endlink
+ structure to specify the name of the recording session and the
+ tracing domain of the channel to create.
+
+ -# Call lttng_add_context() with the recording session handle
+ of step 2 and the context field descriptor of step 1,
+ optionally passing the name of the channel to target.
+
+ -# Destroy the recording session handle with
+ lttng_destroy_handle().
+
+ @sa \lt_man{lttng-add-context,1}
+ <tr>
+ <td>Enabling
+ <td>
+ Use lttng_enable_channel().
+
+ @sa \lt_man{lttng-enable-channel,1}
+ <tr>
+ <td>Disabling
+ <td>
+ Use lttng_disable_channel().
+
+ @sa \lt_man{lttng-disable-channel,1}
+ <tr>
+ <td>Statistics
+ <td>
+ See:
+
+ - lttng_channel_get_discarded_event_count()
+ - lttng_channel_get_lost_packet_count()
+</table>
+
+<h2>\anchor api-channel-channel-props Properties</h2>
+
+The properties of a channel are:
+
+<table>
+ <tr>
+ <th>Property name
+ <th>Description
+ <th>Access
+ <tr>
+ <td>Buffering scheme
+ <td>
+ See \ref api-channel-buf-scheme "Buffering scheme".
+ <td>
+ The lttng_domain::buf_type member for the containing tracing
+ domain.
+
+ All the channels of a given tracing domain share the same
+ buffering scheme.
+ <tr>
+ <td>Event record loss mode
+ <td>
+ See \ref api-channel-er-loss-mode "Event record loss mode".
+ <td>
+ The lttng_channel_attr::overwrite member.
+ <tr>
+ <td>Sub-buffer size
+ <td>
+ See \ref api-channel-sub-buf-size-count "Sub-buffer size and count".
+ <td>
+ The lttng_channel_attr::subbuf_size member.
+ <tr>
+ <td>Sub-buffer count
+ <td>
+ See \ref api-channel-sub-buf-size-count "Sub-buffer size and count".
+ <td>
+ The lttng_channel_attr::num_subbuf member.
+ <tr>
+ <td>Maximum trace file size
+ <td>
+ See \ref api-channel-max-trace-file-size-count "Maximum trace file size and count".
+ <td>
+ The lttng_channel_attr::tracefile_size member.
+ <tr>
+ <td>Maximum trace file count
+ <td>
+ See \ref api-channel-max-trace-file-size-count "Maximum trace file size and count".
+ <td>
+ The lttng_channel_attr::tracefile_count member.
+ <tr>
+ <td>Read timer period
+ <td>
+ See \ref api-channel-read-timer "Read timer".
+ <td>
+ The lttng_channel_attr::read_timer_interval member.
+ <tr>
+ <td>Switch timer period
+ <td>
+ See \ref api-channel-switch-timer "Switch timer".
+ <td>
+ The lttng_channel_attr::switch_timer_interval member.
+ <tr>
+ <td>Live timer period
+ <td>
+ See \ref api-channel-live-timer "Live timer".
+ <td>
+ The \lt_p{live_timer_period} parameter of
+ lttng_session_descriptor_live_network_create() when you create
+ the descriptor of a \ref api-session-live-mode "live" recording
+ session to contain the channel.
+ <tr>
+ <td>Monitor timer period
+ <td>
+ See \ref api-channel-monitor-timer "Monitor timer".
+ <td>
+ - lttng_channel_get_monitor_timer_interval()
+ - lttng_channel_set_monitor_timer_interval()
+ <tr>
+ <td>Output type (Linux kernel channel)
+ <td>
+ Whether to use <code>mmap()</code> or <code>splice()</code>.
+ <td>
+ The lttng_channel_attr::output member.
+ <tr>
+ <td>\anchor api-channel-blocking-timeout Blocking timeout (user space channel)
+ <td>
+ How long to block (if ever) at the instrumentation point site when
+ a sub-buffer is not available for applications executed with the
+ \c LTTNG_UST_ALLOW_BLOCKING environment variable set.
+ <td>
+ - lttng_channel_get_blocking_timeout()
+ - lttng_channel_set_blocking_timeout()
+</table>
+
+All the properties above are immutable once a channel exists.
+
+@sa The <em>CHANNEL AND RING BUFFER</em> section of
+\lt_man{lttng-concepts,7}.
+
+<h3>\anchor api-channel-buf-scheme Buffering scheme</h3>
+
+A channel has at least one ring buffer per CPU. LTTng always records an
+event to the ring buffer dedicated to the CPU which emits it.
+
+The <strong><em>buffering scheme</em></strong> of a
+\link #LTTNG_DOMAIN_UST user space\endlink
+channel determines what has its own set of per-CPU
+ring buffers, considering \lt_var{U} is the Unix user of the process
+running liblttng-ctl:
+
+<dl>
+ <dt>
+ \anchor api-channel-per-user-buf
+ \link #LTTNG_BUFFER_PER_UID Per-user buffering\endlink
+ <dd>
+ Allocate one set of ring buffers (one per CPU) shared by all the
+ instrumented processes of:
+
+ <dl>
+ <dt>If \lt_var{U} is <code>root</code>
+ <dd>
+ Each Unix user.
+
+ @image html per-user-buffering-root.png
+
+ <dt>Otherwise
+ <dd>
+ \lt_var{U}
+
+ @image html per-user-buffering.png
+ </dl>
+
+ <dt>
+ \anchor api-channel-per-proc-buf
+ \link #LTTNG_BUFFER_PER_PID Per-process buffering\endlink
+ <dd>
+ Allocate one set of ring buffers (one per CPU) for each
+ instrumented process of:
+
+ <dl>
+ <dt>If \lt_var{U} is <code>root</code>
+ <dd>
+ All Unix users.
+
+ @image html per-process-buffering-root.png
+
+ <dt>Otherwise
+ <dd>
+ \lt_var{U}
+
+ @image html per-process-buffering.png
+ </dl>
+</dl>
+
+The per-process buffering scheme tends to consume more memory than the
+per-user option because systems generally have more instrumented
+processes than Unix users running instrumented processes. However, the
+per-process buffering scheme ensures that one process having a high
+event throughput won't fill all the shared sub-buffers of the same Unix
+user, only its own.
+
+The buffering scheme of a Linux kernel (#LTTNG_DOMAIN_KERNEL) channel is
+always to allocate a single set of ring buffers for the whole system
+(#LTTNG_BUFFER_GLOBAL). This scheme is similar to the
+\ref api-channel-per-user-buf "per-user" one, but with a single, global
+user "running" the kernel.
+
+To set the buffering scheme of a channel when you create it:
+
+- Set the lttng_domain::buf_type member of the structure which you pass
+ within the #lttng_handle structure to lttng_enable_channel().
+
+ Note that, for a given \lt_obj_session, \em all
+ the channels of a given \lt_obj_domain must share the same buffering
+ scheme.
+
+@sa The <em>Buffering scheme</em> section of \lt_man{lttng-concepts,7}.
+
+<h3>\anchor api-channel-er-loss-mode Event record loss mode</h3>
+
+When LTTng emits an event, LTTng can record it to a specific, available
+sub-buffer within the ring buffers of specific channels. When there's no
+space left in a sub-buffer, the tracer marks it as consumable and
+another, available sub-buffer starts receiving the following event
+records. An LTTng consumer daemon eventually consumes the marked
+sub-buffer, which returns to the available state.
+
+In an ideal world, sub-buffers are consumed faster than they are filled.
+In the real world, however, all sub-buffers can be full at some point,
+leaving no space to record the following events.
+
+By default, LTTng-modules and LTTng-UST are <em>non-blocking</em>
+tracers: when there's no available sub-buffer to record an event, it's
+acceptable to lose event records when the alternative would be to cause
+substantial delays in the execution of the instrumented application.
+LTTng privileges performance over integrity; it aims at perturbing the
+instrumented application as little as possible in order to make the
+detection of subtle race conditions and rare interrupt cascades
+possible.
+
+Since LTTng 2.10, the LTTng user space tracer, LTTng-UST, supports
+a <em>blocking mode</em>: see lttng_channel_get_blocking_timeout() and
+lttng_channel_set_blocking_timeout().
+
+When it comes to losing event records because there's no available
+sub-buffer, or because the blocking timeout of the channel is reached,
+the <strong><em>event record loss mode</em></strong> of the channel
+determines what to do. The available event record loss modes are:
+
+<dl>
+ <dt>\anchor api-channel-discard-mode Discard mode
+ <dd>
+ Drop the newest event records until a sub-buffer becomes available.
+
+ This is the only available mode when you specify a blocking timeout
+ with lttng_channel_set_blocking_timeout().
+
+ With this mode, LTTng increments a count of discarded event records
+ when it discards an event record and saves this count to the trace.
+ A trace reader can use the saved discarded event record count of the
+ trace to decide whether or not to perform some analysis even if
+ trace data is known to be missing.
+
+ Get the number of discarded event records of a channel with
+ lttng_channel_get_discarded_event_count().
+
+ <dt>\anchor api-channel-overwrite-mode Overwrite mode
+ <dd>
+ Clear the sub-buffer containing the oldest event records and start
+ writing the newest event records there.
+
+ This mode is sometimes called <em>flight recorder mode</em> because
+ it's similar to a
+ <a href="https://en.wikipedia.org/wiki/Flight_recorder">flight recorder</a>:
+ always keep a fixed amount of the latest data. It's also
+ similar to the roll mode of an oscilloscope.
+
+ Since LTTng 2.8, with this mode, LTTng writes to a given
+ sub-buffer its sequence number within its data stream. With a
+ \ref api-session-local-mode "local",
+ \ref api-session-net-mode "network streaming", or
+ \ref api-session-live-mode "live" recording session, a trace
+ reader can use such sequence numbers to report discarded packets. A
+ trace reader can use the saved discarded sub-buffer (packet) count
+ of the trace to decide whether or not to perform some analysis even
+ if trace data is known to be missing.
+
+ Get the number of discarded packets (sub-buffers) of a channel with
+ lttng_channel_get_lost_packet_count().
+
+ With this mode, LTTng doesn't write to the trace the exact number of
+ lost event records in the lost sub-buffers.
+</dl>
+
+Which mechanism you should choose depends on your context: prioritize
+the newest or the oldest event records in the ring buffer?
+
+Beware that, in overwrite mode, the tracer abandons a <em>whole
+sub-buffer</em> as soon as a there's no space left for a new event
+record, whereas in discard mode, the tracer only discards the event
+record that doesn't fit.
+
+To set the event record loss mode of a channel when you create it:
+
+- Set the lttng_channel_attr::overwrite member of the lttng_channel::attr
+ member of the structure you pass to lttng_enable_channel().
+
+There are a few ways to decrease your probability of losing event
+records. The
+\ref api-channel-sub-buf-size-count "Sub-buffer size and count" section
+shows how to fine-tune the sub-buffer size and count of a channel to
+virtually stop losing event records, though at the cost of greater
+memory usage.
+
+@sa The <em>Event record loss mode</em> section of
+\lt_man{lttng-concepts,7}.
+
+<h3>\anchor api-channel-sub-buf-size-count Sub-buffer size and count</h3>
+
+A channel has one or more ring buffer for each CPU of the target system.
+
+See \ref api-channel-buf-scheme "Buffering scheme" to learn how many
+ring buffers of a given channel are dedicated to each CPU depending on
+its buffering scheme.
+
+To set the size of each sub-buffer the ring buffers of a channel have
+when you create it:
+
+- Set the lttng_channel_attr::subbuf_size member of the
+ lttng_channel::attr member of the structure you pass to
+ lttng_enable_channel().
+
+To set the number of sub-buffers each ring buffer of a channel has
+when you create it:
+
+- Set the lttng_channel_attr::num_subbuf member of the
+ lttng_channel::attr member of the structure you pass to
+ lttng_enable_channel().
+
+Note that LTTng switching the current sub-buffer of a ring buffer
+(marking a full one as consumable and switching to an available one for
+LTTng to record the next events) introduces noticeable CPU overhead.
+Knowing this, the following list presents a few practical situations
+along with how to configure the sub-buffer size and count for them:
+
+<dl>
+ <dt>High event throughput
+ <dd>
+ In general, prefer large sub-buffers to lower the risk of losing
+ event records.
+
+ Having larger sub-buffers also ensures a lower sub-buffer
+ \ref api-channel-switch-timer "switching frequency".
+
+ The sub-buffer count is only meaningful if you create the channel in
+ \ref api-channel-overwrite-mode "overwrite mode": in this case, if
+ LTTng overwrites a sub-buffer, then the other sub-buffers are left
+ unaltered.
+
+ <dt>Low event throughput
+ <dd>
+ In general, prefer smaller sub-buffers since the risk of losing
+ event records is low.
+
+ Because LTTng emits events less frequently, the sub-buffer switching
+ frequency should remain low and therefore the overhead of the tracer
+ shouldn't be a problem.
+
+ <dt>Low memory system
+ <dd>
+ If your target system has a low memory limit, prefer fewer first,
+ then smaller sub-buffers.
+
+ Even if the system is limited in memory, you want to keep the
+ sub-buffers as large as possible to avoid a high sub-buffer
+ switching frequency.
+</dl>
+
+Note that LTTng uses <a href="https://diamon.org/ctf/">CTF</a> as its
+trace format, which means event record data is very compact. For
+example, the average LTTng kernel event record weights about
+32 bytes. Therefore, a sub-buffer size of 1 MiB is considered
+large.
+
+The previous scenarios highlight the major trade-off between a few large
+sub-buffers and more, smaller sub-buffers: sub-buffer switching
+frequency vs. how many event records are lost in
+\ref api-channel-overwrite-mode "overwrite mode".
+Assuming a constant event throughput and using the overwrite mode, the
+two following configurations have the same ring buffer total size:
+
+<dl>
+ <dt>Two sub-buffers of 4 MiB each
+ <dd>
+ Expect a very low sub-buffer switching frequency, but if LTTng ever
+ needs to overwrite a sub-buffer, half of the event records so far
+ (4 MiB) are definitely lost.
+
+ <dt>Eight sub-buffers of 1 MiB each
+ <dd>
+ Expect four times the tracer overhead of the configuration above,
+ but if LTTng needs to overwrite a sub-buffer, only the eighth of
+ event records so far (1 MiB) are definitely lost.
+</dl>
+
+In \ref api-channel-discard-mode "discard mode", the sub-buffer count
+parameter is pointless: use two sub-buffers and set their size according
+to your requirements.
+
+@sa The <em>Sub-buffer size and count</em> section of
+\lt_man{lttng-concepts,7}.
+
+<h3>\anchor api-channel-max-trace-file-size-count Maximum trace file size and count</h3>
+
+By default, trace files can grow as large as needed.
+
+To set the maximum size of each trace file that LTTng writes from the
+ring buffers of a channel when you create it:
+
+- Set the lttng_channel_attr::tracefile_size member of the
+ lttng_channel::attr member of the structure you pass to
+ lttng_enable_channel().
+
+When the size of a trace file reaches the fixed maximum size of the
+channel, LTTng creates another file to contain the next event records.
+LTTng appends a file count to each trace file name in this case.
+
+If you set the trace file size attribute when you create a channel, the
+maximum number of trace files that LTTng creates is <em>unlimited</em>
+by default.
+
+To limit the size of each trace file that LTTng writes from the
+ring buffers of a channel when you create it:
+
+- Set the lttng_channel_attr::tracefile_count member of the
+ lttng_channel::attr member of the structure you pass to
+ lttng_enable_channel().
+
+When the number of trace files reaches the fixed maximum count of the
+channel, LTTng overwrites the oldest trace file. This mechanism is
+called <em>trace file rotation</em>.
+
+@attention
+ @parblock
+ Even if you don't limit the trace file count, always assume that
+ LTTng manages all the trace files of the recording session.
+
+ In other words, there's no safe way to know if LTTng still holds a
+ given trace file open with the trace file rotation feature.
+
+ The only way to obtain an unmanaged, self-contained LTTng trace
+ before you \link lttng_destroy_session_ext() destroy the
+ recording session\endlink is with the
+ \ref api_session_rotation "recording session rotation" feature,
+ which is available since LTTng 2.11.
+ @endparblock
+
+@sa The <em>Maximum trace file size and count</em> section of
+\lt_man{lttng-concepts,7}.
+
+<h3>\anchor api-channel-timers Timers</h3>
+
+Each channel can have up to four optional
+<strong><em>timers</em></strong>:
+
+<dl>
+ <dt>\anchor api-channel-switch-timer Switch timer
+ <dd>
+ When this timer expires, a sub-buffer switch happens: for each ring
+ buffer of the channel, LTTng marks the current sub-buffer as
+ consumable and switches to an available one to record the next
+ events.
+
+ A switch timer is useful to ensure that LTTng consumes and commits
+ trace data to trace files or to a distant relay daemon
+ (see \lt_man{lttng-relayd,8}) periodically in case of a low event
+ throughput.
+
+ Such a timer is also convenient when you use
+ \ref api-channel-sub-buf-size-count "large sub-buffers"
+ to cope with a sporadic high event throughput, even if the
+ throughput is otherwise low.
+
+ To set the period of the switch timer of a channel when you create
+ it:
+
+ - Set the lttng_channel_attr::switch_timer_interval member of the
+ lttng_channel::attr member of the structure you pass to
+ lttng_enable_channel().
+
+ A channel only has a switch timer when its
+ recording session is \em not in
+ \ref api-session-live-mode "live mode". lttng_enable_channel()
+ ignores the lttng_channel_attr::switch_timer_interval member with a
+ live recording session. For a live recording session, the
+ \ref api-channel-live-timer "live timer" plays the role of the
+ switch timer.
+
+ <dt>\anchor api-channel-live-timer Live timer
+ <dd>
+ Like the \ref api-channel-switch-timer "switch timer", but for a
+ channel which belongs to a
+ \ref api-session-live-mode "live" recording session.
+
+ If this timer expires but there's no sub-buffer to consume, LTTng
+ sends a message with a timestamp to the connected relay daemon (see
+ \lt_man{lttng-relayd,8}) so that its live readers can progress.
+
+ To set the period of the live timer of a channel when you create
+ its recording session:
+
+ - Set the \lt_p{live_timer_period} parameter when you call
+ lttng_session_descriptor_live_network_create() to create a
+ live recording session descriptor to pass to
+ lttng_create_session_ext().
+
+ @note
+ All the channels of a live recording session share the same
+ live timer period.
+
+ <dt>\anchor api-channel-read-timer Read timer
+ <dd>
+ When this timer expires, LTTng checks for full, consumable
+ sub-buffers.
+
+ By default, the LTTng tracers use an asynchronous message mechanism
+ to signal a full sub-buffer so that a consumer daemon can consume
+ it.
+
+ When such messages must be avoided, for example in real-time
+ applications, use this timer instead.
+
+ To set the period of the read timer of a channel when you create
+ it:
+
+ - Set the lttng_channel_attr::read_timer_interval member of the
+ lttng_channel::attr member of the structure you pass to
+ lttng_enable_channel().
+
+ <dt>\anchor api-channel-monitor-timer Monitor timer
+ <dd>
+ When this timer expires, the consumer daemon samples some channel
+ statistics to evaluate the following trigger conditions:
+
+ -# The consumed buffer size of a given recording session becomes
+ greater than some value.
+
+ -# The buffer usage of a given channel becomes greater than some
+ value.
+
+ -# The buffer usage of a given channel becomes less than some value.
+
+ If you disable the monitor timer of a channel \lt_var{C}:
+
+ - The consumed buffer size value of the recording session
+ of \lt_var{C} could be wrong for trigger condition
+ type 1: the consumed buffer size of \lt_var{C} won't be
+ part of the grand total.
+
+ - The buffer usage trigger conditions (types 2 and 3)
+ for \lt_var{C} will never be satisfied.
+
+ See \ref api_trigger to learn more about triggers.
+
+ To set the period of the monitor timer of a channel when you create
+ it:
+
+ - Call lttng_channel_set_monitor_timer_interval() with the
+ #lttng_channel structure you pass to lttng_enable_channel().
+</dl>
+
+@sa The <em>Timers</em> section of \lt_man{lttng-concepts,7}.
+
+@defgroup api_rer Recording event rule API
+@ingroup api_channel
+
+<h1>Concepts</h1>
+
+An <em>instrumentation point</em> is a point, within a piece of
+software, which, when executed, creates an LTTng <em>event</em>.
+See \ref api_inst_pt to learn how to list the available instrumentation
+points.
+
+An <em>event rule</em> is a set of \ref api-rer-conds "conditions" to
+match a set of events.
+
+A <strong><em>recording event rule</em></strong> is a specific type of
+event rule of which the action is to serialize and write the matched
+event as an <em>event record</em> to a sub-buffer of its attached
+\lt_obj_channel.
+
+An event record has a \ref api-rer-er-name "name" and fields.
+
+When LTTng creates an event \lt_var{E}, a recording event
+rule \lt_var{ER} is said to <em>match</em> \lt_var{E}
+when \lt_var{E} satisfies \em all the conditions
+of \lt_var{ER}. This concept is similar to a regular expression
+which matches a set of strings.
+
+When a recording event rule matches an event, LTTng \em emits the event,
+therefore attempting to record it.
+
+@attention
+ @parblock
+ The event creation and emission processes are \em documentation
+ concepts to help understand the journey from an instrumentation
+ point to an event record.
+
+ The actual creation of an event can be costly because LTTng needs to
+ evaluate the arguments of the instrumentation point.
+
+ In practice, LTTng implements various optimizations for the
+ \link #LTTNG_DOMAIN_KERNEL Linux kernel\endlink and
+ \link #LTTNG_DOMAIN_UST user space\endlink \lt_obj_domains
+ to avoid actually creating an event when the tracer knows, thanks to
+ properties which are independent from the event payload and current
+ \link #lttng_event_context_type context\endlink, that it would never
+ emit such an event. Those properties are:
+
+ - The \ref api-rer-conds-inst-pt-type "instrumentation point type".
+
+ - The \ref api-rer-conds-event-name "instrumentation point name" (or
+ event name).
+
+ - The \ref api-rer-conds-ll "instrumentation point log level".
+
+ - The \link lttng_event::enabled status\endlink (enabled or
+ disabled) of the rule itself.
+
+ - The \link lttng_channel::enabled status\endlink (enabled or
+ disabled) of the \lt_obj_channel containing the rule.
+
+ - The \link lttng_session::enabled activity\endlink (started or
+ stopped) of the \lt_obj_session containing the rule.
+
+ - Whether or not the process for which LTTng would create the event
+ is \ref api_pais "allowed to record events".
+
+ In other words: if, for a given instrumentation point \lt_var{IP},
+ the LTTng tracer knows that it would never emit an event,
+ executing \lt_var{IP} represents a simple boolean variable check
+ and, for a \link #LTTNG_DOMAIN_KERNEL Linux kernel\endlink
+ \lt_obj_rer, a few current process attribute checks.
+ @endparblock
+
+You always attach a recording event rule to a
+\lt_obj_channel, which belongs to
+a \lt_obj_session, when you
+\link lttng_enable_event_with_exclusions() create it\endlink.
+A channel owns recording event rules.
+
+When multiple matching recording event rules are attached to the same
+channel, LTTng attempts to serialize and record the matched event
+<em>once</em>.
+
+@image html event-rule.png "Logical path from an instrumentation point to an event record."
+
+As of LTTng-tools \lt_version_maj_min, you cannot remove a
+recording event rule: it exists as long as its \lt_obj_session exists.
+
+<h1>Operations</h1>
+
+The recording event rule operations are:
+
+<table>
+ <tr>
+ <th>Operation
+ <th>Means
+ <tr>
+ <td>Creation
+ <td>
+ -# Call lttng_event_create() to create an initial
+ \link #lttng_event recording event rule descriptor\endlink.
+
+ -# Set the properties of the recording event rule descriptor of
+ step 1 through direct members or with dedicated setters.
+
+ See the property table below.
+
+ -# Create a \link #lttng_handle recording session handle\endlink
+ structure to specify the name of the recording session and the
+ tracing domain of the recording event rule to create.
+
+ -# Call lttng_enable_event_with_exclusions() with the recording
+ session handle of step 3, the recording event rule
+ descriptor of step 1, the name of a
+ \lt_obj_channel to which to attach the
+ created recording event rule, and, depending on the selected
+ function, other properties to create the rule.
+
+ -# Destroy the recording session handle with
+ lttng_destroy_handle() and the recording event rule descriptor
+ with lttng_event_destroy().
+
+ @sa \lt_man{lttng-enable-event,1}
+ <tr>
+ <td>Property access
+ <td>
+ See:
+
+ - The members of #lttng_event
+ - lttng_event_get_userspace_probe_location()
+ - lttng_event_set_userspace_probe_location()
+ - lttng_event_get_filter_expression()
+ - lttng_event_get_exclusion_name_count()
+ - lttng_event_get_exclusion_name()
+
+ @sa \ref api-rer-conds "Recording event rule conditions".
+ <tr>
+ <td>Enabling
+ <td>
+ With an #lttng_event instance which comes from
+ lttng_list_events(), use lttng_enable_event().
+
+ Otherwise, use lttng_enable_event_with_exclusions().
+
+ @sa \lt_man{lttng-enable-event,1}
+ <tr>
+ <td>Disabling
+ <td>
+ Use lttng_disable_event() or lttng_disable_event_ext().
+
+ @sa \lt_man{lttng-disable-event,1}
+</table>
+
+<h1>\anchor api-rer-conds Recording event rule conditions</h1>
+
+For LTTng to emit and record an event \lt_var{E}, \lt_var{E}
+must satisfy \em all the conditions of a recording event
+rule \lt_var{ER}, that is:
+
+<dl>
+ <dt>Explicit conditions
+ <dd>
+ You set the following conditions when you
+ \link lttng_enable_event_with_exclusions() create\endlink
+ \lt_var{ER} from some
+ \link #lttng_event recording event rule descriptor\endlink
+ \c event_rule (#lttng_event).
+
+ <table>
+ <tr>
+ <th>Name
+ <th>Description
+ <tr>
+ <td>
+ \anchor api-rer-conds-inst-pt-type
+ \ref api-rer-conds-inst-pt-type "Instrumentation point type"
+ <td>
+ \lt_var{E} satisfies the instrumentation point type condition
+ of \lt_var{ER} if the instrumentation point from which LTTng
+ creates \lt_var{E} is, depending on the
+ \lt_obj_domain which contains \lt_var{ER}:
+
+ <dl>
+ <dt>#LTTNG_DOMAIN_KERNEL
+ <dd>
+ Depending on
+ \link lttng_event::type <code>event_rule.type</code>\endlink:
+
+ <dl>
+ <dt>#LTTNG_EVENT_TRACEPOINT
+ <dd>
+ An LTTng kernel tracepoint, that is, a statically
+ defined point in the source code of the kernel image
+ or of a kernel module with LTTng kernel tracer macros.
+
+ @sa lttng_list_tracepoints()
+
+ <dt>#LTTNG_EVENT_SYSCALL
+ <dd>
+ The entry and exit of a Linux kernel system call.
+
+ @sa lttng_list_syscalls()
+
+ <dt>#LTTNG_EVENT_PROBE
+ <dd>
+ A Linux
+ <a href="https://www.kernel.org/doc/html/latest/trace/kprobes.html">kprobe</a>,
+ that is, a single probe dynamically placed in the
+ compiled kernel code.
+
+ \link lttng_event::lttng_event_attr_u::probe
+ <code>event_rule.attr.probe</code>\endlink
+ indicates the kprobe location,
+ while \link lttng_event::name
+ <code>event_rule.name</code>\endlink
+ is the name of the created kprobe instrumentation
+ point (future event name).
+
+ The payload of a Linux kprobe event is empty.
+
+ <dt>#LTTNG_EVENT_FUNCTION
+ <dd>
+ A Linux
+ <a href="https://www.kernel.org/doc/html/latest/trace/kprobes.html">kretprobe</a>,
+ that is, two probes dynamically placed at the entry
+ and exit of a function in the compiled kernel code.
+
+ \link lttng_event::lttng_event_attr_u::probe
+ <code>event_rule.attr.probe</code>\endlink
+ indicates the kretprobe location,
+ while \link lttng_event::name
+ <code>event_rule.name</code>\endlink
+ is the name of the created kretprobe instrumentation
+ point (future event name).
+
+ The payload of a Linux kretprobe event is empty.
+
+ <dt>#LTTNG_EVENT_USERSPACE_PROBE
+ <dd>
+ A Linux
+ <a href="https://lwn.net/Articles/499190/">uprobe</a>,
+ that is, a single probe dynamically placed at the
+ entry of a compiled user space application/library
+ function through the kernel.
+
+ Set and get the location of the uprobe with
+ lttng_event_set_userspace_probe_location() and
+ lttng_event_get_userspace_probe_location().
+
+ \link lttng_event::name <code>event_rule.name</code>\endlink
+ is the name of the created uprobe instrumentation
+ point (future event name).
+
+ The payload of a Linux uprobe event is empty.
+ </dl>
+
+ <dt>#LTTNG_DOMAIN_UST
+ <dd>
+ An LTTng user space tracepoint, that is, a statically
+ defined point in the source code of a C/C++
+ application/library with LTTng user space tracer macros.
+
+ \link lttng_event::type <code>event_rule.type</code>\endlink
+ must be #LTTNG_EVENT_TRACEPOINT.
+
+ @sa lttng_list_tracepoints()
+
+ <dt>#LTTNG_DOMAIN_JUL
+ <dt>#LTTNG_DOMAIN_LOG4J
+ <dt>#LTTNG_DOMAIN_PYTHON
+ <dd>
+ A Java/Python logging statement.
+
+ \link lttng_event::type <code>event_rule.type</code>\endlink
+ must be #LTTNG_EVENT_TRACEPOINT.
+
+ @sa lttng_list_tracepoints()
+ </dl>
+ <tr>
+ <td>
+ \anchor api-rer-conds-event-name
+ \ref api-rer-conds-event-name "Event name"
+ <td>
+ An event \lt_var{E} satisfies the event name condition
+ of \lt_var{ER} if the two following statements are
+ \b true:
+
+ - \link lttng_event::name <code>event_rule.name</code>\endlink
+ matches, depending on
+ \link lttng_event::type <code>event_rule.type</code>\endlink
+ (see \ref api-rer-conds-inst-pt-type "Instrumentation point type"
+ above):
+
+ <dl>
+ <dt>#LTTNG_EVENT_TRACEPOINT
+ <dd>
+ The full name of the LTTng tracepoint or Java/Python
+ logger from which LTTng creates \lt_var{E}.
+
+ Note that the full name of a
+ \link #LTTNG_DOMAIN_UST user space\endlink tracepoint is
+ <code><em>PROVIDER</em>:<em>NAME</em></code>, where
+ <code><em>PROVIDER</em></code> is the tracepoint
+ provider name and <code><em>NAME</em></code> is the
+ tracepoint name.
+
+ <dt>#LTTNG_EVENT_SYSCALL
+ <dd>
+ The name of the system call, without any
+ <code>sys_</code> prefix, from which LTTng
+ creates \lt_var{E}.
+ </dl>
+
+ @sa \ref api-rer-er-name "Event record name".
+
+ - If the \lt_obj_domain
+ containing \lt_var{ER} is #LTTNG_DOMAIN_UST:
+ none of the event name exclusion patterns of
+ \c event_rule matches the full name of the user
+ space tracepoint from which LTTng creates \lt_var{E}.
+
+ Set the event name exclusion patterns of
+ \c event_rule when you call
+ lttng_enable_event_with_exclusions().
+
+ Get the event name exclusion patterns of
+ a recording event rule descriptor with
+ lttng_event_get_exclusion_name_count() and
+ lttng_event_get_exclusion_name().
+
+ This condition is only meaningful when
+ \link lttng_event::type <code>event_rule.type</code>\endlink
+ is #LTTNG_EVENT_TRACEPOINT or
+ #LTTNG_EVENT_SYSCALL: it's always satisfied for the other
+ \ref api-rer-conds-inst-pt-type "instrumentation point types".
+
+ In all cases,
+ \link lttng_event::name <code>event_rule.name</code>\endlink
+ and the event name exclusion patterns of
+ \c event_rule are <em>globbing patterns</em>: the
+ <code>*</code> character means "match anything". To match a
+ literal <code>*</code> character, use <code>\\*</code>.
+ <tr>
+ <td>
+ \anchor api-rer-conds-ll
+ \ref api-rer-conds-ll "Instrumentation point log level"
+ <td>
+ An event \lt_var{E} satisfies the instrumentation point
+ log level condition of \lt_var{ER} if, depending on
+ \link lttng_event::loglevel_type <code>event_rule.loglevel_type</code>\endlink,
+ the log level of the LTTng user space tracepoint or
+ logging statement from which LTTng creates \lt_var{E}
+ is:
+
+ <dl>
+ <dt>#LTTNG_EVENT_LOGLEVEL_ALL
+ <dd>
+ Anything (the condition is always satisfied).
+
+ <dt>#LTTNG_EVENT_LOGLEVEL_RANGE
+ <dd>
+ At least as severe as
+ \link lttng_event::loglevel <code>event_rule.loglevel</code>\endlink.
+
+ <dt>#LTTNG_EVENT_LOGLEVEL_SINGLE
+ <dd>
+ Exactly
+ \link lttng_event::loglevel <code>event_rule.loglevel</code>\endlink.
+ </dl>
+
+ This condition is only meaningful when the \lt_obj_domain
+ containing \lt_var{ER} is \em not #LTTNG_DOMAIN_KERNEL:
+ it's always satisfied for #LTTNG_DOMAIN_KERNEL.
+ <tr>
+ <td>
+ \anchor api-rer-conds-filter
+ \ref api-rer-conds-filter "Event payload and context filter"
+ <td>
+ An event \lt_var{E} satisfies the event payload and
+ context filter condition of \lt_var{ER} if
+ \c event_rule has no filter expression or if its filter
+ expression \lt_var{EXPR} evaluates to \b true
+ when LTTng creates \lt_var{E}.
+
+ This condition is only meaningful when:
+
+ - The \lt_obj_domain containing \lt_var{ER} is
+ #LTTNG_DOMAIN_KERNEL or #LTTNG_DOMAIN_UST: it's always
+ satisfied for the other tracing domains.
+
+ - \link lttng_event::type <code>event_rule.type</code>\endlink
+ is #LTTNG_EVENT_TRACEPOINT or #LTTNG_EVENT_SYSCALL:
+ it's always satisfied for the other
+ \ref api-rer-conds-inst-pt-type "instrumentation point types".
+
+ Set the event payload and context filter expression of
+ \c event_rule when you call
+ lttng_enable_event_with_exclusions().
+
+ Get the event payload and context filter expression of
+ a recording event rule descriptor with
+ lttng_event_get_filter_expression().
+
+ \lt_var{EXPR} can contain references to the payload fields
+ of \lt_var{E} and to the current
+ \link #lttng_event_context_type context\endlink fields.
+
+ The expected syntax of \lt_var{EXPR} is similar to the syntax
+ of a C language conditional expression (an expression
+ which an \c if statement can evaluate), but there are a few
+ differences:
+
+ - A <code><em>NAME</em></code> expression identifies an event
+ payload field named <code><em>NAME</em></code> (a
+ C identifier).
+
+ Use the C language dot and square bracket notations to
+ access nested structure and array/sequence fields. You can
+ only use a constant, positive integer number within square
+ brackets. If the index is out of bounds, \lt_var{EXPR} is
+ \b false.
+
+ The value of an enumeration field is an integer.
+
+ When a field expression doesn't exist, \lt_var{EXPR} is
+ \b false.
+
+ Examples: <code>my_field</code>, <code>target_cpu</code>,
+ <code>seq[7]</code>, <code>msg.user[1].data[2][17]</code>.
+
+ - A <code>$ctx.<em>TYPE</em></code> expression identifies the
+ statically-known context field having the type
+ <code><em>TYPE</em></code> (a C identifier).
+
+ When a field expression doesn't exist, \lt_var{EXPR} is \b
+ false.
+
+ Examples: <code>$ctx.prio</code>,
+ <code>$ctx.preemptible</code>,
+ <code>$ctx.perf:cpu:stalled-cycles-frontend</code>.
+
+ - A <code>$app.<em>PROVIDER</em>:<em>TYPE</em></code>
+ expression identifies the application-specific context field
+ having the type <code><em>TYPE</em></code> (a
+ C identifier) from the provider
+ <code><em>PROVIDER</em></code> (a C identifier).
+
+ When a field expression doesn't exist, \lt_var{EXPR} is \b
+ false.
+
+ Example: <code>$app.server:cur_user</code>.
+
+ - Compare strings, either string fields or string literals
+ (double-quoted), with the <code>==</code> and
+ <code>!=</code> operators.
+
+ When comparing to a string literal, the <code>*</code>
+ character means "match anything". To match a literal
+ <code>*</code> character, use <code>\\*</code>.
+
+ Examples: <code>my_field == "user34"</code>,
+ <code>my_field == my_other_field</code>,
+ <code>my_field == "192.168.*"</code>.
+
+ - The
+ <a href="https://en.wikipedia.org/wiki/Order_of_operations">precedence table</a>
+ of the operators which are supported in
+ \lt_var{EXPR} is as follows. In this table, the highest
+ precedence is 1:
+
+ <table>
+ <tr>
+ <th>Precedence
+ <th>Operator
+ <th>Description
+ <th>Associativity
+ <tr>
+ <td>1
+ <td><code>-</code>
+ <td>Unary minus
+ <td>Right-to-left
+ <tr>
+ <td>1
+ <td><code>+</code>
+ <td>Unary plus
+ <td>Right-to-left
+ <tr>
+ <td>1
+ <td><code>!</code>
+ <td>Logical NOT
+ <td>Right-to-left
+ <tr>
+ <td>1
+ <td><code>~</code>
+ <td>Bitwise NOT
+ <td>Right-to-left
+ <tr>
+ <td>2
+ <td><code><<</code>
+ <td>Bitwise left shift
+ <td>Left-to-right
+ <tr>
+ <td>2
+ <td><code>>></code>
+ <td>Bitwise right shift
+ <td>Left-to-right
+ <tr>
+ <td>3
+ <td><code>&</code>
+ <td>Bitwise AND
+ <td>Left-to-right
+ <tr>
+ <td>4
+ <td><code>^</code>
+ <td>Bitwise XOR
+ <td>Left-to-right
+ <tr>
+ <td>5
+ <td><code>|</code>
+ <td>Bitwise OR
+ <td>Left-to-right
+ <tr>
+ <td>6
+ <td><code><</code>
+ <td>Less than
+ <td>Left-to-right
+ <tr>
+ <td>6
+ <td><code><=</code>
+ <td>Less than or equal to
+ <td>Left-to-right
+ <tr>
+ <td>6
+ <td><code>></code>
+ <td>Greater than
+ <td>Left-to-right
+ <tr>
+ <td>6
+ <td><code>>=</code>
+ <td>Greater than or equal to
+ <td>Left-to-right
+ <tr>
+ <td>7
+ <td><code>==</code>
+ <td>Equal to
+ <td>Left-to-right
+ <tr>
+ <td>7
+ <td><code>!=</code>
+ <td>Not equal to
+ <td>Left-to-right
+ <tr>
+ <td>8
+ <td><code>&&</code>
+ <td>Logical AND
+ <td>Left-to-right
+ <tr>
+ <td>9
+ <td><code>||</code>
+ <td>Logical OR
+ <td>Left-to-right
+ </table>
+
+ Parentheses are supported to bypass the default order.
+
+ @attention
+ Unlike the C language, the bitwise AND and OR
+ operators (<code>&</code> and <code>|</code>) in
+ \lt_var{EXPR} take precedence over relational
+ operators (<code><<</code>, <code><=</code>,
+ <code>></code>, <code>>=</code>, <code>==</code>,
+ and <code>!=</code>). This means the expression
+ <code>2 & 2 == 2</code>
+ is \b true while the equivalent C expression
+ is \b false.
+
+ The arithmetic operators are :not: supported.
+
+ LTTng first casts all integer constants and fields to signed
+ 64-bit integers. The representation of negative integers is
+ two's complement. This means that, for example, the signed
+ 8-bit integer field 0xff (-1) becomes 0xffffffffffffffff
+ (still -1) once casted.
+
+ Before a bitwise operator is applied, LTTng casts all its
+ operands to unsigned 64-bit integers, and then casts the
+ result back to a signed 64-bit integer. For the bitwise NOT
+ operator, it's the equivalent of this C expression:
+
+ @code
+ (int64_t) ~((uint64_t) val)
+ @endcode
+
+ For the binary bitwise operators, it's the equivalent of those
+ C expressions:
+
+ @code
+ (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
+ (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
+ (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
+ (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
+ (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
+ @endcode
+
+ If the right-hand side of a bitwise shift operator
+ (<code><<</code> and <code>>></code>) is not in
+ the [0, 63] range, then \lt_var{EXPR} is \b false.
+
+ @note
+ See the \ref api_pais to allow or disallow processes to
+ record LTTng events based on their attributes
+ instead of using equivalent statically-known context
+ fields in \lt_var{EXPR} like <code>$ctx.pid</code>.
+ The former method is much more efficient.
+
+ \lt_var{EXPR} examples:
+
+ @code{.unparsed}
+ msg_id == 23 && size >= 2048
+ @endcode
+
+ @code{.unparsed}
+ $ctx.procname == "lttng*" && (!flag || poel < 34)
+ @endcode
+
+ @code{.unparsed}
+ $app.my_provider:my_context == 17.34e9 || some_enum >= 14
+ @endcode
+
+ @code{.unparsed}
+ $ctx.cpu_id == 2 && filename != "*.log"
+ @endcode
+
+ @code{.unparsed}
+ eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
+ @endcode
+ </table>
+
+ <dt>Implicit conditions
+ <dd>
+ - \lt_var{ER} itself is \link lttng_event::enabled enabled\endlink.
+
+ A recording event rule is enabled on
+ \link lttng_enable_event_with_exclusions() creation\endlink.
+
+ @sa lttng_enable_event() --
+ Creates or enables a recording event rule.
+ @sa lttng_disable_event_ext() --
+ Disables a recording event rule.
+
+ - The \lt_obj_channel which contains \lt_var{ER} is
+ \link lttng_channel::enabled enabled\endlink.
+
+ A channel is enabled on
+ \link lttng_enable_channel() creation\endlink.
+
+ @sa lttng_enable_channel() --
+ Creates or enables a channel.
+ @sa lttng_disable_channel() --
+ Disables a channel.
+
+ - The \lt_obj_session which contains \lt_var{ER} is
+ \link lttng_session::enabled active\endlink (started).
+
+ A recording session is inactive (stopped) on
+ \link lttng_create_session_ext() creation\endlink.
+
+ @sa lttng_start_tracing() --
+ Starts a recording session.
+ @sa lttng_stop_tracing() --
+ Stops a recording session.
+
+ - The process for which LTTng creates \lt_var{E} is
+ \ref api_pais "allowed to record events".
+
+ All processes are allowed to record events on recording session
+ \link lttng_create_session_ext() creation\endlink.
+</dl>
+
+<h1>\anchor api-rer-er-name Event record name</h1>
+
+When LTTng records an event \lt_var{E}, the resulting event record
+has a name which depends on the
+\ref api-rer-conds-inst-pt-type "instrumentation point type condition"
+of the recording event rule \lt_var{ER} which matched \lt_var{E}
+as well as on the \lt_obj_domain which contains \lt_var{ER}:
+
+<table>
+ <tr>
+ <th>Tracing domain
+ <th>Instrumentation point type
+ <th>Event record name
+ <tr>
+ <td>#LTTNG_DOMAIN_KERNEL or #LTTNG_DOMAIN_UST
+ <td>#LTTNG_EVENT_TRACEPOINT
+ <td>
+ Full name of the tracepoint from which LTTng creates \lt_var{E}.
+
+ Note that the full name of a
+ \link #LTTNG_DOMAIN_UST user space\endlink tracepoint is
+ <code><em>PROVIDER</em>:<em>NAME</em></code>, where
+ <code><em>PROVIDER</em></code> is the tracepoint provider name and
+ <code><em>NAME</em></code> is the tracepoint name.
+ <tr>
+ <td>#LTTNG_DOMAIN_JUL
+ <td>#LTTNG_EVENT_TRACEPOINT
+ <td>
+ <code>lttng_jul:event</code>
+
+ Such an event record has a string field <code>logger_name</code>
+ which contains the name of the <code>java.util.logging</code>
+ logger from which LTTng creates \lt_var{E}.
+ <tr>
+ <td>#LTTNG_DOMAIN_LOG4J
+ <td>#LTTNG_EVENT_TRACEPOINT
+ <td>
+ <code>lttng_log4j:event</code>
+
+ Such an event record has a string field <code>logger_name</code>
+ which contains the name of the Apache log4j logger from which
+ LTTng creates \lt_var{E}.
+ <tr>
+ <td>#LTTNG_DOMAIN_PYTHON
+ <td>#LTTNG_EVENT_TRACEPOINT
+ <td>
+ <code>lttng_python:event</code>
+
+ Such an event record has a string field <code>logger_name</code>
+ which contains the name of the Python logger from which LTTng
+ creates \lt_var{E}.
+ <tr>
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>#LTTNG_EVENT_SYSCALL
+ <td>
+ Location:
+
+ <dl>
+ <dt>Entry
+ <dd>
+ <code>syscall_entry_<em>NAME</em></code>, where
+ <code><em>NAME</em></code> is the name of the system call from
+ which LTTng creates \lt_var{E}, without any
+ <code>sys_</code> prefix.
+
+ <dt>Exit
+ <dd>
+ <code>syscall_exit_<em>NAME</em></code>, where
+ <code><em>NAME</em></code> is the name of the system call from
+ which LTTng creates \lt_var{E}, without any
+ <code>sys_</code> prefix.
+ </dl>
+ <tr>
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>#LTTNG_EVENT_PROBE or #LTTNG_EVENT_USERSPACE_PROBE
+ <td>
+ The lttng_event::name member of the
+ descriptor you used to create \lt_var{ER} with
+ lttng_enable_event_with_exclusions().
+ <tr>
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>#LTTNG_EVENT_FUNCTION
+ <td>
+ Location:
+
+ <dl>
+ <dt>Entry
+ <dd><code><em>NAME</em>_entry</code>
+
+ <dt>Exit
+ <dd><code><em>NAME</em>_exit</code>
+ </dl>
+
+ where <code><em>NAME</em></code> is the lttng_event::name member
+ of the descriptor you used to create
+ \lt_var{ER} with lttng_enable_event_with_exclusions().
+</table>
+
+@defgroup api_pais Process attribute inclusion set API
+@ingroup api_session
+
+To be done.
+
+@defgroup api_session_clear Recording session clearing API
+@ingroup api_session
+
+This API makes it possible to clear a \lt_obj_session, that is, to
+delete the contents of its tracing buffers and/or of all its
+\ref api-session-local-mode "local" and
+\ref api-session-net-mode "streamed" trace data.
+
+To clear a recording session:
+
+-# Call lttng_clear_session(), passing the name of the recording session
+ to clear.
+
+ This function initiates a clearing operation, returning immediately.
+
+ This function can set a pointer to a
+ \link #lttng_clear_handle clearing handle\endlink
+ so that you can wait for the completion of the
+ operation. Without such a handle, you can't know when the clearing
+ operation completes and whether or not it does successfully.
+
+-# <strong>If you have a clearing handle from step 1</strong>:
+
+ -# Call lttng_clear_handle_wait_for_completion() to wait for the
+ completion of the clearing operation.
+
+ -# Call lttng_clear_handle_get_result() to get whether or not the
+ clearing operation successfully completed.
+
+ -# Destroy the clearing handle with lttng_clear_handle_destroy().
+
+@sa \lt_man{lttng-clear,1}
+
+@defgroup api_session_snapshot Recording session snapshot API
+@ingroup api_session
+
+To be done.
+
+@defgroup api_session_rotation Recording session rotation API
+@ingroup api_session
+
+To be done.
+
+@defgroup api_session_save_load Recording session saving and loading API
+@ingroup api_session
+
+To be done.
+
+@defgroup api_inst_pt Instrumentation point listing API
+
+The lttng_list_tracepoints() and lttng_list_syscalls() functions set a
+pointer to an array of
+<strong><em>\ref api-rer-inst-pt-descr "instrumentation point descriptors"</em></strong>.
+
+With those two functions, you can get details about the available
+LTTng tracepoints, Java/Python loggers, and Linux kernel system calls,
+as long as you can
+\ref api-gen-sessiond-conn "connect to a session daemon".
+You can then use the discovered information to create corresponding
+\lt_obj_rers so that you can record the events
+which LTTng creates from instrumentation points.
+
+See \ref api_rer to learn more about instrumentation points, events,
+event records, and recording event rules.
+
+@defgroup api_trigger Trigger API
+
+To be done.
+
+@defgroup api_trigger_cond Trigger condition API
+@ingroup api_trigger
+
+To be done.
+
+@defgroup api_trigger_cond_er_matches "Event rule matches" trigger condition API
+@ingroup api_trigger_cond
+
+To be done.
+
+@defgroup api_er Event rule API
+@ingroup api_trigger_cond_er_matches
+
+To be done.
+
+@defgroup api_ll_rule Log level rule API
+@ingroup api_er
+
+To be done.
+
+@defgroup api_ev_expr Event expression API
+@ingroup api_trigger_cond_er_matches
+
+To be done.
+
+@defgroup api_ev_field_val Event field value API
+@ingroup api_trigger_cond_er_matches
+
+To be done.
+
+@defgroup api_trigger_action Trigger action API
+@ingroup api_trigger
+
+To be done.
+
+@defgroup api_notif Notification API
+@ingroup api_trigger_action
+
+To be done.
+
+@defgroup api_error Error query API
+
+To be done.
+*/
--- /dev/null
+.contents h1,
+.contents h2:not(.groupheader),
+.contents h3 {
+ color: #6A2F43;
+}
+
+.contents h1,
+.contents h2:not(.groupheader) {
+ border-bottom: 1px solid #ccc;
+ display: inline-block;
+}
+
+.contents h1 {
+ font-size: 1.5em;
+ margin-top: 2em;
+}
+
+.contents h2:not(.groupheader) {
+ font-size: 1.2em;
+ margin-top: 1.5em;
+}
+
+.contents dl {
+ margin-left: 2em;
+}
+
+.contents dl.params,
+.contents dl.section,
+.contents dl.retval,
+.contents dl.exception,
+.contents dl.tparams {
+ margin-left: 0;
+}
+
+.contents .image {
+ background-color: rgba(0, 0, 0, .05);
+ padding-top: 1em;
+ padding-bottom: 1em;
+}
+
+.contents .image img {
+ border: 1px solid #ccc;
+ background-color: white;
+ padding: 1em;
+}
+
+.contents .image .caption {
+ font-size: 75%;
+}
+
+.contents .fragment {
+ padding: 1em;
+}
+
+#projectname {
+ font-size: 200%;
+}
+
+#projectbrief {
+ display: none;
+}
+
+code.lt-param,
+table.params .paramname {
+ color: #602020;
+ font-weight: bold;
+ font-family: monospace;
+ font-size: 90%;
+}
+
+th > code.lt-param {
+ color: white;
+}
+
+.contents dl.attention {
+ background-color: #fbdfda;
+ padding-top: 1em;
+ padding-bottom: 1em;
+}
+
+.contents table.doxtable th {
+ background-color: #5173b3;
+}
+
+.contents table.doxtable td {
+ vertical-align: top;
+}
+
+.contents p.intertd {
+ font-weight: normal;
+}
+
+.contents td > code:not(.lt-param),
+.contents p > code:not(.lt-param),
+.contents dt > code:not(.lt-param),
+.contents dd > code:not(.lt-param),
+.contents li > code:not(.lt-param) {
+ background-color: rgba(0, 0, 0, .05);
+ padding-left: .2em;
+ padding-right: .2em;
+ border-radius: .25em;
+ border: .1em solid rgba(0, 0, 0, .1)
+}
+
+.contents .lt-var {
+ font-style: italic;
+ font-family: serif;
+ font-size: 1.1em;
+}
* The structures should be initialized to zero before use.
*/
#define LTTNG_CHANNEL_ATTR_PADDING1 LTTNG_SYMBOL_NAME_LEN + 12
+
+/*!
+@brief
+ Attributes of a \link #lttng_channel channel summary\endlink.
+
+@ingroup api_channel
+
+The lttng_channel::attr member is an instance of such a structure.
+
+lttng_channel_set_default_attr() sets the members of such a structure
+to their default values given a specific \lt_obj_domain summary.
+
+\anchor api-channel-valid-attr-struct A \em valid #lttng_channel_attr
+structure satisfies the following constraints:
+
+<table>
+ <tr>
+ <th>Member
+ <th>Constraints
+ <tr>
+ <td>lttng_channel_attr::overwrite
+ <td>0, 1, or -1
+ <tr>
+ <td>lttng_channel_attr::subbuf_size
+ <td>
+ - Greater than 0
+ - Power of two
+ <tr>
+ <td>lttng_channel_attr::num_subbuf
+ <td>
+ - Greater than 0
+ - Power of two
+</table>
+*/
struct lttng_channel_attr {
+ /*!
+ @brief
+ \ref api-channel-er-loss-mode "Event record loss mode".
+
+ One of:
+
+ <dl>
+ <dt>0
+ <dd>
+ The \ref api-channel-er-loss-mode "event record loss mode"
+ of the channel is
+ <em>\ref api-channel-discard-mode "discard"</em>.
+
+ <dt>1
+ <dd>
+ The event record loss mode of the channel is
+ <em>\ref api-channel-overwrite-mode "overwrite"</em>.
+
+ <dt>-1
+ <dd>
+ The event record loss mode of the channel is the default
+ value of its \lt_obj_session:
+
+ <dl>
+ <dt>\ref api-session-snapshot-mode "Snapshot mode"
+ <dd>Overwrite mode
+
+ <dt>Other modes
+ <dd>Discard mode
+ </dl>
+ </dl>
+ */
int overwrite; /* -1: session default, 1: overwrite, 0: discard */
+
+ /*!
+ @brief
+ \ref api-channel-sub-buf-size-count "Sub-buffer size"
+ (bytes).
+ */
uint64_t subbuf_size; /* bytes, power of 2 */
+
+ /*!
+ @brief
+ \ref api-channel-sub-buf-size-count "Sub-buffer count".
+ */
uint64_t num_subbuf; /* power of 2 */
+
+ /*!
+ @brief
+ \ref api-channel-switch-timer "Switch timer period" (µs),
+ if applicable.
+
+ Only available if the \lt_obj_session which
+ owns this channel is \em not in
+ \ref api-session-live-mode "live mode".
+ */
unsigned int switch_timer_interval; /* usec */
+
+ /// \ref api-channel-read-timer "Read timer period" (µs).
unsigned int read_timer_interval; /* usec */
+
+ /// Output type (Linux kernel channel).
enum lttng_event_output output; /* splice, mmap */
+
/* LTTng 2.1 padding limit */
+
+ /*!
+ @brief
+ \ref api-channel-max-trace-file-size-count "Maximum trace file size"
+ (bytes), or 0 for unlimited.
+ */
uint64_t tracefile_size; /* bytes */
+
+ /*!
+ @brief
+ \ref api-channel-max-trace-file-size-count "Maximum trace file count",
+ or 0 for unlimited.
+ */
uint64_t tracefile_count; /* number of tracefiles */
+
/* LTTng 2.3 padding limit */
+
+ /*!
+ @brief
+ \ref api-channel-live-timer "Live timer period" (µs), if
+ applicable.
+
+ You may \em not set this member: use the
+ \lt_p{live_timer_period} parameter of
+ lttng_session_descriptor_live_network_create() when you create
+ the descriptor of a \ref api-session-live-mode "live" recording
+ session to contain the channel to create.
+
+ Only available if the \lt_obj_session which
+ owns this channel is in \ref api-session-live-mode "live mode".
+ */
unsigned int live_timer_interval; /* usec */
+
/* LTTng 2.7 padding limit */
uint32_t align_to_64;
union {
* The structures should be initialized to zero before use.
*/
#define LTTNG_CHANNEL_PADDING1 16
+
+/*!
+@brief
+ \lt_obj_c_channel summary.
+
+@ingroup api_channel
+
+The purpose of such a structure is to provide information about a
+channel itself, but not about its \lt_obj_rers
+(use lttng_list_events() for this).
+
+lttng_list_channels() sets a pointer to an array of all the
+channel summaries of a given \lt_obj_session and \lt_obj_domain.
+
+Most properties are part of the lttng_channel::attr member, but the
+following ones have their own dedicated accessors:
+
+<dl>
+ <dt>\ref api-channel-monitor-timer "Monitor timer" period
+ <dd>
+ - lttng_channel_get_monitor_timer_interval()
+ - lttng_channel_set_monitor_timer_interval()
+
+ <dt>\ref api-channel-blocking-timeout "Blocking timeout"
+ <dd>
+ - lttng_channel_get_blocking_timeout()
+ - lttng_channel_set_blocking_timeout()
+</dl>
+
+Create a channel summary with lttng_channel_create().
+
+Destroy a channel summary with lttng_channel_destroy().
+*/
struct lttng_channel {
+ /// Name.
char name[LTTNG_SYMBOL_NAME_LEN];
+
+ /*!
+ @brief
+ 1 if this \lt_obj_channel is enabled, or 0 otherwise.
+
+ @sa lttng_enable_channel() --
+ Creates or enables a channel.
+ @sa lttng_disable_channel() --
+ Disables a channel.
+ */
uint32_t enabled;
+
+ /// Other properties.
struct lttng_channel_attr attr;
char padding[LTTNG_CHANNEL_PADDING1];
};
-/*
- */
+/*!
+@brief
+ Creates and returns a \lt_obj_channel summary,
+ setting the members of its lttng_channel::attr member to default
+ values according to the \lt_obj_domain summary \lt_p{domain}.
+
+@ingroup api_channel
+
+This function internally calls
+
+@code
+lttng_channel_set_default_attr(domain, &channel->attr);
+@endcode
+
+where \c channel is the returned channel summary.
+
+After you create a channel summary with this function, you can modify
+its \ref api-channel-channel-props "properties" and call
+lttng_enable_channel() to create and enable a channel.
+
+@param[in] domain
+ Tracing domain summary to consider to set the members of the
+ lttng_channel::attr member of the returned structure to default
+ values.
+
+@returns
+ @parblock
+ New channel summary.
+
+ Destroy the returned channel summary with lttng_channel_destroy().
+ @endparblock
+
+@lt_pre_not_null{domain}
+
+@sa lttng_channel_destroy() --
+ Destroys a channel summary.
+*/
LTTNG_EXPORT extern struct lttng_channel *lttng_channel_create(struct lttng_domain *domain);
-/*
- */
+/*!
+@brief
+ Destroys the \lt_obj_channel summary \lt_p{channel}.
+
+@ingroup api_channel
+
+@note
+ This function doesn't destroy the \lt_obj_channel
+ which \lt_p{channel} summarizes: the only way to destroy a channel
+ is to \link lttng_destroy_session_ext() destroy its recording
+ session\endlink.
+
+@param[in] channel
+ @parblock
+ Channel summary to destroy.
+
+ May be \c NULL.
+ @endparblock
+*/
LTTNG_EXPORT extern void lttng_channel_destroy(struct lttng_channel *channel);
-/*
- * List the channel(s) of a session.
- *
- * The handle CAN NOT be NULL.
- *
- * Return the size (number of entries) of the "lttng_channel" array. Caller
- * must free channels. On error, a negative LTTng error code is returned.
- */
+/*!
+@brief
+ Sets \lt_p{*channels} to the summaries of the
+ \lt_obj_channels of the recording session handle \lt_p{handle}.
+
+@ingroup api_session
+
+@param[in] handle
+ Recording session handle which contains the name of the recording
+ session and the summary of the \lt_obj_domain which own the channels
+ of which to get the summaries.
+@param[out] channels
+ @parblock
+ <strong>On success</strong>, this function sets \lt_p{*channels} to
+ the summaries of the channels.
+
+ Free \lt_p{*channels} with <code>free()</code>.
+ @endparblock
+
+@returns
+ The number of items in \lt_p{*channels} on success, or a \em
+ negative #lttng_error_code enumerator otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{handle}
+@lt_pre_valid_c_str{handle->session_name}
+@lt_pre_sess_exists{handle->session_name}
+@pre
+ \lt_p{handle->domain} is valid as per the documentation of
+ #lttng_domain.
+@lt_pre_not_null{channels}
+*/
LTTNG_EXPORT extern int lttng_list_channels(struct lttng_handle *handle,
struct lttng_channel **channels);
-/*
- * Create or enable a channel.
- *
- * The chan and handle params can not be NULL.
- *
- * Return 0 on success else a negative LTTng error code.
- */
+/*!
+@brief
+ Creates or enables a \lt_obj_channel summarized by \lt_p{channel}
+ within the recording session handle \lt_p{handle}.
+
+@ingroup api_channel
+
+This function, depending on \lt_p{channel->name}:
+
+<dl>
+ <dt>
+ \lt_p{channel->name} names an existing
+ channel within the \lt_obj_session and
+ \lt_obj_domain of \lt_p{handle}
+ <dd>
+ Enables the existing channel.
+
+ In this case, this function only uses \lt_p{channel->name}, ignoring
+ all the other properties of \lt_p{channel}.
+
+ <dt>Otherwise
+ <dd>
+ Creates and enables a new channel, considering all the properties of
+ \lt_p{channel}.
+</dl>
+
+@param[in] handle
+ Recording session handle which contains the name of the
+ recording session and the summary of the \lt_obj_domain which own
+ the channel to create or enable.
+@param[in] channel
+ Summary of the channel to create or enable.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{handle}
+@lt_pre_valid_c_str{handle->session_name}
+@lt_pre_sess_exists{handle->session_name}
+@pre
+ \lt_p{handle->domain} is valid as per the documentation of
+ #lttng_domain.
+@lt_pre_not_null{channel}
+@pre
+ <strong>If this function must create a new channel</strong>, then
+ \lt_p{channel->attr} is \ref api-channel-valid-attr-struct "valid".
+@pre
+ <strong>If this function must create a new channel</strong>, then
+ \lt_p{handle->session_name} names a
+ \lt_obj_session which never became
+ \link lttng_session::enabled active\endlink (started) since its
+ creation.
+@pre
+ <strong>If this function must create a new channel</strong>, then
+ all the existing channels of \lt_p{handle} have the same
+ \ref api-channel-buf-scheme "buffering scheme".
+
+@sa lttng_disable_channel() --
+ Disables a channel.
+*/
LTTNG_EXPORT extern int lttng_enable_channel(struct lttng_handle *handle,
- struct lttng_channel *chan);
+ struct lttng_channel *channel);
-/*
- * Disable channel.
- *
- * Name and handle CAN NOT be NULL.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-LTTNG_EXPORT extern int lttng_disable_channel(struct lttng_handle *handle, const char *name);
+/*!
+@brief
+ Disables the \lt_obj_channel named \lt_p{channel_name} within the
+ recording session handle \lt_p{handle}.
-/*
- * Set the default channel attributes for a specific domain and an allocated
- * lttng_channel_attr pointer.
- *
- * If one or both arguments are NULL, nothing happens.
- */
+@ingroup api_channel
+
+@param[in] handle
+ Recording session handle which contains the name of the
+ recording session and the summary of the \lt_obj_domain which own
+ the channel to disable.
+@param[in] channel_name
+ Name of the channel to disable within \lt_p{handle}.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{handle}
+@lt_pre_valid_c_str{handle->session_name}
+@lt_pre_sess_exists{handle->session_name}
+@pre
+ \lt_p{handle->domain} is valid as per the documentation of
+ #lttng_domain.
+@lt_pre_not_null{channel_name}
+@pre
+ \lt_p{channel_name} names an existing channel within the recording
+ session and tracing domain of \lt_p{handle}.
+
+@sa lttng_enable_channel() --
+ Creates or enables a channel.
+*/
+LTTNG_EXPORT extern int lttng_disable_channel(struct lttng_handle *handle,
+ const char *channel_name);
+
+/*!
+@brief
+ Sets the members of \lt_p{attr} to their default values considering
+ the \lt_obj_domain summary \lt_p{domain}.
+
+@ingroup api_channel
+
+Use this function on an lttng_channel::attr member.
+
+@param[in] domain
+ Tracing domain summary to consider to set the members of \lt_p{attr}
+ to their default values.
+@param[in] attr
+ Structure of which to set the members to their default values.
+
+@lt_pre_not_null{domain}
+@lt_pre_not_null{attr}
+*/
LTTNG_EXPORT extern void lttng_channel_set_default_attr(struct lttng_domain *domain,
struct lttng_channel_attr *attr);
-/*
- * Get the discarded event count of a specific LTTng channel.
- *
- * Returns 0 on success, or a negative LTTng error code on error.
- */
-LTTNG_EXPORT extern int lttng_channel_get_discarded_event_count(struct lttng_channel *chan,
- uint64_t *discarded_events);
+/*!
+@brief
+ Sets \lt_p{*count} to the number of discarded event
+ records of the \lt_obj_channel summarized by \lt_p{channel}.
-/*
- * Get the lost packet count of a specific LTTng channel.
- *
- * Returns 0 on success, or a negative LTTng error code on error.
- */
-LTTNG_EXPORT extern int lttng_channel_get_lost_packet_count(struct lttng_channel *chan,
- uint64_t *lost_packets);
+@ingroup api_channel
+
+In \ref api-channel-discard-mode "discard mode", LTTng discards an event
+record when there's no sub-buffer left to write it.
+
+lttng_list_channels() sets a pointer to an array of all the
+channel summaries of a given \lt_obj_session and \lt_obj_domain.
+
+@param[in] channel
+ Summary of the channel of which to get the number of discarded
+ event records.
+@param[out] count
+ <strong>On success</strong>, this function sets \lt_p{*count} to
+ the number of discarded event records of the channel summarized
+ by \lt_p{channel}.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_not_null{channel}
+@pre
+ You obtained \lt_p{channel} with lttng_list_channels().
+@pre
+ The lttng_channel_attr::overwrite member of \lt_p{channel->attr}
+ is 0.
+@lt_pre_not_null{count}
+
+@sa lttng_channel_get_lost_packet_count() --
+ Returns the number of discarded packets (sub-buffers) of a channel.
+*/
+LTTNG_EXPORT extern int lttng_channel_get_discarded_event_count(struct lttng_channel *channel,
+ uint64_t *count);
+
+/*!
+@brief
+ Sets \lt_p{*count} to the number of discarded packets (sub-buffers)
+ of the \lt_obj_channel summarized by \lt_p{channel}.
+
+@ingroup api_channel
+
+In \ref api-channel-overwrite-mode "overwrite mode", LTTng discards a
+whole sub-buffer when there's no sub-buffer left to record an event.
+
+lttng_list_channels() sets a pointer to an array of all the
+channel summaries of a given \lt_obj_session and \lt_obj_domain.
+
+@param[in] channel
+ Summary of the channel of which to get the number of discarded
+ packets.
+@param[out] count
+ <strong>On success</strong>, this function sets \lt_p{*count} to
+ the number of discarded packets of the channel summarized
+ by \lt_p{channel}.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_not_null{channel}
+@pre
+ You obtained \lt_p{channel} with lttng_list_channels().
+@pre
+ The lttng_channel_attr::overwrite member of \lt_p{channel->attr}
+ is 1.
+@lt_pre_not_null{count}
+
+@sa lttng_channel_get_discarded_event_count() --
+ Returns the number of discarded event records of a channel.
+*/
+LTTNG_EXPORT extern int lttng_channel_get_lost_packet_count(struct lttng_channel *channel,
+ uint64_t *count);
+
+/*!
+@brief
+ Sets \lt_p{period} to the
+ \ref api-channel-monitor-timer "monitor timer" period (µs)
+ property of the \lt_obj_channel summary \lt_p{channel}.
+
+@ingroup api_channel
+
+@param[in] channel
+ Summary of the channel of which to get the monitor timer period.
+@param[out] period
+ <strong>On success</strong>, this function sets \lt_p{*period} to
+ the monitor timer period (µs) property of \lt_p{channel}.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_not_null{channel}
+@lt_pre_not_null{period}
+
+@sa lttng_channel_set_monitor_timer_interval() --
+ Sets the monitor timer period property of a channel summary.
+*/
+LTTNG_EXPORT extern int lttng_channel_get_monitor_timer_interval(struct lttng_channel *channel,
+ uint64_t *period);
+
+/*!
+@brief
+ Sets the \ref api-channel-monitor-timer "monitor timer" period
+ property of the channel summary \lt_p{channel} to
+ \lt_p{period} µs.
+
+@ingroup api_channel
+
+@param[in] channel
+ Channel summary of which to set the monitor timer period
+ to \lt_p{period} µs.
+@param[in] period
+ Monitor timer period property to set.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_not_null{channel}
+@pre
+ \lt_p{period} ≥ 1
+
+@sa lttng_channel_get_monitor_timer_interval() --
+ Returns the monitor timer period property of a channel summary.
+*/
+LTTNG_EXPORT extern int lttng_channel_set_monitor_timer_interval(struct lttng_channel *channel,
+ uint64_t period);
+
+/*!
+@brief
+ Sets \lt_p{timeout} to the
+ \ref api-channel-blocking-timeout "blocking timeout"
+ property of the \lt_obj_channel summary \lt_p{channel}.
+
+@ingroup api_channel
+
+This property only applies to \link #LTTNG_DOMAIN_UST user space\endlink
+channels.
+
+@param[in] channel
+ Summary of the channel of which to get the blocking timeout.
+@param[out] timeout
+ @parblock
+ <strong>On success</strong>, this function sets \lt_p{*timeout} to
+ one of:
+
+ <dl>
+ <dt>-1
+ <dd>
+ The blocking timeout of \lt_p{channel} is infinite.
+
+ <dt>0
+ <dd>
+ Blocking is disabled for \lt_p{channel}.
+
+ <dt>Otherwise
+ <dd>
+ The blocking timeout of \lt_p{channel} is
+ \lt_p{*timeout} µs.
+ </dl>
+ @endparblock
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_not_null{channel}
+@pre
+ The \lt_obj_domain type of \lt_p{channel} is #LTTNG_DOMAIN_UST.
+@lt_pre_not_null{timeout}
+
+@sa lttng_channel_set_blocking_timeout() --
+ Sets the blocking timeout property of a channel summary.
+*/
+LTTNG_EXPORT extern int lttng_channel_get_blocking_timeout(struct lttng_channel *channel,
+ int64_t *timeout);
+
+/*!
+@brief
+ Sets the \ref api-channel-blocking-timeout "blocking timeout"
+ property of the channel summary \lt_p{channel} to
+ \lt_p{timeout}.
+
+@ingroup api_channel
+
+This property only applies to \link #LTTNG_DOMAIN_UST user space\endlink
+channels.
+
+@param[in] channel
+ Channel summary of which to set the blocking timeout
+ to \lt_p{timeout}.
+@param[in] timeout
+ @parblock
+ One of:
+
+ <dl>
+ <dt>-1
+ <dd>
+ The blocking timeout of \lt_p{channel} is infinite.
+
+ <dt>0
+ <dd>
+ Blocking is disabled for \lt_p{channel}.
-LTTNG_EXPORT extern int lttng_channel_get_monitor_timer_interval(struct lttng_channel *chan,
- uint64_t *monitor_timer_interval);
+ <dt>Otherwise
+ <dd>
+ The blocking timeout of \lt_p{channel} is
+ \lt_p{timeout} µs.
+ </dl>
+ @endparblock
-LTTNG_EXPORT extern int lttng_channel_set_monitor_timer_interval(struct lttng_channel *chan,
- uint64_t monitor_timer_interval);
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
-LTTNG_EXPORT extern int lttng_channel_get_blocking_timeout(struct lttng_channel *chan,
- int64_t *blocking_timeout);
+@lt_pre_not_null{channel}
+@pre
+ The \lt_obj_domain type of \lt_p{channel} is #LTTNG_DOMAIN_UST.
+@pre
+ \lt_p{timeout} ≥ -1
-LTTNG_EXPORT extern int lttng_channel_set_blocking_timeout(struct lttng_channel *chan,
- int64_t blocking_timeout);
+@sa lttng_channel_get_blocking_timeout() --
+ Returns the blocking timeout property of a channel summary.
+*/
+LTTNG_EXPORT extern int lttng_channel_set_blocking_timeout(struct lttng_channel *channel,
+ int64_t timeout);
#ifdef __cplusplus
}
extern "C" {
#endif
-/*
- * Handle used to represent a specific instance of session clear
- * operation.
- */
+/*!
+@addtogroup api_session_clear
+@{
+*/
+
+/*!
+@struct lttng_clear_handle
+
+@brief
+ \lt_obj_c_session clearing handle (opaque type).
+*/
struct lttng_clear_handle;
-/*
- * Negative values indicate errors. Values >= 0 indicate success.
- */
+/*!
+@brief
+ Return type of \lt_obj_session clearing handle functions.
+
+Error status enumerators have a negative value.
+*/
enum lttng_clear_handle_status {
- LTTNG_CLEAR_HANDLE_STATUS_ERROR = -2,
- LTTNG_CLEAR_HANDLE_STATUS_INVALID = -1,
+ /// Success.
LTTNG_CLEAR_HANDLE_STATUS_OK = 0,
+
+ /// Recording session clearing operation completed.
LTTNG_CLEAR_HANDLE_STATUS_COMPLETED = 1,
+
+ /// Timeout reached.
LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT = 2,
+
+ /// Unsatisfied precondition.
+ LTTNG_CLEAR_HANDLE_STATUS_INVALID = -1,
+
+ /// Other error.
+ LTTNG_CLEAR_HANDLE_STATUS_ERROR = -2,
};
-/*
- * Destroy an lttng_clear_handle.
- * The handle should be discarded after this call.
- */
+/*!
+@brief
+ Destroys the \lt_obj_session clearing handle \lt_p{handle}.
+
+@param[in] handle
+ @parblock
+ Recording session clearing handle to destroy.
+
+ May be \c NULL.
+ @endparblock
+*/
LTTNG_EXPORT extern void lttng_clear_handle_destroy(struct lttng_clear_handle *handle);
-/*
- * Wait for a session clear operation to complete.
- *
- * A negative timeout_ms value can be used to wait indefinitely.
- *
- * Returns LTTNG_CLEAR_HANDLE_STATUS_COMPLETED if the session clear
- * operation was completed. LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT is returned
- * to indicate that the wait timed out.
- * On error, one of the negative lttng_clear_handle_status is returned.
- *
- * Note: This function returning a success status does not mean that
- * the clear operation itself succeeded; it indicates that the _wait_
- * operation completed successfully.
- */
+/*!
+@brief
+ Waits for the \lt_obj_session clearing operation identified by
+ \lt_p{handle} to complete.
+
+If this function returns #LTTNG_CLEAR_HANDLE_STATUS_COMPLETED, then the
+recording session clearing operation identified by \lt_p{handle}
+completed. This doesn't mean, however, that the clearing operation
+itself succeeded; use lttng_clear_handle_get_result() to know this.
+
+@param[in] handle
+ Recording session clearing handle which identifies the clearing
+ operation of which to wait for completion.
+@param[in] timeout_ms
+ Maximum time (milliseconds) to wait for the completion of the
+ recording session clearing operation identified by \lt_p{handle}
+ before returning #LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT, or
+ <code>-1</code> to wait indefinitely.
+
+@retval #LTTNG_CLEAR_HANDLE_STATUS_COMPLETED
+ The recording session clearing operation identified by \lt_p{handle}
+ completed (with or without success).
+@retval #LTTNG_CLEAR_HANDLE_STATUS_INVALID
+ Unsatisfied precondition.
+@retval #LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT
+ The function waited for the completion of the recording session
+ clearing operation for more than \lt_p{timeout_ms} ms.
+@retval #LTTNG_CLEAR_HANDLE_STATUS_ERROR
+ Other error.
+
+@lt_pre_not_null{handle}
+
+@sa lttng_clear_handle_get_result() --
+ Returns whether or not a recording session clearing operation
+ succeeded.
+*/
LTTNG_EXPORT extern enum lttng_clear_handle_status
lttng_clear_handle_wait_for_completion(struct lttng_clear_handle *handle, int timeout_ms);
-/*
- * Get the result of a session clear operation.
- *
- * This function must be used on a clear handle which was successfully waited
- * on.
- *
- * Returns LTTNG_CLEAR_HANDLE_STATUS_OK if the result of the session
- * clear operation could be obtained. Check the value of 'result' to
- * determine if the session clear operation completed successfully or not.
- *
- * On error, one of the negative lttng_clear_handle_status is returned.
- * Returns LTTNG_CLEAR_HANDLE_STATUS_INVALID if the clear operation
- * was not waited-on using the handle or if the arguments of the function are
- * invalid (e.g. NULL).
- */
+/*!
+@brief
+ Sets \lt_p{*result} to the result of the \lt_obj_session clearing
+ operation identified by \lt_p{handle}.
+
+You must successfully wait for the completion of the recording session
+clearing operation identified by \lt_p{handle} with
+lttng_clear_handle_wait_for_completion() before you call this function.
+
+On success, \lt_p{*result} is #LTTNG_OK if the clearing operation was
+successful.
+
+@param[in] handle
+ Handle of the recording session clearing operation of which to get
+ the result.
+@param[out] result
+ @parblock
+ <strong>On success</strong>, this function sets \lt_p{*result} to
+ the result of the recording session clearing operation identified by
+ \lt_p{handle}.
+
+ \lt_p{*result} is #LTTNG_OK if the clearing operation was
+ successful.
+ @endparblock
+
+@retval #LTTNG_CLEAR_HANDLE_STATUS_OK
+ Success: \lt_p{*result} is the result of the recording session
+ clearing operation identified by \lt_p{handle}.
+@retval #LTTNG_CLEAR_HANDLE_STATUS_INVALID
+ Unsatisfied precondition.
+@retval #LTTNG_CLEAR_HANDLE_STATUS_ERROR
+ Other error.
+
+@lt_pre_not_null{handle}
+@pre
+ You successfully waited for the completion of the recording session
+ clearing operation identified by \lt_p{handle} with
+ lttng_clear_handle_wait_for_completion().
+@lt_pre_not_null{result}
+
+@sa lttng_clear_handle_wait_for_completion() --
+ Waits for a recording session clearing operation to complete.
+*/
LTTNG_EXPORT extern enum lttng_clear_handle_status
lttng_clear_handle_get_result(const struct lttng_clear_handle *handle,
enum lttng_error_code *result);
+
+/// @}
+
#ifdef __cplusplus
}
#endif
extern "C" {
#endif
+/*!
+@addtogroup api_session_clear
+@{
+*/
+
struct lttng_clear_handle;
-/*
- * Clear a tracing session.
- *
- * Clear the data buffers and trace data.
- *
- * For sessions saving trace data to disk and streaming over the network to a
- * relay daemon, the buffers content and existing stream files are cleared when
- * the clear command is issued.
- *
- * For snapshot sessions (flight recorder), only the buffer content is cleared.
- * Prior snapshots are individually recorded to disk, and are therefore
- * untouched by this "clear" command.
- *
- * For live sessions streaming over network to a relay daemon, the buffers
- * will be cleared and the files on the relay daemon side will be cleared as
- * well. However, any active live trace viewer currently reading an existing
- * trace packet will be able to proceed to read that packet entirely before
- * skipping over cleared stream data.
- *
- * The clear command guarantees that no trace data produced before this function
- * is called will be present in the resulting trace.
- *
- * Trace data produced between the moment this function is called and when it
- * returns might be present in the resulting trace.
- *
- * Provides an lttng_clear_handle which can be used to wait for the completion
- * of the session's clear.
- *
- * Return LTTNG_OK on success else a negative LTTng error code. The returned
- * handle is owned by the caller and must be free'd using
- * lttng_clear_handle_destroy().
- *
- * Important error codes:
- * LTTNG_ERR_CLEAR_RELAY_DISALLOWED
- * LTTNG_ERR_CLEAR_NOT_AVAILABLE_RELAY
- * LTTNG_ERR_CLEAR_FAIL_CONSUMER
- */
+/*!
+@brief
+ Initiates a clearing operation of the \lt_obj_session
+ named \lt_p{session_name}.
+
+Depending on the mode of the recording session \lt_var{RS}
+named \lt_p{session_name}, the clearing operation attempts to:
+
+<dl>
+ <dt>\ref api-session-local-mode "Local"
+ <dt>\ref api-session-net-mode "Network streaming"
+ <dd>
+ Delete the contents of the recording buffers of \lt_var{RS}.
+
+ Delete the local/remote data stream files of \lt_var{RS}.
+
+ <dt>\ref api-session-snapshot-mode "Snapshot"
+ <dd>
+ Delete the contents of the recording buffers of \lt_var{RS}.
+
+ LTTng doesn't touch prior snapshots of \lt_var{RS}.
+
+ <dt>\ref api-session-live-mode "Live"
+ <dd>
+ Delete the contents of the recording buffers of \lt_var{RS}.
+
+ Delete the remote data stream files of \lt_var{RS}.
+
+ Any active live reader currently reading a data stream packet
+ may continue to read said packet completely.
+</dl>
+
+The clearing operation which this function initiates, if successful,
+guarantees that any trace data which LTTng produced \em before you call
+this function won't be part of any trace, except:
+
+- Preexisting recording session
+ \ref api_session_snapshot "snapshots".
+- Preexisting
+ \ref api_session_rotation "trace chunk archives".
+
+It's possible that trace data which LTTng produces while you're calling
+this function makes it to a trace.
+
+Use \lt_p{*handle} to wait for the completion of the recording session
+clearing operation.
+
+@param[in] session_name
+ Name of the recording session to clear.
+@param[out] handle
+ @parblock
+ <strong>On success</strong>, this function sets \lt_p{*handle} to
+ a handle which identifies this recording session clearing operation.
+
+ May be \c NULL.
+
+ Wait for the completion of this clearing operation with
+ lttng_clear_handle_wait_for_completion().
+
+ Destroy \lt_p{*handle} with lttng_clear_handle_destroy().
+ @endparblock
+
+@returns
+ @parblock
+ #LTTNG_OK on success, or a \em negative enumerator otherwise.
+
+ Notable return values:
+
+ <table>
+ <tr>
+ <td>-#LTTNG_ERR_CLEAR_RELAY_DISALLOWED
+ <td>
+ The relay daemon doesn't allow recording session clearing
+ operations.
+ <tr>
+ <td>-#LTTNG_ERR_CLEAR_NOT_AVAILABLE_RELAY
+ <td>
+ The relay daemon doesn't support the recording session
+ clearing operation.
+ <tr>
+ <td>-#LTTNG_ERR_CLEAR_FAIL_CONSUMER
+ <td>
+ A consumer daemon failed to clear the recording session named
+ \lt_p{session_name}.
+ </table>
+ @endparblock
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+@pre
+ No clearing operation is in progress for the recording session named
+ \lt_p{session_name}.
+*/
LTTNG_EXPORT extern enum lttng_error_code lttng_clear_session(const char *session_name,
struct lttng_clear_handle **handle);
+
+/// @}
+
#ifdef __cplusplus
}
#endif
/*
* Event symbol length. Copied from LTTng kernel ABI.
*/
+
+/*!
+@brief
+ Maximum symbol length.
+
+@ingroup api_gen
+*/
#define LTTNG_SYMBOL_NAME_LEN 256
/*
#define LTTNG_MAX_PID INT32_MAX
#define LTTNG_MAX_PID_STR "2147483647"
+/*!
+@brief
+ Maximum name length.
+
+@ingroup api_gen
+*/
#define LTTNG_NAME_MAX 255
/*
extern "C" {
#endif
-/*
- * Handle used to represent a specific instance of session destruction
- * operation.
- *
- * See lttng_destroy_session_ext() in lttng/session.h.
- */
+/*!
+@addtogroup api_session_destr_handle
+@{
+*/
+
+/*!
+@struct lttng_destruction_handle
+
+@brief
+ Recording session destruction handle (opaque type).
+*/
struct lttng_destruction_handle;
-/*
- * Negative values indicate errors. Values >= 0 indicate success.
- */
+/*!
+@brief
+ Return type of recording session destruction handle fuctions.
+
+Error status enumerators have a negative value.
+*/
enum lttng_destruction_handle_status {
- /* Generic error. */
- LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR = -2,
- /* Invalid parameters provided */
- LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID = -1,
- /* Success. */
+ /// Success.
LTTNG_DESTRUCTION_HANDLE_STATUS_OK = 0,
- /* Destruction operation completed successfully. */
+
+ /// Recording session destruction operation completed.
LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED = 1,
- /* Operation timed out. */
+
+ /// Timeout reached.
LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT = 2,
+
+ /// Unsatisfied precondition.
+ LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID = -1,
+
+ /// Other error.
+ LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR = -2,
};
-/*
- * Destroy an lttng_destruction_session handle.
- * The handle should be discarded after this call.
- */
+/*!
+@brief
+ Destroys the recording session destruction handle \lt_p{handle}.
+
+@param[in] handle
+ @parblock
+ Recording session destruction handle to destroy.
+
+ May be \c NULL.
+ @endparblock
+*/
LTTNG_EXPORT extern void lttng_destruction_handle_destroy(struct lttng_destruction_handle *handle);
-/*
- * Wait for the destruction of a session to complete.
- *
- * A negative timeout_ms value can be used to wait indefinitely.
- *
- * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED if the session destruction
- * operation was completed. LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT is returned
- * to indicate that the wait timed out.
- * On error, one of the negative lttng_destruction_handle_status is returned.
- *
- * Note: This function returning a success status does not mean that
- * the destruction operation itself succeeded; it indicates that the _wait_
- * operation completed successfully.
- */
+/*!
+@brief
+ Waits for the recording session destruction operation identified by
+ \lt_p{handle} to complete.
+
+If this function returns #LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED,
+then the recording session destruction operation identified by
+\lt_p{handle} completed. This doesn't mean, however, that the
+destruction operation itself succeeded; use
+lttng_destruction_handle_get_result() to know this.
+
+@param[in] handle
+ Recording session destruction handle which identifies the
+ destruction operation of which to wait for completion.
+@param[in] timeout_ms
+ Maximum time (milliseconds) to wait for the completion of the
+ recording session destruction operation identified by \lt_p{handle}
+ before returning #LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT, or
+ <code>-1</code> to wait indefinitely.
+
+@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED
+ The recording session destruction operation identified by
+ \lt_p{handle} completed (with or without success).
+@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
+ Unsatisfied precondition.
+@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT
+ The function waited for the completion of the recording session
+ destruction operation for more than \lt_p{timeout_ms} ms.
+@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
+ Other error.
+
+@lt_pre_not_null{handle}
+
+@sa lttng_destruction_handle_get_result() --
+ Returns whether or not a recording session destruction operation
+ succeeded.
+*/
LTTNG_EXPORT extern enum lttng_destruction_handle_status
lttng_destruction_handle_wait_for_completion(struct lttng_destruction_handle *handle,
int timeout_ms);
-/*
- * Get the result of a session destruction operation.
- *
- * This function must be used on a session destruction handle which was
- * successfully waited on.
- *
- * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_OK if the result of the session
- * destruction operation could be obtained. Check the value of 'result' to
- * determine if the destruction of the session completed successfully or not.
- *
- * On error, one of the negative lttng_destruction_handle_status is returned.
- * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID if the session destruction
- * was not waited-on using the handle or if the arguments of the function are
- * invalid (e.g. NULL).
- */
+/*!
+@brief
+ Sets \lt_p{*result} to the result of the recording session
+ destruction operation identified by \lt_p{handle}.
+
+You must successfully wait for the completion of the recording session
+destruction operation identified by \lt_p{handle} with
+lttng_destruction_handle_wait_for_completion() before you call this function.
+
+On success, \lt_p{*result} is #LTTNG_OK if the destruction operation was
+successful.
+
+@param[in] handle
+ Handle of the recording session destruction operation of which to
+ get the result.
+@param[out] result
+ @parblock
+ <strong>On success</strong>, this function sets \lt_p{*result} to
+ the result of the recording session destruction operation identified
+ by \lt_p{handle}.
+
+ \lt_p{*result} is #LTTNG_OK if the destruction operation was
+ successful.
+ @endparblock
+
+@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_OK
+ Success: \lt_p{*result} is the result of the recording session
+ destruction operation identified by \lt_p{handle}.
+@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
+ Unsatisfied precondition.
+@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
+ Other error.
+
+@lt_pre_not_null{handle}
+@pre
+ You successfully waited for the completion of the recording session
+ destruction operation identified by \lt_p{handle} with
+ lttng_destruction_handle_wait_for_completion().
+@lt_pre_not_null{result}
+
+@sa lttng_destruction_handle_wait_for_completion() --
+ Waits for a recording session destruction operation to complete.
+*/
LTTNG_EXPORT extern enum lttng_destruction_handle_status
lttng_destruction_handle_get_result(const struct lttng_destruction_handle *handle,
enum lttng_error_code *result);
-/*
- * Get the status of the session rotation performed as part of the session's
- * destruction.
- *
- * A session will perform a final rotation if it was ever rotated over its
- * lifetime. If this happens, this function returns the state of the rotation
- * that was performed.
- *
- * This function must be used on a session destruction handle which was
- * successfully waited on.
- *
- * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_OK if the state of the session
- * rotation could be obtained. Check the value of 'rotation_state' to
- * determine if the rotation of the session completed successfully or not.
- *
- * On error, one of the negative lttng_destruction_handle_status is returned.
- * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID if the session destruction
- * was not waited-on using the handle or if the arguments of the function are
- * invalid (e.g. NULL).
- *
- * Note that if no rotation was performed, rotation_state will be set to
- * LTTNG_ROTATION_STATE_NO_ROTATION.
- */
+/*!
+@brief
+ Sets \lt_p{*rotation_state} to the state of a final
+ \ref api_session_rotation "rotation" operation which the
+ destruction of the recording session identified by \lt_p{handle}
+ caused.
+
+You must successfully wait for the completion of the recording session
+destruction operation identified by \lt_p{handle} with
+lttng_destruction_handle_wait_for_completion() before you call this
+function.
+
+This function is only useful if LTTng performed at least one recording
+session rotation during the lifetime of the destroyed recording session.
+
+@param[in] handle
+ Handle of the destruction operation of the recording session of
+ which to get the state of the final rotation operation.
+@param[out] rotation_state
+ @parblock
+ <strong>On success</strong>, this function sets
+ \lt_p{*rotation_state} to the state of the final rotation operation
+ which the recording session destruction operation identified by
+ \lt_p{handle} caused.
+
+ \lt_p{*rotation_state} is #LTTNG_ROTATION_STATE_NO_ROTATION if LTTng
+ didn't perform any final recording session rotation.
+ @endparblock
+
+@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_OK
+ Success: \lt_p{*rotation_state} is the state of the final rotation
+ of the destroyed recording session.
+@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
+ Unsatisfied precondition.
+@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
+ Other error.
+
+@lt_pre_not_null{handle}
+@pre
+ You successfully waited for the completion of the recording session
+ destruction operation identified by \lt_p{handle} with
+ lttng_destruction_handle_wait_for_completion().
+@lt_pre_not_null{rotation_state}
+
+@sa lttng_destruction_handle_get_archive_location() --
+ Get the location of the trace chunk archive which a recording
+ session destruction operation created.
+*/
LTTNG_EXPORT extern enum lttng_destruction_handle_status
lttng_destruction_handle_get_rotation_state(const struct lttng_destruction_handle *handle,
enum lttng_rotation_state *rotation_state);
-/*
- * Get the location of the archive resulting from the rotation performed during
- * the session's destruction.
- *
- * This function must be used on a session destruction handle which was
- * successfully waited on and a session rotation must have been be completed
- * successfully in order for this call to succeed.
- *
- * The location returned remains owned by the session destruction handle.
- *
- * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_OK if the location of the archive
- * resulting from the session rotation could be obtained.
- *
- * On error, one of the negative lttng_destruction_handle_status is returned.
- * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID if the session destruction
- * was not waited-on using the handle, if no session rotation occurred as part
- * of the session's destruction, or if the arguments of the function are
- * invalid (e.g. NULL).
- */
+/*!
+@brief
+ Sets \lt_p{*location} to the location of the final
+ \ref api_session_rotation "trace chunk archive" which
+ the destruction of the recording session identified by \lt_p{handle}
+ created.
+
+You must make sure that the destruction of the recording session caused
+a final, successful rotation with
+lttng_destruction_handle_get_rotation_state().
+
+This function is only useful if LTTng performed at least one recording
+session rotation during the lifetime of the destroyed recording session.
+
+@param[in] handle
+ Handle of the destruction operation of the recording session of
+ which to get the location of the final trace chunk archive.
+@param[out] location
+ @parblock
+ <strong>On success</strong>, this function sets
+ \lt_p{*location} to the location of the final trace chunk archive
+ which the recording session destruction operation identified by
+ \lt_p{handle} created.
+
+ \lt_p{*location} is owned by \lt_p{handle}.
+ @endparblock
+
+@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_OK
+ Success: \lt_p{*location} is the location of the final trace
+ chunk archive of the destroyed recording session.
+@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
+ Unsatisfied precondition.
+@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
+ Other error.
+
+@lt_pre_not_null{handle}
+@pre
+ lttng_destruction_handle_get_rotation_state() set the
+ #LTTNG_ROTATION_STATE_COMPLETED state for \lt_p{handle}.
+@lt_pre_not_null{location}
+
+@sa lttng_destruction_handle_get_rotation_state() --
+ Get the state of the final rotation operation which a recording
+ session destruction operation caused.
+*/
LTTNG_EXPORT extern enum lttng_destruction_handle_status
lttng_destruction_handle_get_archive_location(const struct lttng_destruction_handle *handle,
const struct lttng_trace_archive_location **location);
+/// @}
+
#ifdef __cplusplus
}
#endif
extern "C" {
#endif
+/*!
+@addtogroup api_channel
+@{
+*/
+
#include <lttng/constant.h>
#include <lttng/lttng-export.h>
-/*
- * Domain types: the different possible tracers.
- */
+/*!
+@brief
+ Tracing domain type (tracer type).
+*/
enum lttng_domain_type {
- LTTNG_DOMAIN_NONE = 0, /* No associated domain. */
- LTTNG_DOMAIN_KERNEL = 1, /* Linux Kernel tracer. */
- LTTNG_DOMAIN_UST = 2, /* Global Userspace tracer. */
- LTTNG_DOMAIN_JUL = 3, /* Java Util Logging. */
- LTTNG_DOMAIN_LOG4J = 4, /* Java Log4j Framework. */
- LTTNG_DOMAIN_PYTHON = 5, /* Python logging Framework. */
+ /// None.
+ LTTNG_DOMAIN_NONE = 0,
+
+ /// Linux kernel.
+ LTTNG_DOMAIN_KERNEL = 1,
+
+ /// User space.
+ LTTNG_DOMAIN_UST = 2,
+
+ /// <code>java.util.logging</code> (JUL).
+ LTTNG_DOMAIN_JUL = 3,
+
+ /// Apache log4j.
+ LTTNG_DOMAIN_LOG4J = 4,
+
+ /// Python logging.
+ LTTNG_DOMAIN_PYTHON = 5,
};
-/* Buffer type for a specific domain. */
+/*!
+@brief
+ Buffering scheme of a channel.
+
+See \ref api-channel-buf-scheme "Buffering scheme" to learn more.
+*/
enum lttng_buffer_type {
- LTTNG_BUFFER_PER_PID, /* Only supported by UST being the default. */
- LTTNG_BUFFER_PER_UID, /* Only supported by UST. */
- LTTNG_BUFFER_GLOBAL, /* Only supported by the Kernel. */
+ /// Per-process buffering.
+ LTTNG_BUFFER_PER_PID,
+
+ /// Per-user buffering.
+ LTTNG_BUFFER_PER_UID,
+
+ /// Global (Linux kernel) buffering.
+ LTTNG_BUFFER_GLOBAL,
};
/*
*/
#define LTTNG_DOMAIN_PADDING1 12
#define LTTNG_DOMAIN_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
+
+/*!
+@brief
+ Tracing domain summary.
+
+Such a structure is involved:
+
+- As a member of a \link #lttng_handle recording session handle\endlink.
+
+ Some functions which require both a \lt_obj_session
+ and a tracing domain accept an #lttng_handle structure.
+
+- When you list the tracing domains of a recording session with
+ lttng_list_domains().
+
+- When you create a \link #lttng_channel channel summary
+ structure\endlink with lttng_channel_create().
+
+You must initialize such a structure to zeros before setting its
+members and using it, for example:
+
+@code
+struct lttng_domain domain;
+
+memset(&domain, 0, sizeof(domain));
+@endcode
+*/
struct lttng_domain {
+ /// Tracing domain type.
enum lttng_domain_type type;
+
+ /*!
+ @brief
+ Buffering scheme of all the channels associated to this tracing
+ domain.
+ */
enum lttng_buffer_type buf_type;
+
char padding[LTTNG_DOMAIN_PADDING1];
union {
} attr;
};
-/*
- * List the registered domain(s) of a session.
- *
- * Session name CAN NOT be NULL.
- *
- * Return the size (number of entries) of the "lttng_domain" array. Caller
- * must free domains. On error, a negative LTTng error code is returned.
- */
+/// @}
+
+/*!
+@brief
+ Sets \lt_p{*domains} to the summaries of the tracing domains which
+ contain at least one channel within the recording session
+ named \lt_p{session_name}.
+
+@ingroup api_session
+
+@param[in] session_name
+ Name of the recording session for which to get the tracing domain
+ summaries.
+@param[out] domains
+ @parblock
+ <strong>On success</strong>, this function sets \lt_p{*domains} to
+ the summaries of the tracing domains.
+
+ Free \lt_p{*domains} with <code>free()</code>.
+ @endparblock
+
+@returns
+ The number of items in \lt_p{*domains} on success, or a \em negative
+ #lttng_error_code enumerator otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+@lt_pre_not_null{domains}
+*/
LTTNG_EXPORT extern int lttng_list_domains(const char *session_name, struct lttng_domain **domains);
#ifdef __cplusplus
#ifndef LTTNG_EVENT_H
#define LTTNG_EVENT_H
+#ifdef __cplusplus
+extern "C" {
+#endif
+
#include <lttng/handle.h>
#include <lttng/lttng-export.h>
#include <lttng/userspace-probe.h>
-#ifdef __cplusplus
-extern "C" {
-#endif
+/*!
+@brief
+ \ref api-rer-conds-inst-pt-type "Instrumentation type condition"
+ of a recording event
-/*
- * Instrumentation type of tracing event.
- */
+@ingroup api_rer
+*/
enum lttng_event_type {
+ /// Match LTTng kernel tracepoint and Linux system call events.
LTTNG_EVENT_ALL = -1,
+
+ /// Match LTTng tracepoint or Java/Python logging events.
LTTNG_EVENT_TRACEPOINT = 0,
+
+ /*!
+ Match Linux
+ <a href="https://www.kernel.org/doc/html/latest/trace/kprobes.html">kprobe</a>
+ events.
+ */
LTTNG_EVENT_PROBE = 1,
+
+ /*!
+ Match Linux
+ <a href="https://www.kernel.org/doc/html/latest/trace/kprobes.html">kretprobe</a>
+ events.
+ */
LTTNG_EVENT_FUNCTION = 2,
+
+ /// @cond UNUSED
LTTNG_EVENT_FUNCTION_ENTRY = 3,
LTTNG_EVENT_NOOP = 4,
+ /// @endcond
+
+ /// Match Linux system call events.
LTTNG_EVENT_SYSCALL = 5,
+
+ /*!
+ Match Linux
+ <a href="https://lwn.net/Articles/499190/">uprobe</a>
+ events.
+ */
LTTNG_EVENT_USERSPACE_PROBE = 6,
};
-/*
- * Loglevel information.
- */
+/*!
+@brief
+ Operand of the
+ \ref api-rer-conds-ll "instrumentation point log level condition"
+ of a recording event rule.
+
+@ingroup api_rer
+
+In the enumerator descriptions below, consider that \lt_var{LL} is the
+log level value of the condition, that is, the value of the
+lttng_event::loglevel member when the lttng_event::loglevel_type member
+is the described enumerator.
+
+Depending on the \lt_obj_domain of the recording event rule, \lt_var{LL}
+is one of the enumerators of #lttng_loglevel, #lttng_loglevel_jul,
+#lttng_loglevel_log4j, or #lttng_loglevel_python.
+*/
enum lttng_loglevel_type {
+ /// Match events regardless of their log level.
LTTNG_EVENT_LOGLEVEL_ALL = 0,
+
+ /*!
+ Match events with a log level that's at least as severe as
+ \lt_var{LL}.
+ */
LTTNG_EVENT_LOGLEVEL_RANGE = 1,
+
+ /// Match events with a log level that's exacty \lt_var{LL}.
LTTNG_EVENT_LOGLEVEL_SINGLE = 2,
};
-/*
- * Available loglevels.
- */
+/*!
+@brief
+ Value of the
+ \ref api-rer-conds-ll "instrumentation point log level condition"=
+ of an LTTng
+ \link #LTTNG_DOMAIN_UST user space\endlink tracepoint
+ recording event rule.
+
+@ingroup api_rer
+
+@sa #lttng_loglevel_type --
+ Operand of the log level condition of a recording event rule.
+*/
enum lttng_loglevel {
+ /// System is unusable.
LTTNG_LOGLEVEL_EMERG = 0,
+
+ /// Action must be taken immediately.
LTTNG_LOGLEVEL_ALERT = 1,
+
+ /// Critical conditions.
LTTNG_LOGLEVEL_CRIT = 2,
+
+ /// Error conditions.
LTTNG_LOGLEVEL_ERR = 3,
+
+ /// Warning conditions.
LTTNG_LOGLEVEL_WARNING = 4,
+
+ /// Normal, but significant, condition.
LTTNG_LOGLEVEL_NOTICE = 5,
+
+ /// Informational message.
LTTNG_LOGLEVEL_INFO = 6,
+
+ /// Debug information with system-level scope (set of programs).
LTTNG_LOGLEVEL_DEBUG_SYSTEM = 7,
+
+ /// Debug information with program-level scope (set of processes).
LTTNG_LOGLEVEL_DEBUG_PROGRAM = 8,
+
+ /// Debug information with process-level scope (set of modules).
LTTNG_LOGLEVEL_DEBUG_PROCESS = 9,
+
+ /*!
+ Debug information with module (executable/library) scope
+ (set of units).
+ */
LTTNG_LOGLEVEL_DEBUG_MODULE = 10,
+
+ /// Debug information with compilation unit scope (set of functions).
LTTNG_LOGLEVEL_DEBUG_UNIT = 11,
+
+ /// Debug information with function-level scope.
LTTNG_LOGLEVEL_DEBUG_FUNCTION = 12,
+
+ /// Debug information with line-level scope.
LTTNG_LOGLEVEL_DEBUG_LINE = 13,
+
+ /// Debug-level message.
LTTNG_LOGLEVEL_DEBUG = 14,
};
-/*
- * Available loglevels for the JUL domain. Those are an exact map from the
- * class java.util.logging.Level.
- */
+/*!
+@brief
+ Value of the
+ \ref api-rer-conds-ll "instrumentation point log level condition"
+ of a
+ \link #LTTNG_DOMAIN_JUL <code>java.util.logging</code>\endlink
+ recording event rule.
+
+@ingroup api_rer
+
+@sa #lttng_loglevel_type --
+ Operand of the log level condition of a recording event rule.
+*/
enum lttng_loglevel_jul {
+ /// Logging turned off.
LTTNG_LOGLEVEL_JUL_OFF = INT32_MAX,
+
+ /// Serious failure.
LTTNG_LOGLEVEL_JUL_SEVERE = 1000,
+
+ /// Potential problem.
LTTNG_LOGLEVEL_JUL_WARNING = 900,
+
+ /// Informational messages.
LTTNG_LOGLEVEL_JUL_INFO = 800,
+
+ /// Static configuration messages.
LTTNG_LOGLEVEL_JUL_CONFIG = 700,
+
+ /// Tracing information.
LTTNG_LOGLEVEL_JUL_FINE = 500,
+
+ /// Fairly detailed tracing message.
LTTNG_LOGLEVEL_JUL_FINER = 400,
+
+ /// Highly detailed tracing message.
LTTNG_LOGLEVEL_JUL_FINEST = 300,
+
+ /// All messages.
LTTNG_LOGLEVEL_JUL_ALL = INT32_MIN,
};
-/*
- * Available loglevels for the LOG4j domain. Those are an exact map from the
- * class org.apache.log4j.Level.
- */
+/*!
+@brief
+ Value of the
+ \ref api-rer-conds-ll "instrumentation point log level condition"
+ of an
+ \link #LTTNG_DOMAIN_LOG4J Apache log4j\endlink
+ recording event rule.
+
+@ingroup api_rer
+
+@sa #lttng_loglevel_type --
+ Operand of the log level condition of a recording event rule.
+*/
enum lttng_loglevel_log4j {
+ /// Logging turned off.
LTTNG_LOGLEVEL_LOG4J_OFF = INT32_MAX,
+
+ /*!
+ Very severe error events that will presumably lead the
+ application to abort.
+ */
LTTNG_LOGLEVEL_LOG4J_FATAL = 50000,
+
+ /*!
+ Error events that might still allow the application to continue
+ running.
+ */
LTTNG_LOGLEVEL_LOG4J_ERROR = 40000,
+
+ /// Potentially harmful situations.
LTTNG_LOGLEVEL_LOG4J_WARN = 30000,
+
+ /*!
+ Informational messages that highlight the progress of the
+ application at coarse-grained level.
+ */
LTTNG_LOGLEVEL_LOG4J_INFO = 20000,
+
+ /*!
+ Fine-grained informational events that are most useful to debug
+ an application.
+ */
LTTNG_LOGLEVEL_LOG4J_DEBUG = 10000,
+
+ /*!
+ Finer-grained informational events than the
+ #LTTNG_LOGLEVEL_LOG4J_DEBUG level.
+ */
LTTNG_LOGLEVEL_LOG4J_TRACE = 5000,
+
+ /// All levels, including custom levels.
LTTNG_LOGLEVEL_LOG4J_ALL = INT32_MIN,
};
-/*
- * Available loglevels for the Python domain. Those are an exact map from the
- * Level class.
- */
+/*!
+@brief
+ Value of the
+ \ref api-rer-conds-ll "instrumentation point log level condition"
+ of a
+ \link #LTTNG_DOMAIN_PYTHON Python\endlink
+ recording event rule.
+
+@ingroup api_rer
+
+@sa #lttng_loglevel_type --
+ Operand of the log level condition of a recording event rule.
+*/
enum lttng_loglevel_python {
+ /// Critical.
LTTNG_LOGLEVEL_PYTHON_CRITICAL = 50,
+
+ /// Error.
LTTNG_LOGLEVEL_PYTHON_ERROR = 40,
+
+ /// Warning.
LTTNG_LOGLEVEL_PYTHON_WARNING = 30,
+
+ /// Information.
LTTNG_LOGLEVEL_PYTHON_INFO = 20,
+
+ /// Debugging.
LTTNG_LOGLEVEL_PYTHON_DEBUG = 10,
+
+ /// Logging turned off.
LTTNG_LOGLEVEL_PYTHON_NOTSET = 0,
};
-/*
- * LTTng consumer mode
- */
+/*!
+@brief
+ Channel output type.
+
+@ingroup api_channel
+*/
enum lttng_event_output {
+ /// Use the \lt_man_gen{splice,2} system call.
LTTNG_EVENT_SPLICE = 0,
+
+ /// Use the \lt_man_gen{mmap,2} system call.
LTTNG_EVENT_MMAP = 1,
};
-/* Event context possible type */
+/*!
+@brief
+ Context field type.
+
+@ingroup api_channel
+
+The following table indicates, for each enumerator, its description, for
+which \lt_obj_domain it's available, and the
+data type and the name of the resulting context field in traces.
+
+<table>
+ <tr>
+ <th>Enumerator
+ <th>Description
+ <th>Tracing domain
+ <th>Field type
+ <th>Field name
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_PID
+ <td>Process ID
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer
+ <td><code>pid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_PROCNAME
+ <td>Process name
+ <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
+ <td>String
+ <td><code>procname</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_PRIO
+ <td>Process priority
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer
+ <td><code>prio</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_NICE
+ <td>Nice value of the process
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer
+ <td><code>nice</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_VPID
+ <td>Virtual process ID
+ <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
+ <td>Integer
+ <td><code>vpid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_TID
+ <td>Thread ID
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer
+ <td><code>tid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_VTID
+ <td>Virtual thread ID
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer
+ <td><code>vtid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_PPID
+ <td>ID of the parent process
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer
+ <td><code>ppid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_VPPID
+ <td>Virtual ID of the parent process
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer
+ <td><code>vppid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_PTHREAD_ID
+ <td>POSIX thread ID
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer
+ <td><code>pthread_id</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_HOSTNAME
+ <td>Hostname
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>String
+ <td><code>hostname</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_IP
+ <td>Instruction pointer
+ <td>#LTTNG_DOMAIN_UST
+ <td>Integer
+ <td><code>ip</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER
+ <td>
+ Per-CPU perf counter.
+
+ If the lttng_event_context::ctx member of an #lttng_event_context
+ structure is #LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER, then the
+ lttng_event_context::lttng_event_context_u::perf_counter member
+ of lttng_event_context::u selects a specific per-CPU perf counter.
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer
+ <td>Depends on the selected perf counter
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER
+ <td>
+ Per-thread perf counter.
+
+ If the lttng_event_context::ctx member of an #lttng_event_context
+ structure is #LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER, then the
+ lttng_event_context::lttng_event_context_u::perf_counter member
+ of lttng_event_context::u selects a specific per-thread
+ perf counter.
+ <td>#LTTNG_DOMAIN_UST
+ <td>Integer
+ <td>Depends on the selected perf counter
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_APP_CONTEXT
+ <td>
+ Application-specific context.
+
+ If the lttng_event_context::ctx member of an #lttng_event_context
+ structure is #LTTNG_EVENT_CONTEXT_APP_CONTEXT, then the
+ lttng_event_context::lttng_event_context_u::app_ctx member of
+ of lttng_event_context::u selects
+ a specific application-specific context.
+ <td>#LTTNG_DOMAIN_JUL or #LTTNG_DOMAIN_LOG4J
+ <td>Integer or string
+ <td>Depends on the selected application-specific context
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_INTERRUPTIBLE
+ <td>Whether or not the process is interruptible
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer (0 or 1)
+ <td><code>interruptible</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_PREEMPTIBLE
+ <td>Whether or not the process is preemptible
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer (0 or 1)
+ <td><code>preemptible</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_NEED_RESCHEDULE
+ <td>Whether or not the process needs a reschedule
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer (0 or 1)
+ <td><code>need_reschedule</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_MIGRATABLE
+ <td>Whether or not the process is migratable
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer (0 or 1)
+ <td><code>migratable</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_CALLSTACK_KERNEL
+ <td>Linux kernel call stack
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Dynamic-length array of integers (instruction pointers)
+ <td><code>callstack_kernel</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_CALLSTACK_USER
+ <td>
+ User space call stack.
+
+ Only supported on IA-32 and x86-64 architectures.
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Dynamic-length array of integers (instruction pointers)
+ <td><code>callstack_user</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_CGROUP_NS
+ <td>
+ Control group root directory namespace ID.
+
+ @sa \lt_man_gen{cgroup_namespaces,7}
+ <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
+ <td>Integer
+ <td><code>cgroup_ns</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_IPC_NS
+ <td>
+ System V IPC and POSIX message queue namespace ID.
+
+ @sa \lt_man_gen{ipc_namespaces,7}
+ <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
+ <td>Integer
+ <td><code>ipc_ns</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_MNT_NS
+ <td>
+ Mount point namespace ID.
+
+ @sa \lt_man_gen{mount_namespaces,7}
+ <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
+ <td>Integer
+ <td><code>mnt_ns</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_NET_NS
+ <td>
+ Networking namespace ID.
+
+ @sa \lt_man_gen{network_namespaces,7}
+ <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
+ <td>Integer
+ <td><code>net_ns</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_PID_NS
+ <td>
+ Process ID namespace ID.
+
+ @sa \lt_man_gen{pid_namespaces,7}
+ <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
+ <td>Integer
+ <td><code>pid_ns</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_USER_NS
+ <td>
+ User and group ID namespace ID.
+
+ @sa \lt_man_gen{user_namespaces,7}
+ <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
+ <td>Integer
+ <td><code>user_ns</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_UTS_NS
+ <td>
+ Hostname and NIS domain name namespace ID.
+
+ @sa \lt_man_gen{uts_namespaces,7}
+ <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
+ <td>Integer
+ <td><code>uts_ns</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_TIME_NS
+ <td>
+ Boot and monotonic clock namespace ID.
+
+ @sa \lt_man_gen{time_namespaces,7}
+ <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
+ <td>Integer
+ <td><code>time_ns</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_UID
+ <td>User ID
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer
+ <td><code>uid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_EUID
+ <td>Effective user ID
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer
+ <td><code>euid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_SUID
+ <td>Set owner user ID
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer
+ <td><code>suid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_GID
+ <td>Group ID
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer
+ <td><code>gid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_EGID
+ <td>Effective group ID
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer
+ <td><code>egid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_SGID
+ <td>Set owner group ID
+ <td>#LTTNG_DOMAIN_KERNEL
+ <td>Integer
+ <td><code>sgid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_VUID
+ <td>Virtual user ID
+ <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
+ <td>Integer
+ <td><code>vuid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_VEUID
+ <td>Virtual effective user ID
+ <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
+ <td>Integer
+ <td><code>veuid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_VSUID
+ <td>Virtual set owner user ID
+ <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
+ <td>Integer
+ <td><code>vsuid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_VGID
+ <td>Virtual group ID
+ <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
+ <td>Integer
+ <td><code>vgid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_VEGID
+ <td>Virtual effective group ID
+ <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
+ <td>Integer
+ <td><code>vegid</code>
+ <tr>
+ <td>#LTTNG_EVENT_CONTEXT_VSGID
+ <td>Virtual set owner group ID
+ <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
+ <td>Integer
+ <td><code>vsgid</code>
+</table>
+
+@ingroup api_channel
+*/
enum lttng_event_context_type {
+ /// Process ID.
LTTNG_EVENT_CONTEXT_PID = 0,
+
+ /// @cond BACKWARD_COMPAT_EVENT_CTX_TYPES
LTTNG_EVENT_CONTEXT_PERF_COUNTER = 1, /* Backward compat. */
+ /// @endcond
+
+ /// Process name.
LTTNG_EVENT_CONTEXT_PROCNAME = 2,
+
+ /// Process priority.
LTTNG_EVENT_CONTEXT_PRIO = 3,
+
+ /// Nice value of the process.
LTTNG_EVENT_CONTEXT_NICE = 4,
+
+ /// Virtual process ID.
LTTNG_EVENT_CONTEXT_VPID = 5,
+
+ /// Thread ID.
LTTNG_EVENT_CONTEXT_TID = 6,
+
+ /// Virtual thread ID.
LTTNG_EVENT_CONTEXT_VTID = 7,
+
+ /// ID of the parent process.
LTTNG_EVENT_CONTEXT_PPID = 8,
+
+ /// Virtual ID of the parent process.
LTTNG_EVENT_CONTEXT_VPPID = 9,
+
+ /// POSIX thread ID.
LTTNG_EVENT_CONTEXT_PTHREAD_ID = 10,
+
+ /// Hostname.
LTTNG_EVENT_CONTEXT_HOSTNAME = 11,
+
+ /// Instruction pointer.
LTTNG_EVENT_CONTEXT_IP = 12,
+
+ /// Per-CPU perf counter.
LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER = 13,
+
+ /// Per-thread perf counter.
LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER = 14,
+
+ /// Application-specific context.
LTTNG_EVENT_CONTEXT_APP_CONTEXT = 15,
+
+ /// Whether or not the process is interruptible.
LTTNG_EVENT_CONTEXT_INTERRUPTIBLE = 16,
+
+ /// Whether or not the process is preemptible.
LTTNG_EVENT_CONTEXT_PREEMPTIBLE = 17,
+
+ /// Whether or not the process needs a reschedule.
LTTNG_EVENT_CONTEXT_NEED_RESCHEDULE = 18,
+
+ /// Whether or not the process is migratable.
LTTNG_EVENT_CONTEXT_MIGRATABLE = 19,
+
+ /// Linux kernel call stack.
LTTNG_EVENT_CONTEXT_CALLSTACK_KERNEL = 20,
- LTTNG_EVENT_CONTEXT_CALLSTACK_USER = 21, /* Supported on x86_32 and x86_64 only. */
+
+ /// User space call stack.
+ LTTNG_EVENT_CONTEXT_CALLSTACK_USER = 21,
+
+ /// Control group root directory namespace ID.
LTTNG_EVENT_CONTEXT_CGROUP_NS = 22,
+
+ /// System V IPC and POSIX message queue namespace ID.
LTTNG_EVENT_CONTEXT_IPC_NS = 23,
+
+ /// Mount point namespace ID.
LTTNG_EVENT_CONTEXT_MNT_NS = 24,
+
+ /// Networking namespace ID.
LTTNG_EVENT_CONTEXT_NET_NS = 25,
+
+ /// Process ID namespace ID.
LTTNG_EVENT_CONTEXT_PID_NS = 26,
+
+ /// User and group ID namespace ID.
LTTNG_EVENT_CONTEXT_USER_NS = 27,
+
+ /// Hostname and NIS domain name namespace ID.
LTTNG_EVENT_CONTEXT_UTS_NS = 28,
+
+ /// User ID namespace ID.
LTTNG_EVENT_CONTEXT_UID = 29,
+
+ /// Effective user ID namespace ID.
LTTNG_EVENT_CONTEXT_EUID = 30,
+
+ /// Set owner user ID namespace ID.
LTTNG_EVENT_CONTEXT_SUID = 31,
+
+ /// Group ID namespace ID.
LTTNG_EVENT_CONTEXT_GID = 32,
+
+ /// Effective group ID namespace ID.
LTTNG_EVENT_CONTEXT_EGID = 33,
+
+ /// Set owner group ID namespace ID.
LTTNG_EVENT_CONTEXT_SGID = 34,
+
+ /// Virtual user ID namespace ID.
LTTNG_EVENT_CONTEXT_VUID = 35,
+
+ /// Virtual effective user ID namespace ID.
LTTNG_EVENT_CONTEXT_VEUID = 36,
+
+ /// Virtual set owner user ID namespace ID.
LTTNG_EVENT_CONTEXT_VSUID = 37,
+
+ /// Virtual group ID namespace ID.
LTTNG_EVENT_CONTEXT_VGID = 38,
+
+ /// Virtual effective group ID namespace ID.
LTTNG_EVENT_CONTEXT_VEGID = 39,
+
+ /// Virtual set owner group ID namespace ID.
LTTNG_EVENT_CONTEXT_VSGID = 40,
+
+ /// Boot and monotonic clock namespace ID.
LTTNG_EVENT_CONTEXT_TIME_NS = 41,
};
+/*!
+@brief
+ LTTng tracepoint field data type
+ (type of the lttng_event_field::type member).
+
+@ingroup api_inst_pt
+*/
enum lttng_event_field_type {
+ /// Other/unknown.
LTTNG_EVENT_FIELD_OTHER = 0,
+
+ /// Integer.
LTTNG_EVENT_FIELD_INTEGER = 1,
+
+ /// Enumeration.
LTTNG_EVENT_FIELD_ENUM = 2,
+
+ /// Floating point number.
LTTNG_EVENT_FIELD_FLOAT = 3,
+
+ /// String.
LTTNG_EVENT_FIELD_STRING = 4,
};
+/*!
+@brief
+ \ref api-rer-inst-pt-descr "Instrumentation point descriptor"
+ flag (type of the lttng_event::flags member).
+
+@ingroup api_inst_pt
+*/
enum lttng_event_flag {
+ /*!
+ @brief
+ 32-bit Linux system call.
+
+ Only valid when the lttng_event::type member is
+ #LTTNG_EVENT_SYSCALL.
+ */
LTTNG_EVENT_FLAG_SYSCALL_32 = (1U << 0),
+
+ /*!
+ @brief
+ 64-bit Linux system call.
+
+ Only valid when the lttng_event::type member is
+ #LTTNG_EVENT_SYSCALL.
+ */
LTTNG_EVENT_FLAG_SYSCALL_64 = (1U << 1),
};
-/*
- * Perf counter attributes
- *
- * The structures should be initialized to zero before use.
- */
#define LTTNG_PERF_EVENT_PADDING1 16
+
+/*!
+@brief
+ perf counter context field descriptor.
+
+@ingroup api_channel
+
+If the lttng_event_context::ctx member of an #lttng_event_context
+structure is #LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER or
+#LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER, then the
+lttng_event_context::lttng_event_context_u::perf_counter member
+of lttng_event_context::u selects a specific perf counter.
+
+You must initialize such a structure to zeros before setting its members
+and using it, for example:
+
+@code
+struct lttng_event_perf_counter_ctx perf_counter_ctx;
+
+memset(&perf_counter_ctx, 0, sizeof(perf_counter_ctx));
+@endcode
+*/
struct lttng_event_perf_counter_ctx {
+ /*!
+ @brief
+ perf counter type ID.
+
+ One of:
+
+ <table>
+ <tr>
+ <th>Type
+ <th>ID
+ <tr>
+ <td>Hardware counter
+ <td>0
+ <tr>
+ <td>Software counter
+ <td>1
+ <tr>
+ <td>Hardware cache counter
+ <td>3
+ <tr>
+ <td>Performance Monitoring Unit (PMU) counter
+ <td>4
+ </table>
+ */
uint32_t type;
+
+ /*!
+ @brief
+ perf counter configuration.
+
+ Depending on the lttng_event_perf_counter_ctx::type member:
+
+ <dl>
+ <dt>0 (hardware counter)
+ <dd>
+ One of:
+
+ <table>
+ <tr>
+ <th>Counter
+ <th>ID
+ <tr>
+ <td>CPU cycles
+ <td>0
+ <tr>
+ <td>Instructions
+ <td>1
+ <tr>
+ <td>Cache references
+ <td>2
+ <tr>
+ <td>Cache misses
+ <td>3
+ <tr>
+ <td>Branch instructions
+ <td>4
+ <tr>
+ <td>Branch misses
+ <td>5
+ <tr>
+ <td>Bus cycles
+ <td>6
+ <tr>
+ <td>Stalled cycles (front end)
+ <td>7
+ <tr>
+ <td>Stalled cycles (back end)
+ <td>8
+ </table>
+
+ <dt>1 (software counter)
+ <dd>
+ One of:
+
+ <table>
+ <tr>
+ <th>Counter
+ <th>ID
+ <tr>
+ <td>CPU clock
+ <td>0
+ <tr>
+ <td>Task clock
+ <td>1
+ <tr>
+ <td>Page faults
+ <td>2
+ <tr>
+ <td>Context switches
+ <td>3
+ <tr>
+ <td>CPU migrations
+ <td>4
+ <tr>
+ <td>Minor page faults
+ <td>5
+ <tr>
+ <td>Major page faults
+ <td>6
+ <tr>
+ <td>Alignment faults
+ <td>7
+ <tr>
+ <td>Emulation faults
+ <td>8
+ </table>
+
+ <dt>3 (hardware cache counter)
+ <dd>
+ The result of a bitwise OR operation between a cache ID,
+ an operation ID, and a result ID, as follows:
+
+ <table>
+ <tr>
+ <th>Cache ID
+ <th>Description
+ <tr>
+ <td>0
+ <td>Data L1
+ <tr>
+ <td>1
+ <td>Instructions L1
+ <tr>
+ <td>2
+ <td>LL
+ <tr>
+ <td>3
+ <td>Data <a
+ href="https://en.wikipedia.org/wiki/Translation_lookaside_buffer">TLB</a> <tr> <td>4
+ <td>Instruction TLB
+ <tr>
+ <td>5
+ <td>Branch prediction unit (BPU)
+ </table>
+
+ <table>
+ <tr>
+ <th>Operator ID
+ <th>Description
+ <tr>
+ <td>0
+ <td>Read
+ <tr>
+ <td>0x100
+ <td>Write
+ <tr>
+ <td>0x200
+ <td>Prefetch
+ </table>
+
+ <table>
+ <tr>
+ <th>Result ID
+ <th>Description
+ <tr>
+ <td>0
+ <td>Access
+ <tr>
+ <td>0x10000
+ <td>Miss
+ </table>
+
+ <dt>4 (PMU counter)
+ <dd>
+ PMU counter raw ID.
+
+ @sa \lt_man_gen{perf-record,1}
+ </dl>
+ */
uint64_t config;
+
+ /// Context field name.
char name[LTTNG_SYMBOL_NAME_LEN];
char padding[LTTNG_PERF_EVENT_PADDING1];
};
-/*
- * Event/channel context
- *
- * The structures should be initialized to zero before use.
- */
#define LTTNG_EVENT_CONTEXT_PADDING1 16
#define LTTNG_EVENT_CONTEXT_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
+
+/*!
+@brief
+ Context field descriptor.
+
+@ingroup api_channel
+
+Such a structure describes a context field to be recorded within all the
+\ref api_rer "event records" of a given \lt_obj_channel (see
+lttng_add_context()).
+
+You must initialize such a structure to zeros before setting its members
+and using it, for example:
+
+@code
+struct lttng_event_context ctx;
+
+memset(&ctx, 0, sizeof(ctx));
+@endcode
+*/
struct lttng_event_context {
+ /*!
+ @brief
+ Context field type.
+
+ Some types have a \lt_obj_domain
+ constraint.
+
+ If this member has the value
+ #LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER or
+ #LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER, then you must also set
+ the lttng_event_context::lttng_event_context_u::perf_counter
+ member of lttng_event_context::u.
+
+ If this member has the value #LTTNG_EVENT_CONTEXT_APP_CONTEXT,
+ then you must also set the
+ lttng_event_context::lttng_event_context_u::app_ctx member
+ of lttng_event_context::u.
+ */
enum lttng_event_context_type ctx;
+
char padding[LTTNG_EVENT_CONTEXT_PADDING1];
- union {
+ /*!
+ @brief
+ perf counter or application-specific context field
+ descriptor.
+
+ @ingroup api_channel
+ */
+ union lttng_event_context_u {
+ /*!
+ @brief
+ perf counter context field descriptor.
+
+ Only used when the lttng_event_context::ctx member
+ is #LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER or
+ #LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER.
+ */
struct lttng_event_perf_counter_ctx perf_counter;
+
struct {
+ /// Provider name.
char *provider_name;
+
+ /// Field type.
char *ctx_name;
- } app_ctx;
+ }
+
+ /*!
+ @brief
+ Application-specific context field descriptor.
+
+ Only used when the lttng_event_context::ctx member
+ is #LTTNG_EVENT_CONTEXT_APP_CONTEXT.
+ */
+ app_ctx;
+
char padding[LTTNG_EVENT_CONTEXT_PADDING2];
- } u;
+ }
+
+ /// perf counter or application-specific context field descriptor.
+ u;
};
-/*
- * Event probe.
- *
- * Either addr is used or symbol_name and offset.
- *
- * The structures should be initialized to zero before use.
- */
#define LTTNG_EVENT_PROBE_PADDING1 16
+
+/*!
+@brief
+ Legacy Linux kprobe/kretprobe location.
+
+@ingroup api_rer
+
+Such a structure indicates the location of a Linux kprobe/kretprobe for
+a \lt_obj_rer having such an instrumentation point type.
+
+You must initialize such a structure to zeros before setting its members
+and using it, for example:
+
+@code
+struct lttng_event_probe_attr loc;
+
+memset(&loc, 0, sizeof(loc));
+@endcode
+
+Set either lttng_event_probe_attr::addr or
+lttng_event_probe_attr::symbol_name and lttng_event_probe_attr::offset.
+
+@sa \ref api-rer-conds-inst-pt-type "Instrumentation point type condition".
+*/
struct lttng_event_probe_attr {
+ /*!
+ @brief
+ kprobe/kretprobe address.
+
+ If this member is not 0, then
+ lttng_event_probe_attr::symbol_name must be an empty string.
+ */
uint64_t addr;
+ /*!
+ @brief
+ kprobe/kretprobe address offset from the symbol named
+ lttng_event_probe_attr::symbol_name.
+ */
uint64_t offset;
+
+ /*!
+ @brief
+ kprobe/kretprobe symbol name.
+
+ The actual kprobe/kretprobe address is the address of the named
+ symbol plus the value of lttng_event_probe_attr::offset.
+
+ If this member is not an empty string, then
+ lttng_event_probe_attr::addr must be 0.
+ */
char symbol_name[LTTNG_SYMBOL_NAME_LEN];
char padding[LTTNG_EVENT_PROBE_PADDING1];
*/
#define LTTNG_EVENT_PADDING1 12
#define LTTNG_EVENT_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
+
+/*!
+@brief
+ \lt_obj_c_rer descriptor.
+
+@ingroup api_rer
+
+Such a structure describes a recording event rule. More specifically,
+it describes the \ref api-rer-conds "conditions" of a recording
+event rule.
+
+lttng_list_events() sets a pointer to an array of all the recording
+event rule descriptors of a given \lt_obj_channel.
+
+@note
+ \anchor api-rer-inst-pt-descr lttng_list_tracepoints()
+ and lttng_list_syscalls() also set
+ a pointer to an array of instances of this structure. In this
+ context, the #lttng_event structure is named
+ \"<em>instrumentation point descriptor</em>\".
+
+lttng_enable_event(), lttng_enable_event_with_filter(), and
+lttng_enable_event_with_exclusions() expect such a structure to create
+or enable a recording event rule.
+
+Most properties are members of the structure itself, but the
+following ones have their own dedicated accessors:
+
+<dl>
+ <dt>
+ Linux uprobe location (when the lttng_event::type member is
+ #LTTNG_EVENT_USERSPACE_PROBE)
+ <dd>
+ - lttng_event_get_userspace_probe_location()
+ - lttng_event_set_userspace_probe_location()
+
+ <dt>\ref api-rer-conds-event-name "Event name" exclusion patterns
+ <dd>
+ lttng_event_get_exclusion_name()
+
+ <dt>\ref api-rer-conds-filter "Event payload and context filter" expression
+ <dd>
+ lttng_event_get_filter_expression()
+</dl>
+
+Create an empty recording event rule descriptor with
+lttng_event_create().
+
+\anchor api-rer-valid-event-struct A \em valid #lttng_event structure
+satisfies the following constraints:
+
+- If the lttng_event::type member is #LTTNG_EVENT_PROBE or
+ #LTTNG_EVENT_FUNCTION, then the lttng_event::lttng_event_attr_u::probe
+ member of lttng_event::attr is valid according to the
+ documentation of #lttng_event_probe_attr.
+
+- If the lttng_event::type member is #LTTNG_EVENT_USERSPACE_PROBE, then
+ the recording event rule descriptor has a Linux uprobe location
+ (you called lttng_event_set_userspace_probe_location() on it to
+ set it).
+
+Destroy a recording event rule descriptor with lttng_event_destroy().
+*/
struct lttng_event {
/* Offset 0 */
+ /// \ref api-rer-conds-inst-pt-type "Instrumentation point type condition".
enum lttng_event_type type;
/* Offset 4 */
+ /*!
+ @brief \ref api-rer-conds-event-name "Event name" pattern
+ condition.
+
+ If empty, lttng_enable_event(),
+ lttng_enable_event_with_filter(), and
+ lttng_enable_event_with_exclusions() use <code>*</code> (match
+ events with any name).
+
+ If the lttng_event::type member is #LTTNG_EVENT_PROBE,
+ #LTTNG_EVENT_FUNCTION, or #LTTNG_EVENT_USERSPACE_PROBE, then
+ this member is actually the name of the created Linux
+ kprobe/kretprobe/uprobe instrumentation point (future event
+ name).
+
+ If this structure is an
+ \ref api-rer-inst-pt-descr "instrumentation point descriptor",
+ then this member is the name of the LTTng tracepoint, Linux
+ system call, or Java/Python logger.
+ */
char name[LTTNG_SYMBOL_NAME_LEN];
/* Offset 260 */
+ /*!
+ @brief
+ Operand of the
+ \ref api-rer-conds-ll "instrumentation point log level condition".
+ */
enum lttng_loglevel_type loglevel_type;
/* Offset 264 */
+ /*!
+ @brief Value of the
+ \ref api-rer-conds-ll "instrumentation point log level condition".
+
+ This member must be one of the enumerators of
+ #lttng_loglevel, #lttng_loglevel_jul, #lttng_loglevel_log4j, or
+ #lttng_loglevel_python, depending on the
+ \lt_obj_domain when you call lttng_enable_event(),
+ lttng_enable_event_with_filter(), or
+ lttng_enable_event_with_exclusions().
+
+ If this structure is an
+ \ref api-rer-inst-pt-descr "instrumentation point descriptor",
+ then this member is the log level of the LTTng tracepoint or
+ Java/Python logger.
+ */
int loglevel;
/* Offset 268 */
+ /*!
+ @brief
+ 1 if this recording event rule is enabled, or 0 otherwise.
+
+ This is a read-only member.
+
+ @sa lttng_enable_event() --
+ Creates or enables a recording event rule.
+ @sa lttng_disable_event_ext() --
+ Disables a recording event rule.
+ */
int32_t enabled; /* Does not apply: -1 */
/* Offset 272 */
+ /*!
+ @brief
+ ID of the process which offers the instrumentation point
+ described by this structure.
+
+ This is a read-only member.
+
+ This member is \em not part of a recording event rule.
+ */
pid_t pid;
/* Offset 276 */
- unsigned char filter; /* filter enabled ? */
+ /*!
+ @brief
+ 1 if the recording event rule described by this has an
+ \ref api-rer-conds-filter "event payload and context filter"
+ expression, or 0 otherwise.
+
+ This is a read-only member: use the \lt_p{filter_expr} parameter
+ of lttng_enable_event_with_filter() or
+ lttng_enable_event_with_exclusions() when you create a
+ recording event rule to set an event payload and context
+ filter expression.
+
+ If this member is 1, then get the actual filter expression
+ string with lttng_event_get_filter_expression().
+ */
+ unsigned char filter;
/* Offset 277 */
- unsigned char exclusion; /* exclusions added ? */
+ /*!
+ @brief
+ 1 if the recording event rule described by this has
+ \ref api-rer-conds-event-name "event name" exclusion
+ patterns (part of the event name condition), or 0 otherwise.
+
+ This is a read-only member: use the
+ \lt_p{event_name_exclusion_count} and
+ \lt_p{event_name_exclusions} parameters of
+ lttng_enable_event_with_exclusions() when you create a recording
+ event rule to set event name exclusion patterns.
+
+ If this member is 1, then get the actual event name exclusion
+ patterns with lttng_event_get_exclusion_name_count() and
+ lttng_event_get_exclusion_name().
+ */
+ unsigned char exclusion;
/* Offset 278 */
char padding2[2];
/* Offset 280 */
- /* Event flag, from 2.6 and above. */
+ /*!
+ @brief
+ \ref api-rer-inst-pt-descr "Instrumentation point descriptor"
+ flags (bitwise OR).
+
+ This is a read-only member.
+
+ This member is \em not part of a recording event rule.
+ */
enum lttng_event_flag flags;
/* Offset 284 */
} extended;
/* Offset 296 */
- /* Per event type configuration */
- union {
+ /*!
+ @brief
+ Linux kprobe/kretprobe recording event rule configuration.
+
+ @ingroup api_rer
+ */
+ union lttng_event_attr_u {
+ /*!
+ @brief
+ Linux kprobe/kretprobe location.
+
+ Only valid when the lttng_event::type member is
+ #LTTNG_EVENT_PROBE or #LTTNG_EVENT_FUNCTION.
+ */
struct lttng_event_probe_attr probe;
+
struct lttng_event_function_attr ftrace;
char padding[LTTNG_EVENT_PADDING2];
- } attr;
+ }
+
+ /*!
+ @brief
+ Linux kprobe/kretprobe recording event rule configuration.
+
+ Only valid when the lttng_event::type member is
+ #LTTNG_EVENT_PROBE or #LTTNG_EVENT_FUNCTION.
+ */
+ attr;
};
#define LTTNG_EVENT_FIELD_PADDING LTTNG_SYMBOL_NAME_LEN + 32
+
+/*!
+@brief
+ LTTng tracepoint field description.
+
+@ingroup api_inst_pt
+
+lttng_list_tracepoint_fields() sets a pointer to an array of all the
+tracepoint field descriptions of a given \lt_obj_domain.
+*/
struct lttng_event_field {
+ /// Field name.
char field_name[LTTNG_SYMBOL_NAME_LEN];
+
+ /// Field data type.
enum lttng_event_field_type type;
+
char padding[LTTNG_EVENT_FIELD_PADDING];
+
+ /*!
+ @brief
+ \ref api-rer-inst-pt-descr "Descriptor" of the tracepoint
+ which contains this field.
+ */
struct lttng_event event;
+
+ /*!
+ @brief
+ 0 if LTTng writes this field to an event record, or 1
+ otherwise.
+ */
int nowrite;
};
-/*
- * List the event(s) of a session channel.
- *
- * Both handle and channel_name CAN NOT be NULL.
- *
- * Return the size (number of entries) of the "lttng_event" array. Caller must
- * free events. On error a negative LTTng error code is returned.
- */
+/*!
+@brief
+ Sets \lt_p{*event_rules} to the descriptors of the
+ \lt_obj_rers of the \lt_obj_channel named \lt_p{channel_name}
+ within the recording session handle \lt_p{handle}.
+
+@ingroup api_channel
+
+@param[in] handle
+ Recording session handle which contains the name of the
+ recording session and the summary
+ of the \lt_obj_domain which own the channel (named
+ \lt_p{channel_name}) of which to get the recording event rule
+ descriptors.
+@param[in] channel_name
+ Name of the channel, within \lt_p{handle}, of which to get all the
+ recording event rule descriptors.
+@param[out] event_rules
+ @parblock
+ <strong>On success</strong>, this function sets \lt_p{*event_rules}
+ to the recording event rule descriptors.
+
+ Free \lt_p{*event_rules} with <code>free()</code>.
+ @endparblock
+
+@returns
+ The number of items in \lt_p{*event_rules} on success, or a
+ \em negative #lttng_error_code enumerator otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{handle}
+@lt_pre_valid_c_str{handle->session_name}
+@lt_pre_sess_exists{handle->session_name}
+@pre
+ \lt_p{handle->domain} is valid as per the documentation of
+ #lttng_domain.
+@lt_pre_not_null{channel_name}
+@pre
+ \lt_p{channel_name} names an existing channel within the recording
+ session and tracing domain of \lt_p{handle}.
+@lt_pre_not_null{event_rules}
+*/
LTTNG_EXPORT extern int lttng_list_events(struct lttng_handle *handle,
const char *channel_name,
- struct lttng_event **events);
+ struct lttng_event **event_rules);
-/*
- * Create an lttng_event.
- *
- * This creation function, introduced in LTTng 2.11, works around
- * the fact that the layout of the 'lttng_event' is publicly exposed.
- *
- * It allocates a larger object which exposes the same public fields
- * as a 'struct lttng_event', but also allows the use of the following extended
- * attribute setters:
- * - lttng_event_set_userspace_probe_location();
- *
- * Events created through this function must be destroyed using
- * lttng_event_destroy().
- *
- * Returns a zeroed lttng_event on success, NULL on error.
- */
+/*!
+@brief
+ Creates and returns an empty recording event rule descriptor.
+
+@ingroup api_rer
+
+After you create a recording event rule descriptor with this function,
+you can modify its properties and call
+lttng_enable_event_with_exclusions() to create and enable a recording
+event rule.
+
+@returns
+ @parblock
+ New recording event rule descriptor.
+
+ Destroy the returned recording event rule descriptor with
+ lttng_event_destroy().
+ @endparblock
+
+@sa lttng_event_destroy() --
+ Destroys a recording event rule descriptor.
+*/
LTTNG_EXPORT extern struct lttng_event *lttng_event_create(void);
-/*
- * Destroy an lttng_event.
- *
- * This destruction function, introduced in LTTng 2.11, should only
- * be used with events created by lttng_event_create().
- */
-LTTNG_EXPORT extern void lttng_event_destroy(struct lttng_event *event);
+/*!
+@brief
+ Destroys the recording event rule descriptor \lt_p{event_rule}.
-/*
- * Get the filter expression of a specific LTTng event.
- *
- * If the call is successful, then the filter expression's address is put
- * in *filter_expression. If the event has no filter expression,
- * *filter_expression is set to NULL. The caller does NOT own
- * *filter_expression.
- *
- * Returns 0 on success, or a negative LTTng error code on error.
- */
-LTTNG_EXPORT extern int lttng_event_get_filter_expression(struct lttng_event *event,
- const char **filter_string);
+@ingroup api_rer
-/*
- * Get the number of exclusion names of a specific LTTng event.
- *
- * Returns the number of exclusion names on success, or a negative
- * LTTng error code on error.
- */
-LTTNG_EXPORT extern int lttng_event_get_exclusion_name_count(struct lttng_event *event);
+@note
+ This function doesn't destroy the recording event rule
+ which \lt_p{event_rule} describes: you can't destroy a
+ recording event rule.
-/*
- * Get an LTTng event's exclusion name at a given index.
- *
- * If the call is successful, then the exclusion name string's address
- * is put in *exclusion_name. The caller does NOT own *exclusion_name.
- *
- * Returns 0 on success, or a negative LTTng error code on error.
- */
-LTTNG_EXPORT extern int lttng_event_get_exclusion_name(struct lttng_event *event,
+@param[in] event_rule
+ @parblock
+ Recording event rule descriptor to destroy.
+
+ May be \c NULL.
+ @endparblock
+
+@pre
+ <strong>If not \c NULL</strong>, \lt_p{event_rule} was created with
+ lttng_event_create().
+
+@sa lttng_event_create() --
+ Creates an empty recording event rule descriptor.
+*/
+LTTNG_EXPORT extern void lttng_event_destroy(struct lttng_event *event_rule);
+
+/*!
+@brief
+ Sets \lt_p{*filter_expr} to the
+ \ref api-rer-conds-filter "event payload and context filter"
+ expression of the recording event rule described by
+ \lt_p{event_rule}.
+
+@ingroup api_rer
+
+@param[in] event_rule
+ Descriptor of the recording event rule of which to get the event
+ payload and context filter expression.
+@param[out] filter_expr
+ @parblock
+ <strong>On success</strong>, this function sets \lt_p{*filter_expr}
+ to:
+
+ <dl>
+ <dt>
+ If \lt_p{event_rule} has an event payload and context filter
+ expression
+ <dd>
+ The event payload and context filter
+ expression of \lt_p{event_rule}.
+
+ \lt_p{*filter_expr} remains valid as long as \lt_p{event_rule}
+ exists and you don't modify it.
+
+ <dt>Otherwise
+ <dd>\c NULL
+ </dl>
+ @endparblock
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_not_null{event_rule}
+@lt_pre_not_null{filter_expr}
+
+@sa lttng_event::filter --
+ Indicates whether or not a recording event rule has an event payload
+ and context filter.
+*/
+LTTNG_EXPORT extern int lttng_event_get_filter_expression(struct lttng_event *event_rule,
+ const char **filter_expr);
+
+/*!
+@brief
+ Returns the number of \ref api-rer-conds-event-name "event name"
+ exclusion patterns of the recording
+ event rule described by \lt_p{event_rule}.
+
+@ingroup api_rer
+
+@param[in] event_rule
+ Descriptor of the recording event rule of which to get the number
+ of event name exclusion patterns.
+
+@returns
+ Number of event name exclusion patterns of \lt_p{event_rule}, or a
+ \em negative #lttng_error_code enumerator otherwise.
+
+@lt_pre_not_null{event_rule}
+
+@sa lttng_event_get_exclusion_name() --
+ Returns an event name exclusion pattern by index of a recording
+ event rule.
+@sa lttng_event::exclusion --
+ Indicates whether or not a recording event rule has event name
+ exclusion patterns.
+*/
+LTTNG_EXPORT extern int lttng_event_get_exclusion_name_count(struct lttng_event *event_rule);
+
+/*!
+@brief
+ Sets \lt_p{*event_name_exclusion} to the
+ \ref api-rer-conds-event-name "event name" exclusion
+ pattern at index \lt_p{index} of the recording event rule described
+ by \lt_p{event_rule}.
+
+@ingroup api_rer
+
+@param[in] event_rule
+ Descriptor of the recording event rule of which to get the event
+ name exclusion pattern at index \lt_p{index}.
+@param[in] index
+ Index of the event name exclusion pattern to get from
+ \lt_p{event_rule}.
+@param[out] event_name_exclusion
+ @parblock
+ <strong>On success</strong>, this function sets
+ \lt_p{*event_name_exclusion} to the event name exclusion pattern at
+ index \lt_p{index} of
+ \lt_p{event_rule}.
+
+ \lt_p{*event_name_exclusion} remains valis as long as
+ \lt_p{event_rule} exists and you don't modify it.
+ @endparblock
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_not_null{event_rule}
+@pre
+ \lt_p{index} is less than the number of event name exclusion
+ patterns (as returned by lttng_event_get_exclusion_name_count())
+ of \lt_p{event_rule}.
+@lt_pre_not_null{event_name_exclusion}
+
+@sa lttng_event_get_exclusion_name_count() --
+ Returns the number of event name exclusion patterns of a recording
+ event rule.
+*/
+LTTNG_EXPORT extern int lttng_event_get_exclusion_name(struct lttng_event *event_rule,
size_t index,
- const char **exclusion_name);
+ const char **event_name_exclusion);
-/*
- * Get the userspace probe location of a specific LTTng event.
- * If the call is successful, then a pointer to the probe location is returned.
- * If the event has no probe location a NULL pointer is returned. The caller
- * does not own the returned probe location.
- */
+/*!
+@brief
+ Returns the Linux uprobe location of the recording event rule
+ described by \lt_p{event_rule}.
+
+@ingroup api_rer
+
+@param[in] event_rule
+ Descriptor of the recording event rule of which to get the
+ Linux uprobe location.
+
+@returns
+ @parblock
+ Linux uprobe location of the recording event rule described by
+ \lt_p{event_rule}, or \c NULL if none.
+
+ The returned location remains valid as long as \lt_p{event_rule}
+ exists and you don't modify it.
+ @endparblock
+
+@lt_pre_not_null{event_rule}
+@pre
+ \lt_p{event_rule->type} (see lttng_event::type) is
+ #LTTNG_EVENT_USERSPACE_PROBE.
+
+@sa lttng_event_set_userspace_probe_location() --
+ Sets the Linux uprobe location of a recording event rule.
+@sa \ref api-rer-conds-inst-pt-type "Instrumentation point type condition".
+*/
LTTNG_EXPORT extern const struct lttng_userspace_probe_location *
-lttng_event_get_userspace_probe_location(const struct lttng_event *event);
+lttng_event_get_userspace_probe_location(const struct lttng_event *event_rule);
-/*
- * Set an LTTng event's userspace probe location.
- *
- * If the call is successful, then the probe location is set to the event. The
- * ownership of the probe_location is given to the event.
- *
- * Note that the event must have been created using 'lttng_event_create()' in
- * order for this call to succeed.
- *
- * Returns 0 on success, or a negative LTTng error code on error.
- */
+/*!
+@brief
+ Sets the Linux uprobe location of the recording event rule described
+ by \lt_p{event_rule} to \lt_p{location}.
+
+@ingroup api_rer
+
+@param[in] event_rule
+ Descriptor of the recording event rule of which to set the
+ Linux uprobe location to \lt_p{location}.
+@param[in] location
+ New Linux uprobe location of \lt_p{event_rule}.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_not_null{event_rule}
+@pre
+ \lt_p{event_rule} was created with lttng_event_create().
+@pre
+ \lt_p{event_rule->type} (see lttng_event::type) is
+ #LTTNG_EVENT_USERSPACE_PROBE.
+@lt_pre_not_null{location}
+
+@post
+ <strong>On success</strong>, \lt_p{*location} is invalid
+ (its ownership is transfered to \lt_p{event_rule}).
+
+@sa lttng_event_get_userspace_probe_location() --
+ Returns the Linux uprobe location of a recording event rule.
+@sa \ref api-rer-conds-inst-pt-type "Instrumentation point type condition".
+*/
LTTNG_EXPORT extern int
-lttng_event_set_userspace_probe_location(struct lttng_event *event,
- struct lttng_userspace_probe_location *probe_location);
+lttng_event_set_userspace_probe_location(struct lttng_event *event_rule,
+ struct lttng_userspace_probe_location *location);
-/*
- * List the available tracepoints of a specific lttng domain.
- *
- * The handle CAN NOT be NULL.
- *
- * Return the size (number of entries) of the "lttng_event" array. Caller must
- * free events. On error a negative LTTng error code is returned.
- */
+/*!
+@brief
+ Sets \lt_p{*descrs} to the
+ \ref api-rer-inst-pt-descr "descriptors" of the
+ available LTTng tracepoints or Java/Python loggers for the
+ \lt_obj_domain of \lt_p{handle}.
+
+@ingroup api_inst_pt
+
+@param[in] handle
+ @parblock
+ Recording session handle which contains the summary of the
+ \lt_obj_domain which offers the LTTng tracepoints or Java/Python
+ loggers of which to get the descriptors.
+
+ This function ignores \lt_p{handle->session_name}.
+ @endparblock
+@param[out] descrs
+ @parblock
+ <strong>On success</strong>, this function sets \lt_p{*descrs}
+ to the descriptors of the available tracepoints or Java/Python
+ loggers of \lt_p{handle}.
+
+ Free \lt_p{*descrs} with <code>free()</code>.
+ @endparblock
+
+@returns
+ The number of items in \lt_p{*descrs} on success, or a \em
+ negative #lttng_error_code enumerator otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{handle}
+@pre
+ \lt_p{handle->domain} is valid as per the documentation of
+ #lttng_domain.
+@lt_pre_not_null{descrs}
+
+@sa lttng_list_tracepoint_fields() --
+ Returns all the field descriptions of all the available LTTng
+ tracepoints.
+@sa lttng_list_syscalls() --
+ Returns the descriptors of all the available Linux system calls.
+*/
LTTNG_EXPORT extern int lttng_list_tracepoints(struct lttng_handle *handle,
- struct lttng_event **events);
+ struct lttng_event **descrs);
-/*
- * List the available tracepoints fields of a specific lttng domain.
- *
- * The handle CAN NOT be NULL.
- *
- * Return the size (number of entries) of the "lttng_event_field" array.
- * Caller must free fields. On error a negative LTTng error code is
- * returned.
- */
+/*!
+@brief
+ Sets \lt_p{*fields} to the field descriptions of all the available
+ LTTng tracepoints for the \lt_obj_domain of \lt_p{handle}.
+
+@ingroup api_inst_pt
+
+@param[in] handle
+ @parblock
+ Recording session handle which contains the summary of the
+ \lt_obj_domain which offers the LTTng tracepoints of which to get
+ the field descriptions.
+
+ This function ignores \lt_p{handle->session_name}.
+ @endparblock
+@param[out] fields
+ @parblock
+ <strong>On success</strong>, this function sets \lt_p{*fields}
+ to the descriptions of the available LTTng tracepoint fields of
+ \lt_p{handle}.
+
+ Each #lttng_event_field instance in \lt_p{*fields} contains a
+ pointer to the \ref api-rer-inst-pt-descr "descriptor" of
+ a tracepoint which contains the described field
+ (lttng_event_field::event member).
+
+ Free \lt_p{*fields} with <code>free()</code>.
+ @endparblock
+
+@returns
+ The number of items in \lt_p{*fields} on success, or a \em
+ negative #lttng_error_code enumerator otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{handle}
+@pre
+ \lt_p{handle->domain} is valid as per the documentation of
+ #lttng_domain.
+@lt_pre_not_null{fields}
+
+@sa lttng_list_tracepoints() --
+ Returns the descriptors of all the available LTTng tracepoints
+ or Java/Python loggers.
+@sa lttng_list_syscalls() --
+ Returns the descriptors of all the available Linux system calls.
+*/
LTTNG_EXPORT extern int lttng_list_tracepoint_fields(struct lttng_handle *handle,
struct lttng_event_field **fields);
-/*
- * List the available kernel syscall.
- *
- * Return the size (number of entries) of the allocated "lttng_event" array.
- * All events in will be of type syscall. Caller must free events. On error a
- * negative LTTng error code is returned.
- */
-LTTNG_EXPORT extern int lttng_list_syscalls(struct lttng_event **events);
+/*!
+@brief
+ Sets \lt_p{*descrs} to the
+ \ref api-rer-inst-pt-descr "descriptors" of the
+ available Linux system calls for the
+ #LTTNG_DOMAIN_KERNEL tracing domain.
-/*
- * Add context to event(s) for a specific channel (or for all).
- *
- * If the channel_name is NULL and they are no channel for the domain, the
- * default channel is created (channel0). The context is then added on ALL
- * channels since no name was specified.
- *
- * The event_name is ignored since adding a context to an event is not possible
- * for now.
- *
- * Return 0 on success else a negative LTTng error code.
- */
+@ingroup api_inst_pt
+
+@param[out] descrs
+ @parblock
+ <strong>On success</strong>, this function sets \lt_p{*descrs}
+ to the available system calls.
+
+ The #lttng_event instances of \lt_p{*descrs} have an
+ lttng_event::flags member which indicates whether the described
+ system call is 32-bit, 64-bit, or both.
+
+ Free \lt_p{*descrs} with <code>free()</code>.
+ @endparblock
+
+@returns
+ The number of items in \lt_p{*descrs} on success, or a \em
+ negative #lttng_error_code enumerator otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{descrs}
+
+@sa lttng_list_tracepoint_fields() --
+ Returns all the field descriptions of all the available LTTng
+ tracepoints.
+@sa lttng_list_syscalls() --
+ Returns the descriptors of all the available Linux system calls.
+*/
+LTTNG_EXPORT extern int lttng_list_syscalls(struct lttng_event **descrs);
+
+/*!
+@brief
+ Makes the future \ref api_rer "event records" of the
+ \lt_obj_channel named \lt_p{channel_name} (or of a default channel
+ or all the channels if \c NULL) within the
+ \lt_obj_session and \lt_obj_domain of \lt_p{handle}
+ have a context field described by \lt_p{context_field_descriptor}.
+
+@ingroup api_channel
+
+Context values (for example, the ID of the current process, the
+instruction pointer, or the hostname) are always available during
+tracing. This function makes LTTng record a specific context value as a
+field for each future event record of the selected channel(s).
+
+@param[in] handle
+ Recording session handle which contains the name of the recording
+ session and the summary of the \lt_obj_domain which own the
+ channel(s) to select.
+@param[in] context_field_descriptor
+ Descriptor of the context field to add to each event record of
+ the selected channel(s).
+@param[in] event_name
+ Unused: must be \c NULL.
+@param[in] channel_name
+ @parblock
+ Name of the channel to select.
+
+ If \c NULL, then:
+
+ <dl>
+ <dt>
+ If the recording session and tracing domain of
+ \lt_p{handle} have no channels
+ <dd>
+ LTTng creates a new, default channel named \c channel0 within
+ \lt_p{handle} which becomes the selected channel.
+
+ <dt>Otherwise
+ <dd>
+ LTTng selects all the channels of \lt_p{handle}.
+ </dl>
+ @endparblock
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{handle}
+@lt_pre_valid_c_str{handle->session_name}
+@lt_pre_sess_exists{handle->session_name}
+@lt_pre_sess_never_active{handle->session_name}
+@pre
+ \lt_p{handle->domain} is valid (you passed a
+ \lt_obj_domain summary to
+ lttng_create_handle() when you created \lt_p{handle}).
+@pre
+ \lt_p{context_field_descriptor} is valid according to the
+ documentation of #lttng_event_context.
+@pre
+ \lt_p{event_name} is \c NULL.
+@pre
+ <strong>If not \c NULL</strong>, \lt_p{channel_name} names an
+ existing channel within the recording session and tracing domain of
+ \lt_p{handle}.
+*/
LTTNG_EXPORT extern int lttng_add_context(struct lttng_handle *handle,
- struct lttng_event_context *ctx,
+ struct lttng_event_context *context_field_descriptor,
const char *event_name,
const char *channel_name);
-/*
- * Create or enable an event (or events) for a channel.
- *
- * If the event you are trying to enable does not exist, it will be created,
- * else it is enabled. If channel_name is NULL, the default channel is used
- * (channel0).
- *
- * The handle and ev params can not be NULL.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-LTTNG_EXPORT extern int
-lttng_enable_event(struct lttng_handle *handle, struct lttng_event *ev, const char *channel_name);
+/*!
+@brief
+ Alias of lttng_enable_event_with_exclusions() which passes the
+ \ref api-rer-conds-filter "event payload and context filter"
+ expression of \lt_p{event_rule}
+ as the \lt_p{filter_expr} parameter and the
+ \ref api-rer-conds-event-name "event name" exclusion patterns
+ of \lt_p{event_rule} as the
+ \lt_p{event_name_exclusion_count} and
+ \lt_p{event_name_exclusions} parameters.
-/*
- * Create or enable an event with a specific filter.
- *
- * If the event you are trying to enable does not exist, it will be created,
- * else it is enabled.
- * If ev is NULL, all events are enabled with that filter.
- * If channel_name is NULL, the default channel is used (channel0) and created
- * if not found.
- * If filter_expression is NULL, an event without associated filter is
- * created.
- *
- * Return 0 on success else a negative LTTng error code.
- */
+@ingroup api_rer
+
+This function is equivalent to:
+
+@code
+int ret;
+int i;
+char **event_name_exclusions = NULL;
+const char *filter_expr = NULL;
+const int event_name_exclusion_count = lttng_event_get_exclusion_name_count(event_rule);
+
+assert(event_name_exclusion_count >= 0);
+
+if (event_name_exclusion_count > 0) {
+ event_name_exclusions = calloc(event_name_exclusion_count,
+ sizeof(*event_name_exclusions));
+ assert(event_name_exclusions);
+
+ for (i = 0; i < event_name_exclusion_count; i++) {
+ const char *event_name_exclusion;
+
+ ret = lttng_event_get_exclusion_name(event_rule, (size_t) i,
+ &event_name_exclusion);
+ assert(ret == 0);
+ event_name_exclusions[i] = (char *) event_name_exclusion;
+ }
+}
+
+ret = lttng_event_get_filter_expression(event_rule, &filter_expr);
+assert(ret == 0);
+ret = lttng_enable_event_with_exclusions(handle, event_rule, channel_name,
+ filter_expr,
+ event_name_exclusion_count,
+ event_name_exclusions);
+free(event_name_exclusions);
+return ret;
+@endcode
+*/
+LTTNG_EXPORT extern int lttng_enable_event(struct lttng_handle *handle,
+ struct lttng_event *event_rule,
+ const char *channel_name);
+
+/*!
+@brief
+ Alias of lttng_enable_event_with_exclusions() which passes the
+ the \ref api-rer-conds-event-name "event name" exclusion patterns
+ of \lt_p{event_rule} as the
+ \lt_p{event_name_exclusion_count} and
+ \lt_p{event_name_exclusions} parameters.
+
+@ingroup api_rer
+
+This function is equivalent to:
+
+@code
+int ret;
+int i;
+char **event_name_exclusions = NULL;
+const char *filter_expr = NULL;
+const int event_name_exclusion_count = lttng_event_get_exclusion_name_count(event_rule);
+
+assert(event_name_exclusion_count >= 0);
+
+if (event_name_exclusion_count > 0) {
+ event_name_exclusions = calloc(event_name_exclusion_count,
+ sizeof(*event_name_exclusions));
+ assert(event_name_exclusions);
+
+ for (i = 0; i < event_name_exclusion_count; i++) {
+ const char *event_name_exclusion;
+
+ ret = lttng_event_get_exclusion_name(event_rule, (size_t) i,
+ &event_name_exclusion);
+ assert(ret == 0);
+ event_name_exclusions[i] = (char *) event_name_exclusion;
+ }
+}
+
+ret = lttng_enable_event_with_exclusions(handle, event_rule, channel_name,
+ filter_expr,
+ event_name_exclusion_count,
+ event_name_exclusions);
+free(event_name_exclusions);
+return ret;
+@endcode
+*/
LTTNG_EXPORT extern int lttng_enable_event_with_filter(struct lttng_handle *handle,
- struct lttng_event *event,
+ struct lttng_event *event_rule,
const char *channel_name,
- const char *filter_expression);
+ const char *filter_expr);
-/*
- * Create or enable an event with a filter and/or exclusions.
- *
- * If the event you are trying to enable does not exist, it will be created,
- * else it is enabled.
- * If ev is NULL, all events are enabled with the filter and exclusion options.
- * If channel_name is NULL, the default channel is used (channel0) and created
- * if not found.
- * If filter_expression is NULL, an event without associated filter is
- * created.
- * If exclusion count is zero, the event will be created without exclusions.
- *
- * Return 0 on success else a negative LTTng error code.
- */
+/*!
+@brief
+ Creates or enables a recording event rule
+ described by \lt_p{event_rule}, having the
+ \ref api-rer-conds-filter "event payload and context filter"
+ expression \lt_p{filter_expr} and the
+ \ref api-rer-conds-event-name "event name" exclusion patterns
+ \lt_p{event_name_exclusions}, within
+ the \lt_obj_channel named \lt_p{channel_name}
+ (or within a default channel if \c NULL) within the recording
+ session handle \lt_p{handle}.
+
+@ingroup api_rer
+
+This function, depending on the
+\ref api-rer-conds-inst-pt-type "instrumentation point type",
+\ref api-rer-conds-event-name "event name",
+and \ref api-rer-conds-ll "log level" conditions of \lt_p{event_rule},
+as well as on \lt_p{filter_expr} and \lt_p{event_name_exclusions}:
+
+<dl>
+ <dt>
+ The conditions and parameters describe an existing recording event
+ rule within the selected channel
+ <dd>
+ Enables the existing recording event rule.
+
+ <dt>Otherwise
+ <dd>
+ Creates and enables a new recording event rule within the
+ selected channel.
+</dl>
+
+If \lt_p{event_rule->type} is #LTTNG_EVENT_ALL and
+\lt_p{handle->domain.type} is #LTTNG_DOMAIN_KERNEL, then this
+function actually creates or enables two recording event rules: one with
+the #LTTNG_EVENT_TRACEPOINT type, and one with the #LTTNG_EVENT_SYSCALL
+type.
+
+@param[in] handle
+ Recording session handle which contains the name of the recording
+ session and the summary of the \lt_obj_domain which own the selected
+ channel.
+@param[in] event_rule
+ @parblock
+ Descriptor of the recording event rule to create or enable.
+
+ This function:
+
+ - Ignores any event payload and context filter
+ expression within \lt_p{event_rule}: it always uses
+ \lt_p{filter_expr}.
+
+ - Ignores any event name exclusion patterns within
+ \lt_p{event_rule}: it always uses \lt_p{event_name_exclusions}.
+ @endparblock
+@param[in] channel_name
+ @parblock
+ Name of the channel, within \lt_p{handle}, to select (that is,
+ containing the recording event rule to create or enable).
+
+ If \c NULL, then this function uses \c channel0. If no channel named
+ \c channel0 within \lt_p{handle} exists, then LTTng creates a new,
+ default channel named as such and selects it before it creates the
+ recording event rule described by \lt_p{event_rule}.
+ @endparblock
+@param[in] filter_expr
+ @parblock
+ Event payload and context filter expression of the recording
+ event rule to create or enable.
+
+ <strong>If \c NULL</strong>, the created or enabled recording event
+ rule has no event payload and context filter expression.
+
+ This parameter, even when \c NULL, overrides any existing
+ event payload and context filter expression within
+ \lt_p{event_rule}.
+ @endparblock
+@param[in] event_name_exclusion_count
+ Number of items in \lt_p{event_name_exclusions}.
+@param[in] event_name_exclusions
+ @parblock
+ Event name exclusion patterns of the recording event rule to create
+ or enable.
+
+ This function copies the strings of this array.
+
+ \lt_p{event_name_exclusion_count} indicates the size of this
+ array, which may be \c NULL if \lt_p{event_name_exclusion_count}
+ is 0.
+
+ This parameter, even when \c NULL or empty, overrides any existing
+ event name exclusion patterns within \lt_p{event_rule}.
+ @endparblock
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{handle}
+@lt_pre_valid_c_str{handle->session_name}
+@lt_pre_sess_exists{handle->session_name}
+@pre
+ \lt_p{handle->domain} is valid as per the documentation of
+ #lttng_domain.
+@lt_pre_not_null{event_rule}
+@pre
+ \lt_p{event_rule} is \ref api-rer-valid-event-struct "valid".
+@pre
+ <strong>If \lt_p{handle->domain.type} is \em not
+ #LTTNG_DOMAIN_KERNEL</strong>, then \lt_p{event_rule->type} is
+ #LTTNG_EVENT_TRACEPOINT.
+@pre
+ <strong>If \lt_p{handle->domain.type} is \em not
+ #LTTNG_DOMAIN_UST</strong>, then \lt_p{event_name_exclusion_count}
+ is 0.
+@pre
+ <strong>If this function must enable an existing recording event
+ rule</strong>, then the recording event rule to enable is disabled.
+@pre
+ <strong>If not \c NULL</strong>, \lt_p{channel_name} names an
+ existing channel within the recording session and tracing domain of
+ \lt_p{handle}.
+@pre
+ <strong>If \lt_p{channel_name} is \c NULL</strong>, then
+ \lt_p{handle} contains either no channels or a default channel named
+ \c channel0.
+@pre
+ <strong>If not \c NULL</strong>, \lt_p{filter_expr} is a valid
+ event payload and context filter expression.
+@pre
+ \lt_p{event_name_exclusion_count} ≥ 0.
+
+@sa lttng_enable_event() --
+ Alias which calls this function with the event payload and context
+ filter expression and event name exclusion patterns of the
+ recording event rule descriptor.
+@sa lttng_enable_event_with_filter() --
+ Alias which calls this function with the event name exclusion
+ patterns of the recording event rule descriptor.
+@sa lttng_disable_event_ext() --
+ Disables a recording event rule.
+*/
LTTNG_EXPORT extern int lttng_enable_event_with_exclusions(struct lttng_handle *handle,
- struct lttng_event *event,
+ struct lttng_event *event_rule,
const char *channel_name,
- const char *filter_expression,
- int exclusion_count,
- char **exclusion_names);
+ const char *filter_expr,
+ int event_name_exclusion_count,
+ char **event_name_exclusions);
-/*
- * Disable event(s) of a channel and domain.
- *
- * If name is NULL, all events are disabled.
- * If channel_name is NULL, the default channel is used (channel0).
- *
- * Return 0 on success else a negative LTTng error code.
- */
+/*!
+@brief
+ Alias of lttng_disable_event_ext() which creates a temporary
+ recording event rule descriptor, settings its
+ lttng_event::name member to \lt_p{event_name} if not \c NULL and
+ its lttng_event::type member to #LTTNG_EVENT_ALL.
+
+@ingroup api_rer
+
+This function is equivalent to:
+
+@code
+struct lttng_event event_rule = { 0 };
+
+event_rule.type = LTTNG_EVENT_ALL;
+
+if (event_name) {
+ strcpy(event_rule.name, event_name);
+}
+
+event_rule.loglevel = -1;
+return lttng_disable_event_ext(handle, &event_rule, channel_name, NULL);
+@endcode
+*/
LTTNG_EXPORT extern int
-lttng_disable_event(struct lttng_handle *handle, const char *name, const char *channel_name);
+lttng_disable_event(struct lttng_handle *handle, const char *event_name, const char *channel_name);
-/*
- * Disable event(s) of a channel and domain.
- *
- * Takes a struct lttng_event as parameter.
- * If channel_name is NULL, the default channel is used (channel0).
- *
- * Currently, @filter_expression must be NULL. (disabling specific
- * filter expressions not implemented)
- * Currently, only LTTNG_EVENT_ALL and LTTNG_EVENT_SYSCALL event types
- * are implemented for field @ev.
- *
- * Return 0 on success else a negative LTTng error code.
- */
+/*!
+@brief
+ Disables recording event rules by
+ \ref api-rer-conds-inst-pt-type "instrumentation point type" and
+ \ref api-rer-conds-event-name "event name" condition within the
+ \lt_obj_channel named \lt_p{channel_name}
+ (or within a default channel if \c NULL) within the recording
+ session handle \lt_p{handle}.
+
+@ingroup api_rer
+
+Depending on \lt_p{event_rule->name}, this function:
+
+<dl>
+ <dt>Not empty
+ <dd>
+ Depending on \lt_p{event_rule->type}:
+
+ <dl>
+ <dt>#LTTNG_EVENT_ALL
+ <dd>
+ Disables \em all the recording event rules of which the event
+ name pattern is exactly \lt_p{event_rule->name} within the
+ selected channel.
+
+ <dt>Otherwise
+ <dd>
+ Disables all the recording event rules of which the
+ instrumentation point type is
+ \lt_p{event_rule->type} and the event
+ name pattern is exactly \lt_p{event_rule->name} within the
+ selected channel.
+
+ Only supported when \lt_p{handle->domain.type} is
+ #LTTNG_DOMAIN_KERNEL.
+ </dl>
+
+ <dt>Empty
+ <dd>
+ Depending on \lt_p{event_rule->type}:
+
+ <dl>
+ <dt>#LTTNG_EVENT_ALL
+ <dd>
+ Disables \em all the recording event rules within the selected
+ channel.
+
+ <dt>Otherwise
+ <dd>
+ Disables all the recording event rules of which the
+ instrumentation point type is
+ \lt_p{event_rule->type} within the
+ selected channel.
+
+ Only supported when \lt_p{handle->domain.type} is
+ #LTTNG_DOMAIN_KERNEL.
+ </dl>
+</dl>
+
+This function ignores all the other \ref api-rer-conds "condition"
+properties of \lt_p{event_rule}.
+
+To use this function, create a temporary, zeroed
+\link #lttng_event recording event rule descriptor\endlink,
+setting only:
+
+- <strong>Optional, and only if \lt_p{handle->domain.type}
+ is #LTTNG_DOMAIN_KERNEL</strong>: its lttng_event::type member.
+
+- <strong>Optional</strong>: its lttng_event::name member
+
+- Its lttng_event::loglevel member to -1.
+
+For example:
+
+@code
+struct lttng_event event_rule = { 0 };
+
+event_rule.type = LTTNG_EVENT_SYSCALL;
+strcpy(event_rule.name, "open*");
+event_rule.loglevel = -1;
+@endcode
+
+@param[in] handle
+ Recording session handle which contains the name of the recording
+ session and the summary of the \lt_obj_domain which own the selected
+ channel.
+@param[in] event_rule
+ @parblock
+ Recording event rule descriptor which contains the
+ instrumentation point type and event name conditions to consider
+ to disable recording event rules within the selected channel.
+ @endparblock
+@param[in] channel_name
+ @parblock
+ Name of the channel, within \lt_p{handle}, to select (that is,
+ containing the recording event rules to disable).
+
+ If \c NULL, then this function uses \c channel0.
+ @endparblock
+@param[in] filter_expr
+ Unused: must be \c NULL.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{handle}
+@lt_pre_valid_c_str{handle->session_name}
+@lt_pre_sess_exists{handle->session_name}
+@pre
+ \lt_p{handle->domain} is valid as per the documentation of
+ #lttng_domain.
+@lt_pre_not_null{event_rule}
+@pre
+ <strong>If \lt_p{handle->domain.type} is \em not
+ #LTTNG_DOMAIN_KERNEL</strong>, then \lt_p{event_rule->type}
+ is #LTTNG_EVENT_ALL.
+@pre
+ <strong>If not #LTTNG_EVENT_ALL</strong>, then
+ \lt_p{event_rule->type} is the instrumentation point type of at
+ least one Linux kernel recording event rule within the selected
+ channel.
+@pre
+ <strong>If not empty</strong>, then \lt_p{event_rule->name} is the
+ exact event name pattern of at least one recording event rule within
+ the selected channel.
+@pre
+ The recording event rules to disable are enabled.
+@pre
+ <strong>If not \c NULL</strong>, then \lt_p{channel_name} names an
+ existing channel within the recording session and tracing domain of
+ \lt_p{handle}.
+@pre
+ <strong>If \lt_p{channel_name} is \c NULL</strong>, then the
+ channel named \c channel0 exists within the recording session and
+ tracing domain of \lt_p{handle}.
+
+@sa lttng_disable_event() --
+ Alias which calls this function with \lt_p{event_rule->type}
+ set to #LTTNG_EVENT_ALL.
+@sa lttng_enable_event_with_exclusions() --
+ Creates or enables a recording event rule.
+*/
LTTNG_EXPORT extern int lttng_disable_event_ext(struct lttng_handle *handle,
- struct lttng_event *ev,
+ struct lttng_event *event_rule,
const char *channel_name,
- const char *filter_expression);
+ const char *filter_expr);
#ifdef __cplusplus
}
extern "C" {
#endif
+/*!
+@addtogroup api_session
+@{
+*/
+
/*
* Handle used as a context for commands.
*
* The structures should be initialized to zero before use.
*/
#define LTTNG_HANDLE_PADDING1 16
+
+/*!
+@brief
+ Recording session handle.
+
+Such a structure is a pair of a \ref api_session "recording session"
+name and a \ref api-channel-domain "tracing domain" summary.
+
+Some functions which accept a recording session handle parameter ignore
+the recording session name or the tracing domain summary.
+
+Create a recording session handle with lttng_create_handle().
+
+Destroy a recording session handle with lttng_destroy_handle().
+*/
struct lttng_handle {
+ /// \ref api_session "Recording session" name.
char session_name[LTTNG_NAME_MAX];
+
+ /// \ref api-channel-domain "Tracing domain" summary.
struct lttng_domain domain;
char padding[LTTNG_HANDLE_PADDING1];
};
-/*
- * Create an handle used as a context for every request made to the library.
- *
- * This handle contains the session name and domain on which the command will
- * be executed. A domain is basically a tracer like the kernel or user space.
- *
- * A NULL domain indicates that the handle is not bound to a specific domain.
- * This is mostly used for actions that apply on a session and not on a domain
- * (e.g lttng_set_consumer_url).
- *
- * Return a newly allocated handle that should be freed using
- * lttng_destroy_handle. On error, NULL is returned.
- */
+/*!
+@brief
+ Creates and returns a recording session handle from the
+ \ref api_session "recording session" name
+ \lt_p{session_name} and the optional
+ \ref api-channel-domain "tracing domain" summary \lt_p{domain}.
+
+@param[in] session_name
+ @parblock
+ Recording session name part of the recording session handle to
+ create.
+
+ May be \c NULL.
+ @endparblock
+@param[in] domain
+ @parblock
+ Tracing domain summary part of the recording session handle to
+ create.
+
+ May be \c NULL.
+ @endparblock
+
+@returns
+ @parblock
+ New recording session handle.
+
+ Destroy the returned handle with lttng_destroy_handle().
+ @endparblock
+
+@sa lttng_destroy_handle() --
+ Destroys a recording session handle.
+*/
LTTNG_EXPORT extern struct lttng_handle *lttng_create_handle(const char *session_name,
struct lttng_domain *domain);
-/*
- * Destroy an handle that has been previously created with lttng_create_handle.
- *
- * It free the given pointer making it unusable.
- */
+/*!
+@brief
+ Destroys the recording session handle \lt_p{handle}.
+
+@note
+ @parblock
+ This function doesn't destroy the recording session named
+ \lt_p{handle->session_name}, but only the handle itself.
+
+ Use lttng_destroy_session_ext() to destroy a recording session.
+ @endparblock
+
+@param[in] handle
+ @parblock
+ Recording session handle to destroy.
+
+ May be \c NULL.
+ @endparblock
+*/
LTTNG_EXPORT extern void lttng_destroy_handle(struct lttng_handle *handle);
+/// @}
+
#ifdef __cplusplus
}
#endif
#ifndef LTTNG_ERROR_H
#define LTTNG_ERROR_H
-#include <lttng/lttng-export.h>
-
#ifdef __cplusplus
extern "C" {
#endif
+#include <lttng/lttng-export.h>
+
+/*!
+@addtogroup api_gen
+@{
+*/
+
+/*!
+@brief
+ General error codes.
+
+Many functions, most of them dating from older liblttng-ctl versions,
+return this type (or an \c int value which is equal to the negation of
+one of those enumerators).
+
+Not all error codes are relevant to a given function: this API
+documentation makes an effort to document the most relevant status codes
+for each function. This is not always possible, however, as LTTng is
+made of multiple interacting components (tracers, consumer daemons,
+session daemons, and the rest); those error codes can move from one to
+another and the possible error codes of a given liblttng-ctl function
+can change from version to version.
+
+@sa lttng_strerror() --
+ Returns a human-readable message for a general error code, positive
+ or negative.
+*/
enum lttng_error_code {
- LTTNG_OK = 10, /* Ok */
- LTTNG_ERR_UNK = 11, /* Unknown Error */
- LTTNG_ERR_UND = 12, /* Undefined command */
- LTTNG_ERR_SESSION_STARTED = 13, /* Session is running */
- LTTNG_ERR_UNKNOWN_DOMAIN = 14, /* Tracing domain not known */
- LTTNG_ERR_NOT_SUPPORTED = 15, /* Operation not supported */
- LTTNG_ERR_NO_SESSION = 16, /* No session found */
- LTTNG_ERR_CREATE_DIR_FAIL = 17, /* Create directory fail */
- LTTNG_ERR_SESSION_FAIL = 18, /* Create session fail */
- LTTNG_ERR_NO_SESSIOND = 19, /* No session daemon available */
- LTTNG_ERR_SET_URL = 20, /* Error setting URL */
- LTTNG_ERR_URL_EXIST = 21, /* URL already exists. */
- LTTNG_ERR_BUFFER_NOT_SUPPORTED = 22, /* Buffer type not supported. */
- LTTNG_ERR_SESS_NOT_FOUND = 23, /* Session by name not found */
- LTTNG_ERR_BUFFER_TYPE_MISMATCH = 24, /* Buffer type mismatched. */
- LTTNG_ERR_FATAL = 25, /* Fatal error */
- LTTNG_ERR_NOMEM = 26, /* Not enough memory. */
+ /* Internal codes */
+ /// @cond INTERNAL_ERR_CODES
LTTNG_ERR_SELECT_SESS = 27, /* Must select a session */
- LTTNG_ERR_EXIST_SESS = 28, /* Session name already exist */
- LTTNG_ERR_NO_EVENT = 29, /* No event found */
- LTTNG_ERR_CONNECT_FAIL = 30, /* Unable to connect to unix socket */
- LTTNG_ERR_SNAPSHOT_OUTPUT_EXIST = 31, /* Snapshot output already exists */
- LTTNG_ERR_EPERM = 32, /* Permission denied */
- LTTNG_ERR_KERN_NA = 33, /* Kernel tracer unavailable */
- LTTNG_ERR_KERN_VERSION = 34, /* Kernel tracer not compatible */
- LTTNG_ERR_KERN_EVENT_EXIST = 35, /* Kernel event already exists */
- LTTNG_ERR_KERN_SESS_FAIL = 36, /* Kernel create session failed */
- LTTNG_ERR_KERN_CHAN_EXIST = 37, /* Kernel channel already exists */
- LTTNG_ERR_KERN_CHAN_FAIL = 38, /* Kernel create channel failed */
- LTTNG_ERR_KERN_CHAN_NOT_FOUND = 39, /* Kernel channel not found */
- LTTNG_ERR_KERN_CHAN_DISABLE_FAIL = 40, /* Kernel disable channel failed */
- LTTNG_ERR_KERN_CHAN_ENABLE_FAIL = 41, /* Kernel enable channel failed */
- LTTNG_ERR_KERN_CONTEXT_FAIL = 42, /* Kernel add context failed */
- LTTNG_ERR_KERN_ENABLE_FAIL = 43, /* Kernel enable event failed */
- LTTNG_ERR_KERN_DISABLE_FAIL = 44, /* Kernel disable event failed */
- LTTNG_ERR_KERN_META_FAIL = 45, /* Kernel open metadata failed */
- LTTNG_ERR_KERN_START_FAIL = 46, /* Kernel start trace failed */
- LTTNG_ERR_KERN_STOP_FAIL = 47, /* Kernel stop trace failed */
- LTTNG_ERR_KERN_CONSUMER_FAIL = 48, /* Kernel consumer start failed */
- LTTNG_ERR_KERN_STREAM_FAIL = 49, /* Kernel create stream failed */
- LTTNG_ERR_START_SESSION_ONCE = 50, /* Session needs to be started once. */
- LTTNG_ERR_SNAPSHOT_FAIL = 51, /* Snapshot record failed. */
LTTNG_ERR_NO_STREAM = 52, /* Index without stream on relay. */
- LTTNG_ERR_KERN_LIST_FAIL = 53, /* Kernel listing events failed */
LTTNG_ERR_UST_CALIBRATE_FAIL = 54, /* UST calibration failed */
- LTTNG_ERR_UST_EVENT_ENABLED = 55, /* UST event already enabled. */
- LTTNG_ERR_UST_SESS_FAIL = 56, /* UST create session failed */
- LTTNG_ERR_UST_CHAN_EXIST = 57, /* UST channel already exist */
- LTTNG_ERR_UST_CHAN_FAIL = 58, /* UST create channel failed */
- LTTNG_ERR_UST_CHAN_NOT_FOUND = 59, /* UST channel not found */
- LTTNG_ERR_UST_CHAN_DISABLE_FAIL = 60, /* UST disable channel failed */
LTTNG_ERR_UST_CHAN_ENABLE_FAIL = 61, /* UST enable channel failed */
LTTNG_ERR_CHAN_EXIST = 62, /* Channel already exists. */
- LTTNG_ERR_UST_ENABLE_FAIL = 63, /* UST enable event failed */
- LTTNG_ERR_UST_DISABLE_FAIL = 64, /* UST disable event failed */
LTTNG_ERR_UST_META_FAIL = 65, /* UST open metadata failed */
- LTTNG_ERR_UST_START_FAIL = 66, /* UST start trace failed */
- LTTNG_ERR_UST_STOP_FAIL = 67, /* UST stop trace failed */
- LTTNG_ERR_UST_CONSUMER64_FAIL = 68, /* 64-bit UST consumer start failed */
- LTTNG_ERR_UST_CONSUMER32_FAIL = 69, /* 32-bit UST consumer start failed */
LTTNG_ERR_UST_STREAM_FAIL = 70, /* UST create stream failed */
LTTNG_ERR_SNAPSHOT_NODATA = 71, /* No data in snapshot. */
- LTTNG_ERR_NO_CHANNEL = 72, /* No channel found in the session. */
- LTTNG_ERR_SESSION_INVALID_CHAR = 73, /* Invalid characters found in session name. */
- LTTNG_ERR_UST_LIST_FAIL = 74, /* UST listing events failed */
- LTTNG_ERR_UST_EVENT_EXIST = 75, /* UST event exist */
- LTTNG_ERR_UST_EVENT_NOT_FOUND = 76, /* UST event not found */
- LTTNG_ERR_UST_CONTEXT_EXIST = 77, /* UST context exist */
- LTTNG_ERR_UST_CONTEXT_INVAL = 78, /* UST context invalid */
- LTTNG_ERR_NEED_ROOT_SESSIOND = 79, /* root sessiond is needed */
- LTTNG_ERR_TRACE_ALREADY_STARTED = 80, /* Tracing already started */
- LTTNG_ERR_TRACE_ALREADY_STOPPED = 81, /* Tracing already stopped */
- LTTNG_ERR_KERN_EVENT_ENOSYS = 82, /* Kernel event type not supported */
- LTTNG_ERR_NEED_CHANNEL_NAME = 83, /* Non-default channel exists within session: channel name
- needs to be specified with '-c name' */
- LTTNG_ERR_NO_UST = 84, /* LTTng-UST tracer is not supported. Please rebuild lttng-tools with
- lttng-ust support enabled. */
- LTTNG_ERR_SAVE_FILE_EXIST = 85, /* Session file already exists. */
- LTTNG_ERR_SAVE_IO_FAIL = 86, /* IO error while writing session configuration */
- LTTNG_ERR_LOAD_INVALID_CONFIG = 87, /* Invalid session configuration */
- LTTNG_ERR_LOAD_IO_FAIL = 88, /* IO error while reading a session configuration */
- LTTNG_ERR_LOAD_SESSION_NOENT = 89, /* Session file not found */
- LTTNG_ERR_MAX_SIZE_INVALID = 90, /* Snapshot max size is invalid. */
LTTNG_ERR_MI_OUTPUT_TYPE = 91, /* Invalid MI output format */
LTTNG_ERR_MI_IO_FAIL = 92, /* IO error while writing machine interface output */
LTTNG_ERR_MI_NOT_IMPLEMENTED = 93, /* Mi feature not implemented */
- /* 94 */
- /* 95 */
- /* 96 */
- LTTNG_ERR_INVALID = 97, /* Invalid parameter */
- LTTNG_ERR_NO_USTCONSUMERD = 98, /* No UST consumer detected */
- LTTNG_ERR_NO_KERNCONSUMERD = 99, /* No Kernel consumer detected */
LTTNG_ERR_EVENT_EXIST_LOGLEVEL = 100, /* Event enabled with different loglevel */
- LTTNG_ERR_URL_DATA_MISS = 101, /* Missing network data URL */
- LTTNG_ERR_URL_CTRL_MISS = 102, /* Missing network control URL */
- LTTNG_ERR_ENABLE_CONSUMER_FAIL = 103, /* Enabling consumer failed */
- LTTNG_ERR_RELAYD_CONNECT_FAIL = 104, /* lttng-relayd create session failed */
- LTTNG_ERR_RELAYD_VERSION_FAIL = 105, /* lttng-relayd not compatible */
- LTTNG_ERR_FILTER_INVAL = 106, /* Invalid filter bytecode */
- LTTNG_ERR_FILTER_NOMEM = 107, /* Lack of memory for filter bytecode */
LTTNG_ERR_FILTER_EXIST = 108, /* Filter already exist */
- LTTNG_ERR_NO_CONSUMER = 109, /* No consumer exist for the session */
- LTTNG_ERR_EXCLUSION_INVAL = 110, /* Invalid event exclusion data */
- LTTNG_ERR_EXCLUSION_NOMEM = 111, /* Lack of memory while processing event exclusions */
- LTTNG_ERR_INVALID_EVENT_NAME = 112, /* Invalid event name */
- LTTNG_ERR_INVALID_CHANNEL_NAME = 113, /* Invalid channel name */
- LTTNG_ERR_PROCESS_ATTR_EXISTS = 114, /* Process attribute is already tracked */
- LTTNG_ERR_PROCESS_ATTR_MISSING = 115, /* Process attribute was not tracked */
- LTTNG_ERR_INVALID_CHANNEL_DOMAIN = 116, /* Invalid channel domain */
- LTTNG_ERR_OVERFLOW = 117, /* Overflow occurred. */
- LTTNG_ERR_SESSION_NOT_STARTED = 118, /* Session not started */
- LTTNG_ERR_LIVE_SESSION = 119, /* Live session unsupported */
- LTTNG_ERR_PER_PID_SESSION = 120, /* Per-PID sessions unsupported */
- LTTNG_ERR_KERN_CONTEXT_UNAVAILABLE = 121, /* Context unavailable on this kernel */
- LTTNG_ERR_REGEN_STATEDUMP_FAIL = 122, /* Failed to regenerate the state dump */
- LTTNG_ERR_REGEN_STATEDUMP_NOMEM = 123, /* Failed to regenerate the state dump, not enough
- memory */
- LTTNG_ERR_NOT_SNAPSHOT_SESSION = 124, /* Session is not in snapshot mode. */
- LTTNG_ERR_INVALID_TRIGGER = 125, /* Invalid trigger provided. */
- LTTNG_ERR_TRIGGER_EXISTS = 126, /* Trigger already registered. */
- LTTNG_ERR_TRIGGER_NOT_FOUND = 127, /* Trigger not found. */
LTTNG_ERR_COMMAND_CANCELLED = 128, /* Command cancelled. */
- LTTNG_ERR_ROTATION_PENDING = 129, /* Rotation already pending for this session. */
- LTTNG_ERR_ROTATION_NOT_AVAILABLE = 130, /* Rotate feature not available for this type of
- session (e.g: live) */
- LTTNG_ERR_ROTATION_SCHEDULE_SET = 131, /* Schedule type already set for this session. */
- LTTNG_ERR_ROTATION_SCHEDULE_NOT_SET = 132, /* No schedule of this type set for this session.
- */
- LTTNG_ERR_ROTATION_MULTIPLE_AFTER_STOP = 133, /* Already rotated once after a stop. */
- LTTNG_ERR_ROTATION_WRONG_VERSION = 134, /* Session rotation not supported by this kernel
- tracer version */
- LTTNG_ERR_NO_SESSION_OUTPUT = 135, /* Session has no output configured. */
- LTTNG_ERR_ROTATION_NOT_AVAILABLE_RELAY = 136, /* Rotate feature not available on the relay.
- */
- LTTNG_ERR_AGENT_TRACING_DISABLED = 137, /* Agent tracing disabled. */
- LTTNG_ERR_PROBE_LOCATION_INVAL = 138, /* Invalid userspace probe location. */
- LTTNG_ERR_ELF_PARSING = 139, /* ELF parsing error. */
- LTTNG_ERR_SDT_PROBE_SEMAPHORE = 140, /* SDT probe guarded by a semaphore. */
- LTTNG_ERR_ROTATION_FAIL_CONSUMER = 141, /* Rotation failure on consumer */
LTTNG_ERR_ROTATE_RENAME_FAIL_CONSUMER = 142, /* Rotation rename failure on consumer */
LTTNG_ERR_ROTATION_PENDING_LOCAL_FAIL_CONSUMER = 143, /* Rotation pending check (local)
failure on consumer */
LTTNG_ERR_ROTATION_PENDING_RELAY_FAIL_CONSUMER = 144, /* Rotation pending check (relay)
failure on consumer */
LTTNG_ERR_MKDIR_FAIL_CONSUMER = 145, /* mkdir failure on consumer */
- LTTNG_ERR_CHAN_NOT_FOUND = 146, /* Channel not found */
- LTTNG_ERR_SNAPSHOT_UNSUPPORTED = 147, /* Session configuration does not allow the use of
- snapshots */
- LTTNG_ERR_SESSION_NOT_EXIST = 148, /* The session does not exist on the session daemon */
- LTTNG_ERR_CREATE_TRACE_CHUNK_FAIL_CONSUMER = 149, /* trace chunk creation failure on
- consumer */
- LTTNG_ERR_CLOSE_TRACE_CHUNK_FAIL_CONSUMER = 150, /* trace chunk close failure on consumer */
LTTNG_ERR_TRACE_CHUNK_EXISTS_FAIL_CONSUMER = 151, /* failed to query consumer for trace
chunk existence */
- LTTNG_ERR_INVALID_PROTOCOL = 152, /* a protocol error occurred */
- LTTNG_ERR_FILE_CREATION_ERROR = 153, /* failed to create a file */
- LTTNG_ERR_TIMER_STOP_ERROR = 154, /* failed to stop timer. */
- LTTNG_ERR_ROTATION_NOT_AVAILABLE_KERNEL = 155, /* Rotation feature not supported by the
- kernel tracer. */
- LTTNG_ERR_CLEAR_RELAY_DISALLOWED = 156, /* LTTng-relayd peer does not allow lttng clear
- command. */
- LTTNG_ERR_CLEAR_NOT_AVAILABLE_RELAY = 157, /* Clearing a session is not supported by the
- relay daemon. */
- LTTNG_ERR_CLEAR_FAIL_CONSUMER = 158, /* Clear failure on consumer */
- LTTNG_ERR_ROTATION_AFTER_STOP_CLEAR = 159, /* Session was already cleared since it became
- inactive. */
- LTTNG_ERR_USER_NOT_FOUND = 160, /* User not found. */
- LTTNG_ERR_GROUP_NOT_FOUND = 161, /* Group not found. */
- LTTNG_ERR_UNSUPPORTED_DOMAIN = 162, /* Unsupported domain used. */
- LTTNG_ERR_PROCESS_ATTR_TRACKER_INVALID_TRACKING_POLICY = 163, /* Operation does not apply to
- the process attribute
- tracker's tracking policy
- */
- LTTNG_ERR_EVENT_NOTIFIER_GROUP_NOTIFICATION_FD = 164, /* Error initializing event notifier
- group notification file descriptor
- */
- LTTNG_ERR_INVALID_CAPTURE_EXPRESSION = 165, /* Invalid capture expression. */
- LTTNG_ERR_EVENT_NOTIFIER_REGISTRATION = 166, /* Error registering event notifier to the
- tracer. */
- LTTNG_ERR_EVENT_NOTIFIER_ERROR_ACCOUNTING = 167, /* Error initializing event notifier error
- accounting. */
- LTTNG_ERR_EVENT_NOTIFIER_ERROR_ACCOUNTING_FULL = 168, /* Error event notifier error
- accounting full. */
- LTTNG_ERR_INVALID_ERROR_QUERY_TARGET = 169, /* Invalid error query target. */
- LTTNG_ERR_BUFFER_FLUSH_FAILED = 170, /* Buffer flush failed */
+ /// @endcond
+
+ /// Success.
+ LTTNG_OK = 10,
+
+ /// Unknown error.
+ LTTNG_ERR_UNK = 11,
+
+ /// Undefined command.
+ LTTNG_ERR_UND = 12,
+
+ /*!
+ \lt_obj_c_session already
+ \link lttng_session::enabled started\endlink (active).
+ */
+ LTTNG_ERR_SESSION_STARTED = 13,
+
+ /// Unknown \lt_obj_domain.
+ LTTNG_ERR_UNKNOWN_DOMAIN = 14,
+
+ /// Unsupported operation.
+ LTTNG_ERR_NOT_SUPPORTED = 15,
+
+ /// No \lt_obj_session found.
+ LTTNG_ERR_NO_SESSION = 16,
+
+ /// Failed to create a directory.
+ LTTNG_ERR_CREATE_DIR_FAIL = 17,
+
+ /// Failed to create a \lt_obj_session.
+ LTTNG_ERR_SESSION_FAIL = 18,
+
+ /*!
+ No available
+ \ref api-gen-sessiond-conn "session daemon to connect to".
+ */
+ LTTNG_ERR_NO_SESSIOND = 19,
+
+ /// Failed to set an URL.
+ LTTNG_ERR_SET_URL = 20,
+
+ /// URL already exists.
+ LTTNG_ERR_URL_EXIST = 21,
+
+ /// Unsupported \ref api-channel-buf-scheme "buffering scheme".
+ LTTNG_ERR_BUFFER_NOT_SUPPORTED = 22,
+
+ /// Nonexistent \lt_obj_session name.
+ LTTNG_ERR_SESS_NOT_FOUND = 23,
+
+ /*!
+ A \lt_obj_channel within the given \lt_obj_domain already exists
+ and is configured with another
+ \ref api-channel-buf-scheme "buffering scheme".
+ */
+ LTTNG_ERR_BUFFER_TYPE_MISMATCH = 24,
+
+ /// Fatal error.
+ LTTNG_ERR_FATAL = 25,
+
+ /// Failed to allocate memory.
+ LTTNG_ERR_NOMEM = 26,
+
+ /// \lt_obj_c_session name already exists.
+ LTTNG_ERR_EXIST_SESS = 28,
+
+ /// \lt_obj_c_rer not found.
+ LTTNG_ERR_NO_EVENT = 29,
+
+ /// Failed to connect to Unix socket.
+ LTTNG_ERR_CONNECT_FAIL = 30,
+
+ /// \ref api_session_snapshot "Snapshot" output already exists.
+ LTTNG_ERR_SNAPSHOT_OUTPUT_EXIST = 31,
+
+ /// Permission denied.
+ LTTNG_ERR_EPERM = 32,
+
+ /// Linux kernel tracer isn't available.
+ LTTNG_ERR_KERN_NA = 33,
+
+ /// Incompatible Linux kernel tracer.
+ LTTNG_ERR_KERN_VERSION = 34,
+
+ /// Linux kernel \lt_obj_rer already exists.
+ LTTNG_ERR_KERN_EVENT_EXIST = 35,
+
+ /// Linux kernel tracer: failed to create a \lt_obj_session.
+ LTTNG_ERR_KERN_SESS_FAIL = 36,
+
+ /// Linux kernel \lt_obj_channel already exists.
+ LTTNG_ERR_KERN_CHAN_EXIST = 37,
+
+ /// Failed to create a Linux kernel \lt_obj_channel.
+ LTTNG_ERR_KERN_CHAN_FAIL = 38,
+
+ /// Linux kernel \lt_obj_channel not found.
+ LTTNG_ERR_KERN_CHAN_NOT_FOUND = 39,
+
+ /// Failed to disable a Linux kernel \lt_obj_channel.
+ LTTNG_ERR_KERN_CHAN_DISABLE_FAIL = 40,
+
+ /// Failed to create/enable a Linux kernel \lt_obj_channel.
+ LTTNG_ERR_KERN_CHAN_ENABLE_FAIL = 41,
+
+ /*!
+ Failed to add a context field to be recorded to the event
+ records of a Linux kernel \lt_obj_channel.
+ */
+ LTTNG_ERR_KERN_CONTEXT_FAIL = 42,
+
+ /// Failed to create/enable a Linux kernel \lt_obj_rer.
+ LTTNG_ERR_KERN_ENABLE_FAIL = 43,
+
+ /// Failed to disable a Linux kernel \lt_obj_rer.
+ LTTNG_ERR_KERN_DISABLE_FAIL = 44,
+
+ /// Failed to open a Linux kernel trace metadata stream.
+ LTTNG_ERR_KERN_META_FAIL = 45,
+
+ /*!
+ Linux kernel tracer: failed to
+ \link lttng_start_tracing() start tracing\endlink.
+ */
+ LTTNG_ERR_KERN_START_FAIL = 46,
+
+ /*!
+ Linux kernel tracer: failed to
+ \link lttng_stop_tracing stop tracing\endlink.
+ */
+ LTTNG_ERR_KERN_STOP_FAIL = 47,
+
+ /// Failed to start a Linux kernel consumer daemon.
+ LTTNG_ERR_KERN_CONSUMER_FAIL = 48,
+
+ /// Failed to create a Linux kernel trace data stream.
+ LTTNG_ERR_KERN_STREAM_FAIL = 49,
+
+ /*!
+ The \lt_obj_session never became
+ \link lttng_session::enabled active\endlink.
+ */
+ LTTNG_ERR_START_SESSION_ONCE = 50,
+
+ /*!
+ Failed to take a recording session
+ \ref api_session_snapshot "snapshot".
+ */
+ LTTNG_ERR_SNAPSHOT_FAIL = 51,
+
+ /// Failed to list Linux kernel \lt_obj_rers.
+ LTTNG_ERR_KERN_LIST_FAIL = 53,
+
+ /// User space \lt_obj_rer already enabled.
+ LTTNG_ERR_UST_EVENT_ENABLED = 55,
+
+ /*!
+ User space tracer: failed to
+ \link lttng_create_session_ext() create\endlink a
+ \lt_obj_session.
+ */
+ LTTNG_ERR_UST_SESS_FAIL = 56,
+
+ /// User space \lt_obj_channel already exists.
+ LTTNG_ERR_UST_CHAN_EXIST = 57,
+
+ /*!
+ Failed to
+ \link lttng_enable_channel() create\endlink a user space
+ \lt_obj_channel.
+ */
+ LTTNG_ERR_UST_CHAN_FAIL = 58,
+
+ /// User space \lt_obj_channel not found.
+ LTTNG_ERR_UST_CHAN_NOT_FOUND = 59,
+
+ /*!
+ Failed to \link lttng_disable_channel() disable\endlink
+ a user space \lt_obj_channel.
+ */
+ LTTNG_ERR_UST_CHAN_DISABLE_FAIL = 60,
+
+ /// Failed to create/enable a user space \lt_obj_rer.
+ LTTNG_ERR_UST_ENABLE_FAIL = 63,
+
+ /// Failed to disable a user space \lt_obj_rer.
+ LTTNG_ERR_UST_DISABLE_FAIL = 64,
+
+ /*!
+ User space tracer: failed to
+ \link lttng_start_tracing() start tracing\endlink.
+ */
+ LTTNG_ERR_UST_START_FAIL = 66,
+
+ /*!
+ User space tracer: failed to
+ \link lttng_stop_tracing() stop tracing\endlink.
+ */
+ LTTNG_ERR_UST_STOP_FAIL = 67,
+
+ /// Failed to start a 64-bit user space consumer daemon.
+ LTTNG_ERR_UST_CONSUMER64_FAIL = 68,
+
+ /// Failed to start a 32-bit user space consumer daemon.
+ LTTNG_ERR_UST_CONSUMER32_FAIL = 69,
+
+ /// \lt_obj_c_session has no \lt_obj_channels.
+ LTTNG_ERR_NO_CHANNEL = 72,
+
+ /// \lt_obj_c_session name contains an invalid character.
+ LTTNG_ERR_SESSION_INVALID_CHAR = 73,
+
+ /// Failed to list user space \lt_obj_rers.
+ LTTNG_ERR_UST_LIST_FAIL = 74,
+
+ /// User space \lt_obj_rer already exists.
+ LTTNG_ERR_UST_EVENT_EXIST = 75,
+
+ /// User space \lt_obj_rer not found.
+ LTTNG_ERR_UST_EVENT_NOT_FOUND = 76,
+
+ /*!
+ \link lttng_add_context() Context field\endlink to be recorded
+ to the event records of a user space
+ \lt_obj_channel already exists.
+ */
+ LTTNG_ERR_UST_CONTEXT_EXIST = 77,
+
+ /*!
+ Invalid/unknown
+ \link #lttng_event_context_type context field type\endlink.
+ */
+ LTTNG_ERR_UST_CONTEXT_INVAL = 78,
+
+ /*!
+ A root session daemon is required, but isn't available.
+
+ See \ref api-gen-sessiond-conn "Session daemon connection".
+ */
+ LTTNG_ERR_NEED_ROOT_SESSIOND = 79,
+
+ /*!
+ \lt_obj_c_session is already
+ \link lttng_session::enabled active\endlink (started).
+ */
+ LTTNG_ERR_TRACE_ALREADY_STARTED = 80,
+
+ /*!
+ \lt_obj_c_session is already
+ \link lttng_session::enabled inactive\endlink (stopped).
+ */
+ LTTNG_ERR_TRACE_ALREADY_STOPPED = 81,
+
+ /// Linux kernel instrumentation point type not supported.
+ LTTNG_ERR_KERN_EVENT_ENOSYS = 82,
+
+ /*!
+ A \lt_obj_channel name is required because
+ a non-default channel exists within the selected
+ \lt_obj_session and \lt_obj_domain.
+ */
+ LTTNG_ERR_NEED_CHANNEL_NAME = 83,
+
+ /*!
+ \lt_obj_c_channel name is required because a
+ non-default channel exists within the \lt_obj_session.
+ */
+ LTTNG_ERR_NO_UST = 84,
+
+ /*!
+ \ref api_session_save_load "Recording session configuration file"
+ already exists.
+ */
+ LTTNG_ERR_SAVE_FILE_EXIST = 85,
+
+ /*!
+ I/O error while writing a
+ \ref api_session_save_load "recording session configuration file".
+ */
+ LTTNG_ERR_SAVE_IO_FAIL = 86,
+
+ /*!
+ Invalid
+ \ref api_session_save_load "recording session configuration file".
+ */
+ LTTNG_ERR_LOAD_INVALID_CONFIG = 87,
+
+ /*!
+ I/O error while reading a
+ \ref api_session_save_load "recording session configuration file".
+ */
+ LTTNG_ERR_LOAD_IO_FAIL = 88,
+
+ /*!
+ \ref api_session_save_load "Recording session configuration file"
+ not found.
+ */
+ LTTNG_ERR_LOAD_SESSION_NOENT = 89,
+
+ /*!
+ Maximum total size of all the
+ \ref api_session_snapshot "snapshot" trace files is invalid.
+ */
+ LTTNG_ERR_MAX_SIZE_INVALID = 90,
+
+ /* 94 */
+ /* 95 */
+ /* 96 */
+
+ /// Invalid parameter (unsatisfied precondition).
+ LTTNG_ERR_INVALID = 97,
+
+ /// No user space consumer daemon available.
+ LTTNG_ERR_NO_USTCONSUMERD = 98,
+
+ /// No Linux kernel consumer daemon available.
+ LTTNG_ERR_NO_KERNCONSUMERD = 99,
+
+ /// Missing network data \ref api-session-url "URL".
+ LTTNG_ERR_URL_DATA_MISS = 101,
+
+ /// Missing network control \ref api-session-url "URL".
+ LTTNG_ERR_URL_CTRL_MISS = 102,
+
+ /// Failed to communicate with a consumer daemon.
+ LTTNG_ERR_ENABLE_CONSUMER_FAIL = 103,
+
+ /*!
+ Failed to connect to or communicate with a relay daemon
+ (see \lt_man{lttng-relayd,8}).
+ */
+ LTTNG_ERR_RELAYD_CONNECT_FAIL = 104,
+
+ /// Incompatible relay daemon (see \lt_man{lttng-relayd,8}) version.
+ LTTNG_ERR_RELAYD_VERSION_FAIL = 105,
+
+ /*!
+ Invalid \link lttng_enable_event_with_filter() context and event
+ payload filter expression\endlink.
+ */
+ LTTNG_ERR_FILTER_INVAL = 106,
+
+ /*!
+ Failed to allocate memory for a context and event payload filter
+ object.
+ */
+ LTTNG_ERR_FILTER_NOMEM = 107,
+
+ /// No available consumer daemon.
+ LTTNG_ERR_NO_CONSUMER = 109,
+
+ /*!
+ Invalid event name
+ \link lttng_enable_event_with_exclusions() exclusion\endlink
+ data.
+ */
+ LTTNG_ERR_EXCLUSION_INVAL = 110,
+
+ /// Failed to allocate memory for an event name exclusion object.
+ LTTNG_ERR_EXCLUSION_NOMEM = 111,
+
+ /// Invalid event name condition part of a \lt_obj_rer.
+ LTTNG_ERR_INVALID_EVENT_NAME = 112,
+
+ /// Invalid \lt_obj_channel name.
+ LTTNG_ERR_INVALID_CHANNEL_NAME = 113,
+
+ /*!
+ Process attribute is already part of an
+ \ref api_pais "inclusion set".
+ */
+ LTTNG_ERR_PROCESS_ATTR_EXISTS = 114,
+
+ /*!
+ Process attribute isn't part of an
+ \ref api_pais "inclusion set".
+ */
+ LTTNG_ERR_PROCESS_ATTR_MISSING = 115,
+
+ /// Invalid \lt_obj_domain for \lt_obj_channel.
+ LTTNG_ERR_INVALID_CHANNEL_DOMAIN = 116,
+
+ /// Overflow.
+ LTTNG_ERR_OVERFLOW = 117,
+
+ /*!
+ \lt_obj_c_session isn't
+ \link lttng_session::enabled active\endlink (started).
+ */
+ LTTNG_ERR_SESSION_NOT_STARTED = 118,
+
+ /*!
+ Unsupported LTTng \ref api-session-live-mode "live" recording
+ session mode.
+ */
+ LTTNG_ERR_LIVE_SESSION = 119,
+
+ /*!
+ Unsupported
+ \ref api-channel-per-proc-buf "per-process buffering scheme".
+ */
+ LTTNG_ERR_PER_PID_SESSION = 120,
+
+ /*!
+ \link #lttng_event_context_type Context field type\endlink
+ isn't available on the current Linux kernel.
+ */
+ LTTNG_ERR_KERN_CONTEXT_UNAVAILABLE = 121,
+
+ /*!
+ Failed to \link lttng_regenerate_statedump() regenerate the
+ LTTng state dump event records\endlink.
+ */
+ LTTNG_ERR_REGEN_STATEDUMP_FAIL = 122,
+
+ /*!
+ Failed to allocate memory to \link lttng_regenerate_statedump()
+ regenerate the LTTng state dump event records\endlink.
+ */
+ LTTNG_ERR_REGEN_STATEDUMP_NOMEM = 123,
+
+ /*!
+ \lt_obj_c_session isn't in
+ \ref api-session-snapshot-mode "snapshot mode".
+ */
+ LTTNG_ERR_NOT_SNAPSHOT_SESSION = 124,
+
+ /// Invalid \lt_obj_trigger.
+ LTTNG_ERR_INVALID_TRIGGER = 125,
+
+ /// \lt_obj_c_trigger already exists (registered).
+ LTTNG_ERR_TRIGGER_EXISTS = 126,
+
+ /// \lt_obj_c_trigger not found.
+ LTTNG_ERR_TRIGGER_NOT_FOUND = 127,
+
+ /*!
+ \ref api_session_rotation "Recording session rotation" operation
+ already in progress.
+ */
+ LTTNG_ERR_ROTATION_PENDING = 129,
+
+ /*!
+ \ref api_session_rotation "Recording session rotation" feature
+ isn't available for the \ref api-session-modes "mode" of the
+ given recording session.
+ */
+ LTTNG_ERR_ROTATION_NOT_AVAILABLE = 130,
+
+ /*!
+ \ref api_session_rotation "Recording session rotation" schedule
+ already set.
+ */
+ LTTNG_ERR_ROTATION_SCHEDULE_SET = 131,
+
+ /*!
+ \ref api_session_rotation "Recording session rotation" schedule
+ isn't set.
+ */
+ LTTNG_ERR_ROTATION_SCHEDULE_NOT_SET = 132,
+
+ /*!
+ LTTng already
+ \ref api_session_rotation "archived the current trace chunk" of
+ the recording session since it became
+ \link lttng_session::enabled inactive\endlink (stopped).
+ */
+ LTTNG_ERR_ROTATION_MULTIPLE_AFTER_STOP = 133,
+
+ /*!
+ Linux kernel tracer: unavailable
+ \ref api_session_rotation "recording session rotation" feature.
+ */
+ LTTNG_ERR_ROTATION_WRONG_VERSION = 134,
+
+ /// \lt_obj_c_session has no configured output.
+ LTTNG_ERR_NO_SESSION_OUTPUT = 135,
+
+ /*!
+ Relay daemon: unavailable
+ \ref api_session_rotation "recording session rotation" feature.
+ */
+ LTTNG_ERR_ROTATION_NOT_AVAILABLE_RELAY = 136,
+
+ /// Unavailable logging instrumentation point feature.
+ LTTNG_ERR_AGENT_TRACING_DISABLED = 137,
+
+ /// Invalid user space probe location.
+ LTTNG_ERR_PROBE_LOCATION_INVAL = 138,
+
+ /// Failed to parse ELF file.
+ LTTNG_ERR_ELF_PARSING = 139,
+
+ /*!
+ SystemTap User-level Statically Defined Tracing (USDT) probe
+ guarded by a semaphore.
+ */
+ LTTNG_ERR_SDT_PROBE_SEMAPHORE = 140,
+
+ /*!
+ Consumer daemon failed to perform a
+ \ref api_session_rotation "recording session rotation"
+ operation.
+ */
+ LTTNG_ERR_ROTATION_FAIL_CONSUMER = 141,
+
+ /// \lt_obj_c_channel not found.
+ LTTNG_ERR_CHAN_NOT_FOUND = 146,
+
+ /*!
+ Cannot take a
+ \ref api_session_snapshot "snapshot" with the current
+ recording session configuration.
+ */
+ LTTNG_ERR_SNAPSHOT_UNSUPPORTED = 147,
+
+ /// Nonexistent \lt_obj_session.
+ LTTNG_ERR_SESSION_NOT_EXIST = 148,
+
+ /*!
+ Consumer daemon failed to create a
+ \ref api_session_rotation "trace chunk archive".
+ */
+ LTTNG_ERR_CREATE_TRACE_CHUNK_FAIL_CONSUMER = 149,
+
+ /*!
+ Consumer daemon failed to close a
+ \ref api_session_rotation "trace chunk archive".
+ */
+ LTTNG_ERR_CLOSE_TRACE_CHUNK_FAIL_CONSUMER = 150,
+
+ /// Invalid protocol.
+ LTTNG_ERR_INVALID_PROTOCOL = 152,
+
+ /// Failed to create a file.
+ LTTNG_ERR_FILE_CREATION_ERROR = 153,
+
+ /// Failed to stop a timer.
+ LTTNG_ERR_TIMER_STOP_ERROR = 154,
+
+ /*!
+ Linux kernel tracer:
+ \ref api_session_rotation "recording session rotation" feature
+ isn't available.
+ */
+ LTTNG_ERR_ROTATION_NOT_AVAILABLE_KERNEL = 155,
+
+ /*!
+ The relay daemon (see \lt_man{lttng-relayd,8}) doesn't allow
+ \ref api_session_clear "recording session clearing" operations.
+ */
+ LTTNG_ERR_CLEAR_RELAY_DISALLOWED = 156,
+
+ /*!
+ The relay daemon (see \lt_man{lttng-relayd,8}) doesn't support
+ the
+ \ref api_session_clear "recording session clearing" operation.
+ */
+ LTTNG_ERR_CLEAR_NOT_AVAILABLE_RELAY = 157,
+
+ /*!
+ Consumer daemon failed to
+ \ref api_session_clear "clear the recording session".
+ */
+ LTTNG_ERR_CLEAR_FAIL_CONSUMER = 158,
+
+ /*!
+ LTTng already
+ \ref api_session_clear "cleared the recording session" since it
+ became \link lttng_session::enabled inactive\endlink (stopped).
+ */
+ LTTNG_ERR_ROTATION_AFTER_STOP_CLEAR = 159,
+
+ /* Unix user not found. */
+ LTTNG_ERR_USER_NOT_FOUND = 160,
+
+ /* Unix group not found. */
+ LTTNG_ERR_GROUP_NOT_FOUND = 161,
+
+ /* Unsupported \lt_obj_domain. */
+ LTTNG_ERR_UNSUPPORTED_DOMAIN = 162,
+
+ /*!
+ Invalid operation considering the policy of the
+ \ref api_pais "process attribute inclusion set".
+ */
+ LTTNG_ERR_PROCESS_ATTR_TRACKER_INVALID_TRACKING_POLICY = 163,
+
+ /*!
+ Failed to initialize the file descriptor of the event notifier
+ group notification.
+ */
+ LTTNG_ERR_EVENT_NOTIFIER_GROUP_NOTIFICATION_FD = 164,
+
+ /// Invalid event field capture expression.
+ LTTNG_ERR_INVALID_CAPTURE_EXPRESSION = 165,
+
+ /// Failed to register the event notifier to the tracer.
+ LTTNG_ERR_EVENT_NOTIFIER_REGISTRATION = 166,
+
+ /// Failed to initialize the event notifier error accounting.
+ LTTNG_ERR_EVENT_NOTIFIER_ERROR_ACCOUNTING = 167,
+
+ /// Event notifier error accouting is full.
+ LTTNG_ERR_EVENT_NOTIFIER_ERROR_ACCOUNTING_FULL = 168,
+
+ /// Invalid error query target.
+ LTTNG_ERR_INVALID_ERROR_QUERY_TARGET = 169,
+
+ /// Failed to flush a buffer.
+ LTTNG_ERR_BUFFER_FLUSH_FAILED = 170,
/* MUST be last element of the manually-assigned section of the enum */
+ /// @cond INTERNAL_ERR_CODES
LTTNG_ERR_NR,
+ /// @endcond
/* Backward-compatibility assignments */
- LTTNG_ERR_PID_TRACKED = LTTNG_ERR_PROCESS_ATTR_EXISTS, /* Backward compat alias */
- LTTNG_ERR_PID_NOT_TRACKED = LTTNG_ERR_PROCESS_ATTR_MISSING, /* Backward compat alias */
+ /*!
+ Process attribute is already part of an
+ \ref api_pais "inclusion set".
+
+ @deprecated
+ Use #LTTNG_ERR_PROCESS_ATTR_EXISTS.
+ */
+ LTTNG_ERR_PID_TRACKED = LTTNG_ERR_PROCESS_ATTR_EXISTS,
+
+ /*!
+ Process attribute isn't part of an
+ \ref api_pais "inclusion set".
+
+ @deprecated
+ Use #LTTNG_ERR_PROCESS_ATTR_MISSING.
+ */
+ LTTNG_ERR_PID_NOT_TRACKED = LTTNG_ERR_PROCESS_ATTR_MISSING,
};
-/*
- * Return a human-readable error message for a LTTng error code.
- *
- * Parameter MUST be a negative value or else you'll get a generic message.
- */
-LTTNG_EXPORT extern const char *lttng_strerror(int code);
+/*!
+@brief
+ Returns a human-readable message for the general error code
+ \lt_p{error_code}.
+
+@param[in] error_code
+ Error code (one of the #lttng_error_code enumerators), positive or
+ negative, for which to get a corresponding human-readable message.
+
+@returns
+ Human-readable message which corresponds to \lt_p{error_code}.
+
+@pre
+ \lt_p{error_code} is a valid #lttng_error_code enumerator.
+*/
+LTTNG_EXPORT extern const char *lttng_strerror(int error_code);
+
+/// @}
#ifdef __cplusplus
}
#ifndef LTTNG_H
#define LTTNG_H
+#include <lttng/lttng-export.h>
+
/* Error codes that can be returned by API calls */
#include <lttng/lttng-error.h>
#include <lttng/location.h>
#include <lttng/log-level-rule.h>
#include <lttng/lttng-error.h>
-#include <lttng/lttng-export.h>
#include <lttng/notification/channel.h>
#include <lttng/notification/notification.h>
#include <lttng/rotation.h>
char padding[LTTNG_CALIBRATE_PADDING1];
};
-/*
- * Check if a session daemon is alive.
- *
- * Return 1 if alive or 0 if not. On error, returns a negative negative LTTng
- * error code.
- */
+/*!
+@brief
+ Returns whether or not liblttng-ctl is able to connect to a
+ listening session daemon.
+
+@ingroup api_gen
+
+How this function tries to
+\ref api-gen-sessiond-conn "connect to a session daemon" depends on the
+current Unix tracing group (initially \c tracing) of the library. Set
+the tracing group with lttng_set_tracing_group().
+
+@returns
+ @parblock
+ One of:
+
+ <dl>
+ <dt>1</dt>
+ <dd>
+ liblttng-ctl is able to connect to a session daemon.
+
+ <dt>0
+ <dd>
+ liblttng-ctl isn't able to connect to a session daemon.
+
+ <dt>Negative value
+ <dd>
+ Error: a negative #lttng_error_code enumerator.
+ </dl>
+ @endparblock
+
+@sa lttng_set_tracing_group() --
+ Sets the current Unix tracing group of liblttng-ctl.
+*/
LTTNG_EXPORT extern int lttng_session_daemon_alive(void);
-/*
- * Set the tracing group for the *current* flow of execution.
- *
- * On success, returns 0 else a negative LTTng error code.
- */
-LTTNG_EXPORT extern int lttng_set_tracing_group(const char *name);
+/*!
+@brief
+ Sets the current Unix tracing group of liblttng-ctl to \lt_p{group}.
+
+@ingroup api_gen
+
+How the liblttng-ctl functions
+\ref api-gen-sessiond-conn "connect to a session daemon" depends on
+the current Unix tracing group (initially \c tracing) of the library.
+
+@param[in] group
+ New Unix tracing group of liblttng-ctl.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_not_null{group}
+@pre
+ \lt_p{group} names an existing Unix group.
+*/
+LTTNG_EXPORT extern int lttng_set_tracing_group(const char *group);
/*
* This call registers an "outside consumer" for a session and an lttng domain.
LTTNG_EXPORT extern int lttng_register_consumer(struct lttng_handle *handle,
const char *socket_path);
-/*
- * Start tracing for *all* domain(s) in the session.
- *
- * Return 0 on success else a negative LTTng error code.
- */
+/*!
+@brief
+ Makes the recording session named \lt_p{session_name} active,
+ starting all the tracers for its
+ \ref api-channel-channel "channels".
+
+@ingroup api_session
+
+@note
+ An #LTTNG_ACTION_TYPE_START_SESSION trigger action can also activate
+ (start) a recording session.
+
+@param[in] session_name
+ Name of the recording session to activate/start.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+@lt_pre_sess_inactive{session_name}
+
+@sa lttng_stop_tracing() --
+ Stops a recording session.
+@sa \lt_man{lttng-start,1}
+*/
LTTNG_EXPORT extern int lttng_start_tracing(const char *session_name);
-/*
- * Stop tracing for *all* domain(s) in the session.
- *
- * This call will wait for data availability for each domain of the session so
- * this can take an abritrary amount of time. However, when returning you have
- * the guarantee that the data is ready to be read and analyze. Use the
- * _no_wait call below to avoid this behavior.
- *
- * The session_name can't be NULL.
- *
- * Return 0 on success else a negative LTTng error code.
- */
+/*!
+@brief
+ Makes the recording session named \lt_p{session_name} inactive,
+ stopping all the tracers for its
+ \ref api-channel-channel "channels", blocking until the operation
+ completes.
+
+@ingroup api_session
+
+This function blocks until the trace data of the
+recording session named \lt_p{session_name} is valid. Use
+lttng_stop_tracing_no_wait() to avoid a blocking call.
+
+If LTTng \ref api_session_rotation "archived the current trace chunk"
+of the recording session named \lt_p{session_name} at least
+once during its lifetime, then this function renames the current trace
+chunk subdirectory. Although it's safe to
+read the content of this renamed subdirectory while the recording
+session remains inactive, it's \em not a trace chunk archive: you need to
+\link lttng_destroy_session_ext() destroy\endlink the recording session
+or a rotation needs to occur to archive it.
+
+@note
+ An #LTTNG_ACTION_TYPE_STOP_SESSION trigger action can also
+ deactivate (stop) a recording session.
+
+@param[in] session_name
+ Name of the recording session to deactivate/stop.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+@lt_pre_sess_active{session_name}
+
+@sa lttng_stop_tracing_no_wait() --
+ Deactivates a recording session without waiting for the operation
+ to complete.
+@sa lttng_start_tracing() --
+ Starts a recording session.
+@sa \lt_man{lttng-stop,1}
+*/
LTTNG_EXPORT extern int lttng_stop_tracing(const char *session_name);
-/*
- * Behave exactly like lttng_stop_tracing but does not wait for data
- * availability.
- */
+/*!
+@brief
+ Makes the recording session named \lt_p{session_name} inactive,
+ stopping all the tracers for its
+ \ref api-channel-channel "channels" without waiting for the
+ operation to complete.
+
+@ingroup api_session
+
+Unlike lttng_stop_tracing(), this function does \em not block until
+the operation is complete: it returns immediately. This
+means the traces(s) of the recording session might not be valid when
+this function returns, and there's no way to know when it/they become
+valid.
+
+@note
+ An #LTTNG_ACTION_TYPE_STOP_SESSION trigger action can also
+ deactivate (stop) a recording session.
+
+@param[in] session_name
+ Name of the recording session to deactivate/stop.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+@lt_pre_sess_active{session_name}
+@pre
+ No deactivation operation is in progress for the recording session
+ named \lt_p{session_name}.
+
+@sa lttng_stop_tracing() --
+ Deactivates a recording session, blocking until the operation
+ completes.
+@sa lttng_start_tracing() --
+ Starts a recording session.
+@sa \lt_man{lttng-stop,1}
+*/
LTTNG_EXPORT extern int lttng_stop_tracing_no_wait(const char *session_name);
/*
LTTNG_EXPORT extern int
lttng_set_consumer_url(struct lttng_handle *handle, const char *control_url, const char *data_url);
-/*
- * For a given session name, this call checks if the data is ready to be read
- * or is still being extracted by the consumer(s) (pending) hence not ready to
- * be used by any readers.
- *
- * Return 0 if there is _no_ data pending in the buffers thus having a
- * guarantee that the data can be read safely. Else, return 1 if there is still
- * traced data is pending. On error, a negative value is returned and readable
- * by lttng_strerror().
- */
+/*!
+@brief
+ Returns whether or not you may read the traces of the recording
+ session named \lt_p{session_name}.
+
+@ingroup api_session
+
+It's not safe to read the traces of a recording session while
+LTTng is still consuming data from the tracers for its
+\ref api-channel-channel "channels".
+
+This function makes it possible to know when LTTng is done consuming
+trace data from tracers for the channels of the recording session
+named \lt_p{session_name}.
+
+@param[in] session_name
+ Name of the recording session of which get whether or not
+ you may read its traces.
+
+@returns
+ @parblock
+ One of:
+
+ <dl>
+ <dt>0
+ <dd>
+ You may read the traces of the recording session named
+ \lt_p{session_name}.
+
+ This remains true as long as the recording session remains
+ \link lttng_session::enabled inactive\endlink (stopped).
+
+ <dt>1</dt>
+ <dd>
+ You may \em not read the traces of the recording session named
+ \lt_p{session_name}.
+
+ <dt>Negative value
+ <dd>
+ Error: a negative #lttng_error_code enumerator.
+ </dl>
+ @endparblock
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+@lt_pre_sess_inactive{session_name}
+*/
LTTNG_EXPORT extern int lttng_data_pending(const char *session_name);
/*
LTTNG_EXPORT extern enum lttng_error_code
lttng_get_kernel_tracer_status(enum lttng_kernel_tracer_status *status);
-/*
- * Deprecated, replaced by lttng_regenerate_metadata.
- */
-LTTNG_DEPRECATED("Use lttng_regenerate_metadata")
+/*!
+@brief
+ Regenerates the metadata streams of the recording session named
+ \lt_p{session_name}.
+
+@ingroup api_session
+
+@deprecated
+ Use lttng_regenerate_metadata().
+
+@param[in] session_name
+ Name of the recording session of which to regenerate the metadata
+ streams.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+*/
+/// @cond DEPRECATED
+LTTNG_DEPRECATED()
+/// @endcond
LTTNG_EXPORT extern int lttng_metadata_regenerate(const char *session_name);
-/*
- * Trigger the regeneration of the metadata for a session.
- * The new metadata overwrite the previous one locally or remotely (through
- * the lttng-relayd). Only kernel, per-uid and non-live sessions are supported.
- * Return 0 on success, a negative LTTng error code on error.
- */
+/*!
+@brief
+ Regenerates the metadata streams of the recording session named
+ \lt_p{session_name}.
+
+@ingroup api_session
+
+Use this function to resample the offset between the monotonic clock and
+the wall time of the system, and then regenerate (overwrite) all the
+metadata stream files (local or remote) of the recording session
+named \lt_p{session_name}.
+
+More specifically, you may want to resample the wall time following a
+major <a href="https://en.wikipedia.org/wiki/Network_Time_Protocol">NTP</a>
+correction. As such, LTTng can trace a system booting with an incorrect
+wall time before its wall time is NTP-corrected. Regenerating the
+metadata of a recording session ensures that trace readers
+can accurately determine the event record timestamps relative to the
+Unix epoch.
+
+Note that if you plan to \ref api_session_rotation "rotate" the
+recording session named \lt_p{session_name}, this function only
+regenerates the metadata stream files of the \em current and \em next
+trace chunks.
+
+See the preconditions of this function which show important limitations.
+
+@param[in] session_name
+ Name of the recording session of which to regenerate the metadata
+ streams.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+@pre
+ The recording session named \lt_p{session_name} was \em not created
+ in \ref api-session-live-mode "live mode".
+@pre
+ All the \ref api-channel-channel "channels" of the recording session
+ named \lt_p{session_name} use a
+ \ref api-channel-per-user-buf "per-user buffering scheme".
+
+@sa lttng_regenerate_statedump() --
+ Regenerates the state dump event records of a recording session.
+@sa \lt_man{lttng-regenerate,1}
+*/
LTTNG_EXPORT extern int lttng_regenerate_metadata(const char *session_name);
-/*
- * Trigger the regeneration of the statedump for a session. The new statedump
- * information is appended to the currently active trace, the session needs to
- * be active.
- *
- * Return 0 on success, a negative LTTng error code on error.
- */
+/*!
+@brief
+ Regenerates the state dump event records of the recording session
+ named \lt_p{session_name}.
+
+@ingroup api_session
+
+Use this function to collect up-to-date state dump information and
+append corresponding event records to the
+\ref api-channel-channel "sub-buffers" of the recording session named
+\lt_p{session_name}.
+
+This is particularly useful if you created the recording session in
+\ref api-session-snapshot-mode "snapshot mode"
+or if LTTng \ref api_session_rotation "rotates" trace files for one of
+its \ref api-channel-channel "channels": in both cases, the state dump
+information may be lost.
+
+@param[in] session_name
+ Name of the recording session of which to regenerate the
+ state dump event records.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+
+@sa lttng_regenerate_metadata() --
+ Regenerates the metadata streams of a recording session.
+@sa \lt_man{lttng-regenerate,1}
+*/
LTTNG_EXPORT extern int lttng_regenerate_statedump(const char *session_name);
#ifdef __cplusplus
#ifndef LTTNG_SESSION_DESCRIPTOR_H
#define LTTNG_SESSION_DESCRIPTOR_H
-#include <lttng/lttng-export.h>
-
#ifdef __cplusplus
extern "C" {
#endif
+#include <lttng/lttng-export.h>
+
+/*!
+@addtogroup api_session_descr
+@{
+*/
+
+/*!
+@struct lttng_session_descriptor
+
+@brief
+ Recording session descriptor (opaque type).
+*/
struct lttng_session_descriptor;
/*
* default data port, and the 'control_url' host will be used.
*/
+/*!
+@brief
+ Return type of recording session descriptor fuctions.
+
+Error status enumerators have a negative value.
+*/
enum lttng_session_descriptor_status {
- /* Invalid session descriptor parameter. */
- LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID = -1,
+ /// Success.
LTTNG_SESSION_DESCRIPTOR_STATUS_OK = 0,
- /* Session descriptor parameter is unset. */
+
+ /// Unsatisfied precondition.
+ LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID = -1,
+
+ /// Recording session descriptor property is not set.
LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET = 1,
};
-/*
- * Create a session descriptor in no-output mode.
- *
- * The 'name' parameter can be left NULL to auto-generate a session name.
- *
- * Returns an lttng_session_descriptor instance on success, NULL on error.
- */
+/*!
+@brief
+ Creates a recording session descriptor to create a no-output,
+ \ref api-session-local-mode "local" recording session
+ named \lt_p{session_name}.
+
+LTTng won't write any trace data for a recording session created from
+the returned descriptor.
+
+@param[in] session_name
+ @parblock
+ Recording session name.
+
+ If \c NULL, LTTng automatically generates a recording session name
+ when you call lttng_create_session_ext().
+
+ Call lttng_session_descriptor_get_session_name() with the returned
+ recording session descriptor after successfully calling
+ lttng_create_session_ext() to get the generated name.
+ @endparblock
+
+@returns
+ @parblock
+ Recording session descriptor on success, or \c NULL on error.
+
+ Destroy the returned descriptor with
+ lttng_session_descriptor_destroy().
+ @endparblock
+
+@sa lttng_session_descriptor_local_create() --
+ Creates a recording session descriptor to create a
+ \ref api-session-local-mode "local" recording session with an
+ output.
+
+@lt_pre_sess_name_not_auto{session_name}
+*/
LTTNG_EXPORT extern struct lttng_session_descriptor *
-lttng_session_descriptor_create(const char *name);
+lttng_session_descriptor_create(const char *session_name);
-/*
- * Create a session descriptor with a local output destination.
- *
- * The 'name' parameter can be left NULL to auto-generate a session name.
- *
- * The 'path' must either be an absolute path or it can be left NULL to
- * use the default local output destination.
- *
- * Returns an lttng_session_descriptor instance on success, NULL on error.
- */
+/*!
+@brief
+ Creates a recording session descriptor to create a
+ \ref api-session-local-mode "local" recording session
+ named \lt_p{session_name}.
+
+@param[in] session_name
+ @parblock
+ Recording session name.
+
+ If \c NULL, LTTng automatically generates a recording session name
+ when you call lttng_create_session_ext().
+
+ Call lttng_session_descriptor_get_session_name() with the returned
+ recording session descriptor after successfully calling
+ lttng_create_session_ext() to get the generated name.
+ @endparblock
+@param[in] trace_dir
+ @parblock
+ Absolute path of the directory containing the traces of the
+ recording session you create from the returned descriptor.
+
+ If \c NULL, the output directory is, after calling
+ lttng_create_session_ext(),
+ <code><em>$LTTNG_HOME</em>/lttng-traces/<em>NAME</em>-<em>TS</em></code>,
+ with:
+
+ <dl>
+ <dt><code><em>$LTTNG_HOME</em></code>
+ <dd>
+ The value of the \c LTTNG_HOME environment variable, or
+ of the \c HOME environment variable if \c LTTNG_HOME isn't
+ set.
+
+ <dt><code><em>NAME</em></code>
+ <dd>
+ Recording session name (\lt_p{session_name} if not \c NULL, or
+ an automatically generated name otherwise).
+
+ <dt><code><em>TS</em></code>
+ <dd>
+ \link lttng_session_get_creation_time() Timestamp of the
+ creation\endlink of the recording session using the
+ <code>YYYYmmdd-HHMMSS</code> form.
+ </dl>
+ @endparblock
+
+@returns
+ @parblock
+ Recording session descriptor on success, or \c NULL on error.
+
+ Destroy the returned descriptor with
+ lttng_session_descriptor_destroy().
+ @endparblock
+
+@lt_pre_sess_name_not_auto{session_name}
+@pre
+ <strong>If not \c NULL</strong>, \lt_p{trace_dir} is a valid path.
+
+@sa lttng_session_descriptor_create() --
+ Creates a recording session descriptor to create a
+ \ref api-session-local-mode "local" recording session without an
+ output.
+*/
LTTNG_EXPORT extern struct lttng_session_descriptor *
-lttng_session_descriptor_local_create(const char *name, const char *path);
+lttng_session_descriptor_local_create(const char *session_name, const char *trace_dir);
-/*
- * Create a session descriptor with a remote output destination.
- *
- * The 'name' parameter can be left NULL to auto-generate a session name.
- *
- * The 'control_url' and 'data_url' must conform to the URL format
- * described above or can be left NULL to use the default network output.
- *
- * Returns an lttng_session_descriptor instance on success, NULL on error.
- */
+/*!
+@brief
+ Creates a recording session descriptor to create a
+ \ref api-session-net-mode "network streaming" recording session
+ named \lt_p{session_name}.
+
+The valid combinations of \lt_p{control_url} and \lt_p{data_url} are:
+
+<table>
+ <tr>
+ <th>\lt_p{control_url}
+ <th>\lt_p{data_url}
+ <th>Behaviour
+ <tr>
+ <td>\c NULL
+ <td>\c NULL
+ <td>
+ Use \lt_def_net_ctrl_url as \lt_p{control_url}.
+
+ Use \lt_def_net_data_url as \lt_p{data_url}.
+ <tr>
+ <td>\ref api-session-one-port-url "Single-port output URL"
+ <td>\c NULL
+ <td>
+ Use the protocol, host, and trace directory (if any) of
+ \lt_p{control_url} and the port \lt_def_net_data_port
+ as \lt_p{data_url}.
+ <tr>
+ <td>Single-port output URL
+ <td>
+ Single-port output URL with the exact same protocol, host,
+ and trace directory (if any) as \lt_p{control_url}.
+ <td>
+ Use the specified output URLs.
+ <tr>
+ <td>\ref api-session-two-port-url "Two-port output URL"
+ <td>\c NULL
+ <td>
+ Use the protocol, host, data port, and trace directory (if any)
+ of \lt_p{control_url} as \lt_p{data_url}.
+</table>
+
+@param[in] session_name
+ @parblock
+ Recording session name.
+
+ If \c NULL, LTTng automatically generates a recording session name
+ when you call lttng_create_session_ext().
+
+ Call lttng_session_descriptor_get_session_name() with the returned
+ recording session descriptor after successfully calling
+ lttng_create_session_ext() to get the generated name.
+ @endparblock
+@param[in] control_url
+ @parblock
+ One of:
+
+ <dl>
+ <dt>\ref api-session-one-port-url "Single-port output URL"
+ <dd>
+ Indicates where (to which relay daemon; see
+ \lt_man{lttng-relayd,8}) to send the control data.
+
+ <dt>\ref api-session-two-port-url "Two-port output URL"
+ <dd>
+ Indicates where to send the control \em and trace data.
+ </dl>
+
+ If \c NULL, this function uses \lt_def_net_url.
+ @endparblock
+@param[in] data_url
+ @parblock
+ \ref api-session-one-port-url "Single-port output URL" which
+ indicates where to send the trace data.
+
+ May be <code>NULL</code>: see the table above for the default value
+ depending on \lt_p{control_url}.
+ @endparblock
+
+@returns
+ @parblock
+ Recording session descriptor on success, or \c NULL on error.
+
+ Destroy the returned descriptor with
+ lttng_session_descriptor_destroy().
+ @endparblock
+
+@lt_pre_sess_name_not_auto{session_name}
+@pre
+ \lt_p{control_url} and \lt_p{data_url} satisfy one of the valid
+ combinations shown in the table above.
+*/
LTTNG_EXPORT extern struct lttng_session_descriptor *lttng_session_descriptor_network_create(
- const char *name, const char *control_url, const char *data_url);
+ const char *session_name, const char *control_url, const char *data_url);
-/*
- * Create a snapshot session descriptor without a default output.
- *
- * The 'name' parameter can be left NULL to auto-generate a session name.
- *
- * Returns an lttng_session_descriptor instance on success, NULL on error.
- */
+/*!
+@brief
+ Creates a recording session descriptor to create a
+ \ref api-session-snapshot-mode "snapshot" recording session
+ named \lt_p{session_name} without an initial output.
+
+A recording session which lttng_create_session_ext() creates from the
+returned descriptor has no initial snapshot output: you need to either
+add one with lttng_snapshot_add_output() or provide one when you take a
+snapshot with lttng_snapshot_record().
+
+@param[in] session_name
+ @parblock
+ Recording session name.
+
+ If \c NULL, LTTng automatically generates a recording session name
+ when you call lttng_create_session_ext().
+
+ Call lttng_session_descriptor_get_session_name() with the returned
+ recording session descriptor after successfully calling
+ lttng_create_session_ext() to get the generated name.
+ @endparblock
+
+@returns
+ @parblock
+ Recording session descriptor on success, or \c NULL on error.
+
+ Destroy the returned descriptor with
+ lttng_session_descriptor_destroy().
+ @endparblock
+
+@lt_pre_sess_name_not_auto{session_name}
+
+@sa lttng_session_descriptor_snapshot_local_create() --
+ Creates a recording session descriptor to create a
+ \ref api-session-snapshot-mode "snapshot" recording session
+ with an initial local output.
+@sa lttng_session_descriptor_snapshot_network_create() --
+ Creates a recording session descriptor to create a
+ \ref api-session-snapshot-mode "snapshot" recording session
+ with an initial remote output.
+*/
LTTNG_EXPORT extern struct lttng_session_descriptor *
-lttng_session_descriptor_snapshot_create(const char *name);
+lttng_session_descriptor_snapshot_create(const char *session_name);
-/*
- * Create a snapshot session descriptor with a local output destination.
- *
- * The 'name' parameter can be left NULL to auto-generate a session name.
- *
- * The 'path' must either be an absolute path or it can be left NULL to
- * use the default local output destination as the default snapshot output.
- *
- * Returns an lttng_session_descriptor instance on success, NULL on error.
- */
+/*!
+@brief
+ Creates a recording session descriptor to create a
+ \ref api-session-snapshot-mode "snapshot" recording session
+ named \lt_p{session_name} and having an initial local output.
+
+Using the returned descriptor when you call lttng_create_session_ext()
+to create a snapshot recording session is similar to using a descriptor
+which lttng_session_descriptor_snapshot_create() returns and calling
+lttng_snapshot_add_output() after creating the recording session.
+
+The name of this initial snapshot output is <code>snapshot-0</code>.
+
+@param[in] session_name
+ @parblock
+ Recording session name.
+
+ If \c NULL, LTTng automatically generates a recording session name
+ when you call lttng_create_session_ext().
+
+ Call lttng_session_descriptor_get_session_name() with the returned
+ recording session descriptor after successfully calling
+ lttng_create_session_ext() to get the generated name.
+ @endparblock
+@param[in] trace_dir
+ @parblock
+ Absolute path of an initial snapshot output.
+
+ If \c NULL, the snapshot output directory is, after calling
+ lttng_create_session_ext(),
+ <code><em>$LTTNG_HOME</em>/lttng-traces/<em>NAME</em>-<em>TS</em></code>,
+ with:
+
+ <dl>
+ <dt><code><em>$LTTNG_HOME</em></code>
+ <dd>
+ The value of the \c LTTNG_HOME environment variable, or
+ of the \c HOME environment variable if \c LTTNG_HOME isn't
+ set.
+
+ <dt><code><em>NAME</em></code>
+ <dd>
+ Recording session name (\lt_p{session_name} if not \c NULL, or
+ an automatically generated name otherwise).
+
+ <dt><code><em>TS</em></code>
+ <dd>
+ \link lttng_session_get_creation_time() Timestamp of the
+ creation\endlink of the recording session using the
+ <code>YYYYmmdd-HHMMSS</code> form.
+ </dl>
+ @endparblock
+
+@returns
+ @parblock
+ Recording session descriptor on success, or \c NULL on error.
+
+ Destroy the returned descriptor with
+ lttng_session_descriptor_destroy().
+ @endparblock
+
+@lt_pre_sess_name_not_auto{session_name}
+@pre
+ <strong>If not \c NULL</strong>, \lt_p{trace_dir} is a valid path.
+
+@sa lttng_session_descriptor_snapshot_create() --
+ Creates a recording session descriptor to create a
+ \ref api-session-snapshot-mode "snapshot" recording session
+ without an initial output.
+@sa lttng_session_descriptor_snapshot_network_create() --
+ Creates a recording session descriptor to create a
+ \ref api-session-snapshot-mode "snapshot" recording session
+ with an initial remote output.
+*/
LTTNG_EXPORT extern struct lttng_session_descriptor *
-lttng_session_descriptor_snapshot_local_create(const char *name, const char *path);
+lttng_session_descriptor_snapshot_local_create(const char *session_name, const char *trace_dir);
-/*
- * Create a snapshot session descriptor with a remote output destination.
- *
- * The 'name' parameter can be left NULL to auto-generate a session name.
- *
- * The 'control_url' and 'data_url' must conform to the URL format
- * described above or can be left NULL to use the default network output as
- * the default snapshot output.
- *
- * Returns an lttng_session_descriptor instance on success, NULL on error.
- */
+/*!
+@brief
+ Creates a recording session descriptor to create a
+ \ref api-session-snapshot-mode "snapshot" recording session
+ named \lt_p{session_name} and having an initial remote output.
+
+Using the returned descriptor when you call lttng_create_session_ext()
+to create a snapshot recording session is similar to using a descriptor
+which lttng_session_descriptor_snapshot_create() returns and calling
+lttng_snapshot_add_output() after creating the recording session.
+
+The name of this initial snapshot output is <code>snapshot-0</code>.
+
+The valid combinations of \lt_p{control_url} and \lt_p{data_url} are:
+
+<table>
+ <tr>
+ <th>\lt_p{control_url}
+ <th>\lt_p{data_url}
+ <th>Behaviour
+ <tr>
+ <td>\c NULL
+ <td>\c NULL
+ <td>
+ Use \lt_def_net_ctrl_url as \lt_p{control_url}.
+
+ Use \lt_def_net_data_url as \lt_p{data_url}.
+ <tr>
+ <td>\ref api-session-one-port-url "Single-port output URL"
+ <td>\c NULL
+ <td>
+ Use the protocol, host, and trace directory (if any) of
+ \lt_p{control_url} and the port \lt_def_net_data_port
+ as \lt_p{data_url}.
+ <tr>
+ <td>Single-port output URL
+ <td>
+ Single-port output URL with the exact same protocol, host,
+ and trace directory (if any) as \lt_p{control_url}.
+ <td>
+ Use the specified output URLs.
+ <tr>
+ <td>\ref api-session-two-port-url "Two-port output URL"
+ <td>\c NULL
+ <td>
+ Use the protocol, host, data port, and trace directory (if any)
+ of \lt_p{control_url} as \lt_p{data_url}.
+</table>
+
+@param[in] session_name
+ @parblock
+ Recording session name.
+
+ If \c NULL, LTTng automatically generates a recording session name
+ when you call lttng_create_session_ext().
+
+ Call lttng_session_descriptor_get_session_name() with the returned
+ recording session descriptor after successfully calling
+ lttng_create_session_ext() to get the generated name.
+ @endparblock
+@param[in] control_url
+ @parblock
+ Control data URL of an initial snapshot output.
+
+ One of:
+
+ <dl>
+ <dt>\ref api-session-one-port-url "Single-port output URL"
+ <dd>
+ Indicates where (to which relay daemon; see
+ \lt_man{lttng-relayd,8}) to send the control data.
+
+ <dt>\ref api-session-two-port-url "Two-port output URL"
+ <dd>
+ Indicates where to send the control \em and trace data.
+ </dl>
+
+ If \c NULL, this function uses \lt_def_net_url.
+ @endparblock
+@param[in] data_url
+ @parblock
+ Trace data URL of an initial snapshot output.
+
+ \ref api-session-one-port-url "Single-port output URL" which
+ indicates where to send the trace data.
+
+ May be <code>NULL</code>: see the table above for the default value
+ depending on \lt_p{control_url}.
+ @endparblock
+
+@returns
+ @parblock
+ Recording session descriptor on success, or \c NULL on error.
+
+ Destroy the returned descriptor with
+ lttng_session_descriptor_destroy().
+ @endparblock
+
+@lt_pre_sess_name_not_auto{session_name}
+@pre
+ \lt_p{control_url} and \lt_p{data_url} satisfy one of the valid
+ combinations shown in the table above.
+
+@sa lttng_session_descriptor_snapshot_create() --
+ Creates a recording session descriptor to create a
+ \ref api-session-snapshot-mode "snapshot" recording session
+ without an initial output.
+@sa lttng_session_descriptor_snapshot_local_create() --
+ Creates a recording session descriptor to create a
+ \ref api-session-snapshot-mode "snapshot" recording session
+ with an initial local output.
+*/
LTTNG_EXPORT extern struct lttng_session_descriptor *
-lttng_session_descriptor_snapshot_network_create(const char *name,
+lttng_session_descriptor_snapshot_network_create(const char *session_name,
const char *control_url,
const char *data_url);
/*
+ * NOTE: Not documented with Doxygen as what lttng_create_session_ext()
+ * creates from such a descriptor is useless (a live recording session
+ * without any output). Original documentation follows.
+ *
* Create a live session descriptor without an output.
*
* The 'name' parameter can be left NULL to auto-generate a session name.
LTTNG_EXPORT extern struct lttng_session_descriptor *
lttng_session_descriptor_live_create(const char *name, unsigned long long live_timer_interval_us);
-/*
- * Create a live session descriptor with a remote output destination.
- *
- * The 'name' parameter can be left NULL to auto-generate a session name.
- *
- * The 'control_url' and 'data_url' must conform to the URL format
- * described above or can be left NULL to use the default network output.
- *
- * The 'live_timer_interval_us' parameter is the live timer's period, specified
- * in microseconds.
- *
- * This parameter can't be 0. There is no default value defined for a live
- * timer's period.
- *
- * Returns an lttng_session_descriptor instance on success, NULL on error.
- */
+/*!
+@brief
+ Creates a recording session descriptor to create a
+ \ref api-session-live-mode "live" recording session
+ named \lt_p{session_name}.
+
+The valid combinations of \lt_p{control_url} and \lt_p{data_url} are:
+
+<table>
+ <tr>
+ <th>\lt_p{control_url}
+ <th>\lt_p{data_url}
+ <th>Behaviour
+ <tr>
+ <td>\c NULL
+ <td>\c NULL
+ <td>
+ Use \lt_def_net_ctrl_url as \lt_p{control_url}.
+
+ Use \lt_def_net_data_url as \lt_p{data_url}.
+ <tr>
+ <td>\ref api-session-one-port-url "Single-port output URL"
+ <td>\c NULL
+ <td>
+ Use the protocol, host, and trace directory (if any) of
+ \lt_p{control_url} and the port \lt_def_net_data_port
+ as \lt_p{data_url}.
+ <tr>
+ <td>Single-port output URL
+ <td>
+ Single-port output URL with the exact same protocol, host,
+ and trace directory (if any) as \lt_p{control_url}.
+ <td>
+ Use the specified output URLs.
+ <tr>
+ <td>\ref api-session-two-port-url "Two-port output URL"
+ <td>\c NULL
+ <td>
+ Use the protocol, host, data port, and trace directory (if any)
+ of \lt_p{control_url} as \lt_p{data_url}.
+</table>
+
+@param[in] session_name
+ @parblock
+ Recording session name.
+
+ If \c NULL, LTTng automatically generates a recording session name
+ when you call lttng_create_session_ext().
+
+ Call lttng_session_descriptor_get_session_name() with the returned
+ recording session descriptor after successfully calling
+ lttng_create_session_ext() to get the generated name.
+ @endparblock
+@param[in] control_url
+ @parblock
+ One of:
+
+ <dl>
+ <dt>\ref api-session-one-port-url "Single-port output URL"
+ <dd>
+ Indicates where (to which relay daemon; see
+ \lt_man{lttng-relayd,8}) to send the control data.
+
+ <dt>\ref api-session-two-port-url "Two-port output URL"
+ <dd>
+ Indicates where to send the control \em and trace data.
+ </dl>
+
+ If \c NULL, this function uses \lt_def_net_url.
+ @endparblock
+@param[in] data_url
+ @parblock
+ \ref api-session-one-port-url "Single-port output URL" which
+ indicates where to send the trace data.
+
+ May be <code>NULL</code>: see the table above for the default value
+ depending on \lt_p{control_url}.
+ @endparblock
+@param[in] live_timer_period
+ Period (µs) of the \ref api-channel-live-timer "live timers" of all
+ the channels of a recording session which lttng_create_session_ext()
+ creates from the returned descriptor.
+
+@returns
+ @parblock
+ Recording session descriptor on success, or \c NULL on error.
+
+ Destroy the returned descriptor with
+ lttng_session_descriptor_destroy().
+ @endparblock
+
+@lt_pre_sess_name_not_auto{session_name}
+@pre
+ \lt_p{control_url} and \lt_p{data_url} satisfy one of the valid
+ combinations shown in the table above.
+@pre
+ \lt_p{live_timer_period} ≥ 1
+*/
LTTNG_EXPORT extern struct lttng_session_descriptor *
-lttng_session_descriptor_live_network_create(const char *name,
+lttng_session_descriptor_live_network_create(const char *session_name,
const char *control_url,
const char *data_url,
- unsigned long long live_timer_interval_us);
+ unsigned long long live_timer_period);
/*
* Get a session descriptor's session name.
* NULL, and LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET if the descriptor's
* name parameter is unset.
*/
+
+/*!
+@brief
+ Sets \lt_p{*session_name} to the name of the recording session
+ which lttng_create_session_ext() created from the recording
+ session descriptor \lt_p{session_descriptor}.
+
+Call this function after successfully calling lttng_create_session_ext()
+when \lt_p{session_descriptor} wasn't created with a specific recording
+session name to get the automatically generated name of the created
+recording session.
+
+@param[in] session_descriptor
+ Recording session descriptor from which lttng_create_session_ext()
+ previously created the recording session of which to get the name.
+@param[out] session_name
+ @parblock
+ <strong>On success</strong>, this function sets \lt_p{*session_name}
+ to the name of the recording session which
+ lttng_create_session_ext() previously created from
+ \lt_p{session_descriptor}.
+
+ \lt_p{session_descriptor} owns \lt_p{*session_name}.
+
+ \lt_p{*session_name} remains valid until the next recording
+ session descriptor function call with \lt_p{session_descriptor}.
+ @endparblock
+
+@retval #LTTNG_SESSION_DESCRIPTOR_STATUS_OK
+ Success.
+@retval #LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID
+ Unsatisfied precondition.
+@retval #LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET
+ The name property of \lt_p{session_descriptor} is not set.
+
+@lt_pre_not_null{session_descriptor}
+@pre
+ You successfully called lttng_create_session_ext() with
+ \lt_p{session_descriptor}.
+@lt_pre_not_null{session_name}
+*/
LTTNG_EXPORT extern enum lttng_session_descriptor_status
-lttng_session_descriptor_get_session_name(const struct lttng_session_descriptor *descriptor,
- const char **name);
+lttng_session_descriptor_get_session_name(const struct lttng_session_descriptor *session_descriptor,
+ const char **session_name);
-/*
- * Destroy a local lttng_session object.
- *
- * This does not destroy the session on the session daemon; it releases
- * the resources allocated by the descriptor object.
- */
+/*!
+@brief
+ Destroys the recording session descriptor \lt_p{session_descriptor}.
+
+@note
+ @parblock
+ This function doesn't destroy the recording session which
+ lttng_create_session_ext() created from \lt_p{session_descriptor},
+ but only the descriptor itself.
+
+ Use lttng_destroy_session_ext() to destroy a recording session.
+ @endparblock
+
+@param[in] session_descriptor
+ @parblock
+ Recording session descriptor to destroy.
+
+ May be \c NULL.
+ @endparblock
+*/
LTTNG_EXPORT extern void
-lttng_session_descriptor_destroy(struct lttng_session_descriptor *descriptor);
+lttng_session_descriptor_destroy(struct lttng_session_descriptor *session_descriptor);
+
+/// @}
#ifdef __cplusplus
}
extern "C" {
#endif
-#include <lttng/constant.h>
#include <lttng/lttng-export.h>
+/*!
+@addtogroup api_session
+@{
+*/
+
+#include <lttng/constant.h>
+
struct lttng_handle;
struct lttng_session_descriptor;
struct lttng_destruction_handle;
-/*
- * Basic session information.
- *
- * The "enabled" field is only used when listing the sessions which indicate if
- * it's started or not.
- *
- * The structures should be initialized to zero before use.
- */
#define LTTNG_SESSION_PADDING1 8
+
+/*!
+@brief
+ Recording session summary.
+
+The purpose of such a structure is to provide information about a
+\lt_obj_session itself, but not about its \lt_obj_domains
+and \lt_obj_channels (use lttng_list_domains() and lttng_list_channels()
+for this).
+
+lttng_list_sessions() sets a pointer to an array of all the available
+recording session summaries.
+*/
struct lttng_session {
+ /// Name.
char name[LTTNG_NAME_MAX];
- /*
- * Human-readable representation of the trace's destination.
- * In the case of a local tracing session, a path is provided:
- * /path/to/the/output
- *
- * In the case of a remote (network) tracing session, the string has
- * the following format:
- * net://hostname/path:ctrl_port [data: data_port]
- */
+
+ /*!
+ @brief
+ <em>Human-readable</em> representation of the output (local
+ or remote).
+ */
char path[PATH_MAX];
+
+ /*!
+ @brief
+ 1 if this recording session is active (started), or 0
+ otherwise.
+
+ @sa lttng_start_tracing() --
+ Starts a recording session.
+ @sa lttng_stop_tracing() --
+ Stops a recording session.
+ */
uint32_t enabled; /* enabled/started: 1, disabled/stopped: 0 */
+
+ /*!
+ @brief
+ 1 if this recording session was created in
+ \ref api-session-snapshot-mode "snapshot mode",
+ or 0 otherwise.
+
+ @note
+ If this member is 1, then the
+ lttng_session::live_timer_interval member is 0.
+ */
uint32_t snapshot_mode;
+
+ /*!
+ @brief
+ Period (µs) of the \ref api-channel-live-timer "live timers"
+ of the channels of this recording session, or 0 if this
+ recording session wasn't created in
+ \ref api-session-live-mode "live mode".
+
+ @note
+ If this member is \em not 0, then the
+ lttng_session::snapshot_mode member is 0.
+ */
unsigned int live_timer_interval; /* usec */
/*
} extended;
};
-/*
- * Create a session on the session daemon from a session descriptor.
- *
- * See the session descriptor API description in session-descriptor.h
- *
- * Note that unspecified session descriptor parameters, such as a session's
- * name, are updated in the session descriptor if the creation of the session
- * succeeds. This allows users to query the session's auto-generated name
- * after its creation. Note that other attributes can be queried using the
- * session listing API.
- *
- * Returns LTTNG_OK on success. See lttng-error.h for the meaning of the other
- * return codes.
- */
+/*!
+@brief
+ Creates a recording session from the recording session descriptor
+ \lt_p{session_descriptor}.
+
+See \ref api_session_descr to learn how to create a recording session
+descriptor.
+
+On success, if the name property of \lt_p{session_descriptor} isn't set,
+this function sets it to the automatically generated name of the
+recording session. Get the recording session name with
+lttng_session_descriptor_get_session_name().
+
+@param[in] session_descriptor
+ Descriptor from which to create a recording session.
+
+@returns
+ #LTTNG_OK on success, or a \em negative enumerator otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_descriptor}
+@pre
+ If the name property of \lt_p{session_descriptor} is set, then no
+ available recording session has this name.
+
+@sa \ref api_session_descr.
+@sa \lt_man{lttng-create,1}
+*/
LTTNG_EXPORT extern enum lttng_error_code
lttng_create_session_ext(struct lttng_session_descriptor *session_descriptor);
-/*
- * Create a tracing session using a name and an optional URL.
- *
- * If _url_ is NULL, no consumer is created for the session. The name can't be
- * NULL here.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-LTTNG_EXPORT extern int lttng_create_session(const char *name, const char *url);
+/*!
+@brief
+ Creates a recording session named \lt_p{session_name} in
+ \ref api-session-local-mode "local"
+ or \ref api-session-net-mode "network streaming" mode, optionally
+ setting its output URL to \lt_p{output_url}.
-/*
- * Create a tracing session that will exclusively be used for snapshot meaning
- * the session will be in no output mode and every channel enabled for that
- * session will be set in overwrite mode and in mmap output since splice is not
- * supported.
- *
- * Name can't be NULL. If an url is given, it will be used to create a default
- * snapshot output using it as a destination. If NULL, no output will be
- * defined and an add-output call will be needed.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-LTTNG_EXPORT extern int lttng_create_session_snapshot(const char *name, const char *snapshot_url);
+@deprecated
+ Use lttng_create_session_ext() with a dedicated
+ local or network streaming
+ \ref api_session_descr "recording session descriptor".
-/*
- * Create a session exclusively used for live reading.
- *
- * In this mode, the switch-timer parameter is forced for each UST channel, a
- * live-switch-timer is enabled for kernel channels, manually setting
- * switch-timer is forbidden. Synchronization beacons are sent to the relayd,
- * indexes are sent and metadata is checked for each packet.
- *
- * Name can't be NULL. If no URL is given, the default is to send the data to
- * net://127.0.0.1. The timer_interval is in usec.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-LTTNG_EXPORT extern int
-lttng_create_session_live(const char *name, const char *url, unsigned int timer_interval);
+@param[in] session_name
+ Name of the new recording session.
+@param[in] output_url
+ @parblock
+ \ref api-session-url "Output URL" of the recording session to
+ create.
-/*
- * Destroy a tracing session.
- *
- * The session will not be usable, tracing will be stopped thus buffers will be
- * flushed.
- *
- * This call will wait for data availability for each domain of the session,
- * which can take an arbitrary amount of time. However, when returning the
- * tracing data is guaranteed to be ready to be read and analyzed.
- *
- * lttng_destroy_session_no_wait() may be used if such a guarantee is not
- * needed.
- *
- * The name can't be NULL here.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-LTTNG_EXPORT extern int lttng_destroy_session(const char *name);
+ If it's a \ref api-session-one-port-url "single-port output URL",
+ then the trace data port is \lt_def_net_data_port.
-/*
- * Destroy a tracing session.
- *
- * Performs the same function as lttng_destroy_session(), but provides
- * an lttng_destruction_handle which can be used to wait for the completion
- * of the session's destruction. The lttng_destroy_handle can also be used
- * obtain the status and archive location of any implicit session
- * rotation that may have occurred during the session's destruction.
- *
- * Returns LTTNG_OK on success. The returned handle is owned by the caller
- * and must be free'd using lttng_destruction_handle_destroy().
- */
+ If \c NULL, LTTng doesn't write any trace data for this recording
+ session.
+ @endparblock
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_name_not_auto{session_name}
+@pre
+ No available recording session is named \lt_p{session_name}.
+@pre
+ <strong>If not \c NULL</strong>, \lt_p{output_url} is a valid
+ \ref api-session-url "output URL".
+
+@sa lttng_create_session_snapshot() --
+ Creates a recording session in snapshot mode.
+@sa lttng_create_session_live() --
+ Creates a recording session in live mode.
+@sa \lt_man{lttng-create,1}
+*/
+LTTNG_EXPORT extern int lttng_create_session(const char *session_name, const char *output_url);
+
+/*!
+@brief
+ Creates a recording session named \lt_p{session_name} in
+ \ref api-session-snapshot-mode "snapshot" mode, optionally setting
+ the URL of its initial snapshot output to \lt_p{output_url}.
+
+@deprecated
+ Use lttng_create_session_ext() with a dedicated snapshot
+ \ref api_session_descr "recording session descriptor".
+
+@param[in] session_name
+ Name of the new recording session.
+@param[in] output_url
+ @parblock
+ \ref api-session-url "URL" of an initial snapshot output
+ which LTTng adds to this recording session.
+
+ If it's a \ref api-session-one-port-url "single-port output URL",
+ then the trace data port is \lt_def_net_data_port.
+
+ This initial snapshot output is named <code>snapshot-0</code>.
+
+ If \c NULL, then the created recording session has no initial
+ snapshot output: you need to either add one with
+ lttng_snapshot_add_output() or provide one when you take a snapshot
+ with lttng_snapshot_record().
+ @endparblock
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_name_not_auto{session_name}
+@pre
+ No available recording session is named \lt_p{session_name}.
+@pre
+ <strong>If not \c NULL</strong>, \lt_p{output_url} is a valid
+ \ref api-session-url "output URL".
+
+@sa lttng_create_session() --
+ Creates a recording session in local or network streaming mode.
+@sa lttng_create_session_live() --
+ Creates a recording session in live mode.
+@sa \lt_man{lttng-create,1}
+*/
+LTTNG_EXPORT extern int lttng_create_session_snapshot(const char *session_name,
+ const char *output_url);
+
+/*!
+@brief
+ Creates a recording session named \lt_p{session_name} in
+ \ref api-session-live-mode "live" mode, optionally setting its
+ URL to \lt_p{output_url}.
+
+@deprecated
+ Use lttng_create_session_ext() with a dedicated live
+ \ref api_session_descr "recording session descriptor".
+
+@param[in] session_name
+ Name of the new recording session.
+@param[in] output_url
+ @parblock
+ \ref api-session-url "Output URL" of the recording session to
+ create: \ref api-session-one-port-url "single-port" or
+ \ref api-session-two-port-url "two-port".
+
+ If it's a \ref api-session-one-port-url "single-port output URL",
+ then the trace data port is \lt_def_net_data_port.
+
+ If \c NULL, this function uses \lt_def_net_url.
+ @endparblock
+@param[in] live_timer_period
+ Period (µs) of the \ref api-channel-live-timer "live timers" of all
+ the channels of the created recording session.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_name_not_auto{session_name}
+@pre
+ No available recording session is named \lt_p{session_name}.
+@pre
+ <strong>If not \c NULL</strong>, \lt_p{output_url} is a valid
+ \ref api-session-one-port-url "single-port output URL" or
+ \ref api-session-two-port-url "two-port output URL".
+@pre
+ \lt_p{live_timer_period} ≥ 1
+
+@sa lttng_create_session() --
+ Creates a recording session in local or network streaming mode.
+@sa lttng_create_session_snapshot() --
+ Creates a recording session in snapshot mode.
+@sa \lt_man{lttng-create,1}
+*/
+LTTNG_EXPORT extern int lttng_create_session_live(const char *session_name,
+ const char *output_url,
+ unsigned int live_timer_period);
+
+/*!
+@brief
+ Destroys the recording session named \lt_p{session_name}, blocking
+ until the operation completes.
+
+@deprecated
+ Use lttng_destroy_session_ext().
+
+"Destroying" a recording session means freeing the resources which the
+LTTng daemons and tracers acquired for it, also making sure to flush all
+the recorded trace data to either the local file system or the connected
+LTTng relay daemon (see \lt_man{lttng-relayd,8}), depending on the
+\ref api-session-modes "recording session mode".
+
+This function stops any recording activity within the recording session
+named \lt_p{session_name}.
+
+This function implicitly calls lttng_stop_tracing(), blocking until the
+trace data of the recording session becomes valid. Use
+lttng_destroy_session_no_wait() to avoid a blocking call.
+
+@param[in] session_name
+ Name of the recording session to destroy.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+
+@sa lttng_destroy_session_no_wait() --
+ Initiates the destruction operation of a recording session,
+ returning immediately.
+@sa \lt_man{lttng-destroy,1}
+*/
+LTTNG_EXPORT extern int lttng_destroy_session(const char *session_name);
+
+/*!
+@brief
+ Initiates the destruction operation of the recording session named
+ \lt_p{session_name}.
+
+@deprecated
+ Use lttng_destroy_session_ext().
+
+"Destroying" a recording session means freeing the resources which the
+LTTng daemons and tracers acquired for it, also making sure to flush all
+the recorded trace data to either the local file system or the connected
+LTTng relay daemon (see \lt_man{lttng-relayd,8}), depending on the
+\ref api-session-modes "recording session mode".
+
+Unlike lttng_destroy_session(), this function does \em not block until
+the destruction operation is complete: it returns immediately. This
+means the trace(s) of the recording session might not be valid when
+this function returns, and there's no way to know when it/they become
+valid.
+
+@param[in] session_name
+ Name of the recording session to destroy.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+@pre
+ No destruction operation is in progress for the recording session
+ named \lt_p{session_name}.
+
+@sa lttng_destroy_session() --
+ Destroys a recording session, blocking until the operation
+ completes.
+@sa \lt_man{lttng-destroy,1}
+*/
+LTTNG_EXPORT extern int lttng_destroy_session_no_wait(const char *session_name);
+
+/*!
+@brief
+ Initiates a destruction operation of the recording session
+ named \lt_p{session_name}.
+
+"Destroying" a recording session means freeing the resources which the
+LTTng daemons and tracers acquired for it, also making sure to flush all
+the recorded trace data to either the local file system or the connected
+LTTng relay daemon (see \lt_man{lttng-relayd,8}), depending on the
+\ref api-session-modes "recording session mode".
+
+This function doesn't block until the destruction operation completes:
+it only initiates the operation.
+Use \lt_p{*handle} to wait for the operation to complete.
+
+@param[in] session_name
+ Name of the recording session to destroy.
+@param[out] handle
+ @parblock
+ <strong>On success</strong>, this function sets \lt_p{*handle} to
+ a handle which identifies this recording session destruction
+ operation.
+
+ May be \c NULL.
+
+ Wait for the completion of this destruction operation with
+ lttng_destruction_handle_wait_for_completion().
+
+ Destroy \lt_p{*handle} with lttng_destruction_handle_destroy().
+ @endparblock
+
+@returns
+ #LTTNG_OK on success, or a \em negative enumerator otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+@pre
+ No destruction operation is in progress for the recording session
+ named \lt_p{session_name}.
+
+@sa \lt_man{lttng-destroy,1}
+*/
LTTNG_EXPORT extern enum lttng_error_code
lttng_destroy_session_ext(const char *session_name, struct lttng_destruction_handle **handle);
-/*
- * Behaves exactly like lttng_destroy_session but does not wait for data
- * availability.
- */
-LTTNG_EXPORT extern int lttng_destroy_session_no_wait(const char *name);
+/*!
+@brief
+ Sets \lt_p{*sessions} to the summaries of all the available
+ recording sessions.
-/*
- * List all the tracing sessions.
- *
- * Return the number of entries of the "lttng_session" array. The caller
- * must free the returned sessions array directly using free().
- *
- * On error, a negative LTTng error code is returned.
- */
+@param[out] sessions
+ @parblock
+ <strong>On success</strong>, this function sets \lt_p{*sessions} to
+ the summaries of the available recording sessions.
+
+ Free \lt_p{*sessions} with <code>free()</code>.
+ @endparblock
+
+@returns
+ The number of items in \lt_p{*sessions} on success, or a \em
+ negative #lttng_error_code enumerator otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{sessions}
+
+@sa \lt_man{lttng-list,1}
+*/
LTTNG_EXPORT extern int lttng_list_sessions(struct lttng_session **sessions);
-/*
- * Get the creation time of an lttng_session object on the session daemon.
- *
- * This function must only be used with lttng_session objects returned
- * by lttng_list_sessions() or lttng_session_create().
- *
- * The creation time returned is a UNIX timestamp; the number of seconds since
- * Epoch (1970-01-01 00:00:00 +0000 (UTC)).
- *
- * Returns LTTNG_OK on success. See lttng-error.h for the meaning of the other
- * return codes.
- */
+/*!
+@brief
+ Sets \lt_p{*creation_timestamp} to the timestamp of the creation of
+ the recording session summarized by \lt_p{session}.
+
+@param[in] session
+ Summary of the recording session of which to get the creation
+ timestamp, as obtained with lttng_list_sessions().
+@param[out] creation_timestamp
+ <strong>On success</strong>, this function sets
+ \lt_p{*creation_timestamp} to the Unix timestamp of the creation of
+ \lt_p{session}.
+
+@returns
+ #LTTNG_OK on success, or a \em negative enumerator otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session}
+@pre
+ The recording session summarized by \lt_p{session} is accessible
+ within the connected session daemon.
+@lt_pre_not_null{creation_timestamp}
+*/
LTTNG_EXPORT extern enum lttng_error_code
-lttng_session_get_creation_time(const struct lttng_session *session, uint64_t *creation_time);
+lttng_session_get_creation_time(const struct lttng_session *session, uint64_t *creation_timestamp);
-/*
- * Set the shared memory path for a session.
- *
- * Sets the (optional) file system path where shared memory buffers will
- * be created for the session. This is useful for buffer extraction on
- * crash, when used with filesystems like pramfs.
- *
- * Return 0 on success else a negative LTTng error code.
- */
-LTTNG_EXPORT extern int lttng_set_session_shm_path(const char *session_name, const char *shm_path);
+/*!
+@brief
+ Sets the path of the directory containing the shared memory files
+ holding the channel ring buffers of the recording session named
+ \lt_p{session_name} on the local file sytem to \lt_p{shm_dir}.
+
+Specifying a location on an
+<a href="https://en.wikipedia.org/wiki/Non-volatile_random-access_memory">NVRAM</a>
+file system makes it possible to recover the latest recorded trace data
+when the system reboots after a crash with the \lt_man{lttng-crash,1}
+utility.
+
+@param[in] session_name
+ Name of the recording session of which to set the shared memory
+ file directory path.
+@param[in] shm_dir
+ Path of the directory containing the shared memory files of the
+ recording session named \lt_p{session_name}.
+
+@returns
+ 0 on success, or a \em negative #lttng_error_code enumerator
+ otherwise.
+
+@lt_pre_conn
+@lt_pre_not_null{session_name}
+@lt_pre_sess_exists{session_name}
+@lt_pre_sess_never_active{session_name}
+@lt_pre_not_null{shm_dir}
+@pre
+ \lt_p{shm_dir} is a writable directory.
+*/
+LTTNG_EXPORT extern int lttng_set_session_shm_path(const char *session_name, const char *shm_dir);
+
+/// @}
#ifdef __cplusplus
}
--- /dev/null
+# ===========================================================================
+# https://www.gnu.org/software/autoconf-archive/ax_prog_doxygen.html
+# ===========================================================================
+#
+# SYNOPSIS
+#
+# DX_INIT_DOXYGEN(PROJECT-NAME, [DOXYFILE-PATH], [OUTPUT-DIR], ...)
+# DX_DOXYGEN_FEATURE(ON|OFF)
+# DX_DOT_FEATURE(ON|OFF)
+# DX_HTML_FEATURE(ON|OFF)
+# DX_CHM_FEATURE(ON|OFF)
+# DX_CHI_FEATURE(ON|OFF)
+# DX_MAN_FEATURE(ON|OFF)
+# DX_RTF_FEATURE(ON|OFF)
+# DX_XML_FEATURE(ON|OFF)
+# DX_PDF_FEATURE(ON|OFF)
+# DX_PS_FEATURE(ON|OFF)
+#
+# DESCRIPTION
+#
+# The DX_*_FEATURE macros control the default setting for the given
+# Doxygen feature. Supported features are 'DOXYGEN' itself, 'DOT' for
+# generating graphics, 'HTML' for plain HTML, 'CHM' for compressed HTML
+# help (for MS users), 'CHI' for generating a separate .chi file by the
+# .chm file, and 'MAN', 'RTF', 'XML', 'PDF' and 'PS' for the appropriate
+# output formats. The environment variable DOXYGEN_PAPER_SIZE may be
+# specified to override the default 'a4wide' paper size.
+#
+# By default, HTML, PDF and PS documentation is generated as this seems to
+# be the most popular and portable combination. MAN pages created by
+# Doxygen are usually problematic, though by picking an appropriate subset
+# and doing some massaging they might be better than nothing. CHM and RTF
+# are specific for MS (note that you can't generate both HTML and CHM at
+# the same time). The XML is rather useless unless you apply specialized
+# post-processing to it.
+#
+# The macros mainly control the default state of the feature. The use can
+# override the default by specifying --enable or --disable. The macros
+# ensure that contradictory flags are not given (e.g.,
+# --enable-doxygen-html and --enable-doxygen-chm,
+# --enable-doxygen-anything with --disable-doxygen, etc.) Finally, each
+# feature will be automatically disabled (with a warning) if the required
+# programs are missing.
+#
+# Once all the feature defaults have been specified, call DX_INIT_DOXYGEN
+# with the following parameters: a one-word name for the project for use
+# as a filename base etc., an optional configuration file name (the
+# default is '$(srcdir)/Doxyfile', the same as Doxygen's default), and an
+# optional output directory name (the default is 'doxygen-doc'). To run
+# doxygen multiple times for different configuration files and output
+# directories provide more parameters: the second, forth, sixth, etc
+# parameter are configuration file names and the third, fifth, seventh,
+# etc parameter are output directories. No checking is done to catch
+# duplicates.
+#
+# Automake Support
+#
+# The DX_RULES substitution can be used to add all needed rules to the
+# Makefile. Note that this is a substitution without being a variable:
+# only the @DX_RULES@ syntax will work.
+#
+# The provided targets are:
+#
+# doxygen-doc: Generate all doxygen documentation.
+#
+# doxygen-run: Run doxygen, which will generate some of the
+# documentation (HTML, CHM, CHI, MAN, RTF, XML)
+# but will not do the post processing required
+# for the rest of it (PS, PDF).
+#
+# doxygen-ps: Generate doxygen PostScript documentation.
+#
+# doxygen-pdf: Generate doxygen PDF documentation.
+#
+# Note that by default these are not integrated into the automake targets.
+# If doxygen is used to generate man pages, you can achieve this
+# integration by setting man3_MANS to the list of man pages generated and
+# then adding the dependency:
+#
+# $(man3_MANS): doxygen-doc
+#
+# This will cause make to run doxygen and generate all the documentation.
+#
+# The following variable is intended for use in Makefile.am:
+#
+# DX_CLEANFILES = everything to clean.
+#
+# Then add this variable to MOSTLYCLEANFILES.
+#
+# LICENSE
+#
+# Copyright (c) 2009 Oren Ben-Kiki <oren@ben-kiki.org>
+# Copyright (c) 2015 Olaf Mandel <olaf@mandel.name>
+#
+# Copying and distribution of this file, with or without modification, are
+# permitted in any medium without royalty provided the copyright notice
+# and this notice are preserved. This file is offered as-is, without any
+# warranty.
+
+#serial 24
+
+## ----------##
+## Defaults. ##
+## ----------##
+
+DX_ENV=""
+AC_DEFUN([DX_FEATURE_doc], ON)
+AC_DEFUN([DX_FEATURE_dot], OFF)
+AC_DEFUN([DX_FEATURE_man], OFF)
+AC_DEFUN([DX_FEATURE_html], ON)
+AC_DEFUN([DX_FEATURE_chm], OFF)
+AC_DEFUN([DX_FEATURE_chi], OFF)
+AC_DEFUN([DX_FEATURE_rtf], OFF)
+AC_DEFUN([DX_FEATURE_xml], OFF)
+AC_DEFUN([DX_FEATURE_pdf], ON)
+AC_DEFUN([DX_FEATURE_ps], ON)
+
+## --------------- ##
+## Private macros. ##
+## --------------- ##
+
+# DX_ENV_APPEND(VARIABLE, VALUE)
+# ------------------------------
+# Append VARIABLE="VALUE" to DX_ENV for invoking doxygen and add it
+# as a substitution (but not a Makefile variable). The substitution
+# is skipped if the variable name is VERSION.
+AC_DEFUN([DX_ENV_APPEND],
+[AC_SUBST([DX_ENV], ["$DX_ENV $1='$2'"])dnl
+m4_if([$1], [VERSION], [], [AC_SUBST([$1], [$2])dnl
+AM_SUBST_NOTMAKE([$1])])dnl
+])
+
+# DX_DIRNAME_EXPR
+# ---------------
+# Expand into a shell expression prints the directory part of a path.
+AC_DEFUN([DX_DIRNAME_EXPR],
+ [[expr ".$1" : '\(\.\)[^/]*$' \| "x$1" : 'x\(.*\)/[^/]*$']])
+
+# DX_IF_FEATURE(FEATURE, IF-ON, IF-OFF)
+# -------------------------------------
+# Expands according to the M4 (static) status of the feature.
+AC_DEFUN([DX_IF_FEATURE], [ifelse(DX_FEATURE_$1, ON, [$2], [$3])])
+
+# DX_REQUIRE_PROG(VARIABLE, PROGRAM)
+# ----------------------------------
+# Require the specified program to be found for the DX_CURRENT_FEATURE to work.
+AC_DEFUN([DX_REQUIRE_PROG], [
+AC_PATH_TOOL([$1], [$2])
+if test "$DX_FLAG_[]DX_CURRENT_FEATURE$$1" = 1; then
+ AC_MSG_WARN([$2 not found - will not DX_CURRENT_DESCRIPTION])
+ AC_SUBST(DX_FLAG_[]DX_CURRENT_FEATURE, 0)
+fi
+])
+
+# DX_TEST_FEATURE(FEATURE)
+# ------------------------
+# Expand to a shell expression testing whether the feature is active.
+AC_DEFUN([DX_TEST_FEATURE], [test "$DX_FLAG_$1" = 1])
+
+# DX_CHECK_DEPEND(REQUIRED_FEATURE, REQUIRED_STATE)
+# -------------------------------------------------
+# Verify that a required features has the right state before trying to turn on
+# the DX_CURRENT_FEATURE.
+AC_DEFUN([DX_CHECK_DEPEND], [
+test "$DX_FLAG_$1" = "$2" \
+|| AC_MSG_ERROR([doxygen-DX_CURRENT_FEATURE ifelse([$2], 1,
+ requires, contradicts) doxygen-$1])
+])
+
+# DX_CLEAR_DEPEND(FEATURE, REQUIRED_FEATURE, REQUIRED_STATE)
+# ----------------------------------------------------------
+# Turn off the DX_CURRENT_FEATURE if the required feature is off.
+AC_DEFUN([DX_CLEAR_DEPEND], [
+test "$DX_FLAG_$1" = "$2" || AC_SUBST(DX_FLAG_[]DX_CURRENT_FEATURE, 0)
+])
+
+# DX_FEATURE_ARG(FEATURE, DESCRIPTION,
+# CHECK_DEPEND, CLEAR_DEPEND,
+# REQUIRE, DO-IF-ON, DO-IF-OFF)
+# --------------------------------------------
+# Parse the command-line option controlling a feature. CHECK_DEPEND is called
+# if the user explicitly turns the feature on (and invokes DX_CHECK_DEPEND),
+# otherwise CLEAR_DEPEND is called to turn off the default state if a required
+# feature is disabled (using DX_CLEAR_DEPEND). REQUIRE performs additional
+# requirement tests (DX_REQUIRE_PROG). Finally, an automake flag is set and
+# DO-IF-ON or DO-IF-OFF are called according to the final state of the feature.
+AC_DEFUN([DX_ARG_ABLE], [
+ AC_DEFUN([DX_CURRENT_FEATURE], [$1])
+ AC_DEFUN([DX_CURRENT_DESCRIPTION], [$2])
+ AC_ARG_ENABLE(doxygen-$1,
+ [AS_HELP_STRING(DX_IF_FEATURE([$1], [--disable-doxygen-$1],
+ [--enable-doxygen-$1]),
+ DX_IF_FEATURE([$1], [don't $2], [$2]))],
+ [
+case "$enableval" in
+#(
+y|Y|yes|Yes|YES)
+ AC_SUBST([DX_FLAG_$1], 1)
+ $3
+;; #(
+n|N|no|No|NO)
+ AC_SUBST([DX_FLAG_$1], 0)
+;; #(
+*)
+ AC_MSG_ERROR([invalid value '$enableval' given to doxygen-$1])
+;;
+esac
+], [
+AC_SUBST([DX_FLAG_$1], [DX_IF_FEATURE([$1], 1, 0)])
+$4
+])
+if DX_TEST_FEATURE([$1]); then
+ $5
+ :
+fi
+if DX_TEST_FEATURE([$1]); then
+ $6
+ :
+else
+ $7
+ :
+fi
+])
+
+## -------------- ##
+## Public macros. ##
+## -------------- ##
+
+# DX_XXX_FEATURE(DEFAULT_STATE)
+# -----------------------------
+AC_DEFUN([DX_DOXYGEN_FEATURE], [AC_DEFUN([DX_FEATURE_doc], [$1])])
+AC_DEFUN([DX_DOT_FEATURE], [AC_DEFUN([DX_FEATURE_dot], [$1])])
+AC_DEFUN([DX_MAN_FEATURE], [AC_DEFUN([DX_FEATURE_man], [$1])])
+AC_DEFUN([DX_HTML_FEATURE], [AC_DEFUN([DX_FEATURE_html], [$1])])
+AC_DEFUN([DX_CHM_FEATURE], [AC_DEFUN([DX_FEATURE_chm], [$1])])
+AC_DEFUN([DX_CHI_FEATURE], [AC_DEFUN([DX_FEATURE_chi], [$1])])
+AC_DEFUN([DX_RTF_FEATURE], [AC_DEFUN([DX_FEATURE_rtf], [$1])])
+AC_DEFUN([DX_XML_FEATURE], [AC_DEFUN([DX_FEATURE_xml], [$1])])
+AC_DEFUN([DX_XML_FEATURE], [AC_DEFUN([DX_FEATURE_xml], [$1])])
+AC_DEFUN([DX_PDF_FEATURE], [AC_DEFUN([DX_FEATURE_pdf], [$1])])
+AC_DEFUN([DX_PS_FEATURE], [AC_DEFUN([DX_FEATURE_ps], [$1])])
+
+# DX_INIT_DOXYGEN(PROJECT, [CONFIG-FILE], [OUTPUT-DOC-DIR], ...)
+# --------------------------------------------------------------
+# PROJECT also serves as the base name for the documentation files.
+# The default CONFIG-FILE is "$(srcdir)/Doxyfile" and OUTPUT-DOC-DIR is
+# "doxygen-doc".
+# More arguments are interpreted as interleaved CONFIG-FILE and
+# OUTPUT-DOC-DIR values.
+AC_DEFUN([DX_INIT_DOXYGEN], [
+
+# Files:
+AC_SUBST([DX_PROJECT], [$1])
+AC_SUBST([DX_CONFIG], ['ifelse([$2], [], [$(srcdir)/Doxyfile], [$2])'])
+AC_SUBST([DX_DOCDIR], ['ifelse([$3], [], [doxygen-doc], [$3])'])
+m4_if(m4_eval(3 < m4_count($@)), 1, [m4_for([DX_i], 4, m4_count($@), 2,
+ [AC_SUBST([DX_CONFIG]m4_eval(DX_i[/2]),
+ 'm4_default_nblank_quoted(m4_argn(DX_i, $@),
+ [$(srcdir)/Doxyfile])')])])dnl
+m4_if(m4_eval(3 < m4_count($@)), 1, [m4_for([DX_i], 5, m4_count($@,), 2,
+ [AC_SUBST([DX_DOCDIR]m4_eval([(]DX_i[-1)/2]),
+ 'm4_default_nblank_quoted(m4_argn(DX_i, $@),
+ [doxygen-doc])')])])dnl
+m4_define([DX_loop], m4_dquote(m4_if(m4_eval(3 < m4_count($@)), 1,
+ [m4_for([DX_i], 4, m4_count($@), 2, [, m4_eval(DX_i[/2])])],
+ [])))dnl
+
+# Environment variables used inside doxygen.cfg:
+DX_ENV_APPEND(SRCDIR, $srcdir)
+DX_ENV_APPEND(PROJECT, $DX_PROJECT)
+DX_ENV_APPEND(VERSION, $PACKAGE_VERSION)
+
+# Doxygen itself:
+DX_ARG_ABLE(doc, [generate any doxygen documentation],
+ [],
+ [],
+ [DX_REQUIRE_PROG([DX_DOXYGEN], doxygen)
+ DX_REQUIRE_PROG([DX_PERL], perl)],
+ [DX_ENV_APPEND(PERL_PATH, $DX_PERL)])
+
+# Dot for graphics:
+DX_ARG_ABLE(dot, [generate graphics for doxygen documentation],
+ [DX_CHECK_DEPEND(doc, 1)],
+ [DX_CLEAR_DEPEND(doc, 1)],
+ [DX_REQUIRE_PROG([DX_DOT], dot)],
+ [DX_ENV_APPEND(HAVE_DOT, YES)
+ DX_ENV_APPEND(DOT_PATH, [`DX_DIRNAME_EXPR($DX_DOT)`])],
+ [DX_ENV_APPEND(HAVE_DOT, NO)])
+
+# Man pages generation:
+DX_ARG_ABLE(man, [generate doxygen manual pages],
+ [DX_CHECK_DEPEND(doc, 1)],
+ [DX_CLEAR_DEPEND(doc, 1)],
+ [],
+ [DX_ENV_APPEND(GENERATE_MAN, YES)],
+ [DX_ENV_APPEND(GENERATE_MAN, NO)])
+
+# RTF file generation:
+DX_ARG_ABLE(rtf, [generate doxygen RTF documentation],
+ [DX_CHECK_DEPEND(doc, 1)],
+ [DX_CLEAR_DEPEND(doc, 1)],
+ [],
+ [DX_ENV_APPEND(GENERATE_RTF, YES)],
+ [DX_ENV_APPEND(GENERATE_RTF, NO)])
+
+# XML file generation:
+DX_ARG_ABLE(xml, [generate doxygen XML documentation],
+ [DX_CHECK_DEPEND(doc, 1)],
+ [DX_CLEAR_DEPEND(doc, 1)],
+ [],
+ [DX_ENV_APPEND(GENERATE_XML, YES)],
+ [DX_ENV_APPEND(GENERATE_XML, NO)])
+
+# (Compressed) HTML help generation:
+DX_ARG_ABLE(chm, [generate doxygen compressed HTML help documentation],
+ [DX_CHECK_DEPEND(doc, 1)],
+ [DX_CLEAR_DEPEND(doc, 1)],
+ [DX_REQUIRE_PROG([DX_HHC], hhc)],
+ [DX_ENV_APPEND(HHC_PATH, $DX_HHC)
+ DX_ENV_APPEND(GENERATE_HTML, YES)
+ DX_ENV_APPEND(GENERATE_HTMLHELP, YES)],
+ [DX_ENV_APPEND(GENERATE_HTMLHELP, NO)])
+
+# Separate CHI file generation.
+DX_ARG_ABLE(chi, [generate doxygen separate compressed HTML help index file],
+ [DX_CHECK_DEPEND(chm, 1)],
+ [DX_CLEAR_DEPEND(chm, 1)],
+ [],
+ [DX_ENV_APPEND(GENERATE_CHI, YES)],
+ [DX_ENV_APPEND(GENERATE_CHI, NO)])
+
+# Plain HTML pages generation:
+DX_ARG_ABLE(html, [generate doxygen plain HTML documentation],
+ [DX_CHECK_DEPEND(doc, 1) DX_CHECK_DEPEND(chm, 0)],
+ [DX_CLEAR_DEPEND(doc, 1) DX_CLEAR_DEPEND(chm, 0)],
+ [],
+ [DX_ENV_APPEND(GENERATE_HTML, YES)],
+ [DX_TEST_FEATURE(chm) || DX_ENV_APPEND(GENERATE_HTML, NO)])
+
+# PostScript file generation:
+DX_ARG_ABLE(ps, [generate doxygen PostScript documentation],
+ [DX_CHECK_DEPEND(doc, 1)],
+ [DX_CLEAR_DEPEND(doc, 1)],
+ [DX_REQUIRE_PROG([DX_LATEX], latex)
+ DX_REQUIRE_PROG([DX_MAKEINDEX], makeindex)
+ DX_REQUIRE_PROG([DX_DVIPS], dvips)
+ DX_REQUIRE_PROG([DX_EGREP], egrep)])
+
+# PDF file generation:
+DX_ARG_ABLE(pdf, [generate doxygen PDF documentation],
+ [DX_CHECK_DEPEND(doc, 1)],
+ [DX_CLEAR_DEPEND(doc, 1)],
+ [DX_REQUIRE_PROG([DX_PDFLATEX], pdflatex)
+ DX_REQUIRE_PROG([DX_MAKEINDEX], makeindex)
+ DX_REQUIRE_PROG([DX_EGREP], egrep)])
+
+# LaTeX generation for PS and/or PDF:
+if DX_TEST_FEATURE(ps) || DX_TEST_FEATURE(pdf); then
+ DX_ENV_APPEND(GENERATE_LATEX, YES)
+else
+ DX_ENV_APPEND(GENERATE_LATEX, NO)
+fi
+
+# Paper size for PS and/or PDF:
+AC_ARG_VAR(DOXYGEN_PAPER_SIZE,
+ [a4wide (default), a4, letter, legal or executive])
+case "$DOXYGEN_PAPER_SIZE" in
+#(
+"")
+ AC_SUBST(DOXYGEN_PAPER_SIZE, "")
+;; #(
+a4wide|a4|letter|legal|executive)
+ DX_ENV_APPEND(PAPER_SIZE, $DOXYGEN_PAPER_SIZE)
+;; #(
+*)
+ AC_MSG_ERROR([unknown DOXYGEN_PAPER_SIZE='$DOXYGEN_PAPER_SIZE'])
+;;
+esac
+
+# Rules:
+AS_IF([[test $DX_FLAG_html -eq 1]],
+[[DX_SNIPPET_html="## ------------------------------- ##
+## Rules specific for HTML output. ##
+## ------------------------------- ##
+
+DX_CLEAN_HTML = \$(DX_DOCDIR)/html]dnl
+m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
+ \$(DX_DOCDIR]DX_i[)/html]])[
+
+"]],
+[[DX_SNIPPET_html=""]])
+AS_IF([[test $DX_FLAG_chi -eq 1]],
+[[DX_SNIPPET_chi="
+DX_CLEAN_CHI = \$(DX_DOCDIR)/\$(PACKAGE).chi]dnl
+m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
+ \$(DX_DOCDIR]DX_i[)/\$(PACKAGE).chi]])["]],
+[[DX_SNIPPET_chi=""]])
+AS_IF([[test $DX_FLAG_chm -eq 1]],
+[[DX_SNIPPET_chm="## ------------------------------ ##
+## Rules specific for CHM output. ##
+## ------------------------------ ##
+
+DX_CLEAN_CHM = \$(DX_DOCDIR)/chm]dnl
+m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
+ \$(DX_DOCDIR]DX_i[)/chm]])[\
+${DX_SNIPPET_chi}
+
+"]],
+[[DX_SNIPPET_chm=""]])
+AS_IF([[test $DX_FLAG_man -eq 1]],
+[[DX_SNIPPET_man="## ------------------------------ ##
+## Rules specific for MAN output. ##
+## ------------------------------ ##
+
+DX_CLEAN_MAN = \$(DX_DOCDIR)/man]dnl
+m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
+ \$(DX_DOCDIR]DX_i[)/man]])[
+
+"]],
+[[DX_SNIPPET_man=""]])
+AS_IF([[test $DX_FLAG_rtf -eq 1]],
+[[DX_SNIPPET_rtf="## ------------------------------ ##
+## Rules specific for RTF output. ##
+## ------------------------------ ##
+
+DX_CLEAN_RTF = \$(DX_DOCDIR)/rtf]dnl
+m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
+ \$(DX_DOCDIR]DX_i[)/rtf]])[
+
+"]],
+[[DX_SNIPPET_rtf=""]])
+AS_IF([[test $DX_FLAG_xml -eq 1]],
+[[DX_SNIPPET_xml="## ------------------------------ ##
+## Rules specific for XML output. ##
+## ------------------------------ ##
+
+DX_CLEAN_XML = \$(DX_DOCDIR)/xml]dnl
+m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
+ \$(DX_DOCDIR]DX_i[)/xml]])[
+
+"]],
+[[DX_SNIPPET_xml=""]])
+AS_IF([[test $DX_FLAG_ps -eq 1]],
+[[DX_SNIPPET_ps="## ----------------------------- ##
+## Rules specific for PS output. ##
+## ----------------------------- ##
+
+DX_CLEAN_PS = \$(DX_DOCDIR)/\$(PACKAGE).ps]dnl
+m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
+ \$(DX_DOCDIR]DX_i[)/\$(PACKAGE).ps]])[
+
+DX_PS_GOAL = doxygen-ps
+
+doxygen-ps: \$(DX_CLEAN_PS)
+
+]m4_foreach([DX_i], [DX_loop],
+[[\$(DX_DOCDIR]DX_i[)/\$(PACKAGE).ps: \$(DX_DOCDIR]DX_i[)/\$(PACKAGE).tag
+ \$(DX_V_LATEX)cd \$(DX_DOCDIR]DX_i[)/latex; \\
+ rm -f *.aux *.toc *.idx *.ind *.ilg *.log *.out; \\
+ \$(DX_LATEX) refman.tex; \\
+ \$(DX_MAKEINDEX) refman.idx; \\
+ \$(DX_LATEX) refman.tex; \\
+ countdown=5; \\
+ while \$(DX_EGREP) 'Rerun (LaTeX|to get cross-references right)' \\
+ refman.log > /dev/null 2>&1 \\
+ && test \$\$countdown -gt 0; do \\
+ \$(DX_LATEX) refman.tex; \\
+ countdown=\`expr \$\$countdown - 1\`; \\
+ done; \\
+ \$(DX_DVIPS) -o ../\$(PACKAGE).ps refman.dvi
+
+]])["]],
+[[DX_SNIPPET_ps=""]])
+AS_IF([[test $DX_FLAG_pdf -eq 1]],
+[[DX_SNIPPET_pdf="## ------------------------------ ##
+## Rules specific for PDF output. ##
+## ------------------------------ ##
+
+DX_CLEAN_PDF = \$(DX_DOCDIR)/\$(PACKAGE).pdf]dnl
+m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
+ \$(DX_DOCDIR]DX_i[)/\$(PACKAGE).pdf]])[
+
+DX_PDF_GOAL = doxygen-pdf
+
+doxygen-pdf: \$(DX_CLEAN_PDF)
+
+]m4_foreach([DX_i], [DX_loop],
+[[\$(DX_DOCDIR]DX_i[)/\$(PACKAGE).pdf: \$(DX_DOCDIR]DX_i[)/\$(PACKAGE).tag
+ \$(DX_V_LATEX)cd \$(DX_DOCDIR]DX_i[)/latex; \\
+ rm -f *.aux *.toc *.idx *.ind *.ilg *.log *.out; \\
+ \$(DX_PDFLATEX) refman.tex; \\
+ \$(DX_MAKEINDEX) refman.idx; \\
+ \$(DX_PDFLATEX) refman.tex; \\
+ countdown=5; \\
+ while \$(DX_EGREP) 'Rerun (LaTeX|to get cross-references right)' \\
+ refman.log > /dev/null 2>&1 \\
+ && test \$\$countdown -gt 0; do \\
+ \$(DX_PDFLATEX) refman.tex; \\
+ countdown=\`expr \$\$countdown - 1\`; \\
+ done; \\
+ mv refman.pdf ../\$(PACKAGE).pdf
+
+]])["]],
+[[DX_SNIPPET_pdf=""]])
+AS_IF([[test $DX_FLAG_ps -eq 1 -o $DX_FLAG_pdf -eq 1]],
+[[DX_SNIPPET_latex="## ------------------------------------------------- ##
+## Rules specific for LaTeX (shared for PS and PDF). ##
+## ------------------------------------------------- ##
+
+DX_V_LATEX = \$(_DX_v_LATEX_\$(V))
+_DX_v_LATEX_ = \$(_DX_v_LATEX_\$(AM_DEFAULT_VERBOSITY))
+_DX_v_LATEX_0 = @echo \" LATEX \" \$][@;
+
+DX_CLEAN_LATEX = \$(DX_DOCDIR)/latex]dnl
+m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
+ \$(DX_DOCDIR]DX_i[)/latex]])[
+
+"]],
+[[DX_SNIPPET_latex=""]])
+
+AS_IF([[test $DX_FLAG_doc -eq 1]],
+[[DX_SNIPPET_doc="## --------------------------------- ##
+## Format-independent Doxygen rules. ##
+## --------------------------------- ##
+
+${DX_SNIPPET_html}\
+${DX_SNIPPET_chm}\
+${DX_SNIPPET_man}\
+${DX_SNIPPET_rtf}\
+${DX_SNIPPET_xml}\
+${DX_SNIPPET_ps}\
+${DX_SNIPPET_pdf}\
+${DX_SNIPPET_latex}\
+DX_V_DXGEN = \$(_DX_v_DXGEN_\$(V))
+_DX_v_DXGEN_ = \$(_DX_v_DXGEN_\$(AM_DEFAULT_VERBOSITY))
+_DX_v_DXGEN_0 = @echo \" DXGEN \" \$<;
+
+.PHONY: doxygen-run doxygen-doc \$(DX_PS_GOAL) \$(DX_PDF_GOAL)
+
+.INTERMEDIATE: doxygen-run \$(DX_PS_GOAL) \$(DX_PDF_GOAL)
+
+doxygen-run:]m4_foreach([DX_i], [DX_loop],
+ [[ \$(DX_DOCDIR]DX_i[)/\$(PACKAGE).tag]])[
+
+doxygen-doc: doxygen-run \$(DX_PS_GOAL) \$(DX_PDF_GOAL)
+
+]m4_foreach([DX_i], [DX_loop],
+[[\$(DX_DOCDIR]DX_i[)/\$(PACKAGE).tag: \$(DX_CONFIG]DX_i[) \$(pkginclude_HEADERS)
+ \$(A""M_V_at)rm -rf \$(DX_DOCDIR]DX_i[)
+ \$(DX_V_DXGEN)\$(DX_ENV) DOCDIR=\$(DX_DOCDIR]DX_i[) \$(DX_DOXYGEN) \$(DX_CONFIG]DX_i[)
+ \$(A""M_V_at)echo Timestamp >\$][@
+
+]])dnl
+[DX_CLEANFILES = \\]
+m4_foreach([DX_i], [DX_loop],
+[[ \$(DX_DOCDIR]DX_i[)/doxygen_sqlite3.db \\
+ \$(DX_DOCDIR]DX_i[)/\$(PACKAGE).tag \\
+]])dnl
+[ -r \\
+ \$(DX_CLEAN_HTML) \\
+ \$(DX_CLEAN_CHM) \\
+ \$(DX_CLEAN_CHI) \\
+ \$(DX_CLEAN_MAN) \\
+ \$(DX_CLEAN_RTF) \\
+ \$(DX_CLEAN_XML) \\
+ \$(DX_CLEAN_PS) \\
+ \$(DX_CLEAN_PDF) \\
+ \$(DX_CLEAN_LATEX)"]],
+[[DX_SNIPPET_doc=""]])
+AC_SUBST([DX_RULES],
+["${DX_SNIPPET_doc}"])dnl
+AM_SUBST_NOTMAKE([DX_RULES])
+
+#For debugging:
+#echo DX_FLAG_doc=$DX_FLAG_doc
+#echo DX_FLAG_dot=$DX_FLAG_dot
+#echo DX_FLAG_man=$DX_FLAG_man
+#echo DX_FLAG_html=$DX_FLAG_html
+#echo DX_FLAG_chm=$DX_FLAG_chm
+#echo DX_FLAG_chi=$DX_FLAG_chi
+#echo DX_FLAG_rtf=$DX_FLAG_rtf
+#echo DX_FLAG_xml=$DX_FLAG_xml
+#echo DX_FLAG_pdf=$DX_FLAG_pdf
+#echo DX_FLAG_ps=$DX_FLAG_ps
+#echo DX_ENV=$DX_ENV
+])
projects / lttng-tools.git / commitdiff
