From: Jérémie Galarneau Date: Tue, 23 Apr 2024 20:46:47 +0000 (-0400) Subject: Import CStringView from the Babeltrace tree X-Git-Url: https://git.liburcu.org/?p=lttng-tools.git;a=commitdiff_plain;h=HEAD;hp=77c8b540e0389c630764b6298ec71f81ed03c72d Import CStringView from the Babeltrace tree The class is imported as of 1dcaf4b74 in the babeltrace tree. It is renamed and reformated to fit the LTTng-tools conventions. No changes in behaviour are intended. Signed-off-by: Jérémie Galarneau Change-Id: I8acc3833c52c4ac23a91af87157aade0b4bbb7c1 --- diff --git a/.clang-format b/.clang-format index 28ea69873..8fcee64f8 100644 --- a/.clang-format +++ b/.clang-format @@ -35,7 +35,6 @@ BraceWrapping: SplitEmptyFunction: true BreakBeforeBinaryOperators: None BreakBeforeTernaryOperators: false -BreakConstructorInitializers: AfterColon BreakStringLiterals: false ColumnLimit: 100 ConstructorInitializerAllOnOneLineOrOnePerLine: true diff --git a/.gitignore b/.gitignore index 4c5a4e5e9..b0884eb16 100644 --- a/.gitignore +++ b/.gitignore @@ -47,7 +47,6 @@ TAGS /.clangd/ compile_commands.json *_flymake* -/.vscode/* # m4 macros not automatically generated /m4/libtool.m4 diff --git a/.vscode/build.sh b/.vscode/build.sh new file mode 100755 index 000000000..9a4e3625a --- /dev/null +++ b/.vscode/build.sh @@ -0,0 +1,33 @@ +#!/usr/bin/env bash +# Copyright (C) 2024 Jérémie Galarneau +# +# SPDX-License-Identifier: LGPL-2.1-only +# + +source_dir="$1" + +# Run make quietly to check if a Makefile exists +make_output=$(make -C "$source_dir" -q 2>&1) +make_exit_status=$? + +# Check the return status of make -q +if [ $make_exit_status -eq 2 ]; then + # It seems the Makefiles don't exist. Most likely the user forgot to + # setup their tree. + echo "$make_output" + echo -e "\033[33mMake couldn't find a Makefile: did you run ./bootstrap and ./configure ?\033[0m" + exit 1 +fi + +# Check if compile_commands.json does not exist in the source directory and if bear is installed +if [ ! -f "$source_dir/compile_commands.json" ] && which bear >/dev/null 2>&1; then + # Bear is installed and compile_commands.json is not present + # Perform a make clean since compile_commands.json is missing and bear is installed + make -C "$source_dir" clean + + # Prefix bear to the make command + command_prefix="bear -- " +fi + +# Run make with or without bear prefix, depending on the condition above +eval "${command_prefix}"make -C "$source_dir" -j "$(nproc)" diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 000000000..4541842e1 --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,76 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Debug LTTng Client", + "type": "cppdbg", + "request": "launch", + "program": "${workspaceFolder}/src/bin/lttng/.libs/lttng", + // Replace with your args + "args": [ + "help" + ], + "stopAtEntry": false, + "cwd": "${workspaceFolder}", + "environment": [], + "externalConsole": false, + "MIMode": "gdb", + "miDebuggerPath": "${workspaceFolder}/.vscode/libtool_gdb_wrapper.sh", + "setupCommands": [ + { + "description": "Enable pretty-printing for gdb", + "text": "-enable-pretty-printing", + "ignoreFailures": true + } + ], + "preLaunchTask": "Build LTTng-tools" + }, + { + "name": "Debug LTTng Session Daemon", + "type": "cppdbg", + "request": "launch", + "program": "${workspaceFolder}/src/bin/lttng-sessiond/.libs/lttng-sessiond", + "args": [], + "stopAtEntry": false, + "cwd": "${workspaceFolder}", + // The session daemon fails to launch if it can't find the session schema description + "environment": [ + { + "name": "LTTNG_SESSION_CONFIG_XSD_PATH", + "value": "${workspaceFolder}/src/common/" + } + ], + "externalConsole": false, + "MIMode": "gdb", + "miDebuggerPath": "${workspaceFolder}/.vscode/libtool_gdb_wrapper.sh", + "setupCommands": [ + { + "description": "Enable pretty-printing for gdb", + "text": "-enable-pretty-printing", + "ignoreFailures": true + } + ], + "preLaunchTask": "Build LTTng-tools" + }, + { + "name": "Debug LTTng Relay Daemon", + "type": "cppdbg", + "request": "launch", + "program": "${workspaceFolder}/src/bin/lttng-relayd/lttng-relayd", + "args": [], + "cwd": "${workspaceFolder}", + "environment": [], + "externalConsole": false, + "MIMode": "gdb", + "miDebuggerPath": "${workspaceFolder}/.vscode/libtool_gdb_wrapper.sh", + "setupCommands": [ + { + "description": "Enable pretty-printing for gdb", + "text": "-enable-pretty-printing", + "ignoreFailures": true + } + ], + "preLaunchTask": "Build LTTng-tools" + }, + ] +} \ No newline at end of file diff --git a/.vscode/libtool_gdb_wrapper.sh b/.vscode/libtool_gdb_wrapper.sh new file mode 100755 index 000000000..0f60c832d --- /dev/null +++ b/.vscode/libtool_gdb_wrapper.sh @@ -0,0 +1,9 @@ +#!/usr/bin/env sh +# Copyright (C) 2024 Jérémie Galarneau +# +# SPDX-License-Identifier: LGPL-2.1-only +# +# Wrapper script to setup the environment before invoking gdb +# on the in-tree binaries (under `.libs`) + +libtool --mode=execute gdb "$@" diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 000000000..9f28bc573 --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,21 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "type": "shell", + "label": "Build LTTng-tools", + // Assumes you ran ./bootstrap and ./configure with your preferred options + "command": "${workspaceFolder}/.vscode/build.sh ${workspaceFolder}", + "options": { + "cwd": "${workspaceFolder}" + }, + "problemMatcher": [ + "$gcc" + ], + "group": { + "kind": "build", + "isDefault": true + } + } + ] +} \ No newline at end of file diff --git a/README.adoc b/README.adoc index 6ec60856a..676467aa4 100644 --- a/README.adoc +++ b/README.adoc @@ -221,6 +221,21 @@ As there's no official {lib} Python bindings yet, see link:doc/python-howto.txt[`doc/python-howto.txt`] to understand how to use them. +== Supported versions + +The LTTng project supports the last two released stable versions +(e.g. stable-2.13 and stable-2.12). + +Fixes are backported from the master branch to the last stable version unless +those fixes would break the ABI or API. Those fixes may be backported to the +second-last stable version, depending on complexity and ABI/API compatibility. + +Security fixes are backported from the master branch to both of the last stable +version and the second-last stable version. + +New features are integrated into the master branch and not backported to the +last stable branch. + == Community Mailing list:: diff --git a/configure.ac b/configure.ac index b479c7350..0a4d726d7 100644 --- a/configure.ac +++ b/configure.ac @@ -157,6 +157,7 @@ AS_IF([test "x$enable_Werror" = "xyes"], [ AC_PROG_GREP AC_PROG_MAKE_SET AC_PROG_SED +AC_PROG_MKDIR_P AC_PATH_PROG([report_fold], [fold]) LT_INIT @@ -755,6 +756,31 @@ if test "x$test_java_agent_jul" = "xyes" || test "x$test_java_agent_log4j" = "xy 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, @@ -1203,6 +1229,9 @@ AC_SUBST(lttnglibexecdir) 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 @@ -1465,6 +1494,9 @@ m4_popdef([build_man_pages_msg]) 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`" diff --git a/doc/Makefile.am b/doc/Makefile.am index 121db3b89..61d9be6be 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -15,3 +15,7 @@ EXTRA_DIST = quickstart.txt streaming-howto.txt python-howto.txt \ 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 diff --git a/doc/api/.gitignore b/doc/api/.gitignore new file mode 100644 index 000000000..fa4a4101a --- /dev/null +++ b/doc/api/.gitignore @@ -0,0 +1,3 @@ +output/ +Doxyfile +README.html diff --git a/doc/api/Makefile.am b/doc/api/Makefile.am new file mode 100644 index 000000000..b5e85ac44 --- /dev/null +++ b/doc/api/Makefile.am @@ -0,0 +1,4 @@ +# SPDX-License-Identifier: GPL-2.0-only + +SUBDIRS = liblttng-ctl +EXTRA_DIST = README.adoc diff --git a/doc/api/README.adoc b/doc/api/README.adoc new file mode 100644 index 000000000..d62782b14 --- /dev/null +++ b/doc/api/README.adoc @@ -0,0 +1,390 @@ +// Render with Asciidoctor + += LTTng-tools C API documentation guidelines +Philippe Proulx +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 `` and + ``: ++ +-- +---- +@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 + On success, \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 `` and ``. Likewise, you can use strong emphasis +when needed with the `\b` command (one word) or with `` and +``. 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. diff --git a/doc/api/liblttng-ctl/Doxyfile.in b/doc/api/liblttng-ctl/Doxyfile.in new file mode 100644 index 000000000..4e78ae79f --- /dev/null +++ b/doc/api/liblttng-ctl/Doxyfile.in @@ -0,0 +1,218 @@ +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}="\1" +ALIASES += lt_var{1}="\1" +ALIASES += lt_dt_opt="Optional:" +ALIASES += lt_man_nl{2}="\1(\2)" +ALIASES += lt_man{2}="\lt_man_nl{\1,\2}" +ALIASES += lt_man_gen{2}="\lt_man_nl{\1,\2}" +ALIASES += lt_voidp="void *" + +# 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="net://127.0.0.1:@DEFAULT_NETWORK_CONTROL_PORT@" +ALIASES += lt_def_net_data_url="net://127.0.0.1:@DEFAULT_NETWORK_DATA_PORT@" +ALIASES += lt_def_net_url="net://127.0.0.1:@DEFAULT_NETWORK_CONTROL_PORT@:@DEFAULT_NETWORK_DATA_PORT@" + +# 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 diff --git a/doc/api/liblttng-ctl/DoxygenLayout.xml b/doc/api/liblttng-ctl/DoxygenLayout.xml new file mode 100644 index 000000000..6f37926d7 --- /dev/null +++ b/doc/api/liblttng-ctl/DoxygenLayout.xml @@ -0,0 +1,46 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/api/liblttng-ctl/Makefile.am b/doc/api/liblttng-ctl/Makefile.am new file mode 100644 index 000000000..4450a45d3 --- /dev/null +++ b/doc/api/liblttng-ctl/Makefile.am @@ -0,0 +1,19 @@ +# 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 diff --git a/doc/api/liblttng-ctl/dox/groups.dox b/doc/api/liblttng-ctl/dox/groups.dox new file mode 100644 index 000000000..f10de45dd --- /dev/null +++ b/doc/api/liblttng-ctl/dox/groups.dox @@ -0,0 +1,2353 @@ +/*! +@mainpage Bonjour! + +Welcome to the \lt_api (liblttng-ctl) documentation! + +The +Linux Trace Toolkit: next generation +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 LTTng tracing, but +also to +\ref api_trigger "receive notifications when specific events occur". + +

Plumbing

+ +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 +Components of LTTng +section of the LTTng Documentation to learn more. + +

Contents

+ +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 + recording sessions. + + 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 + triggers. + + 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 event rule matches\endlink + condition and the + \link #LTTNG_ACTION_TYPE_NOTIFY notify\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 API reference for the complete table +of contents. + +

Build with liblttng-ctl

+ +To build an application with liblttng-ctl: + +
+
Header file +
+ Include %lttng/lttng.h: + + @code + #include + @endcode + + With + pkg-config, + get the required C flags with: + + @code{.unparsed} + $ pkg-config --cflags lttng-ctl + @endcode + +
Linking +
+ Link your application with liblttng-ctl: + + @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 +
+ +@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() + +

