From 382d32dd80972b4c4cef627b935b4aa488c5fd51 Mon Sep 17 00:00:00 2001
From: Philippe Proulx <eeppeliteloop@gmail.com>
Date: Fri, 19 Dec 2014 16:17:21 -0500
Subject: [PATCH] dynamic-linking: note about instrumenting a SO

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
---
 .../building-linking/dynamic-linking.md       | 41 +++++++++++++++++--
 1 file changed, 37 insertions(+), 4 deletions(-)

diff --git a/contents/using-lttng/instrumenting/c-application/building-linking/dynamic-linking.md b/contents/using-lttng/instrumenting/c-application/building-linking/dynamic-linking.md
index e52363b..aec70c6 100644
--- a/contents/using-lttng/instrumenting/c-application/building-linking/dynamic-linking.md
+++ b/contents/using-lttng/instrumenting/c-application/building-linking/dynamic-linking.md
@@ -68,15 +68,48 @@ provider, but still needs `libdl`:
 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:
 
-- 
2.34.1