X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-ust.3.txt;h=0864b9a303da9f78631acbb4bc3549b05993259e;hb=HEAD;hp=ad1fbbf4bd2a081d26fe3c1ddeccd654ac24c11e;hpb=53f7d0d7404de911dd62dff06f08539e33ea7519;p=lttng-ust.git

diff --git a/doc/man/lttng-ust.3.txt b/doc/man/lttng-ust.3.txt
index ad1fbbf4..601ebec8 100644
--- a/doc/man/lttng-ust.3.txt
+++ b/doc/man/lttng-ust.3.txt
@@ -688,6 +688,27 @@ NOTE: Neither `lttng_ust_tracepoint_enabled()` nor
 `lttng_ust_do_tracepoint()` have a `STAP_PROBEV()` call, so if you need
 it, you should emit this call yourself.
 
+Tracing in C/C++ constructors and destructors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As of LTTng-UST{nbsp}2.13, tracepoint definitions are implemented using
+compound literals. In the following cases, those compound literals are
+allocated on the heap:
+
+* g++{nbsp}<=={nbsp}4.8 is used as the compiler or,
+* `LTTNG_UST_ALLOCATE_COMPOUND_LITERAL_ON_HEAP` is defined in the C pre-processor flags
+and the application is compiled with a C++ compiler
+
+When the compound literals are heap-allocated, there are some cases in which
+both C-style and C++ constructors and destructors will not be traced.
+
+1. C-style constructors and destructors in statically linked archives
+2. C-style constructors and destructors in the application itself
+3. Some C++-style constructors and destructors in the application and statically linked archives
+
+In the 3rd case above, which C++-style constructors and destructors will not be traced depends
+on the initialization order within each translation unit and across the entire program when
+all translation units are linked together.
 
 [[build-static]]
 Statically linking the tracepoint provider
@@ -1209,8 +1230,9 @@ if (lttng_ust_loaded) {
 [[example]]
 EXAMPLE
 -------
+
 NOTE: A few examples are available in the
-https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples[`doc/examples`]
+https://github.com/lttng/lttng-ust/tree/stable-{lttng_version}/doc/examples[`doc/examples`]
 directory of LTTng-UST's source tree.
 
 This example shows all the features documented in the previous
@@ -1325,10 +1347,10 @@ LTTNG_UST_TRACEPOINT_EVENT(
         lttng_ust_field_array(int, array_field, array_arg, 7)
         lttng_ust_field_array_text(char, array_text_field,
                                    array_arg, 5)
-        lttng_ust_field_sequence(int, seq_field, array_arg, int,
+        lttng_ust_field_sequence(int, seq_field, array_arg, unsigned int,
                                  my_integer_arg / 10)
         lttng_ust_field_sequence_text(char, seq_text_field,
-                                      array_arg, int,
+                                      array_arg, unsigned int,
                                       my_integer_arg / 5)
         lttng_ust_field_enum(my_provider, my_enum, int,
                              enum_field, array_arg[1])
@@ -1482,15 +1504,22 @@ int main(int argc, char* argv[])
 
 ENVIRONMENT VARIABLES
 ---------------------
+`LTTNG_UST_APP_PATH`::
+    Path under which unix sockets used for the communication between
+    the application (tracee) instrumented with `liblttng-ust` and the
+    LTTng session and consumer daemons (part of the LTTng-tools project)
+    are located. When `$LTTNG_UST_APP_PATH` is specified, only this path
+    is considered for connecting to a session daemon. The
+    `$LTTNG_UST_APP_PATH` target directory must exist and be accessible
+    by the user before the application is executed for tracing to work.
+    Setting this environment variable disables connection to root and
+    per-user session daemons.
+
 `LTTNG_HOME`::
     Alternative user's home directory. This variable is useful when the
     user running the instrumented application has a non-writable home
-    directory.
-+
-Unix sockets used for the communication between `liblttng-ust` and the
-LTTng session and consumer daemons (part of the LTTng-tools project)
-are located in a specific directory under `$LTTNG_HOME` (or `$HOME` if
-`$LTTNG_HOME` is not set).
+    directory. This path is where unix sockets for communication with
+    the per-user session daemon are located.
 
 `LTTNG_UST_ALLOW_BLOCKING`::
     If set, allow the application to retry event tracing when there's
@@ -1517,7 +1546,7 @@ affect application timings.
     Path to the shared object which acts as the clock override plugin.
     An example of such a plugin can be found in the LTTng-UST
     documentation under
-    https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/clock-override[`examples/clock-override`].
+    https://github.com/lttng/lttng-ust/tree/stable-{lttng_version}/doc/examples/clock-override[`examples/clock-override`].
 
 `LTTNG_UST_DEBUG`::
     If set, enable `liblttng-ust`'s debug and error output.
@@ -1526,7 +1555,24 @@ affect application timings.
     Path to the shared object which acts as the `getcpu()` override
     plugin. An example of such a plugin can be found in the LTTng-UST
     documentation under
-    https://github.com/lttng/lttng-ust/tree/v{lttng_version}/doc/examples/getcpu-override[`examples/getcpu-override`].
+    https://github.com/lttng/lttng-ust/tree/stable-{lttng_version}/doc/examples/getcpu-override[`examples/getcpu-override`].
+
+`LTTNG_UST_MAP_POPULATE_POLICY`::
++
+--
+If set, override the policy used to populate shared memory pages
+within the application. The expected values are:
+
+`none`:::
+  Do not pre-populate any pages, take minor faults on first access
+  while tracing.
+
+`cpu_possible`:::
+  Pre-populate pages for all possible CPUs in the system, as
+  listed by `/sys/devices/system/cpu/possible`.
+--
++
+Default: `none`. If the policy is unknown, use the default.
 
 `LTTNG_UST_REGISTER_TIMEOUT`::
     Waiting time for the _registration done_ session daemon command