much the same as the static library method, except that:
* since the tracepoint provider is not part of the application
- anymore, `TRACEPOINT_DEFINE` _must_ be defined in one translation
- unit (C source file) of the _application_;
+ anymore, `TRACEPOINT_DEFINE` _must_ be defined, for each tracepoint
+ provider, in exactly one translation unit (C source file) of the
+ _application_;
* `TRACEPOINT_PROBE_DYNAMIC_LINKAGE` must be defined next to
`TRACEPOINT_DEFINE`.
+Regarding `TRACEPOINT_DEFINE` and `TRACEPOINT_PROBE_DYNAMIC_LINKAGE`,
+the recommended practice is to use a separate C source file in your
+application to define them, and then include the tracepoint provider
+header files afterwards, e.g.:
+
+~~~ c
+#define TRACEPOINT_DEFINE
+#define TRACEPOINT_PROBE_DYNAMIC_LINKAGE
+
+/* include the header files of one or more tracepoint providers below */
+#include "tp1.h"
+#include "tp2.h"
+#include "tp3.h"
+~~~
+
`TRACEPOINT_PROBE_DYNAMIC_LINKAGE` makes the macros included afterwards
(by including the tracepoint provider header, which itself includes
LTTng-UST headers) aware that the tracepoint provider is to be loaded
gcc -o app other.o files.o of.o your.o app.o <strong>-ldl</strong>
</pre>
-Now, to make LTTng-UST tracing available to the application,
-the `LD_PRELOAD` environment variable is used to preload the
-tracepoint provider shared library _before_ the application actually
-starts:
+Now, to make LTTng-UST tracing available to the application, the
+`LD_PRELOAD` environment variable is used to preload the tracepoint
+provider shared library _before_ the application actually starts:
<pre class="term">
<strong>LD_PRELOAD=/path/to/tp.so</strong> ./app
</pre>
+<div class="tip">
+<p>
+ <span class="t">Note:</span>It is not safe to use
+ <code>dlclose()</code> on a tracepoint provider shared object that
+ is being actively used for tracing, due to a lack of reference
+ counting from LTTng-UST to the shared object.
+</p>
+
+<p>
+ For example, statically linking a tracepoint provider to a
+ shared object which is to be dynamically loaded by an application
+ (e.g., a plugin) is not safe: the shared object, which contains the
+ tracepoint provider, could be dynamically closed
+ (<code>dlclose()</code>) at any time by the application.
+</p>
+
+<p>
+ To instrument a shared object, either:
+</p>
+
+<ol>
+ <li>
+ Statically link the tracepoint provider to the
+ <em>application</em>, or
+ </li>
+ <li>
+ Build the tracepoint provider as a shared object (following
+ the procedure shown in this section), and preload it when
+ tracing is needed using the <code>LD_PRELOAD</code>
+ environment variable.
+ </li>
+</ol>
+</div>
+
Your application will still work without this preloading, albeit without
LTTng-UST tracing support:
<pre class="term">
./app
</pre>
+