doc: implement REUSE with SPDX identifiers

[lttng-ust.git] / doc / man / tracef-tracelog-limitations.txt

diff --git a/doc/man/tracef-tracelog-limitations.txt b/doc/man/tracef-tracelog-limitations.txt
index a94919030ec71ce18f46ec9b49a824404d51534d..a10eac571e5dcb5d92f81bba0bf19842128519a9 100644 (file)
--- a/doc/man/tracef-tracelog-limitations.txt
+++ b/doc/man/tracef-tracelog-limitations.txt
@@ -1,6 +1,12 @@
-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:
+// SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
+// SPDX-License-Identifier: CC-BY-4.0
+//
+: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 +15,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.