X-Git-Url: http://git.lttng.org./?a=blobdiff_plain;f=doc%2Fman%2Ftracef-tracelog-limitations.txt;h=c5bb6babc53118781825d59163992dfc33d7ab4e;hb=5b1163c6cf674c6461cc1e0ad1211924df7af789;hp=a94919030ec71ce18f46ec9b49a824404d51534d;hpb=4ddbd0b790be981d023f344a83e67a8746fa3688;p=lttng-ust.git

diff --git a/doc/man/tracef-tracelog-limitations.txt b/doc/man/tracef-tracelog-limitations.txt
index a9491903..c5bb6bab 100644
--- a/doc/man/tracef-tracelog-limitations.txt
+++ b/doc/man/tracef-tracelog-limitations.txt
@@ -1,6 +1,9 @@
-The +{macro-name}()+ utility macro was developed to make user space
-tracing super simple, albeit with notable disadvantages compared to
-custom, full-fledged tracepoint providers:
+:macro-name: lttng_ust_{macro-suffix}
+:vmacro-name: lttng_ust_v{macro-suffix}
+
+The +{macro-name}()+ and +{vmacro-name}()+ utility macros were
+developed to make user space tracing super simple, albeit with notable
+disadvantages compared to custom, full-fledged tracepoint providers:
 
   * All generated events have the same provider/event names.
   * There's no static type checking.
@@ -9,16 +12,21 @@ custom, full-fledged tracepoint providers:
     macro using your own format. This also means that you cannot use
     filtering using a custom expression at run time because there are no
     isolated fields.
-  * Since +{macro-name}()+ uses C standard library's man:vasprintf(3)
-    function in the background to format the strings at run time, its
-    expected performance is lower than using custom tracepoint providers
-    with typed fields, which do not require a conversion to a string.
+  * Since +{macro-name}()+ and +{vmacro-name}()+ use C standard
+    library's man:vasprintf(3) function in the background to format the
+    strings at run time, their expected performance is lower than using
+    custom tracepoint providers with typed fields, which do not require
+    a conversion to a string.
   * Generally, a string containing the textual representation of the
-    user data fields is not as compact as binary fields in the
-    resulting trace.
+    user data fields is not as compact as binary fields in the resulting
+    trace.
+
+Thus, +{macro-name}()+/+{vmacro-name}()+ are useful for quick
+prototyping and debugging, but should not be considered for any
+permanent/serious application instrumentation.
 
-Thus, +{macro-name}()+ is useful for quick prototyping and debugging, but
-should not be considered for any permanent/serious application
-instrumentation.
++{vmacro-name}()+ does not have a `STAP_PROBEV()` call, because
+`STAP_PROBEV()` does not support `va_list`. If you need it, you should
+emit this call yourself.
 
 See man:lttng-ust(3) to learn more about custom tracepoint providers.