doc/man/lttng-gen-tp.1.txt

   1 lttng-gen-tp(1)
   2 ===============
   3 :object-type: program
   4
   5
   6 NAME
   7 ----
   8 lttng-gen-tp - Generate LTTng-UST tracepoint provider code
   9
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 *lttng-gen-tp* [option:--verbose] [option:--output='FILE'.c]
  15              [option:--output='FILE'.h] [option:--output='FILE'.o] 'TEMPLATE'
  16
  17
  18 DESCRIPTION
  19 -----------
  20 The `lttng-gen-tp` tool simplifies the generation of LTTng-UST
  21 tracepoint provider files. It takes a simple template file, 'TEMPLATE',
  22 and generates the necessary C code to use the defined tracepoints in
  23 your application. See the <<template-file-format,Template file format>>
  24 section below for more information about the format of 'TEMPLATE'.
  25
  26 Currently, `lttng-gen-tp` can generate the `.h`, `.c`, and `.o` files
  27 associated with your tracepoint provider. The generated `.h` file can be
  28 included directly in your application. You can let `lttng-gen-tp`
  29 generate the `.o` file or compile the `.c` file yourself. See
  30 man:lttng-ust(3) for more information about compiling LTTng-UST
  31 tracepoint providers.
  32
  33 By default, `lttng-gen-tp` generates the `.h`, `.c`, and `.o` files,
  34 their basename being the basename of 'TEMPLATE'. You can generate one or
  35 more specific file types with the option:--output option, repeated if
  36 needed.
  37
  38
  39 [[template-file-format]]
  40 Template file format
  41 ~~~~~~~~~~~~~~~~~~~~
  42 The template file, which usually has the `.tp` extension, contains a
  43 list of `LTTNG_UST_TRACEPOINT_EVENT()` definitions and other optional
  44 definition entries, like `LTTNG_UST_TRACEPOINT_LOGLEVEL()`. See
  45 man:lttng-ust(3) for the complete list of available definitions.
  46
  47 The `LTTNG_UST_TRACEPOINT_EVENT()` definitions are written as you would
  48 write them in an LTTng-UST template provider header file. C comments are
  49 supported (`/* */` and `//`), as well as lines starting with `#`.
  50
  51 NOTE: The provider name (the first argument of
  52 `LTTNG_UST_TRACEPOINT_EVENT()`) must be the same in all the
  53 `LTTNG_UST_TRACEPOINT_EVENT()` macros of 'TEMPLATE'.
  54
  55 Here's an example:
  56
  57 ---------------------------------------
  58 LTTNG_UST_TRACEPOINT_EVENT(
  59     // Tracepoint provider name
  60     my_provider,
  61
  62     // Tracepoint/event name
  63     my_event,
  64
  65     // Tracepoint arguments (input)
  66     LTTNG_UST_TP_ARGS(char *, text),
  67
  68     // Tracepoint/event fields (output)
  69     LTTNG_UST_TP_FIELDS(
  70         lttng_ust_field_string(message, text)
  71     )
  72 )
  73 ---------------------------------------
  74
  75
  76 OPTIONS
  77 -------
  78 option:-o, option:--output='FILE'::
  79     Do not generate default files: generate 'FILE'.
  80 +
  81 The extension of 'FILE' determines what is generated, amongst `.h`,
  82 `.c`, and `.o`. This option can be used more than one time to generate
  83 different file types.
  84
  85 option:-v, option:--verbose::
  86     Increase verbosity.
  87
  88 option:-h, option:--help::
  89     Show command help.
  90
  91
  92 ENVIRONMENT VARIABLES
  93 ---------------------
  94 `CC`::
  95     C compiler to use. Default: `cc`, then `gcc` if `cc` is not found.
  96     This option is only relevant when generating the `.o` file.
  97
  98 `CFLAGS`::
  99     Flags and options passed directly to the compiler (`$CC`).
 100     This option is only relevant when generating the `.o` file.
 101
 102
 103 EXIT STATUS
 104 -----------
 105 *0*::
 106     Success
 107
 108 *Non-zero*::
 109     Error
 110
 111
 112 include::common-footer.txt[]
 113
 114
 115 COPYRIGHTS
 116 ----------
 117 `lttng-gen-tp` is part of the LTTng-UST project.
 118
 119 `lttng-gen-tp` is distributed under the
 120 http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html[GNU General
 121 Public License, version 2]. See the
 122 https://github.com/lttng/lttng-ust/blob/v{lttng_version}/COPYING[`COPYING`] file
 123 for more details.
 124
 125
 126 AUTHOR
 127 ------
 128 `lttng-gen-tp` was originally written by
 129 mailto:yannick.brosseau@gmail.com[Yannick Brosseau]. It is currently
 130 maintained by mailto:mathieu.desnoyers@efficios.com[Mathieu Desnoyers].
 131
 132
 133 SEE ALSO
 134 --------
 135 man:lttng-ust(3)