From: Michael Jeanson Date: Tue, 30 Apr 2024 19:17:52 +0000 (-0400) Subject: fix: relayd: unaligned access in trace_chunk_registry_ht_key_hash X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=commitdiff_plain;h=HEAD;hp=36962e16797b5ca590c54a385ca594e2859ef8c2 fix: relayd: unaligned access in trace_chunk_registry_ht_key_hash In 328c2fe7297c941aa9cbcfa4ce944fca1bd7300f, the type of 'lttng_uuid' was changed from a C array of 16 'uint8_t' to a C++ std::array of the same type and length. In 'trace_chunk_registry_ht_key_hash()' we access these 16 bytes as 2 'uint64_t', to do so we used to cast the array to '(uint64_t *)' and then access index 0 and 1. When it was converted to C++, an error was introduced where instead we reinterpret_cast to 'const uint64_t *' the index 0 and 1 of the array which results in a 'uint64_t' pointer to the first and second bytes of the array. These values overlap but since they are used as keys for an hash table it still works. However, on platforms that don't allow unaligned access, the second pointer being only offset by one byte results in a 'Bus error'. Reintroduce the old behavior by applying the index 0 and 1 to the pointer resulting from the reinterpret_cast. Change-Id: I2bc287edbe6864a2a870f9de1f3b4dd8f8a90ace Signed-off-by: Michael Jeanson Signed-off-by: Jérémie Galarneau --- diff --git a/.clang-format b/.clang-format index 66b5ef408..28ea69873 100644 --- a/.clang-format +++ b/.clang-format @@ -1,7 +1,8 @@ AccessModifierOffset: -8 -AlignAfterOpenBracket: DontAlign +AlignAfterOpenBracket: Align AlignConsecutiveAssignments: false AlignConsecutiveDeclarations: false +AlignConsecutiveMacros: Consecutive AlignEscapedNewlines: Left AlignOperands: false AlignTrailingComments: false @@ -14,8 +15,9 @@ AllowShortLoopsOnASingleLine: false AlwaysBreakAfterReturnType: None AlwaysBreakBeforeMultilineStrings: false AlwaysBreakTemplateDeclarations: Yes -BinPackArguments: true +BinPackArguments: false BinPackParameters: false +BitFieldColonSpacing: None BreakBeforeBraces: Custom BreakConstructorInitializers: AfterColon BraceWrapping: @@ -38,21 +40,35 @@ BreakStringLiterals: false ColumnLimit: 100 ConstructorInitializerAllOnOneLineOrOnePerLine: true ConstructorInitializerIndentWidth: 8 -ContinuationIndentWidth: 16 +ContinuationIndentWidth: 8 +Cpp11BracedListStyle: false DerivePointerAlignment: false DisableFormat: false EmptyLineBeforeAccessModifier: LogicalBlock +FixNamespaceComments: true ForEachMacros: - 'cds_lfht_for_each_entry' - 'cds_lfht_for_each_entry_safe' - 'cds_lfht_for_each_duplicate' - 'cds_list_for_each_entry' - 'cds_list_for_each_entry_safe' + - 'for_each_action_mutable' + - 'for_each_action_const' + - 'cds_wfs_for_each_blocking_safe' -IncludeBlocks: Preserve +IncludeBlocks: Regroup IncludeCategories: - - Regex: '.*' + - Regex: '".*"' + Priority: 0 + - Regex: '' Priority: 1 + - Regex: '' + Priority: 2 + - Regex: '' + Priority: 3 + - Regex: '<.*>' + Priority: 9 + IncludeIsMainRegex: '(Test)?$' IndentCaseLabels: false IndentPPDirectives: None diff --git a/.clang-tidy b/.clang-tidy new file mode 100644 index 000000000..5b6f3705b --- /dev/null +++ b/.clang-tidy @@ -0,0 +1,103 @@ +HeaderFilterRegex: '.*((include/.*-internal)|(src/common.*)|(src/bin.*)|(src/lib.*)|(tests.*))\.(h|hpp)$' +Checks: '-*, + bugprone-argument-comment, + bugprone-assert-side-effect, + bugprone-assignment-in-if-condition, + bugprone-bad-signal-to-kill-thread, + bugprone-bool-pointer-implicit-conversion, + bugprone-copy-constructor-init, + bugprone-dangling-handle, + bugprone-exception-escape, + bugprone-fold-init-type, + bugprone-forward-declaration-namespace, + bugprone-forwarding-reference-overload, + bugprone-inaccurate-erase, + bugprone-incorrect-roundings, + bugprone-infinite-loop, + bugprone-integer-division, + bugprone-macro-parentheses, + bugprone-macro-repeated-side-effects, + bugprone-misplaced-operator-in-strlen-in-alloc, + bugprone-misplaced-pointer-arithmetic-in-alloc, + bugprone-move-forwarding-reference, + bugprone-multiple-statement-macro, + bugprone-not-null-terminated-result, + bugprone-parent-virtual-call, + bugprone-posix-return, + bugprone-shared-ptr-array-mismatch, + bugprone-signal-handler, + bugprone-signed-char-misuse, + bugprone-sizeof-container, + bugprone-sizeof-expression, + bugprone-standalone-empty, + bugprone-string-constructor, + bugprone-string-integer-assignment, + bugprone-string-literal-with-embedded-nul, + bugprone-suspicious-enum-usage, + bugprone-suspicious-include, + bugprone-suspicious-memory-comparison + bugprone-suspicious-memset-usage, + bugprone-suspicious-missing-comma, + bugprone-suspicious-realloc-usage, + bugprone-suspicious-semicolon, + bugprone-suspicious-string-compare, + bugprone-swapped-arguments, + bugprone-terminating-continue, + bugprone-throw-keyword-missing, + bugprone-too-small-loop-variable, + bugprone-unchecked-optional-access + bugprone-undefined-memory-manipulation, + bugprone-undelegated-constructor, + bugprone-unhandled-exception-at-new, + bugprone-unhandled-self-assignment, + bugprone-unused-raii, + bugprone-unused-return-value, + bugprone-use-after-move, + bugprone-virtual-near-miss, + bugprone-unused-raii, + bugprone-use-after-move, + cppcoreguidelines-pro-type-const-cast, + cppcoreguidelines-slicing, + cppcoreguidelines-special-member-functions, + cppcoreguidelines-virtual-class-destructor, + google-build-explicit-make-pair, + google-explicit-constructor, + misc-const-correctness, + misc-misleading-identifier, + misc-non-copyable-objects, + misc-throw-by-value-catch-by-reference, + misc-unused-parameters, + misc-unused-using-decls, + misc-use-anonymous-namespace, + modernize-avoid-bind, + modernize-concat-nested-namespaces, + modernize-loop-convert, + modernize-make-shared, + modernize-make-unique, + modernize-pass-by-value, + modernize-redundant-void-arg, + modernize-replace-auto-ptr, + modernize-replace-random-shuffle, + modernize-replace-auto-ptr, + modernize-shrink-to-fit, + modernize-use-bool-literals, + modernize-use-default-member-init, + modernize-use-emplace, + modernize-use-equals-default, + modernize-use-equals-delete, + modernize-use-noexcept, + modernize-use-nullptr, + modernize-use-override, + modernize-use-transparent-functors, + modernize-use-using, + performance-*, + -performance-no-int-to-ptr, + readability-redundant-member-init, + readability-simplify-boolean-expr, + readability-static-definition-in-anonymous-namespace' +FormatStyle: 'file' +CheckOptions: + - key: bugprone-assert-side-effect.AssertMacros + value: assert,LTTNG_ASSERT + - key: bugprone-signed-char-misuse.CharTypdefsToIgnore + value: 'int8_t' diff --git a/.commit_template b/.commit_template new file mode 100644 index 000000000..b0da31505 --- /dev/null +++ b/.commit_template @@ -0,0 +1,24 @@ +Fix: Short description + +Observed issue +============== + +Steps to reproduce (list of commands or narrative description). + +Cause +===== + +Solution +======== + +Known drawbacks +=============== + +References +========== +[1]: + +Fixes: #xxx +Refs: #yyy + +Signed-off-by: diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs new file mode 100644 index 000000000..82b685465 --- /dev/null +++ b/.git-blame-ignore-revs @@ -0,0 +1,4 @@ +# Run clang-format on the whole tree +28ab034a2c3582d07d3423d2d746731f87d3969f +# Clean-up: run format-cpp on the tree +28f23191dcbf047429d51950a337a57d7a3f866a diff --git a/.gitignore b/.gitignore index 827e00e01..b0884eb16 100644 --- a/.gitignore +++ b/.gitignore @@ -31,6 +31,7 @@ stamp-h1 libtool tags /config/ +pre-inst-env .autotools .cproject @@ -46,7 +47,6 @@ TAGS /.clangd/ compile_commands.json *_flymake* -/.vscode/* # m4 macros not automatically generated /m4/libtool.m4 @@ -99,6 +99,11 @@ compile_commands.json /tests/regression/ust/high-throughput/gen-events /tests/regression/tools/filtering/gen-ust-events /tests/utils/testapp/gen-ust-events/gen-ust-events +/tests/utils/testapp/gen-ust-events-constructor/gen-ust-events-constructor-a +/tests/utils/testapp/gen-ust-events-constructor/gen-ust-events-constructor-so +/tests/utils/testapp/gen-ust-events-constructor/gen-ust-events-c-constructor-a +/tests/utils/testapp/gen-ust-events-constructor/gen-ust-events-c-constructor-so +/tests/utils/testapp/gen-ust-events-constructor/uses_heap /tests/utils/testapp/gen-ust-events-ns/gen-ust-events-ns /tests/regression/tools/health/health_check /tests/regression/kernel/select_poll_epoll @@ -132,6 +137,8 @@ compile_commands.json /tests/regression/ust/ust-dl/test_ust-dl /tests/regression/ust/multi-lib/exec-with-callsites /tests/regression/ust/multi-lib/exec-without-callsites +/tests/utils/testapp/gen-data-pending/gen-data-pending +/tests/utils/tap/clock /tests/utils/testapp/gen-syscall-events-callstack/gen-syscall-events-callstack /tests/utils/testapp/gen-ust-events/gen-ust-events /tests/utils/testapp/gen-ust-events-ns/gen-ust-events-ns @@ -170,6 +177,10 @@ compile_commands.json /doc/man/*.h /doc/man/asciidoc-attrs.conf !/doc/man/lttng-health-check.3 +/doc/man/man1 +/doc/man/man3 +/doc/man/man7 +/doc/man/man8 # examples /doc/examples/rotation/rotate-client 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/CONTRIBUTING.md b/CONTRIBUTING.md index 6873d7810..fbb48cd5e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,48 +15,44 @@ control. The upstream Git repository URL is: ## Coding standard -LTTng-tools uses the -[Linux kernel coding style](http://www.kernel.org/doc/Documentation/CodingStyle) -with one addition: single-line `if`/`for`/`while` statements must be -wrapped in braces. - -Example: - -~~~ c -/* not good */ -if (this == that) - goto fail; - -/* good */ -if (this == that) { - goto fail; -} -~~~ +See CodingStyle for guidelines style and design guidelines. -Although the LTTng-tools code base is primarily written in C, it does -contain shell, Perl, and Python code as well. There is no official coding +Although the LTTng-tools code base is primarily written in C++, it does +contain C, shell, and Python code as well. There is no official coding standard for these languages. However, using a style consistent with the rest of the code written in that language is strongly encouraged. ## Creating and sending a patch -LTTng-tools's development flow is primarily email-based, although we -also accept pull requests on our -[GitHub mirror](https://github.com/lttng/lttng-tools) and -[Gerrit Code Review](https://review.lttng.org). If you're going -to create GitHub pull requests, make sure you still follow the +LTTng-tools's development flow is primarily based on +[Gerrit Code Review](https://review.lttng.org), although we also accept +e-mail based patch series on the +[`lttng-dev` mailing list](https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev) +and pull requests on our [GitHub mirror](https://github.com/lttng/lttng-tools). +If you're going to create GitHub pull requests, make sure you still follow the guidelines below. -Like a lot of open source projects, patches are submitted and reviewed -on its development mailing list, -[`lttng-dev`](http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev) -(`lttng-dev@lists.lttng.org`). The mailing list is also used to share -and comment on RFCs and answer +The mailing list is also used to share and comment on +RFCs and answer user questions. -Once your changes have been committed to your local branch, you may use -Git's [`format-patch`](https://git-scm.com/docs/git-format-patch) command +A template commit messsage is available below, and as a file that you may +configure your local check out to use: + + git config commit.template .commit_template + +Once your changes have been comitted to your local branch, you may use the +[git-review](https://opendev.org/opendev/git-review) plugin to submit them +directly to [Gerrit](https://review.lttng.org) using the following command: + + git review + +Please note that you will need to create an account on [Gerrit](https://review.lttng.org) +and add an SSH public key. + +For e-mail based patches you may use Git's +[`format-patch`](https://git-scm.com/docs/git-format-patch) command to generate a patch file. The following command line generates a patch from the latest commit: diff --git a/CodingStyle b/CodingStyle deleted file mode 100644 index 6ff931b15..000000000 --- a/CodingStyle +++ /dev/null @@ -1,132 +0,0 @@ -LTTng-Tools Coding Style - -Author: David Goulet -Last Update: 13/11/2012 - -Tabs VS Spaces: -------------- - -Right, so our two cents in this endless war! This project uses TABS for one -simple reason, the coder can choose whatever size or type his/her indentation -is and can set the prefered coding style by replacing the tabs which each -normally respected IDE/editor can do. - -For vim, here is what I used: - - set shiftwidth=4 - set noexpandtab - -There is one exception for which we use space in this project is for enum, -defines and macros values indentation. For instance: - -Use space to indent the the value so they fit when reading them all. Same goes -for the #define below. - -enum my_enum { - value1 = 1, - value289 = 289, - ... -}; - -#define DEFAULT_VALUE_OF_SOME_SORT 6 -#define THE_ANSWER 42 - -Use either a single space or tabs to indent the '\' at the end of lines. -Use tabs at the beginning of lines. - -Either: - -#define a_macro(x) \ - do { \ - fsync(); \ - } while (0) - -or - -#define a_macro(x) \ - do { \ - fsync(); \ - } while (0) - -Here is a pretty cool vim macro that will highlight your whitespaces and spaces -before tab. This helps a *LOT* when coding. - -" Show trailing whitepace and spaces before a tab: -function MyTrail() - let no_hl_trail = ["man", "help"] - if index(no_hl_trail, &ft) >= 0 - return - endif - syn match ErrorMsg /\s\+$\| \+\ze\t\|\t\+\ze / containedin=@NoTrail -endfunction -syn cluster NoTrail contains=ALL remove=cComment -autocmd Syntax * call MyTrail() - -C Style: -------------- - -The coding style used for this project follows the the Linux kernel guide -lines, except that brackets "{", "}" should typically be used even for -single-line if/else statements. Please refer to: - -- doc/kernel-CodingStyle.txt (copied from Linux 3.4.4 git tree). - -- Linux kernel scripts/checkpatch.pl for a script which verify the patch - coding style. - -For header files, please declare the following in this order: - -1) #defines - - Default values should go in: src/common/defaults.h - - Macros used across the project: src/common/macros.h - -2) Variables - - No _static_ in a header file! This is madness. - - Use _extern_ if the global variable is set else where. - -3) Function prototype - -Furthermore, respect the name spacing of files for each non-static symbol -visiable outside the scope of the C file. For instance, for the utils.c file in -libcommon, every call should be prefixed by "utils_*". - -Error handling: -------------- - -We ask to use one single return point in a function. For that, we uses the -"goto" statement for the error handling creating one single point for error -handling and return code. See the following example: - -int some_function(...) -{ - int ret; - [...] - - if (ret != 0) { - goto error; - } - - [...] -error: - return ret; -} - -Commenting: -------------- - -Every function MUST have a comment above it even if the function is trivial. - -Please add non-trivial comments/documentation as much as you can in the code. -Poor comments WILL be rejected upon merging so please pay attention to this -details because we do! - -If the comments requires more than one line, please format like so: - -/* - * Some comments which requires multiple - * lines [...] - */ - -and on a single line: - -/* My comment on a single line. */ diff --git a/CodingStyle.md b/CodingStyle.md new file mode 100644 index 000000000..0aac92471 --- /dev/null +++ b/CodingStyle.md @@ -0,0 +1,318 @@ +# Coding style guide + +It is said that there is no accounting for taste. However, when it comes to code, we are of the opinion that a _consistent_ style makes it easier to collaborate in a shared code base. + +Style guidelines are bound to be controversial. Some conventions laid out in this guide have objective merit. However, most boil down to personal preferences of the original authors. + +As such, this guide attempts to lay out the conventions used in the project so that new contributors can easily conform to them and minimize time lost during code review. + +Contributions are expected to adhere to these guidelines. + +## C++ + +### Migration from C + +As the LTTng-tools project aims at supporting a broad range of compilers -- currently starting from GCC 4.8 and Clang 3.3 -- its build system is configured to use the C++11 standard. + +LTTng-tools has historically been developped in C99 with liberal uses of GNU extensions. Since the release of LTTng 2.13, it has started a migration to C++. + +In order to ease the transition, it underwent an initial migration phase which had a limited scope: build all existing C code as C++11. + +As such, most of the project's code does not qualify as idiomatic C++ code. This migration is ongoing and expected to span across multiple release cycles. + +However, new contributions are expected to conform the C++ style described in this guide. Some exceptions are allowed for small fixes which have to be back-ported to stable branches. + +### Automated formatting + +All the project's C++ files follow the [clang-format](https://clang.llvm.org/docs/ClangFormat.html) [style](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) of the `.clang-format` file for whitespaces, indentation, and line breaks. + +You _must_ format your changes with clang-format before you contribute a patch. + +Note that clang-format 14 is required to use the project's `.clang-format` file. + +Most text editors allow you to format a sub-section of a source file using clang-format to ensure it adheres to the project's style. + +If you are submitting a change to existing source files, _do not run clang-format on the whole file_ as this may introduce more changes than you intended and _will_ cause your changes to be rejected. + +### Tabs VS Spaces + +While our founding mothers and fathers eschewed any consideration for non-English languages when designing the ASCII character encoding they, in a rare moment of technical decadence, decided to dedicate a character to the sole purpose of expressing tabulations. + +This project makes use of this character to express indentations in its source files. + +Note that while tab characters are used for semantic indentation purposes, spaces are perfectly fine to use for _visual_ alignment (e.g. ascii diagrams). + +### Single line control flow statements + +Single line control flow statements (if/for/while) are required to use braces. + +```cpp +/* bad */ +if (my_thingy) + do_the_thing(); + +/* good */ +if (my_thingy) { + do_the_thing(); +} +``` + +### Naming + +- Use snake case (e.g. `a_snake_case_name`) except for template parameters, which use camel case and end with `Type` (e.g. `ACamelCaseNameType`). + +- Prefer using explicit and verbose names. For instance: + - When naming a variable that indicates a count of bananas, prefer `banana_count` to `bananas`, `count`, or `n`. + - When naming a function or method that validates and initializes a user profile, prefer `validate_and_initialize_user_profile()` to `set_up()`, `viup()`, `do_user_profile()`, `init()`. + +- Avoid the use of overly generic terms like `data`, `ptr`, and `buffer`. + +- Use an underscore prefix for private or protected methods and members, and member type names: `_try_connect()`, `class _user_count`, `int _version`. + +- Name trivial setters and getters like the property name, without a verb (e.g. `set` and `get` prefixes). + + ```cpp + /* good, gets the session's name. */ + session.name(); + /* good, sets the session's name. */ + session.name("my new name"); + + /* good, non-trivial accessor */ + session.add_channel(my_channel); + ``` + +- Use the `is` or `has` prefixes to name boolean properties or functions which return a `bool` type. + +- Do not make-up abbreviations to shorten names. Term of art abbreviations are, however, acceptable. For example: `mpeg`, `ctf`, `cfg`, `init` are accepted. A notable exception to this rule applies to namespaces, see the "Use of namespaces/Aliases" section. + +### Comments + +In general, comments should focus on _why_ something is done and document the assumptions the code was built upon. They should not repeat what it does in plain english except if the code is particularily complex. Keep in mind that what may be obvious to you right now may not be obvious to reviewers... or your future self. + +Also, write comments in grammatically-sound English and avoid writing using telegraph style: + +```cpp +/* Bad: init cfg */ + +/* Bad: init cfg before reply */ + +/* Good: The configuration must be initialized before replying since it initializes the user's credentials. */ +``` + +### Include guards + +Header files must use include guards to prevent multiple inclusion issues. To avoid collisions, the name of include guards must be as specific as possible and include the name of the file. + +```cpp +/* In file thingy-handler.hpp */ + +#ifndef LTTNG_CONSUMERD_THINGY_HANDLER +#define LTTNG_CONSUMERD_THINGY_HANDLER + +/* Some briliant code. */ + +#endif /* LTTNG_CONSUMERD_THINGY_HANDLER */ +``` + + +### Use of namespaces + +Make liberal use of namespaces. Very little should be available in the `lttng`, +let alone global, namespace. + +Moreover, prefer to use anonymous namespaces to the `static` keyword to restrict the visibility of a symbol to its translation unit. + +#### Do not pollute the global namespace + +Never use the `using` directive to import the contents of a namespace. If a namespace is used often in a file, define an alias. + +#### Aliases + +Within a translation unit, it is acceptable to abbreviate commonly-used namespace names to define an alias. For instance, the file containing the implementation of the `food::fruits::citrus::grapefruit` can use the `ffc` namespace alias for brievety. + +```cpp +/* In file grapefruit.cpp */ + +namespace ffc = food::fruits::citrus; + +ffc::grapefruit::grapefruit() +{ + // ... +} +``` + +### File layout example + +```cpp +/* + * Copyright (C) 20xx Robert Binette + * + * SPDX-License-Identifier: GPL-2.0-only + * + */ + +#ifndef LTTNG_THING_DOER_H +#define LTTNG_THING_DOER_H + +/* Mind the order of inclusions, in alphabetical order per category. */ + +/* Project-local headers. */ +#include "my-local-stuff.hpp" +#include "utils.hpp" + +/* Project-wide headers. */ +#include + +/* System headers. */ +#include +#include +#include + +namespace lttng { +namespace sessiond { + +class things; + +using on_new_name_function = std::function; + +class thing_doer : public lttng::sessiond::doer { +public: + explicit thing_doer(const std::string& name); + + void do() override final; + const std::string& name() const; + +private: + unsigned int _count_things(std::vector) const noexcept; + + const std::string _name; +}; + +} /* namespace sessiond */ +} /* namespace lttng */ + +#endif /* LTTNG_THING_DOER_H */ +``` + +### Miscelaneous guidelines + +In general, the project’s contributors make an effort to follow, for C++11 code: + +[The C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) + +[Scott Meyers’s “Effective Modern C++”](https://www.oreilly.com/library/view/effective-modern-c/9781491908419/) + +Here are a couple of reminders: +* When defining a class, put constructors as the first methods, whatever their access (public/protected/private), then the destructor, and then the rest. + +* Declare variables as close to where they are used as possible. + +* Use auto when possible. + +* Use const as much as possible, even for pointer (const char* const) and numeric values (const unsigned int) which never need to change. + +* Make methods const noexcept or const as much as possible. + +* Make constructors explicit unless you really need an implicit constructor (which is rare). + +* Use `std::unique_ptr` to manage memory when possible. + * However, use references (`*my_unique_ptr`) and raw pointers (`my_unique_ptr.get()`) when not transferring ownership. + * Only use `std::shared_ptr` when ownership is conceptually shared. + +* Use `nullptr`, not `NULL` nor `0`. + +* Return by value (rvalue) instead of by output parameter (non-const lvalue reference), even complex objects, unless you can prove that the performance is improved when returning by parameter. + +* For a function parameter or a return value of which the type needs to be a reference or pointer, use: + * **If the value is mandatory**, a reference. + * **If the value is optional**, a raw pointer. + +* Don't use `std::move()` when you already have an rvalue, which means: + * Don't write `return std::move(...);` as this can interfere with RVO (Return Value Optimization). + * Don't use `std::move()` with a function call (`std::move(func())`). + +* For each possible move/copy constructor or assignment operator, do one of: + * Write a custom one. + * Mark it as defaulted (`default`) + * Mark it as deleted (`delete`). + +* Use scoped enumerations (`enum class`). + +* Mark classes known to be final with the `final` keyword. + +* Use type aliases (`using`), not type definitions (`typedef`). + +* Use anonymous namespaces for local functions instead of `static`. + +* Return a structure with named members instead of a generic container such as `std::pair` or `std::tuple`. + +* When a class inherits a base class with virtual methods, use the `override` keyword to mark overridden virtual methods, and do not use the `virtual` keyword again (as the method is already known to be virtual). + +* Define overloaded operators only if their meaning is obvious, unsurprising, and consistent with the corresponding built-in operators. + + For example, use `|` as a bitwise or logical-or, not as a shell-style pipe. + +* Use RAII wrappers when managing system resources or interacting with C libraries. + + In other words, don't rely on ``goto``s and error labels to clean up as you would do in C. + +* Throw an exception when there's an unexpected, exceptional condition, + [including from a constructor](https://isocpp.org/wiki/faq/exceptions#ctors-can-throw), instead of returning a status code. + + However, be mindful of the exception-safety of your users. For instance, `liblttng-ctl` exposes a C interface meaning that is must catch and handle all exceptions, most likely by returning a suitable error code. + +* Accept a by-value parameter and move it (when it's moveable) when you intend to copy it anyway. You can do this with most STL containers. + +## Python + +Python code should be formatted using [black](https://github.com/psf/black). + +## Shell (BASH) + +New scripts and modifications to existing scripts should pass linting +with [Shellcheck](https://www.shellcheck.net/). + +## C Style (historical) + +The coding style used for this project follows the the Linux kernel guide lines, except that brackets `{`, `}` should typically be used even for single-line if/else statements. Please refer to: + +- doc/kernel-CodingStyle.txt (copied from the Linux 3.4.4 tree). + +- Linux kernel scripts/checkpatch.pl for a script which verify the patch + coding style. + +For header files, please declare the following in this order: + +1) `#define` + + - Default values should go in: src/common/defaults.h + - Macros used across the project: src/common/macros.h + +2) Variables + + - No _static_ in a header file! This is madness. + - Use _extern_ if the global variable is set else where. + +3) Function prototype + +Furthermore, respect the name spacing of files for each non-static symbol visiable outside the scope of the C file. For instance, for the utils.c file in libcommon, every call should be prefixed by "utils_*". + +### Error handling + +In legacy C-style code, we ask to use one single return point in a function. For that, we uses the "goto" statement for the error handling creating one single point for error handling and return code. See the following example: + +```c +int some_function(...) +{ + int ret; + [...] + + if (ret != 0) { + goto error; + } + + [...] +error: + return ret; +} +``` diff --git a/Makefile.am b/Makefile.am index 636296e46..040d9df6c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -14,9 +14,10 @@ dist_doc_DATA = LICENSE \ ChangeLog \ README.adoc -dist_noinst_DATA = CodingStyle +dist_noinst_DATA = CodingStyle.md EXTRA_DIST = extras/lttng-bash_completion \ + extras/zsh-completion \ LICENSES/BSD-2-Clause \ LICENSES/BSD-3-Clause \ LICENSES/GPL-2.0 \ diff --git a/README.adoc b/README.adoc index 830dd933e..676467aa4 100644 --- a/README.adoc +++ b/README.adoc @@ -16,7 +16,7 @@ endif::env-github[] 5 May 2020 [.normal] -https://ci.lttng.org/job/lttng-tools_master_build/[image:https://img.shields.io/jenkins/s/https/ci.lttng.org/lttng-tools_master_build.svg[Jenkins, title="Jenkins"]] +https://ci.lttng.org/job/lttng-tools_master_linuxbuild/[image:https://img.shields.io/jenkins/build.svg?jobUrl=https://ci.lttng.org/job/lttng-tools_master_linuxbuild/[Jenkins, title="Jenkins"]] https://scan.coverity.com/projects/lttng-tools[image:https://img.shields.io/coverity/scan/lttng-tools.svg[Coverity, title="Coverity"]] [.lead] @@ -54,7 +54,7 @@ components: * **Linux kernel{nbsp}≥{nbsp}2.6.30** -* **http://www.liburcu.org/[Userspace{nbsp}RCU]{nbsp}≥{nbsp}0.11.0**. +* **http://www.liburcu.org/[Userspace{nbsp}RCU]{nbsp}≥{nbsp}0.14.0**. + Debian/Ubuntu package: `liburcu{nbh}dev`. @@ -72,16 +72,14 @@ The following dependencies are optional: of the https://lttng.org/man/1/lttng-view/[`lttng view`] command, `make{nbsp}check` and tests. + -Debian/Ubuntu package: `babeltrace2` +Debian/Ubuntu package: `babeltrace2 libbabeltrace2-dev` * **https://lttng.org/[LTTng{nbh}UST]** (same minor version as {lt}): LTTng user space tracing (applications and libraries). + Debian/Ubuntu package: `liblttng{nbh}ust{nbh}dev` -* **Perl**: `make{nbsp}check` and tests. - -* **https://www.python.org/[Python]{nbsp}≥{nbsp}3.0**: +* **https://www.python.org/[Python]{nbsp}≥{nbsp}3.4**: `make{nbsp}check` and tests. + Debian/Ubuntu package: `python3` @@ -133,7 +131,7 @@ information on versioning. You need the following tools to build {lt}: * **https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html[GNU{nbsp}Autotools]** - (**Automake{nbsp}≥{nbsp}1.10**, + (**Automake{nbsp}≥{nbsp}1.12**, **Autoconf{nbsp}≥{nbsp}2.64**, and **Autoheader{nbsp}≥{nbsp}2.50**) * **http://www.gnu.org/software/autoconf/[GNU{nbsp}Libtool]{nbsp}≥{nbsp}2.2** @@ -144,7 +142,7 @@ You need the following tools to build {lt}: To build the {lt} manual pages: -* **https://www.methods.co.nz/asciidoc/[AsciiDoc]{nbsp}≥{nbsp}8.4.5** +* **https://asciidoc.org/[AsciiDoc]{nbsp}≥{nbsp}8.4.5** + NOTE: Previous versions could work, but were not tested. @@ -223,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:: @@ -245,3 +258,6 @@ Continuous integration:: Code review:: https://review.lttng.org/q/project:lttng-tools[_lttng{nbh}tools_ project] on LTTng Review + +Contributor's guide:: + https://github.com/lttng/lttng-tools/blob/master/CONTRIBUTING.md \ No newline at end of file diff --git a/configure.ac b/configure.ac index a34e25f21..0a4d726d7 100644 --- a/configure.ac +++ b/configure.ac @@ -90,8 +90,9 @@ m4_define([WARN_FLAGS_C_LIST], [ dnl -Wdiscarded-qualifiers dnl -Wmissing-prototypes dnl -Wmissing-parameter-type dnl - -Wjump-misses-init dnl - -Wnested-externs dnl + -Wsuggest-final-types dnl + -Wsuggest-final-methods dnl + -Wsuggest-override dnl ]) # Pass -Werror as an extra flag during the test: this is needed to make the @@ -156,19 +157,23 @@ 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 # Check for objcopy, required by the base address statedump and dynamic linker tests -AC_CHECK_TOOL([OBJCOPY], [objcopy], [no]) -AS_IF([test "x$OBJCOPY" = "xno"], +AC_CHECK_TOOL([OBJCOPY], [objcopy]) +AS_IF([test "x$OBJCOPY" = "x"], [AC_MSG_WARN([Cannot find objcopy. The base address statedump and dynamic linker tests will be disabled. Install the binutils package to remediate this.])] ) -AM_CONDITIONAL([HAVE_OBJCOPY], [test "x$OBJCOPY" != xno]) +AM_CONDITIONAL([HAVE_OBJCOPY], [test "x$OBJCOPY" != "x"]) # check for pgrep -AC_PATH_PROG([PGREP], [pgrep], [no]) -AM_CONDITIONAL([HAVE_PGREP], [test "x$PGREP" != "xno"]) +AC_PATH_PROG([PGREP], [pgrep]) +AM_CONDITIONAL([HAVE_PGREP], [test "x$PGREP" != "x"]) + +AC_PATH_PROG([SHELLCHECK], [shellcheck]) +AM_CONDITIONAL([HAVE_SHELLCHECK], [test "x$SHELLCHECK" != "x"]) # set $IN_GIT_REPO if we're in the Git repository; the `bootstrap` file # is not distributed in tarballs @@ -299,7 +304,7 @@ AC_CHECK_HEADERS([ \ signal.h stdlib.h sys/un.h sys/socket.h stdlib.h stdio.h \ getopt.h sys/ipc.h sys/shm.h popt.h grp.h arpa/inet.h \ netdb.h netinet/in.h paths.h stddef.h sys/file.h sys/ioctl.h \ - sys/mount.h sys/param.h sys/time.h elf.h + sys/mount.h sys/param.h sys/time.h elf.h sys/random.h sys/syscall.h ]) AM_CONDITIONAL([HAVE_ELF_H], [test x$ac_cv_header_elf_h = xyes]) @@ -311,7 +316,8 @@ AC_CHECK_FUNCS([ \ mkdir munmap putenv realpath rmdir socket strchr strcspn strdup \ strncasecmp strndup strnlen strpbrk strrchr strstr strtol strtoul \ strtoull dirfd gethostbyname2 getipnodebyname epoll_create1 \ - sched_getcpu sysconf sync_file_range + sched_getcpu sysconf sync_file_range getrandom posix_fadvise \ + arc4random flock ]) # Check for pthread_setname_np and pthread_getname_np @@ -652,7 +658,7 @@ AM_CONDITIONAL([PYTHON_BINDING], [test "x$enable_python_binding" = xyes]) if test "x$enable_python_binding" = xyes; then AX_PKG_SWIG($swig_version, [], [ AC_MSG_ERROR([SWIG $swig_version or newer is needed]) ]) AS_IF([test x$enable_shared = xno], [ AC_MSG_ERROR([Python bindings require shared libraries.]) ]) - AM_PATH_PYTHON([3.0]) + AM_PATH_PYTHON([3.4]) AC_ARG_VAR([PYTHON_INCLUDE], [Include flags for python, bypassing python-config]) AC_ARG_VAR([PYTHON_CONFIG], [Path to python-config]) @@ -660,9 +666,9 @@ if test "x$enable_python_binding" = xyes; then AS_IF([test -z "$PYTHON_CONFIG"], [ AC_PATH_PROGS([PYTHON_CONFIG], [python$PYTHON_VERSION-config python-config], - [no], + [], [`dirname $PYTHON`]) - AS_IF([test "$PYTHON_CONFIG" = no], [AC_MSG_ERROR([cannot find python-config for $PYTHON. Do you have python-dev installed?])]) + AS_IF([test "x$PYTHON_CONFIG" = "x"], [AC_MSG_ERROR([cannot find python-config for $PYTHON. Do you have python-dev installed?])]) ]) AC_MSG_CHECKING([python include flags]) PYTHON_INCLUDE=`$PYTHON_CONFIG --includes` @@ -750,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, @@ -766,10 +797,10 @@ have_asciidoc_xmlto=no warn_prebuilt_man_pages=no AS_IF([test "x$man_pages_opt" = "xyes"], [ - AC_PATH_PROG([ASCIIDOC], [asciidoc], [no]) - AC_PATH_PROG([XMLTO], [xmlto], [no]) + AC_PATH_PROG([ASCIIDOC], [asciidoc]) + AC_PATH_PROG([XMLTO], [xmlto]) - AS_IF([test "x$ASCIIDOC" = "xno" || test "x$XMLTO" = "xno"], [ + AS_IF([test "x$ASCIIDOC" = "x" || test "x$XMLTO" = "x"], [ AS_IF([test "x$in_git_repo" = "xyes"], [ # this is an error because we're in the Git repo, which # means the man pages are not already generated for us, @@ -812,8 +843,8 @@ AS_IF([test "x$embedded_help" = "xyes"], [ AS_IF([test "x$man_pages_opt" = "xno"], [ AC_MSG_ERROR([You need the --enable-man-pages option with the --enable-embedded-help option.]) ]) - AC_PATH_PROG([man_prog_path], [man], [no]) - AS_IF([test "x$man_prog_path" = "xno"], [ + AC_PATH_PROG([man_prog_path], [man]) + AS_IF([test "x$man_prog_path" = "x"], [ AC_MSG_ERROR([You need man with the --enable-embedded-help option.]) ]) AC_DEFINE_UNQUOTED([LTTNG_EMBED_HELP], 1, [Embed --help messages.]) @@ -948,6 +979,9 @@ AS_IF([test "$test_sdt_uprobe" = "autodetect"], [ AM_CONDITIONAL([TEST_SDT_UPROBE], [test "$test_sdt_uprobe" = "yes"]) +AC_ARG_ENABLE([lib-lttng-ctl], AS_HELP_STRING([--disable-lib-lttng-ctl], + [Disable the build of liblttng-ctl (only possible if no binaries that depend on it are built)])) + # Arguments for binaries build exclusion AC_ARG_ENABLE([bin-lttng], AS_HELP_STRING([--disable-bin-lttng],[Disable the build of lttng binaries])) AC_ARG_ENABLE([bin-lttng-consumerd], AS_HELP_STRING([--disable-bin-lttng-consumerd], @@ -1018,11 +1052,23 @@ AS_IF([test x$enable_bin_lttng_sessiond != xno], ) # Libraries dependencies enabling +# If we want to build liblttng-ctl +AS_IF([test x$enable_lib_lttng_ctl != xno], + [ + build_lib_lttng_ctl=yes + ] +) +# If we need to build liblttng-ctl because a binary depends on it AS_IF([test x$build_lib_lttng_ctl = xyes], [ build_lib_sessiond_comm=yes ] ) +# Fail if we didn't want to build liblttng-ctl but need to build it anyway +AS_IF([test "x$build_lib_lttng_ctl" = "xyes" -a "x$enable_lib_lttng_ctl" = "xno"],[ + AC_MSG_FAILURE( + [liblttng-ctl must be built, because at least one binary that depends on it is enabled]) +]) AS_IF([test x$build_lib_consumer = xyes], [ @@ -1119,6 +1165,13 @@ test "x$enable_bin_lttng_sessiond" != "xno"], ) AM_CONDITIONAL([BUILD_TESTS], [test x$build_tests = xyes]) + +AS_IF([test "x$build_tests" = "xyes"], + [ + PKG_CHECK_MODULES([babeltrace2], [babeltrace2]) + ] +) + AM_CONDITIONAL([BUILD_EXTRAS], [test x$enable_extras != xno]) # Export libraries build conditions. @@ -1176,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 @@ -1202,6 +1258,7 @@ AC_CONFIG_FILES([ src/vendor/msgpack/Makefile tests/Makefile tests/destructive/Makefile + tests/meta/Makefile tests/regression/Makefile tests/regression/kernel/Makefile tests/regression/tools/Makefile @@ -1234,6 +1291,8 @@ AC_CONFIG_FILES([ tests/regression/tools/trigger/utils/Makefile tests/regression/tools/trigger/name/Makefile tests/regression/tools/trigger/hidden/Makefile + tests/regression/tools/context/Makefile + tests/regression/tools/client/Makefile tests/regression/ust/Makefile tests/regression/ust/nprocesses/Makefile tests/regression/ust/high-throughput/Makefile @@ -1261,17 +1320,24 @@ AC_CONFIG_FILES([ tests/regression/ust/rotation-destroy-flush/Makefile tests/regression/ust/blocking/Makefile tests/regression/ust/namespaces/Makefile + tests/regression/ust/ust-constructor/Makefile tests/stress/Makefile tests/unit/Makefile tests/unit/ini_config/Makefile tests/perf/Makefile tests/utils/Makefile + tests/utils/bt2_plugins/Makefile + tests/utils/bt2_plugins/event_name/Makefile + tests/utils/bt2_plugins/field_stats/Makefile + tests/utils/lttngtest/Makefile tests/utils/tap/Makefile tests/utils/testapp/Makefile + tests/utils/testapp/gen-data-pending/Makefile tests/utils/testapp/gen-ns-events/Makefile tests/utils/testapp/gen-kernel-test-events/Makefile tests/utils/testapp/gen-py-events/Makefile tests/utils/testapp/gen-ust-events/Makefile + tests/utils/testapp/gen-ust-events-constructor/Makefile tests/utils/testapp/gen-ust-events-ns/Makefile tests/utils/testapp/gen-syscall-events-callstack/Makefile tests/utils/testapp/gen-ust-nevents/Makefile @@ -1289,6 +1355,7 @@ AC_CONFIG_FILES([tests/regression/ust/python-logging/test_python_logging],[chmod # Inject LTTNG_TOOLS_BUILD_WITH_LIBPFM variable in test script. AC_CONFIG_FILES([tests/perf/test_perf_raw],[chmod +x tests/perf/test_perf_raw]) AC_CONFIG_FILES([tests/regression/ust/ust-dl/test_ust-dl],[chmod +x tests/regression/ust/ust-dl/test_ust-dl]) +AC_CONFIG_FILES([pre-inst-env],[chmod +x pre-inst-env]) AC_OUTPUT @@ -1334,6 +1401,13 @@ PPRINT_PROP_BOOL([libkmod support], $value) test "x$with_lttng_ust" = "xyes" && value=1 || value=0 PPRINT_PROP_BOOL([LTTng-UST support], $value) +AS_ECHO +PPRINT_SUBTITLE([Libraries]) + +# liblttng-ctl enabled/disabled +test x$build_lib_lttng_ctl != xno && value=1 || value=0 +PPRINT_PROP_BOOL([liblttng-ctl], $value) + AS_ECHO PPRINT_SUBTITLE([Binaries]) @@ -1420,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/doc/examples/rotation/rotate-client-example.c b/doc/examples/rotation/rotate-client-example.c index a5ee70da3..1f9070a04 100644 --- a/doc/examples/rotation/rotate-client-example.c +++ b/doc/examples/rotation/rotate-client-example.c @@ -32,6 +32,8 @@ */ #include + +#include #include #include #include @@ -44,7 +46,10 @@ static volatile int quit = 0; static void sighandler(int signal __attribute__((unused))) { - printf("Signal caught, exiting\n"); + const char msg[] = "Signal caught, exiting\n"; + const int ret = write(STDOUT_FILENO, msg, sizeof(msg)); + + assert(ret == 0); /* NOLINT assert is not async signal safe */ quit = 1; } @@ -76,8 +81,7 @@ static int setup_session(const char *session_name, const char *path) strcpy(ev.name, "*"); ev.loglevel_type = LTTNG_EVENT_LOGLEVEL_ALL; - ret = lttng_enable_event_with_exclusions( - chan_handle, &ev, "mychan", NULL, 0, NULL); + ret = lttng_enable_event_with_exclusions(chan_handle, &ev, "mychan", NULL, 0, NULL); if (ret < 0) { fprintf(stderr, "Failed to enable events (ret = %i)\n", ret); goto end; @@ -153,16 +157,14 @@ static int rotate_session(const char *session_name, const char *ext_program) ret = lttng_rotate_session(session_name, NULL, &handle); if (ret < 0) { - fprintf(stderr, "Failed to rotate session, %s\n", - lttng_strerror(ret)); + fprintf(stderr, "Failed to rotate session, %s\n", lttng_strerror(ret)); goto end; } fflush(stdout); do { - rotation_status = lttng_rotation_handle_get_state( - handle, &rotation_state); + rotation_status = lttng_rotation_handle_get_state(handle, &rotation_state); if (rotation_status != LTTNG_ROTATION_STATUS_OK) { ret = -1; fprintf(stderr, "Failed to get the current rotation's state\n"); @@ -189,27 +191,24 @@ static int rotate_session(const char *session_name, const char *ext_program) const char *absolute_path; enum lttng_trace_archive_location_status location_status; - rotation_status = lttng_rotation_handle_get_archive_location( - handle, &location); + rotation_status = lttng_rotation_handle_get_archive_location(handle, &location); if (rotation_status != LTTNG_ROTATION_STATUS_OK) { - fprintf(stderr, "Failed to retrieve the rotation's completed chunk archive location\n"); + fprintf(stderr, + "Failed to retrieve the rotation's completed chunk archive location\n"); ret = -1; goto end; } - location_status = - lttng_trace_archive_location_local_get_absolute_path( - location, &absolute_path); + location_status = lttng_trace_archive_location_local_get_absolute_path( + location, &absolute_path); if (location_status != LTTNG_TRACE_ARCHIVE_LOCATION_STATUS_OK) { fprintf(stderr, "Failed to get absolute path of completed chunk archive"); ret = -1; goto end; } - printf("Output files of session %s rotated to %s\n", - session_name, absolute_path); - ret = snprintf(cmd, PATH_MAX, "%s %s", ext_program, - absolute_path); + printf("Output files of session %s rotated to %s\n", session_name, absolute_path); + ret = snprintf(cmd, PATH_MAX, "%s %s", ext_program, absolute_path); if (ret < 0) { fprintf(stderr, "Failed to prepare command string\n"); goto end; @@ -219,20 +218,22 @@ static int rotate_session(const char *session_name, const char *ext_program) } case LTTNG_ROTATION_STATE_EXPIRED: printf("Output files of session %s rotated, but the handle expired\n", - session_name); + session_name); ret = 0; goto end; case LTTNG_ROTATION_STATE_ERROR: - fprintf(stderr, "An error occurred with the rotation of session %s\n", - session_name); + fprintf(stderr, + "An error occurred with the rotation of session %s\n", + session_name); ret = -1; goto end; case LTTNG_ROTATION_STATE_ONGOING: abort(); goto end; case LTTNG_ROTATION_STATE_NO_ROTATION: - fprintf(stderr, "No rotation was performed on rotation request for session %s\n", - session_name); + fprintf(stderr, + "No rotation was performed on rotation request for session %s\n", + session_name); ret = -1; goto end; } @@ -260,16 +261,15 @@ end: static void usage(const char *prog_name) { - fprintf(stderr, "Usage: %s \n", - prog_name); + fprintf(stderr, "Usage: %s \n", prog_name); fprintf(stderr, " : the name of the session you want to create\n"); fprintf(stderr, " : the delay in seconds between each rotation\n"); fprintf(stderr, - " : the number of rotation you want to perform, " - "-1 for infinite until ctrl-c\n"); + " : the number of rotation you want to perform, " + "-1 for infinite until ctrl-c\n"); fprintf(stderr, - " : program to run on each chunk, it must be " - "executable, and expect a trace folder as only argument\n"); + " : program to run on each chunk, it must be " + "executable, and expect a trace folder as only argument\n"); fprintf(stderr, "\nThe trace folder is deleted when this program completes.\n"); } diff --git a/doc/examples/trigger-condition-event-matches/instrumented-app.c b/doc/examples/trigger-condition-event-matches/instrumented-app.c index 465b4a123..6148d1c09 100644 --- a/doc/examples/trigger-condition-event-matches/instrumented-app.c +++ b/doc/examples/trigger-condition-event-matches/instrumented-app.c @@ -8,6 +8,7 @@ #include "tracepoint-trigger-example.h" #include + #include #include #include @@ -25,10 +26,10 @@ int main(void) gettimeofday(&tv, NULL); the_time = tv.tv_sec; - strftime(time_str, sizeof(time_str), "[%m-%d-%Y] %T", - localtime(&the_time)); + strftime(time_str, sizeof(time_str), "[%m-%d-%Y] %T", localtime(&the_time)); printf("%s.%ld - Tracing event \"trigger_example:my_event\"\n", - time_str, tv.tv_usec); + time_str, + tv.tv_usec); tracepoint(trigger_example, my_event, i); sleep(2); diff --git a/doc/examples/trigger-condition-event-matches/notification-client.cpp b/doc/examples/trigger-condition-event-matches/notification-client.cpp index bce5d815d..05c7387c2 100644 --- a/doc/examples/trigger-condition-event-matches/notification-client.cpp +++ b/doc/examples/trigger-condition-event-matches/notification-client.cpp @@ -5,6 +5,8 @@ * */ +#include + #include #include @@ -16,14 +18,12 @@ #include #include -#include - static int print_capture(const struct lttng_condition *condition, - const struct lttng_event_field_value *capture, - unsigned int indent_level); + const struct lttng_event_field_value *capture, + unsigned int indent_level); static int print_array(const struct lttng_condition *condition, - const struct lttng_event_field_value *array, - unsigned int indent_level); + const struct lttng_event_field_value *array, + unsigned int indent_level); static void indent(unsigned int indentation_level) { @@ -44,8 +44,7 @@ static void print_one_event_expr(const struct lttng_event_expr *event_expr) { const char *name; - name = lttng_event_expr_event_payload_field_get_name( - event_expr); + name = lttng_event_expr_event_payload_field_get_name(event_expr); printf("%s", name); break; @@ -55,8 +54,7 @@ static void print_one_event_expr(const struct lttng_event_expr *event_expr) { const char *name; - name = lttng_event_expr_channel_context_field_get_name( - event_expr); + name = lttng_event_expr_channel_context_field_get_name(event_expr); printf("$ctx.%s", name); break; @@ -67,10 +65,9 @@ static void print_one_event_expr(const struct lttng_event_expr *event_expr) const char *provider_name; const char *type_name; - provider_name = lttng_event_expr_app_specific_context_field_get_provider_name( - event_expr); - type_name = lttng_event_expr_app_specific_context_field_get_type_name( - event_expr); + provider_name = + lttng_event_expr_app_specific_context_field_get_provider_name(event_expr); + type_name = lttng_event_expr_app_specific_context_field_get_type_name(event_expr); printf("$app.%s:%s", provider_name, type_name); @@ -83,14 +80,12 @@ static void print_one_event_expr(const struct lttng_event_expr *event_expr) const struct lttng_event_expr *parent_expr; enum lttng_event_expr_status status; - parent_expr = lttng_event_expr_array_field_element_get_parent_expr( - event_expr); - LTTNG_ASSERT(parent_expr != NULL); + parent_expr = lttng_event_expr_array_field_element_get_parent_expr(event_expr); + LTTNG_ASSERT(parent_expr != nullptr); print_one_event_expr(parent_expr); - status = lttng_event_expr_array_field_element_get_index( - event_expr, &index); + status = lttng_event_expr_array_field_element_get_index(event_expr, &index); LTTNG_ASSERT(status == LTTNG_EVENT_EXPR_STATUS_OK); printf("[%u]", index); @@ -103,12 +98,10 @@ static void print_one_event_expr(const struct lttng_event_expr *event_expr) } } -static bool action_group_contains_notify( - const struct lttng_action *action_group) +static bool action_group_contains_notify(const struct lttng_action *action_group) { unsigned int i, count; - enum lttng_action_status status = - lttng_action_list_get_count(action_group, &count); + enum lttng_action_status status = lttng_action_list_get_count(action_group, &count); if (status != LTTNG_ACTION_STATUS_OK) { printf("Failed to get action count from action group\n"); @@ -116,10 +109,8 @@ static bool action_group_contains_notify( } for (i = 0; i < count; i++) { - const struct lttng_action *action = - lttng_action_list_get_at_index(action_group, i); - const enum lttng_action_type action_type = - lttng_action_get_type(action); + const struct lttng_action *action = lttng_action_list_get_at_index(action_group, i); + const enum lttng_action_type action_type = lttng_action_get_type(action); if (action_type == LTTNG_ACTION_TYPE_NOTIFY) { return true; @@ -129,22 +120,21 @@ static bool action_group_contains_notify( } static int print_capture(const struct lttng_condition *condition, - const struct lttng_event_field_value *capture, - unsigned int indent_level) + const struct lttng_event_field_value *capture, + unsigned int indent_level) { int ret = 0; enum lttng_event_field_value_status event_field_status; uint64_t u_val; int64_t s_val; double d_val; - const char *string_val = NULL; + const char *string_val = nullptr; switch (lttng_event_field_value_get_type(capture)) { case LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_INT: { event_field_status = - lttng_event_field_value_unsigned_int_get_value( - capture, &u_val); + lttng_event_field_value_unsigned_int_get_value(capture, &u_val); if (event_field_status != LTTNG_EVENT_FIELD_VALUE_STATUS_OK) { ret = 1; goto end; @@ -155,9 +145,7 @@ static int print_capture(const struct lttng_condition *condition, } case LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_INT: { - event_field_status = - lttng_event_field_value_signed_int_get_value( - capture, &s_val); + event_field_status = lttng_event_field_value_signed_int_get_value(capture, &s_val); if (event_field_status != LTTNG_EVENT_FIELD_VALUE_STATUS_OK) { ret = 1; goto end; @@ -169,8 +157,7 @@ static int print_capture(const struct lttng_condition *condition, case LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_ENUM: { event_field_status = - lttng_event_field_value_unsigned_int_get_value( - capture, &u_val); + lttng_event_field_value_unsigned_int_get_value(capture, &u_val); if (event_field_status != LTTNG_EVENT_FIELD_VALUE_STATUS_OK) { ret = 1; goto end; @@ -181,9 +168,7 @@ static int print_capture(const struct lttng_condition *condition, } case LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_ENUM: { - event_field_status = - lttng_event_field_value_signed_int_get_value( - capture, &s_val); + event_field_status = lttng_event_field_value_signed_int_get_value(capture, &s_val); if (event_field_status != LTTNG_EVENT_FIELD_VALUE_STATUS_OK) { ret = 1; goto end; @@ -194,8 +179,7 @@ static int print_capture(const struct lttng_condition *condition, } case LTTNG_EVENT_FIELD_VALUE_TYPE_REAL: { - event_field_status = lttng_event_field_value_real_get_value( - capture, &d_val); + event_field_status = lttng_event_field_value_real_get_value(capture, &d_val); if (event_field_status != LTTNG_EVENT_FIELD_VALUE_STATUS_OK) { ret = 1; goto end; @@ -206,8 +190,7 @@ static int print_capture(const struct lttng_condition *condition, } case LTTNG_EVENT_FIELD_VALUE_TYPE_STRING: { - event_field_status = lttng_event_field_value_string_get_value( - capture, &string_val); + event_field_status = lttng_event_field_value_string_get_value(capture, &string_val); if (event_field_status != LTTNG_EVENT_FIELD_VALUE_STATUS_OK) { ret = 1; goto end; @@ -233,31 +216,30 @@ end: return ret; } -static void print_unavailabe(void) +static void print_unavailabe() { printf("Capture unavailable"); } static int print_array(const struct lttng_condition *condition, - const struct lttng_event_field_value *array, - unsigned int indent_level) + const struct lttng_event_field_value *array, + unsigned int indent_level) { int ret = 0; enum lttng_event_field_value_status event_field_status; unsigned int captured_field_count; - event_field_status = lttng_event_field_value_array_get_length( - array, &captured_field_count); + event_field_status = lttng_event_field_value_array_get_length(array, &captured_field_count); if (event_field_status != LTTNG_EVENT_FIELD_VALUE_STATUS_OK) { ret = 1; goto end; } for (unsigned int i = 0; i < captured_field_count; i++) { - const struct lttng_event_field_value *captured_field = NULL; + const struct lttng_event_field_value *captured_field = nullptr; const struct lttng_event_expr *expr = - lttng_condition_event_rule_matches_get_capture_descriptor_at_index( - condition, i); + lttng_condition_event_rule_matches_get_capture_descriptor_at_index( + condition, i); LTTNG_ASSERT(expr); indent(indent_level + 1); @@ -266,20 +248,17 @@ static int print_array(const struct lttng_condition *condition, print_one_event_expr(expr); printf(" Value: "); - event_field_status = - lttng_event_field_value_array_get_element_at_index( - array, i, &captured_field); + event_field_status = lttng_event_field_value_array_get_element_at_index( + array, i, &captured_field); if (event_field_status != LTTNG_EVENT_FIELD_VALUE_STATUS_OK) { - if (event_field_status == - LTTNG_EVENT_FIELD_VALUE_STATUS_UNAVAILABLE) { + if (event_field_status == LTTNG_EVENT_FIELD_VALUE_STATUS_UNAVAILABLE) { print_unavailabe(); } else { ret = 1; goto end; } } else { - print_capture(condition, captured_field, - indent_level + 1); + print_capture(condition, captured_field, indent_level + 1); } if (i + 1 < captured_field_count) { @@ -297,25 +276,21 @@ end: static int print_captures(struct lttng_notification *notification) { int ret = 0; - const struct lttng_evaluation *evaluation = - lttng_notification_get_evaluation(notification); - const struct lttng_condition *condition = - lttng_notification_get_condition(notification); + const struct lttng_evaluation *evaluation = lttng_notification_get_evaluation(notification); + const struct lttng_condition *condition = lttng_notification_get_condition(notification); /* Status */ enum lttng_condition_status condition_status; enum lttng_evaluation_event_rule_matches_status evaluation_status; - const struct lttng_event_field_value *captured_field_array = NULL; + const struct lttng_event_field_value *captured_field_array = nullptr; unsigned int expected_capture_field_count; LTTNG_ASSERT(lttng_evaluation_get_type(evaluation) == - LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES); + LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES); - condition_status = - lttng_condition_event_rule_matches_get_capture_descriptor_count( - condition, - &expected_capture_field_count); + condition_status = lttng_condition_event_rule_matches_get_capture_descriptor_count( + condition, &expected_capture_field_count); if (condition_status != LTTNG_CONDITION_STATUS_OK) { ret = 1; goto end; @@ -326,9 +301,8 @@ static int print_captures(struct lttng_notification *notification) goto end; } - evaluation_status = - lttng_evaluation_event_rule_matches_get_captured_values( - evaluation, &captured_field_array); + evaluation_status = lttng_evaluation_event_rule_matches_get_captured_values( + evaluation, &captured_field_array); if (evaluation_status != LTTNG_EVALUATION_EVENT_RULE_MATCHES_STATUS_OK) { ret = 1; goto end; @@ -343,10 +317,8 @@ end: static int print_notification(struct lttng_notification *notification) { int ret = 0; - const struct lttng_evaluation *evaluation = - lttng_notification_get_evaluation(notification); - const enum lttng_condition_type type = - lttng_evaluation_get_type(evaluation); + const struct lttng_evaluation *evaluation = lttng_notification_get_evaluation(notification); + const enum lttng_condition_type type = lttng_evaluation_get_type(evaluation); switch (type) { case LTTNG_CONDITION_TYPE_SESSION_CONSUMED_SIZE: @@ -369,13 +341,12 @@ static int print_notification(struct lttng_notification *notification) char time_str[64]; struct timeval tv; time_t the_time; - const struct lttng_trigger *trigger = NULL; + const struct lttng_trigger *trigger = nullptr; - gettimeofday(&tv, NULL); + gettimeofday(&tv, nullptr); the_time = tv.tv_sec; - strftime(time_str, sizeof(time_str), "[%m-%d-%Y] %T", - localtime(&the_time)); + strftime(time_str, sizeof(time_str), "[%m-%d-%Y] %T", localtime(&the_time)); printf("%s.%ld - ", time_str, tv.tv_usec); trigger = lttng_notification_get_trigger(notification); @@ -391,7 +362,7 @@ static int print_notification(struct lttng_notification *notification) } printf("Received notification of event rule matches trigger \"%s\"\n", - trigger_name); + trigger_name); ret = print_captures(notification); break; } @@ -406,10 +377,10 @@ end: int main(int argc, char **argv) { int ret; - struct lttng_triggers *triggers = NULL; + struct lttng_triggers *triggers = nullptr; unsigned int count, i, j, subcription_count = 0, trigger_count; enum lttng_trigger_status trigger_status; - struct lttng_notification_channel *notification_channel = NULL; + struct lttng_notification_channel *notification_channel = nullptr; if (argc < 2) { fprintf(stderr, "Missing trigger name(s)\n"); @@ -420,8 +391,8 @@ int main(int argc, char **argv) trigger_count = argc - 1; - notification_channel = lttng_notification_channel_create( - lttng_session_daemon_notification_endpoint); + notification_channel = + lttng_notification_channel_create(lttng_session_daemon_notification_endpoint); if (!notification_channel) { fprintf(stderr, "Failed to create notification channel\n"); ret = -1; @@ -442,16 +413,13 @@ int main(int argc, char **argv) } for (i = 0; i < count; i++) { - const struct lttng_trigger *trigger = - lttng_triggers_get_at_index(triggers, i); + const struct lttng_trigger *trigger = lttng_triggers_get_at_index(triggers, i); const struct lttng_condition *condition = - lttng_trigger_get_const_condition(trigger); - const struct lttng_action *action = - lttng_trigger_get_const_action(trigger); - const enum lttng_action_type action_type = - lttng_action_get_type(action); + lttng_trigger_get_const_condition(trigger); + const struct lttng_action *action = lttng_trigger_get_const_action(trigger); + const enum lttng_action_type action_type = lttng_action_get_type(action); enum lttng_notification_channel_status channel_status; - const char *trigger_name = NULL; + const char *trigger_name = nullptr; bool subscribe = false; lttng_trigger_get_name(trigger, &trigger_name); @@ -467,28 +435,27 @@ int main(int argc, char **argv) } if (!((action_type == LTTNG_ACTION_TYPE_LIST && - action_group_contains_notify(action)) || - action_type == LTTNG_ACTION_TYPE_NOTIFY)) { + action_group_contains_notify(action)) || + action_type == LTTNG_ACTION_TYPE_NOTIFY)) { printf("The action of trigger \"%s\" is not \"notify\", skipping.\n", - trigger_name); + trigger_name); continue; } - channel_status = lttng_notification_channel_subscribe( - notification_channel, condition); - if (channel_status == - LTTNG_NOTIFICATION_CHANNEL_STATUS_ALREADY_SUBSCRIBED) { + channel_status = + lttng_notification_channel_subscribe(notification_channel, condition); + if (channel_status == LTTNG_NOTIFICATION_CHANNEL_STATUS_ALREADY_SUBSCRIBED) { continue; } if (channel_status) { - fprintf(stderr, "Failed to subscribe to notifications of trigger \"%s\"\n", - trigger_name); + fprintf(stderr, + "Failed to subscribe to notifications of trigger \"%s\"\n", + trigger_name); ret = -1; goto end; } - printf("Subscribed to notifications of trigger \"%s\"\n", - trigger_name); + printf("Subscribed to notifications of trigger \"%s\"\n", trigger_name); subcription_count++; } @@ -502,10 +469,8 @@ int main(int argc, char **argv) struct lttng_notification *notification; enum lttng_notification_channel_status channel_status; - channel_status = - lttng_notification_channel_get_next_notification( - notification_channel, - ¬ification); + channel_status = lttng_notification_channel_get_next_notification( + notification_channel, ¬ification); switch (channel_status) { case LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED: printf("Dropped notification\n"); @@ -524,7 +489,8 @@ int main(int argc, char **argv) printf("Notification channel was closed by peer.\n"); break; default: - fprintf(stderr, "A communication error occurred on the notification channel.\n"); + fprintf(stderr, + "A communication error occurred on the notification channel.\n"); ret = -1; goto end; } diff --git a/doc/examples/trigger-condition-event-matches/tracepoint-trigger-example.h b/doc/examples/trigger-condition-event-matches/tracepoint-trigger-example.h index e82e3c704..9aad47e7c 100644 --- a/doc/examples/trigger-condition-event-matches/tracepoint-trigger-example.h +++ b/doc/examples/trigger-condition-event-matches/tracepoint-trigger-example.h @@ -16,12 +16,10 @@ #include -TRACEPOINT_EVENT(trigger_example, my_event, - TP_ARGS(int, iteration), - TP_FIELDS( - ctf_integer(uint64_t, iteration, iteration) - ) -) +TRACEPOINT_EVENT(trigger_example, + my_event, + TP_ARGS(int, iteration), + TP_FIELDS(ctf_integer(uint64_t, iteration, iteration))) #endif /* _TRACEPOINT_TRIGGER_EXAMPLE_H */ diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 037d84d9f..8f20ede92 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -7,6 +7,9 @@ # function which adds the source directory prefix and adds a given suffix manaddsuffix = $(addsuffix $(1),$(addprefix $(srcdir)/,$(2))) +# Local targets. +LOCAL = + # List only the names without the .*.txt extension here: MAN1_NAMES = \ lttng \ @@ -113,7 +116,7 @@ MAN_H_RECIPE = \ %.8.h: %.8 $(MAN_H_RECIPE) -all-local: $(MAN_H) +LOCAL += $(MAN_H) CLEANFILES += $(MAN_H) endif # EMBED_HELP @@ -205,6 +208,27 @@ dist_man7_MANS += $(MAN7) dist_man8_MANS += $(MAN8) endif # MAN_PAGES_OPT +MAN_HIERARCHY = man1 man3 man7 man8 + +LOCAL += $(MAN_HIERARCHY) + +CLEANFILES += $(MAN_HIERARCHY) + +# Mimic mandb(8) path hierarchy -- as if installed -- by symlinking +# sub-directories to the top man directory. This allows developers to read +# the locally generated man pages. For example `$ ./pre-inst-env man lttng'. +man1: + @ln -s $(abs_builddir) $@ + +man3: + @ln -s $(abs_builddir) $@ + +man7: + @ln -s $(abs_builddir) $@ + +man8: + @ln -s $(abs_builddir) $@ + if !MAN_PAGES_OPT dist-hook: @echo "Error: Please enable the man pages before creating a distribution tarball." @@ -215,5 +239,8 @@ endif # !MAN_PAGES_OPT EXTRA_DIST = $(MAN_TXT) $(COMMON_TXT) $(XSL_FILE) \ $(ASCIIDOC_CONF) $(ASCIIDOC_ATTRS_CONF).in +# Build local targets. +all-local: $(LOCAL) + # keep generated man pages that can be considered intermediate files .PRECIOUS: %.1 %.3 %.7 %.8 diff --git a/doc/man/README.md b/doc/man/README.md index 1b0233b8e..ef1cd6555 100644 --- a/doc/man/README.md +++ b/doc/man/README.md @@ -4,7 +4,7 @@ LTTng-tools man pages This directory contains the sources of the LTTng-tools man pages. LTTng-tools man pages are written in -[AsciiDoc](http://www.methods.co.nz/asciidoc/), and then converted to +[AsciiDoc](https://asciidoc.org/), and then converted to DocBook (XML) using the `asciidoc` command, and finally to troff using the appropriate DocBook XSL stylesheet (using the `xmlto` command). diff --git a/doc/man/lttng-add-context.1.txt b/doc/man/lttng-add-context.1.txt index 49f0a7b03..d8cf42f96 100644 --- a/doc/man/lttng-add-context.1.txt +++ b/doc/man/lttng-add-context.1.txt @@ -55,7 +55,7 @@ channels. Repeat the option:--type='TYPE' option to add more than one context field to be recorded. 'TYPE' is one of: -* A statically-known, or built-in context field named. +* A statically-known, or built-in context field name. * A perf counter name: + diff --git a/doc/man/lttng-add-trigger.1.txt b/doc/man/lttng-add-trigger.1.txt index 656f87b4e..51f91c2ab 100644 --- a/doc/man/lttng-add-trigger.1.txt +++ b/doc/man/lttng-add-trigger.1.txt @@ -168,7 +168,7 @@ option:--action=**notify** [nloption:--rate-policy='POLICY'] {nbsp} + Sends a notification through the notification -mechanism of the session daemon (see man:lttng-session(8)). +mechanism of the session daemon (see man:lttng-sessiond(8)). + The session daemon sends details about the condition evaluation along with the notification. diff --git a/doc/man/lttng-destroy.1.txt b/doc/man/lttng-destroy.1.txt index 457808dab..4c610bb49 100644 --- a/doc/man/lttng-destroy.1.txt +++ b/doc/man/lttng-destroy.1.txt @@ -11,7 +11,7 @@ lttng-destroy - Destroy LTTng recording sessions SYNOPSIS -------- [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *destroy* [option:--no-wait] [option:--all | 'SESSION'] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *destroy* [option:--no-wait] [option:--all | option:--glob 'SESSION' | 'SESSION'] DESCRIPTION @@ -76,6 +76,9 @@ option:-a, option:--all:: man:lttng-list(1), instead of the current recording session or the recording session named 'SESSION'. +option:-g, option:--glob:: + Interpret SESSION as a globbing pattern. + option:-n, option:--no-wait:: Do :not: ensure that the trace data of the recording session(s) to destroy is valid before exiting. @@ -126,6 +129,16 @@ $ lttng destroy --all ---- ==== +.Destroy all recording sessions with the suffix foo. +==== +See the option:--glob option. + +[role="term"] +---- +$ lttng destroy --global '*foo' +---- +==== + include::common-footer.txt[] diff --git a/doc/man/lttng-list.1.txt b/doc/man/lttng-list.1.txt index e9c12ae43..7e6a95b3a 100644 --- a/doc/man/lttng-list.1.txt +++ b/doc/man/lttng-list.1.txt @@ -85,13 +85,13 @@ With the option:--jul, option:--log4j, and/or option:--python options:: Also list the available instrumentation point fields with the option:--fields option. -See man:lttng-concept(7) to learn more about recording sessions, tracing +See man:lttng-concepts(7) to learn more about recording sessions, tracing domains, channels, recording event rules, and instrumentation points. See the ``<>'' section below for usage examples. List the channels and recording event rules of the current recording -session (see man:lttng-concept(7) to learn more) with the +session (see man:lttng-concepts(7) to learn more) with the man:lttng-status(1) command. diff --git a/doc/man/lttng-start.1.txt b/doc/man/lttng-start.1.txt index b595b2f5c..f3ee0e785 100644 --- a/doc/man/lttng-start.1.txt +++ b/doc/man/lttng-start.1.txt @@ -11,7 +11,7 @@ lttng-start - Start an LTTng recording session SYNOPSIS -------- [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *start* ['SESSION'] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *start* [option::--all | option::--glob 'SESSION' | 'SESSION' ] DESCRIPTION @@ -44,6 +44,11 @@ include::common-lttng-cmd-options-head.txt[] include::common-lttng-cmd-help-options.txt[] +option:-a, option:--all:: + Start all sessions. + +option:-g, option:--glob:: + Interpret SESSION as a globbing pattern. include::common-lttng-cmd-after-options.txt[] @@ -67,6 +72,26 @@ $ lttng start my-session ---- ==== +.Start all sessions. +==== +See the option::--all option. + +[role="term"] +---- +$ lttng start --all +---- +==== + +.Start all sessions with the suffix foo. +==== +See the option::--glob option. + +[role="term"] +---- +$ lttng start --glob '*foo' +---- +==== + include::common-footer.txt[] diff --git a/doc/man/lttng-stop.1.txt b/doc/man/lttng-stop.1.txt index 0ad1f0e3c..ca1129df3 100644 --- a/doc/man/lttng-stop.1.txt +++ b/doc/man/lttng-stop.1.txt @@ -11,7 +11,7 @@ lttng-stop - Stop an LTTng recording session SYNOPSIS -------- [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *stop* [option:--no-wait] ['SESSION'] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *stop* [option:--no-wait] [option:--all | option:--glob 'SESSION' | 'SESSION'] DESCRIPTION @@ -62,6 +62,11 @@ option:-n, option:--no-wait:: Do :not: ensure that the trace data of the selected recording session is valid before exiting. +option:-a, option:--all:: + Stop all sessions. + +option:-g, option:--glob:: + Interpret SESSION as a globbing pattern. include::common-lttng-cmd-help-options.txt[] @@ -98,6 +103,26 @@ $ lttng stop --no-wait ---- ==== +.Stop all sessions. +==== +See the option:--all option. + +[role="term"] +---- +$ lttng stop --all +---- +==== + +.Stop all sessions with the suffix foo. +==== +See the option:--glob option. + +[role="term"] +---- +$ lttng stop --glob '*foo' +---- +==== + include::common-footer.txt[] diff --git a/extras/bindings/swig/python/.clang-tidy b/extras/bindings/swig/python/.clang-tidy new file mode 100644 index 000000000..8866f3d4c --- /dev/null +++ b/extras/bindings/swig/python/.clang-tidy @@ -0,0 +1,7 @@ +# clang-tidy uses the closest .clang-tidy in a parent directory +# to override settings. +# +# Add a dummy check since we can't disable them all without +# clang-tidy complaining. This ensures that generated code +# is not flagged. +Checks: '-*,llvm-twine-local' diff --git a/extras/bindings/swig/python/Makefile.am b/extras/bindings/swig/python/Makefile.am index a8fd56d80..d9cdd680d 100644 --- a/extras/bindings/swig/python/Makefile.am +++ b/extras/bindings/swig/python/Makefile.am @@ -7,12 +7,18 @@ lttng.i: lttng.i.in # `swig_this` shadows a global of the same name. Later versions (like 4.0.1) # have renamed this global to `Swig_This_global`. # -# Disable -Wshadow for that file. -AM_CFLAGS += -Wno-shadow - -AM_CFLAGS += -Wno-missing-field-initializers - -AM_CFLAGS += -Wno-cast-function-type +# Disable some warning flags for that file. +AM_CFLAGS += \ + -Wno-cast-function-type \ + -Wno-missing-field-initializers \ + -Wno-null-dereference \ + -Wno-redundant-decls \ + -Wno-shadow \ + -Wno-unused-parameter + +# Swig regularily changes and generates code that results warnings which break +# Werror builds. Disable that option for this sub-project. +AM_CFLAGS += -Wno-error AM_CPPFLAGS += $(PYTHON_INCLUDE) @@ -28,6 +34,11 @@ _lttng_la_LIBADD = $(top_builddir)/src/lib/lttng-ctl/liblttng-ctl.la \ $(top_builddir)/src/common/libsessiond-comm.la \ $(top_builddir)/src/common/libcommon-gpl.la +# Use this fake source file to force the link mode of the library +# from gcc to g++. The library contains only C code, but depends on +# libstdc++. +nodist_EXTRA__lttng_la_SOURCES = dummy.cpp + lttng_wrap.c: lttng.i $(SWIG) -python -I. -I$(top_srcdir)/src/common/sessiond-comm lttng.i diff --git a/extras/bindings/swig/python/lttng.i.in b/extras/bindings/swig/python/lttng.i.in index b555f4aae..94198769c 100644 --- a/extras/bindings/swig/python/lttng.i.in +++ b/extras/bindings/swig/python/lttng.i.in @@ -154,6 +154,28 @@ enum lttng_event_output { %rename("EVENT_CONTEXT_PREEMPTIBLE") LTTNG_EVENT_CONTEXT_PREEMPTIBLE; %rename("EVENT_CONTEXT_NEED_RESCHEDULE") LTTNG_EVENT_CONTEXT_NEED_RESCHEDULE; %rename("EVENT_CONTEXT_MIGRATABLE") LTTNG_EVENT_CONTEXT_MIGRATABLE; +%rename("EVENT_CONTEXT_CALLSTACK_KERNEL") LTTNG_EVENT_CONTEXT_CALLSTACK_KERNEL; +%rename("EVENT_CONTEXT_CALLSTACK_USER") LTTNG_EVENT_CONTEXT_CALLSTACK_USER; +%rename("EVENT_CONTEXT_CGROUP_NS") LTTNG_EVENT_CONTEXT_CGROUP_NS; +%rename("EVENT_CONTEXT_IPC_NS") LTTNG_EVENT_CONTEXT_IPC_NS; +%rename("EVENT_CONTEXT_MNT_NS") LTTNG_EVENT_CONTEXT_MNT_NS; +%rename("EVENT_CONTEXT_NET_NS") LTTNG_EVENT_CONTEXT_NET_NS; +%rename("EVENT_CONTEXT_PID_NS") LTTNG_EVENT_CONTEXT_PID_NS; +%rename("EVENT_CONTEXT_USER_NS") LTTNG_EVENT_CONTEXT_USER_NS; +%rename("EVENT_CONTEXT_UTS_NS") LTTNG_EVENT_CONTEXT_UTS_NS; +%rename("EVENT_CONTEXT_UID") LTTNG_EVENT_CONTEXT_UID; +%rename("EVENT_CONTEXT_EUID") LTTNG_EVENT_CONTEXT_EUID; +%rename("EVENT_CONTEXT_SUID") LTTNG_EVENT_CONTEXT_SUID; +%rename("EVENT_CONTEXT_GID") LTTNG_EVENT_CONTEXT_GID; +%rename("EVENT_CONTEXT_EGID") LTTNG_EVENT_CONTEXT_EGID; +%rename("EVENT_CONTEXT_SGID") LTTNG_EVENT_CONTEXT_SGID; +%rename("EVENT_CONTEXT_VUID") LTTNG_EVENT_CONTEXT_VUID; +%rename("EVENT_CONTEXT_VEUID") LTTNG_EVENT_CONTEXT_VEUID; +%rename("EVENT_CONTEXT_VSUID") LTTNG_EVENT_CONTEXT_VSUID; +%rename("EVENT_CONTEXT_VGID") LTTNG_EVENT_CONTEXT_VGID; +%rename("EVENT_CONTEXT_VEGID") LTTNG_EVENT_CONTEXT_VEGID; +%rename("EVENT_CONTEXT_VSGID") LTTNG_EVENT_CONTEXT_VSGID; +%rename("EVENT_CONTEXT_TIME_NS") LTTNG_EVENT_CONTEXT_TIME_NS; enum lttng_event_context_type { LTTNG_EVENT_CONTEXT_PID = 0, LTTNG_EVENT_CONTEXT_PERF_COUNTER = 1, @@ -175,6 +197,28 @@ enum lttng_event_context_type { LTTNG_EVENT_CONTEXT_PREEMPTIBLE = 17, LTTNG_EVENT_CONTEXT_NEED_RESCHEDULE = 18, LTTNG_EVENT_CONTEXT_MIGRATABLE = 19, + LTTNG_EVENT_CONTEXT_CALLSTACK_KERNEL = 20, + LTTNG_EVENT_CONTEXT_CALLSTACK_USER = 21, + LTTNG_EVENT_CONTEXT_CGROUP_NS = 22, + LTTNG_EVENT_CONTEXT_IPC_NS = 23, + LTTNG_EVENT_CONTEXT_MNT_NS = 24, + LTTNG_EVENT_CONTEXT_NET_NS = 25, + LTTNG_EVENT_CONTEXT_PID_NS = 26, + LTTNG_EVENT_CONTEXT_USER_NS = 27, + LTTNG_EVENT_CONTEXT_UTS_NS = 28, + LTTNG_EVENT_CONTEXT_UID = 29, + LTTNG_EVENT_CONTEXT_EUID = 30, + LTTNG_EVENT_CONTEXT_SUID = 31, + LTTNG_EVENT_CONTEXT_GID = 32, + LTTNG_EVENT_CONTEXT_EGID = 33, + LTTNG_EVENT_CONTEXT_SGID = 34, + LTTNG_EVENT_CONTEXT_VUID = 35, + LTTNG_EVENT_CONTEXT_VEUID = 36, + LTTNG_EVENT_CONTEXT_VSUID = 37, + LTTNG_EVENT_CONTEXT_VGID = 38, + LTTNG_EVENT_CONTEXT_VEGID = 39, + LTTNG_EVENT_CONTEXT_VSGID = 40, + LTTNG_EVENT_CONTEXT_TIME_NS = 41, }; @@ -928,6 +972,72 @@ struct lttng_event_context { case 19: sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_MIGRATABLE)"); break; + case 20: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_CALLSTACK_KERNEL)"); + break; + case 21: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_CALLSTACK_USER)"); + break; + case 22: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_CGROUP_NS)"); + break; + case 23: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_IPC_NS)"); + break; + case 24: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_MNT_NS)"); + break; + case 25: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_NET_NS)"); + break; + case 26: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_PID_NS)"); + break; + case 27: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_USER_NS)"); + break; + case 28: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_UTS_NS)"); + break; + case 29: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_UID)"); + break; + case 30: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_EUID)"); + break; + case 31: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_SUID)"); + break; + case 32: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_GID)"); + break; + case 33: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_EGID)"); + break; + case 34: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_SGID)"); + break; + case 35: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_VUID)"); + break; + case 36: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_VEUID)"); + break; + case 37: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_VSUID)"); + break; + case 38: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_VGID)"); + break; + case 39: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_VEGID)"); + break; + case 40: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_VSGID)"); + break; + case 41: + sprintf(temp, "lttng.EventContext; ctx(EVENT_CONTEXT_TIME_NS)"); + break; default: sprintf(temp, "lttng.EventContext; type(%i)", $self->ctx); break; diff --git a/extras/bindings/swig/python/tests/example.py b/extras/bindings/swig/python/tests/example.py index 45587b56b..56835625b 100644 --- a/extras/bindings/swig/python/tests/example.py +++ b/extras/bindings/swig/python/tests/example.py @@ -7,18 +7,21 @@ from lttng import * + # This error will be raised is something goes wrong class LTTngError(Exception): - def __init__(self, value): - self.value = value - def __str__(self): - return repr(self.value) + def __init__(self, value): + self.value = value + + def __str__(self): + return repr(self.value) + -#Setting up the domain to use +# Setting up the domain to use dom = Domain() dom.type = DOMAIN_KERNEL -#Setting up a channel to use +# Setting up a channel to use channel = Channel() channel.name = "mychan" channel.attr.overwrite = 0 @@ -28,7 +31,7 @@ channel.attr.switch_timer_interval = 0 channel.attr.read_timer_interval = 200 channel.attr.output = EVENT_SPLICE -#Setting up some events that will be used +# Setting up some events that will be used event = Event() event.type = EVENT_TRACEPOINT event.loglevel_type = EVENT_LOGLEVEL_ALL @@ -49,66 +52,66 @@ sched_process_free.type = EVENT_TRACEPOINT sched_process_free.loglevel_type = EVENT_LOGLEVEL_ALL -#Creating a new session -res = create("test","/lttng-traces/test") -if res<0: - raise LTTngError(strerror(res)) +# Creating a new session +res = create("test", "/lttng-traces/test") +if res < 0: + raise LTTngError(strerror(res)) -#Creating handle +# Creating handle han = None han = Handle("test", dom) if han is None: - raise LTTngError("Handle not created") + raise LTTngError("Handle not created") -#Enabling the kernel channel +# Enabling the kernel channel res = enable_channel(han, channel) -if res<0: - raise LTTngError(strerror(res)) +if res < 0: + raise LTTngError(strerror(res)) -#Enabling some events in given channel -#To enable all events in default channel, use -#enable_event(han, event, None) +# Enabling some events in given channel +# To enable all events in default channel, use +# enable_event(han, event, None) res = enable_event(han, sched_switch, channel.name) -if res<0: - raise LTTngError(strerror(res)) +if res < 0: + raise LTTngError(strerror(res)) res = enable_event(han, sched_process_exit, channel.name) -if res<0: - raise LTTngError(strerror(res)) +if res < 0: + raise LTTngError(strerror(res)) res = enable_event(han, sched_process_free, channel.name) -if res<0: - raise LTTngError(strerror(res)) +if res < 0: + raise LTTngError(strerror(res)) -#Disabling an event +# Disabling an event res = disable_event(han, sched_switch.name, channel.name) -if res<0: - raise LTTngError(strerror(res)) +if res < 0: + raise LTTngError(strerror(res)) -#Getting a list of the channels +# Getting a list of the channels l = list_channels(han) if type(l) is int: - raise LTTngError(strerror(l)) + raise LTTngError(strerror(l)) -#Starting the trace +# Starting the trace res = start("test") -if res<0: - raise LTTngError(strerror(res)) +if res < 0: + raise LTTngError(strerror(res)) -#Stopping the trace +# Stopping the trace res = stop("test") -if res<0: - raise LTTngError(strerror(res)) +if res < 0: + raise LTTngError(strerror(res)) -#Disabling a channel +# Disabling a channel res = disable_channel(han, channel.name) -if res<0: - raise LTTngError(strerror(res)) +if res < 0: + raise LTTngError(strerror(res)) -#Destroying the handle +# Destroying the handle del han -#Destroying the session +# Destroying the session res = destroy("test") -if res<0: - raise LTTngError(strerror(res)) +if res < 0: + raise LTTngError(strerror(res)) diff --git a/extras/bindings/swig/python/tests/tests.py b/extras/bindings/swig/python/tests/tests.py index fbbfdc480..7dd1d0624 100644 --- a/extras/bindings/swig/python/tests/tests.py +++ b/extras/bindings/swig/python/tests/tests.py @@ -10,7 +10,8 @@ import time import tempfile from lttng import * -class TestLttngPythonModule (unittest.TestCase): + +class TestLttngPythonModule(unittest.TestCase): def setUp(self): self.tmpdir = tempfile.TemporaryDirectory() @@ -45,7 +46,6 @@ class TestLttngPythonModule (unittest.TestCase): r = destroy("test_kernel_all_ev") self.assertGreaterEqual(r, 0, strerror(r)) - def test_kernel_event(self): dom = Domain() @@ -53,7 +53,7 @@ class TestLttngPythonModule (unittest.TestCase): dom.buf_type = BUFFER_GLOBAL channel = Channel() - channel.name="mychan" + channel.name = "mychan" channel.attr.overwrite = 0 channel.attr.subbuf_size = 4096 channel.attr.num_subbuf = 8 @@ -78,15 +78,15 @@ class TestLttngPythonModule (unittest.TestCase): han = Handle("test_kernel_event", dom) - #Create session test + # Create session test r = create("test_kernel_event", self.tmpdir.name) self.assertGreaterEqual(r, 0, strerror(r)) - #Enabling channel tests + # Enabling channel tests r = enable_channel(han, channel) self.assertGreaterEqual(r, 0, strerror(r)) - #Enabling events tests + # Enabling events tests r = enable_event(han, sched_switch, channel.name) self.assertGreaterEqual(r, 0, strerror(r)) @@ -96,21 +96,21 @@ class TestLttngPythonModule (unittest.TestCase): r = enable_event(han, sched_process_free, channel.name) self.assertGreaterEqual(r, 0, strerror(r)) - #Disabling events tests + # Disabling events tests r = disable_event(han, sched_switch.name, channel.name) self.assertGreaterEqual(r, 0, strerror(r)) r = disable_event(han, sched_process_free.name, channel.name) self.assertGreaterEqual(r, 0, strerror(r)) - #Renabling events tests + # Renabling events tests r = enable_event(han, sched_switch, channel.name) self.assertGreaterEqual(r, 0, strerror(r)) r = enable_event(han, sched_process_free, channel.name) self.assertGreaterEqual(r, 0, strerror(r)) - #Start, stop, destroy + # Start, stop, destroy r = start("test_kernel_event") self.assertGreaterEqual(r, 0, strerror(r)) time.sleep(2) @@ -118,14 +118,12 @@ class TestLttngPythonModule (unittest.TestCase): r = stop("test_kernel_event") self.assertGreaterEqual(r, 0, strerror(r)) - r=disable_channel(han, channel.name) + r = disable_channel(han, channel.name) self.assertGreaterEqual(r, 0, strerror(r)) - r=destroy("test_kernel_event") + r = destroy("test_kernel_event") self.assertGreaterEqual(r, 0, strerror(r)) - - def test_ust_all_events(self): dom = Domain() dom.type = DOMAIN_UST @@ -153,7 +151,6 @@ class TestLttngPythonModule (unittest.TestCase): r = destroy("test_ust_all_ev") self.assertGreaterEqual(r, 0, strerror(r)) - def test_ust_event(self): dom = Domain() @@ -161,7 +158,7 @@ class TestLttngPythonModule (unittest.TestCase): dom.buf_type = BUFFER_PER_UID channel = Channel() - channel.name="mychan" + channel.name = "mychan" channel.attr.overwrite = 0 channel.attr.subbuf_size = 4096 channel.attr.num_subbuf = 8 @@ -186,15 +183,15 @@ class TestLttngPythonModule (unittest.TestCase): han = Handle("test_ust_event", dom) - #Create session test + # Create session test r = create("test_ust_event", self.tmpdir.name) self.assertGreaterEqual(r, 0, strerror(r)) - #Enabling channel tests + # Enabling channel tests r = enable_channel(han, channel) self.assertGreaterEqual(r, 0, strerror(r)) - #Enabling events tests + # Enabling events tests r = enable_event(han, ev1, channel.name) self.assertGreaterEqual(r, 0, strerror(r)) @@ -204,21 +201,21 @@ class TestLttngPythonModule (unittest.TestCase): r = enable_event(han, ev3, channel.name) self.assertGreaterEqual(r, 0, strerror(r)) - #Disabling events tests + # Disabling events tests r = disable_event(han, ev1.name, channel.name) self.assertGreaterEqual(r, 0, strerror(r)) r = disable_event(han, ev3.name, channel.name) self.assertGreaterEqual(r, 0, strerror(r)) - #Renabling events tests + # Renabling events tests r = enable_event(han, ev1, channel.name) self.assertGreaterEqual(r, 0, strerror(r)) r = enable_event(han, ev3, channel.name) self.assertGreaterEqual(r, 0, strerror(r)) - #Start, stop + # Start, stop r = start("test_ust_event") self.assertGreaterEqual(r, 0, strerror(r)) time.sleep(2) @@ -226,7 +223,7 @@ class TestLttngPythonModule (unittest.TestCase): r = stop("test_ust_event") self.assertGreaterEqual(r, 0, strerror(r)) - #Restart/restop + # Restart/restop r = start("test_ust_event") self.assertGreaterEqual(r, 0, strerror(r)) time.sleep(2) @@ -234,25 +231,24 @@ class TestLttngPythonModule (unittest.TestCase): r = stop("test_ust_event") self.assertGreaterEqual(r, 0, strerror(r)) - #Disabling channel and destroy - r=disable_channel(han, channel.name) + # Disabling channel and destroy + r = disable_channel(han, channel.name) self.assertGreaterEqual(r, 0, strerror(r)) - r=destroy("test_ust_event") + r = destroy("test_ust_event") self.assertGreaterEqual(r, 0, strerror(r)) - def test_other_functions(self): dom = Domain() - dom.type=DOMAIN_KERNEL + dom.type = DOMAIN_KERNEL dom.buf_type = BUFFER_GLOBAL - event=Event() - event.type=EVENT_TRACEPOINT - event.loglevel_type=EVENT_LOGLEVEL_ALL + event = Event() + event.type = EVENT_TRACEPOINT + event.loglevel_type = EVENT_LOGLEVEL_ALL ctx = EventContext() - ctx.type=EVENT_CONTEXT_PID + ctx.type = EVENT_CONTEXT_PID chattr = ChannelAttr() chattr.overwrite = 0 @@ -262,7 +258,7 @@ class TestLttngPythonModule (unittest.TestCase): chattr.read_timer_interval = 200 chattr.output = EVENT_SPLICE - han = Handle("test_otherf" , dom) + han = Handle("test_otherf", dom) r = create("test_otherf", self.tmpdir.name) self.assertGreaterEqual(r, 0, strerror(r)) @@ -270,29 +266,28 @@ class TestLttngPythonModule (unittest.TestCase): r = enable_event(han, event, None) self.assertGreaterEqual(r, 0, strerror(r)) - #Context test + # Context test r = add_context(han, ctx, "sched_switch", "channel0") self.assertGreaterEqual(r, 0, strerror(r)) - #Any channel + # Any channel r = add_context(han, ctx, "sched_wakeup", None) self.assertGreaterEqual(r, 0, strerror(r)) - #All events + # All events r = add_context(han, ctx, None, None) self.assertGreaterEqual(r, 0, strerror(r)) - #Def. channel attr + # Def. channel attr channel_set_default_attr(dom, chattr) channel_set_default_attr(None, None) - #Ses Daemon alive + # Ses Daemon alive r = session_daemon_alive() self.assertTrue(r == 1 or r == 0, strerror(r)) - #Setting trace group + # Setting trace group r = set_tracing_group("testing") self.assertGreaterEqual(r, 0, strerror(r)) - r = start("test_otherf") self.assertGreaterEqual(r, 0, strerror(r)) time.sleep(2) @@ -316,6 +311,7 @@ def ust_suite(): suite.addTest(TestLttngPythonModule("test_ust_all_events")) return suite + def kernel_suite(): suite = unittest.TestSuite() suite.addTest(TestLttngPythonModule("test_kernel_event")) @@ -323,7 +319,8 @@ def kernel_suite(): suite.addTest(TestLttngPythonModule("test_other_functions")) return suite -if __name__ == '__main__': + +if __name__ == "__main__": destroy("test_kernel_event") destroy("test_kernel_all_events") destroy("test_ust_all_events") diff --git a/extras/core-handler/crash.c b/extras/core-handler/crash.c index bc7296814..c1e2a91bc 100644 --- a/extras/core-handler/crash.c +++ b/extras/core-handler/crash.c @@ -5,7 +5,6 @@ * */ - #include int main(void) diff --git a/extras/zsh-completion/_lttng b/extras/zsh-completion/_lttng new file mode 100644 index 000000000..b929e5d06 --- /dev/null +++ b/extras/zsh-completion/_lttng @@ -0,0 +1,2040 @@ +#compdef lttng +# +# Copyright (c) 2015-2023 Philippe Proulx +# +# Permission is hereby granted, free of charge, to any person obtaining +# a copy of this software and associated documentation files (the +# "Software"), to deal in the Software without restriction, including +# without limitation the rights to use, copy, modify, merge, publish, +# distribute, sublicense, and/or sell copies of the Software, and to +# permit persons to whom the Software is furnished to do so, subject to +# the following conditions: +# +# The above copyright notice and this permission notice shall be +# included in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +# +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# +# This is a Zsh completion function for the lttng(1) command (see +# ), for versions 2.5 to 2.14. +# +# If you want, at your own risk, the function to work with versions +# above 2.14, set `LTTNG_ZSH_COMP_IGNORE_VERSION_LIMIT=1`. +# +# Each subcommand changes the command part of the current context so +# that you can target a specific subcommand with `zstyle`, for +# example: +# +# $ zstyle ':completion:*:*:lttng-start:*:sessions' verbose yes +# $ zstyle ':completion:*:*:lttng-add-context:type-option:*' \ +# group-order perf-context-types static-context-types +# +# The relevant style arguments and tags are: +# +# `actions` tag (with the `lttng-snapshot` command): +# Snapshot action names. +# +# `channel` argument and `channels` tag: +# Channel names. +# +# The `verbose` style controls whether or not this function adds +# completions as a list (with channel information for each item) or +# simple channel names. +# +# If the verbose style is enabled, then the information part of each +# item starts with either ` [enabled` or ` [disabled` (note the +# two leading spaces), depending on the status of the channel. +# +# `commands` tag: +# lttng(1) subcommand names. +# +# `log-levels` tag: +# Log level names. +# +# `session` argument and `sessions` tag: +# Recording session names. +# +# The `verbose` style controls whether or not this function adds +# completions as a list (with recording session information for each +# item) or simple recording session names. +# +# If the verbose style is enabled, then the information part of each +# item starts with either ` [active` or ` [inactive` (note the two +# leading spaces), depending on the status of the recording session. +# +# `type-option` argument: +# `static-context-types` tag: +# Statically-known context field types. +# +# `perf-context-types` tag: +# perf counter context field types. +# +# `triggers` tag: +# Trigger names. + +# Sets the `minor_version` variable to the minor version of LTTng-tools, +# or to `0` if not found. +__lttng_set_minor_version() { + minor_version=0 + + local -a match + + if [[ $($prog_name --version) =~ '[[:blank:]]+2\.([[:digit:]]+)' ]]; then + minor_version=$match[1] + fi +} + +# Runs the `lttng` command with `"$@"` using `$tracing_group`. +__lttng_run() { + $prog_name --no-sessiond --group=$tracing_group "$@" 2>/dev/null +} + +# Runs the `lttng --mi=xml` command using the selected tracing group +# (`$tracing_group`) with: +# +# `$1`: +# A message of what's expected to show on error. +# +# Other arguments: +# Passed to the command as is. +# +# This function returns 1 with LTTng-tools < 2.6 and if `xmllint` isn't +# available. +__lttng_mi_run() { + local -r msg=$1 + + shift + + if ((minor_version < 6)); then + # MI output requires LTTng-tools ≥ 2.6 + _message -e descriptions $msg + return 1 + fi + + if ((! $+commands[xmllint])); then + # XML output parsing requires xmllint + _message -e descriptions $msg + return 1 + fi + + __lttng_run --mi=xml "$@" + + if (($? != 0)); then + # Command failed + _message -e descriptions $msg + return 1 + fi +} + +# Call this instead of _arguments() within this function when you don't +# need the `-C` option. +__lttng_arguments() { + _arguments -s -W : "$@" +} + +# Returns whether or not the verbose style is enabled for the given +# argument (`$1`) and tag (`$2`), using `$curcontext` for the other +# parts of the full completion context. +__lttng_style_is_verbose() { + local -r arg=$1 tag=$2 + local -r ccparts=("${(@s.:.)curcontext}") + + zstyle -t :completion:${ccparts[1]}:${ccparts[2]}:${ccparts[3]}:$arg:$tag verbose +} + +# Returns 0 if a Linux kernel tracing domain option is set in +# `$opt_args`, or `1` otherwise. +__lttng_kernel_domain_opt_is_set() { + (($+opt_args[-k] || $+opt_args[--kernel] || + $+opt_args[domain--k] || $+opt_args[domain---kernel])) +} + +# Returns 0 if a user space tracing domain option is set in +# `$opt_args`, or `1` otherwise. +__lttng_user_domain_opt_is_set() { + (($+opt_args[-u] || $+opt_args[--userspace] || + $+opt_args[domain--u] || $+opt_args[domain---userspace])) +} + +# Returns 0 if a `java.util.logging` tracing domain option is set in +# `$opt_args`, or `1` otherwise. +__lttng_jul_domain_opt_is_set() { + (($+opt_args[-j] || $+opt_args[--jul] || + $+opt_args[domain--j] || $+opt_args[domain---jul])) +} + +# Returns 0 if an Apache log4j tracing domain option is set in +# `$opt_args`, or `1` otherwise. +__lttng_log4j_domain_opt_is_set() { + (($+opt_args[-l] || $+opt_args[--log4j] || + $+opt_args[domain--l] || $+opt_args[domain---log4j])) +} + +# Returns 0 if a Python tracing domain option is set in `$opt_args`, +# or `1` otherwise. +__lttng_python_domain_opt_is_set() { + (($+opt_args[-p] || $+opt_args[--python] || + $+opt_args[domain--p] || $+opt_args[domain---python])) +} + +# Adds completions for the name of an `lttng` command. +__lttng_complete_cmd_name() { + # LTTng-tools 2.5+ + local cmd_names=( + 'add-context:add context fields to be recorded' + 'create:create a recording session' + 'destroy:destroy a recording session' + 'disable-channel:disable channels' + 'disable-event:disable recording event rules' + 'enable-channel:create or enable a channel' + 'enable-event:create or enable recording event rules' + 'help:show the help of a command' + 'list:list recording sessions and instrumentation points' + 'set-session:set the current recording session' + 'snapshot:take a recording session snapshot' + 'start:start a recording session' + 'stop:stop a recording session' + 'version:show LTTng-tools version information' + 'view:launch a trace reader' + ) + + # LTTng-tools 2.6+ + if ((minor_version >= 6)); then + cmd_names+=( + 'load:load recording session configurations' + 'save:save recording session configurations' + ) + fi + + # LTTng-tools 2.7+ + if ((minor_version >= 7)); then + cmd_names+=( + 'track:allow specific processes to record events' + 'untrack:disallow specific processes to record events' + ) + fi + + # LTTng-tools 2.8+ + if ((minor_version >= 8)); then + cmd_names+=( + 'status:show the status of the current recording session' + ) + fi + + # LTTng-tools 2.9+ + if ((minor_version >= 9)); then + cmd_names+=( + 'regenerate:regenerate specific recording session data' + ) + fi + + # LTTng-tools 2.11+ + if ((minor_version >= 11)); then + cmd_names+=( + 'rotate:archive the current trace chunk of a recording session' + 'enable-rotation:set a recording session rotation schedule' + 'disable-rotation:unset a recording session rotation schedule' + ) + fi + + # LTTng-tools 2.12+ + if ((minor_version >= 12)); then + cmd_names+=( + 'clear:clear a recording session' + ) + fi + + # LTTng-tools 2.13+ + if ((minor_version >= 13)); then + cmd_names+=( + 'add-trigger:add a trigger' + 'list-triggers:list triggers' + 'remove-trigger:remove a trigger' + ) + fi + + # Add completions + local expl + + _describe -t commands command cmd_names +} + +# Adds completions for the name of an `lttng snapshot` action. +__lttng_complete_snapshot_action_name() { + local -r action_names=( + 'add-output:add a snapshot output' + 'del-output:remove a snapshot output' + 'list-output:show the snapshot output' + 'record:take a snapshot' + ) + + # Add completions + local expl + + _describe -t actions 'snapshot action' action_names +} + +# Adds user ID completions. +# +# The added completions are displayed as user names, but the actual +# completions are corresponding user IDs. +__lttng_complete_uid() { + if [[ ! -f /etc/passwd ]]; then + # Weird flex but ok + _message -e descriptions 'user ID' + return + fi + + # Read user names and IDs from `/etc/passwd` + local line + local -a uids names fields + + while read -r line; do + if [[ -z ${line// } ]]; then + # Skip empty line + continue + fi + + # Extract user ID and name + fields=("${(@s/:/)line}") + uids+=($fields[3]) + names+=("$fields[1]") + done < /etc/passwd + + # Add completions + local expl + + _wanted users expl 'user ID' compadd -d names -a uids +} + +# Adds completions for a context field type (for the `--type` option of +# the `add-context` command). +# +# This function replaces the argument field of the current context with +# `type-option`. +# +# This function relies on the tracing domain options of `$opt_args` to +# restrict the offered completions. Without a tracing domain option, +# this function adds all the possible context field type completions. +# +# This function runs `lttng add-context --list` to get the list of +# available context field types. +# +# This function adds completions with both the `static-context-types` +# and `perf-context-types` tags so that the Zsh user can hide a group or +# select them with the `group-order` and `tag-order` style. +__lttng_complete_context_type() { + # Statically-known context field types + local kernel_types=( + pid procname prio nice vpid tid vtid ppid vppid hostname + interruptible preemptible need_reschedule migratable + callstack-kernel callstack-user cgroup_ns ipc_ns mnt_ns net_ns + pid_ns time_ns user_ns uts_ns uid euid suid gid egid sgid vuid veuid + vsuid vgid vegid vsgid + ) + local user_types=( + vpid pthread_id procname ip cgroup_ns ipc_ns mnt_ns net_ns pid_ns + time_ns user_ns uts_ns vuid veuid vsuid vgid vegid vsgid + ) + + # Set `types` and `domain` depending on the selected tracing domain + local -a types + local domain descr_suffix + + if __lttng_kernel_domain_opt_is_set; then + # Kernel context field types + types=($kernel_types) + domain=k + elif __lttng_user_domain_opt_is_set; then + # User space context field types + types=($user_types) + domain=u + else + # No supported tracing domain: offer all context field types + types=($user_types $kernel_types) + descr_suffix=' (all tracing domains)' + fi + + # Get XML list of available context field types + local -r msg='context type' + local list_xml + + list_xml=$(__lttng_mi_run $msg add-context --list) + + if (($? != 0)); then + return 1 + fi + + # Convert to one context field type per line + local lines + + lines=$(__lttng_xmllint_xpath $list_xml '//*[local-name()="symbol"]/text()') + + if (($? != 0)); then + _guard '^-*' $msg + return + fi + + # Filter context field types depending on the selected tracing domain + local -a static_items perf_items + local line + + while read -r line; do + if (($types[(Ie)$line])); then + # Statically-known context field type + static_items+=$line + elif [[ $line = perf:cpu:* && $domain != u ]]; then + # Per-CPU perf counter + perf_items+=$line + elif [[ $line = perf:thread:* && $domain != k ]]; then + # Per-thread perf counter + perf_items+=$line + elif [[ $line = perf:* && $domain != u ]]; then + # Other perf counter (Linux kernel tracing domain or none) + perf_items+=$line + fi + done <<< $lines + + # Add completions + _alternative -C type-option \ + "static-context-types:statically-known context type${descr_suffix}:compadd -a static_items" \ + "perf-context-types:perf counter context type${descr_suffix}:compadd -a perf_items" +} + +# Adds completions for a trigger name. +# +# Relies on `$opt_args[--owner-uid]` to restrict the offered +# completions. +__lttng_complete_trigger_name() { + # Get XML list of available triggers + local msg='trigger name' + local list_xml + + list_xml=$(__lttng_mi_run $msg list-triggers) + + if (($? != 0)); then + return 1 + fi + + # Create the owner UID predicate XPath part + local owner_uid_xpath + + if (($+opt_args[--owner-uid])); then + owner_uid_xpath="[./*[local-name()='owner_uid'] = ${opt_args[--owner-uid]}]" + fi + + # Convert to one trigger name per line + local lines + + lines=$(__lttng_xmllint_xpath $list_xml "//*[local-name()='trigger']$owner_uid_xpath/*[local-name()='name']/text()") + + if (($? != 0)); then + _guard '^-*' $msg + return + fi + + local -a trigger_names + + while read -r line; do + trigger_names+=$line + done <<< $lines + + # Add completions + local expl + + _wanted triggers expl $msg compadd -a trigger_names +} + +# Runs `xmllint` with: +# +# `$1`: +# An XML document to parse. +# +# `$2`: +# An XPath to extract data. +__lttng_xmllint_xpath() { + local -r xml=$1 xpath=$2 + + xmllint --xpath $xpath - <<< $xml 2>/dev/null +} + +# Prints the equivalent recording session status adjective (`active` or +# `inactive`) for an `enabled` XML property, or `unknown` on error. +__lttng_session_status_from_enabled_prop() { + local -r prop=$1 + + case $prop in + true) echo -n active;; + false) echo -n inactive;; + *) echo -n unknown;; + esac +} + +# Prints the value of the immediate XML property named `$3` of the child +# node named `$2` within the parent node `$1`. +__lttng_immediate_prop_from_xml() { + local -r node_xml=$1 node_name=$2 prop_name=$3 + + __lttng_xmllint_xpath $node_xml "/*[local-name()='$node_name']/*[local-name()='$prop_name']/text()" +} + +# Prints the value of the immediate XML `name` property of the child +# node named `$2` within the parent node `$1`. +__lttng_name_prop_from_xml() { + local -r node_xml=$1 node_name=$2 + + __lttng_immediate_prop_from_xml $node_xml $node_name name +} + +# Prints the value of the immediate XML `enabled` property of the child +# node named `$2` within the parent node `$1`. +__lttng_enabled_prop_from_xml() { + local -r node_xml=$1 node_name=$2 + + __lttng_immediate_prop_from_xml $node_xml $node_name enabled +} + +# Adds completions for a recording session name. +# +# Arguments: +# +# `$1`: +# One of: +# +# `all`: +# Add completions for active and inactive recording sessions. +# +# `active`: +# Only add completions for active recording sessions. +# +# `inactive`: +# Only add completions for inactive recording sessions. +# +# `$2`: +# One of: +# +# `all`: +# Add completions for recording sessions regardless of their +# mode. +# +# `snapshot`: +# Only add completions for snapshot recording sessions. +# +# `live`: +# Only add completions for LTTng live recording sessions. +__lttng_complete_session_name() { + local -r req_status=$1 req_mode=$2 + + # Get XML document (summary of recording sessions) + local session_summaries_xml + + session_summaries_xml=$(__lttng_mi_run 'recording session name' list) + + if (($? != 0)); then + return 1 + fi + + # Count recording sessions + local -i session_count + + session_count=$(__lttng_xmllint_xpath $session_summaries_xml 'count(//*[local-name()="session"])') + + if (($? != 0 || session_count == 0)); then + _guard '^-*' 'recording session name' + return + fi + + # Append the name and info of one recording session at a time + local -a session_names session_infos + local -i index iprop + local session_name session_summary_xml snapshot_mode session_status session_info + + # For each recording session summary + for index in {1..$session_count}; do + # Get recording session summary XML node + session_summary_xml=$(__lttng_xmllint_xpath $session_summaries_xml "//*[local-name()='session'][$index]") + + if (($? != 0)); then + continue + fi + + # Get recording session name + session_name=$(__lttng_name_prop_from_xml $session_summary_xml session) + + if (($? != 0)); then + continue + fi + + # Get recording session status + session_status=$(__lttng_enabled_prop_from_xml $session_summary_xml session) + + if (($? != 0)); then + continue + fi + + session_status=$(__lttng_session_status_from_enabled_prop $session_status) + + if [[ $req_status != all && $req_status != $session_status ]]; then + # Skip recording session with unexpected status + continue + fi + + # Get recording session mode + session_mode= + iprop=$(__lttng_immediate_prop_from_xml $session_summary_xml session snapshot_mode) + + if (($? == 0 && iprop)); then + session_mode=snapshot + else + iprop=$(__lttng_immediate_prop_from_xml $session_summary_xml session live_timer_interval) + + if (($? == 0 && iprop)); then + session_mode=live + fi + fi + + if [[ $req_mode != all && $req_mode != $session_mode ]]; then + # Skip recording session with unexpected mode + continue + fi + + session_info=$session_status + + if [[ -n $session_mode ]]; then + session_info+=", $session_mode mode" + fi + + session_names+=("$session_name") + session_infos+=($session_info) + done + + # No recording sessions: show message + if (($#session_names == 0)); then + _guard '^-*' 'recording session name' + return + fi + + # Compute maximum session info length + local -i max_info_len=0 len + + for session_info in $session_infos; do + len=$#session_info + + if ((len > max_info_len)); then + max_info_len=$len + fi + done + + # Compute maximum session name length + local -i max_name_len=0 + + for session_name in $session_names; do + len=$#session_name + + if ((len > max_name_len)); then + max_name_len=$len + fi + done + + # Some room for the longest info string, two spaces, and two brackets + local -ir max_possible_name_len=$((COLUMNS - max_info_len - 5)) + + if ((max_name_len > max_possible_name_len)); then + # Clamp + max_name_len=$max_possible_name_len + fi + + # Create the dislay strings (name, status, mode) + local -a disps + + for index in {1..${#session_names}}; do + disps+=("${(r:$max_name_len:: :)session_names[$index]} [$session_infos[$index]]") + done + + # Add completions + local expl + + if __lttng_style_is_verbose session sessions; then + # Verbose mode (list with infos) + _wanted -C session sessions expl 'recording session name' \ + compadd -d disps -l -a session_names + else + # Just the recording session names + _wanted -C session sessions expl 'recording session name' \ + compadd -a session_names + fi +} + +# Prints the name of the Unix user's current recording session, if any. +__lttng_cur_session_name() { + local -r lttngrc_path=${LTTNG_HOME:-$HOME}/.lttngrc + + if [[ ! -f $lttngrc_path ]]; then + return 1 + fi + + local cur_session_name + local -a match + + while read -r line; do + if [[ $line =~ 'session=([^[:blank:]]+)' ]]; then + cur_session_name=$match[1] + break + fi + done < $lttngrc_path + + if [[ -z $cur_session_name ]]; then + return 1 + fi + + echo -n $cur_session_name +} + +# Prints the equivalent status adjective (`enabled` or `disabled`) for +# an `enabled` XML property, or `unknown` on error. +__lttng_status_from_enabled_prop() { + local -r prop=$1 + + case $prop in + true) echo -n enabled;; + false) echo -n disabled;; + *) echo -n unknown;; + esac +} + +# Prints the XML document of `lttng list $2` (specifics of a single +# recording session). +# +# `$1` is a message of what's expected to show on error. +__lttng_session_xml() { + local -r msg=$1 session_name=$2 + + __lttng_mi_run $msg list $session_name +} + +# Adds completions for a channel name. +# +# This function relies on the tracing domain options of `$opt_args`, +# `$opt_args[-s]`, `$opt_args[--session]`, and the first non-option +# argument to restrict the offered completions. +# +# Arguments: +# +# `$1`: +# One of: +# +# `all`: +# Add completions for enabled and disabled channels. +# +# `enabled`: +# Only add completions for enabled channels. +# +# `disabled`: +# Only add completions for disabled channels. +# +# `$2`: +# `opt`: +# Use `$opt_args[-s]` and `$opt_args[--session]` to find the +# name of the selected recording session. +# +# `arg`: +# Use `$line[1]` to find the name of the selected recording +# session. +__lttng_complete_channel_name() { + local -r req_status=$1 session_name_src=$2 + + shift 2 + + # Find the recording session name to use + local session_name + + if [[ $session_name_src = opt ]]; then + if (($+opt_args[-s])); then + session_name=$opt_args[-s] + elif (($+opt_args[--session])); then + session_name=$opt_args[--session] + fi + elif [[ $session_name_src = arg ]]; then + session_name=$line[1] + fi + + if [[ -z $session_name ]]; then + # Fall back to current recording session + session_name=$(__lttng_cur_session_name) + + if (($? != 0)); then + _guard '^-*' 'channel name' + return + fi + fi + + # Get XML document (detailed recording session) + local session_xml + + session_xml=$(__lttng_session_xml 'channel name' $session_name) + + if (($? != 0)); then + return 1 + fi + + # Count tracing domains + local -i domain_count + + domain_count=$(__lttng_xmllint_xpath $session_xml 'count(//*[local-name()="domain"])') + + if (($? != 0 || domain_count == 0)); then + _guard '^-*' 'channel name' + return + fi + + # Append the name and info of one channel at a time + local domain_xml domain prop + local channel_xml channel_name channel_status channel_erl_mode + local -a channel_names channel_infos + local -i channel_count domain_index channel_index + + # For each tracing domain + for domain_index in {1..$domain_count}; do + # Get tracing domain XML node + domain_xml=$(__lttng_xmllint_xpath $session_xml "//*[local-name()='domain'][$domain_index]") + + if (($? != 0)); then + continue + fi + + # Get tracing domain type + domain=$(__lttng_xmllint_xpath $domain_xml '/*/*[local-name()="type"]/text()') + + if (($? != 0)); then + continue + fi + + # Skip unexpected tracing domains + if [[ $domain = KERNEL ]]; then + if __lttng_user_domain_opt_is_set; then + # Skip unexpected Linux kernel tracing domain + continue + fi + + domain='Linux kernel' + fi + + if [[ $domain = UST ]]; then + if __lttng_kernel_domain_opt_is_set; then + # Skip unexpected user space tracing domain + continue + fi + + domain='user space' + fi + + # Count channels within tracing domain + channel_count=$(__lttng_xmllint_xpath $domain_xml 'count(//*[local-name()="channel"])') + + if (($? != 0 || channel_count == 0)); then + continue + fi + + # For each channel + for channel_index in {1..$channel_count}; do + # Get channel XML node + channel_xml=$(__lttng_xmllint_xpath $domain_xml "//*[local-name()='channel'][$channel_index]") + + if (($? != 0)); then + continue + fi + + # Get channel name + channel_name=$(__lttng_name_prop_from_xml $channel_xml channel) + + if (($? != 0)); then + continue + fi + + # Get channel status + channel_status=$(__lttng_enabled_prop_from_xml $channel_xml channel) + + if (($? != 0)); then + continue + fi + + channel_status=$(__lttng_status_from_enabled_prop $channel_status) + + if [[ $req_status != all && $req_status != $channel_status ]]; then + # Skip channel with unexpected status + continue + fi + + # Get channel event record loss mode + channel_erl_mode=$(__lttng_xmllint_xpath $channel_xml '//*[local-name()="attributes"]/*[local-name()="overwrite_mode"]/text()') + + if (($? != 0)); then + continue + fi + + if [[ $channel_erl_mode = DISCARD ]]; then + channel_erl_mode=discard + elif [[ $channel_erl_mode = OVERWRITE ]]; then + channel_erl_mode=overwrite + fi + + channel_names+=("$channel_name") + channel_infos+=("$channel_status, $domain, $channel_erl_mode mode") + done + done + + # No channels: show message + if (($#channel_names == 0)); then + _guard '^-*' 'channel name' + return + fi + + # Compute maximum channel info length + local channel_info + local -i max_info_len=0 len + + for channel_info in $channel_infos; do + len=$#channel_info + + if ((len > max_info_len)); then + max_info_len=$len + fi + done + + # Compute maximum channel name length + local -i max_name_len=0 + + for channel_name in $channel_names; do + len=$#channel_name + + if ((len > max_name_len)); then + max_name_len=$len + fi + done + + # Some room for the longest info string, two spaces, and two brackets + local -ir max_possible_name_len=$((COLUMNS - max_info_len - 5)) + + if ((max_name_len > max_possible_name_len)); then + # Clamp + max_name_len=$max_possible_name_len + fi + + # Create the dislay strings (name, status, tracing domain, mode) + local -a disps + + for channel_index in {1..${#channel_names}}; do + disps+=("${(r:$max_name_len:: :)channel_names[$channel_index]} [$channel_infos[$channel_index]]") + done + + # Add completions + local expl + + if __lttng_style_is_verbose channel channels; then + # Verbose mode (list with infos). + # + # Using `-2` as Linux kernel and user space channels may have the + # same name, but we want to show the different infos. + _wanted -C channel channels expl 'channel name' \ + compadd "$@" -2 -d disps -l -a channel_names + else + # Just the channel names, no duplicates + _wanted -C channel channels expl 'channel name' \ + compadd "$@" -a channel_names + fi +} + +# Add completions for instrumentation point names. +# +# This function relies on the tracing domain options of `$opt_args` and +# `$opt_args[ip---syscall]` to restrict the offered completions. +__lttng_complete_ip_name() { + local msg + local -a list_opts + + if __lttng_kernel_domain_opt_is_set; then + list_opts=(-k) + + if (($+opt_args[ip---syscall])); then + msg='system call name (no `sys_` prefix)' + list_opts+=(--syscall) + else + msg='Linux kernel tracepoint name' + fi + elif __lttng_user_domain_opt_is_set; then + msg='user space tracepoint name' + list_opts=(-u) + elif __lttng_jul_domain_opt_is_set; then + msg='`java.util.logging` logger name' + list_opts=(-j) + elif __lttng_log4j_domain_opt_is_set; then + msg='Apache log4j logger name' + list_opts=(-l) + elif __lttng_python_domain_opt_is_set; then + msg='Python logger name' + list_opts=(-p) + else + # No tracing domain option + _guard '^-*' 'instrumentation point or recording event rule name' + return + fi + + # Get XML list of available instrumentation point names + local list_xml + + list_xml=$(__lttng_mi_run $msg list $list_opts) + + if (($? != 0)); then + return 1 + fi + + # Convert to one instrumentation point name per line + local ip_names + + ip_names=$(__lttng_xmllint_xpath $list_xml '//*[local-name()="event"]//*[local-name()="name"]/text()') + + if (($? != 0)) || [[ -z $ip_names ]]; then + # `xmllint` error or no instrumentation points + _guard '^-*' $msg + return + fi + + local ip_name + local -a items + + while read -r ip_name; do + if [[ -z $ip_name ]]; then + continue + fi + + items+=($ip_name) + done <<< $ip_names + + # Add completions + local expl + + _wanted instrumentation-points expl $msg compadd "$@" -a items +} + +# Adds completions for the arguments of the `add-context` command. +__lttng_complete_add_context_cmd() { + local specs=( + $help_opt_specs + '(- : *)--list[list the available context field types]' + '(--list -s --session)'{-s+,--session=}'[select a specific recording session]: : __lttng_complete_session_name inactive all' + '(--list -c --channel)'{-c+,--channel=}'[select a specific channel]: : __lttng_complete_channel_name enabled opt' + '(--list)*'{-t+,--type=}'[add a context field to be recorded]: : __lttng_complete_context_type' + + '(domain)' + '(--list)'{-k,--kernel}'[select the Linux kernel tracing domain]' + '(--list)'{-u,--userspace}'[select the user space tracing domain]' + ) + + # The Java tracing domain options require LTTng-tools ≥ 2.8 (for + # application-specific context field types). + if ((minor_version >= 8)); then + specs+=( + '(--list)'{-j,--jul}'[select the `java.util.logging` tracing domain]' + '(--list)'{-l,--log4j}'[select the Apache log4j tracing domain]' + ) + fi + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for log level names. +# +# This function relies on the tracing domain options of `$opt_args` to +# restrict the offered completions. +__lttng_complete_log_level() { + local -a log_levels + + # Fill the `log_levels` array depending on the tracing domain option + if __lttng_user_domain_opt_is_set; then + log_levels=( + EMERG + ALERT + CRIT + ERR + WARNING + NOTICE + INFO + DEBUG_SYSTEM + DEBUG_PROGRAM + DEBUG_PROCESS + DEBUG_MODULE + DEBUG_UNIT + DEBUG_FUNCTION + DEBUG_LINE + DEBUG + ) + elif __lttng_jul_domain_opt_is_set; then + log_levels=( + OFF + SEVERE + WARNING + INFO + CONFIG + FINE + FINER + FINEST + ALL + ) + elif __lttng_log4j_domain_opt_is_set; then + log_levels=( + OFF + FATAL + ERROR + WARN + INFO + DEBUG + TRACE + ALL + ) + elif __lttng_python_domain_opt_is_set; then + log_levels=( + CRITICAL + ERROR + WARNING + INFO + DEBUG + NOTSET + ) + else + # No tracing domain option + _guard '^-*' 'log level name' + fi + + # Add completions + local expl + + _wanted log-levels expl 'log level name' compadd -a log_levels +} + +# Adds completions for a trigger condition type. +__lttng_complete_trigger_condition_type() { + local -r types=( + 'event-rule-matches:an event rule matches an event' + ) + + # Add completions + local expl + + _describe 'trigger condition type' types +} + +# Adds completions for a trigger action type. +__lttng_complete_trigger_action_type() { + local -r types=( + 'notify:send a notification through the notification mechanism' + 'start-session:start a recording session' + 'stop-session:stop a recording session' + 'rotate-session:archive the current trace chunk of a recording session' + 'snapshot-session:take a recording session snapshot' + ) + + # Add completions + local expl + + _describe 'trigger action type' types +} + +# Adds completions for the arguments of the `add-trigger` command. +# +# Note that those completions are incomplete, in that: +# +# • A valid event rule specification, as per lttng-event-rule(7), +# must follow `--condition=event-rule-matches`. +# +# • `--capture` options are possible within an `event-rule-matches` +# condition specifier. +# +# • The `--rate-policy` option and other arguments, sometimes mandatory, +# are possible within an action specifier. +# +# Having full completion for condition and action specifiers require +# more Zsh magic as _arguments(), like most command-line argument +# parsers, doesn't take option positions into account. +__lttng_complete_add_trigger_cmd() { + local -r specs=( + $help_opt_specs + '(-n --name)'{-n+,--name=}'[set the trigger name]:new trigger name:' + '--owner-uid=[add the trigger as another Unix user]: : __lttng_complete_uid' + '--condition=[set the condition type and arguments]: : __lttng_complete_trigger_condition_type' + '*--action=[set the action type and arguments]: : __lttng_complete_trigger_action_type' + ) + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `clear` command. +__lttng_complete_clear_cmd() { + local -r specs=( + $help_opt_specs + '(-a --all):: : __lttng_complete_session_name all all' + '(1 -a --all)'{-a,--all}'[clear all recording sessions]' + ) + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `create` command. +__lttng_complete_create_cmd() { + local specs=( + $help_opt_specs + ':: :_guard "^-*" "new recording session name"' + '(-C --ctrl-url output)'{-C+,--ctrl-url=}'[set the control URL]:control URL:' + '(-D --data-url output)'{-D+,--data-url=}'[set the trace data output URL]:trace data output URL:' + ) + + # The `--shm-path` option requires LTTng-tools ≥ 2.7 + if ((minor_version >= 7)); then + specs+=( + '--shm-path=[write shared memory files to a specific directory]:shared memory file directory:_files -/' + ) + fi + + # Add the remaining option groups + specs+=( + + '(output)' + '(-D --data-url -C --ctrl-url --live)--no-output[disable trace data output]' + '(-D --data-url -C --ctrl-url --live)'{-o+,--output=}'[set the local trace data output directory]:trace data output directory:_files -/' + '(-D --data-url -C --ctrl-url)'{-U+,--set-url=}'[set the trace data output and control URL]:trace data output and control URL:' + + '(mode)' + '(-o --output --no-output)--live=[create an LTTng live recording session]:live timer period (µs):' + '--snapshot[create a snapshot recording session]' + ) + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `destroy` command. +__lttng_complete_destroy_cmd() { + local specs=( + $help_opt_specs + '(-a --all):: : __lttng_complete_session_name all all' + '(1 -a --all)'{-a,--all}'[destroy all recording sessions]' + ) + + # The `--no-wait` option requires LTTng-tools ≥ 2.8 + if ((minor_version >= 8)); then + specs+=( + '(-n --no-wait)'{-n,--no-wait}'[exit immediately]' + ) + fi + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `disable-channel` command. +__lttng_complete_disable_channel_cmd() { + local -r specs=( + $help_opt_specs + '(-s --session)'{-s+,--session=}'[select a specific recording session]: : __lttng_complete_session_name all all' + ': : _sequence __lttng_complete_channel_name enabled opt' + + '(domain)' + {-k,--kernel}'[select the Linux kernel tracing domain]' + {-u,--userspace}'[select the user space tracing domain]' + ) + + # Add completions + __lttng_arguments $specs +} + +# Prints the XML tracing domain name value depending on the tracing +# domain option (in `$opt_args`), or prints nothing and returns 1 when +# not available. +__lttng_xml_domain_name_from_opt() { + if __lttng_kernel_domain_opt_is_set; then + echo -n KERNEL + elif __lttng_user_domain_opt_is_set; then + echo -n UST + elif __lttng_jul_domain_opt_is_set; then + echo -n JUL + elif __lttng_log4j_domain_opt_is_set; then + echo -n LOG4J + elif __lttng_python_domain_opt_is_set; then + echo -n PYTHON + else + return 1 + fi +} + +# Prints the XML instrumentation point type value depending on the +# instrumentation point option (in `$opt_args`). +__lttng_xml_ip_type_from_opt() { + if (($+opt_args[--syscall] || $+opt_args[ip---syscall])); then + echo -n SYSCALL + elif (($+opt_args[--probe] || $+opt_args[ip---probe])); then + echo -n PROBE + elif (($+opt_args[--function] || $+opt_args[ip---function])); then + echo -n FUNCTION + else + echo -n TRACEPOINT + fi +} + +# Adds completions for an old, enabled recording event rule name +# condition (for the `disable-event` command). +__lttng_complete_old_enabled_er_name_cond() { + local -r msg='recording event rule name condition' + + # Find the recording session name to use + local session_name + + if (($+opt_args[-s])); then + session_name=$opt_args[-s] + elif (($+opt_args[--session])); then + session_name=$opt_args[--session] + else + # Fall back to current recording session + session_name=$(__lttng_cur_session_name) + + if (($? != 0)); then + _guard '^-*' $msg + fi + fi + + # Find the channel name to use (`channel0` is the default name) + local channel_name=channel0 + + if (($+opt_args[-c])); then + channel_name=$opt_args[-c] + elif (($+opt_args[--channel])); then + channel_name=$opt_args[--channel] + fi + + # Create tracing domain XPath part + local domain_xpath + local xml_domain_val + + xml_domain_val=$(__lttng_xml_domain_name_from_opt) + + if (($? == 0)); then + domain_xpath="*[local-name() = 'domain'][*[local-name() = 'type'] = '$xml_domain_val']//" + fi + + # Create channel XPath part + local -r channel_xpath="*[local-name() = 'channel'][*[local-name() = 'name'] = '$channel_name']//" + + # Create instrumentation point type XPath part + local -r xml_ip_type_val=$(__lttng_xml_ip_type_from_opt) + local -r ip_type_xpath="[*[local-name() = 'type'] = '$xml_ip_type_val']" + + # Get XML document (detailed recording session) + local session_xml + + session_xml=$(__lttng_session_xml $msg $session_name) + + if (($? != 0)); then + return 1 + fi + + # Convert to one recording event rule name per line + local lines + + lines=$(__lttng_xmllint_xpath $session_xml "//$domain_xpath${channel_xpath}*[local-name() = 'event']${ip_type_xpath}[*[local-name() = 'enabled'] = 'true']/*[local-name() = 'name']/text()") + + if (($? != 0)); then + _guard '^-*' $msg + return + fi + + local -a er_names + + while read -r line; do + if [[ -z ${line// } ]]; then + # Skip empty line + continue + fi + + er_names+=$line + done <<< $lines + + # Add completions + local expl + + _wanted -C event events expl $msg compadd "$@" -a er_names +} + +# Adds completions for the arguments of the `disable-event` command. +__lttng_complete_disable_event_cmd() { + local -r kernel_ip_opt_excl=(--syscall --probe --function) + local specs=( + $help_opt_specs + '(-s --session)'{-s+,--session=}'[select a specific recording session]: : __lttng_complete_session_name all all' + '(-c --channel)'{-c+,--channel=}'[select a specific channel]: : __lttng_complete_channel_name all opt' + + '(names)' + {-a,--all-events}'[disable all recording event rules]' + ': :_sequence __lttng_complete_old_enabled_er_name_cond' + + '(domain)' + {-k,--kernel}'[select the Linux kernel tracing domain]' + "($kernel_ip_opt_excl)"{-u,--userspace}'[select the user space tracing domain]' + "($kernel_ip_opt_excl)"{-j,--jul}'[select the `java.util.logging` tracing domain]' + ) + + # Add tracing domain option specifications based on the minor version + # of LTTng-tools. + if ((minor_version >= 6)); then + specs+=( + "($kernel_ip_opt_excl)"{-l,--log4j}'[select the Apache log4j tracing domain]' + ) + fi + + if ((minor_version >= 7)); then + specs+=( + "($kernel_ip_opt_excl)"{-p,--python}'[select the Python tracing domain]' + ) + fi + + # Add instrumentation point type option specifications based on the + # minor version of LTTng-tools. + if ((minor_version >= 6)); then + specs+=( + + '(ip)' + "($non_kernel_domain_opt_excl)--syscall[disable recording ER matching Linux system call events]" + ) + fi + + if ((minor_version >= 7)); then + specs+=( + '--tracepoint[disable recording ER matching tracepoint events]' + "($non_kernel_domain_opt_excl)--probe[disable recording ER matching kprobe events]" + "($non_kernel_domain_opt_excl)--function[disable recording ER matching kretprobe events]" + ) + fi + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `disable-rotation` command. +__lttng_complete_disable_rotation_cmd() { + local -r specs=( + $help_opt_specs + '(-s --session)'{-s+,--session=}'[select a specific recording session]: : __lttng_complete_session_name all all' + '--timer[disable the periodic rotation schedule]' + '--size[disable the size-based rotation schedule]' + ) + + __lttng_arguments $specs +} + +# Adds completions for a channel output type (`mmap` and, possibly, +# `splice`) (for the `--output` option of the `enable-channel` command). +# +# This function replaces the argument field of the current context with +# `output-opt`. +# +# This function relies on the user space tracing domain options of +# `$opt_args` to restrict the offered completions. Without the user +# space tracing domain option, this function adds the `splice` +# completion too. +__lttng_complete_channel_output_type() { + local output_types=(mmap) + + if ! __lttng_user_domain_opt_is_set; then + # Linux kernel tracing domain or none + output_types+=(splice) + fi + + local expl + + _wanted -C 'output-opt' values expl 'output type' compadd -a output_types +} + +# Adds completions for the non-option argument of the `enable-channel` +# command. +# +# This function either, depending on the keys of `$opt_args`: +# +# At least one creation option: +# Shows a message to enter the new channel name. +# +# Otherwise: +# Adds completions for a comma-separated list of known channel names +# using __lttng_complete_channel_name(). +__lttng_complete_enable_channel_cmd_names() { + local key + local -r enable_opts=( + -s --session + domain---kernel domain--k + domain---userspace domain--u + ) + + # For each key of `$opt_args` + for key in "${(@k)opt_args}"; do + if (($enable_opts[(Ie)$key])); then + # Enabling option exists: skip + continue + fi + + # Creation option exists: single name + _guard '^-*' 'new channel name' + return + done + + # Comma-separated list of existing channel names + _sequence __lttng_complete_channel_name disabled opt +} + +# Adds completions for the arguments of the `enable-channel` command. +__lttng_complete_enable_channel_cmd() { + local specs=( + $help_opt_specs + '--switch-timer=[set the switch timer period]:switch timer period (µs):' + '--read-timer=[set the read timer period]:read timer period (µs):' + '--subbuf-size=[set the size of each sub-buffer]:sub-buffer size (bytes; `k`/`M`/`G` suffixes supported):' + '--num-subbuf=[set the number of sub-buffers per ring buffer]:sub-buffer count:' + '--tracefile-size=[set the maximum size of each trace file]:trace file size (bytes; `k`/`M`/`G` suffixes supported):' + '--tracefile-count=[set the maximum number of trace files]:maximum trace file count:' + '--output=[set the output type]: : __lttng_complete_channel_output_type' + '(-s --session)'{-s+,--session=}'[select a specific recording session]: : __lttng_complete_session_name all all' + ': : __lttng_complete_enable_channel_cmd_names' + ) + + # The `--blocking-timeout` and `--monitor-timer` options require + # LTTng-tools ≥ 2.10. + if ((minor_version >= 10)); then + specs+=( + '(--kernel --overwrite --buffers-global)--blocking-timeout=[set the blocking timeout]:blocking timeout (µs):' + '--monitor-timer=[set the monitor timer period]:monitor timer period (µs):' + ) + fi + + # Add the remaining option groups + specs+=( + + '(domain)' + '(--blocking-timeout --buffers-uid --buffers-pid)'{-k,--kernel}'[select the Linux kernel tracing domain]' + '(--buffers-global)'{-u,--userspace}'[select the user space tracing domain]' + + '(loss-mode)' + '--discard[discard event records with no available sub-buffer]' + '(--blocking-timeout)--overwrite[overwrite oldest sub-buffer with no available sub-buffer]' + + '(buffering)' + '(-k --kernel)--buffers-uid[use per-user ring buffers]' + '(-k --kernel)--buffers-pid[use per-process ring buffers]' + '(-u --userspace --blocking-timeout)--buffers-global[use global ring buffers]' + ) + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `enable-event` command. +__lttng_complete_enable_event_cmd() { + local -r kernel_opts_excl=( + -k --kernel + --syscall + --probe + --userspace-probe + --function + ) + local -r non_kernel_opts_excl=( + $non_kernel_domain_opt_excl + -x --exclude + log-level + ) + local -r exclude_opt_excl=( + $kernel_opts_excl + -j --jul + -l --log4j + -p --python + -x --exclude + ) + local ip_specs=( + '--tracepoint[only match LTTng tracepoint events]' + "($non_kernel_opts_excl)--syscall[only match Linux system call events]" + "($non_kernel_opts_excl)--probe=[only match kprobe events]:kprobe location:" + "($non_kernel_opts_excl)--function=[only match kretprobe events]:kretprobe location:" + ) + local domain_specs=( + "($non_kernel_opts_excl)"{-k,--kernel}'[select the Linux kernel tracing domain]' + "($kernel_opts_excl)"{-u,--userspace}'[select the user space tracing domain]' + "($kernel_opts_excl -x --exclude)"{-j,--jul}'[select the `java.util.logging` tracing domain]' + ) + + # The Apache log4j tracing domain options require LTTng-tools ≥ 2.6 + if ((minor_version >= 6)); then + domain_specs+=( + "($kernel_opts_excl -x --exclude)"{-l,--log4j}'[select the Apache log4j tracing domain]' + ) + fi + + # The Python tracing domain options require LTTng-tools 2.7 + if ((minor_version >= 7)); then + domain_specs+=( + "($kernel_opts_excl -x --exclude)"{-p,--python}'[select the Python tracing domain]' + ) + fi + + # The Linux user space probe instrumentation options require LTTng-tools 2.11 + if ((minor_version >= 11)); then + ip_specs+=( + "($non_kernel_opts_excl)--userspace-probe=[only match Linux user space probe events]:user space probe location:" + ) + fi + + # Add completions. + # + # There's no way, based on the command-line arguments, to distinguish + # between creating a new recording event rule and enabling an + # existing, disabled recording event rule here. + # + # For example, given this: + # + # $ lttng enable-event --kernel --syscall + # + # At this point, the user might want the list of existing, disabled + # kernel system call recording event rule names (current recording + # session, default channel name), or the full list of available system + # call instrumentation point names. + # + # This function makes the arbitrary choice to provide the available + # instrumentation point names (__lttng_complete_ip_name()) because, + # interactively, it seems to be more common/useful than disabling + # existing recording event rules. + local -r specs=( + $help_opt_specs + '(--probe --userspace-probe --function -f --filter)'{-f+,--filter=}'[only match events which satisfy an expression]:filter expression:' + "($exclude_opt_excl)"{-x+,--exclude=}'[exclude event name patterns]:comma-separated list of patterns:' + '(-s --session)'{-s+,--session=}'[select a specific recording session]: : __lttng_complete_session_name all all' + '(-c --channel)'{-c+,--channel=}'[select a specific channel]: : __lttng_complete_channel_name all opt' + + '(log-level)' + "($kernel_opts_excl)--loglevel=[only match events with specific log levels]: : __lttng_complete_log_level" + "($kernel_opts_excl)--loglevel-only=[only match events with an exact log level]: : __lttng_complete_log_level" + + '(names)' + {-a,--all}'[match events regardless of their name]' + ': :_sequence __lttng_complete_ip_name' + + '(ip)' $ip_specs + + '(domain)' $domain_specs + ) + + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `enable-rotation` command. +__lttng_complete_enable_rotation_cmd() { + local -r specs=( + $help_opt_specs + '(-s --session)'{-s+,--session=}'[select a specific recording session]: : __lttng_complete_session_name all all' + '--timer=[rotate periodically]:period (µs; `ms`/`s`/`m`/`h` suffixes supported):' + '--size=[rotate based on flushed size of current trace chunk]:size (bytes; `k`/`M`/`G` suffixes supported):' + ) + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `help` command. +__lttng_complete_help_cmd() { + local -r specs=( + $help_opt_specs + ': : __lttng_complete_cmd_name' + ) + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `list` command. +__lttng_complete_list_cmd() { + local -r domain_opt_excl=( + -d --domain + -f --fields + -c --channel + -k --kernel + -u --userspace + -j --jul + -l --log4j + -p --python + --syscall + ) + local specs=( + $help_opt_specs + '(-d --domain -f --fields --syscall -c --channel 1)'{-f,--fields}'[show instrumentation point fields]' + "($domain_opt_excl)"{-d,--domain}'[show tracing domains with at least one channel]' + '(-d --domain -f --fields --syscall -c --channel)'{-c+,--channel=}'[list the objects of a specific channel]: : __lttng_complete_channel_name all arg' + '(-d --domain -f --fields --syscall):recording session name: __lttng_complete_session_name all all' + '(-d --domain -k --kernel)'{-k,--kernel}'[list Linux kernel tracing domain objects]' + '(-d --domain -u --userspace)'{-u,--userspace}'[list user space tracing domain objects]' + '(-d --domain -j --jul)'{-j,--jul}'[list `java.util.logging` tracing domain objects]' + ) + + # The Apache log4j tracing domain and `--syscall` options require + # LTTng-tools ≥ 2.6. + if ((minor_version >= 6)); then + specs+=( + '(-d --domain -l --log4j)'{-l,--log4j}'[list Apache log4j tracing domain objects]' + '(-d --domain)--syscall[list Linux kernel system calls]' + ) + fi + + # The Python tracing domain options require LTTng-tools 2.7 + if ((minor_version >= 7)); then + specs+=( + '(-d --domain -p --python)'{-p,--python}'[list Python tracing domain objects]' + ) + fi + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `list-triggers` command. +__lttng_complete_list_triggers_cmd() { + __lttng_arguments $help_opt_specs +} + +# Adds completions for the arguments of the `load` command. +__lttng_complete_load_cmd() { + local specs=( + $help_opt_specs + '(-f --force)'{-f,--force}'[overwrite existing recording sessions]' + '(-i --input-path)'{-i+,--input-path=}'[load recording session configurations from a specific path]:recording session configuration path:_files' + '(-a --all --override-name 1)'{-a,--all}'[load all recording session configurations]' + '(-a --all):recording session configuration name:_guard "^-*" "recording session name"' + ) + + if ((minor_version >= 9)); then + specs+=( + '--override-url=[override the loaded recording session output URL]:output URL:' + '(-a --all)--override-name=[override the loaded recording session name]:recording session name:' + ) + fi + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `metadata` command +# (deprecated). +__lttng_complete_metadata_cmd() { + local -r specs=( + $help_opt_specs + ':action:(regenerate)' + '(-s --session)'{-s+,--session=}'[select a specific recording session]: : __lttng_complete_session_name all all' + ) + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `regenerate` command. +__lttng_complete_regenerate_cmd() { + local -r specs=( + $help_opt_specs + ':trace data type:(metadata statedump)' + '(-s --session)'{-s+,--session=}'[select a specific recording session]: : __lttng_complete_session_name all all' + ) + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `remove-trigger` command. +__lttng_complete_remove_trigger_cmd() { + local -r specs=( + $help_opt_specs + '--owner-uid=[remove the trigger as another Unix user]: : __lttng_complete_uid' + ': : __lttng_complete_trigger_name' + ) + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `rotate` command. +__lttng_complete_rotate_cmd() { + local -r specs=( + $help_opt_specs + '(-n --no-wait)'{-n,--no-wait}'[exit immediately]' + ': : __lttng_complete_session_name all all' + ) + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `save` command. +__lttng_complete_save_cmd() { + local -r specs=( + $help_opt_specs + '(-f --force)'{-f,--force}'[overwrite existing recording session configuration files]' + '(-o --output-path)'{-o+,--output-path=}'[save recording session configuration files to a specific directory]:recording session configuration directory:_files -/' + '(-a --all 1)'{-a,--all}'[save all recording session configurations]' + '(-a --all): : __lttng_complete_session_name all all' + ) + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `set-session` command. +__lttng_complete_set_session_cmd() { + local -r specs=( + $help_opt_specs + ': : __lttng_complete_session_name all all' + ) + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `snapshot` command. +__lttng_complete_snapshot_cmd() { + local specs=( + $help_opt_specs + '(-): : __lttng_complete_snapshot_action_name' \ + '(-)*:: :->action-args' \ + ) + + # Add action name completions + local curcontext=$curcontext state state_descr line + local -A opt_args + + _arguments -C -s -W : $specs + + if (($? == 0)); then + # Completions added: we're done + return + fi + + # Add action-specific completions + local -r common_session_specs=( + '(-s --session)'{-s+,--session=}'[select a specific recording session]: : __lttng_complete_session_name all snapshot' + ) + local -r common_output_specs=( + '(-m --max-size)'{-m+,--max-size=}'[set the maximum total size of all snapshot files]:maximum size (bytes; `k`/`M`/`G` suffixes supported):' + '(-n --name)'{-n+,--name=}'[set the snapshot output name]:snapshot output name:' + '(1 -C --ctrl-url output)'{-C+,--ctrl-url=}'[set the control URL]:control URL:' + '(1 -D --data-url output)'{-D+,--data-url=}'[set the trace data output URL]:trace data output URL:' + '(-C --ctrl-url -D --data-url): :_guard "^-*" "snapshot output URL"' + ) + + if [[ $state[1] = action-args ]]; then + # Add completions for the arguments of the specific snapshot action + curcontext=${curcontext%:*:*}:lttng-snapshot-$line[1]: + + case $line[1] in + add-output | record) + specs=($common_session_specs $common_output_specs);; + del-output) + specs=($common_session_specs ':snapshot output index:(1)');; + list-output) + specs=($common_session_specs);; + *) + _message "unknown snapshot action \`$line[1]\`" + return 1 + ;; + esac + + # Add completions + __lttng_arguments $specs + return + fi + + return 1 +} + +# Adds completions for the arguments of the `start` command. +__lttng_complete_start_cmd() { + local -r specs=( + $help_opt_specs + ': : __lttng_complete_session_name inactive all' + ) + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `stop` command. +__lttng_complete_stop_cmd() { + local -r specs=( + $help_opt_specs + '(-n --no-wait)'{-n,--no-wait}'[exit immediately]' + ': : __lttng_complete_session_name active all' + ) + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `status` command. +__lttng_complete_status_cmd() { + __lttng_arguments $help_opt_specs +} + +# Adds completions for the arguments of the `track` command. +__lttng_complete_track_cmd() { + local specs=( + $help_opt_specs + '(-s --session)'{-s+,--session=}'[select a specific recording session]: : __lttng_complete_session_name all all' + '(-a --all)'{-a,--all}'[add all possible values to the selected inclusion sets]' + '(-p --pid)'{-p+,--pid=}'[add values to the process ID inclusion set]:process ID(s):_sequence _pids' + ) + + # Virtual PID and user/group inclusion sets require LTTng-tools ≥ 2.12 + if ((minor_version >= 12)); then + specs+=( + '--vpid=[add values to the virtual process ID inclusion set]:virtual process ID(s):_sequence _pids' + '(-u --userspace)--uid=[add values to the user ID inclusion set]:user(s):_sequence _users' + '--vuid=[add values to the virtual user ID inclusion set]:virtual user(s):_sequence _users' + '(-u --userspace)--gid=[add values to the group ID inclusion set]:group(s):_sequence _groups' + '--vgid=[add values to the virtual group ID inclusion set]:virtual group(s):_sequence _groups' + ) + fi + + # Append tracing domain specifications + specs+=( + + '(domain)' + {-k,--kernel}'[select the Linux kernel tracing domain]' + "(--uid --gid)"{-u,--userspace}'[select the user space tracing domain]' + ) + + # Add completions + __lttng_arguments $specs +} + +# Adds completions for the arguments of the `untrack` command. +__lttng_complete_untrack_cmd() { + # As of LTTng-tools 2.13, the `track` and `untrack` commands expect + # the same arguments. + __lttng_complete_track_cmd +} + +# Adds completions for the arguments of the `version` command. +__lttng_complete_version_cmd() { + __lttng_arguments $help_opt_specs +} + +# Adds completions for the arguments of the `view` command. +__lttng_complete_view_cmd() { + local -r specs=( + $help_opt_specs + '(-e --viewer)'{-e+,--viewer=}'[set the trace reader path]:trace reader path:_files' + '(-t --trace-path): : __lttng_complete_session_name all all' + '(1 -t --trace-path)'{-t+,--trace-path=}'[set the trace directory to pass to the reader]:trace directory:_files -/' + ) + + # Add completions + __lttng_arguments $specs +} + +# Add completions for the specific `lttng` command named `$line[1]`. +__lttng_complete_cmd() { + # An lttng(1) command: replace `lttng` with `lttng-$line[1]` (for + # example, `lttng-add-trigger`). + curcontext=${curcontext%:*:*}:lttng-$line[1]: + + # Keep the tracing group: we need to execute `lttng` for some + # completions and use the required tracing group to connect to the + # same session daemon. + # + # The default tracing group is `tracing`. + local tracing_group=tracing + + if (($+opt_args[-g])); then + tracing_group=$opt_args[-g] + elif (($+opt_args[--group])); then + tracing_group=$opt_args[--group] + fi + + # Add command completions: dispatch to a dedicated function + local -r func_name=__lttng_complete_${line[1]//-/_}_cmd + + if ! typeset -f $func_name >/dev/null; then + _message "unknown command \`$line[1]\`" + return 1 + fi + + local -A opt_args + + $func_name +} + +# Save program name +local -r prog_name=$words[1] + +# First, set the `minor_version` variable to the minor version of +# LTTng-tools. Some features depend on a specific version and this +# completion function supports many versions from LTTng-tools 2.5. +local -i minor_version + +__lttng_set_minor_version + +# Exit now with LTTng-tools < 2.5 or LTTng-tools > 2.14 +local -r ignore_version_limit=${LTTNG_ZSH_COMP_IGNORE_VERSION_LIMIT:-0} + +if ((minor_version < 5 || (minor_version > 14 && !ignore_version_limit))); then + _message "completion not available for LTTng-tools 2.$minor_version; please update the completion files or set \`LTTNG_ZSH_COMP_IGNORE_VERSION_LIMIT=1\`" + return 1 +fi + +# Common help option specifications +local -r help_opt_specs=( + '(- : *)'{-h,--help}'[show help]' +) + +# Common non Linux kernel tracing domain option exclusions +local -r non_kernel_domain_opt_excl=(-u --userspace -j --jul -l --log4j -p --python) + +# General option specifications +local gen_opt_specs=( + $help_opt_specs + '(- : *)--list-commands[list the available commands and quit]' + '--relayd-path=[set the relay daemon path]:relay daemon path:_files -g \*lttng-relayd' + '--group=[set the tracing group]:tracing group:_groups' + '(-q --quiet)*'{-v,--verbose}'[increase verbosity]' + '(-q --quiet -v --verbose)'{-q,--quiet}'[suppress all messages, including warnings and errors]' + '(- : *)'{-V,--version}'[show version and quit]' +) + +# MI output requires LTTng-tools ≥ 2.6 +if ((minor_version >= 6)); then + gen_opt_specs+=( + '(-m --mi)'{-m+,--mi=}'[use the machine interface output]:machine interface type:(xml)' + ) +fi + +# Append session daemon option specifications +gen_opt_specs+=( + + '(sessiond)' + {-n,--no-sessiond}'[do not spawn a session daemon]' + '--sessiond-path=[set the session daemon path]:session daemon path:_files -g \*lttng-sessiond' +) + +# Add general option and command name completions +local curcontext=$curcontext state state_descr line +local -A opt_args + +_arguments -C -s -W : \ + '(-): : __lttng_complete_cmd_name' \ + '(-)*:: :->cmd-args' \ + $gen_opt_specs + +local -ir main_ret=$? + +if ((main_ret == 0)); then + # Completions added: we're done + return +fi + +if [[ $state[1] = cmd-args ]]; then + # Add completions for the arguments of the specific command + __lttng_complete_cmd + return +fi + +return $main_ret diff --git a/extras/zsh-completion/_lttng-crash b/extras/zsh-completion/_lttng-crash new file mode 100644 index 000000000..f595217da --- /dev/null +++ b/extras/zsh-completion/_lttng-crash @@ -0,0 +1,75 @@ +#compdef lttng-crash +# +# Copyright (c) 2015-2023 Philippe Proulx +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. +# +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# +# This is a Zsh completion function for the lttng-crash(1) command (see +# ), for versions 2.7 to 2.14. +# +# If you want, at your own risk, the function to work with versions +# above 2.14, set `LTTNG_ZSH_COMP_IGNORE_VERSION_LIMIT=1`. + +# Sets the `minor_version` variable to the minor version of LTTng-tools, +# or to `0` if not found. +__lttng_set_minor_version() { + minor_version=0 + + local -a match + + if [[ $($words[1] --version) =~ '[[:blank:]]+2\.([[:digit:]]+)' ]]; then + minor_version=$match[1] + fi +} + +# Adds completions for the arguments of the `lttng-crash` command. +__lttng_complete_lttng_crash() { + local curcontext=$curcontext state state_descr line + local -A opt_args + local specs=( + '*'{-v,--verbose}'[increase verbosity]' + '(- : *)'{-V,--version}'[show version and quit]' + '(- : *)'{-h,--help}'[show help]' + '(-x --extract)'{-x+,--extract=}'[set the path of the directory where to extract the trace]:trace extraction directory path:_directories' + '(-e --viewer)'{-e+,--viewer=}'[set the trace reader command]:trace reader command:_files' + '1:shared memory directory:_directories' + ) + + _arguments -C -s -w : $specs +} + +# First, set the `minor_version` variable to the minor version of +# LTTng-tools. Some features depend on a specific version and this +# completion function supports many versions from LTTng-tools 2.7. +local -i minor_version + +__lttng_set_minor_version + +# Exit now with LTTng-tools < 2.7 or LTTng-tools > 2.14 +local -r ignore_version_limit=${LTTNG_ZSH_COMP_IGNORE_VERSION_LIMIT:-0} + +if ((minor_version < 7 || (minor_version > 14 && !ignore_version_limit))); then + _message "completion not available for LTTng-tools 2.$minor_version; please update the completion files or set \`LTTNG_ZSH_COMP_IGNORE_VERSION_LIMIT=1\`" + return 1 +fi + +# Add completions for lttng-crash(1) +__lttng_complete_lttng_crash "$@" diff --git a/extras/zsh-completion/_lttng-relayd b/extras/zsh-completion/_lttng-relayd new file mode 100644 index 000000000..8d1140ff1 --- /dev/null +++ b/extras/zsh-completion/_lttng-relayd @@ -0,0 +1,93 @@ +#compdef lttng-relayd +# +# Copyright (c) 2015-2023 Philippe Proulx +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. +# +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# +# This is a Zsh completion function for the lttng-relayd(1) command +# (see ), for versions 2.5 to 2.14. +# +# If you want, at your own risk, the function to work with versions +# above 2.14, set `LTTNG_ZSH_COMP_IGNORE_VERSION_LIMIT=1`. + +# Sets the `minor_version` variable to the minor version of LTTng-tools, +# or to `0` if not found. +__lttng_set_minor_version() { + minor_version=0 + + local -a match + + if [[ $($words[1] --version) =~ '2\.([[:digit:]]+)' ]]; then + minor_version=$match[1] + fi +} + +# Adds completions for the arguments of the `lttng-relayd` command. +__lttng_complete_lttng_relayd() { + local curcontext=$curcontext state state_descr line + local -A opt_args + + # LTTng-tools 2.5+ + local specs=( + '*'{-v,--verbose}'[increase verbosity]' + '(- : *)'{-V,--version}'[show version and quit]' + '(- : *)'{-h,--help}'[show help]' + '(-d --daemonize -b --background)'{-d,--daemonize}'[start as daemon and close file descriptors (console)]' + '(-b --background -d --daemonize)'{-b,--background}'[start as daemon, but keep file descriptors (console) open]' + '(-C --control-port)'{-C+,--control-port=}'[set the control port URL]:control port URL: ' + '(-D --data-port)'{-D+,--data-port=}'[set the data port URL]:data port URL: ' + '(-L --live-port)'{-L+,--live-port=}'[set the live port URL]:live port URL: ' + '(-o --output)'{-o+,--output=}'[set the trace output directory path]:trace output directory path:_directories' + '(-g --group)'{-g+,--group=}'[set the Unix tracing group name]:Unix tracing group name:_groups' + '(-f --config)'{-f+,--config=}'[set the path to the INI daemon configuration file]:configuration file path:_files' + ) + + # LTTng-tools 2.12+ + if ((minor_version >= 12)); then + specs+=( + '(--fd-pool-size)--fd-pool-size=[set the size of the file descriptor pool]:file descriptor pool size: ' + '(-w --working-directory)'{-w+,--working-directory=}'[set the working directory of the processes `lttng-relayd` creates]:working directory:_directories' + '(-p --group-output-by-host -s --group-output-by-session)'{-p,--group-output-by-host}'[group the written trace directories by hostname]' + '(-p --group-output-by-host -s --group-output-by-session)'{-s,--group-output-by-session}'[group the written trace directories by recording session name]' + '(-x --disallow-clear)'{-x,--disallow-clear}'[disallow clearing operations]' + ) + fi + + _arguments -C -s -w : $specs +} + +# First, set the `minor_version` variable to the minor version of +# LTTng-tools. Some features depend on a specific version and this +# completion function supports many versions from LTTng-tools 2.5. +local -i minor_version + +__lttng_set_minor_version + +# Exit now with LTTng-tools < 2.5 or LTTng-tools > 2.14 +local -r ignore_version_limit=${LTTNG_ZSH_COMP_IGNORE_VERSION_LIMIT:-0} + +if ((minor_version < 5 || (minor_version > 14 && !ignore_version_limit))); then + _message "completion not available for LTTng-tools 2.$minor_version; please update the completion files or set \`LTTNG_ZSH_COMP_IGNORE_VERSION_LIMIT=1\`" + return 1 +fi + +# Add completions for lttng-relayd(1) +__lttng_complete_lttng_relayd "$@" diff --git a/extras/zsh-completion/_lttng-sessiond b/extras/zsh-completion/_lttng-sessiond new file mode 100644 index 000000000..7388c0c4f --- /dev/null +++ b/extras/zsh-completion/_lttng-sessiond @@ -0,0 +1,153 @@ +#compdef lttng-sessiond +# +# Copyright (c) 2015-2023 Philippe Proulx +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. +# +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# +# This is a Zsh completion function for the lttng-sessiond(1) command +# (see ), for versions 2.5 to 2.14. +# +# If you want, at your own risk, the function to work with versions +# above 2.14, set `LTTNG_ZSH_COMP_IGNORE_VERSION_LIMIT=1`. + +# Sets the `minor_version` variable to the minor version of LTTng-tools, +# or to `0` if not found. +__lttng_set_minor_version() { + minor_version=0 + + local -a match + + if [[ $($words[1] --version) =~ '2\.([[:digit:]]+)' ]]; then + minor_version=$match[1] + fi +} + +# Adds completions for an LTTng kernel probe name. +__lttng_complete_probe_modules() { + # Find relevant kernel module files + local dir="/usr/lib/modules/$(uname -r)/extra" + + if [[ ! -d $dir ]]; then + dir="/usr/lib/modules/$(uname -r)/updates" + + if [[ ! -d $dir ]]; then + _message "cannot find directory \"$dir\"" + return 1 + fi + fi + + local -a probe_files=("$dir"/**/lttng-probe-*.(ko|ko.gz|ko.zst)(:t)) + + if (($#probe_files == 0)); then + _message "no probe modules found in \"$dir\"" + return 1 + fi + + # Strip prefix and extension + probe_files=(${probe_files#lttng-probe-}) + probe_files=(${probe_files%.gz}) + probe_files=(${probe_files%.zst}) + probe_files=(${probe_files%.ko}) + + # Add completions + local expl + + compadd "$@" -a - probe_files +} + +# Adds completions for the arguments of the `lttng-sessiond` command. +__lttng_complete_lttng_sessiond() { + local curcontext=$curcontext state state_descr line + local -A opt_args + + # LTTng-tools 2.5+ + local specs=( + '(-q --quiet)*'{-v,--verbose}'[increase verbosity]' + '(-q --quiet -v --verbose)'{-q,--quiet}'[suppress all messages, including warnings and errors]' + '(- : *)'{-V,--version}'[show version and quit]' + '(- : *)'{-h,--help}'[show help]' + '(-c --client-sock)'{-c+,--client-sock=}'[set the path to the client Unix socket]:client Unix socket path:_files' + '(-a --apps-sock)'{-a+,--apps-sock=}'[set the path to the app Unix socket]:app Unix socket path:_files' + '--kconsumerd-err-sock=[set the path to the kernel consumer daemon error socket]:kernel consumer daemon error Unix socket path:_files' + '--kconsumerd-cmd-sock=[set the path to the kernel consumer daemon command socket]:kernel consumer daemon command Unix socket path:_files' + '--ustconsumerd32-err-sock=[set the path to the 32-bit UST consumer daemon error Unix socket]:32-bit UST consumer daemon error Unix socket path:_files' + '--ustconsumerd32-cmd-sock=[set the path to the 32-bit UST consumer daemon command Unix socket]:32-bit UST consumer daemon command Unix socket path:_files' + '--ustconsumerd64-err-sock=[set the path to the 64-bit UST consumer daemon error Unix socket]:64-bit UST consumer daemon error Unix socket path:_files' + '--ustconsumerd64-cmd-sock=[set the path to the 64-bit UST consumer daemon command Unix socket]:64-bit UST consumer daemon command Unix socket path:_files' + '--consumerd32-path=[set the path to the 32-bit UST consumer daemon]:32-bit UST consumer daemon path:_files' + '--consumerd32-libdir=[set the path to the directory containing 32-bit UST consumer daemon libraries]:32-bit UST consumer daemon libraries directory path:_directories' + '--consumerd64-path=[set the path to the 64-bit UST consumer daemon]:64-bit UST consumer daemon path:_files' + '--consumerd64-libdir=[set the path to the directory containing 64-bit UST consumer daemon libraries]:64-bit UST consumer daemon libraries directory path:_directories' + '(-d --daemonize -b --background)'{-d,--daemonize}'[start as daemon and close file descriptors (console)]' + '(-b --background -d --daemonize)'{-b,--background}'[start as daemon, but keep file descriptors (console) open]' + '(-g --group)'{-g+,--group=}'[set the Unix tracing group name]:Unix tracing group name:_groups' + '(-S --sig-parent)'{-S,--sig-parent}'[send the USR1 signal to the parent process to notify readiness]' + '(-p --pidfile)'{-p+,--pidfile=}'[set the path to the PID file]:PID file path:_files' + "--verbose-consumer[increase verbosity of consumer daemon]" + '(--kmod-probes --extra-kmod-probes)--no-kernel[disable the kernel tracer]' + '(-f --config)'{-f+,--config=}'[set the path to the INI daemon configuration file]:configuration file path:_files' + '(-l --load)'{-l+,--load=}'[set the path from which to load recording session configurations]:recording session configurations path:_files' + '(--no-kernel --kmod-probes)--extra-kmod-probes=[extra kernel probe modules to load]:kernel probe module:_sequence __lttng_complete_probe_modules' + ) + + # LTTng-tools 2.5 only + if ((minor_version == 5)); then + specs+=( + '--jul-tcp-port=[set the TCP port on which to listen for `java.util.logging` application registration]:JUL application registration TCP port: ' + ) + fi + + # LTTng-tools 2.6+ + if ((minor_version >= 6)); then + specs+=( + '--agent-tcp-port=[set the TCP port on which to listen for agent application registration]:agent application registration TCP port: ' + '(--no-kernel --extra-kmod-probes)--kmod-probes=[kernel probe modules to load]:kernel probe module:_sequence __lttng_complete_probe_modules' + ) + fi + + # LTTng-tools 2.13+ + if ((minor_version >= 13)); then + specs+=( + '--event-notifier-error-buffer-size-kernel=[set the size of the kernel event notifier error counter buffers]:kernel event notifier error counter buffer size (slots): ' + '--event-notifier-error-buffer-size-userspace=[set the size of the user space event notifier error counter buffers]:user space event notifier error counter buffer size (slots): ' + ) + fi + + _arguments -C -s -w : $specs +} + +# First, set the `minor_version` variable to the minor version of +# LTTng-tools. Some features depend on a specific version and this +# completion function supports many versions from LTTng-tools 2.5. +local -i minor_version + +__lttng_set_minor_version + +# Exit now with LTTng-tools < 2.5 or LTTng-tools > 2.14 +local -r ignore_version_limit=${LTTNG_ZSH_COMP_IGNORE_VERSION_LIMIT:-0} + +if ((minor_version < 5 || (minor_version > 14 && !ignore_version_limit))); then + _message "completion not available for LTTng-tools 2.$minor_version; please update the completion files or set \`LTTNG_ZSH_COMP_IGNORE_VERSION_LIMIT=1\`" + return 1 +fi + +# Add completions for lttng-sessiond(1) +__lttng_complete_lttng_sessiond "$@" diff --git a/format-cpp b/format-cpp new file mode 100755 index 000000000..17275de77 --- /dev/null +++ b/format-cpp @@ -0,0 +1,56 @@ +#!/bin/bash +# +# SPDX-License-Identifier: GPL-2.0-only +# +# Copyright (C) 2020-2022 Philippe Proulx + +expected_formatter_major_version=14 + +# Runs the formatter, making sure it's the expected version. +format_cpp() { + local formatter=$1 + local version + + version=$($formatter --version) + + # shellcheck disable=SC2181 + if (($? != 0)); then + echo "Cannot execute \`$formatter --version\`." >&2 + return 1 + fi + + if [[ "$version" != *"clang-format version $expected_formatter_major_version"* ]]; then + echo "Expecting clang-format $expected_formatter_major_version." >&2 + echo -n Got: >&2 + echo " \`$version\`" >&2 + echo >&2 + echo "Use the FORMATTER environment variable to specify the location of clang-format $expected_formatter_major_version" + return 1 + fi + + local root_dir + + root_dir="$(dirname "${BASH_SOURCE[0]}")" + + # Using xargs to fail as soon as the formatter fails (`-exec` + # won't stop if its subprocess fails). + # + # shellcheck disable=SC2086 + find "$root_dir" -path './src/vendor' -prune \ + -o -type f \( -name '*\.h' -o -name '*\.hpp' -o -name '*\.c' -o -name '*\.cpp' \) \ + -not -path '*/\.*' -print0 | xargs -P$(nproc) -n1 -0 $formatter -i --style=file --fallback-style=none +} + +if [[ -n "$FORMATTER" ]]; then + # Try using environment-provided formatter + formatter=$FORMATTER +elif command -v clang-format-$expected_formatter_major_version &> /dev/null; then + # Try using the expected version of clang-format + formatter="clang-format-$expected_formatter_major_version" +else + # Try using `clang-format` as is + formatter='clang-format' +fi + +# Try to format files +format_cpp "$formatter" diff --git a/include/Makefile.am b/include/Makefile.am index d840d58dc..a2d6a5cf0 100644 --- a/include/Makefile.am +++ b/include/Makefile.am @@ -110,6 +110,7 @@ lttnginclude_HEADERS = \ lttng/event.h \ lttng/handle.h \ lttng/health.h \ + lttng/kernel.h \ lttng/kernel-probe.h \ lttng/load.h \ lttng/location.h \ diff --git a/include/lttng/action/action-internal.hpp b/include/lttng/action/action-internal.hpp index 996e166ec..bf55fa803 100644 --- a/include/lttng/action/action-internal.hpp +++ b/include/lttng/action/action-internal.hpp @@ -13,7 +13,9 @@ #include #include #include + #include + #include #include #include @@ -24,22 +26,17 @@ struct mi_writer; struct mi_lttng_error_query_callbacks; struct lttng_trigger; -typedef bool (*action_validate_cb)(struct lttng_action *action); -typedef void (*action_destroy_cb)(struct lttng_action *action); -typedef int (*action_serialize_cb)(struct lttng_action *action, - struct lttng_payload *payload); -typedef bool (*action_equal_cb)(const struct lttng_action *a, - const struct lttng_action *b); -typedef ssize_t (*action_create_from_payload_cb)( - struct lttng_payload_view *view, - struct lttng_action **action); -typedef const struct lttng_rate_policy *(*action_get_rate_policy_cb)( - const struct lttng_action *action); -typedef enum lttng_action_status (*action_add_error_query_results_cb)( - const struct lttng_action *action, - struct lttng_error_query_results *results); -typedef enum lttng_error_code (*action_mi_serialize_cb)( - const struct lttng_action *condition, struct mi_writer *writer); +using action_validate_cb = bool (*)(struct lttng_action *); +using action_destroy_cb = void (*)(struct lttng_action *); +using action_serialize_cb = int (*)(struct lttng_action *, struct lttng_payload *); +using action_equal_cb = bool (*)(const struct lttng_action *, const struct lttng_action *); +using action_create_from_payload_cb = ssize_t (*)(struct lttng_payload_view *, + struct lttng_action **); +using action_get_rate_policy_cb = const struct lttng_rate_policy *(*) (const struct lttng_action *); +using action_add_error_query_results_cb = enum lttng_action_status (*)( + const struct lttng_action *, struct lttng_error_query_results *); +using action_mi_serialize_cb = enum lttng_error_code (*)(const struct lttng_action *, + struct mi_writer *); struct lttng_action { struct urcu_ref ref; @@ -75,31 +72,29 @@ struct lttng_action_comm { } LTTNG_PACKED; void lttng_action_init(struct lttng_action *action, - enum lttng_action_type type, - action_validate_cb validate, - action_serialize_cb serialize, - action_equal_cb equal, - action_destroy_cb destroy, - action_get_rate_policy_cb get_rate_policy, - action_add_error_query_results_cb add_error_query_results, - action_mi_serialize_cb mi); + enum lttng_action_type type, + action_validate_cb validate, + action_serialize_cb serialize, + action_equal_cb equal, + action_destroy_cb destroy, + action_get_rate_policy_cb get_rate_policy, + action_add_error_query_results_cb add_error_query_results, + action_mi_serialize_cb mi); bool lttng_action_validate(struct lttng_action *action); -int lttng_action_serialize(struct lttng_action *action, - struct lttng_payload *buf); +int lttng_action_serialize(struct lttng_action *action, struct lttng_payload *buf); ssize_t lttng_action_create_from_payload(struct lttng_payload_view *view, - struct lttng_action **action); + struct lttng_action **action); -bool lttng_action_is_equal(const struct lttng_action *a, - const struct lttng_action *b); +bool lttng_action_is_equal(const struct lttng_action *a, const struct lttng_action *b); void lttng_action_get(struct lttng_action *action); void lttng_action_put(struct lttng_action *action); -const char* lttng_action_type_string(enum lttng_action_type action_type); +const char *lttng_action_type_string(enum lttng_action_type action_type); void lttng_action_increase_execution_request_count(struct lttng_action *action); @@ -109,23 +104,23 @@ void lttng_action_increase_execution_failure_count(struct lttng_action *action); bool lttng_action_should_execute(const struct lttng_action *action); -enum lttng_action_status lttng_action_add_error_query_results( - const struct lttng_action *action, - struct lttng_error_query_results *results); +enum lttng_action_status +lttng_action_add_error_query_results(const struct lttng_action *action, + struct lttng_error_query_results *results); /* * For use by the various lttng_action implementation. Implements the default * behavior to the generic error "execution failure counter" that all actions * (except list, which passes-through) provide. */ -enum lttng_action_status lttng_action_generic_add_error_query_results( - const struct lttng_action *action, - struct lttng_error_query_results *results); -enum lttng_error_code lttng_action_mi_serialize(const struct lttng_trigger *trigger, - const struct lttng_action *action, - struct mi_writer *writer, - const struct mi_lttng_error_query_callbacks - *error_query_callbacks, - struct lttng_dynamic_array *action_path_indexes); +enum lttng_action_status +lttng_action_generic_add_error_query_results(const struct lttng_action *action, + struct lttng_error_query_results *results); +enum lttng_error_code +lttng_action_mi_serialize(const struct lttng_trigger *trigger, + const struct lttng_action *action, + struct mi_writer *writer, + const struct mi_lttng_error_query_callbacks *error_query_callbacks, + struct lttng_dynamic_array *action_path_indexes); #endif /* LTTNG_ACTION_INTERNAL_H */ diff --git a/include/lttng/action/action.h b/include/lttng/action/action.h index 70237e43c..6e303f441 100644 --- a/include/lttng/action/action.h +++ b/include/lttng/action/action.h @@ -39,8 +39,7 @@ enum lttng_action_status { * * Returns the type of an action on success, LTTNG_ACTION_TYPE_UNKNOWN on error. */ -LTTNG_EXPORT extern enum lttng_action_type lttng_action_get_type( - const struct lttng_action *action); +LTTNG_EXPORT extern enum lttng_action_type lttng_action_get_type(const struct lttng_action *action); /* * Destroy (frees) an action object. diff --git a/include/lttng/action/list-internal.hpp b/include/lttng/action/list-internal.hpp index 294a53ca2..607d59818 100644 --- a/include/lttng/action/list-internal.hpp +++ b/include/lttng/action/list-internal.hpp @@ -8,10 +8,16 @@ #ifndef LTTNG_ACTION_LIST_INTERNAL_H #define LTTNG_ACTION_LIST_INTERNAL_H -#include - +#include +#include +#include #include +#include + +#include +#include + struct lttng_action; struct lttng_payload_view; struct mi_writer; @@ -25,18 +31,67 @@ struct lttng_trigger; * On success, return the number of bytes consumed from `view`, and the created * list in `*list`. On failure, return -1. */ -extern ssize_t lttng_action_list_create_from_payload( - struct lttng_payload_view *view, - struct lttng_action **list); - -extern struct lttng_action *lttng_action_list_borrow_mutable_at_index( - const struct lttng_action *list, unsigned int index); - -enum lttng_error_code lttng_action_list_mi_serialize(const struct lttng_trigger *trigger, - const struct lttng_action *action, - struct mi_writer *writer, - const struct mi_lttng_error_query_callbacks - *error_query_callbacks, - struct lttng_dynamic_array *action_path_indexes); +extern ssize_t lttng_action_list_create_from_payload(struct lttng_payload_view *view, + struct lttng_action **list); + +extern struct lttng_action * +lttng_action_list_borrow_mutable_at_index(const struct lttng_action *list, unsigned int index); + +enum lttng_error_code +lttng_action_list_mi_serialize(const struct lttng_trigger *trigger, + const struct lttng_action *action, + struct mi_writer *writer, + const struct mi_lttng_error_query_callbacks *error_query_callbacks, + struct lttng_dynamic_array *action_path_indexes); + +namespace lttng { +namespace ctl { +namespace details { +class action_list_operations { +public: + static lttng_action *get(const lttng_action *list, std::size_t index) noexcept + { + return lttng_action_list_borrow_mutable_at_index(list, index); + } + + static std::size_t size(const lttng_action *list) + { + unsigned int count; + const auto status = lttng_action_list_get_count(list, &count); + + if (status != LTTNG_ACTION_STATUS_OK) { + LTTNG_THROW_INVALID_ARGUMENT_ERROR( + "Failed to get action list element count"); + } + + return count; + } +}; + +class const_action_list_operations { +public: + static const lttng_action *get(const lttng_action *list, std::size_t index) noexcept + { + return lttng_action_list_get_at_index(list, index); + } + + static std::size_t size(const lttng_action *list) + { + return action_list_operations::size(list); + } +}; +} /* namespace details */ + +using action_list_view = utils::random_access_container_wrapper; + +using const_action_list_view = + utils::random_access_container_wrapper; + +} /* namespace ctl */ +} /* namespace lttng */ #endif /* LTTNG_ACTION_LIST_INTERNAL_H */ diff --git a/include/lttng/action/list.h b/include/lttng/action/list.h index 0dfffa296..5fe3a503b 100644 --- a/include/lttng/action/list.h +++ b/include/lttng/action/list.h @@ -33,14 +33,14 @@ LTTNG_EXPORT extern struct lttng_action *lttng_action_list_create(void); * * Adding an action list to an action list is not supported. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_list_add_action( - struct lttng_action *list, struct lttng_action *action); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_list_add_action(struct lttng_action *list, struct lttng_action *action); /* * Get the number of actions in an action list. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_list_get_count( - const struct lttng_action *list, unsigned int *count); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_list_get_count(const struct lttng_action *list, unsigned int *count); /* * Get an action from the action list at a given index. @@ -51,9 +51,8 @@ LTTNG_EXPORT extern enum lttng_action_status lttng_action_list_get_count( * * Returns an action, or NULL on error. */ -LTTNG_EXPORT extern const struct lttng_action *lttng_action_list_get_at_index( - const struct lttng_action *list, - unsigned int index); +LTTNG_EXPORT extern const struct lttng_action * +lttng_action_list_get_at_index(const struct lttng_action *list, unsigned int index); #ifdef __cplusplus } diff --git a/include/lttng/action/notify-internal.hpp b/include/lttng/action/notify-internal.hpp index c923019c3..2d4d1bd4a 100644 --- a/include/lttng/action/notify-internal.hpp +++ b/include/lttng/action/notify-internal.hpp @@ -8,16 +8,15 @@ #ifndef LTTNG_ACTION_NOTIFY_INTERNAL_H #define LTTNG_ACTION_NOTIFY_INTERNAL_H -#include #include +#include struct lttng_action_notify { struct lttng_action parent; struct lttng_rate_policy *policy; }; -ssize_t lttng_action_notify_create_from_payload( - struct lttng_payload_view *view, - struct lttng_action **action); +ssize_t lttng_action_notify_create_from_payload(struct lttng_payload_view *view, + struct lttng_action **action); #endif /* LTTNG_ACTION_NOTIFY_INTERNAL_H */ diff --git a/include/lttng/action/notify.h b/include/lttng/action/notify.h index 3aa55e09c..300e28507 100644 --- a/include/lttng/action/notify.h +++ b/include/lttng/action/notify.h @@ -39,9 +39,9 @@ LTTNG_EXPORT extern struct lttng_action *lttng_action_notify_create(void); * LTTNG_ACTION_STATUS_ERROR on internal error, * LTTNG_ACTION_STATUS_INVALID if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_notify_set_rate_policy( - struct lttng_action *action, - const struct lttng_rate_policy *policy); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_notify_set_rate_policy(struct lttng_action *action, + const struct lttng_rate_policy *policy); /* * Get the rate policy of a notify action. @@ -49,9 +49,9 @@ LTTNG_EXPORT extern enum lttng_action_status lttng_action_notify_set_rate_policy * Returns LTTNG_ACTION_STATUS_OK on success, * LTTNG_ACTION_STATUS_INVALID if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_notify_get_rate_policy( - const struct lttng_action *action, - const struct lttng_rate_policy **policy); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_notify_get_rate_policy(const struct lttng_action *action, + const struct lttng_rate_policy **policy); #ifdef __cplusplus } diff --git a/include/lttng/action/path-internal.hpp b/include/lttng/action/path-internal.hpp index f07776b9b..4ad638449 100644 --- a/include/lttng/action/path-internal.hpp +++ b/include/lttng/action/path-internal.hpp @@ -8,25 +8,25 @@ #ifndef LTTNG_ACTION_PATH_INTERNAL_H #define LTTNG_ACTION_PATH_INTERNAL_H -#include -#include #include +#include #include #include + +#include + #include struct lttng_action_path { struct lttng_dynamic_array indexes; }; -int lttng_action_path_copy(const struct lttng_action_path *src, - struct lttng_action_path **dst); +int lttng_action_path_copy(const struct lttng_action_path *src, struct lttng_action_path **dst); -ssize_t lttng_action_path_create_from_payload( - struct lttng_payload_view *view, - struct lttng_action_path **action_path); +ssize_t lttng_action_path_create_from_payload(struct lttng_payload_view *view, + struct lttng_action_path **action_path); int lttng_action_path_serialize(const struct lttng_action_path *action_path, - struct lttng_payload *payload); + struct lttng_payload *payload); #endif /* LTTNG_ACTION_PATH_INTERNAL_H */ diff --git a/include/lttng/action/path.h b/include/lttng/action/path.h index 6ec91676b..88d8b640d 100644 --- a/include/lttng/action/path.h +++ b/include/lttng/action/path.h @@ -9,8 +9,9 @@ #define LTTNG_ACTION_PATH_H #include -#include + #include +#include struct lttng_action_path; @@ -45,22 +46,20 @@ enum lttng_action_path_status { * * The `indexes` are copied internally and can be disposed-of by the caller. */ -LTTNG_EXPORT extern struct lttng_action_path *lttng_action_path_create( - const uint64_t *indexes, size_t index_count); +LTTNG_EXPORT extern struct lttng_action_path *lttng_action_path_create(const uint64_t *indexes, + size_t index_count); /* * Get the count of indexes in an action path. */ -LTTNG_EXPORT extern enum lttng_action_path_status lttng_action_path_get_index_count( - const struct lttng_action_path *path, size_t *index_count); +LTTNG_EXPORT extern enum lttng_action_path_status +lttng_action_path_get_index_count(const struct lttng_action_path *path, size_t *index_count); /* * Get an index from an action path. */ LTTNG_EXPORT extern enum lttng_action_path_status lttng_action_path_get_index_at_index( - const struct lttng_action_path *path, - size_t path_index, - uint64_t *out_index); + const struct lttng_action_path *path, size_t path_index, uint64_t *out_index); /* * Destroy an action path object. diff --git a/include/lttng/action/rate-policy-internal.hpp b/include/lttng/action/rate-policy-internal.hpp index 5f6eb1f45..643a01cda 100644 --- a/include/lttng/action/rate-policy-internal.hpp +++ b/include/lttng/action/rate-policy-internal.hpp @@ -10,33 +10,29 @@ #include #include + #include #include -#include +#include struct mi_writer; -int lttng_rate_policy_serialize(struct lttng_rate_policy *rate_policy, - struct lttng_payload *buf); +int lttng_rate_policy_serialize(struct lttng_rate_policy *rate_policy, struct lttng_payload *buf); ssize_t lttng_rate_policy_create_from_payload(struct lttng_payload_view *view, - struct lttng_rate_policy **rate_policy); + struct lttng_rate_policy **rate_policy); bool lttng_rate_policy_is_equal(const struct lttng_rate_policy *a, - const struct lttng_rate_policy *b); + const struct lttng_rate_policy *b); -const char *lttng_rate_policy_type_string( - enum lttng_rate_policy_type rate_policy_type); +const char *lttng_rate_policy_type_string(enum lttng_rate_policy_type rate_policy_type); -struct lttng_rate_policy *lttng_rate_policy_copy( - const struct lttng_rate_policy *source); +struct lttng_rate_policy *lttng_rate_policy_copy(const struct lttng_rate_policy *source); -bool lttng_rate_policy_should_execute( - const struct lttng_rate_policy *policy, uint64_t counter); +bool lttng_rate_policy_should_execute(const struct lttng_rate_policy *policy, uint64_t counter); -enum lttng_error_code lttng_rate_policy_mi_serialize( - const struct lttng_rate_policy *policy, - struct mi_writer *writer); +enum lttng_error_code lttng_rate_policy_mi_serialize(const struct lttng_rate_policy *policy, + struct mi_writer *writer); #endif /* LTTNG_RATE_POLICY */ diff --git a/include/lttng/action/rate-policy.h b/include/lttng/action/rate-policy.h index 1cd0126e3..229e14c0d 100644 --- a/include/lttng/action/rate-policy.h +++ b/include/lttng/action/rate-policy.h @@ -8,8 +8,9 @@ #ifndef LTTNG_RATE_POLICY_H #define LTTNG_RATE_POLICY_H -#include #include + +#include #include struct lttng_rate_policy; @@ -37,8 +38,8 @@ enum lttng_rate_policy_type { /* * Get the type of a rate policy. */ -LTTNG_EXPORT extern enum lttng_rate_policy_type lttng_rate_policy_get_type( - const struct lttng_rate_policy *policy); +LTTNG_EXPORT extern enum lttng_rate_policy_type +lttng_rate_policy_get_type(const struct lttng_rate_policy *policy); /* * Create a rate_policy of type `every n`. @@ -50,8 +51,7 @@ LTTNG_EXPORT extern enum lttng_rate_policy_type lttng_rate_policy_get_type( * rate_policy objects must be destroyed using the lttng_rate_policy_destroy() * function. */ -LTTNG_EXPORT extern struct lttng_rate_policy *lttng_rate_policy_every_n_create( - uint64_t interval); +LTTNG_EXPORT extern struct lttng_rate_policy *lttng_rate_policy_every_n_create(uint64_t interval); /* * Get the interval of a every N rate policy. @@ -60,8 +60,8 @@ LTTNG_EXPORT extern struct lttng_rate_policy *lttng_rate_policy_every_n_create( * on success, LTTNG_RATE_FIRING_POLICY_STATUS_INVALID if an invalid * parameter is passed. */ -LTTNG_EXPORT extern enum lttng_rate_policy_status lttng_rate_policy_every_n_get_interval( - const struct lttng_rate_policy *policy, uint64_t *interval); +LTTNG_EXPORT extern enum lttng_rate_policy_status +lttng_rate_policy_every_n_get_interval(const struct lttng_rate_policy *policy, uint64_t *interval); /* * Create a rate_policy of type `once after N`. @@ -74,8 +74,8 @@ LTTNG_EXPORT extern enum lttng_rate_policy_status lttng_rate_policy_every_n_get_ * rate_policy objects must be destroyed using the lttng_rate_policy_destroy() * function. */ -LTTNG_EXPORT extern struct lttng_rate_policy *lttng_rate_policy_once_after_n_create( - uint64_t threshold); +LTTNG_EXPORT extern struct lttng_rate_policy * +lttng_rate_policy_once_after_n_create(uint64_t threshold); /* * Get the threshold of a once after N rate policy. @@ -85,8 +85,8 @@ LTTNG_EXPORT extern struct lttng_rate_policy *lttng_rate_policy_once_after_n_cre * parameter is passed. */ LTTNG_EXPORT extern enum lttng_rate_policy_status -lttng_rate_policy_once_after_n_get_threshold( - const struct lttng_rate_policy *policy, uint64_t *threshold); +lttng_rate_policy_once_after_n_get_threshold(const struct lttng_rate_policy *policy, + uint64_t *threshold); /* * Destroy (frees) a rate policy object. diff --git a/include/lttng/action/rotate-session-internal.hpp b/include/lttng/action/rotate-session-internal.hpp index 5030aeac3..cbab68e39 100644 --- a/include/lttng/action/rotate-session-internal.hpp +++ b/include/lttng/action/rotate-session-internal.hpp @@ -19,8 +19,7 @@ struct lttng_payload_view; * On success, return the number of bytes consumed from `view`, and the created * action in `*action`. On failure, return -1. */ -extern ssize_t lttng_action_rotate_session_create_from_payload( - struct lttng_payload_view *view, - struct lttng_action **action); +extern ssize_t lttng_action_rotate_session_create_from_payload(struct lttng_payload_view *view, + struct lttng_action **action); #endif /* LTTNG_ACTION_ROTATE_SESSION_INTERNAL_H */ diff --git a/include/lttng/action/rotate-session.h b/include/lttng/action/rotate-session.h index 199b6f169..e628c5f52 100644 --- a/include/lttng/action/rotate-session.h +++ b/include/lttng/action/rotate-session.h @@ -33,15 +33,16 @@ LTTNG_EXPORT extern struct lttng_action *lttng_action_rotate_session_create(void * Set the session name of an lttng_action object of type * LTTNG_ACTION_TYPE_ROTATE_SESSION. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_rotate_session_set_session_name( - struct lttng_action *action, const char *session_name); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_rotate_session_set_session_name(struct lttng_action *action, const char *session_name); /* * Get the session name of an lttng_action object of type * LTTNG_ACTION_TYPE_ROTATE_SESSION. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_rotate_session_get_session_name( - const struct lttng_action *action, const char **session_name); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_rotate_session_get_session_name(const struct lttng_action *action, + const char **session_name); /* * Set the rate policy of a rotate session action. @@ -50,9 +51,9 @@ LTTNG_EXPORT extern enum lttng_action_status lttng_action_rotate_session_get_ses * LTTNG_ACTION_STATUS_ERROR on internal error, * LTTNG_ACTION_STATUS_INVALID if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_rotate_session_set_rate_policy( - struct lttng_action *action, - const struct lttng_rate_policy *policy); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_rotate_session_set_rate_policy(struct lttng_action *action, + const struct lttng_rate_policy *policy); /* * Get the rate policy of a rotate session action. @@ -60,9 +61,9 @@ LTTNG_EXPORT extern enum lttng_action_status lttng_action_rotate_session_set_rat * Returns LTTNG_ACTION_STATUS_OK on success, * LTTNG_ACTION_STATUS_INVALID if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_rotate_session_get_rate_policy( - const struct lttng_action *action, - const struct lttng_rate_policy **policy); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_rotate_session_get_rate_policy(const struct lttng_action *action, + const struct lttng_rate_policy **policy); #ifdef __cplusplus } diff --git a/include/lttng/action/snapshot-session-internal.hpp b/include/lttng/action/snapshot-session-internal.hpp index 27a8795ad..3943fe8f3 100644 --- a/include/lttng/action/snapshot-session-internal.hpp +++ b/include/lttng/action/snapshot-session-internal.hpp @@ -8,10 +8,10 @@ #ifndef LTTNG_ACTION_SNAPSHOT_SESSION_INTERNAL_H #define LTTNG_ACTION_SNAPSHOT_SESSION_INTERNAL_H -#include - #include +#include + struct lttng_action; struct lttng_payload_view; @@ -21,8 +21,7 @@ struct lttng_payload_view; * On success, return the number of bytes consumed from `view`, and the created * action in `*action`. On failure, return -1. */ -extern ssize_t lttng_action_snapshot_session_create_from_payload( - struct lttng_payload_view *view, - struct lttng_action **action); +extern ssize_t lttng_action_snapshot_session_create_from_payload(struct lttng_payload_view *view, + struct lttng_action **action); #endif /* LTTNG_ACTION_SNAPSHOT_SESSION_INTERNAL_H */ diff --git a/include/lttng/action/snapshot-session.h b/include/lttng/action/snapshot-session.h index 859086200..aadb784b2 100644 --- a/include/lttng/action/snapshot-session.h +++ b/include/lttng/action/snapshot-session.h @@ -34,15 +34,17 @@ LTTNG_EXPORT extern struct lttng_action *lttng_action_snapshot_session_create(vo * Set the session name of an lttng_action object of type * LTTNG_ACTION_TYPE_SNAPSHOT_SESSION. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_snapshot_session_set_session_name( - struct lttng_action *action, const char *session_name); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_snapshot_session_set_session_name(struct lttng_action *action, + const char *session_name); /* * Get the session name of an lttng_action object of type * LTTNG_ACTION_TYPE_SNAPSHOT_SESSION. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_snapshot_session_get_session_name( - const struct lttng_action *action, const char **session_name); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_snapshot_session_get_session_name(const struct lttng_action *action, + const char **session_name); /* * Set an explicit snapshot output for this snapshot session action. @@ -52,16 +54,16 @@ LTTNG_EXPORT extern enum lttng_action_status lttng_action_snapshot_session_get_s * * This function takes ownership of the given snapshot output. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_snapshot_session_set_output( - struct lttng_action *action, - struct lttng_snapshot_output *output); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_snapshot_session_set_output(struct lttng_action *action, + struct lttng_snapshot_output *output); /* * Get the explicit snapshot output for this snapshot session action. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_snapshot_session_get_output( - const struct lttng_action *action, - const struct lttng_snapshot_output **output); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_snapshot_session_get_output(const struct lttng_action *action, + const struct lttng_snapshot_output **output); /* * Set the rate policy of a snapshot session action. @@ -70,9 +72,9 @@ LTTNG_EXPORT extern enum lttng_action_status lttng_action_snapshot_session_get_o * LTTNG_ACTION_STATUS_ERROR on internal error, * LTTNG_ACTION_STATUS_INVALID if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_snapshot_session_set_rate_policy( - struct lttng_action *action, - const struct lttng_rate_policy *policy); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_snapshot_session_set_rate_policy(struct lttng_action *action, + const struct lttng_rate_policy *policy); /* * Get the rate policy of a snapshot session action. @@ -80,9 +82,9 @@ LTTNG_EXPORT extern enum lttng_action_status lttng_action_snapshot_session_set_r * Returns LTTNG_ACTION_STATUS_OK on success, * LTTNG_ACTION_STATUS_INVALID if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_snapshot_session_get_rate_policy( - const struct lttng_action *action, - const struct lttng_rate_policy **policy); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_snapshot_session_get_rate_policy(const struct lttng_action *action, + const struct lttng_rate_policy **policy); #ifdef __cplusplus } diff --git a/include/lttng/action/start-session-internal.hpp b/include/lttng/action/start-session-internal.hpp index 44dab1bf1..d33e073af 100644 --- a/include/lttng/action/start-session-internal.hpp +++ b/include/lttng/action/start-session-internal.hpp @@ -19,8 +19,7 @@ struct lttng_payload_view; * On success, return the number of bytes consumed from `view`, and the created * action in `*action`. On failure, return -1. */ -extern ssize_t lttng_action_start_session_create_from_payload( - struct lttng_payload_view *view, - struct lttng_action **action); +extern ssize_t lttng_action_start_session_create_from_payload(struct lttng_payload_view *view, + struct lttng_action **action); #endif /* LTTNG_ACTION_START_SESSION_INTERNAL_H */ diff --git a/include/lttng/action/start-session.h b/include/lttng/action/start-session.h index db5200032..da8c1c1b9 100644 --- a/include/lttng/action/start-session.h +++ b/include/lttng/action/start-session.h @@ -33,15 +33,16 @@ LTTNG_EXPORT extern struct lttng_action *lttng_action_start_session_create(void) * Set the session name of an lttng_action object of type * LTTNG_ACTION_TYPE_START_SESSION. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_start_session_set_session_name( - struct lttng_action *action, const char *session_name); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_start_session_set_session_name(struct lttng_action *action, const char *session_name); /* * Get the session name of an lttng_action object of type * LTTNG_ACTION_TYPE_START_SESSION. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_start_session_get_session_name( - const struct lttng_action *action, const char **session_name); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_start_session_get_session_name(const struct lttng_action *action, + const char **session_name); /* * Set the rate policy of a start session action. @@ -50,9 +51,9 @@ LTTNG_EXPORT extern enum lttng_action_status lttng_action_start_session_get_sess * LTTNG_ACTION_STATUS_ERROR on internal error, * LTTNG_ACTION_STATUS_INVALID if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_start_session_set_rate_policy( - struct lttng_action *action, - const struct lttng_rate_policy *policy); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_start_session_set_rate_policy(struct lttng_action *action, + const struct lttng_rate_policy *policy); /* * Get the rate policy of a start session action. @@ -60,9 +61,9 @@ LTTNG_EXPORT extern enum lttng_action_status lttng_action_start_session_set_rate * Returns LTTNG_ACTION_STATUS_OK on success, * LTTNG_ACTION_STATUS_INVALID if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_start_session_get_rate_policy( - const struct lttng_action *action, - const struct lttng_rate_policy **policy); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_start_session_get_rate_policy(const struct lttng_action *action, + const struct lttng_rate_policy **policy); #ifdef __cplusplus } diff --git a/include/lttng/action/stop-session-internal.hpp b/include/lttng/action/stop-session-internal.hpp index 22055352f..46f1d6eba 100644 --- a/include/lttng/action/stop-session-internal.hpp +++ b/include/lttng/action/stop-session-internal.hpp @@ -19,8 +19,7 @@ struct lttng_payload_view; * On success, return the number of bytes consumed from `view`, and the created * action in `*action`. On failure, return -1. */ -extern ssize_t lttng_action_stop_session_create_from_payload( - struct lttng_payload_view *view, - struct lttng_action **action); +extern ssize_t lttng_action_stop_session_create_from_payload(struct lttng_payload_view *view, + struct lttng_action **action); #endif /* LTTNG_ACTION_STOP_SESSION_INTERNAL_H */ diff --git a/include/lttng/action/stop-session.h b/include/lttng/action/stop-session.h index 5b223ef23..b4a82a229 100644 --- a/include/lttng/action/stop-session.h +++ b/include/lttng/action/stop-session.h @@ -33,15 +33,16 @@ LTTNG_EXPORT extern struct lttng_action *lttng_action_stop_session_create(void); * Set the session name of an lttng_action object of type * LTTNG_ACTION_TYPE_STOP_SESSION. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_stop_session_set_session_name( - struct lttng_action *action, const char *session_name); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_stop_session_set_session_name(struct lttng_action *action, const char *session_name); /* * Get the session name of an lttng_action object of type * LTTNG_ACTION_TYPE_STOP_SESSION. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_stop_session_get_session_name( - const struct lttng_action *action, const char **session_name); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_stop_session_get_session_name(const struct lttng_action *action, + const char **session_name); /* * Set the rate policy of a stop session action. @@ -50,9 +51,9 @@ LTTNG_EXPORT extern enum lttng_action_status lttng_action_stop_session_get_sessi * LTTNG_ACTION_STATUS_ERROR on internal error, * LTTNG_ACTION_STATUS_INVALID if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_stop_session_set_rate_policy( - struct lttng_action *action, - const struct lttng_rate_policy *policy); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_stop_session_set_rate_policy(struct lttng_action *action, + const struct lttng_rate_policy *policy); /* * Get the rate policy of a stop session action. @@ -60,9 +61,9 @@ LTTNG_EXPORT extern enum lttng_action_status lttng_action_stop_session_set_rate_ * Returns LTTNG_ACTION_STATUS_OK on success, * LTTNG_ACTION_STATUS_INVALID if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_action_status lttng_action_stop_session_get_rate_policy( - const struct lttng_action *action, - const struct lttng_rate_policy **policy); +LTTNG_EXPORT extern enum lttng_action_status +lttng_action_stop_session_get_rate_policy(const struct lttng_action *action, + const struct lttng_rate_policy **policy); #ifdef __cplusplus } diff --git a/include/lttng/channel-internal.hpp b/include/lttng/channel-internal.hpp index d4960828e..bcf3225ed 100644 --- a/include/lttng/channel-internal.hpp +++ b/include/lttng/channel-internal.hpp @@ -8,6 +8,7 @@ #ifndef LTTNG_CHANNEL_INTERNAL_H #define LTTNG_CHANNEL_INTERNAL_H +#include #include struct lttng_channel_extended { @@ -40,22 +41,19 @@ struct lttng_channel_comm { int64_t blocking_timeout; } LTTNG_PACKED; -struct lttng_channel *lttng_channel_create_internal(void); +struct lttng_channel *lttng_channel_create_internal(); struct lttng_channel *lttng_channel_copy(const struct lttng_channel *src); ssize_t lttng_channel_create_from_buffer(const struct lttng_buffer_view *view, - struct lttng_channel **event); + struct lttng_channel **event); -int lttng_channel_serialize(struct lttng_channel *channel, - struct lttng_dynamic_buffer *buf); +int lttng_channel_serialize(struct lttng_channel *channel, struct lttng_dynamic_buffer *buf); void lttng_channel_set_default_extended_attr(struct lttng_domain *domain, - struct lttng_channel_extended *extended_attr); + struct lttng_channel_extended *extended_attr); enum lttng_error_code lttng_channels_create_and_flatten_from_buffer( - const struct lttng_buffer_view *view, - unsigned int count, - struct lttng_channel **channels); + const struct lttng_buffer_view *view, unsigned int count, struct lttng_channel **channels); #endif /* LTTNG_CHANNEL_INTERNAL_H */ diff --git a/include/lttng/channel.h b/include/lttng/channel.h index 62e202d26..a6a6f04fc 100644 --- a/include/lttng/channel.h +++ b/include/lttng/channel.h @@ -11,6 +11,7 @@ #include #include #include + #include #ifdef __cplusplus @@ -22,19 +23,140 @@ extern "C" { * * The structures should be initialized to zero before use. */ -#define LTTNG_CHANNEL_ATTR_PADDING1 LTTNG_SYMBOL_NAME_LEN + 12 +#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 { - int overwrite; /* -1: session default, 1: overwrite, 0: discard */ - uint64_t subbuf_size; /* bytes, power of 2 */ - uint64_t num_subbuf; /* power of 2 */ + /*! + @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 */ - unsigned int read_timer_interval; /* usec */ - enum lttng_event_output output; /* splice, mmap */ + + /// \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 */ - uint64_t tracefile_size; /* bytes */ - uint64_t tracefile_count; /* number of tracefiles */ + + /*! + @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 */ - unsigned int live_timer_interval; /* usec */ + + /*! + @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 { @@ -50,90 +172,509 @@ struct lttng_channel_attr { * * The structures should be initialized to zero before use. */ -#define LTTNG_CHANNEL_PADDING1 16 +#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); + 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. - */ +/*! +@brief + Disables 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 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 *name); + const char *channel_name); -/* - * 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. - */ +/*! +@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); + 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 e07e6c47f..9a8048456 100644 --- a/include/lttng/clear-handle.h +++ b/include/lttng/clear-handle.h @@ -16,66 +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); +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); +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 5dfd5db58..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); + struct lttng_clear_handle **handle); + +/// @} + #ifdef __cplusplus } #endif diff --git a/include/lttng/condition/buffer-usage-internal.hpp b/include/lttng/condition/buffer-usage-internal.hpp index b2e6f85c1..25c91d176 100644 --- a/include/lttng/condition/buffer-usage-internal.hpp +++ b/include/lttng/condition/buffer-usage-internal.hpp @@ -8,12 +8,14 @@ #ifndef LTTNG_CONDITION_BUFFER_USAGE_INTERNAL_H #define LTTNG_CONDITION_BUFFER_USAGE_INTERNAL_H +#include "common/buffer-view.hpp" + +#include + #include #include #include #include -#include "common/buffer-view.hpp" -#include struct lttng_condition_buffer_usage { struct lttng_condition parent; @@ -57,24 +59,21 @@ struct lttng_evaluation_buffer_usage_comm { uint64_t buffer_capacity; } LTTNG_PACKED; -struct lttng_evaluation *lttng_evaluation_buffer_usage_create( - enum lttng_condition_type type, uint64_t use, - uint64_t capacity); +struct lttng_evaluation *lttng_evaluation_buffer_usage_create(enum lttng_condition_type type, + uint64_t use, + uint64_t capacity); -ssize_t lttng_condition_buffer_usage_low_create_from_payload( - struct lttng_payload_view *view, - struct lttng_condition **condition); +ssize_t lttng_condition_buffer_usage_low_create_from_payload(struct lttng_payload_view *view, + struct lttng_condition **condition); -ssize_t lttng_condition_buffer_usage_high_create_from_payload( - struct lttng_payload_view *view, - struct lttng_condition **condition); +ssize_t lttng_condition_buffer_usage_high_create_from_payload(struct lttng_payload_view *view, + struct lttng_condition **condition); -ssize_t lttng_evaluation_buffer_usage_low_create_from_payload( - struct lttng_payload_view *view, - struct lttng_evaluation **evaluation); +ssize_t lttng_evaluation_buffer_usage_low_create_from_payload(struct lttng_payload_view *view, + struct lttng_evaluation **evaluation); -ssize_t lttng_evaluation_buffer_usage_high_create_from_payload( - struct lttng_payload_view *view, - struct lttng_evaluation **evaluation); +ssize_t +lttng_evaluation_buffer_usage_high_create_from_payload(struct lttng_payload_view *view, + struct lttng_evaluation **evaluation); #endif /* LTTNG_CONDITION_BUFFER_USAGE_INTERNAL_H */ diff --git a/include/lttng/condition/buffer-usage.h b/include/lttng/condition/buffer-usage.h index dcdb7ca1f..198f3e657 100644 --- a/include/lttng/condition/buffer-usage.h +++ b/include/lttng/condition/buffer-usage.h @@ -8,12 +8,13 @@ #ifndef LTTNG_CONDITION_BUFFER_USAGE_H #define LTTNG_CONDITION_BUFFER_USAGE_H -#include #include -#include +#include #include #include +#include + #ifdef __cplusplus extern "C" { #endif @@ -57,8 +58,7 @@ extern "C" { * Returns a new condition on success, NULL on failure. This condition must be * destroyed using lttng_condition_destroy(). */ -LTTNG_EXPORT extern struct lttng_condition * -lttng_condition_buffer_usage_low_create(void); +LTTNG_EXPORT extern struct lttng_condition *lttng_condition_buffer_usage_low_create(void); /* * Create a newly allocated upper-bound buffer usage condition. @@ -73,8 +73,7 @@ lttng_condition_buffer_usage_low_create(void); * Returns a new condition on success, NULL on failure. This condition must be * destroyed using lttng_condition_destroy(). */ -LTTNG_EXPORT extern struct lttng_condition * -lttng_condition_buffer_usage_high_create(void); +LTTNG_EXPORT extern struct lttng_condition *lttng_condition_buffer_usage_high_create(void); /* * Get the buffer usage threshold ratio of a buffer usage condition. @@ -89,9 +88,8 @@ lttng_condition_buffer_usage_high_create(void); * call. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_buffer_usage_get_threshold_ratio( - const struct lttng_condition *condition, - double *threshold_ratio); +lttng_condition_buffer_usage_get_threshold_ratio(const struct lttng_condition *condition, + double *threshold_ratio); /* * Set the buffer usage threshold ratio of a buffer usage condition. @@ -105,9 +103,8 @@ lttng_condition_buffer_usage_get_threshold_ratio( * if invalid paramenters are passed. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_buffer_usage_set_threshold_ratio( - struct lttng_condition *condition, - double threshold_ratio); +lttng_condition_buffer_usage_set_threshold_ratio(struct lttng_condition *condition, + double threshold_ratio); /* * Get the buffer usage threshold of a buffer usage condition. @@ -121,9 +118,8 @@ lttng_condition_buffer_usage_set_threshold_ratio( * bytes, was not set prior to this call. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_buffer_usage_get_threshold( - const struct lttng_condition *condition, - uint64_t *threshold_bytes); +lttng_condition_buffer_usage_get_threshold(const struct lttng_condition *condition, + uint64_t *threshold_bytes); /* * Set the buffer usage threshold in bytes of a buffer usage condition. @@ -135,9 +131,8 @@ lttng_condition_buffer_usage_get_threshold( * if invalid paramenters are passed. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_buffer_usage_set_threshold( - struct lttng_condition *condition, - uint64_t threshold_bytes); +lttng_condition_buffer_usage_set_threshold(struct lttng_condition *condition, + uint64_t threshold_bytes); /* * Get the session name property of a buffer usage condition. @@ -152,9 +147,8 @@ lttng_condition_buffer_usage_set_threshold( * was not set prior to this call. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_buffer_usage_get_session_name( - const struct lttng_condition *condition, - const char **session_name); +lttng_condition_buffer_usage_get_session_name(const struct lttng_condition *condition, + const char **session_name); /* * Set the session name property of a buffer usage condition. @@ -165,9 +159,8 @@ lttng_condition_buffer_usage_get_session_name( * if invalid paramenters are passed. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_buffer_usage_set_session_name( - struct lttng_condition *condition, - const char *session_name); +lttng_condition_buffer_usage_set_session_name(struct lttng_condition *condition, + const char *session_name); /* * Get the channel name property of a buffer usage condition. @@ -182,9 +175,8 @@ lttng_condition_buffer_usage_set_session_name( * was not set prior to this call. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_buffer_usage_get_channel_name( - const struct lttng_condition *condition, - const char **channel_name); +lttng_condition_buffer_usage_get_channel_name(const struct lttng_condition *condition, + const char **channel_name); /* * Set the channel name property of a buffer usage condition. @@ -195,9 +187,8 @@ lttng_condition_buffer_usage_get_channel_name( * if invalid paramenters are passed. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_buffer_usage_set_channel_name( - struct lttng_condition *condition, - const char *channel_name); +lttng_condition_buffer_usage_set_channel_name(struct lttng_condition *condition, + const char *channel_name); /* * Get the domain type property of a buffer usage condition. @@ -208,9 +199,8 @@ lttng_condition_buffer_usage_set_channel_name( * call. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_buffer_usage_get_domain_type( - const struct lttng_condition *condition, - enum lttng_domain_type *type); +lttng_condition_buffer_usage_get_domain_type(const struct lttng_condition *condition, + enum lttng_domain_type *type); /* * Set the domain type property of a buffer usage condition. @@ -219,10 +209,8 @@ lttng_condition_buffer_usage_get_domain_type( * if invalid paramenters are passed. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_buffer_usage_set_domain_type( - struct lttng_condition *condition, - enum lttng_domain_type type); - +lttng_condition_buffer_usage_set_domain_type(struct lttng_condition *condition, + enum lttng_domain_type type); /** * lttng_evaluation_buffer_usage are specialised lttng_evaluations which @@ -242,9 +230,8 @@ lttng_condition_buffer_usage_set_domain_type( * an invalid parameter is passed. */ LTTNG_EXPORT extern enum lttng_evaluation_status -lttng_evaluation_buffer_usage_get_usage_ratio( - const struct lttng_evaluation *evaluation, - double *usage_ratio); +lttng_evaluation_buffer_usage_get_usage_ratio(const struct lttng_evaluation *evaluation, + double *usage_ratio); /* * Get the buffer usage property of a buffer usage evaluation. @@ -253,9 +240,8 @@ lttng_evaluation_buffer_usage_get_usage_ratio( * bytes, or LTTNG_EVALUATION_STATUS_INVALID if an invalid parameter is passed. */ LTTNG_EXPORT extern enum lttng_evaluation_status -lttng_evaluation_buffer_usage_get_usage( - const struct lttng_evaluation *evaluation, - uint64_t *usage_bytes); +lttng_evaluation_buffer_usage_get_usage(const struct lttng_evaluation *evaluation, + uint64_t *usage_bytes); #ifdef __cplusplus } diff --git a/include/lttng/condition/condition-internal.hpp b/include/lttng/condition/condition-internal.hpp index 27407d07a..c69ae2a21 100644 --- a/include/lttng/condition/condition-internal.hpp +++ b/include/lttng/condition/condition-internal.hpp @@ -11,8 +11,10 @@ #include #include #include + #include #include + #include #include #include @@ -23,19 +25,14 @@ struct mi_writer; struct mi_lttng_error_query_callbacks; struct lttng_trigger; -typedef void (*condition_destroy_cb)(struct lttng_condition *condition); -typedef bool (*condition_validate_cb)(const struct lttng_condition *condition); -typedef int (*condition_serialize_cb)( - const struct lttng_condition *condition, - struct lttng_payload *payload); -typedef bool (*condition_equal_cb)(const struct lttng_condition *a, - const struct lttng_condition *b); -typedef ssize_t (*condition_create_from_payload_cb)( - struct lttng_payload_view *view, - struct lttng_condition **condition); -typedef enum lttng_error_code (*condition_mi_serialize_cb)( - const struct lttng_condition *condition, - struct mi_writer *writer); +using condition_destroy_cb = void (*)(struct lttng_condition *); +using condition_validate_cb = bool (*)(const struct lttng_condition *); +using condition_serialize_cb = int (*)(const struct lttng_condition *, struct lttng_payload *); +using condition_equal_cb = bool (*)(const struct lttng_condition *, const struct lttng_condition *); +using condition_create_from_payload_cb = ssize_t (*)(struct lttng_payload_view *, + struct lttng_condition **); +using condition_mi_serialize_cb = enum lttng_error_code (*)(const struct lttng_condition *, + struct mi_writer *); struct lttng_condition { /* Reference counting is only exposed to internal users. */ @@ -58,27 +55,23 @@ void lttng_condition_get(struct lttng_condition *condition); void lttng_condition_put(struct lttng_condition *condition); -void lttng_condition_init(struct lttng_condition *condition, - enum lttng_condition_type type); +void lttng_condition_init(struct lttng_condition *condition, enum lttng_condition_type type); bool lttng_condition_validate(const struct lttng_condition *condition); -ssize_t lttng_condition_create_from_payload( - struct lttng_payload_view *view, - struct lttng_condition **condition); +ssize_t lttng_condition_create_from_payload(struct lttng_payload_view *view, + struct lttng_condition **condition); int lttng_condition_serialize(const struct lttng_condition *condition, - struct lttng_payload *payload); + struct lttng_payload *payload); -bool lttng_condition_is_equal(const struct lttng_condition *a, - const struct lttng_condition *b); +bool lttng_condition_is_equal(const struct lttng_condition *a, const struct lttng_condition *b); -enum lttng_error_code lttng_condition_mi_serialize( - const struct lttng_trigger *trigger, - const struct lttng_condition *condition, - struct mi_writer *writer, - const struct mi_lttng_error_query_callbacks - *error_query_callbacks); +enum lttng_error_code +lttng_condition_mi_serialize(const struct lttng_trigger *trigger, + const struct lttng_condition *condition, + struct mi_writer *writer, + const struct mi_lttng_error_query_callbacks *error_query_callbacks); const char *lttng_condition_type_str(enum lttng_condition_type type); diff --git a/include/lttng/condition/condition.h b/include/lttng/condition/condition.h index f0f5ffdd8..13a09c19a 100644 --- a/include/lttng/condition/condition.h +++ b/include/lttng/condition/condition.h @@ -41,8 +41,8 @@ enum lttng_condition_status { * Returns the type of a condition on success, LTTNG_CONDITION_TYPE_UNKNOWN on * error. */ -LTTNG_EXPORT extern enum lttng_condition_type lttng_condition_get_type( - const struct lttng_condition *condition); +LTTNG_EXPORT extern enum lttng_condition_type +lttng_condition_get_type(const struct lttng_condition *condition); /* * Destroy (release) a condition object. diff --git a/include/lttng/condition/evaluation-internal.hpp b/include/lttng/condition/evaluation-internal.hpp index f74927c24..36dc3a544 100644 --- a/include/lttng/condition/evaluation-internal.hpp +++ b/include/lttng/condition/evaluation-internal.hpp @@ -8,19 +8,19 @@ #ifndef LTTNG_EVALUATION_INTERNAL_H #define LTTNG_EVALUATION_INTERNAL_H -#include -#include #include + +#include +#include + #include #include struct lttng_payload; struct lttng_payload_view; -typedef void (*evaluation_destroy_cb)(struct lttng_evaluation *evaluation); -typedef int (*evaluation_serialize_cb)( - const struct lttng_evaluation *evaluation, - struct lttng_payload *payload); +using evaluation_destroy_cb = void (*)(struct lttng_evaluation *); +using evaluation_serialize_cb = int (*)(const struct lttng_evaluation *, struct lttng_payload *); struct lttng_evaluation_comm { /* enum lttng_condition_type type */ @@ -34,15 +34,13 @@ struct lttng_evaluation { evaluation_destroy_cb destroy; }; -void lttng_evaluation_init(struct lttng_evaluation *evaluation, - enum lttng_condition_type type); +void lttng_evaluation_init(struct lttng_evaluation *evaluation, enum lttng_condition_type type); -ssize_t lttng_evaluation_create_from_payload( - const struct lttng_condition *condition, - struct lttng_payload_view *view, - struct lttng_evaluation **evaluation); +ssize_t lttng_evaluation_create_from_payload(const struct lttng_condition *condition, + struct lttng_payload_view *view, + struct lttng_evaluation **evaluation); int lttng_evaluation_serialize(const struct lttng_evaluation *evaluation, - struct lttng_payload *payload); + struct lttng_payload *payload); #endif /* LTTNG_EVALUATION_INTERNAL_H */ diff --git a/include/lttng/condition/evaluation.h b/include/lttng/condition/evaluation.h index 494cb9739..599bc35b3 100644 --- a/include/lttng/condition/evaluation.h +++ b/include/lttng/condition/evaluation.h @@ -31,8 +31,8 @@ enum lttng_evaluation_status { * Returns the type of a condition on success, LTTNG_CONDITION_TYPE_UNKNOWN on * error. */ -LTTNG_EXPORT extern enum lttng_condition_type lttng_evaluation_get_type( - const struct lttng_evaluation *evaluation); +LTTNG_EXPORT extern enum lttng_condition_type +lttng_evaluation_get_type(const struct lttng_evaluation *evaluation); /* * Destroy (frees) an evaluation object. diff --git a/include/lttng/condition/event-rule-matches-internal.hpp b/include/lttng/condition/event-rule-matches-internal.hpp index bb7e03e21..22bfb9557 100644 --- a/include/lttng/condition/event-rule-matches-internal.hpp +++ b/include/lttng/condition/event-rule-matches-internal.hpp @@ -8,12 +8,13 @@ #ifndef LTTNG_CONDITION_EVENT_RULE_MATCHES_INTERNAL_H #define LTTNG_CONDITION_EVENT_RULE_MATCHES_INTERNAL_H -#include #include +#include #include #include + +#include #include -#include #include struct lttng_capture_descriptor { @@ -51,39 +52,34 @@ struct lttng_evaluation_event_rule_matches { struct lttng_event_field_value *captured_values; }; -ssize_t lttng_condition_event_rule_matches_create_from_payload( - struct lttng_payload_view *view, - struct lttng_condition **condition); +ssize_t lttng_condition_event_rule_matches_create_from_payload(struct lttng_payload_view *view, + struct lttng_condition **condition); enum lttng_condition_status -lttng_condition_event_rule_matches_borrow_rule_mutable( - const struct lttng_condition *condition, - struct lttng_event_rule **rule); +lttng_condition_event_rule_matches_borrow_rule_mutable(const struct lttng_condition *condition, + struct lttng_event_rule **rule); -void lttng_condition_event_rule_matches_set_error_counter_index( - struct lttng_condition *condition, - uint64_t error_counter_index); +void lttng_condition_event_rule_matches_set_error_counter_index(struct lttng_condition *condition, + uint64_t error_counter_index); -uint64_t lttng_condition_event_rule_matches_get_error_counter_index( - const struct lttng_condition *condition); +uint64_t +lttng_condition_event_rule_matches_get_error_counter_index(const struct lttng_condition *condition); struct lttng_evaluation *lttng_evaluation_event_rule_matches_create( - const struct lttng_condition_event_rule_matches *condition, - const char *capture_payload, - size_t capture_payload_size, - bool decode_capture_payload); + const struct lttng_condition_event_rule_matches *condition, + const char *capture_payload, + size_t capture_payload_size, + bool decode_capture_payload); ssize_t lttng_evaluation_event_rule_matches_create_from_payload( - const struct lttng_condition_event_rule_matches *condition, - struct lttng_payload_view *view, - struct lttng_evaluation **_evaluation); + const struct lttng_condition_event_rule_matches *condition, + struct lttng_payload_view *view, + struct lttng_evaluation **_evaluation); -enum lttng_error_code -lttng_condition_event_rule_matches_generate_capture_descriptor_bytecode( - struct lttng_condition *condition); +enum lttng_error_code lttng_condition_event_rule_matches_generate_capture_descriptor_bytecode( + struct lttng_condition *condition); -const struct lttng_bytecode * -lttng_condition_event_rule_matches_get_capture_bytecode_at_index( - const struct lttng_condition *condition, unsigned int index); +const struct lttng_bytecode *lttng_condition_event_rule_matches_get_capture_bytecode_at_index( + const struct lttng_condition *condition, unsigned int index); #endif /* LTTNG_CONDITION_EVENT_RULE_MATCHES_INTERNAL_H */ diff --git a/include/lttng/condition/event-rule-matches.h b/include/lttng/condition/event-rule-matches.h index b1bbe08f3..c579a1864 100644 --- a/include/lttng/condition/event-rule-matches.h +++ b/include/lttng/condition/event-rule-matches.h @@ -8,9 +8,9 @@ #ifndef LTTNG_CONDITION_EVENT_RULE_MATCHES_H #define LTTNG_CONDITION_EVENT_RULE_MATCHES_H -#include #include #include +#include #include #ifdef __cplusplus @@ -43,8 +43,8 @@ enum lttng_evaluation_event_rule_matches_status { * Returns a new condition on success, NULL on failure. This condition must be * destroyed using lttng_condition_destroy(). */ -LTTNG_EXPORT extern struct lttng_condition *lttng_condition_event_rule_matches_create( - struct lttng_event_rule *rule); +LTTNG_EXPORT extern struct lttng_condition * +lttng_condition_event_rule_matches_create(struct lttng_event_rule *rule); /* * Get the rule property of an Event Rule Matches condition. @@ -56,9 +56,9 @@ LTTNG_EXPORT extern struct lttng_condition *lttng_condition_event_rule_matches_c * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's rule * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid * parameter is passed. */ -LTTNG_EXPORT extern enum lttng_condition_status lttng_condition_event_rule_matches_get_rule( - const struct lttng_condition *condition, - const struct lttng_event_rule **rule); +LTTNG_EXPORT extern enum lttng_condition_status +lttng_condition_event_rule_matches_get_rule(const struct lttng_condition *condition, + const struct lttng_event_rule **rule); /** * lttng_evaluation_event_rule_matches_hit are specialised lttng_evaluations @@ -92,8 +92,8 @@ LTTNG_EXPORT extern enum lttng_condition_status lttng_condition_event_rule_match */ LTTNG_EXPORT extern enum lttng_evaluation_event_rule_matches_status lttng_evaluation_event_rule_matches_get_captured_values( - const struct lttng_evaluation *evaluation, - const struct lttng_event_field_value **field_val); + const struct lttng_evaluation *evaluation, + const struct lttng_event_field_value **field_val); /* * Appends (transfering the ownership) the capture descriptor `expr` to @@ -124,9 +124,8 @@ lttng_evaluation_event_rule_matches_get_captured_values( * * The associated event-rule does not support runtime capture. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_event_rule_matches_append_capture_descriptor( - struct lttng_condition *condition, - struct lttng_event_expr *expr); +lttng_condition_event_rule_matches_append_capture_descriptor(struct lttng_condition *condition, + struct lttng_event_expr *expr); /* * Sets `*count` to the number of capture descriptors in the Event Rule Matches @@ -145,7 +144,7 @@ lttng_condition_event_rule_matches_append_capture_descriptor( */ LTTNG_EXPORT extern enum lttng_condition_status lttng_condition_event_rule_matches_get_capture_descriptor_count( - const struct lttng_condition *condition, unsigned int *count); + const struct lttng_condition *condition, unsigned int *count); /* * Returns the capture descriptor (borrowed) of the Event Rule Matches condition @@ -160,7 +159,7 @@ lttng_condition_event_rule_matches_get_capture_descriptor_count( */ LTTNG_EXPORT extern const struct lttng_event_expr * lttng_condition_event_rule_matches_get_capture_descriptor_at_index( - const struct lttng_condition *condition, unsigned int index); + const struct lttng_condition *condition, unsigned int index); #ifdef __cplusplus } diff --git a/include/lttng/condition/session-consumed-size-internal.hpp b/include/lttng/condition/session-consumed-size-internal.hpp index cdfa10034..e49a60814 100644 --- a/include/lttng/condition/session-consumed-size-internal.hpp +++ b/include/lttng/condition/session-consumed-size-internal.hpp @@ -8,12 +8,13 @@ #ifndef LTTNG_CONDITION_SESSION_CONSUMED_SIZE_INTERNAL_H #define LTTNG_CONDITION_SESSION_CONSUMED_SIZE_INTERNAL_H -#include -#include -#include #include #include +#include +#include +#include + struct lttng_payload; struct lttng_payload_view; @@ -42,15 +43,14 @@ struct lttng_evaluation_session_consumed_size_comm { uint64_t session_consumed; } LTTNG_PACKED; -struct lttng_evaluation *lttng_evaluation_session_consumed_size_create( - uint64_t consumed); +struct lttng_evaluation *lttng_evaluation_session_consumed_size_create(uint64_t consumed); -ssize_t lttng_condition_session_consumed_size_create_from_payload( - struct lttng_payload_view *view, - struct lttng_condition **condition); +ssize_t +lttng_condition_session_consumed_size_create_from_payload(struct lttng_payload_view *view, + struct lttng_condition **condition); -ssize_t lttng_evaluation_session_consumed_size_create_from_payload( - struct lttng_payload_view *view, - struct lttng_evaluation **evaluation); +ssize_t +lttng_evaluation_session_consumed_size_create_from_payload(struct lttng_payload_view *view, + struct lttng_evaluation **evaluation); #endif /* LTTNG_CONDITION_SESSION_CONSUMED_SIZE_INTERNAL_H */ diff --git a/include/lttng/condition/session-consumed-size.h b/include/lttng/condition/session-consumed-size.h index 4d52cb689..98284c748 100644 --- a/include/lttng/condition/session-consumed-size.h +++ b/include/lttng/condition/session-consumed-size.h @@ -8,9 +8,10 @@ #ifndef LTTNG_CONDITION_SESSION_CONSUMED_SIZE_H #define LTTNG_CONDITION_SESSION_CONSUMED_SIZE_H -#include #include +#include #include + #include #ifdef __cplusplus @@ -43,8 +44,7 @@ extern "C" { * Returns a new condition on success, NULL on failure. This condition must be * destroyed using lttng_condition_destroy(). */ -LTTNG_EXPORT extern struct lttng_condition * -lttng_condition_session_consumed_size_create(void); +LTTNG_EXPORT extern struct lttng_condition *lttng_condition_session_consumed_size_create(void); /* * Get the threshold of a session consumed size condition. @@ -58,9 +58,8 @@ lttng_condition_session_consumed_size_create(void); * bytes, was not set prior to this call. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_session_consumed_size_get_threshold( - const struct lttng_condition *condition, - uint64_t *consumed_threshold_bytes); +lttng_condition_session_consumed_size_get_threshold(const struct lttng_condition *condition, + uint64_t *consumed_threshold_bytes); /* * Set the threshold of a session consumed size usage condition. @@ -71,9 +70,8 @@ lttng_condition_session_consumed_size_get_threshold( * if invalid parameters are passed. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_session_consumed_size_set_threshold( - struct lttng_condition *condition, - uint64_t consumed_threshold_bytes); +lttng_condition_session_consumed_size_set_threshold(struct lttng_condition *condition, + uint64_t consumed_threshold_bytes); /* * Get the session name property of a session consumed size condition. @@ -88,9 +86,8 @@ lttng_condition_session_consumed_size_set_threshold( * was not set prior to this call. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_session_consumed_size_get_session_name( - const struct lttng_condition *condition, - const char **session_name); +lttng_condition_session_consumed_size_get_session_name(const struct lttng_condition *condition, + const char **session_name); /* * Set the session name property of a session consumed size condition. @@ -101,9 +98,8 @@ lttng_condition_session_consumed_size_get_session_name( * if invalid parameters are passed. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_session_consumed_size_set_session_name( - struct lttng_condition *condition, - const char *session_name); +lttng_condition_session_consumed_size_set_session_name(struct lttng_condition *condition, + const char *session_name); /** * lttng_evaluation_session_consumed_size is specialised lttng_evaluations @@ -118,9 +114,8 @@ lttng_condition_session_consumed_size_set_session_name( * bytes, or LTTNG_EVALUATION_STATUS_INVALID if an invalid parameter is passed. */ LTTNG_EXPORT extern enum lttng_evaluation_status -lttng_evaluation_session_consumed_size_get_consumed_size( - const struct lttng_evaluation *evaluation, - uint64_t *session_consumed); +lttng_evaluation_session_consumed_size_get_consumed_size(const struct lttng_evaluation *evaluation, + uint64_t *session_consumed); #ifdef __cplusplus } diff --git a/include/lttng/condition/session-rotation-internal.hpp b/include/lttng/condition/session-rotation-internal.hpp index e9a298445..a3d14b493 100644 --- a/include/lttng/condition/session-rotation-internal.hpp +++ b/include/lttng/condition/session-rotation-internal.hpp @@ -8,12 +8,14 @@ #ifndef LTTNG_CONDITION_SESSION_ROTATION_INTERNAL_H #define LTTNG_CONDITION_SESSION_ROTATION_INTERNAL_H -#include +#include "common/buffer-view.hpp" + +#include + #include #include -#include "common/buffer-view.hpp" +#include #include -#include struct lttng_condition_session_rotation { struct lttng_condition parent; @@ -37,28 +39,26 @@ struct lttng_evaluation_session_rotation_comm { uint8_t has_location; } LTTNG_PACKED; -ssize_t lttng_condition_session_rotation_ongoing_create_from_payload( - struct lttng_payload_view *view, - struct lttng_condition **condition); +ssize_t +lttng_condition_session_rotation_ongoing_create_from_payload(struct lttng_payload_view *view, + struct lttng_condition **condition); -ssize_t lttng_condition_session_rotation_completed_create_from_payload( - struct lttng_payload_view *view, - struct lttng_condition **condition); +ssize_t +lttng_condition_session_rotation_completed_create_from_payload(struct lttng_payload_view *view, + struct lttng_condition **condition); -struct lttng_evaluation *lttng_evaluation_session_rotation_ongoing_create( - uint64_t id); +struct lttng_evaluation *lttng_evaluation_session_rotation_ongoing_create(uint64_t id); /* Ownership of location is transferred to the evaluation. */ -struct lttng_evaluation *lttng_evaluation_session_rotation_completed_create( - uint64_t id, - struct lttng_trace_archive_location *location); +struct lttng_evaluation * +lttng_evaluation_session_rotation_completed_create(uint64_t id, + struct lttng_trace_archive_location *location); -ssize_t lttng_evaluation_session_rotation_ongoing_create_from_payload( - struct lttng_payload_view *view, - struct lttng_evaluation **evaluation); +ssize_t +lttng_evaluation_session_rotation_ongoing_create_from_payload(struct lttng_payload_view *view, + struct lttng_evaluation **evaluation); ssize_t lttng_evaluation_session_rotation_completed_create_from_payload( - struct lttng_payload_view *view, - struct lttng_evaluation **evaluation); + struct lttng_payload_view *view, struct lttng_evaluation **evaluation); #endif /* LTTNG_CONDITION_SESSION_ROTATION_INTERNAL_H */ diff --git a/include/lttng/condition/session-rotation.h b/include/lttng/condition/session-rotation.h index 086fff915..6e6207fb2 100644 --- a/include/lttng/condition/session-rotation.h +++ b/include/lttng/condition/session-rotation.h @@ -8,13 +8,14 @@ #ifndef LTTNG_CONDITION_SESSION_ROTATION_H #define LTTNG_CONDITION_SESSION_ROTATION_H -#include #include -#include +#include #include #include #include +#include + #ifdef __cplusplus extern "C" { #endif @@ -39,8 +40,7 @@ extern "C" { * Returns a new condition on success, NULL on failure. This condition must be * destroyed using lttng_condition_destroy(). */ -LTTNG_EXPORT extern struct lttng_condition * -lttng_condition_session_rotation_ongoing_create(void); +LTTNG_EXPORT extern struct lttng_condition *lttng_condition_session_rotation_ongoing_create(void); /* * Create a newly allocated session rotation completion condition. @@ -54,8 +54,7 @@ lttng_condition_session_rotation_ongoing_create(void); * Returns a new condition on success, NULL on failure. This condition must be * destroyed using lttng_condition_destroy(). */ -LTTNG_EXPORT extern struct lttng_condition * -lttng_condition_session_rotation_completed_create(void); +LTTNG_EXPORT extern struct lttng_condition *lttng_condition_session_rotation_completed_create(void); /* * Get the session name property of a session rotation condition. @@ -70,9 +69,8 @@ lttng_condition_session_rotation_completed_create(void); * was not set prior to this call. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_session_rotation_get_session_name( - const struct lttng_condition *condition, - const char **session_name); +lttng_condition_session_rotation_get_session_name(const struct lttng_condition *condition, + const char **session_name); /* * Set the session name property of a session rotation condition. @@ -83,9 +81,8 @@ lttng_condition_session_rotation_get_session_name( * if invalid paramenters are passed. */ LTTNG_EXPORT extern enum lttng_condition_status -lttng_condition_session_rotation_set_session_name( - struct lttng_condition *condition, - const char *session_name); +lttng_condition_session_rotation_set_session_name(struct lttng_condition *condition, + const char *session_name); /** * lttng_evaluation_session_rotation are specialised lttng_evaluations @@ -101,8 +98,7 @@ lttng_condition_session_rotation_set_session_name( * passed. */ LTTNG_EXPORT extern enum lttng_evaluation_status -lttng_evaluation_session_rotation_get_id( - const struct lttng_evaluation *evaluation, uint64_t *id); +lttng_evaluation_session_rotation_get_id(const struct lttng_evaluation *evaluation, uint64_t *id); /* * Get the session rotation location property of a session rotation completed @@ -121,8 +117,8 @@ lttng_evaluation_session_rotation_get_id( */ LTTNG_EXPORT extern enum lttng_evaluation_status lttng_evaluation_session_rotation_completed_get_location( - const struct lttng_evaluation *evaluation, - const struct lttng_trace_archive_location **location); + const struct lttng_evaluation *evaluation, + const struct lttng_trace_archive_location **location); #ifdef __cplusplus } diff --git a/include/lttng/constant.h b/include/lttng/constant.h index 1b6f44d8b..f20e96458 100644 --- a/include/lttng/constant.h +++ b/include/lttng/constant.h @@ -9,9 +9,7 @@ #define LTTNG_CONSTANT_H #ifndef LTTNG_DEPRECATED -#if defined (__GNUC__) \ - && ((__GNUC__ == 4) && (__GNUC_MINOR__ >= 5) \ - || __GNUC__ >= 5) +#if defined(__GNUC__) && ((__GNUC__ == 4) && (__GNUC_MINOR__ >= 5) || __GNUC__ >= 5) #define LTTNG_DEPRECATED(msg) __attribute__((deprecated(msg))) #else #define LTTNG_DEPRECATED(msg) __attribute__((deprecated)) @@ -35,16 +33,29 @@ /* * Event symbol length. Copied from LTTng kernel ABI. */ -#define LTTNG_SYMBOL_NAME_LEN 256 + +/*! +@brief + Maximum symbol length. + +@ingroup api_gen +*/ +#define LTTNG_SYMBOL_NAME_LEN 256 /* * PROC(5) mentions that PID_MAX_LIMIT may not exceed 2^22 on 64-bit HW. * We prefer to use 32-bits for simplicity's sake. */ -#define LTTNG_MAX_PID INT32_MAX -#define LTTNG_MAX_PID_STR "2147483647" +#define LTTNG_MAX_PID INT32_MAX +#define LTTNG_MAX_PID_STR "2147483647" + +/*! +@brief + Maximum name length. -#define LTTNG_NAME_MAX 255 +@ingroup api_gen +*/ +#define LTTNG_NAME_MAX 255 /* * POSIX guarantees that a host name will not exceed 255 characters. @@ -53,8 +64,8 @@ * * 256 is used to include a trailing NULL character. */ -#define LTTNG_HOST_NAME_MAX 256 +#define LTTNG_HOST_NAME_MAX 256 -#define LTTNG_PATH_MAX 4096 +#define LTTNG_PATH_MAX 4096 #endif /* LTTNG_CONSTANT_H */ diff --git a/include/lttng/destruction-handle.h b/include/lttng/destruction-handle.h index 6fa4339ac..108ba4aa6 100644 --- a/include/lttng/destruction-handle.h +++ b/include/lttng/destruction-handle.h @@ -8,134 +8,253 @@ #ifndef LTTNG_DESTRUCTION_HANDLE_H #define LTTNG_DESTRUCTION_HANDLE_H -#include #include #include +#include #ifdef __cplusplus 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. - */ -LTTNG_EXPORT extern void lttng_destruction_handle_destroy( - struct lttng_destruction_handle *handle); +/*! +@brief + Destroys the recording session destruction handle \lt_p{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. - */ +@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); + +/*! +@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); +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); +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); +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); +lttng_destruction_handle_get_archive_location(const struct lttng_destruction_handle *handle, + const struct lttng_trace_archive_location **location); + +/// @} #ifdef __cplusplus } diff --git a/include/lttng/domain-internal.hpp b/include/lttng/domain-internal.hpp index 4439c7825..f41d61e84 100644 --- a/include/lttng/domain-internal.hpp +++ b/include/lttng/domain-internal.hpp @@ -8,8 +8,8 @@ #ifndef LTTNG_DOMAIN_INTERNAL_H #define LTTNG_DOMAIN_INTERNAL_H -#include "lttng/domain.h" #include "common/macros.hpp" +#include "lttng/domain.h" const char *lttng_domain_type_str(enum lttng_domain_type domain_type); diff --git a/include/lttng/domain.h b/include/lttng/domain.h index 192c04bf2..26e9da932 100644 --- a/include/lttng/domain.h +++ b/include/lttng/domain.h @@ -12,36 +12,98 @@ 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, }; /* * The structures should be initialized to zero before use. */ -#define LTTNG_DOMAIN_PADDING1 12 -#define LTTNG_DOMAIN_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32 +#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,16 +113,37 @@ 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. - */ -LTTNG_EXPORT extern int lttng_list_domains(const char *session_name, - struct lttng_domain **domains); +/// @} + +/*! +@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/endpoint-internal.hpp b/include/lttng/endpoint-internal.hpp index 5317f7ff5..306a96a47 100644 --- a/include/lttng/endpoint-internal.hpp +++ b/include/lttng/endpoint-internal.hpp @@ -8,9 +8,10 @@ #ifndef LTTNG_ENDPOINT_INTERNAL_H #define LTTNG_ENDPOINT_INTERNAL_H -#include #include +#include + enum lttng_endpoint_type { LTTNG_ENDPOINT_TYPE_DEFAULT_SESSIOND_NOTIFICATION = 0, LTTNG_ENDPOINT_TYPE_DEFAULT_SESSIOND_COMMAND = 1, diff --git a/include/lttng/error-query-internal.hpp b/include/lttng/error-query-internal.hpp index 7bf4da748..39ec36535 100644 --- a/include/lttng/error-query-internal.hpp +++ b/include/lttng/error-query-internal.hpp @@ -3,17 +3,18 @@ * * Copyright (C) 2021 Jérémie Galarneau * - * SPDX-License-Identifier: GPL-2.1-only + * SPDX-License-Identifier: LGPL-2.1-only * */ #ifndef LTTNG_ERROR_QUERY_INTERNAL_H #define LTTNG_ERROR_QUERY_INTERNAL_H -#include #include -#include #include +#include + +#include struct mi_writer; @@ -23,59 +24,53 @@ enum lttng_error_query_target_type { LTTNG_ERROR_QUERY_TARGET_TYPE_ACTION, }; -enum lttng_error_query_target_type lttng_error_query_get_target_type( - const struct lttng_error_query *query); +enum lttng_error_query_target_type +lttng_error_query_get_target_type(const struct lttng_error_query *query); -const struct lttng_trigger *lttng_error_query_trigger_borrow_target( - const struct lttng_error_query *query); +const struct lttng_trigger * +lttng_error_query_trigger_borrow_target(const struct lttng_error_query *query); -const struct lttng_trigger *lttng_error_query_condition_borrow_target( - const struct lttng_error_query *query); +const struct lttng_trigger * +lttng_error_query_condition_borrow_target(const struct lttng_error_query *query); -const struct lttng_trigger *lttng_error_query_action_borrow_trigger_target( - const struct lttng_error_query *query); +const struct lttng_trigger * +lttng_error_query_action_borrow_trigger_target(const struct lttng_error_query *query); -struct lttng_action *lttng_error_query_action_borrow_action_target( - const struct lttng_error_query *query, - struct lttng_trigger *trigger); +struct lttng_action * +lttng_error_query_action_borrow_action_target(const struct lttng_error_query *query, + struct lttng_trigger *trigger); int lttng_error_query_serialize(const struct lttng_error_query *query, - struct lttng_payload *payload); + struct lttng_payload *payload); ssize_t lttng_error_query_create_from_payload(struct lttng_payload_view *view, - struct lttng_error_query **query); + struct lttng_error_query **query); -int lttng_error_query_result_serialize( - const struct lttng_error_query_result *result, - struct lttng_payload *payload); +int lttng_error_query_result_serialize(const struct lttng_error_query_result *result, + struct lttng_payload *payload); -ssize_t lttng_error_query_result_create_from_payload( - struct lttng_payload_view *view, - struct lttng_error_query_result **result); +ssize_t lttng_error_query_result_create_from_payload(struct lttng_payload_view *view, + struct lttng_error_query_result **result); -int lttng_error_query_results_serialize( - const struct lttng_error_query_results *results, - struct lttng_payload *payload); +int lttng_error_query_results_serialize(const struct lttng_error_query_results *results, + struct lttng_payload *payload); -ssize_t lttng_error_query_results_create_from_payload( - struct lttng_payload_view *view, - struct lttng_error_query_results **results); +ssize_t lttng_error_query_results_create_from_payload(struct lttng_payload_view *view, + struct lttng_error_query_results **results); struct lttng_error_query_result * -lttng_error_query_result_counter_create( - const char *name, const char *description, uint64_t value); +lttng_error_query_result_counter_create(const char *name, const char *description, uint64_t value); void lttng_error_query_result_destroy(struct lttng_error_query_result *result); -struct lttng_error_query_results *lttng_error_query_results_create(void); +struct lttng_error_query_results *lttng_error_query_results_create(); /* Ownership of `result` is transferred on success. */ -int lttng_error_query_results_add_result( - struct lttng_error_query_results *results, - struct lttng_error_query_result *result); +int lttng_error_query_results_add_result(struct lttng_error_query_results *results, + struct lttng_error_query_result *result); -enum lttng_error_code lttng_error_query_results_mi_serialize( - const struct lttng_error_query_results *results, - struct mi_writer *writer); +enum lttng_error_code +lttng_error_query_results_mi_serialize(const struct lttng_error_query_results *results, + struct mi_writer *writer); #endif /* LTTNG_ERROR_QUERY_INTERNAL_H */ diff --git a/include/lttng/error-query.h b/include/lttng/error-query.h index a7cbae421..cebf8266c 100644 --- a/include/lttng/error-query.h +++ b/include/lttng/error-query.h @@ -3,16 +3,17 @@ * * Copyright (C) 2021 Jérémie Galarneau * - * SPDX-License-Identifier: GPL-2.1-only + * SPDX-License-Identifier: LGPL-2.1-only * */ #ifndef LTTNG_ERROR_QUERY_H #define LTTNG_ERROR_QUERY_H -#include #include +#include #include + #include #ifdef __cplusplus @@ -59,12 +60,12 @@ enum lttng_error_query_results_status { }; /* Create an error query targetting a trigger object. */ -LTTNG_EXPORT extern struct lttng_error_query *lttng_error_query_trigger_create( - const struct lttng_trigger *trigger); +LTTNG_EXPORT extern struct lttng_error_query * +lttng_error_query_trigger_create(const struct lttng_trigger *trigger); /* Create an error query targetting a trigger's condition object. */ -LTTNG_EXPORT extern struct lttng_error_query *lttng_error_query_condition_create( - const struct lttng_trigger *trigger); +LTTNG_EXPORT extern struct lttng_error_query * +lttng_error_query_condition_create(const struct lttng_trigger *trigger); /* * Create an error query targetting an action object. @@ -72,9 +73,9 @@ LTTNG_EXPORT extern struct lttng_error_query *lttng_error_query_condition_create * `action_path` is copied internally. The root of the `action_path` is the * action of `trigger`. */ -LTTNG_EXPORT extern struct lttng_error_query *lttng_error_query_action_create( - const struct lttng_trigger *trigger, - const struct lttng_action_path *action_path); +LTTNG_EXPORT extern struct lttng_error_query * +lttng_error_query_action_create(const struct lttng_trigger *trigger, + const struct lttng_action_path *action_path); /* Destroy an error query. */ LTTNG_EXPORT extern void lttng_error_query_destroy(struct lttng_error_query *query); @@ -85,47 +86,43 @@ LTTNG_EXPORT extern void lttng_error_query_destroy(struct lttng_error_query *que * Currently, only the `lttng_session_daemon_command_endpoint` is supported, * see `lttng/endpoint.h`. */ -LTTNG_EXPORT extern enum lttng_error_code lttng_error_query_execute( - const struct lttng_error_query *query, - const struct lttng_endpoint *endpoint, - struct lttng_error_query_results **results); +LTTNG_EXPORT extern enum lttng_error_code +lttng_error_query_execute(const struct lttng_error_query *query, + const struct lttng_endpoint *endpoint, + struct lttng_error_query_results **results); /* Get the number of results in a result set. */ LTTNG_EXPORT LTTNG_EXPORT extern enum lttng_error_query_results_status -lttng_error_query_results_get_count( - const struct lttng_error_query_results *results, - unsigned int *count); +lttng_error_query_results_get_count(const struct lttng_error_query_results *results, + unsigned int *count); /* Get a result from a result set by index. */ LTTNG_EXPORT extern enum lttng_error_query_results_status -lttng_error_query_results_get_result( - const struct lttng_error_query_results *results, - const struct lttng_error_query_result **result, - unsigned int index); +lttng_error_query_results_get_result(const struct lttng_error_query_results *results, + const struct lttng_error_query_result **result, + unsigned int index); /* Destroy an error query result set. */ -LTTNG_EXPORT extern void lttng_error_query_results_destroy( - struct lttng_error_query_results *results); +LTTNG_EXPORT extern void +lttng_error_query_results_destroy(struct lttng_error_query_results *results); /* Get the type of an error query result. */ -LTTNG_EXPORT extern enum lttng_error_query_result_type lttng_error_query_result_get_type( - const struct lttng_error_query_result *result); +LTTNG_EXPORT extern enum lttng_error_query_result_type +lttng_error_query_result_get_type(const struct lttng_error_query_result *result); /* Get the name of result. */ -LTTNG_EXPORT extern enum lttng_error_query_result_status lttng_error_query_result_get_name( - const struct lttng_error_query_result *result, - const char **name); +LTTNG_EXPORT extern enum lttng_error_query_result_status +lttng_error_query_result_get_name(const struct lttng_error_query_result *result, const char **name); /* Get the description of a result. */ LTTNG_EXPORT extern enum lttng_error_query_result_status -lttng_error_query_result_get_description( - const struct lttng_error_query_result *result, - const char **description); +lttng_error_query_result_get_description(const struct lttng_error_query_result *result, + const char **description); /* Get the value of an error counter. */ LTTNG_EXPORT extern enum lttng_error_query_result_status -lttng_error_query_result_counter_get_value( - const struct lttng_error_query_result *result, uint64_t *value); +lttng_error_query_result_counter_get_value(const struct lttng_error_query_result *result, + uint64_t *value); #ifdef __cplusplus } diff --git a/include/lttng/event-expr-internal.hpp b/include/lttng/event-expr-internal.hpp index 07547e587..c44e63e4a 100644 --- a/include/lttng/event-expr-internal.hpp +++ b/include/lttng/event-expr-internal.hpp @@ -9,6 +9,7 @@ #define LTTNG_EVENT_EXPR_INTERNAL_H #include + #include struct lttng_bytecode; @@ -47,21 +48,19 @@ struct lttng_event_expr_array_field_element { /* * Returns whether or not `expr` is an l-value (locator value). */ -static inline -bool lttng_event_expr_is_lvalue(const struct lttng_event_expr *expr) +static inline bool lttng_event_expr_is_lvalue(const struct lttng_event_expr *expr) { LTTNG_ASSERT(expr); return expr->type == LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD || - expr->type == LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD || - expr->type == LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD || - expr->type == LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT; + expr->type == LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD || + expr->type == LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD || + expr->type == LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT; } int lttng_event_expr_to_bytecode(const struct lttng_event_expr *expr, - struct lttng_bytecode **bytecode_out); + struct lttng_bytecode **bytecode_out); -enum lttng_error_code lttng_event_expr_mi_serialize( - const struct lttng_event_expr *expression, - struct mi_writer *writer); +enum lttng_error_code lttng_event_expr_mi_serialize(const struct lttng_event_expr *expression, + struct mi_writer *writer); #endif /* LTTNG_EVENT_EXPR_INTERNAL_H */ diff --git a/include/lttng/event-expr.h b/include/lttng/event-expr.h index cab22c97e..7b42785ca 100644 --- a/include/lttng/event-expr.h +++ b/include/lttng/event-expr.h @@ -9,6 +9,7 @@ #define LTTNG_EVENT_EXPR_H #include + #include struct lttng_event_expr; @@ -84,8 +85,8 @@ enum lttng_event_expr_status { * Returns the type of the event expression `expr`, or * `LTTNG_EVENT_EXPR_TYPE_INVALID` if `expr` is `NULL`. */ -LTTNG_EXPORT extern enum lttng_event_expr_type lttng_event_expr_get_type( - const struct lttng_event_expr *expr); +LTTNG_EXPORT extern enum lttng_event_expr_type +lttng_event_expr_get_type(const struct lttng_event_expr *expr); /* * Creates an event payload field expression for the payload field named @@ -96,8 +97,8 @@ LTTNG_EXPORT extern enum lttng_event_expr_type lttng_event_expr_get_type( * * There's a memory error. * * `field_name` is `NULL`. */ -LTTNG_EXPORT extern struct lttng_event_expr *lttng_event_expr_event_payload_field_create( - const char *field_name); +LTTNG_EXPORT extern struct lttng_event_expr * +lttng_event_expr_event_payload_field_create(const char *field_name); /* * Returns the field name of the event payload field expression `expr`, @@ -107,8 +108,8 @@ LTTNG_EXPORT extern struct lttng_event_expr *lttng_event_expr_event_payload_fiel * * The type of `expr` is not * `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD`. */ -LTTNG_EXPORT extern const char *lttng_event_expr_event_payload_field_get_name( - const struct lttng_event_expr *expr); +LTTNG_EXPORT extern const char * +lttng_event_expr_event_payload_field_get_name(const struct lttng_event_expr *expr); /* * Creates a per-channel context field expression for the per-channel @@ -130,8 +131,8 @@ lttng_event_expr_channel_context_field_create(const char *field_name); * * The type of `expr` is not * `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD`. */ -LTTNG_EXPORT extern const char *lttng_event_expr_channel_context_field_get_name( - const struct lttng_event_expr *expr); +LTTNG_EXPORT extern const char * +lttng_event_expr_channel_context_field_get_name(const struct lttng_event_expr *expr); /* * Creates an application-specific context field expression for the @@ -145,8 +146,8 @@ LTTNG_EXPORT extern const char *lttng_event_expr_channel_context_field_get_name( * * `type_name` is `NULL`. */ LTTNG_EXPORT extern struct lttng_event_expr * -lttng_event_expr_app_specific_context_field_create( - const char *provider_name, const char *type_name); +lttng_event_expr_app_specific_context_field_create(const char *provider_name, + const char *type_name); /* * Returns the provider name of the application-specific context field @@ -157,8 +158,7 @@ lttng_event_expr_app_specific_context_field_create( * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`. */ LTTNG_EXPORT extern const char * -lttng_event_expr_app_specific_context_field_get_provider_name( - const struct lttng_event_expr *expr); +lttng_event_expr_app_specific_context_field_get_provider_name(const struct lttng_event_expr *expr); /* * Returns the type name of the application-specific context field @@ -169,8 +169,7 @@ lttng_event_expr_app_specific_context_field_get_provider_name( * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`. */ LTTNG_EXPORT extern const char * -lttng_event_expr_app_specific_context_field_get_type_name( - const struct lttng_event_expr *expr); +lttng_event_expr_app_specific_context_field_get_type_name(const struct lttng_event_expr *expr); /* * Creates an array field element expression for the parent array field @@ -188,9 +187,9 @@ lttng_event_expr_app_specific_context_field_get_type_name( * * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD` * * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT` */ -LTTNG_EXPORT extern struct lttng_event_expr *lttng_event_expr_array_field_element_create( - struct lttng_event_expr *array_field_expr, - unsigned int index); +LTTNG_EXPORT extern struct lttng_event_expr * +lttng_event_expr_array_field_element_create(struct lttng_event_expr *array_field_expr, + unsigned int index); /* * Returns the parent array field expression of the array field element @@ -201,8 +200,7 @@ LTTNG_EXPORT extern struct lttng_event_expr *lttng_event_expr_array_field_elemen * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`. */ LTTNG_EXPORT extern const struct lttng_event_expr * -lttng_event_expr_array_field_element_get_parent_expr( - const struct lttng_event_expr *expr); +lttng_event_expr_array_field_element_get_parent_expr(const struct lttng_event_expr *expr); /* * Sets `*index` to the index of the array field element expression @@ -220,8 +218,8 @@ lttng_event_expr_array_field_element_get_parent_expr( * * `index` is `NULL`. */ LTTNG_EXPORT extern enum lttng_event_expr_status -lttng_event_expr_array_field_element_get_index( - const struct lttng_event_expr *expr, unsigned int *index); +lttng_event_expr_array_field_element_get_index(const struct lttng_event_expr *expr, + unsigned int *index); /* * Returns whether or not the event expressions `expr_a` and `expr_b` @@ -230,7 +228,7 @@ lttng_event_expr_array_field_element_get_index( * `expr_a` and `expr_b` can be `NULL`. */ LTTNG_EXPORT extern bool lttng_event_expr_is_equal(const struct lttng_event_expr *expr_a, - const struct lttng_event_expr *expr_b); + const struct lttng_event_expr *expr_b); /* * Destroys the event expression `expr` if not `NULL`. diff --git a/include/lttng/event-field-value-internal.hpp b/include/lttng/event-field-value-internal.hpp index 03ef8960b..57a6a3e1c 100644 --- a/include/lttng/event-field-value-internal.hpp +++ b/include/lttng/event-field-value-internal.hpp @@ -8,10 +8,12 @@ #ifndef LTTNG_EVENT_FIELD_VALUE_INTERNAL_H #define LTTNG_EVENT_FIELD_VALUE_INTERNAL_H -#include -#include #include +#include + +#include + struct lttng_event_field_value { enum lttng_event_field_value_type type; }; @@ -114,9 +116,8 @@ struct lttng_event_field_value_array { * * `count` is `NULL`. */ enum lttng_event_field_value_status -lttng_event_field_value_enum_get_label_count( - const struct lttng_event_field_value *field_val, - unsigned int *count); +lttng_event_field_value_enum_get_label_count(const struct lttng_event_field_value *field_val, + unsigned int *count); /* * Returns the label at index `index` of the enumeration event field @@ -129,45 +130,39 @@ lttng_event_field_value_enum_get_label_count( * * `index` is greater than or equal to the label count of `field_val`, * as returned by lttng_event_field_value_enum_get_label_count(). */ -const char *lttng_event_field_value_enum_get_label_at_index( - const struct lttng_event_field_value *field_val, - unsigned int index); +const char * +lttng_event_field_value_enum_get_label_at_index(const struct lttng_event_field_value *field_val, + unsigned int index); -struct lttng_event_field_value *lttng_event_field_value_uint_create( - uint64_t val); +struct lttng_event_field_value *lttng_event_field_value_uint_create(uint64_t val); -struct lttng_event_field_value *lttng_event_field_value_int_create( - int64_t val); +struct lttng_event_field_value *lttng_event_field_value_int_create(int64_t val); -struct lttng_event_field_value *lttng_event_field_value_enum_uint_create( - uint64_t val); +struct lttng_event_field_value *lttng_event_field_value_enum_uint_create(uint64_t val); -struct lttng_event_field_value *lttng_event_field_value_enum_int_create( - int64_t val); +struct lttng_event_field_value *lttng_event_field_value_enum_int_create(int64_t val); struct lttng_event_field_value *lttng_event_field_value_real_create(double val); -struct lttng_event_field_value *lttng_event_field_value_string_create( - const char *val); +struct lttng_event_field_value *lttng_event_field_value_string_create(const char *val); -struct lttng_event_field_value *lttng_event_field_value_string_create_with_size( - const char *val, size_t size); +struct lttng_event_field_value *lttng_event_field_value_string_create_with_size(const char *val, + size_t size); -struct lttng_event_field_value *lttng_event_field_value_array_create(void); +struct lttng_event_field_value *lttng_event_field_value_array_create(); -int lttng_event_field_value_enum_append_label( - struct lttng_event_field_value *field_val, const char *label); +int lttng_event_field_value_enum_append_label(struct lttng_event_field_value *field_val, + const char *label); -int lttng_event_field_value_enum_append_label_with_size( - struct lttng_event_field_value *field_val, const char *label, - size_t size); +int lttng_event_field_value_enum_append_label_with_size(struct lttng_event_field_value *field_val, + const char *label, + size_t size); -int lttng_event_field_value_array_append( - struct lttng_event_field_value *array_field_val, - struct lttng_event_field_value *field_val); +int lttng_event_field_value_array_append(struct lttng_event_field_value *array_field_val, + struct lttng_event_field_value *field_val); int lttng_event_field_value_array_append_unavailable( - struct lttng_event_field_value *array_field_val); + struct lttng_event_field_value *array_field_val); void lttng_event_field_value_destroy(struct lttng_event_field_value *field_val); diff --git a/include/lttng/event-field-value.h b/include/lttng/event-field-value.h index 02d93c661..7f10deec3 100644 --- a/include/lttng/event-field-value.h +++ b/include/lttng/event-field-value.h @@ -9,6 +9,7 @@ #define LTTNG_EVENT_FIELD_VALUE_H #include + #include struct lttng_event_field_value; @@ -104,8 +105,8 @@ enum lttng_event_field_value_status { * `LTTNG_EVENT_FIELD_VALUE_TYPE_INVALID`: * `field_val` is `NULL`. */ -LTTNG_EXPORT extern enum lttng_event_field_value_type lttng_event_field_value_get_type( - const struct lttng_event_field_value *field_val); +LTTNG_EXPORT extern enum lttng_event_field_value_type +lttng_event_field_value_get_type(const struct lttng_event_field_value *field_val); /* * Sets `*val` to the raw value of the unsigned integer/enumeration @@ -124,8 +125,8 @@ LTTNG_EXPORT extern enum lttng_event_field_value_type lttng_event_field_value_ge * * `val` is `NULL`. */ LTTNG_EXPORT extern enum lttng_event_field_value_status -lttng_event_field_value_unsigned_int_get_value( - const struct lttng_event_field_value *field_val, uint64_t *val); +lttng_event_field_value_unsigned_int_get_value(const struct lttng_event_field_value *field_val, + uint64_t *val); /* * Sets `*val` to the raw value of the signed integer/enumeration event @@ -144,8 +145,8 @@ lttng_event_field_value_unsigned_int_get_value( * * `val` is `NULL`. */ LTTNG_EXPORT extern enum lttng_event_field_value_status -lttng_event_field_value_signed_int_get_value( - const struct lttng_event_field_value *field_val, int64_t *val); +lttng_event_field_value_signed_int_get_value(const struct lttng_event_field_value *field_val, + int64_t *val); /* * Sets `*val` to the raw value of the real event field value @@ -163,8 +164,8 @@ lttng_event_field_value_signed_int_get_value( * * `val` is `NULL`. */ LTTNG_EXPORT extern enum lttng_event_field_value_status -lttng_event_field_value_real_get_value( - const struct lttng_event_field_value *field_val, double *val); +lttng_event_field_value_real_get_value(const struct lttng_event_field_value *field_val, + double *val); /* * Returns the raw value (an UTF-8 C string) of the string event field @@ -179,9 +180,8 @@ lttng_event_field_value_real_get_value( * `LTTNG_EVENT_FIELD_VALUE_TYPE_STRING`. */ LTTNG_EXPORT extern enum lttng_event_field_value_status -lttng_event_field_value_string_get_value( - const struct lttng_event_field_value *field_val, - const char **value); +lttng_event_field_value_string_get_value(const struct lttng_event_field_value *field_val, + const char **value); /* * Sets `*length` to the length (the number of contained elements) of @@ -199,9 +199,8 @@ lttng_event_field_value_string_get_value( * * `length` is `NULL`. */ LTTNG_EXPORT extern enum lttng_event_field_value_status -lttng_event_field_value_array_get_length( - const struct lttng_event_field_value *field_val, - unsigned int *length); +lttng_event_field_value_array_get_length(const struct lttng_event_field_value *field_val, + unsigned int *length); /* * Sets `*elem_field_val` to the event field value at index `index` in @@ -225,9 +224,9 @@ lttng_event_field_value_array_get_length( */ LTTNG_EXPORT extern enum lttng_event_field_value_status lttng_event_field_value_array_get_element_at_index( - const struct lttng_event_field_value *field_val, - unsigned int index, - const struct lttng_event_field_value **elem_field_val); + const struct lttng_event_field_value *field_val, + unsigned int index, + const struct lttng_event_field_value **elem_field_val); #ifdef __cplusplus } diff --git a/include/lttng/event-internal.hpp b/include/lttng/event-internal.hpp index daa8fa68e..3d8893b69 100644 --- a/include/lttng/event-internal.hpp +++ b/include/lttng/event-internal.hpp @@ -13,6 +13,7 @@ #define LTTNG_EVENT_INTERNAL_H #include + #include #include @@ -58,7 +59,7 @@ struct lttng_event_comm { struct lttng_event_exclusion_comm { /* Includes terminator `\0`. */ uint32_t len; - char payload []; + char payload[]; } LTTNG_PACKED; struct lttng_event_probe_attr_comm { @@ -154,43 +155,38 @@ struct lttng_event_extended { struct lttng_event *lttng_event_copy(const struct lttng_event *event); ssize_t lttng_event_create_from_payload(struct lttng_payload_view *view, - struct lttng_event **out_event, - struct lttng_event_exclusion **out_exclusion, - char **out_filter_expression, - struct lttng_bytecode **out_bytecode); + struct lttng_event **out_event, + struct lttng_event_exclusion **out_exclusion, + char **out_filter_expression, + struct lttng_bytecode **out_bytecode); int lttng_event_serialize(const struct lttng_event *event, - unsigned int exclusion_count, - char **exclusion_list, - char *filter_expression, - size_t bytecode_len, - struct lttng_bytecode *bytecode, - struct lttng_payload *payload); + unsigned int exclusion_count, + const char *const *exclusion_list, + const char *filter_expression, + size_t bytecode_len, + struct lttng_bytecode *bytecode, + struct lttng_payload *payload); -ssize_t lttng_event_context_create_from_payload( - struct lttng_payload_view *view, - struct lttng_event_context **event_ctx); +ssize_t lttng_event_context_create_from_payload(struct lttng_payload_view *view, + struct lttng_event_context **event_ctx); int lttng_event_context_serialize(struct lttng_event_context *context, - struct lttng_payload *payload); + struct lttng_payload *payload); void lttng_event_context_destroy(struct lttng_event_context *context); -enum lttng_error_code lttng_events_create_and_flatten_from_payload( - struct lttng_payload_view *view, - unsigned int count, - struct lttng_event **events); +enum lttng_error_code lttng_events_create_and_flatten_from_payload(struct lttng_payload_view *view, + unsigned int count, + struct lttng_event **events); -ssize_t lttng_event_field_create_from_payload( - struct lttng_payload_view *view, - struct lttng_event_field **field); +ssize_t lttng_event_field_create_from_payload(struct lttng_payload_view *view, + struct lttng_event_field **field); int lttng_event_field_serialize(const struct lttng_event_field *field, - struct lttng_payload *payload); + struct lttng_payload *payload); enum lttng_error_code lttng_event_fields_create_and_flatten_from_payload( - struct lttng_payload_view *view, - unsigned int count, - struct lttng_event_field **fields); + struct lttng_payload_view *view, unsigned int count, struct lttng_event_field **fields); #endif /* LTTNG_EVENT_INTERNAL_H */ diff --git a/include/lttng/event-rule/event-rule-internal.hpp b/include/lttng/event-rule/event-rule-internal.hpp index 46fb98144..1b73b0609 100644 --- a/include/lttng/event-rule/event-rule-internal.hpp +++ b/include/lttng/event-rule/event-rule-internal.hpp @@ -8,13 +8,15 @@ #ifndef LTTNG_EVENT_RULE_INTERNAL_H #define LTTNG_EVENT_RULE_INTERNAL_H -#include #include +#include #include + #include -#include #include +#include #include + #include #include #include @@ -31,36 +33,24 @@ enum lttng_event_rule_generate_exclusions_status { LTTNG_EVENT_RULE_GENERATE_EXCLUSIONS_STATUS_OUT_OF_MEMORY, }; -typedef void (*event_rule_destroy_cb)(struct lttng_event_rule *event_rule); -typedef bool (*event_rule_validate_cb)( - const struct lttng_event_rule *event_rule); -typedef int (*event_rule_serialize_cb)( - const struct lttng_event_rule *event_rule, - struct lttng_payload *payload); -typedef bool (*event_rule_equal_cb)(const struct lttng_event_rule *a, - const struct lttng_event_rule *b); -typedef ssize_t (*event_rule_create_from_payload_cb)( - struct lttng_payload_view *view, - struct lttng_event_rule **event_rule); -typedef enum lttng_error_code (*event_rule_generate_filter_bytecode_cb)( - struct lttng_event_rule *event_rule, - const struct lttng_credentials *creds); -typedef const char *(*event_rule_get_filter_cb)( - const struct lttng_event_rule *event_rule); -typedef const struct lttng_bytecode *( - *event_rule_get_filter_bytecode_cb)( - const struct lttng_event_rule *event_rule); -typedef enum lttng_event_rule_generate_exclusions_status ( - *event_rule_generate_exclusions_cb)( - const struct lttng_event_rule *event_rule, - struct lttng_event_exclusion **exclusions); -typedef unsigned long (*event_rule_hash_cb)( - const struct lttng_event_rule *event_rule); -typedef struct lttng_event *(*event_rule_generate_lttng_event_cb)( - const struct lttng_event_rule *event_rule); -typedef enum lttng_error_code (*event_rule_mi_serialize_cb)( - const struct lttng_event_rule *event_rule, - struct mi_writer *writer); +using event_rule_destroy_cb = void (*)(struct lttng_event_rule *); +using event_rule_validate_cb = bool (*)(const struct lttng_event_rule *); +using event_rule_serialize_cb = int (*)(const struct lttng_event_rule *, struct lttng_payload *); +using event_rule_equal_cb = bool (*)(const struct lttng_event_rule *, + const struct lttng_event_rule *); +using event_rule_create_from_payload_cb = ssize_t (*)(struct lttng_payload_view *, + struct lttng_event_rule **); +using event_rule_generate_filter_bytecode_cb = + enum lttng_error_code (*)(struct lttng_event_rule *, const struct lttng_credentials *); +using event_rule_get_filter_cb = const char *(*) (const struct lttng_event_rule *); +using event_rule_get_filter_bytecode_cb = + const struct lttng_bytecode *(*) (const struct lttng_event_rule *); +using event_rule_generate_exclusions_cb = enum lttng_event_rule_generate_exclusions_status (*)( + const struct lttng_event_rule *, struct lttng_event_exclusion **); +using event_rule_hash_cb = unsigned long (*)(const struct lttng_event_rule *); +using event_rule_generate_lttng_event_cb = struct lttng_event *(*) (const struct lttng_event_rule *); +using event_rule_mi_serialize_cb = enum lttng_error_code (*)(const struct lttng_event_rule *, + struct mi_writer *); struct lttng_event_rule { struct urcu_ref ref; @@ -84,31 +74,27 @@ struct lttng_event_rule_comm { char payload[]; }; -void lttng_event_rule_init(struct lttng_event_rule *event_rule, - enum lttng_event_rule_type type); +void lttng_event_rule_init(struct lttng_event_rule *event_rule, enum lttng_event_rule_type type); bool lttng_event_rule_validate(const struct lttng_event_rule *event_rule); -ssize_t lttng_event_rule_create_from_payload( - struct lttng_payload_view *payload, - struct lttng_event_rule **event_rule); +ssize_t lttng_event_rule_create_from_payload(struct lttng_payload_view *payload, + struct lttng_event_rule **event_rule); int lttng_event_rule_serialize(const struct lttng_event_rule *event_rule, - struct lttng_payload *payload); + struct lttng_payload *payload); -bool lttng_event_rule_is_equal(const struct lttng_event_rule *a, - const struct lttng_event_rule *b); +bool lttng_event_rule_is_equal(const struct lttng_event_rule *a, const struct lttng_event_rule *b); bool lttng_event_rule_get(struct lttng_event_rule *rule); void lttng_event_rule_put(struct lttng_event_rule *rule); -enum lttng_domain_type lttng_event_rule_get_domain_type( - const struct lttng_event_rule *rule); +enum lttng_domain_type lttng_event_rule_get_domain_type(const struct lttng_event_rule *rule); -enum lttng_error_code lttng_event_rule_generate_filter_bytecode( - struct lttng_event_rule *rule, - const struct lttng_credentials *creds); +enum lttng_error_code +lttng_event_rule_generate_filter_bytecode(struct lttng_event_rule *rule, + const struct lttng_credentials *creds); /* * If not present/implemented returns NULL. @@ -120,8 +106,8 @@ const char *lttng_event_rule_get_filter(const struct lttng_event_rule *rule); * If not present/implemented returns NULL. * Caller DOES NOT own the returned object. */ -const struct lttng_bytecode *lttng_event_rule_get_filter_bytecode( - const struct lttng_event_rule *rule); +const struct lttng_bytecode * +lttng_event_rule_get_filter_bytecode(const struct lttng_event_rule *rule); /* * If not present/implemented return NULL. @@ -129,7 +115,7 @@ const struct lttng_bytecode *lttng_event_rule_get_filter_bytecode( */ enum lttng_event_rule_generate_exclusions_status lttng_event_rule_generate_exclusions(const struct lttng_event_rule *rule, - struct lttng_event_exclusion **exclusions); + struct lttng_event_exclusion **exclusions); const char *lttng_event_rule_type_str(enum lttng_event_rule_type type); @@ -144,13 +130,12 @@ unsigned long lttng_event_rule_hash(const struct lttng_event_rule *rule); * * The caller owns the returned object. */ -struct lttng_event *lttng_event_rule_generate_lttng_event( - const struct lttng_event_rule *rule); +struct lttng_event *lttng_event_rule_generate_lttng_event(const struct lttng_event_rule *rule); /* Test if an event rule targets an agent domain. */ bool lttng_event_rule_targets_agent_domain(const struct lttng_event_rule *rule); -enum lttng_error_code lttng_event_rule_mi_serialize( - const struct lttng_event_rule *rule, struct mi_writer *writer); +enum lttng_error_code lttng_event_rule_mi_serialize(const struct lttng_event_rule *rule, + struct mi_writer *writer); #endif /* LTTNG_EVENT_RULE_INTERNAL_H */ diff --git a/include/lttng/event-rule/event-rule.h b/include/lttng/event-rule/event-rule.h index 0c2453ccf..a75db771e 100644 --- a/include/lttng/event-rule/event-rule.h +++ b/include/lttng/event-rule/event-rule.h @@ -48,8 +48,8 @@ enum lttng_event_rule_status { * Returns the type of an event rule on success, LTTNG_EVENT_RULE_UNKNOWN on * error. */ -LTTNG_EXPORT extern enum lttng_event_rule_type lttng_event_rule_get_type( - const struct lttng_event_rule *event_rule); +LTTNG_EXPORT extern enum lttng_event_rule_type +lttng_event_rule_get_type(const struct lttng_event_rule *event_rule); /* * Destroy an event rule object. diff --git a/include/lttng/event-rule/jul-logging-internal.hpp b/include/lttng/event-rule/jul-logging-internal.hpp index b769f0f80..c84ab7a7f 100644 --- a/include/lttng/event-rule/jul-logging-internal.hpp +++ b/include/lttng/event-rule/jul-logging-internal.hpp @@ -8,9 +8,10 @@ #ifndef LTTNG_EVENT_RULE_JUL_LOGGING_INTERNAL_H #define LTTNG_EVENT_RULE_JUL_LOGGING_INTERNAL_H -#include #include #include +#include + #include #include #include @@ -51,8 +52,7 @@ struct lttng_event_rule_jul_logging_comm { char payload[]; } LTTNG_PACKED; -ssize_t lttng_event_rule_jul_logging_create_from_payload( - struct lttng_payload_view *view, - struct lttng_event_rule **rule); +ssize_t lttng_event_rule_jul_logging_create_from_payload(struct lttng_payload_view *view, + struct lttng_event_rule **rule); #endif /* LTTNG_EVENT_RULE_JUL_LOGGING_INTERNAL_H */ diff --git a/include/lttng/event-rule/jul-logging.h b/include/lttng/event-rule/jul-logging.h index 833e6adff..7960c1c7e 100644 --- a/include/lttng/event-rule/jul-logging.h +++ b/include/lttng/event-rule/jul-logging.h @@ -9,9 +9,9 @@ #define LTTNG_EVENT_RULE_JUL_LOGGING_H #include +#include #include #include -#include #ifdef __cplusplus extern "C" { @@ -35,8 +35,8 @@ LTTNG_EXPORT extern struct lttng_event_rule *lttng_event_rule_jul_logging_create * Return LTTNG_EVENT_RULE_STATUS_OK on success, LTTNG_EVENT_RULE_STATUS_INVALID * if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_jul_logging_set_name_pattern( - struct lttng_event_rule *rule, const char *pattern); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_jul_logging_set_name_pattern(struct lttng_event_rule *rule, const char *pattern); /* * Get the name pattern of a jul logging event rule. @@ -50,8 +50,9 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_jul_logging_se * parameter is passed, or LTTNG_EVENT_RULE_STATUS_UNSET if a pattern * was not set prior to this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_jul_logging_get_name_pattern( - const struct lttng_event_rule *rule, const char **pattern); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_jul_logging_get_name_pattern(const struct lttng_event_rule *rule, + const char **pattern); /* * Set the filter expression of a jul logging event rule. @@ -61,8 +62,8 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_jul_logging_ge * Return LTTNG_EVENT_RULE_STATUS_OK on success, LTTNG_EVENT_RULE_STATUS_INVALID * if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_jul_logging_set_filter( - struct lttng_event_rule *rule, const char *expression); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_jul_logging_set_filter(struct lttng_event_rule *rule, const char *expression); /* * Get the filter expression of a jul logging event rule. @@ -76,8 +77,9 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_jul_logging_se * parameter is passed, or LTTNG_EVENT_RULE_STATUS_UNSET if a filter expression * was not set prior to this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_jul_logging_get_filter( - const struct lttng_event_rule *rule, const char **expression); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_jul_logging_get_filter(const struct lttng_event_rule *rule, + const char **expression); /* * Set the log level rule of a jul logging event rule. @@ -89,7 +91,7 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_jul_logging_ge */ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_jul_logging_set_log_level_rule(struct lttng_event_rule *rule, - const struct lttng_log_level_rule *log_level_rule); + const struct lttng_log_level_rule *log_level_rule); /* * Get the log level rule of a jul logging event rule. @@ -104,9 +106,8 @@ lttng_event_rule_jul_logging_set_log_level_rule(struct lttng_event_rule *rule, * to this call. */ LTTNG_EXPORT extern enum lttng_event_rule_status -lttng_event_rule_jul_logging_get_log_level_rule( - const struct lttng_event_rule *rule, - const struct lttng_log_level_rule **log_level_rule); +lttng_event_rule_jul_logging_get_log_level_rule(const struct lttng_event_rule *rule, + const struct lttng_log_level_rule **log_level_rule); #ifdef __cplusplus } diff --git a/include/lttng/event-rule/kernel-kprobe-internal.hpp b/include/lttng/event-rule/kernel-kprobe-internal.hpp index 5b4997987..f92fc10c4 100644 --- a/include/lttng/event-rule/kernel-kprobe-internal.hpp +++ b/include/lttng/event-rule/kernel-kprobe-internal.hpp @@ -8,8 +8,9 @@ #ifndef LTTNG_EVENT_RULE_KERNEL_KPROBE_INTERNAL_H #define LTTNG_EVENT_RULE_KERNEL_KPROBE_INTERNAL_H -#include #include +#include + #include #include @@ -31,8 +32,7 @@ struct lttng_event_rule_kernel_kprobe_comm { char payload[]; } LTTNG_PACKED; -ssize_t lttng_event_rule_kernel_kprobe_create_from_payload( - struct lttng_payload_view *payload, - struct lttng_event_rule **rule); +ssize_t lttng_event_rule_kernel_kprobe_create_from_payload(struct lttng_payload_view *payload, + struct lttng_event_rule **rule); #endif /* LTTNG_EVENT_RULE_KERNEL_KPROBE_INTERNAL_H */ diff --git a/include/lttng/event-rule/kernel-kprobe.h b/include/lttng/event-rule/kernel-kprobe.h index c970116af..6e292f0d1 100644 --- a/include/lttng/event-rule/kernel-kprobe.h +++ b/include/lttng/event-rule/kernel-kprobe.h @@ -25,8 +25,8 @@ struct lttng_kernel_probe_location; * Returns a new event rule on success, NULL on failure. The returned event rule * must be destroyed using lttng_event_rule_destroy(). */ -LTTNG_EXPORT extern struct lttng_event_rule *lttng_event_rule_kernel_kprobe_create( - const struct lttng_kernel_probe_location *location); +LTTNG_EXPORT extern struct lttng_event_rule * +lttng_event_rule_kernel_kprobe_create(const struct lttng_kernel_probe_location *location); /* * Get the kernel probe location of a kernel kprobe event rule. @@ -40,9 +40,9 @@ LTTNG_EXPORT extern struct lttng_event_rule *lttng_event_rule_kernel_kprobe_crea * passed, or LTTNG_EVENT_RULE_STATUS_UNSET if a location was not set prior to * this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_kprobe_get_location( - const struct lttng_event_rule *rule, - const struct lttng_kernel_probe_location **location); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_kernel_kprobe_get_location(const struct lttng_event_rule *rule, + const struct lttng_kernel_probe_location **location); /* * Set the name of a kernel kprobe event rule. @@ -52,8 +52,8 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_kprobe_ * Returns LTTNG_EVENT_RULE_STATUS_OK on success, LTTNG_EVENT_RULE_STATUS_INVALID * if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_kprobe_set_event_name( - struct lttng_event_rule *rule, const char *name); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_kernel_kprobe_set_event_name(struct lttng_event_rule *rule, const char *name); /* * Get the name of a kernel kprobe event rule. @@ -66,8 +66,9 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_kprobe_ * success, LTTNG_EVENT_RULE_STATUS_INVALID if an invalid parameter is passed, * or LTTNG_EVENT_RULE_STATUS_UNSET if a name was not set prior to this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_kprobe_get_event_name( - const struct lttng_event_rule *rule, const char **name); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_kernel_kprobe_get_event_name(const struct lttng_event_rule *rule, + const char **name); #ifdef __cplusplus } diff --git a/include/lttng/event-rule/kernel-syscall-internal.hpp b/include/lttng/event-rule/kernel-syscall-internal.hpp index 2ca1823ec..9cef606bb 100644 --- a/include/lttng/event-rule/kernel-syscall-internal.hpp +++ b/include/lttng/event-rule/kernel-syscall-internal.hpp @@ -8,8 +8,9 @@ #ifndef LTTNG_EVENT_RULE_KERNEL_SYSCALL_INTERNAL_H #define LTTNG_EVENT_RULE_KERNEL_SYSCALL_INTERNAL_H -#include #include +#include + #include #include @@ -40,11 +41,10 @@ struct lttng_event_rule_kernel_syscall_comm { char payload[]; } LTTNG_PACKED; -ssize_t lttng_event_rule_kernel_syscall_create_from_payload( - struct lttng_payload_view *view, - struct lttng_event_rule **rule); +ssize_t lttng_event_rule_kernel_syscall_create_from_payload(struct lttng_payload_view *view, + struct lttng_event_rule **rule); const char *lttng_event_rule_kernel_syscall_emission_site_str( - enum lttng_event_rule_kernel_syscall_emission_site emission_site); + enum lttng_event_rule_kernel_syscall_emission_site emission_site); #endif /* LTTNG_EVENT_RULE_KERNEL_SYSCALL_INTERNAL_H */ diff --git a/include/lttng/event-rule/kernel-syscall.h b/include/lttng/event-rule/kernel-syscall.h index ce8be6a5d..4ae104ff6 100644 --- a/include/lttng/event-rule/kernel-syscall.h +++ b/include/lttng/event-rule/kernel-syscall.h @@ -31,8 +31,8 @@ enum lttng_event_rule_kernel_syscall_emission_site { * Returns a new event rule on success, NULL on failure. This event rule must be * destroyed using lttng_event_rule_destroy(). */ -LTTNG_EXPORT extern struct lttng_event_rule *lttng_event_rule_kernel_syscall_create(enum - lttng_event_rule_kernel_syscall_emission_site emission_site); +LTTNG_EXPORT extern struct lttng_event_rule *lttng_event_rule_kernel_syscall_create( + enum lttng_event_rule_kernel_syscall_emission_site emission_site); /* * Set the name pattern of a kernel syscall event rule. @@ -44,8 +44,9 @@ LTTNG_EXPORT extern struct lttng_event_rule *lttng_event_rule_kernel_syscall_cre * Returns LTTNG_EVENT_RULE_STATUS_OK on success, LTTNG_EVENT_RULE_STATUS_INVALID * if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_syscall_set_name_pattern( - struct lttng_event_rule *rule, const char *pattern); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_kernel_syscall_set_name_pattern(struct lttng_event_rule *rule, + const char *pattern); /* * Get the name pattern of a kernel syscall event rule. @@ -59,8 +60,9 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_syscall * parameter is passed, or LTTNG_EVENT_RULE_STATUS_UNSET if a pattern * was not set prior to this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_syscall_get_name_pattern( - const struct lttng_event_rule *rule, const char **pattern); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_kernel_syscall_get_name_pattern(const struct lttng_event_rule *rule, + const char **pattern); /* * Set the filter expression of a kernel syscall event rule. @@ -70,8 +72,8 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_syscall * Returns LTTNG_EVENT_RULE_STATUS_OK on success, LTTNG_EVENT_RULE_STATUS_INVALID * if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_syscall_set_filter( - struct lttng_event_rule *rule, const char *expression); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_kernel_syscall_set_filter(struct lttng_event_rule *rule, const char *expression); /* * Get the filter expression of a kernel syscall event rule. @@ -85,8 +87,9 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_syscall * parameter is passed, or LTTNG_EVENT_RULE_STATUS_UNSET if a filter expression * was not set prior to this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_syscall_get_filter( - const struct lttng_event_rule *rule, const char **expression); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_kernel_syscall_get_filter(const struct lttng_event_rule *rule, + const char **expression); /* * Get the emission site of a kernel syscall event rule. @@ -94,8 +97,7 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_syscall * Returns a enum lttng_event_rule_kernel_syscall_emission_site. */ LTTNG_EXPORT extern enum lttng_event_rule_kernel_syscall_emission_site -lttng_event_rule_kernel_syscall_get_emission_site( - const struct lttng_event_rule *rule); +lttng_event_rule_kernel_syscall_get_emission_site(const struct lttng_event_rule *rule); #ifdef __cplusplus } diff --git a/include/lttng/event-rule/kernel-tracepoint-internal.hpp b/include/lttng/event-rule/kernel-tracepoint-internal.hpp index d800eef91..1a0e50abd 100644 --- a/include/lttng/event-rule/kernel-tracepoint-internal.hpp +++ b/include/lttng/event-rule/kernel-tracepoint-internal.hpp @@ -8,9 +8,10 @@ #ifndef LTTNG_EVENT_RULE_KERNEL_TRACEPOINT_INTERNAL_H #define LTTNG_EVENT_RULE_KERNEL_TRACEPOINT_INTERNAL_H -#include #include #include +#include + #include #include #include @@ -44,8 +45,7 @@ struct lttng_event_rule_kernel_tracepoint_comm { char payload[]; } LTTNG_PACKED; -ssize_t lttng_event_rule_kernel_tracepoint_create_from_payload( - struct lttng_payload_view *view, - struct lttng_event_rule **rule); +ssize_t lttng_event_rule_kernel_tracepoint_create_from_payload(struct lttng_payload_view *view, + struct lttng_event_rule **rule); #endif /* LTTNG_EVENT_RULE_KERNEL_TRACEPOINT_INTERNAL_H */ diff --git a/include/lttng/event-rule/kernel-tracepoint.h b/include/lttng/event-rule/kernel-tracepoint.h index 550a04ac4..6c566e159 100644 --- a/include/lttng/event-rule/kernel-tracepoint.h +++ b/include/lttng/event-rule/kernel-tracepoint.h @@ -34,8 +34,9 @@ LTTNG_EXPORT extern struct lttng_event_rule *lttng_event_rule_kernel_tracepoint_ * Return LTTNG_EVENT_RULE_STATUS_OK on success, LTTNG_EVENT_RULE_STATUS_INVALID * if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_tracepoint_set_name_pattern( - struct lttng_event_rule *rule, const char *pattern); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_kernel_tracepoint_set_name_pattern(struct lttng_event_rule *rule, + const char *pattern); /* * Get the name pattern of a kernel tracepoint event rule. @@ -49,8 +50,9 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_tracepo * parameter is passed, or LTTNG_EVENT_RULE_STATUS_UNSET if a pattern * was not set prior to this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_tracepoint_get_name_pattern( - const struct lttng_event_rule *rule, const char **pattern); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_kernel_tracepoint_get_name_pattern(const struct lttng_event_rule *rule, + const char **pattern); /* * Set the filter expression of a kernel tracepoint event rule. @@ -60,8 +62,9 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_tracepo * Return LTTNG_EVENT_RULE_STATUS_OK on success, LTTNG_EVENT_RULE_STATUS_INVALID * if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_tracepoint_set_filter( - struct lttng_event_rule *rule, const char *expression); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_kernel_tracepoint_set_filter(struct lttng_event_rule *rule, + const char *expression); /* * Get the filter expression of a kernel tracepoint event rule. @@ -75,8 +78,9 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_tracepo * parameter is passed, or LTTNG_EVENT_RULE_STATUS_UNSET if a filter expression * was not set prior to this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_tracepoint_get_filter( - const struct lttng_event_rule *rule, const char **expression); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_kernel_tracepoint_get_filter(const struct lttng_event_rule *rule, + const char **expression); #ifdef __cplusplus } diff --git a/include/lttng/event-rule/kernel-uprobe-internal.hpp b/include/lttng/event-rule/kernel-uprobe-internal.hpp index f9a193100..61dfd4f3f 100644 --- a/include/lttng/event-rule/kernel-uprobe-internal.hpp +++ b/include/lttng/event-rule/kernel-uprobe-internal.hpp @@ -8,8 +8,9 @@ #ifndef LTTNG_EVENT_RULE_KERNEL_UPROBE_INTERNAL_H #define LTTNG_EVENT_RULE_KERNEL_UPROBE_INTERNAL_H -#include #include +#include + #include #include @@ -32,12 +33,10 @@ struct lttng_event_rule_kernel_uprobe_comm { char payload[]; } LTTNG_PACKED; -ssize_t lttng_event_rule_kernel_uprobe_create_from_payload( - struct lttng_payload_view *view, - struct lttng_event_rule **rule); +ssize_t lttng_event_rule_kernel_uprobe_create_from_payload(struct lttng_payload_view *view, + struct lttng_event_rule **rule); struct lttng_userspace_probe_location * -lttng_event_rule_kernel_uprobe_get_location_mutable( - const struct lttng_event_rule *rule); +lttng_event_rule_kernel_uprobe_get_location_mutable(const struct lttng_event_rule *rule); #endif /* LTTNG_EVENT_RULE_KERNEL_UPROBE_INTERNAL_H */ diff --git a/include/lttng/event-rule/kernel-uprobe.h b/include/lttng/event-rule/kernel-uprobe.h index 6b29b695d..cfb0ccaa7 100644 --- a/include/lttng/event-rule/kernel-uprobe.h +++ b/include/lttng/event-rule/kernel-uprobe.h @@ -24,8 +24,8 @@ extern "C" { * Returns a new event rule on success, NULL on failure. This event rule must be * destroyed using lttng_event_rule_destroy(). */ -LTTNG_EXPORT extern struct lttng_event_rule *lttng_event_rule_kernel_uprobe_create( - const struct lttng_userspace_probe_location *location); +LTTNG_EXPORT extern struct lttng_event_rule * +lttng_event_rule_kernel_uprobe_create(const struct lttng_userspace_probe_location *location); /* * Get the location of a kernel uprobe event rule. @@ -39,9 +39,9 @@ LTTNG_EXPORT extern struct lttng_event_rule *lttng_event_rule_kernel_uprobe_crea * passed, or LTTNG_EVENT_RULE_STATUS_UNSET if a location was not set prior to * this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_uprobe_get_location( - const struct lttng_event_rule *rule, - const struct lttng_userspace_probe_location **location); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_kernel_uprobe_get_location(const struct lttng_event_rule *rule, + const struct lttng_userspace_probe_location **location); /* * Set the name of a kernel uprobe event rule. @@ -51,8 +51,8 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_uprobe_ * Return LTTNG_EVENT_RULE_STATUS_OK on success, LTTNG_EVENT_RULE_STATUS_INVALID * if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_uprobe_set_event_name( - struct lttng_event_rule *rule, const char *name); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_kernel_uprobe_set_event_name(struct lttng_event_rule *rule, const char *name); /* * Get the name of a kernel uprobe event rule. @@ -65,8 +65,9 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_uprobe_ * success, LTTNG_EVENT_RULE_STATUS_INVALID if an invalid parameter is passed, * or LTTNG_EVENT_RULE_STATUS_UNSET if a name was not set prior to this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_kernel_uprobe_get_event_name( - const struct lttng_event_rule *rule, const char **name); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_kernel_uprobe_get_event_name(const struct lttng_event_rule *rule, + const char **name); #ifdef __cplusplus } diff --git a/include/lttng/event-rule/log4j-logging-internal.hpp b/include/lttng/event-rule/log4j-logging-internal.hpp index a65e74b6d..239bf98ee 100644 --- a/include/lttng/event-rule/log4j-logging-internal.hpp +++ b/include/lttng/event-rule/log4j-logging-internal.hpp @@ -8,9 +8,10 @@ #ifndef LTTNG_EVENT_RULE_LOG4J_LOGGING_INTERNAL_H #define LTTNG_EVENT_RULE_LOG4J_LOGGING_INTERNAL_H -#include #include #include +#include + #include #include #include @@ -51,8 +52,7 @@ struct lttng_event_rule_log4j_logging_comm { char payload[]; } LTTNG_PACKED; -ssize_t lttng_event_rule_log4j_logging_create_from_payload( - struct lttng_payload_view *view, - struct lttng_event_rule **rule); +ssize_t lttng_event_rule_log4j_logging_create_from_payload(struct lttng_payload_view *view, + struct lttng_event_rule **rule); #endif /* LTTNG_EVENT_RULE_LOG4J_LOGGING_INTERNAL_H */ diff --git a/include/lttng/event-rule/log4j-logging.h b/include/lttng/event-rule/log4j-logging.h index 277e7d950..9128b4d69 100644 --- a/include/lttng/event-rule/log4j-logging.h +++ b/include/lttng/event-rule/log4j-logging.h @@ -9,9 +9,9 @@ #define LTTNG_EVENT_RULE_LOG4J_LOGGING_H #include +#include #include #include -#include #ifdef __cplusplus extern "C" { @@ -35,8 +35,8 @@ LTTNG_EXPORT extern struct lttng_event_rule *lttng_event_rule_log4j_logging_crea * Return LTTNG_EVENT_RULE_STATUS_OK on success, LTTNG_EVENT_RULE_STATUS_INVALID * if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_log4j_logging_set_name_pattern( - struct lttng_event_rule *rule, const char *pattern); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_log4j_logging_set_name_pattern(struct lttng_event_rule *rule, const char *pattern); /* * Get the name pattern of a log4j logging event rule. @@ -50,8 +50,9 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_log4j_logging_ * parameter is passed, or LTTNG_EVENT_RULE_STATUS_UNSET if a pattern * was not set prior to this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_log4j_logging_get_name_pattern( - const struct lttng_event_rule *rule, const char **pattern); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_log4j_logging_get_name_pattern(const struct lttng_event_rule *rule, + const char **pattern); /* * Set the filter expression of a log4j logging event rule. @@ -61,8 +62,8 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_log4j_logging_ * Return LTTNG_EVENT_RULE_STATUS_OK on success, LTTNG_EVENT_RULE_STATUS_INVALID * if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_log4j_logging_set_filter( - struct lttng_event_rule *rule, const char *expression); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_log4j_logging_set_filter(struct lttng_event_rule *rule, const char *expression); /* * Get the filter expression of a log4j logging event rule. @@ -76,8 +77,9 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_log4j_logging_ * parameter is passed, or LTTNG_EVENT_RULE_STATUS_UNSET if a filter expression * was not set prior to this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_log4j_logging_get_filter( - const struct lttng_event_rule *rule, const char **expression); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_log4j_logging_get_filter(const struct lttng_event_rule *rule, + const char **expression); /* * Set the log level rule of a log4j logging event rule. @@ -87,9 +89,8 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_log4j_logging_ * Return LTTNG_EVENT_RULE_STATUS_OK on success, LTTNG_EVENT_RULE_STATUS_INVALID * if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status -lttng_event_rule_log4j_logging_set_log_level_rule(struct lttng_event_rule *rule, - const struct lttng_log_level_rule *log_level_rule); +LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_log4j_logging_set_log_level_rule( + struct lttng_event_rule *rule, const struct lttng_log_level_rule *log_level_rule); /* * Get the log level rule of a log4j logging event rule. @@ -103,10 +104,8 @@ lttng_event_rule_log4j_logging_set_log_level_rule(struct lttng_event_rule *rule, * is passed, or LTTNG_EVENT_RULE_STATUS_UNSET if a log level rule was not set prior * to this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status -lttng_event_rule_log4j_logging_get_log_level_rule( - const struct lttng_event_rule *rule, - const struct lttng_log_level_rule **log_level_rule); +LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_log4j_logging_get_log_level_rule( + const struct lttng_event_rule *rule, const struct lttng_log_level_rule **log_level_rule); #ifdef __cplusplus } diff --git a/include/lttng/event-rule/python-logging-internal.hpp b/include/lttng/event-rule/python-logging-internal.hpp index d23f4e2a5..f7513f420 100644 --- a/include/lttng/event-rule/python-logging-internal.hpp +++ b/include/lttng/event-rule/python-logging-internal.hpp @@ -8,9 +8,10 @@ #ifndef LTTNG_EVENT_RULE_PYTHON_LOGGING_INTERNAL_H #define LTTNG_EVENT_RULE_PYTHON_LOGGING_INTERNAL_H -#include #include #include +#include + #include #include #include @@ -51,8 +52,7 @@ struct lttng_event_rule_python_logging_comm { char payload[]; } LTTNG_PACKED; -ssize_t lttng_event_rule_python_logging_create_from_payload( - struct lttng_payload_view *view, - struct lttng_event_rule **rule); +ssize_t lttng_event_rule_python_logging_create_from_payload(struct lttng_payload_view *view, + struct lttng_event_rule **rule); #endif /* LTTNG_EVENT_RULE_PYTHON_LOGGING_INTERNAL_H */ diff --git a/include/lttng/event-rule/python-logging.h b/include/lttng/event-rule/python-logging.h index d4a6ada47..d77be2e50 100644 --- a/include/lttng/event-rule/python-logging.h +++ b/include/lttng/event-rule/python-logging.h @@ -9,9 +9,9 @@ #define LTTNG_EVENT_RULE_PYTHON_LOGGING_H #include +#include #include #include -#include #ifdef __cplusplus extern "C" { @@ -35,8 +35,9 @@ LTTNG_EXPORT extern struct lttng_event_rule *lttng_event_rule_python_logging_cre * Return LTTNG_EVENT_RULE_STATUS_OK on success, LTTNG_EVENT_RULE_STATUS_INVALID * if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_python_logging_set_name_pattern( - struct lttng_event_rule *rule, const char *pattern); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_python_logging_set_name_pattern(struct lttng_event_rule *rule, + const char *pattern); /* * Get the name pattern of a python logging event rule. @@ -50,8 +51,9 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_python_logging * parameter is passed, or LTTNG_EVENT_RULE_STATUS_UNSET if a pattern * was not set prior to this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_python_logging_get_name_pattern( - const struct lttng_event_rule *rule, const char **pattern); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_python_logging_get_name_pattern(const struct lttng_event_rule *rule, + const char **pattern); /* * Set the filter expression of a python logging event rule. @@ -61,8 +63,8 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_python_logging * Return LTTNG_EVENT_RULE_STATUS_OK on success, LTTNG_EVENT_RULE_STATUS_INVALID * if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_python_logging_set_filter( - struct lttng_event_rule *rule, const char *expression); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_python_logging_set_filter(struct lttng_event_rule *rule, const char *expression); /* * Get the filter expression of a python logging event rule. @@ -76,8 +78,9 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_python_logging * parameter is passed, or LTTNG_EVENT_RULE_STATUS_UNSET if a filter expression * was not set prior to this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_python_logging_get_filter( - const struct lttng_event_rule *rule, const char **expression); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_python_logging_get_filter(const struct lttng_event_rule *rule, + const char **expression); /* * Set the log level rule of a python logging event rule. @@ -87,9 +90,8 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_python_logging * Return LTTNG_EVENT_RULE_STATUS_OK on success, LTTNG_EVENT_RULE_STATUS_INVALID * if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status -lttng_event_rule_python_logging_set_log_level_rule(struct lttng_event_rule *rule, - const struct lttng_log_level_rule *log_level_rule); +LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_python_logging_set_log_level_rule( + struct lttng_event_rule *rule, const struct lttng_log_level_rule *log_level_rule); /* * Get the log level rule of a python logging event rule. @@ -103,10 +105,8 @@ lttng_event_rule_python_logging_set_log_level_rule(struct lttng_event_rule *rule * is passed, or LTTNG_EVENT_RULE_STATUS_UNSET if a log level rule was not set prior * to this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status -lttng_event_rule_python_logging_get_log_level_rule( - const struct lttng_event_rule *rule, - const struct lttng_log_level_rule **log_level_rule); +LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_python_logging_get_log_level_rule( + const struct lttng_event_rule *rule, const struct lttng_log_level_rule **log_level_rule); #ifdef __cplusplus } diff --git a/include/lttng/event-rule/user-tracepoint-internal.hpp b/include/lttng/event-rule/user-tracepoint-internal.hpp index 1960a8a4d..65199bbbc 100644 --- a/include/lttng/event-rule/user-tracepoint-internal.hpp +++ b/include/lttng/event-rule/user-tracepoint-internal.hpp @@ -8,9 +8,10 @@ #ifndef LTTNG_EVENT_RULE_USER_TRACEPOINT_INTERNAL_H #define LTTNG_EVENT_RULE_USER_TRACEPOINT_INTERNAL_H -#include #include #include +#include + #include #include #include @@ -58,8 +59,7 @@ struct lttng_event_rule_user_tracepoint_comm { char payload[]; } LTTNG_PACKED; -ssize_t lttng_event_rule_user_tracepoint_create_from_payload( - struct lttng_payload_view *view, - struct lttng_event_rule **rule); +ssize_t lttng_event_rule_user_tracepoint_create_from_payload(struct lttng_payload_view *view, + struct lttng_event_rule **rule); #endif /* LTTNG_EVENT_RULE_USER_TRACEPOINT_INTERNAL_H */ diff --git a/include/lttng/event-rule/user-tracepoint.h b/include/lttng/event-rule/user-tracepoint.h index 7ee91ce79..8f227b778 100644 --- a/include/lttng/event-rule/user-tracepoint.h +++ b/include/lttng/event-rule/user-tracepoint.h @@ -10,9 +10,9 @@ #include #include +#include #include #include -#include #ifdef __cplusplus extern "C" { @@ -36,8 +36,9 @@ LTTNG_EXPORT extern struct lttng_event_rule *lttng_event_rule_user_tracepoint_cr * Return LTTNG_EVENT_RULE_STATUS_OK on success, LTTNG_EVENT_RULE_STATUS_INVALID * if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_user_tracepoint_set_name_pattern( - struct lttng_event_rule *rule, const char *pattern); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_user_tracepoint_set_name_pattern(struct lttng_event_rule *rule, + const char *pattern); /* * Get the name pattern of a user tracepoint event rule. @@ -51,8 +52,9 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_user_tracepoin * parameter is passed, or LTTNG_EVENT_RULE_STATUS_UNSET if a pattern * was not set prior to this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_user_tracepoint_get_name_pattern( - const struct lttng_event_rule *rule, const char **pattern); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_user_tracepoint_get_name_pattern(const struct lttng_event_rule *rule, + const char **pattern); /* * Set the filter expression of a user tracepoint event rule. @@ -62,8 +64,8 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_user_tracepoin * Return LTTNG_EVENT_RULE_STATUS_OK on success, LTTNG_EVENT_RULE_STATUS_INVALID * if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_user_tracepoint_set_filter( - struct lttng_event_rule *rule, const char *expression); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_user_tracepoint_set_filter(struct lttng_event_rule *rule, const char *expression); /* * Get the filter expression of a user tracepoint event rule. @@ -77,8 +79,9 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_user_tracepoin * parameter is passed, or LTTNG_EVENT_RULE_STATUS_UNSET if a filter expression * was not set prior to this call. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_user_tracepoint_get_filter( - const struct lttng_event_rule *rule, const char **expression); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_user_tracepoint_get_filter(const struct lttng_event_rule *rule, + const char **expression); /* * Set the log level rule of a user tracepoint event rule. @@ -89,8 +92,8 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_user_tracepoin * if invalid parameters are passed. */ LTTNG_EXPORT extern enum lttng_event_rule_status -lttng_event_rule_user_tracepoint_set_log_level_rule(struct lttng_event_rule *rule, - const struct lttng_log_level_rule *log_level_rule); +lttng_event_rule_user_tracepoint_set_log_level_rule( + struct lttng_event_rule *rule, const struct lttng_log_level_rule *log_level_rule); /* * Get the log level rule of a user tracepoint event rule. @@ -106,8 +109,7 @@ lttng_event_rule_user_tracepoint_set_log_level_rule(struct lttng_event_rule *rul */ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_user_tracepoint_get_log_level_rule( - const struct lttng_event_rule *rule, - const struct lttng_log_level_rule **log_level_rule); + const struct lttng_event_rule *rule, const struct lttng_log_level_rule **log_level_rule); /* * Add a name pattern exclusion to the set of name pattern exclusion of an event rule. @@ -117,9 +119,9 @@ lttng_event_rule_user_tracepoint_get_log_level_rule( * Returns LTTNG_EVENT_RULE_STATUS_OK on success, * LTTNG_EVENT_RULE_STATUS_INVALID if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_user_tracepoint_add_name_pattern_exclusion( - struct lttng_event_rule *rule, - const char *exclusion); +LTTNG_EXPORT extern enum lttng_event_rule_status +lttng_event_rule_user_tracepoint_add_name_pattern_exclusion(struct lttng_event_rule *rule, + const char *exclusion); /* * Get the name pattern exclusions property count of an event rule. @@ -130,7 +132,7 @@ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_user_tracepoin */ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_user_tracepoint_get_name_pattern_exclusion_count( - const struct lttng_event_rule *rule, unsigned int *count); + const struct lttng_event_rule *rule, unsigned int *count); /* * Get the pattern name exclusion at the given index. @@ -141,9 +143,7 @@ lttng_event_rule_user_tracepoint_get_name_pattern_exclusion_count( */ LTTNG_EXPORT extern enum lttng_event_rule_status lttng_event_rule_user_tracepoint_get_name_pattern_exclusion_at_index( - const struct lttng_event_rule *rule, - unsigned int index, - const char **exclusion); + const struct lttng_event_rule *rule, unsigned int index, const char **exclusion); #ifdef __cplusplus } diff --git a/include/lttng/event.h b/include/lttng/event.h index 5915db6d6..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 { - LTTNG_EVENT_ALL = -1, - LTTNG_EVENT_TRACEPOINT = 0, - LTTNG_EVENT_PROBE = 1, - LTTNG_EVENT_FUNCTION = 2, - LTTNG_EVENT_FUNCTION_ENTRY = 3, - LTTNG_EVENT_NOOP = 4, - LTTNG_EVENT_SYSCALL = 5, - LTTNG_EVENT_USERSPACE_PROBE = 6, + /// 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 { - LTTNG_EVENT_LOGLEVEL_ALL = 0, - LTTNG_EVENT_LOGLEVEL_RANGE = 1, - LTTNG_EVENT_LOGLEVEL_SINGLE = 2, + /// 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 { - LTTNG_LOGLEVEL_EMERG = 0, - LTTNG_LOGLEVEL_ALERT = 1, - LTTNG_LOGLEVEL_CRIT = 2, - LTTNG_LOGLEVEL_ERR = 3, - LTTNG_LOGLEVEL_WARNING = 4, - LTTNG_LOGLEVEL_NOTICE = 5, - LTTNG_LOGLEVEL_INFO = 6, - LTTNG_LOGLEVEL_DEBUG_SYSTEM = 7, - LTTNG_LOGLEVEL_DEBUG_PROGRAM = 8, - LTTNG_LOGLEVEL_DEBUG_PROCESS = 9, - LTTNG_LOGLEVEL_DEBUG_MODULE = 10, - LTTNG_LOGLEVEL_DEBUG_UNIT = 11, - LTTNG_LOGLEVEL_DEBUG_FUNCTION = 12, - LTTNG_LOGLEVEL_DEBUG_LINE = 13, - LTTNG_LOGLEVEL_DEBUG = 14, + /// 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 { - LTTNG_LOGLEVEL_JUL_OFF = INT32_MAX, - LTTNG_LOGLEVEL_JUL_SEVERE = 1000, - LTTNG_LOGLEVEL_JUL_WARNING = 900, - LTTNG_LOGLEVEL_JUL_INFO = 800, - LTTNG_LOGLEVEL_JUL_CONFIG = 700, - LTTNG_LOGLEVEL_JUL_FINE = 500, - LTTNG_LOGLEVEL_JUL_FINER = 400, - LTTNG_LOGLEVEL_JUL_FINEST = 300, - LTTNG_LOGLEVEL_JUL_ALL = INT32_MIN, + /// 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 { - LTTNG_LOGLEVEL_LOG4J_OFF = INT32_MAX, - LTTNG_LOGLEVEL_LOG4J_FATAL = 50000, - LTTNG_LOGLEVEL_LOG4J_ERROR = 40000, - LTTNG_LOGLEVEL_LOG4J_WARN = 30000, - LTTNG_LOGLEVEL_LOG4J_INFO = 20000, - LTTNG_LOGLEVEL_LOG4J_DEBUG = 10000, - LTTNG_LOGLEVEL_LOG4J_TRACE = 5000, - LTTNG_LOGLEVEL_LOG4J_ALL = INT32_MIN, + /// 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 { - LTTNG_LOGLEVEL_PYTHON_CRITICAL = 50, - LTTNG_LOGLEVEL_PYTHON_ERROR = 40, - LTTNG_LOGLEVEL_PYTHON_WARNING = 30, - LTTNG_LOGLEVEL_PYTHON_INFO = 20, - LTTNG_LOGLEVEL_PYTHON_DEBUG = 10, - LTTNG_LOGLEVEL_PYTHON_NOTSET = 0, + /// 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 { - LTTNG_EVENT_SPLICE = 0, - LTTNG_EVENT_MMAP = 1, + /// 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 { - LTTNG_EVENT_CONTEXT_PID = 0, - LTTNG_EVENT_CONTEXT_PERF_COUNTER = 1, /* Backward compat. */ - LTTNG_EVENT_CONTEXT_PROCNAME = 2, - LTTNG_EVENT_CONTEXT_PRIO = 3, - LTTNG_EVENT_CONTEXT_NICE = 4, - LTTNG_EVENT_CONTEXT_VPID = 5, - LTTNG_EVENT_CONTEXT_TID = 6, - LTTNG_EVENT_CONTEXT_VTID = 7, - LTTNG_EVENT_CONTEXT_PPID = 8, - LTTNG_EVENT_CONTEXT_VPPID = 9, - LTTNG_EVENT_CONTEXT_PTHREAD_ID = 10, - LTTNG_EVENT_CONTEXT_HOSTNAME = 11, - LTTNG_EVENT_CONTEXT_IP = 12, - LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER = 13, + /// 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, - LTTNG_EVENT_CONTEXT_APP_CONTEXT = 15, - LTTNG_EVENT_CONTEXT_INTERRUPTIBLE = 16, - LTTNG_EVENT_CONTEXT_PREEMPTIBLE = 17, - LTTNG_EVENT_CONTEXT_NEED_RESCHEDULE = 18, - LTTNG_EVENT_CONTEXT_MIGRATABLE = 19, - LTTNG_EVENT_CONTEXT_CALLSTACK_KERNEL = 20, - LTTNG_EVENT_CONTEXT_CALLSTACK_USER = 21, /* Supported on x86_32 and x86_64 only. */ - LTTNG_EVENT_CONTEXT_CGROUP_NS = 22, - LTTNG_EVENT_CONTEXT_IPC_NS = 23, - LTTNG_EVENT_CONTEXT_MNT_NS = 24, - LTTNG_EVENT_CONTEXT_NET_NS = 25, - LTTNG_EVENT_CONTEXT_PID_NS = 26, - LTTNG_EVENT_CONTEXT_USER_NS = 27, - LTTNG_EVENT_CONTEXT_UTS_NS = 28, - LTTNG_EVENT_CONTEXT_UID = 29, - LTTNG_EVENT_CONTEXT_EUID = 30, - LTTNG_EVENT_CONTEXT_SUID = 31, - LTTNG_EVENT_CONTEXT_GID = 32, - LTTNG_EVENT_CONTEXT_EGID = 33, - LTTNG_EVENT_CONTEXT_SGID = 34, - LTTNG_EVENT_CONTEXT_VUID = 35, - LTTNG_EVENT_CONTEXT_VEUID = 36, - LTTNG_EVENT_CONTEXT_VSUID = 37, - LTTNG_EVENT_CONTEXT_VGID = 38, - LTTNG_EVENT_CONTEXT_VEGID = 39, - LTTNG_EVENT_CONTEXT_VSGID = 40, - LTTNG_EVENT_CONTEXT_TIME_NS = 41, + + /// 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, + + /// 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 { - LTTNG_EVENT_FIELD_OTHER = 0, - LTTNG_EVENT_FIELD_INTEGER = 1, - LTTNG_EVENT_FIELD_ENUM = 2, - LTTNG_EVENT_FIELD_FLOAT = 3, - LTTNG_EVENT_FIELD_STRING = 4, + /// 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 { - LTTNG_EVENT_FLAG_SYSCALL_32 = (1U << 0), - LTTNG_EVENT_FLAG_SYSCALL_64 = (1U << 1), + /*! + @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 +#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 +#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 +#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]; @@ -229,7 +1142,7 @@ struct lttng_event_probe_attr { * * The structures should be initialized to zero before use. */ -#define LTTNG_EVENT_FUNCTION_PADDING1 16 +#define LTTNG_EVENT_FUNCTION_PADDING1 16 struct lttng_event_function_attr { char symbol_name[LTTNG_SYMBOL_NAME_LEN]; @@ -241,38 +1154,202 @@ struct lttng_event_function_attr { * * The structures should be initialized to zero before use. */ -#define LTTNG_EVENT_PADDING1 12 -#define LTTNG_EVENT_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32 +#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 */ - int32_t enabled; /* Does not apply: -1 */ + /*! + @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,241 +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 +#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); + const char *channel_name, + 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, - size_t index, const char **exclusion_name); +@param[in] event_rule + @parblock + Recording event rule descriptor to destroy. -/* - * 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. - */ + 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 **event_name_exclusion); + +/*! +@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. - */ -LTTNG_EXPORT extern int lttng_event_set_userspace_probe_location(struct lttng_event *event, - struct lttng_userspace_probe_location *probe_location); +/*! +@brief + Sets the Linux uprobe location of the recording event rule described + by \lt_p{event_rule} to \lt_p{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. - */ +@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_rule, + struct lttng_userspace_probe_location *location); + +/*! +@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); + 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, const char *event_name, - const char *channel_name); + 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. - */ +/*! +@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. + +@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 *ev, const char *channel_name); + struct lttng_event *event_rule, + const char *channel_name); -/* - * 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. - */ +/*! +@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, const char *channel_name, - const char *filter_expression); + struct lttng_event *event_rule, + const char *channel_name, + 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, const char *channel_name, - const char *filter_expression, - int exclusion_count, char **exclusion_names); + struct lttng_event *event_rule, + const char *channel_name, + 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. - */ -LTTNG_EXPORT extern int lttng_disable_event(struct lttng_handle *handle, - const char *name, const char *channel_name); +/*! +@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. -/* - * 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. - */ +@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 *event_name, const char *channel_name); + +/*! +@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, const char *channel_name, - const char *filter_expression); + struct lttng_event *event_rule, + const char *channel_name, + const char *filter_expr); #ifdef __cplusplus } diff --git a/include/lttng/handle.h b/include/lttng/handle.h index efc889f1d..08f9eaad9 100644 --- a/include/lttng/handle.h +++ b/include/lttng/handle.h @@ -15,42 +15,99 @@ 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 +#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); + 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 } diff --git a/include/lttng/health-internal.hpp b/include/lttng/health-internal.hpp index 67bdc6a5e..eee164cb1 100644 --- a/include/lttng/health-internal.hpp +++ b/include/lttng/health-internal.hpp @@ -10,26 +10,28 @@ */ #include +#include + +#include + #include +#include #include #include -#include -#include -#include /* * These are the value added to the current state depending of the position in * the thread where is either waiting on a poll() or running in the code. */ -#define HEALTH_POLL_VALUE (1UL << 0) -#define HEALTH_CODE_VALUE (1UL << 1) +#define HEALTH_POLL_VALUE (1UL << 0) +#define HEALTH_CODE_VALUE (1UL << 1) -#define HEALTH_IS_IN_POLL(x) ((x) & HEALTH_POLL_VALUE) +#define HEALTH_IS_IN_POLL(x) ((x) &HEALTH_POLL_VALUE) struct health_app; enum health_flags { - HEALTH_ERROR = (1U << 0), + HEALTH_ERROR = (1U << 0), }; struct health_state { @@ -43,40 +45,39 @@ struct health_state { /* * current and flags are updated by multiple threads concurrently. */ - unsigned long current; /* progress counter, updated atomically */ - enum health_flags flags; /* other flags, updated atomically */ - int type; /* Indicates the nature of the thread. */ + unsigned long current; /* progress counter, updated atomically */ + enum health_flags flags; /* other flags, updated atomically */ + int type; /* Indicates the nature of the thread. */ /* Node of the global TLS state list. */ struct cds_list_head node; }; enum health_cmd { - HEALTH_CMD_CHECK = 0, + HEALTH_CMD_CHECK = 0, }; struct health_comm_msg { - uint32_t cmd; /* enum health_cmd */ + uint32_t cmd; /* enum health_cmd */ } LTTNG_PACKED; struct health_comm_reply { - uint64_t ret_code; /* bitmask of threads in bad health */ + uint64_t ret_code; /* bitmask of threads in bad health */ } LTTNG_PACKED; /* Declare TLS health state. */ -extern DECLARE_URCU_TLS(struct health_state, health_state); +extern thread_local struct health_state health_state; /* * Update current counter by 1 to indicate that the thread entered or left a * blocking state caused by a poll(). If the counter's value is not an even * number (meaning a code execution flow), an LTTNG_ASSERT() is raised. */ -static inline void health_poll_entry(void) +static inline void health_poll_entry() { /* Code MUST be in code execution state which is an even number. */ - LTTNG_ASSERT(!(uatomic_read(&URCU_TLS(health_state).current) - & HEALTH_POLL_VALUE)); + LTTNG_ASSERT(!(uatomic_read(&health_state.current) & HEALTH_POLL_VALUE)); - uatomic_add(&URCU_TLS(health_state).current, HEALTH_POLL_VALUE); + uatomic_add(&health_state.current, HEALTH_POLL_VALUE); } /* @@ -84,30 +85,29 @@ static inline void health_poll_entry(void) * If the counter's value is not an odd number (a poll execution), an LTTNG_ASSERT() * is raised. */ -static inline void health_poll_exit(void) +static inline void health_poll_exit() { /* Code MUST be in poll execution state which is an odd number. */ - LTTNG_ASSERT(uatomic_read(&URCU_TLS(health_state).current) - & HEALTH_POLL_VALUE); + LTTNG_ASSERT(uatomic_read(&health_state.current) & HEALTH_POLL_VALUE); - uatomic_add(&URCU_TLS(health_state).current, HEALTH_POLL_VALUE); + uatomic_add(&health_state.current, HEALTH_POLL_VALUE); } /* * Update current counter by 2 indicates progress in execution of a * thread. */ -static inline void health_code_update(void) +static inline void health_code_update() { - uatomic_add(&URCU_TLS(health_state).current, HEALTH_CODE_VALUE); + uatomic_add(&health_state.current, HEALTH_CODE_VALUE); } /* * Set health "error" flag. */ -static inline void health_error(void) +static inline void health_error() { - uatomic_or(&URCU_TLS(health_state).flags, HEALTH_ERROR); + uatomic_or(&health_state.flags, HEALTH_ERROR); } struct health_app *health_app_create(int nr_types); diff --git a/include/lttng/health.h b/include/lttng/health.h index 26e885705..4e82c7be1 100644 --- a/include/lttng/health.h +++ b/include/lttng/health.h @@ -40,7 +40,7 @@ LTTNG_EXPORT extern struct lttng_health *lttng_health_create_sessiond(void); * Return a newly allocated health object, or NULL on error. */ LTTNG_EXPORT extern struct lttng_health * - lttng_health_create_consumerd(enum lttng_health_consumerd consumerd); +lttng_health_create_consumerd(enum lttng_health_consumerd consumerd); /** * lttng_health_create_relayd - Create relayd health object @@ -101,8 +101,7 @@ LTTNG_EXPORT extern int lttng_health_get_nr_threads(const struct lttng_health *h * lttng_health_destroy() is called on @health. */ LTTNG_EXPORT extern const struct lttng_health_thread * - lttng_health_get_thread(const struct lttng_health *health, - unsigned int nth_thread); +lttng_health_get_thread(const struct lttng_health *health, unsigned int nth_thread); /** * lttng_health_thread_state - Get thread health state diff --git a/include/lttng/kernel-probe-internal.hpp b/include/lttng/kernel-probe-internal.hpp index 07c546f9d..bdafb4d0a 100644 --- a/include/lttng/kernel-probe-internal.hpp +++ b/include/lttng/kernel-probe-internal.hpp @@ -10,9 +10,10 @@ #include #include -#include + #include #include + #include #include #include @@ -22,23 +23,17 @@ struct lttng_payload_view; struct lttng_dynamic_buffer; struct mi_writer; -typedef bool (*kernel_probe_location_equal_cb)( - const struct lttng_kernel_probe_location *a, - const struct lttng_kernel_probe_location *b); -typedef int (*kernel_probe_location_serialize_cb)( - const struct lttng_kernel_probe_location *kernel_probe_location, - struct lttng_payload *payload); -typedef bool (*kernel_probe_location_equal_cb)( - const struct lttng_kernel_probe_location *a, - const struct lttng_kernel_probe_location *b); -typedef ssize_t (*kernel_probe_location_create_from_payload_cb)( - struct lttng_payload_view *view, - struct lttng_kernel_probe_location **kernel_probe_location); -typedef unsigned long (*kernel_probe_location_hash_cb)( - const struct lttng_kernel_probe_location *location); -typedef enum lttng_error_code (*kernel_probe_location_mi_serialize_cb)( - const struct lttng_kernel_probe_location *location, - struct mi_writer *writer); +using kernel_probe_location_equal_cb = bool (*)(const struct lttng_kernel_probe_location *, + const struct lttng_kernel_probe_location *); +using kernel_probe_location_serialize_cb = int (*)(const struct lttng_kernel_probe_location *, + struct lttng_payload *); +using kernel_probe_location_equal_cb = bool (*)(const struct lttng_kernel_probe_location *, + const struct lttng_kernel_probe_location *); +using kernel_probe_location_create_from_payload_cb = + ssize_t (*)(struct lttng_payload_view *, struct lttng_kernel_probe_location **); +using kernel_probe_location_hash_cb = unsigned long (*)(const struct lttng_kernel_probe_location *); +using kernel_probe_location_mi_serialize_cb = + enum lttng_error_code (*)(const struct lttng_kernel_probe_location *, struct mi_writer *); struct lttng_kernel_probe_location_comm { /* enum lttng_kernel_probe_location_type */ @@ -86,26 +81,22 @@ struct lttng_kernel_probe_location_address { uint64_t address; }; -int lttng_kernel_probe_location_serialize( - const struct lttng_kernel_probe_location *location, - struct lttng_payload *payload); +int lttng_kernel_probe_location_serialize(const struct lttng_kernel_probe_location *location, + struct lttng_payload *payload); ssize_t lttng_kernel_probe_location_create_from_payload( - struct lttng_payload_view *view, - struct lttng_kernel_probe_location **probe_location); + struct lttng_payload_view *view, struct lttng_kernel_probe_location **probe_location); -bool lttng_kernel_probe_location_is_equal( - const struct lttng_kernel_probe_location *a, - const struct lttng_kernel_probe_location *b); +bool lttng_kernel_probe_location_is_equal(const struct lttng_kernel_probe_location *a, + const struct lttng_kernel_probe_location *b); -struct lttng_kernel_probe_location *lttng_kernel_probe_location_copy( - const struct lttng_kernel_probe_location *location); +struct lttng_kernel_probe_location * +lttng_kernel_probe_location_copy(const struct lttng_kernel_probe_location *location); -unsigned long lttng_kernel_probe_location_hash( - const struct lttng_kernel_probe_location *location); +unsigned long lttng_kernel_probe_location_hash(const struct lttng_kernel_probe_location *location); -enum lttng_error_code lttng_kernel_probe_location_mi_serialize( - const struct lttng_kernel_probe_location *location, - struct mi_writer *writer); +enum lttng_error_code +lttng_kernel_probe_location_mi_serialize(const struct lttng_kernel_probe_location *location, + struct mi_writer *writer); #endif /* LTTNG_KERNEL_PROBE_INTERNAL_H */ diff --git a/include/lttng/kernel-probe.h b/include/lttng/kernel-probe.h index cdd617dea..8e894fae8 100644 --- a/include/lttng/kernel-probe.h +++ b/include/lttng/kernel-probe.h @@ -9,6 +9,7 @@ #define LTTNG_KERNEL_PROBE_H #include + #include #ifdef __cplusplus @@ -18,53 +19,50 @@ extern "C" { struct lttng_kernel_probe_location; enum lttng_kernel_probe_location_status { - LTTNG_KERNEL_PROBE_LOCATION_STATUS_OK = 0, + LTTNG_KERNEL_PROBE_LOCATION_STATUS_OK = 0, /* Invalid parameters provided. */ - LTTNG_KERNEL_PROBE_LOCATION_STATUS_INVALID = -1, + LTTNG_KERNEL_PROBE_LOCATION_STATUS_INVALID = -1, }; enum lttng_kernel_probe_location_type { - LTTNG_KERNEL_PROBE_LOCATION_TYPE_UNKNOWN = -1, + LTTNG_KERNEL_PROBE_LOCATION_TYPE_UNKNOWN = -1, /* Location derived from a symbol and an offset. */ - LTTNG_KERNEL_PROBE_LOCATION_TYPE_SYMBOL_OFFSET = 0, + LTTNG_KERNEL_PROBE_LOCATION_TYPE_SYMBOL_OFFSET = 0, /* Location derived from an address. */ - LTTNG_KERNEL_PROBE_LOCATION_TYPE_ADDRESS = 1, + LTTNG_KERNEL_PROBE_LOCATION_TYPE_ADDRESS = 1, }; /* * Get the type of the kernel probe location. */ LTTNG_EXPORT extern enum lttng_kernel_probe_location_type -lttng_kernel_probe_location_get_type( - const struct lttng_kernel_probe_location *location); +lttng_kernel_probe_location_get_type(const struct lttng_kernel_probe_location *location); /* * Destroy the kernel probe location. */ -LTTNG_EXPORT extern void lttng_kernel_probe_location_destroy( - struct lttng_kernel_probe_location *location); +LTTNG_EXPORT extern void +lttng_kernel_probe_location_destroy(struct lttng_kernel_probe_location *location); /* * Create a symbol derived probe location. * On failure, NULL is returned. */ LTTNG_EXPORT extern struct lttng_kernel_probe_location * -lttng_kernel_probe_location_symbol_create(const char *symbol_name, - uint64_t offset); +lttng_kernel_probe_location_symbol_create(const char *symbol_name, uint64_t offset); /* * Get the symbol name of a symbol derived probe location. */ -LTTNG_EXPORT extern const char *lttng_kernel_probe_location_symbol_get_name( - const struct lttng_kernel_probe_location *location); +LTTNG_EXPORT extern const char * +lttng_kernel_probe_location_symbol_get_name(const struct lttng_kernel_probe_location *location); /* * Get the offset of a symbol derived location. */ LTTNG_EXPORT extern enum lttng_kernel_probe_location_status -lttng_kernel_probe_location_symbol_get_offset( - const struct lttng_kernel_probe_location *location, - uint64_t *offset); +lttng_kernel_probe_location_symbol_get_offset(const struct lttng_kernel_probe_location *location, + uint64_t *offset); /* * Create an address derived probe location. @@ -77,9 +75,8 @@ lttng_kernel_probe_location_address_create(uint64_t address); * Get the address of an address derived probe location. */ LTTNG_EXPORT extern enum lttng_kernel_probe_location_status -lttng_kernel_probe_location_address_get_address( - const struct lttng_kernel_probe_location *location, - uint64_t *offset); +lttng_kernel_probe_location_address_get_address(const struct lttng_kernel_probe_location *location, + uint64_t *offset); #ifdef __cplusplus } diff --git a/include/lttng/kernel.h b/include/lttng/kernel.h new file mode 100644 index 000000000..d3a9f05b5 --- /dev/null +++ b/include/lttng/kernel.h @@ -0,0 +1,44 @@ +/* + * kernel.h + * + * Linux Trace Toolkit Control Library Header File + * + * Copyright (C) 2023 Kienan Stewart + * + * SPDX-License-Identifier; LGPL-2.1-only + * + */ + +#ifndef LTTNG_KERNEL_H +#define LTTNG_KERNEL_H + +#ifdef __cplusplus +extern "C" { +#endif + +enum lttng_kernel_tracer_status { + /* Loaded without error. */ + LTTNG_KERNEL_TRACER_STATUS_INITIALIZED = 0, + /* Unknown error. */ + LTTNG_KERNEL_TRACER_STATUS_ERR_UNKNOWN = -1, + /* lttng-sessiond isn't running as root. */ + LTTNG_KERNEL_TRACER_STATUS_ERR_NEED_ROOT = -2, + /* Notifier setup failed. */ + LTTNG_KERNEL_TRACER_STATUS_ERR_NOTIFIER = -3, + /* Failed to open /proc/lttng. */ + LTTNG_KERNEL_TRACER_STATUS_ERR_OPEN_PROC_LTTNG = -4, + /* Version mismatch between kernel tracer and kernel tracer ABI. */ + LTTNG_KERNEL_TRACER_STATUS_ERR_VERSION_MISMATCH = -5, + /* Kernel module loading failed. */ + LTTNG_KERNEL_TRACER_STATUS_ERR_MODULES_UNKNOWN = -6, + /* Kernel modules missing. */ + LTTNG_KERNEL_TRACER_STATUS_ERR_MODULES_MISSING = -7, + /* Kernel module signature error. */ + LTTNG_KERNEL_TRACER_STATUS_ERR_MODULES_SIGNATURE = -8, +}; + +#ifdef __cplusplus +} +#endif + +#endif /* LTTNG_KERNEL_H */ diff --git a/include/lttng/load-internal.hpp b/include/lttng/load-internal.hpp index ef09ffd9c..78f38e47e 100644 --- a/include/lttng/load-internal.hpp +++ b/include/lttng/load-internal.hpp @@ -9,12 +9,13 @@ #ifndef LTTNG_LOAD_INTERNAL_ABI_H #define LTTNG_LOAD_INTERNAL_ABI_H -#include -#include +#include +#include #include -#include -#include + +#include +#include /* * Object used by the load_session API. This is opaque to the public library. diff --git a/include/lttng/load.h b/include/lttng/load.h index 0395bb414..5f7b4ec44 100644 --- a/include/lttng/load.h +++ b/include/lttng/load.h @@ -31,21 +31,20 @@ LTTNG_EXPORT extern struct lttng_load_session_attr *lttng_load_session_attr_crea */ LTTNG_EXPORT extern void lttng_load_session_attr_destroy(struct lttng_load_session_attr *attr); - /* * Load session attribute getter family of functions. */ /* Return session name. NULL indicates all sessions must be loaded. */ -LTTNG_EXPORT extern const char *lttng_load_session_attr_get_session_name( - struct lttng_load_session_attr *attr); +LTTNG_EXPORT extern const char * +lttng_load_session_attr_get_session_name(struct lttng_load_session_attr *attr); /* * Return input URL. A NULL value indicates the default session * configuration location. The URL format used is documented in lttng-create(1). * NULL indicates that the default session configuration path is used. */ -LTTNG_EXPORT extern const char *lttng_load_session_attr_get_input_url( - struct lttng_load_session_attr *attr); +LTTNG_EXPORT extern const char * +lttng_load_session_attr_get_input_url(struct lttng_load_session_attr *attr); /* * Return the configuration overwrite attribute. This attribute indicates @@ -53,8 +52,7 @@ LTTNG_EXPORT extern const char *lttng_load_session_attr_get_input_url( * same name already exists. If such a session exists, it is destroyed before * the replacement is loaded. */ -LTTNG_EXPORT extern int lttng_load_session_attr_get_overwrite( - struct lttng_load_session_attr *attr); +LTTNG_EXPORT extern int lttng_load_session_attr_get_overwrite(struct lttng_load_session_attr *attr); /* * Return the destination URL configuration override attribute. This attribute @@ -63,8 +61,8 @@ LTTNG_EXPORT extern int lttng_load_session_attr_get_overwrite( * * NULL indicates no override will be applied on configuration load. */ -LTTNG_EXPORT extern const char *lttng_load_session_attr_get_override_url( - struct lttng_load_session_attr *attr); +LTTNG_EXPORT extern const char * +lttng_load_session_attr_get_override_url(struct lttng_load_session_attr *attr); /* * Return the configuration override control URL attribute. This attribute @@ -73,8 +71,8 @@ LTTNG_EXPORT extern const char *lttng_load_session_attr_get_override_url( * * NULL indicates no control URL override will be applied on configuration load. */ -LTTNG_EXPORT extern const char *lttng_load_session_attr_get_override_ctrl_url( - struct lttng_load_session_attr *attr); +LTTNG_EXPORT extern const char * +lttng_load_session_attr_get_override_ctrl_url(struct lttng_load_session_attr *attr); /* * Return the configuration override data URL attribute. This attribute @@ -83,8 +81,8 @@ LTTNG_EXPORT extern const char *lttng_load_session_attr_get_override_ctrl_url( * * NULL indicates no data URL override will be applied on configuration load. */ -LTTNG_EXPORT extern const char *lttng_load_session_attr_get_override_data_url( - struct lttng_load_session_attr *attr); +LTTNG_EXPORT extern const char * +lttng_load_session_attr_get_override_data_url(struct lttng_load_session_attr *attr); /* * Return the configuration override session name attribute. @@ -94,8 +92,8 @@ LTTNG_EXPORT extern const char *lttng_load_session_attr_get_override_data_url( * NULL indicates no session name override will be applied on configuration * load. */ -LTTNG_EXPORT extern const char *lttng_load_session_attr_get_override_session_name( - struct lttng_load_session_attr *attr); +LTTNG_EXPORT extern const char * +lttng_load_session_attr_get_override_session_name(struct lttng_load_session_attr *attr); /* * Load session attribute setter family of functions. @@ -108,8 +106,9 @@ LTTNG_EXPORT extern const char *lttng_load_session_attr_get_override_session_nam * Set the name of the session to load. A NULL name means all sessions * found at the input URL will be loaded. */ -LTTNG_EXPORT extern int lttng_load_session_attr_set_session_name( - struct lttng_load_session_attr *attr, const char *session_name); +LTTNG_EXPORT extern int +lttng_load_session_attr_set_session_name(struct lttng_load_session_attr *attr, + const char *session_name); /* * Set the URL of the session configuration to load. A NULL value indicates the @@ -117,16 +116,16 @@ LTTNG_EXPORT extern int lttng_load_session_attr_set_session_name( * * Note that file:// is the only supported URL format. */ -LTTNG_EXPORT extern int lttng_load_session_attr_set_input_url( - struct lttng_load_session_attr *attr, const char *url); +LTTNG_EXPORT extern int lttng_load_session_attr_set_input_url(struct lttng_load_session_attr *attr, + const char *url); /* * Set the overwrite attribute. If set to true, current sessions matching the * loaded sessions will be destroyed and be replaced by the session(s) being * loaded. */ -LTTNG_EXPORT extern int lttng_load_session_attr_set_overwrite( - struct lttng_load_session_attr *attr, int overwrite); +LTTNG_EXPORT extern int lttng_load_session_attr_set_overwrite(struct lttng_load_session_attr *attr, + int overwrite); /* * The following setter are for overriding sessions attributes during the @@ -145,8 +144,8 @@ LTTNG_EXPORT extern int lttng_load_session_attr_set_overwrite( * * See lttng-create(1) for more detail. */ -LTTNG_EXPORT extern int lttng_load_session_attr_set_override_url( - struct lttng_load_session_attr *attr, const char *url); +LTTNG_EXPORT extern int +lttng_load_session_attr_set_override_url(struct lttng_load_session_attr *attr, const char *url); /* * Set the control url override attribute. @@ -158,8 +157,9 @@ LTTNG_EXPORT extern int lttng_load_session_attr_set_override_url( * * See lttng-create(1) for more detail. */ -LTTNG_EXPORT extern int lttng_load_session_attr_set_override_ctrl_url( - struct lttng_load_session_attr *attr, const char *url); +LTTNG_EXPORT extern int +lttng_load_session_attr_set_override_ctrl_url(struct lttng_load_session_attr *attr, + const char *url); /* * Set the data url override attribute. @@ -171,8 +171,9 @@ LTTNG_EXPORT extern int lttng_load_session_attr_set_override_ctrl_url( * * See lttng-create(1) for more detail. */ -LTTNG_EXPORT extern int lttng_load_session_attr_set_override_data_url( - struct lttng_load_session_attr *attr, const char *url); +LTTNG_EXPORT extern int +lttng_load_session_attr_set_override_data_url(struct lttng_load_session_attr *attr, + const char *url); /* * Set the session name override attribute. @@ -180,8 +181,9 @@ LTTNG_EXPORT extern int lttng_load_session_attr_set_override_data_url( * Loading a configuration file defining multiple sessions will fail if a * session name is provided. */ -LTTNG_EXPORT extern int lttng_load_session_attr_set_override_session_name( - struct lttng_load_session_attr *attr, const char *session_name); +LTTNG_EXPORT extern int +lttng_load_session_attr_set_override_session_name(struct lttng_load_session_attr *attr, + const char *session_name); /* * Load session configuration(s). diff --git a/include/lttng/location-internal.hpp b/include/lttng/location-internal.hpp index 4daeed061..669347e2e 100644 --- a/include/lttng/location-internal.hpp +++ b/include/lttng/location-internal.hpp @@ -8,10 +8,12 @@ #ifndef LTTNG_LOCATION_INTERNAL_H #define LTTNG_LOCATION_INTERNAL_H -#include -#include #include +#include #include + +#include + #include #include @@ -73,28 +75,24 @@ struct lttng_trace_archive_location_comm { char payload[]; } LTTNG_PACKED; - -struct lttng_trace_archive_location *lttng_trace_archive_location_local_create( - const char *path); +struct lttng_trace_archive_location *lttng_trace_archive_location_local_create(const char *path); struct lttng_trace_archive_location *lttng_trace_archive_location_relay_create( - const char *host, - enum lttng_trace_archive_location_relay_protocol_type protocol, - uint16_t control_port, uint16_t data_port, - const char *relative_path); + const char *host, + enum lttng_trace_archive_location_relay_protocol_type protocol, + uint16_t control_port, + uint16_t data_port, + const char *relative_path); -ssize_t lttng_trace_archive_location_create_from_buffer( - const struct lttng_buffer_view *buffer, - struct lttng_trace_archive_location **location); +ssize_t +lttng_trace_archive_location_create_from_buffer(const struct lttng_buffer_view *buffer, + struct lttng_trace_archive_location **location); -ssize_t lttng_trace_archive_location_serialize( - const struct lttng_trace_archive_location *location, - struct lttng_dynamic_buffer *buffer); +ssize_t lttng_trace_archive_location_serialize(const struct lttng_trace_archive_location *location, + struct lttng_dynamic_buffer *buffer); -void lttng_trace_archive_location_get( - struct lttng_trace_archive_location *location); +void lttng_trace_archive_location_get(struct lttng_trace_archive_location *location); -void lttng_trace_archive_location_put( - struct lttng_trace_archive_location *location); +void lttng_trace_archive_location_put(struct lttng_trace_archive_location *location); #endif /* LTTNG_LOCATION_INTERNAL_H */ diff --git a/include/lttng/location.h b/include/lttng/location.h index ce686315e..a1ea16f23 100644 --- a/include/lttng/location.h +++ b/include/lttng/location.h @@ -9,6 +9,7 @@ #define LTTNG_LOCATION_H #include + #include #ifdef __cplusplus @@ -40,8 +41,7 @@ struct lttng_trace_archive_location; * Get a trace archive location's type. */ LTTNG_EXPORT extern enum lttng_trace_archive_location_type -lttng_trace_archive_location_get_type( - const struct lttng_trace_archive_location *location); +lttng_trace_archive_location_get_type(const struct lttng_trace_archive_location *location); /* * Get the absolute path of a local trace archive location. @@ -50,8 +50,7 @@ lttng_trace_archive_location_get_type( */ LTTNG_EXPORT extern enum lttng_trace_archive_location_status lttng_trace_archive_location_local_get_absolute_path( - const struct lttng_trace_archive_location *location, - const char **absolute_path); + const struct lttng_trace_archive_location *location, const char **absolute_path); /* * Get the host address of the relay daemon associated to this trace archive @@ -60,9 +59,8 @@ lttng_trace_archive_location_local_get_absolute_path( * The trace archive location maintains ownership of relay_host. */ LTTNG_EXPORT extern enum lttng_trace_archive_location_status -lttng_trace_archive_location_relay_get_host( - const struct lttng_trace_archive_location *location, - const char **relay_host); +lttng_trace_archive_location_relay_get_host(const struct lttng_trace_archive_location *location, + const char **relay_host); /* * Get the control port of the relay daemon associated to this trace archive @@ -70,8 +68,7 @@ lttng_trace_archive_location_relay_get_host( */ LTTNG_EXPORT extern enum lttng_trace_archive_location_status lttng_trace_archive_location_relay_get_control_port( - const struct lttng_trace_archive_location *location, - uint16_t *control_port); + const struct lttng_trace_archive_location *location, uint16_t *control_port); /* * Get the data port of the relay daemon associated to this trace archive @@ -79,8 +76,7 @@ lttng_trace_archive_location_relay_get_control_port( */ LTTNG_EXPORT extern enum lttng_trace_archive_location_status lttng_trace_archive_location_relay_get_data_port( - const struct lttng_trace_archive_location *location, - uint16_t *data_port); + const struct lttng_trace_archive_location *location, uint16_t *data_port); /* * Get the protocol used to communicate with the relay daemon associated to this @@ -88,8 +84,8 @@ lttng_trace_archive_location_relay_get_data_port( */ LTTNG_EXPORT extern enum lttng_trace_archive_location_status lttng_trace_archive_location_relay_get_protocol_type( - const struct lttng_trace_archive_location *location, - enum lttng_trace_archive_location_relay_protocol_type *protocol); + const struct lttng_trace_archive_location *location, + enum lttng_trace_archive_location_relay_protocol_type *protocol); /* * Get path relative to the relay daemon's current output path. @@ -98,8 +94,7 @@ lttng_trace_archive_location_relay_get_protocol_type( */ LTTNG_EXPORT extern enum lttng_trace_archive_location_status lttng_trace_archive_location_relay_get_relative_path( - const struct lttng_trace_archive_location *location, - const char **relative_path); + const struct lttng_trace_archive_location *location, const char **relative_path); #ifdef __cplusplus } diff --git a/include/lttng/log-level-rule-internal.hpp b/include/lttng/log-level-rule-internal.hpp index 71447cfe3..6b08e8a5f 100644 --- a/include/lttng/log-level-rule-internal.hpp +++ b/include/lttng/log-level-rule-internal.hpp @@ -8,17 +8,18 @@ #ifndef LTTNG_LOG_LEVEL_RULE_INTERNAL_H #define LTTNG_LOG_LEVEL_RULE_INTERNAL_H -#include - #include #include #include #include #include + #include #include #include +#include + struct mi_writer; /* @@ -36,29 +37,24 @@ struct lttng_log_level_rule_comm { int32_t level; }; -ssize_t lttng_log_level_rule_create_from_payload( - struct lttng_payload_view *view, - struct lttng_log_level_rule **rule); +ssize_t lttng_log_level_rule_create_from_payload(struct lttng_payload_view *view, + struct lttng_log_level_rule **rule); int lttng_log_level_rule_serialize(const struct lttng_log_level_rule *rule, - struct lttng_payload *payload); + struct lttng_payload *payload); bool lttng_log_level_rule_is_equal(const struct lttng_log_level_rule *a, - const struct lttng_log_level_rule *b); + const struct lttng_log_level_rule *b); -struct lttng_log_level_rule *lttng_log_level_rule_copy( - const struct lttng_log_level_rule *source); +struct lttng_log_level_rule *lttng_log_level_rule_copy(const struct lttng_log_level_rule *source); -void lttng_log_level_rule_to_loglevel( - const struct lttng_log_level_rule *log_level_rule, - enum lttng_loglevel_type *loglevel_type, - int *loglevel_value); +void lttng_log_level_rule_to_loglevel(const struct lttng_log_level_rule *log_level_rule, + enum lttng_loglevel_type *loglevel_type, + int *loglevel_value); -unsigned long lttng_log_level_rule_hash( - const struct lttng_log_level_rule *log_level_rule); +unsigned long lttng_log_level_rule_hash(const struct lttng_log_level_rule *log_level_rule); -enum lttng_error_code lttng_log_level_rule_mi_serialize( - const struct lttng_log_level_rule *rule, - struct mi_writer *writer); +enum lttng_error_code lttng_log_level_rule_mi_serialize(const struct lttng_log_level_rule *rule, + struct mi_writer *writer); #endif /* LTTNG_LOG_LEVEL_RULE_INTERNAL_H */ diff --git a/include/lttng/log-level-rule.h b/include/lttng/log-level-rule.h index ddb3501a1..a73b26ae3 100644 --- a/include/lttng/log-level-rule.h +++ b/include/lttng/log-level-rule.h @@ -34,8 +34,8 @@ enum lttng_log_level_rule_status { * `LTTNG_LOG_LEVEL_RULE_TYPE_UNKNOWN`: * `rule` is `NULL`. */ -LTTNG_EXPORT extern enum lttng_log_level_rule_type lttng_log_level_rule_get_type( - const struct lttng_log_level_rule *rule); +LTTNG_EXPORT extern enum lttng_log_level_rule_type +lttng_log_level_rule_get_type(const struct lttng_log_level_rule *rule); /* * Creates a log level rule for which a log level must match exactly `level` to @@ -48,8 +48,7 @@ LTTNG_EXPORT extern enum lttng_log_level_rule_type lttng_log_level_rule_get_type * The returned log level rule must be destroyed using * lttng_log_level_rule_destroy(). */ -LTTNG_EXPORT extern struct lttng_log_level_rule *lttng_log_level_rule_exactly_create( - int level); +LTTNG_EXPORT extern struct lttng_log_level_rule *lttng_log_level_rule_exactly_create(int level); /* * Sets `level` to the level of the "exactly" log level rule `rule`. @@ -64,8 +63,8 @@ LTTNG_EXPORT extern struct lttng_log_level_rule *lttng_log_level_rule_exactly_cr * * `level` is NULL. * * The type of `rule` is not `LTTNG_LOG_LEVEL_RULE_TYPE_EXACTLY`. */ -LTTNG_EXPORT extern enum lttng_log_level_rule_status lttng_log_level_rule_exactly_get_level( - const struct lttng_log_level_rule *rule, int *level); +LTTNG_EXPORT extern enum lttng_log_level_rule_status +lttng_log_level_rule_exactly_get_level(const struct lttng_log_level_rule *rule, int *level); /* * Creates a log level rule for which a log level must be at least as severe as @@ -97,14 +96,13 @@ lttng_log_level_rule_at_least_as_severe_as_create(int level); * `LTTNG_LOG_LEVEL_RULE_TYPE_AT_LEAST_AS_SEVERE_AS`. */ LTTNG_EXPORT extern enum lttng_log_level_rule_status -lttng_log_level_rule_at_least_as_severe_as_get_level( - const struct lttng_log_level_rule *rule, int *level); +lttng_log_level_rule_at_least_as_severe_as_get_level(const struct lttng_log_level_rule *rule, + int *level); /* * Destroy the log level rule `log_level_rule` if not `NULL`. */ -LTTNG_EXPORT extern void lttng_log_level_rule_destroy( - struct lttng_log_level_rule *log_level_rule); +LTTNG_EXPORT extern void lttng_log_level_rule_destroy(struct lttng_log_level_rule *log_level_rule); #ifdef __cplusplus } diff --git a/include/lttng/lttng-error.h b/include/lttng/lttng-error.h index 790a78a0b..fa05af777 100644 --- a/include/lttng/lttng-error.h +++ b/include/lttng/lttng-error.h @@ -15,189 +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. */ - 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 */ + /* Internal codes */ + /// @cond INTERNAL_ERR_CODES + LTTNG_ERR_SELECT_SESS = 27, /* Must select a session */ + LTTNG_ERR_NO_STREAM = 52, /* Index without stream on relay. */ + LTTNG_ERR_UST_CALIBRATE_FAIL = 54, /* UST calibration failed */ + LTTNG_ERR_UST_CHAN_ENABLE_FAIL = 61, /* UST enable channel failed */ + LTTNG_ERR_CHAN_EXIST = 62, /* Channel already exists. */ + LTTNG_ERR_UST_META_FAIL = 65, /* UST open metadata failed */ + LTTNG_ERR_UST_STREAM_FAIL = 70, /* UST create stream failed */ + LTTNG_ERR_SNAPSHOT_NODATA = 71, /* No data in snapshot. */ + 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 */ + LTTNG_ERR_EVENT_EXIST_LOGLEVEL = 100, /* Event enabled with different loglevel */ + LTTNG_ERR_FILTER_EXIST = 108, /* Filter already exist */ + LTTNG_ERR_COMMAND_CANCELLED = 128, /* Command cancelled. */ + 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_TRACE_CHUNK_EXISTS_FAIL_CONSUMER = 151, /* failed to query consumer for trace + chunk existence */ + /// @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 */ - 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 */ + + /// 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-export.h b/include/lttng/lttng-export.h index ae3990a29..51eca4ee7 100644 --- a/include/lttng/lttng-export.h +++ b/include/lttng/lttng-export.h @@ -7,8 +7,8 @@ #ifndef LTTNG_EXPORT_H #define LTTNG_EXPORT_H #if defined(_WIN32) || defined(__CYGWIN__) -# define LTTNG_EXPORT +#define LTTNG_EXPORT #else -# define LTTNG_EXPORT __attribute__((visibility("default"))) +#define LTTNG_EXPORT __attribute__((visibility("default"))) #endif #endif diff --git a/include/lttng/lttng.h b/include/lttng/lttng.h index dbfe9a7db..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 @@ -42,23 +44,23 @@ #include #include #include -#include #include #include #include -#include #include #include +#include +#include #include #include #include #include #include +#include #include #include #include #include -#include #include #include #include @@ -75,35 +77,79 @@ extern "C" { #endif enum lttng_calibrate_type { - LTTNG_CALIBRATE_FUNCTION = 0, + LTTNG_CALIBRATE_FUNCTION = 0, }; /* Machine interface output type */ enum lttng_mi_output_type { - LTTNG_MI_XML = 1 /* XML output */ + LTTNG_MI_XML = 1 /* XML output */ }; -#define LTTNG_CALIBRATE_PADDING1 16 +#define LTTNG_CALIBRATE_PADDING1 16 struct lttng_calibrate { enum lttng_calibrate_type type; 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. @@ -116,33 +162,126 @@ LTTNG_EXPORT extern int lttng_set_tracing_group(const char *name); * Return 0 on success else a negative LTTng error code. */ LTTNG_EXPORT extern int lttng_register_consumer(struct lttng_handle *handle, - const char *socket_path); + 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); /* @@ -152,7 +291,7 @@ LTTNG_EXPORT extern int lttng_stop_tracing_no_wait(const char *session_name); #pragma GCC diagnostic push #pragma GCC diagnostic ignored "-Wshadow" LTTNG_EXPORT extern int lttng_calibrate(struct lttng_handle *handle, - struct lttng_calibrate *calibrate); + struct lttng_calibrate *calibrate); #pragma GCC diagnostic pop /* @@ -179,42 +318,180 @@ LTTNG_EXPORT extern int lttng_calibrate(struct lttng_handle *handle, * * Return 0 on success else a negative LTTng error code. */ -LTTNG_EXPORT extern int lttng_set_consumer_url(struct lttng_handle *handle, - const char *control_url, const char *data_url); +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); /* - * Deprecated, replaced by lttng_regenerate_metadata. + * Gets the status of the kernel tracer. + * + * Sets the value of the argument, which must not be null. */ -LTTNG_DEPRECATED("Use lttng_regenerate_metadata") +LTTNG_EXPORT extern enum lttng_error_code +lttng_get_kernel_tracer_status(enum lttng_kernel_tracer_status *status); + +/*! +@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/notification/channel-internal.hpp b/include/lttng/notification/channel-internal.hpp index 3364704ee..173b3dcdc 100644 --- a/include/lttng/notification/channel-internal.hpp +++ b/include/lttng/notification/channel-internal.hpp @@ -8,12 +8,15 @@ #ifndef LTTNG_NOTIFICATION_CHANNEL_INTERNAL_H #define LTTNG_NOTIFICATION_CHANNEL_INTERNAL_H -#include #include +#include #include -#include -#include + +#include + #include +#include +#include #include /* @@ -82,6 +85,11 @@ struct pending_notification { * in the pending_notifications list. */ struct lttng_notification_channel { + using uptr = std::unique_ptr< + lttng_notification_channel, + lttng::memory::create_deleter_class::deleter>; + pthread_mutex_t lock; int socket; struct { diff --git a/include/lttng/notification/channel.h b/include/lttng/notification/channel.h index 030c88cbd..dad62b0b3 100644 --- a/include/lttng/notification/channel.h +++ b/include/lttng/notification/channel.h @@ -9,6 +9,7 @@ #define LTTNG_NOTIFICATION_CHANNEL_H #include + #include #ifdef __cplusplus @@ -58,8 +59,8 @@ enum lttng_notification_channel_status { * The returned lttng_notification_channel must be destroyed using * the lttng_notification_channel_destroy() function. */ -LTTNG_EXPORT extern struct lttng_notification_channel *lttng_notification_channel_create( - struct lttng_endpoint *endpoint); +LTTNG_EXPORT extern struct lttng_notification_channel * +lttng_notification_channel_create(struct lttng_endpoint *endpoint); /* * Get the next notification received on a notification channel. @@ -83,9 +84,8 @@ LTTNG_EXPORT extern struct lttng_notification_channel *lttng_notification_channe * that caused the reception to fail. */ LTTNG_EXPORT extern enum lttng_notification_channel_status -lttng_notification_channel_get_next_notification( - struct lttng_notification_channel *channel, - struct lttng_notification **notification); +lttng_notification_channel_get_next_notification(struct lttng_notification_channel *channel, + struct lttng_notification **notification); /* * Check whether a notification is pending on a notification channel. @@ -104,9 +104,8 @@ lttng_notification_channel_get_next_notification( * provided. */ LTTNG_EXPORT extern enum lttng_notification_channel_status -lttng_notification_channel_has_pending_notification( - struct lttng_notification_channel *channel, - bool *notification_pending); +lttng_notification_channel_has_pending_notification(struct lttng_notification_channel *channel, + bool *notification_pending); /* * Subscribe to notifications of a condition through a notification channel. @@ -124,9 +123,8 @@ lttng_notification_channel_has_pending_notification( * client was already subscribed to the condition through this channel. */ LTTNG_EXPORT extern enum lttng_notification_channel_status -lttng_notification_channel_subscribe( - struct lttng_notification_channel *channel, - const struct lttng_condition *condition); +lttng_notification_channel_subscribe(struct lttng_notification_channel *channel, + const struct lttng_condition *condition); /* * Unsubscribe to notifications of a condition through a notification channel. @@ -144,15 +142,14 @@ lttng_notification_channel_subscribe( * client was not already subscribed to the condition through this channel. */ LTTNG_EXPORT extern enum lttng_notification_channel_status -lttng_notification_channel_unsubscribe( - struct lttng_notification_channel *channel, - const struct lttng_condition *condition); +lttng_notification_channel_unsubscribe(struct lttng_notification_channel *channel, + const struct lttng_condition *condition); /* * Closes and destroys (frees) a notification channel. */ -LTTNG_EXPORT extern void lttng_notification_channel_destroy( - struct lttng_notification_channel *channel); +LTTNG_EXPORT extern void +lttng_notification_channel_destroy(struct lttng_notification_channel *channel); #ifdef __cplusplus } diff --git a/include/lttng/notification/notification-internal.hpp b/include/lttng/notification/notification-internal.hpp index 9557c38b8..36b3d7f38 100644 --- a/include/lttng/notification/notification-internal.hpp +++ b/include/lttng/notification/notification-internal.hpp @@ -8,16 +8,25 @@ #ifndef LTTNG_NOTIFICATION_INTERNAL_H #define LTTNG_NOTIFICATION_INTERNAL_H -#include #include -#include +#include + +#include + +#include #include +#include #include struct lttng_payload; struct lttng_payload_view; struct lttng_notification { + using uptr = std::unique_ptr< + lttng_notification, + lttng::memory::create_deleter_class::deleter>; + struct lttng_trigger *trigger; struct lttng_evaluation *evaluation; }; @@ -29,23 +38,21 @@ struct lttng_notification_comm { char payload[]; } LTTNG_PACKED; -struct lttng_notification *lttng_notification_create( - struct lttng_trigger *trigger, - struct lttng_evaluation *evaluation); +struct lttng_notification *lttng_notification_create(struct lttng_trigger *trigger, + struct lttng_evaluation *evaluation); int lttng_notification_serialize(const struct lttng_notification *notification, - struct lttng_payload *payload); + struct lttng_payload *payload); -ssize_t lttng_notification_create_from_payload( - struct lttng_payload_view *view, - struct lttng_notification **notification); +ssize_t lttng_notification_create_from_payload(struct lttng_payload_view *view, + struct lttng_notification **notification); -const struct lttng_condition *lttng_notification_get_const_condition( - const struct lttng_notification *notification); -const struct lttng_evaluation *lttng_notification_get_const_evaluation( - const struct lttng_notification *notification); +const struct lttng_condition * +lttng_notification_get_const_condition(const struct lttng_notification *notification); +const struct lttng_evaluation * +lttng_notification_get_const_evaluation(const struct lttng_notification *notification); -const struct lttng_trigger *lttng_notification_get_const_trigger( - const struct lttng_notification *notification); +const struct lttng_trigger * +lttng_notification_get_const_trigger(const struct lttng_notification *notification); #endif /* LTTNG_NOTIFICATION_INTERNAL_H */ diff --git a/include/lttng/notification/notification.h b/include/lttng/notification/notification.h index d1c088fec..c434f1132 100644 --- a/include/lttng/notification/notification.h +++ b/include/lttng/notification/notification.h @@ -30,8 +30,8 @@ struct lttng_notification; * * Returns an lttng_condition object on success, NULL on error. */ -LTTNG_EXPORT extern const struct lttng_condition *lttng_notification_get_condition( - struct lttng_notification *notification); +LTTNG_EXPORT extern const struct lttng_condition * +lttng_notification_get_condition(struct lttng_notification *notification); /* * Get a notification's condition's evaluation. @@ -45,8 +45,8 @@ LTTNG_EXPORT extern const struct lttng_condition *lttng_notification_get_conditi * * Returns an lttng_evaluation object on success, NULL on error. */ -LTTNG_EXPORT extern const struct lttng_evaluation *lttng_notification_get_evaluation( - struct lttng_notification *notification); +LTTNG_EXPORT extern const struct lttng_evaluation * +lttng_notification_get_evaluation(struct lttng_notification *notification); /* * Get a notification's origin trigger. @@ -57,8 +57,8 @@ LTTNG_EXPORT extern const struct lttng_evaluation *lttng_notification_get_evalua * * Returns an lttng_trigger object on success, NULL on error. */ -LTTNG_EXPORT extern const struct lttng_trigger *lttng_notification_get_trigger( - struct lttng_notification *notification); +LTTNG_EXPORT extern const struct lttng_trigger * +lttng_notification_get_trigger(struct lttng_notification *notification); /* * Destroys (frees) a notification. The notification's condition and evaluation diff --git a/include/lttng/ref-internal.hpp b/include/lttng/ref-internal.hpp index a02ae4cdc..8416d6bcf 100644 --- a/include/lttng/ref-internal.hpp +++ b/include/lttng/ref-internal.hpp @@ -1,6 +1,3 @@ -#ifndef LTTNG_REF_INTERNAL_H -#define LTTNG_REF_INTERNAL_H - /* * LTTng - Non thread-safe reference counting * @@ -10,24 +7,28 @@ * */ +#ifndef LTTNG_REF_INTERNAL_H +#define LTTNG_REF_INTERNAL_H + +#include + +#include -typedef void (*lttng_release_func)(void *); +using lttng_release_func = void (*)(void *); struct lttng_ref { unsigned long count; lttng_release_func release; }; -static inline -void lttng_ref_init(struct lttng_ref *ref, lttng_release_func release) +static inline void lttng_ref_init(struct lttng_ref *ref, lttng_release_func release) { LTTNG_ASSERT(ref); ref->count = 1; ref->release = release; } -static inline -void lttng_ref_get(struct lttng_ref *ref) +static inline void lttng_ref_get(struct lttng_ref *ref) { LTTNG_ASSERT(ref); ref->count++; @@ -35,8 +36,7 @@ void lttng_ref_get(struct lttng_ref *ref) LTTNG_ASSERT(ref->count); } -static inline -void lttng_ref_put(struct lttng_ref *ref) +static inline void lttng_ref_put(struct lttng_ref *ref) { LTTNG_ASSERT(ref); /* Underflow check. */ diff --git a/include/lttng/rotate-internal.hpp b/include/lttng/rotate-internal.hpp index 076f50a9a..dbc66f345 100644 --- a/include/lttng/rotate-internal.hpp +++ b/include/lttng/rotate-internal.hpp @@ -8,13 +8,14 @@ #ifndef LTTNG_ROTATE_INTERNAL_ABI_H #define LTTNG_ROTATE_INTERNAL_ABI_H -#include -#include -#include +#include #include #include -#include + +#include +#include +#include /* * Object returned by the rotate session API. @@ -70,12 +71,12 @@ struct lttng_rotation_schedules { * are then copied to the user's lttng_rotation_handle object. */ -/* For the LTTNG_ROTATE_SESSION command. */ +/* For the LTTCOMM_SESSIOND_COMMAND_ROTATE_SESSION command. */ struct lttng_rotate_session_return { uint64_t rotation_id; } LTTNG_PACKED; -/* For the LTTNG_ROTATION_GET_INFO command. */ +/* For the LTTCOMM_SESSIOND_COMMAND_ROTATION_GET_INFO command. */ struct lttng_rotation_get_info_return { /* Represents values defined in enum lttng_rotation_state. */ int32_t status; diff --git a/include/lttng/rotation.h b/include/lttng/rotation.h index 08f2a985b..e5b14e8b7 100644 --- a/include/lttng/rotation.h +++ b/include/lttng/rotation.h @@ -9,10 +9,11 @@ #ifndef LTTNG_ROTATION_H #define LTTNG_ROTATION_H -#include #include #include +#include + #ifdef __cplusplus extern "C" { #endif @@ -102,9 +103,9 @@ struct lttng_rotation_handle; * This will issue a request to the session daemon on every call. Hence, * the result of this call may change over time. */ -LTTNG_EXPORT extern enum lttng_rotation_status lttng_rotation_handle_get_state( - struct lttng_rotation_handle *rotation_handle, - enum lttng_rotation_state *rotation_state); +LTTNG_EXPORT extern enum lttng_rotation_status +lttng_rotation_handle_get_state(struct lttng_rotation_handle *rotation_handle, + enum lttng_rotation_state *rotation_state); /* * Get the location of the rotation's resulting archive. @@ -115,15 +116,15 @@ LTTNG_EXPORT extern enum lttng_rotation_status lttng_rotation_handle_get_state( * Note that location will not be set in case of error, or if the session * rotation handle has expired. */ -LTTNG_EXPORT extern enum lttng_rotation_status lttng_rotation_handle_get_archive_location( - struct lttng_rotation_handle *rotation_handle, - const struct lttng_trace_archive_location **location); +LTTNG_EXPORT extern enum lttng_rotation_status +lttng_rotation_handle_get_archive_location(struct lttng_rotation_handle *rotation_handle, + const struct lttng_trace_archive_location **location); /* * Destroy an lttng_rotate_session handle. */ -LTTNG_EXPORT extern void lttng_rotation_handle_destroy( - struct lttng_rotation_handle *rotation_handle); +LTTNG_EXPORT extern void +lttng_rotation_handle_destroy(struct lttng_rotation_handle *rotation_handle); /* * Rotate the output folder of the session. @@ -139,14 +140,14 @@ LTTNG_EXPORT extern void lttng_rotation_handle_destroy( * LTTng error code on error. */ LTTNG_EXPORT extern int lttng_rotate_session(const char *session_name, - struct lttng_rotation_immediate_descriptor *descriptor, - struct lttng_rotation_handle **rotation_handle); + struct lttng_rotation_immediate_descriptor *descriptor, + struct lttng_rotation_handle **rotation_handle); /* * Get the type of a rotation schedule object. */ -LTTNG_EXPORT extern enum lttng_rotation_schedule_type lttng_rotation_schedule_get_type( - const struct lttng_rotation_schedule *schedule); +LTTNG_EXPORT extern enum lttng_rotation_schedule_type +lttng_rotation_schedule_get_type(const struct lttng_rotation_schedule *schedule); /* * Return a newly allocated size-based session rotation schedule or NULL on @@ -162,24 +163,21 @@ lttng_rotation_schedule_size_threshold_create(void); * LTTNG_ROTATION_STATUS_UNAVAILABLE is returned if the value is unset. */ LTTNG_EXPORT extern enum lttng_rotation_status -lttng_rotation_schedule_size_threshold_get_threshold( - const struct lttng_rotation_schedule *schedule, - uint64_t *size_threshold_bytes); +lttng_rotation_schedule_size_threshold_get_threshold(const struct lttng_rotation_schedule *schedule, + uint64_t *size_threshold_bytes); /* * Set a session rotation schedule's size threshold. */ LTTNG_EXPORT extern enum lttng_rotation_status -lttng_rotation_schedule_size_threshold_set_threshold( - struct lttng_rotation_schedule *schedule, - uint64_t size_threshold_bytes); +lttng_rotation_schedule_size_threshold_set_threshold(struct lttng_rotation_schedule *schedule, + uint64_t size_threshold_bytes); /* * Return a newly allocated periodic session rotation schedule or NULL on * error. */ -LTTNG_EXPORT extern struct lttng_rotation_schedule * -lttng_rotation_schedule_periodic_create(void); +LTTNG_EXPORT extern struct lttng_rotation_schedule *lttng_rotation_schedule_periodic_create(void); /* * Get a time-based session rotation schedule's period. @@ -187,36 +185,35 @@ lttng_rotation_schedule_periodic_create(void); * Returns LTTNG_ROTATION_STATUS_OK on success. * LTTNG_ROTATION_STATUS_UNAVAILABLE is returned if the value is unset. */ -LTTNG_EXPORT extern enum lttng_rotation_status lttng_rotation_schedule_periodic_get_period( - const struct lttng_rotation_schedule *schedule, - uint64_t *period_us); +LTTNG_EXPORT extern enum lttng_rotation_status +lttng_rotation_schedule_periodic_get_period(const struct lttng_rotation_schedule *schedule, + uint64_t *period_us); /* * Set a time-based session rotation schedule's period. */ -LTTNG_EXPORT extern enum lttng_rotation_status lttng_rotation_schedule_periodic_set_period( - struct lttng_rotation_schedule *schedule, - uint64_t period_us); +LTTNG_EXPORT extern enum lttng_rotation_status +lttng_rotation_schedule_periodic_set_period(struct lttng_rotation_schedule *schedule, + uint64_t period_us); /* * Destroy a rotation schedule. */ -LTTNG_EXPORT extern void lttng_rotation_schedule_destroy( - struct lttng_rotation_schedule *schedule); +LTTNG_EXPORT extern void lttng_rotation_schedule_destroy(struct lttng_rotation_schedule *schedule); /* * Destroy a set of rotation schedules. Pointers to any schedule contained * in this set become invalid after this call. */ -LTTNG_EXPORT extern void lttng_rotation_schedules_destroy( - struct lttng_rotation_schedules *schedules); +LTTNG_EXPORT extern void +lttng_rotation_schedules_destroy(struct lttng_rotation_schedules *schedules); /* * Get the number of schedules in a schedule set. */ -LTTNG_EXPORT extern enum lttng_rotation_status lttng_rotation_schedules_get_count( - const struct lttng_rotation_schedules *schedules, - unsigned int *count); +LTTNG_EXPORT extern enum lttng_rotation_status +lttng_rotation_schedules_get_count(const struct lttng_rotation_schedules *schedules, + unsigned int *count); /* * Get a schedule from the set at a given index. @@ -228,9 +225,8 @@ LTTNG_EXPORT extern enum lttng_rotation_status lttng_rotation_schedules_get_coun * Returns a rotation schedule, or NULL on error. */ LTTNG_EXPORT extern const struct lttng_rotation_schedule * -lttng_rotation_schedules_get_at_index( - const struct lttng_rotation_schedules *schedules, - unsigned int index); +lttng_rotation_schedules_get_at_index(const struct lttng_rotation_schedules *schedules, + unsigned int index); /* * Add a session rotation schedule to a session. @@ -242,9 +238,9 @@ lttng_rotation_schedules_get_at_index( * LTTNG_ROTATION_STATUS_SCHEDULE_ALREADY_SET if a rotation of the same type * is already set. */ -LTTNG_EXPORT extern enum lttng_rotation_status lttng_session_add_rotation_schedule( - const char *session_name, - const struct lttng_rotation_schedule *schedule); +LTTNG_EXPORT extern enum lttng_rotation_status +lttng_session_add_rotation_schedule(const char *session_name, + const struct lttng_rotation_schedule *schedule); /* * Remove a session rotation schedule from a session. @@ -253,18 +249,18 @@ LTTNG_EXPORT extern enum lttng_rotation_status lttng_session_add_rotation_schedu * LTTNG_ROTATION_STATUS_SCHEDULE_INVALID if the provided schedule is * not set. */ -LTTNG_EXPORT extern enum lttng_rotation_status lttng_session_remove_rotation_schedule( - const char *session_name, - const struct lttng_rotation_schedule *schedule); +LTTNG_EXPORT extern enum lttng_rotation_status +lttng_session_remove_rotation_schedule(const char *session_name, + const struct lttng_rotation_schedule *schedule); /* * Get the rotation schedules associated with a given session. * * Returns LTTNG_OK on success, or a negative lttng error code on error. */ -LTTNG_EXPORT extern int lttng_session_list_rotation_schedules( - const char *session_name, - struct lttng_rotation_schedules **schedules); +LTTNG_EXPORT extern int +lttng_session_list_rotation_schedules(const char *session_name, + struct lttng_rotation_schedules **schedules); #ifdef __cplusplus } diff --git a/include/lttng/save-internal.hpp b/include/lttng/save-internal.hpp index 6b2bb9433..4b8343bdb 100644 --- a/include/lttng/save-internal.hpp +++ b/include/lttng/save-internal.hpp @@ -8,11 +8,12 @@ #ifndef LTTNG_SAVE_INTERNAL_ABI_H #define LTTNG_SAVE_INTERNAL_ABI_H -#include -#include +#include #include -#include + +#include +#include /* * Object used by the save_session API. This is opaque to the public library. diff --git a/include/lttng/save.h b/include/lttng/save.h index d28fdffcd..6120467a7 100644 --- a/include/lttng/save.h +++ b/include/lttng/save.h @@ -30,39 +30,36 @@ LTTNG_EXPORT extern struct lttng_save_session_attr *lttng_save_session_attr_crea */ LTTNG_EXPORT extern void lttng_save_session_attr_destroy(struct lttng_save_session_attr *output); - /* * Save session attribute getter family functions. */ /* Return session name. NULL indicated all sessions must be saved. */ -LTTNG_EXPORT extern const char *lttng_save_session_attr_get_session_name( - struct lttng_save_session_attr *attr); +LTTNG_EXPORT extern const char * +lttng_save_session_attr_get_session_name(struct lttng_save_session_attr *attr); /* * Return destination URL. A NULL value indicates the default session * configuration location. The URL format used is documented in lttng(1). * NULL indicates that the default session configuration path is used. */ -LTTNG_EXPORT extern const char *lttng_save_session_attr_get_output_url( - struct lttng_save_session_attr *attr); +LTTNG_EXPORT extern const char * +lttng_save_session_attr_get_output_url(struct lttng_save_session_attr *attr); /* * Return the configuration overwrite attribute. This attribute indicates * whether or not existing configuration files must be overwritten. */ -LTTNG_EXPORT extern int lttng_save_session_attr_get_overwrite( - struct lttng_save_session_attr *attr); +LTTNG_EXPORT extern int lttng_save_session_attr_get_overwrite(struct lttng_save_session_attr *attr); /* * Return the omit name configuration attribute. This attribute indicates * whether or not the saved sessions' names should be omitted. */ -LTTNG_EXPORT extern int lttng_save_session_attr_get_omit_name( - struct lttng_save_session_attr *attr); +LTTNG_EXPORT extern int lttng_save_session_attr_get_omit_name(struct lttng_save_session_attr *attr); /* * Return the omit output configuration attribute. This attribute indicates * whether or not the saved sessions' output configuration should be omitted. */ -LTTNG_EXPORT extern int lttng_save_session_attr_get_omit_output( - struct lttng_save_session_attr *attr); +LTTNG_EXPORT extern int +lttng_save_session_attr_get_omit_output(struct lttng_save_session_attr *attr); /* * Save session attribute setter family functions. @@ -75,33 +72,34 @@ LTTNG_EXPORT extern int lttng_save_session_attr_get_omit_output( * Set the name of the session to save. A NULL name means all sessions * known to the session daemon will be saved. */ -LTTNG_EXPORT extern int lttng_save_session_attr_set_session_name( - struct lttng_save_session_attr *attr, const char *session_name); +LTTNG_EXPORT extern int +lttng_save_session_attr_set_session_name(struct lttng_save_session_attr *attr, + const char *session_name); /* * Set the URL of the session configuration to save. A NULL value indicates the * use of the default location being the session one. The URL's format is is * documented in lttng(1). */ -LTTNG_EXPORT extern int lttng_save_session_attr_set_output_url( - struct lttng_save_session_attr *attr, const char *url); +LTTNG_EXPORT extern int lttng_save_session_attr_set_output_url(struct lttng_save_session_attr *attr, + const char *url); /* * Set the overwrite attribute. If set to true, files of the same name as the * current session configuration URL will be overwritten. */ -LTTNG_EXPORT extern int lttng_save_session_attr_set_overwrite( - struct lttng_save_session_attr *attr, int overwrite); +LTTNG_EXPORT extern int lttng_save_session_attr_set_overwrite(struct lttng_save_session_attr *attr, + int overwrite); /* * Set the omit name attribute. If set to true, the sessions' names are omitted * from the resulting session configuration file. */ -LTTNG_EXPORT extern int lttng_save_session_attr_set_omit_name( - struct lttng_save_session_attr *attr, int omit_name); +LTTNG_EXPORT extern int lttng_save_session_attr_set_omit_name(struct lttng_save_session_attr *attr, + int omit_name); /* * Set the omit output attribute. If set to true, the sessions' output * configurations are omitted from the resulting session configuration file. */ -LTTNG_EXPORT extern int lttng_save_session_attr_set_omit_output( - struct lttng_save_session_attr *attr, int omit_output); +LTTNG_EXPORT extern int +lttng_save_session_attr_set_omit_output(struct lttng_save_session_attr *attr, int omit_output); /* * Save session configuration(s). diff --git a/include/lttng/session-descriptor-internal.hpp b/include/lttng/session-descriptor-internal.hpp index c132f5600..a2dd70d57 100644 --- a/include/lttng/session-descriptor-internal.hpp +++ b/include/lttng/session-descriptor-internal.hpp @@ -8,11 +8,13 @@ #ifndef LTTNG_SESSION_DESCRIPTOR_INTERNAL_H #define LTTNG_SESSION_DESCRIPTOR_INTERNAL_H -#include -#include -#include -#include #include +#include +#include + +#include +#include + #include /* Note that these enums are used as part of the lttnctl protocol. */ @@ -33,52 +35,44 @@ enum lttng_session_descriptor_output_type { LTTNG_SESSION_DESCRIPTOR_OUTPUT_TYPE_NETWORK = 2, }; -ssize_t lttng_session_descriptor_create_from_buffer( - const struct lttng_buffer_view *view, - struct lttng_session_descriptor **descriptor); +ssize_t lttng_session_descriptor_create_from_buffer(const struct lttng_buffer_view *view, + struct lttng_session_descriptor **descriptor); -int lttng_session_descriptor_serialize( - const struct lttng_session_descriptor *descriptor, - struct lttng_dynamic_buffer *buffer); +int lttng_session_descriptor_serialize(const struct lttng_session_descriptor *descriptor, + struct lttng_dynamic_buffer *buffer); enum lttng_session_descriptor_type -lttng_session_descriptor_get_type( - const struct lttng_session_descriptor *descriptor); +lttng_session_descriptor_get_type(const struct lttng_session_descriptor *descriptor); enum lttng_session_descriptor_output_type -lttng_session_descriptor_get_output_type( - const struct lttng_session_descriptor *descriptor); +lttng_session_descriptor_get_output_type(const struct lttng_session_descriptor *descriptor); void lttng_session_descriptor_get_local_output_uri( - const struct lttng_session_descriptor *descriptor, - struct lttng_uri *local_uri); + const struct lttng_session_descriptor *descriptor, struct lttng_uri *local_uri); void lttng_session_descriptor_get_network_output_uris( - const struct lttng_session_descriptor *descriptor, - struct lttng_uri *control, - struct lttng_uri *data); + const struct lttng_session_descriptor *descriptor, + struct lttng_uri *control, + struct lttng_uri *data); unsigned long long -lttng_session_descriptor_live_get_timer_interval( - const struct lttng_session_descriptor *descriptor); +lttng_session_descriptor_live_get_timer_interval(const struct lttng_session_descriptor *descriptor); -int lttng_session_descriptor_set_session_name( - struct lttng_session_descriptor *descriptor, - const char *name); +int lttng_session_descriptor_set_session_name(struct lttng_session_descriptor *descriptor, + const char *name); bool lttng_session_descriptor_is_output_destination_initialized( - const struct lttng_session_descriptor *descriptor); + const struct lttng_session_descriptor *descriptor); bool lttng_session_descriptor_has_output_directory( - const struct lttng_session_descriptor *descriptor); + const struct lttng_session_descriptor *descriptor); -enum lttng_error_code lttng_session_descriptor_set_default_output( - struct lttng_session_descriptor *descriptor, - time_t *session_creation_time, - const char *absolute_home_path); +enum lttng_error_code +lttng_session_descriptor_set_default_output(struct lttng_session_descriptor *descriptor, + time_t *session_creation_time, + const char *absolute_home_path); -int lttng_session_descriptor_assign( - struct lttng_session_descriptor *dst_descriptor, - const struct lttng_session_descriptor *src_descriptor); +int lttng_session_descriptor_assign(struct lttng_session_descriptor *dst_descriptor, + const struct lttng_session_descriptor *src_descriptor); #endif /* LTTNG_SESSION_DESCRIPTOR_INTERNAL_H */ diff --git a/include/lttng/session-descriptor.h b/include/lttng/session-descriptor.h index 5db04be7e..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,91 +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. - */ -LTTNG_EXPORT extern struct lttng_session_descriptor * -lttng_session_descriptor_create(const char *name); +/*! +@brief + Creates a recording session descriptor to create a no-output, + \ref api-session-local-mode "local" recording session + named \lt_p{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. - */ +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_local_create(const char *name, const char *path); +lttng_session_descriptor_create(const char *session_name); -/* - * 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-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_network_create(const char *name, - const char *control_url, const char *data_url); +lttng_session_descriptor_local_create(const char *session_name, const char *trace_dir); -/* - * 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-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 *session_name, const char *control_url, const char *data_url); + +/*! +@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, - const char *control_url, const char *data_url); +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. @@ -188,30 +576,111 @@ lttng_session_descriptor_snapshot_network_create(const char *name, * Returns an lttng_session_descriptor instance on success, NULL on error. */ LTTNG_EXPORT extern struct lttng_session_descriptor * -lttng_session_descriptor_live_create( - const char *name, unsigned long long live_timer_interval_us); +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, - const char *control_url, const char *data_url, - unsigned long long live_timer_interval_us); +lttng_session_descriptor_live_network_create(const char *session_name, + const char *control_url, + const char *data_url, + unsigned long long live_timer_period); /* * Get a session descriptor's session name. @@ -228,19 +697,75 @@ lttng_session_descriptor_live_network_create( * 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. - */ -LTTNG_EXPORT extern void lttng_session_descriptor_destroy( - struct lttng_session_descriptor *descriptor); +/*! +@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 *session_descriptor); + +/// @} #ifdef __cplusplus } diff --git a/include/lttng/session-internal.hpp b/include/lttng/session-internal.hpp index 7f73b9610..61e65981c 100644 --- a/include/lttng/session-internal.hpp +++ b/include/lttng/session-internal.hpp @@ -8,8 +8,12 @@ #ifndef LTTNG_SESSION_INTERNAL_H #define LTTNG_SESSION_INTERNAL_H -#include #include +#include + +#include + +struct lttng_session; struct lttng_session_extended { struct { @@ -18,4 +22,8 @@ struct lttng_session_extended { } LTTNG_PACKED creation_time; } LTTNG_PACKED; +using lttng_session_uptr = std::unique_ptr< + lttng_session[], + lttng::memory::create_deleter_class::deleter>; + #endif /* LTTNG_SESSION_INTERNAL_H */ diff --git a/include/lttng/session.h b/include/lttng/session.h index 153a37b03..a6735edad 100644 --- a/include/lttng/session.h +++ b/include/lttng/session.h @@ -13,37 +13,80 @@ 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 +#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]; - uint32_t enabled; /* enabled/started: 1, disabled/stopped: 0 */ + + /*! + @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; - unsigned int live_timer_interval; /* usec */ + + /*! + @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 */ /* * End of public attributes. @@ -73,140 +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. - */ -LTTNG_EXPORT extern enum lttng_error_code lttng_create_session_ext( - struct lttng_session_descriptor *session_descriptor); +/*! +@brief + Creates a recording session from the recording session descriptor + \lt_p{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); +See \ref api_session_descr to learn how to create a recording session +descriptor. -/* - * 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); +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(). -/* - * 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_descriptor + Descriptor from which to create a recording session. -/* - * 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); +@returns + #LTTNG_OK on success, or a \em negative enumerator otherwise. -/* - * 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(). - */ -LTTNG_EXPORT extern enum lttng_error_code lttng_destroy_session_ext(const char *session_name, - struct lttng_destruction_handle **handle); +@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. -/* - * 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); +@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); -/* - * 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. - */ +/*! +@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}. + +@deprecated + Use lttng_create_session_ext() with a dedicated + local or network streaming + \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. + + 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, 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); + +/*! +@brief + Sets \lt_p{*sessions} to the summaries of all the available + recording sessions. + +@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. - */ -LTTNG_EXPORT extern enum lttng_error_code lttng_session_get_creation_time( - const struct lttng_session *session, uint64_t *creation_time); +/*! +@brief + Sets \lt_p{*creation_timestamp} to the timestamp of the creation of + the recording session summarized by \lt_p{session}. -/* - * 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); +@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_timestamp); + +/*! +@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/include/lttng/snapshot-internal.hpp b/include/lttng/snapshot-internal.hpp index c60a1963b..706bf6ebf 100644 --- a/include/lttng/snapshot-internal.hpp +++ b/include/lttng/snapshot-internal.hpp @@ -8,10 +8,12 @@ #ifndef LTTNG_SNAPSHOT_INTERNAL_ABI_H #define LTTNG_SNAPSHOT_INTERNAL_ABI_H +#include + +#include + #include #include -#include -#include /* * Object used for the snapshot API. This is opaque to the public library. diff --git a/include/lttng/snapshot.h b/include/lttng/snapshot.h index b777e006b..4c1049b4d 100644 --- a/include/lttng/snapshot.h +++ b/include/lttng/snapshot.h @@ -8,8 +8,9 @@ #ifndef LTTNG_SNAPSHOT_H #define LTTNG_SNAPSHOT_H -#include #include + +#include #include #include @@ -40,15 +41,20 @@ LTTNG_EXPORT extern void lttng_snapshot_output_destroy(struct lttng_snapshot_out */ /* Return snapshot ID. */ -LTTNG_EXPORT extern uint32_t lttng_snapshot_output_get_id(const struct lttng_snapshot_output *output); +LTTNG_EXPORT extern uint32_t +lttng_snapshot_output_get_id(const struct lttng_snapshot_output *output); /* Return maximum size of a snapshot. */ -LTTNG_EXPORT extern uint64_t lttng_snapshot_output_get_maxsize(const struct lttng_snapshot_output *output); +LTTNG_EXPORT extern uint64_t +lttng_snapshot_output_get_maxsize(const struct lttng_snapshot_output *output); /* Return snapshot name. */ -LTTNG_EXPORT extern const char *lttng_snapshot_output_get_name(const struct lttng_snapshot_output *output); +LTTNG_EXPORT extern const char * +lttng_snapshot_output_get_name(const struct lttng_snapshot_output *output); /* Return snapshot control URL in a text format. */ -LTTNG_EXPORT extern const char *lttng_snapshot_output_get_ctrl_url(const struct lttng_snapshot_output *output); +LTTNG_EXPORT extern const char * +lttng_snapshot_output_get_ctrl_url(const struct lttng_snapshot_output *output); /* Return snapshot data URL in a text format. */ -LTTNG_EXPORT extern const char *lttng_snapshot_output_get_data_url(const struct lttng_snapshot_output *output); +LTTNG_EXPORT extern const char * +lttng_snapshot_output_get_data_url(const struct lttng_snapshot_output *output); /* * Snapshot output setter family functions. @@ -59,13 +65,13 @@ LTTNG_EXPORT extern const char *lttng_snapshot_output_get_data_url(const struct /* Set a custom ID. */ LTTNG_EXPORT extern int lttng_snapshot_output_set_id(uint32_t id, - struct lttng_snapshot_output *output); + struct lttng_snapshot_output *output); /* Set the maximum size. */ LTTNG_EXPORT extern int lttng_snapshot_output_set_size(uint64_t size, - struct lttng_snapshot_output *output); + struct lttng_snapshot_output *output); /* Set the snapshot name. */ LTTNG_EXPORT extern int lttng_snapshot_output_set_name(const char *name, - struct lttng_snapshot_output *output); + struct lttng_snapshot_output *output); /* * Set the output destination to be a path on the local filesystem. @@ -75,7 +81,7 @@ LTTNG_EXPORT extern int lttng_snapshot_output_set_name(const char *name, * Return 0 on success or else a negative LTTNG_ERR code. */ LTTNG_EXPORT extern int lttng_snapshot_output_set_local_path(const char *path, - struct lttng_snapshot_output *output); + struct lttng_snapshot_output *output); /* * Set the output destination to be the network from a combined control/data @@ -86,7 +92,7 @@ LTTNG_EXPORT extern int lttng_snapshot_output_set_local_path(const char *path, * Return 0 on success or else a negative LTTNG_ERR code. */ LTTNG_EXPORT extern int lttng_snapshot_output_set_network_url(const char *url, - struct lttng_snapshot_output *output); + struct lttng_snapshot_output *output); /* * Set the output destination to be the network using separate URLs for control @@ -99,15 +105,14 @@ LTTNG_EXPORT extern int lttng_snapshot_output_set_network_url(const char *url, * Return 0 on success or else a negative LTTNG_ERR code. */ LTTNG_EXPORT extern int lttng_snapshot_output_set_network_urls( - const char *ctrl_url, const char *data_url, - struct lttng_snapshot_output *output); + const char *ctrl_url, const char *data_url, struct lttng_snapshot_output *output); /* Set the control URL. Local and remote URL are supported. */ LTTNG_EXPORT extern int lttng_snapshot_output_set_ctrl_url(const char *url, - struct lttng_snapshot_output *output); + struct lttng_snapshot_output *output); /* Set the data URL. Local and remote URL are supported. */ LTTNG_EXPORT extern int lttng_snapshot_output_set_data_url(const char *url, - struct lttng_snapshot_output *output); + struct lttng_snapshot_output *output); /* * Add an output object to a session identified by name. @@ -115,7 +120,7 @@ LTTNG_EXPORT extern int lttng_snapshot_output_set_data_url(const char *url, * Return 0 on success or else a negative LTTNG_ERR code. */ LTTNG_EXPORT extern int lttng_snapshot_add_output(const char *session_name, - struct lttng_snapshot_output *output); + struct lttng_snapshot_output *output); /* * Delete an output object to a session identified by name. @@ -123,7 +128,7 @@ LTTNG_EXPORT extern int lttng_snapshot_add_output(const char *session_name, * Return 0 on success or else a negative LTTNG_ERR code. */ LTTNG_EXPORT extern int lttng_snapshot_del_output(const char *session_name, - struct lttng_snapshot_output *output); + struct lttng_snapshot_output *output); /* * List all snapshot output(s) of a session identified by name. The output list @@ -133,7 +138,7 @@ LTTNG_EXPORT extern int lttng_snapshot_del_output(const char *session_name, * is untouched. */ LTTNG_EXPORT extern int lttng_snapshot_list_output(const char *session_name, - struct lttng_snapshot_output_list **list); + struct lttng_snapshot_output_list **list); /* * Return the next available snapshot output object in the given list. A list @@ -142,13 +147,14 @@ LTTNG_EXPORT extern int lttng_snapshot_list_output(const char *session_name, * Return the next object on success or else NULL indicating the end of the * list. */ -LTTNG_EXPORT extern struct lttng_snapshot_output *lttng_snapshot_output_list_get_next( - struct lttng_snapshot_output_list *list); +LTTNG_EXPORT extern struct lttng_snapshot_output * +lttng_snapshot_output_list_get_next(struct lttng_snapshot_output_list *list); /* * Free an output list object. */ -LTTNG_EXPORT extern void lttng_snapshot_output_list_destroy(struct lttng_snapshot_output_list *list); +LTTNG_EXPORT extern void +lttng_snapshot_output_list_destroy(struct lttng_snapshot_output_list *list); /* * Snapshot a trace for the given session. @@ -162,8 +168,8 @@ LTTNG_EXPORT extern void lttng_snapshot_output_list_destroy(struct lttng_snapsho * * Return 0 on success or else a negative LTTNG_ERR value. */ -LTTNG_EXPORT extern int lttng_snapshot_record(const char *session_name, - struct lttng_snapshot_output *output, int wait); +LTTNG_EXPORT extern int +lttng_snapshot_record(const char *session_name, struct lttng_snapshot_output *output, int wait); #ifdef __cplusplus } diff --git a/include/lttng/tracker.h b/include/lttng/tracker.h index 869f8a8f8..f8f493e66 100644 --- a/include/lttng/tracker.h +++ b/include/lttng/tracker.h @@ -116,17 +116,17 @@ struct lttng_process_attr_values; * The tracker's ownership is transfered to the caller. Use * lttng_process_attr_tracker_handle_destroy() to dispose of it. */ -LTTNG_EXPORT extern enum lttng_error_code lttng_session_get_tracker_handle( - const char *session_name, - enum lttng_domain_type domain, - enum lttng_process_attr process_attr, - struct lttng_process_attr_tracker_handle **out_tracker_handle); +LTTNG_EXPORT extern enum lttng_error_code +lttng_session_get_tracker_handle(const char *session_name, + enum lttng_domain_type domain, + enum lttng_process_attr process_attr, + struct lttng_process_attr_tracker_handle **out_tracker_handle); /* * Destroy a process attribute tracker handle. */ -LTTNG_EXPORT extern void lttng_process_attr_tracker_handle_destroy( - struct lttng_process_attr_tracker_handle *tracker_handle); +LTTNG_EXPORT extern void +lttng_process_attr_tracker_handle_destroy(struct lttng_process_attr_tracker_handle *tracker_handle); /* * Get the tracking policy of a process attribute tracker. @@ -137,8 +137,8 @@ LTTNG_EXPORT extern void lttng_process_attr_tracker_handle_destroy( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_tracker_handle_get_tracking_policy( - const struct lttng_process_attr_tracker_handle *tracker_handle, - enum lttng_tracking_policy *policy); + const struct lttng_process_attr_tracker_handle *tracker_handle, + enum lttng_tracking_policy *policy); /* * Set the tracking policy of a process attribute tracker. @@ -150,8 +150,8 @@ lttng_process_attr_tracker_handle_get_tracking_policy( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_tracker_handle_set_tracking_policy( - const struct lttng_process_attr_tracker_handle *tracker_handle, - enum lttng_tracking_policy policy); + const struct lttng_process_attr_tracker_handle *tracker_handle, + enum lttng_tracking_policy policy); /* * Add a numerical PID to the process ID process attribute tracker inclusion @@ -165,9 +165,7 @@ lttng_process_attr_tracker_handle_set_tracking_policy( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_process_id_tracker_handle_add_pid( - const struct lttng_process_attr_tracker_handle - *process_id_tracker, - pid_t pid); + const struct lttng_process_attr_tracker_handle *process_id_tracker, pid_t pid); /* * Remove a numerical PID from the process ID process attribute tracker include @@ -180,9 +178,7 @@ lttng_process_attr_process_id_tracker_handle_add_pid( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_process_id_tracker_handle_remove_pid( - const struct lttng_process_attr_tracker_handle - *process_id_tracker, - pid_t pid); + const struct lttng_process_attr_tracker_handle *process_id_tracker, pid_t pid); /* * Add a numerical PID to the virtual process ID process attribute tracker @@ -196,9 +192,7 @@ lttng_process_attr_process_id_tracker_handle_remove_pid( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_virtual_process_id_tracker_handle_add_pid( - const struct lttng_process_attr_tracker_handle - *process_id_tracker, - pid_t vpid); + const struct lttng_process_attr_tracker_handle *process_id_tracker, pid_t vpid); /* * Remove a numerical PID from the virtual process ID process attribute tracker @@ -211,9 +205,7 @@ lttng_process_attr_virtual_process_id_tracker_handle_add_pid( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_virtual_process_id_tracker_handle_remove_pid( - const struct lttng_process_attr_tracker_handle - *process_id_tracker, - pid_t vpid); + const struct lttng_process_attr_tracker_handle *process_id_tracker, pid_t vpid); /* * Add a numerical UID to the user ID process attribute tracker inclusion set. @@ -226,8 +218,7 @@ lttng_process_attr_virtual_process_id_tracker_handle_remove_pid( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_user_id_tracker_handle_add_uid( - const struct lttng_process_attr_tracker_handle *user_id_tracker, - uid_t uid); + const struct lttng_process_attr_tracker_handle *user_id_tracker, uid_t uid); /* * Remove a numerical UID from the user ID process attribute tracker include @@ -240,8 +231,7 @@ lttng_process_attr_user_id_tracker_handle_add_uid( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_user_id_tracker_handle_remove_uid( - const struct lttng_process_attr_tracker_handle *user_id_tracker, - uid_t uid); + const struct lttng_process_attr_tracker_handle *user_id_tracker, uid_t uid); /* * Add a user name to the user ID process attribute tracker inclusion set. @@ -257,8 +247,7 @@ lttng_process_attr_user_id_tracker_handle_remove_uid( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_user_id_tracker_handle_add_user_name( - const struct lttng_process_attr_tracker_handle *user_id_tracker, - const char *user_name); + const struct lttng_process_attr_tracker_handle *user_id_tracker, const char *user_name); /* * Remove a user name from the user ID process attribute tracker include @@ -274,8 +263,7 @@ lttng_process_attr_user_id_tracker_handle_add_user_name( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_user_id_tracker_handle_remove_user_name( - const struct lttng_process_attr_tracker_handle *user_id_tracker, - const char *user_name); + const struct lttng_process_attr_tracker_handle *user_id_tracker, const char *user_name); /* * Add a numerical UID to the virtual user ID process attribute tracker @@ -289,8 +277,7 @@ lttng_process_attr_user_id_tracker_handle_remove_user_name( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_virtual_user_id_tracker_handle_add_uid( - const struct lttng_process_attr_tracker_handle *user_id_tracker, - uid_t vuid); + const struct lttng_process_attr_tracker_handle *user_id_tracker, uid_t vuid); /* * Remove a numerical UID from the virtual user ID process attribute tracker @@ -303,8 +290,7 @@ lttng_process_attr_virtual_user_id_tracker_handle_add_uid( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_virtual_user_id_tracker_handle_remove_uid( - const struct lttng_process_attr_tracker_handle *user_id_tracker, - uid_t vuid); + const struct lttng_process_attr_tracker_handle *user_id_tracker, uid_t vuid); /* * Add a user name to the virtual user ID process attribute tracker include @@ -321,8 +307,8 @@ lttng_process_attr_virtual_user_id_tracker_handle_remove_uid( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_virtual_user_id_tracker_handle_add_user_name( - const struct lttng_process_attr_tracker_handle *user_id_tracker, - const char *virtual_user_name); + const struct lttng_process_attr_tracker_handle *user_id_tracker, + const char *virtual_user_name); /* * Remove a user name from the virtual user ID process attribute tracker @@ -338,8 +324,8 @@ lttng_process_attr_virtual_user_id_tracker_handle_add_user_name( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_virtual_user_id_tracker_handle_remove_user_name( - const struct lttng_process_attr_tracker_handle *user_id_tracker, - const char *virtual_user_name); + const struct lttng_process_attr_tracker_handle *user_id_tracker, + const char *virtual_user_name); /* * Add a numerical GID to the group ID process attribute tracker inclusion set. @@ -352,8 +338,7 @@ lttng_process_attr_virtual_user_id_tracker_handle_remove_user_name( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_group_id_tracker_handle_add_gid( - const struct lttng_process_attr_tracker_handle *group_id_tracker, - gid_t gid); + const struct lttng_process_attr_tracker_handle *group_id_tracker, gid_t gid); /* * Remove a numerical GID from the group ID process attribute tracker include @@ -366,8 +351,7 @@ lttng_process_attr_group_id_tracker_handle_add_gid( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_group_id_tracker_handle_remove_gid( - const struct lttng_process_attr_tracker_handle *group_id_tracker, - gid_t gid); + const struct lttng_process_attr_tracker_handle *group_id_tracker, gid_t gid); /* * Add a group name to the group ID process attribute tracker inclusion set. @@ -383,8 +367,7 @@ lttng_process_attr_group_id_tracker_handle_remove_gid( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_group_id_tracker_handle_add_group_name( - const struct lttng_process_attr_tracker_handle *group_id_tracker, - const char *group_name); + const struct lttng_process_attr_tracker_handle *group_id_tracker, const char *group_name); /* * Remove a group name from the group ID process attribute tracker include @@ -400,8 +383,7 @@ lttng_process_attr_group_id_tracker_handle_add_group_name( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_group_id_tracker_handle_remove_group_name( - const struct lttng_process_attr_tracker_handle *group_id_tracker, - const char *group_name); + const struct lttng_process_attr_tracker_handle *group_id_tracker, const char *group_name); /* * Add a numerical GID to the virtual group ID process attribute tracker @@ -415,8 +397,7 @@ lttng_process_attr_group_id_tracker_handle_remove_group_name( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_virtual_group_id_tracker_handle_add_gid( - const struct lttng_process_attr_tracker_handle *group_id_tracker, - gid_t vgid); + const struct lttng_process_attr_tracker_handle *group_id_tracker, gid_t vgid); /* * Remove a numerical GID from the virtual group ID process attribute tracker @@ -429,8 +410,7 @@ lttng_process_attr_virtual_group_id_tracker_handle_add_gid( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_virtual_group_id_tracker_handle_remove_gid( - const struct lttng_process_attr_tracker_handle *group_id_tracker, - gid_t vgid); + const struct lttng_process_attr_tracker_handle *group_id_tracker, gid_t vgid); /* * Add a group name to the virtual group ID process attribute tracker include @@ -447,8 +427,8 @@ lttng_process_attr_virtual_group_id_tracker_handle_remove_gid( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_virtual_group_id_tracker_handle_add_group_name( - const struct lttng_process_attr_tracker_handle *group_id_tracker, - const char *virtual_group_name); + const struct lttng_process_attr_tracker_handle *group_id_tracker, + const char *virtual_group_name); /* * Remove a group name from the virtual group ID process attribute tracker @@ -464,8 +444,8 @@ lttng_process_attr_virtual_group_id_tracker_handle_add_group_name( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_virtual_group_id_tracker_handle_remove_group_name( - const struct lttng_process_attr_tracker_handle *group_id_tracker, - const char *virtual_group_name); + const struct lttng_process_attr_tracker_handle *group_id_tracker, + const char *virtual_group_name); /* * Get the process attribute values that are part of a tracker's inclusion set. @@ -482,8 +462,8 @@ lttng_process_attr_virtual_group_id_tracker_handle_remove_group_name( */ LTTNG_EXPORT extern enum lttng_process_attr_tracker_handle_status lttng_process_attr_tracker_handle_get_inclusion_set( - struct lttng_process_attr_tracker_handle *tracker_handle, - const struct lttng_process_attr_values **values); + struct lttng_process_attr_tracker_handle *tracker_handle, + const struct lttng_process_attr_values **values); /* * Get the count of values within a set of process attribute values. @@ -492,9 +472,8 @@ lttng_process_attr_tracker_handle_get_inclusion_set( * LTTNG_PROCESS_ATTR_VALUES_STATUS_INVALID if an invalid argument is provided. */ LTTNG_EXPORT extern enum lttng_process_attr_values_status -lttng_process_attr_values_get_count( - const struct lttng_process_attr_values *values, - unsigned int *count); +lttng_process_attr_values_get_count(const struct lttng_process_attr_values *values, + unsigned int *count); /* * Get the type of a process attribute value at a given index. @@ -503,9 +482,8 @@ lttng_process_attr_values_get_count( * LTTNG_PROCESS_ATTR_VALUE_TYPE_INVALID if an invalid argument is provided. */ LTTNG_EXPORT extern enum lttng_process_attr_value_type -lttng_process_attr_values_get_type_at_index( - const struct lttng_process_attr_values *values, - unsigned int index); +lttng_process_attr_values_get_type_at_index(const struct lttng_process_attr_values *values, + unsigned int index); /* * Get a process ID process attribute value. @@ -515,10 +493,9 @@ lttng_process_attr_values_get_type_at_index( * is not a process ID. */ LTTNG_EXPORT extern enum lttng_process_attr_values_status -lttng_process_attr_values_get_pid_at_index( - const struct lttng_process_attr_values *values, - unsigned int index, - pid_t *pid); +lttng_process_attr_values_get_pid_at_index(const struct lttng_process_attr_values *values, + unsigned int index, + pid_t *pid); /* * Get a user ID process attribute value. @@ -528,10 +505,9 @@ lttng_process_attr_values_get_pid_at_index( * is not a user ID. */ LTTNG_EXPORT extern enum lttng_process_attr_values_status -lttng_process_attr_values_get_uid_at_index( - const struct lttng_process_attr_values *values, - unsigned int index, - uid_t *uid); +lttng_process_attr_values_get_uid_at_index(const struct lttng_process_attr_values *values, + unsigned int index, + uid_t *uid); /* * Get a user name process attribute value. @@ -541,10 +517,9 @@ lttng_process_attr_values_get_uid_at_index( * is not a user name. */ LTTNG_EXPORT extern enum lttng_process_attr_values_status -lttng_process_attr_values_get_user_name_at_index( - const struct lttng_process_attr_values *values, - unsigned int index, - const char **user_name); +lttng_process_attr_values_get_user_name_at_index(const struct lttng_process_attr_values *values, + unsigned int index, + const char **user_name); /* * Get a group ID process attribute value. @@ -554,10 +529,9 @@ lttng_process_attr_values_get_user_name_at_index( * is not a group ID. */ LTTNG_EXPORT extern enum lttng_process_attr_values_status -lttng_process_attr_values_get_gid_at_index( - const struct lttng_process_attr_values *values, - unsigned int index, - gid_t *gid); +lttng_process_attr_values_get_gid_at_index(const struct lttng_process_attr_values *values, + unsigned int index, + gid_t *gid); /* * Get a group name process attribute value. @@ -567,10 +541,9 @@ lttng_process_attr_values_get_gid_at_index( * is not a group name. */ LTTNG_EXPORT extern enum lttng_process_attr_values_status -lttng_process_attr_values_get_group_name_at_index( - const struct lttng_process_attr_values *values, - unsigned int index, - const char **group_name); +lttng_process_attr_values_get_group_name_at_index(const struct lttng_process_attr_values *values, + unsigned int index, + const char **group_name); /* The following entry points are deprecated. */ @@ -589,10 +562,8 @@ lttng_process_attr_values_get_group_name_at_index( * * Returns 0 on success, else a negative LTTng error code. */ -LTTNG_EXPORT extern int lttng_list_tracker_pids(struct lttng_handle *handle, - int *enabled, - int32_t **pids, - size_t *nr_pids); +LTTNG_EXPORT extern int +lttng_list_tracker_pids(struct lttng_handle *handle, int *enabled, int32_t **pids, size_t *nr_pids); /* * Deprecated: see `lttng_process_attr_process_id_tracker_handle_add_pid`. diff --git a/include/lttng/trigger/trigger-internal.hpp b/include/lttng/trigger/trigger-internal.hpp index a05a36ed3..c0aa3506a 100644 --- a/include/lttng/trigger/trigger-internal.hpp +++ b/include/lttng/trigger/trigger-internal.hpp @@ -12,7 +12,9 @@ #include #include #include + #include + #include #include #include @@ -107,26 +109,21 @@ struct lttng_triggers_comm { }; ssize_t lttng_trigger_create_from_payload(struct lttng_payload_view *view, - struct lttng_trigger **trigger); + struct lttng_trigger **trigger); -int lttng_trigger_serialize(const struct lttng_trigger *trigger, - struct lttng_payload *payload); +int lttng_trigger_serialize(const struct lttng_trigger *trigger, struct lttng_payload *payload); bool lttng_trigger_validate(const struct lttng_trigger *trigger); -int lttng_trigger_assign_name( - struct lttng_trigger *dst, const struct lttng_trigger *src); +int lttng_trigger_assign_name(struct lttng_trigger *dst, const struct lttng_trigger *src); -void lttng_trigger_set_tracer_token( - struct lttng_trigger *trigger, uint64_t token); +void lttng_trigger_set_tracer_token(struct lttng_trigger *trigger, uint64_t token); uint64_t lttng_trigger_get_tracer_token(const struct lttng_trigger *trigger); -int lttng_trigger_generate_name(struct lttng_trigger *trigger, - uint64_t unique_id); +int lttng_trigger_generate_name(struct lttng_trigger *trigger, uint64_t unique_id); -bool lttng_trigger_is_equal( - const struct lttng_trigger *a, const struct lttng_trigger *b); +bool lttng_trigger_is_equal(const struct lttng_trigger *a, const struct lttng_trigger *b); bool lttng_trigger_is_hidden(const struct lttng_trigger *trigger); @@ -140,16 +137,16 @@ void lttng_trigger_put(struct lttng_trigger *trigger); * Serialize a trigger to a mi_writer. * Return LTTNG_OK in success, other enum lttng_error_code on error. */ -enum lttng_error_code lttng_trigger_mi_serialize(const struct lttng_trigger *trigger, - struct mi_writer *writer, - const struct mi_lttng_error_query_callbacks - *error_query_callbacks); +enum lttng_error_code +lttng_trigger_mi_serialize(const struct lttng_trigger *trigger, + struct mi_writer *writer, + const struct mi_lttng_error_query_callbacks *error_query_callbacks); /* * Allocate a new set of triggers. * The returned object must be freed via lttng_triggers_destroy. */ -struct lttng_triggers *lttng_triggers_create(void); +struct lttng_triggers *lttng_triggers_create(); /* * Return the a pointer to a mutable element at index "index" of an @@ -161,8 +158,8 @@ struct lttng_triggers *lttng_triggers_create(void); * The ownership of the trigger set element is NOT transfered. * The returned object can NOT be freed via lttng_trigger_destroy. */ -struct lttng_trigger *lttng_triggers_borrow_mutable_at_index( - const struct lttng_triggers *triggers, unsigned int index); +struct lttng_trigger *lttng_triggers_borrow_mutable_at_index(const struct lttng_triggers *triggers, + unsigned int index); /* * Add a trigger to the triggers set. @@ -170,8 +167,7 @@ struct lttng_trigger *lttng_triggers_borrow_mutable_at_index( * A reference to the added trigger is acquired on behalf of the trigger set * on success. */ -int lttng_triggers_add( - struct lttng_triggers *triggers, struct lttng_trigger *trigger); +int lttng_triggers_add(struct lttng_triggers *triggers, struct lttng_trigger *trigger); /* * Remove all triggers marked as hidden from the provided trigger set. @@ -182,41 +178,38 @@ int lttng_triggers_remove_hidden_triggers(struct lttng_triggers *triggers); * Serialize a trigger set to an lttng_payload object. * Return LTTNG_OK on success, negative lttng error code on error. */ -int lttng_triggers_serialize(const struct lttng_triggers *triggers, - struct lttng_payload *payload); +int lttng_triggers_serialize(const struct lttng_triggers *triggers, struct lttng_payload *payload); ssize_t lttng_triggers_create_from_payload(struct lttng_payload_view *view, - struct lttng_triggers **triggers); + struct lttng_triggers **triggers); /* * Serialize a trigger set to a mi_writer. * Return LTTNG_OK in success, other enum lttng_error_code on error. */ -enum lttng_error_code lttng_triggers_mi_serialize(const struct lttng_triggers *triggers, - struct mi_writer *writer, - const struct mi_lttng_error_query_callbacks - *error_query_callbacks); +enum lttng_error_code +lttng_triggers_mi_serialize(const struct lttng_triggers *triggers, + struct mi_writer *writer, + const struct mi_lttng_error_query_callbacks *error_query_callbacks); -const struct lttng_credentials *lttng_trigger_get_credentials( - const struct lttng_trigger *trigger); +const struct lttng_credentials *lttng_trigger_get_credentials(const struct lttng_trigger *trigger); void lttng_trigger_set_credentials(struct lttng_trigger *trigger, - const struct lttng_credentials *creds); + const struct lttng_credentials *creds); /* * Return the type of any underlying domain restriction. If no particular * requirement is present, returns LTTNG_DOMAIN_NONE. */ -enum lttng_domain_type lttng_trigger_get_underlying_domain_type_restriction( - const struct lttng_trigger *trigger); +enum lttng_domain_type +lttng_trigger_get_underlying_domain_type_restriction(const struct lttng_trigger *trigger); /* * Generate any bytecode related to the trigger. * On success LTTNG_OK. On error, returns lttng_error code. */ -enum lttng_error_code lttng_trigger_generate_bytecode( - struct lttng_trigger *trigger, - const struct lttng_credentials *creds); +enum lttng_error_code lttng_trigger_generate_bytecode(struct lttng_trigger *trigger, + const struct lttng_credentials *creds); /* * Note that the trigger object is not locked by "copy" as it is const and @@ -253,17 +246,17 @@ void lttng_trigger_lock(struct lttng_trigger *trigger); void lttng_trigger_unlock(struct lttng_trigger *trigger); -enum lttng_trigger_status lttng_trigger_add_error_results( - const struct lttng_trigger *trigger, - struct lttng_error_query_results *results); +enum lttng_trigger_status +lttng_trigger_add_error_results(const struct lttng_trigger *trigger, + struct lttng_error_query_results *results); -enum lttng_trigger_status lttng_trigger_condition_add_error_results( - const struct lttng_trigger *trigger, - struct lttng_error_query_results *results); +enum lttng_trigger_status +lttng_trigger_condition_add_error_results(const struct lttng_trigger *trigger, + struct lttng_error_query_results *results); -enum lttng_trigger_status lttng_trigger_add_action_error_query_results( - struct lttng_trigger *trigger, - struct lttng_error_query_results *results); +enum lttng_trigger_status +lttng_trigger_add_action_error_query_results(struct lttng_trigger *trigger, + struct lttng_error_query_results *results); /* * Set the trigger name. @@ -276,7 +269,6 @@ enum lttng_trigger_status lttng_trigger_add_action_error_query_results( * Return LTTNG_TRIGGER_STATUS_OK on success, LTTNG_TRIGGER_STATUS_INVALID * if invalid parameters are passed. */ -enum lttng_trigger_status lttng_trigger_set_name( - struct lttng_trigger *trigger, const char *name); +enum lttng_trigger_status lttng_trigger_set_name(struct lttng_trigger *trigger, const char *name); #endif /* LTTNG_TRIGGER_INTERNAL_H */ diff --git a/include/lttng/trigger/trigger.h b/include/lttng/trigger/trigger.h index 0a944a15a..18ab06e50 100644 --- a/include/lttng/trigger/trigger.h +++ b/include/lttng/trigger/trigger.h @@ -8,12 +8,13 @@ #ifndef LTTNG_TRIGGER_H #define LTTNG_TRIGGER_H -#include #include -#include #include #include +#include +#include + struct lttng_action; struct lttng_condition; struct lttng_trigger; @@ -63,8 +64,8 @@ enum lttng_trigger_status { * Trigger objects must be destroyed using the lttng_trigger_destroy() * function. */ -LTTNG_EXPORT extern struct lttng_trigger *lttng_trigger_create( - struct lttng_condition *condition, struct lttng_action *action); +LTTNG_EXPORT extern struct lttng_trigger *lttng_trigger_create(struct lttng_condition *condition, + struct lttng_action *action); /* * Set the user identity (uid) of a trigger. @@ -75,8 +76,8 @@ LTTNG_EXPORT extern struct lttng_trigger *lttng_trigger_create( * LTTNG_TRIGGER_STATUS_EPERM if not authorized, * LTTNG_TRIGGER_STATUS_INVALID if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_trigger_status lttng_trigger_set_owner_uid( - struct lttng_trigger *trigger, uid_t uid); +LTTNG_EXPORT extern enum lttng_trigger_status +lttng_trigger_set_owner_uid(struct lttng_trigger *trigger, uid_t uid); /* * Get the user identity (uid) of a trigger. @@ -85,8 +86,8 @@ LTTNG_EXPORT extern enum lttng_trigger_status lttng_trigger_set_owner_uid( * LTTNG_TRIGGER_STATUS_UNSET if unset, * LTTNG_TRIGGER_STATUS_INVALID if invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_trigger_status lttng_trigger_get_owner_uid( - const struct lttng_trigger *trigger, uid_t *uid); +LTTNG_EXPORT extern enum lttng_trigger_status +lttng_trigger_get_owner_uid(const struct lttng_trigger *trigger, uid_t *uid); /* * Get the condition of a trigger. @@ -95,11 +96,11 @@ LTTNG_EXPORT extern enum lttng_trigger_status lttng_trigger_get_owner_uid( * * Returns a condition on success, NULL on error. */ -LTTNG_EXPORT extern struct lttng_condition *lttng_trigger_get_condition( - struct lttng_trigger *trigger); +LTTNG_EXPORT extern struct lttng_condition * +lttng_trigger_get_condition(struct lttng_trigger *trigger); -LTTNG_EXPORT extern const struct lttng_condition *lttng_trigger_get_const_condition( - const struct lttng_trigger *trigger); +LTTNG_EXPORT extern const struct lttng_condition * +lttng_trigger_get_const_condition(const struct lttng_trigger *trigger); /* * Get the action of a trigger. @@ -108,11 +109,10 @@ LTTNG_EXPORT extern const struct lttng_condition *lttng_trigger_get_const_condit * * Returns an action on success, NULL on error. */ -LTTNG_EXPORT extern struct lttng_action *lttng_trigger_get_action( - struct lttng_trigger *trigger); +LTTNG_EXPORT extern struct lttng_action *lttng_trigger_get_action(struct lttng_trigger *trigger); -LTTNG_EXPORT extern const struct lttng_action *lttng_trigger_get_const_action( - const struct lttng_trigger *trigger); +LTTNG_EXPORT extern const struct lttng_action * +lttng_trigger_get_const_action(const struct lttng_trigger *trigger); /* * Get the name of a trigger. @@ -125,8 +125,8 @@ LTTNG_EXPORT extern const struct lttng_action *lttng_trigger_get_const_action( * success, LTTNG_TRIGGER_STATUS_INVALID if an invalid parameter is passed, * or LTTNG_TRIGGER_STATUS_UNSET if the trigger is unnamed. */ -LTTNG_EXPORT extern enum lttng_trigger_status lttng_trigger_get_name( - const struct lttng_trigger *trigger, const char **name); +LTTNG_EXPORT extern enum lttng_trigger_status +lttng_trigger_get_name(const struct lttng_trigger *trigger, const char **name); /* * Destroy (frees) a trigger object. @@ -141,9 +141,8 @@ LTTNG_EXPORT extern void lttng_trigger_destroy(struct lttng_trigger *trigger); * * Returns an LTTng status code. */ -LTTNG_EXPORT extern enum lttng_error_code lttng_register_trigger_with_name( - struct lttng_trigger *trigger, - const char *name); +LTTNG_EXPORT extern enum lttng_error_code +lttng_register_trigger_with_name(struct lttng_trigger *trigger, const char *name); /* * Register a trigger to the session daemon, generating a unique name for its @@ -155,8 +154,8 @@ LTTNG_EXPORT extern enum lttng_error_code lttng_register_trigger_with_name( * * Returns an LTTng status code. */ -LTTNG_EXPORT extern enum lttng_error_code lttng_register_trigger_with_automatic_name( - struct lttng_trigger *trigger); +LTTNG_EXPORT extern enum lttng_error_code +lttng_register_trigger_with_automatic_name(struct lttng_trigger *trigger); /* * Unregister a trigger from the session daemon. @@ -177,8 +176,7 @@ LTTNG_EXPORT extern int lttng_unregister_trigger(const struct lttng_trigger *tri * * Returns LTTNG_OK on success, else a suitable LTTng error code. */ -LTTNG_EXPORT extern enum lttng_error_code lttng_list_triggers( - struct lttng_triggers **triggers); +LTTNG_EXPORT extern enum lttng_error_code lttng_list_triggers(struct lttng_triggers **triggers); /* * Get a trigger from the set at a given index. @@ -189,8 +187,8 @@ LTTNG_EXPORT extern enum lttng_error_code lttng_list_triggers( * * Returns a trigger, or NULL on error. */ -LTTNG_EXPORT extern const struct lttng_trigger *lttng_triggers_get_at_index( - const struct lttng_triggers *triggers, unsigned int index); +LTTNG_EXPORT extern const struct lttng_trigger * +lttng_triggers_get_at_index(const struct lttng_triggers *triggers, unsigned int index); /* * Get the number of triggers in a trigger set. @@ -198,8 +196,8 @@ LTTNG_EXPORT extern const struct lttng_trigger *lttng_triggers_get_at_index( * Return LTTNG_TRIGGER_STATUS_OK on success, * LTTNG_TRIGGER_STATUS_INVALID when invalid parameters are passed. */ -LTTNG_EXPORT extern enum lttng_trigger_status lttng_triggers_get_count( - const struct lttng_triggers *triggers, unsigned int *count); +LTTNG_EXPORT extern enum lttng_trigger_status +lttng_triggers_get_count(const struct lttng_triggers *triggers, unsigned int *count); /* * Destroy a trigger set. diff --git a/include/lttng/userspace-probe-internal.hpp b/include/lttng/userspace-probe-internal.hpp index 392242dae..016aeb1c6 100644 --- a/include/lttng/userspace-probe-internal.hpp +++ b/include/lttng/userspace-probe-internal.hpp @@ -9,9 +9,12 @@ #ifndef LTTNG_USERSPACE_PROBE_INTERNAL_H #define LTTNG_USERSPACE_PROBE_INTERNAL_H -#include -#include #include +#include + +#include +#include + #include struct lttng_payload; @@ -19,14 +22,12 @@ struct lttng_payload_view; struct lttng_dynamic_buffer; struct mi_writer; -typedef bool (*userspace_probe_location_equal_cb)( - const struct lttng_userspace_probe_location *a, - const struct lttng_userspace_probe_location *b); -typedef unsigned long (*userspace_probe_location_hash_cb)( - const struct lttng_userspace_probe_location *location); -typedef enum lttng_error_code (*userspace_probe_location_mi)( - const struct lttng_userspace_probe_location *location, - struct mi_writer); +using userspace_probe_location_equal_cb = bool (*)(const struct lttng_userspace_probe_location *, + const struct lttng_userspace_probe_location *); +using userspace_probe_location_hash_cb = + unsigned long (*)(const struct lttng_userspace_probe_location *); +using userspace_probe_location_mi = + enum lttng_error_code (*)(const struct lttng_userspace_probe_location *, struct mi_writer); /* * No elf-specific comm structure is defined since no elf-specific payload is @@ -124,39 +125,35 @@ struct lttng_userspace_probe_location_tracepoint { struct fd_handle *binary_fd_handle; }; -int lttng_userspace_probe_location_serialize( - const struct lttng_userspace_probe_location *location, - struct lttng_payload *payload); +int lttng_userspace_probe_location_serialize(const struct lttng_userspace_probe_location *location, + struct lttng_payload *payload); int lttng_userspace_probe_location_create_from_payload( - struct lttng_payload_view *view, - struct lttng_userspace_probe_location **probe_location); + struct lttng_payload_view *view, struct lttng_userspace_probe_location **probe_location); /* * Returns a version of the location that is serialized to a contiguous region * of memory. Pass NULL to buffer to only get the storage requirement of the * flattened userspace probe location. */ -int lttng_userspace_probe_location_flatten( - const struct lttng_userspace_probe_location *location, - struct lttng_dynamic_buffer *buffer); +int lttng_userspace_probe_location_flatten(const struct lttng_userspace_probe_location *location, + struct lttng_dynamic_buffer *buffer); -struct lttng_userspace_probe_location *lttng_userspace_probe_location_copy( - const struct lttng_userspace_probe_location *location); +struct lttng_userspace_probe_location * +lttng_userspace_probe_location_copy(const struct lttng_userspace_probe_location *location); bool lttng_userspace_probe_location_lookup_method_is_equal( - const struct lttng_userspace_probe_location_lookup_method *a, - const struct lttng_userspace_probe_location_lookup_method *b); + const struct lttng_userspace_probe_location_lookup_method *a, + const struct lttng_userspace_probe_location_lookup_method *b); -bool lttng_userspace_probe_location_is_equal( - const struct lttng_userspace_probe_location *a, - const struct lttng_userspace_probe_location *b); +bool lttng_userspace_probe_location_is_equal(const struct lttng_userspace_probe_location *a, + const struct lttng_userspace_probe_location *b); -unsigned long lttng_userspace_probe_location_hash( - const struct lttng_userspace_probe_location *location); +unsigned long +lttng_userspace_probe_location_hash(const struct lttng_userspace_probe_location *location); -enum lttng_error_code lttng_userspace_probe_location_mi_serialize( - const struct lttng_userspace_probe_location *location, - struct mi_writer *writer); +enum lttng_error_code +lttng_userspace_probe_location_mi_serialize(const struct lttng_userspace_probe_location *location, + struct mi_writer *writer); #endif /* LTTNG_USERSPACE_PROBE_INTERNAL_H */ diff --git a/include/lttng/userspace-probe.h b/include/lttng/userspace-probe.h index b6fc13508..7de667efc 100644 --- a/include/lttng/userspace-probe.h +++ b/include/lttng/userspace-probe.h @@ -21,10 +21,10 @@ extern "C" { struct lttng_userspace_probe_location_lookup_method; enum lttng_userspace_probe_location_lookup_method_type { - LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_UNKNOWN = -1, - LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_FUNCTION_DEFAULT = 0, - LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_FUNCTION_ELF = 1, - LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_TRACEPOINT_SDT = 2, + LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_UNKNOWN = -1, + LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_FUNCTION_DEFAULT = 0, + LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_FUNCTION_ELF = 1, + LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_TRACEPOINT_SDT = 2, }; /* @@ -32,13 +32,13 @@ enum lttng_userspace_probe_location_lookup_method_type { */ LTTNG_EXPORT extern enum lttng_userspace_probe_location_lookup_method_type lttng_userspace_probe_location_lookup_method_get_type( - const struct lttng_userspace_probe_location_lookup_method *lookup_method); + const struct lttng_userspace_probe_location_lookup_method *lookup_method); /* * Destroy a lookup method. */ LTTNG_EXPORT extern void lttng_userspace_probe_location_lookup_method_destroy( - struct lttng_userspace_probe_location_lookup_method *lookup_method); + struct lttng_userspace_probe_location_lookup_method *lookup_method); /* * Create a tracepoint ELF function lookup method struct. @@ -54,7 +54,6 @@ lttng_userspace_probe_location_lookup_method_function_elf_create(void); LTTNG_EXPORT extern struct lttng_userspace_probe_location_lookup_method * lttng_userspace_probe_location_lookup_method_tracepoint_sdt_create(void); - /* * Contains all the information needed to compute the instrumentation point in * the binary. It is used in conjonction with a lookup method. @@ -62,32 +61,30 @@ lttng_userspace_probe_location_lookup_method_tracepoint_sdt_create(void); struct lttng_userspace_probe_location; enum lttng_userspace_probe_location_status { - LTTNG_USERSPACE_PROBE_LOCATION_STATUS_OK = 0, + LTTNG_USERSPACE_PROBE_LOCATION_STATUS_OK = 0, /* Invalid parameters provided. */ - LTTNG_USERSPACE_PROBE_LOCATION_STATUS_INVALID = -1, + LTTNG_USERSPACE_PROBE_LOCATION_STATUS_INVALID = -1, }; enum lttng_userspace_probe_location_type { - LTTNG_USERSPACE_PROBE_LOCATION_TYPE_UNKNOWN = -1, + LTTNG_USERSPACE_PROBE_LOCATION_TYPE_UNKNOWN = -1, /* Function. */ - LTTNG_USERSPACE_PROBE_LOCATION_TYPE_FUNCTION = 0, + LTTNG_USERSPACE_PROBE_LOCATION_TYPE_FUNCTION = 0, /* SDT probe's callsites. */ - LTTNG_USERSPACE_PROBE_LOCATION_TYPE_TRACEPOINT = 1, + LTTNG_USERSPACE_PROBE_LOCATION_TYPE_TRACEPOINT = 1, }; /* * Get the type of the userspace probe location. */ LTTNG_EXPORT extern enum lttng_userspace_probe_location_type -lttng_userspace_probe_location_get_type( - const struct lttng_userspace_probe_location *location); +lttng_userspace_probe_location_get_type(const struct lttng_userspace_probe_location *location); /* * Destroy the userspace probe location. */ -LTTNG_EXPORT extern void lttng_userspace_probe_location_destroy( - struct lttng_userspace_probe_location *location); - +LTTNG_EXPORT extern void +lttng_userspace_probe_location_destroy(struct lttng_userspace_probe_location *location); enum lttng_userspace_probe_location_function_instrumentation_type { LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_UNKNOWN = -1, @@ -104,35 +101,36 @@ enum lttng_userspace_probe_location_function_instrumentation_type { * location. */ LTTNG_EXPORT extern struct lttng_userspace_probe_location * -lttng_userspace_probe_location_function_create(const char *binary_path, - const char *function_name, - struct lttng_userspace_probe_location_lookup_method *lookup_method); +lttng_userspace_probe_location_function_create( + const char *binary_path, + const char *function_name, + struct lttng_userspace_probe_location_lookup_method *lookup_method); /* * Get the target binary path of the probe location of the function type. */ LTTNG_EXPORT extern const char *lttng_userspace_probe_location_function_get_binary_path( - const struct lttng_userspace_probe_location *location); + const struct lttng_userspace_probe_location *location); /* * Get the target function type of the probe location of the function type. */ LTTNG_EXPORT extern const char *lttng_userspace_probe_location_function_get_function_name( - const struct lttng_userspace_probe_location *location); + const struct lttng_userspace_probe_location *location); /* * Get the FD to the target binary file to the probe location of the function * type. The FD is only valid for the duration of the lifetime of `location`. */ LTTNG_EXPORT extern int lttng_userspace_probe_location_function_get_binary_fd( - const struct lttng_userspace_probe_location *location); + const struct lttng_userspace_probe_location *location); /* * Get the instrumentation type of the function probe location. */ LTTNG_EXPORT extern enum lttng_userspace_probe_location_function_instrumentation_type lttng_userspace_probe_location_function_get_instrumentation_type( - const struct lttng_userspace_probe_location *location); + const struct lttng_userspace_probe_location *location); /* * Get the instrumentation type of the function probe location. @@ -145,8 +143,8 @@ lttng_userspace_probe_location_function_get_instrumentation_type( */ LTTNG_EXPORT extern enum lttng_userspace_probe_location_status lttng_userspace_probe_location_function_set_instrumentation_type( - const struct lttng_userspace_probe_location *location, - enum lttng_userspace_probe_location_function_instrumentation_type instrumentation_type); + const struct lttng_userspace_probe_location *location, + enum lttng_userspace_probe_location_function_instrumentation_type instrumentation_type); /* * Get the lookup method of the given userspace probe location. @@ -156,7 +154,7 @@ lttng_userspace_probe_location_function_set_instrumentation_type( */ LTTNG_EXPORT extern const struct lttng_userspace_probe_location_lookup_method * lttng_userspace_probe_location_get_lookup_method( - const struct lttng_userspace_probe_location *location); + const struct lttng_userspace_probe_location *location); /* * Create a probe location of the tracepoint type. @@ -168,35 +166,37 @@ lttng_userspace_probe_location_get_lookup_method( * location. */ LTTNG_EXPORT extern struct lttng_userspace_probe_location * -lttng_userspace_probe_location_tracepoint_create(const char *binary_path, - const char *probe_name, const char *provider_name, - struct lttng_userspace_probe_location_lookup_method *lookup_method); +lttng_userspace_probe_location_tracepoint_create( + const char *binary_path, + const char *probe_name, + const char *provider_name, + struct lttng_userspace_probe_location_lookup_method *lookup_method); /* * Get the target binary path of the probe location of the tracepoint type. */ LTTNG_EXPORT extern const char *lttng_userspace_probe_location_tracepoint_get_binary_path( - const struct lttng_userspace_probe_location *location); + const struct lttng_userspace_probe_location *location); /* * Get the target probe name of the probe location of the tracepoint type. */ LTTNG_EXPORT extern const char *lttng_userspace_probe_location_tracepoint_get_probe_name( - const struct lttng_userspace_probe_location *location); + const struct lttng_userspace_probe_location *location); /* * Get the target probe provider name of the probe location of the tracepoint * type. */ LTTNG_EXPORT extern const char *lttng_userspace_probe_location_tracepoint_get_provider_name( - const struct lttng_userspace_probe_location *location); + const struct lttng_userspace_probe_location *location); /* * Get the FD to the target binary file to the probe location of the tracepoint * type. The FD is only valid for the duration of the lifetime of `location`. */ LTTNG_EXPORT extern int lttng_userspace_probe_location_tracepoint_get_binary_fd( - const struct lttng_userspace_probe_location *location); + const struct lttng_userspace_probe_location *location); #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/pre-inst-env.in b/pre-inst-env.in new file mode 100644 index 000000000..f779aa453 --- /dev/null +++ b/pre-inst-env.in @@ -0,0 +1,39 @@ +#!/bin/sh +# SPDX-License-Identifier: GPL-2.0-only +# +# Copyright (c) 2023 Olivier Dion + +srcdir=$(realpath "@abs_top_srcdir@") +builddir=$(realpath "@abs_top_builddir@") +bin="$builddir/src/bin" + +# lttng-sessiond setup. +LTTNG_SESSION_CONFIG_XSD_PATH="$srcdir/src/common" +export LTTNG_SESSION_CONFIG_XSD_PATH + +LTTNG_CONSUMERD32_BIN="$bin/lttng-consumerd/lttng-consumerd" +LTTNG_CONSUMERD64_BIN="$bin/lttng-consumerd/lttng-consumerd" +export LTTNG_CONSUMERD32_BIN +export LTTNG_CONSUMERD64_BIN + +# lttng-create setup. +LTTNG_SESSIOND_PATH="$bin/lttng-sessiond/lttng-sessiond" +export LTTNG_SESSIOND_PATH + +# Easy access to binaries. +PATH="$bin/lttng:$bin/lttng-consumerd:$bin/lttng-crash:$bin/lttng-relayd:$bin/lttng-sessiond:$PATH" +export PATH + +# Use local path to search manual pages. +MANPATH="$builddir/doc/man" +export MANPATH + +# Use local path to search manual pages for lttng --help. +LTTNG_MANPATH="$builddir/doc/man" +export LTTNG_MANPATH + +# Use system man instead of /usr/bin/man. +LTTNG_MAN_BIN_PATH=$(type -p man) +export LTTNG_MAN_BIN_PATH + +exec "$@" diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 000000000..28c78a076 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,4 @@ +[project] +requires-python = ">= 3.4" + +[tool.black] diff --git a/src/bin/lttng-consumerd/health-consumerd.cpp b/src/bin/lttng-consumerd/health-consumerd.cpp index 8417fc6dc..d0a6ce14f 100644 --- a/src/bin/lttng-consumerd/health-consumerd.cpp +++ b/src/bin/lttng-consumerd/health-consumerd.cpp @@ -6,59 +6,44 @@ */ #define _LGPL_SOURCE +#include "health-consumerd.hpp" +#include "lttng-consumerd.hpp" + +#include +#include +#include +#include +#include +#include +#include + #include #include #include +#include #include +#include #include #include #include #include #include #include +#include #include #include #include #include #include -#include -#include +#include #include -#include #include -#include -#include - -#include -#include -#include -#include -#include -#include -#include - -#include "lttng-consumerd.hpp" -#include "health-consumerd.hpp" +#include /* Global health check unix path */ static char health_unix_sock_path[PATH_MAX]; -int health_quit_pipe[2]; - -/* - * Check if the thread quit pipe was triggered. - * - * Return 1 if it was triggered else 0; - */ -static -int check_health_quit_pipe(int fd, uint32_t events) -{ - if (fd == health_quit_pipe[0] && (events & LPOLLIN)) { - return 1; - } - - return 0; -} +int health_quit_pipe[2] = { -1, -1 }; /* * Send data on a unix socket using the liblttsessiondcomm API. @@ -75,8 +60,7 @@ static int send_unix_sock(int sock, void *buf, size_t len) return lttcomm_send_unix_sock(sock, buf, len); } -static -int setup_health_path(void) +static int setup_health_path() { int is_root, ret = 0; enum lttng_consumer_type type; @@ -91,16 +75,19 @@ int setup_health_path(void) } switch (type) { case LTTNG_CONSUMER_KERNEL: - snprintf(health_unix_sock_path, sizeof(health_unix_sock_path), - DEFAULT_GLOBAL_KCONSUMER_HEALTH_UNIX_SOCK); + snprintf(health_unix_sock_path, + sizeof(health_unix_sock_path), + DEFAULT_GLOBAL_KCONSUMER_HEALTH_UNIX_SOCK); break; case LTTNG_CONSUMER64_UST: - snprintf(health_unix_sock_path, sizeof(health_unix_sock_path), - DEFAULT_GLOBAL_USTCONSUMER64_HEALTH_UNIX_SOCK); + snprintf(health_unix_sock_path, + sizeof(health_unix_sock_path), + DEFAULT_GLOBAL_USTCONSUMER64_HEALTH_UNIX_SOCK); break; case LTTNG_CONSUMER32_UST: - snprintf(health_unix_sock_path, sizeof(health_unix_sock_path), - DEFAULT_GLOBAL_USTCONSUMER32_HEALTH_UNIX_SOCK); + snprintf(health_unix_sock_path, + sizeof(health_unix_sock_path), + DEFAULT_GLOBAL_USTCONSUMER32_HEALTH_UNIX_SOCK); break; default: ret = -EINVAL; @@ -108,7 +95,7 @@ int setup_health_path(void) } } else { home_path = utils_get_home_dir(); - if (home_path == NULL) { + if (home_path == nullptr) { /* TODO: Add --socket PATH option */ ERR("Can't get HOME directory for sockets creation."); ret = -EPERM; @@ -121,16 +108,22 @@ int setup_health_path(void) } switch (type) { case LTTNG_CONSUMER_KERNEL: - snprintf(health_unix_sock_path, sizeof(health_unix_sock_path), - DEFAULT_HOME_KCONSUMER_HEALTH_UNIX_SOCK, home_path); + snprintf(health_unix_sock_path, + sizeof(health_unix_sock_path), + DEFAULT_HOME_KCONSUMER_HEALTH_UNIX_SOCK, + home_path); break; case LTTNG_CONSUMER64_UST: - snprintf(health_unix_sock_path, sizeof(health_unix_sock_path), - DEFAULT_HOME_USTCONSUMER64_HEALTH_UNIX_SOCK, home_path); + snprintf(health_unix_sock_path, + sizeof(health_unix_sock_path), + DEFAULT_HOME_USTCONSUMER64_HEALTH_UNIX_SOCK, + home_path); break; case LTTNG_CONSUMER32_UST: - snprintf(health_unix_sock_path, sizeof(health_unix_sock_path), - DEFAULT_HOME_USTCONSUMER32_HEALTH_UNIX_SOCK, home_path); + snprintf(health_unix_sock_path, + sizeof(health_unix_sock_path), + DEFAULT_HOME_USTCONSUMER32_HEALTH_UNIX_SOCK, + home_path); break; default: ret = -EINVAL; @@ -146,8 +139,8 @@ end: */ void *thread_manage_health_consumerd(void *data __attribute__((unused))) { - int sock = -1, new_sock = -1, ret, i, pollfd, err = -1; - uint32_t revents, nb_fd; + int sock = -1, new_sock = -1, ret, i, err = -1; + uint32_t nb_fd; struct lttng_poll_event events; struct health_comm_msg msg; struct health_comm_reply reply; @@ -189,8 +182,7 @@ void *thread_manage_health_consumerd(void *data __attribute__((unused))) goto error; } - ret = chmod(health_unix_sock_path, - S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP); + ret = chmod(health_unix_sock_path, S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP); if (ret < 0) { ERR("Unable to set permissions on %s", health_unix_sock_path); PERROR("chmod"); @@ -232,11 +224,11 @@ void *thread_manage_health_consumerd(void *data __attribute__((unused))) cmm_smp_mb__before_uatomic_dec(); uatomic_dec(<tng_consumer_ready); - while (1) { + while (true) { DBG("Health check ready"); /* Inifinite blocking call, waiting for transmission */ -restart: + restart: ret = lttng_poll_wait(&events, -1); if (ret < 0) { /* @@ -252,20 +244,20 @@ restart: for (i = 0; i < nb_fd; i++) { /* Fetch once the poll data */ - revents = LTTNG_POLL_GETEV(&events, i); - pollfd = LTTNG_POLL_GETFD(&events, i); + const auto revents = LTTNG_POLL_GETEV(&events, i); + const auto pollfd = LTTNG_POLL_GETFD(&events, i); - /* Thread quit pipe has been closed. Killing thread. */ - ret = check_health_quit_pipe(pollfd, revents); - if (ret) { + /* Activity on health quit pipe, exiting. */ + if (pollfd == health_quit_pipe[0]) { + DBG("Activity on health quit pipe"); err = 0; goto exit; } /* Event on the registration socket */ if (pollfd == sock) { - if (revents & (LPOLLERR | LPOLLHUP | LPOLLRDHUP) - && !(revents & LPOLLIN)) { + if (revents & (LPOLLERR | LPOLLHUP | LPOLLRDHUP) && + !(revents & LPOLLIN)) { ERR("Health socket poll error"); goto error; } @@ -284,7 +276,7 @@ restart: (void) utils_set_fd_cloexec(new_sock); DBG("Receiving data from client for health..."); - ret = lttcomm_recv_unix_sock(new_sock, (void *)&msg, sizeof(msg)); + ret = lttcomm_recv_unix_sock(new_sock, (void *) &msg, sizeof(msg)); if (ret <= 0) { DBG("Nothing recv() from client... continuing"); ret = close(new_sock); @@ -342,5 +334,5 @@ error: lttng_poll_clean(&events); rcu_unregister_thread(); - return NULL; + return nullptr; } diff --git a/src/bin/lttng-consumerd/health-consumerd.hpp b/src/bin/lttng-consumerd/health-consumerd.hpp index 4e3bf8686..109ccb4c4 100644 --- a/src/bin/lttng-consumerd/health-consumerd.hpp +++ b/src/bin/lttng-consumerd/health-consumerd.hpp @@ -11,11 +11,11 @@ #include enum health_type_consumerd { - HEALTH_CONSUMERD_TYPE_CHANNEL = 0, - HEALTH_CONSUMERD_TYPE_METADATA = 1, - HEALTH_CONSUMERD_TYPE_DATA = 2, - HEALTH_CONSUMERD_TYPE_SESSIOND = 3, - HEALTH_CONSUMERD_TYPE_METADATA_TIMER = 4, + HEALTH_CONSUMERD_TYPE_CHANNEL = 0, + HEALTH_CONSUMERD_TYPE_METADATA = 1, + HEALTH_CONSUMERD_TYPE_DATA = 2, + HEALTH_CONSUMERD_TYPE_SESSIOND = 3, + HEALTH_CONSUMERD_TYPE_METADATA_TIMER = 4, NR_HEALTH_CONSUMERD_TYPES, }; diff --git a/src/bin/lttng-consumerd/lttng-consumerd.cpp b/src/bin/lttng-consumerd/lttng-consumerd.cpp index a8bda52ba..e46b6b671 100644 --- a/src/bin/lttng-consumerd/lttng-consumerd.cpp +++ b/src/bin/lttng-consumerd/lttng-consumerd.cpp @@ -7,53 +7,53 @@ */ #define _LGPL_SOURCE +#include "health-consumerd.hpp" +#include "lttng-consumerd.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include + #include #include #include #include +#include #include #include #include #include #include #include +#include #include #include #include #include #include -#include -#include +#include #include -#include #include -#include - -#include -#include -#include -#include -#include -#include -#include -#include - -#include "lttng-consumerd.hpp" -#include "health-consumerd.hpp" +#include /* threads (channel handling, poll, metadata, sessiond) */ -static pthread_t channel_thread, data_thread, metadata_thread, - sessiond_thread, metadata_timer_thread, health_thread; +static pthread_t channel_thread, data_thread, metadata_thread, sessiond_thread, + metadata_timer_thread, health_thread; static bool metadata_timer_thread_online; /* to count the number of times the user pressed ctrl+c */ static int sigintcount = 0; /* Argument variables */ -int lttng_opt_quiet; /* not static in error.h */ -int lttng_opt_verbose; /* not static in error.h */ -int lttng_opt_mi; /* not static in error.h */ +int lttng_opt_quiet; /* not static in error.h */ +int lttng_opt_verbose; /* not static in error.h */ +int lttng_opt_mi; /* not static in error.h */ static int opt_daemon; static const char *progname; @@ -82,8 +82,7 @@ enum lttng_consumer_type lttng_consumer_get_type(void) /* * Signal handler for the daemon */ -static void sighandler(int sig, siginfo_t *siginfo, - void *arg __attribute__((unused))) +static void sighandler(int sig, siginfo_t *siginfo, void *arg __attribute__((unused))) { if (sig == SIGINT && sigintcount++ == 0) { DBG("ignoring first SIGINT"); @@ -116,7 +115,7 @@ static void sighandler(int sig, siginfo_t *siginfo, * Setup signal handler for : * SIGINT, SIGTERM, SIGPIPE, SIGBUS */ -static int set_signal_handler(void) +static int set_signal_handler() { int ret = 0; struct sigaction sa; @@ -131,24 +130,24 @@ static int set_signal_handler(void) sa.sa_flags = SA_SIGINFO; sa.sa_sigaction = sighandler; - if ((ret = sigaction(SIGTERM, &sa, NULL)) < 0) { + if ((ret = sigaction(SIGTERM, &sa, nullptr)) < 0) { PERROR("sigaction"); return ret; } - if ((ret = sigaction(SIGINT, &sa, NULL)) < 0) { + if ((ret = sigaction(SIGINT, &sa, nullptr)) < 0) { PERROR("sigaction"); return ret; } - if ((ret = sigaction(SIGBUS, &sa, NULL)) < 0) { + if ((ret = sigaction(SIGBUS, &sa, nullptr)) < 0) { PERROR("sigaction"); return ret; } sa.sa_flags = 0; sa.sa_handler = SIG_IGN; - if ((ret = sigaction(SIGPIPE, &sa, NULL)) < 0) { + if ((ret = sigaction(SIGPIPE, &sa, nullptr)) < 0) { PERROR("sigaction"); return ret; } @@ -162,32 +161,42 @@ static int set_signal_handler(void) static void usage(FILE *fp) { fprintf(fp, "Usage: %s OPTIONS\n\nOptions:\n", progname); - fprintf(fp, " -h, --help " - "Display this usage.\n"); - fprintf(fp, " -c, --consumerd-cmd-sock PATH " - "Specify path for the command socket\n"); - fprintf(fp, " -e, --consumerd-err-sock PATH " - "Specify path for the error socket\n"); - fprintf(fp, " -d, --daemonize " - "Start as a daemon.\n"); - fprintf(fp, " -q, --quiet " - "No output at all.\n"); - fprintf(fp, " -v, --verbose " - "Verbose mode. Activate DBG() macro.\n"); - fprintf(fp, " -V, --version " - "Show version number.\n"); - fprintf(fp, " -g, --group NAME " - "Specify the tracing group name. (default: tracing)\n"); - fprintf(fp, " -k, --kernel " - "Consumer kernel buffers (default).\n"); - fprintf(fp, " -u, --ust " - "Consumer UST buffers.%s\n", + fprintf(fp, + " -h, --help " + "Display this usage.\n"); + fprintf(fp, + " -c, --consumerd-cmd-sock PATH " + "Specify path for the command socket\n"); + fprintf(fp, + " -e, --consumerd-err-sock PATH " + "Specify path for the error socket\n"); + fprintf(fp, + " -d, --daemonize " + "Start as a daemon.\n"); + fprintf(fp, + " -q, --quiet " + "No output at all.\n"); + fprintf(fp, + " -v, --verbose " + "Verbose mode. Activate DBG() macro.\n"); + fprintf(fp, + " -V, --version " + "Show version number.\n"); + fprintf(fp, + " -g, --group NAME " + "Specify the tracing group name. (default: tracing)\n"); + fprintf(fp, + " -k, --kernel " + "Consumer kernel buffers (default).\n"); + fprintf(fp, + " -u, --ust " + "Consumer UST buffers.%s\n", #ifdef HAVE_LIBLTTNG_UST_CTL - "" + "" #else - " (support not compiled in)" + " (support not compiled in)" #endif - ); + ); } /* @@ -197,34 +206,35 @@ static int parse_args(int argc, char **argv) { int c, ret = 0; - static struct option long_options[] = { - { "consumerd-cmd-sock", 1, 0, 'c' }, - { "consumerd-err-sock", 1, 0, 'e' }, - { "daemonize", 0, 0, 'd' }, - { "group", 1, 0, 'g' }, - { "help", 0, 0, 'h' }, - { "quiet", 0, 0, 'q' }, - { "verbose", 0, 0, 'v' }, - { "version", 0, 0, 'V' }, - { "kernel", 0, 0, 'k' }, + static struct option long_options[] = { { "consumerd-cmd-sock", 1, nullptr, 'c' }, + { "consumerd-err-sock", 1, nullptr, 'e' }, + { "daemonize", 0, nullptr, 'd' }, + { "group", 1, nullptr, 'g' }, + { "help", 0, nullptr, 'h' }, + { "quiet", 0, nullptr, 'q' }, + { "verbose", 0, nullptr, 'v' }, + { "version", 0, nullptr, 'V' }, + { "kernel", 0, nullptr, 'k' }, #ifdef HAVE_LIBLTTNG_UST_CTL - { "ust", 0, 0, 'u' }, + { "ust", 0, nullptr, 'u' }, #endif - { NULL, 0, 0, 0 } - }; + { nullptr, 0, nullptr, 0 } }; - while (1) { + while (true) { int option_index = 0; - c = getopt_long(argc, argv, "dhqvVku" "c:e:g:", - long_options, &option_index); + c = getopt_long(argc, + argv, + "dhqvVku" + "c:e:g:", + long_options, + &option_index); if (c == -1) { break; } switch (c) { case 0: - fprintf(stderr, "option %s", - long_options[option_index].name); + fprintf(stderr, "option %s", long_options[option_index].name); if (optarg) { fprintf(stderr, " with arg %s\n", optarg); ret = -1; @@ -234,7 +244,7 @@ static int parse_args(int argc, char **argv) case 'c': if (lttng_is_setuid_setgid()) { WARN("Getting '%s' argument from setuid/setgid binary refused for security reasons.", - "-c, --consumerd-cmd-sock"); + "-c, --consumerd-cmd-sock"); } else { snprintf(command_sock_path, PATH_MAX, "%s", optarg); } @@ -242,7 +252,7 @@ static int parse_args(int argc, char **argv) case 'e': if (lttng_is_setuid_setgid()) { WARN("Getting '%s' argument from setuid/setgid binary refused for security reasons.", - "-e, --consumerd-err-sock"); + "-e, --consumerd-err-sock"); } else { snprintf(error_sock_path, PATH_MAX, "%s", optarg); } @@ -253,7 +263,7 @@ static int parse_args(int argc, char **argv) case 'g': if (lttng_is_setuid_setgid()) { WARN("Getting '%s' argument from setuid/setgid binary refused for security reasons.", - "-g, --group"); + "-g, --group"); } else { tracing_group_name = optarg; } @@ -275,13 +285,13 @@ static int parse_args(int argc, char **argv) break; #ifdef HAVE_LIBLTTNG_UST_CTL case 'u': -# if (CAA_BITS_PER_LONG == 64) +#if (CAA_BITS_PER_LONG == 64) opt_type = LTTNG_CONSUMER64_UST; -# elif (CAA_BITS_PER_LONG == 32) +#elif (CAA_BITS_PER_LONG == 32) opt_type = LTTNG_CONSUMER32_UST; -# else -# error "Unknown bitness" -# endif +#else +#error "Unknown bitness" +#endif break; #endif default: @@ -298,7 +308,7 @@ end: * Set open files limit to unlimited. This daemon can open a large number of * file descriptors in order to consumer multiple kernel traces. */ -static void set_ulimit(void) +static void set_ulimit() { int ret; struct rlimit lim; @@ -324,7 +334,7 @@ int main(int argc, char **argv) rcu_register_thread(); - if (run_as_create_worker(argv[0], NULL, NULL) < 0) { + if (run_as_create_worker(argv[0], nullptr, nullptr) < 0) { goto exit_set_signal_handler; } @@ -379,27 +389,30 @@ int main(int argc, char **argv) if (*command_sock_path == '\0') { switch (opt_type) { case LTTNG_CONSUMER_KERNEL: - ret = snprintf(command_sock_path, PATH_MAX, - DEFAULT_KCONSUMERD_CMD_SOCK_PATH, - DEFAULT_LTTNG_RUNDIR); + ret = snprintf(command_sock_path, + PATH_MAX, + DEFAULT_KCONSUMERD_CMD_SOCK_PATH, + DEFAULT_LTTNG_RUNDIR); if (ret < 0) { retval = -1; goto exit_init_data; } break; case LTTNG_CONSUMER64_UST: - ret = snprintf(command_sock_path, PATH_MAX, - DEFAULT_USTCONSUMERD64_CMD_SOCK_PATH, - DEFAULT_LTTNG_RUNDIR); + ret = snprintf(command_sock_path, + PATH_MAX, + DEFAULT_USTCONSUMERD64_CMD_SOCK_PATH, + DEFAULT_LTTNG_RUNDIR); if (ret < 0) { retval = -1; goto exit_init_data; } break; case LTTNG_CONSUMER32_UST: - ret = snprintf(command_sock_path, PATH_MAX, - DEFAULT_USTCONSUMERD32_CMD_SOCK_PATH, - DEFAULT_LTTNG_RUNDIR); + ret = snprintf(command_sock_path, + PATH_MAX, + DEFAULT_USTCONSUMERD32_CMD_SOCK_PATH, + DEFAULT_LTTNG_RUNDIR); if (ret < 0) { retval = -1; goto exit_init_data; @@ -429,8 +442,11 @@ int main(int argc, char **argv) } /* create the consumer instance with and assign the callbacks */ - the_consumer_context = lttng_consumer_create(opt_type, lttng_consumer_read_subbuffer, - NULL, lttng_consumer_on_recv_stream, NULL); + the_consumer_context = lttng_consumer_create(opt_type, + lttng_consumer_read_subbuffer, + nullptr, + lttng_consumer_on_recv_stream, + nullptr); if (!the_consumer_context) { retval = -1; goto exit_init_data; @@ -440,27 +456,30 @@ int main(int argc, char **argv) if (*error_sock_path == '\0') { switch (opt_type) { case LTTNG_CONSUMER_KERNEL: - ret = snprintf(error_sock_path, PATH_MAX, - DEFAULT_KCONSUMERD_ERR_SOCK_PATH, - DEFAULT_LTTNG_RUNDIR); + ret = snprintf(error_sock_path, + PATH_MAX, + DEFAULT_KCONSUMERD_ERR_SOCK_PATH, + DEFAULT_LTTNG_RUNDIR); if (ret < 0) { retval = -1; goto exit_init_data; } break; case LTTNG_CONSUMER64_UST: - ret = snprintf(error_sock_path, PATH_MAX, - DEFAULT_USTCONSUMERD64_ERR_SOCK_PATH, - DEFAULT_LTTNG_RUNDIR); + ret = snprintf(error_sock_path, + PATH_MAX, + DEFAULT_USTCONSUMERD64_ERR_SOCK_PATH, + DEFAULT_LTTNG_RUNDIR); if (ret < 0) { retval = -1; goto exit_init_data; } break; case LTTNG_CONSUMER32_UST: - ret = snprintf(error_sock_path, PATH_MAX, - DEFAULT_USTCONSUMERD32_ERR_SOCK_PATH, - DEFAULT_LTTNG_RUNDIR); + ret = snprintf(error_sock_path, + PATH_MAX, + DEFAULT_USTCONSUMERD32_ERR_SOCK_PATH, + DEFAULT_LTTNG_RUNDIR); if (ret < 0) { retval = -1; goto exit_init_data; @@ -502,8 +521,10 @@ int main(int argc, char **argv) } /* Create thread to manage the client socket */ - ret = pthread_create(&health_thread, default_pthread_attr(), - thread_manage_health_consumerd, (void *) NULL); + ret = pthread_create(&health_thread, + default_pthread_attr(), + thread_manage_health_consumerd, + (void *) nullptr); if (ret) { errno = ret; PERROR("pthread_create health"); @@ -518,14 +539,16 @@ int main(int argc, char **argv) while (uatomic_read(<tng_consumer_ready)) { usleep(100000); } - cmm_smp_mb(); /* Read ready before following operations */ + cmm_smp_mb(); /* Read ready before following operations */ /* * Create the thread to manage the UST metadata periodic timer and * live timer. */ - ret = pthread_create(&metadata_timer_thread, NULL, - consumer_timer_thread, (void *) the_consumer_context); + ret = pthread_create(&metadata_timer_thread, + nullptr, + consumer_timer_thread, + (void *) the_consumer_context); if (ret) { errno = ret; PERROR("pthread_create"); @@ -535,9 +558,10 @@ int main(int argc, char **argv) metadata_timer_thread_online = true; /* Create thread to manage channels */ - ret = pthread_create(&channel_thread, default_pthread_attr(), - consumer_thread_channel_poll, - (void *) the_consumer_context); + ret = pthread_create(&channel_thread, + default_pthread_attr(), + consumer_thread_channel_poll, + (void *) the_consumer_context); if (ret) { errno = ret; PERROR("pthread_create"); @@ -546,9 +570,10 @@ int main(int argc, char **argv) } /* Create thread to manage the polling/writing of trace metadata */ - ret = pthread_create(&metadata_thread, default_pthread_attr(), - consumer_thread_metadata_poll, - (void *) the_consumer_context); + ret = pthread_create(&metadata_thread, + default_pthread_attr(), + consumer_thread_metadata_poll, + (void *) the_consumer_context); if (ret) { errno = ret; PERROR("pthread_create"); @@ -557,8 +582,10 @@ int main(int argc, char **argv) } /* Create thread to manage the polling/writing of trace data */ - ret = pthread_create(&data_thread, default_pthread_attr(), - consumer_thread_data_poll, (void *) the_consumer_context); + ret = pthread_create(&data_thread, + default_pthread_attr(), + consumer_thread_data_poll, + (void *) the_consumer_context); if (ret) { errno = ret; PERROR("pthread_create"); @@ -567,9 +594,10 @@ int main(int argc, char **argv) } /* Create the thread to manage the reception of fds */ - ret = pthread_create(&sessiond_thread, default_pthread_attr(), - consumer_thread_sessiond_poll, - (void *) the_consumer_context); + ret = pthread_create(&sessiond_thread, + default_pthread_attr(), + consumer_thread_sessiond_poll, + (void *) the_consumer_context); if (ret) { errno = ret; PERROR("pthread_create"); @@ -577,7 +605,6 @@ int main(int argc, char **argv) goto exit_sessiond_thread; } - /* * This is where we start awaiting program completion (e.g. through * signal that asks threads to teardown. @@ -665,8 +692,8 @@ exit_init_data: metadata_timer_thread_online = false; } tmp_ctx = the_consumer_context; - the_consumer_context = NULL; - cmm_barrier(); /* Clear ctx for signal handler. */ + the_consumer_context = nullptr; + cmm_barrier(); /* Clear ctx for signal handler. */ lttng_consumer_destroy(tmp_ctx); if (health_consumerd) { diff --git a/src/bin/lttng-consumerd/lttng-consumerd.hpp b/src/bin/lttng-consumerd/lttng-consumerd.hpp index 833116ade..f21d5abba 100644 --- a/src/bin/lttng-consumerd/lttng-consumerd.hpp +++ b/src/bin/lttng-consumerd/lttng-consumerd.hpp @@ -9,8 +9,9 @@ #ifndef _LTTNG_CONSUMERD_H #define _LTTNG_CONSUMERD_H +#include -#define NR_LTTNG_CONSUMER_READY 1 +#define NR_LTTNG_CONSUMER_READY 1 extern int lttng_consumer_ready; extern const char *tracing_group_name; @@ -20,7 +21,6 @@ extern const char *tracing_group_name; * have a C linkage name makes it easier, as it avoids having to look up a * mangled name. */ -extern "C" LTTNG_EXPORT -enum lttng_consumer_type lttng_consumer_get_type(); +extern "C" LTTNG_EXPORT enum lttng_consumer_type lttng_consumer_get_type(); #endif /* _LTTNG_CONSUMERD_H */ diff --git a/src/bin/lttng-crash/lttng-crash.cpp b/src/bin/lttng-crash/lttng-crash.cpp index 3987a60dd..d4e41e033 100644 --- a/src/bin/lttng-crash/lttng-crash.cpp +++ b/src/bin/lttng-crash/lttng-crash.cpp @@ -6,34 +6,34 @@ * */ +#include +#include +#include +#include + +#include + +#include +#include +#include #include +#include #include +#include #include #include #include +#include #include #include -#include -#include -#include #include #include -#include -#include -#include -#include -#include - #include -#include -#include -#include -#include -#define COPY_BUFLEN 4096 -#define RB_CRASH_DUMP_ABI_LEN 32 +#define COPY_BUFLEN 4096 +#define RB_CRASH_DUMP_ABI_LEN 32 -#define RB_CRASH_DUMP_ABI_MAGIC_LEN 16 +#define RB_CRASH_DUMP_ABI_MAGIC_LEN 16 /* * The 128-bit magic number is xor'd in the process data so it does not @@ -42,29 +42,28 @@ * 0x17, 0x7B, 0xF1, 0x77, 0xBF, 0x17, 0x7B, 0xF1, * 0x77, 0xBF, 0x17, 0x7B, 0xF1, 0x77, 0xBF, 0x17, */ -#define RB_CRASH_DUMP_ABI_MAGIC_XOR \ - { \ - 0x17 ^ 0xFF, 0x7B ^ 0xFF, 0xF1 ^ 0xFF, 0x77 ^ 0xFF, \ - 0xBF ^ 0xFF, 0x17 ^ 0xFF, 0x7B ^ 0xFF, 0xF1 ^ 0xFF, \ - 0x77 ^ 0xFF, 0xBF ^ 0xFF, 0x17 ^ 0xFF, 0x7B ^ 0xFF, \ - 0xF1 ^ 0xFF, 0x77 ^ 0xFF, 0xBF ^ 0xFF, 0x17 ^ 0xFF, \ +#define RB_CRASH_DUMP_ABI_MAGIC_XOR \ + { \ + 0x17 ^ 0xFF, 0x7B ^ 0xFF, 0xF1 ^ 0xFF, 0x77 ^ 0xFF, 0xBF ^ 0xFF, 0x17 ^ 0xFF, \ + 0x7B ^ 0xFF, 0xF1 ^ 0xFF, 0x77 ^ 0xFF, 0xBF ^ 0xFF, 0x17 ^ 0xFF, \ + 0x7B ^ 0xFF, 0xF1 ^ 0xFF, 0x77 ^ 0xFF, 0xBF ^ 0xFF, 0x17 ^ 0xFF, \ } static const char *help_msg = #ifdef LTTNG_EMBED_HELP #include #else -NULL + nullptr #endif -; + ; /* * Non-static to ensure the compiler does not optimize away the xor. */ uint8_t lttng_crash_expected_magic_xor[] = RB_CRASH_DUMP_ABI_MAGIC_XOR; -#define RB_CRASH_ENDIAN 0x1234 -#define RB_CRASH_ENDIAN_REVERSE 0x3412 +#define RB_CRASH_ENDIAN 0x1234 +#define RB_CRASH_ENDIAN_REVERSE 0x3412 enum lttng_crash_type { LTTNG_CRASH_TYPE_UST = 0, @@ -73,43 +72,43 @@ enum lttng_crash_type { /* LTTng ring buffer defines (copied) */ -#define HALF_ULONG_BITS(wl) (((wl) * CHAR_BIT) >> 1) +#define HALF_ULONG_BITS(wl) (((wl) *CHAR_BIT) >> 1) -#define SB_ID_OFFSET_SHIFT(wl) (HALF_ULONG_BITS(wl) + 1) -#define SB_ID_OFFSET_COUNT(wl) (1UL << SB_ID_OFFSET_SHIFT(wl)) -#define SB_ID_OFFSET_MASK(wl) (~(SB_ID_OFFSET_COUNT(wl) - 1)) +#define SB_ID_OFFSET_SHIFT(wl) (HALF_ULONG_BITS(wl) + 1) +#define SB_ID_OFFSET_COUNT(wl) (1UL << SB_ID_OFFSET_SHIFT(wl)) +#define SB_ID_OFFSET_MASK(wl) (~(SB_ID_OFFSET_COUNT(wl) - 1)) /* * Lowest bit of top word half belongs to noref. Used only for overwrite mode. */ -#define SB_ID_NOREF_SHIFT(wl) (SB_ID_OFFSET_SHIFT(wl) - 1) -#define SB_ID_NOREF_COUNT(wl) (1UL << SB_ID_NOREF_SHIFT(wl)) -#define SB_ID_NOREF_MASK(wl) SB_ID_NOREF_COUNT(wl) +#define SB_ID_NOREF_SHIFT(wl) (SB_ID_OFFSET_SHIFT(wl) - 1) +#define SB_ID_NOREF_COUNT(wl) (1UL << SB_ID_NOREF_SHIFT(wl)) +#define SB_ID_NOREF_MASK(wl) SB_ID_NOREF_COUNT(wl) /* * In overwrite mode: lowest half of word is used for index. * Limit of 2^16 subbuffers per buffer on 32-bit, 2^32 on 64-bit. * In producer-consumer mode: whole word used for index. */ -#define SB_ID_INDEX_SHIFT(wl) 0 -#define SB_ID_INDEX_COUNT(wl) (1UL << SB_ID_INDEX_SHIFT(wl)) -#define SB_ID_INDEX_MASK(wl) (SB_ID_NOREF_COUNT(wl) - 1) +#define SB_ID_INDEX_SHIFT(wl) 0 +#define SB_ID_INDEX_COUNT(wl) (1UL << SB_ID_INDEX_SHIFT(wl)) +#define SB_ID_INDEX_MASK(wl) (SB_ID_NOREF_COUNT(wl) - 1) enum rb_modes { - RING_BUFFER_OVERWRITE = 0, /* Overwrite when buffer full */ - RING_BUFFER_DISCARD = 1, /* Discard when buffer full */ + RING_BUFFER_OVERWRITE = 0, /* Overwrite when buffer full */ + RING_BUFFER_DISCARD = 1, /* Discard when buffer full */ }; namespace { struct crash_abi_unknown { uint8_t magic[RB_CRASH_DUMP_ABI_MAGIC_LEN]; - uint64_t mmap_length; /* Overall length of crash record */ - uint16_t endian; /* - * { 0x12, 0x34 }: big endian - * { 0x34, 0x12 }: little endian - */ - uint16_t major; /* Major number. */ - uint16_t minor; /* Minor number. */ - uint8_t word_size; /* Word size (bytes). */ - uint8_t layout_type; /* enum lttng_crash_layout */ + uint64_t mmap_length; /* Overall length of crash record */ + uint16_t endian; /* + * { 0x12, 0x34 }: big endian + * { 0x34, 0x12 }: little endian + */ + uint16_t major; /* Major number. */ + uint16_t minor; /* Minor number. */ + uint8_t word_size; /* Word size (bytes). */ + uint8_t layout_type; /* enum lttng_crash_layout */ } __attribute__((packed)); struct crash_abi_0_0 { @@ -144,26 +143,21 @@ struct crash_abi_0_0 { uint32_t sb_array; } __attribute__((packed)) stride; - uint64_t buf_size; /* Size of the buffer */ - uint64_t subbuf_size; /* Sub-buffer size */ - uint64_t num_subbuf; /* Number of sub-buffers for writer */ - uint32_t mode; /* Buffer mode: 0: overwrite, 1: discard */ + uint64_t buf_size; /* Size of the buffer */ + uint64_t subbuf_size; /* Sub-buffer size */ + uint64_t num_subbuf; /* Number of sub-buffers for writer */ + uint32_t mode; /* Buffer mode: 0: overwrite, 1: discard */ } __attribute__((packed)); struct lttng_crash_layout { struct { - int prod_offset, consumed_offset, - commit_hot_array, commit_hot_seq, - buf_wsb_array, buf_wsb_id, - sb_array, sb_array_shmp_offset, - sb_backend_p_offset, content_size, - packet_size; + int prod_offset, consumed_offset, commit_hot_array, commit_hot_seq, buf_wsb_array, + buf_wsb_id, sb_array, sb_array_shmp_offset, sb_backend_p_offset, + content_size, packet_size; } offset; struct { - int prod_offset, consumed_offset, - commit_hot_seq, buf_wsb_id, - sb_array_shmp_offset, sb_backend_p_offset, - content_size, packet_size; + int prod_offset, consumed_offset, commit_hot_seq, buf_wsb_id, sb_array_shmp_offset, + sb_backend_p_offset, content_size, packet_size; } length; struct { int commit_hot_array, buf_wsb_array, sb_array; @@ -172,18 +166,18 @@ struct lttng_crash_layout { int reverse_byte_order; int word_size; - uint64_t mmap_length; /* Length of crash record */ - uint64_t buf_size; /* Size of the buffer */ - uint64_t subbuf_size; /* Sub-buffer size */ - uint64_t num_subbuf; /* Number of sub-buffers for writer */ - uint32_t mode; /* Buffer mode: 0: overwrite, 1: discard */ + uint64_t mmap_length; /* Length of crash record */ + uint64_t buf_size; /* Size of the buffer */ + uint64_t subbuf_size; /* Sub-buffer size */ + uint64_t num_subbuf; /* Number of sub-buffers for writer */ + uint32_t mode; /* Buffer mode: 0: overwrite, 1: discard */ }; } /* namespace */ /* Variables */ static const char *progname; -static char *opt_viewer_path = NULL; -static char *opt_output_path = NULL; +static char *opt_viewer_path = nullptr; +static char *opt_output_path = nullptr; static char *the_input_path; @@ -195,16 +189,13 @@ enum { /* Getopt options. No first level command. */ static struct option long_options[] = { - { "version", 0, NULL, 'V' }, - { "help", 0, NULL, 'h' }, - { "verbose", 0, NULL, 'v' }, - { "viewer", 1, NULL, 'e' }, - { "extract", 1, NULL, 'x' }, - { "list-options", 0, NULL, OPT_DUMP_OPTIONS }, - { NULL, 0, NULL, 0 }, + { "version", 0, nullptr, 'V' }, { "help", 0, nullptr, 'h' }, + { "verbose", 0, nullptr, 'v' }, { "viewer", 1, nullptr, 'e' }, + { "extract", 1, nullptr, 'x' }, { "list-options", 0, nullptr, OPT_DUMP_OPTIONS }, + { nullptr, 0, nullptr, 0 }, }; -static void usage(void) +static void usage() { int ret = utils_show_help(1, "lttng-crash", help_msg); @@ -217,11 +208,11 @@ static void usage(void) static void version(FILE *ofp) { - fprintf(ofp, "%s (LTTng Crash Trace Viewer) " VERSION " - " VERSION_NAME - "%s%s\n", - progname, - GIT_VERSION[0] == '\0' ? "" : " - " GIT_VERSION, - EXTRA_VERSION_NAME[0] == '\0' ? "" : " - " EXTRA_VERSION_NAME); + fprintf(ofp, + "%s (LTTng Crash Trace Viewer) " VERSION " - " VERSION_NAME "%s%s\n", + progname, + GIT_VERSION[0] == '\0' ? "" : " - " GIT_VERSION, + EXTRA_VERSION_NAME[0] == '\0' ? "" : " - " EXTRA_VERSION_NAME); } /* @@ -233,10 +224,10 @@ static void version(FILE *ofp) static void list_options(FILE *ofp) { int i = 0; - struct option *option = NULL; + struct option *option = nullptr; option = &long_options[i]; - while (option->name != NULL) { + while (option->name != nullptr) { fprintf(ofp, "--%s\n", option->name); if (isprint(option->val)) { @@ -262,7 +253,7 @@ static int parse_args(int argc, char **argv) exit(EXIT_FAILURE); } - while ((opt = getopt_long(argc, argv, "+Vhve:x:", long_options, NULL)) != -1) { + while ((opt = getopt_long(argc, argv, "+Vhve:x:", long_options, nullptr)) != -1) { switch (opt) { case 'V': version(stdout); @@ -310,8 +301,7 @@ error: return -1; } -static -int copy_file(const char *file_dest, const char *file_src) +static int copy_file(const char *file_dest, const char *file_src) { int fd_src = -1, fd_dest = -1; ssize_t readlen, writelen; @@ -326,8 +316,7 @@ int copy_file(const char *file_dest, const char *file_src) ret = -errno; goto error; } - fd_dest = open(file_dest, O_RDWR | O_CREAT | O_EXCL, - S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP); + fd_dest = open(file_dest, O_RDWR | O_CREAT | O_EXCL, S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP); if (fd_dest < 0) { PERROR("Error opening %s for writing", file_dest); ret = -errno; @@ -368,25 +357,26 @@ error: return ret; } -static -uint64_t _crash_get_field(const struct lttng_crash_layout *layout, - const char *ptr, size_t size) +static uint64_t +_crash_get_field(const struct lttng_crash_layout *layout, const char *ptr, size_t size) { switch (size) { - case 1: return *(uint8_t *) ptr; - case 2: if (layout->reverse_byte_order) { + case 1: + return *(uint8_t *) ptr; + case 2: + if (layout->reverse_byte_order) { return bswap_16(*(uint16_t *) ptr); } else { return *(uint16_t *) ptr; - } - case 4: if (layout->reverse_byte_order) { + case 4: + if (layout->reverse_byte_order) { return bswap_32(*(uint32_t *) ptr); } else { return *(uint32_t *) ptr; - } - case 8: if (layout->reverse_byte_order) { + case 8: + if (layout->reverse_byte_order) { return bswap_64(*(uint64_t *) ptr); } else { return *(uint64_t *) ptr; @@ -395,37 +385,30 @@ uint64_t _crash_get_field(const struct lttng_crash_layout *layout, abort(); return -1; } - } -#define crash_get_field(layout, map, name) \ - _crash_get_field(layout, (map) + (layout)->offset.name, \ - layout->length.name) - -#define crash_get_array_field(layout, map, array_name, idx, field_name) \ - _crash_get_field(layout, \ - (map) + (layout)->offset.array_name \ - + (idx * (layout)->stride.array_name) \ - + (layout)->offset.field_name, \ - (layout)->length.field_name) - -#define crash_get_hdr_raw_field(layout, hdr, name) ((hdr)->name) - -#define crash_get_hdr_field(layout, hdr, name) \ - _crash_get_field(layout, (const char *) &(hdr)->name, \ - sizeof((hdr)->name)) - -#define crash_get_layout(layout, hdr, name) \ - do { \ - (layout)->name = crash_get_hdr_field(layout, hdr, \ - name); \ - DBG("layout.%s = %" PRIu64, #name, \ - (uint64_t) (layout)->name); \ +#define crash_get_field(layout, map, name) \ + _crash_get_field(layout, (map) + (layout)->offset.name, (layout)->length.name) + +#define crash_get_array_field(layout, map, array_name, idx, field_name) \ + _crash_get_field(layout, \ + (map) + (layout)->offset.array_name + \ + ((idx) * (layout)->stride.array_name) + \ + (layout)->offset.field_name, \ + (layout)->length.field_name) + +#define crash_get_hdr_raw_field(layout, hdr, name) ((hdr)->name) + +#define crash_get_hdr_field(layout, hdr, name) \ + _crash_get_field(layout, (const char *) &(hdr)->name, sizeof((hdr)->name)) + +#define crash_get_layout(layout, hdr, name) \ + do { \ + (layout)->name = crash_get_hdr_field(layout, hdr, name); \ + DBG("layout.%s = %" PRIu64, #name, (uint64_t) (layout)->name); \ } while (0) -static -int get_crash_layout_0_0(struct lttng_crash_layout *layout, - char *map) +static int get_crash_layout_0_0(struct lttng_crash_layout *layout, char *map) { const struct crash_abi_0_0 *abi = (const struct crash_abi_0_0 *) map; @@ -462,18 +445,28 @@ int get_crash_layout_0_0(struct lttng_crash_layout *layout, return 0; } -static -void print_dbg_magic(const uint8_t *magic) +static void print_dbg_magic(const uint8_t *magic) { DBG("magic: 0x%X%X%X%X%X%X%X%X%X%X%X%X%X%X%X%X", - magic[0], magic[1], magic[2], magic[3], - magic[4], magic[5], magic[6], magic[7], - magic[8], magic[9], magic[10], magic[11], - magic[12], magic[13], magic[14], magic[15]); + magic[0], + magic[1], + magic[2], + magic[3], + magic[4], + magic[5], + magic[6], + magic[7], + magic[8], + magic[9], + magic[10], + magic[11], + magic[12], + magic[13], + magic[14], + magic[15]); } -static -int check_magic(const uint8_t *magic) +static int check_magic(const uint8_t *magic) { int i; @@ -485,9 +478,7 @@ int check_magic(const uint8_t *magic) return 0; } -static -int get_crash_layout(struct lttng_crash_layout *layout, int fd, - const char *input_file) +static int get_crash_layout(struct lttng_crash_layout *layout, int fd, const char *input_file) { char *map; int ret = 0, unmapret; @@ -507,14 +498,14 @@ int get_crash_layout(struct lttng_crash_layout *layout, int fd, } if (stat.st_size < RB_CRASH_DUMP_ABI_LEN) { ERR("File '%s' truncated: file length of %" PRIi64 - " bytes does not meet the minimal expected " - "length of %d bytes", - input_file, (int64_t) stat.st_size, - RB_CRASH_DUMP_ABI_LEN); + " bytes does not meet the minimal expected " + "length of %d bytes", + input_file, + (int64_t) stat.st_size, + RB_CRASH_DUMP_ABI_LEN); return -1; } - map = (char *) mmap(NULL, RB_CRASH_DUMP_ABI_LEN, PROT_READ, MAP_PRIVATE, - fd, 0); + map = (char *) mmap(nullptr, RB_CRASH_DUMP_ABI_LEN, PROT_READ, MAP_PRIVATE, fd, 0); if (map == MAP_FAILED) { PERROR("Mapping file"); return -1; @@ -524,7 +515,7 @@ int get_crash_layout(struct lttng_crash_layout *layout, int fd, print_dbg_magic(magic); if (check_magic(magic)) { DBG("Unknown magic number"); - ret = 1; /* positive return value, skip */ + ret = 1; /* positive return value, skip */ goto end; } endian = crash_get_hdr_field(layout, abi, endian); @@ -536,7 +527,7 @@ int get_crash_layout(struct lttng_crash_layout *layout, int fd, break; default: DBG("Unknown endianness value: 0x%X", (unsigned int) endian); - ret = 1; /* positive return value, skip */ + ret = 1; /* positive return value, skip */ goto end; } layout_type = (enum lttng_crash_type) crash_get_hdr_field(layout, abi, layout_type); @@ -545,11 +536,11 @@ int get_crash_layout(struct lttng_crash_layout *layout, int fd, break; case LTTNG_CRASH_TYPE_KERNEL: ERR("lttng-modules buffer layout support not implemented"); - ret = 1; /* positive return value, skip */ + ret = 1; /* positive return value, skip */ goto end; default: ERR("Unknown layout type %u", (unsigned int) layout_type); - ret = 1; /* positive return value, skip */ + ret = 1; /* positive return value, skip */ goto end; } mmap_length = crash_get_hdr_field(layout, abi, mmap_length); @@ -590,43 +581,36 @@ end: } /* buf_trunc mask selects only the buffer number. */ -static inline -uint64_t buf_trunc(uint64_t offset, uint64_t buf_size) +static inline uint64_t buf_trunc(uint64_t offset, uint64_t buf_size) { return offset & ~(buf_size - 1); } /* subbuf_trunc mask selects the subbuffer number. */ -static inline -uint64_t subbuf_trunc(uint64_t offset, uint64_t subbuf_size) +static inline uint64_t subbuf_trunc(uint64_t offset, uint64_t subbuf_size) { return offset & ~(subbuf_size - 1); } /* buf_offset mask selects only the offset within the current buffer. */ -static inline -uint64_t buf_offset(uint64_t offset, uint64_t buf_size) +static inline uint64_t buf_offset(uint64_t offset, uint64_t buf_size) { return offset & (buf_size - 1); } /* subbuf_offset mask selects the offset within the current subbuffer. */ -static inline -uint64_t subbuf_offset(uint64_t offset, uint64_t subbuf_size) +static inline uint64_t subbuf_offset(uint64_t offset, uint64_t subbuf_size) { return offset & (subbuf_size - 1); } /* subbuf_index returns the index of the current subbuffer within the buffer. */ -static inline -uint64_t subbuf_index(uint64_t offset, uint64_t buf_size, uint64_t subbuf_size) +static inline uint64_t subbuf_index(uint64_t offset, uint64_t buf_size, uint64_t subbuf_size) { return buf_offset(offset, buf_size) / subbuf_size; } -static inline -uint64_t subbuffer_id_get_index(uint32_t mode, uint64_t id, - unsigned int wl) +static inline uint64_t subbuffer_id_get_index(uint32_t mode, uint64_t id, unsigned int wl) { if (mode == RING_BUFFER_OVERWRITE) return id & SB_ID_INDEX_MASK(wl); @@ -634,14 +618,11 @@ uint64_t subbuffer_id_get_index(uint32_t mode, uint64_t id, return id; } -static -int copy_crash_subbuf(const struct lttng_crash_layout *layout, - int fd_dest, char *buf, uint64_t offset) +static int +copy_crash_subbuf(const struct lttng_crash_layout *layout, int fd_dest, char *buf, uint64_t offset) { - uint64_t buf_size, subbuf_size, num_subbuf, sbidx, id, - sb_bindex, rpages_offset, p_offset, seq_cc, - committed, commit_count_mask, consumed_cur, - packet_size; + uint64_t buf_size, subbuf_size, num_subbuf, sbidx, id, sb_bindex, rpages_offset, p_offset, + seq_cc, committed, commit_count_mask, consumed_cur, packet_size; char *subbuf_ptr; ssize_t writelen; @@ -656,13 +637,14 @@ int copy_crash_subbuf(const struct lttng_crash_layout *layout, num_subbuf = layout->num_subbuf; switch (layout->word_size) { - case 4: commit_count_mask = 0xFFFFFFFFULL / num_subbuf; + case 4: + commit_count_mask = 0xFFFFFFFFULL / num_subbuf; break; - case 8: commit_count_mask = 0xFFFFFFFFFFFFFFFFULL / num_subbuf; + case 8: + commit_count_mask = 0xFFFFFFFFFFFFFFFFULL / num_subbuf; break; default: - ERR("Unsupported word size: %u", - (unsigned int) layout->word_size); + ERR("Unsupported word size: %u", (unsigned int) layout->word_size); return -EINVAL; } @@ -673,16 +655,16 @@ int copy_crash_subbuf(const struct lttng_crash_layout *layout, * Find where the seq cc is located. Compute length of data to * copy. */ - seq_cc = crash_get_array_field(layout, buf, commit_hot_array, - sbidx, commit_hot_seq); + seq_cc = crash_get_array_field(layout, buf, commit_hot_array, sbidx, commit_hot_seq); consumed_cur = crash_get_field(layout, buf, consumed_offset); /* * Check that the buffer we are getting is after or at * consumed_cur position. */ - if ((long) subbuf_trunc(offset, subbuf_size) - - (long) subbuf_trunc(consumed_cur, subbuf_size) < 0) { + if ((long) subbuf_trunc(offset, subbuf_size) - + (long) subbuf_trunc(consumed_cur, subbuf_size) < + 0) { DBG("No data: position is before consumed_cur"); goto nodata; } @@ -690,9 +672,9 @@ int copy_crash_subbuf(const struct lttng_crash_layout *layout, /* * Check if subbuffer has been fully committed. */ - if (((seq_cc - subbuf_size) & commit_count_mask) - - (buf_trunc(offset, buf_size) / num_subbuf) - == 0) { + if (((seq_cc - subbuf_size) & commit_count_mask) - + (buf_trunc(offset, buf_size) / num_subbuf) == + 0) { committed = subbuf_size; } else { committed = subbuf_offset(seq_cc, subbuf_size); @@ -703,14 +685,11 @@ int copy_crash_subbuf(const struct lttng_crash_layout *layout, } /* Find actual physical offset in subbuffer table */ - id = crash_get_array_field(layout, buf, buf_wsb_array, - sbidx, buf_wsb_id); - sb_bindex = subbuffer_id_get_index(layout->mode, id, - layout->word_size); - rpages_offset = crash_get_array_field(layout, buf, sb_array, - sb_bindex, sb_array_shmp_offset); - p_offset = crash_get_field(layout, buf + rpages_offset, - sb_backend_p_offset); + id = crash_get_array_field(layout, buf, buf_wsb_array, sbidx, buf_wsb_id); + sb_bindex = subbuffer_id_get_index(layout->mode, id, layout->word_size); + rpages_offset = + crash_get_array_field(layout, buf, sb_array, sb_bindex, sb_array_shmp_offset); + p_offset = crash_get_field(layout, buf + rpages_offset, sb_backend_p_offset); subbuf_ptr = buf + p_offset; if (committed == subbuf_size) { @@ -719,8 +698,8 @@ int copy_crash_subbuf(const struct lttng_crash_layout *layout, */ if (layout->length.packet_size) { memcpy(&packet_size, - subbuf_ptr + layout->offset.packet_size, - layout->length.packet_size); + subbuf_ptr + layout->offset.packet_size, + layout->length.packet_size); if (layout->reverse_byte_order) { packet_size = bswap_64(packet_size); } @@ -742,11 +721,13 @@ int copy_crash_subbuf(const struct lttng_crash_layout *layout, } if (layout->length.content_size) { memcpy(subbuf_ptr + layout->offset.content_size, - &patch_size, layout->length.content_size); + &patch_size, + layout->length.content_size); } if (layout->length.packet_size) { memcpy(subbuf_ptr + layout->offset.packet_size, - &patch_size, layout->length.packet_size); + &patch_size, + layout->length.packet_size); } packet_size = committed; } @@ -766,9 +747,7 @@ nodata: return -ENODATA; } -static -int copy_crash_data(const struct lttng_crash_layout *layout, int fd_dest, - int fd_src) +static int copy_crash_data(const struct lttng_crash_layout *layout, int fd_dest, int fd_src) { char *buf; int ret = 0, has_data = 0; @@ -800,8 +779,7 @@ int copy_crash_data(const struct lttng_crash_layout *layout, int fd_dest, DBG("consumed_offset: 0x%" PRIx64, consumed_offset); subbuf_size = layout->subbuf_size; - for (offset = consumed_offset; offset < prod_offset; - offset += subbuf_size) { + for (offset = consumed_offset; offset < prod_offset; offset += subbuf_size) { ret = copy_crash_subbuf(layout, fd_dest, buf, offset); if (!ret) { has_data = 1; @@ -822,20 +800,18 @@ end: } } -static -int extract_file(int output_dir_fd, const char *output_file, - int input_dir_fd, const char *input_file) +static int +extract_file(int output_dir_fd, const char *output_file, int input_dir_fd, const char *input_file) { int fd_dest, fd_src, ret = 0, closeret; struct lttng_crash_layout layout; - layout.reverse_byte_order = 0; /* For reading magic number */ + layout.reverse_byte_order = 0; /* For reading magic number */ DBG("Extract file '%s'", input_file); fd_src = openat(input_dir_fd, input_file, O_RDONLY); if (fd_src < 0) { - PERROR("Error opening '%s' for reading", - input_file); + PERROR("Error opening '%s' for reading", input_file); ret = -1; goto end; } @@ -846,12 +822,12 @@ int extract_file(int output_dir_fd, const char *output_file, goto close_src; } - fd_dest = openat(output_dir_fd, output_file, - O_RDWR | O_CREAT | O_EXCL, - S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP); + fd_dest = openat(output_dir_fd, + output_file, + O_RDWR | O_CREAT | O_EXCL, + S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP); if (fd_dest < 0) { - PERROR("Error opening '%s' for writing", - output_file); + PERROR("Error opening '%s' for writing", output_file); ret = -1; goto close_src; } @@ -881,13 +857,11 @@ end: return ret; } -static -int extract_all_files(const char *output_path, - const char *input_path) +static int extract_all_files(const char *output_path, const char *input_path) { DIR *input_dir, *output_dir; int input_dir_fd, output_dir_fd, ret = 0, closeret; - struct dirent *entry; /* input */ + struct dirent *entry; /* input */ /* Open input directory */ input_dir = opendir(input_path); @@ -914,11 +888,9 @@ int extract_all_files(const char *output_path, } while ((entry = readdir(input_dir))) { - if (!strcmp(entry->d_name, ".") - || !strcmp(entry->d_name, "..")) + if (!strcmp(entry->d_name, ".") || !strcmp(entry->d_name, "..")) continue; - ret = extract_file(output_dir_fd, entry->d_name, - input_dir_fd, entry->d_name); + ret = extract_file(output_dir_fd, entry->d_name, input_dir_fd, entry->d_name); if (ret == -ENODATA) { DBG("No data in file '%s', skipping", entry->d_name); ret = 0; @@ -942,9 +914,7 @@ int extract_all_files(const char *output_path, return ret; } -static -int extract_one_trace(const char *output_path, - const char *input_path) +static int extract_one_trace(const char *output_path, const char *input_path) { char dest[PATH_MAX], src[PATH_MAX]; int ret; @@ -969,9 +939,7 @@ int extract_one_trace(const char *output_path, return extract_all_files(output_path, input_path); } -static -int extract_trace_recursive(const char *output_path, - const char *input_path) +static int extract_trace_recursive(const char *output_path, const char *input_path) { DIR *dir; int dir_fd, ret = 0, closeret; @@ -999,20 +967,19 @@ int extract_trace_recursive(const char *output_path, size_t name_len; char filename[PATH_MAX]; - if (!strcmp(entry->d_name, ".") - || !strcmp(entry->d_name, "..")) { + if (!strcmp(entry->d_name, ".") || !strcmp(entry->d_name, "..")) { continue; } name_len = strlen(entry->d_name); if (path_len + name_len + 2 > sizeof(filename)) { ERR("Failed to remove file: path name too long (%s/%s)", - input_path, entry->d_name); + input_path, + entry->d_name); continue; } - if (snprintf(filename, sizeof(filename), "%s/%s", - input_path, entry->d_name) < 0) { + if (snprintf(filename, sizeof(filename), "%s/%s", input_path, entry->d_name) < 0) { ERR("Failed to format path."); continue; } @@ -1026,12 +993,13 @@ int extract_trace_recursive(const char *output_path, char output_subpath[PATH_MAX]; char input_subpath[PATH_MAX]; - strncpy(output_subpath, output_path, - sizeof(output_subpath)); + strncpy(output_subpath, output_path, sizeof(output_subpath)); output_subpath[sizeof(output_subpath) - 1] = '\0'; - strncat(output_subpath, "/", + strncat(output_subpath, + "/", sizeof(output_subpath) - strlen(output_subpath) - 1); - strncat(output_subpath, entry->d_name, + strncat(output_subpath, + entry->d_name, sizeof(output_subpath) - strlen(output_subpath) - 1); ret = mkdir(output_subpath, S_IRWXU | S_IRWXG); @@ -1041,26 +1009,25 @@ int extract_trace_recursive(const char *output_path, goto end; } - strncpy(input_subpath, input_path, - sizeof(input_subpath)); + strncpy(input_subpath, input_path, sizeof(input_subpath)); input_subpath[sizeof(input_subpath) - 1] = '\0'; - strncat(input_subpath, "/", + strncat(input_subpath, + "/", sizeof(input_subpath) - strlen(input_subpath) - 1); - strncat(input_subpath, entry->d_name, + strncat(input_subpath, + entry->d_name, sizeof(input_subpath) - strlen(input_subpath) - 1); - ret = extract_trace_recursive(output_subpath, - input_subpath); + ret = extract_trace_recursive(output_subpath, input_subpath); if (ret) { has_warning = 1; } } else if (S_ISREG(st.st_mode) || S_ISLNK(st.st_mode)) { if (!strcmp(entry->d_name, "metadata")) { - ret = extract_one_trace(output_path, - input_path); + ret = extract_one_trace(output_path, input_path); if (ret) { WARN("Error extracting trace '%s', continuing anyway.", - input_path); + input_path); has_warning = 1; } } @@ -1077,8 +1044,7 @@ end: return has_warning; } -static -int delete_dir_recursive(const char *path) +static int delete_dir_recursive(const char *path) { DIR *dir; int dir_fd, ret = 0, closeret; @@ -1090,7 +1056,7 @@ int delete_dir_recursive(const char *path) if (!dir) { PERROR("Cannot open '%s' path", path); ret = -errno; - goto end_no_closedir; + goto end_no_closedir; } path_len = strlen(path); @@ -1107,20 +1073,19 @@ int delete_dir_recursive(const char *path) size_t name_len; char filename[PATH_MAX]; - if (!strcmp(entry->d_name, ".") - || !strcmp(entry->d_name, "..")) { + if (!strcmp(entry->d_name, ".") || !strcmp(entry->d_name, "..")) { continue; } name_len = strlen(entry->d_name); if (path_len + name_len + 2 > sizeof(filename)) { ERR("Failed to remove file: path name too long (%s/%s)", - path, entry->d_name); + path, + entry->d_name); continue; } - if (snprintf(filename, sizeof(filename), "%s/%s", - path, entry->d_name) < 0) { + if (snprintf(filename, sizeof(filename), "%s/%s", path, entry->d_name) < 0) { ERR("Failed to format path."); continue; } @@ -1140,10 +1105,8 @@ int delete_dir_recursive(const char *path) } strncpy(subpath, path, PATH_MAX); subpath[PATH_MAX - 1] = '\0'; - strncat(subpath, "/", - PATH_MAX - strlen(subpath) - 1); - strncat(subpath, entry->d_name, - PATH_MAX - strlen(subpath) - 1); + strncat(subpath, "/", PATH_MAX - strlen(subpath) - 1); + strncat(subpath, entry->d_name, PATH_MAX - strlen(subpath) - 1); ret = delete_dir_recursive(subpath); free(subpath); @@ -1177,8 +1140,7 @@ end_no_closedir: return ret; } -static -int view_trace(const char *trace_path, char *viewer_path) +static int view_trace(const char *trace_path, char *viewer_path) { pid_t pid; @@ -1216,7 +1178,7 @@ int main(int argc, char *argv[]) { int ret; bool has_warning = false; - const char *output_path = NULL; + const char *output_path = nullptr; char tmppath[] = "/tmp/lttng-crash-XXXXXX"; progname = argv[0] ? argv[0] : "lttng-crash"; diff --git a/src/bin/lttng-relayd/Makefile.am b/src/bin/lttng-relayd/Makefile.am index b473d5c62..fce8c2346 100644 --- a/src/bin/lttng-relayd/Makefile.am +++ b/src/bin/lttng-relayd/Makefile.am @@ -25,7 +25,8 @@ lttng_relayd_SOURCES = main.cpp lttng-relayd.hpp utils.hpp utils.cpp cmd.hpp \ tracefile-array.cpp tracefile-array.hpp \ tcp_keep_alive.cpp tcp_keep_alive.hpp \ sessiond-trace-chunks.cpp sessiond-trace-chunks.hpp \ - backward-compatibility-group-by.cpp backward-compatibility-group-by.hpp + backward-compatibility-group-by.cpp backward-compatibility-group-by.hpp \ + thread-utils.cpp # link on liblttngctl for check if relayd is already alive. lttng_relayd_LDADD = $(URCU_LIBS) \ diff --git a/src/bin/lttng-relayd/backward-compatibility-group-by.cpp b/src/bin/lttng-relayd/backward-compatibility-group-by.cpp index 78f8a1971..a14a33acc 100644 --- a/src/bin/lttng-relayd/backward-compatibility-group-by.cpp +++ b/src/bin/lttng-relayd/backward-compatibility-group-by.cpp @@ -5,20 +5,19 @@ * */ +#include "backward-compatibility-group-by.hpp" #include "common/time.hpp" -#include -#include -#include -#include #include #include #include -#include "backward-compatibility-group-by.hpp" +#include +#include +#include +#include -#define DATETIME_REGEX \ - ".*-[1-2][0-9][0-9][0-9][0-1][0-9][0-3][0-9]-[0-2][0-9][0-5][0-9][0-5][0-9]$" +#define DATETIME_REGEX ".*-[1-2][0-9][0-9][0-9][0-1][0-9][0-3][0-9]-[0-2][0-9][0-5][0-9][0-5][0-9]$" /* * Provide support for --group-output-by-session for producer >= 2.4 and < 2.11. @@ -28,16 +27,16 @@ * Return the allocated string containing the new stream path or else NULL. */ char *backward_compat_group_by_session(const char *path, - const char *local_session_name, - time_t relay_session_creation_time) + const char *local_session_name, + time_t relay_session_creation_time) { int ret; size_t len; char *leftover_ptr; - char *local_copy = NULL; - char *datetime = NULL; - char *partial_base_path = NULL; - char *filepath_per_session = NULL; + char *local_copy = nullptr; + char *datetime = nullptr; + char *partial_base_path = nullptr; + char *filepath_per_session = nullptr; const char *second_token_ptr; const char *leftover_second_token_ptr; const char *hostname_ptr; @@ -48,7 +47,8 @@ char *backward_compat_group_by_session(const char *path, LTTNG_ASSERT(local_session_name[0] != '\0'); DBG("Parsing path \"%s\" of session \"%s\" to create a new path that is grouped by session", - path, local_session_name); + path, + local_session_name); /* Get a local copy for strtok */ local_copy = strdup(path); @@ -74,15 +74,13 @@ char *backward_compat_group_by_session(const char *path, */ hostname_ptr = strtok_r(local_copy, "/", &leftover_ptr); if (!hostname_ptr) { - ERR("Failed to parse session path \"%s\": couldn't identify hostname", - path); + ERR("Failed to parse session path \"%s\": couldn't identify hostname", path); goto error; } - second_token_ptr = strtok_r(NULL, "/", &leftover_ptr); + second_token_ptr = strtok_r(nullptr, "/", &leftover_ptr); if (!second_token_ptr) { - ERR("Failed to parse session path \"%s\": couldn't identify session name", - path); + ERR("Failed to parse session path \"%s\": couldn't identify session name", path); goto error; } @@ -100,8 +98,7 @@ char *backward_compat_group_by_session(const char *path, * --