doc/man/tracef.3.txt

   1 tracef(3)
   2 =========
   3 :object-type: macro
   4
   5
   6 NAME
   7 ----
   8 tracef, vtracef - LTTng-UST printf(3)-like interface
   9
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 *#include <lttng/tracef.h>*
  15
  16 [verse]
  17 #define *tracef*('fmt', ...)
  18 #define *vtracef*('fmt', 'ap')
  19
  20 Link with `-llttng-ust -llttng-ust-common`.
  21
  22
  23 DESCRIPTION
  24 -----------
  25 The LTTng-UST `tracef()` and `vtracef()` API allows you to trace your
  26 application with the help of simple man:printf(3)-like and
  27 man:vprintf(3)-like macros.
  28
  29 The 'fmt' argument is passed directly as the 'fmt' parameter of
  30 man:vasprintf(3), as well as:
  31
  32 For `tracef()`::
  33     The optional parameters following 'fmt'.
  34
  35 For `vtracef()`::
  36     The 'ap' parameter as the 'ap' parameter of man:vasprintf(3)
  37     (`va_list` type).
  38
  39 To use `tracef()` or `vtracef()`, include `<lttng/tracef.h>` where you
  40 need it, and link your application with `liblttng-ust`. See the
  41 <<example,EXAMPLE>> section below for a complete usage example.
  42
  43 Once your application is instrumented with `tracef()` and/or `vtracef()`
  44 calls and ready to run, use man:lttng-enable-event(1) to enable the
  45 `lttng_ust_tracef:*` event.
  46
  47 The `tracef()` and `vtracef()` events contain a single field, named
  48 `msg`, which is the formatted string output.
  49
  50 If you need to attach a specific log level to a `tracef()`/`vtracef()`
  51 call, use man:tracelog(3) and man:vtracelog(3) instead.
  52
  53 See also the <<limitations,LIMITATIONS>> section below for important
  54 limitations to consider when using `tracef()` or `vtracef()`.
  55
  56
  57 [[example]]
  58 EXAMPLE
  59 -------
  60 Here's a usage example of `tracef()`:
  61
  62 -------------------------------------------------------------------
  63 #include <stdlib.h>
  64 #include <lttng/tracef.h>
  65
  66 int main(void)
  67 {
  68     int i;
  69
  70     for (i = 0; i < 25; i++) {
  71         tracef("my message: %s, this integer: %d", "a message", i);
  72     }
  73
  74     return EXIT_SUCCESS;
  75 }
  76 -------------------------------------------------------------------
  77
  78 This C source file, saved as `app.c`, can be compiled into a program
  79 like this:
  80
  81 [role="term"]
  82 ----
  83 $ cc -o app app.c -llttng-ust -llttng-ust-common
  84 ----
  85
  86 You can create an LTTng tracing session, enable the `tracef()` events,
  87 and start the created tracing session like this:
  88
  89 [role="term"]
  90 ----
  91 $ lttng create my-session
  92 $ lttng enable-event --userspace 'lttng_ust_tracef:*'
  93 $ lttng start
  94 ----
  95
  96 Next, start the program to be traced:
  97
  98 [role="term"]
  99 ----
 100 $ ./app
 101 ----
 102
 103 Finally, stop the tracing session, and inspect the recorded events:
 104
 105 [role="term"]
 106 ----
 107 $ lttng stop
 108 $ lttng view
 109 ----
 110
 111
 112 [[limitations]]
 113 LIMITATIONS
 114 -----------
 115 :macro-name: tracef
 116
 117 include::tracef-tracelog-limitations.txt[]
 118
 119
 120 include::common-footer.txt[]
 121
 122 include::common-copyrights.txt[]
 123
 124 include::common-authors.txt[]
 125
 126
 127 SEE ALSO
 128 --------
 129 man:tracelog(3),
 130 man:vtracelog(3),
 131 man:lttng-ust(3),
 132 man:lttng(1),
 133 man:printf(3)