doc/man: document LTTng-UST 2.13
authorPhilippe Proulx <eeppeliteloop@gmail.com>
Tue, 25 May 2021 17:06:56 +0000 (13:06 -0400)
committerMathieu Desnoyers <mathieu.desnoyers@efficios.com>
Mon, 7 Jun 2021 19:29:43 +0000 (15:29 -0400)
Significant changes:

* Prefix all macro/definition names with `LTTNG_UST_` or `lttng_ust_`
  where needed.

* Prefix all log level definitions with `LTTNG_UST_TRACEPOINT_LOGLEVEL`.

* lttng-ust(3):

  * Add "Compatibility with previous APIs" section to explain
    the new `LTTNG_UST_COMPAT_API_VERSION` definition.

  * Document the new tracepoint class provider name parameter of
    `LTTNG_UST_TRACEPOINT_EVENT_INSTANCE()`.

    Update examples accordingly.

* Mention `liblttng-ust-common` where missing.

* tracef(3), vtracef(3), tracelog(3), and vtracelog(3) now indicate that
  the macros are part of version 0 of the LTTng-UST API, albeit still
  available, and point to lttng_ust_tracef(3), lttng_ust_vtracef(3),
  lttng_ust_tracelog(3), and lttng_ust_vtracelog(3).

* New lttng_ust_do_tracepoint(3), lttng_ust_tracepoint(3),
  and lttng_ust_tracepoint_enabled(3) manual pages which source
  lttng-ust(3).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Change-Id: I07d6ace0d6f219c36d7c99a455726bbf4b0736a2

15 files changed:
.gitignore
doc/man/Makefile.am
doc/man/README.md
doc/man/log-levels.txt
doc/man/lttng-gen-tp.1.txt
doc/man/lttng-ust-cyg-profile.3.txt
doc/man/lttng-ust.3.txt
doc/man/lttng_ust_do_tracepoint.3 [new file with mode: 0644]
doc/man/lttng_ust_tracef.3.txt [new file with mode: 0644]
doc/man/lttng_ust_tracelog.3.txt [new file with mode: 0644]
doc/man/lttng_ust_tracepoint.3 [new file with mode: 0644]
doc/man/lttng_ust_tracepoint_enabled.3 [new file with mode: 0644]
doc/man/tracef-tracelog-limitations.txt
doc/man/tracef.3.txt
doc/man/tracelog.3.txt

index 9d504cc08753a4eb85b8a5e236916f434465bdee..68b258db8049c648b48a4f7e4a6be979a5425e1f 100644 (file)
@@ -73,6 +73,10 @@ cscope.*
 /doc/man/tracelog.3
 /doc/man/vtracef.3
 /doc/man/vtracelog.3
+/doc/man/lttng_ust_tracef.3
+/doc/man/lttng_ust_tracelog.3
+/doc/man/lttng_ust_vtracef.3
+/doc/man/lttng_ust_vtracelog.3
 
 /tests/benchmark/bench1
 /tests/benchmark/bench2
index dfc319a42eab1c6a8856f62ada2b76b19a5308eb..fed0e344b16b7b1453392b786c4d550201720658 100644 (file)
@@ -12,16 +12,24 @@ MAN1_NAMES = \
        lttng-gen-tp
 MAN3_NAMES = \
        lttng-ust \
-       tracef \
-       tracelog \
        lttng-ust-dl \
-       lttng-ust-cyg-profile
+       lttng-ust-cyg-profile \
+       lttng_ust_tracef \
+       lttng_ust_tracelog \
+       tracef \
+       tracelog
 
 # Man page aliases (generated from other sources):
-MAN3_ALIASES = vtracef.3 vtracelog.3
+MAN3_ALIASES = lttng_ust_vtracef.3 lttng_ust_vtracelog.3 vtracef.3 vtracelog.3
 
 # troff man pages:
-MAN3_TROFF = do_tracepoint.3 tracepoint.3 tracepoint_enabled.3
+MAN3_TROFF = \
+       do_tracepoint.3 \
+       lttng_ust_do_tracepoint.3 \
+       lttng_ust_tracepoint.3 \
+       lttng_ust_tracepoint_enabled.3 \
+       tracepoint.3 \
+       tracepoint_enabled.3
 
 # AsciiDoc sources and outputs:
 MAN1_TXT = $(call manaddsuffix,.1.txt,$(MAN1_NAMES))
@@ -93,7 +101,14 @@ tracef.3 vtracef.3: tracef.3.alias
 tracelog.3 vtracelog.3: tracelog.3.alias
        @# Empty recipe to mark tracelog.3 and vtracelog.3 as rebuilt
 
-.INTERMEDIATE: tracef.3.alias tracelog.3.alias
+lttng_ust_tracef.3 lttng_ust_vtracef.3: lttng_ust_tracef.3.alias
+       @# Empty recipe to mark lttng_ust_tracef.3 and lttng_ust_vtracef.3 as rebuilt
+
+lttng_ust_tracelog.3 lttng_ust_vtracelog.3: lttng_ust_tracelog.3.alias
+       @# Empty recipe to mark lttng_ust_tracelog.3 and lttng_ust_vtracelog.3 as rebuilt
+
+
+.INTERMEDIATE: tracef.3.alias tracelog.3.alias lttng_ust_tracef.3.alias lttng_ust_tracelog.3.alias
 
 tracef.3.alias: tracef.3.xml $(XSL_FILE)
        $(XTO) $< $(xmlto_verbose_out)
@@ -101,6 +116,12 @@ tracef.3.alias: tracef.3.xml $(XSL_FILE)
 tracelog.3.alias: tracelog.3.xml $(XSL_FILE)
        $(XTO) $< $(xmlto_verbose_out)
 
+lttng_ust_tracef.3.alias: lttng_ust_tracef.3.xml $(XSL_FILE)
+       $(XTO) $< $(xmlto_verbose_out)
+
+lttng_ust_tracelog.3.alias: lttng_ust_tracelog.3.xml $(XSL_FILE)
+       $(XTO) $< $(xmlto_verbose_out)
+
 %.3: %.3.xml $(XSL_FILE)
        $(XTO) $< $(xmlto_verbose_out)
 
index b895f22fd17c69de22a66c48e23c78382b67a8a8..bcd9301df73f90357679b71493863a790d99c56d 100644 (file)
@@ -66,7 +66,7 @@ Includes
     before the copyrights section.
   * `log-levels.txt`: definition list of LTTng-UST log levels.
   * `tracef-tracelog-limitations.txt`: limitations that apply to both
-    the `tracef(3)` and `tracelog(3)` man pages.
+    the `lttng_ust_tracef(3)` and `lttng_ust_tracelog(3)` man pages.
 
 
 Convention
index b5afe92f731d9d81a3e24573a8fe7e7bcbb20966..392c6cb42b3b03faf0751bd19a050e41c9fe30f3 100644 (file)
@@ -1,44 +1,44 @@
-`TRACE_EMERG`::
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_EMERG`::
     System is unusable.
 
-`TRACE_ALERT`::
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_ALERT`::
     Action must be taken immediately.
 
-`TRACE_CRIT`::
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_CRIT`::
     Critical conditions.
 
-`TRACE_ERR`::
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_ERR`::
     Error conditions.
 
-`TRACE_WARNING`::
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_WARNING`::
     Warning conditions.
 
-`TRACE_NOTICE`::
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_NOTICE`::
     Normal, but significant, condition.
 
-`TRACE_INFO`::
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO`::
     Informational message.
 
-`TRACE_DEBUG_SYSTEM`::
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_SYSTEM`::
     Debug information with system-level scope (set of programs).
 
-`TRACE_DEBUG_PROGRAM`::
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_PROGRAM`::
     Debug information with program-level scope (set of processes).
 
-`TRACE_DEBUG_PROCESS`::
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_PROCESS`::
     Debug information with process-level scope (set of modules).
 
-`TRACE_DEBUG_MODULE`::
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_MODULE`::
     Debug information with module (executable/library) scope (set of units).
 
-`TRACE_DEBUG_UNIT`::
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_UNIT`::
     Debug information with compilation unit scope (set of functions).
 
-`TRACE_DEBUG_FUNCTION`::
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_FUNCTION`::
     Debug information with function-level scope.
 
-`TRACE_DEBUG_LINE`::
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_LINE`::
     Debug information with line-level scope (default log level).
 
-`TRACE_DEBUG`::
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG`::
     Debug-level message.
index 2fa73c8722616e0f8bd6d4078a9bb68df1529343..969a1e318327625823fe3b5199fe005e5972d564 100644 (file)
@@ -40,21 +40,22 @@ needed.
 Template file format
 ~~~~~~~~~~~~~~~~~~~~
 The template file, which usually has the `.tp` extension, contains a
-list of `TRACEPOINT_EVENT()` definitions and other optional definition
-entries, like `TRACEPOINT_LOGLEVEL()`. See man:lttng-ust(3) for
-the complete list of available definitions.
+list of `LTTNG_UST_TRACEPOINT_EVENT()` definitions and other optional
+definition entries, like `LTTNG_UST_TRACEPOINT_LOGLEVEL()`. See
+man:lttng-ust(3) for the complete list of available definitions.
 
-The `TRACEPOINT_EVENT()` definitions are written as you would write them
-in an LTTng-UST template provider header file. C comments are supported
-(`/* */` and `//`), as well as lines starting with `#`.
+The `LTTNG_UST_TRACEPOINT_EVENT()` definitions are written as you would
+write them in an LTTng-UST template provider header file. C comments are
+supported (`/* */` and `//`), as well as lines starting with `#`.
 
-NOTE: The provider name (the first argument of `TRACEPOINT_EVENT()`)
-must be the same in all the `TRACEPOINT_EVENT()` macros of 'TEMPLATE'.
+NOTE: The provider name (the first argument of
+`LTTNG_UST_TRACEPOINT_EVENT()`) must be the same in all the
+`LTTNG_UST_TRACEPOINT_EVENT()` macros of 'TEMPLATE'.
 
 Here's an example:
 
 ---------------------------------------