\anchor api-gen-sessiond-conn Session daemon connection

+ +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: + +
+
\lt_var{U} is \c root +
Connect to the root session daemon. + +
\lt_var{U} is not \c root +
+
+
If \lt_var{U} is part of the current liblttng-ctl Unix tracing group +
+ 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}. + +
If \lt_var{U} is not part of the tracing group +
+ Connect to the session daemon of \lt_var{U}. +
+
+ +The Unix tracing group of the root session daemon is one of: + +
+
+ With the \--group=GROUP option of the root + session daemon +
+ Exactly GROUP. + + In that case, you must call lttng_set_tracing_group(), passing + exactly GROUP, \em before you call a + liblttng-ctl function which needs to connect to a session daemon. + +
+ Without the \--group option of the root + session daemon +
+ Exactly \c tracing (also the default Unix tracing group of + liblttng-ctl, therefore you don't need to call + lttng_set_tracing_group()). +
+ +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 recording session 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 +ATM +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 RECORDING SESSION section of \lt_man{lttng-concepts,7}. + +

Operations

+ +The recording session operations are: + + + + + + + + + + + + + + + + +
Operation + Means +
Creation + + -# 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} +
Destruction + + -# 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. + + -# If you have a destruction handle from + step 1: + + -# 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} +
Basic property access + + 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() +
\lt_obj_c_domain access + + -# 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 free(). +
\lt_obj_c_channel access + + -# 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 free(). +
Activity control + + 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. +
Listing + + -# 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 free(). + + @sa \lt_man{lttng-list,1} +
Process attribute inclusion set access + See \ref api_pais +
Clearing + See \ref api_session_clear +
Snapshot recording + + See \ref api_session_snapshot + + The #LTTNG_ACTION_TYPE_SNAPSHOT_SESSION trigger action can also + take a recording session snapshot. +
Rotation + + See \ref api_session_rotation + + The #LTTNG_ACTION_TYPE_ROTATE_SESSION trigger action can also + rotate a recording session. +
Saving and loading + See \ref api_session_save_load +
Trace data regeneration + + See: + + - lttng_regenerate_metadata() + - lttng_regenerate_statedump() + + @sa \lt_man{lttng-regenerate,1} +
+ +

\anchor api-session-modes Recording session modes

+ +LTTng offers four recording session modes: + + + + + + + +
Mode + Description + Descriptor creation function(s) +
\anchor api-session-local-mode Local + + Write the trace data to the local file system, or do not write any + trace data. + + - lttng_session_descriptor_create() + - lttng_session_descriptor_local_create() +
\anchor api-session-net-mode Network streaming + + Send the trace data over the network to a listening relay daemon + (see \lt_man{lttng-relayd,8}). + lttng_session_descriptor_network_create() +
\anchor api-session-snapshot-mode Snapshot + + 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"\". + + - lttng_session_descriptor_snapshot_create() + - lttng_session_descriptor_snapshot_local_create() + - lttng_session_descriptor_snapshot_network_create() +
\anchor api-session-live-mode Live + + Send the trace data over the network to a listening relay daemon + for live reading. + + An LTTng live reader (for example, + Babeltrace 2) can + connect to the same relay daemon to receive trace data while the + recording session is active. + + lttng_session_descriptor_live_network_create() +
+ +@sa The Recording session modes section of +\lt_man{lttng-concepts,7}. + +

\anchor api-session-url Output URL format

+ +Some functions of the \lt_api require an output +URL. + +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: + + + + + + +
Type + Description + Format +
\anchor api-session-local-url Local + + 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() + + file://TRACEDIR + +
+
TRACEDIR +
+ Absolute path to the directory containing the trace data on + the local file system. +
+
\anchor api-session-one-port-url Remote: single port + + 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() + + PROTO://HOST[:PORT][/TRACEDIR] + +
+
PROTO +
+ Network protocol, amongst: + +
+
\c net +
+ TCP over IPv4. + +
\c net6 +
+ TCP over IPv6. + +
\c tcp +
+ Same as net. + +
\c tcp6 +
+ Same as net6. +
+ +
HOST +
+ Hostname or IP address. + + An IPv6 address must be enclosed in square brackets ([ + and ]); see + RFC 2732. + +
PORT +
+ 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. + +
TRACEDIR +
+ 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 Output directory + section of \lt_man{lttng-relayd,8}). +
+
\anchor api-session-two-port-url Remote: control and data ports + + 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() + + PROTO://HOST:CTRLPORT:DATAPORT[/TRACEDIR] + +
+
PROTO +
+ Network protocol, amongst: + +
+
\c net +
+ TCP over IPv4. + +
\c net6 +
+ TCP over IPv6. + +
\c tcp +
+ Same as net. + +
\c tcp6 +
+ Same as net6. +
+ +
HOST +
+ Hostname or IP address. + + An IPv6 address must be enclosed in square brackets ([ + and ]); see + RFC 2732. + +
CTRLPORT +
+ Control TCP port. + +
DATAPORT +
+ Trace data TCP port. + +
TRACEDIR +
+ 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 \--output option of + \lt_man{lttng-relayd,8}). +
+
+ +@defgroup api_session_descr Recording session descriptor API +@ingroup api_session + +A recording session descriptor 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": + +
+
\ref api-session-local-mode "Local mode" +
+ One of: + + - lttng_session_descriptor_create() + - lttng_session_descriptor_local_create() + +
\ref api-session-net-mode "Network streaming mode" +
+ lttng_session_descriptor_network_create() + +
\ref api-session-snapshot-mode "Snapshot mode" +
+ One of: + + - lttng_session_descriptor_snapshot_create() + - lttng_session_descriptor_snapshot_local_create() + - lttng_session_descriptor_snapshot_network_create() + +
\ref api-session-live-mode "Live mode" +
+ lttng_session_descriptor_live_network_create() +
+ +-# 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 recording session destruction handle +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. + +-# If LTTng performed at least one + \ref api_session_rotation "rotation" of the destroyed recording + session, 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 + +

\anchor api-channel-domain Tracing domain

+ +A tracing domain identifies a type of LTTng +tracer. + +A tracing domain has its own properties and features. + +There are currently five available tracing domains: + + + + + + + + +
Domain name + Type enumerator +
Linux kernel + #LTTNG_DOMAIN_KERNEL +
User space + #LTTNG_DOMAIN_UST +
java.util.logging (JUL) + #LTTNG_DOMAIN_JUL +
Apache log4j + #LTTNG_DOMAIN_LOG4J +
Python logging + #LTTNG_DOMAIN_PYTHON +
+ +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 TRACING DOMAIN section of \lt_man{lttng-concepts,7}. + +

\anchor api-channel-channel Channel

+ +A channel is an object which is responsible +for a set of ring buffers. + +Each ring buffer is divided into multiple sub-buffers. 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 java.util.logging\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. + +

Operations

+ +The channel operations are: + + + + + + + + + + +
Operation + Means +
Creation + + -# 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} +
Basic property access + + See the \ref api-channel-channel-props "property table" below. +
\lt_obj_c_rer access + + -# 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 free(). +
Event record context field adding + + -# 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} +
Enabling + + Use lttng_enable_channel(). + + @sa \lt_man{lttng-enable-channel,1} +
Disabling + + Use lttng_disable_channel(). + + @sa \lt_man{lttng-disable-channel,1} +
Statistics + + See: + + - lttng_channel_get_discarded_event_count() + - lttng_channel_get_lost_packet_count() +
+ +

\anchor api-channel-channel-props Properties

+ +The properties of a channel are: + + + + + + + + + + + + + + + +
Property name + Description + Access +
Buffering scheme + + See \ref api-channel-buf-scheme "Buffering scheme". + + The lttng_domain::buf_type member for the containing tracing + domain. + + All the channels of a given tracing domain share the same + buffering scheme. +
Event record loss mode + + See \ref api-channel-er-loss-mode "Event record loss mode". + + The lttng_channel_attr::overwrite member. +
Sub-buffer size + + See \ref api-channel-sub-buf-size-count "Sub-buffer size and count". + + The lttng_channel_attr::subbuf_size member. +
Sub-buffer count + + See \ref api-channel-sub-buf-size-count "Sub-buffer size and count". + + The lttng_channel_attr::num_subbuf member. +
Maximum trace file size + + See \ref api-channel-max-trace-file-size-count "Maximum trace file size and count". + + The lttng_channel_attr::tracefile_size member. +
Maximum trace file count + + See \ref api-channel-max-trace-file-size-count "Maximum trace file size and count". + + The lttng_channel_attr::tracefile_count member. +
Read timer period + + See \ref api-channel-read-timer "Read timer". + + The lttng_channel_attr::read_timer_interval member. +
Switch timer period + + See \ref api-channel-switch-timer "Switch timer". + + The lttng_channel_attr::switch_timer_interval member. +
Live timer period + + See \ref api-channel-live-timer "Live timer". + + 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. +
Monitor timer period + + See \ref api-channel-monitor-timer "Monitor timer". + + - lttng_channel_get_monitor_timer_interval() + - lttng_channel_set_monitor_timer_interval() +
Output type (Linux kernel channel) + + Whether to use mmap() or splice(). + + The lttng_channel_attr::output member. +
\anchor api-channel-blocking-timeout Blocking timeout (user space channel) + + 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. + + - lttng_channel_get_blocking_timeout() + - lttng_channel_set_blocking_timeout() +
+ +All the properties above are immutable once a channel exists. + +@sa The CHANNEL AND RING BUFFER section of +\lt_man{lttng-concepts,7}. + +

\anchor api-channel-buf-scheme Buffering scheme

+ +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 buffering scheme 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: + +
+
+ \anchor api-channel-per-user-buf + \link #LTTNG_BUFFER_PER_UID Per-user buffering\endlink +
+ Allocate one set of ring buffers (one per CPU) shared by all the + instrumented processes of: + +
+
If \lt_var{U} is root +
+ Each Unix user. + + @image html per-user-buffering-root.png + +
Otherwise +
+ \lt_var{U} + + @image html per-user-buffering.png +
+ +
+ \anchor api-channel-per-proc-buf + \link #LTTNG_BUFFER_PER_PID Per-process buffering\endlink +
+ Allocate one set of ring buffers (one per CPU) for each + instrumented process of: + +
+
If \lt_var{U} is root +
+ All Unix users. + + @image html per-process-buffering-root.png + +
Otherwise +
+ \lt_var{U} + + @image html per-process-buffering.png +
+
+ +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 Buffering scheme section of \lt_man{lttng-concepts,7}. + +

\anchor api-channel-er-loss-mode Event record loss mode

+ +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 non-blocking +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 blocking mode: 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 event record loss mode of the channel +determines what to do. The available event record loss modes are: + +
+
\anchor api-channel-discard-mode Discard mode +
+ 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(). + +
\anchor api-channel-overwrite-mode Overwrite mode +
+ Clear the sub-buffer containing the oldest event records and start + writing the newest event records there. + + This mode is sometimes called flight recorder mode because + it's similar to a + flight recorder: + 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. +
+ +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 whole +sub-buffer 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 Event record loss mode section of +\lt_man{lttng-concepts,7}. + +

\anchor api-channel-sub-buf-size-count Sub-buffer size and count

+ +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: + +
+
High event throughput +
+ 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. + +
Low event throughput +
+ 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. + +
Low memory system +
+ 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. +
+ +Note that LTTng uses CTF 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: + +
+
Two sub-buffers of 4 MiB each +
+ 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. + +
Eight sub-buffers of 1 MiB each +
+ 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. +
+ +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 Sub-buffer size and count section of +\lt_man{lttng-concepts,7}. + +

\anchor api-channel-max-trace-file-size-count Maximum trace file size and count

+ +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 unlimited +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 trace file rotation. + +@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 Maximum trace file size and count section of +\lt_man{lttng-concepts,7}. + +

\anchor api-channel-timers Timers

