From d6208c2d79b114af0c7ab1ea78240b2d11081066 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Tue, 9 Mar 2021 22:38:35 -0500 Subject: [PATCH] tracef.3.txt/tracelog.3.txt: always take variadic variants into account This patch makes the `tracef.3.txt` and `tracelog.3.txt` manual page sources always mention the variadic variant where the non-variadic variant is mentioned for consistency. This patch also changes the `va_list` type from the "SYNOPSIS" sections as vtracef() and vtracelog() are macros. The type of the `ap` parameter (`va_list`) is given in the "DESCRIPTION" sections. Signed-off-by: Philippe Proulx Signed-off-by: Mathieu Desnoyers Change-Id: I84a795d16a39a483c43f1963189cd7e1faa5c329 --- doc/man/tracef.3.txt | 38 +++++++++++++++++++++------------ doc/man/tracelog.3.txt | 48 +++++++++++++++++++++++++----------------- 2 files changed, 53 insertions(+), 33 deletions(-) diff --git a/doc/man/tracef.3.txt b/doc/man/tracef.3.txt index 2894ca45..cdd23aec 100644 --- a/doc/man/tracef.3.txt +++ b/doc/man/tracef.3.txt @@ -15,31 +15,40 @@ SYNOPSIS [verse] #define *tracef*('fmt', ...) -#define *vtracef*('fmt', 'va_list' ap) +#define *vtracef*('fmt', 'ap') Link with `-llttng-ust`. DESCRIPTION ----------- -The LTTng-UST `tracef()` API allows you to trace your application with -the help of a simple man:printf(3)-like macro. 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 `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. -To use `tracef()` or `vtracef()`, include `` where you need it, -and link your application with `liblttng-ust`. See the <> -section below for a complete usage example. +The 'fmt' argument is passed directly as the 'fmt' parameter of +man:vasprintf(3), as well as: -Once your application is instrumented with `tracef()` or `vtracef()` calls and -ready to run, use man:lttng-enable-event(1) to enable the +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 `` where you +need it, and link your application with `liblttng-ust`. See the +<> 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()` events contain a single field, named `msg`, which is the -formatted string output. +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()` call, use -man:tracelog(3) instead. +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 <> section below for important limitations to consider when using `tracef()` or `vtracef()`. @@ -118,6 +127,7 @@ include::common-authors.txt[] SEE ALSO -------- man:tracelog(3), +man:vtracelog(3), man:lttng-ust(3), man:lttng(1), man:printf(3) diff --git a/doc/man/tracelog.3.txt b/doc/man/tracelog.3.txt index 8997f117..544d027a 100644 --- a/doc/man/tracelog.3.txt +++ b/doc/man/tracelog.3.txt @@ -15,37 +15,46 @@ SYNOPSIS [verse] #define *tracelog*('level', 'fmt', ...) -#define *vtracelog*('level', 'fmt', 'va_list' ap) +#define *vtracelog*('level', 'fmt', 'ap') Link with `-llttng-ust`. 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()` or `vtracelog()`, include `` where you -need it, and link your application with `liblttng-ust`. -See the <> section below for a complete usage example. +To use `tracelog()` or `vtracelog()`, include `` where +you need it, and link your application with `liblttng-ust`. See the +<> 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"] |=== @@ -64,8 +73,8 @@ The `tracelog()` events contain the following fields: |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 <> section below for important limitations to consider when using `tracelog()` or `vtracelog()`. @@ -162,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) -- 2.34.1