Clarify probe registration documentation/errors

[lttng-ust.git] / doc / man / lttng-ust.3

diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3
index 6bbfc96c3a29112f98176bf49653df10799083dc..0de6b6a1e9e1d1bccee7bce37e964cb25d15e62a 100644 (file)
--- a/doc/man/lttng-ust.3
+++ b/doc/man/lttng-ust.3
@@ -148,6 +148,11 @@ TRACEPOINT_EVENT(
                ctf_float(double, doublefield, doublearg)
        )
 )
+
+There can be an arbitrary number of tracepoint providers within an
+application, but they must each have their own provider name. Duplicate
+provider names are not allowed.
+
 .fi
 
 .SH "ASSIGNING LOGLEVEL TO EVENTS"
@@ -251,13 +256,13 @@ carefully:
        directly or through a static library (.a):
     - Into exactly one object of your application: define
       "TRACEPOINT_DEFINE" and include the tracepoint provider.
-    - Use "-I." for the compilation unit containing the tracepoint
+    - Use "\-I." for the compilation unit containing the tracepoint
       provider include (e.g. tp.c).
-    - Link application with "-ldl".
+    - Link application with "\-ldl".
     - If building the provider directly into the application,
-      link the application with "-llttng-ust".
+      link the application with "\-llttng-ust".
     - If building a static library for the provider, link the static
-      library with "-lllttng-ust".
+      library with "\-llttng-ust".
     - Include the tracepoint provider header into all C files using
       the provider.
     - Example:
@@ -271,9 +276,9 @@ carefully:
       provider header.
     - Include the tracepoint provider header into all instrumented C
       files that use the provider.
-    - Compile the tracepoint provider with "-I.".
-    - Link the tracepoint provider with "-llttng-ust".
-    - Link application with "-ldl".
+    - Compile the tracepoint provider with "\-I.".
+    - Link the tracepoint provider with "\-llttng-ust".
+    - Link application with "\-ldl".
     - Set a LD_PRELOAD environment to preload the tracepoint provider
       shared object before starting the application when tracing is
       needed.
@@ -284,9 +289,23 @@ carefully:
     way libc lazily resolves Thread-Local Storage (TLS) symbols when a
     library is dlopen'd, linking the tracepoint probe or liblttng-ust
     with dlopen() is discouraged. They should be linked with the
-    application using "-llibname" or loaded with LD_PRELOAD.
+    application using "\-llibname" or loaded with LD_PRELOAD.
   - Enable instrumentation and control tracing with the "lttng" command
     from lttng-tools. See lttng-tools doc/quickstart.txt.
+  - Note for C++ support: although an application instrumented with
+    tracepoints can be compiled with g++, tracepoint probes should be
+    compiled with gcc (only tested with gcc so far).
+
+.fi
+
+.SH "USING LTTNG UST WITH DAEMONS"
+
+.nf
+Some extra care is needed when using liblttng-ust with daemon
+applications that call fork(), clone(), or BSD rfork() without a
+following exec() family system call. The library "liblttng-ust-fork.so"
+needs to be preloaded for the application (launch with e.g.
+LD_PRELOAD=liblttng-ust-fork.so appname).
 
 .fi
 
@@ -302,7 +321,7 @@ specify how long the applications should wait for sessiond
 "registration done" command before proceeding to execute the main
 program. The default is 3000ms (3 seconds). The timeout value is
 specified in milliseconds. The value 0 means "don't wait". The value
--1 means "wait forever". Setting this environment variable to 0 is
+\-1 means "wait forever". Setting this environment variable to 0 is
 recommended for applications with time constraints on the process
 startup time.
 .PP
@@ -312,10 +331,23 @@ startup time.
 .PP
 lttng-gen-tp(1), lttng(1), babeltrace(1), lttng-sessiond(8)
 .PP
+
+.SH "COMPATIBILITY"
+
+.PP
+Older lttng-ust libraries reject more recent, and incompatible, probe
+providers. Newer lttng-ust librairies accept older probe providers, even
+though some newer features might not be available with those providers.
+.PP
+
 .SH "BUGS"
 
 .PP
-No knows bugs at this point.
+LTTng-UST 2.0 and 2.1 lttng-ust libraries do not check for probe
+provider version compatibility. This can lead to out-of-bound accesses
+when using a more recent probe provider with an older lttng-ust library.
+These error only trigger when tracing is active. This issue has been
+fixed in LTTng-UST 2.2.
 
 If you encounter any issues or usability problem, please report it on
 our mailing list <lttng-dev@lists.lttng.org> to help improve this