+ +Each channel can have up to four optional +timers: + +
+
\anchor api-channel-switch-timer Switch timer +
+ 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. + +
\anchor api-channel-live-timer Live timer +
+ 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. + +
\anchor api-channel-read-timer Read timer +
+ 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(). + +
\anchor api-channel-monitor-timer Monitor timer +
+ 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(). +
+ +@sa The Timers section of \lt_man{lttng-concepts,7}. + +@defgroup api_rer Recording event rule API +@ingroup api_channel + +

Concepts

+ +An instrumentation point is a point, within a piece of +software, which, when executed, creates an LTTng event. +See \ref api_inst_pt to learn how to list the available instrumentation +points. + +An event rule is a set of \ref api-rer-conds "conditions" to +match a set of events. + +A recording event rule is a specific type of +event rule of which the action is to serialize and write the matched +event as an event record 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 match \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 +once. + +@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. + +

Operations

+ +The recording event rule operations are: + + + + + + + +
Operation + Means +
Creation + + -# 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} +
Property access + + 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". +
Enabling + + 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} +
Disabling + + Use lttng_disable_event() or lttng_disable_event_ext(). + + @sa \lt_man{lttng-disable-event,1} +
+ +

\anchor api-rer-conds Recording event rule conditions

+ +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: + +
+
Explicit conditions +
+ 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). + + + + + + + +
Name + Description +
+ \anchor api-rer-conds-inst-pt-type + \ref api-rer-conds-inst-pt-type "Instrumentation point type" + + \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}: + +
+
#LTTNG_DOMAIN_KERNEL +
+ Depending on + \link lttng_event::type event_rule.type\endlink: + +
+
#LTTNG_EVENT_TRACEPOINT +
+ 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() + +
#LTTNG_EVENT_SYSCALL +
+ The entry and exit of a Linux kernel system call. + + @sa lttng_list_syscalls() + +
#LTTNG_EVENT_PROBE +
+ A Linux + kprobe, + that is, a single probe dynamically placed in the + compiled kernel code. + + \link lttng_event::lttng_event_attr_u::probe + event_rule.attr.probe\endlink + indicates the kprobe location, + while \link lttng_event::name + event_rule.name\endlink + is the name of the created kprobe instrumentation + point (future event name). + + The payload of a Linux kprobe event is empty. + +
#LTTNG_EVENT_FUNCTION +
+ A Linux + kretprobe, + 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 + event_rule.attr.probe\endlink + indicates the kretprobe location, + while \link lttng_event::name + event_rule.name\endlink + is the name of the created kretprobe instrumentation + point (future event name). + + The payload of a Linux kretprobe event is empty. + +
#LTTNG_EVENT_USERSPACE_PROBE +
+ A Linux + uprobe, + 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 event_rule.name\endlink + is the name of the created uprobe instrumentation + point (future event name). + + The payload of a Linux uprobe event is empty. +
+ +
#LTTNG_DOMAIN_UST +
+ 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 event_rule.type\endlink + must be #LTTNG_EVENT_TRACEPOINT. + + @sa lttng_list_tracepoints() + +
#LTTNG_DOMAIN_JUL +
#LTTNG_DOMAIN_LOG4J +
#LTTNG_DOMAIN_PYTHON +
+ A Java/Python logging statement. + + \link lttng_event::type event_rule.type\endlink + must be #LTTNG_EVENT_TRACEPOINT. + + @sa lttng_list_tracepoints() +
+
+ \anchor api-rer-conds-event-name + \ref api-rer-conds-event-name "Event name" + + 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 event_rule.name\endlink + matches, depending on + \link lttng_event::type event_rule.type\endlink + (see \ref api-rer-conds-inst-pt-type "Instrumentation point type" + above): + +
+
#LTTNG_EVENT_TRACEPOINT +
+ 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 + PROVIDER:NAME, where + PROVIDER is the tracepoint + provider name and NAME is the + tracepoint name. + +
#LTTNG_EVENT_SYSCALL +
+ The name of the system call, without any + sys_ prefix, from which LTTng + creates \lt_var{E}. +
+ + @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 event_rule.type\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 event_rule.name\endlink + and the event name exclusion patterns of + \c event_rule are globbing patterns: the + * character means "match anything". To match a + literal * character, use \\*. +
+ \anchor api-rer-conds-ll + \ref api-rer-conds-ll "Instrumentation point log level" + + An event \lt_var{E} satisfies the instrumentation point + log level condition of \lt_var{ER} if, depending on + \link lttng_event::loglevel_type event_rule.loglevel_type\endlink, + the log level of the LTTng user space tracepoint or + logging statement from which LTTng creates \lt_var{E} + is: + +
+
#LTTNG_EVENT_LOGLEVEL_ALL +
+ Anything (the condition is always satisfied). + +
#LTTNG_EVENT_LOGLEVEL_RANGE +
+ At least as severe as + \link lttng_event::loglevel event_rule.loglevel\endlink. + +
#LTTNG_EVENT_LOGLEVEL_SINGLE +
+ Exactly + \link lttng_event::loglevel event_rule.loglevel\endlink. +
+ + 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. +
+ \anchor api-rer-conds-filter + \ref api-rer-conds-filter "Event payload and context filter" + + 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 event_rule.type\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 NAME expression identifies an event + payload field named NAME (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: my_field, target_cpu, + seq[7], msg.user[1].data[2][17]. + + - A $ctx.TYPE expression identifies the + statically-known context field having the type + TYPE (a C identifier). + + When a field expression doesn't exist, \lt_var{EXPR} is \b + false. + + Examples: $ctx.prio, + $ctx.preemptible, + $ctx.perf:cpu:stalled-cycles-frontend. + + - A $app.PROVIDER:TYPE + expression identifies the application-specific context field + having the type TYPE (a + C identifier) from the provider + PROVIDER (a C identifier). + + When a field expression doesn't exist, \lt_var{EXPR} is \b + false. + + Example: $app.server:cur_user. + + - Compare strings, either string fields or string literals + (double-quoted), with the == and + != operators. + + When comparing to a string literal, the * + character means "match anything". To match a literal + * character, use \\*. + + Examples: my_field == "user34", + my_field == my_other_field, + my_field == "192.168.*". + + - The + precedence table + of the operators which are supported in + \lt_var{EXPR} is as follows. In this table, the highest + precedence is 1: + + + + + + + + + + + + + + + + + + + + +
Precedence + Operator + Description + Associativity +
1 + - + Unary minus + Right-to-left +
1 + + + Unary plus + Right-to-left +
1 + ! + Logical NOT + Right-to-left +
1 + ~ + Bitwise NOT + Right-to-left +
2 + << + Bitwise left shift + Left-to-right +
2 + >> + Bitwise right shift + Left-to-right +
3 + & + Bitwise AND + Left-to-right +
4 + ^ + Bitwise XOR + Left-to-right +
5 + | + Bitwise OR + Left-to-right +
6 + < + Less than + Left-to-right +
6 + <= + Less than or equal to + Left-to-right +
6 + > + Greater than + Left-to-right +
6 + >= + Greater than or equal to + Left-to-right +
7 + == + Equal to + Left-to-right +
7 + != + Not equal to + Left-to-right +
8 + && + Logical AND + Left-to-right +
9 + || + Logical OR + Left-to-right +
+ + Parentheses are supported to bypass the default order. + + @attention + Unlike the C language, the bitwise AND and OR + operators (& and |) in + \lt_var{EXPR} take precedence over relational + operators (<<, <=, + >, >=, ==, + and !=). This means the expression + 2 & 2 == 2 + 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 + (<< and >>) 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 $ctx.pid. + 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 +
+ +
Implicit conditions +
+ - \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. +
+ +

\anchor api-rer-er-name Event record name

+ +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}: + + + + + + + + + + +
Tracing domain + Instrumentation point type + Event record name +
#LTTNG_DOMAIN_KERNEL or #LTTNG_DOMAIN_UST + #LTTNG_EVENT_TRACEPOINT + + 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 + PROVIDER:NAME, where + PROVIDER is the tracepoint provider name and + NAME is the tracepoint name. +
#LTTNG_DOMAIN_JUL + #LTTNG_EVENT_TRACEPOINT + + lttng_jul:event + + Such an event record has a string field logger_name + which contains the name of the java.util.logging + logger from which LTTng creates \lt_var{E}. +
#LTTNG_DOMAIN_LOG4J + #LTTNG_EVENT_TRACEPOINT + + lttng_log4j:event + + Such an event record has a string field logger_name + which contains the name of the Apache log4j logger from which + LTTng creates \lt_var{E}. +
#LTTNG_DOMAIN_PYTHON + #LTTNG_EVENT_TRACEPOINT + + lttng_python:event + + Such an event record has a string field logger_name + which contains the name of the Python logger from which LTTng + creates \lt_var{E}. +
#LTTNG_DOMAIN_KERNEL + #LTTNG_EVENT_SYSCALL + + Location: + +
+
Entry +
+ syscall_entry_NAME, where + NAME is the name of the system call from + which LTTng creates \lt_var{E}, without any + sys_ prefix. + +
Exit +
+ syscall_exit_NAME, where + NAME is the name of the system call from + which LTTng creates \lt_var{E}, without any + sys_ prefix. +
+
#LTTNG_DOMAIN_KERNEL + #LTTNG_EVENT_PROBE or #LTTNG_EVENT_USERSPACE_PROBE + + The lttng_event::name member of the + descriptor you used to create \lt_var{ER} with + lttng_enable_event_with_exclusions(). +
#LTTNG_DOMAIN_KERNEL + #LTTNG_EVENT_FUNCTION + + Location: + +
+
Entry +
NAME_entry + +
Exit +
NAME_exit +
+ + where NAME is the lttng_event::name member + of the descriptor you used to create + \lt_var{ER} with lttng_enable_event_with_exclusions(). +
+ +@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. + +-# If you have a clearing handle from step 1: + + -# 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 +\ref api-rer-inst-pt-descr "instrumentation point descriptors". + +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. +*/ diff --git a/doc/api/liblttng-ctl/images/concepts.png b/doc/api/liblttng-ctl/images/concepts.png new file mode 100644 index 000000000..b0977bec9 Binary files /dev/null and b/doc/api/liblttng-ctl/images/concepts.png differ diff --git a/doc/api/liblttng-ctl/images/event-rule.png b/doc/api/liblttng-ctl/images/event-rule.png new file mode 100644 index 000000000..9c05ecf07 Binary files /dev/null and b/doc/api/liblttng-ctl/images/event-rule.png differ diff --git a/doc/api/liblttng-ctl/images/live.png b/doc/api/liblttng-ctl/images/live.png new file mode 100644 index 000000000..1ab2420a6 Binary files /dev/null and b/doc/api/liblttng-ctl/images/live.png differ diff --git a/doc/api/liblttng-ctl/images/many-sessions.png b/doc/api/liblttng-ctl/images/many-sessions.png new file mode 100644 index 000000000..447248a32 Binary files /dev/null and b/doc/api/liblttng-ctl/images/many-sessions.png differ diff --git a/doc/api/liblttng-ctl/images/per-process-buffering-root.png b/doc/api/liblttng-ctl/images/per-process-buffering-root.png new file mode 100644 index 000000000..c028cc7f7 Binary files /dev/null and b/doc/api/liblttng-ctl/images/per-process-buffering-root.png differ diff --git a/doc/api/liblttng-ctl/images/per-process-buffering.png b/doc/api/liblttng-ctl/images/per-process-buffering.png new file mode 100644 index 000000000..a2c98501f Binary files /dev/null and b/doc/api/liblttng-ctl/images/per-process-buffering.png differ diff --git a/doc/api/liblttng-ctl/images/per-user-buffering-root.png b/doc/api/liblttng-ctl/images/per-user-buffering-root.png new file mode 100644 index 000000000..aa7ff2ae0 Binary files /dev/null and b/doc/api/liblttng-ctl/images/per-user-buffering-root.png differ diff --git a/doc/api/liblttng-ctl/images/per-user-buffering.png b/doc/api/liblttng-ctl/images/per-user-buffering.png new file mode 100644 index 000000000..cb83d2116 Binary files /dev/null and b/doc/api/liblttng-ctl/images/per-user-buffering.png differ diff --git a/doc/api/liblttng-ctl/images/plumbing.png b/doc/api/liblttng-ctl/images/plumbing.png new file mode 100644 index 000000000..00797e574 Binary files /dev/null and b/doc/api/liblttng-ctl/images/plumbing.png differ diff --git a/doc/api/liblttng-ctl/images/rotation.png b/doc/api/liblttng-ctl/images/rotation.png new file mode 100644 index 000000000..66f5c420a Binary files /dev/null and b/doc/api/liblttng-ctl/images/rotation.png differ diff --git a/doc/api/liblttng-ctl/images/snapshot.png b/doc/api/liblttng-ctl/images/snapshot.png new file mode 100644 index 000000000..c004d1f9b Binary files /dev/null and b/doc/api/liblttng-ctl/images/snapshot.png differ diff --git a/doc/api/liblttng-ctl/style.css b/doc/api/liblttng-ctl/style.css new file mode 100644 index 000000000..25b69cec5 --- /dev/null +++ b/doc/api/liblttng-ctl/style.css @@ -0,0 +1,109 @@ +.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; +} diff --git a/include/lttng/channel.h b/include/lttng/channel.h index 3d175b8a4..a6a6f04fc 100644 --- a/include/lttng/channel.h +++ b/include/lttng/channel.h @@ -24,18 +24,139 @@ extern "C" { * 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: + + + + + + +
Member + Constraints +
lttng_channel_attr::overwrite + 0, 1, or -1 +
lttng_channel_attr::subbuf_size + + - Greater than 0 + - Power of two +
lttng_channel_attr::num_subbuf + + - Greater than 0 + - Power of two +
+*/ struct lttng_channel_attr { + /*! + @brief + \ref api-channel-er-loss-mode "Event record loss mode". + + One of: + +
+
0 +
+ The \ref api-channel-er-loss-mode "event record loss mode" + of the channel is + \ref api-channel-discard-mode "discard". + +
1 +
+ The event record loss mode of the channel is + \ref api-channel-overwrite-mode "overwrite". + +
-1 +
+ The event record loss mode of the channel is the default + value of its \lt_obj_session: + +
+
\ref api-session-snapshot-mode "Snapshot mode" +
Overwrite mode + +
Other modes +
Discard mode +
+
+ */ 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 { @@ -52,88 +173,508 @@ struct lttng_channel_attr { * 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: + +
+
\ref api-channel-monitor-timer "Monitor timer" period +
+ - lttng_channel_get_monitor_timer_interval() + - lttng_channel_set_monitor_timer_interval() + +
\ref api-channel-blocking-timeout "Blocking timeout" +
+ - lttng_channel_get_blocking_timeout() + - lttng_channel_set_blocking_timeout() +
+ +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 + On success, this function sets \lt_p{*channels} to + the summaries of the channels. + + Free \lt_p{*channels} with free(). + @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}: + +
+
+ \lt_p{channel->name} names an existing + channel within the \lt_obj_session and + \lt_obj_domain of \lt_p{handle} +
+ Enables the existing channel. + + In this case, this function only uses \lt_p{channel->name}, ignoring + all the other properties of \lt_p{channel}. + +
Otherwise +
+ Creates and enables a new channel, considering all the properties of + \lt_p{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 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 + If this function must create a new channel, then + \lt_p{channel->attr} is \ref api-channel-valid-attr-struct "valid". +@pre + If this function must create a new channel, 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 + If this function must create a new channel, 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 + On success, 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 + On success, 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 + On success, 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 + On success, this function sets \lt_p{*timeout} to + one of: + +
+
-1 +
+ The blocking timeout of \lt_p{channel} is infinite. + +
0 +
+ Blocking is disabled for \lt_p{channel}. + +
Otherwise +
+ The blocking timeout of \lt_p{channel} is + \lt_p{*timeout} Âµs. +
+ @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: + +
+
-1 +
+ The blocking timeout of \lt_p{channel} is infinite. + +
0 +
+ 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); +
Otherwise +
+ The blocking timeout of \lt_p{channel} is + \lt_p{timeout} Âµs. +
+ @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 } diff --git a/include/lttng/clear-handle.h b/include/lttng/clear-handle.h index 4fc5695ed..9a8048456 100644 --- a/include/lttng/clear-handle.h +++ b/include/lttng/clear-handle.h @@ -16,64 +16,143 @@ 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 + -1 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 + On success, 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 diff --git a/include/lttng/clear.h b/include/lttng/clear.h index 8961e166f..34d8e4981 100644 --- a/include/lttng/clear.h +++ b/include/lttng/clear.h @@ -16,47 +16,112 @@ 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: + +
+
\ref api-session-local-mode "Local" +
\ref api-session-net-mode "Network streaming" +
+ Delete the contents of the recording buffers of \lt_var{RS}. + + Delete the local/remote data stream files of \lt_var{RS}. + +
\ref api-session-snapshot-mode "Snapshot" +
+ Delete the contents of the recording buffers of \lt_var{RS}. + + LTTng doesn't touch prior snapshots of \lt_var{RS}. + +
\ref api-session-live-mode "Live" +
+ 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. +
+ +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 + On success, 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: + + + + + +
-#LTTNG_ERR_CLEAR_RELAY_DISALLOWED + + The relay daemon doesn't allow recording session clearing + operations. +
-#LTTNG_ERR_CLEAR_NOT_AVAILABLE_RELAY + + The relay daemon doesn't support the recording session + clearing operation. +
-#LTTNG_ERR_CLEAR_FAIL_CONSUMER + + A consumer daemon failed to clear the recording session named + \lt_p{session_name}. +
+ @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 diff --git a/include/lttng/constant.h b/include/lttng/constant.h index 2cbb46095..f20e96458 100644 --- a/include/lttng/constant.h +++ b/include/lttng/constant.h @@ -33,6 +33,13 @@ /* * Event symbol length. Copied from LTTng kernel ABI. */ + +/*! +@brief + Maximum symbol length. + +@ingroup api_gen +*/ #define LTTNG_SYMBOL_NAME_LEN 256 /* @@ -42,6 +49,12 @@ #define LTTNG_MAX_PID INT32_MAX #define LTTNG_MAX_PID_STR "2147483647" +/*! +@brief + Maximum name length. + +@ingroup api_gen +*/ #define LTTNG_NAME_MAX 255 /* diff --git a/include/lttng/destruction-handle.h b/include/lttng/destruction-handle.h index d14bc16a8..108ba4aa6 100644 --- a/include/lttng/destruction-handle.h +++ b/include/lttng/destruction-handle.h @@ -16,123 +16,246 @@ 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 + -1 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 + On success, 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 + On success, 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 + On success, 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 diff --git a/include/lttng/domain.h b/include/lttng/domain.h index 90c949721..26e9da932 100644 --- a/include/lttng/domain.h +++ b/include/lttng/domain.h @@ -12,26 +12,53 @@ extern "C" { #endif +/*! +@addtogroup api_channel +@{ +*/ + #include #include -/* - * 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, + + /// java.util.logging (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, }; /* @@ -39,9 +66,44 @@ enum lttng_buffer_type { */ #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 { @@ -51,14 +113,36 @@ struct lttng_domain { } 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 + On success, this function sets \lt_p{*domains} to + the summaries of the tracing domains. + + Free \lt_p{*domains} with free(). + @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 diff --git a/include/lttng/event.h b/include/lttng/event.h index 202fd8992..e4ee28988 100644 --- a/include/lttng/event.h +++ b/include/lttng/event.h @@ -9,216 +9,1129 @@ #ifndef LTTNG_EVENT_H #define LTTNG_EVENT_H +#ifdef __cplusplus +extern "C" { +#endif + #include #include #include -#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 + kprobe + events. + */ LTTNG_EVENT_PROBE = 1, + + /*! + Match Linux + kretprobe + 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 + uprobe + 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 java.util.logging\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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Enumerator + Description + Tracing domain + Field type + Field name +
#LTTNG_EVENT_CONTEXT_PID + Process ID + #LTTNG_DOMAIN_KERNEL + Integer + pid +
#LTTNG_EVENT_CONTEXT_PROCNAME + Process name + #LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST + String + procname +
#LTTNG_EVENT_CONTEXT_PRIO + Process priority + #LTTNG_DOMAIN_KERNEL + Integer + prio +
#LTTNG_EVENT_CONTEXT_NICE + Nice value of the process + #LTTNG_DOMAIN_KERNEL + Integer + nice +
#LTTNG_EVENT_CONTEXT_VPID + Virtual process ID + #LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST + Integer + vpid +
#LTTNG_EVENT_CONTEXT_TID + Thread ID + #LTTNG_DOMAIN_KERNEL + Integer + tid +
#LTTNG_EVENT_CONTEXT_VTID + Virtual thread ID + #LTTNG_DOMAIN_KERNEL + Integer + vtid +
#LTTNG_EVENT_CONTEXT_PPID + ID of the parent process + #LTTNG_DOMAIN_KERNEL + Integer + ppid +
#LTTNG_EVENT_CONTEXT_VPPID + Virtual ID of the parent process + #LTTNG_DOMAIN_KERNEL + Integer + vppid +
#LTTNG_EVENT_CONTEXT_PTHREAD_ID + POSIX thread ID + #LTTNG_DOMAIN_KERNEL + Integer + pthread_id +
#LTTNG_EVENT_CONTEXT_HOSTNAME + Hostname + #LTTNG_DOMAIN_KERNEL + String + hostname +
#LTTNG_EVENT_CONTEXT_IP + Instruction pointer + #LTTNG_DOMAIN_UST + Integer + ip +
#LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER + + 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. + #LTTNG_DOMAIN_KERNEL + Integer + Depends on the selected perf counter +
#LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER + + 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. + #LTTNG_DOMAIN_UST + Integer + Depends on the selected perf counter +
#LTTNG_EVENT_CONTEXT_APP_CONTEXT + + 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. + #LTTNG_DOMAIN_JUL or #LTTNG_DOMAIN_LOG4J + Integer or string + Depends on the selected application-specific context +
#LTTNG_EVENT_CONTEXT_INTERRUPTIBLE + Whether or not the process is interruptible + #LTTNG_DOMAIN_KERNEL + Integer (0 or 1) + interruptible +
#LTTNG_EVENT_CONTEXT_PREEMPTIBLE + Whether or not the process is preemptible + #LTTNG_DOMAIN_KERNEL + Integer (0 or 1) + preemptible +
#LTTNG_EVENT_CONTEXT_NEED_RESCHEDULE + Whether or not the process needs a reschedule + #LTTNG_DOMAIN_KERNEL + Integer (0 or 1) + need_reschedule +
#LTTNG_EVENT_CONTEXT_MIGRATABLE + Whether or not the process is migratable + #LTTNG_DOMAIN_KERNEL + Integer (0 or 1) + migratable +
#LTTNG_EVENT_CONTEXT_CALLSTACK_KERNEL + Linux kernel call stack + #LTTNG_DOMAIN_KERNEL + Dynamic-length array of integers (instruction pointers) + callstack_kernel +
#LTTNG_EVENT_CONTEXT_CALLSTACK_USER + + User space call stack. + + Only supported on IA-32 and x86-64 architectures. + #LTTNG_DOMAIN_KERNEL + Dynamic-length array of integers (instruction pointers) + callstack_user +
#LTTNG_EVENT_CONTEXT_CGROUP_NS + + Control group root directory namespace ID. + + @sa \lt_man_gen{cgroup_namespaces,7} + #LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST + Integer + cgroup_ns +
#LTTNG_EVENT_CONTEXT_IPC_NS + + System V IPC and POSIX message queue namespace ID. + + @sa \lt_man_gen{ipc_namespaces,7} + #LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST + Integer + ipc_ns +
#LTTNG_EVENT_CONTEXT_MNT_NS + + Mount point namespace ID. + + @sa \lt_man_gen{mount_namespaces,7} + #LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST + Integer + mnt_ns +
#LTTNG_EVENT_CONTEXT_NET_NS + + Networking namespace ID. + + @sa \lt_man_gen{network_namespaces,7} + #LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST + Integer + net_ns +
#LTTNG_EVENT_CONTEXT_PID_NS + + Process ID namespace ID. + + @sa \lt_man_gen{pid_namespaces,7} + #LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST + Integer + pid_ns +
#LTTNG_EVENT_CONTEXT_USER_NS + + User and group ID namespace ID. + + @sa \lt_man_gen{user_namespaces,7} + #LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST + Integer + user_ns +
#LTTNG_EVENT_CONTEXT_UTS_NS + + Hostname and NIS domain name namespace ID. + + @sa \lt_man_gen{uts_namespaces,7} + #LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST + Integer + uts_ns +
#LTTNG_EVENT_CONTEXT_TIME_NS + + Boot and monotonic clock namespace ID. + + @sa \lt_man_gen{time_namespaces,7} + #LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST + Integer + time_ns +
#LTTNG_EVENT_CONTEXT_UID + User ID + #LTTNG_DOMAIN_KERNEL + Integer + uid +
#LTTNG_EVENT_CONTEXT_EUID + Effective user ID + #LTTNG_DOMAIN_KERNEL + Integer + euid +
#LTTNG_EVENT_CONTEXT_SUID + Set owner user ID + #LTTNG_DOMAIN_KERNEL + Integer + suid +
#LTTNG_EVENT_CONTEXT_GID + Group ID + #LTTNG_DOMAIN_KERNEL + Integer + gid +
#LTTNG_EVENT_CONTEXT_EGID + Effective group ID + #LTTNG_DOMAIN_KERNEL + Integer + egid +
#LTTNG_EVENT_CONTEXT_SGID + Set owner group ID + #LTTNG_DOMAIN_KERNEL + Integer + sgid +
#LTTNG_EVENT_CONTEXT_VUID + Virtual user ID + #LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST + Integer + vuid +
#LTTNG_EVENT_CONTEXT_VEUID + Virtual effective user ID + #LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST + Integer + veuid +
#LTTNG_EVENT_CONTEXT_VSUID + Virtual set owner user ID + #LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST + Integer + vsuid +
#LTTNG_EVENT_CONTEXT_VGID + Virtual group ID + #LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST + Integer + vgid +
#LTTNG_EVENT_CONTEXT_VEGID + Virtual effective group ID + #LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST + Integer + vegid +
#LTTNG_EVENT_CONTEXT_VSGID + Virtual set owner group ID + #LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST + Integer + vsgid +
+ +@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: + + + + + + + +
Type + ID +
Hardware counter + 0 +
Software counter + 1 +
Hardware cache counter + 3 +
Performance Monitoring Unit (PMU) counter + 4 +
+ */ uint32_t type; + + /*! + @brief + perf counter configuration. + + Depending on the lttng_event_perf_counter_ctx::type member: + +
+
0 (hardware counter) +
+ One of: + + + + + + + + + + + + +
Counter + ID +
CPU cycles + 0 +
Instructions + 1 +
Cache references + 2 +
Cache misses + 3 +
Branch instructions + 4 +
Branch misses + 5 +
Bus cycles + 6 +
Stalled cycles (front end) + 7 +
Stalled cycles (back end) + 8 +
+ +
1 (software counter) +
+ One of: + + + + + + + + + + + + +
Counter + ID +
CPU clock + 0 +
Task clock + 1 +
Page faults + 2 +
Context switches + 3 +
CPU migrations + 4 +
Minor page faults + 5 +
Major page faults + 6 +
Alignment faults + 7 +
Emulation faults + 8 +
+ +
3 (hardware cache counter) +
+ The result of a bitwise OR operation between a cache ID, + an operation ID, and a result ID, as follows: + + + + + + + + +
Cache ID + Description +
0 + Data L1 +
1 + Instructions L1 +
2 + LL +
3 + Data TLB
4 + Instruction TLB +
5 + Branch prediction unit (BPU) +
+ + + + + + +
Operator ID + Description +
0 + Read +
0x100 + Write +
0x200 + Prefetch +
+ + + + + +
Result ID + Description +
0 + Access +
0x10000 + Miss +
+ +
4 (PMU counter) +
+ PMU counter raw ID. + + @sa \lt_man_gen{perf-record,1} +
+ */ 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]; @@ -243,36 +1156,200 @@ struct lttng_event_function_attr { */ #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 + \"instrumentation point descriptor\". + +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: + +
+
+ Linux uprobe location (when the lttng_event::type member is + #LTTNG_EVENT_USERSPACE_PROBE) +
+ - lttng_event_get_userspace_probe_location() + - lttng_event_set_userspace_probe_location() + +
\ref api-rer-conds-event-name "Event name" exclusion patterns +
+ lttng_event_get_exclusion_name() + +
\ref api-rer-conds-filter "Event payload and context filter" expression +
+ lttng_event_get_filter_expression() +
+ +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 * (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 */ @@ -285,249 +1362,989 @@ struct lttng_event { } 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 + On success, this function sets \lt_p{*event_rules} + to the recording event rule descriptors. + + Free \lt_p{*event_rules} with free(). + @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 + If not \c NULL, \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 + On success, this function sets \lt_p{*filter_expr} + to: + +
+
+ If \lt_p{event_rule} has an event payload and context filter + expression +
+ 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. + +
Otherwise +
\c NULL +
+ @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 + On success, 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 + On success, \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 + On success, 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 free(). + @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 + On success, 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 free(). + @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 + On success, 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 free(). + @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: + +
+
+ If the recording session and tracing domain of + \lt_p{handle} have no channels +
+ LTTng creates a new, default channel named \c channel0 within + \lt_p{handle} which becomes the selected channel. + +
Otherwise +
+ LTTng selects all the channels of \lt_p{handle}. +
+ @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 + If not \c NULL, \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}: + +
+
+ The conditions and parameters describe an existing recording event + rule within the selected channel +
+ Enables the existing recording event rule. + +
Otherwise +
+ Creates and enables a new recording event rule within the + selected channel. +
+ +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. + + If \c NULL, 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 + If \lt_p{handle->domain.type} is \em not + #LTTNG_DOMAIN_KERNEL, then \lt_p{event_rule->type} is + #LTTNG_EVENT_TRACEPOINT. +@pre + If \lt_p{handle->domain.type} is \em not + #LTTNG_DOMAIN_UST, then \lt_p{event_name_exclusion_count} + is 0. +@pre + If this function must enable an existing recording event + rule, then the recording event rule to enable is disabled. +@pre + If not \c NULL, \lt_p{channel_name} names an + existing channel within the recording session and tracing domain of + \lt_p{handle}. +@pre + If \lt_p{channel_name} is \c NULL, then + \lt_p{handle} contains either no channels or a default channel named + \c channel0. +@pre + If not \c NULL, \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: + +
+
Not empty +
+ Depending on \lt_p{event_rule->type}: + +
+
#LTTNG_EVENT_ALL +
+ Disables \em all the recording event rules of which the event + name pattern is exactly \lt_p{event_rule->name} within the + selected channel. + +
Otherwise +
+ 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. +
+ +
Empty +
+ Depending on \lt_p{event_rule->type}: + +
+
#LTTNG_EVENT_ALL +
+ Disables \em all the recording event rules within the selected + channel. + +
Otherwise +
+ 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. +
+
+ +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: + +- Optional, and only if \lt_p{handle->domain.type} + is #LTTNG_DOMAIN_KERNEL: its lttng_event::type member. + +- Optional: 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 + If \lt_p{handle->domain.type} is \em not + #LTTNG_DOMAIN_KERNEL, then \lt_p{event_rule->type} + is #LTTNG_EVENT_ALL. +@pre + If not #LTTNG_EVENT_ALL, 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 + If not empty, 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 + If not \c NULL, then \lt_p{channel_name} names an + existing channel within the recording session and tracing domain of + \lt_p{handle}. +@pre + If \lt_p{channel_name} is \c NULL, 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 } diff --git a/include/lttng/handle.h b/include/lttng/handle.h index 14a0e5407..08f9eaad9 100644 --- a/include/lttng/handle.h +++ b/include/lttng/handle.h @@ -15,42 +15,100 @@ 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 diff --git a/include/lttng/lttng-error.h b/include/lttng/lttng-error.h index df23a67bb..fa05af777 100644 --- a/include/lttng/lttng-error.h +++ b/include/lttng/lttng-error.h @@ -15,213 +15,717 @@ #ifndef LTTNG_ERROR_H #define LTTNG_ERROR_H -#include - #ifdef __cplusplus extern "C" { #endif +#include + +/*! +@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 } diff --git a/include/lttng/lttng.h b/include/lttng/lttng.h index 4dc24a522..6ae331bda 100644 --- a/include/lttng/lttng.h +++ b/include/lttng/lttng.h @@ -12,6 +12,8 @@ #ifndef LTTNG_H #define LTTNG_H +#include + /* Error codes that can be returned by API calls */ #include @@ -59,7 +61,6 @@ #include #include #include -#include #include #include #include @@ -91,20 +92,64 @@ struct lttng_calibrate { 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: + +
+
1
+
+ liblttng-ctl is able to connect to a session daemon. + +
0 +
+ liblttng-ctl isn't able to connect to a session daemon. + +
Negative value +
+ Error: a negative #lttng_error_code enumerator. +
+ @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. @@ -119,31 +164,124 @@ LTTNG_EXPORT extern int lttng_set_tracing_group(const char *name); 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); /* @@ -183,16 +321,54 @@ LTTNG_EXPORT extern int lttng_calibrate(struct lttng_handle *handle, 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: + +
+
0 +
+ 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). + +
1
+
+ You may \em not read the traces of the recording session named + \lt_p{session_name}. + +
Negative value +
+ Error: a negative #lttng_error_code enumerator. +
+ @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); /* @@ -203,27 +379,119 @@ 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 NTP +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 diff --git a/include/lttng/session-descriptor.h b/include/lttng/session-descriptor.h index a67a4bf1c..f4151b3a8 100644 --- a/include/lttng/session-descriptor.h +++ b/include/lttng/session-descriptor.h @@ -8,12 +8,23 @@ #ifndef LTTNG_SESSION_DESCRIPTOR_H #define LTTNG_SESSION_DESCRIPTOR_H -#include - #ifdef __cplusplus extern "C" { #endif +#include + +/*! +@addtogroup api_session_descr +@{ +*/ + +/*! +@struct lttng_session_descriptor + +@brief + Recording session descriptor (opaque type). +*/ struct lttng_session_descriptor; /* @@ -90,90 +101,468 @@ 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(), + $LTTNG_HOME/lttng-traces/NAME-TS, + with: + +
+
$LTTNG_HOME +
+ The value of the \c LTTNG_HOME environment variable, or + of the \c HOME environment variable if \c LTTNG_HOME isn't + set. + +
NAME +
+ Recording session name (\lt_p{session_name} if not \c NULL, or + an automatically generated name otherwise). + +
TS +
+ \link lttng_session_get_creation_time() Timestamp of the + creation\endlink of the recording session using the + YYYYmmdd-HHMMSS form. +
+ @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 + If not \c NULL, \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: + + + + + + + +
\lt_p{control_url} + \lt_p{data_url} + Behaviour +
\c NULL + \c NULL + + Use \lt_def_net_ctrl_url as \lt_p{control_url}. + + Use \lt_def_net_data_url as \lt_p{data_url}. +
\ref api-session-one-port-url "Single-port output URL" + \c NULL + + 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}. +
Single-port output URL + + Single-port output URL with the exact same protocol, host, + and trace directory (if any) as \lt_p{control_url}. + + Use the specified output URLs. +
\ref api-session-two-port-url "Two-port output URL" + \c NULL + + Use the protocol, host, data port, and trace directory (if any) + of \lt_p{control_url} as \lt_p{data_url}. +
+ +@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: + +
+
\ref api-session-one-port-url "Single-port output URL" +
+ Indicates where (to which relay daemon; see + \lt_man{lttng-relayd,8}) to send the control data. + +
\ref api-session-two-port-url "Two-port output URL" +
+ Indicates where to send the control \em and trace data. +
+ + 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 NULL: 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 snapshot-0. + +@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(), + $LTTNG_HOME/lttng-traces/NAME-TS, + with: + +
+
$LTTNG_HOME +
+ The value of the \c LTTNG_HOME environment variable, or + of the \c HOME environment variable if \c LTTNG_HOME isn't + set. + +
NAME +
+ Recording session name (\lt_p{session_name} if not \c NULL, or + an automatically generated name otherwise). + +
TS +
+ \link lttng_session_get_creation_time() Timestamp of the + creation\endlink of the recording session using the + YYYYmmdd-HHMMSS form. +
+ @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 + If not \c NULL, \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 snapshot-0. + +The valid combinations of \lt_p{control_url} and \lt_p{data_url} are: + + + + + + + +
\lt_p{control_url} + \lt_p{data_url} + Behaviour +
\c NULL + \c NULL + + Use \lt_def_net_ctrl_url as \lt_p{control_url}. + + Use \lt_def_net_data_url as \lt_p{data_url}. +
\ref api-session-one-port-url "Single-port output URL" + \c NULL + + 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}. +
Single-port output URL + + Single-port output URL with the exact same protocol, host, + and trace directory (if any) as \lt_p{control_url}. + + Use the specified output URLs. +
\ref api-session-two-port-url "Two-port output URL" + \c NULL + + Use the protocol, host, data port, and trace directory (if any) + of \lt_p{control_url} as \lt_p{data_url}. +
+ +@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: + +
+
\ref api-session-one-port-url "Single-port output URL" +
+ Indicates where (to which relay daemon; see + \lt_man{lttng-relayd,8}) to send the control data. + +
\ref api-session-two-port-url "Two-port output URL" +
+ Indicates where to send the control \em and trace data. +
+ + 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 NULL: 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. @@ -189,27 +578,109 @@ lttng_session_descriptor_snapshot_network_create(const char *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: + + + + + + + +
\lt_p{control_url} + \lt_p{data_url} + Behaviour +
\c NULL + \c NULL + + Use \lt_def_net_ctrl_url as \lt_p{control_url}. + + Use \lt_def_net_data_url as \lt_p{data_url}. +
\ref api-session-one-port-url "Single-port output URL" + \c NULL + + 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}. +
Single-port output URL + + Single-port output URL with the exact same protocol, host, + and trace directory (if any) as \lt_p{control_url}. + + Use the specified output URLs. +
\ref api-session-two-port-url "Two-port output URL" + \c NULL + + Use the protocol, host, data port, and trace directory (if any) + of \lt_p{control_url} as \lt_p{data_url}. +
+ +@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: + +
+
\ref api-session-one-port-url "Single-port output URL" +
+ Indicates where (to which relay daemon; see + \lt_man{lttng-relayd,8}) to send the control data. + +
\ref api-session-two-port-url "Two-port output URL" +
+ Indicates where to send the control \em and trace data. +
+ + 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 NULL: 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. @@ -226,18 +697,75 @@ lttng_session_descriptor_live_network_create(const char *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 + On success, 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 } diff --git a/include/lttng/session.h b/include/lttng/session.h index 9be506fc1..a6735edad 100644 --- a/include/lttng/session.h +++ b/include/lttng/session.h @@ -13,36 +13,79 @@ extern "C" { #endif -#include #include +/*! +@addtogroup api_session +@{ +*/ + +#include + 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 + Human-readable 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 */ /* @@ -73,138 +116,397 @@ struct lttng_session { } 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 + If not \c NULL, \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 snapshot-0. + + 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 + If not \c NULL, \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 + If not \c NULL, \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 + On success, 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 + On success, this function sets \lt_p{*sessions} to + the summaries of the available recording sessions. + + Free \lt_p{*sessions} with free(). + @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 + On success, 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 +NVRAM +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 } diff --git a/m4/ax_prog_doxygen.m4 b/m4/ax_prog_doxygen.m4 new file mode 100644 index 000000000..ed1dc83b4 --- /dev/null +++ b/m4/ax_prog_doxygen.m4 @@ -0,0 +1,586 @@ +# =========================================================================== +# 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 +# Copyright (c) 2015 Olaf Mandel +# +# 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 +]) diff --git a/src/bin/lttng-relayd/sessiond-trace-chunks.cpp b/src/bin/lttng-relayd/sessiond-trace-chunks.cpp index 9d793c9bc..2326878fb 100644 --- a/src/bin/lttng-relayd/sessiond-trace-chunks.cpp +++ b/src/bin/lttng-relayd/sessiond-trace-chunks.cpp @@ -78,8 +78,8 @@ struct trace_chunk_registry_ht_element { static unsigned long trace_chunk_registry_ht_key_hash(const struct trace_chunk_registry_ht_key *key) { - const uint64_t uuid_h1 = *reinterpret_cast(&key->sessiond_uuid[0]); - const uint64_t uuid_h2 = *reinterpret_cast(&key->sessiond_uuid[1]); + const uint64_t uuid_h1 = reinterpret_cast(key->sessiond_uuid.data())[0]; + const uint64_t uuid_h2 = reinterpret_cast(key->sessiond_uuid.data())[1]; return hash_key_u64(&uuid_h1, lttng_ht_seed) ^ hash_key_u64(&uuid_h2, lttng_ht_seed); } diff --git a/src/bin/lttng-sessiond/manage-consumer.cpp b/src/bin/lttng-sessiond/manage-consumer.cpp index b7eb10800..27a368e7f 100644 --- a/src/bin/lttng-sessiond/manage-consumer.cpp +++ b/src/bin/lttng-sessiond/manage-consumer.cpp @@ -164,8 +164,13 @@ static void *thread_consumer_management(void *data) DBG2("Receiving code from consumer err_sock"); - /* Getting status code from kconsumerd */ - ret = lttcomm_recv_unix_sock(sock, &code, sizeof(enum lttcomm_return_code)); + /* Getting status code from consumerd */ + { + std::int32_t comm_code = 0; + + ret = lttcomm_recv_unix_sock(sock, &comm_code, sizeof(comm_code)); + code = static_cast(comm_code); + } if (ret <= 0) { mark_thread_intialization_as_failed(notifiers); goto error; @@ -304,9 +309,14 @@ static void *thread_consumer_management(void *data) goto error; } health_code_update(); - /* Wait for any kconsumerd error */ - ret = lttcomm_recv_unix_sock( - sock, &code, sizeof(enum lttcomm_return_code)); + /* Wait for any consumerd error */ + { + std::int32_t comm_code = 0; + + ret = lttcomm_recv_unix_sock( + sock, &comm_code, sizeof(comm_code)); + code = static_cast(comm_code); + } if (ret <= 0) { ERR("consumer closed the command socket"); goto error; diff --git a/src/bin/lttng-sessiond/ust-app.cpp b/src/bin/lttng-sessiond/ust-app.cpp index 12250edfd..d993b7b44 100644 --- a/src/bin/lttng-sessiond/ust-app.cpp +++ b/src/bin/lttng-sessiond/ust-app.cpp @@ -6025,8 +6025,8 @@ static void ust_app_synchronize_event_notifier_rules(struct ust_app *app) } for (i = 0; i < count; i++) { - struct lttng_condition *condition; - struct lttng_event_rule *event_rule; + const struct lttng_condition *condition; + const struct lttng_event_rule *event_rule; struct lttng_trigger *trigger; const struct ust_app_event_notifier_rule *looked_up_event_notifier_rule; enum lttng_condition_status condition_status; @@ -6036,7 +6036,7 @@ static void ust_app_synchronize_event_notifier_rules(struct ust_app *app) LTTNG_ASSERT(trigger); token = lttng_trigger_get_tracer_token(trigger); - condition = lttng_trigger_get_condition(trigger); + condition = lttng_trigger_get_const_condition(trigger); if (lttng_condition_get_type(condition) != LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES) { @@ -6044,8 +6044,8 @@ static void ust_app_synchronize_event_notifier_rules(struct ust_app *app) continue; } - condition_status = lttng_condition_event_rule_matches_borrow_rule_mutable( - condition, &event_rule); + condition_status = + lttng_condition_event_rule_matches_get_rule(condition, &event_rule); LTTNG_ASSERT(condition_status == LTTNG_CONDITION_STATUS_OK); if (lttng_event_rule_get_domain_type(event_rule) == LTTNG_DOMAIN_KERNEL) { diff --git a/src/common/Makefile.am b/src/common/Makefile.am index 34fd83452..8170e6e5a 100644 --- a/src/common/Makefile.am +++ b/src/common/Makefile.am @@ -115,6 +115,7 @@ libcommon_lgpl_la_SOURCES = \ time.cpp \ tracker.cpp tracker.hpp \ trigger.cpp \ + type-traits.hpp \ unix.cpp unix.hpp \ uri.cpp uri.hpp \ userspace-probe.cpp \ @@ -432,6 +433,7 @@ endif # libstring-utils noinst_LTLIBRARIES += libstring-utils.la libstring_utils_la_SOURCES = \ + string-utils/c-string-view.hpp \ string-utils/format.hpp \ string-utils/string-utils.cpp \ string-utils/string-utils.hpp diff --git a/src/common/consumer/consumer-timer.cpp b/src/common/consumer/consumer-timer.cpp index 8c9371bae..2ae7f0f73 100644 --- a/src/common/consumer/consumer-timer.cpp +++ b/src/common/consumer/consumer-timer.cpp @@ -530,7 +530,7 @@ int consumer_timer_monitor_stop(struct lttng_consumer_channel *channel) ret = consumer_channel_timer_stop(&channel->monitor_timer, LTTNG_CONSUMER_SIG_MONITOR); if (ret == -1) { - ERR("Failed to stop live timer"); + ERR("Failed to stop monitor timer"); goto end; } diff --git a/src/common/consumer/consumer.cpp b/src/common/consumer/consumer.cpp index 7e7e7d384..1da243601 100644 --- a/src/common/consumer/consumer.cpp +++ b/src/common/consumer/consumer.cpp @@ -45,6 +45,7 @@ #include #include #include +#include #include lttng_consumer_global_data the_consumer_data; @@ -177,13 +178,6 @@ static void clean_channel_stream_list(struct lttng_consumer_channel *channel) /* Delete streams that might have been left in the stream list. */ cds_list_for_each_entry_safe (stream, stmp, &channel->streams.head, send_node) { - /* - * Once a stream is added to this list, the buffers were created so we - * have a guarantee that this call will succeed. Setting the monitor - * mode to 0 so we don't lock nor try to delete the stream from the - * global hash table. - */ - stream->monitor = 0; consumer_stream_destroy(stream, nullptr); } } @@ -1255,11 +1249,17 @@ void lttng_consumer_set_command_sock_path(struct lttng_consumer_local_data *ctx, * Send return code to the session daemon. * If the socket is not defined, we return 0, it is not a fatal error */ -int lttng_consumer_send_error(struct lttng_consumer_local_data *ctx, int cmd) +int lttng_consumer_send_error(struct lttng_consumer_local_data *ctx, + enum lttcomm_return_code error_code) { if (ctx->consumer_error_socket > 0) { + const std::int32_t comm_code = std::int32_t(error_code); + + static_assert( + sizeof(comm_code) >= sizeof(std::underlying_type), + "Fixed-size communication type too small to accomodate lttcomm_return_code"); return lttcomm_send_unix_sock( - ctx->consumer_error_socket, &cmd, sizeof(enum lttcomm_sessiond_command)); + ctx->consumer_error_socket, &comm_code, sizeof(comm_code)); } return 0; diff --git a/src/common/consumer/consumer.hpp b/src/common/consumer/consumer.hpp index c62e01453..851b3e2b8 100644 --- a/src/common/consumer/consumer.hpp +++ b/src/common/consumer/consumer.hpp @@ -921,7 +921,8 @@ void lttng_consumer_set_command_sock_path(struct lttng_consumer_local_data *ctx, * Returns the return code of sendmsg : the number of bytes transmitted or -1 * on error. */ -int lttng_consumer_send_error(struct lttng_consumer_local_data *ctx, int cmd); +int lttng_consumer_send_error(struct lttng_consumer_local_data *ctx, + enum lttcomm_return_code error_code); /* * Called from signal handler to ensure a clean exit. diff --git a/src/common/event-rule/kernel-syscall.cpp b/src/common/event-rule/kernel-syscall.cpp index 23a432aac..933c3543f 100644 --- a/src/common/event-rule/kernel-syscall.cpp +++ b/src/common/event-rule/kernel-syscall.cpp @@ -133,6 +133,10 @@ static bool lttng_event_rule_kernel_syscall_is_equal(const struct lttng_event_ru goto end; } + if (a->emission_site != b->emission_site) { + goto end; + } + is_equal = true; end: return is_equal; diff --git a/src/common/scope-exit.hpp b/src/common/scope-exit.hpp index 20d9b892d..3f8c90f80 100644 --- a/src/common/scope-exit.hpp +++ b/src/common/scope-exit.hpp @@ -33,7 +33,8 @@ class scope_exit { public: /* * Since ScopeExitInvocableType will be invoked in the destructor, it - * must be `noexcept` lest we anger the undefined behaviour gods. + * must be `noexcept` lest we anger the undefined behaviour gods by throwing + * an exception while an exception is active. */ static_assert(details::is_invocation_noexcept::value, "scope_exit requires a noexcept invocable type"); diff --git a/src/common/string-utils/c-string-view.hpp b/src/common/string-utils/c-string-view.hpp new file mode 100644 index 000000000..6b175ea33 --- /dev/null +++ b/src/common/string-utils/c-string-view.hpp @@ -0,0 +1,262 @@ +/* + * Copyright (c) 2023 Philippe Proulx + * + * SPDX-License-Identifier: MIT + */ + +#ifndef LTTNG_C_STRING_VIEW_HPP +#define LTTNG_C_STRING_VIEW_HPP + +#include +#include + +#include +#include +#include +#include + +namespace lttng { + +/* + * A view on a constant null-terminated C string. + */ +class c_string_view final { +public: + /* + * Builds an empty view (data() returns `nullptr`). + * + * Intentionally not explicit. + */ + constexpr c_string_view() noexcept = default; + + /* + * Builds a view of the C string `str` (may be `nullptr`). + * + * Intentionally not explicit. + */ + /* NOLINTBEGIN(google-explicit-constructor) */ + constexpr c_string_view(const char *const str) noexcept : _str{ str } + { + } + /* NOLINTEND(google-explicit-constructor) */ + + /* + * Builds a view of the string `str`. + */ + /* NOLINTBEGIN(google-explicit-constructor) */ + c_string_view(const std::string& str) noexcept : _str{ str.c_str() } + { + } + /* NOLINTEND */ + + /* + * Makes this view view the C string `str` (may be `nullptr`). + */ + c_string_view& operator=(const char *const str) noexcept + { + _str = str; + return *this; + } + + /* + * Viewed null-terminated C string (may be `nullptr`). + */ + const char *data() const noexcept + { + return _str; + } + + /* + * Alias of data(). + */ + operator const char *() const noexcept /* NOLINT(google-explicit-constructor) */ + { + return this->data(); + } + + /* + * Evaluate as boolean (false means an empty string). + */ + operator bool() const noexcept /* NOLINT(google-explicit-constructor) */ + { + return *this->data(); + } + + /* + * Alias of data(). + */ + const char *operator*() const noexcept + { + return this->data(); + } + + /* + * Alias of data(). + * + * data() must not return `nullptr`. + */ + const char *begin() const noexcept + { + return this->data(); + } + + /* + * Pointer to the null character of the viewed C string. + * + * data() must not return `nullptr`. + */ + const char *end() const noexcept + { + return _str + this->len(); + } + + /* + * Length of the viewed C string, excluding the null character. + * + * data() must not return `nullptr`. + */ + std::size_t len() const noexcept + { + return std::strlen(_str); + } + + /* + * Returns an `std::string` instance containing a copy of the viewed + * C string. + * + * data() must not return `nullptr`. + */ + std::string str() const + { + return std::string{ _str }; + } + + /* + * Alias of str(). + */ + operator std::string() const /* NOLINT(google-explicit-constructor) */ + { + return this->str(); + } + + /* + * Returns the character at index `i`. + * + * `i` must be less than what len() returns. + * + * data() must not return `nullptr`. + */ + char operator[](const std::size_t i) const noexcept + { + return _str[i]; + } + + bool startsWith(const lttng::c_string_view prefix) const noexcept + { + return std::strncmp(_str, (const char *) prefix, prefix.len()) == 0; + } + +private: + const char *_str = nullptr; +}; + +inline const char *format_as(const c_string_view& str) +{ + return str ? *str : "(null)"; +} + +namespace internal { + +template +const char *as_const_char_ptr(StrT&& val) noexcept +{ + return val.data(); +} + +inline const char *as_const_char_ptr(const char *const val) noexcept +{ + return val; +} + +template +using comparable_with_c_string_view = lttng::traits:: + is_one_of::type, c_string_view, std::string, const char *>; + +} /* namespace internal */ + +/* + * Returns true if `lhs` is equal to `rhs`. + * + * `LhsT` and `RhsT` may be any of: + * + * • `const char *` + * • `std::string` + * • `c_string_view` + * + * Both `lhs` and `rhs` must not have an underlying `nullptr` raw data. + */ +template < + typename LhsT, + typename RhsT, + typename = + typename std::enable_if::value>::type, + typename = + typename std::enable_if::value>::type> +bool operator==(LhsT&& lhs, RhsT&& rhs) noexcept +{ + const auto raw_lhs = internal::as_const_char_ptr(lhs); + const auto raw_rhs = internal::as_const_char_ptr(rhs); + + return std::strcmp(raw_lhs, raw_rhs) == 0; +} + +/* + * Returns true if `lhs` is not equal to `rhs`. + * + * `LhsT` and `RhsT` may be any of: + * + * • `const char *` + * • `std::string` + * • `c_string_view` + * + * Both `lhs` and `rhs` must not have an underlying `nullptr` raw data. + */ +template < + typename LhsT, + typename RhsT, + typename = + typename std::enable_if::value>::type, + typename = + typename std::enable_if::value>::type> +bool operator!=(LhsT&& lhs, RhsT&& rhs) noexcept +{ + return !(std::forward(lhs) == std::forward(rhs)); +} + +} /* namespace lttng */ + +/* + * Appends `rhs` to `lhs`. + */ +inline void operator+=(std::string& lhs, lttng::c_string_view rhs) +{ + lhs += rhs.data(); +} + +namespace std { +template <> +struct hash { + std::size_t operator()(const lttng::c_string_view& str) const + { + auto hash_value = std::hash{}('\0'); + + for (auto character : str) { + hash_value ^= std::hash{}(character); + } + + return hash_value; + } +}; +} /* namespace std */ + +#endif /* LTTNG_C_STRING_VIEW_HPP */ diff --git a/src/common/type-traits.hpp b/src/common/type-traits.hpp new file mode 100644 index 000000000..3801bf13f --- /dev/null +++ b/src/common/type-traits.hpp @@ -0,0 +1,38 @@ +/* + * Copyright (c) 2023 Philippe Proulx + * + * SPDX-License-Identifier: MIT + */ + +#ifndef LTTNG_TYPE_TRAITS_HPP +#define LTTNG_TYPE_TRAITS_HPP + +#include + +namespace lttng { +namespace traits { + +/* + * Provides the member constant `value` equal to: + * + * `T` is in the list of types `Ts`: + * `true` + * + * Otherwise: + * `false` + */ +template +struct is_one_of : std::false_type { +}; + +template +struct is_one_of : std::true_type { +}; + +template +struct is_one_of : is_one_of { +}; +} /* namespace traits */ +} /* namespace lttng */ + +#endif /* LTTNG_TYPE_TRAITS_HPP */ diff --git a/tests/regression/Makefile.am b/tests/regression/Makefile.am index ca3fb2d52..da5cb1b57 100644 --- a/tests/regression/Makefile.am +++ b/tests/regression/Makefile.am @@ -16,6 +16,7 @@ TESTS = tools/base-path/test_ust \ tools/health/test_thread_ok \ tools/live/test_kernel \ tools/live/test_lttng_kernel \ + tools/live/test_per_application_leaks.py \ tools/live/test_ust \ tools/live/test_ust_tracefile_count \ tools/live/test_lttng_ust \ diff --git a/tests/regression/tools/live/Makefile.am b/tests/regression/tools/live/Makefile.am index 494b982df..3ad9b7ba3 100644 --- a/tests/regression/tools/live/Makefile.am +++ b/tests/regression/tools/live/Makefile.am @@ -6,7 +6,7 @@ LIBTAP=$(top_builddir)/tests/utils/tap/libtap.la LIBLTTNG_SESSIOND_COMMON=$(top_builddir)/src/bin/lttng-sessiond/liblttng-sessiond-common.la noinst_PROGRAMS = live_test -EXTRA_DIST = test_kernel test_lttng_kernel +EXTRA_DIST = test_kernel test_lttng_kernel test_per_application_leaks.py if HAVE_LIBLTTNG_UST_CTL EXTRA_DIST += test_ust test_ust_tracefile_count test_lttng_ust diff --git a/tests/regression/tools/live/test_per_application_leaks.py b/tests/regression/tools/live/test_per_application_leaks.py new file mode 100755 index 000000000..1d12049ed --- /dev/null +++ b/tests/regression/tools/live/test_per_application_leaks.py @@ -0,0 +1,155 @@ +#!/usr/bin/env python3 +# +# SPDX-FileCyoprightText: Kienan Stewart +# SPDX-License-Identifier: GPL-2.0-only + +""" +Test that the consumerd doesn't leak file descriptor allocations in /dev/shm +when the relayd exits before instrumented applications start. + +@see https://bugs.lttng.org/issues/1411 +""" + +import os +import pathlib +import subprocess +import sys + +test_utils_import_path = pathlib.Path(__file__).absolute().parents[3] / "utils" +sys.path.append(str(test_utils_import_path)) + +import lttngtest + + +def get_consumerd_pid(tap, parent, match_string): + pid = 0 + try: + process = subprocess.Popen( + ["pgrep", "-P", str(parent), "-f", match_string], + stdout=subprocess.PIPE, + ) + process.wait() + output = str(process.stdout.read(), encoding="UTF-8").splitlines() + if len(output) != 1: + raise Exception( + "Unexpected number of output lines (got {}): {}".format( + len(output), output + ) + ) + pid = int(output[0]) + except Exception as e: + tap.diagnostic( + "Failed to find child process of '{}' matching '{}': '{}'".format( + parent, match_string, str(e) + ) + ) + return pid + + +def count_process_dev_shm_fds(pid): + count = 0 + if pid == 0: + return count + dir = os.path.join("/proc", str(pid), "fd") + for root, dirs, files in os.walk(dir): + for f in files: + filename = pathlib.Path(os.path.join(root, f)) + try: + if filename.is_symlink() and str(filename.resolve()).startswith( + "/dev/shm/shm-ust-consumer" + ): + count += 1 + except FileNotFoundError: + # As we're walking /proc/XX/fd/, fds may be added or removed + continue + return count + + +def count_dev_shm_fds(tap, test_env): + consumer32_pid = get_consumerd_pid(tap, test_env._sessiond.pid, "ustconsumerd32") + fds_consumerd32 = count_process_dev_shm_fds(consumer32_pid) + consumer64_pid = get_consumerd_pid(tap, test_env._sessiond.pid, "ustconsumerd64") + fds_consumerd64 = count_process_dev_shm_fds(consumer64_pid) + return (fds_consumerd32, fds_consumerd64) + + +def test_fd_leak(tap, test_env, buffer_sharing_policy, kill_relayd=True): + tap.diagnostic( + "test_fd_leak with buffer sharing policy {}, kill relayd: {}".format( + buffer_sharing_policy, kill_relayd + ) + ) + client = lttngtest.LTTngClient(test_env, log=tap.diagnostic) + output = lttngtest.NetworkSessionOutputLocation( + "net://localhost:{}:{}/".format( + test_env.lttng_relayd_control_port, test_env.lttng_relayd_data_port + ) + ) + + session = client.create_session(output=output, live=True) + channel = session.add_channel( + lttngtest.lttngctl.TracingDomain.User, + buffer_sharing_policy=buffer_sharing_policy, + ) + channel.add_recording_rule(lttngtest.lttngctl.UserTracepointEventRule()) + session.start() + + count_post_start = count_dev_shm_fds(tap, test_env) + + # Kill the relayd + if kill_relayd: + test_env._terminate_relayd() + + test_env.launch_wait_trace_test_application(10) + count_post_app1 = count_dev_shm_fds(tap, test_env) + + test_env.launch_wait_trace_test_application(10) + count_post_app2 = count_dev_shm_fds(tap, test_env) + + test_env.launch_wait_trace_test_application(10) + count_post_app3 = count_dev_shm_fds(tap, test_env) + + session.stop() + session.destroy() + + count_post_destroy = count_dev_shm_fds(tap, test_env) + + tap.diagnostic( + "FD counts post-start: {}, post-destroy: {}".format( + count_post_start, count_post_destroy + ) + ) + tap.test( + count_post_start == count_post_destroy, + "Count of consumerd FDs in /dev/shm are equal after session start then after destroy", + ) + + tap.diagnostic( + "FD counts post-app-1: {}, post-app-2: {}, post-app-3: {}".format( + count_post_app1, count_post_app2, count_post_app3 + ) + ) + if buffer_sharing_policy == lttngtest.lttngctl.BufferSharingPolicy.PerUID: + tap.test( + (count_post_app1 == count_post_app2) + and (count_post_app2 == count_post_app3), + "Count of consumerd FDs in /dev/shm doesn't leak over several application invocations", + ) + else: + tap.skip( + "Count of consumerds FDs in /dev/shm doesn't leak over several application invocations - no mechanism is available to guarantee buffer reclamation within a given time frame" + ) + + +tap = lttngtest.TapGenerator(8) +for kill_relayd in [True, False]: + for buffer_sharing_policy in [ + lttngtest.lttngctl.BufferSharingPolicy.PerUID, + lttngtest.lttngctl.BufferSharingPolicy.PerPID, + ]: + with lttngtest.test_environment( + log=tap.diagnostic, with_relayd=True, with_sessiond=True + ) as test_env: + test_fd_leak(tap, test_env, buffer_sharing_policy, kill_relayd) + +sys.exit(0 if tap.is_successful else 1) diff --git a/tests/regression/ust/rotation-destroy-flush/test_rotation_destroy_flush b/tests/regression/ust/rotation-destroy-flush/test_rotation_destroy_flush index 669bcbc43..64161768f 100755 --- a/tests/regression/ust/rotation-destroy-flush/test_rotation_destroy_flush +++ b/tests/regression/ust/rotation-destroy-flush/test_rotation_destroy_flush @@ -23,11 +23,11 @@ SIZE_LIMIT=$PAGE_SIZE NR_ITER=10 NUM_TESTS=$((15*$NR_ITER)) -# Ensure the daemons invoke abort on error. -export LTTNG_ABORT_ON_ERROR=1 - source $TESTDIR/utils/utils.sh +# Ensure the daemons invoke abort on error. +check_skip_kernel_test || export LTTNG_ABORT_ON_ERROR=1 + # MUST set TESTDIR before calling those functions function run_app() { diff --git a/tests/utils/lttngtest/environment.py b/tests/utils/lttngtest/environment.py index 74dcfb8d2..73d18874b 100644 --- a/tests/utils/lttngtest/environment.py +++ b/tests/utils/lttngtest/environment.py @@ -618,14 +618,20 @@ class _Environment(logger._Logger): Launch an application that will trace from within constructors. """ return _TraceTestApplication( - self._project_root - / "tests" - / "utils" - / "testapp" - / subpath, + self._project_root / "tests" / "utils" / "testapp" / subpath, self, ) + def _terminate_relayd(self): + if self._relayd and self._relayd.poll() is None: + self._relayd.terminate() + self._relayd.wait() + if self._relayd_output_consumer: + self._relayd_output_consumer.join() + self._relayd_output_consumer = None + self._log("Relayd killed") + self._relayd = None + # Clean-up managed processes def _cleanup(self): # type: () -> None @@ -646,14 +652,7 @@ class _Environment(logger._Logger): self._log("Session daemon killed") self._sessiond = None - if self._relayd and self._relayd.poll() is None: - self._relayd.terminate() - self._relayd.wait() - if self._relayd_output_consumer: - self._relayd_output_consumer.join() - self._relayd_output_consumer = None - self._log("Relayd killed") - self._relayd = None + self._terminate_relayd() self._lttng_home = None diff --git a/tests/utils/xml-utils/Makefile.am b/tests/utils/xml-utils/Makefile.am index 7997d94e1..5890eef27 100644 --- a/tests/utils/xml-utils/Makefile.am +++ b/tests/utils/xml-utils/Makefile.am @@ -1,5 +1,7 @@ # SPDX-License-Identifier: GPL-2.0-only +EXTRA_DIST = common.hpp + noinst_PROGRAMS = validate_xml extract_xml pretty_xml validate_xml_SOURCES = validate_xml.cpp validate_xml_CPPFLAGS = $(libxml2_CFLAGS) $(AM_CPPFLAGS) @@ -9,7 +11,7 @@ extract_xml_SOURCES = extract_xml.cpp extract_xml_CPPFLAGS = $(libxml2_CFLAGS) $(AM_CPPFLAGS) extract_xml_LDADD = $(libxml2_LIBS) -pretty_xml_SOURCES = pretty_xml.c +pretty_xml_SOURCES = pretty_xml.cpp pretty_xml_CPPFLAGS = $(libxml2_CFLAGS) $(AM_CPPFLAGS) pretty_xml_LDADD = $(libxml2_LIBS) diff --git a/tests/utils/xml-utils/common.hpp b/tests/utils/xml-utils/common.hpp new file mode 100644 index 000000000..01a9b5207 --- /dev/null +++ b/tests/utils/xml-utils/common.hpp @@ -0,0 +1,49 @@ +/* + * Copyright (C) 2024 EfficiOS Inc. + * + * SPDX-License-Identifier: LGPL-2.1-only + * + */ + +#ifndef TESTS_UTILS_XML_UTILS_COMMON_HPP +#define TESTS_UTILS_XML_UTILS_COMMON_HPP + +#include "common/make-unique-wrapper.hpp" + +#include +#include + +namespace lttng { +namespace libxml { + +using parser_ctx_uptr = std::unique_ptr< + xmlParserCtxt, + lttng::memory::create_deleter_class::deleter>; +using doc_uptr = + std::unique_ptr::deleter>; + +/* + * Manage the global parser context of libxml2. + * There should only be one instance of this class per process. + */ +class global_parser_context { +public: + global_parser_context() + { + xmlInitParser(); + } + + ~global_parser_context() + { + xmlCleanupParser(); + } + + /* Deactivate copy and assignment. */ + global_parser_context(const global_parser_context&) = delete; + global_parser_context(global_parser_context&&) = delete; + global_parser_context& operator=(const global_parser_context&) = delete; + global_parser_context& operator=(global_parser_context&&) = delete; +}; +} /* namespace libxml */ +} /* namespace lttng */ +#endif /* TESTS_UTILS_XML_UTILS_COMMON_HPP */ diff --git a/tests/utils/xml-utils/extract_xml.cpp b/tests/utils/xml-utils/extract_xml.cpp index 3995dde48..280f2ed02 100644 --- a/tests/utils/xml-utils/extract_xml.cpp +++ b/tests/utils/xml-utils/extract_xml.cpp @@ -24,6 +24,8 @@ * node;b; * node;c; */ +#include "common.hpp" + #include #include @@ -36,6 +38,8 @@ #include #include +namespace ll = lttng::libxml; + #if defined(LIBXML_XPATH_ENABLED) static int opt_verbose; @@ -176,8 +180,15 @@ static int extract_xpath(const char *xml_path, const xmlChar *xpath) LTTNG_ASSERT(xml_path); LTTNG_ASSERT(xpath); + ll::parser_ctx_uptr parserCtx{ xmlNewParserCtxt() }; + + if (!parserCtx) { + fprintf(stderr, "ERR: could not allocate an XML parser context\n"); + return -1; + } + /* Parse the xml file */ - doc = xmlParseFile(xml_path); + doc = xmlCtxtReadFile(parserCtx.get(), xml_path, nullptr, XML_PARSE_NOBLANKS); if (!doc) { fprintf(stderr, "ERR parsing: xml file invalid \"%s\"\n", xml_path); return -1; @@ -253,7 +264,6 @@ int main(int argc, char **argv) /* Init libxml */ xmlInitParser(); - xmlKeepBlanksDefault(0); if (access(argv[optind], F_OK)) { fprintf(stderr, "ERR:%s\n", "Xml path not valid"); return -1; diff --git a/tests/utils/xml-utils/pretty_xml.c b/tests/utils/xml-utils/pretty_xml.c deleted file mode 100644 index 3f296f023..000000000 --- a/tests/utils/xml-utils/pretty_xml.c +++ /dev/null @@ -1,37 +0,0 @@ -/* - * Copyright (C) 2021 EfficiOS Inc. - * - * SPDX-License-Identifier: GPL-2.0-only - * - */ - -/* - * Prettyfi a xml input from stdin to stddout. - * This allows a more human friendly format for xml testing when problems occur. - */ - -#include - -int main(void) -{ - xmlDocPtr doc = NULL; - - /* Init libxml. */ - xmlInitParser(); - xmlKeepBlanksDefault(0); - - /* Parse the XML document from stdin. */ - doc = xmlParseFile("-"); - if (!doc) { - fprintf(stderr, "ERR parsing: xml input invalid"); - return -1; - } - - xmlDocFormatDump(stdout, doc, 1); - - xmlFreeDoc(doc); - /* Shutdown libxml. */ - xmlCleanupParser(); - - return 0; -} diff --git a/tests/utils/xml-utils/pretty_xml.cpp b/tests/utils/xml-utils/pretty_xml.cpp new file mode 100644 index 000000000..8a6e967a7 --- /dev/null +++ b/tests/utils/xml-utils/pretty_xml.cpp @@ -0,0 +1,39 @@ +/* + * Copyright (C) 2021 EfficiOS Inc. + * + * SPDX-License-Identifier: GPL-2.0-only + * + */ + +/* + * Prettyfi a xml input from stdin to stddout. + * This allows a more human friendly format for xml testing when problems occur. + */ + +#include "common.hpp" + +#include + +#include +#include +#include + +namespace ll = lttng::libxml; + +int main() +{ + const ll::global_parser_context global_parser_context; + const ll::parser_ctx_uptr parserCtx{ xmlNewParserCtxt() }; + + /* Parse the XML document from stdin. */ + const ll::doc_uptr doc{ xmlCtxtReadFd( + parserCtx.get(), STDIN_FILENO, nullptr, nullptr, XML_PARSE_NOBLANKS) }; + if (!doc) { + std::cerr << "Error: invalid XML input on stdin\n"; + return -1; + } + + xmlDocFormatDump(stdout, doc.get(), 1); + + return 0; +}