-TRACEPOINT_EVENT(
+LTTNG_UST_TRACEPOINT_EVENT(
     // Tracepoint provider name
     my_provider,
 
@@ -62,11 +63,11 @@ TRACEPOINT_EVENT(
     my_event,
 
     // Tracepoint arguments (input)
-    TP_ARGS(char *, text),
+    LTTNG_UST_TP_ARGS(char *, text),
 
     // Tracepoint/event fields (output)
-    TP_FIELDS(
-        ctf_string(message, text)
+    LTTNG_UST_TP_FIELDS(
+        lttng_ust_field_string(message, text)
     )
 )
 ---------------------------------------
index 5105f76be38d7f59829e4d9fa91446f636804e3e..73aac26c7de75f8ca7d2a2affbc0e9bf4a0e266a 100644 (file)
@@ -1,5 +1,5 @@
-lttng-ust-dl(3)
-===============
+lttng-ust-cyg-profile(3)
+========================
 :object-type: library
 
 
@@ -100,7 +100,7 @@ Fast function tracing
 ~~~~~~~~~~~~~~~~~~~~~
 The following LTTng-UST events are available when using
 `liblttng-ust-cyg-profile-fast.so`. Their log level is set to
-`TRACE_DEBUG_FUNCTION`.
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_FUNCTION`.
 
 `lttng_ust_cyg_profile_fast:func_entry`::
     Emitted when an application function is entered, or more
@@ -132,7 +132,7 @@ Verbose function tracing
 ~~~~~~~~~~~~~~~~~~~~~~~~
 The following LTTng-UST events are available when using
 `liblttng-ust-cyg-profile.so`. Their log level is set to
-`TRACE_DEBUG_FUNCTION`.
+`LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG_FUNCTION`.
 
 `lttng_ust_cyg_profile:func_entry`::
     Emitted when an application function is entered, or more
index aa157019df41dd474fdeef02ed1984a9b79b6ae3..55b2b20dedba75e6895d9fe4147f7e579b34d90f 100644 (file)
@@ -14,56 +14,72 @@ SYNOPSIS
 *#include <lttng/tracepoint.h>*
 
 [verse]
-#define *TRACEPOINT_ENUM*('prov_name', 'enum_name', 'mappings')
-#define *TRACEPOINT_EVENT*('prov_name', 't_name', 'args', 'fields')
-#define *TRACEPOINT_EVENT_CLASS*('prov_name', 'class_name', 'args', 'fields')
-#define *TRACEPOINT_EVENT_INSTANCE*('prov_name', 'class_name', 't_name', 'args')
-#define *TRACEPOINT_LOGLEVEL*('prov_name', 't_name', 'level')
-#define *ctf_array*('int_type', 'field_name', 'expr', 'count')
-#define *ctf_array_nowrite*('int_type', 'field_name', 'expr', 'count')
-#define *ctf_array_hex*('int_type', 'field_name', 'expr', 'count')
-#define *ctf_array_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
-#define *ctf_array_network*('int_type', 'field_name', 'expr', 'count')
-#define *ctf_array_network_nowrite*('int_type', 'field_name', 'expr', 'count')
-#define *ctf_array_network_hex*('int_type', 'field_name', 'expr', 'count')
-#define *ctf_array_network_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
-#define *ctf_array_text*(char, 'field_name', 'expr', 'count')
-#define *ctf_array_text_nowrite*(char, 'field_name', 'expr', 'count')
-#define *ctf_enum*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr')
-#define *ctf_enum_nowrite*('prov_name', 'enum_name', 'int_type', 'field_name',
-                         'expr')
-#define *ctf_enum_value*('label', 'value')
-#define *ctf_enum_range*('label', 'start', 'end')
-#define *ctf_float*('float_type', 'field_name', 'expr')
-#define *ctf_float_nowrite*('float_type', 'field_name', 'expr')
-#define *ctf_integer*('int_type', 'field_name', 'expr')
-#define *ctf_integer_hex*('int_type', 'field_name', 'expr')
-#define *ctf_integer_network*('int_type', 'field_name', 'expr')
-#define *ctf_integer_network_hex*('int_type', 'field_name', 'expr')
-#define *ctf_integer_nowrite*('int_type', 'field_name', 'expr')
-#define *ctf_sequence*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
-#define *ctf_sequence_nowrite*('int_type', 'field_name', 'expr', 'len_type',
-                             'len_expr')
-#define *ctf_sequence_hex*('int_type', 'field_name', 'expr', 'len_type',
-                         'len_expr')
-#define *ctf_sequence_nowrite_hex*('int_type', 'field_name', 'expr', 'len_type',
-                                 'len_expr')
-#define *ctf_sequence_network*('int_type', 'field_name', 'expr', 'len_type',
-                             'len_expr')
-#define *ctf_sequence_network_nowrite*('int_type', 'field_name', 'expr',
+#define *LTTNG_UST_TP_ARGS*('args'...)
+#define *LTTNG_UST_TP_ENUM_VALUES*('values'...)
+#define *LTTNG_UST_TP_FIELDS*('fields'...)
+#define *LTTNG_UST_TRACEPOINT_ENUM*('prov_name', 'enum_name', 'mappings')
+#define *LTTNG_UST_TRACEPOINT_EVENT*('prov_name', 't_name', 'args', 'fields')
+#define *LTTNG_UST_TRACEPOINT_EVENT_CLASS*('cls_prov_name', 'cls_name',
+                                         'args', 'fields')
+#define *LTTNG_UST_TRACEPOINT_EVENT_INSTANCE*('cls_prov_name', 'cls_name',
+                                            'inst_prov_name', 't_name', 'args')
+#define *LTTNG_UST_TRACEPOINT_LOGLEVEL*('prov_name', 't_name', 'level')
+#define *lttng_ust_do_tracepoint*('prov_name', 't_name', ...)
+#define *lttng_ust_field_array*('int_type', 'field_name', 'expr', 'count')
+#define *lttng_ust_field_array_nowrite*('int_type', 'field_name', 'expr', 'count')
+#define *lttng_ust_field_array_hex*('int_type', 'field_name', 'expr', 'count')
+#define *lttng_ust_field_array_nowrite_hex*('int_type', 'field_name', 'expr',
+                                          'count')
+#define *lttng_ust_field_array_network*('int_type', 'field_name', 'expr', 'count')
+#define *lttng_ust_field_array_network_nowrite*('int_type', 'field_name',
+                                              'expr', 'count')
+#define *lttng_ust_field_array_network_hex*('int_type', 'field_name', 'expr',
+                                          'count')
+#define *lttng_ust_field_array_network_nowrite_hex*('int_type', 'field_name',
+                                                  'expr', 'count')
+#define *lttng_ust_field_array_text*(char, 'field_name', 'expr', 'count')
+#define *lttng_ust_field_array_text_nowrite*(char, 'field_name', 'expr',
+                                           'count')
+#define *lttng_ust_field_enum*('prov_name', 'enum_name', 'int_type', 'field_name',
+                             'expr')
+#define *lttng_ust_field_enum_nowrite*('prov_name', 'enum_name', 'int_type',
+                                     'field_name', 'expr')
+#define *lttng_ust_field_enum_value*('label', 'value')
+#define *lttng_ust_field_enum_range*('label', 'start', 'end')
+#define *lttng_ust_field_float*('float_type', 'field_name', 'expr')
+#define *lttng_ust_field_float_nowrite*('float_type', 'field_name', 'expr')
+#define *lttng_ust_field_integer*('int_type', 'field_name', 'expr')
+#define *lttng_ust_field_integer_hex*('int_type', 'field_name', 'expr')
+#define *lttng_ust_field_integer_network*('int_type', 'field_name', 'expr')
+#define *lttng_ust_field_integer_network_hex*('int_type', 'field_name', 'expr')
+#define *lttng_ust_field_integer_nowrite*('int_type', 'field_name', 'expr')
+#define *lttng_ust_field_sequence*('int_type', 'field_name', 'expr',
+                                 'len_type', 'len_expr')
+#define *lttng_ust_field_sequence_nowrite*('int_type', 'field_name', 'expr',
+                                         'len_type', 'len_expr')
+#define *lttng_ust_field_sequence_hex*('int_type', 'field_name', 'expr',
                                      'len_type', 'len_expr')
-#define *ctf_sequence_network_hex*('int_type', 'field_name', 'expr', 'len_type',
-                                 'len_expr')
-#define *ctf_sequence_network_nowrite_hex*('int_type', 'field_name', 'expr',
+#define *lttng_ust_field_sequence_nowrite_hex*('int_type', 'field_name', 'expr',
+                                             'len_type', 'len_expr')
+#define *lttng_ust_field_sequence_network*('int_type', 'field_name', 'expr',
                                          'len_type', 'len_expr')
-#define *ctf_sequence_text*(char, 'field_name', 'expr', 'len_type', 'len_expr')
-#define *ctf_sequence_text_nowrite*(char, 'field_name', 'expr', 'len_type',
-                                  'len_expr')
-#define *ctf_string*('field_name', 'expr')
-#define *ctf_string_nowrite*('field_name', 'expr')
-#define *do_tracepoint*('prov_name', 't_name', ...)
-#define *tracepoint*('prov_name', 't_name', ...)
-#define *tracepoint_enabled*('prov_name', 't_name')
+#define *lttng_ust_field_sequence_network_nowrite*('int_type', 'field_name',
+                                                 'expr', 'len_type',
+                                                 'len_expr')
+#define *lttng_ust_field_sequence_network_hex*('int_type', 'field_name', 'expr',
+                                             'len_type', 'len_expr')
+#define *lttng_ust_field_sequence_network_nowrite_hex*('int_type',
+                                                     'field_name',
+                                                     'expr', 'len_type',
+                                                     'len_expr')
+#define *lttng_ust_field_sequence_text*(char, 'field_name', 'expr', 'len_type',
+                                      'len_expr')
+#define *lttng_ust_field_sequence_text_nowrite*(char, 'field_name', 'expr',
+                                              'len_type', 'len_expr')
+#define *lttng_ust_field_string*('field_name', 'expr')
+#define *lttng_ust_field_string_nowrite*('field_name', 'expr')
+#define *lttng_ust_tracepoint*('prov_name', 't_name', ...)
+#define *lttng_ust_tracepoint_enabled*('prov_name', 't_name')
 
 Link with `-llttng-ust -llttng-ust-common -ldl`, following this man page.
 
@@ -87,25 +103,57 @@ http://lttng.org/docs/[the online LTTng documentation].
 
 There are three ways to use `liblttng-ust`:
 
-  * Using the man:tracef(3) API, which is similar to man:printf(3).
-  * Using the man:tracelog(3) API, which is man:tracef(3) with
-    a log level parameter.
+  * Using the man:lttng_ust_tracef(3) API, which is similar to
+    man:printf(3).
+  * Using the man:lttng_ust_tracelog(3) API, which is
+    man:lttng_ust_tracef(3) with a log level parameter.
   * Defining your own tracepoints. See the
     <<creating-tp,Creating a tracepoint provider>> section below.
 
 
+Compatibility with previous APIs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Since LTTng-UST{nbsp}2.13, the `LTTNG_UST_COMPAT_API_VERSION` definition
+controls which LTTng-UST APIs are available (compiled):
+
+Undefined::
+    All APIs are available.
+
+'N' (0 or positive integer)::
+    API version{nbsp}__N__, and all the following existing APIs, are
+    available. Previous APIs are not available (not compiled).
+
+The following table shows the mapping from LTTng-UST versions (up to
+LTTng-UST{nbsp}{manversion}) to available API versions:
+
+[options="header"]
+|====
+|LTTng-UST version |Available API versions
+|2.0 to 2.12 |0
+|2.13 |0 and 1
+|====
+
+This manual page **only** documents version{nbsp}1 of the API.
+
+If you wish to have access to version{nbsp}0 of the API (for example,
+the `tracepoint()`, `ctf_integer()`, and `TRACEPOINT_EVENT()` macros),
+then either don't define `LTTNG_UST_COMPAT_API_VERSION`, or define it to
+`0` before including any LTTng-UST header.
+
+
 [[creating-tp]]
 Creating a tracepoint provider
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Creating a tracepoint provider is the first step of using
 `liblttng-ust`. The next steps are:
 
-  * <<tracepoint,Instrumenting your application with `tracepoint()` calls>>
+  * <<tracepoint,Instrumenting your application with
+    `lttng_ust_tracepoint()` calls>>
   * Building your application with LTTng-UST support, either
     <<build-static,statically>> or <<build-dynamic,dynamically>>.
 
-A *tracepoint provider* is a compiled object containing the event
-probes corresponding to your custom tracepoint definitions. A tracepoint
+A *tracepoint provider* is a compiled object containing the event probes
+corresponding to your custom tracepoint definitions. A tracepoint
 provider contains the code to get the size of an event and to serialize
 it, amongst other things.
 
@@ -113,21 +161,23 @@ To create a tracepoint provider, start with the following
 _tracepoint provider header_ template:
 
 ------------------------------------------------------------------------
-#undef TRACEPOINT_PROVIDER
-#define TRACEPOINT_PROVIDER my_provider
+#undef LTTNG_UST_TRACEPOINT_PROVIDER
+#define LTTNG_UST_TRACEPOINT_PROVIDER my_provider
 
-#undef TRACEPOINT_INCLUDE
-#define TRACEPOINT_INCLUDE "./tp.h"
+#undef LTTNG_UST_TRACEPOINT_INCLUDE
+#define LTTNG_UST_TRACEPOINT_INCLUDE "./tp.h"
 
-#if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
+#if !defined(_TP_H) || \
+    defined(LTTNG_UST_TRACEPOINT_HEADER_MULTI_READ)
 #define _TP_H
 
 #include <lttng/tracepoint.h>
 
 /*
- * TRACEPOINT_EVENT(), TRACEPOINT_EVENT_CLASS(),
- * TRACEPOINT_EVENT_INSTANCE(), TRACEPOINT_LOGLEVEL(),
- * and `TRACEPOINT_ENUM()` are used here.
+ * LTTNG_UST_TRACEPOINT_EVENT(), LTTNG_UST_TRACEPOINT_EVENT_CLASS(),
+ * LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(),
+ * LTTNG_UST_TRACEPOINT_LOGLEVEL(), and `LTTNG_UST_TRACEPOINT_ENUM()`
+ * are used here.
  */
 
 #endif /* _TP_H */
@@ -136,14 +186,14 @@ _tracepoint provider header_ template:
 ------------------------------------------------------------------------
 
 In this template, the tracepoint provider is named `my_provider`
-(`TRACEPOINT_PROVIDER` definition). The file needs to bear the
-name of the `TRACEPOINT_INCLUDE` definition (`tp.h` in this case).
+(`LTTNG_UST_TRACEPOINT_PROVIDER` definition). The file needs to bear the
+name of the `LTTNG_UST_TRACEPOINT_INCLUDE` definition (`tp.h` in this case).
 Between `#include <lttng/tracepoint.h>` and `#endif` go
-the invocations of the <<tracepoint-event,`TRACEPOINT_EVENT()`>>,
-<<tracepoint-event-class,`TRACEPOINT_EVENT_CLASS()`>>,
-<<tracepoint-event-class,`TRACEPOINT_EVENT_INSTANCE()`>>,
-<<tracepoint-loglevel,`TRACEPOINT_LOGLEVEL()`>>, and
-<<tracepoint-enum,`TRACEPOINT_ENUM()`>> macros.
+the invocations of the <<tracepoint-event,`LTTNG_UST_TRACEPOINT_EVENT()`>>,
+<<tracepoint-event-class,`LTTNG_UST_TRACEPOINT_EVENT_CLASS()`>>,
+<<tracepoint-event-class,`LTTNG_UST_TRACEPOINT_EVENT_INSTANCE()`>>,
+<<tracepoint-loglevel,`LTTNG_UST_TRACEPOINT_LOGLEVEL()`>>, and
+<<tracepoint-enum,`LTTNG_UST_TRACEPOINT_ENUM()`>> macros.
 
 NOTE: You can avoid writing the prologue and epilogue boilerplate in the
 template file above by using the man:lttng-gen-tp(1) tool shipped with
@@ -153,7 +203,7 @@ The tracepoint provider header file needs to be included in a source
 file which looks like this:
 
 ------------------------------------------------------------------------
-#define TRACEPOINT_CREATE_PROBES
+#define LTTNG_UST_TRACEPOINT_CREATE_PROBES
 
 #include "tp.h"
 ------------------------------------------------------------------------
@@ -164,24 +214,24 @@ tracepoint provider sources, ready to be compiled.
 You can create multiple tracepoint providers to be used in a single
 application, but each one must have its own header file.
 
-The <<tracepoint-event,`TRACEPOINT_EVENT()` usage>> section below
-shows how to use the `TRACEPOINT_EVENT()` macro to define the actual
+The <<tracepoint-event,`LTTNG_UST_TRACEPOINT_EVENT()` usage>> section below
+shows how to use the `LTTNG_UST_TRACEPOINT_EVENT()` macro to define the actual
 tracepoints in the tracepoint provider header file.
 
 See the <<example,EXAMPLE>> section below for a complete example.
 
 
 [[tracepoint-event]]
-`TRACEPOINT_EVENT()` usage
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-The `TRACEPOINT_EVENT()` macro is used in a template provider
+`LTTNG_UST_TRACEPOINT_EVENT()` usage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The `LTTNG_UST_TRACEPOINT_EVENT()` macro is used in a template provider
 header file (see the <<creating-tp,Creating a tracepoint provider>>
 section above) to define LTTng-UST tracepoints.
 
-The `TRACEPOINT_EVENT()` usage template is as follows:
+The `LTTNG_UST_TRACEPOINT_EVENT()` usage template is as follows:
 
 ------------------------------------------------------------------------
-TRACEPOINT_EVENT(
+LTTNG_UST_TRACEPOINT_EVENT(
     /* Tracepoint provider name */
     my_provider,
 
@@ -189,26 +239,26 @@ TRACEPOINT_EVENT(
     my_tracepoint,
 
     /* List of tracepoint arguments (input) */
-    TP_ARGS(
+    LTTNG_UST_TP_ARGS(
         ...
     ),
 
     /* List of fields of eventual event (output) */
-    TP_FIELDS(
+    LTTNG_UST_TP_FIELDS(
         ...
     )
 )
 ------------------------------------------------------------------------
 
-The `TP_ARGS()` macro contains the input arguments of the tracepoint.
+The `LTTNG_UST_TP_ARGS()` macro contains the input arguments of the tracepoint.
 Those arguments can be used in the argument expressions of the output
-fields defined in `TP_FIELDS()`.
+fields defined in `LTTNG_UST_TP_FIELDS()`.
 
-The format of the `TP_ARGS()` parameters is: C type, then argument name;
+The format of the `LTTNG_UST_TP_ARGS()` parameters is: C type, then argument name;
 repeat as needed, up to ten times. For example:
 
 ------------------------------------------------------------------------
-TP_ARGS(
+LTTNG_UST_TP_ARGS(
     int, my_int,
     const char *, my_string,
     FILE *, my_file,
@@ -217,105 +267,118 @@ TP_ARGS(
 )
 ------------------------------------------------------------------------
 
-The `TP_FIELDS()` macro contains the output fields of the tracepoint,
-that is, the actual data that can be recorded in the payload of an
-event emitted by this tracepoint.
+The `LTTNG_UST_TP_FIELDS()` macro contains the output fields of the tracepoint,
+that is, the actual data that can be recorded in the payload of an event
+emitted by this tracepoint.
 
-The `TP_FIELDS()` macro contains a list of `ctf_*()` macros
-:not: separated by commas. The available macros are documented in the
-<<ctf-macros,Available `ctf_*()` field type macros>> section below.
+The `LTTNG_UST_TP_FIELDS()` macro contains a list of
+`lttng_ust_field_*()` macros :not: separated by commas.
+The available macros are documented in the
+<<ctf-macros,Available `lttng_ust_field_*()` field type macros>>
+section below.
 
 
 [[ctf-macros]]
-Available `ctf_*()` field type macros
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This section documents the available `ctf_*()` macros that can be
-inserted in the `TP_FIELDS()` macro of the
-<<tracepoint-event,`TRACEPOINT_EVENT()` macro>>.
+Available field macros
+~~~~~~~~~~~~~~~~~~~~~~
+This section documents the available `lttng_ust_field_*()` macros that
+can be inserted in the `LTTNG_UST_TP_FIELDS()` macro of the
+<<tracepoint-event,`LTTNG_UST_TRACEPOINT_EVENT()` macro>>.
 
 Standard integer, displayed in base 10:
 
 [verse]
-*ctf_integer*('int_type', 'field_name', 'expr')
-*ctf_integer_nowrite*('int_type', 'field_name', 'expr')
+*lttng_ust_field_integer*('int_type', 'field_name', 'expr')
+*lttng_ust_field_integer_nowrite*('int_type', 'field_name', 'expr')
 
 Standard integer, displayed in base 16:
 
 [verse]
-*ctf_integer_hex*('int_type', 'field_name', 'expr')
+*lttng_ust_field_integer_hex*('int_type', 'field_name', 'expr')
 
 Integer in network byte order (big endian), displayed in base 10:
 
 [verse]
-*ctf_integer_network*('int_type', 'field_name', 'expr')
+*lttng_ust_field_integer_network*('int_type', 'field_name', 'expr')
 
 Integer in network byte order, displayed in base 16:
 
 [verse]
-*ctf_integer_network_hex*('int_type', 'field_name', 'expr')
+*lttng_ust_field_integer_network_hex*('int_type', 'field_name', 'expr')
 
 Floating point number:
 
 [verse]
-*ctf_float*('float_type', 'field_name', 'expr')
-*ctf_float_nowrite*('float_type', 'field_name', 'expr')
+*lttng_ust_field_float*('float_type', 'field_name', 'expr')
+*lttng_ust_field_float_nowrite*('float_type', 'field_name', 'expr')
 
 Null-terminated string:
 
 [verse]
-*ctf_string*('field_name', 'expr')
-*ctf_string_nowrite*('field_name', 'expr')
+*lttng_ust_field_string*('field_name', 'expr')
+*lttng_ust_field_string_nowrite*('field_name', 'expr')
 
 Statically-sized array of integers (`_hex` versions displayed in
 hexadecimal, `_network` versions in network byte order):
 
 [verse]
-*ctf_array*('int_type', 'field_name', 'expr', 'count')
-*ctf_array_nowrite*('int_type', 'field_name', 'expr', 'count')
-*ctf_array_hex*('int_type', 'field_name', 'expr', 'count')
-*ctf_array_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
-*ctf_array_network*('int_type', 'field_name', 'expr', 'count')
-*ctf_array_network_nowrite*('int_type', 'field_name', 'expr', 'count')
-*ctf_array_network_hex*('int_type', 'field_name', 'expr', 'count')
-*ctf_array_network_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
+*lttng_ust_field_array*('int_type', 'field_name', 'expr', 'count')
+*lttng_ust_field_array_nowrite*('int_type', 'field_name', 'expr', 'count')
+*lttng_ust_field_array_hex*('int_type', 'field_name', 'expr', 'count')
+*lttng_ust_field_array_nowrite_hex*('int_type', 'field_name', 'expr', 'count')
+*lttng_ust_field_array_network*('int_type', 'field_name', 'expr', 'count')
+*lttng_ust_field_array_network_nowrite*('int_type', 'field_name', 'expr',
+                                      'count')
+*lttng_ust_field_array_network_hex*('int_type', 'field_name', 'expr', 'count')
+*lttng_ust_field_array_network_nowrite_hex*('int_type', 'field_name',
+                                          'expr', 'count')
 
 Statically-sized array, printed as text; no need to be null-terminated:
 
 [verse]
-*ctf_array_text*(char, 'field_name', 'expr', 'count')
-*ctf_array_text_nowrite*(char, 'field_name', 'expr', 'count')
+*lttng_ust_field_array_text*(char, 'field_name', 'expr', 'count')
+*lttng_ust_field_array_text_nowrite*(char, 'field_name', 'expr', 'count')
 
 Dynamically-sized array of integers (`_hex` versions displayed in
 hexadecimal, `_network` versions in network byte order):
 
 [verse]
-*ctf_sequence*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
-*ctf_sequence_nowrite*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
-*ctf_sequence_hex*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
-*ctf_sequence_nowrite_hex*('int_type', 'field_name', 'expr', 'len_type',
+*lttng_ust_field_sequence*('int_type', 'field_name', 'expr', 'len_type',
                          'len_expr')
-*ctf_sequence_network*('int_type', 'field_name', 'expr', 'len_type', 'len_expr')
-*ctf_sequence_network_nowrite*('int_type', 'field_name', 'expr', 'len_type',
+*lttng_ust_field_sequence_nowrite*('int_type', 'field_name', 'expr',
+                                 'len_type', 'len_expr')
+*lttng_ust_field_sequence_hex*('int_type', 'field_name', 'expr', 'len_type',
                              'len_expr')
-*ctf_sequence_network_hex*('int_type', 'field_name', 'expr', 'len_type',
-                         'len_expr')
-*ctf_sequence_network_nowrite_hex*('int_type', 'field_name', 'expr',
+*lttng_ust_field_sequence_nowrite_hex*('int_type', 'field_name', 'expr',
+                                     'len_type', 'len_expr')
+*lttng_ust_field_sequence_network*('int_type', 'field_name', 'expr',
                                  'len_type', 'len_expr')
+*lttng_ust_field_sequence_network_nowrite*('int_type', 'field_name', 'expr',
+                                         'len_type', 'len_expr')
+*lttng_ust_field_sequence_network_hex*('int_type', 'field_name', 'expr',
+                                     'len_type', 'len_expr')
+*lttng_ust_field_sequence_network_nowrite_hex*('int_type', 'field_name',
+                                             'expr', 'len_type',
+                                             'len_expr')
 
 Dynamically-sized array, displayed as text; no need to be null-terminated:
 
 [verse]
-*ctf_sequence_text*(char, 'field_name', 'expr', 'len_type', 'len_expr')
-*ctf_sequence_text_nowrite*(char, 'field_name', 'expr', 'len_type', 'len_expr')
+*lttng_ust_field_sequence_text*(char, 'field_name', 'expr', 'len_type',
+                              'len_expr')
+*lttng_ust_field_sequence_text_nowrite*(char, 'field_name', 'expr',
+                                      'len_type', 'len_expr')
 
 Enumeration. The enumeration field must be defined before using this
-macro with the `TRACEPOINT_ENUM()` macro. See the
-<<tracepoint-enum,`TRACEPOINT_ENUM()` usage>> section for more
+macro with the `LTTNG_UST_TRACEPOINT_ENUM()` macro. See the
+<<tracepoint-enum,`LTTNG_UST_TRACEPOINT_ENUM()` usage>> section for more
 information.
 
 [verse]
-*ctf_enum*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr')
-*ctf_enum_nowrite*('prov_name', 'enum_name', 'int_type', 'field_name', 'expr')
+*lttng_ust_field_enum*('prov_name', 'enum_name', 'int_type', 'field_name',
+                     'expr')
+*lttng_ust_field_enum_nowrite*('prov_name', 'enum_name', 'int_type',
+                             'field_name', 'expr')
 
 The parameters are:
 
@@ -325,14 +388,14 @@ The parameters are:
 
 'enum_name'::
     Name of an enumeration field previously defined with the
-    `TRACEPOINT_ENUM()` macro. See the
-    <<tracepoint-enum,`TRACEPOINT_ENUM()` usage>> section for more
+    `LTTNG_UST_TRACEPOINT_ENUM()` macro. See the
+    <<tracepoint-enum,`LTTNG_UST_TRACEPOINT_ENUM()` usage>> section for more
     information.
 
 'expr'::
     C expression resulting in the field's value. This expression can
     use one or more arguments passed to the tracepoint. The arguments
-    of a given tracepoint are defined in the `TP_ARGS()` macro (see
+    of a given tracepoint are defined in the `LTTNG_UST_TP_ARGS()` macro (see
     the <<creating-tp,Creating a tracepoint provider>> section above).
 
 'field_name'::
@@ -367,17 +430,18 @@ See the <<example,EXAMPLE>> section below for a complete example.
 
 
 [[tracepoint-enum]]
-`TRACEPOINT_ENUM()` usage
-~~~~~~~~~~~~~~~~~~~~~~~~~
+`LTTNG_UST_TRACEPOINT_ENUM()` usage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 An enumeration field is a list of mappings between an integers, or a
 range of integers, and strings (sometimes called _labels_ or
 _enumerators_). Enumeration fields can be used to have a more compact
 trace when the possible values for a field are limited.
 
-An enumeration field is defined with the `TRACEPOINT_ENUM()` macro:
+An enumeration field is defined with the `LTTNG_UST_TRACEPOINT_ENUM()`
+macro:
 
 ------------------------------------------------------------------------
-TRACEPOINT_ENUM(
+LTTNG_UST_TRACEPOINT_ENUM(
     /* Tracepoint provider name */
     my_provider,
 
@@ -385,27 +449,28 @@ TRACEPOINT_ENUM(
     my_enum,
 
     /* Enumeration mappings */
-    TP_ENUM_VALUES(
+    LTTNG_UST_TP_ENUM_VALUES(
         ...
     )
 )
 ------------------------------------------------------------------------
 
-`TP_ENUM_VALUES()` contains a list of enumeration mappings, :not:
-separated by commas. Two macros can be used in the `TP_ENUM_VALUES()`:
-`ctf_enum_value()` and `ctf_enum_range()`.
+`LTTNG_UST_TP_ENUM_VALUES()` contains a list of enumeration mappings,
+:not: separated by commas. Two macros can be used in the
+`LTTNG_UST_TP_ENUM_VALUES()`: `lttng_ust_field_enum_value()` and
+`lttng_ust_field_enum_range()`.
 
-`ctf_enum_value()` is a single value mapping:
+`lttng_ust_field_enum_value()` is a single value mapping:
 
 [verse]
-*ctf_enum_value*('label', 'value')
+*lttng_ust_field_enum_value*('label', 'value')
 
 This macro maps the given 'label' string to the value 'value'.
 
-`ctf_enum_range()` is a range mapping:
+`lttng_ust_field_enum_range()` is a range mapping:
 
 [verse]
-*ctf_enum_range*('label', 'start', 'end')
+*lttng_ust_field_enum_range*('label', 'start', 'end')
 
 This macro maps the given 'label' string to the range of integers from
 'start' to 'end', inclusively. Range mappings may overlap, but the
@@ -416,40 +481,46 @@ See the <<example,EXAMPLE>> section below for a complete example.
 
 
 [[tracepoint-event-class]]
-`TRACEPOINT_EVENT_CLASS()` usage
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`LTTNG_UST_TRACEPOINT_EVENT_CLASS()` usage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 A *tracepoint class* is a class of tracepoints sharing the
 same field types and names. A tracepoint instance is one instance of
 such a declared tracepoint class, with its own event name.
 
-LTTng-UST creates one event serialization function per tracepoint
-class. Using `TRACEPOINT_EVENT()` creates one tracepoint class per
-tracepoint definition, whereas using `TRACEPOINT_EVENT_CLASS()` and
-`TRACEPOINT_EVENT_INSTANCE()` creates one tracepoint class, and one or
-more tracepoint instances of this class. In other words, many
+LTTng-UST creates one event serialization function per tracepoint class.
+Using `LTTNG_UST_TRACEPOINT_EVENT()` creates one tracepoint class per
+tracepoint definition, whereas using
+`LTTNG_UST_TRACEPOINT_EVENT_CLASS()` and
+`LTTNG_UST_TRACEPOINT_EVENT_INSTANCE()` creates one tracepoint class,
+and one or more tracepoint instances of this class. In other words, many
 tracepoints can reuse the same serialization code. Reusing the same
 code, when possible, can reduce cache pollution, thus improve
 performance.
 
-The `TRACEPOINT_EVENT_CLASS()` macro accepts the same parameters as
-the `TRACEPOINT_EVENT()` macro, except that instead of an event name,
-its second parameter is the _tracepoint class name_:
+The `LTTNG_UST_TRACEPOINT_EVENT_CLASS()` macro accepts the same
+parameters as the `LTTNG_UST_TRACEPOINT_EVENT()` macro, except that
+instead of an event name, its second parameter is the _tracepoint class
+name_:
 
 ------------------------------------------------------------------------
-TRACEPOINT_EVENT_CLASS(
-    /* Tracepoint provider name */
+#define LTTNG_UST_TRACEPOINT_PROVIDER my_provider
+
+/* ... */
+
+LTTNG_UST_TRACEPOINT_EVENT_CLASS(
+    /* Tracepoint class provider name */
     my_provider,
 
     /* Tracepoint class name */
     my_tracepoint_class,
 
     /* List of tracepoint arguments (input) */
-    TP_ARGS(
+    LTTNG_UST_TP_ARGS(
         ...
     ),
 
     /* List of fields of eventual event (output) */
-    TP_FIELDS(
+    LTTNG_UST_TP_FIELDS(
         ...
     )
 )
@@ -459,33 +530,58 @@ Once the tracepoint class is defined, you can create as many tracepoint
 instances as needed:
 
 -------------------------------------------------------------------------
-TRACEPOINT_EVENT_INSTANCE(
-    /* Tracepoint provider name */
+#define LTTNG_UST_TRACEPOINT_PROVIDER natality
+
+/* ... */
+
+LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
+    /* Name of the tracepoint class provider */
     my_provider,
 
     /* Tracepoint class name */
     my_tracepoint_class,
 
+    /* Name of the local (instance) tracepoint provider */
+    natality,
+
     /* Tracepoint/event name */
     my_tracepoint,
 
     /* List of tracepoint arguments (input) */
-    TP_ARGS(
+    LTTNG_UST_TP_ARGS(
         ...
     )
 )
 ------------------------------------------------------------------------
 
-As you can see, the `TRACEPOINT_EVENT_INSTANCE()` does not contain
-the `TP_FIELDS()` macro, because they are defined at the
-`TRACEPOINT_EVENT_CLASS()` level.
+As you can see, the `LTTNG_UST_TRACEPOINT_EVENT_INSTANCE()` does not
+contain the `LTTNG_UST_TP_FIELDS()` macro, because they are defined at
+the `LTTNG_UST_TRACEPOINT_EVENT_CLASS()` level.
+
+Note that the `LTTNG_UST_TRACEPOINT_EVENT_INSTANCE()` macro requires two
+provider names:
+
+* The name of the tracepoint class provider (`my_provider` in the
+  example above).
++
+This is the same as the first argument of the
+`LTTNG_UST_TRACEPOINT_EVENT_CLASS()` expansion to refer to.
+
+* The name of the local, or instance, provider (`natality` in the
+  example above).
++
+This is the provider name which becomes the prefix part of the name of
+the events which such a tracepoint creates.
+
+The two provider names may be different if the tracepoint class and the
+tracepoint instance macros are in two different translation units.
 
 See the <<example,EXAMPLE>> section below for a complete example.
 
 
 [[tracepoint-loglevel]]
-`TRACEPOINT_LOGLEVEL()` usage
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`LTTNG_UST_TRACEPOINT_LOGLEVEL()` usage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Optionally, a *log level* can be assigned to a defined tracepoint.
 Assigning different levels of severity to tracepoints can be useful:
 when controlling tracing sessions, you can choose to only enable
@@ -494,12 +590,13 @@ nloption:--loglevel and nloption:--loglevel-only options of the
 man:lttng-enable-event(1) command.
 
 Log levels are assigned to tracepoints that are already defined using
-the `TRACEPOINT_LOGLEVEL()` macro. The latter must be used after having
-used `TRACEPOINT_EVENT()` or `TRACEPOINT_EVENT_INSTANCE()` for a given
-tracepoint. The `TRACEPOINT_LOGLEVEL()` macro is used as follows:
+the `LTTNG_UST_TRACEPOINT_LOGLEVEL()` macro. The latter must be used
+after having used `LTTNG_UST_TRACEPOINT_EVENT()` or
+`LTTNG_UST_TRACEPOINT_EVENT_INSTANCE()` for a given tracepoint. The
+`LTTNG_UST_TRACEPOINT_LOGLEVEL()` macro is used as follows:
 
 ------------------------------------------------------------------------
-TRACEPOINT_LOGLEVEL(
+LTTNG_UST_TRACEPOINT_LOGLEVEL(
     /* Tracepoint provider name */
     my_provider,
 
@@ -507,7 +604,7 @@ TRACEPOINT_LOGLEVEL(
     my_tracepoint,
 
     /* Log level */
-    TRACE_INFO
+    LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO
 )
 ------------------------------------------------------------------------
 
@@ -524,10 +621,10 @@ Instrumenting your application
 Once the tracepoint provider is created (see the
 <<creating-tp,Creating a tracepoint provider>> section above), you can
 instrument your application with the defined tracepoints thanks to the
-`tracepoint()` macro:
+`lttng_ust_tracepoint()` macro:
 
 [verse]
-#define *tracepoint*('prov_name', 't_name', ...)
+#define *lttng_ust_tracepoint*('prov_name', 't_name', ...)
 
 With:
 
@@ -541,48 +638,48 @@ With:
     Tracepoint arguments, if any.
 
 Make sure to include the tracepoint provider header file anywhere you
-use `tracepoint()` for this provider.
+use `lttng_ust_tracepoint()` for this provider.
 
-NOTE: Even though LTTng-UST supports `tracepoint()` call site duplicates
-having the same provider and tracepoint names, it is recommended to use
-a provider/tracepoint name pair only once within the application source
-code to help map events back to their call sites when analyzing the
-trace.
+NOTE: Even though LTTng-UST supports `lttng_ust_tracepoint()` call site
+duplicates having the same provider and tracepoint names, it is
+recommended to use a provider/tracepoint name pair only once within the
+application source code to help map events back to their call sites when
+analyzing the trace.
 
 Sometimes, arguments to the tracepoint are expensive to compute (take
 call stack, for example). To avoid the computation when the tracepoint
-is disabled, you can use the `tracepoint_enabled()` and
-`do_tracepoint()` macros:
+is disabled, you can use the `lttng_ust_tracepoint_enabled()` and
+`lttng_ust_do_tracepoint()` macros:
 
 [verse]
-#define *tracepoint_enabled*('prov_name', 't_name')
-#define *do_tracepoint*('prov_name', 't_name', ...)
+#define *lttng_ust_tracepoint_enabled*('prov_name', 't_name')
+#define *lttng_ust_do_tracepoint*('prov_name', 't_name', ...)
 
-`tracepoint_enabled()` returns a non-zero value if the tracepoint
+`lttng_ust_tracepoint_enabled()` returns a non-zero value if the tracepoint
 named 't_name' from the provider named 'prov_name' is enabled at
 run time.
 
-`do_tracepoint()` is like `tracepoint()`, except that it doesn't check
-if the tracepoint is enabled. Using `tracepoint()` with
-`tracepoint_enabled()` is dangerous since `tracepoint()` also contains
-the `tracepoint_enabled()` check, thus a race condition is possible
+`lttng_ust_do_tracepoint()` is like `lttng_ust_tracepoint()`, except that it doesn't check
+if the tracepoint is enabled. Using `lttng_ust_tracepoint()` with
+`lttng_ust_tracepoint_enabled()` is dangerous since `lttng_ust_tracepoint()` also contains
+the `lttng_ust_tracepoint_enabled()` check, thus a race condition is possible
 in this situation:
 
 ------------------------------------------------------------------------
-if (tracepoint_enabled(my_provider, my_tracepoint)) {
+if (lttng_ust_tracepoint_enabled(my_provider, my_tracepoint)) {
     stuff = prepare_stuff();
 }
 
-tracepoint(my_provider, my_tracepoint, stuff);
+lttng_ust_tracepoint(my_provider, my_tracepoint, stuff);
 ------------------------------------------------------------------------
 
 If the tracepoint is enabled after the condition, then `stuff` is not
 prepared: the emitted event will either contain wrong data, or the
 whole application could crash (segmentation fault, for example).
 
-NOTE: Neither `tracepoint_enabled()` nor `do_tracepoint()` have
-a `STAP_PROBEV()` call, so if you need it, you should emit this call
-yourself.
+NOTE: Neither `lttng_ust_tracepoint_enabled()` nor
+`lttng_ust_do_tracepoint()` have a `STAP_PROBEV()` call, so if you need
+it, you should emit this call yourself.
 
 
 [[build-static]]
@@ -591,13 +688,13 @@ Statically linking the tracepoint provider
 With the static linking method, compiled tracepoint providers are copied
 into the target application.
 
-Define `TRACEPOINT_DEFINE` definition below the
-`TRACEPOINT_CREATE_PROBES` definition in the tracepoint provider
-source:
+Define `LTTNG_UST_TRACEPOINT_DEFINE` definition below the
+`LTTNG_UST_TRACEPOINT_CREATE_PROBES` definition in the tracepoint
+provider source:
 
 ------------------------------------------------------------------------
-#define TRACEPOINT_CREATE_PROBES
-#define TRACEPOINT_DEFINE
+#define LTTNG_UST_TRACEPOINT_CREATE_PROBES
+#define LTTNG_UST_TRACEPOINT_DEFINE
 
 #include "tp.h"
 ------------------------------------------------------------------------
@@ -610,8 +707,8 @@ $ cc -c -I. tp.c
 ----
 
 NOTE: Although an application instrumented with LTTng-UST tracepoints
-can be compiled with a C++ compiler, tracepoint probes should be
-compiled with a C compiler.
+can be compiled with a $$C++$$ compiler, tracepoint probes
+should be compiled with a C compiler.
 
 At this point, you _can_ archive this tracepoint provider object file,
 possibly with other object files of your application or with other
@@ -631,8 +728,8 @@ change, but need not to be otherwise recompiled (unless the tracepoint
 provider's API changes).
 
 Then, link your application with this object file (or with the static
-library containing it) and with `liblttng-ust` and `libdl`
-(`libc` on a BSD system):
+library containing it) and with `liblttng-ust`, `liblttng-ust-common`,
+and `libdl` (`libc` on a BSD system):
 
 [role="term"]
 ----
@@ -655,20 +752,20 @@ much the same as the <<build-static,static linking method>>, except
 that:
 
   * Since the tracepoint provider is not part of the application,
-    `TRACEPOINT_DEFINE` must be defined, for each tracepoint
-    provider, in exactly one source file of the
-    _application_
-  * `TRACEPOINT_PROBE_DYNAMIC_LINKAGE` must be defined next
-    to `TRACEPOINT_DEFINE`
+    `LTTNG_UST_TRACEPOINT_DEFINE` must be defined, for each tracepoint
+    provider, in exactly one source file of the _application_
+  * `LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE` must be defined next to
+    `LTTNG_UST_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, then include the tracepoint provider header
-files afterwards. For example, as `tp-define.c`:
+Regarding `LTTNG_UST_TRACEPOINT_DEFINE` and
+`LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE`, the recommended practice
+is to use a separate C source file in your application to define them,
+then include the tracepoint provider header files afterwards. For
+example, as `tp-define.c`:
 
 ------------------------------------------------------------------------
-#define TRACEPOINT_DEFINE
-#define TRACEPOINT_PROBE_DYNAMIC_LINKAGE
+#define LTTNG_UST_TRACEPOINT_DEFINE
+#define LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE
 
 #include "tp.h"
 ------------------------------------------------------------------------
@@ -686,7 +783,8 @@ It is then linked as a shared library like this:
 
 [role="term"]
 ----
-$ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust -llttng-ust-common
+$ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust \
+     -llttng-ust-common
 ----
 
 This tracepoint provider shared object isn't linked with the user
@@ -1162,13 +1260,14 @@ Tracepoint provider header file
 `tp.h`:
 
 ------------------------------------------------------------------------
-#undef TRACEPOINT_PROVIDER
-#define TRACEPOINT_PROVIDER my_provider
+#undef LTTNG_UST_TRACEPOINT_PROVIDER
+#define LTTNG_UST_TRACEPOINT_PROVIDER my_provider
 
-#undef TRACEPOINT_INCLUDE
-#define TRACEPOINT_INCLUDE "./tp.h"
+#undef LTTNG_USTTRACEPOINT_INCLUDE
+#define LTTNG_USTTRACEPOINT_INCLUDE "./tp.h"
 
-#if !defined(_TP_H) || defined(TRACEPOINT_HEADER_MULTI_READ)
+#if !defined(_TP_H) || \
+    defined(LTTNG_UST_TRACEPOINT_HEADER_MULTI_READ)
 #define _TP_H
 
 #include <lttng/tracepoint.h>
@@ -1176,100 +1275,108 @@ Tracepoint provider header file
 
 #include "app.h"
 
-TRACEPOINT_EVENT(
+LTTNG_UST_TRACEPOINT_EVENT(
     my_provider,
     simple_event,
-    TP_ARGS(
+    LTTNG_UST_TP_ARGS(
         int, my_integer_arg,
         const char *, my_string_arg
     ),
-    TP_FIELDS(
-        ctf_string(argc, my_string_arg)
-        ctf_integer(int, argv, my_integer_arg)
+    LTTNG_UST_TP_FIELDS(
+        lttng_ust_field_string(argc, my_string_arg)
+        lttng_ust_field_integer(int, argv, my_integer_arg)
     )
 )
 
-TRACEPOINT_ENUM(
+LTTNG_UST_TRACEPOINT_ENUM(
     my_provider,
     my_enum,
-    TP_ENUM_VALUES(
-        ctf_enum_value("ZERO", 0)
-        ctf_enum_value("ONE", 1)
-        ctf_enum_value("TWO", 2)
-        ctf_enum_range("A RANGE", 52, 125)
-        ctf_enum_value("ONE THOUSAND", 1000)
+    LTTNG_UST_TP_ENUM_VALUES(
+        lttng_ust_field_enum_value("ZERO", 0)
+        lttng_ust_field_enum_value("ONE", 1)
+        lttng_ust_field_enum_value("TWO", 2)
+        lttng_ust_field_enum_range("A RANGE", 52, 125)
+        lttng_ust_field_enum_value("ONE THOUSAND", 1000)
     )
 )
 
-TRACEPOINT_EVENT(
+LTTNG_UST_TRACEPOINT_EVENT(
     my_provider,
     big_event,
-    TP_ARGS(
+    LTTNG_UST_TP_ARGS(
         int, my_integer_arg,
         const char *, my_string_arg,
         FILE *, stream,
         double, flt_arg,
         int *, array_arg
     ),
-    TP_FIELDS(
-        ctf_integer(int, int_field1, my_integer_arg * 2)
-        ctf_integer_hex(long int, stream_pos, ftell(stream))
-        ctf_float(double, float_field, flt_arg)
-        ctf_string(string_field, my_string_arg)
-        ctf_array(int, array_field, array_arg, 7)
-        ctf_array_text(char, array_text_field, array_arg, 5)
-        ctf_sequence(int, seq_field, array_arg, int,
-                     my_integer_arg / 10)
-        ctf_sequence_text(char, seq_text_field, array_arg,
-                          int, my_integer_arg / 5)
-        ctf_enum(my_provider, my_enum, int,
-                 enum_field, array_arg[1])
+    LTTNG_UST_TP_FIELDS(
+        lttng_ust_field_integer(int, int_field1, my_integer_arg * 2)
+        lttng_ust_field_integer_hex(long int, stream_pos,
+                                    ftell(stream))
+        lttng_ust_field_float(double, float_field, flt_arg)
+        lttng_ust_field_string(string_field, my_string_arg)
+        lttng_ust_field_array(int, array_field, array_arg, 7)
+        lttng_ust_field_array_text(char, array_text_field,
+                                   array_arg, 5)
+        lttng_ust_field_sequence(int, seq_field, array_arg, int,
+                                 my_integer_arg / 10)
+        lttng_ust_field_sequence_text(char, seq_text_field,
+                                      array_arg, int,
+                                      my_integer_arg / 5)
+        lttng_ust_field_enum(my_provider, my_enum, int,
+                             enum_field, array_arg[1])
     )
 )
 
-TRACEPOINT_LOGLEVEL(my_provider, big_event, TRACE_WARNING)
+LTTNG_UST_TRACEPOINT_LOGLEVEL(my_provider, big_event,
+                              LTTNG_UST_TRACEPOINT_LOGLEVEL_WARNING)
 
-TRACEPOINT_EVENT_CLASS(
+LTTNG_UST_TRACEPOINT_EVENT_CLASS(
     my_provider,
     my_tracepoint_class,
-    TP_ARGS(
+    LTTNG_UST_TP_ARGS(
         int, my_integer_arg,
         struct app_struct *, app_struct_arg
     ),
-    TP_FIELDS(
-        ctf_integer(int, a, my_integer_arg)
-        ctf_integer(unsigned long, b, app_struct_arg->b)
-        ctf_string(c, app_struct_arg->c)
+    LTTNG_UST_TP_FIELDS(
+        lttng_ust_field_integer(int, a, my_integer_arg)
+        lttng_ust_field_integer(unsigned long, b, app_struct_arg->b)
+        lttng_ust_field_string(c, app_struct_arg->c)
     )
 )
 
-TRACEPOINT_EVENT_INSTANCE(
+LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
     my_provider,
     my_tracepoint_class,
+    my_provider,
     event_instance1,
-    TP_ARGS(
+    LTTNG_UST_TP_ARGS(
         int, my_integer_arg,
         struct app_struct *, app_struct_arg
     )
 )
 
-TRACEPOINT_EVENT_INSTANCE(
+LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
     my_provider,
     my_tracepoint_class,
+    my_provider,
     event_instance2,
-    TP_ARGS(
+    LTTNG_UST_TP_ARGS(
         int, my_integer_arg,
         struct app_struct *, app_struct_arg
     )
 )
 
-TRACEPOINT_LOGLEVEL(my_provider, event_instance2, TRACE_INFO)
+LTTNG_UST_TRACEPOINT_LOGLEVEL(my_provider, event_instance2,
+                              LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO)
 
-TRACEPOINT_EVENT_INSTANCE(
+LTTNG_UST_TRACEPOINT_EVENT_INSTANCE(
     my_provider,
     my_tracepoint_class,
+    my_provider,
     event_instance3,
-    TP_ARGS(
+    LTTNG_UST_TP_ARGS(
         int, my_integer_arg,
         struct app_struct *, app_struct_arg
     )
@@ -1286,8 +1393,8 @@ Tracepoint provider source file
 `tp.c`:
 
 ------------------------------------------------------------------------
-#define TRACEPOINT_CREATE_PROBES
-#define TRACEPOINT_DEFINE
+#define LTTNG_UST_TRACEPOINT_CREATE_PROBES
+#define LTTNG_UST_TRACEPOINT_DEFINE
 
 #include "tp.h"
 ------------------------------------------------------------------------
@@ -1331,7 +1438,7 @@ int main(int argc, char* argv[])
     FILE *stream;
     struct app_struct app_struct;
 
-    tracepoint(my_provider, simple_event, argc, argv[0]);
+    lttng_ust_tracepoint(my_provider, simple_event, argc, argv[0]);
     stream = fopen("/tmp/app.txt", "w");
 
     if (!stream) {
@@ -1346,19 +1453,22 @@ int main(int argc, char* argv[])
         return EXIT_FAILURE;
     }
 
-    tracepoint(my_provider, big_event, 35, "hello tracepoint",
-               stream, -3.14, array_of_ints);
+    lttng_ust_tracepoint(my_provider, big_event, 35,
+                         "hello tracepoint", stream, -3.14,
+                         array_of_ints);
     fclose(stream);
     app_struct.b = argc;
     app_struct.c = "[the string]";
-    tracepoint(my_provider, event_instance1, 23, &app_struct);
+    lttng_ust_tracepoint(my_provider, event_instance1, 23,
+                         &app_struct);
     app_struct.b = argc * 5;
     app_struct.c = "[other string]";
-    tracepoint(my_provider, event_instance2, 17, &app_struct);
+    lttng_ust_tracepoint(my_provider, event_instance2, 17,
+                         &app_struct);
     app_struct.b = 23;
     app_struct.c = "nothing";
-    tracepoint(my_provider, event_instance3, -52, &app_struct);
-
+    lttng_ust_tracepoint(my_provider, event_instance3, -52,
+                         &app_struct);
     return EXIT_SUCCESS;
 }
 ------------------------------------------------------------------------
@@ -1437,8 +1547,8 @@ include::common-authors.txt[]
 
 SEE ALSO
 --------
-man:tracef(3),
-man:tracelog(3),
+man:lttng_ust_tracef(3),
+man:lttng_ust_tracelog(3),
 man:lttng-gen-tp(1),
 man:lttng-ust-dl(3),
 man:lttng-ust-cyg-profile(3),
diff --git a/doc/man/lttng_ust_do_tracepoint.3 b/doc/man/lttng_ust_do_tracepoint.3
new file mode 100644 (file)
index 0000000..afb50be
--- /dev/null
@@ -0,0 +1 @@
+.so man3/lttng-ust.3
diff --git a/doc/man/lttng_ust_tracef.3.txt b/doc/man/lttng_ust_tracef.3.txt
new file mode 100644 (file)
index 0000000..0c90172
--- /dev/null
@@ -0,0 +1,137 @@
+lttng_ust_tracef(3)
+===================
+:object-type: macro
+
+
+NAME
+----
+lttng_ust_tracef, lttng_ust_vtracef - LTTng-UST printf(3)-like interface
+
+
+SYNOPSIS
+--------
+[verse]
+*#include <lttng/tracef.h>*
+
+[verse]
+#define *lttng_ust_tracef*('fmt', ...)
+#define *lttng_ust_vtracef*('fmt', 'ap')
+
+Link with `-llttng-ust -llttng-ust-common`.
+
+
+DESCRIPTION
+-----------
+The LTTng-UST `lttng_ust_tracef()` and `lttng_ust_vtracef()` API allows
+you to trace your application with the help of simple man:printf(3)-like
+and man:vprintf(3)-like macros.
+
+The 'fmt' argument is passed directly as the 'fmt' parameter of
+man:vasprintf(3), as well as:
+
+For `lttng_ust_tracef()`::
+    The optional parameters following 'fmt'.
+
+For `lttng_ust_vtracef()`::
+    The 'ap' parameter as the 'ap' parameter of man:vasprintf(3)
+    (`va_list` type).
+
+To use `lttng_ust_tracef()` or `lttng_ust_vtracef()`, include
+`<lttng/tracef.h>` where you need it, and link your application with
+`liblttng-ust` and `liblttng-ust-common`. See the <<example,EXAMPLE>>
+section below for a complete usage example.
+
+Once your application is instrumented with `lttng_ust_tracef()` and/or
+`lttng_ust_vtracef()` calls and ready to run, use
+man:lttng-enable-event(1) to enable the `lttng_ust_tracef:*` event.
+
+The `lttng_ust_tracef()` and `lttng_ust_vtracef()` events contain a
+single field, named `msg`, which is the formatted string output.
+
+If you need to attach a specific log level to a
+`lttng_ust_tracef()`/`lttng_ust_vtracef()` call, use
+man:lttng_ust_tracelog(3) and man:lttng_ust_vtracelog(3) instead.
+
+See also the <<limitations,LIMITATIONS>> section below for important
+limitations to consider when using `lttng_ust_tracef()` or
+`lttng_ust_vtracef()`.
+
+
+[[example]]
+EXAMPLE
+-------
+Here's a usage example of `lttng_ust_tracef()`:
+
+-------------------------------------------------------------------
+#include <stdlib.h>
+#include <lttng/tracef.h>
+
+int main(void)
+{
+    int i;
+
+    for (i = 0; i < 25; i++) {
+        lttng_ust_tracef("my message: %s, this integer: %d",
+                         "a message", i);
+    }
+
+    return EXIT_SUCCESS;
+}
+-------------------------------------------------------------------
+
+This C source file, saved as `app.c`, can be compiled into a program
+like this:
+
+[role="term"]
+----
+$ cc -o app app.c -llttng-ust -llttng-ust-common
+----
+
+You can create an LTTng tracing session, enable the `lttng_ust_tracef()`
+events, and start the created tracing session like this:
+
+[role="term"]
+----
+$ lttng create my-session
+$ lttng enable-event --userspace 'lttng_ust_tracef:*'
+$ lttng start
+----
+
+Next, start the program to be traced:
+
+[role="term"]
+----
+$ ./app
+----
+
+Finally, stop the tracing session, and inspect the recorded events:
+
+[role="term"]
+----
+$ lttng stop
+$ lttng view
+----
+
+
+[[limitations]]
+LIMITATIONS
+-----------
+:macro-suffix: tracef
+
+include::tracef-tracelog-limitations.txt[]
+
+
+include::common-footer.txt[]
+
+include::common-copyrights.txt[]
+
+include::common-authors.txt[]
+
+
+SEE ALSO
+--------
+man:lttng_ust_tracelog(3),
+man:lttng_ust_vtracelog(3),
+man:lttng-ust(3),
+man:lttng(1),
+man:printf(3)
diff --git a/doc/man/lttng_ust_tracelog.3.txt b/doc/man/lttng_ust_tracelog.3.txt
new file mode 100644 (file)
index 0000000..d0a315d
--- /dev/null
@@ -0,0 +1,185 @@
+lttng_ust_tracelog(3)
+=====================
+:object-type: macro
+
+
+NAME
+----
+lttng_ust_tracelog, lttng_ust_vtracelog - LTTng-UST printf(3)-like interface with a log level
+
+
+SYNOPSIS
+--------
+[verse]
+*#include <lttng/tracelog.h>*
+
+[verse]
+#define *lttng_ust_tracelog*('level', 'fmt', ...)
+#define *lttng_ust_vtracelog*('level', 'fmt', 'ap')
+
+Link with `-llttng-ust -llttng-ust-common`.
+
+
+DESCRIPTION
+-----------
+The LTTng-UST `lttng_ust_tracelog()` and `lttng_ust_vtracelog()` API
+allows you to trace your application with the help of simple
+man:printf(3)-like and man:vprintf(3)-like macros, with an additional
+parameter for the desired log level.
+
+The 'fmt' argument is passed directly as the 'fmt' parameter of
+man:vasprintf(3), as well as:
+
+For `lttng_ust_tracelog()`::
+    The optional parameters following 'fmt'.
+
+For `lttng_ust_vtracelog()`::
+    The 'ap' parameter as the 'ap' parameter of man:vasprintf(3)
+    (`va_list` type).
+
+The purpose of `lttng_ust_tracelog()` and `lttng_ust_vtracelog()` is to
+ease the migration from logging to tracing.
+
+The available values for the 'level' parameter are:
+
+include::log-levels.txt[]
+
+To use `lttng_ust_tracelog()` or `lttng_ust_vtracelog()`, include
+`<lttng/tracelog.h>` where you need it, and link your application with
+`liblttng-ust` and `liblttng-ust-common`. See the <<example,EXAMPLE>>
+section below for a complete usage example.
+
+Once your application is instrumented with `lttng_ust_tracelog()` and/or
+`lttng_ust_vtracelog()` calls and ready to run, use
+man:lttng-enable-event(1) to enable the `lttng_ust_tracelog:*` event.
+You can isolate specific log levels with the nloption:--loglevel and
+nloption:--loglevel-only options of this command.
+
+The `lttng_ust_tracelog()` and `lttng_ust_vtracelog()` events contain
+the following fields:
+
+[options="header"]
+|===
+|Field name |Description
+
+|`line`
+|Line in source file where `lttng_ust_tracelog()` was called.
+
+|`file`
+|Source file from which `lttng_ust_tracelog()` was called.
+
+|`func`
+|Function name from which `lttng_ust_tracelog()` was called.
+
+|`msg`
+|Formatted string output.
+|===
+
+If you do not need to attach a specific log level to a
+`lttng_ust_tracelog()`/`lttng_ust_vtracelog()` call, use
+man:lttng_ust_tracef(3) instead.
+
+See also the <<limitations,LIMITATIONS>> section below for important
+limitations to consider when using `lttng_ust_tracelog()` or
+`lttng_ust_vtracelog()`.
+
+
+[[example]]
+EXAMPLE
+-------
+Here's a usage example of `lttng_ust_tracelog()`:
+
+-------------------------------------------------------------------
+#include <stdlib.h>
+#include <lttng/tracelog.h>
+
+int main(int argc, char *argv[])
+{
+    int i;
+
+    if (argc < 2) {
+        lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_CRIT,
+                           "Not enough arguments: %d", argc);
+        return EXIT_FAILURE;
+    }
+
+    lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO,
+                       "Starting app with %d arguments", argc);
+
+    for (i = 0; i < argc; i++) {
+        lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_DEBUG,
+                           "Argument %d: %s", i, argv[i]);
+    }
+
+    lttng_ust_tracelog(LTTNG_UST_TRACEPOINT_LOGLEVEL_INFO,
+                       "Exiting app");
+    return EXIT_SUCCESS;
+}
+-------------------------------------------------------------------
+
+This C source file, saved as `app.c`, can be compiled into a program
+like this:
+
+[role="term"]
+----
+$ cc -o app app.c -llttng-ust -llttng-ust-common
+----
+
+You can create an LTTng tracing session, enable all the
+`lttng_ust_tracelog()` events, and start the created tracing session
+like this:
+
+[role="term"]
+----
+$ lttng create my-session
+$ lttng enable-event --userspace 'lttng_ust_tracelog:*'
+$ lttng start
+----
+
+Or you can enable `lttng_ust_tracelog()` events matching a log level at
+least as severe as a given log level:
+
+[role="term"]
+----
+$ lttng enable-event --userspace 'lttng_ust_tracelog:*' \
+                     --loglevel=INFO
+----
+
+Next, start the program to be traced:
+
+[role="term"]
+----
+$ ./app a few arguments passed to this application
+----
+
+Finally, stop the tracing session, and inspect the recorded events:
+
+[role="term"]
+----
+$ lttng stop
+$ lttng view
+----
+
+
+[[limitations]]
+LIMITATIONS
+-----------
+:macro-suffix: tracelog
+
+include::tracef-tracelog-limitations.txt[]
+
+
+include::common-footer.txt[]
+
+include::common-copyrights.txt[]
+
+include::common-authors.txt[]
+
+
+SEE ALSO
+--------
+man:lttng_ust_tracef(3),
+man:lttng_ust_vtracef(3),
+man:lttng-ust(3),
+man:lttng(1),
+man:printf(3)
diff --git a/doc/man/lttng_ust_tracepoint.3 b/doc/man/lttng_ust_tracepoint.3
new file mode 100644 (file)
index 0000000..afb50be
--- /dev/null
@@ -0,0 +1 @@
+.so man3/lttng-ust.3
diff --git a/doc/man/lttng_ust_tracepoint_enabled.3 b/doc/man/lttng_ust_tracepoint_enabled.3
new file mode 100644 (file)
index 0000000..afb50be
--- /dev/null
@@ -0,0 +1 @@
+.so man3/lttng-ust.3
index c2112abf4bb9014420f802ce29261607d5ea7251..c5bb6babc53118781825d59163992dfc33d7ab4e 100644 (file)
@@ -1,4 +1,7 @@
-The +{macro-name}()+ and +v{macro-name}()+ utility macros were
+: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:
 
@@ -9,7 +12,7 @@ disadvantages compared to 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}()+ and +v{macro-name}()+ use C standard
+  * 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
@@ -18,11 +21,11 @@ disadvantages compared to custom, full-fledged tracepoint providers:
     user data fields is not as compact as binary fields in the resulting
     trace.
 
-Thus, +{macro-name}()+/+v{macro-name}()+ are useful for quick
+Thus, +{macro-name}()+/+{vmacro-name}()+ are useful for quick
 prototyping and debugging, but should not be considered for any
 permanent/serious application instrumentation.
 
-+v{macro-name}()+ does not have a `STAP_PROBEV()` call, because
++{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.
 
index 21456add358213d6104493841d3c17844e28f7be..dc2b293b1557de44f0ec86027f6db8cce5aebaff 100644 (file)
@@ -22,100 +22,13 @@ Link with `-llttng-ust -llttng-ust-common`.
 
 DESCRIPTION
 -----------
-The LTTng-UST `tracef()` and `vtracef()` API allows you to trace your
-application with the help of simple man:printf(3)-like and
-man:vprintf(3)-like macros.
-
-The 'fmt' argument is passed directly as the 'fmt' parameter of
-man:vasprintf(3), as well as:
-
-For `tracef()`::
-    The optional parameters following 'fmt'.
-
-For `vtracef()`::
-    The 'ap' parameter as the 'ap' parameter of man:vasprintf(3)
-    (`va_list` type).
-
-To use `tracef()` or `vtracef()`, include `<lttng/tracef.h>` where you
-need it, and link your application with `liblttng-ust`. See the
-<<example,EXAMPLE>> section below for a complete usage example.
-
-Once your application is instrumented with `tracef()` and/or `vtracef()`
-calls and ready to run, use man:lttng-enable-event(1) to enable the
-`lttng_ust_tracef:*` event.
-
-The `tracef()` and `vtracef()` events contain a single field, named
-`msg`, which is the formatted string output.
-
-If you need to attach a specific log level to a `tracef()`/`vtracef()`
-call, use man:tracelog(3) and man:vtracelog(3) instead.
-
-See also the <<limitations,LIMITATIONS>> section below for important
-limitations to consider when using `tracef()` or `vtracef()`.
-
-
-[[example]]
-EXAMPLE
--------
-Here's a usage example of `tracef()`:
-
--------------------------------------------------------------------
-#include <stdlib.h>
-#include <lttng/tracef.h>
-
-int main(void)
-{
-    int i;
-
-    for (i = 0; i < 25; i++) {
-        tracef("my message: %s, this integer: %d", "a message", i);
-    }
-
-    return EXIT_SUCCESS;
-}
--------------------------------------------------------------------
-
-This C source file, saved as `app.c`, can be compiled into a program
-like this:
-
-[role="term"]
-----
-$ cc -o app app.c -llttng-ust -llttng-ust-common
-----
-
-You can create an LTTng tracing session, enable the `tracef()` events,
-and start the created tracing session like this:
-
-[role="term"]
-----
-$ lttng create my-session
-$ lttng enable-event --userspace 'lttng_ust_tracef:*'
-$ lttng start
-----
-
-Next, start the program to be traced:
-
-[role="term"]
-----
-$ ./app
-----
-
-Finally, stop the tracing session, and inspect the recorded events:
-
-[role="term"]
-----
-$ lttng stop
-$ lttng view
-----
-
-
-[[limitations]]
-LIMITATIONS
------------
-:macro-name: tracef
-
-include::tracef-tracelog-limitations.txt[]
+The `tracef()` and `vtracef()` macros are part of version{nbsp}0 of the
+LTTng-UST API (see the ``Compatibility with previous APIs'' section of
+man:lttng-ust(3)).
 
+Prefer using man:lttng_ust_tracef(3) and man:lttng_ust_vtracef(3) which
+are part of version{nbsp}1 of the API and have the `lttng_ust_`
+namespace.
 
 include::common-footer.txt[]
 
@@ -126,8 +39,5 @@ include::common-authors.txt[]
 
 SEE ALSO
 --------
-man:tracelog(3),
-man:vtracelog(3),
-man:lttng-ust(3),
-man:lttng(1),
-man:printf(3)
+man:lttng_ust_tracef(3),
+man:lttng_ust_vtracef(3)
index 1f97a0bdd68b092c4bfa7d93df49b7b1681b91c1..13284636fdc48ec8a512f4677bef5e0098957613 100644 (file)
@@ -22,143 +22,13 @@ Link with `-llttng-ust -llttng-ust-common`.
 
 DESCRIPTION
 -----------
-The LTTng-UST `tracelog()` and `vtracelog()` API allows you to trace
-your application with the help of simple man:printf(3)-like and
-man:vprintf(3)-like macros, with an additional parameter for the desired
-log level.
+The `tracelog()` and `vtracelog()` macros are part of version{nbsp}0 of
+the LTTng-UST API (see the ``Compatibility with previous APIs'' section
+of man:lttng-ust(3)).
 
-The 'fmt' argument is passed directly as the 'fmt' parameter of
-man:vasprintf(3), as well as:
-
-For `tracelog()`::
-    The optional parameters following 'fmt'.
-
-For `vtracelog()`::
-    The 'ap' parameter as the 'ap' parameter of man:vasprintf(3)
-    (`va_list` type).
-
-The purpose of `tracelog()` and `vtracelog()` is to ease the migration
-from logging to tracing.
-
-The available values for the 'level' parameter are:
-
-include::log-levels.txt[]
-
-To use `tracelog()` or `vtracelog()`, include `<lttng/tracelog.h>` where
-you need it, and link your application with `liblttng-ust`. See the
-<<example,EXAMPLE>> section below for a complete usage example.
-
-Once your application is instrumented with `tracelog()` and/or
-`vtracelog()` calls and ready to run, use man:lttng-enable-event(1) to
-enable the `lttng_ust_tracelog:*` event. You can isolate specific log
-levels with the nloption:--loglevel and nloption:--loglevel-only options
-of this command.
-
-The `tracelog()` and `vtracelog()` events contain the following fields:
-
-[options="header"]
-|===
-|Field name |Description
-
-|`line`
-|Line in source file where `tracelog()` was called.
-
-|`file`
-|Source file from which `tracelog()` was called.
-
-|`func`
-|Function name from which `tracelog()` was called.
-
-|`msg`
-|Formatted string output.
-|===
-
-If you do not need to attach a specific log level to a
-`tracelog()`/`vtracelog()` call, use man:tracef(3) instead.
-
-See also the <<limitations,LIMITATIONS>> section below for important
-limitations to consider when using `tracelog()` or `vtracelog()`.
-
-
-[[example]]
-EXAMPLE
--------
-Here's a usage example of `tracelog()`:
-
--------------------------------------------------------------------
-#include <stdlib.h>
-#include <lttng/tracelog.h>
-
-int main(int argc, char *argv[])
-{
-    int i;
-
-    if (argc < 2) {
-        tracelog(TRACE_CRIT, "Not enough arguments: %d", argc);
-        return EXIT_FAILURE;
-    }
-
-    tracelog(TRACE_INFO, "Starting app with %d arguments", argc);
-
-    for (i = 0; i < argc; i++) {
-        tracelog(TRACE_DEBUG, "Argument %d: %s", i, argv[i]);
-    }
-
-    tracelog(TRACE_INFO, "Exiting app");
-
-    return EXIT_SUCCESS;
-}
--------------------------------------------------------------------
-
-This C source file, saved as `app.c`, can be compiled into a program
-like this:
-
-[role="term"]
-----
-$ cc -o app app.c -llttng-ust -llttng-ust-common
-----
-
-You can create an LTTng tracing session, enable all the `tracelog()`
-events, and start the created tracing session like this:
-
-[role="term"]
-----
-$ lttng create my-session
-$ lttng enable-event --userspace 'lttng_ust_tracelog:*'
-$ lttng start
-----
-
-Or you can enable `tracelog()` events matching a log level at least
-as severe as a given log level:
-
-[role="term"]
-----
-$ lttng enable-event --userspace 'lttng_ust_tracelog:*' \
-                   --loglevel=TRACE_INFO
-----
-
-Next, start the program to be traced:
-
-[role="term"]
-----
-$ ./app a few arguments passed to this application
-----
-
-Finally, stop the tracing session, and inspect the recorded events:
-
-[role="term"]
-----
-$ lttng stop
-$ lttng view
-----
-
-
-[[limitations]]
-LIMITATIONS
------------
-:macro-name: tracelog
-
-include::tracef-tracelog-limitations.txt[]
+Prefer using man:lttng_ust_tracelog(3) and man:lttng_ust_vtracelog(3)
+which are part of version{nbsp}1 of the API and have the `lttng_ust_`
+namespace.
 
 
 include::common-footer.txt[]
@@ -170,8 +40,5 @@ include::common-authors.txt[]
 
 SEE ALSO
 --------
-man:tracef(3),
-man:vtracef(3),
-man:lttng-ust(3),
-man:lttng(1),
-man:printf(3)
+man:lttng_ust_tracelog(3),
+man:lttng_ust_vtracelog(3)
This page took 0.052959 seconds and 4 git commands to generate.