From 45efc5a3b38867d47fc5d4d2d11197e0cd71530d Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Tue, 9 Mar 2021 22:41:34 -0500 Subject: [PATCH] tracef-tracelog-limitations.txt: take variadic variant into account This patch changes `tracef-tracelog-limitations.txt` so as to always mention the variadic variant where the non-variadic variant is mentioned for consistency. Signed-off-by: Philippe Proulx Signed-off-by: Mathieu Desnoyers Change-Id: I13250fdae647ea58c042238c88b674c56d4f3fc0 --- doc/man/tracef-tracelog-limitations.txt | 30 +++++++++++++------------ 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/doc/man/tracef-tracelog-limitations.txt b/doc/man/tracef-tracelog-limitations.txt index ad4130dd..c2112abf 100644 --- a/doc/man/tracef-tracelog-limitations.txt +++ b/doc/man/tracef-tracelog-limitations.txt @@ -1,6 +1,6 @@ -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: +The +{macro-name}()+ and +v{macro-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,19 +9,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 +v{macro-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}()+ is useful for quick prototyping and debugging, but -should not be considered for any permanent/serious application -instrumentation. +Thus, +{macro-name}()+/+v{macro-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 `STAP_PROBEV()` -does not support `va_list`. If you need it, you should emit this call yourself. ++v{macro-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. -- 2.34.1