doc: add -llttng-ust-common to linking cmd in manpages

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

diff --git a/doc/man/tracelog.3.txt b/doc/man/tracelog.3.txt
index e90e91895b7614d95b5f4f93630384d470ca79a1..1f97a0bdd68b092c4bfa7d93df49b7b1681b91c1 100644 (file)
--- a/doc/man/tracelog.3.txt
+++ b/doc/man/tracelog.3.txt
@@ -5,7 +5,7 @@ tracelog(3)
 
 NAME
 ----
-tracelog - LTTng-UST printf(3)-like interface with a log level
+tracelog, vtracelog - LTTng-UST printf(3)-like interface with a log level
 
 
 SYNOPSIS
@@ -15,59 +15,69 @@ SYNOPSIS
 
 [verse]
 #define *tracelog*('level', 'fmt', ...)
+#define *vtracelog*('level', 'fmt', 'ap')
 
-Link with `-llttng-ust`.
+Link with `-llttng-ust -llttng-ust-common`.
 
 
 DESCRIPTION
 -----------
-The LTTng-UST `tracelog()` API allows you to trace your application with
-the help of a simple man:printf(3)-like macro, with an additional
-parameter for the desired log level. The 'fmt' argument is passed
-directly to the 'fmt' parameter of man:vasprintf(3), as well as
-the optional parameters following 'fmt'.
+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 purpose of `tracelog()` is to ease the migration from logging to
-tracing.
+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()`, 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.
+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()` 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.
+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()` events contain the following fields:
+The `tracelog()` and `vtracelog()` events contain the following fields:
 
 [options="header"]
 |===
 |Field name |Description
 
 |`line`
-|Line in source file where `tracelog()` was called
+|Line in source file where `tracelog()` was called.
 
 |`file`
-|Source file from which `tracelog()` was called
+|Source file from which `tracelog()` was called.
 
 |`func`
-|Function name from which `tracelog()` was called
+|Function name from which `tracelog()` was called.
 
 |`msg`
-|Formatted string output
+|Formatted string output.
 |===
 
-If you do not need to attach a specific log level to a `tracelog()`
-call, use man:tracef(3) instead.
+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()`.
+limitations to consider when using `tracelog()` or `vtracelog()`.
 
 
 [[example]]
@@ -104,43 +114,43 @@ 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
----------------------------
+----
+$ 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
----------------------------------------------------
+----
+$ 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:*' \
+----
+$ 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
-------------------------------------------------
+----
+$ ./app a few arguments passed to this application
+----
 
 Finally, stop the tracing session, and inspect the recorded events:
 
 [role="term"]
-----------
-lttng stop
-lttng view
-----------
+----
+$ lttng stop
+$ lttng view
+----
 
 
 [[limitations]]
@@ -161,6 +171,7 @@ include::common-authors.txt[]
 SEE ALSO
 --------
 man:tracef(3),
+man:vtracef(3),
 man:lttng-ust(3),
 man:lttng(1),
 man:printf(3)